@intentic/extension-api 1.248.0 → 1.250.0

package/src/background.ts

@@ -2,106 +2,39 @@ import type { Ref } from "vue";
 import type { Disposable, IntenticApi } from "./api.js";
 import { sandboxRef, sandboxScopeGuard } from "./scope.js";
 
-/* WHAT AN EXTENSION DOES WHILE NONE OF IT IS ON SCREEN, the two pieces every surface that badges a rail tile
- * turned out to need, and had been writing out by hand.
- *
- * A tile has to be able to say something before it is opened. That rules out the view's own query, which stops
- * when the component unmounts, and it rules out the file-change push AS AN INVALIDATION, because evicting a
- * cache entry only reaches a query something is observing. So the state lives at module scope (scope.ts) and
- * something refreshes it.
- *
- * THAT SOMETHING IS THE WRITE ITSELF WHEREVER THE ANSWER LIVES IN A FILE, and the timer is the backstop. The
- * push was already arriving and already naming this extension's paths, it was simply spent entirely on the cache
- * (`api.workspace.onDidChangeFiles`), so every badge in the workspace was as fresh as its own interval and no
- * fresher: an approvals queue the owner had just emptied went on claiming six items for a minute, and the slowest
- * tile here is ten minutes behind the file it describes. A count that is wrong for minutes at a time is worse
- * than no count, because the owner learns to distrust the one they cannot check without clicking.
- *
- * What the interval is still FOR, and why it did not simply go away: a source that is not a file at all (a CI
- * provider, a Komodo deployment) has nothing to push, so for those it remains the only feed; and for the rest it
- * covers the gap no push can close, a watcher that dropped an event, an exclusion nobody noticed. Where a file
- * binding carries the news, `everyMs` is honestly a slow safety net and the extensions here say so.
- *
- * Seven modules across six extensions arrived at the identical shape for that timer, and it carries five rules
- * that are each invisible until they are broken:
- *
- *   never reject      it runs detached, so a throw is an unhandled rejection with no caller to report to, and
- *                     that includes reading the host handle, which throws before activate() has bound one
- *   skip when down    an unreachable daemon is not news; asking it is a failed request per tick, forever
- *   guard the await   a read issued before a sandbox switch must not write its answer into the box after it
- *   keep the last     a transient failure is not evidence that nothing is waiting, so a failed read changes
- *                     nothing rather than blanking the tile
- *   stop the clock    the interval is disposed with the extension, or a switched-off extension keeps polling
- *
- * Six of the seven copies got the third one wrong, which is what this pair exists to make impossible. What is
- * NOT here is what each tile SAYS: the count, the tone and the wording are the whole point of each surface and
- * differ deliberately, so `badge()` stays with the extension that owns the judgement. */
+// Sandbox-scoped background polling for a badge that needs an answer before its tile opens: state lives at module
+// scope, refreshed by a coalesced interval and a file-change wake. A failed read keeps the last value; a read is
+// dropped if the sandbox switched while it was in flight.
 
 export interface SandboxPoll<T> {
-    /* The value, as sandbox-scoped module state (scope.ts). Read it from `badge()` or `detect()` and the host's
-     * own computed repaints when it moves; write to it directly for the local fold a "mark as seen" does, which
-     * is what clears a tile on the spot instead of at the next tick. */
+    // Sandbox-scoped state (scope.ts); write directly to fold in a local change like "mark as seen".
     readonly state: Ref<T>;
-    /* Begin reading: on the extension's own `contributes.files` being written, and on the interval. Push the
-     * Disposable onto `context.subscriptions` and both stop with the extension.
-     *
-     * The file wake needs nothing declared here. An extension that named the paths its views derive from has
-     * already said which writes change this answer, so subscribing is unconditional and an extension that
-     * declared none is simply never woken.
-     */
+    // Begins reading on the interval and on the extension's own file writes; push onto context.subscriptions.
     start(): Disposable;
-    // Read now, off-cycle, for the moments that change the answer and should not wait out the interval: a
-    // connection appearing, a draft published, a run discarded.
+    // Reads immediately, off-cycle, for a moment that should not wait for the interval.
     refresh(): void;
 }
 
 export interface SandboxPollOptions<T> {
-    // The extension's own host handle (hostSlot). A function, not the api itself, because this is constructed
-    // at module load and nothing is bound until activate() runs.
+    // A function, not the api itself: nothing is bound until activate() runs.
     readonly host: () => IntenticApi;
-    /* How often, in milliseconds. There is no default on purpose: the right interval is a claim about how fast
-     * the answer actually changes, and a surface that has not thought about it will inherit whatever number
-     * happened to be chosen here. A badge is glanced at, so the honest range is minutes, not seconds.
-     *
-     * Read it against `start()`'s file wake. If the answer lives in a path your manifest declares, the write
-     * already refreshes this and the interval is a BACKSTOP for the frame nobody delivered, so the honest number
-     * there is slow. If it lives behind somebody else's API, nothing pushes and this is the only feed. */
+    // No default: choose an interval that reflects how fast the answer actually changes.
     readonly everyMs: number;
     // The value before anything has been read, rebuilt on every sandbox switch (sandboxRef).
     readonly initial: () => T;
-    /* The read. Gets the api and the value currently held, the second for a poll that ACCUMULATES rather than
-     * replaces, where one failed source must leave its own last answer standing beside the others. Throwing is
-     * fine and means "nothing changed": the value in hand is kept.
-     */
+    // Gets the api and the value held (for an accumulating poll); throwing means nothing changed, value kept.
     readonly read: (api: IntenticApi, previous: T) => Promise<T>;
-    /* Whether `start()` reads immediately as well as on the interval. Default true, because a tile that only
-     * badges a minute after login is a tile nobody trusts. Set false when the poll has nothing to ask until
-     * something else tells it what to ask about, deployments learns its connections from `detect()`. */
+    // Defaults to reading immediately too; set false when there's nothing to ask until told (detect()).
     readonly immediate?: boolean;
-    // For a value that owns something the garbage collector will not take back; see sandboxRef.
+    // For a value that owns something the garbage collector will not take back.
     readonly dispose?: (previous: T) => void;
 }
 
-/* HOW LONG A BURST OF WRITES IS ALLOWED TO COALESCE before the wake reads. The daemon already batches its
- * watcher at 250ms, but one logical event is often several batches, an acceptance run writing a result file per
- * story, a publish rewriting a staging tree, so without this the widest scan in the workspace would be re-run
- * per frame. Trailing rather than leading: the last write in a burst is the one whose answer is true.
- *
- * Short enough that the badge still moves while the owner is looking at the screen that caused the write, which
- * is the entire point of not waiting for the interval. */
+// How long a burst of writes may coalesce before the wake reads; trailing, since the last write wins.
 const WAKE_MS = 400;
 
-/* ONE LANE FOR EVERY BACKGROUND READ IN THIS WINDOW.
- *
- * Extensions activate together, so their minute clocks also fire together. Letting each timer issue its own
- * request turned one harmless cadence into a burst across the daemon: the widest poll could still be walking
- * the workspace while CI, deployments and chores all started beside it. A reconnect was worse, because every
- * file-backed poll was woken in the same frame.
- *
- * Per-poll coalescing matters as much as the global lane. A wake that lands while its read is QUEUED adds no
- * information; a wake that lands while it is RUNNING may describe a change the in-flight read missed, so it
- * earns exactly one trailing pass. Re-queueing that pass at the back keeps one noisy poll from starving the
- * others. */
+// One shared read lane for the whole window, so simultaneous per-extension timers don't burst the daemon at once.
+// Per-poll: a wake mid-queue is redundant, a wake mid-run earns exactly one trailing pass, requeued at the back.
 interface ScheduledRead {
     queued: boolean;
     running: boolean;
@@ -154,12 +87,8 @@ const scheduleRead = (scheduled: ScheduledRead): void => {
     void drainScheduledReads();
 };
 
-/* Re-read when the extension's own declared files are written.
- *
- * Contained in a try/catch because BOTH of its failure modes are ordinary rather than exceptional: `host()`
- * throws until activate() has bound a handle, and an older host has no `onDidChangeFiles` at all (this arrived in
- * api 2.10.0, and an extension may declare `engines.intentic` wider than that). Either way the poll falls back to
- * exactly the timer it had before, which is a slower badge and never a broken one. */
+// Re-reads when the extension's declared files change. Wrapped in try/catch: host() throws before activate(), and an
+// older host may lack onDidChangeFiles; either way it falls back to the timer alone.
 const wakeOnFiles = (host: () => IntenticApi, read: () => void): Disposable => {
     let pending: ReturnType<typeof setTimeout> | undefined;
     let subscription: Disposable | undefined;
@@ -200,8 +129,7 @@ export const sandboxPoll = <T>(options: SandboxPollOptions<T>): SandboxPoll<T> =
             }
             state.value = next;
         } catch {
-            // Whatever went wrong, an unbound host, a refused route, a daemon mid-boot, the answer is the
-            // same: leave the last value standing. "We could not ask" is not "there is nothing there".
+            // Leave the last value standing; "could not ask" is not "nothing there".
         }
     };
     const scheduled: ScheduledRead = { queued: false, running: false, trailing: false, read: once };
@@ -225,41 +153,14 @@ export const sandboxPoll = <T>(options: SandboxPollOptions<T>): SandboxPoll<T> =
     };
 };
 
-/* WHAT THE OWNER HAS ALREADY SEEN, as a file in the workspace.
- *
- * The rail's bar is that a badge means "something happened here that you do not already know about". Meeting it
- * needs somewhere to record what they DO know, and three extensions independently chose the same home: a JSON
- * object under `.intentic`, keyed by whatever identifies the thing. That is the right home, it survives a
- * reload, it is shared across the owner's browsers, and it needs no setting nobody would ever type, but each
- * of them then hand-wrote the same tolerant reader and the same careful write.
- *
- * KEY → MARK, where the mark is what makes the entry STALE. That is the whole vocabulary, and it covers both
- * the ledgers that compare (a chore's evidence digest, a story's verdict, the same key with a different mark
- * is news again) and the ones that only ask whether a key is present at all (a document set reviewed once).
- * A presence-only ledger writes the acknowledgement time as its mark, which nothing reads and a human opening
- * the file is glad of.
- *
- * The file is written by agents and editable by hand, so a missing, truncated or hand-mangled one reads as
- * "nothing acknowledged". That direction is deliberate: bad bookkeeping may light a badge that should have been
- * quiet, and must never hide one that should have been lit.
- *
- * BOTH WRITES ANSWER "did this take effect", which is the question the caller's NEXT line depends on. Marking
- * something seen is almost always followed by folding it out of the badge locally, so the tile clears on the
- * spot rather than at the next poll, and that fold is a write into sandbox-scoped state, so it must not happen
- * when the acknowledgement itself was abandoned because the owner switched sandbox mid-operation. It would
- * silence the NEW box's badge for a fact about the old one. `false` means only that: the scope moved. A ledger
- * that already said what you asked it to say answers `true`, because it does. */
+// Key → mark map of what the owner has already seen, stored as JSON under `.intentic`. Missing or unparseable reads as
+// nothing acknowledged; a write's `false` return means only that the sandbox scope moved mid-write.
 export interface SandboxLedger {
     // Everything acknowledged so far. Absent, unparseable or not-an-object all read as nothing.
     read(): Promise<Readonly<Record<string, string>>>;
-    /* Record these, leaving every other entry alone, the ordinary acknowledgement. No write happens when
-     * nothing moved: the file push would otherwise cost every connected browser a refetch for a file whose
-     * content is identical. */
+    // Records these, leaving every other entry alone; no write happens when nothing moved.
     mark(entries: Readonly<Record<string, string>>): Promise<boolean>;
-    /* Make these the WHOLE ledger, dropping anything not named. For a ledger whose keys go out of scope, a
-     * run that has scrolled past the scan window can never be seen again, and merging forever would grow the
-     * file without bound. Same no-op-when-unchanged rule as `mark`.
-     */
+    // Makes these the whole ledger, dropping anything not named; same no-op-when-unchanged rule as mark.
     replace(entries: Readonly<Record<string, string>>): Promise<boolean>;
 }
 
@@ -269,20 +170,17 @@ const sameEntries = (left: Readonly<Record<string, string>>, right: Readonly<Rec
 export const sandboxLedger = (host: () => IntenticApi, path: string): SandboxLedger => {
     const read = async (): Promise<Readonly<Record<string, string>>> => {
         const parsed = await host().workspace.readJson<Record<string, unknown>>(path);
-        // Non-string values are dropped rather than coerced: a mark is a string, and anything else is somebody
-        // else's idea of what this file is for.
+        // Non-string values are dropped, not coerced: a mark is always a string.
         return Object.fromEntries(Object.entries(parsed ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === `string`));
     };
 
-    /* One writer for both verbs, and the scope guard lives HERE rather than at the call site, this is the
-     * only thing in an extension's background work that damages state on DISK when a sandbox switch lands
-     * mid-operation. Reading one workspace's acknowledgements and writing them into the tree of the workspace
-     * the owner has just moved to is bookkeeping filed in the wrong place, which no later poll corrects. */
+    // One writer for both mark and replace; the scope guard lives here, not at the call site, since a sandbox switch
+    // mid-write would file the acknowledgement into the workspace the owner just left.
     const settle = async (next: (seen: Readonly<Record<string, string>>) => Readonly<Record<string, string>>): Promise<boolean> => {
         const current = sandboxScopeGuard();
         const seen = await read();
         const wanted = next(seen);
-        // Already saying it. Nothing to write, and the caller's local fold is still right.
+        // Already saying it: nothing to write, and the caller's fold stays correct.
         if (sameEntries(seen, wanted)) {
             return true;
         }

package/src/diff.ts

@@ -1,73 +1,42 @@
 import type { PartialFileDiff } from "@intentic/sandbox-contract";
 
-/* WHAT AN EXTENSION HANDS THE HOST TO OPEN A DIFF, the argument to `api.workspace.openDiff`.
- *
- * A diff belongs in the editor area beside the files it is about, in the same tab strip as everything else the
- * user has open. That strip is the host's, so an extension that has computed a before/after pair has nowhere to
- * put it: a view renders inside its own frame, and a document provider inside its own tab. This is the way out,
- * and it is the whole shape of the contribution, the extension says what changed, the host owns the tab, the
- * viewer, the close orchestration and the dirty-buffer bookkeeping.
- *
- * It lives in the PUBLIC api package rather than in the app because the app is downstream of it: the workspace's
- * own review surfaces build the identical payload, and having two spellings of it is how the two would drift. */
+// The argument to `api.workspace.openDiff`: the extension says what changed, the host owns the tab, viewer and
+// dirty-buffer bookkeeping. Lives in the public api package because the app's own review surfaces build the identical
+// payload.
 
-// Git's vocabulary for what happened to a file. "conflicted" is git's unmerged state (`U`) and is not a kind of
-// modification, there is no stage 0 for such a path, so nothing a commit could record. The host renders each of
-// these as its own letter and colour.
+// Git's vocabulary for what happened to a file; the host renders each as its own letter and colour. "conflicted" is
+// git's unmerged state (`U`), not a kind of modification.
 export type ChangeStatus = "added" | "modified" | "deleted" | "renamed" | "type-changed" | "conflicted";
 
-/* A binary diff ships no text, so its two sides ride the payload as daemon URLs its BYTES are fetched from
- * rather than as content. An absent side means that side does not exist, an added file has no before, a deleted
- * one no after, and the viewer then gives the side that does exist the whole pane instead of drawing an empty
- * half beside it. */
+// A binary diff ships its two sides as daemon URLs to fetch bytes from, not as content. An absent side means that side
+// does not exist; the viewer gives the pane entirely to the side that does.
 export interface DiffRawSides {
     readonly beforeRaw?: string;
     readonly afterRaw?: string;
 }
 
 export interface DiffPayload extends DiffRawSides {
-    /* The diff SOURCE's identity, a commit sha, a snapshot id, `working:<repo>`. Together with `scope` and
-     * `path` it is the tab's identity, so re-opening the same file at the same commit focuses the tab that is
-     * already open rather than stacking a second copy of it. Pick something stable and collision-free; prefixing
-     * with the extension's own id is the safe habit. */
+    // Identity of the diff source (commit sha, snapshot id, `working:<repo>`); with `scope`/`path` it is the tab's
+    // identity, so a reopen focuses it.
     readonly key: string;
     // Which repo (or snapshot scope) the path is relative to, the other half of the tab identity.
     readonly scope: string;
-    // The tab's label. Short: the strip is narrow, and "file.ts @ a1b2c3d" reads better than a full path.
+    // The tab's label; keep it short (e.g. "file.ts @ a1b2c3d"), the strip is narrow.
     readonly label: string;
     readonly status: ChangeStatus;
     readonly path: string;
-    // The two sides as text. Absent where the side does not exist, or where the content is binary/oversized,
-    // `binary` and `partial` are what the viewer renders instead of an empty pane.
+    // The two sides as text; absent when a side doesn't exist or is binary/oversized (see `binary`/`partial`).
     readonly before?: string;
     readonly after?: string;
     readonly binary?: boolean;
-    /* A file too big to hand over whole, described by its changed regions instead (a unified patch) plus the
-     * sizes of the two sides. The host's viewer rebuilds a real diff out of it, with the file's own line
-     * numbers, so an extension that has computed a huge before/after pair has something better to offer than
-     * a refusal: set this and leave `before`/`after` off. See PartialFileDiff for how the patch is read. */
+    // A big file's changed regions (a unified patch) plus both sizes; set this instead of before/after.
     readonly partial?: PartialFileDiff;
-    // What the row that opened this diff already knew about its size, carried onto the tab's toolbar. Absent
-    // where the source has no numstat to give (a binary file, a change list without line counts), the toolbar
-    // then renders nothing rather than a zero.
+    // Size already known by the row that opened this, shown on the tab's toolbar; absent renders nothing, not zero.
     readonly additions?: number;
     readonly deletions?: number;
-    /* THE CONTENT IS STILL COMING, open the tab now and fill it in when it lands (`workspace.fillDiff`).
-     *
-     * Reading a file the source has to compute or fetch is a wait, and a wait that has nowhere to be drawn gets
-     * drawn on the click instead: the row is clicked, nothing on screen changes, and the reader clicks it again.
-     * Everything the tab needs to exist, its identity, its label, the status letter and the line counts, is
-     * known before the content is, so the tab opens on the click and the panes fill underneath it.
-     *
-     * Absent means the payload IS the content, which is what an extension handing over an already-computed
-     * before/after pair should send. */
+    // Opens the tab immediately and fills content later via `workspace.fillDiff`; absent means the payload is the
+    // content.
     readonly pending?: boolean;
-    /* THIS IS A LOOK, NOT AN OPEN: the tab takes the strip's single transient slot (the italic tab), and the
-     * next peek replaces it in place.
-     *
-     * It is the difference between a list being READ and a file being CHOSEN. An extension whose document lists
-     * changed files (a commit's, a run's) has a reader who will click ten of them in a row, and ten pinned tabs
-     * is what the slot exists to prevent, so those clicks are peeks and a double-click, which should send the
-     * payload without this, is what keeps one. Absent means keep, which is right for a single deliberate open. */
+    // A peek, not an open: reuses the strip's one transient tab slot instead of pinning a new one; absent keeps it.
     readonly preview?: boolean;
 }

package/src/facts.ts

@@ -1,17 +1,9 @@
-/* The stable DETECTION facts, the subset of the daemon's wire schemas an extension's `detect()` reads to decide
- * when to activate a view. This is deliberately narrow (evidence over identity) so activation logic doesn't
- * couple to the daemon's fuller summaries. It is NOT the data plane: an activated extension reads real data over
- * `api.sandbox.request/json` against the `@intentic/sandbox-contract` schemas, the first-party wire contract,
- * gated per-route by the manifest's `permissions.sandbox` allowlist. (Because every first-party extension is
- * in-repo and compiled together, a wire change there is caught by the compiler and fixed atomically, so there is
- * no separate "stable data API" to promote, only detection is version-stable.) The daemon's own summaries
- * (PanelSummary, CapabilitySummary) are structural supersets and flow into `detect()` unmapped, but only THESE
- * fields are guaranteed to it. Optional fields carry `| undefined` so zod-inferred wire types assign under
- * exactOptionalPropertyTypes. */
+// Stable detection facts `detect()` reads to decide when to activate a view: narrow and evidence-based, not the data
+// plane (real data comes via `api.sandbox.request/json` against sandbox-contract schemas). Optional fields carry `|
+// undefined` for exactOptionalPropertyTypes.
 
-// Daemon-computed content facts for one discovered repository under /work (`repo` is its root-relative dir),
-// evidence over identity: a repo is served because of what it CONTAINS (deploy.config.ts, pnpm-workspace.yaml
-// + turbo.json, .intentic/ui), not what it happens to be named.
+// Daemon-computed content facts for one repo under /work (`repo` is its root-relative dir); evidence over identity,
+// based on what the repo contains, not its name.
 export interface RepoFacts {
     readonly repo: string;
     // The workspace role this repo dir occupies; absent for extra clones.
@@ -23,19 +15,14 @@ export interface RepoFacts {
     readonly directoryUi: boolean;
     readonly monorepo: boolean;
     readonly vitest: boolean;
-    // Whether the repo describes its features as user stories (a docs/user-stories directory), the one fact
-    // here that is language-agnostic, and the evidence an acceptance-testing surface activates on.
+    // Whether the repo has a docs/user-stories directory; what an acceptance-testing surface activates on.
     readonly userStories: boolean;
-    /* Whether the repo carries architecture documentation (a docs/architecture directory).
-     *
-     * Here so that a surface which READS documentation can tell, without asking the file routes, which repos
-     * have any. The alternative was a read per repo on a poll, an answer the daemon already has from the same
-     * one-pass scan that produces every other fact on this interface. */
+    // Whether the repo has a docs/architecture directory.
     readonly docs: boolean;
 }
 
-// One connected capability's secret-free echo, `kind` is an open string: new kinds appear without an API bump,
-// and matching on one couples the extension to that kind's continued existence.
+// One connected capability's secret-free echo. `kind` is an open string; matching on one couples the extension to it
+// continuing to exist.
 export interface CapabilityFacts {
     readonly id: string;
     readonly kind: string;

package/src/host.ts

@@ -1,18 +1,8 @@
 import type { IntenticApi } from "./api.js";
 
-/* THE AMBIENT HOST HANDLE, one slot per extension. `activate(api)` binds it once, before any view renders, so
- * the extension's composables reach the authenticated daemon transport, cache scoping and workspace facts
- * through `host()`, the way `vscode.*` is ambient to a VSCode extension. Not app internals: everything flows
- * through the public IntenticApi.
- *
- * A FACTORY rather than a module-level slot here, and that is the whole reason this lives in the API package
- * instead of being one shared `host()`. The web shell publishes ONE instance of this module to every bundle
- * (extension-host/hostModules.ts), so a slot held at module scope would be a single global that the last
- * extension to activate silently takes over. Each extension calls this once and keeps its own closure:
- *
- *     export const { bindHost, host } = hostSlot(`ext-activity`);
- *
- * The names come back already spelled the way call sites use them, so nothing downstream renames anything. */
+// Per-extension host handle, ambient like `vscode.*`: `activate(api)` binds it once via `bindHost`, `host()` reads it.
+// A factory, not a module-level slot: the web shell publishes one instance of this module to every extension's bundle,
+// so a shared slot would be overwritten by whichever activates last.
 export const hostSlot = (extension: string): { bindHost: (api: IntenticApi) => void; host: () => IntenticApi } => {
     let current: IntenticApi | undefined;
     return {

package/src/protocol.ts

@@ -1,18 +1,6 @@
-/* THE HALF OF THIS PACKAGE THAT RUNS WITHOUT A BROWSER, the protocol version and the matcher that compares a
- * manifest's `engines.intentic` against it.
- *
- * The root barrel is the EXTENSION-facing surface, and an extension runs in the app, so the barrel is free to
- * reach for vue: `scope.ts` imports `ref` as a value, not a type. The daemon is the other consumer, and it
- * needs exactly these two names, to refuse an incompatible extension (backend-supervisor), to stamp the
- * version it provides (backend-host-main), to write an engines range into a scaffold. It has no vue and no
- * reason to grow one, but `export *` loads every re-exported module eagerly, so importing the barrel for
- * `extensionApiVersion` alone dragged `vue` into a Node process that could not resolve it, the daemon crashed
- * on boot and the sandbox never became healthy.
- *
- * Hence this entry point. `@intentic/extension-api/protocol` is what host-side Node code imports; the root
- * barrel keeps exporting both names too, so nothing about the published extension surface changes. Type-only
- * imports from the root (`ExtensionServerApi` and friends) stay where they are, those are erased at compile
- * time and never reach the loader. */
+// Node-safe entry point for `satisfiesEngines`/`extensionApiVersion`: the root barrel's `export *` eagerly loads every
+// module including vue, which a host-side Node process (the daemon) cannot resolve. The root barrel still re-exports
+// both names too.
 
 export { satisfiesEngines } from "./engines.js";
 export { extensionApiVersion } from "./version.js";

package/src/route.ts

@@ -1,17 +1,11 @@
-/* The URL-query rules behind `api.route`, as pure functions, the same split `permissions.ts` uses: the host owns
- * the router, this owns the rule, and the rule is testable without one.
- *
- * A view's internal navigation lives in the QUERY because the path is already spoken for: `/ext/:ext/:key?` has
- * exactly one free segment and it means "which activation". So several views can be addressing the same query
- * string at once, and the one rule that matters is that none of them may clobber another's key. */
+// Pure functions behind `api.route`'s URL-query rules; the host owns the router, this owns the rule. Navigation lives
+// in the query since `/ext/:ext/:key?` has only one free segment (the activation); no view may clobber another's key.
 
 // What the router hands back for a query: vue-router yields `string | null` per key, or an array when a key repeats.
 export type RawQuery = Readonly<Record<string, string | readonly (string | null)[] | null | undefined>>;
 
-/* Flatten a router query to the scalar record extensions read. A repeated key takes its FIRST value rather than
- * its last: a view's state is singular, and the first occurrence is the one a hand-written or shared link means.
- * A valueless key (`?draft`) reads as the empty string, which is falsy-ish for the caller to test but never
- * `undefined`, absent and present-but-empty are different answers. */
+// Flattens a router query to a scalar record. A repeated key keeps its first value (what a hand-written or shared link
+// means); a valueless key (`?draft`) becomes `""`, never `undefined`.
 export const flattenQuery = (query: RawQuery): Record<string, string> => {
     const out: Record<string, string> = {};
     for (const [key, value] of Object.entries(query)) {
@@ -25,10 +19,8 @@ export const flattenQuery = (query: RawQuery): Record<string, string> => {
     return out;
 };
 
-/* Merge a patch into the live query. `undefined` REMOVES its key, that is how a view says "I am no longer on a
- * page" without leaving `?doc=` behind, so the tidy URL is the one you get by default rather than one you have to
- * construct. Every key the patch does not mention is carried through untouched, which is the whole invariant:
- * a documentation view setting `doc` must not drop the terminal's or another view's parameters. */
+// Merges a patch into the live query; `undefined` removes that key rather than leaving `?doc=` behind. Every key the
+// patch doesn't mention passes through untouched.
 export const mergeQuery = (current: RawQuery, patch: Readonly<Record<string, string | undefined>>): Record<string, string> => {
     const next = flattenQuery(current);
     for (const [key, value] of Object.entries(patch)) {

package/src/scope.ts

@@ -1,27 +1,7 @@
 import { ref, type Ref } from "vue";
 
-/* STATE THAT BELONGS TO ONE SANDBOX, and the reason an extension cannot be left to remember that itself.
- *
- * Three tiers of client state exist in this app, and each needs a different answer to "what happens on a
- * switch". Cached server state is keyed by `api.sandbox.key(...)`, so it is answered by construction. State
- * inside a mounted component dies with the component. THIS is the third tier: module state owned by
- * `activate()`, the badge counts, the document-presence maps, the poll results that must survive the view
- * being unmounted, because a badge you only see once you have already navigated to the view is pointless.
- *
- * Nothing owned it. A rail tile filled by a ten-minute timer therefore kept the PREVIOUS sandbox's number for
- * up to ten minutes after a switch, under the new sandbox's name, a badge is a claim addressed to the reader,
- * and one describing a workspace they are no longer looking at is worse than no badge at all. It was not one
- * extension's mistake either: every extension that badges had the identical shape, which is the signature of a
- * missing primitive rather than of carelessness.
- *
- * So the host owns it. Declare the state through `sandboxRef` and the host empties it on every switch; there
- * is no subscription to remember and no teardown to write.
- *
- * A MODULE-LEVEL REGISTRY IS CORRECT HERE, and that is worth saying because `hostSlot` in this same package
- * warns against exactly that. The shell publishes ONE instance of this module to every bundle
- * (extension-host/hostModules.ts), so a slot held here is shared by all of them, which made it wrong for a
- * per-extension host handle and makes it right for this: one switch empties every extension's scope, and no
- * extension can be missed. */
+// Module state scoped to one sandbox (badge counts, poll results) that must survive a component unmount. Declare it
+// through `sandboxRef`; the host clears it on every sandbox switch, so there is no subscription or teardown to write.
 
 interface Registered {
     readonly clear: () => void;
@@ -29,22 +9,11 @@ interface Registered {
 
 const registered: Registered[] = [];
 
-/* Which scope the extensions are in, counted rather than named, this module cannot see the sandbox id, and
- * does not need to. All any caller asks is "is this still the scope I started in", and a counter answers that
- * without this package having to know what a sandbox is. */
+// Sandbox scope counter; this package can't see sandbox ids, only whether the scope changed since a value was captured.
 let generation = 0;
 
-/* MODULE STATE FOR ONE SANDBOX. `initial` is a factory, not a value, so each scope starts from a fresh object
- * rather than sharing (and slowly mutating) one literal written at import time.
- *
- *     const unseen = sandboxRef<readonly ChoreVerdict[]>(() => []);
- *
- * It is an ordinary `Ref` in every other respect: read it in a `badge()` or a `detect()` and the host's own
- * computed re-renders the tile when it changes, exactly as before. READ, not write, see `sandboxValue`.
- *
- * `dispose` is for state that owns something the garbage collector will not take back, an object URL, a
- * subscription. It is handed the value being dropped, once, at the moment the scope closes. Most callers need
- * none: a list of verdicts is released by being replaced. */
+// Module state scoped to one sandbox: resets to a fresh `initial()` on every switch. `dispose`, if given, runs once on
+// the outgoing value, for state that owns something the garbage collector won't reclaim.
 export const sandboxRef = <T>(initial: () => T, dispose?: (previous: T) => void): Ref<T> => {
     const state = ref(initial()) as Ref<T>;
     registered.push({
@@ -56,30 +25,14 @@ export const sandboxRef = <T>(initial: () => T, dispose?: (previous: T) => void)
     return state;
 };
 
-// A sandbox-scoped box that nothing observes. Same shape as a `Ref` on purpose, `.value`, read and written,
-// so moving state between the two is one word at the declaration and nothing at the call sites.
+// A sandbox-scoped box that nothing observes; same `.value` shape as a `Ref` so state can move between the two without
+// changing call sites.
 export interface SandboxValue<T> {
     value: T;
 }
 
-/* MODULE STATE FOR ONE SANDBOX THAT NOTHING RENDERS, `sandboxRef`'s lifetime without its reactivity, for the
- * bookkeeping a background poll keeps for ITSELF: which connections to ask about next round, the cursor a
- * fetch resumes from, the id a retry belongs to.
- *
- * It exists because of where `detect()` and `badge()` are called from. Both run INSIDE the host's render
- * computed, that is the whole mechanism by which a tile repaints when a poll lands, and a `Ref` WRITTEN from
- * inside a computed is that computed mutating its own dependency. Vue re-runs it, the write happens again, and
- * the rail recurses until Vue abandons the flush mid-frame. What the reader sees then is not one broken tile:
- * every update queued behind the rail is dropped with the flush, so the whole window stops answering, and the
- * console fills with a recursion error naming a component that is merely where the loop was noticed.
- *
- * So the division is by AUDIENCE, not by lifetime: `sandboxRef` for what a tile SHOWS, `sandboxValue` for what
- * a poll REMEMBERS. Both are emptied on a switch by the same door, and writing this one from a render callback
- * is safe precisely because there is nothing to invalidate. When a poll's own bookkeeping later turns out to
- * be worth showing, promoting it is a one-word change, and the promotion is the moment to check that nothing
- * writes it from `detect()`.
- *
- * `dispose` behaves exactly as it does on `sandboxRef`. */
+// Like `sandboxRef` but not reactive: safe to write from inside `detect()`/`badge()`, which run inside the host's own
+// render computed, where writing a `Ref` would re-trigger it recursively.
 export const sandboxValue = <T>(initial: () => T, dispose?: (previous: T) => void): SandboxValue<T> => {
     const box: SandboxValue<T> = { value: initial() };
     registered.push({
@@ -91,28 +44,14 @@ export const sandboxValue = <T>(initial: () => T, dispose?: (previous: T) => voi
     return box;
 };
 
-/* THE GUARD FOR WORK THAT WAS ALREADY IN FLIGHT WHEN THE SWITCH HAPPENED.
- *
- * Emptying the refs is not enough on its own. A poll that issued its request under the old sandbox resolves a
- * moment after the switch, and writes the old box's answer into the fresh scope, the same wrong badge, just
- * harder to reproduce. There is no way for this module to cancel that request, so it offers the one thing the
- * caller needs instead: a way to ask, after the await, whether the answer is still wanted.
- *
- * Take it BEFORE the await, ask it AFTER:
- *
- *     const current = sandboxScopeGuard();
- *     const report = await api.sandbox.fetch(query);
- *     if (!current()) return;
- *     unseen.value = assess(report);
- *
- * Two lines, and the failure it prevents is invisible without them. */
+// Snapshot the current scope before an await; call the result after to check the scope hasn't switched meanwhile.
+// Needed because emptying the refs doesn't stop an in-flight request from writing its answer into the new scope.
 export const sandboxScopeGuard = (): (() => boolean) => {
     const taken = generation;
     return () => taken === generation;
 };
 
-/* THE HOST'S DOOR, called by the shell when the active sandbox changes, not by extensions, which have nothing
- * to reset and no business resetting each other's. */
+// Called by the shell whenever the active sandbox changes; extensions never call this, they have nothing to reset.
 export const resetSandboxScope = (): void => {
     generation += 1;
     for (const entry of registered) {