@drawnagency/primitives 0.1.114 → 0.1.116

package/dist/storage/memory.d.ts

@@ -0,0 +1,21 @@
+import { type StorageProvider } from "./types";
+type Files = Record<string, string | Uint8Array | null>;
+export type MemoryStorage = StorageProvider & {
+    /**
+     * Commit straight to a branch as another writer would — a concurrent editor
+     * save on the draft (created from main if absent), or a merge onto main.
+     * Returns the new commit's sha.
+     */
+    commit(branch: "main" | "draft", files: Files, message?: string): string;
+    /**
+     * Run `fn` once at the start of the next `writeFiles`, before its
+     * `baseVersion` check: a writer landing between a caller's read and its write.
+     */
+    beforeNextWrite(fn: () => void): void;
+};
+export declare function createMemoryStorage(seed?: {
+    main?: Files;
+    draft?: Files;
+}): MemoryStorage;
+export {};
+//# sourceMappingURL=memory.d.ts.map

package/dist/storage/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/storage/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAWjB,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;AAMxD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG;IAC5C;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzE;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACvC,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAO,GAAG,aAAa,CAoI7F"}

package/dist/storage/memory.js

@@ -0,0 +1,129 @@
+import {
+  IDEMPOTENCY_TRAILER,
+  NothingToPublishError,
+  StorageConflictError
+} from "../chunk-UUUSJDIG.js";
+import "../chunk-JSBRDJBE.js";
+
+// src/storage/memory.ts
+var PUBLISHED_PREFIXES = ["src/content/", "assets/"];
+function createMemoryStorage(seed = {}) {
+  const commits = /* @__PURE__ */ new Map();
+  let counter = 0;
+  let mainHead;
+  let draftHead = null;
+  let pendingHook = null;
+  function newCommit(tree, parent, message) {
+    counter += 1;
+    const sha = counter.toString(16).padStart(40, "0");
+    commits.set(sha, { tree, parent, message });
+    return sha;
+  }
+  function applyFiles(base, files) {
+    const tree = new Map(base);
+    for (const [path, content] of Object.entries(files)) {
+      if (content === null) tree.delete(path);
+      else tree.set(path, toBytes(content));
+    }
+    return tree;
+  }
+  function commitTo(branch, files, message = "commit") {
+    if (branch === "main") {
+      mainHead = newCommit(applyFiles(commits.get(mainHead).tree, files), mainHead, message);
+      return mainHead;
+    }
+    const parent = draftHead ?? mainHead;
+    draftHead = newCommit(applyFiles(commits.get(parent).tree, files), parent, message);
+    return draftHead;
+  }
+  function treeFor(options) {
+    if (options?.at !== void 0) return commits.get(options.at)?.tree ?? null;
+    if (options?.draft) return draftHead === null ? null : commits.get(draftHead).tree;
+    return commits.get(mainHead).tree;
+  }
+  function checkBase(options) {
+    if (options && "baseVersion" in options) {
+      const expected = options.baseVersion ?? null;
+      if (expected !== draftHead) throw new StorageConflictError(draftHead);
+    }
+  }
+  mainHead = newCommit(applyFiles(/* @__PURE__ */ new Map(), seed.main ?? {}), null, "initial");
+  if (seed.draft) commitTo("draft", seed.draft, "seed draft");
+  return {
+    commit: commitTo,
+    beforeNextWrite(fn) {
+      pendingHook = fn;
+    },
+    async writeFiles(files, message, options) {
+      const hook = pendingHook;
+      pendingHook = null;
+      hook?.();
+      checkBase(options);
+      if (files.length === 0) return { version: draftHead ?? mainHead };
+      const parentTree = commits.get(draftHead ?? mainHead).tree;
+      const changes = {};
+      for (const file of files) {
+        if (file.content === null && !parentTree.has(file.path)) {
+          throw new Error(`Cannot delete ${file.path}: it is not on the branch`);
+        }
+        changes[file.path] = file.content === null || file.content instanceof Uint8Array || file.encoding !== "base64" ? file.content : fromBase64(file.content);
+      }
+      return { version: commitTo("draft", changes, message) };
+    },
+    async readFile(path, options) {
+      return treeFor(options)?.get(path) ?? null;
+    },
+    async listDirectory(path, options) {
+      const tree = treeFor(options);
+      if (!tree) return [];
+      const prefix = path.endsWith("/") ? path : `${path}/`;
+      const names = [];
+      for (const key of tree.keys()) {
+        if (!key.startsWith(prefix)) continue;
+        const rest = key.slice(prefix.length);
+        if (!rest.includes("/")) names.push(rest);
+      }
+      return names;
+    },
+    async getVersion() {
+      return mainHead;
+    },
+    async getDraftVersion() {
+      return draftHead;
+    },
+    async promoteDraft() {
+      if (draftHead === null) throw new NothingToPublishError();
+      const draft = commits.get(draftHead).tree;
+      const main = commits.get(mainHead).tree;
+      const published = (p) => PUBLISHED_PREFIXES.some((prefix) => p.startsWith(prefix));
+      if (![...draft.keys(), ...main.keys()].some(published)) {
+        throw new Error("No editor-managed content found on the saved branch \u2014 refusing to publish.");
+      }
+      const tree = new Map([...main].filter(([p]) => !published(p)));
+      for (const [p, bytes] of draft) if (published(p)) tree.set(p, bytes);
+      mainHead = newCommit(tree, mainHead, "Publish content via Brand Portal");
+      draftHead = null;
+      return { version: mainHead };
+    },
+    async findCommitByIdempotencyKey(key, options) {
+      const limit = Math.min(Math.max(options?.limit ?? 30, 1), 100);
+      const trailer = `${IDEMPOTENCY_TRAILER}: ${key}`;
+      let sha = draftHead;
+      for (let seen = 0; sha !== null && seen < limit; seen += 1) {
+        const commit = commits.get(sha);
+        if (commit.message.split("\n").some((line) => line.trim() === trailer)) return sha;
+        sha = commit.parent;
+      }
+      return null;
+    }
+  };
+}
+function toBytes(content) {
+  return typeof content === "string" ? new TextEncoder().encode(content) : content;
+}
+function fromBase64(content) {
+  return Uint8Array.from(atob(content), (c) => c.charCodeAt(0));
+}
+export {
+  createMemoryStorage
+};

package/dist/storage/types.d.ts

@@ -25,13 +25,22 @@ export interface StorageProvider {
     }>;
     readFile(path: string, options?: {
         draft?: boolean;
+        at?: string;
     }): Promise<Uint8Array | null>;
     promoteDraft(): Promise<{
         version: string;
     }>;
+    /** The published branch's head. Never a valid `baseVersion`. */
     getVersion(): Promise<string>;
+    /**
+     * The draft branch's head, or null when no draft exists — exactly the value
+     * `writeFiles` accepts as `baseVersion`.
+     */
+    getDraftVersion(): Promise<string | null>;
+    /** File basenames directly under `path` (no subdirectories); `[]` when absent. Same options as `readFile`. */
     listDirectory(path: string, options?: {
         draft?: boolean;
+        at?: string;
     }): Promise<string[]>;
     /**
      * Find a recent commit on the draft branch whose message carries the given

package/dist/storage/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawnagency/primitives",
-  "version": "0.1.114",
+  "version": "0.1.116",
   "description": "Browser-safe foundation of the Brand Portal framework: Zod schemas, section components, editor shell, hooks, pure libs, collab contract, document engine.",
   "type": "module",
   "exports": {
@@ -81,6 +81,22 @@
       "types": "./dist/lib/registry.d.ts",
       "default": "./dist/lib/registry.js"
     },
+    "./lib/storage-tier": {
+      "types": "./dist/lib/storage-tier.d.ts",
+      "default": "./dist/lib/storage-tier.js"
+    },
+    "./lib/image-variant-plan": {
+      "types": "./dist/lib/image-variant-plan.d.ts",
+      "default": "./dist/lib/image-variant-plan.js"
+    },
+    "./lib/media-ops": {
+      "types": "./dist/lib/media-ops.d.ts",
+      "default": "./dist/lib/media-ops.js"
+    },
+    "./lib/sidecars": {
+      "types": "./dist/lib/sidecars.d.ts",
+      "default": "./dist/lib/sidecars.js"
+    },
     "./lib/index-ops": {
       "types": "./dist/lib/index-ops.d.ts",
       "default": "./dist/lib/index-ops.js"
@@ -89,6 +105,18 @@
       "types": "./dist/lib/reference-validation.d.ts",
       "default": "./dist/lib/reference-validation.js"
     },
+    "./lib/section-check": {
+      "types": "./dist/lib/section-check.d.ts",
+      "default": "./dist/lib/section-check.js"
+    },
+    "./lib/site-validation": {
+      "types": "./dist/lib/site-validation.d.ts",
+      "default": "./dist/lib/site-validation.js"
+    },
+    "./lib/document-refs": {
+      "types": "./dist/lib/document-refs.d.ts",
+      "default": "./dist/lib/document-refs.js"
+    },
     "./lib/deck-access": {
       "types": "./dist/lib/deck-access.d.ts",
       "default": "./dist/lib/deck-access.js"
@@ -165,6 +193,10 @@
       "types": "./dist/storage/index.d.ts",
       "default": "./dist/storage/index.js"
     },
+    "./storage/memory": {
+      "types": "./dist/storage/memory.d.ts",
+      "default": "./dist/storage/memory.js"
+    },
     "./types/database": {
       "types": "./dist/types/database.d.ts",
       "default": "./dist/types/database.js"
@@ -193,6 +225,7 @@
     "clsx": "^2.1.1",
     "dexie": "^4.4.2",
     "dompurify": "^3.2.6",
+    "entities": "^6.0.1",
     "jose": "^6.2.2",
     "lucide-react": "^1.7.0",
     "marked": "^18.0.5",

package/src/collab/rebase.ts

@@ -4,9 +4,7 @@
 import type { LoadedSection } from "../lib/loader";
 import type { SiteIndex } from "../schemas/site-config";
 import { IndexSchema } from "../schemas/site-config";
-import { NavFileSchema } from "../schemas/nav";
-import { TagsFileSchema } from "../schemas/tags";
-import { mergeTags } from "../lib/tags";
+import { liftSidecars, NAV, TAGS } from "../lib/sidecars";
 
 export interface RebaseArgs {
   localSections: LoadedSection[];
@@ -110,19 +108,17 @@ export function reconcileRemoteIndex(remoteIndex: SiteIndex, localIndex: SiteInd
  *  intact rather than flattening it. The `tags` sidecar is lifted the same way,
  *  for the same reason. */
 export function applyRemoteIndexUpdate(rawRemoteIndex: unknown, localIndex: SiteIndex): SiteIndex | null {
-  const rawNav = (rawRemoteIndex as { nav?: unknown } | null | undefined)?.nav;
-  const rawTags = (rawRemoteIndex as { tags?: unknown } | null | undefined)?.tags;
+  const lifted = liftSidecars(rawRemoteIndex);
+  // safeParse, not parse: this arrives off the network, and a throw inside a
+  // collab callback would take down the session rather than one bad message.
   const parsed = IndexSchema.safeParse(rawRemoteIndex);
   if (!parsed.success) return null;
 
-  // safeParse, not parse: this arrives off the network, and a throw inside a
-  // collab callback would take down the session rather than one bad message.
-  const parsedNav = rawNav === undefined ? null : NavFileSchema.safeParse({ entries: rawNav });
-  const nav = parsedNav?.success ? parsedNav.data.entries : localIndex.nav;
-  // Tags get the identical lift. Their section ids are not pruned to our index
-  // here — siteTags reconciles on read, and the next tags write reconciles too.
-  const parsedTags = rawTags === undefined ? null : TagsFileSchema.safeParse({ tags: rawTags });
-  const tags = parsedTags?.success ? parsedTags.data.tags : localIndex.tags;
+  // A peer's Degraded read is never adopted: installing a lossy tree would arm
+  // our next save to write it over the file. Tags' section ids are not pruned
+  // to our index here — siteTags reconciles on read, and tags writes reconcile.
+  const nav = lifted.nav && !lifted.nav.degraded ? lifted.nav.entries : localIndex.nav;
+  const tags = lifted.tags && !lifted.tags.degraded ? lifted.tags.entries : localIndex.tags;
 
   const reconciled = reconcileRemoteIndex(parsed.data, localIndex);
   return {
@@ -237,16 +233,16 @@ export function rebaseContent(args: RebaseArgs): RebaseResult {
   // conflict dialog, so persisted-beats-unsaved is the safe rule. A remote with
   // no nav (an older server that doesn't attach the sidecar) leaves ours intact
   // rather than flattening it; readers repair any drift via reconcileNav.
-  const nav = args.remoteIndex.nav !== undefined ? args.remoteIndex.nav : args.localIndex.nav;
+  const nav = NAV.rebase({ base: args.baselineIndex?.nav, local: args.localIndex.nav, remote: args.remoteIndex.nav });
   if (nav !== undefined) index = { ...index, nav };
 
-  // Tags: three-way, not nav's "persisted wins" — see mergeTags for why and for
+  // Tags: three-way, not nav's "persisted wins" — see TAGS.rebase (mergeTags) for why and for
   // the exact rules. Only the dirty branch merges: the clean branch above took
   // the remote's tags as-is, including their absence from an older server,
   // which leaves tags unloaded (so no write touches tags.json) rather than
   // reviving a local copy nothing local edited.
   if (args.localIndexDirty) {
-    const tags = mergeTags({ base: args.baselineIndex?.tags, local: args.localIndex.tags, remote: args.remoteIndex.tags });
+    const tags = TAGS.rebase({ base: args.baselineIndex?.tags, local: args.localIndex.tags, remote: args.remoteIndex.tags });
     // undefined only when neither local nor remote carries tags, in which case
     // the localIndex-derived index above carries none either.
     if (tags !== undefined) index = { ...index, tags };

package/src/components/shell/EditorShell.tsx

@@ -689,6 +689,7 @@ export default function EditorShell({
           media: remote.mediaManifest ?? mediaManifestRef.current,
           documents: remote.documentManifest ?? documentManifestRef.current ?? {},
         },
+        remote.tagsDegraded,
         {
           savedBranchSha: remote.savedBranchSha,
           changedSectionIds: remote.changedSectionIds,
@@ -775,6 +776,7 @@ export default function EditorShell({
       }
       setSections(result.sections);
       setSiteIndex(result.index);
+      setTagsDegraded(remote.tagsDegraded);
       setSavedSha(remote.savedBranchSha);
       setChangedSectionIds(new Set(remote.changedSectionIds));
       setMainIndex(remote.mainIndex);
@@ -800,6 +802,7 @@ export default function EditorShell({
           media: remote.mediaManifest ?? mediaManifestRef.current,
           documents: remote.documentManifest ?? documentManifestRef.current ?? {},
         },
+        remote.tagsDegraded,
         {
           savedBranchSha: remote.savedBranchSha,
           changedSectionIds: remote.changedSectionIds,
@@ -957,6 +960,7 @@ export default function EditorShell({
     clearConfigDirty: persistence.clearConfigDirty,
     siteIndexRef,
     siteConfig,
+    tagsDegraded,
     sections,
     deletedSectionIds: Array.from(deletedSections),
     onSaveWarnings: setSaveWarnings,
@@ -1069,6 +1073,7 @@ export default function EditorShell({
         // onMediaPublished / onDocumentsPublished callbacks only refresh through a
         // state effect and can still lag by a render at this point.
         { media: committedManifest, documents: committedDocumentManifest },
+        tagsDegraded,
         {
           savedBranchSha: sha,
           changedSectionIds: [...changed],
@@ -1318,12 +1323,10 @@ export default function EditorShell({
         loadedIndex = data.index;
         loadedConfig = SiteConfigSchema.parse(data.siteConfig);
         if (data.mediaManifest) loadedManifest = data.mediaManifest;
-        // A degraded tags read is cached as "not loaded", so a later cache-hit
-        // load stays read-only for tags instead of trusting the partial list.
-        const { tags: _partialTags, ...untaggedIndex } = data.index;
         await cacheContent(
-          data.sha, data.sections, data.tagsDegraded ? untaggedIndex : data.index, data.siteConfig,
+          data.sha, data.sections, data.index, data.siteConfig,
           { media: loadedManifest, documents: data.documentManifest ?? {} },
+          data.tagsDegraded,
           {
             savedBranchSha: data.savedBranchSha,
             changedSectionIds: data.changedSectionIds,

package/src/hooks/useEditorPublish.ts

@@ -10,6 +10,7 @@ import { getDirtySectionRows, hasLocalChanges, discardSavedChanges, cacheContent
 import { packUploads, packDocumentUploads, type MediaUploadPayload, type DocumentUploadPayload } from "../lib/save-chunks";
 import type { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
 import { assembleSavedManifest } from "../lib/media-folders";
+import { imageVariantPath } from "../lib/image-variant-plan";
 import { buildCommittedBaseline } from "../collab/recovery";
 
 function blobToBase64(blob: Blob): Promise<string> {
@@ -63,6 +64,9 @@ interface PublishDeps {
   clearConfigDirty: () => void;
   siteIndexRef: React.RefObject<SiteIndex>;
   siteConfig: SiteConfig | null;
+  /** This session's tags read was degraded; the cache re-primes record tags
+   *  as not loaded (see cacheContent). */
+  tagsDegraded: boolean;
   sections: LoadedSection[];
   deletedSectionIds?: string[];
   /** Receives the ids that were actually committed this save (so the caller can
@@ -148,6 +152,7 @@ export function useEditorPublish({
   clearConfigDirty,
   siteIndexRef,
   siteConfig,
+  tagsDegraded,
   sections,
   deletedSectionIds,
   onSuccess,
@@ -208,7 +213,7 @@ export function useEditorPublish({
           const ext = mimeExt[item.mimeType] ?? "bin";
           blobPayloads.push({ path: `assets/images/${item.folder}/original.${ext}`, base64 });
         } else {
-          blobPayloads.push({ path: `assets/images/${item.folder}/${key}.webp`, base64 });
+          blobPayloads.push({ path: imageVariantPath(item.folder, key), base64 });
         }
       }
 
@@ -815,7 +820,7 @@ export function useEditorPublish({
           await cacheContent(saved.sha, baselineSections, saved.sentIndex, siteConfig!, {
             media: saved.committedManifest,
             documents: saved.committedDocumentManifest,
-          });
+          }, tagsDegraded);
           finishSave(saved.uploadedItems, saved.savedSections.map((r) => r.sectionId));
           if (saved.committedDocumentIds.length > 0) onDocumentsPublished?.(saved.committedDocumentIds);
           if (saved.committedDocumentDeletions.length > 0) onDocumentsDeleted?.(saved.committedDocumentDeletions);
@@ -857,7 +862,7 @@ export function useEditorPublish({
           await cacheContent(sha, baselineSections, sentIndex, siteConfig!, {
             media: committedManifest!,
             documents: committedDocumentManifest!,
-          });
+          }, tagsDegraded);
         } catch (cleanupError) {
           console.error("Publish succeeded but the cache re-key failed:", cleanupError);
           onShasUpdated(null, sha);
@@ -877,7 +882,7 @@ export function useEditorPublish({
       setPublishAction("idle");
       setSaveProgress(null);
     }
-  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, recoverConflict, saveChunkBudget, getEditGeneration, pendingDocumentDeletions]);
+  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, recoverConflict, saveChunkBudget, getEditGeneration, pendingDocumentDeletions, tagsDegraded]);
 
   return { publishAction, publishFeedback, saveProgress, handleSave, handlePublish, handleSaveAndPublish };
 }

package/src/hooks/useMediaPipeline.ts

@@ -1,5 +1,6 @@
 import { useState, useCallback, useEffect, useRef, useMemo } from "react";
-import { hashFileBuffer, sanitizeMediaName } from "../media/utils";
+import { hashFileBuffer } from "../media/utils";
+import { mediaIdentity, imageManifestEntry } from "../lib/image-variant-plan";
 import { ProcessingQueue, type QueueItem, type QueueEvent } from "../media/queue";
 import type { MediaManifest, MediaItem as LibraryMediaItem } from "../media/types";
 import type { SiteConfig } from "../schemas/site-config";
@@ -235,7 +236,16 @@ export function useMediaPipeline({
         if (event.type === "complete" && event.item.result) {
           const result = event.item.result;
           const kind = event.item.kind;
-          const sanitizedName = sanitizeMediaName(event.item.originalName);
+          // A still image's manifest entry comes only from the plan the worker
+          // rendered. One without a plan (a stale cached worker after a deploy)
+          // is a failed upload, never a quiet entry with no variants.
+          if (kind === "image" && !result.plan) {
+            uploadTargetsRef.current.delete(event.item.hash);
+            hiddenUploadsRef.current.delete(event.item.hash);
+            uploadCallbacksRef.current.delete(event.item.hash);
+            onUploadErrorRef.current?.(`"${event.item.originalName}" couldn't be processed — reload the editor and try again.`);
+            return;
+          }
 
           const finalize = async (
             localUrls: Record<string, string>,
@@ -245,23 +255,23 @@ export function useMediaPipeline({
           ) => {
             if (destroyedRef.current) return;
             const targetFolderId = uploadTargetsRef.current.get(event.item.hash) ?? null;
+            // A still image's entry comes from the plan the worker rendered;
+            // animated and video items have no variants, only the identity.
+            const base: LibraryMediaItem = result.plan
+              ? imageManifestEntry(result.plan, result.variants, result.primaryBlob.size)
+              : {
+                ...mediaIdentity(event.item.hash, event.item.originalName),
+                kind,
+                width,
+                height,
+                mimeType: event.item.mimeType,
+                size: result.primaryBlob.size,
+                variants: [],
+                alt: "",
+                storage: "github",
+              };
             const item: LibraryMediaItem = {
-              id: event.item.hash,
-              hash: event.item.hash,
-              kind,
-              originalName: sanitizedName,
-              width,
-              height,
-              mimeType: kind === "image" ? "image/webp" : event.item.mimeType,
-              size: result.primaryBlob.size,
-              folder: `${sanitizedName}-${event.item.hash}`,
-              variants: result.variants.map((v) => ({
-                width: v.width,
-                height: v.height,
-                size: v.size,
-              })),
-              alt: "",
-              storage: "github",
+              ...base,
               ...(targetFolderId ? { folderId: targetFolderId } : {}),
               ...(hiddenUploadsRef.current.get(event.item.hash) ? { hidden: true } : {}),
             };
@@ -408,17 +418,13 @@ export function useMediaPipeline({
 
       try {
         const { posterBlob, width, height, duration } = await generateVideoPoster(file, mediaConfig.quality);
-        const sanitizedName = sanitizeMediaName(file.name);
         const item: LibraryMediaItem = {
-          id: hash,
-          hash,
+          ...mediaIdentity(hash, file.name),
           kind: "video",
-          originalName: sanitizedName,
           width,
           height,
           mimeType: file.type,
           size: file.size,
-          folder: `${sanitizedName}-${hash}`,
           variants: [],
           alt: "",
           storage: "assets",

package/src/lib/dexie.ts

@@ -511,6 +511,12 @@ export async function persistAll(
  * cache hit then served pre-upload media ("No Image" on images the published site
  * rendered fine) and an empty document manifest ("File missing" on committed
  * documents). Passing them positionally makes forgetting a compile error.
+ *
+ * `tagsDegraded` is required for the same reason. A degraded tags read caches
+ * as "not loaded" (the index without `tags`), so a later cache-hit load stays
+ * read-only for tags instead of trusting the partial list. Only the cold load
+ * used to strip it, so a conflict recovery, remote sync or save re-primed the
+ * row with the partial list and the next cache hit re-enabled tag editing.
  */
 export async function cacheContent(
   sha: string,
@@ -518,6 +524,7 @@ export async function cacheContent(
   index: SiteIndex,
   siteConfig: Record<string, unknown>,
   manifests: { media: MediaManifest; documents: DocumentManifest },
+  tagsDegraded: boolean,
   diff?: {
     savedBranchSha?: string | null;
     changedSectionIds?: string[];
@@ -526,11 +533,12 @@ export async function cacheContent(
   },
 ): Promise<void> {
   const now = new Date().toISOString();
+  const { tags: _partialTags, ...untaggedIndex } = index;
   await getDb().contentCache.put({
     key: "current",
     sha,
     sections,
-    index,
+    index: tagsDegraded ? untaggedIndex : index,
     siteConfig,
     updatedAt: now,
     savedBranchSha: diff?.savedBranchSha ?? null,

package/src/lib/document-refs.ts

@@ -81,3 +81,33 @@ export function clearDocumentRefs(
   if (!changed) return { changed: false, section };
   return { changed: true, section: { ...section, content: { ...section.content, children: next } } };
 }
+
+/**
+ * The non-empty `documentId`s referenced by unvalidated section JSON, including
+ * ones nested in a container's children — `tallyDocumentIds` for a body that
+ * has not been through a schema, so every step is shape-checked. Walks by node
+ * type like the rest of this module, so an unrelated field called `doc` is
+ * never mistaken for a reference.
+ */
+export function collectDocumentIds(value: unknown, out: Set<string> = new Set()): Set<string> {
+  if (Array.isArray(value)) {
+    for (const item of value) collectDocumentIds(item, out);
+    return out;
+  }
+  if (typeof value !== "object" || value === null) return out;
+  const node = value as { type?: unknown; content?: unknown };
+  const content = node.content;
+  if (typeof content !== "object" || content === null || Array.isArray(content)) return out;
+  const record = content as Record<string, unknown>;
+
+  if (node.type === "document") {
+    const doc = record.doc;
+    const documentId =
+      typeof doc === "object" && doc !== null ? (doc as Record<string, unknown>).documentId : undefined;
+    // Empty string is the routine unconfigured slot (the schema defaults to
+    // it), not a broken reference.
+    if (typeof documentId === "string" && documentId !== "") out.add(documentId);
+  }
+  if (Array.isArray(record.children)) collectDocumentIds(record.children, out);
+  return out;
+}