@jxsuite/studio 3.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -52,19 +52,20 @@
     "lint:styles": "bun run scripts/check-styles.ts",
     "test": "bun run lint:styles && bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^3.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.1.0",
-    "@jxsuite/ai": "^0.36.4",
-    "@jxsuite/collab": "^0.8.3",
-    "@jxsuite/create": "^1.3.7",
-    "@jxsuite/formulas": "^0.0.14",
-    "@jxsuite/markup": "^0.4.7",
-    "@jxsuite/protocol": "^2.0.0",
-    "@jxsuite/runtime": "^2.1.0",
-    "@jxsuite/schema": "^1.9.0",
+    "@jxsuite/ai": "^0.36.5",
+    "@jxsuite/collab": "^0.8.4",
+    "@jxsuite/create": "^1.3.8",
+    "@jxsuite/formulas": "^0.0.15",
+    "@jxsuite/markup": "^0.4.8",
+    "@jxsuite/protocol": "^2.1.0",
+    "@jxsuite/runtime": "^3.0.0",
+    "@jxsuite/schema": "^2.0.0",
+    "@jxsuite/site": "^1.0.0",
     "@spectrum-web-components/accordion": "^1.12.2",
     "@spectrum-web-components/action-bar": "1.12.2",
     "@spectrum-web-components/action-button": "^1.12.2",
@@ -107,15 +108,15 @@
     "lit": "^3.3.3",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.56.0",
-    "tabulator-tables": "^6.5",
+    "tabulator-tables": "^6.5.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6",
+    "@happy-dom/global-registrator": "^20.11.8",
     "@types/mdast": "^4.0.4",
-    "@webref/css": "^8.7.2",
-    "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.82.2"
+    "@webref/css": "^8.7.3",
+    "@webref/elements": "^2.8.0",
+    "@webref/idl": "^3.83.0"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

package/src/browse/library-pane.ts

@@ -42,6 +42,7 @@ import { invalidateUsages } from "../services/references";
 import { confirmFileDelete, renamePromptMessage } from "../files/file-ops";
 import { createFileIn, openFileInTab } from "../files/files";
 import { createEntry } from "../content/entry-commands";
+import { formatByExtension, formatSerialize } from "../format/format-host";
 import { entryCollections } from "../content/entry-model";
 import { uploadAccept, uploadAssets } from "../files/media-upload";
 import { localeLabel } from "@jxsuite/schema/locale";
@@ -70,6 +71,7 @@ import {
   tableRowsTpl,
 } from "./library-layouts";
 import type { ActivityHandle } from "../panels/activity-panel";
+import type { FormatChoice } from "../files/files";
 import type { EffectScope } from "@vue/reactivity";
 import type { LibraryFile, LibraryLayout } from "./library-model";
 import type { LibrarySource } from "./library-source";
@@ -602,10 +604,60 @@ export function libraryNewEntries(): LibraryNewEntry[] {
  * `createEntry` is called rather than reimplemented; a second seeder here would drift from the one
  * the palette's `content.newEntry` uses within a release.
  *
- * A **document kind** keeps `files.ts`'s verbatim name field, deliberately: a page may be a `.md`
- * as easily as a `.json`, so the extension the author types is a real choice and forcing one here
- * would remove it. A collection's extension is not a choice — it is the collection's.
+ * A **document kind** gets the format PICKER, which is the same argument the verbatim name field
+ * used to make: a page may be a `.md` as easily as a `.json`, so the extension is a real choice —
+ * now offered rather than left to be typed from memory. A collection's extension is not a choice;
+ * it is the collection's, and `createEntry` supplies it.
+ *
+ * **A layout is not a choice either, and that is not a policy.** Both readers of a layout parse it
+ * as JSON and neither dispatches through the format registry — `site/layout-resolver.ts` throws and
+ * `site-context.ts` returns null — so a `.md` layout is a file the build cannot load. There is no
+ * `"layout"` document kind for a format to declare, so this is stated here rather than derived.
+ *
+ * A **component** keeps the picker: a format whose `$studio.documentMode.componentWhen` promotes a
+ * frontmatter `tagName` (Markdown's does) can express one perfectly well. What it cannot do is
+ * express one from a `newFileTemplate` that carries no `tagName`, so the seed below supplies it —
+ * through the format's own serializer, because this module knows no format's syntax.
+ */
+/** How each document kind's extension is settled. Anything else falls back to the full picker. */
+const FORMAT_CHOICE_BY_KIND: Record<string, FormatChoice> = {
+  component: { defaultExt: ".json", docKind: "component", kind: "choose" },
+  layout: { ext: ".json", kind: "fixed" },
+  page: { defaultExt: ".json", docKind: "page", kind: "choose" },
+};
+
+/**
+ * The body a new component starts as, when the reader picked a format rather than `.json`.
+ *
+ * `.json` answers `undefined` and takes the shared blank document. A format answers with its OWN
+ * serialization of `{ tagName }` — never a hand-written `---\ntagName: …\n---`, which would put one
+ * format's syntax in the Library. Without the `tagName` the file satisfies neither
+ * `$studio.documentMode.componentWhen` nor the build's tag registration, and is a component nothing
+ * loads. A stem that is not a valid custom-element name (no hyphen) cannot carry one, so it falls
+ * back to the format's own template and the author names the tag themselves.
  */
+async function componentSeed(ext: string, fileName: string): Promise<string | undefined> {
+  const format = formatByExtension(ext);
+  if (!format?.capabilities.serialize) {
+    return undefined;
+  }
+  const tagName = fileName.slice(0, fileName.length - ext.length);
+  if (!/^[a-z][\d.a-z]*-[\d.a-z-]*$/.test(tagName)) {
+    return undefined;
+  }
+  try {
+    return await formatSerialize(
+      format.name,
+      { children: [], tagName },
+      { frontmatter: true, mode: "roundtrip" },
+    );
+  } catch {
+    // The serializer is the project's, so its failure is not a reason to refuse the creation —
+    // The format's own template still produces a file the author can finish by hand.
+    return undefined;
+  }
+}
+
 export async function createLibraryEntry(key: string): Promise<string | null> {
   const entry = libraryNewEntries().find((row) => row.key === key);
   if (!entry) {
@@ -614,7 +666,9 @@ export async function createLibraryEntry(key: string): Promise<string | null> {
   const created =
     entry.collection === undefined
       ? await createFileIn({
+          ...(entry.key === "component" ? { content: componentSeed } : {}),
           dir: entry.dir,
+          format: FORMAT_CHOICE_BY_KIND[entry.key] ?? { defaultExt: ".json", kind: "choose" },
           source: "Library",
           suggestedName: "untitled",
           title: `New ${entry.label}`,

package/src/canvas/canvas-render.ts

@@ -37,10 +37,12 @@ import { attachCursorStyles } from "../collab/monaco-cursors";
 import type { AwarenessLike } from "../collab/monaco-cursors";
 import type { BindingAwareness } from "../collab/monaco-binding";
 import { monacoTheme, shell } from "../shell";
-import { parseSourceForPath, serializeDocument } from "../files/file-ops";
+import { parseSourceForPath } from "../files/file-ops";
+import { serializeDocument } from "../files/serialize-document";
 import { detachGridPanel, gridPanelMounted, renderGridMode } from "../grid/grid-panel";
 import { detachLibraryPane, libraryPaneMounted, renderLibraryMode } from "../browse/library-pane";
 import { detachEntryPane, entryPaneMounted, renderEntryMode } from "../content/entry-editor";
+import { detachMediaPane, mediaPaneMounted, renderMediaMode } from "../media/media-pane";
 import {
   detachSettingsPane,
   renderSettingsPane,
@@ -370,6 +372,7 @@ function resetCanvasView(surface: CanvasSurface) {
   detachGridPanel(paneId);
   detachLibraryPane(paneId);
   detachEntryPane(paneId);
+  detachMediaPane(paneId);
   detachSettingsPane(paneId);
   disposeSourceCollab(surface);
   disposeSourceEditor(surface);
@@ -883,6 +886,12 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
+  // Media fast-path, same shape: the viewer owns its own effect, so learning an image's dimensions
+  // Repaints that panel and nothing reaches the canvas pipeline.
+  if (canvasMode === "media" && mediaPaneMounted(surface.paneId, tab) && !modeChanged) {
+    return;
+  }
+
   // Settings fast-path, same shape: the Project Settings editor subscribes to the section registry
   // And to its own chosen section, so a mounted editor needs nothing from the canvas pipeline.
   if (canvasMode === "settings" && settingsPaneMounted(surface) && !modeChanged) {
@@ -953,6 +962,9 @@ function renderCanvasImpl(surface: CanvasSurface) {
     // Same for the entry form, whose effect scope subscribes to the document's frontmatter
     detachEntryPane(surface.paneId);
 
+    // And for the media viewer, whose effect scope subscribes to the tab's path
+    detachMediaPane(surface.paneId);
+
     // Same for the Project Settings editor, which holds a registry subscription
     detachSettingsPane(surface.paneId);
 
@@ -1068,6 +1080,15 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
+  /* Media mode: an image, a video, a font specimen — a file the studio can SHOW but has no document
+     model for (`media/media-pane.ts`). Same non-iframe-editor pattern as the four above. */
+  if (canvasMode === "media") {
+    canvasWrap.style.padding = "0";
+    canvasWrap.style.display = "block";
+    renderMediaMode(surface, tab);
+    return;
+  }
+
   // Grid mode: spreadsheet editor over the tab's grid source (mirrors the Monaco/stylebook
   // Non-iframe-editor pattern; the panel owns its own reactivity from here).
   if (canvasMode === "grid") {
@@ -1508,6 +1529,7 @@ setSurfaceTeardown((surface) => {
   detachGridPanel(surface.paneId);
   detachLibraryPane(surface.paneId);
   detachEntryPane(surface.paneId);
+  detachMediaPane(surface.paneId);
   detachSettingsPane(surface.paneId);
   attachDocumentHeaderHost(surface.paneId, null);
   disposeSourceCollab(surface);

package/src/canvas/iframe-patch.ts

@@ -56,12 +56,38 @@ export function applyIframePatch(
   const echoed = new Set(echoPaths.map((p) => serializeJxPath(p)));
   for (const op of forwardOps) {
     if (op.op === "set-key" && echoed.has(serializeJxPath(op.path))) {
+      // The content is already right; only the model-derived placeholder class can be stale, and
+      // Reconciling a class touches neither the caret nor the text under it.
+      syncEchoedPlaceholder(shadowDoc, op.path, container);
       continue;
     }
     applyOpToDom(shadowDoc, op, container, ctx);
   }
 }
 
+/**
+ * Re-derive the empty-placeholder class of an ECHOED node without writing its content.
+ *
+ * An echo is the author's own typing coming back as a patch, so the DOM already holds the text —
+ * but `empty-text-placeholder` was stamped when the block was empty and nothing else would ever
+ * take it off, because the write that would have (patchText) is exactly what echo suppression
+ * skips. The CSS asks the DOM whether the block is empty, so nothing is misdrawn in the meantime;
+ * this keeps the class itself honest, so the DOM does not carry a claim the document contradicts.
+ *
+ * Best-effort by design: a missing element is not an error worth escalating a full render (and the
+ * caret with it) over a class.
+ */
+function syncEchoedPlaceholder(
+  doc: JxMutableNode,
+  path: (string | number)[],
+  container: HTMLElement,
+): void {
+  const el = findElement(container, path);
+  if (el) {
+    syncPlaceholderClass(el, getNodeAtPath(doc, path));
+  }
+}
+
 /** The render context, asserted present for ops that re-render a subtree (the caller always has it). */
 function requireCtx(ctx: IframeRenderCtx | undefined): IframeRenderCtx {
   if (!ctx) {
@@ -134,7 +160,7 @@ function insertChild(
   // Remap existing siblings BEFORE attaching the new subtree so it isn't itself remapped.
   remapChildPaths(container, parentPath, index, 1);
   insertAt(parentEl, newEl, domChildReference(parentEl, parentNode, index));
-  syncContainerPlaceholder(parentEl, parentNode);
+  syncPlaceholderClass(parentEl, parentNode);
 }
 
 /** Re-render the node at `docPath` and swap it into the DOM in place (disposing the old subtree). */
@@ -165,7 +191,7 @@ function removeChild(
   el.remove();
   remapChildPaths(container, parentPath, index + 1, -1);
   if (parentEl) {
-    syncContainerPlaceholder(parentEl, getNodeAtPath(doc, parentPath));
+    syncPlaceholderClass(parentEl, getNodeAtPath(doc, parentPath));
   }
 }
 
@@ -202,25 +228,25 @@ function moveChild(
   // Emptiness may have changed at either end (e.g. moved the last/only child out, or into an empty
   // Container) — keep both parents' placeholder classes in sync with the folded doc.
   if (fromParentEl) {
-    syncContainerPlaceholder(
+    syncPlaceholderClass(
       fromParentEl,
       getNodeAtPath(doc, elementPath(fromParentEl) ?? fromParentPath),
     );
   }
-  syncContainerPlaceholder(toParentEl, toParentNode);
+  syncPlaceholderClass(toParentEl, toParentNode);
 }
 
 /**
- * Keep a container's empty-placeholder class in sync with its (folded) doc node after a child
- * change.
+ * Put `el`'s empty-placeholder class back in step with its (folded) doc node — a container's after
+ * a child change, a text block's after its content changed.
  */
-function syncContainerPlaceholder(parentEl: Element, parentNode: JxMutableNode | undefined): void {
+function syncPlaceholderClass(el: Element, node: JxMutableNode | undefined): void {
   for (const cls of EMPTY_PLACEHOLDER_CLASSES) {
-    parentEl.classList.remove(cls);
+    el.classList.remove(cls);
   }
-  const placeholder = parentNode ? computeEmptyPlaceholderClass(parentNode) : null;
+  const placeholder = node ? computeEmptyPlaceholderClass(node) : null;
   if (placeholder) {
-    parentEl.classList.add(placeholder);
+    el.classList.add(placeholder);
   }
 }
 
@@ -321,24 +347,24 @@ function patchText(doc: JxMutableNode, path: (string | number)[], container: HTM
   const el = requireElement(container, path);
   const node = getNodeAtPath(doc, path);
   el.textContent = textDisplayValue(node);
-  for (const cls of EMPTY_PLACEHOLDER_CLASSES) {
-    el.classList.remove(cls);
-  }
-  const placeholder = node ? computeEmptyPlaceholderClass(node) : null;
-  if (placeholder) {
-    el.classList.add(placeholder);
-  }
+  syncPlaceholderClass(el, node);
 }
 
 /** Locate the rendered element for a document path via its stamped `data-jx-path` attribute. */
 function requireElement(container: HTMLElement, path: (string | number)[]): HTMLElement {
+  const el = findElement(container, path);
+  if (!el) {
+    throw new Error(`iframe-patch-element-not-found:${serializeJxPath(path)}`);
+  }
+  return el;
+}
+
+/** The rendered element for a document path, or null when this render has none. */
+function findElement(container: HTMLElement, path: (string | number)[]): HTMLElement | null {
   const serialized = serializeJxPath(path);
   const esc = serialized.replaceAll("\\", String.raw`\\`).replaceAll("'", String.raw`\'`);
   const el = container.querySelector(`[data-jx-path='${esc}']`);
-  if (!(el instanceof HTMLElement)) {
-    throw new Error(`iframe-patch-element-not-found:${serialized}`);
-  }
-  return el;
+  return el instanceof HTMLElement ? el : null;
 }
 
 /**

package/src/canvas/iframe-render.ts

@@ -28,7 +28,7 @@ import {
 import { resolveAssetRef } from "./asset-resolve";
 import { classifyRenderNode, serializeJxPath } from "./path-mapping";
 import type { AssetContext } from "./asset-resolve";
-import { SITE_STYLE_ID, buildSiteStyleCSS } from "./site-style-css";
+import { SITE_STYLE_ID, buildSiteStyleCSS } from "@jxsuite/site/site-style";
 import type { CanvasMode } from "./iframe-protocol";
 import type { JxDocument } from "@jxsuite/schema/types";
 import type { PathMapCtx } from "./path-mapping";
@@ -105,9 +105,25 @@ export const EDIT_PLACEHOLDER_STYLE_ID = "jx-canvas-edit-css";
  * iframe-safe fallbacks — the parent theme variables (--fg-dim/--radius/--accent) don't exist in
  * the iframe document. The placeholder CLASSES are stamped by prepareForEditMode (parent-side
  * resolution + surgical subtree renders), so preview mode never matches these rules — but the sheet
- * is still removed there (belt and braces). The `[contenteditable="true"]:empty` hint is new: it
- * marks the caret's empty paragraph (e.g. right after an Enter split) and advertises the slash
- * menu.
+ * is still removed there (belt and braces). The `[data-jx-active-block]` hint marks the caret's
+ * empty paragraph (e.g. right after an Enter split) and advertises the slash menu.
+ *
+ * `.empty-text-placeholder` is gated on emptiness IN THE DOM because a CLASS cannot tell the truth
+ * about a block the author is typing in. The class is stamped from the document, and the first
+ * thing typed into an empty block reaches the DOM natively — the model learns of it a commit tick
+ * later, and that patch comes back as an ECHO, which `applyIframePatch` deliberately does not
+ * re-render (it would destroy the caret). So the class outlived its own meaning, and "Click here to
+ * add text..." sat beside the text you had just typed until the next full render. The class now
+ * selects WHICH affordance; the DOM answers whether the block is empty.
+ *
+ * "Empty" is `:empty` OR a lone `<br>`, because emptying a block by editing does not leave it
+ * `:empty`: the engine drops in a filler `<br>` to keep the line visible (Chrome 151, verified —
+ * `execCommand("delete")` over a `<p>`'s whole content leaves `<p><br></p>`). Without that arm the
+ * affordance would go dark exactly when the block became empty again.
+ *
+ * `:not([data-jx-active-block])` keeps the slash hint winning on an empty block that HAS the caret:
+ * both rules match the same element, and the emptiness test broke the specificity tie that used to
+ * decide it by source order.
  */
 export const EDIT_PLACEHOLDER_CSS = `
 .empty-media-placeholder {
@@ -123,7 +139,7 @@ export const EDIT_PLACEHOLDER_CSS = `
   font-size: 0;
   overflow: hidden;
 }
-.empty-text-placeholder:not([contenteditable])::after {
+.empty-text-placeholder:is(:empty, :has(> br:only-child)):not([data-jx-active-block]):not([contenteditable])::after {
   content: "Click here to add text...";
   color: color-mix(in srgb, #808080 40%, transparent);
   font-style: italic;
@@ -149,7 +165,7 @@ export const EDIT_PLACEHOLDER_CSS = `
   pointer-events: none;
   white-space: nowrap;
 }
-[data-jx-active-block]:empty::after {
+[data-jx-active-block]:is(:empty, :has(> br:only-child))::after {
   content: "Type / for commands";
   color: color-mix(in srgb, #808080 40%, transparent);
   font-style: italic;

package/src/commands/app-commands.ts

@@ -61,6 +61,7 @@ import { i18nCommands } from "../i18n/i18n-commands";
 import { newProjectCommands } from "../new-project/new-project-modal";
 import { canvasCommands } from "../editor/shortcuts";
 import { formatCommands, registerSelectionCommands } from "../panels/block-action-bar";
+import { fileFormatCommands } from "../format/convert-file";
 import { registerTabCommands } from "../workspace/workspace";
 import { derivationCommands, noopDerivationDeps } from "../workspace/pane-derive";
 import type { AnyCommand } from "./registry";
@@ -154,6 +155,9 @@ export function appCommandSet(): AnyCommand[] {
     // That renders them, and projected here so the palette, the level check and the generated
     // Keyboard sheet all see the first `caret`-scoped chords the app has ever had.
     ...formatCommands(),
+    // The file-format verb: `file.convertFormat`, declared for `context/file` so the Files tree
+    // Renders it off the record rather than hand-building a row beside the declared ones.
+    ...fileFormatCommands(),
     /* The canvas keyboard's own nine, plus the clipboard pair they spread.
        These were the last records the app registered and this projection did not contain, so ⌘C,
        ⌘X, ⌘V, Enter, the three structural arrows and all three zoom chords were absent from

package/src/commands/command-args.ts

@@ -216,6 +216,35 @@ export function enumProperty(declared: readonly string[], description: string):
   return { description, enum: [...declared], type: "string" };
 }
 
+/**
+ * An enum property whose values are derived WHEN THE SCHEMA IS READ, not when the record is
+ * defined.
+ *
+ * `enumProperty(collections(), …)` looks identical and is wrong for anything a PROJECT supplies,
+ * and the difference is invisible in a unit test: a command record is built at module scope —
+ * `commands/app-commands.ts` and `studio.ts` both build theirs before a project is open — so the
+ * array freezes at `[]`, and `panels/quick-search.ts`'s `paletteArgs` offers an empty choice list
+ * forever after. `run` re-derives the list, which is why the programmatic call works and the
+ * palette does not: two answers to "what is there", one of them a snapshot of the empty boot
+ * state.
+ *
+ * A getter is the whole fix — the palette reads `property.enum` when it opens the prompt, the AI
+ * tool's parameters serialise it when the tool list is built, and `scripts/check-shot-contract.ts`
+ * reads it in a bare Bun process where the honest answer really is "none declared".
+ */
+export function derivedEnumProperty(
+  declared: () => readonly string[],
+  description: string,
+): object {
+  return {
+    description,
+    get enum() {
+      return [...declared()];
+    },
+    type: "string",
+  };
+}
+
 /** A number property, optionally bounded — the bounds a control already enforces, written down. */
 export function numberProperty(
   description: string,

package/src/commands/context.ts

@@ -55,6 +55,7 @@ export type EditorKind =
   | "library"
   | "config"
   | "entry"
+  | "media"
   | "none";
 
 /** The Canvas view axis — one control, three values (§4.2). */
@@ -87,6 +88,10 @@ const EDITOR_KIND_BY_MODE: Readonly<Record<string, EditorKind>> = {
   "git-diff": "diff",
   grid: "grid",
   manage: "library",
+  /* The Media viewer — `media/media-pane.ts`. An image, a video, a font specimen: files the studio
+     can SHOW but has no document model for, which is why clicking one used to end in "No format
+     class imported for …", advice that means nothing about a PNG. */
+  media: "media",
   preview: "canvas",
   /* Project Settings — `settings/settings-document.ts`'s SETTINGS_MODE. A form over `project.json`,
      which is a configuration object and not a document tree; `stylebook` (Project Styles) is the
@@ -117,6 +122,7 @@ export const EDITOR_KIND_LABELS: Readonly<Record<EditorKind, string>> = {
   diff: "Diff",
   entry: "Entry",
   grid: "Grid",
+  media: "Media",
   library: "Library",
   none: "None",
 };
@@ -232,6 +238,14 @@ export interface CommandContext {
   ai: {
     configured: boolean;
     streaming: boolean;
+    /**
+     * A turn is suspended on an `ask_user` question.
+     *
+     * Distinct from `streaming` rather than folded into it: no tokens are moving, so a surface that
+     * paints a spinner on `streaming` must not paint one here — but the turn is alive and holding a
+     * tool open, so Stop is enabled on the union of the two.
+     */
+    waiting: boolean;
   };
   capability: Record<Capability, boolean>;
 }
@@ -287,7 +301,7 @@ export function emptyContext(): CommandContext {
     focus: { region: "pane" },
     modal: { open: false },
     collab: { attached: false, readOnly: false, sourceCanonical: false },
-    ai: { configured: false, streaming: false },
+    ai: { configured: false, streaming: false, waiting: false },
     capability: {
       gitClone: false,
       importSite: false,

package/src/commands/defaults.ts

@@ -102,6 +102,7 @@ export interface CommandDeps {
   undo: () => void;
   redo: () => void;
   openInBrowser: () => void | Promise<void>;
+  buildSite: () => void | Promise<void>;
   closeDocument: () => void;
   duplicateSelection: () => void;
   deleteSelection: () => void;
@@ -147,6 +148,7 @@ export function noopCommandDeps(): CommandDeps {
     undo: () => {},
     redo: () => {},
     openInBrowser: () => {},
+    buildSite: () => {},
     closeDocument: () => {},
     duplicateSelection: () => {},
     deleteSelection: () => {},
@@ -243,9 +245,35 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       group: "2_output",
       when: (ctx) => ctx.project.isSite,
       enablement: documentOpen,
-      requires: "a built page to open",
+      /* "A page to preview", not "a built page to open". Nothing is built on the way here any
+         more: the working tree is rendered at its real route, so what this waits for is a document
+         with a route rather than an output file. */
+      requires: "a page to preview",
       run: () => deps.openInBrowser(),
     },
+    {
+      /*
+       * The compiler, kept reachable under its own verb.
+       *
+       * `View: Open in Browser` used to run a full build, which answered "does my site build?" as a
+       * side effect of asking "what does this page look like?". Those are different questions and
+       * only one of them is worth waiting for a bundler, an image pipeline and every emitter. So
+       * the build keeps a command of its own rather than disappearing with the coupling.
+       *
+       * `commandbar/overflow` rather than `commandbar/primary`: the primary row is budgeted at five
+       * and is document-level by frequency (studio-ui-guidelines §12), and a build is neither
+       * frequent nor about the document in front of you. No default chord for the same reason.
+       */
+      id: "project.buildSite",
+      title: "Build Site",
+      category: "Project",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "2_output",
+      when: (ctx) => ctx.project.isSite,
+      requires: "a site project",
+      run: () => deps.buildSite(),
+    },
 
     // ── Edit ──
     {

package/src/commands/levels.ts

@@ -77,6 +77,14 @@ export const PLACEMENTS = [
    */
   "blockbar/format",
   "outline/row",
+  /**
+   * The rail foot's ⚙ Settings menu — the settings FAMILY, and only it.
+   *
+   * A separate placement rather than a second use of `commandbar/overflow`, for the reason the
+   * status bar is three placements: the ⬢ menu is the chrome's residue for retired controls and
+   * this is a named family with its own trigger. Same admits, different surface, different budget.
+   */
+  "settings/menu",
   "palette",
   "never",
 ] as const;
@@ -119,6 +127,14 @@ export const PLACEMENT_MATRIX: Readonly<Record<Placement, PlacementRule>> = {
     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" },
+  "settings/menu": {
+    admits: ["application", "project"],
+    note:
+      "the rail foot's gear menu — the settings family. It is a MENU, not a pinned slot, so it " +
+      "may host two levels for the reason commandbar/overflow does: a menu prints each row's own " +
+      "name, chord and gate, and draws a divider where the level changes. The rail's PINNED " +
+      "groups stay single-level, in PANEL_PLACEMENT_MATRIX",
+  },
   palette: {
     admits: ["application", "project", "document", "selection"],
     note: "the level-agnostic surface; it groups rows by level",

package/src/commands/live-context.ts

@@ -72,6 +72,8 @@ export interface LiveContextSources {
    * private, so there is nothing to read yet; the caller passes a probe when one exists.
    */
   aiStreaming?: () => boolean;
+  /** Whether a turn is suspended on an `ask_user` question (`panels/ai-panel.ts`). */
+  aiWaiting?: () => boolean;
 }
 
 /** `capability.*` is presence-of-method on the PAL — the check every call site does by hand today. */
@@ -187,6 +189,7 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
 
     ctx.ai.configured = sources.aiConfigured();
     ctx.ai.streaming = sources.aiStreaming?.() ?? false;
+    ctx.ai.waiting = sources.aiWaiting?.() ?? false;
     ctx.capability = capabilities(sources.platform());
     return ctx;
   };