@jxsuite/studio 2.4.3 → 4.0.0

package/src/canvas/canvas-live-render.ts

@@ -20,6 +20,7 @@ import {
   resolveLayoutDoc,
 } from "../site-context";
 import { documentBase } from "./canvas-origin";
+import { getPlatform, hasPlatform } from "../platform";
 import { componentRegistry, computeRelativePath } from "../files/components";
 import { prepareForEditMode } from "../utils/edit-display";
 import {
@@ -28,11 +29,11 @@ import {
   substitutePreviewParams,
 } from "../page-params";
 import { isComponentDoc, substitutePreviewProps } from "../component-props";
-import { rewriteContentAssets } from "./content-assets";
+import { assetContextFor } from "./asset-refs";
 
+import type { AssetContext } from "./asset-refs";
 import type { JxElement, JxMutableNode, JxPath } from "@jxsuite/schema/types";
 import type { ComponentEntry } from "../files/components.js";
-import type { ContentSectionEntry } from "../types";
 import type { LayoutMarker } from "./path-mapping";
 import type { Tab } from "../tabs/tab";
 import type { WireMapperCtx } from "./iframe-protocol";
@@ -138,6 +139,8 @@ export async function resolveCanvasDocument(
 ): Promise<{
   renderDoc: JxMutableNode;
   docBase: string | undefined;
+  /** How the canvas must address project media, or null when its origin serves the site URL space. */
+  assets: AssetContext | null;
   mapperCtx: WireMapperCtx;
   siteStyle: Record<string, unknown> | null;
 }> {
@@ -179,9 +182,23 @@ export async function resolveCanvasDocument(
     }
   }
 
-  const docBase = S.documentPath
-    ? new URL(S.documentPath, documentBase(projectState?.projectRoot)).href
-    : undefined;
+  const fileBase = documentBase(projectState?.projectRoot);
+  const docBase = S.documentPath ? new URL(S.documentPath, fileBase).href : undefined;
+  /*
+   * How this render addresses media, as PLAIN DATA — the resolver itself is a function and cannot
+   * cross into the canvas realm, so the iframe rebuilds it from this.
+   *
+   * It replaces a walk over the render document that used to sit further down this function. A walk
+   * can only ever see LITERAL values: `applyAttributes` resolves a `{"$ref": …}` or `"${…}"` src
+   * inside a reactive effect, so at walk time a bound image src is not a string at all. That is why
+   * a collection listing of thirty bound card images broke all at once in preview and nowhere else
+   * — design and edit swap every bound src for a transparent pixel, so they never reached the
+   * network to fail.
+   */
+  const assets = assetContextFor(S.documentPath, {
+    fileBaseUrl: fileBase,
+    ...(hasPlatform() ? { space: getPlatform().assetSpace } : {}),
+  });
 
   // Substitute chosen dynamic route params ({$ref: "#/$params/x"} → literal), inject state.$page,
   // And bake the substituted class-prototype state entries via the backend resolver — in every
@@ -210,16 +227,6 @@ export async function resolveCanvasDocument(
     }
   }
 
-  // A content entry references its media relative to ITSELF; the built site serves those files from
-  // The content type's asset mount. Studio opens the entry standalone, so the collection loader that
-  // Normally performs that mapping never runs — do it here, on the RENDER doc only, so the canvas
-  // Previews the URL production serves while the source doc keeps the authored relative ref.
-  renderDoc = rewriteContentAssets(
-    renderDoc,
-    S.documentPath,
-    projectState?.projectConfig?.content as Record<string, ContentSectionEntry> | undefined,
-  );
-
   const arrayPaths = new Set<string>();
   if (canvasMode === "design" || canvasMode === "edit") {
     (function findArrayPaths(node: JxMutableNode, path: (string | number)[]) {
@@ -321,6 +328,7 @@ export async function resolveCanvasDocument(
   }
 
   return {
+    assets,
     docBase,
     mapperCtx: {
       arrayPaths: [...arrayPaths],

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-entry.ts

@@ -859,6 +859,7 @@ export function startCanvasIframe(opts: {
         stopDataScopeWatch = null;
         handle?.dispose();
         handle = await renderResolvedDocument({
+          assets: msg.assets ?? null,
           container,
           doc: msg.doc as JxDocument,
           docBase: msg.docBase,

package/src/canvas/iframe-host.ts

@@ -2775,6 +2775,7 @@ function preparePassRender(
     const formatElements = formatByName(renderTab?.doc.sourceFormat)?.studio?.elements;
     const editableTags = formatElements ? formatEditableVerdicts(formatElements) : undefined;
     return {
+      assets: resolved.assets,
       doc: cloneableDoc,
       docBase: resolved.docBase ?? `${canvasBaseOrigin()}/`,
       mapperCtx: resolved.mapperCtx,
@@ -2898,6 +2899,9 @@ export function mountStylebookCanvas(
   const message: ParentToIframe = {
     // The specimen carries no tab identity, but the STAGE it is mounted into does: a stylebook is
     // Opened as a tab like anything else, and its `previewColorScheme` is that tab's.
+    /* A stylebook specimen is generated, not a project document, so it references no project
+       media and needs no resolution. */
+    assets: null,
     colorScheme: schemeWireFor(tabOfContainer(canvasEl)),
     doc: cloneableDoc,
     docBase: `${canvasBaseOrigin()}/`,

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-protocol.ts

@@ -9,6 +9,7 @@
  * the cross-frame analog of the legacy renderer's `renderGeneration` staleness guard.
  */
 
+import type { AssetContext } from "./asset-resolve";
 import type { JxDocOp } from "../tabs/patch-ops";
 import type { JxContentResult, SlashCommand } from "../editor/inline-edit";
 import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
@@ -88,6 +89,14 @@ export type ParentToIframe =
        */
       allowAutoRequests?: boolean;
       docBase: string;
+      /**
+       * How this host addresses project media, or null/absent when the canvas origin serves the
+       * site's own URL space (desktop, `jx dev`) and no reference needs resolving.
+       *
+       * Plain data because the resolver is a FUNCTION and functions do not cross a realm: the
+       * iframe rebuilds the resolver from this and installs it on the runtime.
+       */
+      assets?: AssetContext | null;
       mapperCtx: WireMapperCtx;
       siteStyle: Record<string, unknown> | null;
       // Forced color-scheme preview (spec §9.5): "light"/"dark" sets data-color-scheme on the

package/src/canvas/iframe-render.ts

@@ -13,19 +13,22 @@
 
 import {
   buildScope,
+  canvasStyleValue,
   defineElement,
   renderNode,
   runScoped,
+  setCanvasAssetResolver,
   setCanvasDelinkAnchors,
   setCanvasViewportTranspose,
   setRootMedia,
   setSkipAutoRequests,
   setSkipServerFunctions,
   setStampPropBindings,
-  transposeCanvasUnits,
 } from "@jxsuite/runtime";
+import { resolveAssetRef } from "./asset-resolve";
 import { classifyRenderNode, serializeJxPath } from "./path-mapping";
-import { SITE_STYLE_ID, buildSiteStyleCSS } from "./site-style-css";
+import type { AssetContext } from "./asset-resolve";
+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";
@@ -102,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 {
@@ -120,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;
@@ -146,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;
@@ -409,7 +428,9 @@ export function applySiteStyle(
     existing?.remove();
     return;
   }
-  const css = buildSiteStyleCSS(siteStyle, mediaQueries, transposeCanvasUnits);
+  /* `canvasStyleValue`, not `transposeCanvasUnits`: the site style block is CSS the canvas emits
+     itself, so a `url()` in it needs the same asset resolution every other declaration gets. */
+  const css = buildSiteStyleCSS(siteStyle, mediaQueries, canvasStyleValue);
   if (existing) {
     existing.textContent = css;
     return;
@@ -434,7 +455,7 @@ export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark"
 }
 
 /** Inject the document's `$head` (link/meta/script) into the iframe's <head>, de-duped by href/src. */
-export function injectHead(doc: JxDocument): void {
+export function injectHead(doc: JxDocument, assets: AssetContext | null = null): void {
   const head = (doc as { $head?: HeadEntry[] }).$head;
   if (!Array.isArray(head)) {
     return;
@@ -451,14 +472,16 @@ export function injectHead(doc: JxDocument): void {
     const attrs = { ...entry.attributes } as Record<string, unknown>;
     for (const key of ["href", "src"]) {
       const val = attrs[key];
-      if (
-        typeof val === "string" &&
-        !val.startsWith("/") &&
-        !val.startsWith(".") &&
-        !val.startsWith("http")
-      ) {
+      if (typeof val !== "string" || val === "") {
+        continue;
+      }
+      if (!val.startsWith("/") && !val.startsWith(".") && !val.startsWith("http")) {
+        /* The bare-specifier lane owns `/node_modules/<pkg>` — the HOST's URL space, not the
+           project's. A project resolver has nothing to resolve it to, so it never sees it. */
         attrs[key] = `/node_modules/${val}`;
+        continue;
       }
+      attrs[key] = resolveAssetRef(val, assets) ?? val;
     }
     const sel = `${tag}${attrs.href ? `[href="${String(attrs.href)}"]` : ""}${attrs.src ? `[src="${String(attrs.src)}"]` : ""}`;
     if (sel !== tag && document.head.querySelector(sel)) {
@@ -620,9 +643,20 @@ export async function renderResolvedDocument(opts: {
   mode: CanvasMode;
   mapperCtx: PathMapCtx;
   siteStyle?: Record<string, unknown> | null;
+  /**
+   * How this host addresses project media, or null when the canvas origin serves the site's own URL
+   * space (desktop, `jx dev`) and references need no resolution at all.
+   */
+  assets?: AssetContext | null;
   /** This render may fetch automatic `Request` entries even outside preview (Data-panel Refresh). */
   allowAutoRequests?: boolean;
 }): Promise<RenderHandle> {
+  /* FIRST, before anything emits CSS or an attribute. The resolver is module-global in the runtime,
+     so it is set on every render — including to null — or a previous document's context would
+     resolve this one's references. It cannot cross the realm as a function, which is why the parent
+     posts the plain-data context and the resolver is closed over it here. */
+  const assets = opts.assets ?? null;
+  setCanvasAssetResolver(assets ? (value) => resolveAssetRef(value, assets) : null);
   setSkipServerFunctions(opts.mode !== "preview");
   // Same gate for automatic `$prototype: "Request"` state entries. `buildScope` re-resolves every
   // State entry on each full render, so without this an escalating authoring action (a signals-panel
@@ -644,7 +678,7 @@ export async function renderResolvedDocument(opts: {
   // Component internals get stamped).
   setStampPropBindings(opts.mode === "design" || opts.mode === "edit");
   applySiteStyle(opts.siteStyle, (opts.doc as { $media?: Record<string, string> }).$media ?? {});
-  injectHead(opts.doc);
+  injectHead(opts.doc, assets);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);
   syncPreviewShell(opts.container.ownerDocument, opts.mode);
   syncStylebookCss(opts.container.ownerDocument, opts.mode);

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",