@jxsuite/studio 8.0.0 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -61,31 +61,31 @@
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^4.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^3.0.0",
-    "@jxsuite/ai": "^0.39.5",
+    "@jxsuite/ai": "^0.40.0",
     "@jxsuite/collab": "^0.11.2",
-    "@jxsuite/create": "^1.3.16",
-    "@jxsuite/formulas": "^0.0.22",
+    "@jxsuite/create": "^1.4.0",
+    "@jxsuite/formulas": "^0.0.24",
     "@jxsuite/markup": "^1.0.0",
     "@jxsuite/protocol": "^4.0.0",
-    "@jxsuite/runtime": "^5.0.0",
+    "@jxsuite/runtime": "^5.2.0",
     "@jxsuite/schema": "^4.0.0",
-    "@jxsuite/site": "^2.0.5",
-    "@jxsuite/ui": "^0.7.0",
+    "@jxsuite/site": "^2.2.0",
+    "@jxsuite/ui": "^0.8.0",
     "@vue/reactivity": "3.5.44",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.57.0",
-    "tabulator-tables": "^6.6.1",
+    "tabulator-tables": "^6.7.1",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^21.0.3",
+    "@happy-dom/global-registrator": "^21.0.4",
     "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4",
-    "@webref/css": "^8.7.7",
+    "@webref/css": "^8.7.8",
     "@webref/elements": "^2.9.2",
-    "@webref/idl": "^3.85.2"
+    "@webref/idl": "^3.86.0"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

package/src/browse/component-examples.ts

@@ -3,49 +3,25 @@
  *
  * A preview instance used to be given nothing, so it drew its definition's DEFAULTS, and a starter
  * component's defaults are empty strings: a page header with no title, a band with no label, a card
- * with no name. A component is only ever seen with props, so the preview asks where it has been
- * given some, in this order:
+ * with no name. The definition's own `examples` fill that gap: the JSON Schema keyword a typed
+ * state entry may carry (`spec.md` §5.3, Shape 2), whose first value is the author's own sample.
+ * Only a prop that is not private (`spec.md` §5.6), and whose sample is literal data, is taken.
  *
- * 1. The definition's own `examples`: the JSON Schema keyword a typed state entry may carry (`spec.md`
- *    §5.3, Shape 2), whose first value is the author's own sample.
- * 2. Its first use in the project that passes literal values: the reference index names the files that
- *    use the tag, and the instance among them that passes the most literal props is the likeliest
- *    to draw the component as the author meant it. A bound prop (`${…}`, `$ref`) has no value
- *    outside the page that binds it, so it is not one.
- * 3. A list that draws it ({@link componentSampleRow}): a component used only as a repeater's row,
- *    every prop bound to the row, is drawn as that list's first row, with the list's data.
- *
- * Only a prop the definition declares, and that is not private (`spec.md` §5.6), is taken. Files in
- * the project's default language are read before translations, so a preview reads in the language
- * the site is written in first.
+ * The preview never looks further than the definition. It once borrowed props from the component's
+ * first use in the project, and drew a component used only as a list row as that list's first row,
+ * both found through the reference index; that cost one project-wide usage query per component on
+ * every Library and Project Styles paint, which on a hosted project was enough requests at once to
+ * reset the session. A batched or on-demand source may bring it back.
  *
  * @docs studio/interface
  */
 
-import {
-  isJsonObject,
-  isNodeObject,
-  isPrivateStateKey,
-  isRef,
-  isString,
-} from "@jxsuite/schema/guards";
-import { localeOfPath, resolveI18n } from "@jxsuite/schema/locale";
-import { getPlatform } from "../platform";
-import { formatForPath, loadFormats } from "../format/format-host";
-import { parseSourceForPath } from "../files/file-ops";
-import { loadUsages } from "../services/references";
-import { documentBase } from "../canvas/canvas-origin";
-import { bakeRepeaterSources } from "../canvas/repeater-sources";
-import { pageContextFor } from "../canvas/canvas-page-context";
-import { projectState } from "../store";
-import type { JsonValue, JxDocument, JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
+import { isJsonObject, isPrivateStateKey, isString } from "@jxsuite/schema/guards";
+import type { JsonValue, JxDocument, JxDocumentValue } from "@jxsuite/schema/types";
 
 /** A component's sample props, by state key. */
 export type ExampleProps = Map<string, JsonValue>;
 
-/** How many of the files that use a component are read for an instance to draw it from. */
-const USAGE_FILES_READ = 4;
-
 /** Whether a value is plain data a prop can hold outside any page: no template, no binding. */
 export function isLiteralProp(value: JxDocumentValue | undefined): value is JsonValue {
   if (value === undefined) {
@@ -68,13 +44,11 @@ export function isLiteralProp(value: JxDocumentValue | undefined): value is Json
   return true;
 }
 
-/** The definition's public prop keys: its state entries, without the private ones. */
-function propKeys(definition: JxDocument): Set<string> {
-  return new Set(Object.keys(definition.state ?? {}).filter((key) => !isPrivateStateKey(key)));
-}
-
-/** The first `examples` value of each typed state entry that declares one. */
-export function declaredExamples(definition: JxDocument): ExampleProps {
+/**
+ * The props a component's preview instance is given: the first `examples` value of each public
+ * typed state entry that declares a literal one.
+ */
+export function componentExampleProps(definition: JxDocument): ExampleProps {
   const out: ExampleProps = new Map();
   for (const [key, entry] of Object.entries(definition.state ?? {})) {
     if (isPrivateStateKey(key) || !isJsonObject(entry) || !Array.isArray(entry.examples)) {
@@ -87,186 +61,3 @@ export function declaredExamples(definition: JxDocument): ExampleProps {
   }
   return out;
 }
-
-/** Every node of a tree, each with the repeater (if any) whose row template holds it. */
-function eachNode(
-  tree: JxDocumentValue | undefined,
-  visit: (node: JxMutableNode, repeater: JxMutableNode | null) => void,
-): void {
-  const walk = (value: JxDocumentValue | undefined, repeater: JxMutableNode | null): void => {
-    if (Array.isArray(value)) {
-      for (const member of value) {
-        walk(member, repeater);
-      }
-      return;
-    }
-    if (!isNodeObject(value)) {
-      return;
-    }
-    visit(value, repeater);
-    walk(value.children, repeater);
-    walk(value.map, value.$prototype === "Array" ? value : repeater);
-    for (const branch of Object.values(value.cases ?? {})) {
-      walk(branch, repeater);
-    }
-  };
-  walk(tree, null);
-}
-
-/**
- * The literal props of the instance of `tagName` in `tree` that passes the most of them, among the
- * keys the definition declares; empty when no instance passes any.
- */
-export function literalUsageProps(
-  tree: JxDocumentValue | undefined,
-  tagName: string,
-  keys: ReadonlySet<string>,
-): ExampleProps {
-  let best: ExampleProps = new Map();
-  eachNode(tree, (node) => {
-    if (node.tagName !== tagName || !isJsonObject(node.$props)) {
-      return;
-    }
-    const found: ExampleProps = new Map();
-    for (const [key, prop] of Object.entries(node.$props)) {
-      if (keys.has(key) && isLiteralProp(prop)) {
-        found.set(key, prop);
-      }
-    }
-    if (found.size > best.size) {
-      best = found;
-    }
-  });
-  return best;
-}
-
-/** One project document as a tree, or null when it cannot be read or parsed. */
-async function readTree(path: string): Promise<JxMutableNode | null> {
-  try {
-    const content = await getPlatform().readFile(path);
-    await loadFormats();
-    let tree: JxDocumentValue;
-    if (formatForPath(path)) {
-      const parsed = await parseSourceForPath(path, content);
-      tree = parsed.document;
-    } else if (path.endsWith(".json")) {
-      /* SAFETY: a `.json` project document is JSON, and every read of it below is guarded. */
-      tree = JSON.parse(content) as JxDocumentValue;
-    } else {
-      return null;
-    }
-    return isNodeObject(tree) ? tree : null;
-  } catch {
-    return null;
-  }
-}
-
-/** The files that use a component, default language first, at most {@link USAGE_FILES_READ}. */
-async function usageFiles(path: string, tagName: string): Promise<string[]> {
-  const usages = await loadUsages({ path, tagName });
-  if (usages.status !== "ready") {
-    return [];
-  }
-  const { i18n } = resolveI18n(projectState?.projectConfig ?? {});
-  const translated = (file: string): boolean => {
-    const locale = localeOfPath(file, i18n);
-    return locale !== null && locale !== i18n?.defaultLocale;
-  };
-  const files = usages.result.files.map((file) => file.path);
-  return [
-    ...files.filter((file) => !translated(file)),
-    ...files.filter((file) => translated(file)),
-  ].slice(0, USAGE_FILES_READ);
-}
-
-/** The props a component's preview instance is given (sources 1 and 2 of the module comment). */
-export async function componentExampleProps(
-  definition: JxDocument,
-  path: string,
-): Promise<ExampleProps> {
-  const keys = propKeys(definition);
-  const tagName = isString(definition.tagName) ? definition.tagName : null;
-  const examples = declaredExamples(definition);
-  if (!tagName || keys.size === 0) {
-    return examples;
-  }
-  let best: ExampleProps = new Map();
-  for (const file of await usageFiles(path, tagName)) {
-    const found = literalUsageProps(await readTree(file), tagName, keys);
-    if (found.size > best.size) {
-      best = found;
-    }
-  }
-  // The author's own sample wins over a page's value for the same prop.
-  return new Map([...best, ...examples]);
-}
-
-/** A sample-row document, and the file whose list it draws (its relative refs resolve there). */
-export interface SampleRow {
-  doc: JxDocument;
-  file: string;
-}
-
-/** The state key a repeater reads its whole list from (`#/state/shows`), or null. */
-function listKeyOf(repeater: JxMutableNode): string | null {
-  const { items } = repeater;
-  if (!isRef(items) || !items.$ref.startsWith("#/state/")) {
-    return null;
-  }
-  const key = items.$ref.slice("#/state/".length);
-  return key !== "" && !key.includes("/") ? key : null;
-}
-
-/**
- * A document that draws the first row of a list using the component (source 3 of the module
- * comment), or null when no file that uses it has one: the list's repeater, its data resolved the
- * way the canvas resolves it for Edit (`canvas/repeater-sources.ts`) and cut to its first item, in
- * the page's own state and `$site` / `$page`.
- */
-export async function componentSampleRow(
-  definition: JxDocument,
-  path: string,
-): Promise<SampleRow | null> {
-  const tagName = isString(definition.tagName) ? definition.tagName : null;
-  if (!tagName) {
-    return null;
-  }
-  for (const file of await usageFiles(path, tagName)) {
-    const tree = await readTree(file);
-    const lists: JxMutableNode[] = [];
-    eachNode(tree, (node, repeater) => {
-      if (node.tagName === tagName && repeater && listKeyOf(repeater)) {
-        lists.push(repeater);
-      }
-    });
-    const [list] = lists;
-    const key = list ? listKeyOf(list) : null;
-    if (!tree || !list || !key) {
-      continue;
-    }
-    const baked = await bakeRepeaterSources(
-      tree,
-      [key],
-      new URL(file, documentBase(projectState?.projectRoot)).href,
-    );
-    const rows = baked.state?.[key];
-    if (!Array.isArray(rows) || rows.length === 0) {
-      continue;
-    }
-    const context = file.startsWith("pages/")
-      ? await pageContextFor(
-          { documentPath: file, isEntry: false, lang: tree.$lang, title: tree.title },
-          projectState?.projectConfig,
-        )
-      : null;
-    return {
-      doc: {
-        children: [list],
-        state: { ...baked.state, [key]: rows.slice(0, 1), ...context },
-        tagName: "div",
-      },
-      file,
-    };
-  }
-  return null;
-}

package/src/browse/library-preview.ts

@@ -39,8 +39,8 @@ import { componentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
 import { loadFormats, formatForPath } from "../format/format-host";
 import { parseSourceForPath } from "../files/file-ops";
-import { defineComponent, renderComponentPreview } from "../panels/component-preview";
-import { componentExampleProps, componentSampleRow } from "./component-examples";
+import { renderComponentPreview } from "../panels/component-preview";
+import { componentExampleProps } from "./component-examples";
 import { loadProjectPreviewSheets } from "./preview-style";
 import type { ComponentEntry } from "../files/components";
 import type { JsonValue, JxDocument } from "@jxsuite/schema/types";
@@ -170,7 +170,7 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
 async function renderDocument(
   document_: JxDocument,
   filePath: string,
-  context = assetContextFor(filePath, hostAssetDeclarations()),
+  context: ReturnType<typeof assetContextFor>,
 ): Promise<HTMLElement | null> {
   setSkipServerFunctions(true);
   /* The document's own URL, as the canvas spells it, and the canvas's dev-proxy token. With the
@@ -195,8 +195,8 @@ async function renderDocument(
 }
 
 /**
- * A project component's preview: an instance given its sample props when it renders with them, else
- * the first row of a list that draws it (`component-examples.ts`), else none.
+ * A project component's preview: an instance given its declared sample props
+ * (`component-examples.ts`), or none when the definition does not render with them.
  */
 async function projectComponentPreview(
   component: ComponentEntry,
@@ -206,14 +206,7 @@ async function projectComponentPreview(
   if (!definition) {
     return null;
   }
-  const props = await componentExampleProps(definition, path);
-  if (props.size > 0 && (await rendersWith(definition, path, props))) {
-    return renderComponentPreview(component, props);
-  }
-  const sample = await componentSampleRow(definition, path);
-  if (sample && (await defineComponent(component))) {
-    return renderDocument(sample.doc, sample.file);
-  }
+  const props = componentExampleProps(definition);
   return (await rendersWith(definition, path, props))
     ? renderComponentPreview(component, props)
     : null;

package/src/browse/preview-root.ts

@@ -14,10 +14,13 @@ import { isFunction } from "@jxsuite/schema/guards";
 import { projectPreviewSheets } from "./preview-style";
 
 /**
- * The one rule a preview needs that its box cannot give it from outside: an image whose prop
- * defaults to nothing draws a broken-image icon and its alt text, which in a thumbnail is noise,
- * not the component. Everything else about the box (its size, its scale, its light surface) is the
- * surface document's, on the island itself.
+ * The one rule a preview needs that its box cannot give it from outside: an image with no source
+ * draws a broken-image icon and its alt text, which in a thumbnail is noise. A COMPONENT preview
+ * never reaches it — `renderComponentPreview` fills such an image with the preview placeholder
+ * (`canvas/preview-placeholder.ts`), whose `data:` source this selector does not match — so it
+ * hides the empty images of DOCUMENT previews (the Content home's cards), which draw what the page
+ * wrote. Everything else about the box (its size, its scale, its light surface) is the surface
+ * document's, on the island itself.
  */
 const PREVIEW_RULES = 'img:not([src]), img[src=""] { visibility: hidden; }';
 

package/src/canvas/canvas-utils.ts

@@ -925,6 +925,17 @@ export const CANVAS_MODES = [
 
 export type CanvasMode = (typeof CANVAS_MODES)[number];
 
+/**
+ * The modes a person, the assistant or a script may ASK for by name: every mode but `git-diff`.
+ *
+ * Diff is implicit (studio.md §3): a comparison is entered by choosing a changed file or a version
+ * in Publish, which says what it is compared against, and left by Back. Named here it would be a
+ * comparison of whatever file happened to be open against whatever HEAD happened to be, which is
+ * not a thing anyone asked to see. The mode stays in {@link CANVAS_MODES} because the stage draws
+ * it; the Source Control panel enters it through `setCanvasMode` directly.
+ */
+export const SELECTABLE_CANVAS_MODES = CANVAS_MODES.filter((mode) => mode !== "git-diff");
+
 /** The base modes the preview flag composes with — the two the Canvas view axis shows it beside. */
 const PREVIEWABLE_BASE_MODES = new Set(["edit", "design"]);
 
@@ -1166,7 +1177,10 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
   return [
     {
       args: argsSchema({
-        mode: enumProperty(CANVAS_MODES, "The canvas mode to switch the active pane to."),
+        mode: enumProperty(
+          SELECTABLE_CANVAS_MODES,
+          "The canvas mode to switch the active pane to.",
+        ),
       }),
       category: "View",
       id: "canvas.setMode",
@@ -1189,7 +1203,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
         description:
           "Switch the active document's editor mode. edit and design put its element tree on " +
           "the canvas, where the document tools work; preview renders it as a visitor sees it; " +
-          "source shows the JSON; stylebook, tokens, grid and git-diff open other editors. Use it to " +
+          "source shows the JSON; stylebook, tokens and grid open other editors. Use it to " +
           "return a document to edit or design when the tree tools are refused.",
         name: "set_canvas_mode",
         /* `after.editor.kind` rather than the tab's own field: it is the gate's read (`treeEditable`
@@ -1197,7 +1211,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
            cannot disagree. The mode named is the one requested — `run` resolved, so it is the mode
            the tab is in. */
         report: ({ after, args }) => {
-          const mode = enumArg("canvas.setMode", args, "mode", CANVAS_MODES);
+          const mode = enumArg("canvas.setMode", args, "mode", SELECTABLE_CANVAS_MODES);
           const reach =
             after.editor.kind === "canvas"
               ? "the document tools address its element tree"
@@ -1206,7 +1220,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
         },
       },
       run: (_commandCtx, args) => {
-        const mode = enumArg("canvas.setMode", args, "mode", CANVAS_MODES);
+        const mode = enumArg("canvas.setMode", args, "mode", SELECTABLE_CANVAS_MODES);
         const tab = requireTab("canvas.setMode");
         const { modes } = tab.capabilities;
         if (!modes.includes(mode)) {

package/src/canvas/iframe-editable-root.ts

@@ -439,14 +439,20 @@ export function startEditableRoot(
    * cannot put a caret in them. Capture-phase pointerdown gives the bridge a chance to open a
    * nested editing host BEFORE the browser computes the caret, so the click still lands where it
    * was aimed.
+   *
+   * Any other press inside uneditable content (a component's own internals, frozen layout chrome)
+   * drops the selection. The browser leaves the selection where it was when the press lands on
+   * something no caret can enter, so the caret went on blinking in the block clicked BEFORE, with
+   * the component now selected in the editor and every keystroke still typed into that block.
    */
   const onPointerDownCapture = (e: Event) => {
-    if (!editingAllowed() || !deps.onPropActivate) {
+    if (!editingAllowed()) {
       return;
     }
-    let el = e.target instanceof Element ? e.target : null;
+    const target = e.target instanceof Element ? e.target : null;
+    let el = deps.onPropActivate ? target : null;
     while (el && el !== container) {
-      if (hasDataset(el) && el.dataset.jxBoundProp) {
+      if (hasDataset(el) && el.dataset.jxBoundProp && deps.onPropActivate) {
         /* SAFETY: The runtime builds SVG and MathML nodes as `createElementNS(...) as HTMLElement`
            and stamps `data-jx-bound-prop` through that same `HTMLElement`-typed path, so a
            foreign-namespace prop host already travels downstream as an `HTMLElement`. */
@@ -463,10 +469,13 @@ export function startEditableRoot(
       }
       // A stamped page block first means this is ordinary page DOM, not component internals.
       if (hasDataset(el) && el.dataset.jxPath) {
-        return;
+        break;
       }
       el = el.parentElement;
     }
+    if (target?.closest("[contenteditable]")?.getAttribute("contenteditable") === "false") {
+      doc.getSelection()?.removeAllRanges();
+    }
   };
 
   /**

package/src/canvas/iframe-entry.ts

@@ -16,6 +16,7 @@ import {
   captureLocaleBaseline,
   applySiteStyle,
   installCanvasImageRetry,
+  isRetryableImage,
   renderResolvedDocument,
 } from "./iframe-render";
 import { measureHits, startInteraction } from "./iframe-interaction";
@@ -613,7 +614,8 @@ export function startCanvasIframe(opts: {
   }
 
   const onImageError = (event: Event): void => {
-    if (event.target instanceof HTMLImageElement) {
+    // Only a failure `installCanvasImageRetry` will retry is pending; an empty source settles broken.
+    if (event.target instanceof HTMLImageElement && isRetryableImage(event.target)) {
       retryingImages.set(event.target, Date.now() + IMAGE_RETRY_WINDOW_MS);
       armIdleWatch();
     }

package/src/canvas/iframe-interaction.ts

@@ -8,7 +8,7 @@
 
 import { jxPathSelector, parseJxPath, serializeJxPath } from "./path-mapping";
 import { isFunction } from "@jxsuite/schema/guards";
-import { rectOf } from "../utils/geometry";
+import { isDisplayContents, rectOf } from "../utils/geometry";
 import { computeInsertZones, insertZonesKey } from "./iframe-insert";
 import { getActiveElement, isEditing } from "../editor/inline-edit";
 import type { IframeChannel } from "./iframe-channel";
@@ -76,11 +76,20 @@ export function nearestHit(target: EventTarget | null): NodeHit | null {
  *
  * An engine without `checkVisibility` gets the benefit of the doubt. Withholding a selection box
  * from a node that is on screen is a worse failure than drawing one for a node that is not.
+ *
+ * `checkVisibility` also answers false for an element with no box of its own, and a `display:
+ * contents` element never has one. A component host styled that way (its rendered root does the
+ * layout) is on screen whenever anything inside it is, so its children are asked instead. Without
+ * this, selecting such a component drew no selection box and no action bar, because every one of
+ * them was reported hidden.
  */
 function isRendered(el: Element): boolean {
   // Absent on engines that predate it, whatever lib.dom says.
   const check: Element["checkVisibility"] | undefined = el.checkVisibility;
-  return isFunction(check) ? check.call(el, { checkVisibilityCSS: true }) : true;
+  if (!isFunction(check) || check.call(el, { checkVisibilityCSS: true })) {
+    return true;
+  }
+  return isDisplayContents(el) && [...el.children].some((child) => isRendered(child));
 }
 
 /**

package/src/canvas/iframe-render.ts

@@ -30,6 +30,7 @@ import {
   setStampPropBindings,
 } from "@jxsuite/runtime";
 import { resolveAssetRef } from "./asset-resolve";
+import { fillPreviewImages } from "./preview-placeholder";
 import { classifyRenderNode, jxPathSelector, serializeJxPath } from "./path-mapping";
 /* No cycle: `iframe-position.ts` imports only `path-mapping` and a type. It already owns the
    stamped-attribute lookup, escaping included, so a second query built here would be a second
@@ -994,6 +995,20 @@ export function makeStamper(ctx: PathMapCtx) {
  * so they're untouched. Returns a teardown that removes the listener. <img> error events don't
  * bubble, so listen in CAPTURE.
  */
+/**
+ * Whether a failed `<img>` is one a retry could ever fix.
+ *
+ * Read from the AUTHORED attribute, not `img.src`: the property is the RESOLVED url, and an empty
+ * `src=""` resolves to the document's own url, so a check on the property never saw the empty
+ * source it meant to skip. The frame then re-requested `canvas.html` as an image three times, and
+ * its quiescence report counted each failure as a pending retry, holding Studio's idle probe open
+ * for a component drawn without its image prop. A data: URL never errors transiently either.
+ */
+export function isRetryableImage(img: HTMLImageElement): boolean {
+  const raw = img.getAttribute("src")?.trim() ?? "";
+  return raw !== "" && !raw.startsWith("data:");
+}
+
 export function installCanvasImageRetry(root: HTMLElement, maxAttempts = 3): () => void {
   const attempts = new WeakMap<HTMLImageElement, number>();
   const onError = (event: Event): void => {
@@ -1001,8 +1016,8 @@ export function installCanvasImageRetry(root: HTMLElement, maxAttempts = 3): ()
     if (!(img instanceof HTMLImageElement)) {
       return;
     }
-    // A data: URL never errors (and an empty src isn't a real request) — nothing to retry.
-    if (!img.src || img.src.startsWith("data:")) {
+    // An empty or data: source is not a request a retry could fix.
+    if (!isRetryableImage(img)) {
       return;
     }
     const attempt = (attempts.get(img) ?? 0) + 1;
@@ -1127,8 +1142,15 @@ export async function renderResolvedDocument(opts: {
   // Marks last, and for the same reason: they are resolved by querying stamped attributes, which
   // Only exist once the tree the stamper walked is actually in the container.
   applyDiffMarks(opts.container, opts.diffMarks ?? null);
+  /* Stylebook specimens are component previews: an image a specimen has no source for draws as a
+     placeholder (`preview-placeholder.ts`). Never in a page's canvas, where an empty image is
+     something its author should see. */
+  const stopPlaceholders = opts.mode === "stylebook" ? fillPreviewImages(opts.container) : null;
   return {
     ctx: { defs: $defs, docBase: opts.docBase, mapperCtx: opts.mapperCtx, mode: opts.mode },
-    dispose: stop,
+    dispose: () => {
+      stopPlaceholders?.();
+      stop();
+    },
   };
 }