@jxsuite/studio 2.0.1 → 2.1.0

package/src/commands/levels.ts

@@ -0,0 +1,345 @@
+/**
+ * Levels.ts — the containment taxonomy and the level × placement matrix.
+ *
+ * Two vocabularies live here, and keeping them apart is the whole point (UX-REDESIGN-PLAN §5.1):
+ *
+ * - {@link Level} answers WHAT a record acts on. It governs placement and is CI-checked.
+ * - {@link KeyScope} answers WHERE a chord is live. It governs keyboard dispatch only.
+ *
+ * Conflating them is how "position encodes scope" degrades into unenforced prose. The clearest case
+ * is inline text formatting: Bold acts on a text range inside the selected node, so its `level` is
+ * `selection`, while its `keyScope` is `caret` — which is what makes the chord live only when a
+ * caret exists. There is deliberately no `range` level; a fifth level would demand a fifth region
+ * and there is none.
+ *
+ * {@link PLACEMENT_MATRIX} is the normative table: each placement declares the set of levels it
+ * admits. Mixed regions are mixed IN THE TABLE, never by prose exemption — the status bar is three
+ * separate single-level placements, not one "mixed" one. `scripts/check-command-levels.ts`
+ * validates every registered command's `menus` against this table, and `createCommandRegistry`
+ * applies the same check at registration so a violation cannot reach a running app either.
+ *
+ * Panel placements (the two rail groups, the navigator dock body, the bottom dock, the inspector
+ * dock) are part of the same matrix in `studio-ui-guidelines.md` §12 and live here too, in
+ * {@link PANEL_PLACEMENT_MATRIX}: `registerPanel()` (`panels/panel-registry.ts`) now exists, so a
+ * Panel record declares a `level` for the same reason a Command does and is checked the same way.
+ * The two tables are separate because their placement VOCABULARIES are disjoint — a command is
+ * never "in the rail's upper group", and a panel is never "in the block action bar".
+ */
+
+/** Containment level — WHAT a record acts on. Governs placement. CI-checked. */
+export const LEVELS = ["application", "project", "document", "selection"] as const;
+
+export type Level = (typeof LEVELS)[number];
+
+/** Keyboard dispatch scope — WHERE a chord is live. Orthogonal to {@link Level}. */
+export const KEY_SCOPES = ["global", "canvas", "caret", "grid", "code", "dock", "palette"] as const;
+
+export type KeyScope = (typeof KEY_SCOPES)[number];
+
+/** Command categories. The palette renders rows as "<Category>: <title>". */
+export const CATEGORIES = [
+  "File",
+  "Edit",
+  "Selection",
+  "Insert",
+  "View",
+  "Document",
+  "Project",
+  "Source Control",
+  "Publish",
+  "Assistant",
+  "Collaborate",
+  "Help",
+] as const;
+
+export type Category = (typeof CATEGORIES)[number];
+
+/** Every surface a command may declare itself into. `"never"` means keyboard/API only. */
+export const PLACEMENTS = [
+  "commandbar/primary",
+  "commandbar/overflow",
+  "statusbar/project",
+  "statusbar/document",
+  "statusbar/selection",
+  "context/element",
+  "context/file",
+  "context/layer",
+  "context/tab",
+  "context/pane",
+  "blockbar",
+  /**
+   * The block action bar's SECOND cluster — inline formatting, shown while the caret is in text.
+   *
+   * A separate placement rather than a crowd inside `blockbar`, for the reason the status bar is
+   * three placements and not one "mixed" region: the bar's verb cluster is capped at five, and
+   * eight format verbs sharing that cap would push Bold into a `⋮` menu. Same level, same surface,
+   * different budget — which is a row in the table, not an exemption in prose.
+   */
+  "blockbar/format",
+  "outline/row",
+  "palette",
+  "never",
+] as const;
+
+export type Placement = (typeof PLACEMENTS)[number];
+
+/** One row of the matrix: the levels a placement admits, plus why it is drawn that way. */
+export interface PlacementRule {
+  /** Levels this placement accepts. A command declaring any other level is a CI failure. */
+  admits: readonly Level[];
+  /** The reason, printed in the violation message so the fix is obvious from the failure. */
+  note: string;
+}
+
+/**
+ * The level × placement matrix — normative copy, mirrored into `studio-ui-guidelines.md` §12.
+ *
+ * Read a row as: "this region renders records of these levels, and nothing else."
+ */
+export const PLACEMENT_MATRIX: Readonly<Record<Placement, PlacementRule>> = {
+  "commandbar/primary": {
+    admits: ["application", "document"],
+    note: "document only for Save / Undo / Redo / Open in Browser, by frequency; ≤5 total",
+  },
+  "commandbar/overflow": {
+    admits: ["application", "project", "document"],
+    note: "never selection — the Command Bar is not a selection surface",
+  },
+  "statusbar/project": { admits: ["project"], note: "the status bar's left field" },
+  "statusbar/document": { admits: ["document"], note: "the status bar's centre field" },
+  "statusbar/selection": { admits: ["selection"], note: "the status bar's right field" },
+  "context/element": { admits: ["selection"], note: "the canvas element menu acts on a selection" },
+  "context/file": { admits: ["project"], note: "a file row addresses the project's file set" },
+  "context/layer": { admits: ["selection"], note: "an outline row IS a selection" },
+  "context/tab": { admits: ["document"], note: "a tab addresses one document" },
+  "context/pane": { admits: ["document"], note: "a pane hosts one document" },
+  blockbar: { admits: ["selection"], note: "the floating bar owns selection-scoped verbs" },
+  "blockbar/format": {
+    admits: ["selection"],
+    note: "the bar's inline-format cluster — a range inside the selection is still the selection",
+  },
+  "outline/row": { admits: ["selection"], note: "row actions act on the row's node" },
+  palette: {
+    admits: ["application", "project", "document", "selection"],
+    note: "the level-agnostic surface; it groups rows by level",
+  },
+  never: {
+    admits: ["application", "project", "document", "selection"],
+    note: "keyboard- and API-only; no rendered surface to be misplaced in",
+  },
+};
+
+// ─── Panels ───────────────────────────────────────────────────────────────────
+
+/**
+ * Every surface a Panel record may occupy.
+ *
+ * The rail's two level groups are SEPARATE placements, not one "mixed" region — principle 2's whole
+ * point. `navigator` is the dock body below them, which hosts whichever panel the rail selected and
+ * prints that panel's level in its header, so it is the one panel placement admitting two levels.
+ */
+export const PANEL_PLACEMENTS = [
+  "rail/project",
+  "rail/document",
+  "navigator",
+  "inspector",
+  "dock.bottom",
+] as const;
+
+export type PanelPlacement = (typeof PANEL_PLACEMENTS)[number];
+
+/**
+ * The level × placement matrix for Panel records — normative copy, mirrored into
+ * `studio-ui-guidelines.md` §12 beside {@link PLACEMENT_MATRIX}.
+ *
+ * The rail rows are what stop it re-accreting: a panel cannot be filed in the PROJECT group because
+ * "it feels project-ish", only because the state it WRITES is the project's (principle 3).
+ */
+export const PANEL_PLACEMENT_MATRIX: Readonly<Record<PanelPlacement, PlacementRule>> = {
+  "rail/project": {
+    admits: ["project"],
+    note: "the rail's upper group — Files, Search, Source Control, Problems",
+  },
+  "rail/document": {
+    admits: ["document"],
+    note: "the rail's lower group — Outline, Page, Data, Packages",
+  },
+  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" },
+  "dock.bottom": { admits: ["project", "document"], note: "the panel header states which" },
+};
+
+/** The subset of a Panel record this check reads. */
+export interface PlaceablePanel {
+  id: string;
+  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;
+}
+
+/** One rejected (panel, placement) pair. Shaped like {@link PlacementViolation}, keyed by panel. */
+export interface PanelPlacementViolation {
+  panelId: string;
+  placement: string;
+  level: string;
+  message: string;
+}
+
+/** The dock body placement a panel's `dock` names. */
+function dockPlacement(dock: PlaceablePanel["dock"]): PanelPlacement {
+  return dock === "bottom" ? "dock.bottom" : dock;
+}
+
+/**
+ * Every placement a Panel record occupies: its dock body, plus its rail group when it has a button.
+ *
+ * The rail group is DERIVED from the level rather than declared, which is what makes "grouped by
+ * level with a divider" (§3.2 ②) a property of the data instead of an ordering convention in the
+ * rail's template. A rail panel whose level has no group (`application`, `selection`) therefore
+ * names a placement the matrix does not contain, and is rejected below.
+ */
+export function panelPlacements(panel: PlaceablePanel): string[] {
+  const placements: string[] = [dockPlacement(panel.dock)];
+  if (panel.rail !== false) {
+    placements.push(`rail/${panel.level}`);
+  }
+  return placements;
+}
+
+/** 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);
+}
+
+/** Check one Panel record against {@link PANEL_PLACEMENT_MATRIX}. */
+export function checkPanelPlacement(panel: PlaceablePanel): PanelPlacementViolation[] {
+  const violations: PanelPlacementViolation[] = [];
+  if (!isLevel(panel.level)) {
+    violations.push({
+      panelId: panel.id,
+      placement: "—",
+      level: String(panel.level),
+      message:
+        `declares unknown level "${String(panel.level)}" ` +
+        `(expected one of: ${LEVELS.join(", ")})`,
+    });
+    return violations;
+  }
+  for (const placement of panelPlacements(panel)) {
+    if (!isPanelPlacement(placement)) {
+      violations.push({
+        panelId: panel.id,
+        placement,
+        level: panel.level,
+        message:
+          `is level "${panel.level}" and would render in "${placement}", which is not a panel ` +
+          `placement — the rail has a group for project and one for document, and nothing else`,
+      });
+      continue;
+    }
+    const rule = PANEL_PLACEMENT_MATRIX[placement];
+    if (!rule.admits.includes(panel.level)) {
+      violations.push({
+        panelId: panel.id,
+        placement,
+        level: panel.level,
+        message:
+          `is level "${panel.level}" but "${placement}" admits only ` +
+          `${rule.admits.join(", ")} — ${rule.note}`,
+      });
+    }
+  }
+  return violations;
+}
+
+/** Check a whole panel set. Empty result = the set satisfies the matrix. */
+export function checkPanelPlacements(panels: readonly PlaceablePanel[]): PanelPlacementViolation[] {
+  return panels.flatMap((panel) => checkPanelPlacement(panel));
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+/** The subset of a command record the placement check needs. */
+export interface PlaceableRecord {
+  id: string;
+  level: Level;
+  menus?: readonly Placement[] | undefined;
+}
+
+/** One rejected (command, placement) pair. */
+export interface PlacementViolation {
+  commandId: string;
+  placement: string;
+  level: string;
+  /** Ready-to-print explanation: what was declared, what the row admits, and why. */
+  message: string;
+}
+
+/** Whether `placement` is one of the {@link PLACEMENTS}. */
+export function isPlacement(value: string): value is Placement {
+  return (PLACEMENTS as readonly string[]).includes(value);
+}
+
+/** Whether `level` is one of the {@link LEVELS}. */
+export function isLevel(value: string): value is Level {
+  return (LEVELS as readonly string[]).includes(value);
+}
+
+/** Whether the matrix lets a `level` record render in `placement`. */
+export function placementAdmits(placement: Placement, level: Level): boolean {
+  return PLACEMENT_MATRIX[placement].admits.includes(level);
+}
+
+/**
+ * Check one record's declared placements against the matrix.
+ *
+ * A record with no `menus` defaults to `["palette"]`, which admits every level, so the default is
+ * always legal — a command has to opt IN to a region before it can be misplaced.
+ */
+export function checkRecordPlacements(record: PlaceableRecord): PlacementViolation[] {
+  const violations: PlacementViolation[] = [];
+  if (!isLevel(record.level)) {
+    violations.push({
+      commandId: record.id,
+      placement: "—",
+      level: String(record.level),
+      message:
+        `declares unknown level "${String(record.level)}" ` +
+        `(expected one of: ${LEVELS.join(", ")})`,
+    });
+    return violations;
+  }
+  for (const placement of record.menus ?? []) {
+    if (!isPlacement(placement)) {
+      violations.push({
+        commandId: record.id,
+        placement: String(placement),
+        level: record.level,
+        message: `declares unknown placement "${String(placement)}"`,
+      });
+      continue;
+    }
+    const rule = PLACEMENT_MATRIX[placement];
+    if (!rule.admits.includes(record.level)) {
+      violations.push({
+        commandId: record.id,
+        placement,
+        level: record.level,
+        message:
+          `is level "${record.level}" but "${placement}" admits only ` +
+          `${rule.admits.join(", ")} — ${rule.note}`,
+      });
+    }
+  }
+  return violations;
+}
+
+/** Check a whole command set. Empty result = the set satisfies the matrix. */
+export function checkPlacements(records: readonly PlaceableRecord[]): PlacementViolation[] {
+  return records.flatMap((record) => checkRecordPlacements(record));
+}

package/src/commands/live-context.ts

@@ -0,0 +1,193 @@
+/// <reference lib="dom" />
+/**
+ * Live-context.ts — the running app's answer to `getContext()`.
+ *
+ * `context.ts` owns the SHAPE and refuses to import a state module, which is what lets the CI
+ * checks load the command set in a bare Bun process. This file is the other half: it reads the
+ * three places state actually lives — the reactive `shell` record, `workspace` / `activeTab`, and
+ * `projectState` — and projects them onto that shape, once per predicate evaluation.
+ *
+ * **A fresh snapshot per call, deliberately.** The registry calls `getContext()` inside
+ * `visible()`, `isEnabled()` and `run()`, so a surface that repaints from an effect reads
+ * `shell.focusRegion`, `activeTab.value` and the tab's session THROUGH this builder while that
+ * effect is collecting dependencies — the effect therefore tracks them and re-runs when they
+ * change. Caching the record would be the one change that breaks that, and there is nothing to
+ * cache: every field is a property read or a `typeof fn === "function"` test.
+ *
+ * The recorded pitfall for reactive state — build nested collections complete BEFORE inserting
+ * them, because writes through a raw ref skip effects — does not bite here for the same reason: the
+ * returned record is a plain, complete, throwaway object. It is never made reactive and never
+ * mutated after construction.
+ *
+ * Four facts arrive by injection rather than by import: the canvas mode (owned by `studio.ts`), the
+ * caret and modal flags (`canvas/iframe-host.ts`, `ui/layers.ts`) and the platform. Injecting them
+ * keeps this module free of the import cycle studio.ts → shortcuts.ts → live-context.ts →
+ * studio.ts, and lets a test state a context without standing up the app.
+ */
+
+import { resolveI18n } from "@jxsuite/schema/locale";
+import { componentRegistry } from "../files/components";
+import { getNodeAtPath, projectState } from "../store";
+import { shell } from "../shell";
+import { activeTab, workspace } from "../workspace/workspace";
+import { primarySelection } from "../tabs/selection";
+import { canRedo, canUndo } from "../tabs/transact";
+import { collabState } from "../collab/collab-state";
+
+import { canvasViewForMode, editorKindForMode, emptyContext } from "./context";
+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]";
+
+/**
+ * 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.
+ */
+export function isTextEntryFocused(doc: Document = document): boolean {
+  const el = doc.activeElement;
+  return el instanceof HTMLElement && el.matches(TEXT_ENTRY);
+}
+
+/** The facts this module cannot reach without an import cycle or a DOM/platform singleton. */
+export interface LiveContextSources {
+  /** `studio.ts`'s `getCanvasMode()` — the per-tab preview toggle already composed in. */
+  canvasMode: () => string;
+  /** `canvas/iframe-host.ts`'s bridge-derived caret flag (P1). */
+  isCaretActive: () => boolean;
+  /** `ui/layers.ts`'s `isModalOpen()`. */
+  isModalOpen: () => boolean;
+  /** The registered platform, or null before one is registered. */
+  platform: () => StudioPlatform | null;
+  /** Whether the assistant has usable credentials (`services/ai-models`). */
+  aiConfigured: () => boolean;
+  /**
+   * Whether the assistant is mid-stream. `panels/ai-panel.ts` keeps its `DocumentAssistant` module-
+   * private, so there is nothing to read yet; the caller passes a probe when one exists.
+   */
+  aiStreaming?: () => boolean;
+}
+
+/** `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";
+  return {
+    dataRows: has("dataRows"),
+    // The real member now, not the `codeService` stand-in it was minted against: the usage query is
+    // Its own route over the rename refactor's walker, and cloud computes it server-side.
+    findReferences: has("findReferences"),
+    gitClone: has("gitClone"),
+    importSite: has("importSite"),
+    openProjectInNewWindow: has("openProjectInNewWindow"),
+    // Multi-window is a desktop-only family; `newWindow` is the one every member implies.
+    windowControls: has("newWindow"),
+  };
+}
+
+/**
+ * Build the live `getContext` thunk.
+ *
+ * @returns A function the registry calls per predicate evaluation.
+ */
+export function createLiveContext(sources: LiveContextSources): () => CommandContext {
+  return () => {
+    const ctx = emptyContext();
+    const tab = activeTab.value ?? null;
+    const project = projectState;
+    const mode = sources.canvasMode();
+
+    ctx.project.open = project !== null;
+    ctx.project.isSite = project?.isSiteProject === true;
+    // A project is a repository once git has answered for it. Before the first refresh the honest
+    // Answer is "not yet", and Source Control's own commands are the ones that refresh it.
+    ctx.project.isRepo = shell.git.status?.isRepo === true;
+    /*
+     * Two locales, not two entries in the array: the shared resolver canonicalizes and drops what
+     * it cannot parse, so `["en", "en", "not_a_tag"]` is one locale and gates nothing on. Reading
+     * `.length` off the raw config would open every i18n surface on a project that has none.
+     *
+     * `@jxsuite/schema/locale` and not `site-context.ts`: everything reachable from
+     * `app-commands.ts` has to load in a bare Bun process with no DOM, and that module reaches the
+     * platform. This one is `Intl` and string math.
+     */
+    ctx.project.isMultilingual =
+      (resolveI18n(project?.projectConfig ?? {}).i18n?.locales.length ?? 0) > 1;
+    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.document.open = tab !== null;
+    ctx.document.dirty = tab?.doc.dirty === true;
+    ctx.document.mode = tab?.doc.mode ?? "";
+    ctx.document.canUndo = tab ? canUndo(tab) : false;
+    ctx.document.canRedo = tab ? canRedo(tab) : false;
+
+    ctx.editor.kind = tab ? editorKindForMode(mode) : "none";
+    ctx.canvas.view = canvasViewForMode(mode);
+    /* The grid, counted from the grid. This read spent two phases saying "panes land in P3; until
+       then the grid is one pane showing the focused tab" — through P3, which built the pane model,
+       and through P8, which gave every pane a live stage. It counted `workspace.tabOrder`, the
+       FOCUSED pane's strip, so it could never answer 2 and answered 0 whenever no tab was open,
+       while a pane with no tab is still a pane. `derived` was declared and never assigned at all.
+       `services/automation.ts` publishes this whole record as `probe.state()`, so the screenshot
+       pipeline and the assistant were both reading it.
+
+       `derived` is ASSIGNED now, and it means "the grid contains a derived pane" — the fact the two
+       predicates that need it actually ask. A third phase of a declared-never-assigned context key
+       is not caution; it is the `layoutSelection`-with-no-writer shape this codebase keeps
+       catching. */
+    ctx.pane.count = workspace.panes.length;
+    ctx.pane.derived = workspace.panes.some((pane) => pane.derived !== null);
+
+    const paths = tab?.session.selection ?? [];
+    const selection = primarySelection(paths);
+    if (selection) {
+      const node = getNodeAtPath(tab!.doc.document, selection);
+      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 : "";
+      // 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.isRepeater = node?.$prototype === "Array";
+    }
+    // Layout chrome is NOT a document selection: the node is not in the open page at all.
+    ctx.selection.isLayoutNode = shell.layoutSelection !== null;
+
+    // A parent-realm text field owns the keyboard exactly as a canvas caret does. Folding both into
+    // One key is what lets `keyScopeStack` stay a pure function of the context.
+    ctx.caret.active = sources.isCaretActive() || isTextEntryFocused();
+    /* …and folding them is wrong for a RECORD, which is why `inCanvas` is the bridge fact alone.
+       `format.bold` and `format.link` are `keyScope: "caret"`, so they are live wherever the caret
+       stack is — including the link popover's own URL field, where ⌘K would re-mount the popover
+       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.modal.open = sources.isModalOpen();
+
+    if (tab) {
+      const collab = collabState(tab);
+      ctx.collab.attached = collab.active;
+      ctx.collab.readOnly = collab.readOnly;
+      ctx.collab.sourceCanonical = collab.sourceCanonical;
+    }
+
+    ctx.ai.configured = sources.aiConfigured();
+    ctx.ai.streaming = sources.aiStreaming?.() ?? false;
+    ctx.capability = capabilities(sources.platform());
+    return ctx;
+  };
+}