@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/lib/demoGate.ts

@@ -0,0 +1,113 @@
+/**
+ * Demo password gate (HTTP Basic Auth) for named hosts.
+ *
+ * A lightweight "put a password in front of it before we show it" gate for demo
+ * subdomains (e.g. shop.tokenoftrust.store). Deliberately DISTINCT from the
+ * ShipLoop customization-preview gate (resolveCustomizationEnv / `preview.` hosts
+ * + signed, tenant-bound tokens): this is a single shared static password,
+ * browser-native, covering every path + subresource on the host. It runs first
+ * in the middleware so a blocked host never reaches tenant resolution, the edge
+ * cache, or any render.
+ *
+ * Config is env-driven so gating/ungating a host or rotating the password needs
+ * NO code change:
+ *   DEMO_GATE_HOSTS    comma-separated hostnames to gate ("" / unset = none)
+ *   DEMO_GATE_PASSWORD the shared password (set via `wrangler secret`; unset = off)
+ *   DEMO_GATE_REALM    optional Basic-Auth realm label (default "Demo")
+ *
+ * The username is IGNORED — share it as "any username, password: …", the usual
+ * demo pattern. If no password is configured the gate is a no-op everywhere.
+ */
+
+const REALM_FALLBACK = "Demo";
+
+/** Lowercase, trim, and drop any `:port` suffix so host matching is exact. */
+export function normalizeHost(host: string): string {
+  return host.trim().toLowerCase().replace(/:\d+$/, "");
+}
+
+/**
+ * True when `host` matches the comma-separated gate list (case/port-insensitive).
+ *
+ * Entries are either an exact host (`storefront.tokenoftrust.workers.dev`) or a
+ * leading-`*.` wildcard (`*.tokenoftrust.store`) that matches ANY subdomain of
+ * that zone at any depth — `shop.tokenoftrust.store`,
+ * `storefront.tokenoftrust.store`, `preview.acme.tokenoftrust.store` — but NOT
+ * the bare apex. Wildcards are what let us gate every tenant (present + future)
+ * on a shared zone without enumerating each host.
+ */
+export function hostInGateList(host: string, hostsCsv: string | null | undefined): boolean {
+  const h = normalizeHost(host);
+  const list = (hostsCsv ?? "").split(",").map(normalizeHost).filter(Boolean);
+  for (const entry of list) {
+    if (entry.startsWith("*.")) {
+      const suffix = entry.slice(1); // ".tokenoftrust.store"
+      if (h.length > suffix.length && h.endsWith(suffix)) return true;
+    } else if (h === entry) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Parse the password out of an `Authorization: Basic …` header; null if absent/malformed. */
+function passwordFromAuthHeader(header: string | null): string | null {
+  if (!header) return null;
+  const [scheme, encoded] = header.split(" ");
+  if (!scheme || scheme.toLowerCase() !== "basic" || !encoded) return null;
+  let decoded: string;
+  try {
+    decoded = atob(encoded);
+  } catch {
+    return null;
+  }
+  const colon = decoded.indexOf(":");
+  if (colon === -1) return null;
+  return decoded.slice(colon + 1);
+}
+
+/** Length-hiding constant-time-ish string equality (avoids early-exit timing leaks). */
+function safeEqual(a: string, b: string): boolean {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
+
+export interface DemoGateEnv {
+  hosts?: string | null;
+  password?: string | null;
+  realm?: string | null;
+}
+
+/**
+ * Decide whether a request to `host` is allowed past the demo gate.
+ * Returns a 401 Response to send when the gate blocks; null when the host is
+ * ungated, the gate is disabled, or valid credentials were supplied.
+ */
+export function evaluateDemoGate(
+  host: string,
+  authorization: string | null,
+  env: DemoGateEnv,
+): Response | null {
+  const password = env.password?.trim();
+  if (!password) return null; // no password configured → gate disabled globally
+
+  if (!hostInGateList(host, env.hosts)) return null; // this host isn't gated
+
+  const supplied = passwordFromAuthHeader(authorization);
+  if (supplied !== null && safeEqual(supplied, password)) return null; // authorized
+
+  const realm = (env.realm?.trim() || REALM_FALLBACK).replace(/"/g, "");
+  return new Response("Authentication required.", {
+    status: 401,
+    headers: {
+      "WWW-Authenticate": `Basic realm="${realm}", charset="UTF-8"`,
+      "Content-Type": "text/plain; charset=utf-8",
+      // Never let a browser/CDN cache the challenge or a would-be authorized body.
+      "Cache-Control": "no-store",
+    },
+  });
+}

package/apps/storefront/src/lib/dev/activityIngestToken.ts

@@ -0,0 +1,78 @@
+/**
+ * Opaque, SESSION-KV-backed credential that lets a developer's LOCAL dev-loop
+ * process authenticate POST /api/dev/activity on the hosted Worker — the
+ * local→hosted activity bridge (handoff
+ * 2026-07-14-hosted-dev-activity-bridge-and-stepper).
+ *
+ * Minted alongside the existing cli-signin-code paste
+ * (apps/storefront/src/lib/dev/cliSignInCode.ts) and cached by the CLI in
+ * ~/.tot/credentials.json. Deliberately NOT a signed token: this reuses the
+ * SESSION KV binding that already exists in every environment (dev/qa/prod),
+ * so it needs no new secret to provision. Revoking is just deleting the KV
+ * entry — the same posture as the browser's own tot_session cookie (see
+ * lib/auth/session.ts).
+ */
+
+const KEY_PREFIX = "dev-activity-token:";
+/** Secondary index: developer+tenant -> their current live token, so a re-mint can
+ * revoke the previous one instead of accumulating an unbounded number of live
+ * 30-day credentials (every fresh invite/sign-in paste mints a new one). */
+const INDEX_PREFIX = "dev-activity-token-by-dev:";
+/** 30 days — re-minted on every fresh invite/sign-in paste, so this rarely lapses in practice. */
+const TTL_SECONDS = 30 * 24 * 3600;
+
+export interface ActivityIngestClaims {
+  email: string;
+  tenant: string;
+  capability: string;
+}
+
+function newToken(): string {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function indexKey(email: string, tenant: string): string {
+  return `${INDEX_PREFIX}${tenant}:${email}`;
+}
+
+/**
+ * Mint a fresh activity-ingest token scoped to this developer + their own tenant.
+ * Revokes any token previously minted for the SAME developer+tenant first, so
+ * repeated invite/sign-in pastes leave at most one live credential per
+ * developer+tenant instead of accumulating indefinitely.
+ */
+export async function mintActivityIngestToken(
+  kv: KVNamespace,
+  claims: ActivityIngestClaims,
+): Promise<{ token: string; expiresAt: string }> {
+  const idxKey = indexKey(claims.email, claims.tenant);
+  const priorToken = await kv.get(idxKey);
+  if (priorToken) await kv.delete(KEY_PREFIX + priorToken);
+
+  const token = newToken();
+  const expiresAt = new Date(Date.now() + TTL_SECONDS * 1000).toISOString();
+  await kv.put(KEY_PREFIX + token, JSON.stringify(claims), { expirationTtl: TTL_SECONDS });
+  await kv.put(idxKey, token, { expirationTtl: TTL_SECONDS });
+  return { token, expiresAt };
+}
+
+/** Verify a bearer token from a local dev-loop POST. Null when absent/expired/malformed. */
+export async function verifyActivityIngestToken(
+  kv: KVNamespace,
+  token: string,
+): Promise<ActivityIngestClaims | null> {
+  if (!token) return null;
+  const raw = await kv.get(KEY_PREFIX + token);
+  if (!raw) return null;
+  try {
+    const claims = JSON.parse(raw) as ActivityIngestClaims;
+    if (!claims?.tenant || !claims?.email) return null;
+    return claims;
+  } catch {
+    return null;
+  }
+}

package/apps/storefront/src/lib/dev/activityStore.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-vendor "recent activity" feed for the hosted /dev panel — a small ring
+ * buffer of file-save events reported by a developer's LOCAL dev loop (see
+ * activityIngestToken.ts for the write-path auth). File-level only, per
+ * decision (no per-line diff, no separate published-history tier — see
+ * handoff 2026-07-14-hosted-dev-activity-bridge-and-stepper).
+ */
+
+export type ActivityEventKind = "change" | "add" | "unlink" | "up";
+
+export interface ActivityEvent {
+  /** Tenant-relative file path for content events; omitted for status pings ("up"). */
+  file?: string;
+  event: ActivityEventKind;
+  /** Epoch ms, as reported by the local loop. */
+  at: number;
+}
+
+const KEY_PREFIX = "dev-activity:";
+const MAX_EVENTS = 30;
+/** Ephemeral, session-scoped buffer — v1 scope (file-level only, no durable history). */
+const TTL_SECONDS = 24 * 3600;
+
+function key(appDomain: string): string {
+  return KEY_PREFIX + appDomain;
+}
+
+/** Read the vendor's recent activity, oldest first. Never throws. */
+export async function readActivity(kv: KVNamespace, appDomain: string): Promise<ActivityEvent[]> {
+  try {
+    const raw = await kv.get(key(appDomain));
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Append one reported event to the vendor's ring buffer (bounded, TTL'd). */
+export async function appendActivity(
+  kv: KVNamespace,
+  appDomain: string,
+  ev: ActivityEvent,
+): Promise<void> {
+  const existing = await readActivity(kv, appDomain);
+  const next = [...existing, ev].slice(-MAX_EVENTS);
+  await kv.put(key(appDomain), JSON.stringify(next), { expirationTtl: TTL_SECONDS });
+}
+
+/**
+ * Business-readable translation of a reported file path + event, for the
+ * activity log. File-level only — no per-line diff enrichment (Darrin,
+ * 2026-07-14: "we can show that in step 2").
+ */
+export function describeActivity(file: string | undefined, event: ActivityEventKind): string {
+  if (event === "up") return "Your store is running locally";
+  const f = (file || "").replace(/^\/+/, "");
+  const verb = event === "add" ? "added" : event === "unlink" ? "removed" : "edited";
+
+  if (f === "content/home.html") return `Home page ${verb}`;
+  if (f.startsWith("content/") && f.endsWith(".html")) {
+    const page = f.slice("content/".length, -".html".length);
+    return `Page "${page}" ${verb}`;
+  }
+  if (f.startsWith("content/") && f.endsWith(".json")) {
+    return event === "change" ? "Page content updated" : `Page content ${verb}`;
+  }
+  if (f === "theme.json" || /theme.*\.css$/i.test(f)) return "Branding/theme changed";
+  if (f.startsWith("public/")) return `Image/asset ${verb}`;
+  return `${f} ${verb}`;
+}

package/apps/storefront/src/lib/dev/ai-widget-client.js

@@ -0,0 +1,308 @@
+// The floating "✦ ask" affordance for `tot dev`'s inline-AI edit loop (WS5 G1).
+// Injected into every page ONLY in `astro dev` by inlineAiEditPlugin in
+// astro.config.mjs (never bundled into the production build — this file isn't
+// imported by any Astro page/component, only served verbatim by that dev-only
+// Vite middleware). Talks to /__tot/ai-edit and /__tot/ai-undo, which
+// scripts/dev/ai-edit.mjs implements against the tenant this `tot dev` run is
+// serving (TOT_DEV_TENANT).
+//
+// Plain vanilla JS, no build step, no framework — this never ships to users.
+
+(function () {
+  const ROOT_ID = "__tot-ai-widget";
+  if (document.getElementById(ROOT_ID)) return; // one instance per page
+
+  const root = document.createElement("div");
+  root.id = ROOT_ID;
+  root.innerHTML = `
+    <style>
+      #${ROOT_ID} { position: fixed; right: 1rem; bottom: 1rem; z-index: 2147483647;
+        font: 14px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      #${ROOT_ID} .toggle { width: 3rem; height: 3rem; border-radius: 999px; border: none;
+        background: #16181d; color: #e8e6e0; font-size: 1.25rem; cursor: pointer;
+        box-shadow: 0 8px 24px -8px rgba(0,0,0,.45); }
+      #${ROOT_ID} .toggle:hover { background: #23262d; }
+      #${ROOT_ID} .panel { display: none; position: absolute; right: 0; bottom: 3.75rem;
+        width: 22rem; max-width: 90vw; background: #fff; color: #16191d; border-radius: 12px;
+        box-shadow: 0 16px 40px -12px rgba(0,0,0,.35); border: 1px solid #e4e0d6; padding: .9rem; }
+      #${ROOT_ID}.open .panel { display: block; }
+      #${ROOT_ID} textarea { width: 100%; box-sizing: border-box; resize: vertical; min-height: 3.5rem;
+        border: 1px solid #d8d4c8; border-radius: 8px; padding: .5rem .6rem; font: inherit; }
+      #${ROOT_ID} .row { display: flex; gap: .4rem; margin-top: .5rem; }
+      #${ROOT_ID} button.primary { flex: 1; background: #0f7b6c; color: #fff; border: none;
+        border-radius: 8px; padding: .5rem .7rem; font: 600 .85rem/1 inherit; cursor: pointer; }
+      #${ROOT_ID} button.primary:disabled { opacity: .5; cursor: default; }
+      #${ROOT_ID} button.secondary { background: #ece9e0; color: #2a2d31; border: none;
+        border-radius: 8px; padding: .5rem .7rem; font: 600 .8rem/1 inherit; cursor: pointer; }
+      #${ROOT_ID} .status { margin-top: .6rem; font-size: .82rem; white-space: pre-wrap; }
+      #${ROOT_ID} .status.error { color: #a83a3a; }
+      #${ROOT_ID} .status.ok { color: #0f7b6c; }
+      #${ROOT_ID} details { margin-top: .5rem; }
+      #${ROOT_ID} pre { max-height: 12rem; overflow: auto; background: #16181d; color: #dbe3ea;
+        border-radius: 8px; padding: .5rem .6rem; font-size: .75rem; }
+      /* Locate mode (C7): highlight box, hint, and result toast — top-level ids so
+         they overlay the whole page, outside the widget's own stacking. */
+      #${ROOT_ID}-locate-hi { position: fixed; z-index: 2147483646; pointer-events: none;
+        border: 2px solid #0f7b6c; background: rgba(15,123,108,.12); border-radius: 3px; display: none; }
+      #${ROOT_ID}-locate-hint { position: fixed; left: 50%; top: 1rem; transform: translateX(-50%);
+        z-index: 2147483647; background: #16181d; color: #e8e6e0; font: 600 .8rem/1 -apple-system, sans-serif;
+        padding: .55rem .9rem; border-radius: 999px; box-shadow: 0 8px 24px -8px rgba(0,0,0,.45); display: none; }
+      #${ROOT_ID}-locate-toast { position: fixed; left: 50%; bottom: 1rem; transform: translateX(-50%) translateY(160%);
+        z-index: 2147483647; background: #16181d; color: #e8e6e0; display: flex; align-items: center;
+        font: 500 .8rem/1.3 ui-monospace, Menlo, monospace; padding: .6rem 1rem; border-radius: 8px;
+        box-shadow: 0 8px 24px -8px rgba(0,0,0,.45); transition: transform .25s; max-width: 90vw; }
+      #${ROOT_ID}-locate-toast.show { transform: translateX(-50%) translateY(0); }
+    </style>
+    <button class="toggle" type="button" aria-label="Ask AI to edit this site" title="Ask AI to edit this site">✦</button>
+    <div class="panel">
+      <textarea placeholder="e.g. make it darker but still friendly" aria-label="Describe the change"></textarea>
+      <div class="row">
+        <button class="primary" type="button" data-action="ask">Ask</button>
+        <button class="secondary" type="button" data-action="undo">Undo last</button>
+        <button class="secondary" type="button" data-action="locate" title="Click an element on the page to jump to its source">◎ Locate</button>
+      </div>
+      <div class="status" role="status" aria-live="polite"></div>
+    </div>
+  `;
+  document.body.appendChild(root);
+
+  const toggle = root.querySelector(".toggle");
+  const textarea = root.querySelector("textarea");
+  const askBtn = root.querySelector('[data-action="ask"]');
+  const undoBtn = root.querySelector('[data-action="undo"]');
+  const status = root.querySelector(".status");
+
+  toggle.addEventListener("click", () => root.classList.toggle("open"));
+
+  function setStatus(text, kind) {
+    status.textContent = text;
+    status.className = "status" + (kind ? " " + kind : "");
+  }
+
+  function renderResult(result) {
+    if (!result.ok) {
+      setStatus(result.message || `Refused (${result.status}).`, "error");
+      return;
+    }
+    if (result.status === "noop") {
+      setStatus(result.summary || "No change was needed.", "ok");
+      return;
+    }
+    setStatus(`✔ ${result.summary} — reloading…`, "ok");
+    // The file write already fires the existing content/theme HMR watch (see
+    // astro.config.mjs's tenantHotReload); nothing else to do here.
+  }
+
+  async function postJson(path, body) {
+    const res = await fetch(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body || {}),
+    });
+    return res.json();
+  }
+
+  askBtn.addEventListener("click", async () => {
+    const prompt = textarea.value.trim();
+    if (!prompt) return;
+    askBtn.disabled = true;
+    setStatus("Asking…");
+    try {
+      const result = await postJson("/__tot/ai-edit", { prompt });
+      renderResult(result);
+    } catch (e) {
+      setStatus(`Request failed: ${e.message}`, "error");
+    } finally {
+      askBtn.disabled = false;
+    }
+  });
+
+  undoBtn.addEventListener("click", async () => {
+    undoBtn.disabled = true;
+    setStatus("Undoing…");
+    try {
+      const result = await postJson("/__tot/ai-undo", {});
+      if (!result.ok) {
+        setStatus(result.message || "Nothing to undo.", "error");
+      } else {
+        setStatus(`↺ Reverted "${result.undid}" — reloading…`, "ok");
+      }
+    } catch (e) {
+      setStatus(`Request failed: ${e.message}`, "error");
+    } finally {
+      undoBtn.disabled = false;
+    }
+  });
+
+  textarea.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) askBtn.click();
+  });
+
+  // ── Locate mode (C7): click an element → its source file:line:col ──────────
+  // Enter locate mode, hover to highlight, click an element: we capture a DOM path
+  // and POST it to /__tot/locate, which (server-side, scripts/dev/dev-locate.mjs)
+  // parses the raw-HTML tenant source with parse5 and walks the SAME path to a
+  // line:col. captureDomPath MUST stay in lockstep with scripts/dev/locate.mjs's
+  // walk (see its header + locate.test.mjs's round-trip): a DOM path is an array of
+  // { tag, index } from <body>'s child down to the target, index = 0-based position
+  // among same-tag element siblings (nth-of-type). Raw-HTML tenants only; the server
+  // refuses templated pages with { status: "not_raw_html" }.
+  function captureDomPath(el) {
+    const path = [];
+    let node = el;
+    while (node && node.tagName && node.tagName.toLowerCase() !== "body") {
+      const parent = node.parentElement;
+      if (!parent) break;
+      const tag = node.tagName.toLowerCase();
+      let index = 0;
+      for (let sib = node.previousElementSibling; sib; sib = sib.previousElementSibling) {
+        if (sib.tagName.toLowerCase() === tag) index += 1;
+      }
+      path.unshift({ tag, index });
+      if (parent.tagName && parent.tagName.toLowerCase() === "body") break;
+      node = parent;
+    }
+    return path;
+  }
+  // Exposed for the in-browser verification harness (dev-only, harmless in prod
+  // since this whole file is never bundled into the production build).
+  window.__totCaptureDomPath = captureDomPath;
+
+  const locateBtn = root.querySelector('[data-action="locate"]');
+  let hi, hint, ltoast, locating = false, lastHover = null;
+
+  function ensureLocateEls() {
+    if (hi) return;
+    hi = document.createElement("div");
+    hi.id = ROOT_ID + "-locate-hi";
+    hint = document.createElement("div");
+    hint.id = ROOT_ID + "-locate-hint";
+    hint.textContent = "Click an element to jump to its source · Esc to cancel";
+    ltoast = document.createElement("div");
+    ltoast.id = ROOT_ID + "-locate-toast";
+    document.body.append(hi, hint, ltoast);
+  }
+
+  function inWidget(el) {
+    return !!el && (el === root || root.contains(el) || el === hi || el === hint || el === ltoast);
+  }
+
+  function onMove(e) {
+    const el = document.elementFromPoint(e.clientX, e.clientY);
+    if (!el || inWidget(el)) {
+      hi.style.display = "none";
+      lastHover = null;
+      return;
+    }
+    lastHover = el;
+    const r = el.getBoundingClientRect();
+    hi.style.display = "block";
+    hi.style.left = r.left + "px";
+    hi.style.top = r.top + "px";
+    hi.style.width = r.width + "px";
+    hi.style.height = r.height + "px";
+  }
+
+  function showLToast(text, located) {
+    ensureLocateEls();
+    ltoast.textContent = text;
+    if (located) {
+      // Best-effort $EDITOR jump (server degrades gracefully when unset).
+      const open = document.createElement("button");
+      open.textContent = "Open in editor";
+      open.style.cssText =
+        "margin-left:.7rem;background:#0f7b6c;color:#fff;border:none;border-radius:6px;" +
+        "padding:.3rem .6rem;font:600 .72rem/1 -apple-system,sans-serif;cursor:pointer";
+      open.addEventListener("click", () => {
+        postJson("/__tot/open-in-editor", located).catch(() => {});
+      });
+      ltoast.appendChild(open);
+    }
+    ltoast.classList.add("show");
+    clearTimeout(showLToast._t);
+    showLToast._t = setTimeout(() => ltoast.classList.remove("show"), 6000);
+  }
+
+  async function onClick(e) {
+    if (inWidget(e.target)) return; // clicks on the widget itself pass through
+    e.preventDefault();
+    e.stopPropagation();
+    const el = lastHover || document.elementFromPoint(e.clientX, e.clientY);
+    exitLocate();
+    if (!el) return;
+    const domPath = captureDomPath(el);
+    // C8 (capstone) branches HERE: when framed (window !== window.parent) it
+    // postMessages { type:"tot:locate", path, line, col } to the parent editor
+    // instead of this standalone toast. C7 ships the standalone path only.
+    let res, body;
+    try {
+      res = await fetch("/__tot/locate", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ domPath, path: location.pathname }),
+      });
+      body = await res.json();
+    } catch (err) {
+      showLToast("Locate unavailable — is tot dev running?");
+      return;
+    }
+    // C8 capstone: when this page is FRAMED (the live-preview iframe inside /dev),
+    // deliver the result to the parent cockpit instead of a standalone toast — the
+    // parent opens the file + places the cursor. Only content-region hits (a real
+    // {line,col}) are forwarded; chrome/refused clicks stay silent inside the frame
+    // (no toast over the preview, no misleading jump), honoring the content-region
+    // decision. targetOrigin is our own origin (same-origin preview) — never "*".
+    const framed = window !== window.parent;
+    if (!res.ok || (body && body.status)) {
+      if (framed) return; // refused inside the frame — quietly no-op
+      showLToast(
+        body && body.status === "not_raw_html"
+          ? "Locate works on raw-HTML tenants only — this page is templated."
+          : "Couldn’t find that element in the source.",
+      );
+      return;
+    }
+    if (framed) {
+      try {
+        window.parent.postMessage(
+          { type: "tot:locate", path: body.path, line: body.line, col: body.col },
+          window.location.origin,
+        );
+      } catch (err) { /* parent gone / cross-origin — nothing to do */ }
+      return;
+    }
+    showLToast(`${body.path}:${body.line}:${body.col}`, body);
+  }
+
+  function onEsc(e) {
+    if (e.key === "Escape") {
+      e.preventDefault();
+      exitLocate();
+    }
+  }
+
+  function enterLocate() {
+    ensureLocateEls();
+    locating = true;
+    root.classList.remove("open");
+    hint.style.display = "block";
+    document.addEventListener("mousemove", onMove, true);
+    document.addEventListener("click", onClick, true);
+    document.addEventListener("keydown", onEsc, true);
+    document.body.style.cursor = "crosshair";
+  }
+
+  function exitLocate() {
+    locating = false;
+    if (hi) hi.style.display = "none";
+    if (hint) hint.style.display = "none";
+    document.removeEventListener("mousemove", onMove, true);
+    document.removeEventListener("click", onClick, true);
+    document.removeEventListener("keydown", onEsc, true);
+    document.body.style.cursor = "";
+  }
+
+  if (locateBtn) {
+    locateBtn.addEventListener("click", () => (locating ? exitLocate() : enterLocate()));
+  }
+})();

package/apps/storefront/src/lib/dev/apiBase.ts

@@ -0,0 +1,14 @@
+/**
+ * Environment-aware endpoint base for the /dev cockpit (file tree/viewer/diff +
+ * click-to-source). Local `astro dev` serves these off dev-server-only plugins at
+ * `/__tot/*` (dev-plugins/dev-file-browser.mjs, dev-write.mjs, dev-diff.mjs, ...) —
+ * paths that don't exist in the deployed Cloudflare Worker. The hosted Worker instead
+ * serves the SAME shape off `/api/dev/*` Astro API routes, landing incrementally
+ * (cp-tree, cp-file, cp-write, cp-diff, cp-locate). One dev.astro UI, one resolver.
+ *
+ * See decision `architecture-environment-aware-cockpit`
+ * (workstream tot-lime-cloud-dev-cockpit).
+ */
+export function resolveDevApiBase(isDev: boolean): string {
+  return isDev ? "/__tot" : "/api/dev";
+}