@jxsuite/studio 4.1.0 → 5.1.0

package/src/services/model-uri.ts

@@ -29,3 +29,78 @@ export const ENTRY_SCHEMA_FILES = new Set(["project.schema.json", "document.sche
 export function modelUriFor(path: string): string {
   return ENTRY_SCHEMA_FILES.has(path) ? `file:///.jx/generated/${path}` : `file:///${path}`;
 }
+
+/**
+ * The two model URIs a comparison's Monaco diff editor mounts at.
+ *
+ * **A reserved namespace, because the collision is otherwise unrepresentable-by-luck rather than
+ * unrepresentable.** Two models on one URI throws (`Cannot create model because a model with the
+ * same URI already exists`), and `workspace/pane-derive.ts` refuses a Code lens on a file whose
+ * source editor is already open for exactly that reason. A diff editor is a THIRD claimant on the
+ * same path, and neither existing guard can see it: one asks about panes, the other about presets.
+ * Disjoint URIs make the collision impossible instead of refused.
+ *
+ * **Per pane**, because the primary can hold a comparison in Code while a Diff lens beside it holds
+ * the same file's — two diff editors over one file, four models, all four distinct.
+ *
+ * The cost, stated: a relative `$schema` resolves against the model URI, so the HEAD side gets no
+ * JSON validation. That is correct rather than merely tolerable — a comparison is read-only, and
+ * red squiggles on a git object nobody can edit would be noise. The Code lens on the real URI keeps
+ * its markers.
+ *
+ * @param {string} paneId
+ * @param {string} path - Project-relative file path
+ * @returns {{ head: string; work: string }}
+ */
+export function diffModelUrisFor(paneId: string, path: string): { head: string; work: string } {
+  return {
+    head: `file:///.jx/diff/${paneId}/head/${path}`,
+    work: `file:///.jx/diff/${paneId}/work/${path}`,
+  };
+}
+
+/**
+ * Monaco's language id for a path, for a buffer with no tab and no format class behind it.
+ *
+ * `sourceLang` answers from a Tab's format class, which a comparison may not have: a diff can be
+ * over a `.ts`, a `.css` or a `.gitignore`, none of which opens as a document at all. Unknown
+ * extensions resolve to `plaintext` rather than being forced into a registered language —
+ * `monaco-setup` contributes only JSON, TypeScript and JavaScript, and the red/green line
+ * decorations come from the diff algorithm rather than from a tokenizer, so plaintext loses
+ * highlighting and nothing else.
+ */
+export function monacoLangForPath(path: string): string {
+  const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+  switch (ext) {
+    case "cjs":
+    case "js":
+    case "mjs": {
+      return "javascript";
+    }
+    case "css": {
+      return "css";
+    }
+    case "htm":
+    case "html": {
+      return "html";
+    }
+    case "json": {
+      return "json";
+    }
+    case "md": {
+      return "markdown";
+    }
+    case "cts":
+    case "mts":
+    case "ts": {
+      return "typescript";
+    }
+    case "yaml":
+    case "yml": {
+      return "yaml";
+    }
+    default: {
+      return "plaintext";
+    }
+  }
+}

package/src/services/notify.ts

@@ -14,12 +14,13 @@
  * | `toast`   | the fourth overlay layer   | timed, dismissible | reversible, or needs no action |
  * | `problem` | the Bottom dock's Problems | until it is fixed  | it must be fixed               |
  *
- * §7.1 names a third tier — **inline**, the `error` slot on `ui/field-row.ts`'s `renderFieldRow`.
- * It is deliberately NOT a member of {@link NotificationTier}: an inline error is a value a control
- * renders next to the field the user is editing, not a record the app posts to a host, and it has
- * no store to live in. Declaring a tier here whose only possible outcome is being dropped on the
- * floor would be exactly the silence this module exists to end, so the union has two members and
- * the third tier arrives as `renderFieldRow`'s own parameter (P4.4).
+ * §7.1 names a third tier — **inline**, the refusal a field draws at the control (`jx-field`'s own
+ * `[part="error"]`, projected by whichever inspector document owns the row). It is deliberately NOT
+ * a member of {@link NotificationTier}: an inline error is a value a control renders next to the
+ * field the user is editing, not a record the app posts to a host, and it has no store to live in.
+ * Declaring a tier here whose only possible outcome is being dropped on the floor would be exactly
+ * the silence this module exists to end, so the union has two members and the third tier arrives as
+ * a field's own projected value (P4.4).
  *
  * **Recovery is a command id, not a per-call-site closure.** `notify.error("Save failed", { action:
  * "file.save" })` gives the toast and the Problems row a Retry button whose label, availability,
@@ -254,6 +255,62 @@ export function clearProblems(match?: (record: Notification) => boolean): number
   return removed;
 }
 
+/**
+ * One outstanding problem, as a REPORT hands it to a caller that cannot see the store: the
+ * assistant, whose `check_accessibility` / `check_popovers` / `validate_redirects` tools return the
+ * findings the person sees in the dock as `ToolResult.data`.
+ *
+ * The record's identity and clock are left out on purpose (`id` is a lit key, `at` is for "2m
+ * ago"); what remains is what a reader acts on — the sentence, the long form, the file, how bad it
+ * is, and the repair command a Fix button would run.
+ */
+export interface ProblemFinding {
+  message: string;
+  severity: Severity;
+  detail?: string;
+  path?: string;
+  key?: string;
+  action?: string;
+  actionArgs?: Record<string, unknown>;
+}
+
+/**
+ * The outstanding problems one reporter filed, in the order they were filed — the same read the
+ * Problems tab makes when it groups by `source`, projected to {@link ProblemFinding}.
+ *
+ * @param {string} source - The `source` the reporter files under.
+ * @returns {ProblemFinding[]}
+ */
+export function problemFindings(source: string): ProblemFinding[] {
+  const findings: ProblemFinding[] = [];
+  for (const record of problems) {
+    if (record.source !== source) {
+      continue;
+    }
+    const finding: ProblemFinding = { message: record.message, severity: record.severity };
+    /* Copied key by key rather than spread from the record: `exactOptionalPropertyTypes` refuses
+       an explicit `undefined`, and the model reads the JSON, where an absent key and an undefined
+       one serialise the same but a `undefined`-valued key is a lie about what the row holds. */
+    if (record.detail !== undefined) {
+      finding.detail = record.detail;
+    }
+    if (record.path !== undefined) {
+      finding.path = record.path;
+    }
+    if (record.key !== undefined) {
+      finding.key = record.key;
+    }
+    if (record.action !== undefined) {
+      finding.action = record.action;
+    }
+    if (record.actionArgs !== undefined) {
+      finding.actionArgs = record.actionArgs;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}
+
 /** How many problems are outstanding, optionally of one severity — the badge and the status bar. */
 export function problemCount(severity?: Severity): number {
   return severity === undefined

package/src/services/popover-report.ts

@@ -0,0 +1,325 @@
+/**
+ * Popover correctness over the document an author is editing.
+ *
+ * A second document report beside the accessibility one, and separate from it on purpose: an
+ * `A11yFinding` is typed to a WCAG criterion, and none of these are WCAG failures. A popover whose
+ * base rule sets `display` is not inaccessible, it is BROKEN — laid out on every page whether or
+ * not anyone opened it — and forcing that into a criterion field would be a lie in the report's own
+ * vocabulary. `popover-unnamed` is the one finding that genuinely IS a WCAG matter, and it belongs
+ * to `a11y-report.ts` rather than here.
+ *
+ * The rules themselves live in `@jxsuite/schema/overlays`, not in this file. Three surfaces judge
+ * the same documents — this report, `jx build`, and the starter conformance test — and three copies
+ * of "what is wrong with a popover" is three chances for them to disagree with each other in front
+ * of an author.
+ *
+ * **Every finding that can be repaired carries the command that repairs it** (ATAG 2.0 B.3.2), and
+ * the ones that cannot carry none. "Point this invoker at the right panel" has no mechanical answer
+ * — which panel is the author's decision — so that finding is a sentence, not a button. A button
+ * that does not do what it says is worse than no button.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+import { activeTab } from "../workspace/workspace";
+import { clearProblems, notify, problemFindings } from "./notify";
+import {
+  findPopoverDefects,
+  popoverDisplayRepair,
+  POPOVER_DEFAULT_MODE,
+} from "@jxsuite/schema/overlays";
+import { findDialogDefects } from "@jxsuite/schema/dialogs";
+import { INVOKER_TAGS, POPOVER_TAGS } from "@jxsuite/ui";
+import {
+  mutateUpdateAttribute,
+  mutateUpdateNestedStyle,
+  mutateUpdateNestedStylePath,
+  mutateUpdateStyle,
+  transactDoc,
+} from "../tabs/transact";
+import { getNodeAtPath } from "../state";
+import type { AnyCommand, CommandRegistry } from "../commands/registry";
+import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
+import type { JxPath } from "../state";
+import type { PopoverFix, PopoverPath } from "@jxsuite/schema/overlays";
+
+/** The `source` every record here files under, so a re-run clears exactly its own. */
+/**
+ * What the kit's own elements are, so the lints judge them as what they render rather than as
+ * unknown tags: an overlay element IS a popover, and a kit button IS an invoker.
+ */
+const KIT_SCOPE = { invokerTags: INVOKER_TAGS, popoverTags: POPOVER_TAGS };
+
+export const POPOVER_PROBLEM_SOURCE = "Popover";
+
+/** The command that repairs each fix kind. A finding with no fix carries no action. */
+const REPAIR_COMMAND: Record<PopoverFix, string> = {
+  display: "document.repairPopoverDisplay",
+  "open-display": "document.repairPopoverDisplay",
+  invoker: "document.repairPopoverInvoker",
+  mode: "document.repairPopoverMode",
+};
+
+/**
+ * The Problem key for one defect, with an ordinal when this run has already keyed one just like it.
+ *
+ * Rule and path are not enough on their own, because one node can carry several defects of ONE
+ * rule: `breakpoint-display` files one per `@media` block that sets `display`, so a panel with two
+ * of them is two defects sharing a rule and a path. A Problem key REPLACES rather than stacks, so
+ * the author was told about the last block and never heard about the earlier one. The first
+ * occurrence keeps the bare key, so nothing already distinct moves.
+ *
+ * @param seen How many keys of each shape this run has filed already, mutated in place.
+ * @param prefix The report half filing it, `popover` or `dialog`.
+ * @param rule The defect's rule id.
+ * @param path The node the defect is about.
+ * @returns The key to file it under.
+ */
+function problemKey(
+  seen: Map<string, number>,
+  prefix: string,
+  rule: string,
+  path: PopoverPath,
+): string {
+  const base = `${prefix}.${rule}.${path.join("/")}`;
+  const before = seen.get(base) ?? 0;
+  seen.set(base, before + 1);
+  return before === 0 ? base : `${base}#${before}`;
+}
+
+/**
+ * File every popover defect in `doc` as a Problem, replacing whatever this source filed before.
+ *
+ * @param doc The document to check.
+ * @param path The document's project-relative path, for the Problem's file column.
+ * @returns How many findings were filed.
+ */
+export function reportPopoverProblems(doc: JxElement, path?: string): number {
+  clearProblems((record) => record.source === POPOVER_PROBLEM_SOURCE);
+  const seen = new Map<string, number>();
+  const defects = findPopoverDefects(doc, KIT_SCOPE);
+  for (const defect of defects) {
+    const action = defect.fix === undefined ? undefined : REPAIR_COMMAND[defect.fix];
+    notify(defect.severity, defect.message, {
+      detail: defect.detail,
+      /* Keyed by RULE AND PATH, not by rule alone: a header with two popovers can carry the same
+         defect twice, and a key that collapsed them would report one and silently drop the other.
+         The ordinal `problemKey` adds is the other half of that: one node can also carry the same
+         rule twice, which rule and path alone cannot tell apart either. */
+      key: problemKey(seen, "popover", defect.rule, defect.path),
+      source: POPOVER_PROBLEM_SOURCE,
+      tier: "problem",
+      ...(action === undefined ? {} : { action, actionArgs: { path: defect.path } }),
+      ...(path === undefined ? {} : { path }),
+    });
+  }
+  /* The dialog and invoker-command rules (spec §8.7) file under the same source: one report for
+     everything the platform overlays. They carry no repair button yet — the popover repairs move
+     `display` into `:popover-open`, and a dialog's open rule is a different selector. */
+  const dialogDefects = findDialogDefects(doc, KIT_SCOPE);
+  for (const defect of dialogDefects) {
+    notify(defect.severity, defect.message, {
+      detail: defect.detail,
+      key: problemKey(seen, "dialog", defect.rule, defect.path),
+      source: POPOVER_PROBLEM_SOURCE,
+      tier: "problem",
+      ...(path === undefined ? {} : { path }),
+    });
+  }
+  return defects.length + dialogDefects.length;
+}
+
+/** Read the path argument a repair command was invoked with, or throw naming the command. */
+function repairPath(id: string, args: Record<string, unknown> | undefined): JxPath {
+  const path = args?.path;
+  if (!Array.isArray(path)) {
+    throw new RangeError(`command "${id}" needs a "path" argument naming the popover`);
+  }
+  return path as JxPath;
+}
+
+/** The active tab, or a refusal naming the command that needed one. */
+function repairTab(id: string) {
+  const tab = activeTab.value;
+  if (!tab) {
+    throw new RangeError(`command "${id}" needs an open document`);
+  }
+  return tab;
+}
+
+/**
+ * The three repairs, and the registrar that keeps them out of a second definition site.
+ *
+ * Each one is a single `transactDoc`, so the whole move is ONE undo entry: an author who does not
+ * like the result presses undo once, not three times.
+ *
+ * @returns The command records.
+ */
+export function popoverCommands(): AnyCommand[] {
+  return [
+    {
+      category: "Document",
+      group: "2_document",
+      id: "document.checkPopovers",
+      level: "document",
+      menus: ["palette"],
+      requires: "an open document",
+      run: () => {
+        const tab = repairTab("document.checkPopovers");
+        const filed = reportPopoverProblems(tab.doc.document, tab.documentPath ?? undefined);
+        notify.success(
+          filed === 0
+            ? "No popover problems found in this document."
+            : `${filed} popover problem(s) filed.`,
+          { key: "popover.run", source: POPOVER_PROBLEM_SOURCE },
+        );
+      },
+      title: "Check Popovers",
+      when: (ctx) => ctx.document.open,
+      aiTool: {
+        description:
+          "Check the open document for popover defects an author can fix — a base-rule `display` " +
+          "that defeats the browser's own hiding of a closed popover, `popovertarget` on an " +
+          "element that cannot invoke, a target naming no popover, a cut exit animation — and " +
+          "file each as a Problem. The findings come back as data.",
+        name: "check_popovers",
+        /* Same shape and reason as `check_accessibility`: the Problems store filtered by this
+           source is the panel's own read, and each finding carries the repair command it offers. */
+        report: () => {
+          const findings = problemFindings(POPOVER_PROBLEM_SOURCE);
+          const n = findings.length;
+          return {
+            data: findings,
+            summary:
+              n === 0
+                ? "No popover problems found in this document."
+                : `Filed ${n} popover problem${n === 1 ? "" : "s"} in Problems.`,
+          };
+        },
+      },
+    },
+    {
+      args: {
+        additionalProperties: false,
+        properties: {
+          path: { items: { type: ["string", "number"] }, type: "array" },
+        },
+        required: ["path"],
+        type: "object",
+      },
+      category: "Document",
+      group: "2_document",
+      id: "document.repairPopoverDisplay",
+      level: "document",
+      menus: [],
+      requires: "a popover whose base rule sets display",
+      run: (_ctx, args) => {
+        const id = "document.repairPopoverDisplay";
+        const tab = repairTab(id);
+        const path = repairPath(id, args);
+        const node = getNodeAtPath(tab.doc.document, path) as JxMutableNode | undefined;
+        const repair = popoverDisplayRepair(node?.style);
+        if (!repair) {
+          throw new RangeError(`command "${id}": nothing to move — this popover sets no display`);
+        }
+        transactDoc(tab, (t) => {
+          for (const prop of repair.base) {
+            mutateUpdateStyle(t, path, prop, "");
+          }
+          for (const at of repair.breakpoints) {
+            mutateUpdateNestedStylePath(t, path, [at], "display", "");
+          }
+          /* `openDisplay` is null when `:popover-open` already declares one. The open state is the
+             author's intent and the base rule is the accident, so the existing value is kept. */
+          if (repair.openDisplay !== null) {
+            mutateUpdateNestedStyle(t, path, ":popover-open", "display", repair.openDisplay);
+          }
+        });
+        notify.success("Moved `display` into `:popover-open`.", {
+          key: "popover.repaired.display",
+          source: POPOVER_PROBLEM_SOURCE,
+        });
+      },
+      title: "Move display into :popover-open",
+      when: (ctx) => ctx.document.open,
+    },
+    {
+      args: {
+        additionalProperties: false,
+        properties: {
+          path: { items: { type: ["string", "number"] }, type: "array" },
+        },
+        required: ["path"],
+        type: "object",
+      },
+      category: "Document",
+      group: "2_document",
+      id: "document.repairPopoverInvoker",
+      level: "document",
+      menus: [],
+      requires: "an element carrying popovertarget that cannot invoke",
+      run: (_ctx, args) => {
+        const id = "document.repairPopoverInvoker";
+        const tab = repairTab(id);
+        const path = repairPath(id, args);
+        /* REMOVES rather than converting the element to a <button>. The two attributes do nothing
+           where they are, so removing them changes no behaviour and tells the truth; turning a link
+           into a button changes the page, and which of the two the author wants is not knowable
+           from here. */
+        transactDoc(tab, (t) => {
+          mutateUpdateAttribute(t, path, "popovertarget");
+          mutateUpdateAttribute(t, path, "popovertargetaction");
+        });
+        notify.success("Removed the attributes, which did nothing on this element.", {
+          key: "popover.repaired.invoker",
+          source: POPOVER_PROBLEM_SOURCE,
+        });
+      },
+      title: "Remove the inert popover attributes",
+      when: (ctx) => ctx.document.open,
+    },
+    {
+      args: {
+        additionalProperties: false,
+        properties: {
+          path: { items: { type: ["string", "number"] }, type: "array" },
+        },
+        required: ["path"],
+        type: "object",
+      },
+      category: "Document",
+      group: "2_document",
+      id: "document.repairPopoverMode",
+      level: "document",
+      menus: [],
+      requires: "a popover whose mode is not one of the three keywords",
+      run: (_ctx, args) => {
+        const id = "document.repairPopoverMode";
+        const tab = repairTab(id);
+        const path = repairPath(id, args);
+        transactDoc(tab, (t) => {
+          mutateUpdateAttribute(t, path, "popover", POPOVER_DEFAULT_MODE);
+        });
+        notify.success(`Set \`popover\` to "${POPOVER_DEFAULT_MODE}".`, {
+          key: "popover.repaired.mode",
+          source: POPOVER_PROBLEM_SOURCE,
+        });
+      },
+      title: "Set popover to auto",
+      when: (ctx) => ctx.document.open,
+    },
+  ];
+}
+
+/**
+ * Register them on a live registry.
+ *
+ * A registrar as well as a factory, for the reason `a11y-report.ts` gives: `appCommandSet()` and
+ * the running app are two different code paths, and a record in one and not the other is a command
+ * CI counts and the app cannot run.
+ *
+ * @param registry The registry to register into.
+ */
+export function registerPopoverCommands(registry: CommandRegistry): void {
+  registry.registerAll(popoverCommands());
+}

package/src/services/surface-registry.ts

@@ -0,0 +1,56 @@
+/**
+ * Every mounted surface document, by root.
+ *
+ * The shell holds many Jx roots at once — one per surface — and needs to answer two questions about
+ * them that neither the runtime nor the DOM can: which roots render a given custom element (so a
+ * redefinition can re-mount exactly those), and which roots came from a given surface document (so
+ * a saved edit to that document re-mounts them). `mountSurface` registers here and unregisters on
+ * dispose; nothing else writes.
+ */
+
+export interface SurfaceMount {
+  readonly id: number;
+  /** The surface name the document was registered under. */
+  readonly name: string;
+  readonly host: HTMLElement;
+  /** Custom-element tags the render instantiated, as the runtime reported them. */
+  readonly elements: ReadonlySet<string>;
+  /** Dispose and mount again into the same host with the same scope. */
+  readonly remount: () => Promise<void>;
+}
+
+const mounts = new Map<number, SurfaceMount>();
+let nextId = 1;
+
+/** Record a mount; returns the id `unregisterMount` takes. */
+export function registerMount(entry: Omit<SurfaceMount, "id">): number {
+  const id = nextId;
+  nextId += 1;
+  mounts.set(id, { ...entry, id });
+  return id;
+}
+
+export function unregisterMount(id: number): void {
+  mounts.delete(id);
+}
+
+/** Every live mount, in mount order. */
+export function surfaceMounts(): SurfaceMount[] {
+  return [...mounts.values()];
+}
+
+/** The mounts whose render instantiated `tag`. */
+export function mountsUsing(tag: string): SurfaceMount[] {
+  const lower = tag.toLowerCase();
+  return surfaceMounts().filter((m) => m.elements.has(lower));
+}
+
+/** The mounts of one surface document. */
+export function mountsOf(name: string): SurfaceMount[] {
+  return surfaceMounts().filter((m) => m.name === name);
+}
+
+/** Forget every mount without disposing it — for tests. */
+export function resetSurfaceRegistry(): void {
+  mounts.clear();
+}

package/src/services/tool-executor.ts

@@ -126,6 +126,12 @@ export async function runAgentLoop({
             chatState.appendDelta(event.content);
             break;
           }
+          case "reasoning": {
+            /* Kept on the turn, not shown as answer text — the next round has to replay it (see
+               chat-state's toMessagesArray). */
+            chatState.appendReasoning(event.content);
+            break;
+          }
           case "tool_call_start": {
             chatState.appendToolCallStart(event.id, event.name);
             toolCalls.set(event.id, { name: event.name, arguments: "" });