@jxsuite/studio 4.0.0 → 5.0.0

package/src/commands/command-args.ts

@@ -4,8 +4,12 @@
  * Every scriptable command carries an `args` JSON Schema (spec §13.1, plan §13.3): the palette
  * prompts from it, the AI tool's parameters are it, and `scripts/check-shot-contract.ts` validates
  * every manifest step against it in the `checks` job. This module is the RUNTIME half of that same
- * declaration — the four lines inside `run` that turn `Record<string, unknown>` into the typed
- * value the implementation wants.
+ * declaration, twice over: the typed readers a `run` body calls (`stringArg(...)` and its family),
+ * and {@link coerceArgs}, which `registry.run` applies to the received record BEFORE `run` for
+ * every caller — the palette, `__jxAutomation`, the assistant and a chord alike. The coercion
+ * dispatches each declared property to the reader its shape names, so a caller reads the same
+ * refusal sentence whether the schema or the `run` body caught it: they are the same functions
+ * reading the same values, and cannot disagree.
  *
  * Two rules, and they are the reason this is a module rather than twelve copies of `String(x)`:
  *
@@ -115,10 +119,12 @@ export function enumArg<T extends string>(
 ): T {
   const value = args[key];
   if (typeof value !== "string" || !(declared as readonly string[]).includes(value)) {
+    // `none` for an empty set: a derived enum (`derivedEnumProperty`) is honestly empty before the
+    // Project supplies its values, and "declared: " with nothing after it reads as a truncation.
     throw refuse(
       commandId,
       key,
-      `${describe(value)} is not declared — declared: ${declared.join(", ")}`,
+      `${describe(value)} is not declared — declared: ${declared.join(", ") || "none"}`,
     );
   }
   return value as T;
@@ -194,9 +200,11 @@ export function pathListArg(
 }
 
 // ─── Schema fragments ─────────────────────────────────────────────────────────
-// The declarations above are enforced at RUN time; these are the same facts in the form the palette
-// Prompt, the AI tool's parameter list and Lane 1's static check read. Keeping the pair adjacent is
-// Deliberate: a schema that disagrees with its coercion is the defect this module exists to prevent.
+// The readers above are what a `run` body calls; these are the same facts in the form the palette
+// Prompt, the AI tool's parameter list and Lane 1's static check read. The pair used to be kept
+// Adjacent so a reviewer could see that a schema agreed with its coercion; `coerceArgs` below made
+// Them ONE call site, so a schema that disagrees with its coercion is now a refusal rather than a
+// Defect a reviewer has to spot — which is what this module exists to prevent.
 
 /** `{ type: "object", properties, required, additionalProperties: false }` in one call. */
 export function argsSchema(
@@ -280,3 +288,358 @@ export function pathListProperty(description: string): object {
 export function stringProperty(description: string): object {
   return { description, type: "string" };
 }
+
+// ─── Schema-driven coercion ───────────────────────────────────────────────────
+// `registry.run` applies a record's `args` schema to the received values before `run`, for every
+// Caller. Each property is handed to the reader its SHAPE names, so the sentence a caller reads is
+// The one the `run` body would have produced — the readers are the same functions, not a second
+// Validator that agrees with them today. What the schema cannot say (a breakpoint the document
+// Defines, a path that addresses a node) stays in `run`; the schema owns the shape.
+
+/** The JSON Schema keywords a command property uses. Read loosely; unknown keywords are ignored. */
+interface PropertySchema {
+  type?: string | readonly string[];
+  enum?: readonly unknown[];
+  const?: unknown;
+  oneOf?: readonly PropertySchema[];
+  items?: PropertySchema;
+  minimum?: number;
+  maximum?: number;
+}
+
+/** The object schema `argsSchema` writes, as {@link coerceArgs} reads it. */
+interface ArgsSchemaShape {
+  properties?: Record<string, PropertySchema>;
+  required?: readonly string[];
+  additionalProperties?: boolean;
+}
+
+/**
+ * The rows of {@link coerceArgs}'s dispatch table, by name.
+ *
+ * Exported so a test can assert which row every shipped property lands in — `pass-through` is the
+ * row for a shape no reader exists for, and the sweep in `tests/command-args.test.ts` asserts no
+ * record in `appCommandSet()` reaches it. A property that would is a schema nothing coerces, which
+ * is the disagreement this section exists to close.
+ */
+export type CoercionRow =
+  | "enum"
+  | "const"
+  | "one-of"
+  | "typed"
+  | "boolean"
+  | "bounded-number"
+  | "number"
+  | "string"
+  | "path"
+  | "path-list"
+  | "pass-through";
+
+/** Whether an `items.type` list is `JxPath`'s `["string", "number"]`, in either order. */
+function isPathSegmentTypes(types: readonly string[]): boolean {
+  return types.length === 2 && types.includes("string") && types.includes("number");
+}
+
+/** A single JSON type name, or the list form `["number", "null"]`, as a list. */
+function typesOf(type: string | readonly string[]): readonly string[] {
+  return Array.isArray(type) ? type : [type as string];
+}
+
+/**
+ * Which reader a property's shape names.
+ *
+ * `"enum" in property`, not `property.enum`: a `derivedEnumProperty` carries its values behind a
+ * getter, and this function only classifies. The getter is read by the `enum` row when the value is
+ * coerced, which is what makes the list live at that moment rather than at classification.
+ */
+export function describeShape(property: object): CoercionRow {
+  const p = property as PropertySchema;
+  if ("enum" in p) {
+    return "enum";
+  }
+  if ("const" in p) {
+    return "const";
+  }
+  if (Array.isArray(p.oneOf)) {
+    return "one-of";
+  }
+  if (Array.isArray(p.type)) {
+    return "typed";
+  }
+  switch (p.type) {
+    case "boolean": {
+      return "boolean";
+    }
+    case "number":
+    case "integer": {
+      // Both bounds, as `numberProperty` writes them. A half-open interval is not a shape any
+      // Record declares, so it reads as a plain number and `run` owns the bound.
+      return p.minimum !== undefined && p.maximum !== undefined ? "bounded-number" : "number";
+    }
+    case "string": {
+      return "string";
+    }
+    case "array": {
+      const items = p.items?.type;
+      // The `path` row is the `JxPath` shape `pathProperty` writes — segments that are strings or
+      // Numbers, exactly — not any array whose items carry a type list. `pathArg` refuses a null
+      // Segment, so `items: { type: ["string", "null"] }` would be read by the wrong reader; it
+      // Lands in `pass-through` instead, where the sweep names it.
+      if (Array.isArray(items)) {
+        return isPathSegmentTypes(items) ? "path" : "pass-through";
+      }
+      return items === "array" ? "path-list" : "pass-through";
+    }
+    case "null":
+    case "object": {
+      return "typed";
+    }
+    default: {
+      break;
+    }
+  }
+  // No `type` at all (a description alone), or one no reader exists for: the sweep names it.
+  return "pass-through";
+}
+
+/** Whether a value is of one JSON type. `number` means FINITE, as {@link numberArg} already insists. */
+function isJsonType(type: string, value: unknown): boolean {
+  switch (type) {
+    case "null": {
+      return value === null;
+    }
+    case "boolean": {
+      return typeof value === "boolean";
+    }
+    case "string": {
+      return typeof value === "string";
+    }
+    case "number": {
+      return typeof value === "number" && Number.isFinite(value);
+    }
+    case "integer": {
+      return typeof value === "number" && Number.isInteger(value);
+    }
+    case "array": {
+      return Array.isArray(value);
+    }
+    case "object": {
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    default: {
+      break;
+    }
+  }
+  // A type name JSON Schema does not define admits nothing, and the sentence prints it back.
+  return false;
+}
+
+/** `number or null`, `string, number, boolean, array, object or null` — a type list as prose. */
+function listTypes(types: readonly string[]): string {
+  if (types.length <= 1) {
+    return types.join("");
+  }
+  return `${types.slice(0, -1).join(", ")} or ${types.at(-1)}`;
+}
+
+/**
+ * A required argument admitted by JSON-type membership — the `type: ["number", "null"]` shape.
+ *
+ * `null` is admitted only when listed, which is the whole difference from a reader that treats it
+ * as "absent": `canvas.setEditWidth { width: null }` MEANS "back to the breakpoint's width", and
+ * `canvas.setTestProp { value: null }` means "clear it". Nothing is coerced between types.
+ */
+export function typedArg(
+  commandId: string,
+  args: CommandArgValues,
+  key: string,
+  types: readonly string[],
+): unknown {
+  const value = args[key];
+  if (!types.some((type) => isJsonType(type, value))) {
+    throw refuse(commandId, key, `expected ${listTypes(types)}, got ${describe(value)}`);
+  }
+  return value;
+}
+
+/** One line per row, for the sentence a `oneOf` refusal prints when no branch admits the value. */
+function shapeOf(property: PropertySchema): string {
+  switch (describeShape(property)) {
+    case "enum": {
+      return `one of ${(property.enum ?? []).map((v) => describe(v)).join(" | ")}`;
+    }
+    case "const": {
+      return `the constant ${describe(property.const)}`;
+    }
+    case "one-of": {
+      return (property.oneOf ?? []).map((branch) => shapeOf(branch)).join(" or ");
+    }
+    case "typed": {
+      return listTypes(typesOf(property.type ?? []));
+    }
+    case "boolean": {
+      return "a boolean";
+    }
+    case "bounded-number": {
+      return `a number from ${property.minimum} to ${property.maximum}`;
+    }
+    case "number": {
+      return "a finite number";
+    }
+    case "string": {
+      return "a non-empty string";
+    }
+    case "path": {
+      return "a document path";
+    }
+    case "path-list": {
+      return "a list of document paths";
+    }
+    default: {
+      // The pass-through row. A branch with NO shape admits every value, so this is composed only
+      // For a shaped branch no reader exists for — an array of strings, say — whose pre-check
+      // Skipped it without a refusal of its own to print.
+      return "anything";
+    }
+  }
+}
+
+/**
+ * A required argument matching one of several shapes — `canvas.setFit`'s word-or-number,
+ * `selection.set`'s path-or-null.
+ *
+ * A branch is TRIED only when it admits the value's JSON type, so the refusal a caller reads is
+ * that branch's own: `canvas.setFit { fit: 10 }` reads {@link boundedNumberArg}'s range sentence,
+ * `style.setSelector { selector: "" }` reads {@link stringArg}'s, exactly as the `run` bodies
+ * printed them. Only a value no branch could take is answered with the list of shapes.
+ */
+function oneOfArg(
+  commandId: string,
+  args: CommandArgValues,
+  key: string,
+  branches: readonly PropertySchema[],
+): unknown {
+  const value = args[key];
+  const refusals: unknown[] = [];
+  for (const branch of branches) {
+    if (
+      branch.type !== undefined &&
+      !typesOf(branch.type).some((type) => isJsonType(type, value))
+    ) {
+      continue;
+    }
+    try {
+      return coerceProperty(commandId, args, key, branch);
+    } catch (error) {
+      refusals.push(error);
+    }
+  }
+  if (refusals.length === 1) {
+    throw refusals[0];
+  }
+  throw refuse(
+    commandId,
+    key,
+    `expected ${branches.map((branch) => shapeOf(branch)).join(" or ")}, got ${describe(value)}`,
+  );
+}
+
+/** One property through the reader its row names. The value comes back as the reader returns it. */
+function coerceProperty(
+  commandId: string,
+  args: CommandArgValues,
+  key: string,
+  property: PropertySchema,
+): unknown {
+  switch (describeShape(property)) {
+    case "enum": {
+      // The read of `property.enum` is HERE — a derived list is resolved at coercion time.
+      return enumArg(commandId, args, key, (property.enum ?? []) as readonly string[]);
+    }
+    case "const": {
+      const value = args[key];
+      if (value !== property.const) {
+        throw refuse(
+          commandId,
+          key,
+          `expected the constant ${describe(property.const)}, got ${describe(value)}`,
+        );
+      }
+      return value;
+    }
+    case "one-of": {
+      return oneOfArg(commandId, args, key, property.oneOf ?? []);
+    }
+    case "typed": {
+      return typedArg(commandId, args, key, typesOf(property.type ?? []));
+    }
+    case "boolean": {
+      return booleanArg(commandId, args, key);
+    }
+    case "bounded-number": {
+      return boundedNumberArg(commandId, args, key, property.minimum!, property.maximum!);
+    }
+    case "number": {
+      return numberArg(commandId, args, key);
+    }
+    case "string": {
+      return stringArg(commandId, args, key);
+    }
+    case "path": {
+      return pathArg(commandId, args, key);
+    }
+    case "path-list": {
+      return pathListArg(commandId, args, key);
+    }
+    default: {
+      // `pass-through`: a shape no reader exists for. The sweep in `tests/command-args.test.ts`
+      // Asserts no shipped record reaches it, so this is a hand-built schema being handed on.
+      return args[key];
+    }
+  }
+}
+
+/**
+ * Apply a declared `args` schema to received values: every property to the reader its shape names.
+ *
+ * The rules, in the order they are applied:
+ *
+ * - A key the schema does not declare is refused when `additionalProperties` is `false` (every record
+ *   `argsSchema` writes), and the sentence lists what IS declared — the same family as
+ *   {@link enumArg}'s, because a misspelt key and a misspelt value are the same mistake.
+ * - A declared key that is absent is skipped when it is not `required`, and handed to its reader when
+ *   it is: the reader already says `missing`.
+ * - A present value goes through its row. An explicit `undefined` counts as absent — JSON cannot
+ *   carry one, and every reader above already treats it so.
+ *
+ * Returns a fresh record with the same present keys, each holding what its reader returned. The
+ * `run` body keeps its own `stringArg(...)` lines as typed readers and can never disagree with this
+ * pass, because they are the same functions reading the same values.
+ */
+export function coerceArgs(
+  commandId: string,
+  schema: object,
+  args: CommandArgValues,
+): CommandArgValues {
+  const spec = schema as ArgsSchemaShape;
+  const properties = spec.properties ?? {};
+  const declared = Object.keys(properties);
+  const required = spec.required ?? [];
+  const coerced: CommandArgValues = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || Object.hasOwn(properties, key)) {
+      continue;
+    }
+    if (spec.additionalProperties === false) {
+      throw refuse(commandId, key, `not declared — declared: ${declared.join(", ") || "none"}`);
+    }
+    coerced[key] = value;
+  }
+  for (const key of declared) {
+    if (args[key] === undefined && !required.includes(key)) {
+      continue;
+    }
+    coerced[key] = coerceProperty(commandId, args, key, properties[key]!);
+  }
+  return coerced;
+}

package/src/commands/defaults.ts

@@ -199,6 +199,23 @@ const hasSelection = (ctx: CommandContext) =>
 const structurallyEditable = (ctx: CommandContext) =>
   !ctx.selection.isRoot && ctx.selection.paths.every((path) => isSpliceablePath(path));
 
+/**
+ * The one sentence for {@link structurallyEditable}, read by Delete and Duplicate both.
+ *
+ * It names the gate the predicate actually has (§12.4's corollary): the old sentences said "not the
+ * document root" and "has a sibling position" for a gate that also refuses a repeater's template
+ * and a `$switch` case, which sent a reader who had selected a template looking for a root. Two
+ * records with one predicate carry one sentence, because the tooltip, the palette subtitle and the
+ * assistant's refusal are all this string.
+ */
+const SPLICEABLE_SELECTION =
+  "an element selected on the canvas that has a sibling position: not the document root, a " +
+  "repeater's template or a switch case";
+
+/** `[children, 0] and [children, 2]` — how a report names the paths it acted on. */
+const describePaths = (paths: readonly (readonly (string | number)[])[]) =>
+  paths.map((path) => `[${path.join(", ")}]`).join(" and ");
+
 /**
  * The default command set.
  *
@@ -213,7 +230,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       title: "Save",
       category: "File",
       level: "document",
-      icon: "save",
+      icon: "floppy-disk",
       keybinding: "mod+s",
       menus: ["commandbar/primary", "statusbar/document", "palette"],
       group: "1_file",
@@ -239,7 +256,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       title: "Open in Browser",
       category: "View",
       level: "document",
-      icon: "browser",
+      icon: "arrow-square-out",
       keybinding: "mod+shift+o",
       menus: ["commandbar/primary", "statusbar/document", "palette"],
       group: "2_output",
@@ -281,7 +298,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       title: "Undo",
       category: "Edit",
       level: "document",
-      icon: "undo",
+      icon: "arrow-u-up-left",
       keybinding: "mod+z",
       menus: ["commandbar/primary", "palette"],
       group: "1_history",
@@ -295,7 +312,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       title: "Redo",
       category: "Edit",
       level: "document",
-      icon: "redo",
+      icon: "arrow-u-up-right",
       keybinding: ["mod+shift+z", "mod+y"],
       menus: ["commandbar/primary", "palette"],
       group: "1_history",
@@ -325,10 +342,18 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       // Document. Both surfaces that render this record had to hand-guard it before the record
       // Said so.
       enablement: structurallyEditable,
-      requires: "an element that has a sibling position",
+      requires: SPLICEABLE_SELECTION,
       aiTool: {
         name: "duplicate_node",
-        description: "Duplicate the currently selected element, inserting the copy after it.",
+        description:
+          "Duplicate elements in the document, inserting each copy after its original, as one " +
+          "undoable step. The copies become the selection.",
+        /* `mutateDuplicateNodes` selects the clones, so `after.selection.paths` IS the answer to
+           "where are the copies" — the same read the Inspector makes to address them. */
+        report: ({ after }) => {
+          const n = after.selection.paths.length;
+          return `Duplicated ${n} element${n === 1 ? "" : "s"}; the ${n === 1 ? "copy is" : "copies are"} selected at ${describePaths(after.selection.paths)}.`;
+        },
       },
       run: () => deps.duplicateSelection(),
     },
@@ -347,13 +372,12 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       // Already — its content is the single `map` template, not a child list.
       enablement: (ctx) => structurallyEditable(ctx) && !ctx.selection.isRepeater,
       requires: "an element with a sibling position that is not already a repeater",
-      aiTool: {
-        name: "repeat_node",
-        description:
-          "Turn the selected element into a repeater template, rendering it once per item of a " +
-          "data collection the author picks in the dialog this opens.",
-      },
       /*
+       * No `aiTool`, by §12.4's second deletion rule: `run` waits on a person. The dialog picks the
+       * collection, and a projected call would suspend the agent's turn on it while the loop counts
+       * the round as work; a cancel returns nothing a report could describe. A record with a
+       * `collection` argument that skips the dialog would be the way back in, and is a UX call.
+       *
        * The one record here whose implementation is not injected, and the reason is a property of
        * the implementation rather than of this record: `convertToRepeater()` is self-contained —
        * it reads the active tab, opens its own dialog and commits its own transaction — so there
@@ -391,10 +415,16 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       // Refused by the same gate, and refusing the whole batch is why a mixed selection can no
       // Longer half-apply.
       enablement: structurallyEditable,
-      requires: "an element selection that is not the document root",
+      requires: SPLICEABLE_SELECTION,
       aiTool: {
         name: "delete_node",
-        description: "Delete the currently selected element from the document.",
+        description: "Delete elements from the document as one undoable step.",
+        /* `before` is the context after the bridge's selector step, so its paths are what was
+           deleted; `after.selection` is what `mutateRemoveNode`'s repair left. */
+        report: ({ before, after }) => {
+          const n = before.selection.paths.length;
+          return `Deleted ${n} element${n === 1 ? "" : "s"} at ${describePaths(before.selection.paths)} in one undo step; the selection is now ${after.selection.count === 0 ? "empty" : "elsewhere"}.`;
+        },
       },
       run: () => deps.deleteSelection(),
     },

package/src/commands/live-context.ts

@@ -39,16 +39,22 @@ import type { CommandContext, FocusRegion } from "./context";
 import type { StudioPlatform } from "../types";
 
 /** Elements that own the keyboard while focused. Matches the old listener's target test exactly. */
-const TEXT_ENTRY =
-  "input, textarea, select, sp-textfield, sp-search, sp-number-field, sp-picker, [contenteditable=true]";
+const TEXT_ENTRY = "input, textarea, select, [contenteditable=true]";
 
 /**
  * Whether a parent-realm text control has focus.
  *
  * The old listener asked this of `e.target`; asking it of `document.activeElement` is the same
- * answer — a keydown's target IS the focused element, and shadow-DOM retargeting maps the inner
- * `<input>` of an `sp-textfield` onto the host in both cases — but it makes the fact part of the
- * CONTEXT instead of part of the event, so a `when` predicate can read it too.
+ * answer — a keydown's target IS the focused element — but it makes the fact part of the CONTEXT
+ * instead of part of the event, so a `when` predicate can read it too.
+ *
+ * The selector also named `sp-textfield`, `sp-search`, `sp-number-field` and `sp-picker`, and it
+ * had to: a Spectrum control's real `<input>` lives in a SHADOW ROOT, so both the event's target
+ * and `document.activeElement` retarget onto the custom element, and the native entries never saw
+ * it. The kit declares no shadow root anywhere (`ui.md` §3.2), so `jx-textfield`, `jx-select` and
+ * `jx-number-field` each put their native control in the caller's own tree and `activeElement` IS
+ * that control. Nothing was substituted for the four, because the answer comes one node deeper and
+ * `input, textarea, select` was always the entry that would give it.
  */
 export function isTextEntryFocused(doc: Document = document): boolean {
   const el = doc.activeElement;

package/src/commands/reference.ts

@@ -2,7 +2,7 @@
  * Reference.ts — the registry, projected into the two generated documentation pages.
  *
  * Plan §12 P3 lists `docs/studio/interface/shortcuts.md` and a new
- * `docs/studio/interface/commands.md` as **generated from the registry and CI-diffed**, which is
+ * `docs/studio/interface/commands.md` as **generated from the registry at build time**, which is
  * the last of §5.5's seven derivations: with the chrome, the keymap, the palette, the menus and the
  * automation surface all rendering the same records, a hand-maintained shortcut sheet is the only
  * place left for the app's keyboard and its documentation to disagree.
@@ -175,6 +175,15 @@ function chordCell(chords: readonly string[]): string {
   return chords.length === 0 ? "—" : chords.map((chord) => `\`${chord}\``).join(" or ");
 }
 
+/**
+ * The assistant tool a record projects, as one cell: `` `delete_node` ``, or the same empty-cell
+ * dash {@link chordCell} prints. `CommandRow.aiTool` was computed and printed nowhere; a
+ * declaration MAKES a tool now (`services/ai-command-tools.ts`), so the page says which.
+ */
+function toolCell(aiTool: string): string {
+  return aiTool === "" ? "—" : `\`${aiTool}\``;
+}
+
 /**
  * The body of `docs/studio/interface/shortcuts.md` — one `##` section per scope.
  *
@@ -212,13 +221,14 @@ export function commandsMarkdown(rows: readonly CommandRow[]): string {
     sections.push(
       `## ${category}\n`,
       table(
-        ["Command", "Id", "Shortcut", "Level", "Requires"],
+        ["Command", "Id", "Shortcut", "Level", "Requires", "Assistant"],
         inCategory.map((row) => [
           row.destructive ? `${row.title} (destructive)` : row.title,
           `\`${row.id}\``,
           chordCell(row.mac),
           row.level,
           row.requires || "—",
+          toolCell(row.aiTool),
         ]),
       ),
     );