@volter/editor-core 0.5.57

package/src/asset-workflow/pixi-spritesheet.ts

@@ -0,0 +1,197 @@
+/**
+ * Pixi's native spritesheet sidecar — TexturePacker hash/array JSON, the
+ * same document AssetPack writes as `image.png.json`. The game loads THAT
+ * file (`Assets.load('images/game-screen.png.json')`); the PNG is the atlas
+ * page, not the authored unit.
+ */
+
+export interface PixiSpritesheetFrame {
+  readonly name: string;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly rotated: boolean;
+  /** Untrimmed sprite canvas — Unity/Aseprite's document size. */
+  readonly sourceWidth: number;
+  readonly sourceHeight: number;
+  /** Where the packed pixels sit inside that canvas. */
+  readonly trimX: number;
+  readonly trimY: number;
+}
+
+export interface PixiSpritesheet {
+  readonly image: string;
+  readonly frames: readonly PixiSpritesheetFrame[];
+}
+
+export function spritesheetResolutionRank(name: string): number {
+  if (/@[0-9.]+x\./i.test(name)) return 1;
+  if (/\.webp\.json$/i.test(name)) return 2;
+  if (/\.png\.json$/i.test(name)) return 3;
+  return 0;
+}
+
+export function spritesheetFamilyKey(path: string): string {
+  const slash = path.lastIndexOf('/');
+  const dir = slash < 0 ? '' : path.slice(0, slash);
+  const file = slash < 0 ? path : path.slice(slash + 1);
+  const stem = file
+    .replace(/@[0-9.]+x/i, '')
+    .replace(/\.(png|webp|jpe?g)\.json$/i, '')
+    .replace(/\.json$/i, '');
+  return dir ? `${dir}/${stem}` : stem;
+}
+
+export function parsePixiSpritesheet(source: string): PixiSpritesheet | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const record = parsed as {
+    frames?: unknown;
+    meta?: { image?: unknown };
+  };
+  const image = typeof record.meta?.image === 'string' ? fileName(record.meta.image) : '';
+  const frames = readFrames(record.frames);
+  if (!image || frames.length === 0) return null;
+  return { image, frames };
+}
+
+/** Content/open path: `assets/images/game-screen.png#satellite`. */
+export function splitSpritesheetAssetPath(path: string): {
+  readonly sheetPath: string;
+  readonly frameName: string | null;
+} {
+  const trimmed = path.replace(/^\//, '');
+  const hash = trimmed.lastIndexOf('#');
+  if (hash < 0) return { sheetPath: trimmed, frameName: null };
+  return { sheetPath: trimmed.slice(0, hash), frameName: trimmed.slice(hash + 1) || null };
+}
+
+/** Tab title: the frame name, never `game-screen.png#satellite`. */
+export function spritesheetFrameTitle(path: string): string {
+  const { sheetPath, frameName } = splitSpritesheetAssetPath(path);
+  return frameName ?? sheetPath.split('/').pop() ?? path;
+}
+
+export function sidecarPathForSheet(sheetPath: string): string {
+  return `${sheetPath.replace(/^\//, '')}.json`;
+}
+
+export function sheetVariantsFor(image: string): readonly string[] {
+  const ext = image.match(/\.[a-z0-9]+$/i)?.[0] ?? '';
+  const stem = image.slice(0, image.length - ext.length);
+  return [
+    image,
+    `${stem}.png`,
+    `${stem}.webp`,
+    `${stem}.jpg`,
+    `${stem}@0.5x${ext}`,
+    `${stem}@0.5x.png`,
+    `${stem}@0.5x.webp`,
+    `${stem}@2x${ext}`,
+    `${stem}@2x.png`,
+    `${stem}@2x.webp`,
+  ];
+}
+
+function readFrames(frames: unknown): PixiSpritesheetFrame[] {
+  if (!frames || typeof frames !== 'object') return [];
+  if (Array.isArray(frames)) {
+    return frames.flatMap((entry) => {
+      if (!entry || typeof entry !== 'object') return [];
+      const row = entry as FrameRecord;
+      const name = typeof row.filename === 'string' ? row.filename : '';
+      const parsed = readFrame(row);
+      if (!name || !parsed) return [];
+      return [{ name: stripFrameExt(name), ...parsed }];
+    });
+  }
+  return Object.entries(frames as Record<string, unknown>).flatMap(([name, entry]) => {
+    if (!entry || typeof entry !== 'object') return [];
+    const parsed = readFrame(entry as FrameRecord);
+    if (!parsed) return [];
+    return [{ name: stripFrameExt(name), ...parsed }];
+  });
+}
+
+interface FrameRecord {
+  filename?: unknown;
+  frame?: unknown;
+  rotated?: unknown;
+  sourceSize?: unknown;
+  spriteSourceSize?: unknown;
+}
+
+function readFrame(row: FrameRecord): Omit<PixiSpritesheetFrame, 'name'> | null {
+  const box = readBox(row.frame);
+  if (!box) return null;
+  const source = readSize(row.sourceSize) ?? { width: box.width, height: box.height };
+  const trim = readPoint(row.spriteSourceSize);
+  return {
+    ...box,
+    rotated: row.rotated === true,
+    sourceWidth: source.width,
+    sourceHeight: source.height,
+    trimX: trim?.x ?? 0,
+    trimY: trim?.y ?? 0,
+  };
+}
+
+function readBox(frame: unknown): { x: number; y: number; width: number; height: number } | null {
+  if (!frame || typeof frame !== 'object') return null;
+  const box = frame as { x?: unknown; y?: unknown; w?: unknown; h?: unknown };
+  if (
+    typeof box.x !== 'number' ||
+    typeof box.y !== 'number' ||
+    typeof box.w !== 'number' ||
+    typeof box.h !== 'number'
+  ) {
+    return null;
+  }
+  return { x: box.x, y: box.y, width: box.w, height: box.h };
+}
+
+function readSize(value: unknown): { width: number; height: number } | null {
+  if (!value || typeof value !== 'object') return null;
+  const size = value as { w?: unknown; h?: unknown };
+  if (typeof size.w !== 'number' || typeof size.h !== 'number') return null;
+  return { width: size.w, height: size.h };
+}
+
+function readPoint(value: unknown): { x: number; y: number } | null {
+  if (!value || typeof value !== 'object') return null;
+  const point = value as { x?: unknown; y?: unknown };
+  if (typeof point.x !== 'number' || typeof point.y !== 'number') return null;
+  return { x: point.x, y: point.y };
+}
+
+/**
+ * Packed rect Pixi samples. A rotated TexturePacker frame stores the
+ * unrotated size in `frame` and occupies the swapped rect on the page.
+ */
+export function packedFrameRect(
+  frame: Pick<PixiSpritesheetFrame, 'x' | 'y' | 'width' | 'height' | 'rotated'>,
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} {
+  return frame.rotated
+    ? { x: frame.x, y: frame.y, width: frame.height, height: frame.width }
+    : { x: frame.x, y: frame.y, width: frame.width, height: frame.height };
+}
+
+function fileName(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash < 0 ? path : path.slice(slash + 1);
+}
+
+function stripFrameExt(name: string): string {
+  return name.replace(/\.(png|webp|jpe?g)$/i, '');
+}

package/src/asset-workflow/preview-resource-lifetime.ts

@@ -0,0 +1,44 @@
+export type PreviewResourceKind =
+  | 'webglContext'
+  | 'animationFrame'
+  | 'resizeObserver'
+  | 'objectUrl';
+
+export interface PreviewResourceSnapshot {
+  webglContext: number;
+  animationFrame: number;
+  resizeObserver: number;
+  objectUrl: number;
+  peaks: Record<PreviewResourceKind, number>;
+}
+
+const current: Record<PreviewResourceKind, number> = {
+  webglContext: 0,
+  animationFrame: 0,
+  resizeObserver: 0,
+  objectUrl: 0,
+};
+const peaks = { ...current };
+
+/** Local diagnostic counter used by stress tests and the Debugger; never uploads identifiers. */
+export function registerPreviewResource(kind: PreviewResourceKind): () => void {
+  current[kind]++;
+  peaks[kind] = Math.max(peaks[kind], current[kind]);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    current[kind] = Math.max(0, current[kind] - 1);
+  };
+}
+
+export function previewResourceSnapshot(): PreviewResourceSnapshot {
+  return { ...current, peaks: { ...peaks } };
+}
+
+export function resetPreviewResourceCounters(): void {
+  for (const key of Object.keys(current) as PreviewResourceKind[]) {
+    current[key] = 0;
+    peaks[key] = 0;
+  }
+}

package/src/asset-workflow/project-asset-commands.ts

@@ -0,0 +1,23 @@
+export const PROJECT_ASSET_COMMANDS = {
+  open: { id: 'project-asset.open', shortcut: 'Enter' },
+  rename: { id: 'project-asset.rename', shortcut: 'F2' },
+  move: { id: 'project-asset.move', shortcut: null },
+  duplicate: { id: 'project-asset.duplicate', shortcut: 'Mod+D' },
+  delete: { id: 'project-asset.delete', shortcut: 'Delete' },
+  copyPath: { id: 'project-asset.copy-path', shortcut: 'Mod+Shift+C' },
+  reveal: { id: 'project-asset.reveal', shortcut: null },
+  refresh: { id: 'project-asset.refresh', shortcut: 'Mod+R' },
+  import: { id: 'project-asset.import', shortcut: null },
+  createFolder: { id: 'project-asset.create-folder', shortcut: 'Mod+Shift+N' },
+} as const;
+
+export type ProjectAssetCommandId =
+  (typeof PROJECT_ASSET_COMMANDS)[keyof typeof PROJECT_ASSET_COMMANDS]['id'];
+
+export function projectAssetCommandIds(): readonly ProjectAssetCommandId[] {
+  return Object.values(PROJECT_ASSET_COMMANDS).map((command) => command.id);
+}
+
+export function projectContentBrowserStateKey(projectId: string): string {
+  return `vgai:project-content:v1:${projectId}`;
+}

package/src/asset-workflow/project-asset-health.ts

@@ -0,0 +1,139 @@
+import type { StorageBackend } from '../storage/types';
+import { assetCapabilities } from './asset-capabilities';
+import type { AssetHealth, AssetHealthCode } from './asset-types';
+
+export interface ProjectAssetFileSnapshot {
+  readonly path: string;
+  readonly text?: string;
+}
+
+export interface ProjectAssetReference {
+  readonly ownerPath: string;
+  readonly jsonPath: string;
+  readonly assetPath: string;
+}
+
+export interface ProjectAssetHealthResult {
+  readonly health: AssetHealth;
+  readonly dependencies: readonly string[];
+  readonly references: readonly ProjectAssetReference[];
+}
+
+function collectStringPaths(value: unknown, path = '$'): { path: string; value: string }[] {
+  if (typeof value === 'string') return [{ path, value }];
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => collectStringPaths(entry, `${path}[${index}]`));
+  }
+  if (!value || typeof value !== 'object') return [];
+  return Object.entries(value).flatMap(([key, entry]) =>
+    collectStringPaths(entry, `${path}.${key}`),
+  );
+}
+
+function externalDependencies(assetPath: string, text: string | undefined): string[] {
+  if (!text || !assetPath.toLowerCase().endsWith('.gltf')) return [];
+  try {
+    const json = JSON.parse(text) as { buffers?: { uri?: string }[]; images?: { uri?: string }[] };
+    const base = assetPath.includes('/') ? assetPath.slice(0, assetPath.lastIndexOf('/') + 1) : '';
+    return [...(json.buffers ?? []), ...(json.images ?? [])].flatMap((entry) =>
+      entry.uri && !entry.uri.startsWith('data:') ? [`${base}${entry.uri}`] : [],
+    );
+  } catch {
+    return [];
+  }
+}
+
+export function inspectProjectAssetHealth(input: {
+  readonly assetPath: string;
+  readonly files: readonly ProjectAssetFileSnapshot[];
+}): ProjectAssetHealthResult {
+  const byPath = new Map(input.files.map((file) => [file.path.replace(/^\//, ''), file]));
+  const assetPath = input.assetPath.replace(/^\//, '');
+  const asset = byPath.get(assetPath);
+  const codes = new Set<AssetHealthCode>();
+  const capability = assetCapabilities(assetPath);
+  if (!asset) codes.add('missing-file');
+  if (!capability.importable) codes.add('unsupported-format');
+  else if (!capability.runtimeReady) codes.add('source-only');
+
+  if (asset?.text && capability.kind === 'json') {
+    try {
+      JSON.parse(asset.text);
+    } catch {
+      codes.add('invalid-metadata');
+    }
+  }
+
+  const dependencies = externalDependencies(assetPath, asset?.text);
+  if (dependencies.some((path) => !byPath.has(path))) codes.add('missing-dependency');
+  // Catalog attribution is project-authoring state in .vgai/provenance.json,
+  // outside this public/-rooted storage snapshot. Do not infer it is missing
+  // from the deliberate absence of a legacy per-directory sidecar.
+
+  const references: ProjectAssetReference[] = [];
+  for (const file of input.files) {
+    // JSON is a common structured container, not a vgai material dialect.
+    // Walk any JSON document supplied by the project snapshot and report the
+    // exact path of a matching asset reference.
+    if (!file.text || !/\.json$/i.test(file.path)) continue;
+    try {
+      for (const candidate of collectStringPaths(JSON.parse(file.text))) {
+        const normalized = candidate.value.replace(/^\//, '');
+        if (normalized === assetPath) {
+          references.push({ ownerPath: file.path, jsonPath: candidate.path, assetPath });
+        } else if (normalized.startsWith('assets/') && !byPath.has(normalized)) {
+          codes.add('broken-asset-reference');
+        }
+      }
+    } catch {}
+  }
+
+  if (codes.size === 0) codes.add('healthy');
+  const errorCodes = new Set<AssetHealthCode>([
+    'missing-file',
+    'missing-dependency',
+    'invalid-metadata',
+    'broken-asset-reference',
+  ]);
+  return {
+    health: {
+      status: [...codes].some((code) => errorCodes.has(code))
+        ? 'error'
+        : codes.has('healthy')
+          ? 'healthy'
+          : 'warning',
+      codes: [...codes],
+    },
+    dependencies,
+    references,
+  };
+}
+
+async function snapshotProjectFiles(
+  backend: StorageBackend,
+  dir = '',
+): Promise<ProjectAssetFileSnapshot[]> {
+  const entries = await backend.list(dir);
+  const snapshots: ProjectAssetFileSnapshot[] = [];
+  for (const entry of entries) {
+    const path = dir ? `${dir}/${entry.name}` : entry.name;
+    if (entry.type === 'dir') {
+      snapshots.push(...(await snapshotProjectFiles(backend, path)));
+    } else if (/\.json$|\.gltf$/i.test(path)) {
+      snapshots.push({ path, text: await backend.read(path) });
+    } else {
+      snapshots.push({ path });
+    }
+  }
+  return snapshots;
+}
+
+export async function inspectProjectAssetHealthFromStorage(
+  backend: StorageBackend,
+  assetPath: string,
+): Promise<ProjectAssetHealthResult> {
+  return inspectProjectAssetHealth({
+    assetPath,
+    files: await snapshotProjectFiles(backend),
+  });
+}

package/src/asset-workflow/project-asset-operations.ts

@@ -0,0 +1,154 @@
+import type { HistoryService } from '../history/history-service';
+import { getProjectFileHistory } from '../history/project-file-history';
+import type { StorageBackend } from '../storage/types';
+
+export type ProjectAssetOperation =
+  | { readonly type: 'create-folder'; readonly path: string }
+  | { readonly type: 'duplicate'; readonly source: string; readonly destination: string }
+  | { readonly type: 'move'; readonly source: string; readonly destination: string }
+  | {
+      readonly type: 'move-many';
+      readonly moves: readonly { readonly source: string; readonly destination: string }[];
+    }
+  | { readonly type: 'delete'; readonly paths: readonly string[] }
+  | { readonly type: 'import'; readonly files: readonly { path: string; bytes: Uint8Array }[] };
+
+/** Announce a project asset write. Every consumer of `editor:assets-changed`
+ *  keys off this — the panel listing, and the public-asset blob bridge that
+ *  makes a newly written file loadable by its own URL. Exported because
+ *  writes also happen OUTSIDE the operation union (the browser asset
+ *  library's own download path). */
+export function emitAssetMutation(detail: {
+  type: 'move' | 'delete' | 'change';
+  oldPath?: string;
+  newPath?: string;
+  paths?: readonly string[];
+}): void {
+  if (typeof window === 'undefined') return;
+  window.dispatchEvent(new CustomEvent('editor:asset-mutation', { detail }));
+  window.dispatchEvent(new CustomEvent('editor:assets-changed'));
+}
+
+function validPath(path: string): string {
+  const normalized = path
+    .replace(/^\/+/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/');
+  if (
+    !normalized ||
+    normalized === '.' ||
+    normalized.split('/').some((part) => !part || part === '..')
+  ) {
+    throw new Error(`Invalid project asset path: ${path}`);
+  }
+  return normalized;
+}
+
+async function assertDestinationsFree(backend: StorageBackend, paths: readonly string[]) {
+  for (const path of paths) {
+    if (await backend.exists(path)) throw new Error(`An asset already exists at ${path}.`);
+  }
+}
+
+/** Executes all writes through exact-byte project history; no UI owns filesystem mutation. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the tagged operation union is intentionally centralized so every project mutation shares one atomic history boundary.
+export async function executeProjectAssetOperation(
+  operation: ProjectAssetOperation,
+  dependencies: { readonly backend: StorageBackend; readonly history: HistoryService },
+): Promise<boolean> {
+  const files = getProjectFileHistory(dependencies.history, dependencies.backend);
+  switch (operation.type) {
+    case 'create-folder': {
+      const folder = validPath(operation.path);
+      const marker = `${folder}/.vgai-folder`;
+      if (await dependencies.backend.exists(folder))
+        throw new Error(`Folder already exists: ${folder}.`);
+      return files.write(marker, '', { label: `Create folder ${folder}` });
+    }
+    case 'duplicate': {
+      const source = validPath(operation.source);
+      const destination = validPath(operation.destination);
+      await assertDestinationsFree(dependencies.backend, [destination]);
+      const bytes = await dependencies.backend.readBytes(source);
+      return files.write(destination, bytes, { label: `Duplicate ${source}` });
+    }
+    case 'move': {
+      const source = validPath(operation.source);
+      const destination = validPath(operation.destination);
+      await assertDestinationsFree(dependencies.backend, [destination]);
+      const bytes = await dependencies.backend.readBytes(source);
+      const changes = new Map<string, string | Uint8Array | null>([
+        [destination, bytes],
+        [source, null],
+      ]);
+      const changed = await files.mutate(
+        [...changes].map(([path, data]) => ({ path, data })),
+        { label: `Move ${source}` },
+      );
+      if (changed) emitAssetMutation({ type: 'move', oldPath: source, newPath: destination });
+      return changed;
+    }
+    case 'move-many': {
+      const moves = operation.moves.map((move) => ({
+        source: validPath(move.source),
+        destination: validPath(move.destination),
+      }));
+      if (moves.length === 0) return false;
+      const sources = new Set(moves.map((move) => move.source));
+      const destinations = moves.map((move) => move.destination);
+      if (new Set(destinations).size !== destinations.length) {
+        throw new Error('Batch move destinations must be unique.');
+      }
+      for (const destination of destinations) {
+        if (!sources.has(destination) && (await dependencies.backend.exists(destination))) {
+          throw new Error(`An asset already exists at ${destination}.`);
+        }
+      }
+      const payloads = await Promise.all(
+        moves.map(async (move) => ({
+          ...move,
+          bytes: await dependencies.backend.readBytes(move.source),
+        })),
+      );
+      const changes = new Map<string, string | Uint8Array | null>();
+      for (const { destination, bytes } of payloads) changes.set(destination, bytes);
+      for (const { source } of payloads) {
+        if (!destinations.includes(source)) changes.set(source, null);
+      }
+      const changed = await files.mutate(
+        [...changes].map(([path, data]) => ({ path, data })),
+        { label: `Move ${moves.length} assets` },
+      );
+      if (changed) {
+        for (const move of moves) {
+          emitAssetMutation({ type: 'move', oldPath: move.source, newPath: move.destination });
+        }
+      }
+      return changed;
+    }
+    case 'delete': {
+      const paths = [...new Set(operation.paths.map(validPath))];
+      const changed = await files.mutate(
+        paths.map((path) => ({ path, data: null })),
+        { label: `Delete ${paths.length} asset${paths.length === 1 ? '' : 's'}` },
+      );
+      if (changed) emitAssetMutation({ type: 'delete', paths });
+      return changed;
+    }
+    case 'import': {
+      const imported = operation.files.map((file) => ({
+        path: validPath(file.path),
+        data: file.bytes,
+      }));
+      await assertDestinationsFree(
+        dependencies.backend,
+        imported.map((file) => file.path),
+      );
+      const changed = await files.mutate(imported, {
+        label: `Import ${imported.length} asset${imported.length === 1 ? '' : 's'}`,
+      });
+      if (changed) emitAssetMutation({ type: 'change', paths: imported.map((file) => file.path) });
+      return changed;
+    }
+  }
+}

package/src/asset-workflow/project-asset-roots.ts

@@ -0,0 +1,68 @@
+/**
+ * The asset ROOTS Content lists, and the one place a row's root plus its
+ * root-relative path becomes a project path or a URL.
+ *
+ * `public/` is the shipped game's assets; `references/` is reference material
+ * that lives in the project and is deliberately NOT shipped (see
+ * `@vgai/sdk/output-roots` for the writer's half of the same rule). Both are
+ * ordinary directories of ordinary files — there is no reference database, no
+ * import step, and no copy into `public/` to make something appear.
+ *
+ * Why a reference is addressed through `/project-game-static/`: that middleware
+ * (`vite-plugin-project-game-static.ts`) already serves the CURRENTLY OPEN
+ * project's own folder verbatim, which is exactly what a reference needs and
+ * exactly what `public/`'s root-relative URLs are not — a public asset's URL is
+ * `/<publicRelativePath>` because a shipped game addresses it that way, and
+ * giving references the same spelling would collide with the game's own paths.
+ * Nothing new is served; a reference simply uses the project-file route that
+ * already exists.
+ *
+ * `projectPathForAssetUrl` is the inverse: a bytes reader takes the URL a
+ * document or a tile already holds and asks THIS module which project file it
+ * names.
+ */
+
+export const REFERENCE_ROOT = 'references';
+
+/** A listable asset root. `public` is the default and the shipped one. */
+export type AssetRootId = 'public' | typeof REFERENCE_ROOT;
+
+export const ASSET_ROOTS: readonly AssetRootId[] = ['public', REFERENCE_ROOT];
+
+/** The URL prefix a reference is served under on the local editor server. */
+export const REFERENCE_URL_PREFIX = `/project-game-static/${REFERENCE_ROOT}/`;
+
+/** Project-root-relative path for a root + root-relative path. */
+export function projectAssetPath(root: AssetRootId, rootRelativePath: string): string {
+  return `${root}/${rootRelativePath}`;
+}
+
+/**
+ * The URL editor chrome, asset documents and the Inspector address this asset
+ * by. Public keeps its exact existing spelling (`/textures/crate.png`).
+ */
+export function assetRootServingUrl(root: AssetRootId, rootRelativePath: string): string {
+  return root === REFERENCE_ROOT
+    ? `${REFERENCE_URL_PREFIX}${rootRelativePath}`
+    : `/${rootRelativePath}`;
+}
+
+/** Is this URL/document path a reference rather than a public asset? */
+export function isReferenceAssetUrl(url: string): boolean {
+  return url.startsWith(REFERENCE_URL_PREFIX);
+}
+
+/**
+ * Which project file a serving URL names — the inverse of
+ * {@link assetRootServingUrl}, and the one mapping every bytes reader uses.
+ * A plain `/x.png` is a public asset, so it answers `public/x.png`, which is
+ * the rule those readers used to hardcode.
+ */
+export function projectPathForAssetUrl(url: string): string {
+  const servingUrl = url.startsWith('/') ? url : `/${url}`;
+  if (isReferenceAssetUrl(servingUrl)) {
+    return projectAssetPath(REFERENCE_ROOT, servingUrl.slice(REFERENCE_URL_PREFIX.length));
+  }
+  const withoutSlash = url.startsWith('/') ? url.slice(1) : url;
+  return withoutSlash.startsWith('public/') ? withoutSlash : `public/${withoutSlash}`;
+}