@augurworks/augur 0.15.2 → 0.15.4

package/src/_worker.js

@@ -104,6 +104,10 @@ import { PURGED_AUTHOR, purgeThreads, idCollisions } from "./purge.mjs";
 import { authoredUnits, unitOfPath, unitPaths } from "./publish-units.mjs";
 import { composePublish, forkLanded } from "./publish-compose.mjs";
 import { normUnit, splitDraftPath, unitTable, draftAddress, DRAFT_ID_RE } from "./unit-core.mjs";
+import {
+  siteModel, derivedPathKind, renderRootIndex, renderOpportunityIndex, renderPlaygroundIndex,
+  renderTierIndex, renderComponentsIndex, searchIndex, catalogFrom,
+} from "./galleries.mjs";
 // `F-fork-verb`. Fork as a deliberate verb — one unit aliased to a new path, zero bytes
 // moved — plus the rule that keeps a fork's lineage and owner alive across every later
 // publish. Both are pure, and both are the CLI's too if it ever needs them.
@@ -4333,7 +4337,7 @@ function resolveBundlePath(manifests, pathname) {
 // against. It is the first argument for the same reason `loadTenantContext` takes it
 // first: everything below reads one workspace's store, and a function that had to guess
 // would resolve a path against whatever the isolate happened to hold.
-async function assetFetch(tenantId, env, request) {
+async function assetFetch(tenantId, env, request, opts = {}) {
   if (!bundleMode(env)) return env.ASSETS.fetch(request);
   const url = new URL(request.url);
   // ── a draft address: the draft's table, not the manifest ─────────────────────────
@@ -4352,6 +4356,22 @@ async function assetFetch(tenantId, env, request) {
     return blobResponse(env, request, f);
   }
   const manifests = await loadManifests(tenantId, env);
+  // ── a design-system draft, across the site (`?ds=<draft>`, §5) ──────────────────
+  // A path under the workspace's declared skill folder resolves from THAT draft's table
+  // when the request carries one, so a shared change can be looked at on every prototype
+  // before it lands. Only the skill's own paths: a prototype's files never come from it,
+  // and a draft that does not hold the file falls through to main.
+  if (opts.dsDraft && DRAFT_ID_RE.test(opts.dsDraft) && decoded) {
+    const skill = Object.values(manifests)
+      .flatMap((m) => ((m && m.routing) || {}).publicSkillPrefixes || [])
+      .map(normUnit).find((p) => p && decoded.startsWith(p));
+    const stub = skill ? unitStub(env, tenantId, skill) : null;
+    if (stub) {
+      const dr = await unitCall(stub, `/draft/${opts.dsDraft}`, null, "GET");
+      const f = dr.status === 200 && dr.body.table ? dr.body.table[decoded] : null;
+      if (f) return blobResponse(env, request, f);
+    }
+  }
   const r = resolveBundlePath(manifests, url.pathname);
   if (r.redirect) return Response.redirect(new URL(r.redirect + url.search, url).toString(), 308);
   if (r.miss) return new Response("Not Found", { status: 404 });
@@ -4783,6 +4803,9 @@ function publishRefusalBody(refusal) {
     "viewer-role": "This account can look around but not publish.",
     "not-an-admin": "This token was minted for an admin and this account is no longer one. Run `augur login` again for a token scoped to what it may still publish.",
   }[refusal];
+  // `unknown-token` and `wrong-space` stay a bare `forbidden` ON PURPOSE: a guessed token
+  // must not learn whether it exists somewhere. The sentence a person needs — pair again —
+  // is said by the CLI, which knows it just used a saved token (scripts/lib/draft.mjs).
   return message ? { error: "forbidden", message } : { error: "forbidden" };
 }
 
@@ -5029,21 +5052,23 @@ const UNIT_CT_RE = /^[\w.+-]+\/[\w.+-]+(; ?charset=[\w-]+)?$/i;
 // to anonymous visitors, from a draft on a folder nobody edits.
 const isNewUnitPath = (unit) => unit.split("/").filter(Boolean).length === 2;
 // Top-level folders a NEW unit may not be created under. A landing replaces a unit's
-// folder wholesale, so a draft opened on `/components/button/` or `/skills/x-ui/` would
-// have replaced the design system's or the gallery's own files with whatever one draft
-// held. These are the folders a site builds from and every prototype reads: the design
-// system, the gallery pages, the changelog, the search index, engine chrome (`_`, `__`).
-// Stateless and the same on every workspace — an opportunity folder is anything else,
-// `/playground/<name>/` included. A unit the manifest ALREADY declares is never held to
-// this: the manifest is the authority on what exists.
+// folder wholesale, so the folders whose contents are GENERATED — the tokens page, the
+// primitives gallery, the changelog, the search index, fonts, engine chrome (`_`, `__`) —
+// are never a unit. The four library tiers are NOT here: `/components/button/` is one
+// demo folder, a unit like any prototype, and the tier's own index is a sibling file the
+// derived renderer owns. `skills` stays reserved with ONE exception, decided where the
+// workspace's declared design system is known (`unitApi`): the skill folder the space
+// names is the design-system unit. Stateless and the same on every workspace. A unit the
+// manifest ALREADY declares is never held to this: the manifest is the authority.
 const RESERVED_UNIT_FOLDERS = Object.freeze([
-  "base", "components", "pages", "patterns", "skills", "tokens", "fonts",
-  "admin", "changelog", "search",
+  "skills", "tokens", "primitives", "fonts", "tracks", "admin", "changelog", "search",
 ]);
 const isReservedUnitFolder = (unit) => {
   const first = unit.split("/").filter(Boolean)[0] || "";
   return first.startsWith("_") || RESERVED_UNIT_FOLDERS.includes(first);
 };
+/** The one unit allowed under `skills/`: the design system the workspace declares. */
+const isDeclaredSkillUnit = (unit, tctx) => ((tctx && tctx.PUBLIC_SKILL_PREFIXES) || []).some((p) => normUnit(p) === unit);
 const shortText = (s, n) => String(s == null ? "" : s).slice(0, n);
 // `tctx.SPACES` is a routing field, filled from the live manifests by `loadTenantContext`
 // on the request's normal path — which this route also goes through, since `handleRequest`
@@ -5077,7 +5102,12 @@ function defaultSpaceIdFromManifests(manifests) {
  * rule the commit handler already keeps. `unitSources` records the landing so the old
  * composed publish treats the unit as somebody's work rather than as a fast-forward.
  */
-const UNIT_LANDING_ATTEMPTS = 3;
+// Every landing in a space writes the one manifest by compare-and-set. Three attempts
+// with no pause between them lost 2 of 8 landings made in the same second (measured live,
+// 6 Sep 2026); six attempts with a little jitter between them is what a burst of agents
+// landing at once needs. The CLI lands again on `manifest-contended` as well.
+const UNIT_LANDING_ATTEMPTS = 6;
+const landingBackoff = (attempt) => new Promise((r) => setTimeout(r, 30 + Math.random() * 90 * (attempt + 1)));
 async function writeUnitLanding(tctx, env, spaceId, unit, table, changed, who, now) {
   const bundles = bundlesFor(env, tctx.tenantId);
   const key = `spaces/${spaceId}/manifest.json`;
@@ -5140,7 +5170,11 @@ async function writeUnitLanding(tctx, env, spaceId, unit, table, changed, who, n
     // A unit the manifest already declares keeps the entry it has, spelling and all: the
     // set union that replaced it added a second, normalized entry beside one written
     // without its trailing slash, and two entries for one unit is two things to prune.
-    routing.publicPrefixes = authoredUnits(cur).has(unit)
+    // The design-system unit is the one landing that adds NO public prefix: its public
+    // surface is the rendered-asset rule `publicSkillPrefixes` already spells, and a whole
+    // skill folder opened to the gate would expose the documents that rule keeps gated.
+    const skillUnit = ((cur.routing || {}).publicSkillPrefixes || []).some((p) => normUnit(p) === unit);
+    routing.publicPrefixes = authoredUnits(cur).has(unit) || skillUnit
       ? [...(routing.publicPrefixes || [])]
       : [...(routing.publicPrefixes || []), unit];
     routing.unitSources = { ...(routing.unitSources || {}), [unit]: { sha: null, dirty: false, landed: true, by: who.personId, at: now } };
@@ -5158,7 +5192,7 @@ async function writeUnitLanding(tctx, env, spaceId, unit, table, changed, who, n
     // A store that answers `null` refused the precondition — R2's way of saying the object
     // moved under us. Anything else is a write.
     const wrote = await bundles.put(key, JSON.stringify(out), etag ? { onlyIf: { etagMatches: etag } } : undefined);
-    if (etag && wrote === null) { bustManifests(tctx.tenantId); continue; }
+    if (etag && wrote === null) { bustManifests(tctx.tenantId); await landingBackoff(attempt); continue; }
     // THE BYTES ARE LIVE FROM HERE: the manifest is the pointer visitors follow. The version
     // document is the rollback record, and a store failure writing it must not turn a landing
     // that already happened into a reported failure with no lease release — it is logged as
@@ -5249,6 +5283,12 @@ async function unitCaller(tctx, request, env, spaceId) {
   return { who: { personId: personId(me.email), label: me.email }, session: session || "browser" };
 }
 
+/** A `draft-closed` answer names who landed it by id; the roster puts the face on it. */
+function closedFace(tctx, body) {
+  if (!body || body.error !== "draft-closed" || !body.by) return body;
+  return { ...body, ...personFace(tctx.USERS, body.by) };
+}
+
 async function unitApi(tctx, request, url, env) {
   const verb = url.pathname.slice(UNIT_API_PREFIX.length);
   if (!/^[a-z-]+$/.test(verb)) return jsonResponse({ error: "bad-path" }, 400);
@@ -5297,7 +5337,7 @@ async function unitApi(tctx, request, url, env) {
   // reached, so a folder that is not one is never given a draft to be adopted from later.
   // A unit the space ALREADY publishes is a unit whatever its shape (the manifest is the
   // authority on what exists); anything else has to be the shape a new one is created in.
-  if (!authoredUnits(live).has(unit)) {
+  if (!authoredUnits(live).has(unit) && !isDeclaredSkillUnit(unit, tctx)) {
     if (!isNewUnitPath(unit)) return jsonResponse({ error: "bad-unit", reason: "not-a-prototype-folder" }, 400);
     if (isReservedUnitFolder(unit)) return jsonResponse({ error: "bad-unit", reason: "reserved-folder" }, 400);
   }
@@ -5373,13 +5413,13 @@ async function unitApi(tctx, request, url, env) {
     }
     if (missing.length) return jsonResponse({ error: "missing-blobs", missing: [...new Set(missing)] }, 409);
     const r = await unitCall(stub, "/save", { draftId: body.draftId, draftRevision: body.draftRevision, changes, baseRevision: body.baseRevision, at: now });
-    return jsonResponse(r.body, r.status);
+    return jsonResponse(closedFace(tctx, r.body), r.status);
   }
   if (verb === "land" || verb === "restore") {
     const r = await unitCall(stub, `/${verb}`, verb === "land"
       ? { draftId: body.draftId, baseRevision: body.baseRevision, at: now }
       : { revision: body.revision, at: now });
-    if (r.status !== 200) return jsonResponse(r.body, r.status);
+    if (r.status !== 200) return jsonResponse(closedFace(tctx, r.body), r.status);
     const written = await writeUnitLanding(tctx, env, spaceId, unit, r.body.table, r.body.changed, who, now);
     if (written.error) {
       await unitCall(stub, "/abandon-land", { lease: r.body.lease });
@@ -5418,7 +5458,7 @@ async function unitApi(tctx, request, url, env) {
   if (verb === "sync" || verb === "discard") {
     const r = await unitCall(stub, `/${verb}`, { draftId: body.draftId, at: now });
     if (verb === "discard" && r.status === 200) await noteUnitDrafts(tctx, env, stub, unit, now);
-    return jsonResponse(r.body, r.status);
+    return jsonResponse(closedFace(tctx, r.body), r.status);
   }
   return jsonResponse({ error: "unknown-verb" }, 404);
 }
@@ -5427,46 +5467,6 @@ async function publishApi(tctx, request, url, env) {
   const [spaceId, op, arg] = url.pathname.slice("/__publish/".length).split("/");
   if (!spaceId || !op || !/^[a-z0-9_][a-z0-9-]*$/.test(spaceId)) return jsonResponse({ error: "bad-path" }, 400);
 
-  // ── working marks (`F-presence-marks`) ─────────────────────────────────────
-  //
-  // AHEAD OF THE BUNDLE-STORE GUARD, deliberately: a mark is not published content and
-  // holds nothing the store knows about, so an instance serving from ASSETS — `augur dev`,
-  // `npm run offline`, a raw engine build — is exactly where two agents most need to stay
-  // out of each other's way, and 501 there would be an accident of where the check sits.
-  //
-  // ANY VALID PUBLISH TOKEN, whatever its scope. A mark names a path, not a space, and a
-  // space-scoped token holder is precisely the person whose work-start is worth announcing.
-  // The capability gate still applies, so a restricted credential (the control plane's
-  // purge token) reaches this no more than it reaches anything else.
-  if (spaceId === "_marks") {
-    const a = await publishAuthDetailed(tctx, request, env, spaceId, true);
-    if (!a.entry) return jsonResponse(publishRefusalBody(a.refusal), 403);
-    if (capabilityRefusal(a.entry, spaceId, op)) {
-      return jsonResponse({ error: "forbidden", reason: "capability-not-granted" }, 403);
-    }
-    // WHO, from the credential and never from the body. `augur login` labels a token with
-    // the holder's address; a token an admin minted by hand carries whatever they typed,
-    // which hashes to a stable id that resolves to no roster face — honest, and better
-    // than letting the caller name itself.
-    const who = { personId: personId(a.entry.label || "") };
-    if (op === "list" && request.method === "GET") {
-      return jsonResponse({ ...(await readMarks(tctx, env)), ttlMs: MARK_TTL_MS, maxTtlMs: MARK_TTL_MAX_MS });
-    }
-    let body = null;
-    if (request.method === "POST") {
-      try { body = await request.json(); } catch (e) { return jsonResponse({ error: "bad-json" }, 400); }
-    }
-    if (op === "set" && request.method === "POST") {
-      const out = await writeMark(tctx, env, who, { path: body && body.path, ttl: body && body.ttl });
-      return out.error ? jsonResponse(out, out.error === "bad-input" ? 400 : 503) : jsonResponse(out);
-    }
-    if (op === "clear" && request.method === "POST") {
-      const out = await clearMark(tctx, env, who, { path: body && body.path });
-      return out.error ? jsonResponse(out, out.error === "bad-input" ? 400 : 503) : jsonResponse(out);
-    }
-    return jsonResponse({ error: "unknown-op" }, 400);
-  }
-
   if (!env.BUNDLES) return jsonResponse({ error: "bundle-store-not-configured" }, 501);
   // This workspace's view of the store. `blobs/` is content-addressed and shared, so the
   // three `blobs/…` operations below deliberately keep using the binding directly — the
@@ -7238,6 +7238,94 @@ async function composeChrome(tctx, res, url) {
   return new Response(html, { status: res.status, statusText: res.statusText, headers });
 }
 
+// ---- Derived pages (drafts that land, §6.4) -------------------------------------
+// Where drafts are served, the gallery, each opportunity's index, the playground, the
+// library tiers and the finder's index are RENDERED HERE from the live store, so a landing
+// is on them at once and no client build ships them. The stored copies a publish once
+// baked are ignored on this path — they cannot know about a landing. Where drafts are not
+// served, nothing here runs and the stored pages serve exactly as before.
+//
+// Two store reads feed a render besides the manifest — the status baseline
+// (`/prototype-status.json`) and the design-system catalog (`/registry.json`) — cached per
+// manifest version; the status OVERLAY is read fresh every time, one get, as the status
+// route itself reads it. Per-request work after that is string rendering.
+const DERIVED = tenantCache("derived");
+const DERIVED_PATH_RE = /^\/(?:[^/]+\/?(?:index\.html)?|index\.html|__search\.json)?$/;
+async function derivedInputs(tctx, env, spaceId, manifest) {
+  const slot = DERIVED.entry(tctx.tenantId, () => ({ key: null, baseline: {}, catalog: {} }));
+  const key = `${spaceId}:${manifest.version}`;
+  if (slot.key === key) return slot;
+  const readJson = async (p) => {
+    const f = (manifest.files || {})[p];
+    if (!f || !env.BUNDLES) return null;
+    try {
+      const obj = await env.BUNDLES.get("blobs/" + f.h);
+      return obj ? JSON.parse(await obj.text()) : null;
+    } catch (e) { return null; }
+  };
+  const base = await readJson("/prototype-status.json");
+  const baseline = {};
+  for (const [k, v] of Object.entries(base && typeof base === "object" ? base : {})) {
+    if (!k.startsWith("_") && typeof v === "string") baseline[k] = v;
+  }
+  slot.baseline = baseline;
+  slot.catalog = catalogFrom(await readJson("/registry.json"));
+  slot.key = key;
+  return slot;
+}
+/** A derived page for this path, or null when the path is not one (or drafts are not served here). */
+async function derivedPage(tctx, env, url) {
+  if (!draftsServedHere(env) || !DERIVED_PATH_RE.test(url.pathname)) return null;
+  const manifests = await loadManifests(tctx.tenantId, env);
+  const spaceId = defaultSpaceIdFromCtx(tctx) || defaultSpaceIdFromManifests(manifests);
+  const manifest = spaceId ? manifests[spaceId] : null;
+  if (!manifest || !manifest.files) return null;
+  const inputs = await derivedInputs(tctx, env, spaceId, manifest);
+  const store = overlayFor(env, tctx);
+  let statuses = {};
+  try { statuses = store ? (await store.read("statuses")) || {} : {}; } catch (e) { statuses = {}; }
+  // A recorded author resolves to a face through the roster; an id nobody answers to
+  // (an ex-member, the `live` adoption) is nobody's face rather than a blank chip.
+  const people = (id) => { const f = personFace(tctx.USERS, id); return f.name ? { id, ...f } : null; };
+  const now = Date.now();
+  const model = siteModel({ manifest, statuses, baseline: inputs.baseline, people, now });
+  const kind = derivedPathKind(url.pathname, model);
+  if (!kind) return null;
+  const sp = (tctx.SPACES || []).find((s) => s.id === spaceId) || {};
+  const ctx = { spaces: tctx.SPACES || [], activeSpace: spaceId, chrome: tctx.CHROME_POINTER || null, projectsLabel: sp.projectsLabel || "", now };
+  if (kind.kind === "search") return jsonResponse(searchIndex(model, ctx), 200, { "Cache-Control": "no-cache" });
+  if (kind.kind === "opportunity" && !kind.slash) return Response.redirect(new URL(`/${encodeURIComponent(kind.name)}/${url.search}`, url).toString(), 308);
+  const html = kind.kind === "root" ? renderRootIndex(model, ctx)
+    : kind.kind === "opportunity" ? renderOpportunityIndex(model, kind.name, ctx)
+    : kind.kind === "playground" ? renderPlaygroundIndex(model, ctx)
+    : kind.kind === "tier" ? renderTierIndex(model, kind.tier, ctx)
+    : kind.kind === "components" ? renderComponentsIndex(model, inputs.catalog, ctx)
+    : null;
+  if (html == null) return null;
+  return new Response(html, { status: 200, headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": ASSET_REVALIDATE } });
+}
+
+// ---- The design-system overlay cookie (`?ds=`) --------------------------------
+// `?ds=<draft>` on any page names a design-system draft to look through; the cookie keeps
+// it while the person navigates; `?ds=` with nothing drops it. A malformed id is nobody's
+// draft and touches no cookie. Members only — the branch that reads this is past the gate.
+const DS_COOKIE = "augur_ds";
+function dsOverlay(request, url) {
+  if (url.searchParams.has("ds")) {
+    const v = url.searchParams.get("ds") || "";
+    if (v === "") return { draft: null, setCookie: `${DS_COOKIE}=; Path=/; Max-Age=0; SameSite=Lax; Secure; HttpOnly` };
+    if (!DRAFT_ID_RE.test(v)) return { draft: null, setCookie: null };
+    return { draft: v, setCookie: `${DS_COOKIE}=${v}; Path=/; SameSite=Lax; Secure; HttpOnly` };
+  }
+  const c = cookieValue(request.headers.get("Cookie") || "", DS_COOKIE);
+  return { draft: c && DRAFT_ID_RE.test(c) ? c : null, setCookie: null };
+}
+function withSetCookie(res, cookie) {
+  const out = new Response(res.body, res);
+  out.headers.append("Set-Cookie", cookie);
+  return out;
+}
+
 // ---- The draft bar (drafts that land, §5) -------------------------------------
 // A prototype is raw HTML from a space and carries no chrome; a draft has no build step
 // that could bake one in. So a member looking at a unit's page — main or a draft address —
@@ -7835,16 +7923,6 @@ const OVERLAY_KV_KEYS = Object.freeze({
   boards: Object.freeze({ doc: "board", layout: "keyed", workspaceScoped: true }),
   // Canvas image METADATA — the bytes are in R2. See assetApi.
   assets: Object.freeze({ doc: "basset-meta", layout: "keyed" }),
-  // WORKING MARKS — "something is editing here right now". One row per path, and the row
-  // is only meaningful until its own TTL runs out. See the marks section below.
-  //
-  // `map` RATHER THAN `keyed`, and the trade is worth naming because it looks backwards.
-  // Keyed would give one KV document per path, so two marks written in the same window
-  // could not lose each other. It would also turn every READ into a kv.list plus a get per
-  // row — and marks are read by a gallery page as well as by the CLI, which puts a listing
-  // in front of ordinary page loads on a store whose daily get budget has been exhausted
-  // before. One document is one get. What it costs is stated on `writeMark`.
-  marks: Object.freeze({ doc: "marks", layout: "map" }),
   // WHICH UNITS HAVE OPEN DRAFTS — a hint the gallery reads so it can ask the right unit
   // objects and no others (`draftsIndexApi`). One row per unit, `{n, at}`, written from
   // the object's own presence answer after open, land and discard. NEVER THE TRUTH: the
@@ -9055,11 +9133,12 @@ function doorText(f) {
       + `  ${f.connect}\n\n`
       + `It prints a link and a code. The owner of this workspace opens the link in a\n`
       + `browser they are already signed in to and enters the code. The token lands on\n`
-      + `that machine, and \`augur publish\` / \`augur ship\` use it from then on. With no\n`
+      + `that machine, and every verb below uses it from then on. Talking to that person\n`
+      + `through messages rather than a terminal? Add --no-wait: it prints the line and\n`
+      + `exits; run the same command again after they approve and the token is collected.\n`
+      + `With no\n`
       + `source tree yet, \`npx @augurworks/augur clone --space ${f.workspace}\` then fetches one (it reads\n`
       + `the origin from the pairing).\n\n`
-      + `Not on npm yet? The engine clone sits next to every workspace that publishes:\n\n`
-      + `  node <engine>/scripts/cli.mjs connect --origin ${f.origin}\n\n`
     : `Device pairing is switched off on this workspace. Ask an admin for an invite;\n`
       + `once you have signed in, \`augur login\` (email and password, meant for CI)\n`
       + `trades that for a publish token.\n\n`;
@@ -10221,235 +10300,6 @@ async function nameApi(tctx, request, url, env) {
   return jsonResponse({ error: "method-not-allowed" }, 405);
 }
 
-// ---- Working marks (KV-backed, single key) ----------------------------------
-//
-// `F-presence-marks`. Nothing anywhere said what was already being worked on. Two
-// collaborators' tools — usually two agents, on two machines, told to improve "the
-// checkout flow" — would each open the same folder, each edit it, and find out at publish
-// time, where the answer is a fork and a conflict file nobody asked for.
-//
-// ⚠️ THIS IS DELIBERATELY NOT A LOCK, and every line below is written so it cannot become
-// one. A mark REFUSES NOTHING. It is not consulted by the gate, by the publish handler, by
-// the commit CAS or by anything else that could say no. It is a note left where the next
-// reader will look, and the whole protocol is: write one before you start, read them
-// before you start. Enforcement when coordination fails is the composed publish's job
-// (`src/publish-compose.mjs`), which is the only place in this engine allowed to refuse a
-// write over a collision — and it does it on evidence, after the fact, never on a claim.
-//
-// THE PROTOCOL IS AGENT-FIRST. The badge a person sees on a gallery card is the byproduct,
-// not the point: as an agent's edit shrinks toward seconds, a mark is FELT almost never and
-// READ always. So the write side is the CLI (`augur mark`, over a publish token, see the
-// `_marks` branch in publishApi) and the browser side is read-only — a person editing in a
-// tab is not running a work-start step and inventing one for them would be a lie about who
-// wrote what.
-//
-// ⚠️ A MARK EXPIRES BY ITSELF AND IS NEVER TRUSTED TO BE CLEARED. The thing that leaves a
-// mark is a process that can be killed — Ctrl-C, an OOM, a laptop lid — and a claim that
-// outlives the claimant is worse than no claim at all, because the next reader believes it.
-// So EXPIRY IS A READ-TIME FILTER (`liveMarks`), not a cleanup job: the moment `startedAt +
-// ttl` is in the past the mark is gone from every answer, whether or not anything ever runs
-// again. `sweepExpired` below only reclaims the BYTES, opportunistically, and correctness
-// never depends on it having run.
-
-/** How long a mark is good for when the caller does not say. */
-const MARK_TTL_MS = 10 * 60_000;
-/**
- * The longest a caller may ask for. An agent that wants four hours is describing a lock,
- * and the answer to a lock is a shorter mark re-written as the work continues.
- */
-const MARK_TTL_MAX_MS = 60 * 60_000;
-/** The shortest, so a `--ttl 0` cannot write a mark that is already dead. */
-const MARK_TTL_MIN_MS = 5_000;
-/**
- * How many lapsed rows one write may reclaim. Bounded low because on the KV backing each
- * row delete is a whole-document read and put, so the sweep can cost more than the litter
- * it collects; an unbounded one would turn a work-start step into a hundred writes on a
- * workspace nobody has marked in a month. Nothing depends on it running at all.
- */
-const MARK_SWEEP_MAX = 4;
-/** Belt and braces: a workspace cannot be filled with marks by a loop. */
-const MARK_MAX_ROWS = 200;
-
-/**
- * One spelling of a path, so two tools that mean the same folder agree.
- *
- * Leading and trailing slash, always: a mark names a UNIT — the prototype folder a URL
- * names and a person edits — and `unitOfPath` in src/publish-units.mjs decides containment
- * by prefix, which only works when a folder ends in a slash. `/a/b` and `/a/bc/` would
- * otherwise overlap.
- */
-function normalizeMarkPath(p) {
-  const s = clamp(p, 300);
-  if (!s) return "";
-  const trimmed = s.trim().replace(/^\.\//, "").replace(/\/{2,}/g, "/");
-  if (!trimmed || trimmed === "/") return "/";
-  return `/${trimmed.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
-}
-
-/**
- * Do these two paths describe overlapping work? Containment in either direction — a mark
- * on `/checkout/` covers `/checkout/step-two/`, and a mark on `/checkout/step-two/` is
- * worth showing to somebody about to take `/checkout/`.
- */
-function markPathsOverlap(a, b) {
-  const x = normalizeMarkPath(a), y = normalizeMarkPath(b);
-  if (!x || !y) return false;
-  return x === y || x.startsWith(y) || y.startsWith(x);
-}
-
-/** The instant a mark stops meaning anything. Pure, and the only definition of expiry. */
-function markExpiresAt(m) {
-  const started = Date.parse((m && m.startedAt) || "");
-  if (!Number.isFinite(started)) return 0;
-  const ttl = Number.isFinite(+(m && m.ttl)) ? +m.ttl : MARK_TTL_MS;
-  return started + Math.min(Math.max(ttl, MARK_TTL_MIN_MS), MARK_TTL_MAX_MS);
-}
-
-/**
- * The live marks in a stored map, newest first. THE expiry rule — every reader goes
- * through here, so a lapsed mark cannot be reported by one surface and hidden by another.
- */
-function liveMarks(map, now = Date.now()) {
-  return Object.entries(map || {})
-    .map(([path, m]) => (m && typeof m === "object" ? { ...m, path: m.path || path } : null))
-    .filter((m) => m && markExpiresAt(m) > now)
-    .sort((a, b) => Date.parse(b.startedAt || 0) - Date.parse(a.startedAt || 0));
-}
-
-/**
- * What a mark looks like on the wire: the stored row plus two things a reader would
- * otherwise have to compute, and one it could not — the display name behind the id.
- *
- * The NAME IS RESOLVED, NEVER STORED. `personId` is the same one-way hash a comment
- * carries, so a mark holds no address; the roster turns it back into a face at read time,
- * which also means a rename shows through and an ex-member resolves to nobody.
- */
-function decorateMark(m, users, now = Date.now()) {
-  const u = (users || []).find((x) => x && personId(x.email) === m.personId);
-  return {
-    path: m.path,
-    personId: m.personId || null,
-    startedAt: m.startedAt,
-    ttl: markExpiresAt(m) - Date.parse(m.startedAt),
-    by: u ? u.name || nameFromEmail(u.email) : null,
-    initials: u ? u.initials || initialsFor(u.name || u.email) : null,
-    color: u ? u.color || null : null,
-    expiresIn: Math.max(0, markExpiresAt(m) - now),
-  };
-}
-
-/** Read the live marks for a workspace, decorated. `null` store answers with nothing. */
-async function readMarks(tctx, env) {
-  const store = overlayFor(env, tctx);
-  if (!store) return { marks: [], warning: "no-kv-binding" };
-  const map = await store.read("marks");
-  const now = Date.now();
-  return { marks: liveMarks(map, now).map((m) => decorateMark(m, tctx.USERS, now)), now };
-}
-
-/**
- * Reclaim the bytes of rows that lapsed. NOT the expiry mechanism — `liveMarks` already
- * stopped reporting these, and this runs only so a one-way author id does not sit in the
- * store for months after it stopped meaning anything. Per-key deletes, never a whole-family
- * `replace`: a replace computed from a read taken moments ago would drop a mark another
- * agent wrote in between, and on the workspace object it would delete rows it never read.
- *
- * It swallows its own failures on purpose. Reclaiming bytes may never be the reason a
- * work-start step reports a failure, because the mark it was announcing is already written.
- */
-async function sweepExpired(store, map, now, keep) {
-  let swept = 0;
-  for (const [path, m] of Object.entries(map || {})) {
-    if (swept >= MARK_SWEEP_MAX) break;
-    if (path === keep) continue;
-    if (markExpiresAt(m) > now) continue;
-    try { await store.set("marks", "", path, null); swept++; } catch (e) { break; }
-  }
-  return swept;
-}
-
-/**
- * Write one mark. `who` is resolved by the caller from a credential — a session or a
- * publish token — and NEVER from the request body, exactly like a comment's authorship.
- *
- * ⚠️ ON THE KV BACKING TWO MARKS WRITTEN IN THE SAME WINDOW CAN LOSE EACH OTHER, and that
- * is a known cost rather than an oversight. A `map` family is one document: `set` reads it,
- * changes one key and puts it back, so a mark written between the read and the put is
- * overwritten — and KV reads converge globally rather than instantly, which makes the
- * window as wide as the convergence, not as wide as the round trip. The overlay's own
- * header says the same thing about statuses, names and pins; the workspace object closes
- * it for all of them at once by making each key a row.
- *
- * WHY IT IS SURVIVABLE HERE AND WOULD NOT BE IN A LOCK. A lost mark costs the next reader
- * a hint. It cannot cost anybody work, because nothing anywhere asks a mark for permission:
- * the loser of the race is still editing, still publishing, and still protected by the
- * composed publish, which settles a real collision on evidence. A lock that lost a write
- * would hand two writers the same exclusive claim, which is why this is not one.
- */
-async function writeMark(tctx, env, who, { path, ttl }) {
-  const store = overlayFor(env, tctx);
-  if (!store) return { error: "no-kv-binding" };
-  const p = normalizeMarkPath(path);
-  if (!p) return { error: "bad-input" };
-  const ms = Number.isFinite(+ttl) && +ttl > 0
-    ? Math.min(Math.max(+ttl, MARK_TTL_MIN_MS), MARK_TTL_MAX_MS)
-    : MARK_TTL_MS;
-  const now = Date.now();
-  const before = await store.read("marks");
-  // The only refusal on this route, and it is a runaway-loop guard rather than a policy:
-  // this many things being worked on at once in one workspace is a script, not a team.
-  const live = liveMarks(before, now);
-  if (live.length >= MARK_MAX_ROWS && !live.some((m) => m.path === p)) {
-    return { error: "too-many-marks" };
-  }
-  // ⚠️ THE ROW CARRIES NO ADDRESS — not in the value and not in the `owner` column. A mark
-  // is read by more things than a comment thread is (a gallery page stamps a badge from
-  // it), and `personId` is exactly enough to put a face on it.
-  const mark = { path: p, personId: who.personId, startedAt: new Date(now).toISOString(), ttl: ms };
-  await store.set("marks", "", p, mark, null);
-  const swept = await sweepExpired(store, before, now, p);
-  // The answer is COMPUTED from what was just written, never re-read. A second read costs
-  // a round trip to say what this function already knows, and on KV it can come back
-  // STALER than the write it was meant to confirm — a work-start step that printed "your
-  // mark is not there" right after writing it would teach people to distrust the tool.
-  const marks = [mark, ...live.filter((m) => m.path !== p)];
-  return {
-    mark: decorateMark(mark, tctx.USERS, now),
-    marks: marks.map((m) => decorateMark(m, tctx.USERS, now)),
-    swept,
-  };
-}
-
-/**
- * Release a mark early. A COURTESY, never the guarantee — the TTL is the guarantee, and a
- * tool that is killed never reaches this. Only the mark's own author may clear it: taking
- * somebody else's mark down would turn the note into something worth fighting over.
- */
-async function clearMark(tctx, env, who, { path }) {
-  const store = overlayFor(env, tctx);
-  if (!store) return { error: "no-kv-binding" };
-  const p = normalizeMarkPath(path);
-  if (!p) return { error: "bad-input" };
-  const map = await store.read("marks");
-  const cur = (map || {})[p];
-  const now = Date.now();
-  if (!cur || markExpiresAt(cur) <= now) return { cleared: false, reason: "no-mark" };
-  if (cur.personId !== who.personId) return { cleared: false, reason: "not-yours" };
-  await store.set("marks", "", p, null);
-  const marks = liveMarks(map, now).filter((m) => m.path !== p);
-  return { cleared: true, marks: marks.map((m) => decorateMark(m, tctx.USERS, now)) };
-}
-
-/**
- * The browser's read. GET only, on purpose — see the header: the badge is the byproduct of
- * an agent protocol, and a tab is not a work-start step.
- */
-async function marksApi(tctx, request, url, env) {
-  if (request.method !== "GET") return jsonResponse({ error: "method-not-allowed" }, 405);
-  const out = await readMarks(tctx, env);
-  return jsonResponse({ ...out, ttlMs: MARK_TTL_MS });
-}
-
 // ---- Prototype deletion (repo-write via dispatch webhook) -------------------
 // "Delete forever" on a prototype card. The worker holds NO repo credentials —
 // it forwards the request to a per-instance webhook (a GitHub repository_dispatch
@@ -12299,13 +12149,6 @@ async function handleRequest(request, env, ctx, url, trace) {
       if (!authed) return jsonResponse({ error: "unauthorized" }, 401);
       return pinsApi(tctx, request, url, env, me);
     }
-    // Working marks — READ ONLY here. Who is working where is workspace-internal, so it
-    // asks for a session like the gallery around it; the WRITE side is a publish token and
-    // lives under /__publish/_marks, because a work-start step is something a tool runs.
-    if (url.pathname === "/__marks") {
-      if (!authed) return jsonResponse({ error: "unauthorized" }, 401);
-      return marksApi(tctx, request, url, env);
-    }
     if (url.pathname === "/__name") {
       if (!authed) return jsonResponse({ error: "unauthorized" }, 401);
       const denied = viewerWriteRefusal(request, url, me, "name", tctx.SPACES);
@@ -12433,13 +12276,20 @@ async function handleRequest(request, env, ctx, url, trace) {
     // Past the gate (or nothing gates the site) → serve. A 404 gets one more chance
     // as a created canvas (a KV-registered board with no repo file — see canvasesApi).
     if (authed) {
-      const asset = await assetFetch(tctx.tenantId, env, request);
+      // A design-system draft to look through (`?ds=`), remembered in a cookie.
+      const ds = dsOverlay(request, url);
+      const stamp = (res) => (ds.setCookie ? withSetCookie(res, ds.setCookie) : res);
+      // Where drafts are served, the gallery and its indexes are derived from the live
+      // store rather than read from it — a landing is on them at once.
+      const derived = await derivedPage(tctx, env, url);
+      if (derived) return stamp(derived.status === 308 ? derived : await serveContent(tctx, derived, url, me, env));
+      const asset = await assetFetch(tctx.tenantId, env, request, { dsDraft: ds.draft });
       if (asset.status === 404) {
         const virt = await virtualCanvas(tctx, request, env, url);
-        if (virt) return virt;
-        return notFoundResponse(tctx);
+        if (virt) return stamp(virt);
+        return stamp(notFoundResponse(tctx));
       }
-      return serveContent(tctx, asset, url, me, env);
+      return stamp(await serveContent(tctx, asset, url, me, env));
     }
 
     // Created canvas boards are public like published prototypes — same obscure
@@ -12504,9 +12354,6 @@ export const __testables = Object.freeze({
   nextPublishVersion, overlayFor, overlayKvKey, statusApi, nameApi, pinsApi,
   currencyApi, currencyRows, freshness, whenWords, parseSince, unitKey, unitProvenance,
   STALE_AFTER_DAYS, STATUS_LABELS, VALID_STATUS,
-  marksApi, readMarks, writeMark, clearMark, liveMarks, markExpiresAt, decorateMark,
-  normalizeMarkPath, markPathsOverlap, sweepExpired,
-  MARK_TTL_MS, MARK_TTL_MAX_MS, MARK_TTL_MIN_MS, MARK_SWEEP_MAX, MARK_MAX_ROWS,
   exportState, importState,
   quotaBump, quotaMinute, quotaDay, workspaceStatus, touchWorkspaceActivity,
   deleteWorkspace, purgeDue, blobGc, clearFamilies, NEVER_CLEARED,
@@ -12524,7 +12371,7 @@ export const __testables = Object.freeze({
   doorFacts, doorText, wantsMachineDoor, gateResponse, DOOR_DOCS, DOOR_WELL_KNOWN,
   resumeAfterDormancy,
   PITI_VIEW_KEY, PITI_REMARKS_KEY,
-  publishAuthDetailed, unitApi, unitCaller, personFace, withDraftUi, draftUiBoot, isEngineChrome, publishRefusalBody, splitDraftPath,
+  publishAuthDetailed, unitApi, unitCaller, personFace, withDraftUi, draftUiBoot, derivedPage, dsOverlay, isEngineChrome, publishRefusalBody, splitDraftPath,
   adminStorageApi,
   adminCustomDomainApi,
   isPrefixBacked, backedPublicPrefixes,