@jxsuite/studio 6.1.2 → 8.0.0

package/src/browse/preview-root.ts

@@ -0,0 +1,78 @@
+/// <reference lib="dom" />
+/**
+ * A live preview's root: the shadow root an island shows a rendered document or component in (the
+ * Site panel's component cards and the Content home's cards, `specs/studio.md` §5.7 and §9.1.2).
+ *
+ * A module of its own, apart from `library-preview.ts`, because what a preview IS (the render, the
+ * cache, the visibility gate) and where it is SHOWN are separate questions, and the second is plain
+ * DOM that every surface hosting a preview answers the same way.
+ *
+ * @docs studio/interface
+ */
+
+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.
+ */
+const PREVIEW_RULES = 'img:not([src]), img[src=""] { visibility: hidden; }';
+
+const _previewSheets = new WeakMap<Document, CSSStyleSheet>();
+
+/** The preview rules as a sheet of `doc`'s own (a constructed sheet is adoptable only there). */
+function previewSheetFor(doc: Document): CSSStyleSheet | null {
+  const known = _previewSheets.get(doc);
+  if (known) {
+    return known;
+  }
+  const Sheet = doc.defaultView?.CSSStyleSheet;
+  if (!isFunction(Sheet)) {
+    return null;
+  }
+  const sheet = new Sheet();
+  sheet.replaceSync(PREVIEW_RULES);
+  _previewSheets.set(doc, sheet);
+  return sheet;
+}
+
+/**
+ * Show a rendered preview in its island, inside a shadow root of the island's own.
+ *
+ * **A preview is a page's part, rendered in Studio's window, and the shadow root is what keeps it a
+ * guest there.** It used to be appended straight into the island, so a component's own ids joined
+ * Studio's: Elite Equipment Rental's `<h2 id="equipment">` was the document's `#equipment`, an
+ * `aria-labelledby` or a fragment link anywhere in the chrome could resolve to a thumbnail, and two
+ * cards of one component made the id a duplicate. Ids, `getElementById` and Studio's linked
+ * stylesheets all stop at the root's boundary; inherited properties (the island's text colour and
+ * size) still cross it, which is what the light document surface relies on.
+ *
+ * The runtime's rules are not lost: the Jx runtime writes every element's style into sheets it
+ * adopts on the document (`openSink` in `@jxsuite/runtime`), keyed on each element's `data-jx`
+ * hash, and those sheets are adopted into the root too, so a component draws as it did. They are
+ * read at each fill, so a sheet the runtime opened since the last one is included.
+ *
+ * @param slot The island the surface document drew empty.
+ * @param rendered The preview, from `previewFor` (`library-preview.ts`).
+ */
+export function mountPreview(slot: HTMLElement, rendered: HTMLElement): void {
+  const root = slot.shadowRoot ?? slot.attachShadow({ mode: "open" });
+  const own = previewSheetFor(slot.ownerDocument);
+  /* The project's sheets first, the runtime's after them: on the page, the site's stylesheet is
+     in the document and the runtime's rules are adopted after it, so a component's own rule wins
+     over a site rule of equal specificity there, and must here. */
+  root.adoptedStyleSheets = [
+    ...projectPreviewSheets(),
+    ...slot.ownerDocument.adoptedStyleSheets,
+    ...(own ? [own] : []),
+  ];
+  root.replaceChildren(rendered);
+}
+
+/** The preview an island is showing, or null while it shows none. */
+export function shownPreview(slot: Element): Element | null {
+  return slot.shadowRoot?.firstElementChild ?? null;
+}

package/src/browse/preview-style.ts

@@ -0,0 +1,155 @@
+/// <reference lib="dom" />
+/**
+ * The project's stylesheet, as a live preview's root adopts it.
+ *
+ * A component card or a page card in the Site panel and the Content home draws a part of a page in
+ * Studio's own window, inside a shadow root of its box (`preview-root.ts`). It drew that part with
+ * the runtime's rules alone: none of the site's tokens, typography or linked stylesheets, which is
+ * where most of a component's look lives, so a museum card or a site header drew as an empty white
+ * box. A page draws with two things this module supplies: `project.json`'s `style`, emitted by the
+ * builder the canvas and the build share (`@jxsuite/site/site-style`), and the stylesheets the
+ * project's `$head` links.
+ *
+ * Both address the page's `:root` and `body`, which a shadow root does not have: inside it the box
+ * the preview is drawn in is `:host`. The project block is emitted with `:host` as its root and
+ * body, and a linked sheet's own `:root`, `html` and `body` selectors are re-pointed at `:host`
+ * through the CSSOM, rule by rule, so a site's custom properties and body typography reach the
+ * preview the way they reach the page. A web font is the one thing that does not: `@font-face` is
+ * not honoured inside a shadow root, so a preview draws in the fallback face.
+ *
+ * Built once per project configuration and shared by every preview of it.
+ *
+ * @docs studio/interface
+ */
+
+import { buildSiteStyleCSS } from "@jxsuite/site/site-style";
+import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { previewAssetSrcFor } from "../canvas/asset-refs";
+import { projectState } from "../store";
+import type { JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+
+/** The preview box, as a project sheet names the page's root and body inside a shadow root. */
+const HOST_ROOTS = { body: ":host", root: ":host" };
+
+/** Every sheet built for a configuration, settled or in flight. */
+const _sheets = new WeakMap<ProjectConfig, Promise<CSSStyleSheet[]>>();
+/** The settled answers, for the synchronous mount. */
+const _settled = new WeakMap<ProjectConfig, CSSStyleSheet[]>();
+
+/** A selector of the page's root or body re-pointed at the preview box; `null` when unchanged. */
+export function hostSelector(selector: string): string | null {
+  const rewritten = selector
+    .replaceAll(/:root\b/g, ":host")
+    .replaceAll(/(^|[\s,>+~(])(?:html|body)(?![\w-])/g, "$1:host")
+    .replaceAll(/:host(?:\s*>?\s*:host)+/g, ":host");
+  return rewritten === selector ? null : rewritten;
+}
+
+/** What holds rules: a sheet, or a grouping rule (`@media`, `@supports`, a nesting style rule). */
+type RuleContainer = CSSStyleSheet | CSSGroupingRule;
+
+/**
+ * Re-point every style rule under `container` (at any depth of grouping or nesting) at the box.
+ *
+ * A rule is REPLACED by its own text under the new selector rather than assigned a new
+ * `selectorText`: the assignment is settable in browsers but not in every CSSOM, and replacing it
+ * keeps its declarations, its nested rules and its place in source order either way. A rewritten
+ * selector the engine cannot parse keeps the rule as it was.
+ */
+function rehostRules(container: RuleContainer): void {
+  for (let index = 0; index < container.cssRules.length; index += 1) {
+    const rule = container.cssRules[index];
+    const rewritten = rule instanceof CSSStyleRule ? hostSelector(rule.selectorText) : null;
+    if (rule instanceof CSSStyleRule && rewritten !== null) {
+      const text = `${rewritten}${rule.cssText.slice(rule.cssText.indexOf("{"))}`;
+      try {
+        container.insertRule(text, index);
+        container.deleteRule(index + 1);
+      } catch {
+        // Unparseable under the new selector: the original stays.
+      }
+    }
+    const current = container.cssRules[index];
+    if (current instanceof CSSGroupingRule) {
+      rehostRules(current);
+    }
+  }
+}
+
+/** The stylesheet `href`s the project's `$head` links, in order. */
+export function headStylesheetHrefs(head: readonly JxHeadEntry[] | undefined): string[] {
+  const hrefs: string[] = [];
+  for (const entry of head ?? []) {
+    if (!isNonNullObject(entry) || String(entry.tagName).toLowerCase() !== "link") {
+      continue;
+    }
+    const { href, rel } = entry.attributes ?? {};
+    if (isString(href) && href !== "" && isString(rel) && rel.split(/\s+/).includes("stylesheet")) {
+      hrefs.push(href);
+    }
+  }
+  return hrefs;
+}
+
+/** One linked stylesheet as a preview sheet, or null when it cannot be read. */
+async function linkedSheet(href: string): Promise<CSSStyleSheet | null> {
+  const url = previewAssetSrcFor(href, "project.json");
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      return null;
+    }
+    const absolute = new URL(url, location.href).href;
+    // Its own URL as the base, so the sheet's relative `url()` references resolve as they do on the
+    // Page and not against Studio's address.
+    const sheet = new CSSStyleSheet({ baseURL: absolute });
+    sheet.replaceSync(await response.text());
+    rehostRules(sheet);
+    return sheet;
+  } catch {
+    return null;
+  }
+}
+
+/** Build every sheet for one configuration: the linked sheets in `$head` order, then the block. */
+async function buildSheets(config: ProjectConfig): Promise<CSSStyleSheet[]> {
+  const linked = await Promise.all(
+    headStylesheetHrefs(config.$head).map((href) => linkedSheet(href)),
+  );
+  const sheets = linked.filter((sheet): sheet is CSSStyleSheet => sheet !== null);
+  const { style } = config;
+  if (isNonNullObject(style)) {
+    const block = new CSSStyleSheet();
+    block.replaceSync(
+      buildSiteStyleCSS(style, config.$media ?? {}, (value) => value, undefined, HOST_ROOTS),
+    );
+    sheets.push(block);
+  }
+  return sheets;
+}
+
+/**
+ * Read the open project's preview sheets, building them on first ask. A preview awaits this before
+ * it is shown, so {@link projectPreviewSheets} has the answer by the time a box is filled.
+ */
+export function loadProjectPreviewSheets(): Promise<CSSStyleSheet[]> {
+  const config = projectState?.projectConfig;
+  if (!config || !isFunction(globalThis.CSSStyleSheet)) {
+    return Promise.resolve([]);
+  }
+  let pending = _sheets.get(config);
+  if (!pending) {
+    pending = buildSheets(config).then((sheets) => {
+      _settled.set(config, sheets);
+      return sheets;
+    });
+    _sheets.set(config, pending);
+  }
+  return pending;
+}
+
+/** The open project's preview sheets as far as they are built: none until the first read lands. */
+export function projectPreviewSheets(): readonly CSSStyleSheet[] {
+  const config = projectState?.projectConfig;
+  return (config && _settled.get(config)) ?? [];
+}

package/src/canvas/asset-refs.ts

@@ -97,10 +97,25 @@ export function assetContextFor(
  * @returns {string} A src the parent realm can load
  */
 export function previewAssetSrc(value: string): string {
+  return previewAssetSrcFor(value, activeTab.value?.documentPath);
+}
+
+/**
+ * {@link previewAssetSrc} for a value authored in a NAMED document rather than the focused one.
+ *
+ * A project-level surface (Project Settings › Overview previewing the `$head` favicon of
+ * `project.json`) is about the project whatever tab is in front, so it names its document instead
+ * of asking which one has the focus.
+ *
+ * @param {string} value - The reference as the author wrote it
+ * @param {string | null | undefined} documentPath - Project-relative path of the authoring document
+ * @returns {string} A src the parent realm can load
+ */
+export function previewAssetSrcFor(value: string, documentPath: string | null | undefined): string {
   if (!value) {
     return value;
   }
-  const ctx = assetContextFor(activeTab.value?.documentPath, hostAssetDeclarations());
+  const ctx = assetContextFor(documentPath, hostAssetDeclarations());
   const versioned = ctx && { ...ctx, versions: assetVersionsSnapshot() };
   return loopbackAssetSrc(resolveAssetRef(value, versioned) ?? value);
 }

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

@@ -7,13 +7,20 @@
  */
 
 import { projectState, stripEventHandlers } from "../store";
-import { displayTagName, isMappedArray, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import {
+  displayTagName,
+  isJsonObject,
+  isMappedArray,
+  isNonNullObject,
+  isString,
+} from "@jxsuite/schema/guards";
 import { canvasModeOfTab } from "./canvas-surface";
 import { toRaw } from "../reactivity";
 import {
   distributePageIntoLayout,
   getEffectiveElements,
   getEffectiveHead,
+  extensionClassPaths,
   getEffectiveImports,
   getEffectiveLayoutPath,
   getEffectiveMedia,
@@ -21,6 +28,9 @@ import {
 } from "../site-context";
 import { documentBase } from "./canvas-origin";
 import { componentRegistry, computeRelativePath } from "../files/components";
+import { collectUsedTags } from "@jxsuite/schema/component-meta";
+import { injectContext } from "@jxsuite/site/context";
+import { documentUrlPattern } from "@jxsuite/site/routes";
 import { prepareForEditMode } from "../utils/edit-display";
 import {
   paramBoundStateKeys,
@@ -29,9 +39,22 @@ import {
 } from "../page-params";
 import { isComponentDoc, substitutePreviewProps } from "../component-props";
 import { assetContextFor, hostAssetDeclarations } from "./asset-refs";
+import { collectionForFile } from "../content/collection-match";
+import { writesEntryOnCanvas } from "../content/content-collections";
+import { collectionPage, entryLayoutPath, entryLocale } from "../content/collection-pages";
+import { pageContextFor } from "./canvas-page-context";
+import { loadExtensions } from "../format/format-host";
+import { bakeRepeaterSources, extensionClassKeys, repeaterSourceKeys } from "./repeater-sources";
 
 import type { AssetContext } from "./asset-refs";
-import type { JxElement, JxMutableNode, JxPath, JxStyle } from "@jxsuite/schema/types";
+import type {
+  JsonValue,
+  JxDocument,
+  JxElement,
+  JxMutableNode,
+  JxPath,
+  JxStyle,
+} from "@jxsuite/schema/types";
 import type { ComponentEntry } from "../files/components.js";
 import type { LayoutMarker } from "./path-mapping";
 import type { Tab } from "../tabs/tab";
@@ -112,6 +135,115 @@ export function markLayoutNodes(node: JxMutableNode, file: string, path: JxPath
   }
 }
 
+/**
+ * A layout as the canvas wraps a document in it: read, its nodes marked with the file they come
+ * from, and itself wrapped in the layout ITS `$layout` names, all the way up.
+ *
+ * A layout can sit in another layout (`layouts/post.json` → `layouts/base.json`), and the build
+ * resolves the whole chain (`@jxsuite/site` `resolveLayout`), so a page drawn in the inner layout
+ * alone lost the outer one's nav and footer on the canvas and nowhere else. Each level is merged
+ * the way the build merges it, and each node keeps the marker of the file it was authored in, so
+ * opening a locked node still opens the layout that holds it. A cycle stops at the first repeat
+ * rather than recursing forever, and a parent that cannot be read leaves the chain where it is.
+ *
+ * @param {string} layoutPath - The `$layout` reference, project-relative as authored
+ * @param {Set<string>} [seen] - Files already on the chain
+ * @returns {Promise<JxMutableNode | null>} The merged, marked layout, or null when unreadable
+ */
+export async function resolveCanvasLayout(
+  layoutPath: string,
+  seen = new Set<string>(),
+): Promise<JxMutableNode | null> {
+  const file = layoutPath.replace(/^\.\//, "");
+  if (seen.has(file)) {
+    return null;
+  }
+  seen.add(file);
+  const layoutDoc = await resolveLayoutDoc(layoutPath);
+  if (!layoutDoc) {
+    return null;
+  }
+  // The SAME normalization resolveLayoutDoc reads the file with, so the marker's `file` is a path
+  // The editor can hand straight to navigateToComponent when the author asks to open it.
+  markLayoutNodes(layoutDoc, file);
+  const parentRef = layoutDoc.$layout;
+  if (!isString(parentRef) || !parentRef) {
+    return layoutDoc;
+  }
+  const parent = await resolveCanvasLayout(parentRef, seen);
+  if (!parent) {
+    return layoutDoc;
+  }
+  const merged = distributePageIntoLayout(parent, layoutDoc);
+  delete merged.$layout;
+  return merged;
+}
+
+/**
+ * Re-address a layout's `$elements` imports from the layout's file to the document being drawn.
+ *
+ * A layout's `{ $ref: "../components/site-nav.json" }` is relative to the LAYOUT, but once the
+ * layout is merged around a document the canvas resolves every `$ref` against the document's own
+ * base. A page in `pages/` sits as deep as `layouts/`, so the two answers agreed by coincidence; an
+ * entry in `content/menu/` or a page in `pages/blog/` resolved the same ref to
+ * `content/components/…`, which 404s and leaves the nav and footer unregistered. Each entry is
+ * re-addressed from the file its `$__layout` marker names, which is the file it was authored in at
+ * every level of a layout chain. Bare specifiers and URLs are left alone, and so is an entry with
+ * no marker (the document's own).
+ *
+ * @param {(JxElement | string)[] | undefined} elements - The merged document's `$elements`
+ * @param {string} documentPath - The project-relative path of the document being drawn
+ */
+export function rebaseLayoutElementRefs(
+  elements: readonly (JxElement | string | null)[] | undefined,
+  documentPath: string,
+) {
+  for (const el of elements ?? []) {
+    if (!isNonNullObject(el) || !isString(el.$ref) || !/^\.\.?\//.test(el.$ref)) {
+      continue;
+    }
+    const marker = el["$__layout"];
+    if (!isJsonObject(marker) || !isString(marker.file)) {
+      continue;
+    }
+    const target = new URL(el.$ref, `jx-project:/${marker.file}`).pathname.replace(/^\//, "");
+    el.$ref = computeRelativePath(documentPath, target);
+  }
+}
+
+/**
+ * A document's own layout override: its root's `$layout`, or a Markdown document's frontmatter
+ * `$layout` (which the build reads, and which the Inspector's Page tab writes); `undefined` when it
+ * names none.
+ */
+export function pageLayout(doc: JxMutableNode, tab: Tab | null): string | false | undefined {
+  if (doc.$layout !== undefined) {
+    return doc.$layout;
+  }
+  const fromFrontmatter = tab?.doc.content.frontmatter.$layout;
+  return isString(fromFrontmatter) || fromFrontmatter === false ? fromFrontmatter : undefined;
+}
+
+/**
+ * The layout a collection entry is drawn in (studio.md §22.5): the entry's own `$layout` (on its
+ * document, or in its frontmatter for a Markdown entry, {@link pageLayout}), else its collection's
+ * template page's `$layout`, else the project's `defaults.layout`. `null` when none applies.
+ *
+ * The template PAGE's own body is not spliced around the entry: a page that binds the entry into a
+ * wrapper of its own shows that wrapper only in Preview of the page itself, because the edit
+ * transforms cannot map the entry's paths through the page's bound node.
+ */
+export async function entryLayout(
+  doc: JxMutableNode,
+  tab: Tab | null,
+  path: string | null | undefined,
+): Promise<string | null> {
+  const own = pageLayout(doc, tab);
+  const match = path ? collectionForFile(path) : null;
+  const page = match ? await collectionPage(match.name, entryLocale(path)) : null;
+  return entryLayoutPath(own, page);
+}
+
 /**
  * Resolve a document into the form the iframe canvas renders: layout-distributed, edit-transformed,
  * with components/imports/$media/$head merged in, plus the path-mapper context and site style. This
@@ -176,24 +308,35 @@ export async function resolveCanvasDocument(
     S.documentPath &&
     projectState?.isSiteProject &&
     (S.documentPath.startsWith("pages/") || S.documentPath.startsWith("./pages/"));
+  /* A collection entry written on the canvas is drawn the way a page is: inside a layout, with the
+     layout's nodes locked and the entry's own tree the editable region (studio.md §22.5). */
+  const isEntry =
+    !isPage && Boolean(projectState?.isSiteProject) && writesEntryOnCanvas(S.documentPath);
   let pageContentPrefix: (string | number)[] | null = null;
   let pageContentOffset = 0;
 
   // Layout wrapping obeys the tab-bar's "show layout elements" toggle (default on); with it off,
   // The page renders alone — the unwrapped path is identical to a non-layout page.
-  if (isPage && tab?.session.ui.showLayout !== false) {
-    const layoutPath = getEffectiveLayoutPath(doc.$layout);
+  if ((isPage || isEntry) && tab?.session.ui.showLayout !== false) {
+    const layoutPath = isEntry
+      ? await entryLayout(doc, tab, S.documentPath)
+      : getEffectiveLayoutPath(pageLayout(doc, tab));
     if (layoutPath) {
-      const layoutDoc = await resolveLayoutDoc(layoutPath);
+      const layoutDoc = await resolveCanvasLayout(layoutPath);
       if (layoutDoc) {
-        // The SAME normalization resolveLayoutDoc reads the file with, so the marker's `file` is a
-        // Path the editor can hand straight to navigateToComponent when the author asks to open it.
-        markLayoutNodes(layoutDoc, layoutPath.replace(/^\.\//, ""));
         const pageForSlots = canvasMode === "preview" ? structuredClone(toRaw(doc)) : renderDoc;
         const merged = distributePageIntoLayout(layoutDoc, pageForSlots);
         renderDoc =
           canvasMode === "preview" ? merged : prepareForEditMode(stripEventHandlers(merged));
         layoutWrapped = true;
+        if (S.documentPath) {
+          /* SAFETY: a document's `$elements` entries are tag-name strings, `{ $ref }` imports or
+             inline element definitions (a hand-edited null among them is skipped by the walk). */
+          rebaseLayoutElementRefs(
+            renderDoc.$elements as (JxElement | string | null)[] | undefined,
+            S.documentPath,
+          );
+        }
         const pageContent = findPageContentPrefix(merged);
         pageContentPrefix = pageContent?.prefix ?? null;
         pageContentOffset = pageContent?.offset ?? 0;
@@ -201,6 +344,24 @@ export async function resolveCanvasDocument(
     }
   }
 
+  /* `$site` / `$page`, and the project's own state, exactly as the build injects them — a layout
+     that binds `${state.$page.url}` (a header marking its current link) threw on the canvas, and in
+     Preview, where templates are live, that one TypeError blanked the whole page. Onto COPIES of
+     `state` and `imports`: the edit-mode render doc shares both with the tab's source document,
+     which must not gain injected keys it would then save. */
+  const projectConfig = projectState?.projectConfig;
+  if (isPage && projectConfig) {
+    renderDoc = { ...renderDoc, state: { ...renderDoc.state } };
+    if (renderDoc.imports) {
+      renderDoc.imports = { ...renderDoc.imports };
+    }
+    /* SAFETY: a page render document is a JxDocument in all but its declared (mutable) type;
+       `injectContext` writes `state`, `$media` and `imports`, all of which the copy above owns. */
+    injectContext(renderDoc as JxDocument, projectConfig, {
+      urlPattern: documentUrlPattern(S.documentPath),
+    });
+  }
+
   const fileBase = documentBase(projectState?.projectRoot);
   const docBase = S.documentPath ? new URL(S.documentPath, fileBase).href : undefined;
   /*
@@ -230,6 +391,40 @@ export async function resolveCanvasDocument(
     }
   }
 
+  // `$site` and `$page`, as the build injects them (canvas-page-context.ts), in every mode: Preview
+  // Draws the page as it ships, and edit mode evaluates a component's bound props live. For a page
+  // This refines the pair injected above with the chosen route params and the project's i18n, and
+  // It is the only injection a collection entry gets.
+  if ((isPage || isEntry) && S.documentPath) {
+    const context = await pageContextFor(
+      {
+        documentPath: S.documentPath,
+        fields: isEntry ? (tab?.doc.content.frontmatter ?? null) : null,
+        isEntry,
+        lang: doc.$lang,
+        params: tab?.session.ui.previewParams ?? {},
+        title: doc.title,
+      },
+      projectState?.projectConfig,
+    );
+    if (context) {
+      // A rebuild, not a write: the render doc shares nodes with the tab's source document.
+      renderDoc = { ...renderDoc, state: { ...renderDoc.state, ...context } };
+    }
+  }
+
+  /* Class-backed state resolved before the render rather than by it (repeater-sources.ts): in every
+     mode, an entry naming an enabled extension's class by a bare `$prototype`, as the build
+     resolves it; in Edit and Design, also the collections a repeater reads, whose first item draws
+     the repeater's template. */
+  const extensions = await loadExtensions();
+  const classes = extensionClassPaths(extensions);
+  const bakeKeys = extensionClassKeys(renderDoc, classes);
+  if (canvasMode !== "preview") {
+    bakeKeys.push(...repeaterSourceKeys(doc));
+  }
+  renderDoc = await bakeRepeaterSources(renderDoc, [...new Set(bakeKeys)], docBase, classes);
+
   // Component definition docs (non-page): seed chosen test-prop values into the render doc's state
   // So a non-instantiated component previews with real data — templates, dataScope snapshots, and
   // Live/snapshot expression previews all see the values (M6, the previewParams mirror). Pure
@@ -302,28 +497,25 @@ export async function resolveCanvasDocument(
       // A null entry in a document's `$elements` names nothing, so it contributes no ref.
       effectiveElements.map((e: JxElement | string) => (isNonNullObject(e) ? e.$ref : e)),
     );
-    const collectTags = (node: JxMutableNode): Set<string> => {
-      const tags = new Set<string>();
-      // Document JSON can hold a null or scalar where a node belongs; it carries no tag.
-      if (!isNonNullObject(node)) {
-        return tags;
-      }
-      if (node.tagName) {
-        tags.add(displayTagName(node.tagName));
-      }
-      if (Array.isArray(node.children)) {
-        for (const child of node.children) {
-          if (!isString(child)) {
-            for (const t of collectTags(child)) {
-              tags.add(t);
-            }
-          }
-        }
+    /* Every tag the render can reach: the document's own, then — through the registry's `uses` —
+       each component's, transitively. Components address one another by bare `tagName` and declare
+       no `$elements` (the build finds them project-wide), so a tag that only appears INSIDE a
+       component (a card's panel, a header's theme toggle) was never registered here and rendered as
+       an empty, unstyled element. */
+    const byTag = new Map(componentRegistry.map((c: ComponentEntry) => [c.tagName, c]));
+    /* SAFETY: a render document is JSON by construction (it crosses into the canvas realm by
+       `postMessage`); the walk only reads `tagName`, `children`, `map` and `cases` off it. */
+    const reachable = collectUsedTags(renderDoc as JsonValue);
+    if (renderDoc.tagName) {
+      reachable.add(displayTagName(renderDoc.tagName));
+    }
+    for (const tag of reachable) {
+      for (const used of byTag.get(tag)?.uses ?? []) {
+        reachable.add(used);
       }
-      return tags;
-    };
-    for (const tag of collectTags(renderDoc)) {
-      const comp = componentRegistry.find((c: ComponentEntry) => c.tagName === tag);
+    }
+    for (const tag of reachable) {
+      const comp = byTag.get(tag);
       if (comp && comp.source !== "npm" && comp.path) {
         const relPath = computeRelativePath(S.documentPath ?? null, comp.path);
         if (!existingRefs.has(relPath)) {
@@ -336,7 +528,7 @@ export async function resolveCanvasDocument(
   if (effectiveElements.length > 0) {
     renderDoc.$elements = effectiveElements;
   }
-  renderDoc.imports = getEffectiveImports(renderDoc.imports);
+  renderDoc.imports = getEffectiveImports(renderDoc.imports, extensions);
   // The effective-media/head getters always answer a value: the merge, or an empty one.
   renderDoc.$media = getEffectiveMedia(renderDoc.$media);
   renderDoc.$head = getEffectiveHead(renderDoc.$head);

package/src/canvas/canvas-origin.ts

@@ -1,20 +1,20 @@
 /// <reference lib="dom" />
 /**
- * Canvas origin derivation. The canvas iframe may load same-origin (dev server / chromium /
- * electrobun gate-off, where the platform canvasUrl is a relative path) or cross-origin (electrobun
- * loopback, where canvasUrl is an absolute http://127.0.0.1:<port> URL).
+ * Canvas origin derivation. The canvas iframe may load same-origin (dev server / chromium / cloud,
+ * where the platform canvasUrl is a relative path) or cross-origin (a host whose canvasUrl is an
+ * absolute http://127.0.0.1:<port> URL).
  *
  * CanvasBaseOrigin() returns the origin the canvas document lives on, so callers that build
  * absolute asset/doc URLs target the right server. For a relative canvasUrl this resolves to
- * location.origin — IDENTITY for the same-origin paths, so dev/chromium/electrobun-gate-off are
- * byte-identical to before.
+ * location.origin — IDENTITY for the same-origin paths, so dev/chromium/cloud are byte-identical to
+ * before.
  */
 
 import { getPlatform, hasPlatform } from "../platform";
 
 /**
- * The origin serving the canvas document. When the platform registers an absolute canvasUrl
- * (electrobun loopback), this is that URL's origin; otherwise it falls back to the parent's own
+ * The origin serving the canvas document. When the platform registers an absolute canvasUrl (an
+ * absolute loopback URL), this is that URL's origin; otherwise it falls back to the parent's own
  * origin (a relative canvasUrl resolves against location.href to location.origin).
  */
 export function canvasBaseOrigin(): string {
@@ -25,6 +25,31 @@ export function canvasBaseOrigin(): string {
   return location.origin;
 }
 
+/**
+ * The dev-proxy token for a render in the SHELL's own realm, or null when it has none to use.
+ *
+ * A desktop server gates `/__jx_resolve__` and `/__jx_server__` on its rpcToken, and the canvas
+ * iframe authenticates by reading it off its own URL (`?rpcToken=`). The shell renders documents
+ * too (the Library's previews, the assistant's render check) through its own copy of the runtime,
+ * and that copy was never told: every `$src` class on a previewed page posted without the token and
+ * drew a 403. The token is read off the same canvas URL rather than a second channel, so there is
+ * one place it is handed out.
+ *
+ * Same-origin only. A cross-origin canvas (an absolute loopback canvasUrl) is not where the shell's
+ * relative dev-proxy fetches go, so its token would authenticate nothing and is better not spread
+ * around.
+ *
+ * @returns {string | null} The token, or null on a host with no token or a cross-origin canvas.
+ */
+export function hostResolveToken(): string | null {
+  const canvasUrl = hasPlatform() ? getPlatform().canvasUrl : undefined;
+  if (!canvasUrl) {
+    return null;
+  }
+  const url = new URL(canvasUrl, location.href);
+  return url.origin === location.origin ? url.searchParams.get("rpcToken") : null;
+}
+
 /**
  * The base the canvas fetches PROJECT FILES against — component `$ref`s, `$src` modules, images.
  *
@@ -69,11 +94,11 @@ export function documentBase(projectRoot?: string): string {
  * the desktop MutationObserver only rewrites asynchronously. Rendering the src loopback-absolute up
  * front eliminates that race for direct-parent <img> sites.
  *
- * Guarded: this ONLY rewrites when a real cross-origin http(s) loopback is registered (electrobun
- * loopback, canvasUrl set to an absolute http URL) whose origin differs from location.origin.
- * Otherwise — dev server, chromium, electrobun gate-off, and the pre-activate window — it returns
- * the ORIGINAL relative path unchanged, keeping those cases byte-identical (an absolute
- * ${location.origin}/... on the shell would just reintroduce views://... — the exact bug).
+ * Guarded: this ONLY rewrites when a real cross-origin http(s) loopback is registered (canvasUrl
+ * set to an absolute http URL) whose origin differs from location.origin. Otherwise — dev server,
+ * chromium, cloud, and the pre-activate window — it returns the ORIGINAL relative path unchanged,
+ * keeping those cases byte-identical (an absolute ${location.origin}/... on the shell would just
+ * reintroduce views://... — the exact bug).
  *
  * Only for PROJECT asset srcs; NEVER call it for shell-packaged views:// assets (sp-icons, bundled
  * chrome). Already-absolute inputs (data:/blob:/http/views://) are returned untouched, so it is