@jxsuite/studio 6.1.1 → 8.0.0

package/src/commands/defaults.ts

@@ -50,9 +50,9 @@ export type DockId = "navigator" | "inspector" | "bottom";
 export type PaletteMode = "picker" | "files" | "commands" | "nodes" | "projects";
 
 /**
- * One panel, as the ⌘1–8 direct keys address it.
+ * One panel, as its `panel.focus.<id>` record addresses it.
  *
- * Structurally the part of `panels/panel-registry.ts`'s `PanelRecord` a chord needs, declared here
+ * Structurally the part of `panels/panel-registry.ts`'s `PanelRecord` a record needs, declared here
  * rather than imported so this module keeps its one load-bearing property: it imports no state and
  * no DOM, which is what lets the three CI checks load the command set in a bare Bun process. The
  * ROSTER arrives by injection ({@link CommandDeps.panelRoster}) from the panel registry, so there
@@ -64,30 +64,52 @@ export interface RailPanel {
   /** The panel's human name, which is also the command's title after "Show ". */
   title: string;
   /** `false` for a panel with no rail button — reachable by name, not by number. */
-  rail?: boolean;
+  rail?: boolean | "developer";
   /** The panel's own visibility predicate, composed into the command's. */
   when?: (ctx: CommandContext) => boolean;
 }
 
-/** How many rail panels get a ⌘N: the Navigator rail (§5.1) spends four per level group. */
-export const RAIL_CHORD_LIMIT = 8;
+/** The Inspector strip's three tabs (§6): Page · Element · Assistant. */
+export type InspectorStripId = "page" | "element" | "assistant";
 
 /**
- * The Inspector's four tabs, in the order §6 names them — which is the order ⌘⇧1–4 follow.
+ * One Inspector LEAF — a view the dock can show — in the order §6 names them, which is the order
+ * ⌘⇧1–5 follow: Page, Element's Content · Style · Logic, then Assistant.
  *
- * `"assistant"` is the fourth tab, not a dock of its own (there is no assistant column, §3.1), so
- * it is one of `shell.ts`'s `INSPECTOR_TAB_IDS` like the other three.
+ * `"assistant"` is a leaf, not a dock of its own (there is no assistant column, §3.1), so it is one
+ * of `shell.ts`'s `INSPECTOR_TAB_IDS` like the others. `strip` says which of the three strip tabs
+ * hosts the leaf: the three node views share Element, behind a sub-switch, because they share one
+ * target.
  */
 export interface InspectorTab {
-  /** The stored `session.ui.rightTab` value, or `"assistant"` for the assistant dock. */
+  /** The stored `session.ui.rightTab` value. */
   id: string;
   title: string;
+  strip: InspectorStripId;
 }
 
 export const INSPECTOR_TABS: readonly InspectorTab[] = [
-  { id: "properties", title: "Content" },
-  { id: "style", title: "Style" },
-  { id: "events", title: "Logic" },
+  { id: "page", strip: "page", title: "Page" },
+  { id: "properties", strip: "element", title: "Content" },
+  { id: "style", strip: "element", title: "Style" },
+  { id: "events", strip: "element", title: "Logic" },
+  { id: "assistant", strip: "assistant", title: "Assistant" },
+];
+
+/** One tab of the strip, and the leaves it hosts. */
+export interface InspectorStripTab {
+  id: InspectorStripId;
+  title: string;
+}
+
+/**
+ * The strip, in order. Three tabs, under the four-per-dock cap (`studio-ui-guidelines.md` §12.2):
+ * Element's sub-switch is inside a tab's body and is not a dock tab. The Page tab's title is
+ * contextual on screen (Page, Template, Component, Entry or Document, §6); this is its name.
+ */
+export const INSPECTOR_STRIP: readonly InspectorStripTab[] = [
+  { id: "page", title: "Page" },
+  { id: "element", title: "Element" },
   { id: "assistant", title: "Assistant" },
 ];
 
@@ -119,7 +141,8 @@ export interface CommandDeps {
    */
   newWindow: () => void | Promise<void>;
   /**
-   * The rail's panels in rail order, then the rail-less ones — the roster ⌘1–8 is generated from.
+   * The rail's panels in rail order, then the rail-less ones — the roster `panel.focus.*` is
+   * generated from.
    *
    * Every entry is a Navigator panel: the rail is the Navigator's, and a Bottom-dock tab is
    * addressed by `view.setBottomTab` instead — one door per surface. `panels/navigator-panels.ts`'s
@@ -131,8 +154,8 @@ export interface CommandDeps {
   panelRoster: readonly RailPanel[];
   /**
    * Toggle-FOCUS a panel: reveal it and take focus, or — when it already has focus — collapse the
-   * dock hosting it and hand focus back to the pane. Deliberately not toggle-visible: ⌘1 pressed
-   * from the canvas must land you in Files, not close it.
+   * dock hosting it and hand focus back to the pane. Deliberately not toggle-visible: running it
+   * from the canvas must land you in the panel, not close it.
    */
   focusPanel: (panelId: string) => void;
   /** Show an Inspector tab and focus the dock. `"assistant"` addresses the assistant dock. */
@@ -305,6 +328,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       keybinding: "mod+z",
       menus: ["commandbar/primary", "palette"],
       group: "1_history",
+      order: 1,
       when: documentOpen,
       enablement: (ctx) => ctx.document.canUndo,
       requires: "a change to undo",
@@ -319,6 +343,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       keybinding: ["mod+shift+z", "mod+y"],
       menus: ["commandbar/primary", "palette"],
       group: "1_history",
+      order: 2,
       when: documentOpen,
       enablement: (ctx) => ctx.document.canRedo,
       requires: "a change to redo",
@@ -545,7 +570,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
        * The other half of multi-window, and the half that had no door.
        *
        * "Open a project ELSEWHERE" is reachable from Open Project and from Recents
-       * (desktop.md §4.2a); "open an EMPTY window" was reachable only from the ElectroBun
+       * (desktop.md §4.2a); "open an EMPTY window" was reachable only from the desktop
        * launcher's native application menu — so on a launcher whose window has no menu bar,
        * `newWindow` existed on the platform and could not be run. Gated on the same capability
        * every other multi-window verb is, so a host with one window does not offer it.
@@ -601,40 +626,39 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
 }
 
 /**
- * ⌘1–8 — one record per panel, generated from {@link CommandDeps.panelRoster}.
+ * One `panel.focus.<id>` record per Navigator panel, generated from
+ * {@link CommandDeps.panelRoster}.
  *
- * Generated rather than written out eight times for the reason the whole registry exists: the rail,
- * the chord, the palette row and the generated shortcut sheet are then four renderings of one list.
- * Only the first eight get a chord; a ninth panel keeps its name and its palette row, which is the
- * cost studio-ui-guidelines.md §12.2 puts on chrome.
+ * Generated rather than written out once per panel for the reason the whole registry exists: the
+ * rail, the palette row and the generated command sheet are then three renderings of one list.
+ *
+ * **No chords.** ⌘1–8 used to follow the rail here. The digit row now switches WORKSPACES (⌘1–5,
+ * `view.setWorkspace`), because the rail is Design's alone and a chord that reached a panel from
+ * Publish would open a column the workspace does not draw. The records stay, in the palette and
+ * bindable in Preferences › Keyboard, and the rail is the pointer's way to them.
  */
 export function panelFocusCommands(deps: CommandDeps): AnyCommand[] {
-  let chordsSpent = 0;
-  return deps.panelRoster.map((panel) => {
-    const command: AnyCommand = {
-      id: `panel.focus.${panel.id}`,
-      title: `Show ${panel.title}`,
-      category: "View",
-      // Application, like `view.setActivity`: revealing a panel arranges the workspace. What the
-      // PANEL acts on is the panel record's own level, and that is `registerPanel()`'s field.
-      level: "application",
-      menus: ["palette"],
-      group: "4_docks",
-      requires: "an open project",
-      // The panel's OWN `when` composes in, so a declared-but-unbuilt surface (Search, Problems)
-      // Has no palette row and no live chord — the record exists, the affordance does not.
-      when: (ctx: CommandContext) => ctx.project.open && (panel.when?.(ctx) ?? true),
-      run: () => deps.focusPanel(panel.id),
-    };
-    if (panel.rail !== false && chordsSpent < RAIL_CHORD_LIMIT) {
-      chordsSpent += 1;
-      command.keybinding = `mod+${chordsSpent}`;
-    }
-    return command;
-  });
+  return deps.panelRoster.map((panel): AnyCommand => ({
+    id: `panel.focus.${panel.id}`,
+    title: `Show ${panel.title}`,
+    category: "View",
+    // Application, like `view.setActivity`: revealing a panel arranges the workspace. What the
+    // PANEL acts on is the panel record's own level, and that is `registerPanel()`'s field.
+    level: "application",
+    menus: ["palette"],
+    group: "4_docks",
+    requires: "an open project",
+    // The panel's OWN `when` composes in, so a declared-but-unbuilt surface (Search, Problems)
+    // Has no palette row — the record exists, the affordance does not.
+    when: (ctx: CommandContext) => ctx.project.open && (panel.when?.(ctx) ?? true),
+    run: () => deps.focusPanel(panel.id),
+  }));
 }
 
-/** ⌘⇧1–4 — one record per Inspector tab, generated from {@link INSPECTOR_TABS}. */
+/**
+ * ⌘⇧1–5 — one record per Inspector leaf, generated from {@link INSPECTOR_TABS}, so the chords
+ * follow the strip left to right: Page, Element › Content, Style, Logic, then Assistant.
+ */
 export function inspectorFocusCommands(deps: CommandDeps): AnyCommand[] {
   return INSPECTOR_TABS.map((tab, index) => {
     const command: AnyCommand = {

package/src/commands/keymap.ts

@@ -27,6 +27,7 @@
  *    colliding still throws, because that one is a bug in the app and nobody's preference.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { KEY_SCOPES } from "./levels";
 import type { KeyScope } from "./levels";
 
@@ -36,33 +37,33 @@ const MODIFIER_ORDER = ["mod", "ctrl", "alt", "shift"] as const;
 type Modifier = (typeof MODIFIER_ORDER)[number];
 
 /** Spellings people actually write, mapped onto the canonical four. */
-const MODIFIER_ALIASES: Readonly<Record<string, Modifier>> = {
-  mod: "mod",
-  cmd: "mod",
-  command: "mod",
-  meta: "mod",
-  super: "mod",
-  ctrl: "ctrl",
-  control: "ctrl",
-  alt: "alt",
-  opt: "alt",
-  option: "alt",
-  shift: "shift",
-};
+const MODIFIER_ALIASES = new Map<string, Modifier>([
+  ["mod", "mod"],
+  ["cmd", "mod"],
+  ["command", "mod"],
+  ["meta", "mod"],
+  ["super", "mod"],
+  ["ctrl", "ctrl"],
+  ["control", "ctrl"],
+  ["alt", "alt"],
+  ["opt", "alt"],
+  ["option", "alt"],
+  ["shift", "shift"],
+]);
 
 /** Key aliases — arrow/space spellings and the `KeyboardEvent.key` values that differ. */
-const KEY_ALIASES: Readonly<Record<string, string>> = {
-  up: "arrowup",
-  down: "arrowdown",
-  left: "arrowleft",
-  right: "arrowright",
-  esc: "escape",
-  space: " ",
-  spacebar: " ",
-  del: "delete",
-  plus: "=",
-  return: "enter",
-};
+const KEY_ALIASES = new Map<string, string>([
+  ["up", "arrowup"],
+  ["down", "arrowdown"],
+  ["left", "arrowleft"],
+  ["right", "arrowright"],
+  ["esc", "escape"],
+  ["space", " "],
+  ["spacebar", " "],
+  ["del", "delete"],
+  ["plus", "="],
+  ["return", "enter"],
+]);
 
 /** How each modifier prints, per platform. */
 const MAC_GLYPHS: Readonly<Record<Modifier, string>> = {
@@ -80,18 +81,18 @@ const PC_LABELS: Readonly<Record<Modifier, string>> = {
 };
 
 /** Keys whose printed name is not just the uppercased token. */
-const KEY_LABELS: Readonly<Record<string, string>> = {
-  arrowup: "↑",
-  arrowdown: "↓",
-  arrowleft: "←",
-  arrowright: "→",
-  " ": "Space",
-  escape: "Esc",
-  enter: "Enter",
-  tab: "Tab",
-  delete: "Delete",
-  backspace: "Backspace",
-};
+const KEY_LABELS = new Map<string, string>([
+  ["arrowup", "↑"],
+  ["arrowdown", "↓"],
+  ["arrowleft", "←"],
+  ["arrowright", "→"],
+  [" ", "Space"],
+  ["escape", "Esc"],
+  ["enter", "Enter"],
+  ["tab", "Tab"],
+  ["delete", "Delete"],
+  ["backspace", "Backspace"],
+]);
 
 /**
  * The five fields the keymap reads off a keyboard event.
@@ -159,12 +160,12 @@ export function parseChord(chord: string): ParsedChord {
     // Parses the same as "Cmd+Shift+P".
     const trimmed = token.trim();
     const lower = trimmed === "" ? " " : trimmed.toLowerCase();
-    const modifier = MODIFIER_ALIASES[lower];
+    const modifier = MODIFIER_ALIASES.get(lower);
     if (modifier) {
       parsed[modifier] = true;
       continue;
     }
-    parsed.key = KEY_ALIASES[lower] ?? lower;
+    parsed.key = KEY_ALIASES.get(lower) ?? lower;
   }
   if (!parsed.key) {
     throw new Error(`keybinding "${chord}" has no key — a chord needs more than modifiers`);
@@ -185,6 +186,9 @@ export function normalizeChord(chord: string): string {
 
 /** Whether the current platform is a mac. `navigator` is injectable so tests never touch globals. */
 export function isMacPlatform(
+  /* SAFETY: this module types without the DOM lib, so `globalThis` does not declare `navigator`.
+     Where a host provides one (every webview, Bun), its `platform` and `userAgent` are strings,
+     which is all `PlatformInfo` reads; where none exists the `?? {}` default answers. */
   nav: PlatformInfo = (globalThis as { navigator?: PlatformInfo }).navigator ?? {},
 ): boolean {
   return /mac/i.test(nav.platform ?? nav.userAgent ?? "");
@@ -209,7 +213,7 @@ export function chordFromEvent(event: KeyChordEvent, mac: boolean): string {
      chord needs more than modifiers") — so every bare modifier press threw out of `resolveEvent`,
      into the keydown listener, and onto the console. `""` is the honest answer, and
      {@link Keymap.resolveEvent} reads it as "no chord yet". */
-  if (MODIFIER_ALIASES[key]) {
+  if (MODIFIER_ALIASES.has(key)) {
     return "";
   }
   const parsed: ParsedChord = {
@@ -219,7 +223,7 @@ export function chordFromEvent(event: KeyChordEvent, mac: boolean): string {
     // Shift is implied by an uppercase letter but a chord table cannot rely on that: with ⇧ held
     // `e.key` is "Z" for ⌘⇧Z and "?" for ⇧/, so the flag is the only stable signal.
     shift: event.shiftKey,
-    key: KEY_ALIASES[key] ?? key,
+    key: KEY_ALIASES.get(key) ?? key,
   };
   return serializeChord(parsed);
 }
@@ -229,7 +233,7 @@ export function formatChord(chord: string, mac: boolean): string {
   const parsed = parseChord(chord);
   const held = MODIFIER_ORDER.filter((modifier) => parsed[modifier]);
   const key =
-    KEY_LABELS[parsed.key] ??
+    KEY_LABELS.get(parsed.key) ??
     (parsed.key.length === 1
       ? parsed.key.toUpperCase()
       : parsed.key.charAt(0).toUpperCase() + parsed.key.slice(1));
@@ -386,7 +390,7 @@ export function createKeymap(options: { mac?: boolean } = {}): Keymap {
     if (!raw) {
       return [];
     }
-    return (typeof raw === "string" ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
+    return (isString(raw) ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
   }
 
   function tableFor(scope: KeyScope): Map<string, Claim> {
@@ -543,14 +547,23 @@ export function createKeymap(options: { mac?: boolean } = {}): Keymap {
  * The command id is deliberately dropped — the frame decides whether to forward, never what runs —
  * and the projection is a pure function of the keymap so the host can recompute and repost it
  * whenever a rebinding lands.
+ *
+ * `except` names commands whose chords the second realm must leave alone: a command that never
+ * applies to what that realm draws (`canvas/iframe-keys.ts` `HOST_ONLY_COMMANDS`) would otherwise
+ * have the realm cancel the keystroke's own default for nothing.
  */
 export function chordsInScopes<S extends KeyScope>(
   keymap: Keymap,
   scopes: readonly S[],
+  except: ReadonlySet<string> = new Set(),
 ): { chord: string; scope: S }[] {
   const seen = new Set<string>();
   const out: { chord: string; scope: S }[] = [];
   for (const entry of keymap.entries()) {
+    // A command that can never run on behalf of the second realm must not make it swallow a key.
+    if (except.has(entry.commandId)) {
+      continue;
+    }
     /* `find` rather than a `Set.has` test: the narrowed member is what makes the result carry the
        CALLER's scope union. The canvas frame's table is three scopes wide (`FRAME_KEY_SCOPES`) and
        has to stay that way across the bridge, where `SyncedChord` declares exactly those three —

package/src/commands/levels.ts

@@ -176,17 +176,20 @@ export type PanelPlacement = (typeof PANEL_PLACEMENTS)[number];
 export const PANEL_PLACEMENT_MATRIX: Readonly<Record<PanelPlacement, PlacementRule>> = {
   "rail/project": {
     admits: ["project"],
-    note: "the rail's upper group — Files, Search, Source Control, Problems",
+    note: "the rail's upper group — Site, and Files with the developer panels on",
   },
   "rail/document": {
     admits: ["document"],
-    note: "the rail's lower group — Outline, Page, Data, Packages",
+    note: "the rail's lower group — Outline, Data, and Packages with the developer panels on",
   },
   navigator: {
     admits: ["project", "document"],
     note: "whichever level the hosted panel declares; the panel header prints it",
   },
-  inspector: { admits: ["selection"], note: "the Inspector's tabs are selection surfaces" },
+  inspector: {
+    admits: ["document", "selection"],
+    note: "Page is the open document's tab, Element the selection's (§6)",
+  },
   "dock.bottom": { admits: ["project", "document"], note: "the panel header states which" },
 };
 
@@ -196,8 +199,11 @@ export interface PlaceablePanel {
   level: Level;
   /** The dock hosting the panel's body. */
   dock: "navigator" | "inspector" | "bottom";
-  /** `false` for a panel with no rail button — it declares no rail-group placement. */
-  rail?: boolean | undefined;
+  /**
+   * `false` for a panel with no rail button — it declares no rail-group placement. `"developer"` is
+   * a rail button only while the developer panels are shown, and it still holds its placement.
+   */
+  rail?: boolean | "developer" | undefined;
 }
 
 /** One rejected (panel, placement) pair. Shaped like {@link PlacementViolation}, keyed by panel. */
@@ -231,7 +237,7 @@ export function panelPlacements(panel: PlaceablePanel): string[] {
 
 /** Whether `value` is one of the {@link PANEL_PLACEMENTS}. */
 export function isPanelPlacement(value: string): value is PanelPlacement {
-  return (PANEL_PLACEMENTS as readonly string[]).includes(value);
+  return PANEL_PLACEMENTS.some((placement) => placement === value);
 }
 
 /** Check one Panel record against {@link PANEL_PLACEMENT_MATRIX}. */
@@ -300,12 +306,12 @@ export interface PlacementViolation {
 
 /** Whether `placement` is one of the {@link PLACEMENTS}. */
 export function isPlacement(value: string): value is Placement {
-  return (PLACEMENTS as readonly string[]).includes(value);
+  return PLACEMENTS.some((placement) => placement === value);
 }
 
 /** Whether `level` is one of the {@link LEVELS}. */
 export function isLevel(value: string): value is Level {
-  return (LEVELS as readonly string[]).includes(value);
+  return LEVELS.some((level) => level === value);
 }
 
 /** Whether the matrix lets a `level` record render in `placement`. */

package/src/commands/live-context.ts

@@ -25,6 +25,7 @@
  * studio.ts, and lets a test state a context without standing up the app.
  */
 
+import { isFunction, isString } from "@jxsuite/schema/guards";
 import { resolveI18n } from "@jxsuite/schema/locale";
 import { componentRegistry } from "../files/components";
 import { getNodeAtPath, projectState } from "../store";
@@ -36,7 +37,7 @@ import { hasTyping } from "../tabs/typing";
 import { collabState } from "../collab/collab-state";
 
 import { canvasViewForMode, editorKindForMode, emptyContext } from "./context";
-import type { CommandContext, FocusRegion } from "./context";
+import type { CommandContext } from "./context";
 import type { StudioPlatform } from "../types";
 
 /** Elements that own the keyboard while focused. Matches the old listener's target test exactly. */
@@ -86,7 +87,7 @@ export interface LiveContextSources {
 
 /** `capability.*` is presence-of-method on the PAL — the check every call site does by hand today. */
 function capabilities(platform: StudioPlatform | null): CommandContext["capability"] {
-  const has = (key: keyof StudioPlatform) => typeof platform?.[key] === "function";
+  const has = (key: keyof StudioPlatform) => isFunction(platform?.[key]);
   return {
     dataRows: has("dataRows"),
     // The real member now, not the `codeService` stand-in it was minted against: the usage query is
@@ -96,6 +97,7 @@ function capabilities(platform: StudioPlatform | null): CommandContext["capabili
     importSite: has("importSite"),
     openProjectInNewWindow: has("openProjectInNewWindow"),
     readFileBytes: has("readFileBytes"),
+    publish: has("cfApi"),
     // Multi-window is a desktop-only family; `newWindow` is the one every member implies.
     windowControls: has("newWindow"),
   };
@@ -132,6 +134,7 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
     ctx.git.ahead = shell.git.status?.ahead ?? 0;
     ctx.git.behind = shell.git.status?.behind ?? 0;
     ctx.git.dirtyCount = shell.git.status?.files.length ?? 0;
+    ctx.workspace.id = shell.workspace;
 
     ctx.document.open = tab !== null;
     // Typing still in a source buffer is unsaved work too, though the document has not seen it.
@@ -161,18 +164,17 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
     const selection = primarySelection(paths);
     if (selection) {
       const node = getNodeAtPath(tab!.doc.document, selection);
+      const tagName = node?.tagName;
       ctx.selection.count = paths.length;
       ctx.selection.paths = paths.map((path) => [...path]);
       // Every remaining fact describes the PRIMARY — the one node a single-target verb addresses —
       // Except `isRoot`, which is the batch's own gate: a batch containing the document element
       // Cannot be deleted or duplicated any more than that element could be on its own.
-      ctx.selection.kind = typeof node?.tagName === "string" ? node.tagName : "";
+      ctx.selection.kind = isString(tagName) ? tagName : "";
       // A path of fewer than two segments addresses the document element itself — the same test
       // `shortcuts.ts` spelled as `selection.length >= 2` at four separate call sites.
       ctx.selection.isRoot = paths.some((path) => path.length < 2);
-      ctx.selection.isComponentInstance = componentRegistry.some(
-        (c) => c.tagName === node?.tagName,
-      );
+      ctx.selection.isComponentInstance = componentRegistry.some((c) => c.tagName === tagName);
       ctx.selection.isRepeater = node?.$prototype === "Array";
     }
     // Layout chrome is NOT a document selection: the node is not in the open page at all.
@@ -187,7 +189,7 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
        being typed into. The stack asks "is something being typed into"; a record asks "is the
        thing being typed into the page". */
     ctx.caret.inCanvas = sources.isCaretActive();
-    ctx.focus.region = shell.focusRegion as FocusRegion;
+    ctx.focus.region = shell.focusRegion;
     ctx.modal.open = sources.isModalOpen();
 
     if (tab) {

package/src/commands/reference.ts

@@ -17,6 +17,7 @@
  * between runs is a CI diff nobody can review.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { formatChord, normalizeChord } from "./keymap";
 import { CATEGORIES } from "./levels";
 import type { KeybindingOverrides } from "./keymap";
@@ -83,7 +84,7 @@ function chordsOf(command: AnyCommand): string[] {
   if (!raw) {
     return [];
   }
-  return (typeof raw === "string" ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
+  return (isString(raw) ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
 }
 
 /**

package/src/commands/registry.ts

@@ -36,13 +36,12 @@ import { createKeymap } from "./keymap";
 import type { KeyChordEvent, Keymap, KeymapMatch } from "./keymap";
 import { checkRecordPlacements } from "./levels";
 import type { Category, KeyScope, Level, Placement } from "./levels";
+import { isFunction } from "@jxsuite/schema/guards";
 import { coerceArgs } from "./command-args";
+import type { CommandArgsSchema, CommandArgValues } from "./command-args";
 import { runReported } from "./run-reported";
 import type { CommandContext } from "./context";
 
-/** Arguments as they arrive from a palette prompt, an automation manifest step or an AI tool call. */
-export type CommandArgs = Record<string, unknown>;
-
 /** How an action's effect is undone — surfaced to the user before an agent runs it. */
 export type UndoScope = "document" | "project" | "none";
 
@@ -77,11 +76,17 @@ export interface Command<A = void> {
    * shot check's contract AND what {@link CommandRegistry.run} coerces the received record against
    * before `run` sees it (`command-args.ts`'s `coerceArgs`). One object, four readers.
    */
-  args?: object;
+  args?: CommandArgsSchema;
   /** Surfaces this command renders in. Defaults to `["palette"]`. */
   menus?: readonly Placement[];
   /** Menu ordering key: "1_clipboard", "3_structure", "9_danger". */
   group?: string;
+  /**
+   * Position within its {@link Command.group}, lower first. A command without one follows the
+   * ordered commands of its group, by title. A group whose members have a reading order of their
+   * own (Undo before Redo) states it here, because the title is an accident of the language.
+   */
+  order?: number;
   /**
    * How the effect is undone. Also the LEDGER SCOPE of a bridged write:
    * `services/ai-command-tools.ts` records one "Changed N files" entry per path a projected run
@@ -216,7 +221,7 @@ export interface CommandRegistry {
    * `RangeError` naming the argument when `args` does not fit the record's schema — synchronously,
    * before `run` is entered, whichever surface the call came from.
    */
-  run: (id: string, args?: CommandArgs) => void | Promise<void>;
+  run: (id: string, args?: CommandArgValues) => void | Promise<void>;
   /** The chord index, conflict-checked at registration. */
   keymap: Keymap;
   /** Resolve a keyboard event through a scope stack and run what it hits. */
@@ -254,7 +259,7 @@ function checkProjection(command: AnyCommand, toolNames: ReadonlyMap<string, str
       `command "${command.id}" aiTool name "${tool.name}" is already projected by "${claimant}"`,
     );
   }
-  if (typeof tool.report !== "function") {
+  if (!isFunction(tool.report)) {
     throw new TypeError(
       `command "${command.id}" declares aiTool without a report: a tool that can only say ` +
         `"done" is refused`,
@@ -270,8 +275,7 @@ function checkProjection(command: AnyCommand, toolNames: ReadonlyMap<string, str
      selector's `paths` property in FRONT of the record's own `args`, so a record that declares its
      own `paths` would have two definitions of one argument — the model would read the record's
      description and the bridge would hand the value to the selector. */
-  const properties = (command.args as { properties?: Record<string, unknown> } | undefined)
-    ?.properties;
+  const properties = command.args?.properties;
   if (command.level === "selection" && properties && Object.hasOwn(properties, "paths")) {
     throw new Error(
       `command "${command.id}" is selection-level and may not declare "paths": the assistant ` +
@@ -341,11 +345,11 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
       if (violations.length > 0) {
         throw new Error(`command "${command.id}" ${violations[0]!.message}`);
       }
-      checkProjection(command as AnyCommand, toolNames);
+      checkProjection(command, toolNames);
       // Chord conflicts throw from the keymap; do this LAST so a rejected record leaves the
       // Registry untouched in every failure mode — the tool name is claimed only after it.
       keymap.add(command);
-      commands.set(command.id, command as AnyCommand);
+      commands.set(command.id, command);
       if (command.aiTool) {
         toolNames.set(command.aiTool.name, command.id);
       }
@@ -373,7 +377,10 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
             (command.menus ?? ["palette"]).includes(placement) && visibleWith(command, ctx),
         )
         .toSorted(
-          (a, b) => (a.group ?? "").localeCompare(b.group ?? "") || a.title.localeCompare(b.title),
+          (a, b) =>
+            (a.group ?? "").localeCompare(b.group ?? "") ||
+            (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY) ||
+            a.title.localeCompare(b.title),
         );
     },
     isVisible(id) {
@@ -404,6 +411,10 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
          their typed readers; `coerceArgs` dispatches to the same functions, so the two cannot
          disagree. A record with no `args` takes whatever it was handed, as it always has. */
       const coerced = command.args ? coerceArgs(id, command.args, args) : args;
+      /* SAFETY: a stored record is `Command<never>` because the map erases each record's own `A`.
+         The runtime contract for that erased `A` is the record's `args` schema, which `coerceArgs`
+         has just applied (every key its reader's return value, an undeclared key refused); a
+         record with no schema takes the caller's record as it always has. */
       return command.run(ctx, coerced as never);
     },
     keymap,