@sigrun/shared 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-24
+### Added
+- Extension-surface wire types, including block-instance and live-view
+  contracts shared by the server, webui, and TUI.
+
+## [0.1.1] - 2026-10-23
+### Added
+- `./live` and `./blocks` export subpaths.
+
 ## [0.1.0] - 2026-10-21
 ### Added
 - First published release of the shared leaf (workspace package of

package/dist/blocks/index.d.ts

@@ -17,6 +17,7 @@ export { ICON_NAMES } from "./icons.js";
 export { lttb } from "./lttb.js";
 export { formatValue } from "./format.js";
 export { toText } from "./text.js";
+export { canonicalJson, eventKeyWeb, instanceKey } from "./instance.js";
 export type { Action, ActionButton, Bindable, Binding, Block, BlockBase, BulkAction, CalloutBlock, Card, CardBadge, CardMetric, CardMeta, CardStatus, ChartAxisX, ChartAxisY, ChartBlock, ChartSeries, ChartThreshold, ChoiceField, ChoiceOption, CollectionBlock, CollectionColumn, CollectionGroup, CollectionSort, CollectionTime, ColumnChild, ColumnsBlock, Confirm, CoreTarget, DataOp, DataOps, DataUpdate, DateField, DatePreset, DaterangeField, DatetimeField, DetailsBlock, DiffBlock, Field, FieldBase, FieldsBlock, FieldsRow, FileField, Format, FormBlock, GridBlock, GridChild, ImageBlock, ListField, LogBlock, LogLine, LongtextField, MarkdownBlock, MeterBlock, MeterThreshold, NumberField, PageBlock, PageEmpty, Placement, SectionBlock, SecretField, Size, StackBlock, StatBlock, TextField, ToggleField, Tone, Tree, TreeBlock, TreeNode, WidthCondition, } from "./types.js";
 export type { IconName } from "./icons.js";
 export type { TextOptions } from "./text.js";

package/dist/blocks/index.js

@@ -18,3 +18,4 @@ export { ICON_NAMES } from "./icons.js";
 export { lttb } from "./lttb.js";
 export { formatValue } from "./format.js";
 export { toText } from "./text.js";
+export { canonicalJson, eventKeyWeb, instanceKey } from "./instance.js";

package/dist/blocks/instance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The instance-key helpers the CHANNELS need (UI-blocks U3 Task 5, spec
+ * §7.3): `canonicalJson` (the default `instanceKey`) and
+ * `eventKeyWeb`/`eventKeyNode` (the wire `k` — sha256 hex of
+ * `slug\0id\0key`). The server's copy lives in
+ * `src/server/surfaces/instance.ts`; these are the DOM- and Node-safe
+ * twins (WebCrypto's `crypto.subtle.digest` vs `node:crypto`), kept
+ * byte-compatible by the shared canonical-JSON rule.
+ *
+ * The wire's purity rule holds: NO node: imports here — the Node flavor
+ * is a separate module (`instance-node.ts`) so the webui never sees it.
+ */
+import type { JsonObject, JsonValue } from "../json.js";
+/**
+ * Canonical JSON: every object serializes with keys SORTED (recursive);
+ * primitives and arrays serialize as usual. Two params objects equal up
+ * to key order produce byte-identical strings — the same rule as the
+ * server's `canonicalJson` (kept in sync by hand; both sides pin it by
+ * test).
+ */
+export declare function canonicalJson(value: JsonValue): string;
+/** The default instance key (spec §7.3): canonical JSON of the params. */
+export declare function instanceKey(params: JsonObject): string;
+/**
+ * The wire `k` for one surface instance (spec §7.3), WebCrypto flavor:
+ * `sha256(slug + "\0" + id + "\0" + key)` hex. Async (the DOM digest is
+ * promise-shaped); the Node twin (`instance-node.ts`) is sync.
+ */
+export declare function eventKeyWeb(slug: string, id: string, key: string): Promise<string>;

package/dist/blocks/instance.js

@@ -0,0 +1,51 @@
+/**
+ * The instance-key helpers the CHANNELS need (UI-blocks U3 Task 5, spec
+ * §7.3): `canonicalJson` (the default `instanceKey`) and
+ * `eventKeyWeb`/`eventKeyNode` (the wire `k` — sha256 hex of
+ * `slug\0id\0key`). The server's copy lives in
+ * `src/server/surfaces/instance.ts`; these are the DOM- and Node-safe
+ * twins (WebCrypto's `crypto.subtle.digest` vs `node:crypto`), kept
+ * byte-compatible by the shared canonical-JSON rule.
+ *
+ * The wire's purity rule holds: NO node: imports here — the Node flavor
+ * is a separate module (`instance-node.ts`) so the webui never sees it.
+ */
+/**
+ * Canonical JSON: every object serializes with keys SORTED (recursive);
+ * primitives and arrays serialize as usual. Two params objects equal up
+ * to key order produce byte-identical strings — the same rule as the
+ * server's `canonicalJson` (kept in sync by hand; both sides pin it by
+ * test).
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const keys = Object.keys(value).sort();
+        const parts = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+        return `{${parts.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** The default instance key (spec §7.3): canonical JSON of the params. */
+export function instanceKey(params) {
+    return canonicalJson(params);
+}
+/** The hex encoding of a sha256 digest buffer. */
+function hex(buffer) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}
+/**
+ * The wire `k` for one surface instance (spec §7.3), WebCrypto flavor:
+ * `sha256(slug + "\0" + id + "\0" + key)` hex. Async (the DOM digest is
+ * promise-shaped); the Node twin (`instance-node.ts`) is sync.
+ */
+export async function eventKeyWeb(slug, id, key) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode([slug, id, key].join("\u0000")));
+    return hex(digest);
+}

package/dist/views.d.ts

@@ -402,6 +402,14 @@ export interface MetaResponse {
          * worker's first run.
          */
         readonly workers?: readonly WorkerStatus[];
+        /**
+         * The declared surfaces (UI-blocks U3 Task 5): the flattened
+         * view + panel rows the channels register their rail/panel
+         * entries from. Absent when the extension declared none. The
+         * meta response carries the DECLARATION (id/title/icon/
+         * placement); access filtering is render-time (§6.5).
+         */
+        readonly surfaces?: readonly ExtensionSurfaceInfo[];
     }[];
     /**
      * §5 health: pure aggregation over boot-retained §3 producers (spec
@@ -589,6 +597,8 @@ export interface ExtensionInfo {
     readonly workers: readonly WorkerStatus[];
     /** The declared HTTP routes, one `{method, path, auth}` each (W5 Task 2). */
     routes?: readonly ExtensionRouteInfo[];
+    /** The declared surfaces, one `{id, title, icon, placement}` each (U3 Task 1); absent when none. */
+    surfaces?: readonly ExtensionSurfaceInfo[];
     /**
      * The channel ids this extension contributes (gateway C1, spec §7):
      * present only on rows of extensions whose factory result carried
@@ -622,6 +632,26 @@ export interface ExtensionRouteInfo {
     readonly path: string;
     readonly auth: string;
 }
+/**
+ * One `GET /v1/extensions` surface row (UI-blocks U3 Task 1, spec
+ * §7.1): the extension-declared views and panels — what the channels'
+ * rail (views) and right panel (panels) register from. One row per
+ * declared surface, in declaration order (views before panels).
+ */
+export interface ExtensionSurfaceInfo {
+    readonly id: string;
+    readonly title: string;
+    readonly icon: string;
+    /** The declared placement; `settings` sections (§13.3) are not in this workstream. */
+    readonly placement: "view" | "panel";
+    /** The declared refresh cadence (spec §7.1); channels refetch data on
+     *  this interval while the surface is visible. Absent → no cadence. */
+    readonly refreshMs?: number;
+    /** §7.3 shared-data flag: a sharedData surface's `since` fetches may
+     *  answer with `ops` and NO `data` — channels fall back to a full
+     *  fetch (ops folding is U1). Absent → per-instance data. */
+    readonly sharedData?: boolean;
+}
 /** The `GET /v1/extensions` payload (spec §7.7). */
 export interface ExtensionsResponse {
     readonly extensions: readonly ExtensionInfo[];
@@ -781,4 +811,12 @@ export type HostEventWire = {
     /** W4 Task 4 (§8.4): the changed job's summary, WITHOUT `access` — the events stream computes `accessOf` per principal and adds it before delivery (a hidden job's event is withheld entirely). */
     readonly type: "job.changed";
     readonly job: Omit<JobWire, "access">;
+} | {
+    /** UI-blocks U3 Task 4 (spec §7.3): one surface instance changed. `k` is the hashed instance key (sha256(slug + "\0" + id + "\0" + key) hex) — the event NEVER carries params or data (render/data are principal-specific; the watcher refetches as itself). Delivered only to streams in the watcher registry whose stored access is not `"none"`. */
+    readonly type: "surface.changed";
+    readonly slug: string;
+    readonly id: string;
+    readonly k: string;
+    readonly rev: number;
+    readonly treeRev: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/shared",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "sigrun shared leaf package \u2014 theme tokens, turn/conversation shaping, and the channel wire types (pure leaf, zero dependencies)",
 	"type": "module",
 	"exports": {