@tokenoftrust/storefront-runner 2.0.46 → 2.0.48

package/apps/storefront/dev-plugins/tenant-hot-reload.mjs

@@ -15,7 +15,6 @@ import { readFile } from "node:fs/promises";
 // normalized to match Vite's ctx.file (Vite always reports posix-style paths).
 const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
 const TENANTS_DIR = join(REPO_ROOT, "tenants").replace(/\\/g, "/");
-const PUBLIC_TENANTS_DEST = fileURLToPath(new URL("../public/tenants", import.meta.url));
 
 /** Per-file finding signatures, so an unchanged warning is not reprinted on every
  *  keystroke-save. Lives for the dev server's lifetime. */
@@ -58,12 +57,13 @@ async function loadTsModule(server, url) {
  * @param {string} file
  * @returns {{ id: string, rest: string } | null}
  */
-export function classifyTenantFile(file) {
+export function classifyTenantFile(file, tenantsDir = TENANTS_DIR) {
   const f = String(file).replace(/\\/g, "/");
-  if (!f.startsWith(TENANTS_DIR + "/")) return null;
+  const normalizedTenantsDir = String(tenantsDir).replace(/\\/g, "/");
+  if (!f.startsWith(normalizedTenantsDir + "/")) return null;
   // "<id>/<...>" for a real tenant, "e2e/<id>/<...>" for a platform test tenant —
   // consume the nesting segment so `id` is always the tenant's own id.
-  let rel = f.slice(TENANTS_DIR.length + 1);
+  let rel = f.slice(normalizedTenantsDir.length + 1);
   if (rel.startsWith(E2E_TENANT_DIR + "/")) rel = rel.slice(E2E_TENANT_DIR.length + 1);
   const slash = rel.indexOf("/");
   if (slash < 0) return null;
@@ -102,23 +102,31 @@ export function stripThemeMeta(parsed) {
  * save mirroring into public/tenants/<id>/.
  * @param {string} id
  */
-export function isVersionedTenant(id) {
+export function isVersionedTenant(id, root = REPO_ROOT) {
   const envList = (process.env.TENANT_ASSETS_VERSIONED ?? "")
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean);
   if (envList.includes(id)) return true;
-  return existsSync(join(REPO_ROOT, ...tenantDirSegments(id), ".tot", "assets-versioned"));
+  return existsSync(join(root, ...tenantDirSegments(id), ".tot", "assets-versioned"));
 }
 
 /**
  * Re-mirror one changed/added public asset into public/tenants/<id>/ (skip R2-versioned).
  * @param {string} id @param {string} rest @param {string} sourceFile
  */
-async function mirrorPublicAsset(id, rest, sourceFile) {
-  if (isVersionedTenant(id)) return;
+async function mirrorPublicAsset(
+  id,
+  rest,
+  sourceFile,
+  {
+    root = REPO_ROOT,
+    publicTenantsDest = join(root, "apps", "storefront", "public", "tenants"),
+  } = {},
+) {
+  if (isVersionedTenant(id, root)) return;
   const { cp, mkdir } = await import("node:fs/promises");
-  const target = join(PUBLIC_TENANTS_DEST, id, rest.slice("public/".length));
+  const target = join(publicTenantsDest, id, rest.slice("public/".length));
   try {
     await mkdir(dirname(target), { recursive: true });
     await cp(sourceFile, target);
@@ -131,10 +139,17 @@ async function mirrorPublicAsset(id, rest, sourceFile) {
  * Remove the stale mirrored copy under public/tenants/<id>/ when a public asset is deleted.
  * @param {string} id @param {string} rest
  */
-async function unmirrorPublicAsset(id, rest) {
-  if (isVersionedTenant(id)) return;
+async function unmirrorPublicAsset(
+  id,
+  rest,
+  {
+    root = REPO_ROOT,
+    publicTenantsDest = join(root, "apps", "storefront", "public", "tenants"),
+  } = {},
+) {
+  if (isVersionedTenant(id, root)) return;
   const { rm } = await import("node:fs/promises");
-  const target = join(PUBLIC_TENANTS_DEST, id, rest.slice("public/".length));
+  const target = join(publicTenantsDest, id, rest.slice("public/".length));
   try {
     await rm(target, { force: true });
   } catch {
@@ -194,7 +209,11 @@ export function seedKnown(root, known) {
 // the worker teardown, same as the change path). Public assets are NOT in any
 // graph, so Vite ignores their add/unlink entirely — we mirror (add) / un-mirror
 // (unlink) and reload ourselves. loopState.lastEvent then reflects add/unlink.
-export function tenantHotReload() {
+export function tenantHotReload({
+  root = REPO_ROOT,
+  publicTenantsDest = join(root, "apps", "storefront", "public", "tenants"),
+} = {}) {
+  const tenantsDir = join(root, "tenants").replace(/\\/g, "/");
   // Typed `any`: `vite` isn't a direct dependency of this package (it's pulled in
   // transitively via astro), so `import('vite').Plugin` can't be resolved here and
   // importing from "vite" would even fail at runtime. `any` keeps the hook params
@@ -205,7 +224,7 @@ export function tenantHotReload() {
     apply: "serve",
     /** @param {any} server */
     configureServer(server) {
-      server.watcher.add(TENANTS_DIR);
+      server.watcher.add(tenantsDir);
 
       // Tell the hosted /dev panel the store is UP the moment the dev server is
       // listening — completes Step 1 ("Get running") before any edit. Best-effort,
@@ -218,12 +237,12 @@ export function tenantHotReload() {
       // really added/removed so the guard stays accurate for the session.
       /** @type {Set<string>} */
       const known = new Set();
-      seedKnown(TENANTS_DIR, known);
+      seedKnown(tenantsDir, known);
 
       /** @param {"add"|"unlink"} event @param {string} rawPath */
       const onAddUnlink = async (event, rawPath) => {
         const file = String(rawPath).replace(/\\/g, "/");
-        const c = classifyTenantFile(file);
+        const c = classifyTenantFile(file, tenantsDir);
         if (!c) return;
         const { id, rest } = c;
 
@@ -244,8 +263,11 @@ export function tenantHotReload() {
         // Public assets: Vite doesn't react (not in the module graph). Maintain the
         // mirror ourselves, then reload (server.ws.send is timestamped by the Monitor).
         if (rest.startsWith("public/")) {
-          if (event === "add") await mirrorPublicAsset(id, rest, file);
-          else await unmirrorPublicAsset(id, rest);
+          if (event === "add") {
+            await mirrorPublicAsset(id, rest, file, { root, publicTenantsDest });
+          } else {
+            await unmirrorPublicAsset(id, rest, { root, publicTenantsDest });
+          }
           server.ws.send({ type: "full-reload" });
           return;
         }
@@ -259,7 +281,7 @@ export function tenantHotReload() {
     },
     /** @param {any} ctx */
     async handleHotUpdate(ctx) {
-      const c = classifyTenantFile(ctx.file);
+      const c = classifyTenantFile(ctx.file, tenantsDir);
       if (!c) return undefined;
       const { id, rest } = c;
 
@@ -276,7 +298,7 @@ export function tenantHotReload() {
       // terminal a beat later. Putting this in the reload path would tax every
       // save to report something that is almost always empty.
       void validateSavedFile({
-        tenantDir: join(REPO_ROOT, tenantDirRelative(id)),
+        tenantDir: join(root, tenantDirRelative(id)),
         tenantId: id,
         rest,
         memo: savedFileFindings,
@@ -301,7 +323,10 @@ export function tenantHotReload() {
       // Unlike content HTML this reloads no worker, so there's no teardown race to
       // fire ahead of. Skip R2-versioned tenants, like copy-tenant-assets.mjs.
       if (rest.startsWith("public/")) {
-        await mirrorPublicAsset(id, rest, ctx.file.replace(/\\/g, "/"));
+        await mirrorPublicAsset(id, rest, ctx.file.replace(/\\/g, "/"), {
+          root,
+          publicTenantsDest,
+        });
         ctx.server.ws.send({ type: "full-reload" });
         return [];
       }

package/apps/storefront/integrations/materialize-guard.mjs

@@ -19,7 +19,7 @@ import {
  *   STATIC publish (materialize-tenant.mjs) sets this to the single tenant it renders,
  *   so a sibling tenant can never block it. Unset ⇒ framework-only Worker build.
  */
-export function materializeGuard() {
+export function materializeGuard({ root } = {}) {
   return {
     name: "materialize-guard",
     hooks: {
@@ -40,7 +40,7 @@ export function materializeGuard() {
           // set (not "all tenants", which `null` would mean), so a sibling
           // tenant that is present-but-stale can never block this build.
           const frameworkOnlyTenants = [];
-          const { problems } = checkPinned(undefined, { expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
+          const { problems } = checkPinned(root, { expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
           const absent = problems.filter((p) => p.reason === "absent");
           const real = problems.filter((p) => p.reason !== "absent");
           if (absent.length) {
@@ -49,11 +49,11 @@ export function materializeGuard() {
             else console.log(msg);
           }
           if (real.length) {
-            assertPinnedMaterialized({ expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
+            assertPinnedMaterialized({ root, expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
           }
           return;
         }
-        assertPinnedMaterialized({ expectRef, allowUnpinned, onlyTenants });
+        assertPinnedMaterialized({ root, expectRef, allowUnpinned, onlyTenants });
       },
     },
   };

package/apps/storefront/src/config/publicationSpaceRegistry.ts

@@ -10,7 +10,7 @@ const ROOT_SOURCES: Readonly<Record<string, PublicationSpaceSourceV1>> = {
     defaultBranch: "main",
   },
   "sample-store.com": { forge: "gitea", repo: "sample-store.com", defaultBranch: "main" },
-  "sample-store.e2e.test": { forge: "fixture", repo: "sample-store.e2e.test", defaultBranch: "main" },
+  "sample-store.e2e.test": { forge: "gitea", repo: "sample-store.e2e.test", defaultBranch: "main" },
   "verify.e2e.test": { forge: "fixture", repo: "verify.e2e.test", defaultBranch: "main" },
   "fixture.e2e.test": { forge: "fixture", repo: "fixture.e2e.test", defaultBranch: "main" },
   "chrome.e2e.test": { forge: "fixture", repo: "chrome.e2e.test", defaultBranch: "main" },

package/apps/storefront/src/lib/assets/captured-original-serve.ts

@@ -0,0 +1,146 @@
+/**
+ * Worker-safe serve of revision-bound captured originals.
+ *
+ * Does not import Node capture — R2 + Web Crypto only. Bytes are served only
+ * when the sealed revision manifest names the address.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+
+const ADDRESS_RE = /^[0-9a-f]{64}$/;
+/** Hostname-like tenant ids (no scheme, no path separators). */
+const TENANT_ID_RE = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/i;
+/** Hostname-like revision ids, or production `sha256:<64 hex>`. */
+const REVISION_ID_RE =
+  /^(?:[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?|sha256:[0-9a-f]{64})$/i;
+
+function isSafeTenantId(tenantId: string): boolean {
+  return TENANT_ID_RE.test(tenantId);
+}
+function isSafeRevisionId(revisionId: string): boolean {
+  return REVISION_ID_RE.test(revisionId);
+}
+/** Same key layout as private-controlplane original-image-capture manifestKey. */
+function originalImageManifestObjectKey(tenantId: string, revisionId: string): string {
+  return `original-images/${tenantId}/revisions/${revisionId}/manifest.json`;
+}
+
+const EXT_TYPE: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+};
+
+export type CapturedOriginalBucket = {
+  get(key: string): Promise<unknown>;
+};
+
+type ManifestEntry = {
+  address: string;
+  byteLength: number;
+  mediaType: string;
+};
+
+function objectKey(tenantId: string, address: string): string {
+  return `original-images/${tenantId}/objects/${address}`;
+}
+
+/** Parse `/_a/<sha256>[.ext]` — null when the path is not a pinned asset URL. */
+export function parsePinnedImagePath(pathname: string): { address: string; ext: string } | null {
+  const match = pathname.match(/^\/_a\/([0-9a-f]{64})(\.[A-Za-z0-9]+)?$/);
+  if (!match) return null;
+  return { address: match[1]!, ext: match[2] ?? "" };
+}
+
+async function readManifestEntries(
+  bucket: CapturedOriginalBucket,
+  tenantId: string,
+  revisionId: string,
+): Promise<ManifestEntry[] | null> {
+  if (!isSafeTenantId(tenantId) || !isSafeRevisionId(revisionId)) return null;
+  try {
+    const object = await bucket.get(originalImageManifestObjectKey(tenantId, revisionId));
+    if (!object || typeof object !== "object") return null;
+    const body = object as { arrayBuffer?: () => Promise<ArrayBuffer> };
+    if (typeof body.arrayBuffer !== "function") return null;
+    const parsed = JSON.parse(new TextDecoder().decode(new Uint8Array(await body.arrayBuffer()))) as {
+      version?: unknown;
+      revisionId?: unknown;
+      entries?: unknown;
+    };
+    if (parsed.version !== 1 || parsed.revisionId !== revisionId || !Array.isArray(parsed.entries)) {
+      return null;
+    }
+    const entries: ManifestEntry[] = [];
+    for (const raw of parsed.entries) {
+      if (!raw || typeof raw !== "object") return null;
+      const entry = raw as Partial<ManifestEntry>;
+      if (typeof entry.address !== "string" || !ADDRESS_RE.test(entry.address)) return null;
+      if (typeof entry.byteLength !== "number" || typeof entry.mediaType !== "string") return null;
+      entries.push({
+        address: entry.address,
+        byteLength: entry.byteLength,
+        mediaType: entry.mediaType,
+      });
+    }
+    return entries;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serve a captured original for the exact tenant+revision, or null to fall through.
+ * Missing/unbound/tampered addresses are 404 with no locator or digest in the body.
+ */
+export async function tryServeCapturedOriginal(input: {
+  bucket: CapturedOriginalBucket;
+  tenantId: string;
+  revisionId: string;
+  pathname: string;
+  method?: string;
+}): Promise<Response | null> {
+  const parsed = parsePinnedImagePath(input.pathname);
+  if (!parsed) return null;
+  if (!isSafeTenantId(input.tenantId) || !isSafeRevisionId(input.revisionId)) {
+    return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  }
+
+  const entries = await readManifestEntries(input.bucket, input.tenantId, input.revisionId);
+  const entry = entries?.find((item) => item.address === parsed.address);
+  if (!entry) {
+    return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  }
+
+  try {
+    const object = await input.bucket.get(objectKey(input.tenantId, parsed.address));
+    if (!object || typeof object !== "object") {
+      return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+    }
+    const body = object as { arrayBuffer?: () => Promise<ArrayBuffer> };
+    if (typeof body.arrayBuffer !== "function") {
+      return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+    }
+    const bytes = new Uint8Array(await body.arrayBuffer());
+    if (bytes.byteLength !== entry.byteLength) {
+      return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+    }
+    const digest = await sha256Hex(bytes);
+    if (digest !== parsed.address) {
+      return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+    }
+    const contentType = EXT_TYPE[parsed.ext.toLowerCase()] ?? entry.mediaType;
+    const headers: Record<string, string> = {
+      "content-type": contentType,
+      "cache-control": "public, max-age=31536000, immutable",
+      "x-tot-original-image": "revision-bound",
+      "content-length": String(bytes.byteLength),
+    };
+    const method = (input.method ?? "GET").toUpperCase();
+    return new Response(method === "HEAD" ? null : bytes, { status: 200, headers });
+  } catch {
+    return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  }
+}

package/apps/storefront/src/lib/assets/preview-version-cookie.ts

@@ -0,0 +1,31 @@
+/**
+ * Resolve the candidate/revision asset pin from preview cookies.
+ *
+ * Candidate and revision renderers set `tot_preview_version` (the exact sha) and
+ * `tot_preview` (capability token). Subresource GETs (img `/_a/…`, `/tenants/…`)
+ * carry those cookies but not `__tot_candidate_pin`, so this is the revision
+ * authority for revision-bound captured originals and preview assets.
+ */
+import { verifyPreviewToken } from "@tot/public-runtime";
+
+const SAFE_VERSION_ID = /^[A-Za-z0-9._-]{1,128}$/;
+
+export async function resolvePreviewVersionFromCookies(input: {
+  tenantId: string;
+  previewVersionCookie: string | null | undefined;
+  previewTokenCookie: string | null | undefined;
+  secret: string | null | undefined;
+  nowSeconds?: number;
+}): Promise<string | null> {
+  const versionId = input.previewVersionCookie?.trim() || null;
+  const token = input.previewTokenCookie?.trim() || null;
+  if (!versionId || !token || !input.tenantId || !input.secret) return null;
+  if (!SAFE_VERSION_ID.test(versionId) || versionId.includes("..")) return null;
+  const verified = await verifyPreviewToken(
+    input.secret,
+    token,
+    input.nowSeconds ?? Math.floor(Date.now() / 1000),
+  );
+  if (!verified.ok || verified.claims.tenantId !== input.tenantId) return null;
+  return versionId;
+}

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -196,7 +196,7 @@ export function isDevCliSessionPath(pathname: string): boolean {
  * it: an unauthenticated request still gets a 401 from the route's own check.
  */
 export function isStaticBundleUploadPath(pathname: string): boolean {
-  return pathname === "/api/publish/stage-bundle";
+  return pathname === "/api/publish/stage-bundle" || pathname === "/api/publish/captured-original";
 }
 
 /**

package/apps/storefront/src/lib/storyblok/provider.ts

@@ -33,6 +33,7 @@ import { renderRawChrome } from "../rawChrome.js";
 import { parseChromeConfig } from "../chrome/parseConfig.js";
 import { parseChromeAssignments } from "../chrome/model.js";
 import { stampTrackingIdsAtPublish } from "../tracking/publishSafetyNet.js";
+import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
 
 /** Safe, always-valid fallback when neither the tenant's own chrome.json nor
  * the default scope's validates — the storefront must always render. */
@@ -702,11 +703,13 @@ export class VersionPinnedContentProvider implements ContentProvider {
   ) {}
 
   private pinnedRaw(relative: string): Promise<string | null> {
-    return readVersionArtifact(
+    const path = contentArtifactPath(this.tenantId, relative);
+    return readWithImagePreviewRewriteOverlay(
       this.get,
       this.tenantId,
       this.versionId,
-      contentArtifactPath(this.tenantId, relative),
+      path,
+      () => readVersionArtifact(this.get, this.tenantId, this.versionId, path),
     );
   }
 

package/apps/storefront/src/middleware/index.ts

@@ -231,6 +231,19 @@ export const onRequest = defineMiddleware(async (context, next) => {
   // keep off the public path. Managed installs are not consulted: they inject
   // document markup, never asset bytes, so this stays a D1-free path.
   if (branch === "static-passthrough") {
+    const candidatePin = await resolveCandidateContentPin(url, tenant.tenant_id);
+    const { resolvePreviewVersionFromCookies } = await import("@/lib/assets/preview-version-cookie");
+    const cookieRevision = await resolvePreviewVersionFromCookies({
+      tenantId: tenant.tenant_id,
+      previewVersionCookie: context.cookies.get("tot_preview_version")?.value,
+      previewTokenCookie: context.cookies.get("tot_preview")?.value,
+      secret: await readEnv("CUSTOMIZATION_PREVIEW_SECRET"),
+    });
+    const capturedRevisionId = candidatePin?.versionId ?? cookieRevision;
+    const originalsBucket =
+      capturedRevisionId
+        ? ((await readR2("PRODUCT_IMAGES")) ?? (await readR2("TENANT_ASSETS")) ?? null)
+        : null;
     const bundled = await tryServeStaticBundle({
       request,
       url,
@@ -241,9 +254,17 @@ export const onRequest = defineMiddleware(async (context, next) => {
       isPreviewHost: host.toLowerCase().startsWith("preview."),
       hasPreviewToken:
         url.searchParams.has("__preview") || !!context.cookies.get("tot_preview")?.value,
-      hasCandidatePin: !!(await resolveCandidateContentPin(url, tenant.tenant_id)),
+      hasCandidatePin: !!candidatePin,
       hasDraftCookie: !!context.cookies.get(DEV_DRAFT_COOKIE)?.value,
       hasManagedInstalls: false,
+      ...(capturedRevisionId && originalsBucket
+        ? {
+            capturedOriginal: {
+              bucket: originalsBucket as { get(key: string): Promise<unknown> },
+              revisionId: capturedRevisionId,
+            },
+          }
+        : {}),
     });
     if (bundled) return bundled;
     const rootLocation = platformStaticRootLocationV1({

package/apps/storefront/src/middleware/renderChain.ts

@@ -12,7 +12,7 @@ import type { APIContext, MiddlewareNext } from "astro";
 import { referenceTheme } from "@/themes/reference";
 import { mergeTheme, themeToCssVars } from "@/themes/schema";
 import { createToTClient } from "@/lib/tot/ToTClient";
-import { readEnv } from "@/lib/runtimeEnv";
+import { readEnv, readR2 } from "@/lib/runtimeEnv";
 import { tryServeStaticBundle } from "./staticBundle.js";
 import { resolveCandidateContentPin } from "./candidatePin.js";
 import { createContentProvider, DevDraftContentProvider } from "@/lib/storyblok/provider";
@@ -248,6 +248,19 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // Digest-addressed static-bundle serving. Deliberately before the edge page
   // cache/catalog/theme machinery. A selected publication bypasses this legacy
   // whole-site bundle until B1 can compose mounted spaces into it reproducibly.
+  const { resolvePreviewVersionFromCookies } = await import("@/lib/assets/preview-version-cookie");
+  const cookieRevision = await resolvePreviewVersionFromCookies({
+    tenantId: tenant.tenant_id,
+    previewVersionCookie: context.cookies.get("tot_preview_version")?.value,
+    previewTokenCookie: cookieToken,
+    secret: previewSecret,
+    nowSeconds,
+  });
+  const capturedRevisionId = candidatePin?.versionId ?? cookieRevision;
+  const originalsBucket =
+    capturedRevisionId
+      ? ((await readR2("PRODUCT_IMAGES")) ?? (await readR2("TENANT_ASSETS")) ?? null)
+      : null;
   const bundled = publicationSource.status === "legacy-root" ? await tryServeStaticBundle({
     request,
     url,
@@ -260,6 +273,14 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     hasCandidatePin: !!candidatePin,
     hasDraftCookie: !!draftCookie,
     hasManagedInstalls: managedIntegrationDeclarations.length > 0,
+    ...(capturedRevisionId && originalsBucket
+      ? {
+          capturedOriginal: {
+            bucket: originalsBucket as { get(key: string): Promise<unknown> },
+            revisionId: capturedRevisionId,
+          },
+        }
+      : {}),
   }) : null;
   if (bundled) return bundled;
 

package/apps/storefront/src/middleware/staticBundle.ts

@@ -31,6 +31,14 @@ export interface StaticBundleAttemptInput {
   hasDraftCookie: boolean;
   /** Managed installs inject document markup, so a bundled DOCUMENT would be stale. */
   hasManagedInstalls: boolean;
+  /**
+   * When set, a `/_a/<sha>` miss falls through to revision-bound captured
+   * originals (hosted preview image capture) before returning 404.
+   */
+  capturedOriginal?: {
+    bucket: { get(key: string): Promise<unknown> };
+    revisionId: string;
+  };
 }
 
 /**
@@ -71,10 +79,33 @@ export async function tryServeStaticBundle(
         url.pathname,
         method,
       );
-      if (pinned) {
-        if (pinnedKey && cache && pinned.ok) await putCachedPage(cache, pinnedKey, pinned);
+      if (pinned && pinned.ok) {
+        if (pinnedKey && cache) await putCachedPage(cache, pinnedKey, pinned);
         return pinned;
       }
+      // `/_a/` miss: try revision-bound captured originals before the pinned 404.
+      if (input.capturedOriginal && url.pathname.startsWith("/_a/")) {
+        const { tryServeCapturedOriginal } = await import("@/lib/assets/captured-original-serve");
+        const captured = await tryServeCapturedOriginal({
+          bucket: input.capturedOriginal.bucket,
+          tenantId: tenant.tenant_id,
+          revisionId: input.capturedOriginal.revisionId,
+          pathname: url.pathname,
+          method,
+        });
+        if (captured) return captured;
+      }
+      if (pinned) return pinned;
+    } else if (input.capturedOriginal && url.pathname.startsWith("/_a/")) {
+      const { tryServeCapturedOriginal } = await import("@/lib/assets/captured-original-serve");
+      const captured = await tryServeCapturedOriginal({
+        bucket: input.capturedOriginal.bucket,
+        tenantId: tenant.tenant_id,
+        revisionId: input.capturedOriginal.revisionId,
+        pathname: url.pathname,
+        method,
+      });
+      if (captured) return captured;
     }
   }
 

package/apps/storefront/src/pages/tenants/[id]/[...path].ts

@@ -13,38 +13,50 @@
  * and a versioned tenant (skipped from baking via a `.tot/assets-versioned`
  * marker) falls through to R2. When the tenant has no published asset version,
  * `serveTenantAsset` returns null → 404 (nothing published yet).
+ *
+ * Preview sessions also consult the image-capture rewrite overlay so rewritten
+ * `public/*.css` (and similar text assets) serve `/_a/<sha>` references.
  */
 import type { APIContext } from "astro";
 import {
+  assetContentType,
+  parseTenantAssetPath,
   serveTenantAsset,
-  verifyPreviewToken,
   type R2BucketLike,
 } from "@tot/public-runtime";
+import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
 import { readR2, readKv, readEnv } from "@/lib/env";
+import { resolvePreviewVersionFromCookies } from "@/lib/assets/preview-version-cookie";
 
 export const prerender = false;
 
-/** A versionId is a content sha — restrict to a safe R2 key segment (no traversal). */
-const SAFE_VERSION_ID = /^[A-Za-z0-9._-]{1,128}$/;
-
-/**
- * Resolve a CANDIDATE-preview version override for this asset request, or null.
- * A candidate/revision page sets `tot_preview_version` (its versionId) + the
- * `tot_preview` capability token; when the token verifies for THIS tenant, we serve
- * that exact snapshot (`tenants/<id>/<versionId>/…`) instead of the channel pointer,
- * so a candidate's NEW assets — unreachable via the never-flipped channel — resolve.
- * Token-gated + tenant-matched so it can never serve another tenant's snapshot.
- */
-async function resolvePreviewVersion(context: APIContext, urlTenant: string): Promise<string | null> {
-  const versionId = context.cookies.get("tot_preview_version")?.value ?? null;
-  const token = context.cookies.get("tot_preview")?.value ?? null;
-  if (!versionId || !token || !urlTenant) return null;
-  if (!SAFE_VERSION_ID.test(versionId) || versionId.includes("..")) return null;
-  const secret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
-  if (!secret) return null;
-  const verified = await verifyPreviewToken(secret, token, Math.floor(Date.now() / 1000));
-  if (!verified.ok || verified.claims.tenantId !== urlTenant) return null;
-  return versionId;
+async function tryServePreviewRewriteOverlay(input: {
+  kvGet: (key: string) => Promise<string | null>;
+  tenantId: string;
+  revisionId: string;
+  pathname: string;
+}): Promise<Response | null> {
+  const parsed = parseTenantAssetPath(input.pathname);
+  if (!parsed || parsed.tenantId !== input.tenantId) return null;
+  // Capture overlays store repo paths as tenants/<id>/public/<rel>.
+  const overlayPath = `tenants/${input.tenantId}/public/${parsed.rel}`;
+  const text = await readWithImagePreviewRewriteOverlay(
+    input.kvGet,
+    input.tenantId,
+    input.revisionId,
+    overlayPath,
+    async () => null,
+  );
+  if (text == null) return null;
+  return new Response(text, {
+    status: 200,
+    headers: {
+      "content-type": assetContentType(parsed.rel),
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+      "x-tot-image-preview-rewrite": "1",
+    },
+  });
 }
 
 export async function GET(context: APIContext): Promise<Response> {
@@ -60,7 +72,24 @@ export async function GET(context: APIContext): Promise<Response> {
     });
   }
 
-  const previewVersionId = await resolvePreviewVersion(context, context.params.id ?? "");
+  const urlTenant = context.params.id ?? "";
+  const previewVersionId = await resolvePreviewVersionFromCookies({
+    tenantId: urlTenant,
+    previewVersionCookie: context.cookies.get("tot_preview_version")?.value,
+    previewTokenCookie: context.cookies.get("tot_preview")?.value,
+    secret: await readEnv("CUSTOMIZATION_PREVIEW_SECRET"),
+  });
+
+  const pathname = new URL(context.request.url).pathname;
+  if (previewVersionId) {
+    const overlay = await tryServePreviewRewriteOverlay({
+      kvGet: (key) => kv.get(key),
+      tenantId: urlTenant,
+      revisionId: previewVersionId,
+      pathname,
+    });
+    if (overlay) return overlay;
+  }
 
   const res = await serveTenantAsset(
     {
@@ -71,7 +100,7 @@ export async function GET(context: APIContext): Promise<Response> {
       ...(previewVersionId ? { versionId: previewVersionId } : {}),
       ifNoneMatch: context.request.headers.get("if-none-match"),
     },
-    new URL(context.request.url).pathname,
+    pathname,
   );
 
   // A candidate-preview asset must NEVER be edge/CDN-cached under its tokenless URL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.46",
+  "version": "2.0.48",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -12,6 +12,9 @@
     "./blog-visibility": "./src/blog-visibility.mjs",
     "./publication-redirects": "./src/publication-redirects.mjs",
     "./image-dependencies": "./src/image-dependencies.ts",
+    "./image-finding-dependencies": "./src/image-finding-dependencies.ts",
+    "./image-finding-acceptance": "./src/image-finding-acceptance.ts",
+    "./image-preview-rewrite-overlay": "./src/image-preview-rewrite-overlay.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./integration/lifecycle-host-asset": "./src/integration/lifecycle-host-asset.mjs",
     "./integration/native-ga4-sandbox-asset": "./src/integration/native-ga4-sandbox-asset.mjs"

package/packages/public-runtime/src/image-dependency-identity.ts

@@ -0,0 +1,11 @@
+import type { ImageDependency } from "./image-dependencies.js";
+
+/** Private locator-free identity, stable when artifact order changes. */
+export async function digestImageDependencyIdentity(
+  dependency: Pick<ImageDependency, "surface" | "reason" | "canonicalLocator">,
+): Promise<string> {
+  if (!dependency.reason) throw new Error("image dependency has no unresolved reason");
+  const input = `${dependency.surface}\0${dependency.reason}\0${dependency.canonicalLocator}`;
+  const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input)));
+  return `sha256:${[...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}

package/packages/public-runtime/src/image-finding-acceptance.ts

@@ -0,0 +1,168 @@
+/**
+ * Exact image-finding acceptance helpers: canonical digests and the application /
+ * publication overridability classifiers. Findings themselves never carry a locator,
+ * tenant id, path, or content digest — only stable ids, codes, and reasons.
+ */
+import { sha256Hex } from "./hash.js";
+import type {
+  ImageDependencyFinding,
+  ImageDependencyReason,
+} from "./image-dependencies.js";
+
+export type ImageApplicationClass = ImageDependencyFinding["authoring"];
+export type ImagePublicationClass = ImageDependencyFinding["hostedPreview"];
+
+/** Capture findings are never overridable; every reason is a negative control. */
+export const NON_OVERRIDABLE_CAPTURE_REASONS = [
+  "symlink",
+  "fifo",
+  "device",
+  "escape",
+  "changed-file",
+  "unsafe-scheme",
+  "userinfo",
+  "nonstandard-port",
+  "blocked-address",
+  "redirect-limit",
+  "timeout",
+  "too-large",
+  "mime",
+  "magic",
+  "active-content",
+  "pixels",
+  "tampered",
+  "fetch-failed",
+  "unsupported",
+  "store-failed",
+  "manifest-mismatch",
+  "unbound",
+] as const;
+
+export type NonOverridableCaptureReason = (typeof NON_OVERRIDABLE_CAPTURE_REASONS)[number];
+
+/** Dependency reasons that are security/isolation errors in both classifiers. */
+export const NON_OVERRIDABLE_DEPENDENCY_REASONS = [
+  "cross-tenant",
+  "tenant-escape",
+  "unsafe-scheme",
+  "malformed",
+] as const;
+
+export type NonOverridableDependencyReason = (typeof NON_OVERRIDABLE_DEPENDENCY_REASONS)[number];
+
+/** Safe unresolved / deferred image reasons an owner may accept. */
+export const OVERRIDABLE_DEPENDENCY_REASONS = ["third-party", "local", "unsupported"] as const;
+
+export type ImageFindingIdentity = {
+  id: string;
+  code: string;
+  reason: string;
+};
+
+/** Stable publish/operation finding id for an overridable image finding. */
+export function formatOverridableImageFindingId(finding: Pick<ImageDependencyFinding, "id">): string {
+  return `IMAGE: ${finding.id}`;
+}
+
+/** Stable publish/operation finding id for a non-overridable image finding. */
+export function formatBlockingImageFindingId(
+  finding: Pick<ImageDependencyFinding, "id" | "code">,
+): string {
+  return `${finding.code}: ${finding.id}`;
+}
+
+export function formatImageFindingId(finding: Pick<ImageDependencyFinding, "id" | "code" | "overridable">): string {
+  return finding.overridable
+    ? formatOverridableImageFindingId(finding)
+    : formatBlockingImageFindingId(finding);
+}
+
+/** Application (authoring) classifier — warning vs non-overridable security. */
+export function classifyImageFindingApplication(
+  reason: ImageDependencyReason,
+): ImageApplicationClass {
+  return (NON_OVERRIDABLE_DEPENDENCY_REASONS as readonly string[]).includes(reason)
+    ? "non-overridable-security-error"
+    : "warning";
+}
+
+/** Publication / hosted-preview classifier — overridable quality vs security. */
+export function classifyImageFindingPublication(
+  reason: ImageDependencyReason,
+): ImagePublicationClass {
+  return (NON_OVERRIDABLE_DEPENDENCY_REASONS as readonly string[]).includes(reason)
+    ? "non-overridable-security-error"
+    : "overridable-quality-error";
+}
+
+export function isOverridableImageDependencyReason(reason: ImageDependencyReason): boolean {
+  return classifyImageFindingPublication(reason) === "overridable-quality-error";
+}
+
+/** Capture-time findings are never overridable in either classifier. */
+export function classifyCaptureFindingApplication(
+  _reason: NonOverridableCaptureReason,
+): "non-overridable-security-error" {
+  return "non-overridable-security-error";
+}
+
+export function classifyCaptureFindingPublication(
+  _reason: NonOverridableCaptureReason,
+): "non-overridable-security-error" {
+  return "non-overridable-security-error";
+}
+
+/**
+ * Canonical sorted digest of an image finding set. Identity is id+code+reason only —
+ * never a locator, tenant, path, or byte digest.
+ */
+export async function digestImageFindingSet(
+  findings: readonly ImageFindingIdentity[],
+): Promise<string> {
+  const lines = findings
+    .map((f) => `${f.id}\0${f.code}\0${f.reason}`)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return `sha256:${await sha256Hex(lines.join("\n"))}`;
+}
+
+/** Digest of the exact finding id strings recorded on an acceptance / problem. */
+export async function digestFindingIdSet(findingIds: readonly string[]): Promise<string> {
+  const lines = [...findingIds].map(String).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return `sha256:${await sha256Hex(lines.join("\n"))}`;
+}
+
+export { digestImageDependencyIdentity } from "./image-dependency-identity.js";
+
+/**
+ * Capture-manifest digest: SHA-256 over the same sorted JSON encoding the capture
+ * store seals. Locators stay inside the sealed bytes; callers persist only this digest.
+ */
+export async function digestCaptureManifest(manifest: {
+  version: 1;
+  revisionId: string;
+  entries: ReadonlyArray<{
+    provenance: { kind: "local" | "remote"; locator: string };
+    address: string;
+    byteLength: number;
+    mediaType: string;
+  }>;
+}): Promise<string> {
+  const entries = [...manifest.entries].sort((left, right) => {
+    if (left.provenance.locator < right.provenance.locator) return -1;
+    if (left.provenance.locator > right.provenance.locator) return 1;
+    return left.address < right.address ? -1 : left.address > right.address ? 1 : 0;
+  });
+  const encoded = new TextEncoder().encode(
+    JSON.stringify({ version: 1, revisionId: manifest.revisionId, entries }),
+  );
+  return `sha256:${await sha256Hex(encoded)}`;
+}
+
+export function isImageFindingId(findingId: string): boolean {
+  const prefix = String(findingId).split(":", 1)[0]!.trim();
+  return prefix === "IMAGE" || prefix.startsWith("image-");
+}
+
+export function imageFindingIdsIn(findingIds: readonly string[]): string[] {
+  return findingIds.filter(isImageFindingId);
+}

package/packages/public-runtime/src/image-finding-dependencies.ts

@@ -0,0 +1,31 @@
+import type { ImageDependency, ImageDependencyFinding, ImageDependencyScan } from "./image-dependencies.js";
+
+/** Recover one unresolved finding's exact scanner group without a locator in its ID. */
+export function dependenciesForScanFinding(
+  finding: ImageDependencyFinding,
+  scan: ImageDependencyScan,
+): ImageDependency[] {
+  const match = /^image-dependency-(\d+)-(\d+)$/.exec(finding.id);
+  if (!match) return [];
+  const artifactIndex = Number(match[1]) - 1;
+  const groupOrdinal = Number(match[2]);
+  const seen = new Map<string, { dep: ImageDependency; ordinal: number }>();
+  const counts = new Map<number, number>();
+  for (const dep of scan.dependencies) {
+    if (dep.disposition !== "capture-required" && dep.disposition !== "security-error" &&
+      dep.disposition !== "deferred") continue;
+    const key = `${dep.artifactIndex}\0${dep.surface}\0${dep.disposition}\0${dep.reason}\0${dep.canonicalLocator}`;
+    if (seen.has(key)) continue;
+    const ordinal = (counts.get(dep.artifactIndex) ?? 0) + 1;
+    counts.set(dep.artifactIndex, ordinal);
+    seen.set(key, { dep, ordinal });
+  }
+  const group = [...seen.values()].find(
+    (entry) => entry.dep.artifactIndex === artifactIndex && entry.ordinal === groupOrdinal,
+  );
+  if (!group) return [];
+  return scan.dependencies.filter((dep) =>
+    dep.artifactIndex === group.dep.artifactIndex && dep.surface === group.dep.surface &&
+    dep.disposition === group.dep.disposition && dep.reason === group.dep.reason &&
+    dep.canonicalLocator === group.dep.canonicalLocator);
+}

package/packages/public-runtime/src/image-preview-rewrite-overlay.ts

@@ -0,0 +1,69 @@
+/**
+ * Revision-bound overlay of capture-rewritten preview artifacts (read path).
+ *
+ * Site-version manifests are immutable; successful `/_a/<sha>` rewrites are
+ * stored as content-addressed artifact bytes plus this overlay map. Preview
+ * reads prefer the overlay so candidate documents reference platform-owned URLs.
+ */
+import { contentArtifactPath, customizationArtifactKey, themeArtifactPath } from "./customization-runtime.js";
+
+export type ImagePreviewRewriteOverlay = {
+  version: 1;
+  revisionId: string;
+  /** Capture-manifest digest bound at write time; mismatched rewrite loses CAS. */
+  captureManifestDigest: string;
+  /** Full artifact path → content hash (same keys as SiteVersionManifest.artifacts). */
+  artifacts: Record<string, string>;
+};
+
+export function imagePreviewRewriteOverlayKey(tenantId: string, revisionId: string): string {
+  return `cust:image-preview-rewrite:${tenantId}:${revisionId}`;
+}
+
+/** Map a repo-relative capture artifact path to the preview manifest artifact path. */
+export function previewManifestPathFor(tenantId: string, repoPath: string): string {
+  if (repoPath === "theme.json") return themeArtifactPath(tenantId);
+  if (repoPath.startsWith("content/")) {
+    return contentArtifactPath(tenantId, repoPath.slice("content/".length));
+  }
+  return `tenants/${tenantId}/${repoPath}`;
+}
+
+export async function readImagePreviewRewriteOverlay(
+  get: (key: string) => Promise<string | null>,
+  tenantId: string,
+  revisionId: string,
+): Promise<ImagePreviewRewriteOverlay | null> {
+  try {
+    const raw = await get(imagePreviewRewriteOverlayKey(tenantId, revisionId));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<ImagePreviewRewriteOverlay>;
+    if (parsed.version !== 1 || parsed.revisionId !== revisionId) return null;
+    if (typeof parsed.captureManifestDigest !== "string") return null;
+    if (!/^sha256:[0-9a-f]{64}$/.test(parsed.captureManifestDigest)) return null;
+    if (!parsed.artifacts || typeof parsed.artifacts !== "object") return null;
+    return {
+      version: 1,
+      revisionId,
+      captureManifestDigest: parsed.captureManifestDigest,
+      artifacts: { ...parsed.artifacts },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Prefer overlay bytes for a full artifact path when present. */
+export async function readWithImagePreviewRewriteOverlay(
+  get: (key: string) => Promise<string | null>,
+  tenantId: string,
+  revisionId: string,
+  manifestPath: string,
+  fallback: () => Promise<string | null>,
+): Promise<string | null> {
+  const overlay = await readImagePreviewRewriteOverlay(get, tenantId, revisionId);
+  const hash = overlay?.artifacts?.[manifestPath];
+  if (!hash) return fallback();
+  const bytes = await get(customizationArtifactKey(tenantId, hash));
+  return bytes ?? fallback();
+}

package/packages/public-runtime/src/tenant-assets.ts

@@ -63,6 +63,12 @@ export interface R2PutOptionsLike {
    *  verify can detect a truncated/corrupted object independent of trusting the
    *  store's own reported size alone (see `verifyMaterializedAssets`). */
   customMetadata?: Record<string, string>;
+  /**
+   * Conditional write. `etagDoesNotMatch: "*"` creates the object only when the
+   * key is absent (HTTP If-None-Match: *). Capture uses it so an immutable
+   * content address is never overwritten.
+   */
+  onlyIf?: { etagDoesNotMatch?: string };
 }
 
 export interface R2BucketLike {

package/scripts/tenant/materialize-tenant-content.mjs

@@ -2,14 +2,13 @@
 /**
  * Materialize a Gitea-hosted tenant's content into the monorepo working tree.
  *
- * Real tenants live in per-tenant Gitea repos (git.tokenoftrust.com/storefront/
- * <repo>) — the SOURCE OF TRUTH. The monorepo's `tenants/<id>/` dirs for those
- * tenants are gitignored, disposable LOCAL/PER-TENANT build input (the same
- * stance as apps/storefront/public/tenants/, see .gitignore). The shared
- * Storefront Worker reads published tenant revisions from KV/R2 and does NOT run
- * this first. Local tenant development and a named per-tenant static publish do.
- * Committed-fixture tenants (home, sample-store.e2e.test) are NOT materialized
- * — they're tracked in git and this script refuses to touch them.
+ * Gitea repos (git.tokenoftrust.com/storefront/<repo>) are the source of truth
+ * for tenants declared in the manifest. Materialized content uses the shared
+ * tenant directory resolver: `tenants/<id>/` for real tenants and
+ * `tenants/e2e/<id>/` for synthetic tenants. The shared Storefront Worker reads
+ * published tenant revisions from KV/R2; local development and per-tenant
+ * static publication materialize their exact source. Tenants absent from the
+ * manifest are committed fixtures and are refused.
  *
  * Which tenants are Gitea-classified lives in `tenants/.gitea-tenants.json`
  * (the same manifest the CI reintroduction guard reads —
@@ -24,9 +23,9 @@
  *      the canonical shape (theme.json, content/, public/) when absent.
  *   3. Copy each mapped workspace path into the monorepo target, REPLACING the
  *      target tree (stale files from a previous materialize are removed). Every
- *      target must resolve under `tenants/<id>/` — anything else is refused.
+ *      target must resolve under that tenant's directory — anything else is refused.
  *   4. Copy `.tot/config.json` itself (the CLI + validate flows read it) and
- *      stamp `tenants/<id>/.materialized.json` with { repo, ref, sha, at } so
+ *      stamp the tenant's `.materialized.json` with { repo, ref, sha, at } so
  *      `--check` and humans can see what's populated.
  *
  * Modes:
@@ -71,6 +70,7 @@ import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { tenantDirRelative } from "../lib/tenant-dirs.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..", "..");
@@ -119,9 +119,14 @@ export function buildCloneUrl({ base, repo, user, token }) {
  * write elsewhere in the tree (compare reconcile's manifest deny-by-default).
  */
 export function resolveTargetPath(root, tenant, repoPath) {
-  const target = resolve(root, repoPath);
-  const bound = resolve(root, "tenants", tenant) + sep;
-  if (!target.startsWith(bound) && target !== resolve(root, "tenants", tenant)) {
+  const declared = `tenants/${tenant}`;
+  const physical = tenantDirRelative(tenant);
+  const translated = repoPath === declared ? physical
+    : repoPath.startsWith(`${declared}/`) ? `${physical}${repoPath.slice(declared.length)}` : repoPath;
+  const target = resolve(root, translated);
+  const tenantRoot = resolve(root, physical);
+  const bound = tenantRoot + sep;
+  if (!target.startsWith(bound) && target !== tenantRoot) {
     throw new Error(
       `mapping target "${repoPath}" escapes tenants/${tenant}/ — refusing`,
     );
@@ -142,15 +147,19 @@ function canonicalMappings(tenant) {
 /**
  * Copy one mapping from the checked-out tenant repo into the monorepo tree.
  * `tree` targets are replaced wholesale so a removed file doesn't linger from a
- * previous materialize. Missing OPTIONAL workspace paths are skipped (a tenant
- * without public/ is fine); the reconcile-side required-artifact rules (theme +
+ * previous materialize. Missing OPTIONAL workspace paths remove any old target
+ * (a tenant without public/ is fine); the reconcile-side required-artifact rules (theme +
  * home present) are enforced by validate/reconcile, not here.
  */
 export function copyMapping({ checkoutDir, root, tenant, mapping, log = (/** @type {string} */ _m) => {} }) {
   const src = join(checkoutDir, mapping.workspace.replace(/\/+$/, ""));
   const target = resolveTargetPath(root, tenant, mapping.repo.replace(/\/+$/, ""));
+  if (target === resolve(root, tenantDirRelative(tenant))) {
+    throw new Error("mapping target cannot replace the tenant root");
+  }
   if (!existsSync(src)) {
-    log(`  ~ ${mapping.workspace} absent in repo — skipped`);
+    rmSync(target, { recursive: true, force: true });
+    log(`  ~ ${mapping.workspace} absent in repo — old target removed`);
     return { copied: false, target };
   }
   if (mapping.kind === "tree" && existsSync(target)) {
@@ -229,7 +238,7 @@ export function materializeTenant({
       // local iteration against the default branch is legitimate; publishes are
       // separately guarded by ci-www-publish.sh's PUBLISH_REF requirement.
       console.warn(
-        `[materialize-tenant-content] WARNING: no --ref given — materializing ${tenant} from the ` +
+        `[materialize-tenant-content] WARNING: no --ref given — materializing from the ` +
           `repo's DEFAULT branch, which may be stale. Pin a commit (--ref <sha|branch>) for anything ` +
           `feeding a build or publish.`,
       );
@@ -262,6 +271,8 @@ export function materializeTenant({
     if (existsSync(cfgPath)) {
       const cfgTarget = resolveTargetPath(root, tenant, `tenants/${tenant}/.tot/config.json`);
       cpSync(cfgPath, cfgTarget);
+    } else {
+      rmSync(resolveTargetPath(root, tenant, `tenants/${tenant}/.tot/config.json`), { force: true });
     }
     // The assets-r2-versioned opt-in marker:
     // copy-tenant-assets.mjs reads this from the MATERIALIZED tree, not the repo
@@ -276,6 +287,8 @@ export function materializeTenant({
       );
       cpSync(versionedMarkerSrc, versionedMarkerTarget);
       log(`  + .tot/assets-versioned → tenants/${tenant}/.tot/assets-versioned`);
+    } else {
+      rmSync(resolveTargetPath(root, tenant, `tenants/${tenant}/.tot/assets-versioned`), { force: true });
     }
     const stamp = resolveTargetPath(root, tenant, `tenants/${tenant}/.materialized.json`);
     writeFileSync(
@@ -302,7 +315,7 @@ export function checkMaterialized(root = repoRoot) {
   const manifest = loadManifest(root);
   const missing = [];
   for (const tenant of Object.keys(manifest.tenants)) {
-    const dir = join(root, "tenants", tenant);
+    const dir = join(root, tenantDirRelative(tenant));
     const populated =
       existsSync(join(dir, "theme.json")) ||
       existsSync(join(dir, "content")) ||
@@ -345,7 +358,7 @@ export function checkPinned(
   const scope = onlyTenants ? new Set(onlyTenants) : null;
   for (const tenant of Object.keys(manifest.tenants)) {
     if (scope && !scope.has(tenant)) continue;
-    const dir = join(root, "tenants", tenant);
+    const dir = join(root, tenantDirRelative(tenant));
     const populated =
       existsSync(join(dir, "theme.json")) ||
       existsSync(join(dir, "content")) ||
@@ -432,7 +445,7 @@ export function checkFresh(
   const scope = onlyTenants ? new Set(onlyTenants) : null;
   for (const tenant of Object.keys(manifest.tenants)) {
     if (scope && !scope.has(tenant)) continue;
-    const stampPath = join(root, "tenants", tenant, ".materialized.json");
+    const stampPath = join(root, tenantDirRelative(tenant), ".materialized.json");
     if (!existsSync(stampPath)) continue; // checkPinned already reports absent/missing
     let stamp;
     try {
@@ -610,15 +623,21 @@ function main() {
   }
   for (const tenant of targets) {
     const repo = manifest.tenants[tenant]?.repo ?? tenant;
-    console.log(`Materializing ${tenant} (repo ${repo})…`);
-    materializeTenant({
-      tenant,
-      repo,
-      ref: args.ref,
-      remote: args.remote,
-      gitBase,
-      log: (s) => console.log(s),
-    });
+    const synthetic = manifest.tenants[tenant]?.kind === "synthetic-qa";
+    console.log(synthetic ? "Materializing synthetic QA source…" : `Materializing ${tenant} (repo ${repo})…`);
+    try {
+      materializeTenant({
+        tenant,
+        repo,
+        ref: args.ref,
+        remote: args.remote,
+        gitBase,
+        log: synthetic ? () => {} : (s) => console.log(s),
+      });
+    } catch (error) {
+      if (synthetic) throw new Error("synthetic QA materialization refused");
+      throw error;
+    }
   }
 }