@sigrun/tui 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.10.1] - 2026-11-06
+
+- Version-locked bump with the 0.10.1 core line (no changes).
+
+## [0.10.0] - 2026-11-06
+
+- Extension views render in the main pane (mount, key routing, overlay-aware Esc
+  back-to-list/close, dispose) with block navigation (`SurfaceState.onNavigate`), notice
+  flashes on the status bar, and the ext-transport URL fix (suffix routes after `?params=`).
+
 ## [0.9.0] - 2026-11-05
 
 - Decline on declinable interaction cards (`alt+s` in answer mode; `alt+d` is the

package/dist/blocks/ext-transport.d.ts

@@ -2,8 +2,8 @@
  * The TUI's extension-surface transport (UI-blocks U3 Task 5): implements
  * the shared `SurfaceTransport` contract over the U3 routes (spec §7.2)
  * as the TUI's remote client. One transport = one surface instance
- * (slug + id + params); the wire `k` (hashed instance key) keys the
- * change-event routing in {@link ExtSurfaceHub}.
+ * (slug + id + params); the hub routes change events by (slug, id) —
+ * the wire `k` is not matched (see ExtSurfaceHub).
  *
  * Like the webui twin, every fetch carries `X-Sigrun-Stream` once the
  * launcher hands the stream id in (the watcher entry's stream);
@@ -52,14 +52,22 @@ export declare function createExtSurfaceTransport(options: ExtSurfaceTransportOp
 /**
  * The change-event router (the launcher's dispatch seam): `attach`
  * creates a transport whose `onChanged` subscribes into the hub under
- * the instance's (slug, id, k); `dispatch` fans a `surface.changed`
- * event out to the matching subscriptions only.
+ * the instance's (slug, id); `dispatch` fans a `surface.changed` event
+ * out to every subscription of the event's view. The event's `k` is NOT
+ * matched: the server hashes the principal-scoped instance key (jobs /
+ * skills / curator fold the user in), which no client hash can
+ * reproduce. The server already targets the event at the streams
+ * watching that exact instance (watchers.streamsFor), so matching the
+ * view is safe; a second instance of the same view refetches once.
  */
 export declare class ExtSurfaceHub {
     #private;
-    /** Create a transport whose `onChanged` subscribes into this hub. */
-    attach(options: ExtSurfaceTransportOptions, keyHash: string): ExtSurfaceTransportHandle;
-    /** Fire every subscription matching the event's (slug, id, k). */
+    /** Create a transport whose `onChanged` subscribes into this hub. The
+     *  `keyHash` argument is retained for call-site compatibility (dispatch
+     *  no longer routes on it — see the class doc). */
+    attach(options: ExtSurfaceTransportOptions, _keyHash: string): ExtSurfaceTransportHandle;
+    /** Fire every subscription of the event's (slug, id), whatever the
+     *  event's `k`. */
     dispatch(event: {
         readonly slug: string;
         readonly id: string;

package/dist/blocks/ext-transport.js

@@ -2,8 +2,8 @@
  * The TUI's extension-surface transport (UI-blocks U3 Task 5): implements
  * the shared `SurfaceTransport` contract over the U3 routes (spec §7.2)
  * as the TUI's remote client. One transport = one surface instance
- * (slug + id + params); the wire `k` (hashed instance key) keys the
- * change-event routing in {@link ExtSurfaceHub}.
+ * (slug + id + params); the hub routes change events by (slug, id) —
+ * the wire `k` is not matched (see ExtSurfaceHub).
  *
  * Like the webui twin, every fetch carries `X-Sigrun-Stream` once the
  * launcher hands the stream id in (the watcher entry's stream);
@@ -28,13 +28,24 @@ export function surfaceKeyHash(slug, id, key) {
 export function transportKey(options) {
     return instanceKey(options.params ?? {});
 }
+/** The surface path WITHOUT any query — suffix routes (/data, /actions,
+ *  /uploads) build from this and add their own query last (appending a
+ *  suffix after `?params=` would land after the query string — the
+ *  webui's E8 find, now the TUI's fetchData fix). */
+function surfaceBase(options) {
+    return `/v1/ext/${encodeURIComponent(options.slug)}/surfaces/${encodeURIComponent(options.id)}`;
+}
+/** The URL-encoded params JSON. */
+function paramsQuery(options) {
+    return encodeURIComponent(JSON.stringify(options.params ?? {}));
+}
 /** The base path for one surface instance (`?params=` omitted when `{}`). */
 function surfacePath(options) {
-    const base = `/v1/ext/${encodeURIComponent(options.slug)}/surfaces/${encodeURIComponent(options.id)}`;
+    const base = surfaceBase(options);
     if (options.params === undefined || Object.keys(options.params).length === 0) {
         return base;
     }
-    return `${base}?params=${encodeURIComponent(JSON.stringify(options.params))}`;
+    return `${base}?params=${paramsQuery(options)}`;
 }
 function withQuery(path, key, value) {
     return `${path}${path.includes("?") ? "&" : "?"}${key}=${value}`;
@@ -75,11 +86,11 @@ export function createExtSurfaceTransport(options) {
             return get(surfacePath(options));
         },
         fetchData(since) {
-            const path = `${surfacePath(options)}/data`;
+            const path = `${surfaceBase(options)}/data?params=${paramsQuery(options)}`;
             return get(since === undefined ? path : withQuery(path, "since", String(since)));
         },
         async act(body) {
-            const response = await doFetch(`${baseUrl}${surfacePath(options)}/actions`, {
+            const response = await doFetch(`${baseUrl}${surfaceBase(options)}/actions`, {
                 method: "POST",
                 headers: { ...headers(), "content-type": "application/json" },
                 body: JSON.stringify({ ...body, params: options.params ?? {} }),
@@ -87,7 +98,7 @@ export function createExtSurfaceTransport(options) {
             return (await response.json());
         },
         async upload(body) {
-            const base = surfacePath(options);
+            const base = surfaceBase(options);
             const path = withQuery(`${baseUrl}${base}/uploads/${encodeURIComponent(body.field)}/${encodeURIComponent(body.name)}`, "params", encodeURIComponent(JSON.stringify(options.params ?? {})));
             const response = await doFetch(path, {
                 method: "PUT",
@@ -119,13 +130,20 @@ export function createExtSurfaceTransport(options) {
 /**
  * The change-event router (the launcher's dispatch seam): `attach`
  * creates a transport whose `onChanged` subscribes into the hub under
- * the instance's (slug, id, k); `dispatch` fans a `surface.changed`
- * event out to the matching subscriptions only.
+ * the instance's (slug, id); `dispatch` fans a `surface.changed` event
+ * out to every subscription of the event's view. The event's `k` is NOT
+ * matched: the server hashes the principal-scoped instance key (jobs /
+ * skills / curator fold the user in), which no client hash can
+ * reproduce. The server already targets the event at the streams
+ * watching that exact instance (watchers.streamsFor), so matching the
+ * view is safe; a second instance of the same view refetches once.
  */
 export class ExtSurfaceHub {
     #subscriptions = new Set();
-    /** Create a transport whose `onChanged` subscribes into this hub. */
-    attach(options, keyHash) {
+    /** Create a transport whose `onChanged` subscribes into this hub. The
+     *  `keyHash` argument is retained for call-site compatibility (dispatch
+     *  no longer routes on it — see the class doc). */
+    attach(options, _keyHash) {
         const base = createExtSurfaceTransport(options);
         const hub = this;
         const transport = {
@@ -138,7 +156,6 @@ export class ExtSurfaceHub {
                 const subscription = {
                     slug: options.slug,
                     id: options.id,
-                    keyHash,
                     listener,
                 };
                 hub.#subscriptions.add(subscription);
@@ -152,12 +169,12 @@ export class ExtSurfaceHub {
             setStreamId: (next) => base.setStreamId(next),
         };
     }
-    /** Fire every subscription matching the event's (slug, id, k). */
+    /** Fire every subscription of the event's (slug, id), whatever the
+     *  event's `k`. */
     dispatch(event) {
         for (const subscription of this.#subscriptions) {
             if (subscription.slug === event.slug &&
-                subscription.id === event.id &&
-                subscription.keyHash === event.k) {
+                subscription.id === event.id) {
                 subscription.listener({ rev: event.rev, treeRev: event.treeRev });
             }
         }

package/dist/blocks/surface.d.ts

@@ -27,7 +27,7 @@
  * identical to U1 (a move against an unknown handler still goes to the
  * transport, unoverlaid).
  */
-import type { Action, JsonObject, JsonValue, SurfaceTransport, Tree } from "@sigrun/shared/blocks";
+import type { Action, CoreTarget, JsonObject, JsonValue, SurfaceTransport, Tree } from "@sigrun/shared/blocks";
 /** An action has 10 s to answer before it counts as a reject (§6.3). */
 export declare const ACT_TIMEOUT_MS = 10000;
 /** The notice cap: pending notices drop oldest-first past 50 (a flood
@@ -49,6 +49,14 @@ export interface SurfaceView {
 /** The surface state container (class shape — the TUI has no hook layer). */
 export declare class SurfaceState {
     #private;
+    /** The shell's navigate sink (jobs-editor Task 7): navigate actions
+     *  and accepted results' `navigate` route here — shell-local, never
+     *  posted (spec §6.1; the webui's useSurface.onNavigate). */
+    onNavigate: ((action: {
+        type: "navigate";
+        params?: JsonObject;
+        target?: CoreTarget;
+    }) => void) | undefined;
     constructor(transport: SurfaceTransport);
     /** The current snapshot: confirmed data with the overlay applied. */
     get view(): SurfaceView;
@@ -75,6 +83,8 @@ export declare class SurfaceState {
     load(): Promise<void>;
     /** Stop listening and cancel every pending action timer. */
     dispose(): void;
-    /** Dispatch an action to the surface; a move joins the overlay first. */
+    /** Dispatch an action to the surface; a move joins the overlay first.
+     *  A navigate action is SHELL-LOCAL: it routes through `onNavigate`
+     *  and never reaches the transport (spec §6.1). */
     dispatch(action: Action, payload: JsonValue): void;
 }

package/dist/blocks/surface.js

@@ -190,6 +190,10 @@ export class SurfaceState {
      *  never reaches the transport. */
     #viewBranch = {};
     #actionSeq = 0;
+    /** The shell's navigate sink (jobs-editor Task 7): navigate actions
+     *  and accepted results' `navigate` route here — shell-local, never
+     *  posted (spec §6.1; the webui's useSurface.onNavigate). */
+    onNavigate;
     /** The highest rev a change event announced (gap detect). */
     #announcedRev = 0;
     #timers = new Map();
@@ -403,8 +407,14 @@ export class SurfaceState {
             // event or keepalive retries (§7.3).
         }
     }
-    /** Dispatch an action to the surface; a move joins the overlay first. */
+    /** Dispatch an action to the surface; a move joins the overlay first.
+     *  A navigate action is SHELL-LOCAL: it routes through `onNavigate`
+     *  and never reaches the transport (spec §6.1). */
     dispatch(action, payload) {
+        if (action.type === "navigate") {
+            this.onNavigate?.(action);
+            return;
+        }
         const payloadObject = typeof payload === "object" && payload !== null && !Array.isArray(payload)
             ? payload
             : {};
@@ -451,8 +461,17 @@ export class SurfaceState {
                 return;
             }
             this.#serverErrors = {};
-            if (result.toast !== undefined)
-                this.#notice(result.toast);
+            // An accepted act's `navigate` routes through the shell LAST
+            // (jobs-editor Task 7, plan-review P2): after the toast and
+            // after the non-move refetch is kicked off — the app's
+            // handler may dispose this state.
+            const finishAccept = () => {
+                if (result.toast !== undefined)
+                    this.#notice(result.toast);
+                if (result.navigate?.type === "navigate") {
+                    this.onNavigate?.(result.navigate);
+                }
+            };
             if (!isMove) {
                 // A non-move accept (the settings save): the rev already
                 // bumped server-side (the optimistic check needs the form's
@@ -462,6 +481,7 @@ export class SurfaceState {
                 // surface.changed hub — the app owns the probe).
                 this.#rev = result.rev;
                 void this.#fullRefetch();
+                finishAccept();
                 return;
             }
             if (result.ops !== undefined) {
@@ -471,6 +491,7 @@ export class SurfaceState {
                 catch (error) {
                     if (error instanceof DataOpError) {
                         void this.#fullRefetch();
+                        finishAccept();
                         return;
                     }
                     throw error;
@@ -483,6 +504,7 @@ export class SurfaceState {
                 }
                 this.#overlay = this.#overlay.filter((entry) => entry.actionId !== actionId);
                 this.#emit();
+                finishAccept();
             }
             else {
                 // Accept without ops: hold the entry until confirmed reaches
@@ -495,6 +517,7 @@ export class SurfaceState {
                 this.#rev = Math.max(this.#rev, result.rev);
                 this.#overlay = this.#overlay.map((entry) => entry.actionId === actionId ? { ...entry, untilRev: result.rev } : entry);
                 this.#emit();
+                finishAccept();
             }
         })
             .catch(() => {

package/dist/ui/app.d.ts

@@ -49,6 +49,7 @@
 import { Editor, type Component, type TUI } from "@earendil-works/pi-tui";
 import type { SigrunClient } from "../api.js";
 import type { CoreTarget, JsonObject } from "@sigrun/shared/blocks";
+import { SurfaceState } from "../blocks/surface.js";
 import { type Unwatch, type WatchHandlers, type WatchOptions } from "../sse.js";
 import { type TuiTheme } from "../theme.js";
 import type { Action, ActionHost, Focus } from "../actions.js";
@@ -150,7 +151,10 @@ export declare class TuiApp implements Component, ActionHost {
     get extView(): {
         readonly slug: string;
         readonly id: string;
+        readonly params: JsonObject;
     } | undefined;
+    /** The open view's surface state (tests + Task 7's navigation). */
+    get extViewState(): SurfaceState | undefined;
     /**
      * Open an extension VIEW in the main pane (U3 Task 5, spec §7.1):
      * the sidebar's view selection swaps the pane's content to the

package/dist/ui/app.js

@@ -50,6 +50,8 @@ import { Editor, HStack, Key, matchesKey, VStack, } from "@earendil-works/pi-tui
 import { SigrunApiError } from "../api.js";
 import { ExtSurfaceHub, surfaceKeyHash, transportKey, } from "../blocks/ext-transport.js";
 import { ChatSurfaceHub } from "../blocks/chat-transport.js";
+import { SurfaceState } from "../blocks/surface.js";
+import { SurfaceView } from "../blocks/surface-view.js";
 import { watchConversation } from "../sse.js";
 import { spawnSync } from "node:child_process";
 import { plainTuiTheme } from "../theme.js";
@@ -306,7 +308,15 @@ export class TuiApp {
     get extView() {
         return this.#extView === undefined
             ? undefined
-            : { slug: this.#extView.slug, id: this.#extView.id };
+            : {
+                slug: this.#extView.slug,
+                id: this.#extView.id,
+                params: this.#extView.params,
+            };
+    }
+    /** The open view's surface state (tests + Task 7's navigation). */
+    get extViewState() {
+        return this.#extView?.state;
     }
     /**
      * Open an extension VIEW in the main pane (U3 Task 5, spec §7.1):
@@ -315,11 +325,12 @@ export class TuiApp {
      * the transport + identity here so U2's mount is one prop pass.
      */
     async openExtView(slug, id, params) {
-        const key = transportKey({ slug, id, baseUrl: this.#watchOptions.baseUrl, ...(params === undefined ? {} : { params }) });
+        const instanceParams = params ?? {};
+        const key = transportKey({ slug, id, baseUrl: this.#watchOptions.baseUrl, params: instanceParams });
         const handle = this.#extHub.attach({
             slug,
             id,
-            ...(params === undefined ? {} : { params }),
+            params: instanceParams,
             baseUrl: this.#watchOptions.baseUrl,
             ...(this.#watchOptions.user === undefined
                 ? {}
@@ -330,8 +341,44 @@ export class TuiApp {
             ...(this.#eventsStreamId === undefined
                 ? {}
                 : { streamId: this.#eventsStreamId }),
+            // A test-injected client fetch carries the view's loads (the
+            // settings view's shape; production's client leaves it ambient).
+            ...(this.#client.fetch === undefined
+                ? {}
+                : { fetch: this.#client.fetch }),
         }, surfaceKeyHash(slug, id, key));
-        this.#extView = { slug, id, handle };
+        // A swap disposes the previous view's state BEFORE the new one
+        // opens (the settings view's openSection shape): no orphaned
+        // subscriptions or action timers survive a re-open.
+        this.#extView?.state.dispose();
+        const state = new SurfaceState(handle.transport);
+        // Navigation wiring (jobs-editor Task 7): a navigate action or an
+        // accepted result's `navigate` reopens THIS view with the params
+        // (params-only) or routes a core target through the shell — never
+        // posted to the server (SurfaceState.dispatch short-circuits it).
+        state.onNavigate = (nav) => nav.target !== undefined
+            ? void this.navigateCoreTarget(nav.target)
+            : void this.openExtView(slug, id, nav.params ?? {});
+        const view = new SurfaceView(state, {
+            theme: this.#theme,
+            unicode: this.#unicode,
+        });
+        state.onChange(() => {
+            // The surface's notices (action toasts, rejections) land as
+            // pane notices (the post-close backlog) AND flash the status
+            // bar while mounted — the pane is not painted while this view
+            // owns the main slot, so the flash is the visible channel
+            // (SurfaceState's contract names the status bar as the host
+            // notice seam).
+            for (const notice of state.consumeNotices()) {
+                this.pane.showNotice(notice);
+                this.#flashStatus(notice);
+            }
+            this.#tui.requestRender();
+        });
+        this.#extView = { slug, id, params: instanceParams, handle, state, view };
+        this.mainContent.set(view);
+        void state.load();
         this.#tui.requestRender();
     }
     /**
@@ -388,7 +435,9 @@ export class TuiApp {
     closeExtView() {
         if (this.#extView === undefined)
             return false;
+        this.#extView.state.dispose();
         this.#extView = undefined;
+        this.mainContent.set(this.pane);
         this.#tui.requestRender();
         return true;
     }
@@ -725,11 +774,28 @@ export class TuiApp {
             this.#abortActive();
             return true;
         }
-        // Esc closes an open extension view — back to the
-        // conversation pane; the surface's fetches stop (the keepalive
-        // stops with the view, spec §7.3's stop-when-hidden).
-        if (matchesKey(data, Key.escape) && this.#extView !== undefined) {
-            return this.closeExtView();
+        // The open extension view owns its keys (Task 6): Esc forwards to
+        // the view while its page has an overlay (actions menu, sidebar
+        // drawer, pushed detail — spec §12.3's page contract); otherwise
+        // Esc with params reopens the view at the list (`{}`), and Esc at
+        // the list closes the view. Non-Esc keys route to the view.
+        if (this.#extView !== undefined) {
+            if (matchesKey(data, Key.escape)) {
+                const inner = this.#extView.view.inner;
+                if (inner?.hasOverlay === true) {
+                    this.#extView.view.handleInput(data);
+                    return true;
+                }
+                if (Object.keys(this.#extView.params).length > 0) {
+                    void this.openExtView(this.#extView.slug, this.#extView.id, {}).catch((error) => {
+                        this.pane.showError(describeCommandError("open view", error));
+                    });
+                    return true;
+                }
+                return this.closeExtView();
+            }
+            this.#extView.view.handleInput(data);
+            return true;
         }
         return false;
     }
@@ -970,6 +1036,8 @@ export class TuiApp {
         this.#restartGeneration += 1;
         this.interactions.dispose();
         this.ambient.dispose();
+        this.#extView?.state.dispose();
+        this.#extView = undefined;
         // The pane's chat-block surface states hold live hub subscriptions
         // + action timers — the shell owns their teardown (the pane never
         // leaves a subscription behind).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/tui",
-	"version": "0.9.0",
+	"version": "0.10.1",
 	"description": "sigrun terminal client (pi-tui based) over the \u00a75 API \u2014 spawned by the sigrun CLI, or standalone against a server URL",
 	"type": "module",
 	"bin": {
@@ -21,7 +21,7 @@
 	},
 	"dependencies": {
 		"@earendil-works/pi-tui": "^1.3.0",
-		"@sigrun/shared": "0.9.0"
+		"@sigrun/shared": "0.10.1"
 	},
 	"devDependencies": {
 		"typescript": "^7.0.2",