@jxsuite/studio 2.4.2 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "2.4.2",
+  "version": "3.0.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -57,14 +57,14 @@
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^3.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.1.0",
-    "@jxsuite/ai": "^0.36.2",
-    "@jxsuite/collab": "^0.8.1",
-    "@jxsuite/create": "^1.3.5",
-    "@jxsuite/formulas": "^0.0.12",
-    "@jxsuite/markup": "^0.4.5",
-    "@jxsuite/protocol": "^1.2.0",
-    "@jxsuite/runtime": "^2.0.4",
-    "@jxsuite/schema": "^1.8.0",
+    "@jxsuite/ai": "^0.36.4",
+    "@jxsuite/collab": "^0.8.3",
+    "@jxsuite/create": "^1.3.7",
+    "@jxsuite/formulas": "^0.0.14",
+    "@jxsuite/markup": "^0.4.7",
+    "@jxsuite/protocol": "^2.0.0",
+    "@jxsuite/runtime": "^2.1.0",
+    "@jxsuite/schema": "^1.9.0",
     "@spectrum-web-components/accordion": "^1.12.2",
     "@spectrum-web-components/action-bar": "1.12.2",
     "@spectrum-web-components/action-button": "^1.12.2",

package/src/browse/library-layouts.ts

@@ -19,7 +19,7 @@ import { html, nothing } from "lit-html";
 import { repeat } from "lit-html/directives/repeat.js";
 import { ref } from "lit-html/directives/ref.js";
 import { isImage } from "../files/media-upload";
-import { loopbackAssetSrc } from "../canvas/canvas-origin";
+import { previewFileSrc } from "../files/media-paths";
 import { localeLabel } from "@jxsuite/schema/locale";
 import { groupByCategory, groupByDate } from "./library-model";
 import type { LibraryFile, LibraryLayout } from "./library-model";
@@ -154,7 +154,7 @@ function previewTpl(file: LibraryFile, ctx: LayoutContext): TemplateResult {
     return html`<img
       class="library-thumb"
       loading="lazy"
-      src=${loopbackAssetSrc(`/${file.path}`)}
+      src=${previewFileSrc(file.path)}
       alt=""
     />`;
   }
@@ -268,7 +268,7 @@ export function mediaTpl(files: readonly LibraryFile[], ctx: LayoutContext): Tem
               ? html`<img
                   class="library-thumb"
                   loading="lazy"
-                  src=${loopbackAssetSrc(`/${file.path}`)}
+                  src=${previewFileSrc(file.path)}
                   alt=""
                 />`
               : html`<sp-icon-document size="l"></sp-icon-document>`

package/src/browse/library-pane.ts

@@ -43,7 +43,7 @@ import { confirmFileDelete, renamePromptMessage } from "../files/file-ops";
 import { createFileIn, openFileInTab } from "../files/files";
 import { createEntry } from "../content/entry-commands";
 import { entryCollections } from "../content/entry-model";
-import { UPLOAD_ACCEPT, uploadAssets } from "../files/media-upload";
+import { uploadAccept, uploadAssets } from "../files/media-upload";
 import { localeLabel } from "@jxsuite/schema/locale";
 import {
   LIBRARY_CATEGORIES,
@@ -760,7 +760,7 @@ function toolbarTpl(panel: ActiveLibraryPane, files: readonly LibraryFile[]) {
       <input
         type="file"
         multiple
-        accept=${UPLOAD_ACCEPT}
+        accept=${uploadAccept()}
         class="library-upload-input"
         @change=${(e: Event) => {
           const input = e.target as HTMLInputElement;

package/src/browse/library-preview.ts

@@ -19,7 +19,13 @@
  * already knows a preview is in flight without this module declaring an idle source of its own.
  */
 
-import { buildScope, renderNode, setSkipServerFunctions } from "@jxsuite/runtime";
+import {
+  buildScope,
+  renderNode,
+  setCanvasAssetResolver,
+  setSkipServerFunctions,
+} from "@jxsuite/runtime";
+import { assetContextFor, hostAssetDeclarations, resolveAssetRef } from "../canvas/asset-refs";
 import { componentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
 import { loadFormats, formatForPath } from "../format/format-host";
@@ -115,6 +121,7 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
   try {
     const content = await getPlatform().readFile(filePath);
     setSkipServerFunctions(true);
+    const assets = assetContextFor(filePath, hostAssetDeclarations());
     await loadFormats();
     let document_: JxDocument;
     if (formatForPath(filePath)) {
@@ -124,8 +131,17 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
       document_ = JSON.parse(content) as JxDocument;
     }
     const scope = await buildScope(document_, {}, location.href);
-    const element = renderNode(document_, scope);
-    return element instanceof HTMLElement ? element : null;
+    /* This render lands in the PARENT document, so an `<img src="/hero.jpg">` inside it resolves
+       against `index.html` — which is the shell, not the site. Same hook the canvas installs, same
+       context, restored afterwards because the next preview is a different document and a stale
+       `documentDir` would resolve its relative refs against the wrong entry. */
+    setCanvasAssetResolver((value) => resolveAssetRef(value, assets));
+    try {
+      const element = renderNode(document_, scope);
+      return element instanceof HTMLElement ? element : null;
+    } finally {
+      setCanvasAssetResolver(null);
+    }
   } catch {
     return null;
   }

package/src/canvas/asset-refs.ts

@@ -0,0 +1,119 @@
+/**
+ * Asset references, resolved for the canvas — the half that asks the running editor.
+ *
+ * The resolution math itself is {@link file://./asset-resolve.ts}, which is pure and which the
+ * canvas iframe imports. This module is everything that has to look something up: the open
+ * project's content sections and locales, the active tab, the registered platform's declarations.
+ *
+ * The split is by REALM. The iframe bundle is deliberately dependency-light, and reaching
+ * `projectState` or `getPlatform()` from it drags the whole editor shell in behind it — which is
+ * what `check-studio-dist` caught the first time these lived in one file.
+ *
+ * @docs studio/projects/media
+ */
+
+import { resolveI18n } from "@jxsuite/schema/locale";
+import { BUILD_LANES, dirOfPath } from "@jxsuite/schema/asset-paths";
+import { contentMountFor, resolveAssetRef } from "./asset-resolve";
+import { documentBase, loopbackAssetSrc } from "./canvas-origin";
+import { getPlatform, hasPlatform } from "../platform";
+import { projectState } from "../store";
+import { activeTab } from "../workspace/workspace";
+import type { AssetContext } from "./asset-resolve";
+import type { ContentSectionEntry } from "../types";
+
+/* Re-exported so callers that want both halves import one module. The pure ones are defined next
+   door precisely so the iframe can reach them WITHOUT reaching any of the above. */
+export { contentMountFor, mountedRefFor, resolveAssetRef } from "./asset-resolve";
+export type { AssetContext } from "./asset-resolve";
+
+/**
+ * The open project's canonical locale tags, or `[]` when it declares none.
+ *
+ * Through `resolveI18n` rather than off the raw config, so `EN-us` means the same thing here as it
+ * does in the compiler and the content loader — the whole reason that resolver is in
+ * `@jxsuite/schema`.
+ */
+export function projectLocales(): string[] {
+  return resolveI18n(projectState?.projectConfig ?? {}).i18n?.locales ?? [];
+}
+
+/**
+ * The context for a document in the project currently open, or null when nothing applies.
+ *
+ * @param {string | null | undefined} documentPath - Project-relative path of the open document
+ * @param {object} [over] - Host declarations: the asset space and the project-file base URL
+ * @returns {AssetContext | null} A context, or null when no resolution is needed
+ */
+export function assetContextFor(
+  documentPath: string | null | undefined,
+  over?: { space?: "site" | "repo" | undefined; fileBaseUrl?: string | undefined },
+): AssetContext | null {
+  const space = over?.space ?? "site";
+  const mount = contentMountFor(
+    documentPath,
+    projectState?.projectConfig?.content as Record<string, ContentSectionEntry> | undefined,
+    projectLocales(),
+  );
+  /* In site space the mount is the ONLY thing that needs doing, so no mount means no work. In repo
+     space every reference needs rebasing, mount or not. */
+  if (space === "site" && !mount) {
+    return null;
+  }
+  return {
+    documentDir: dirOfPath(documentPath ?? ""),
+    ...(over?.fileBaseUrl === undefined ? {} : { fileBaseUrl: over.fileBaseUrl }),
+    lanes: BUILD_LANES,
+    mounts: mount ? [mount] : [],
+    space,
+  };
+}
+
+/**
+ * The src a PARENT-REALM preview should load for an AUTHORED value — a media-picker thumbnail, the
+ * social card in the SEO modal.
+ *
+ * The canvas resolves its own references; panel chrome renders in the parent document, where a
+ * content-relative value would resolve against `index.html` and 404 exactly as it did in the
+ * canvas. Same mapping, same rule — resolved against the ACTIVE tab, which is the entry whose field
+ * is being edited.
+ *
+ * Takes what the author WROTE. For a project FILE PATH — a library thumbnail, a media-browser tile
+ * — use `previewFileSrc` in `files/media-paths`; the two are separate because a file path is not an
+ * authored reference and confusing them is silent.
+ *
+ * The loopback absolutization is folded in rather than left to the caller: every one of the four
+ * call sites needs both steps, and one that composed them by hand would work everywhere except the
+ * desktop shell, where a relative src resolves against `views://`.
+ *
+ * @param {string} value - The reference as the author wrote it
+ * @returns {string} A src the parent realm can load
+ */
+export function previewAssetSrc(value: string): string {
+  if (!value) {
+    return value;
+  }
+  const ctx = assetContextFor(activeTab.value?.documentPath, hostAssetDeclarations());
+  return loopbackAssetSrc(resolveAssetRef(value, ctx) ?? value);
+}
+
+/**
+ * What the registered host says about media — the platform's `assetSpace`, and the base project
+ * files are served under.
+ *
+ * Read through the platform rather than passed in, because every caller is panel chrome with no
+ * access to the render pipeline and because the answer is a property of the HOST, not of the call.
+ * The canvas pipeline builds the same two values from the same two places; the difference is only
+ * that it already has the document in hand.
+ *
+ * @returns {{ space?: "site" | "repo"; fileBaseUrl: string }} The host's declarations
+ */
+export function hostAssetDeclarations(): {
+  space?: "site" | "repo" | undefined;
+  fileBaseUrl: string;
+} {
+  return {
+    fileBaseUrl: documentBase(projectState?.projectRoot),
+    ...(hasPlatform() ? { space: getPlatform().assetSpace } : {}),
+  };
+}

package/src/canvas/asset-resolve.ts

@@ -0,0 +1,256 @@
+/**
+ * Asset references, resolved for the canvas — the PURE half.
+ *
+ * Separate from `asset-refs.ts` for one reason, and it is a hard one: this module runs **inside the
+ * canvas iframe**, which is a deliberately dependency-light bundle. `asset-refs.ts` reaches the
+ * open project, the active tab and the registered platform, and importing any of that from the
+ * iframe drags the entire editor shell in behind it. The build gate caught exactly that.
+ *
+ * So the split is by REALM, not by taste: everything here is a pure function of its arguments, and
+ * everything that has to ask the running editor a question lives next door.
+ *
+ * A document names media in one of two shapes, and neither is a URL the canvas can use as written.
+ *
+ * A content entry references media relative to ITSELF — `![](./images/hero.png)` — so the file
+ * reads correctly in a plain markdown editor and so collections sourced outside the project root
+ * still reach their media (specs/site-architecture.md §9.3). On the built site the collection
+ * loader rewrites those refs onto the content type's asset mount,
+ * `/content/<type>/images/hero.png`. Studio opens an entry as a STANDALONE document, so that loader
+ * never runs.
+ *
+ * A page references media by SITE URL — `/hero.jpg` — which is a file the project tree calls
+ * `public/hero.jpg`. That works wherever the canvas is hosted by something that serves the site's
+ * own URL space, which is what the dev server and the desktop loopback both are.
+ *
+ * {@link AssetContext} is the host's answer to "which of those two do you serve", and
+ * {@link resolveAssetRef} is the whole of the resolution:
+ *
+ * - `"site"` — the origin already answers site URLs, so only the content-mount mapping is missing.
+ *   This is what desktop and `jx dev` have always done, and the default when a host says nothing.
+ * - `"repo"` — nothing answers a site URL, and the host serves PROJECT PATHS under a base instead.
+ *   Every reference resolves to the file it names and is rebased onto that base. The mount detour
+ *   disappears: a content entry's `./images/hero.png` is already `content/posts/images/hero.png`, a
+ *   real path the host can serve.
+ *
+ * The SOURCE document is never touched in either case: the authored ref is what gets serialized
+ * back to disk, and the properties panel shows the author what they wrote.
+ *
+ * One deliberate divergence from the content loader: it declines to rewrite a ref whose target does
+ * not exist (`existsSync`), leaving an unresolvable path alone rather than changing its meaning.
+ * The browser has no filesystem, so this resolves optimistically. A missing file is broken either
+ * way; pointing at the URL the built site would have attempted is the more informative failure.
+ *
+ * @docs studio/projects/media
+ */
+
+import {
+  assetUrlFor,
+  encodeProjectPath,
+  isNonRelativeRef,
+  joinProjectPath,
+  projectPathForRef,
+  splitRefSuffix,
+} from "@jxsuite/schema/asset-paths";
+import type { AssetLane, AssetMount } from "@jxsuite/schema/asset-paths";
+import type { ContentSectionEntry } from "../types";
+
+/** Content type names safe in a URL path segment. Mirrors `SAFE_TYPE_NAME` in the content loader. */
+const SAFE_TYPE_NAME = /^[\w.~-]+$/;
+
+/** The project.json section key content types live under; also their URL namespace. */
+const SECTION_KEY = "content";
+
+/**
+ * The placeholder a content type's `source` may carry to say "one directory per locale".
+ *
+ * Held here rather than imported out of the parser extension's content loader ({@link
+ * file://../../../../extensions/parser/src/content-loader.ts}): that module reads the filesystem
+ * and this one runs in a browser. It is also an extension, and core may not import one.
+ */
+const LOCALE_PLACEHOLDER = "{locale}";
+
+/**
+ * Everything the canvas needs to resolve one reference, as PLAIN DATA.
+ *
+ * Plain data because it has to cross a realm. The resolver itself is a function and cannot be
+ * posted into the canvas iframe, so the parent posts this beside the render document and the iframe
+ * builds the resolver from it locally.
+ */
+export interface AssetContext {
+  /** What the canvas ORIGIN answers for a site URL — the platform's `assetSpace`, defaulted. */
+  space: "site" | "repo";
+  /**
+   * Base URL under which the host serves PROJECT PATHS. Required by `"repo"` and inert without it:
+   * a host that declares repo space and no base has told us its site URLs are wrong without telling
+   * us what is right, and inventing an answer there would be worse than leaving the ref alone.
+   */
+  fileBaseUrl?: string | undefined;
+  /** Project-relative directory of the document being rendered (`""` at the project root). */
+  documentDir: string;
+  /** Project-relative asset mounts that apply to this document. */
+  mounts: AssetMount[];
+  /**
+   * The resolution order for a site-absolute URL.
+   *
+   * `BUILD_LANES` by default, and that is the deliberate answer rather than an omission: with no
+   * filesystem to probe, a lane list has to collapse to ONE candidate, and the one that makes the
+   * preview agree with the deployed site is the build's. See `DEV_SERVER_LANES` for the order the
+   * editing servers actually use, and why the two differ.
+   */
+  lanes: readonly AssetLane[];
+}
+
+/**
+ * The asset mount for the content type that owns `documentPath`, or null when the document is not a
+ * directory-backed content entry.
+ *
+ * Only in-project sources can match: an entry Studio can address project-relatively is by
+ * definition inside the project, and a source pointing elsewhere (`../../docs`) names files the
+ * file tree cannot reach in the first place.
+ *
+ * @param {string | null | undefined} documentPath - Project-relative path of the open document
+ * @param {Record<string, ContentSectionEntry> | null | undefined} content - Project.json `content`
+ * @param {readonly string[]} [locales] - Canonical locale tags, for `{locale}` sources
+ * @returns {AssetMount | null} The mount, project-relative
+ */
+export function contentMountFor(
+  documentPath: string | null | undefined,
+  content: Record<string, ContentSectionEntry> | null | undefined,
+  locales: readonly string[] = [],
+): AssetMount | null {
+  if (!documentPath || !content) {
+    return null;
+  }
+  const path = documentPath.replaceAll("\\", "/").replace(/^\.\//, "");
+  let best: AssetMount | null = null;
+  const consider = (dir: string, urlPrefix: string): void => {
+    if (path.startsWith(`${dir}/`) && (!best || dir.length > best.dir.length)) {
+      best = { dir, urlPrefix };
+    }
+  };
+  for (const [name, def] of Object.entries(content)) {
+    if (!def?.source || !SAFE_TYPE_NAME.test(name)) {
+      continue;
+    }
+    const dir = normalizeSource(def.source);
+    // A single-file source is not a collection directory — its siblings are not its assets.
+    if (dir === "" || dir.startsWith("..")) {
+      continue;
+    }
+    if (dir.includes(LOCALE_PLACEHOLDER)) {
+      const mount = localeMountFor(path, dir, name, locales);
+      if (mount) {
+        consider(mount.dir, mount.urlPrefix);
+      }
+      continue;
+    }
+    if (/\.[a-z0-9]+$/i.test(dir)) {
+      continue;
+    }
+    consider(dir, `/${SECTION_KEY}/${name}`);
+  }
+  return best;
+}
+
+/**
+ * The mount for ONE locale of a `{locale}` source — the locale being whichever one `path` is in.
+ *
+ * A localized content type is N directories, not N content types, and each publishes separately at
+ * `/content/<type>/<locale>` so a French post's `./hero.png` and its English translation's cannot
+ * collide at one URL. The content loader picks the directory by probing the disk (`localeSource`);
+ * Studio has no disk, so it reads the locale out of the document path it was given and checks that
+ * against the project's declared tags. That is not a weaker test — the path IS the file, so the
+ * only question left is whether its directory is a locale the project declares.
+ *
+ * Matched case-insensitively, for the same reason the loader does: two writers name that directory
+ * and they differ. A project that declared `fr-CA` most likely typed `fr-CA/`, while Studio creates
+ * `fr-ca/` because a page directory becomes a URL and the site's URLs are lowercase. The mount's
+ * `dir` is the spelling on disk and its `urlPrefix` is the CANONICAL tag, exactly as the loader
+ * publishes it.
+ */
+function localeMountFor(
+  path: string,
+  source: string,
+  name: string,
+  locales: readonly string[],
+): AssetMount | null {
+  const cut = source.indexOf(LOCALE_PLACEHOLDER);
+  const head = source.slice(0, cut);
+  const tail = source.slice(cut + LOCALE_PLACEHOLDER.length);
+  if (!path.startsWith(head)) {
+    return null;
+  }
+  const segment = path.slice(head.length).split("/")[0] ?? "";
+  if (segment === "" || !SAFE_TYPE_NAME.test(segment)) {
+    return null;
+  }
+  const canonical = locales.find((tag) => tag.toLowerCase() === segment.toLowerCase());
+  if (canonical === undefined || !SAFE_TYPE_NAME.test(canonical)) {
+    return null;
+  }
+  const dir = `${head}${segment}${tail}`.replace(/\/+$/, "");
+  return { dir, urlPrefix: `/${SECTION_KEY}/${name}/${canonical}` };
+}
+
+/** Strip `./` and any trailing slash from a configured `source`, the way collectionDirs does. */
+function normalizeSource(source: string): string {
+  return source.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+
+/**
+ * The URL the canvas should load for one authored reference, or null to leave it as written.
+ *
+ * Null is not a failure — it is most of the answers. An absolute URL, a `data:` URI, a `${…}`
+ * template that did not resolve to a project file, a `../` escape out of the collection: each one
+ * already means what it says, and changing it would be the bug.
+ *
+ * @param {string} value - The reference as the author wrote it
+ * @param {AssetContext | null} ctx - The host's asset context, or null for no resolution at all
+ * @returns {string | null} The URL to load, or null to leave `value` untouched
+ */
+export function resolveAssetRef(value: string, ctx: AssetContext | null): string | null {
+  if (!ctx || value === "") {
+    return null;
+  }
+  if (ctx.space === "repo") {
+    if (!ctx.fileBaseUrl) {
+      return null;
+    }
+    const path = projectPathForRef(value, ctx.documentDir, ctx.mounts, ctx.lanes);
+    if (path === null) {
+      return null;
+    }
+    const { suffix } = splitRefSuffix(value);
+    return `${ctx.fileBaseUrl}${encodeProjectPath(path)}${suffix}`;
+  }
+  const [mount] = ctx.mounts;
+  return mount ? mountedRefFor(value, ctx.documentDir, mount) : null;
+}
+
+/**
+ * The mounted URL for one content-relative reference, or null to leave it as written. A ref is
+ * rewritten only when it is relative and lands inside the collection directory — anything else (an
+ * absolute URL, a project-root path, a bound template, a `../` escape out of the collection) keeps
+ * the meaning it already had.
+ */
+export function mountedRefFor(value: string, entryDir: string, mount: AssetMount): string | null {
+  if (isNonRelativeRef(value)) {
+    return null;
+  }
+  const { path: bare, suffix } = splitRefSuffix(value);
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(bare);
+  } catch {
+    return null;
+  }
+  const target = joinProjectPath(entryDir, decoded);
+  if (target === null) {
+    return null;
+  }
+  const url = assetUrlFor([mount], target);
+  if (!url) {
+    return null; // Outside the collection — not the mount's to publish.
+  }
+  return `${url}${suffix}`;
+}

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/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-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