diff --git a/docs/screenshots/finish-dark.webp b/docs/screenshots/finish-dark.webp index 6288852..481b273 100644 Binary files a/docs/screenshots/finish-dark.webp and b/docs/screenshots/finish-dark.webp differ diff --git a/docs/screenshots/finish-light.webp b/docs/screenshots/finish-light.webp index 4e9fee1..9aa274b 100644 Binary files a/docs/screenshots/finish-light.webp and b/docs/screenshots/finish-light.webp differ diff --git a/scripts/test-web-console.mjs b/scripts/test-web-console.mjs index ca71399..f58f52b 100644 --- a/scripts/test-web-console.mjs +++ b/scripts/test-web-console.mjs @@ -1050,7 +1050,7 @@ test("help: every number the help quotes matches the code", () => { const panels = new Map( [...tpl.matchAll(/
([\s\S]*?)<\/section>/g)].map((m) => [m[1], m[2]]) ); - const firstSeven = HELP_TABS.slice(0, 7).map((t) => panels.get(t.id)).join("\n"); + const firstEight = HELP_TABS.slice(0, 8).map((t) => panels.get(t.id)).join("\n"); const used = [ "closedTabMinutes", "maxLifeHours", @@ -1062,7 +1062,7 @@ test("help: every number the help quotes matches the code", () => { "maxUploadMb", "cleanupDays", ]; - for (const key of used) assert.ok(firstSeven.includes(`data-fact="${key}"`), `tabs 1 to 7 quote ${key}`); + for (const key of used) assert.ok(firstEight.includes(`data-fact="${key}"`), `tabs 1 to 8 quote ${key}`); }); /* ---------------------------------------------------------- image uploads */ @@ -7048,3 +7048,56 @@ test("the Changelog card comes just before Git commit and is always on", () => { assert.equal(cardAvailability(entry, scan, null).on, true); } }); + +/* ------------------------------------------- getting started: stuck help and the finished screen */ + +const EM = String.fromCharCode(0x2014); +const publicSource = (name) => fs.readFileSync(path.join(ROOT, "src", "web-console", "public", name), "utf8"); + +test("help: the stuck tab is second, with a callout and four symptom rows before the diagram", () => { + assert.equal(HELP_TABS[0].id, "about"); + assert.equal(HELP_TABS[1].id, "stuck"); + const tpl = helpTemplate(); + const panel = tpl.match(/
([\s\S]*?)<\/section>/)[1]; + assert.match(panel, /
/); + assert.match(panel, /Check this first/); + assert.match(panel, /look at your terminal/); + assert.equal((panel.match(/class="help-row"/g) || []).length, 4, "four symptom rows"); + for (const part of ["You see", "Likely cause", "Do this"]) { + assert.equal((panel.match(new RegExp(`
${part}
`, "g")) || []).length, 4, `each row has "${part}"`); + } + assert.ok(panel.indexOf("help-rows") < panel.indexOf("help-figure"), "the rows come before the diagram"); + assert.match(panel, /]*aria-hidden="true"/, "the icon is decoration"); +}); + +test("status line: the quiet and Not running lines offer What to check, opening Help on the stuck tab", () => { + const app = publicSource("app.js"); + assert.match(app, /help\.textContent = "What to check"/); + assert.match(app, /openHelpOn\("stuck"\)/); + // Exactly the three lines that carry it: the approval hint, the stale line and the Not running line. + const render = app.slice(app.indexOf("function renderStatus()"), app.indexOf("/* ---------------------------------------------------------------- brief */")); + assert.match(render, /Boolean\(hint\)/); + assert.equal((render.match(/^\s+true\n\s+\);/gm) || []).length, 2, "the stale and Not running lines pass check"); +}); + +test("finished screen: every shape shows Before you close this, with three rows", () => { + const app = publicSource("app.js"); + const handoff = app.slice(app.indexOf("function renderHandoff(")); + assert.match(handoff.slice(0, handoff.indexOf("\n}\n")), /card\.appendChild\(renderCloseGuide\(shape\)\)/); + const guide = app.slice(app.indexOf("function renderCloseGuide("), app.indexOf("function renderHandoff(")); + for (const label of ["Safe to close", "Start fresh", "Carry on", "Before you close this"]) { + assert.ok(guide.includes(label), `the guide says "${label}"`); + } + assert.match(guide, /shape === "paused"/, "a pause changes the Start fresh sentence"); + assert.match(guide, /resume command/); +}); + +test("getting started: the new help, status and finished-screen strings carry no em dash", () => { + const app = publicSource("app.js"); + const guide = app.slice(app.indexOf("const GUIDE_ICONS"), app.indexOf("function renderHandoff(")); + assert.ok(!guide.includes(EM), "the close guide has no em dash"); + const tpl = helpTemplate(); + const stuck = tpl.match(/
([\s\S]*?)<\/section>/)[1]; + const fresh = stuck.slice(0, stuck.indexOf("

Not running, or not connected?

")); + assert.ok(!fresh.includes(EM), "the callout and rows have no em dash"); +}); diff --git a/src/web-console/public/app.css b/src/web-console/public/app.css index ad509b8..21550e3 100644 --- a/src/web-console/public/app.css +++ b/src/web-console/public/app.css @@ -1376,6 +1376,26 @@ h1 { .presets { margin-top: 12px; gap: 8px; } .presets-label { font-size: 12.5px; color: var(--ink-3); } +/* "Before you close this": three rows on every finished screen. The icon sits + in a coloured circle and the label says the same thing, so no meaning rests + on colour alone. */ +.handoff-guide { + margin: 20px 0 0; padding: 14px 16px; + background: var(--panel-2); border: 1px solid var(--rule-2); border-radius: var(--radius); +} +.handoff-guide-title { margin: 0 0 10px; font: 600 15px/1.3 var(--serif); color: var(--ink); } +.handoff-guide-rows { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 10px; } +.handoff-guide-row { display: flex; align-items: flex-start; gap: 12px; font-size: 14px; color: var(--ink-2); } +.handoff-guide-text { min-width: 0; overflow-wrap: anywhere; } +.handoff-guide-label { color: var(--ink); } +.handoff-guide-icon { + flex: none; display: inline-flex; align-items: center; justify-content: center; + width: 28px; height: 28px; border-radius: 50%; border: 1.5px solid currentColor; +} +.handoff-guide-icon svg { fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; } +.handoff-guide-icon.is-safe { color: var(--ok); background: var(--ok-soft); } +.handoff-guide-icon.is-fresh { color: var(--accent-ink); background: var(--accent); border-color: var(--accent); } +.handoff-guide-icon.is-carry { color: var(--accent); background: var(--accent-soft); } .handoff-close { margin: 16px 0 0; color: var(--ink-2); } .handoff-tools { margin-top: 16px; } .handoff-unsent { @@ -2361,6 +2381,26 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; } padding: 1px 5px; overflow-wrap: anywhere; } +/* Help, "When something looks stuck": a calm callout and a symptom / cause / action list. */ +.help-panel .help-callout { + display: flex; align-items: flex-start; gap: 12px; + margin: 0 0 16px; padding: 12px 14px; + background: var(--stage-soft); border: 1px solid var(--stage); border-left-width: 4px; border-radius: var(--radius); +} +.help-callout-icon { flex: none; width: 22px; height: 22px; margin-top: 1px; fill: none; stroke: var(--stage); stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; } +.help-panel .help-callout-label { display: block; margin-bottom: 2px; font-size: 14px; color: var(--ink); } +.help-panel .help-callout p { margin: 0; color: var(--ink); } +.help-panel ol.help-rows { list-style: none; margin: 0 0 12px; padding: 0; } +.help-row { margin: 0 0 8px; padding: 10px 12px; background: var(--panel-2); border: 1px solid var(--rule); border-radius: var(--radius); } +.help-panel .help-row:last-child { margin-bottom: 0; } +.help-row dl { display: grid; grid-template-columns: max-content 1fr; gap: 3px 12px; margin: 0; } +.help-row dt { font-size: 12px; font-weight: 700; letter-spacing: 0.02em; text-transform: uppercase; color: var(--ink-2); padding-top: 1px; } +.help-row dd { margin: 0; font-size: 13.5px; color: var(--ink); min-width: 0; overflow-wrap: anywhere; } +@media (max-width: 520px) { + .help-row dl { grid-template-columns: 1fr; gap: 0; } + .help-row dt { margin-top: 6px; } + .help-row dt:first-child { margin-top: 0; } +} .help-panel .handoff-command { margin: 0 0 12px; } .help-panel .handoff-command:last-child { margin-bottom: 0; } .help-panel .handoff-code { @@ -3567,3 +3607,12 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; } color: var(--accent); font-weight: 700; } + +/* "What to check", beside the quiet and Not running lines. A link in a button's clothes. */ +.status-help { + font: inherit; font-size: 0.92em; font-weight: 600; + color: var(--accent); background: none; border: 0; padding: 0 2px; + text-decoration: underline; text-underline-offset: 2px; cursor: pointer; +} +.status-help:hover { text-decoration-thickness: 2px; } +.status-help:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; border-radius: 3px; } diff --git a/src/web-console/public/app.js b/src/web-console/public/app.js index af46e6a..307e0ff 100644 --- a/src/web-console/public/app.js +++ b/src/web-console/public/app.js @@ -1637,23 +1637,32 @@ function renderStatus() { // end right now, and it flies too: the ring and the stars mean the same // thing. Never on the stale or adrift lines: a turning ring beside // "has not checked in" would contradict the sentence it sits next to. - const say = (mood, line, count, spin) => { + // `check` adds a "What to check" button that opens Help on the stuck tab. + const say = (mood, line, count, spin, check) => { if (mood !== moodNow) { moodNow = mood; moodVar = Math.floor(Math.random() * MOOD_VARIANTS[mood]); } bot.setAttribute("class", `planny is-${mood} v${moodVar}`); - if (text.dataset.line !== line) { - text.dataset.line = line; - text.replaceChildren( - ...line.split(/\*\*(.+?)\*\*/).map((part, i) => { - if (i % 2 === 0) return document.createTextNode(part); - const key = document.createElement("strong"); - key.className = "agent-key"; - key.textContent = part; - return key; - }) - ); + const shown = check ? `${line}|check` : line; + if (text.dataset.line !== shown) { + text.dataset.line = shown; + const parts = line.split(/\*\*(.+?)\*\*/).map((part, i) => { + if (i % 2 === 0) return document.createTextNode(part); + const key = document.createElement("strong"); + key.className = "agent-key"; + key.textContent = part; + return key; + }); + if (check) { + const help = document.createElement("button"); + help.type = "button"; + help.className = "status-help"; + help.textContent = "What to check"; + help.addEventListener("click", () => openHelpOn("stuck")); + parts.push(document.createTextNode(" "), help); + } + text.replaceChildren(...parts); } tick.textContent = count || ""; $("agent-spin").hidden = !spin; @@ -1710,13 +1719,16 @@ function renderStatus() { if (agentStale()) { return say( "work", - "Still working on it. Longer tasks can go a few minutes between updates. Your answers are saved. If it stays quiet for a long while, check your terminal (it may be waiting on a permission approval)." + "Still working on it. Longer tasks can go a few minutes between updates. Your answers are saved. If it stays quiet for a long while, check your terminal (it may be waiting on a permission approval).", + "", + false, + true ); } // Same clock as agentStale(), so the soft line at 30 s hands over to the // stale message at two minutes on one timeline. const hint = agentLastSeen ? approvalHint(S.agent, Date.now() - Date.parse(agentLastSeen)) : ""; - return say("work", hint || activity() || "Plan2Code is thinking…", fmtMs(workingMs()), true); + return say("work", hint || activity() || "Plan2Code is thinking…", fmtMs(workingMs()), true, Boolean(hint)); } // Between pressing Send and the agent picking it up, the agent's own status // is still "waiting" because it has not started yet. Reading that as "your @@ -1729,7 +1741,10 @@ function renderStatus() { "adrift", stranded() ? "Plan2Code is not running. Your answers are saved and waiting for it. If the terminal is idle, type **continue** there and it will pick them up; it may also be waiting for your permission approval." - : "Plan2Code is not running right now. Anything you answer here is saved. If the terminal is idle, type **continue** there to wake it; it may also be waiting for your permission approval." + : "Plan2Code is not running right now. Anything you answer here is saved. If the terminal is idle, type **continue** there to wake it; it may also be waiting for your permission approval.", + "", + false, + true ); } @@ -2312,6 +2327,69 @@ function paintMain(main) { // in prose and useless for the single action a screen exists to offer. A // finish with nothing left to run skips the last two beats: it gets a quiet // pointer at the dashboard instead of a Next step block. +// "Before you close this": the three things someone looking at a finished +// screen wonders. Every finish shape gets it; a pause says where the place is +// kept, and a session with nothing left to run points at the dashboard alone. +const GUIDE_ICONS = { + safe: ["M5 12.5 10 17.5 19 7"], + fresh: ["M19.5 12a7.5 7.5 0 1 1-2.4-5.5", "M19.5 4v4.5H15"], + carry: ["M5 12h13", "M13 6.5 18.5 12 13 17.5"], +}; + +function guideIcon(kind) { + const wrap = el("span", `handoff-guide-icon is-${kind}`); + wrap.setAttribute("aria-hidden", "true"); + const svg = document.createElementNS(SVG_NS, "svg"); + svg.setAttribute("viewBox", "0 0 24 24"); + svg.setAttribute("width", "16"); + svg.setAttribute("height", "16"); + for (const d of GUIDE_ICONS[kind]) { + const path = document.createElementNS(SVG_NS, "path"); + path.setAttribute("d", d); + svg.appendChild(path); + } + wrap.appendChild(svg); + return wrap; +} + +function renderCloseGuide(shape) { + const panel = el("section", "handoff-guide"); + panel.setAttribute("aria-labelledby", "handoff-guide-title"); + const title = el("h3", "handoff-guide-title", "Before you close this"); + title.id = "handoff-guide-title"; + panel.appendChild(title); + const rows = [ + ["safe", "Safe to close", "This tab is only a window. Everything is saved on disk, and nothing here needs you."], + [ + "fresh", + "Start fresh", + shape === "paused" + ? "Restart your agent window, or close the old session and start a new one. Your saved place is picked up by the resume command above." + : "Restart your agent window, or close the old session and start a new one. A new session starts from clean context. This one is full of this step's instructions, so continuing in it is slower and can confuse the next step.", + ], + [ + "carry", + "Carry on", + shape === "all-done" + ? `In the new session, start from the dashboard with \`${DASHBOARD_COMMAND}\`.` + : `Paste the command above in the new session, or start from the dashboard with \`${DASHBOARD_COMMAND}\`.`, + ], + ]; + const list = el("ul", "handoff-guide-rows"); + for (const [kind, label, text] of rows) { + const row = el("li", "handoff-guide-row"); + row.appendChild(guideIcon(kind)); + const body = el("div", "handoff-guide-text"); + body.appendChild(el("strong", "handoff-guide-label", label)); + body.appendChild(document.createTextNode(" ")); + body.appendChild(textWithCode("span", "handoff-guide-line", text)); + row.appendChild(body); + list.appendChild(row); + } + panel.appendChild(list); + return panel; +} + function renderHandoff(fin) { const card = el("article", "card handoff"); card.appendChild(el("p", "card-kicker", "Session ended")); @@ -2402,13 +2480,15 @@ function renderHandoff(fin) { } } + card.appendChild(renderCloseGuide(shape)); + card.appendChild( el( "p", "handoff-close", reviewPending() === "open" - ? "The review is optional. Skip it and you can close this tab: nothing else here needs you." - : "Then you can close this tab. Nothing here needs you any more." + ? "The review is optional. Skip it and nothing else here needs you." + : "That is everything on this page." ) ); diff --git a/src/web-console/public/help.js b/src/web-console/public/help.js index 3e63eae..86a12ea 100644 --- a/src/web-console/public/help.js +++ b/src/web-console/public/help.js @@ -9,6 +9,7 @@ const tab = (id, label, diagram) => Object.freeze({ id, label, diagram }); export const HELP_TABS = Object.freeze([ tab("about", "What this page is", true), + tab("stuck", "When something looks stuck", true), tab("around", "Finding your way around", true), tab("workspace", "Your workspace", false), tab("planny", "Reading Planny", true), @@ -22,7 +23,6 @@ export const HELP_TABS = Object.freeze([ tab("subagents", "Helpers (subagents)", false), tab("ask", "Ask a quick question", false), tab("finishing", "Stopping and finishing", false), - tab("stuck", "When something looks stuck", true), tab("prefs", "Keyboard and preferences", false), tab("privacy", "Privacy and where things are saved", false), ]); diff --git a/src/web-console/public/index.html b/src/web-console/public/index.html index 2fba5d6..89c1eaf 100644 --- a/src/web-console/public/index.html +++ b/src/web-console/public/index.html @@ -602,6 +602,10 @@ + + + + @@ -660,10 +664,6 @@ - - - - @@ -757,7 +757,174 @@

- + +
+

When something looks stuck

+

+ This page and Plan2Code in your terminal are two programs, and either + can stop without the other. Nothing you have typed is lost either way. +

+
+ +
+ Check this first +

+ If nothing seems to be happening, look at your terminal. Plan2Code + often stops there to ask your permission, and this page cannot see it. +

+
+
+

What you might see

+
    +
  1. +
    +
    You see
    The line beside Planny stays quiet for a minute or two while it is working.
    +
    Likely cause
    A permission prompt is waiting in your terminal.
    +
    Do this
    Switch to the terminal and answer it.
    +
    +
  2. +
  3. +
    +
    You see
    Not running (Planny grey and still).
    +
    Likely cause
    Plan2Code has not checked in for a few minutes.
    +
    Do this
    Look at the terminal. If it is idle, type continue there.
    +
    +
  4. +
  5. +
    +
    You see
    Not connected (Planny faded, his star shut).
    +
    Likely cause
    The program behind this page shut itself down.
    +
    Do this
    Ask Plan2Code to resume the session, and use the new link.
    +
    +
  6. +
  7. +
    +
    You see
    Nothing on the page changes after you press Send.
    +
    Likely cause
    The agent is busy, or has finished its turn.
    +
    Do this
    Your answer is saved. Check the terminal.
    +
    +
  8. +
+
+ + What to check when something looks stuck + + A decision flow. First: does Planny say Not connected? If yes, run + the command again and use the new link. If no: does he say Not + running? If yes, look at the terminal, which may be waiting for + your permission, finished or errored. Either way, and in every + other case, answering anyway is safe, because what you send is + held until Plan2Code collects it. + + + + + + + + Says Not + connected? + + Run the command again, + use the new link + + yes + + no + + Says Not + running? + + Look at the terminal: waiting + for permission, finished, errored? + + yes + + no + + + + Answering anyway is safe: + what you send is held until it is collected + + +
Whatever you find, nothing you have typed is lost.
+
+

Not running, or not connected?

+ +

"Reading Planny" shows every mood side by side.

+

It may be waiting for you in the terminal

+

+ Plan2Code sometimes stops in the terminal to ask your permission + before it runs a command or changes a file, and this page cannot see + that. After about 30 seconds of silence while it is working, the line + beside Planny asks "Still working, or waiting on an approval in your + terminal?" Have a look at the terminal: answering there sets it going + again. +

+

+ If it stays quiet a couple of minutes longer, the line changes to + "Still working on it. Longer tasks can go a few minutes between + updates", with Planny still + in his working pose. It may be busy, or still waiting on you in the + terminal; the terminal is where to look. A build that said a task may + take longer gets that long before the line changes. +

+

+ Hands-off modes, such as auto mode in Claude Code or + smart mode in Devin, cut down on those stops, though some + may still need you. +

+

Answering anyway

+

+ You can keep answering and press Send while Plan2Code is not running. + What you send is written to disk and held until something collects it, + so starting Plan2Code again picks it up where you left off. +

+

Getting a new link

+

The program behind this page shuts itself down:

+ +

+ To get it back, ask Plan2Code in the terminal to resume the session, + or run the step's command again, and use the new link it gives you. + Everything you typed, sent or not, is still there. +

+
+ resume the session and print the web console address here +
+
+ +

Finding your way around

@@ -891,7 +1058,7 @@

- +

Your workspace

@@ -982,7 +1149,7 @@

- +

Reading Planny

@@ -1030,7 +1197,7 @@

- +

Answering questions

@@ -1099,7 +1266,7 @@

- +

Sending and what happens next

@@ -1185,7 +1352,7 @@

- +

Notes and attachments

@@ -1253,7 +1420,7 @@

- +

Documents and printing

@@ -1312,7 +1479,7 @@

- +

The dashboard

@@ -1435,7 +1602,7 @@

- +

Session meter

@@ -1483,7 +1650,7 @@

- +

Watching a build

@@ -1551,7 +1718,7 @@

- +

Helpers (subagents)

@@ -1606,7 +1773,7 @@

- +

Ask a quick question

@@ -1697,7 +1864,7 @@

- +

Stopping and finishing

@@ -1779,128 +1946,6 @@

- -
-

When something looks stuck

-

- This page and Plan2Code in your terminal are two programs, and either - can stop without the other. Nothing you have typed is lost either way. -

-
- - What to check when something looks stuck - - A decision flow. First: does Planny say Not connected? If yes, run - the command again and use the new link. If no: does he say Not - running? If yes, look at the terminal, which may be waiting for - your permission, finished or errored. Either way, and in every - other case, answering anyway is safe, because what you send is - held until Plan2Code collects it. - - - - - - - - Says Not - connected? - - Run the command again, - use the new link - - yes - - no - - Says Not - running? - - Look at the terminal: waiting - for permission, finished, errored? - - yes - - no - - - - Answering anyway is safe: - what you send is held until it is collected - - -
Whatever you find, nothing you have typed is lost.
-
-

Not running, or not connected?

- -

"Reading Planny" shows every mood side by side.

-

It may be waiting for you in the terminal

-

- Plan2Code sometimes stops in the terminal to ask your permission - before it runs a command or changes a file, and this page cannot see - that. After about 30 seconds of silence while it is working, the line - beside Planny asks "Still working, or waiting on an approval in your - terminal?" Have a look at the terminal: answering there sets it going - again. -

-

- If it stays quiet a couple of minutes longer, the line changes to - "Still working on it. Longer tasks can go a few minutes between - updates", with Planny still - in his working pose. It may be busy, or still waiting on you in the - terminal; the terminal is where to look. A build that said a task may - take longer gets that long before the line changes. -

-

- Hands-off modes, such as auto mode in Claude Code or - smart mode in Devin, cut down on those stops, though some - may still need you. -

-

Answering anyway

-

- You can keep answering and press Send while Plan2Code is not running. - What you send is written to disk and held until something collects it, - so starting Plan2Code again picks it up where you left off. -

-

Getting a new link

-

The program behind this page shuts itself down:

- -

- To get it back, ask Plan2Code in the terminal to resume the session, - or run the step's command again, and use the new link it gives you. - Everything you typed, sent or not, is still there. -

-
- resume the session and print the web console address here -
-
-

Keyboard and preferences