@jxsuite/studio 5.2.0 → 5.4.0

package/src/page-params.ts

@@ -2,12 +2,12 @@
 /**
  * Dynamic route-param helpers for the tab-bar's $params picker.
  *
- * A page like `pages/products/[sku].json` declares its candidate values in a `$paths` block (spec
- * §4.3). At build time the compiler expands those into concrete routes (`resolvePathEntries` in
- * `@jxsuite/compiler`); in the studio the same shapes are resolved live so the author can pick one
- * value to render. The chosen values are substituted into the canvas render document
- * (`substitutePreviewParams`), which mirrors what the compiler's context injection produces for the
- * matching built page.
+ * A page like `pages/products/[sku].json` declares its candidate values in a `$paths` block
+ * (site-architecture.md §4.3). At build time the compiler expands those into concrete routes
+ * (`resolvePathEntries` in `@jxsuite/compiler`); in the studio the same shapes are resolved live so
+ * the author can pick one value to render. The chosen values are substituted into the canvas render
+ * document (`substitutePreviewParams`), which mirrors what the compiler's context injection
+ * produces for the matching built page.
  */
 
 import { documentUrlPattern as routePattern } from "@jxsuite/site/routes";

package/src/panels/activity-panel.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * Activity — where a long operation lives while it runs, and what it leaves behind (plan §7.3).
+ * Activity — where a long operation lives while it runs, and what it leaves behind (§16.4).
  *
  * What this replaces: `ui/progress-modal.ts` was **the only surface in Studio with a real error
  * view** — a red headline, the captured log in a `<pre>`, an explicit Close — and it had four call
@@ -19,14 +19,14 @@
  *   on its row, which is the affordance a hung install has never had;
  * - And it **fails into Problems** — {@link ActivityHandle.fail} raises a `notify.error` carrying the
  *   log as its `detail`, so the failure outlives the run and carries a Retry command. That is
- *   §7.3's "the progress modal's error view is promoted into Problems", in one function.
+ *   §16.4's promotion of the progress modal's error view into Problems, in one function.
  *
  * **Nothing here blocks.** `showProgressModal` still exists for the four dependency-install sites
- * §7.3 keeps blocking, and it is now a thin front end over {@link beginActivity} — so even the
+ * §16.4 keeps blocking, and it is now a thin front end over {@link beginActivity} — so even the
  * blocking case leaves an inspectable entry behind, and closing the modal no longer loses it.
  *
  * `services/idle.ts` reads {@link activityIdleBlockers}: an open operation means the app is not
- * settled, which is the §13.6 S4 obligation every phase's checklist carries.
+ * settled, which is how §16.4 makes running activities a `probe.idle()` source.
  *
  * **The feed itself is a Jx document** (`surfaces/panel-activity.json`, mounted by
  * `surfaces/panel-activity.ts`). What stays here is the record and the vocabulary a row is written
@@ -154,7 +154,7 @@ export interface ActivityOptions {
    * Stop the operation.
    *
    * Its presence is what draws the Cancel button, so an operation that cannot honestly be stopped
-   * must not pass one — a Cancel that does nothing is the failure §7 exists to end, restated as a
+   * must not pass one — a Cancel that does nothing is the failure §16 exists to end, restated as a
    * button.
    */
   cancel?: () => void;
@@ -176,7 +176,7 @@ export interface ActivityHandle {
   /**
    * Finish with a failure — and raise the Problem that outlives it.
    *
-   * The log goes into the notification's `detail`, so the persistent, inspectable error view §7.3
+   * The log goes into the notification's `detail`, so the persistent, inspectable error view §16.4
    * asks for is the Problems row, not a modal that has to stay open to be read.
    */
   fail: (message: string, opts?: { action?: string; path?: string }) => void;
@@ -324,7 +324,7 @@ export function resetActivities(): void {
 /**
  * What is still running, as `services/idle.ts` phrases it.
  *
- * §13.6 S4 puts this on every phase's checklist: an app with an operation in flight has not
+ * §16.4 makes this a `probe.idle()` condition (§13.5): an app with an operation in flight has not
  * finished reacting, so a screenshot taken now photographs a half-done import. A FINISHED entry is
  * not a blocker — the list stays on screen forever and waiting for it to empty would never settle.
  */
@@ -449,8 +449,8 @@ const ACTIVITY_SURFACE: ActivitySurfaceDeps = {
  * Two documents, two hosts, and that is the seam rather than a layout: a document CLEARS the host
  * it is given and lit renders BESIDE foreign nodes, so a document and a lit template can never
  * share a container. The checklist belongs to `publish/deploy-checklist.ts` — a deploy is a long
- * operation with a log, which is why P4 folded it in here rather than giving it a fifth dock tab —
- * and it sits above the feed because its whole job is to say what is missing BEFORE you begin.
+ * operation with a log, which is why it was folded in here rather than given a fifth dock tab — and
+ * it sits above the feed because its whole job is to say what is missing BEFORE you begin.
  *
  * **`data-deploy-checklist` and `data-activity-surface` are the markers, and they are attributes
  * rather than classes for two reasons.** Nothing styles them, and a class no stylesheet defines is
@@ -500,7 +500,8 @@ export function registerActivityPanel(): void {
     dock: "bottom",
     icon: "clock-counter-clockwise",
     // No rail button: the Bottom dock's tabs are reached by ⌘J and `view.setBottomTab`, and a
-    // Fifth rail slot for a surface with no steady state would spend chrome §2 principle 9 caps.
+    // Fifth rail slot for a surface with no steady state would spend chrome the budget caps
+    // (studio-ui-guidelines.md §12.2).
     rail: false,
     badge: () => (runningActivities().length > 0 ? runningActivities().length : null),
     render: () => renderActivityBody(),

package/src/panels/ai-chat/chat-view.ts

@@ -4,17 +4,19 @@
  *
  * Message-row anatomy: user messages render as right-aligned bubbles (attached-context blocks
  * become chips), assistant messages render sanitized markdown plus tool-call chips, tool messages
- * surface failures only (ADR §11.3), the streaming tail renders as plain text with a cursor
+ * surface failures only, the streaming tail renders as plain text with a cursor
  * (markdown parses once on finalize), and chat errors get a danger row with recovery advice and a
  * Retry. **None of that is markup here any more** — `surfaces/ai-chat.json` draws it and this
  * module decides what it says, which is the same split the file always had with a document on the
  * other side of it instead of a lit template.
  *
- * §7.4 (AI honesty) is why three things here are not what they were:
+ * ai.md §3.2 (the accountable turn) is why three things here are not what they were:
  *
- * - **A chip renders its OUTCOME.** `ToolCallRecord.result` has always been populated by the loop
- *   and ignored by this renderer, so a chip that said `update_style: ["children",0]` said exactly
- *   as much when the edit had been refused as when it had landed.
+ * - **A chip renders its OUTCOME.** It reads `ToolCallRecord.result`, so a chip that said
+ *   `update_style: ["children",0]` no longer says exactly as much when the edit was refused as when
+ *   it landed. The live loop attaches each result as its call finishes (`appendToolResult`), and a
+ *   restored chat backfills it from the tool message that answered the call
+ *   (`services/tool-outcomes.ts`).
  * - **A turn renders what it CHANGED.** The changed-files summary comes off the write ledger
  *   (`services/ai-writes.ts`), which records whether each change went through a transaction or
  *   straight to disk — so the undo caveat is rendered to the human holding ⌘Z instead of being
@@ -22,8 +24,8 @@
  * - **An error offers Retry.** `chatState.retryLast()` has been implemented, exported and called by
  *   nobody; the error row is where it belongs.
  *
- * §11.1 is why the three buttons here are not callbacks any more. History, New Chat and Retry were
- * closures this module received and invoked, so the capabilities existed ONLY as buttons: the
+ * ai.md §3.0 is why the three buttons here are not callbacks any more. History, New Chat and Retry
+ * were closures this module received and invoked, so the capabilities existed ONLY as buttons: the
  * `Assistant` category held zero records, and nothing could reach them from the palette, a chord,
  * the automation runner or the generated commands sheet. They are {@link projectCommand} now, in
  * the idiom `surfaces/statusbar.ts` established — the record is the definition site, and this file
@@ -116,6 +118,9 @@ export function formatErrorAdvice(error: string): string {
   if (lower.includes("500") || lower.includes("internal")) {
     return "The upstream API returned a server error. Try again in a moment.";
   }
+  if (lower.includes("empty reply")) {
+    return "Try again, or pick another model: some send back nothing for a request they cannot handle.";
+  }
   return "";
 }
 
@@ -191,10 +196,9 @@ export function tokenLabel(tokens: number): string {
  * The sentence behind the token readout.
  *
  * `services/context-manager.ts` has computed both numbers on every turn since it was written, and
- * `chat-state.ts` has stored them — with NO READER anywhere. Plan §11.6: "Context budget manager →
- * tokenCount / contextWarning actually rendered". So a conversation was silently trimmed, the
- * assistant forgot what you told it ten turns ago, and the two numbers that would have explained
- * why sat in the store.
+ * `chat-state.ts` has stored them — with NO READER anywhere. So a conversation was silently
+ * trimmed, the assistant forgot what you told it ten turns ago, and the two numbers that would have
+ * explained why sat in the store.
  *
  * @param {number} tokens
  * @param {boolean} overBudget
@@ -289,7 +293,16 @@ export function toolOutcomeText(tc: ToolCallRecord): string {
   if (!result) {
     return "";
   }
-  return (result.success ? result.summary : result.error) ?? "";
+  const text = (result.success ? result.summary : result.error) ?? "";
+  /* An import's summary is written for the model: its first sentence says what happened ("Imported
+     <url> into <root> and opened it", or that it was not opened), and the rest instructs the model
+     what to read and ask next. The person reads the first sentence; the rest is not addressed to
+     them. The live chip draws the run's own log beside it. */
+  if (tc.name === IMPORT_TOOL && result.success) {
+    const end = /\.(?:\s|$)/.exec(text);
+    return end ? text.slice(0, end.index + 1) : text;
+  }
+  return text;
 }
 
 /** How a question card reaches the store that resolves it, and an import its record. */
@@ -535,8 +548,8 @@ export function projectRows(opts: MessageListOptions): ChatRowView[] {
       continue;
     }
     if (msg.role === "tool") {
-      // Show only failed tool results so the user knows why an edit didn't land (ADR §11.3).
-      // Successful tool results stay hidden to reduce noise.
+      /* Show only failed tool results so the user knows why an edit didn't land. Successful tool
+         results stay hidden to reduce noise; the chip on the call already states its outcome. */
       const parsed = tryParseToolResult(msg.content);
       if (parsed && !parsed.success) {
         rows.push({

package/src/panels/ai-chat/composer.ts

@@ -40,6 +40,7 @@ import type { JxMutableNode } from "@jxsuite/schema/types";
 export interface ComposerOptions {
   /** Receives the full message content (typed text + serialized context). */
   onSend: (text: string) => void;
+  /** Whether a turn is in flight: the whole turn, tools included, not only its token stream. */
   isStreaming: () => boolean;
   /**
    * Whether the turn is suspended on a question. The composer becomes the answer field: Enter still
@@ -72,7 +73,10 @@ export interface Composer {
   view: () => ComposerView;
   /** The reader typed. */
   edit: (text: string) => void;
-  /** Send what is typed, if anything is and nothing is already in flight. */
+  /**
+   * Send what is typed, if anything is. During a turn, only when a question waits: that send is its
+   * answer.
+   */
   send: () => void;
   clear: () => void;
   /** Open the attach menu under the button that was pressed. */
@@ -239,7 +243,8 @@ export function createComposer(opts: ComposerOptions): Composer {
   }
 
   function send() {
-    if (!draft.trim() || opts.isStreaming()) {
+    // A send while a question waits is its answer, so a running turn refuses only an ordinary send.
+    if (!draft.trim() || (opts.isStreaming() && !(opts.isAwaiting?.() ?? false))) {
       return;
     }
     const text = buildMessageWithContext(draft, chips);
@@ -290,7 +295,9 @@ export function createComposer(opts: ComposerOptions): Composer {
         : "Ask the assistant… (Enter to send)",
       sendDisabled: draft.trim().length === 0,
       sendLabel: awaiting ? "Answer" : "Send",
-      sendState: streaming ? "stop" : "send",
+      /* Answer, else Stop, else Send. A waiting question outranks Stop because the composer is its
+         answer field, and a turn in flight otherwise offers Stop for all of it, tools included. */
+      sendState: !awaiting && streaming ? "stop" : "send",
     };
   }
 

package/src/panels/ai-panel.ts

@@ -64,6 +64,7 @@ import type { AiChatSurface, AiChatView } from "../surfaces/ai-chat";
 import type { AnyCommand } from "../commands/registry";
 import type { CommandContext } from "../commands/context";
 import type { EffectScope } from "@vue/reactivity";
+import type { Message } from "@jxsuite/ai/chat-state";
 
 // ─── State (module-level, persists across tab switches) ─────────────────────
 
@@ -136,11 +137,12 @@ let projectionQueued = false;
  * **Coalesced on a microtask, for two reasons that are not about paint.** A turn writes several
  * reactive facts in one tick — the message, the status, the token count — and the transcript
  * projection is O(messages), so running it once per write would rebuild the whole list three times
- * for one event. And the write LEDGER (`services/ai-writes.ts`) is a plain array: `endTurn` files
+ * for one event. And the write LEDGER (`services/ai-writes.ts`) is a plain array: `fileTurn` files
  * it immediately after the assistant message lands, so a projection that ran synchronously inside
- * the effect would read the turn's changed-files summary one write too early, every time. The old
- * frame loop hid both by accident of deferral; this states them. Precedent: `panels/overlays.ts`,
- * §9.3's second scheduler.
+ * the effect would read the turn's changed-files summary one write too early, every time. (When it
+ * lands later than that, after a Stop mid-stream, the send re-projects once the turn has settled.)
+ * The old frame loop hid both by accident of deferral; this states them. Precedent:
+ * `panels/overlays.ts`, studio-ui-guidelines.md §9.3's second scheduler.
  */
 export function renderAiPanel(): void {
   if (projectionQueued || !surface) {
@@ -187,8 +189,18 @@ function watchAssistant() {
       const last = cs.messages.at(-1);
       void last?.content;
       void last?.toolCalls?.length;
+      /* A call's result lands on its request's record once the tool has run, and the chip draws
+         it. By then the tail may be an earlier call's `tool` reply rather than the request, so the
+         request is found behind the replies, and every one of its records is tracked. */
+      for (const tc of latestRequest(cs.messages)?.toolCalls ?? []) {
+        void tc.result;
+      }
       void cs.status;
       void cs.error;
+      // The composer's Send/Stop follows the turn, which outlasts the stream's status.
+      void assistant.isTurnActive();
+      // A usage frame moves the token count and nothing else this effect reads.
+      void cs.tokenCount;
       // The registry is composed AFTER the bootstrap mounts this, and it is a reactive holder —
       // Reading it here is what turns the header's skeleton into its real buttons.
       void activeRegistry();
@@ -208,6 +220,22 @@ function watchAssistant() {
   });
 }
 
+/**
+ * The assistant message the tool replies at the end of the transcript answer: the one whose chips a
+ * running tool's result is about to change.
+ *
+ * @param {readonly Message[]} messages
+ * @returns {Message | undefined}
+ */
+function latestRequest(messages: readonly Message[]): Message | undefined {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (messages[index]!.role !== "tool") {
+      return messages[index];
+    }
+  }
+  return undefined;
+}
+
 // ─── Lifecycle ──────────────────────────────────────────────────────────────
 
 export function mountAiPanel() {
@@ -231,14 +259,20 @@ export function mountAiPanel() {
  * them is a 400. It travels as the tool result instead, and the question's own card renders it.
  */
 async function handleAssistantSend(text: string) {
-  if (!text.trim() || assistant.chatState.status === "streaming") {
+  if (!text.trim()) {
     return;
   }
+  /* Answering comes first: a question is put by a turn that is still running, so a send while one
+     waits is its answer, never a second turn. */
   if (answerAsk(text.trim())) {
     surface?.pin();
     renderAiPanel();
     return;
   }
+  // One turn per window: a send during a turn, tools included, starts nothing.
+  if (isAssistantStreaming()) {
+    return;
+  }
   // A send always lands in the chat view, pinned to the newest message.
   view = "chat";
   surface?.pin();
@@ -248,11 +282,18 @@ async function handleAssistantSend(text: string) {
   } catch {
     // Synchronous failure (e.g. network unreachable) — the DocumentAssistant's
     // Own try/catch calls chatState.setError(), which the watcher renders.
+  } finally {
+    /* The turn's changes are filed in the loop's `finally`, and the ledger is not reactive. It is
+       usually filed in the same job as the turn's last reactive write, but not after a Stop
+       mid-stream: that write (`cancelStream`) lands microtasks before the aborted stream winds
+       down, so the coalesced projection has already drawn the reply without its summary. One
+       projection once the turn has settled is the one that is guaranteed to see it. */
+    renderAiPanel();
   }
 }
 
 /**
- * Re-send the last user message — §7.4's Retry.
+ * Re-send the last user message — ai.md §3.0's Retry.
  *
  * `chatState.retryLast()` pops the failed assistant turn AND the user message that caused it, on
  * the contract that the caller re-sends. It has been exported with zero callers since it was
@@ -272,7 +313,7 @@ async function handleRetry(): Promise<void> {
 }
 
 /**
- * Undo everything one assistant turn changed — §7.4's "Restore to here".
+ * Undo everything one assistant turn changed — ai.md §3.2's "Restore to here".
  *
  * The loop opens one batch per turn per document, so undoing the turn is undoing that batch. The
  * button is offered by the projection only when every recorded change was transactional; this guard
@@ -314,8 +355,19 @@ export function handleRestore(messageId: string): void {
  * project brief). Delegates to the same send path as the composer. Safe to call right after the
  * Assistant tab renders — the reactive watcher projects chat-state into the panel whenever it
  * mounts.
+ *
+ * **A seed waits for the window's turn, and is never refused.** One window runs one turn, and a
+ * turn outlives the call that ended it: New Chat stops the running one, but its loop unwinds
+ * afterwards, and a project switch does not stop it at all. A seed sent in that window was refused
+ * and lost without a word, taking the New Project hand-off with it. Waiting also keeps a seed from
+ * being taken as the answer to a question the old turn still had open.
  */
 export async function seedAssistantPrompt(text: string): Promise<void> {
+  /* One wait is enough: the turn's end settles in its loop's `finally`, and this resumes on the next
+     microtask, before any event could start another turn. */
+  if (assistant.isTurnActive()) {
+    await assistant.whenTurnEnds();
+  }
   await handleAssistantSend(text);
 }
 
@@ -461,15 +513,20 @@ export function isAssistantWaiting(): boolean {
  * Whether a turn is in flight — the probe `commands/live-context.ts` declares as `aiStreaming` and
  * projects onto `ctx.ai.streaming`.
  *
+ * The whole turn, not the token stream. The chat's `status` reads idle while a round's tools run,
+ * while a question waits and through a minutes-long import, so reading it here left Stop refused
+ * and Send offered in the middle of a turn, and a second send could start a second turn beside the
+ * first. The assistant's own turn fact is true from an accepted send until its loop ends.
+ *
  * That source was declared optional with the note "there is nothing to read yet; the caller passes
  * a probe when one exists", and no caller ever did — so `ctx.ai.streaming` read `false` forever and
- * `assistant.stop` would have been permanently refused. Reading the reactive chat state here is
- * what makes the fact LIVE: `createLiveContext` builds a fresh record per predicate evaluation, so
- * a surface projecting from an effect tracks this status and re-projects when the stream starts or
- * ends.
+ * `assistant.stop` would have been permanently refused. Reading the assistant's reactive turn flag
+ * here is what makes the fact LIVE: `createLiveContext` builds a fresh record per predicate
+ * evaluation, so a surface projecting from an effect tracks the flag and re-projects when a turn
+ * starts or ends.
  */
 export function isAssistantStreaming(): boolean {
-  return assistant.chatState.status === "streaming";
+  return assistant.isTurnActive();
 }
 
 function stop() {
@@ -595,25 +652,24 @@ function projectPanel(): AiChatView {
   };
 }
 
-// ─── The `Assistant:` command family (§11.1) ────────────────────────────────
+// ─── The `Assistant:` command family (ai.md §3.0) ───────────────────────────
 
 /**
  * Six records, beside the chat session they write.
  *
- * §11.1 pays for the chat column's demotion into an Inspector tab with a command family, and the
- * `Assistant` category — declared in `commands/levels.ts` since the taxonomy landed — held ZERO
- * records. Every capability below already existed and every one of them existed ONLY as a button in
- * this panel: not in the palette, not bindable, not reachable by `__jxAutomation` or by name, and
- * absent from the generated commands and shortcuts sheets. A capability that one surface can reach
- * and the registry cannot is the second definition site inverted.
+ * The chat column's demotion into an Inspector tab was paid for with a command family (ai.md §3.0),
+ * and the `Assistant` category — declared in `commands/levels.ts` since the taxonomy landed — held
+ * ZERO records. Every capability below already existed and every one of them existed ONLY as a
+ * button in this panel: not in the palette, not bindable, not reachable by `__jxAutomation` or by
+ * name, and absent from the generated commands and shortcuts sheets. A capability that one surface
+ * can reach and the registry cannot is the second definition site inverted.
  *
- * **All six are `level: "application"`, by principle 3 — a record is filed by the level of the
- * state it WRITES, not the state it reads.** The chat session is application state: it outlives the
- * open document, survives project close, and `assistant.attachSelection` is the case that proves
- * the rule — it READS the canvas selection and writes a chip into the composer, so it is
- * application, not selection, however selection-ish it looks. That is also why it may declare
- * `menus: ["palette"]` at all: `blockbar` and `context/element` admit selection-level records
- * only.
+ * **All six are `level: "application"`, by §13.2 — a record is filed by the level of the state it
+ * WRITES, not the state it reads.** The chat session is application state: it outlives the open
+ * document, survives project close, and `assistant.attachSelection` is the case that proves the
+ * rule — it READS the canvas selection and writes a chip into the composer, so it is application,
+ * not selection, however selection-ish it looks. That is also why it may declare `menus:
+ * ["palette"]` at all: `blockbar` and `context/element` admit selection-level records only.
  *
  * **No `aiTool` on any of them.** The assistant projecting "start a new chat" into its own tool
  * list would let a turn end its own conversation; the tier tables in `services/ai-tools.ts` gate
@@ -710,9 +766,11 @@ export function assistantCommands(): AnyCommand[] {
       menus: ["palette"],
       group: "2_turn",
       requires: "a turn in flight",
-      /* The union, not just `streaming`. A turn suspended on `ask_user` moves no tokens, so
-         `ctx.ai.streaming` reads false — and that is precisely the turn a reader who does not want
-         to answer needs to end. */
+      /* `streaming` covers the whole turn, a waiting question included: a turn suspended on
+         `ask_user` moves no tokens, and it is precisely the turn a reader who does not want to
+         answer needs to end. A question is only ever put inside a turn, so `waiting` adds nothing
+         here; it stays in the union so a question could still be stopped if one were ever raised
+         without a turn. */
       enablement: (ctx: CommandContext) => ctx.ai.streaming || ctx.ai.waiting,
       run: stop,
     },

package/src/panels/block-action-bar.ts

@@ -2,7 +2,7 @@
 /**
  * Block action bar — the floating toolbar above the selected element.
  *
- * The bar is a RENDERING of the command registry (plan §3.2 region ⑩, §5.5): its verb cluster is
+ * The bar is a RENDERING of the command registry (§4.4, §13): its verb cluster is
  * `registry.forPlacement("blockbar")`, sliced at {@link BLOCKBAR_MAX_ITEMS} with the remainder
  * behind a `⋮` overflow menu. Every button's accessible name is its record's `title` and its
  * tooltip carries `keymap.formatBinding(id)`, so no action is named twice.
@@ -19,8 +19,8 @@
  * whether each can act, where the bar belongs against the selection rect, when it steps aside, and
  * what a press does. The toolbar role, the roving caret and the ←/→/Home/End contract are
  * `jx-action-group`'s, so the hand-written `[data-toolbar-item]` ring is gone with the template
- * that needed it; the `⋮` menu is the kit menu every other Studio surface opens (§12.5), so there
- * is no second list of actions.
+ * that needed it; the `⋮` menu is the kit menu every other Studio surface opens
+ * (studio-ui-guidelines.md §12.5), so there is no second list of actions.
  *
  * This module is also the single definition site for the structural selection verbs — move
  * up/down/in/out and the component pair — because their implementations live here.
@@ -49,6 +49,7 @@ import {
 } from "../store";
 import { activeTab } from "../workspace/workspace";
 import { activeCanvasSurface, stageContaining } from "../canvas/canvas-surface";
+import { panelOfSurface } from "../canvas/canvas-helpers";
 import { primarySelection, structuralBatch } from "../tabs/selection";
 import {
   mutateDuplicateNodes,
@@ -207,10 +208,13 @@ function repositionBlockActionBar(): void {
   });
 }
 
+/** The bar's own height plus its 4px stand-off: the room it needs ABOVE an anchor to stand there. */
+const BAR_CLEARANCE = 38;
+
 /**
- * The bar's position for `anchor` (flipping below the element near the top edge), or null when the
- * anchor's vertical extent has left the canvas area — the popover layer has no clipping, so a
- * clamped bar would float detached over the app toolbar / panel headers.
+ * The bar's position for `anchor` (flipping below the element when it cannot stand above it), or
+ * null when the anchor's vertical extent has left the canvas area — the popover layer has no
+ * clipping, so a clamped bar would float detached over the app toolbar / panel headers.
  *
  * @param {{ left: number; top: number; height: number }} anchor
  */
@@ -224,17 +228,39 @@ function barPosition(anchor: {
      stage — and the pane is the FOCUSED one, because that is where the caret is. This asked
      "the stage showing the active tab", which was the same answer only while a tab could be on
      screen in one place; with a document displayed in two panes it picked whichever came first in
-     the grid, and clipped the bar against a stage the author is not typing in. */
-  const stage = activeCanvasSurface().wrap;
-  if (stage) {
-    const wrap = rectOf(stage);
-    if (anchor.top + anchor.height < wrap.top || anchor.top > wrap.bottom) {
-      return null;
-    }
+     the grid, and clipped the bar against a stage the author is not typing in.
+     …and against the box that SCROLLS, where the stage has one. Edit docks the Document Header
+     card above its scroller, inside the same stage cell, so a node scrolled up under the band is
+     still inside the stage while nobody can see it — and the bar would float over the card,
+     pointing at a node the card is covering. Everywhere else there is no scroller and the stage is
+     the viewport, as it always was. */
+  const surface = activeCanvasSurface();
+  const viewport = panelOfSurface(surface)?.scrollContainer ?? surface.wrap;
+  const box = viewport ? rectOf(viewport) : null;
+  if (box && (anchor.top + anchor.height < box.top || anchor.top > box.bottom)) {
+    return null;
+  }
+  /* ABOVE the anchor where the bar fits above it INSIDE that viewport, and BELOW it where it does
+     not. The flip used to be decided against a flat 80 in WINDOW coordinates, the app's own top
+     chrome, which is the same answer only while the viewport starts near the top of the window.
+     Edit's scroller starts under a band, so an anchor whose top had scrolled under the card while
+     its bottom was still on screen put the bar ON the card — over the fields it covers, taking
+     their clicks. Flipped is better than hidden: the element is visible, so its bar should be, and
+     past the clip above the anchor's bottom edge is inside the viewport, so the flipped bar is too.
+     The fallback is that same 80px of chrome, for a stage no pass has measured yet. */
+  const ceiling = box ? box.top : 80 - BAR_CLEARANCE;
+  const above = anchor.top - BAR_CLEARANCE;
+  if (above >= ceiling) {
+    return { left: anchor.left, top: above };
   }
+  /* Below it, and kept INSIDE the viewport: an element taller than what is left of the scroller has
+     its bottom edge off screen, and the bar would follow it there — over the status bar, or over
+     whatever the pane below is showing. Clamped, it stands on that element's last visible strip,
+     still pointing at it and still off the card. */
+  const below = anchor.top + anchor.height + 4;
   return {
     left: anchor.left,
-    top: anchor.top < 80 ? anchor.top + anchor.height + 4 : anchor.top - 38,
+    top: box ? Math.max(box.top, Math.min(below, box.bottom - BAR_CLEARANCE)) : below,
   };
 }
 
@@ -276,16 +302,16 @@ function clampBarToWindow(bar: HTMLElement): void {
  * `formatBold` because Jx owns its markup. So ⌘B in the canvas did nothing at all, in an app whose
  * toolbar advertised it.
  *
- * They are the case UX-REDESIGN-PLAN §5.1 uses to justify two fields, so they are written the way
- * it says: `level: "selection"` — a range inside the selected node is still the selection, and a
- * fifth `range` level would demand a fifth region — with `keyScope: "caret"`, which is what makes
- * the chord live only where a caret is. They were, until this change, the only capability in Studio
- * with a chord and no record.
+ * They are the case that justifies the record's two fields (specs/studio.md §13.2–§13.3), so they
+ * are written the way it says: `level: "selection"` — a range inside the selected node is still the
+ * selection, and a fifth `range` level would demand a fifth region — with `keyScope: "caret"`,
+ * which is what makes the chord live only where a caret is. They were, until this change, the only
+ * capability in Studio with a chord and no record.
  *
  * **The set is the schema's, the verbs are the registry's.** `data/elements-meta.json` says which
  * of the eight a given tag accepts (`$inlineActions`), so the bar draws four on an `<h1>` and eight
  * on a `<p>`; what each one is CALLED, which chord it holds and what it does are on the record.
- * That is the same division P5.3 made for value sources — caps derive from the schema, behaviour
+ * That is the same division §6.6 makes for value sources — caps derive from the schema, behaviour
  * does not.
  *
  * `when` is {@link CommandContext.caret.inCanvas} and not `caret.active`: the caret stack is live
@@ -654,9 +680,9 @@ const hasTarget = (ctx: CommandContext) => ctx.selection.count > 0;
  * (Duplicate, from `commands/defaults.ts`) and `9_danger` (Delete, likewise), which is the order
  * the bar and the Outline rows both render in.
  *
- * No `keybinding` is claimed here on purpose. The chord table is `editor/shortcuts.ts`'s port (plan
- * P2 workstream 4); claiming chords from a panel would decide that port's outcome by accident. The
- * buttons still print the chords of the records that DO carry them.
+ * No `keybinding` is claimed here on purpose. The chord table belongs to `editor/shortcuts.ts`'s
+ * scope-stack dispatcher (§13.3); claiming chords from a panel would decide its contents by
+ * accident. The buttons still print the chords of the records that DO carry them.
  */
 export function registerSelectionCommands(
   registry: CommandRegistry,
@@ -828,7 +854,7 @@ export function selectionCommandRegistry(): CommandRegistry {
   return registry;
 }
 
-/** How many verb buttons the bar renders before the rest fold into `⋮` (plan §3.2 ⑩). */
+/** How many verb buttons render before the rest fold into `⋮` (studio-ui-guidelines.md §12.1). */
 export const BLOCKBAR_MAX_ITEMS = 5;
 
 /**
@@ -996,10 +1022,10 @@ export function dismissBlockBarOverflow(): void {
  * Show the `⋮` menu under `anchor`. Rows carry the same names, chords and refusals as the buttons.
  *
  * Shared by the block action bar and the Outline rows, and it is the KIT menu
- * (`surfaces/menu.json`, §12.5) rather than a list of this surface's own: one popover, one roving
- * caret, one typeahead, one Escape. `target` (the Outline row's node) is captured per row and
- * re-applied when a row is chosen, because a row action acts on the row's node and the hovered row
- * is not the selected one.
+ * (`surfaces/menu.json`, studio-ui-guidelines.md §12.5) rather than a list of this surface's own:
+ * one popover, one roving caret, one typeahead, one Escape. `target` (the Outline row's node) is
+ * captured per row and re-applied when a row is chosen, because a row action acts on the row's node
+ * and the hovered row is not the selected one.
  */
 export function showCommandOverflow(
   anchor: HTMLElement,
@@ -1192,10 +1218,10 @@ export function isLinkPopoverOpen(): boolean {
  * snapshot; Apply/Remove post `applyFormat` link intents the iframe applies.
  *
  * By RECORD ID, not by rendered text. This queried `sp-action-button[title^="Link"]`, which is the
- * addressing §13's first rule bans in the screenshot manifest — a match on a title the app DERIVES
- * (it now reads "Link… (⌘K)", and on Windows it reads something else again). The id is the input
- * the app accepts, and the button is one the surface ANNOUNCED as it drew it rather than one this
- * module re-finds.
+ * addressing the shot contract's R1 (`scripts/screenshots/README.md`) bans in the screenshot
+ * manifest — a match on a title the app DERIVES (it now reads "Link… (⌘K)", and on Windows it reads
+ * something else again). The id is the input the app accepts, and the button is one the surface
+ * ANNOUNCED as it drew it rather than one this module re-finds.
  */
 export function openLinkPopoverFromShortcut(): void {
   const surface = _surface;
@@ -1413,7 +1439,7 @@ function projectBar(): BlockBarView | null {
     (editingProp ? ` · ${editingProp}` : "");
   // The handle is chrome, not a verb, so it renders on every selection; only a node that actually
   // Sits at a child index can be dragged, and at the root it is a disabled affordance rather than a
-  // Missing one (§8.6: ONE shape).
+  // Missing one (studio-ui-guidelines.md §8.6: ONE shape).
   const canDrag = structuralTarget(selection) !== null;
 
   return {