@jxsuite/studio 2.4.3 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "2.4.3",
+  "version": "4.0.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -52,19 +52,20 @@
     "lint:styles": "bun run scripts/check-styles.ts",
     "test": "bun run lint:styles && bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^3.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.1.0",
-    "@jxsuite/ai": "^0.36.3",
-    "@jxsuite/collab": "^0.8.2",
-    "@jxsuite/create": "^1.3.6",
-    "@jxsuite/formulas": "^0.0.13",
-    "@jxsuite/markup": "^0.4.6",
-    "@jxsuite/protocol": "^1.2.1",
-    "@jxsuite/runtime": "^2.0.5",
-    "@jxsuite/schema": "^1.8.1",
+    "@jxsuite/ai": "^0.36.5",
+    "@jxsuite/collab": "^0.8.4",
+    "@jxsuite/create": "^1.3.8",
+    "@jxsuite/formulas": "^0.0.15",
+    "@jxsuite/markup": "^0.4.8",
+    "@jxsuite/protocol": "^2.1.0",
+    "@jxsuite/runtime": "^3.0.0",
+    "@jxsuite/schema": "^2.0.0",
+    "@jxsuite/site": "^1.0.0",
     "@spectrum-web-components/accordion": "^1.12.2",
     "@spectrum-web-components/action-bar": "1.12.2",
     "@spectrum-web-components/action-button": "^1.12.2",
@@ -107,15 +108,15 @@
     "lit": "^3.3.3",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.56.0",
-    "tabulator-tables": "^6.5",
+    "tabulator-tables": "^6.5.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6",
+    "@happy-dom/global-registrator": "^20.11.8",
     "@types/mdast": "^4.0.4",
-    "@webref/css": "^8.7.2",
-    "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.82.2"
+    "@webref/css": "^8.7.3",
+    "@webref/elements": "^2.8.0",
+    "@webref/idl": "^3.83.0"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

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

@@ -42,8 +42,9 @@ import { invalidateUsages } from "../services/references";
 import { confirmFileDelete, renamePromptMessage } from "../files/file-ops";
 import { createFileIn, openFileInTab } from "../files/files";
 import { createEntry } from "../content/entry-commands";
+import { formatByExtension, formatSerialize } from "../format/format-host";
 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,
@@ -70,6 +71,7 @@ import {
   tableRowsTpl,
 } from "./library-layouts";
 import type { ActivityHandle } from "../panels/activity-panel";
+import type { FormatChoice } from "../files/files";
 import type { EffectScope } from "@vue/reactivity";
 import type { LibraryFile, LibraryLayout } from "./library-model";
 import type { LibrarySource } from "./library-source";
@@ -602,10 +604,60 @@ export function libraryNewEntries(): LibraryNewEntry[] {
  * `createEntry` is called rather than reimplemented; a second seeder here would drift from the one
  * the palette's `content.newEntry` uses within a release.
  *
- * A **document kind** keeps `files.ts`'s verbatim name field, deliberately: a page may be a `.md`
- * as easily as a `.json`, so the extension the author types is a real choice and forcing one here
- * would remove it. A collection's extension is not a choice — it is the collection's.
+ * A **document kind** gets the format PICKER, which is the same argument the verbatim name field
+ * used to make: a page may be a `.md` as easily as a `.json`, so the extension is a real choice —
+ * now offered rather than left to be typed from memory. A collection's extension is not a choice;
+ * it is the collection's, and `createEntry` supplies it.
+ *
+ * **A layout is not a choice either, and that is not a policy.** Both readers of a layout parse it
+ * as JSON and neither dispatches through the format registry — `site/layout-resolver.ts` throws and
+ * `site-context.ts` returns null — so a `.md` layout is a file the build cannot load. There is no
+ * `"layout"` document kind for a format to declare, so this is stated here rather than derived.
+ *
+ * A **component** keeps the picker: a format whose `$studio.documentMode.componentWhen` promotes a
+ * frontmatter `tagName` (Markdown's does) can express one perfectly well. What it cannot do is
+ * express one from a `newFileTemplate` that carries no `tagName`, so the seed below supplies it —
+ * through the format's own serializer, because this module knows no format's syntax.
+ */
+/** How each document kind's extension is settled. Anything else falls back to the full picker. */
+const FORMAT_CHOICE_BY_KIND: Record<string, FormatChoice> = {
+  component: { defaultExt: ".json", docKind: "component", kind: "choose" },
+  layout: { ext: ".json", kind: "fixed" },
+  page: { defaultExt: ".json", docKind: "page", kind: "choose" },
+};
+
+/**
+ * The body a new component starts as, when the reader picked a format rather than `.json`.
+ *
+ * `.json` answers `undefined` and takes the shared blank document. A format answers with its OWN
+ * serialization of `{ tagName }` — never a hand-written `---\ntagName: …\n---`, which would put one
+ * format's syntax in the Library. Without the `tagName` the file satisfies neither
+ * `$studio.documentMode.componentWhen` nor the build's tag registration, and is a component nothing
+ * loads. A stem that is not a valid custom-element name (no hyphen) cannot carry one, so it falls
+ * back to the format's own template and the author names the tag themselves.
  */
+async function componentSeed(ext: string, fileName: string): Promise<string | undefined> {
+  const format = formatByExtension(ext);
+  if (!format?.capabilities.serialize) {
+    return undefined;
+  }
+  const tagName = fileName.slice(0, fileName.length - ext.length);
+  if (!/^[a-z][\d.a-z]*-[\d.a-z-]*$/.test(tagName)) {
+    return undefined;
+  }
+  try {
+    return await formatSerialize(
+      format.name,
+      { children: [], tagName },
+      { frontmatter: true, mode: "roundtrip" },
+    );
+  } catch {
+    // The serializer is the project's, so its failure is not a reason to refuse the creation —
+    // The format's own template still produces a file the author can finish by hand.
+    return undefined;
+  }
+}
+
 export async function createLibraryEntry(key: string): Promise<string | null> {
   const entry = libraryNewEntries().find((row) => row.key === key);
   if (!entry) {
@@ -614,7 +666,9 @@ export async function createLibraryEntry(key: string): Promise<string | null> {
   const created =
     entry.collection === undefined
       ? await createFileIn({
+          ...(entry.key === "component" ? { content: componentSeed } : {}),
           dir: entry.dir,
+          format: FORMAT_CHOICE_BY_KIND[entry.key] ?? { defaultExt: ".json", kind: "choose" },
           source: "Library",
           suggestedName: "untitled",
           title: `New ${entry.label}`,
@@ -760,7 +814,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}`;
+}