@jxsuite/studio 2.0.0 → 2.1.0

package/src/services/ai-system-prompt.ts

@@ -24,6 +24,11 @@ interface BuildSystemPromptOptions {
   projectRoot?: string | undefined;
   /** Whether a project is open. Defaults to `!!projectRoot` (kept explicit for tests). */
   hasProject?: boolean | undefined;
+  /**
+   * See {@link AiToolState.treeEditable}. Defaults to true so a caller with no registry — the
+   * prompt-shape tests — advertises the same list it always did.
+   */
+  treeEditable?: boolean | undefined;
   /** Project-relative file paths for the inventory section (project modes; capped). */
   fileInventory?: string[] | undefined;
 }
@@ -34,7 +39,20 @@ const FILE_INVENTORY_CAP = 100;
 // ─── Tool tiers (single source of truth for prompt AND gating) ──────────────
 
 /** Studio state a tool tier requires. Used by the gating registry AND the prompt tool list. */
-export type AiToolTier = "no-project" | "project" | "document";
+/**
+ * `document-tree` is `document` plus the condition the HUMAN's equivalent verbs already carry.
+ *
+ * `Command.aiTool`'s contract is "the human's gate and the agent's gate stay one predicate", and
+ * these two gates were not one. The registry's `selection.delete` / `duplicate` / `moveUp` require
+ * `editor.kind === "canvas"` because the Outline renders whatever the active tab's document is —
+ * with Project Settings open, `project.json` drawn as a layer tree. The assistant's tier asked only
+ * whether a tab existed, so in that exact state the agent was advertised `remove_node` and
+ * `move_node` and executed them against the file that defines the project, while the human's
+ * `delete_node` was refused. `remove_node` self-refuses only the document root (`path.length < 2`),
+ * a weaker test than `structurallyEditable`, so a repeater template or `$switch` case was removable
+ * by the agent and not by the person.
+ */
+export type AiToolTier = "no-project" | "project" | "document" | "document-tree";
 
 export interface AiToolInfo {
   name: string;
@@ -108,63 +126,79 @@ export const AI_TOOL_TIERS: AiToolInfo[] = [
   },
   {
     name: "set_property",
-    tier: "document",
+    tier: "document-tree",
     blurb:
       "set_property(path, key, value) — set or remove a property on the node at path (tagName, textContent, className, style, attributes, $props…). Pass value: null to remove.",
   },
   {
     name: "set_style",
-    tier: "document",
+    tier: "document-tree",
     blurb:
       'set_style(path, property, value) — set or remove a CSS style property (camelCase) on a node. Values as strings: "10px", "var(--color-accent)". Pass value: null to remove.',
   },
   {
     name: "set_text",
-    tier: "document",
+    tier: "document-tree",
     blurb: 'set_text(path, value) — convenient alias for set_property with key: "textContent".',
   },
   {
     name: "add_child",
-    tier: "document",
+    tier: "document-tree",
     blurb:
       "add_child(parentPath, index, node) — insert a new node into the children of parentPath at index.",
   },
   {
     name: "remove_node",
-    tier: "document",
+    tier: "document-tree",
     blurb: "remove_node(path) — remove the node at path.",
   },
   {
     name: "move_node",
-    tier: "document",
+    tier: "document-tree",
     blurb: "move_node(fromPath, toParentPath, toIndex) — move a node from one location to another.",
   },
   {
     name: "add_state",
-    tier: "document",
+    tier: "document-tree",
     blurb:
       "add_state(key, value) — add a reactive state variable under the document's 'state' object. Value can be scalar, typed, computed, function, or data source.",
   },
   {
     name: "update_state",
-    tier: "document",
+    tier: "document-tree",
     blurb: "update_state(key, value) — update or remove (value: null) an existing state variable.",
   },
 ];
 
+/** The studio facts a tier is decided by. An object because four positional booleans is a trap. */
+export interface AiToolState {
+  hasProject: boolean;
+  hasDocument: boolean;
+  /**
+   * The open document is an element tree the canvas is editing — `editor.kind === "canvas"`.
+   *
+   * Read from the COMMAND CONTEXT the human's verbs are evaluated against, not recomputed here, so
+   * the two gates are one predicate rather than two that agree until someone edits one of them.
+   */
+  treeEditable: boolean;
+}
+
 /**
  * Whether a tier's tools are active for the given studio state. Shared semantics with the gating
  * registry: bootstrap tools vanish once a project opens; project tools need a project; document
  * tools need an active document (even in single-file mode without a project).
  */
-export function tierActive(tier: AiToolTier, hasProject: boolean, hasDocument: boolean): boolean {
+export function tierActive(tier: AiToolTier, state: AiToolState): boolean {
   if (tier === "no-project") {
-    return !hasProject;
+    return !state.hasProject;
   }
   if (tier === "project") {
-    return hasProject;
+    return state.hasProject;
+  }
+  if (tier === "document-tree") {
+    return state.hasDocument && state.treeEditable;
   }
-  return hasDocument;
+  return state.hasDocument;
 }
 
 // ─── Jx Schema Reference (condensed) ────────────────────────────────────────
@@ -525,12 +559,17 @@ export function buildSystemPrompt({
   components,
   projectRoot,
   hasProject = Boolean(projectRoot),
+  treeEditable = true,
   fileInventory,
 }: BuildSystemPromptOptions = {}) {
   const hasDocument = Boolean(document);
 
   // 1. Role, state-appropriate workflow, and the tool list for the current state.
-  const toolList = AI_TOOL_TIERS.filter((t) => tierActive(t.tier, hasProject, hasDocument))
+  // The list the model is TOLD about and the list the gate will honour are the same filter, so a
+  // Refusal is never a surprise to it.
+  const toolList = AI_TOOL_TIERS.filter((t) =>
+    tierActive(t.tier, { hasDocument, hasProject, treeEditable }),
+  )
     .map((t) => `- ${t.blurb}`)
     .join("\n");
 

package/src/services/ai-tools.ts

@@ -27,6 +27,7 @@ import {
 } from "../tabs/transact";
 import type { JxNodeValue } from "../tabs/transact";
 import { validateDoc } from "./jx-validate";
+import { recordWrite } from "./ai-writes";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
 
 const PATH_DESCRIPTION =
@@ -127,7 +128,24 @@ async function applyAndValidate(
   const before = new Set(await validate(rawBefore));
   const renderOkBefore = renderCheck ? await renderCheck(rawBefore) : { ok: true };
 
-  transactDoc(tab, mutationFn);
+  /* AND THE WRITE CAN BE REFUSED, in which case the model must be told rather than congratulated.
+     The collab gate pauses structural editing while source is canonical, and this went on to
+     record a ledger entry ("Changed N files") and validate the UNCHANGED document — which produces
+     no new errors, so the tool answered `success: true`. The model then built its next three edits
+     on a change that never existed. A refusal is an ordinary state of the room, so it is an error
+     result with a reason the model can act on (wait, or ask the author), not a thrown exception. */
+  if (!transactDoc(tab, mutationFn)) {
+    return {
+      success: false,
+      error:
+        "The document is frozen: a collaborator is editing its source, so structural edits are " +
+        "paused. Nothing was changed. Try again once source editing ends.",
+    };
+  }
+  /* One ledger entry per mutation, so the panel's "Changed N files" counts documents the model
+     touched rather than sentences it wrote (§7.4). `disk: false` is the load-bearing half: this
+     went through transactDoc, so the tab's history — and "Restore to here" — can reach it. */
+  recordWrite({ disk: false, ok: true, path: tab.documentPath ?? "(untitled)", tool: summary });
 
   const rawAfter = toRaw(tab.doc.document);
   const after = await validate(rawAfter);
@@ -734,14 +752,23 @@ export function registerAiTools(
         }
         try {
           await saveFile(relPath, JSON.stringify(content, null, 2));
+          recordWrite({ disk: true, ok: true, path: relPath, tool: "create_component" });
           return {
             success: true,
             summary: await reconcileAfterWrite(relPath, `Created component at "${relPath}".`),
           };
         } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          recordWrite({
+            disk: true,
+            error: message,
+            ok: false,
+            path: relPath,
+            tool: "create_component",
+          });
           return {
             success: false,
-            error: `Failed to write file: ${error instanceof Error ? error.message : String(error)}`,
+            error: `Failed to write file: ${message}`,
           };
         }
       },
@@ -802,14 +829,23 @@ export function registerAiTools(
         }
         try {
           await saveFile(relPath, JSON.stringify(content, null, 2));
+          recordWrite({ disk: true, ok: true, path: relPath, tool: "create_page" });
           return {
             success: true,
             summary: await reconcileAfterWrite(relPath, `Created page at "${relPath}".`),
           };
         } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          recordWrite({
+            disk: true,
+            error: message,
+            ok: false,
+            path: relPath,
+            tool: "create_page",
+          });
           return {
             success: false,
-            error: `Failed to write file: ${error instanceof Error ? error.message : String(error)}`,
+            error: `Failed to write file: ${message}`,
           };
         }
       },

package/src/services/ai-writes.ts

@@ -0,0 +1,154 @@
+/**
+ * Ai-writes.ts — what the assistant changed, per turn, and whether you can take it back.
+ *
+ * §7.4 (AI honesty). Two facts about an assistant turn were legible only to the model:
+ *
+ * 1. **Which files it changed.** The loop collected `result.summary` strings and fed them back into
+ *    the conversation; the human got a paragraph of prose in which "I updated the hero" and "I
+ *    rewrote layouts/base.json" are the same shape of sentence.
+ * 2. **Which of those changes undo can reach.** Document tools mutate through `transactDoc`, so ⌘Z
+ *    covers them. `write_file` and `write_project_config` go straight to disk through the platform,
+ *    where there is no history and never was — and the caveat was appended to the MODEL-facing tool
+ *    summary, telling the party that cannot press ⌘Z and not the party that can.
+ *
+ * A ledger rather than a parse of the summaries, because a summary is prose the model reads and a
+ * ledger is a record the UI renders — deriving one from the other would make the panel's honesty
+ * depend on the wording of a sentence written for somebody else.
+ *
+ * The tools record; the loop bounds the turn; the panel renders. Nothing here knows about lit, and
+ * nothing here imports the loop, so a tool can be honest without either.
+ */
+
+/** One change the assistant made, as recorded by the tool that made it. */
+export interface AiWrite {
+  /** Project-relative path, or the document path for an in-editor mutation. */
+  path: string;
+  /** The tool that did it — the command title the chip renders. */
+  tool: string;
+  /**
+   * True when the change went to disk with no transaction behind it.
+   *
+   * This is the undo caveat, as a fact rather than a sentence: a `disk` write is NOT reachable by
+   * ⌘Z, by the tab's history, or by "Restore to here". The panel says so, in those words, to the
+   * person who would otherwise press ⌘Z and believe it worked.
+   */
+  disk: boolean;
+  /** False when the tool reported a failure — a listed attempt that changed nothing. */
+  ok: boolean;
+  /** Why it failed, when it did. */
+  error?: string;
+}
+
+/** Every write recorded during one assistant turn, in the order the tools made them. */
+export interface AiTurn {
+  /** The id of the assistant message the turn produced — how the panel finds its own ledger. */
+  id: string;
+  writes: AiWrite[];
+}
+
+/** Completed turns, oldest first. Bounded: a session's history is the session store's job. */
+const turns: AiTurn[] = [];
+
+/** How many turns of ledger are kept. Older ones drop their summary; the messages remain. */
+export const MAX_TURNS = 50;
+
+let open: AiTurn | null = null;
+
+/**
+ * Start recording. Called by the agent loop once per user turn.
+ *
+ * Idempotent on the same id so a nested or re-entered loop cannot split one turn's writes across
+ * two ledgers — which is the same class of bug as the batch that was opened against whichever tab
+ * happened to be active.
+ *
+ * @param {string} id
+ */
+export function beginTurn(id: string): void {
+  if (open?.id === id) {
+    return;
+  }
+  open = { id, writes: [] };
+}
+
+/**
+ * Record one change. A no-op when no turn is open, so a tool invoked outside the loop — a command,
+ * a test — costs nothing and reports nothing.
+ *
+ * @param {AiWrite} write
+ */
+export function recordWrite(write: AiWrite): void {
+  open?.writes.push(write);
+}
+
+/**
+ * Close the open turn and file it under `id`.
+ *
+ * The id arrives at the END because it is the assistant message's id, which does not exist when the
+ * turn starts — the loop opens the turn before it knows what the model will say.
+ *
+ * @param {string} id - The assistant message the turn produced
+ * @returns {AiWrite[]} What was recorded
+ */
+export function endTurn(id: string): AiWrite[] {
+  if (!open) {
+    return [];
+  }
+  const turn: AiTurn = { id, writes: open.writes };
+  open = null;
+  if (turn.writes.length === 0) {
+    return [];
+  }
+  turns.push(turn);
+  while (turns.length > MAX_TURNS) {
+    turns.shift();
+  }
+  return turn.writes;
+}
+
+/**
+ * What the turn that produced this assistant message changed. Empty for a turn that changed
+ * nothing, which is why the panel renders no summary at all rather than "Changed 0 files".
+ *
+ * @param {string} id
+ * @returns {AiWrite[]}
+ */
+export function writesForTurn(id: string): AiWrite[] {
+  return turns.find((turn) => turn.id === id)?.writes ?? [];
+}
+
+/**
+ * The one-line summary the panel puts above the expander.
+ *
+ * Counts DISTINCT paths, not writes: a turn that edits the same document six times changed one
+ * file, and saying "Changed 6 files" would be the same dishonesty in the other direction. Disk
+ * writes are called out separately because they are the ones undo cannot reach.
+ *
+ * @param {AiWrite[]} writes
+ * @returns {string}
+ */
+export function summarizeWrites(writes: AiWrite[]): string {
+  const applied = writes.filter((w) => w.ok);
+  const paths = new Set(applied.map((w) => w.path));
+  const failed = writes.length - applied.length;
+  if (paths.size === 0) {
+    return failed > 0 ? `${failed} change${failed === 1 ? "" : "s"} failed` : "";
+  }
+  const files = `Changed ${paths.size} file${paths.size === 1 ? "" : "s"}`;
+  const diskPaths = new Set(applied.filter((w) => w.disk).map((w) => w.path));
+  const parts = [files];
+  if (diskPaths.size > 0) {
+    parts.push(
+      `${diskPaths.size} written to disk — undo cannot reach ${diskPaths.size === 1 ? "it" : "them"}`,
+    );
+  }
+  if (failed > 0) {
+    parts.push(`${failed} failed`);
+  }
+  return parts.join(" · ");
+}
+
+/** Drop every ledger. For tests and for the "new chat" / "close project" paths. */
+export function resetAiWrites(): void {
+  turns.splice(0);
+  open = null;
+}

package/src/services/announce.ts

@@ -0,0 +1,97 @@
+/**
+ * The app's live region: one element, one call site, everything the app says out loud.
+ *
+ * **Why this exists.** `notify.ts` is the app's only way to say what happened, and its default tier
+ * routes **error ⇒ problem**. But the `role="status"` region lived on the _toast_ host, and the
+ * Problems panel had none at all — so a **failure reached no live region whatsoever**. The app
+ * would post "Save failed", show it in a panel, and a screen-reader user would be told nothing. A
+ * panel-local region would not have fixed it either: the Problems list lives in the Bottom dock,
+ * and a region inside a hidden tab announces nothing.
+ *
+ * So the announcer is not a panel's concern. It is called from {@link notify} itself — one call
+ * site, so a record cannot be posted without being announced, and a future host gets announcements
+ * for free rather than having to remember.
+ *
+ * **Two regions, because politeness is not a style choice** (WAI-ARIA §5.2.9). `assertive`
+ * interrupts whatever the reader is listening to, which is right for a failure and rude for a save.
+ * `polite` waits for a pause. Mixing both in one region does not work — the attribute is read when
+ * the region is created, not when the text changes — so there are two, and the severity picks.
+ *
+ * **The text is cleared, then set on a later frame.** A live region announces a _change_; writing
+ * the same string twice is not one, so a repeated failure would be silent. Clearing first makes
+ * every post a change.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+/** How urgently a message interrupts. Errors interrupt; everything else waits for a pause. */
+export type Politeness = "assertive" | "polite";
+
+const REGION_ID: Readonly<Record<Politeness, string>> = {
+  assertive: "jx-live-assertive",
+  polite: "jx-live-polite",
+};
+
+/**
+ * Find (or create) a live region.
+ *
+ * It is appended to `<body>` rather than to any panel, and it is visually hidden with the clip-rect
+ * idiom rather than `display: none` — a display-none region is removed from the accessibility tree
+ * entirely and announces nothing, which is the classic way to ship a live region that does not
+ * work.
+ */
+function region(politeness: Politeness): HTMLElement | null {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const id = REGION_ID[politeness];
+  const existing = document.querySelector<HTMLElement>(`#${id}`);
+  if (existing) {
+    return existing;
+  }
+  const node = document.createElement("div");
+  node.id = id;
+  node.setAttribute("aria-live", politeness);
+  /* `status` for polite and `alert` for assertive: the implicit roles, so an assistive technology
+     that reads roles rather than the attribute agrees with one that does the opposite. */
+  node.setAttribute("role", politeness === "assertive" ? "alert" : "status");
+  node.setAttribute("aria-atomic", "true");
+  node.style.cssText =
+    "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;" +
+    "clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0";
+  document.body.append(node);
+  return node;
+}
+
+/**
+ * Say something out loud.
+ *
+ * @param {string} message What to announce. Empty strings are ignored — a live region that receives
+ *   one announces nothing, so posting it only hides a caller's bug.
+ * @param {Politeness} [politeness] Defaults to `polite`.
+ */
+export function announce(message: string, politeness: Politeness = "polite"): void {
+  if (message === "") {
+    return;
+  }
+  const node = region(politeness);
+  if (!node) {
+    return;
+  }
+  node.textContent = "";
+  /* A live region announces a CHANGE. Writing the same string twice is not one, so a second
+     identical failure would be silent without the clear-then-set on a later turn. */
+  setTimeout(() => {
+    node.textContent = message;
+  }, 0);
+}
+
+/** Remove both regions. Tests only — a leaked region makes the next test's assertions ambiguous. */
+export function resetAnnouncer(): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  for (const id of Object.values(REGION_ID)) {
+    document.querySelector(`#${id}`)?.remove();
+  }
+}