@adminiumjs/widgets 0.1.0-rc.1

package/dist/binding/StreamTransportContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamTransportContext.d.ts","sourceRoot":"","sources":["../../src/binding/StreamTransportContext.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,4BAA4B,+BAE5F;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAE3D"}

package/dist/binding/StreamTransportContext.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React context carrying the app's realtime {@link StreamTransport} (04 §5.3).
+ * The host app (`apps/dashboard`) constructs the concrete WS/SSE transport once
+ * and provides it here; `useWidgetStream` reads it for bound stream widgets.
+ * Absent a provider, bound widgets stay disconnected (demo/unbound widgets
+ * build their own deterministic transport and never touch this context).
+ */
+import { createContext, useContext } from 'react';
+const StreamTransportContext = createContext(null);
+/** Provide the realtime stream transport to descendant stream widgets. */
+export function StreamTransportProvider({ transport, children }) {
+    return _jsx(StreamTransportContext.Provider, { value: transport, children: children });
+}
+/** The provided transport, or `null` when no provider is mounted. */
+export function useStreamTransport() {
+    return useContext(StreamTransportContext);
+}
+//# sourceMappingURL=StreamTransportContext.js.map

package/dist/binding/StreamTransportContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamTransportContext.js","sourceRoot":"","sources":["../../src/binding/StreamTransportContext.tsx"],"names":[],"mappings":";AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,OAAO,CAAC;AAIlE,MAAM,sBAAsB,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AAO3E,0EAA0E;AAC1E,MAAM,UAAU,uBAAuB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAgC;IAC3F,OAAO,KAAC,sBAAsB,CAAC,QAAQ,IAAC,KAAK,EAAE,SAAS,YAAG,QAAQ,GAAmC,CAAC;AACzG,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kBAAkB;IAChC,OAAO,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAC5C,CAAC"}

package/dist/binding/demo-stream.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic seeded demo stream (04-widget-registry.md §5.3 demo mode, §7.7
+ * determinism). Unbound stream widgets — Storybook, builder-palette previews,
+ * first-run empty states — drive the exact same buffer/hook pipeline from this
+ * generator instead of a live socket.
+ *
+ * `demoStreamRecords(seed, n)` is byte-identical across runs and platforms: the
+ * canonical mulberry32 PRNG (no `Date.now`/`Math.random`) picks from fixed
+ * template arrays, timestamps come from a fixed base plus an index step. The
+ * generated records intentionally match the `log-table`/`activity-feed` row
+ * shape so the demo transport can drive those shells directly.
+ */
+import type { StreamRealtimeEvent, StreamTransport } from './stream-types.js';
+/** A synthetic feed record (shape shared with `log-table` / `activity-feed`). */
+export interface DemoStreamRecord {
+    id: number;
+    ts: string;
+    actor: string;
+    category: string;
+    categoryTone: string;
+    action: string;
+    resource: string;
+    status?: string;
+    code?: number;
+}
+/** Fixed timeline anchor — never `Date.now()`, so runs are reproducible. */
+export declare const DEMO_STREAM_BASE_MS: number;
+/** Per-index timestamp step (newer indices are later in time). */
+export declare const DEMO_STREAM_STEP_MS = 3200;
+/** Deterministic channel name for demo/unbound stream widgets. */
+export declare const DEMO_STREAM_CHANNEL = "widget-data:demo:demo.events";
+/** One deterministic record for `(seed, index)`. Stable across runs. */
+export declare function demoStreamRecord(seed: number, index: number): DemoStreamRecord;
+/**
+ * `count` deterministic records. `order: 'desc'` (default) returns them
+ * newest-first (matching a server snapshot); `'asc'` returns oldest-first
+ * (the order the demo transport emits them live).
+ */
+export declare function demoStreamRecords(seed: number, count: number, order?: 'asc' | 'desc'): DemoStreamRecord[];
+/** Wrap a demo record as a `record.create` realtime event. */
+export declare function demoStreamEvent(channel: string, record: DemoStreamRecord): StreamRealtimeEvent;
+export interface DemoStreamTransportOptions {
+    seed: number;
+    /** Emit cadence in ms; default 3200. */
+    intervalMs?: number | undefined;
+    /** Index the live emission starts from (past this, records are "new"). */
+    startIndex?: number | undefined;
+    /** Timer seams for deterministic tests; default the globals. */
+    setInterval?: ((cb: () => void, ms: number) => unknown) | undefined;
+    clearInterval?: ((handle: unknown) => void) | undefined;
+}
+/**
+ * A {@link StreamTransport} that emits the deterministic demo stream on an
+ * interval. Reports `connected: true` immediately. Multiple subscribers on the
+ * same demo channel each get their own independent emission cursor, so a story
+ * with several demo feeds stays reproducible per-widget.
+ */
+export declare function createDemoStreamTransport(opts: DemoStreamTransportOptions): StreamTransport;
+//# sourceMappingURL=demo-stream.d.ts.map

package/dist/binding/demo-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-stream.d.ts","sourceRoot":"","sources":["../../src/binding/demo-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAkB,mBAAmB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAc9F,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAaD,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,QAAmC,CAAC;AACpE,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAElE,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,KAAK,GAAG,MAAe,GAC7B,gBAAgB,EAAE,CAGpB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CAE9F;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gEAAgE;IAChE,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IACpE,aAAa,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,0BAA0B,GAAG,eAAe,CAoB3F"}

package/dist/binding/demo-stream.js

@@ -0,0 +1,90 @@
+/**
+ * Deterministic seeded demo stream (04-widget-registry.md §5.3 demo mode, §7.7
+ * determinism). Unbound stream widgets — Storybook, builder-palette previews,
+ * first-run empty states — drive the exact same buffer/hook pipeline from this
+ * generator instead of a live socket.
+ *
+ * `demoStreamRecords(seed, n)` is byte-identical across runs and platforms: the
+ * canonical mulberry32 PRNG (no `Date.now`/`Math.random`) picks from fixed
+ * template arrays, timestamps come from a fixed base plus an index step. The
+ * generated records intentionally match the `log-table`/`activity-feed` row
+ * shape so the demo transport can drive those shells directly.
+ */
+/** Mulberry32 — canonical form (matches `@adminium/charts`); deterministic. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const DEMO_TEMPLATES = [
+    { category: 'auth', categoryTone: 'info', action: 'signed in', resource: 'session/9f2a', status: 'success' },
+    { category: 'billing', categoryTone: 'warn', action: 'charge failed for', resource: 'sub_4821', code: 402 },
+    { category: 'api', categoryTone: 'neutral', action: 'POST', resource: '/v1/orders', code: 201 },
+    { category: 'webhook', categoryTone: 'accent', action: 'delivered', resource: 'order.paid', code: 200 },
+    { category: 'api', categoryTone: 'neutral', action: 'GET', resource: '/v1/reports', code: 500 },
+    { category: 'export', categoryTone: 'info', action: 'generated', resource: 'customers.csv', status: 'success' },
+];
+const DEMO_ACTORS = ['Ada Lovelace', 'System', 'api-gw', 'Grace Hopper', 'cron'];
+/** Fixed timeline anchor — never `Date.now()`, so runs are reproducible. */
+export const DEMO_STREAM_BASE_MS = Date.UTC(2026, 6, 14, 14, 30, 0);
+/** Per-index timestamp step (newer indices are later in time). */
+export const DEMO_STREAM_STEP_MS = 3_200;
+/** Deterministic channel name for demo/unbound stream widgets. */
+export const DEMO_STREAM_CHANNEL = 'widget-data:demo:demo.events';
+/** One deterministic record for `(seed, index)`. Stable across runs. */
+export function demoStreamRecord(seed, index) {
+    const random = mulberry32(((seed >>> 0) ^ Math.imul(index + 1, 0x9e3779b1)) >>> 0);
+    const template = DEMO_TEMPLATES[Math.floor(random() * DEMO_TEMPLATES.length) % DEMO_TEMPLATES.length];
+    const actor = DEMO_ACTORS[Math.floor(random() * DEMO_ACTORS.length) % DEMO_ACTORS.length];
+    return {
+        id: index + 1,
+        ts: new Date(DEMO_STREAM_BASE_MS + index * DEMO_STREAM_STEP_MS).toISOString(),
+        actor,
+        ...template,
+    };
+}
+/**
+ * `count` deterministic records. `order: 'desc'` (default) returns them
+ * newest-first (matching a server snapshot); `'asc'` returns oldest-first
+ * (the order the demo transport emits them live).
+ */
+export function demoStreamRecords(seed, count, order = 'desc') {
+    const asc = Array.from({ length: Math.max(0, count) }, (_, index) => demoStreamRecord(seed, index));
+    return order === 'asc' ? asc : asc.reverse();
+}
+/** Wrap a demo record as a `record.create` realtime event. */
+export function demoStreamEvent(channel, record) {
+    return { channel, type: 'record.create', data: { type: 'record.create', row: record }, ts: record.ts };
+}
+/**
+ * A {@link StreamTransport} that emits the deterministic demo stream on an
+ * interval. Reports `connected: true` immediately. Multiple subscribers on the
+ * same demo channel each get their own independent emission cursor, so a story
+ * with several demo feeds stays reproducible per-widget.
+ */
+export function createDemoStreamTransport(opts) {
+    const intervalMs = opts.intervalMs ?? DEMO_STREAM_STEP_MS;
+    const start = opts.startIndex ?? 0;
+    const setTimer = opts.setInterval ?? ((cb, ms) => setInterval(cb, ms));
+    const clearTimer = opts.clearInterval ?? ((handle) => clearInterval(handle));
+    return {
+        subscribe(channel, listener, onStatus) {
+            onStatus?.(true);
+            let index = start;
+            const handle = setTimer(() => {
+                listener(demoStreamEvent(channel, demoStreamRecord(opts.seed, index)));
+                index += 1;
+            }, intervalMs);
+            return () => {
+                onStatus?.(false);
+                clearTimer(handle);
+            };
+        },
+    };
+}
+//# sourceMappingURL=demo-stream.js.map

package/dist/binding/demo-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-stream.js","sourceRoot":"","sources":["../../src/binding/demo-stream.ts"],"names":[],"mappings":"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"}

package/dist/binding/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@adminium/widgets/binding` — the `stream` data-binding layer (04-widget-registry.md
+ * §5.3): the transport contract + provider, the bounded newest-first buffer,
+ * the deterministic demo stream, channel naming, and the `useWidgetStream`
+ * hook. The host app injects a concrete WS/SSE transport; widgets consume the
+ * hook. Kept out of the React-free `@adminium/widgets/page-config` leaf.
+ */
+export type { StreamRealtimeEvent, StreamListener, StreamStatusListener, StreamTransport, StreamShape, StreamEventPayload, } from './stream-types.js';
+export { WIDGET_DATA_CHANNEL_PREFIX, qualifiedTableName, streamChannel, streamChannelForSource, type StreamSource, } from './stream-channel.js';
+export { DEFAULT_STREAM_MAX, seedStreamBuffer, upsertStreamItem, upsertStreamItems, removeStreamItem, markStreamRead, type StreamBufferState, type StreamUpsertOptions, } from './stream-buffer.js';
+export { DEMO_STREAM_BASE_MS, DEMO_STREAM_STEP_MS, DEMO_STREAM_CHANNEL, demoStreamRecord, demoStreamRecords, demoStreamEvent, createDemoStreamTransport, type DemoStreamRecord, type DemoStreamTransportOptions, } from './demo-stream.js';
+export { StreamTransportProvider, useStreamTransport, type StreamTransportProviderProps, } from './StreamTransportContext.js';
+export { useWidgetStream, type UseWidgetStreamOptions, type WidgetStream, } from './useWidgetStream.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/binding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/binding/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,yBAAyB,EACzB,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,4BAA4B,GAClC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,YAAY,GAClB,MAAM,sBAAsB,CAAC"}

package/dist/binding/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@adminium/widgets/binding` — the `stream` data-binding layer (04-widget-registry.md
+ * §5.3): the transport contract + provider, the bounded newest-first buffer,
+ * the deterministic demo stream, channel naming, and the `useWidgetStream`
+ * hook. The host app injects a concrete WS/SSE transport; widgets consume the
+ * hook. Kept out of the React-free `@adminium/widgets/page-config` leaf.
+ */
+export { WIDGET_DATA_CHANNEL_PREFIX, qualifiedTableName, streamChannel, streamChannelForSource, } from './stream-channel.js';
+export { DEFAULT_STREAM_MAX, seedStreamBuffer, upsertStreamItem, upsertStreamItems, removeStreamItem, markStreamRead, } from './stream-buffer.js';
+export { DEMO_STREAM_BASE_MS, DEMO_STREAM_STEP_MS, DEMO_STREAM_CHANNEL, demoStreamRecord, demoStreamRecords, demoStreamEvent, createDemoStreamTransport, } from './demo-stream.js';
+export { StreamTransportProvider, useStreamTransport, } from './StreamTransportContext.js';
+export { useWidgetStream, } from './useWidgetStream.js';
+//# sourceMappingURL=index.js.map

package/dist/binding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/binding/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,sBAAsB,GAEvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,GAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,yBAAyB,GAG1B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,GAEnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,eAAe,GAGhB,MAAM,sBAAsB,CAAC"}

package/dist/binding/stream-buffer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Bounded, newest-first stream buffer (04-widget-registry.md §5.3). Pure and
+ * immutable so the fold is unit-testable without a socket or the DOM:
+ *
+ * - `upsertStreamItem` prepends a new item (newest first) or replaces an
+ *   existing one in place — this makes optimistic prepends idempotent when the
+ *   server later echoes the same row (same key ⇒ replace, not duplicate);
+ * - the buffer is capped at `max` items; the oldest fall off the tail;
+ * - `unread` counts items added since the last `markStreamRead` (the
+ *   `unread-badge` source of truth); replacements and optimistic prepends do
+ *   not bump it.
+ */
+/** Default retained-item cap for a stream buffer. */
+export declare const DEFAULT_STREAM_MAX = 100;
+export interface StreamBufferState<T> {
+    /** Newest-first, length ≤ `max`. */
+    readonly items: readonly T[];
+    /** Items added since the last `markStreamRead`. */
+    readonly unread: number;
+}
+export interface StreamUpsertOptions<T> {
+    getKey: (item: T) => string | number;
+    /** Retained-item cap; default {@link DEFAULT_STREAM_MAX}. */
+    max?: number | undefined;
+    /** Count this insert toward `unread`; default `true`. Optimistic/self writes pass `false`. */
+    countUnread?: boolean | undefined;
+}
+/** Seed a buffer from an initial snapshot (already newest-first). `unread` = 0. */
+export declare function seedStreamBuffer<T>(snapshot?: readonly T[], max?: number): StreamBufferState<T>;
+/**
+ * Prepend `item` (newest first), or replace the existing item with the same key
+ * in place. A replacement keeps its position and never bumps `unread`.
+ */
+export declare function upsertStreamItem<T>(state: StreamBufferState<T>, item: T, opts: StreamUpsertOptions<T>): StreamBufferState<T>;
+/**
+ * Apply a batch of items in chronological order (oldest → newest); the newest
+ * ends up at index 0. Equivalent to folding `upsertStreamItem` left-to-right.
+ */
+export declare function upsertStreamItems<T>(state: StreamBufferState<T>, items: readonly T[], opts: StreamUpsertOptions<T>): StreamBufferState<T>;
+/** Drop the item with `key`, if present. Never changes `unread`. */
+export declare function removeStreamItem<T>(state: StreamBufferState<T>, key: string | number, getKey: (item: T) => string | number): StreamBufferState<T>;
+/** Reset the unread counter (the feed has been viewed). */
+export declare function markStreamRead<T>(state: StreamBufferState<T>): StreamBufferState<T>;
+//# sourceMappingURL=stream-buffer.d.ts.map

package/dist/binding/stream-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-buffer.d.ts","sourceRoot":"","sources":["../../src/binding/stream-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,CAAC;IACrC,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,QAAQ,GAAE,SAAS,CAAC,EAAO,EAC3B,GAAG,GAAE,MAA2B,GAC/B,iBAAiB,CAAC,CAAC,CAAC,CAGtB;AAaD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC3B,iBAAiB,CAAC,CAAC,CAAC,CAatB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC3B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC3B,iBAAiB,CAAC,CAAC,CAAC,CAEtB;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC3B,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GACnC,iBAAiB,CAAC,CAAC,CAAC,CAMtB;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAEnF"}

package/dist/binding/stream-buffer.js

@@ -0,0 +1,65 @@
+/**
+ * Bounded, newest-first stream buffer (04-widget-registry.md §5.3). Pure and
+ * immutable so the fold is unit-testable without a socket or the DOM:
+ *
+ * - `upsertStreamItem` prepends a new item (newest first) or replaces an
+ *   existing one in place — this makes optimistic prepends idempotent when the
+ *   server later echoes the same row (same key ⇒ replace, not duplicate);
+ * - the buffer is capped at `max` items; the oldest fall off the tail;
+ * - `unread` counts items added since the last `markStreamRead` (the
+ *   `unread-badge` source of truth); replacements and optimistic prepends do
+ *   not bump it.
+ */
+/** Default retained-item cap for a stream buffer. */
+export const DEFAULT_STREAM_MAX = 100;
+/** Seed a buffer from an initial snapshot (already newest-first). `unread` = 0. */
+export function seedStreamBuffer(snapshot = [], max = DEFAULT_STREAM_MAX) {
+    const cap = Math.max(0, max);
+    return { items: snapshot.slice(0, cap), unread: 0 };
+}
+function indexOfKey(items, key, getKey) {
+    for (let i = 0; i < items.length; i += 1) {
+        if (getKey(items[i]) === key)
+            return i;
+    }
+    return -1;
+}
+/**
+ * Prepend `item` (newest first), or replace the existing item with the same key
+ * in place. A replacement keeps its position and never bumps `unread`.
+ */
+export function upsertStreamItem(state, item, opts) {
+    const max = Math.max(0, opts.max ?? DEFAULT_STREAM_MAX);
+    const countUnread = opts.countUnread ?? true;
+    const key = opts.getKey(item);
+    const existing = indexOfKey(state.items, key, opts.getKey);
+    if (existing >= 0) {
+        const items = state.items.slice();
+        items[existing] = item;
+        return { items, unread: state.unread };
+    }
+    const prepended = [item, ...state.items];
+    const items = prepended.length > max ? prepended.slice(0, max) : prepended;
+    return { items, unread: countUnread ? state.unread + 1 : state.unread };
+}
+/**
+ * Apply a batch of items in chronological order (oldest → newest); the newest
+ * ends up at index 0. Equivalent to folding `upsertStreamItem` left-to-right.
+ */
+export function upsertStreamItems(state, items, opts) {
+    return items.reduce((acc, item) => upsertStreamItem(acc, item, opts), state);
+}
+/** Drop the item with `key`, if present. Never changes `unread`. */
+export function removeStreamItem(state, key, getKey) {
+    const index = indexOfKey(state.items, key, getKey);
+    if (index < 0)
+        return state;
+    const items = state.items.slice();
+    items.splice(index, 1);
+    return { items, unread: state.unread };
+}
+/** Reset the unread counter (the feed has been viewed). */
+export function markStreamRead(state) {
+    return state.unread === 0 ? state : { items: state.items, unread: 0 };
+}
+//# sourceMappingURL=stream-buffer.js.map

package/dist/binding/stream-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-buffer.js","sourceRoot":"","sources":["../../src/binding/stream-buffer.ts"],"names":[],"mappings":"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"}

package/dist/binding/stream-channel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Widget-data stream channel names (04-widget-registry.md §5.3). Channels are
+ * `widget-data:{connectionId}:{qualifiedTable}`; the qualified table is the
+ * snapshot's own id (`schema.name` on Postgres, bare `name` on MySQL/SQLite),
+ * matching the CRUD mutation publisher (`table:{connectionId}:{table.id}`).
+ *
+ * The authoritative channel for a bound widget is the one the server returns in
+ * the `StreamShape` envelope (it resolves the table id). `streamChannelForSource`
+ * derives the same name client-side for demo/preview bindings that already carry
+ * the qualified source.
+ */
+export declare const WIDGET_DATA_CHANNEL_PREFIX = "widget-data";
+/** A binding source as it appears in a query descriptor. */
+export interface StreamSource {
+    schema?: string | undefined;
+    name: string;
+}
+/** `schema.name` (Postgres) or bare `name` (MySQL/SQLite). */
+export declare function qualifiedTableName(source: StreamSource): string;
+/** `widget-data:{connectionId}:{qualifiedTable}`. */
+export declare function streamChannel(connectionId: string, qualifiedTable: string): string;
+/** Derive the channel from a descriptor's `connectionId` + `source`. */
+export declare function streamChannelForSource(connectionId: string, source: StreamSource): string;
+//# sourceMappingURL=stream-channel.d.ts.map

package/dist/binding/stream-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-channel.d.ts","sourceRoot":"","sources":["../../src/binding/stream-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AAExD,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAI/D;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAEzF"}

package/dist/binding/stream-channel.js

@@ -0,0 +1,27 @@
+/**
+ * Widget-data stream channel names (04-widget-registry.md §5.3). Channels are
+ * `widget-data:{connectionId}:{qualifiedTable}`; the qualified table is the
+ * snapshot's own id (`schema.name` on Postgres, bare `name` on MySQL/SQLite),
+ * matching the CRUD mutation publisher (`table:{connectionId}:{table.id}`).
+ *
+ * The authoritative channel for a bound widget is the one the server returns in
+ * the `StreamShape` envelope (it resolves the table id). `streamChannelForSource`
+ * derives the same name client-side for demo/preview bindings that already carry
+ * the qualified source.
+ */
+export const WIDGET_DATA_CHANNEL_PREFIX = 'widget-data';
+/** `schema.name` (Postgres) or bare `name` (MySQL/SQLite). */
+export function qualifiedTableName(source) {
+    return source.schema === undefined || source.schema === ''
+        ? source.name
+        : `${source.schema}.${source.name}`;
+}
+/** `widget-data:{connectionId}:{qualifiedTable}`. */
+export function streamChannel(connectionId, qualifiedTable) {
+    return `${WIDGET_DATA_CHANNEL_PREFIX}:${connectionId}:${qualifiedTable}`;
+}
+/** Derive the channel from a descriptor's `connectionId` + `source`. */
+export function streamChannelForSource(connectionId, source) {
+    return streamChannel(connectionId, qualifiedTableName(source));
+}
+//# sourceMappingURL=stream-channel.js.map

package/dist/binding/stream-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-channel.js","sourceRoot":"","sources":["../../src/binding/stream-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,aAAa,CAAC;AAQxD,8DAA8D;AAC9D,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE;QACxD,CAAC,CAAC,MAAM,CAAC,IAAI;QACb,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,YAAoB,EAAE,cAAsB;IACxE,OAAO,GAAG,0BAA0B,IAAI,YAAY,IAAI,cAAc,EAAE,CAAC;AAC3E,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,sBAAsB,CAAC,YAAoB,EAAE,MAAoB;IAC/E,OAAO,aAAa,CAAC,YAAY,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;AACjE,CAAC"}

package/dist/binding/stream-types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `stream` data-binding shape — client transport contracts (04-widget-registry.md
+ * §3 `stream`, §5.3 realtime). Append-only event delivery for the live widgets
+ * (`realtime-feed`, live `log-table` tails, `unread-badge`).
+ *
+ * A widget bound to a `stream` descriptor receives, from the widget-data query,
+ * a `StreamShape` envelope `{ channel, snapshot }` (the server resolves the
+ * table id, so the channel is authoritative). It then subscribes to `channel`
+ * over the injected {@link StreamTransport} (WS with SSE fallback, wired by the
+ * host app) and folds subsequent events into a bounded buffer. Demo/unbound
+ * mode drives the same pipeline from a deterministic seeded generator instead.
+ *
+ * This module is React-aware but transport-agnostic: the concrete WS/SSE
+ * transport lives in the host app (`apps/dashboard/src/api/streamTransport.ts`)
+ * and is injected through {@link StreamTransportProvider}. Tests and Storybook
+ * inject a mock or the demo transport.
+ */
+/** The wire shape of every server→client realtime event (mirrors the hub). */
+export interface StreamRealtimeEvent {
+    channel: string;
+    type: string;
+    data: unknown;
+    /** ISO-8601 UTC. */
+    ts: string;
+}
+/** Fan-out sink for one subscribed channel. */
+export type StreamListener = (event: StreamRealtimeEvent) => void;
+/** Connection-status sink (WS open / SSE fallback open ⇒ `true`). */
+export type StreamStatusListener = (connected: boolean) => void;
+/**
+ * A multiplexed realtime transport. `subscribe` attaches a listener to one
+ * channel and returns the matching unsubscribe. The host implementation keeps
+ * a single connection and reference-counts channels (WS `subscribe`/
+ * `unsubscribe` frames, SSE fallback); the binding hook never sees the socket.
+ */
+export interface StreamTransport {
+    subscribe(channel: string, listener: StreamListener, onStatus?: StreamStatusListener): () => void;
+}
+/**
+ * Server→client `stream` envelope (04 §3 `StreamShape`). Returned by the
+ * widget-data query for a `shape: 'stream'` descriptor: the resolved WS channel
+ * plus the initial (PII-masked) snapshot rows the buffer seeds from.
+ */
+export interface StreamShape {
+    shape: 'stream';
+    channel: string;
+    snapshot: Record<string, unknown>[];
+    columns?: {
+        name: string;
+        logicalType: string;
+        nullable: boolean;
+        isPrimaryKey: boolean;
+    }[];
+}
+/**
+ * Payload carried by a widget-data stream event's `data` field, published by
+ * the server on CRUD/job mutations. `row` is always PII-masked (never a
+ * forbidden column); `delete` events carry the masked pre-image so the buffer
+ * can drop the row by key.
+ */
+export interface StreamEventPayload {
+    /** e.g. `record.create` | `record.update` | `record.delete` | `record.bulk-*`. */
+    type: string;
+    pk?: unknown;
+    row?: Record<string, unknown> | null | undefined;
+}
+//# sourceMappingURL=stream-types.d.ts.map

package/dist/binding/stream-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-types.d.ts","sourceRoot":"","sources":["../../src/binding/stream-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,+CAA+C;AAC/C,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAElE,qEAAqE;AACrE,MAAM,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CACP,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,MAAM,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC7F;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;CAClD"}

package/dist/binding/stream-types.js

@@ -0,0 +1,19 @@
+/**
+ * `stream` data-binding shape — client transport contracts (04-widget-registry.md
+ * §3 `stream`, §5.3 realtime). Append-only event delivery for the live widgets
+ * (`realtime-feed`, live `log-table` tails, `unread-badge`).
+ *
+ * A widget bound to a `stream` descriptor receives, from the widget-data query,
+ * a `StreamShape` envelope `{ channel, snapshot }` (the server resolves the
+ * table id, so the channel is authoritative). It then subscribes to `channel`
+ * over the injected {@link StreamTransport} (WS with SSE fallback, wired by the
+ * host app) and folds subsequent events into a bounded buffer. Demo/unbound
+ * mode drives the same pipeline from a deterministic seeded generator instead.
+ *
+ * This module is React-aware but transport-agnostic: the concrete WS/SSE
+ * transport lives in the host app (`apps/dashboard/src/api/streamTransport.ts`)
+ * and is injected through {@link StreamTransportProvider}. Tests and Storybook
+ * inject a mock or the demo transport.
+ */
+export {};
+//# sourceMappingURL=stream-types.js.map

package/dist/binding/stream-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-types.js","sourceRoot":"","sources":["../../src/binding/stream-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/binding/useWidgetStream.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `useWidgetStream` — the client half of the `stream` binding (04-widget-registry.md
+ * §5.3). A stream widget (realtime-feed, live log-table tail, unread-badge)
+ * calls this with the server-returned `channel` + `snapshot` (bound mode) or a
+ * demo seed (unbound/preview mode); it subscribes over the injected
+ * {@link StreamTransport}, folds events into a bounded newest-first buffer, and
+ * exposes the buffer, an unread counter, a connection flag, pause/resume, and an
+ * optimistic `prepend`.
+ *
+ * Transport is injected via {@link StreamTransportProvider} (bound mode) or
+ * built in-hook from the deterministic demo generator (unbound mode). The hook
+ * itself is transport-agnostic, so it is fully unit-testable with a mock
+ * transport — no socket, no server.
+ */
+import type { StreamEventPayload, StreamRealtimeEvent, StreamTransport } from './stream-types.js';
+export interface UseWidgetStreamOptions<T> {
+    /** Authoritative channel from the server `StreamShape`. Absent ⇒ demo mode. */
+    channel?: string | undefined;
+    /** Initial rows (server `StreamShape.snapshot`), newest-first. */
+    snapshot?: readonly T[] | undefined;
+    /** Stable identity for dedupe/optimistic reconciliation (required). */
+    getKey: (item: T) => string | number;
+    /** Retained-item cap; default {@link DEFAULT_STREAM_MAX}. */
+    max?: number | undefined;
+    /** Map an event payload → item; default reads `payload.row`. `null` ⇒ ignore. */
+    selectItem?: ((payload: StreamEventPayload, event: StreamRealtimeEvent) => T | null) | undefined;
+    /** Event types treated as removals; default: type ends with `delete`. */
+    isRemoval?: ((payload: StreamEventPayload) => boolean) | undefined;
+    /** Demo/unbound mode seed + cadence (used only when `channel` is absent). */
+    demo?: {
+        seed: number;
+        intervalMs?: number | undefined;
+    } | undefined;
+    /** Controlled pause; omit for internal pause state. */
+    paused?: boolean | undefined;
+    onPausedChange?: ((paused: boolean) => void) | undefined;
+    /** Explicit transport override (tests); otherwise context/demo transport. */
+    transport?: StreamTransport | undefined;
+}
+export interface WidgetStream<T> {
+    /** Newest-first buffered items (≤ `max`). */
+    items: readonly T[];
+    /** Unseen items: buffered-since-`markRead` plus any held while paused. */
+    unread: number;
+    /** WS/SSE connected (demo transport reports `true`). */
+    connected: boolean;
+    /** Paused state (content frozen; incoming events held until resume). */
+    paused: boolean;
+    setPaused: (paused: boolean) => void;
+    /** Mark the visible feed as read (does not clear paused-held items). */
+    markRead: () => void;
+    /** Optimistically prepend a locally-created item (does not bump unread). */
+    prepend: (item: T) => void;
+}
+export declare function useWidgetStream<T>(options: UseWidgetStreamOptions<T>): WidgetStream<T>;
+//# sourceMappingURL=useWidgetStream.d.ts.map

package/dist/binding/useWidgetStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWidgetStream.d.ts","sourceRoot":"","sources":["../../src/binding/useWidgetStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC;IACpC,uEAAuE;IACvE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,CAAC;IACrC,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,iFAAiF;IACjF,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,mBAAmB,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACjG,yEAAyE;IACzE,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IACnE,6EAA6E;IAC7E,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC;IACrE,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,cAAc,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACzD,6EAA6E;IAC7E,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,6CAA6C;IAC7C,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,wEAAwE;IACxE,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,4EAA4E;IAC5E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5B;AAeD,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CA8ItF"}