@jxsuite/studio 6.1.1 → 8.0.0

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

@@ -7,21 +7,30 @@
  */
 
 import { projectState, stripEventHandlers } from "../store";
-import { displayTagName } 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,
   resolveLayoutDoc,
 } from "../site-context";
 import { documentBase } from "./canvas-origin";
-import { getPlatform, hasPlatform } from "../platform";
 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,10 +38,23 @@ import {
   substitutePreviewParams,
 } from "../page-params";
 import { isComponentDoc, substitutePreviewProps } from "../component-props";
-import { assetContextFor } from "./asset-refs";
+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 } 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";
@@ -55,19 +77,20 @@ function findPageContentPrefix(
   node: JxMutableNode,
   path: (string | number)[] = [],
 ): { prefix: (string | number)[]; offset: number } | null {
-  if (!node || typeof node !== "object") {
+  // Document JSON can hold a null or scalar where a node belongs; neither has page content.
+  if (!isNonNullObject(node)) {
     return null;
   }
   if (Array.isArray(node.children)) {
     const firstPageIdx = node.children.findIndex(
-      (child) => child && typeof child === "object" && !child.$__layout,
+      (child) => isNonNullObject(child) && !child.$__layout,
     );
     if (firstPageIdx !== -1) {
       return { offset: firstPageIdx, prefix: [...path, "children"] };
     }
     for (let i = 0; i < node.children.length; i++) {
       const child = node.children[i];
-      if (child && typeof child === "object" && child.$__layout) {
+      if (isNonNullObject(child) && child.$__layout) {
         const found = findPageContentPrefix(child, [...path, "children", i]);
         if (found) {
           return found;
@@ -87,13 +110,14 @@ function findPageContentPrefix(
  * editor can open the layout with that node selected. See {@link LayoutMarker}.
  */
 export function markLayoutNodes(node: JxMutableNode, file: string, path: JxPath = []) {
-  if (!node || typeof node !== "object") {
+  // Layout JSON can hold a null or scalar where a node belongs; there is nothing to mark on it.
+  if (!isNonNullObject(node)) {
     return;
   }
   node.$__layout = { file, path } satisfies LayoutMarker;
   if (Array.isArray(node.children)) {
     for (const [i, child] of node.children.entries()) {
-      if (typeof child === "string") {
+      if (isString(child)) {
         continue;
       }
       markLayoutNodes(child, file, [...path, "children", i]);
@@ -101,13 +125,125 @@ export function markLayoutNodes(node: JxMutableNode, file: string, path: JxPath
   }
   if (Array.isArray(node.$elements)) {
     for (const [i, el] of node.$elements.entries()) {
-      if (typeof el !== "string") {
+      if (!isString(el)) {
+        /* SAFETY: a non-string `$elements` entry is an inline element definition or a `{ $ref }`
+           import. markLayoutNodes stamps `$__layout` and walks `children` / `$elements`, which a
+           `$ref` entry simply lacks, so it is marked as a childless node. */
         markLayoutNodes(el as JxMutableNode, file, [...path, "$elements", i]);
       }
     }
   }
 }
 
+/**
+ * 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
@@ -157,7 +293,7 @@ export async function resolveCanvasDocument(
   /** 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;
+  siteStyle: JxStyle | null;
 }> {
   const S = { documentPath: tab?.documentPath, mode: tab?.doc.mode };
   const canvasMode = modeOverride ?? canvasModeOfTab(tab);
@@ -172,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)) as JxMutableNode | null;
+      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;
@@ -197,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;
   /*
@@ -210,10 +375,7 @@ export async function resolveCanvasDocument(
    * — 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 } : {}),
-  });
+  const assets = assetContextFor(S.documentPath, hostAssetDeclarations());
 
   // 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
@@ -222,15 +384,47 @@ export async function resolveCanvasDocument(
   // (posted as shadowDoc), whose $refs must survive for editing/serialization.
   if (isPage && tab) {
     const { previewParams } = tab.session.ui;
-    if (previewParams && Object.keys(previewParams).length > 0) {
-      const boundKeys = paramBoundStateKeys(
-        (doc as { state?: Record<string, unknown> }).state ?? null,
-      );
+    if (Object.keys(previewParams).length > 0) {
+      const boundKeys = paramBoundStateKeys(doc.state ?? null);
       renderDoc = substitutePreviewParams(renderDoc, previewParams, S.documentPath);
       await resolveParamBoundState(renderDoc, boundKeys, docBase);
     }
   }
 
+  // `$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
@@ -253,30 +447,29 @@ export async function resolveCanvasDocument(
   const arrayPaths = new Set<string>();
   if (canvasMode !== "preview") {
     (function findArrayPaths(node: JxMutableNode, path: (string | number)[]) {
-      if (!node || typeof node !== "object") {
+      // Document JSON can hold a null or scalar where a node belongs; it holds no repeater.
+      if (!isNonNullObject(node)) {
         return;
       }
-      if ((node as unknown as { $prototype?: string }).$prototype === "Array") {
+      if (node.$prototype === "Array") {
         arrayPaths.add(path.join("/"));
-        const mapDef = (node as JxMutableNode).map;
-        if (mapDef && typeof mapDef === "object") {
+        const mapDef = node.map;
+        if (isNonNullObject(mapDef)) {
           findArrayPaths(mapDef, [...path, "map"]);
         }
         return;
       }
       if (Array.isArray(node.children)) {
-        for (let i = 0; i < node.children.length; i++) {
-          const child = node.children[i];
-          if (typeof child === "string") {
+        for (const [i, child] of node.children.entries()) {
+          if (isString(child)) {
             continue;
           }
-          findArrayPaths(child!, [...path, "children", i]);
+          findArrayPaths(child, [...path, "children", i]);
         }
-      } else if (
-        node.children &&
-        typeof node.children === "object" &&
-        (node.children as unknown as { $prototype?: string }).$prototype === "Array"
-      ) {
+      } else if (isMappedArray(node.children)) {
+        /* SAFETY: the bare mapped-array slot is a repeater node in all but its declared type, and
+           the walk reads only what isMappedArray just established (`$prototype`) and its `map`
+           template, an element definition. */
         findArrayPaths(node.children as JxMutableNode, [...path, "children"]);
       }
       if (node.$switch && node.cases) {
@@ -295,32 +488,34 @@ export async function resolveCanvasDocument(
   const isLayoutDoc =
     S.documentPath != null &&
     (S.documentPath.startsWith("layouts/") || S.documentPath.startsWith("./layouts/"));
+  /* SAFETY: a document's `$elements` entries are tag-name strings, `{ $ref }` imports or inline
+     element definitions, each a JxElement or a string; getEffectiveElements only dedups them by the
+     string itself or by `$ref`. */
   const effectiveElements = getEffectiveElements(renderDoc.$elements as (JxElement | string)[]);
   if ((S.mode === "content" || layoutWrapped || isLayoutDoc) && componentRegistry.length > 0) {
     const existingRefs = new Set(
-      effectiveElements.map((e: JxElement | string) => (typeof e === "string" ? e : e?.$ref)),
+      // 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>();
-      if (!node || typeof node !== "object") {
-        return tags;
-      }
-      if (node.tagName) {
-        tags.add(displayTagName(node.tagName));
-      }
-      if (Array.isArray(node.children)) {
-        for (const child of node.children) {
-          if (typeof child !== "string") {
-            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)) {
@@ -331,24 +526,12 @@ export async function resolveCanvasDocument(
     }
   }
   if (effectiveElements.length > 0) {
-    renderDoc.$elements = effectiveElements as (string | JxMutableNode | { $ref: string })[];
-  }
-  renderDoc.imports = getEffectiveImports(renderDoc.imports);
-  // The effective-media/head getters return the merged value or undefined. Optional properties
-  // Cannot be assigned undefined under exactOptionalPropertyTypes, so clear them by deleting the key
-  // When the getter yields nothing.
-  const media = getEffectiveMedia(renderDoc.$media);
-  if (media === undefined) {
-    delete renderDoc.$media;
-  } else {
-    renderDoc.$media = media as NonNullable<JxMutableNode["$media"]>;
-  }
-  const head = getEffectiveHead(renderDoc.$head);
-  if (head === undefined) {
-    delete renderDoc.$head;
-  } else {
-    renderDoc.$head = head as NonNullable<JxMutableNode["$head"]>;
+    renderDoc.$elements = effectiveElements;
   }
+  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);
 
   return {
     assets,
@@ -361,6 +544,6 @@ export async function resolveCanvasDocument(
       pageContentPrefix,
     },
     renderDoc,
-    siteStyle: (projectState?.projectConfig?.style as Record<string, unknown>) ?? null,
+    siteStyle: projectState?.projectConfig?.style ?? null,
   };
 }

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