@intentic/extension-api 1.223.0 → 1.224.0

package/src/background.ts

@@ -2,7 +2,7 @@ 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
+/* 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
@@ -12,7 +12,7 @@ import { sandboxRef, sandboxScopeGuard } from "./scope.js";
  * 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
+ *   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
@@ -31,7 +31,7 @@ export interface SandboxPoll<T> {
     readonly state: Ref<T>;
     // Begin polling. Push the Disposable onto `context.subscriptions` and the clock stops with the extension.
     start(): Disposable;
-    // Read now, off-cycle — for the moments that change the answer and should not wait out the interval: a
+    // 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.
     refresh(): void;
 }
@@ -46,14 +46,14 @@ export interface SandboxPollOptions<T> {
     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
+    /* 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.
      */
     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()`. */
+     * something else tells it what to ask about, deployments learns its connections from `detect()`. */
     readonly immediate?: boolean;
     // For a value that owns something the garbage collector will not take back; see sandboxRef.
     readonly dispose?: (previous: T) => void;
@@ -75,7 +75,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
+            // 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".
         }
     };
@@ -97,12 +97,12 @@ export const sandboxPoll = <T>(options: SandboxPollOptions<T>): SandboxPoll<T> =
  *
  * 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
+ * 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
+ * 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.
@@ -113,18 +113,18 @@ export const sandboxPoll = <T>(options: SandboxPollOptions<T>): SandboxPoll<T> =
  *
  * 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
+ * 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. */
 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
+    /* 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. */
     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
+    /* 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`.
      */
@@ -142,7 +142,7 @@ export const sandboxLedger = (host: () => IntenticApi, path: string): SandboxLed
         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
+    /* 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. */

package/src/diff.ts

@@ -1,22 +1,22 @@
-/* WHAT AN EXTENSION HANDS THE HOST TO OPEN A DIFF — the argument to `api.workspace.openDiff`.
+/* 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
+ * 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. */
 
 // 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
+// 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.
 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
+ * 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. */
 export interface DiffRawSides {
     readonly beforeRaw?: string;
@@ -24,33 +24,33 @@ export interface DiffRawSides {
 }
 
 export interface DiffPayload extends DiffRawSides {
-    /* The diff SOURCE's identity — a commit sha, a snapshot id, `working:<repo>`. Together with `scope` and
+    /* 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. */
     readonly key: string;
-    // Which repo (or snapshot scope) the path is relative to — the other half of the tab identity.
+    // 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.
     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 —
+    // The two sides as text. Absent where the side does not exist, or where the content is binary/oversized,
     // `binary` and `truncated` are what the viewer renders instead of an empty pane.
     readonly before?: string;
     readonly after?: string;
     readonly binary?: boolean;
     readonly truncated?: boolean;
     // 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
+    // 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.
     readonly additions?: number;
     readonly deletions?: number;
-    /* THE CONTENT IS STILL COMING — open the tab now and fill it in when it lands (`workspace.fillDiff`).
+    /* 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
+     * 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

package/src/engines.ts

@@ -1,5 +1,5 @@
 // Minimal matcher for a manifest's `engines.intentic` range against the host's extension API version: an exact
-// version ("0.1.0") or a caret range ("^0.1", "^1", "^1.2.3"). Caret follows semver — same major at or above
+// version ("0.1.0") or a caret range ("^0.1", "^1", "^1.2.3"). Caret follows semver, same major at or above
 // the floor, and while the major is 0 the minor is breaking too. Anything unparseable fails closed: the loader
 // reports the extension incompatible rather than activating on a guess.
 

package/src/facts.ts

@@ -1,15 +1,15 @@
-/* The stable DETECTION facts — the subset of the daemon's wire schemas an extension's `detect()` reads to decide
+/* 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,
+ * `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
+ * 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. */
 
-// Daemon-computed content facts for one discovered repository under /work (`repo` is its root-relative dir) —
+// 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.
 export interface RepoFacts {
@@ -23,18 +23,18 @@ 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
+    // 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.
     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
+     * 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. */
     readonly docs: boolean;
 }
 
-// One connected capability's secret-free echo — `kind` is an open string: new kinds appear without an API bump,
+// 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.
 export interface CapabilityFacts {
     readonly id: string;

package/src/host.ts

@@ -2,7 +2,7 @@ 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 `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

package/src/protocol.ts

@@ -1,17 +1,17 @@
-/* THE HALF OF THIS PACKAGE THAT RUNS WITHOUT A BROWSER — the protocol version and the matcher that compares a
+/* 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
+ * 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
+ * `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
+ * imports from the root (`ExtensionServerApi` and friends) stay where they are, those are erased at compile
  * time and never reach the loader. */
 
 export { satisfiesEngines } from "./engines.js";

package/src/route.ts

@@ -1,4 +1,4 @@
-/* The URL-query rules behind `api.route`, as pure functions — the same split `permissions.ts` uses: the host owns
+/* 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
@@ -11,7 +11,7 @@ export type RawQuery = Readonly<Record<string, string | readonly (string | null)
 /* 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. */
+ * `undefined`, absent and present-but-empty are different answers. */
 export const flattenQuery = (query: RawQuery): Record<string, string> => {
     const out: Record<string, string> = {};
     for (const [key, value] of Object.entries(query)) {
@@ -25,7 +25,7 @@ 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
+/* 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. */

package/src/scope.ts

@@ -5,11 +5,11 @@ import { ref, type Ref } from "vue";
  * 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
+ * `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,
+ * 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.
@@ -19,7 +19,7 @@ import { ref, type Ref } from "vue";
  *
  * 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
+ * (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. */
 
@@ -29,7 +29,7 @@ interface Registered {
 
 const registered: Registered[] = [];
 
-/* Which scope the extensions are in, counted rather than named — this module cannot see the sandbox id, and
+/* 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. */
 let generation = 0;
@@ -40,9 +40,9 @@ let generation = 0;
  *     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`.
+ * 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
+ * `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. */
 export const sandboxRef = <T>(initial: () => T, dispose?: (previous: T) => void): Ref<T> => {
@@ -56,18 +56,18 @@ 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 —
+// 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.
 export interface SandboxValue<T> {
     value: T;
 }
 
-/* MODULE STATE FOR ONE SANDBOX THAT NOTHING RENDERS — `sandboxRef`'s lifetime without its reactivity, for the
+/* 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
+ * 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
@@ -76,7 +76,7 @@ export interface SandboxValue<T> {
  * 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
+ * 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`. */
@@ -94,7 +94,7 @@ export const sandboxValue = <T>(initial: () => T, dispose?: (previous: T) => voi
 /* 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
+ * 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.
  *
@@ -111,7 +111,7 @@ export const sandboxScopeGuard = (): (() => boolean) => {
     return () => taken === generation;
 };
 
-/* THE HOST'S DOOR, called by the shell when the active sandbox changes — not by extensions, which have nothing
+/* 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. */
 export const resetSandboxScope = (): void => {
     generation += 1;

package/src/server.ts

@@ -1,49 +1,49 @@
-/* THE SERVER HALF an extension programs against — the daemon-side twin of IntenticApi (api.ts).
+/* THE SERVER HALF an extension programs against, the daemon-side twin of IntenticApi (api.ts).
  *
- * A manifest `server` bundle exports `activateServer(api, context)`, and the daemon's BACKEND HOST — one
- * separate supervised node process shared by every enabled extension with a backend — imports the bundle and
+ * A manifest `server` bundle exports `activateServer(api, context)`, and the daemon's BACKEND HOST, one
+ * separate supervised node process shared by every enabled extension with a backend, imports the bundle and
  * calls it. A separate process rather than the daemon itself because loaded code can never be unloaded: the
  * off switch, an upgrade to a new sha and a live-edited workspace extension all require the process holding
  * the old code to die, and that process must never be the daemon (chat, terminals and file sync live there).
  * A shared process rather than one per extension because the trust model is full trust (install is owner-only
- * and sha-pinned) — isolation between extensions would buy robustness nobody is billed for.
+ * and sha-pinned), isolation between extensions would buy robustness nobody is billed for.
  *
  * Full trust is also why this surface is deliberately small. The backend runs in the sandbox container as the
- * same user the daemon does, so the workspace is reachable with plain `node:fs` — the api hands over PATHS,
+ * same user the daemon does, so the workspace is reachable with plain `node:fs`, the api hands over PATHS,
  * not a file service. What it does mediate is the two things a path cannot carry: the extension's route
  * namespace (mount), and its reach into the daemon's own routes (daemon.*, gated by the manifest's
- * `permissions.daemon` — the daemon refuses undeclared routes, same grammar and same honesty rule as the UI
+ * `permissions.daemon`, the daemon refuses undeclared routes, same grammar and same honesty rule as the UI
  * half's `permissions.sandbox`). */
 
 // One request into this extension's namespace. The host strips the `/x/<id>` prefix before dispatch, so the
-// handler sees the extension's OWN paths — the same paths its contract declares and its UI half calls.
+// handler sees the extension's OWN paths, the same paths its contract declares and its UI half calls.
 // `undefined` means "not mine": the host answers 404 without the extension having to speak HTTP for it.
 export type BackendRouteHandler = (request: Request) => Promise<Response | undefined>;
 
 export interface ExtensionServerApi {
-    // The host's @intentic/extension-api version — what `engines.intentic` was checked against.
+    // The host's @intentic/extension-api version, what `engines.intentic` was checked against.
     readonly apiVersion: string;
-    // The workspace root (absolute). The backend reads and writes under it with node's own fs — full trust
+    // The workspace root (absolute). The backend reads and writes under it with node's own fs, full trust
     // means no file service in between. Durable state belongs in workspace files (the same rule the UI half
     // lives by): it survives restarts, is shared across browsers, and the agent editing it out-of-band is the
     // product.
     readonly workspaceRoot: string;
-    // This extension's own checkout (absolute) — where its bundled assets sit.
+    // This extension's own checkout (absolute), where its bundled assets sit.
     readonly extensionDir: string;
     // A line in the daemon's log, attributed to this extension.
     readonly log: (message: string) => void;
     readonly routes: {
-        /* Serve this extension's route namespace. The daemon proxies /x/<id>/* here — through its ordinary
+        /* Serve this extension's route namespace. The daemon proxies /x/<id>/* here, through its ordinary
          * auth (an owner's browser, a member at the route's role floor), so a backend never sees an
          * unauthenticated request and never sees a credential. One handler per extension: the extension owns
          * its whole namespace, and how it routes inside it (an oRPC handler over its own contract, a plain
          * switch) is its own business. A second mount replaces the first. */
         mount(handler: BackendRouteHandler): void;
     };
-    /* The authenticated transport to the daemon's own routes — the backend's `api.sandbox`. Auth is a minted
+    /* The authenticated transport to the daemon's own routes, the backend's `api.sandbox`. Auth is a minted
      * per-extension token injected here; the daemon's gate checks every call against the manifest's
      * `permissions.daemon` allowlist, so a backend's reach into the core is declared, reviewable and refusable
-     * exactly like the UI half's. The extension's own namespace needs no declaration — but there is also no
+     * exactly like the UI half's. The extension's own namespace needs no declaration, but there is also no
      * reason to dial yourself over HTTP. */
     readonly daemon: {
         request(path: string, init?: RequestInit): Promise<Response>;
@@ -52,13 +52,13 @@ export interface ExtensionServerApi {
 }
 
 export interface ExtensionServerContext {
-    // The extension's routing id — its /x/<id> namespace segment (the capability entry id for a git-installed
+    // The extension's routing id, its /x/<id> namespace segment (the capability entry id for a git-installed
     // extension, publisher.name otherwise; the same id the UI half sees as ExtensionSummary.id).
     readonly extensionId: string;
 }
 
 // The shape of the manifest `server` bundle's default export (or its named exports): `activateServer` runs
-// once per backend-host start, after the engines check. There is no deactivate — retirement IS the host
+// once per backend-host start, after the engines check. There is no deactivate, retirement IS the host
 // process ending, which is the one teardown that cannot leak.
 export interface ExtensionServerModule {
     activateServer(api: ExtensionServerApi, context: ExtensionServerContext): void | Promise<void>;

package/src/stream.ts

@@ -1,9 +1,9 @@
-/* Reading a daemon SSE/ndjson stream — the transport half of `sandbox.request().body`. The daemon emits SSE
+/* Reading a daemon SSE/ndjson stream, the transport half of `sandbox.request().body`. The daemon emits SSE
  * frames (blank-line separated, each a `data: <JSON>` line, an oRPC event-iterator failure as `event: error`),
  * so consuming a streamed apply/plan/provision means reframing + JSON-parsing. Pure (ReadableStream in, async
- * records out), no deps — extensions bundle it; the shim path never touches it. */
+ * records out), no deps, extensions bundle it; the shim path never touches it. */
 
-// A silent daemon — one that accepts the stream then sends nothing and never closes — would park reader.read()
+// A silent daemon, one that accepts the stream then sends nothing and never closes, would park reader.read()
 // forever, hanging the consumer. A live daemon heartbeats (≤1s) over the stream, so no bytes for this long means
 // the connection is dead: cancel the reader and end the generator instead of waiting indefinitely.
 const SSE_IDLE_MS = 120_000;

package/src/surface.json

@@ -467,5 +467,71 @@
             "sandboxValue",
             "satisfiesEngines"
         ]
+    },
+    "2.9.0": {
+        "manifest": [
+            "$schema",
+            "art",
+            "category",
+            "contributes",
+            "engines",
+            "entry",
+            "icon",
+            "logo",
+            "name",
+            "permissions",
+            "publisher",
+            "server",
+            "version"
+        ],
+        "contributes": [
+            "agent",
+            "automationTemplates",
+            "bin",
+            "capabilities",
+            "commands",
+            "documents",
+            "environment",
+            "files",
+            "listener",
+            "processes",
+            "settings",
+            "viewers",
+            "views"
+        ],
+        "api": [
+            "apiVersion",
+            "chat",
+            "commands",
+            "documents",
+            "href",
+            "models",
+            "navigate",
+            "processes",
+            "route",
+            "sandbox",
+            "settings",
+            "terminal",
+            "theme",
+            "viewers",
+            "views",
+            "workspace"
+        ],
+        "listener": ["automation", "events", "provider"],
+        "sandboxApi": ["fetch", "json", "key", "origin", "reachable", "request", "role", "rpc"],
+        "moduleExports": [
+            "extensionApiVersion",
+            "flattenQuery",
+            "hostSlot",
+            "mergeQuery",
+            "readDaemonStream",
+            "resetSandboxScope",
+            "sandboxLedger",
+            "sandboxPoll",
+            "sandboxRef",
+            "sandboxScopeGuard",
+            "sandboxValue",
+            "satisfiesEngines"
+        ]
     }
 }

package/src/version.ts

@@ -1,56 +1,62 @@
-// The extension API's protocol version — the value `engines.intentic` ranges are matched against at load, and
+// The extension API's protocol version, the value `engines.intentic` ranges are matched against at load, and
 // the value the host reports as IntenticApi.apiVersion. Bumped ONLY with the published package: additive
 // surface = minor, breaking = major. This package is the one deliberate exception to the repo's no-legacy rule.
 //
 // 1.0.0 rather than 0.5.0, and the reason is the drift that forced that bump. While the major was 0 the caret
-// matcher treats the MINOR as breaking (engines.ts), so every addition invalidated every declared range — which
+// matcher treats the MINOR as breaking (engines.ts), so every addition invalidated every declared range, which
 // made bumping expensive enough that two surface changes (connectors → capabilities, api.documents.open) shipped
 // without one, and the number stopped being true. At 1.x an addition is 1.1.0 and costs authors nothing, so the
 // bump that keeps this honest is the cheap one. surface-guard.test.ts is what makes it non-optional.
 // 2.0.0 makes listener contributions self-describing: the former `eventTypes` array became labelled `events`
-// plus the automation-editor vocabulary the provider owns. That is intentionally breaking — a 1.x listener
+// plus the automation-editor vocabulary the provider owns. That is intentionally breaking, a 1.x listener
 // manifest cannot honestly promise that a generic host can configure it.
 // 2.1.0 adds the backend half: a manifest `server` bundle (activateServer, run by the daemon's backend host
-// under /x/<id>/…) and `permissions.daemon` beside `permissions.sandbox`. Additive — a 2.0 manifest is a 2.1
+// under /x/<id>/…) and `permissions.daemon` beside `permissions.sandbox`. Additive, a 2.0 manifest is a 2.1
 // manifest that ships no backend.
 // 2.2.0 opens the automation composer: `contributes.automationTemplates` lets a pack ship the starting points
 // for its own service, and a `listener` may declare a second narrowing field (`automation.branchField`) for a
 // source whose events carry one. Both fold into the daemon's trigger catalogue, so a pack that knows something
 // worth waking on says so itself instead of being written into the automations surface. Additive.
-// 2.3.0 adds `api.sandbox.role()` — the signed-in user's trust tier, for affordance gating (the daemon floors
+// 2.3.0 adds `api.sandbox.role()`, the signed-in user's trust tier, for affordance gating (the daemon floors
 // every route regardless). Surfaced when the drafts queue moved out of the app: approve/reject are
 // maintainer-and-up, and no extension could say so. Additive. The surface guard grew a `sandboxApi` member
 // list with this release, so additions below the top-level grain are recorded from here on.
 // 2.4.0 gives the manifest an authoring schema: `$schema` is a declared field, and every contribution point now
 // carries the sentence that explains it, generated out to intentic-extension.schema.json. An editor pointed at
-// that URL completes the fields, shows what each one does, and marks a key nothing declares — which used to be
+// that URL completes the fields, shows what each one does, and marks a key nothing declares, which used to be
 // the one class of mistake nothing caught, because zod strips what it does not know rather than refusing it.
 // Additive: a manifest that names no schema is unchanged.
 // 2.5.0 lets an extension bring its own picture: `art` carries a complete SVG document inline, above the
 // simple-icons `logo` and the host's `icon` in the same ladder. The two tiers before it could say "this is
-// Slack" or "this is a server", and nothing could say "this is mine" — so a page listing seven unfamiliar
+// Slack" or "this is a server", and nothing could say "this is mine", so a page listing seven unfamiliar
 // extensions drew seven near-identical glyphs, which is the shape of a directory rather than of a shelf. Inline
 // rather than a URL because the row is drawn before any code is cloned: a link would put a stranger's server in
-// the render path, track who is browsing, and rot after approval. Additive — a manifest that ships no drawing
+// the render path, track who is browsing, and rot after approval. Additive, a manifest that ships no drawing
 // falls to exactly the mark it had before.
 // 2.6.0 gives module state an owner across a sandbox switch: `sandboxRef` declares state that belongs to ONE
 // sandbox and `sandboxScopeGuard` protects the write of a read that was already in flight when the switch
-// happened (scope.ts). The tier existed and nothing cleared it — every extension that badges a rail tile from a
+// happened (scope.ts). The tier existed and nothing cleared it, every extension that badges a rail tile from a
 // timer kept the previous sandbox's count under the new sandbox's name, which is the one thing a badge must
 // never do. Additive: an extension that keeps no module state is unchanged, and the host resets the scope
 // whether or not anything registered.
 // 2.7.0 adds the two halves of work an extension does while none of it is on screen (background.ts):
 // `sandboxPoll`, the timer behind a rail badge, and `sandboxLedger`, the file recording what the owner has
-// already seen. Seven modules across six extensions had hand-written the same poller — five invisible rules
-// each, and six of the seven had the sandbox-switch one wrong — and three had hand-written the same tolerant
+// already seen. Seven modules across six extensions had hand-written the same poller, five invisible rules
+// each, and six of the seven had the sandbox-switch one wrong, and three had hand-written the same tolerant
 // reader and careful write over the same shape of file. Additive: nothing is removed, and an extension that
 // keeps polling by hand still runs.
 // 2.8.0 splits sandbox-scoped module state by AUDIENCE: `sandboxValue` is `sandboxRef`'s lifetime without its
 // reactivity, for what a background poll remembers for itself (which connections to ask about next round, the
 // cursor a fetch resumes from) rather than what a tile shows. `detect()` and `badge()` both run inside the
-// host's render computed, so a `Ref` written from either is a computed mutating its own dependency — Vue
+// host's render computed, so a `Ref` written from either is a computed mutating its own dependency. Vue
 // re-runs it, it writes again, and the rail recurses until the flush is abandoned mid-frame, dropping every
 // unrelated update queued behind it. The symptom is a window that stops answering, blamed on whichever
 // component the loop was noticed in, so the fix has to be a box nothing observes rather than a rule to
 // remember. Additive: `sandboxRef` is unchanged, and both are emptied on a switch by the same door.
-export const extensionApiVersion = "2.8.0";
+// 2.9.0 adds `api.href` — the same app path the host would navigate to, as a browser address. A view that can
+// only call `navigate` has to draw every destination it offers as a <button>, and a button is not a link: no
+// address under the pointer, nothing in the browser's own right-click menu, nothing to copy, and Ctrl/⌘-click
+// moving the tab the reader is in instead of opening a second one. Six views across three packs had each drawn
+// a place that way, so the fix has to be reachable from the API rather than repeated per pack. Additive:
+// `navigate` is unchanged, and it is still what a plain click calls.
+export const extensionApiVersion = "2.9.0";