@tokenoftrust/storefront-runner 1.3.2

package/LICENSE

@@ -0,0 +1,58 @@
+Token of Trust Source-Available License — Local Development Only
+Version 1.0
+
+Copyright (c) 2026 Token of Trust, Inc. All rights reserved.
+
+1. DEFINITIONS
+   "Software" means this source code and any accompanying files in this
+   repository or distribution, including the storefront renderer runtime, the
+   `@tot/public-runtime` package, the storefront-runner distributable, and any
+   derivative works.
+   "Local Development" means running, building, and modifying the Software on a
+   machine you control, for the sole purpose of evaluating it or developing and
+   previewing your own tenant content against it. Serving the Software to any
+   third party, or over any public or shared network, is NOT Local Development.
+   "Token of Trust" means Token of Trust, Inc.
+
+2. GRANT (LOCAL DEVELOPMENT ONLY)
+   Subject to the terms below, Token of Trust grants you a personal,
+   non-exclusive, non-transferable, revocable license to use, copy, build, and
+   modify the Software SOLELY for Local Development.
+
+3. PERMISSION REQUIRED FOR EVERYTHING ELSE
+   Any use of the Software beyond Local Development requires the PRIOR WRITTEN
+   PERMISSION of Token of Trust. Without such permission you may NOT, in whole or
+   in part:
+   (a) deploy, host, serve, or otherwise run the Software in production or for
+       any third party, or on any public, staging, or shared/network-accessible
+       environment;
+   (b) use the Software for any commercial purpose or to provide a service to
+       others;
+   (c) distribute, publish, sublicense, sell, rent, lease, or otherwise make the
+       Software (or a derivative of it) available to any third party; or
+   (d) remove or obscure this license or the copyright notices.
+   To request permission, contact Token of Trust at legal@tokenoftrust.com.
+
+4. NO TRADEMARK LICENSE
+   This license grants no rights to the Token of Trust name, logos, or
+   trademarks.
+
+5. RESERVATION OF RIGHTS
+   All rights not expressly granted are reserved by Token of Trust. This is a
+   source-available license, not an open-source license; the Software is not
+   licensed under any OSI-approved license.
+
+6. TERMINATION
+   This license terminates automatically if you breach it. On termination you
+   must stop using the Software and destroy all copies in your possession.
+
+7. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL TOKEN OF TRUST BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# Storefront Runner
+
+A world-shareable, multi-tenant **renderer runtime** for the Token of Trust
+storefront. It serves N tenants (or differently-named variants of one tenant) at
+path-prefix URLs — the same thing `astro dev` does for the full platform — with
+the control-plane services (content authoring, compliance, and the publish/deploy
+control plane) kept private and **physically carved out**.
+
+## Run
+
+```sh
+pnpm install
+pnpm dev            # astro dev on http://localhost:4321
+```
+
+Tenants resolve by `Host` header first, then by a `/<domain>/…` path prefix
+(DNS-free, for localhost). Try:
+
+- http://localhost:4321/                        (the neutral "home" default)
+- http://localhost:4321/sample-store.example/   (generic sample store — shows the 21+ compliance gate)
+
+Your OWN tenant is served by the `tot dev` loop, which grafts your checkout into
+`tenants/<id>/` at runtime — no bundled merchants ship with the runner.
+
+## Add a tenant
+
+Adding a tenant is a one-object edit in `apps/storefront/src/config/tenants.ts`
+(see `SAMPLE_TENANT`), plus a `tenants/<id>/` directory for its
+content/theme/public assets.
+
+## IP boundary
+
+This distributable depends only on `@tot/public-runtime` (the renderer-safe
+model). The private control-plane package is absent, so a control-plane import
+cannot resolve here.
+
+## License
+
+Source-available, **local-development only** (see `LICENSE`). You may run, build,
+and modify this for Local Development. Any other use — deploying, hosting, or
+serving it to third parties, or any production/commercial use — requires the
+prior written permission of Token of Trust, Inc.

package/apps/storefront/astro.config.mjs

@@ -0,0 +1,66 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import cloudflare from "@astrojs/cloudflare";
+import preact from "@astrojs/preact";
+import tailwindcss from "@tailwindcss/vite";
+import { tenantHotReload } from "./dev-plugins/tenant-hot-reload.mjs";
+
+// SSR on Cloudflare Workers. `output: 'server'` because every response is
+// tenant-resolved at the edge from the Host header (see src/middleware).
+// Preact powers the handful of interactive islands (variant selector, gallery,
+// facets, search typeahead, mobile drawer) — near-zero JS everywhere else.
+export default defineConfig({
+  output: "server",
+  // Externalize all CSS (no auto-inlined <style>) so a strict CSP needs no
+  // inline-style allowance for elements — every stylesheet is a 'self' <link>.
+  // Small first-paint tradeoff, offset by cross-page caching (see LIMITATIONS).
+  build: { inlineStylesheets: "never" },
+  adapter: cloudflare({
+    // Local image/asset placeholders are served from /public; real product
+    // images get rehosted to R2 in Phase 1 ETL (see DECISIONS.md).
+    imageService: "compile",
+  }),
+  integrations: [preact({ compat: true })],
+  vite: {
+    plugins: [tailwindcss(), tenantHotReload()],
+    optimizeDeps: {
+      // Vite's SSR optimizer can try to prebundle the Cloudflare adapter's
+      // worker entrypoints, then the worker runner looks for a generated
+      // deps_ssr module that may not exist after a restart/HMR cache turn.
+      // Keep adapter entrypoints external so workerd loads the real package
+      // exports from @astrojs/cloudflare instead of an optimized cache file.
+      exclude: [
+        "@astrojs/cloudflare/entrypoints/server",
+        "@astrojs/cloudflare/entrypoints/server.js",
+        "@astrojs/cloudflare/entrypoints/preview",
+        "@astrojs/cloudflare/entrypoints/preview.js",
+      ],
+    },
+    // Dev-only: let the dev server accept tenant Host headers so host-based
+    // tenant routing can be tested locally (e.g. curl -H 'Host: sample-store.example').
+    // Prod runs on Cloudflare Workers, which has no such allowlist.
+    server: {
+      allowedHosts: [
+        "sample-store.example",
+        "www.sample-store.example",
+        "pilot.tokenoftrust.com",
+      ],
+      // Containerized `tot dev` (scripts/dev): a bind-mount often doesn't deliver
+      // inotify events, so Vite's file watcher must POLL for save→HMR to fire.
+      // Gated on CHOKIDAR_USEPOLLING (set by the dev image/compose) so native/local
+      // dev keeps instant, zero-overhead event-based watching. Explicit rather than
+      // relying on Vite auto-reading the env, so it's version-proof.
+      ...(process.env.CHOKIDAR_USEPOLLING
+        ? {
+            watch: {
+              usePolling: true,
+              interval: Number(process.env.CHOKIDAR_INTERVAL) || 300,
+            },
+          }
+        : {}),
+    },
+  },
+  // Canonical/sitemap host comes from the resolved tenant, not here.
+  // `site` is a fallback only used when no tenant context is available.
+  site: "https://pilot.tokenoftrust.com",
+});

package/apps/storefront/dev-plugins/dev-loop-state.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+//
+// In-memory state for the /dev live-loop Monitor (C1). A module singleton — one
+// per dev-server process, shared by the tenant-hot-reload plugin (which records
+// saves) and the dev-loop-monitor plugin (which records reloads + serves the
+// status endpoint). Never reaches production: every dev-plugin runs
+// `apply: "serve"`, so this module is loaded only under `astro dev`.
+//
+// The Monitor reads this via GET /__tot/dev-loop-status (poll) and via the
+// `tot:loop` custom HMR event; both carry the same snapshot(). The message
+// envelope {type, at, seq, payload} is the extensible P0 seam — each later phase
+// (tot:file-changed, tot:write-applied, …) adds a `type` string without
+// changing this shape.
+//
+// NOTE — markReload()/snapshot()/loopEnvelope() are consumed ONLY by
+// dev-loop-monitor.mjs, which is a cockpit-only plugin excluded from the
+// shipped LOCAL RUNNER build (scripts/build/build-runner.mjs's DROP set) — this
+// module ships there too (tenant-hot-reload.mjs's markSave/activity-bridge
+// dependency), so within the pruned runner tree those three exports are
+// unreachable. That's expected, not a bug: this file still serves BOTH the
+// monorepo's own `astro dev` (where dev-loop-monitor.mjs IS wired, per
+// apps/storefront/astro.config.mjs) and the runner (markSave/activity-bridge
+// only). Don't delete them thinking they're dead — they're dead only from the
+// runner's vantage point.
+
+/** @typedef {"change"|"add"|"unlink"} LoopEvent */
+
+const state = {
+  /** dev server is up (true for the life of the process). */
+  server: true,
+  /** resolved dev-server port, once known. */
+  port: /** @type {number|null} */ (null),
+  /** last saved file, repo-relative posix (e.g. "tokenoftrust/content/home.html"). */
+  watchedFile: /** @type {string|null} */ (null),
+  /** epoch ms of the last watched-file save seen. */
+  lastSaveAt: /** @type {number|null} */ (null),
+  /** epoch ms of the last full-reload broadcast to the browser. */
+  lastReloadAt: /** @type {number|null} */ (null),
+  /** kind of the last file event (C2 fills add/unlink; C1 only sees change). */
+  lastEvent: /** @type {LoopEvent|null} */ (null),
+  /** epoch ms the process/state came up. */
+  startedAt: Date.now(),
+};
+
+let seq = 0;
+
+/** The live mutable state object (shared by the plugins). */
+export function getLoopState() {
+  return state;
+}
+
+// --- local→hosted activity bridge ------------------------------------------
+// When `tot login --code` cached an activity-bridge credential (piggybacked on
+// the invite paste — see packages/cli/src/commands/login.mjs), `tot dev`
+// threads it in as these two env vars (commands/dev.mjs runMonorepo). Report
+// each save to the developer's own hosted /dev panel so its activity log +
+// Step-2 gate can react — debounced (rapid saves collapse to the latest) and
+// best-effort: a failed/offline hosted worker must NEVER break the local loop.
+const ACTIVITY_REPORT_DEBOUNCE_MS = 800;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let activityReportTimer = null;
+
+/**
+ * @param {string} relFile tenant-relative posix path
+ * @param {LoopEvent} event
+ */
+/** POST one activity body to the hosted panel, best-effort. No-op without the bridge env.
+ * @param {Record<string, unknown>} body */
+function postActivity(body) {
+  const url = process.env.TOT_DEV_ACTIVITY_URL;
+  const token = process.env.TOT_DEV_ACTIVITY_TOKEN;
+  if (!url || !token) return; // no hosted bridge cached — plain local dev, unchanged
+  fetch(`${String(url).replace(/\/+$/, "")}/api/dev/activity`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  }).catch(() => {
+    /* best-effort — hosted panel just won't show this event */
+  });
+}
+
+/** @param {string} relFile @param {LoopEvent} event */
+function scheduleActivityReport(relFile, event) {
+  if (!process.env.TOT_DEV_ACTIVITY_URL || !process.env.TOT_DEV_ACTIVITY_TOKEN) return;
+  if (activityReportTimer) clearTimeout(activityReportTimer);
+  const at = Date.now();
+  activityReportTimer = setTimeout(() => postActivity({ file: relFile, event, at }), ACTIVITY_REPORT_DEBOUNCE_MS);
+  if (typeof activityReportTimer.unref === "function") activityReportTimer.unref();
+}
+
+/**
+ * Report that the developer's store is UP + serving — the hosted /dev panel uses this
+ * to complete Step 1 ("Get running") the moment the site is live, BEFORE any edit.
+ * One-shot, best-effort. Safe to call once the dev server answers.
+ */
+export function reportServerUp() {
+  postActivity({ event: "up", at: Date.now() });
+}
+
+/**
+ * Record the resolved dev-server port (best-effort, idempotent).
+ * @param {unknown} p
+ */
+export function setPort(p) {
+  if (typeof p === "number" && Number.isFinite(p)) state.port = p;
+}
+
+/**
+ * Record a watched-file save.
+ * @param {string} relFile repo-relative posix path
+ * @param {LoopEvent} [event]
+ */
+export function markSave(relFile, event = "change") {
+  state.lastSaveAt = Date.now();
+  state.watchedFile = relFile;
+  state.lastEvent = event;
+  scheduleActivityReport(relFile, event);
+}
+
+/** Record a full-reload having been broadcast to the browser. */
+export function markReload() {
+  state.lastReloadAt = Date.now();
+}
+
+/**
+ * Serializable snapshot for GET /__tot/dev-loop-status and the tot:loop payload.
+ * `tenant` is read live from the env (set by scripts/tot-dev.mjs on this Node
+ * process — the Vite layer sees it reliably, unlike SSR/workerd).
+ */
+export function snapshot() {
+  return {
+    server: state.server,
+    port: state.port,
+    tenant: process.env.TOT_DEV_TENANT || null,
+    watchedFile: state.watchedFile,
+    lastSaveAt: state.lastSaveAt,
+    lastReloadAt: state.lastReloadAt,
+    lastEvent: state.lastEvent,
+    startedAt: state.startedAt,
+  };
+}
+
+/** The extensible message envelope (P0 seam): {type, at, seq, payload}. */
+export function loopEnvelope() {
+  seq += 1;
+  return { type: "tot:loop", at: Date.now(), seq, payload: snapshot() };
+}

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

@@ -0,0 +1,238 @@
+// @ts-check
+import { fileURLToPath } from "node:url";
+import { readdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { markSave, reportServerUp } from "./dev-loop-state.mjs";
+
+// Repo-root tenants/ dir (colocated tenant layout) + the generated static dest
+// the predev copy step mirrors public/ into. This module lives at
+// apps/storefront/dev-plugins/, so tenants/ is three levels up. Forward-slash
+// normalized to match Vite's ctx.file (Vite always reports posix-style paths).
+const TENANTS_DIR = fileURLToPath(new URL("../../../tenants", import.meta.url)).replace(/\\/g, "/");
+const PUBLIC_TENANTS_DEST = fileURLToPath(new URL("../public/tenants", import.meta.url));
+
+/**
+ * Classify a watched absolute path as a tenant file: → { id, rest } where `rest`
+ * is tenant-relative posix ("content/home.html", "public/logo.png"), or null if
+ * the path isn't under a tenant. Shared by handleHotUpdate (change) and the
+ * add/unlink watcher handlers so both agree on the content/-vs-public/ split.
+ * @param {string} file
+ * @returns {{ id: string, rest: string } | null}
+ */
+export function classifyTenantFile(file) {
+  const f = String(file).replace(/\\/g, "/");
+  if (!f.startsWith(TENANTS_DIR + "/")) return null;
+  const rel = f.slice(TENANTS_DIR.length + 1); // "<id>/<...>"
+  const slash = rel.indexOf("/");
+  if (slash < 0) return null;
+  return { id: rel.slice(0, slash), rest: rel.slice(slash + 1) };
+}
+
+/** True for the raw content HTML that's read fresh from disk per request. @param {string} rest */
+export function isContentHtml(rest) {
+  return rest.startsWith("content/") && rest.endsWith(".html");
+}
+
+/**
+ * Is this tenant opted out of static-asset mirroring (R2-versioned)? Matches
+ * scripts/build/copy-tenant-assets.mjs's isVersioned EXACTLY (both the marker
+ * file AND the TENANT_ASSETS_VERSIONED env var count) — the predev build and
+ * this dev-loop mirror must agree, or a tenant opted out solely via the env
+ * var would still get its R2-versioned assets silently shadowed by a dev-loop
+ * save mirroring into public/tenants/<id>/.
+ * @param {string} id
+ */
+export function isVersionedTenant(id) {
+  const envList = (process.env.TENANT_ASSETS_VERSIONED ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (envList.includes(id)) return true;
+  return existsSync(join(TENANTS_DIR, 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;
+  const { cp, mkdir } = await import("node:fs/promises");
+  const target = join(PUBLIC_TENANTS_DEST, id, rest.slice("public/".length));
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    await cp(sourceFile, target);
+  } catch {
+    /* best-effort; still reload */
+  }
+}
+
+/**
+ * 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;
+  const { rm } = await import("node:fs/promises");
+  const target = join(PUBLIC_TENANTS_DEST, id, rest.slice("public/".length));
+  try {
+    await rm(target, { force: true });
+  } catch {
+    /* best-effort; still reload */
+  }
+}
+
+/**
+ * Seed the set of tenant files present when watching starts. Chokidar re-emits
+ * an "add" for every pre-existing file under a path passed to `.add()` after the
+ * initial scan (TENANTS_DIR sits ABOVE the Astro root, so it IS a post-ready
+ * add) — without this snapshot that boot echo would flood the Monitor with
+ * bogus "add" events and re-mirror every asset. Real adds (files created after
+ * boot) aren't in the set. Dependency-free recursive walk; dev-only + small.
+ * @param {string} root
+ * @param {Set<string>} known
+ */
+export function seedKnown(root, known) {
+  const walk = (/** @type {string} */ dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const abs = `${dir}/${e.name}`;
+      if (e.isDirectory()) walk(abs);
+      else if (e.isFile()) known.add(abs);
+    }
+  };
+  walk(root);
+}
+
+// Dev-only default posture: save a colocated tenant file → the browser reloads.
+// The `tenants/<id>/` tree sits ABOVE the Astro root and reaches the app only
+// through a lazy `?raw` glob (HTML, bypassed by the dev disk-read) or the predev
+// public/ copy — never Vite's own module graph — so Vite doesn't watch it and a
+// save would otherwise do nothing. We watch it explicitly and reload on change:
+//   - content/**.html — read fresh from disk per request
+//     (LocalContentProvider.readRawDevFile), so just reload. (The Vite HMR client
+//     is injected into these otherwise-pipeline-bypassing pages in dev; see
+//     rawHtmlResponse in src/lib/rawMarketingHtml.ts.)
+//   - public/**        — re-mirror the one changed asset into public/tenants/<id>/
+//     (skipping R2-versioned tenants, like copy-tenant-assets.mjs), then reload.
+// content/*.json, themes/*.json and theme.json are ordinary glob imports, so Vite
+// already invalidates + reloads them — left to default handling. Returning []
+// suppresses the pointless glob HMR that would otherwise fire for the raw files.
+//
+// RENAME/DELETE (C2): handleHotUpdate fires only on "change". Empirically, an
+// add/unlink of a content/*.html file already triggers a correct Vite full-reload
+// (its `?raw` glob is invalidated) and never crashes — so for content HTML we ONLY
+// record the event for the Monitor and let Vite reload (sending our own would race
+// 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() {
+  // 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
+  // untyped without that reference.
+  /** @type {any} */
+  const plugin = {
+    name: "tot:tenant-hot-reload",
+    apply: "serve",
+    /** @param {any} server */
+    configureServer(server) {
+      server.watcher.add(TENANTS_DIR);
+
+      // 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,
+      // no-op without the activity-bridge env (see reportServerUp / dev-loop-state).
+      try {
+        server.httpServer?.once?.("listening", () => reportServerUp());
+      } catch { /* best-effort */ }
+
+      // Guard the initial-scan add echo (see seedKnown). Maintained as files are
+      // really added/removed so the guard stays accurate for the session.
+      /** @type {Set<string>} */
+      const known = new Set();
+      seedKnown(TENANTS_DIR, known);
+
+      /** @param {"add"|"unlink"} event @param {string} rawPath */
+      const onAddUnlink = async (event, rawPath) => {
+        const file = String(rawPath).replace(/\\/g, "/");
+        const c = classifyTenantFile(file);
+        if (!c) return;
+        const { id, rest } = c;
+
+        if (event === "add") {
+          if (known.has(file)) return; // initial-scan echo, not a real add
+          known.add(file);
+        } else {
+          known.delete(file);
+        }
+
+        // Record the event for the live-loop Monitor (C1) — lastEvent = add/unlink.
+        markSave(rest, event);
+
+        // Content HTML: Vite's `?raw` glob invalidation already emits a correctly
+        // timed full-reload; don't send our own (teardown race). Just recorded above.
+        if (isContentHtml(rest)) return;
+
+        // 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);
+          server.ws.send({ type: "full-reload" });
+          return;
+        }
+
+        // json/theme add/unlink: ordinary glob imports — Vite reloads them; the
+        // markSave above is enough for the Monitor.
+      };
+
+      server.watcher.on("add", (/** @type {string} */ p) => onAddUnlink("add", p));
+      server.watcher.on("unlink", (/** @type {string} */ p) => onAddUnlink("unlink", p));
+    },
+    /** @param {any} ctx */
+    async handleHotUpdate(ctx) {
+      const c = classifyTenantFile(ctx.file);
+      if (!c) return undefined;
+      const { id, rest } = c;
+
+      // Record the save for the live-loop Monitor (C1) the instant a watched
+      // tenant file changes — before any branch below decides how to reload.
+      // `rest` is tenant-relative (e.g. "content/home.html"), matching the
+      // Monitor's readout. Covers content HTML, public assets, and the
+      // json/theme files that fall through to Vite's default handling. The
+      // matching reload is timestamped by dev-loop-monitor's ws/hot wrap.
+      markSave(rest, "change");
+
+      // Content HTML: the change invalidates the SSR module graph, so the
+      // Cloudflare Vite plugin reloads the worker and — once it is ready — emits
+      // its own correctly-timed full-reload (which the injected Vite HMR client
+      // acts on). We must NOT send our own reload: firing on the raw file-change
+      // event races ahead of the worker reload, so the browser re-navigates while
+      // miniflare is mid-teardown → "page not loaded" + an error overlay. Just let
+      // default handling run.
+      if (isContentHtml(rest)) {
+        return undefined;
+      }
+
+      // Public assets (CSS, images) aren't in the module graph — they're mirrored
+      // into public/tenants/<id>/ at predev, and a programmatic write there does
+      // NOT trip the platform's own reload. So: re-mirror the one changed file
+      // (await it so the served copy is current), THEN send the reload ourselves.
+      // 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, "/"));
+        ctx.server.ws.send({ type: "full-reload" });
+        return [];
+      }
+
+      return undefined;
+    },
+  };
+  return plugin;
+}