@volter/editor-core 0.5.57

package/src/asset-workflow/asset-ledger-backend.ts

@@ -0,0 +1,126 @@
+/**
+ * `StorageBackend` side of the asset provenance ledger (D-AP3) — the
+ * browser/isomorphic sibling of `packages/editor/server/asset-ledger-store.ts`,
+ * which reads/writes `.vgai/assets.json` via `node:fs` for the local
+ * (HttpStorage-backed) Node editor. Every environment materializes through the
+ * SAME record shape (`../asset-workflow/asset-ledger.ts`'s pure schema) — only
+ * the I/O side differs, exactly like `storage/seed.ts`'s `readProjectManifest`
+ * reading `vgai.project.json` through a `StorageBackend` instead of `node:fs`.
+ *
+ * Used by `hosted-asset-materialization.ts` (D-AP4 — a project's declared
+ * packs).
+ *
+ * Concurrency: the same two-half protection the Node side takes, over this
+ * side's I/O (see `./ledger-write-lock.ts`). The in-realm chain covers one tab
+ * — several declared entries materializing in one pass, the Library panel and a
+ * reopen retry overlapping — and the `.lock` file covers the case only another
+ * realm can see: two tabs open on the same project, both retrying their
+ * declared packs. `writeIfAbsent` is honest about not being O_EXCL on
+ * handle APIs (it "serializes same-origin writers and rechecks at handle
+ * acquisition"), which is exactly the guarantee that matters here — the racing
+ * writers ARE same-origin — so it is the strongest primitive available and not
+ * a claim of more.
+ */
+
+import { withPathLock } from '../storage/path-lock';
+import type { StorageBackend } from '../storage/types';
+import {
+  ASSET_LEDGER_PATH,
+  type AssetLedger,
+  type AssetLedgerEntry,
+  normalizeLedgerPath,
+  parseAssetLedgerJson,
+  serializeAssetLedger,
+  sourceHashFromSha256,
+  upsertAssetLedgerEntry,
+} from './asset-ledger';
+import { createSerializer, withExclusiveLock } from './ledger-write-lock';
+
+/** Read the ledger via `backend`. Absent → `{}`. Corrupt → throws (same
+ *  contract as the Node `asset-ledger-store.ts` — a provenance record that
+ *  silently drops entries is worse than no record). */
+export async function readAssetLedgerFromBackend(backend: StorageBackend): Promise<AssetLedger> {
+  if (!(await backend.exists(ASSET_LEDGER_PATH))) return {};
+  return parseAssetLedgerJson(await backend.read(ASSET_LEDGER_PATH));
+}
+
+export async function writeAssetLedgerToBackend(
+  backend: StorageBackend,
+  ledger: AssetLedger,
+): Promise<void> {
+  await backend.write(ASSET_LEDGER_PATH, serializeAssetLedger(ledger));
+}
+
+export interface BackendMaterializationRecord {
+  /** Project-relative destination, e.g. `public/asset-library/local/x/y.glb`. */
+  readonly destPath: string;
+  /** `source:id` — the library's identity for this asset. */
+  readonly key: string;
+  /** License string as the library reported it, if it reported one. */
+  readonly license?: string | undefined;
+  /** The LIBRARY's sha256 of the source bytes. Omit when the library has
+   *  none — never substitute a hash of the bytes just written (anti-shim). */
+  readonly sourceSha256?: string | undefined;
+  readonly materializedAt?: string;
+}
+
+const LEDGER_LOCK_PATH = `${ASSET_LEDGER_PATH}.lock`;
+const serializeLedgerWrite = createSerializer();
+/** Stable per-backend key for the in-realm chain (`backend.id` is shared by
+ *  every instance of a backend TYPE, so it cannot key this on its own). */
+const backendKeys = new WeakMap<StorageBackend, string>();
+let nextBackendKey = 0;
+
+function ledgerWriteKey(backend: StorageBackend): string {
+  const existing = backendKeys.get(backend);
+  if (existing !== undefined) return existing;
+  nextBackendKey += 1;
+  const key = `${backend.id}#${nextBackendKey}`;
+  backendKeys.set(backend, key);
+  return key;
+}
+
+/** Record one materialization in the project's ledger, via `backend`. */
+export async function recordAssetMaterializationInBackend(
+  backend: StorageBackend,
+  record: BackendMaterializationRecord,
+): Promise<void> {
+  const entry: AssetLedgerEntry = {
+    key: record.key,
+    ...(record.license ? { license: record.license } : {}),
+    ...(record.sourceSha256 ? { sourceHash: sourceHashFromSha256(record.sourceSha256) } : {}),
+    materializedAt: record.materializedAt ?? new Date().toISOString(),
+  };
+  await serializeLedgerWrite(ledgerWriteKey(backend), () =>
+    withExclusiveLock(
+      {
+        createIfAbsent: (content) => backend.writeIfAbsent(LEDGER_LOCK_PATH, content),
+        read: async () =>
+          (await backend.exists(LEDGER_LOCK_PATH)) ? backend.read(LEDGER_LOCK_PATH) : null,
+        // Compare-and-delete (see `./ledger-write-lock.ts`'s `ExclusiveLockIO`),
+        // and its three steps must not interleave with another realm's — so
+        // they run under the SAME path lock `HandleStorage.writeIfAbsent` takes
+        // (`../storage/path-lock.ts`). That makes this side genuinely atomic
+        // against every same-origin tab, so it needs no `rename` takeover
+        // like the `node:fs` side.
+        // NOT covered: `HttpStorage`, whose peer writer is the Node server/CLI
+        // rather than another tab — Web Locks cannot reach a separate process,
+        // and neither can anything else available in the page.
+        removeIfHeldBy: (expected) =>
+          withPathLock(backend.id, LEDGER_LOCK_PATH, async () => {
+            if (!(await backend.exists(LEDGER_LOCK_PATH))) return;
+            if ((await backend.read(LEDGER_LOCK_PATH)) !== expected) return;
+            await backend.remove(LEDGER_LOCK_PATH);
+          }),
+      },
+      async () => {
+        const ledger = await readAssetLedgerFromBackend(backend);
+        await writeAssetLedgerToBackend(
+          backend,
+          upsertAssetLedgerEntry(ledger, normalizeLedgerPath(record.destPath), entry),
+        );
+      },
+      { owner: backend.id },
+    ),
+  );
+}

package/src/asset-workflow/asset-ledger.ts

@@ -0,0 +1,156 @@
+/**
+ * The project-owned asset provenance ledger — `.vgai/assets.json` (D-AP3).
+ *
+ * Assets follow the capability model: the asset library is the SOURCE, a
+ * project owns its COPIES. Every materialization — the editor's Library-panel
+ * download, the template/example `asset-packs:sync` script, the hosted seed —
+ * records the copy here, keyed by PROJECT-RELATIVE destination path.
+ *
+ * One ledger, not per-file sidecars: sidecars pollute asset directories and
+ * break tooling that globs them.
+ *
+ * The ledger is the license/attribution record and the drift input. Comparing a
+ * file's current hash to `sourceHash` distinguishes "the user edited their copy"
+ * (legitimate; git reports it) from "the library moved" (reported, never
+ * auto-applied — there is deliberately no `vgai asset update`).
+ *
+ * ANTI-SHIM: `license` and `sourceHash` are OPTIONAL and are recorded only when
+ * the library actually supplied them. We never hash the bytes we just wrote and
+ * call the result a `sourceHash` — that would make every copy look pristine
+ * forever and destroy the drift signal the field exists for. A materialization
+ * path with no library-supplied hash records the key and the timestamp and
+ * nothing else. Today that is the polyhaven/ambientcg remote proxy, whose
+ * upstream APIs publish no per-file digest; the local/cloud catalog paths
+ * (34,412 assets) carry `sha256` and populate the field.
+ */
+
+import { isContainedRelativePath } from '@volter/editor-sdk/session/relative-path-guard';
+import { z } from 'zod';
+
+/** Project-relative location of the ledger. */
+export const ASSET_LEDGER_PATH = '.vgai/assets.json';
+
+/** The library's asset identity: `source:id` (see `onlineAssetKey`). */
+export function assetKey(source: string, id: string): string {
+  return `${source}:${id}`;
+}
+
+export const AssetLedgerEntrySchema = z
+  .object({
+    /** `source:id` — the library's own identity for the asset. */
+    key: z.string().min(1),
+    /** SPDX-ish license string as the library reported it, when it reported one. */
+    license: z.string().min(1).optional(),
+    /** The LIBRARY's digest of the source bytes — never a re-hash of our copy. */
+    sourceHash: z
+      .string()
+      .regex(/^sha256-[a-f0-9]{64}$/, 'sourceHash must be "sha256-<64 hex>"')
+      .optional(),
+    /** ISO-8601 instant the copy was written into this project. */
+    materializedAt: z.string().datetime(),
+  })
+  .strict();
+
+export const AssetLedgerSchema = z.record(z.string().min(1), AssetLedgerEntrySchema);
+
+export type AssetLedgerEntry = z.infer<typeof AssetLedgerEntrySchema>;
+export type AssetLedger = Record<string, AssetLedgerEntry>;
+
+/** Format a raw hex digest as the ledger's `sourceHash`. Rejects non-digests
+ *  loudly rather than storing something that only looks like a hash. */
+export function sourceHashFromSha256(sha256: string): string {
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw new Error(`Not a sha256 digest, refusing to record it as a sourceHash: ${sha256}`);
+  }
+  return `sha256-${sha256}`;
+}
+
+/** The raw hex digest inside a `sha256-…` sourceHash, or null for other forms. */
+export function sha256FromSourceHash(sourceHash: string): string | null {
+  const match = /^sha256-([a-f0-9]{64})$/.exec(sourceHash);
+  return match?.[1] ?? null;
+}
+
+/** Normalize a ledger key: project-relative, forward slashes, no leading `./`. */
+export function normalizeLedgerPath(path: string): string {
+  const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^\/+/, '');
+  if (!normalized) throw new Error('An asset ledger path cannot be empty.');
+  if (!isContainedRelativePath(normalized)) {
+    throw new Error(`An asset ledger path cannot escape the project: ${path}`);
+  }
+  return normalized;
+}
+
+/** Parse a ledger document. Throws (loudly) on anything malformed — a
+ *  provenance record that silently drops entries is worse than no record. */
+export function parseAssetLedger(input: unknown): AssetLedger {
+  return AssetLedgerSchema.parse(input);
+}
+
+/** Parse ledger JSON text; an absent ledger is `{}`, a CORRUPT one throws. */
+export function parseAssetLedgerJson(text: string | null | undefined): AssetLedger {
+  if (text == null || text.trim() === '') return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new Error(`${ASSET_LEDGER_PATH} is not valid JSON: ${String(cause)}`);
+  }
+  return parseAssetLedger(parsed);
+}
+
+/** Record one materialization. Pure: returns a new, key-sorted ledger. */
+export function upsertAssetLedgerEntry(
+  ledger: AssetLedger,
+  destPath: string,
+  entry: AssetLedgerEntry,
+): AssetLedger {
+  const key = normalizeLedgerPath(destPath);
+  const validated = AssetLedgerEntrySchema.parse(entry);
+  const merged: AssetLedger = { ...ledger, [key]: validated };
+  const sorted: AssetLedger = {};
+  for (const path of Object.keys(merged).sort()) sorted[path] = merged[path]!;
+  return sorted;
+}
+
+/** Serialize for disk — stable key order, trailing newline. */
+export function serializeAssetLedger(ledger: AssetLedger): string {
+  const sorted: AssetLedger = {};
+  for (const path of Object.keys(ledger).sort()) sorted[path] = ledger[path]!;
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+
+export type AssetLedgerDrift =
+  | { readonly status: 'untracked' }
+  | { readonly status: 'unknown-source-hash' }
+  | { readonly status: 'pristine' }
+  | {
+      readonly status: 'edited-locally';
+      readonly sourceHash: string;
+      readonly currentHash: string;
+    };
+
+/**
+ * Classify one copy against its ledger entry. `currentHash` is the sha256 of
+ * the bytes on disk RIGHT NOW.
+ *
+ * This deliberately cannot tell "user edited" from "library moved" on its own —
+ * both show as a hash difference. The ledger supplies one half (what we copied);
+ * re-reading the library supplies the other. Callers that have not consulted the
+ * library must report `edited-locally` as "differs from what was materialized",
+ * never as "the library moved".
+ */
+export function classifyAssetLedgerDrift(
+  ledger: AssetLedger,
+  destPath: string,
+  currentSha256: string,
+): AssetLedgerDrift {
+  const entry = ledger[normalizeLedgerPath(destPath)];
+  if (!entry) return { status: 'untracked' };
+  if (!entry.sourceHash) return { status: 'unknown-source-hash' };
+  const expected = sha256FromSourceHash(entry.sourceHash);
+  if (expected === null) return { status: 'unknown-source-hash' };
+  return expected === currentSha256
+    ? { status: 'pristine' }
+    : { status: 'edited-locally', sourceHash: expected, currentHash: currentSha256 };
+}

package/src/asset-workflow/asset-materialization-report.ts

@@ -0,0 +1,140 @@
+/**
+ * The FAILURE CHANNEL for declared-asset-pack materialization (D-AP4):
+ * *"Failure = loud degradation, not fabrication. ... the missing asset is
+ * reported in the editor console + status surface with a retry affordance, and
+ * dependent features degrade honestly."*
+ *
+ * `materializeDeclaredAssetPacks` already fails closed per entry — it never
+ * writes placeholder bytes and never blocks the other entries — but it only
+ * RETURNS a `failed` array, and an array with no reader is the hazard: a seed
+ * that lands without its clips would look like a working editor with a
+ * mysteriously dead animation, which is the worst possible outcome and
+ * precisely what the anti-shim rule forbids.
+ *
+ * This module is that reader, and it is deliberately TWO channels, because
+ * neither alone is enough — D-AP4's own words, *"reported in the editor
+ * console + status surface with a retry affordance"*:
+ *
+ *   1. `editorConsole.error` — one line per failed entry, subsystem `assets`,
+ *      naming the library key, the destination path, the reason, and what
+ *      degrades.
+ *   2. A module-level report slot the status bar's `asset-materialization`
+ *      contribution reads (`../components/status-contributions.tsx`),
+ *      carrying the RETRY affordance. Retry re-runs materialization against
+ *      the active backend, which is safe and cheap by construction: the
+ *      materializer skips every entry already in the ledger, so a retry only
+ *      refetches what is still missing.
+ *
+ * That status item used to be a red banner across the top of the shell. The
+ * editor has ONE error home — console line, bottom-left status item, the
+ * Console utility behind it — and a second one only taught users two places
+ * to look, so the banner is gone.
+ *
+ * Same plain module-singleton + own-`subscribe` shape as
+ * `../authoring/mount-failure-report.ts`.
+ */
+
+import { editorConsole } from '../editor-console';
+import type { StorageBackend } from '../storage/types';
+import type { AssetPackMaterializationResult } from './hosted-asset-materialization';
+
+/** One declared pack entry that did not materialize — the exact fields both
+ *  channels show. Flattened out of `AssetPackMaterializationFailure` so the
+ *  banner never has to know the materializer's own types. */
+export interface AssetMaterializationFailure {
+  /** Library key, `source:id` (e.g. `local:a7c5288306d9e98cb7dbdbd2`). */
+  readonly key: string;
+  /** Project-relative destination the bytes were meant to land at. */
+  readonly dest: string;
+  /** Declaring pack name from `asset-manifest.json`. */
+  readonly pack: string;
+  /** The materializer's own reason string — never fabricated, never softened. */
+  readonly reason: string;
+}
+
+let _failures: readonly AssetMaterializationFailure[] = [];
+const _listeners = new Set<() => void>();
+
+/** `useSyncExternalStore`-compatible subscribe for the banner. */
+export function subscribeToAssetMaterializationFailures(callback: () => void): () => void {
+  _listeners.add(callback);
+  return () => _listeners.delete(callback);
+}
+
+/** Every declared entry that failed to materialize, in declaration order. */
+export function getAssetMaterializationFailures(): readonly AssetMaterializationFailure[] {
+  return _failures;
+}
+
+/** Clear the slot (the banner's dismiss). Does not retry. */
+export function clearAssetMaterializationFailures(): void {
+  _failures = [];
+  notify();
+}
+
+function notify(): void {
+  for (const listener of _listeners) listener();
+}
+
+/**
+ * The message BOTH channels use, so the console line and the banner row can
+ * never drift apart. Names the key, the destination and the reason, then says
+ * what degrades — a reader who sees only this line knows what is broken and
+ * what it costs them.
+ */
+export function formatAssetMaterializationFailure(failure: AssetMaterializationFailure): string {
+  return (
+    `Starter asset "${failure.key}" (pack "${failure.pack}") did not materialize into ` +
+    `${failure.dest}: ${failure.reason} Nothing was written for it — features that read ` +
+    'that file degrade (a missing clips GLB leaves the character standing without ' +
+    'locomotion clips). Use Retry once the cause is fixed.'
+  );
+}
+
+/**
+ * Report a materialization result through both channels. Called by every
+ * production materialization site (today: `../storage/seed.ts`'s
+ * `seedIfEmpty`) so no caller can forget to read `failed`.
+ *
+ * A result with no failures CLEARS the slot: that is what makes a successful
+ * retry dismiss its own banner.
+ */
+export function reportAssetMaterialization(result: AssetPackMaterializationResult): void {
+  const failures = result.failed.map((failure) => ({
+    key: failure.entry.key,
+    dest: failure.entry.dest,
+    pack: failure.entry.pack,
+    reason: failure.reason,
+  }));
+  for (const failure of failures) {
+    editorConsole.error(formatAssetMaterializationFailure(failure), 'assets');
+  }
+  _failures = failures;
+  notify();
+}
+
+/**
+ * Re-run materialization against `backend` and re-report. Retry-safe by
+ * construction (the materializer skips ledger-present entries), so this
+ * refetches only what is still missing.
+ *
+ * A THROW here is the manifest itself being unreadable/invalid — not a
+ * per-entry failure — so it degrades through the console too rather than
+ * becoming an unhandled rejection in a click handler.
+ */
+export async function retryAssetMaterialization(backend: StorageBackend): Promise<void> {
+  try {
+    // Lazy for the same reason the seed's call is: the materializer is the
+    // heaviest thing this report knows, and only the retry needs it.
+    const { materializeDeclaredAssetPacks } = await import('./hosted-asset-materialization');
+    const result = await materializeDeclaredAssetPacks(backend);
+    reportAssetMaterialization(result);
+  } catch (error) {
+    editorConsole.error(
+      `Retrying asset materialization failed before any entry was attempted: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      'assets',
+    );
+  }
+}