@sharpee/channel-service 1.0.0

package/renderer/renderer.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * @sharpee/channel-service/renderer — `Renderer` host implementation.
+ *
+ * Owner context: consumer-side dispatcher. Drives `CmgtPacket` and
+ * `TurnPacket` instances into registered `ChannelRenderer` plug-ins,
+ * holds the channel state store, and pumps commands back to the
+ * engine.
+ *
+ * Public interface (per ADR-165 §2, §3, §4, §5, §7):
+ *  - `Renderer` class implementing the same-named interface.
+ *  - `createRenderer(opts)` factory for ergonomic instantiation.
+ *
+ * @see ADR-165 — Renderer Architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Renderer = void 0;
+exports.createRenderer = createRenderer;
+const json_tree_fallback_1 = require("./json-tree-fallback");
+/**
+ * Concrete `Renderer` host (ADR-165 §2).
+ *
+ * One instance per session. Holds:
+ *  - the registered `ChannelRenderer`s (last-write-wins per channel id),
+ *  - the channel state store (replace-latest, append-accumulating,
+ *    event-no-entry — ADR-165 §5),
+ *  - the slot handles (`getSlot` / `registerSlot` per §7),
+ *  - the current `CmgtPacket` (so `onValue` can pass the matching
+ *    `ChannelDefinition` to the renderer),
+ *  - the command-handler subscriber list.
+ *
+ * No DOM, no transport, no engine. Concrete consumers compose this
+ * with their host platform.
+ */
+class Renderer {
+    renderers = new Map();
+    fallbackRenderers = new Map();
+    state = {};
+    slots = new Map();
+    commandHandlers = new Set();
+    currentManifest;
+    warn;
+    buildFallback;
+    constructor(opts = {}) {
+        this.warn = opts.warn ?? ((m) => {
+            // eslint-disable-next-line no-console
+            console.warn(m);
+        });
+        this.buildFallback = (0, json_tree_fallback_1.createJsonTreeFallbackFactory)({
+            warn: opts.fallbackWarn ?? this.warn,
+            output: opts.fallbackOutput,
+        });
+    }
+    // ────────────────────────────────────────────────────────────────
+    //  Registration
+    // ────────────────────────────────────────────────────────────────
+    /**
+     * Register a `ChannelRenderer` (ADR-165 §3). Last-write-wins —
+     * re-registering replaces the prior renderer for that id.
+     */
+    registerRenderer(channelId, renderer) {
+        this.renderers.set(channelId, renderer);
+    }
+    /**
+     * Register a slot (ADR-165 §7). Stories that replace the
+     * platform-default layout call this for each region.
+     */
+    registerSlot(name, handle) {
+        this.slots.set(name, handle);
+    }
+    /**
+     * Resolve a slot handle, or `null` if not registered.
+     */
+    getSlot(name) {
+        return this.slots.has(name) ? this.slots.get(name) : null;
+    }
+    // ────────────────────────────────────────────────────────────────
+    //  Command pump
+    // ────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to commands emitted by channel renderers.
+     */
+    onCommand(handler) {
+        this.commandHandlers.add(handler);
+    }
+    /**
+     * Emit a command from a `ChannelRenderer` (UI-gesture origin).
+     * All registered handlers receive the packet synchronously.
+     */
+    emitCommand(text) {
+        const packet = { kind: 'command', text };
+        for (const handler of this.commandHandlers) {
+            handler(packet);
+        }
+    }
+    // ────────────────────────────────────────────────────────────────
+    //  Lifecycle
+    // ────────────────────────────────────────────────────────────────
+    /**
+     * Apply a CMGT packet (ADR-165 §4 lifecycle).
+     *
+     *  1. If a prior manifest exists, run `onDestroy` for each of its
+     *     renderers (in registration order for determinism).
+     *  2. Reset the state store.
+     *  3. Update the current manifest.
+     *  4. Run `onCmgt` for each new-manifest renderer in registration
+     *     order.
+     */
+    applyCmgt(packet) {
+        if (this.currentManifest) {
+            for (const channel of this.currentManifest.channels) {
+                const r = this.renderers.get(channel.id) ?? this.fallbackRenderers.get(channel.id);
+                r?.onDestroy?.();
+            }
+        }
+        this.state = {};
+        this.currentManifest = packet;
+        // Reset fallback cache so a re-mounted session re-issues the
+        // one-time warning if a channel still lacks a renderer.
+        this.fallbackRenderers.clear();
+        for (const channel of packet.channels) {
+            const r = this.resolveRenderer(channel.id);
+            r.onCmgt?.(channel, packet);
+        }
+    }
+    /**
+     * Dispatch a turn packet (ADR-165 §4 dispatch contract).
+     *
+     * Iterates the current manifest in registration order. For each
+     * manifest entry that has a payload value, updates the state
+     * store per mode and invokes `onValue`. Handles the `clear`
+     * channel specially — empties append-mode state stores and fires
+     * `onClear` hooks.
+     */
+    applyTurnPacket(packet) {
+        if (!this.currentManifest) {
+            this.warn('[channel-service] applyTurnPacket called before applyCmgt; ' +
+                'turn packet ignored. Bootstrap order: cmgt before turn (ADR-163 §11).');
+            return;
+        }
+        // Check for a `clear` event in this turn packet — handle it
+        // first so subsequent main/append channel emissions land in an
+        // emptied store.
+        const clearValue = packet.payload['clear'];
+        if (clearValue !== undefined) {
+            this.handleClear(clearValue);
+        }
+        // Walk the manifest in registration order. The payload's own
+        // key order is irrelevant — manifest order is the contract.
+        for (const channel of this.currentManifest.channels) {
+            // The clear channel itself was already handled above; let
+            // its renderer fire normally too (visual side-effects).
+            if (!Object.prototype.hasOwnProperty.call(packet.payload, channel.id)) {
+                continue;
+            }
+            const value = packet.payload[channel.id];
+            this.applyChannelValue(channel, value);
+        }
+    }
+    /**
+     * Snapshot of the channel state store (deep-cloned) — for tests
+     * and ADR-163 AC-12 round-trip.
+     */
+    getStateSnapshot() {
+        return deepClone(this.state);
+    }
+    // ────────────────────────────────────────────────────────────────
+    //  Private — dispatch helpers
+    // ────────────────────────────────────────────────────────────────
+    /**
+     * Update the state store per mode and invoke the renderer's
+     * `onValue`.
+     */
+    applyChannelValue(channel, value) {
+        switch (channel.mode) {
+            case 'replace': {
+                this.state[channel.id] = value;
+                break;
+            }
+            case 'append': {
+                const entries = Array.isArray(value) ? value : [value];
+                const existing = this.state[channel.id];
+                const accumulator = Array.isArray(existing) ? existing : [];
+                this.state[channel.id] = accumulator.concat(entries);
+                break;
+            }
+            case 'event': {
+                // Event channels do NOT write to the state store (ADR-165 §5).
+                break;
+            }
+        }
+        const renderer = this.resolveRenderer(channel.id);
+        renderer.onValue(value, channel);
+    }
+    /**
+     * Handle a `clear` channel emission (ADR-165 §4 step 2).
+     *
+     * `value.target` (when set) names a specific append-mode channel
+     * to clear; an empty / missing target clears every append-mode
+     * channel currently registered in the manifest.
+     */
+    handleClear(value) {
+        if (!this.currentManifest)
+            return;
+        const target = value && typeof value === 'object' && 'target' in value
+            ? value.target
+            : undefined;
+        for (const channel of this.currentManifest.channels) {
+            if (channel.mode !== 'append')
+                continue;
+            if (target !== undefined && target !== '' && channel.id !== target)
+                continue;
+            // Reset state store entry first (ADR-165 §4 says state is
+            // reset BEFORE onClear runs).
+            delete this.state[channel.id];
+            const renderer = this.renderers.get(channel.id);
+            renderer?.onClear?.(target ?? channel.id);
+        }
+    }
+    /**
+     * Resolve the renderer for a channel id. Returns the registered
+     * renderer when present; otherwise lazily creates and caches a
+     * JSON-tree fallback (so the one-time warning fires once per
+     * channel id, not once per emission).
+     */
+    resolveRenderer(channelId) {
+        const registered = this.renderers.get(channelId);
+        if (registered)
+            return registered;
+        let fallback = this.fallbackRenderers.get(channelId);
+        if (!fallback) {
+            fallback = this.buildFallback(channelId);
+            this.fallbackRenderers.set(channelId, fallback);
+        }
+        return fallback;
+    }
+}
+exports.Renderer = Renderer;
+/**
+ * Convenience factory for `new Renderer(opts)`.
+ */
+function createRenderer(opts = {}) {
+    return new Renderer(opts);
+}
+/**
+ * Deep-clone helper for `getStateSnapshot`. Uses `structuredClone`
+ * when available; falls back to `JSON.parse(JSON.stringify(...))`
+ * for compatibility with older runtimes.
+ */
+function deepClone(value) {
+    if (typeof globalThis.structuredClone === 'function') {
+        return globalThis.structuredClone(value);
+    }
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        // Last resort — return shallow copy if value cannot round-trip.
+        return Array.isArray(value) ? [...value] : { ...value };
+    }
+}
+//# sourceMappingURL=renderer.js.map

package/renderer/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/channel-service/src/renderer/renderer.ts"],"names":[],"mappings":"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"}

package/renderer/types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @sharpee/channel-service/renderer — consumer-side type contracts.
+ *
+ * Owner context: consumer side of channel-I/O. Defines the
+ * `ChannelRenderer` plug-in shape, the `Renderer` host that drives
+ * packets into renderers, and the small `SlotHandle` abstraction the
+ * default layouts use to address output regions.
+ *
+ * Public interface (per ADR-165 §1, §2, §5, §7):
+ *  - `ChannelRenderer` — per-channel rendering contract; only
+ *    `onValue` is required.
+ *  - `Renderer` — top-level host the consumer drives.
+ *  - `ChannelStateStore` — in-memory state per channel id (replace
+ *    keeps latest, append accumulates, event has no entry).
+ *  - `SlotHandle` — opaque handle the default layouts use; concrete
+ *    consumers narrow to `HTMLElement` (DOM), terminal region (CLI),
+ *    or whatever their output medium uses.
+ *
+ * No implementation lives here. Pure types so renderer-host packages
+ * (browser, CLI, multi-user) and channel-renderer authors share a
+ * single contract.
+ *
+ * @see ADR-165 — Renderer Architecture
+ */
+import type { ChannelDefinition, CmgtPacket, CommandPacket, TurnPacket } from "../../if-domain/index";
+/**
+ * Per-channel rendering logic (ADR-165 §1).
+ *
+ * A `ChannelRenderer` is registered against a channel id via
+ * `Renderer.registerRenderer(channelId, renderer)`. The dispatcher
+ * invokes `onValue` once per emission of that channel in a turn
+ * packet; optional hooks fire on lifecycle transitions.
+ *
+ * The interface is deliberately small. Cross-channel logic (a
+ * status-bar renderer reading both `location` and `score`) lives in
+ * the host module, not inside individual `ChannelRenderer` instances.
+ */
+export interface ChannelRenderer {
+    /**
+     * Required. Called once per emission of this channel in a turn
+     * packet. The shape of `value` mirrors the channel's mode:
+     *
+     *  - **replace-mode** — the latest scalar value (or `null` for
+     *    hide / stop signals per ADR-163 §6).
+     *  - **append-mode** — an array of new entries this turn (per
+     *    ADR-163 §5; the renderer accumulates across turns).
+     *  - **event-mode** — the event payload.
+     *
+     * `channel` is the manifest entry — useful for renderers that
+     * decide formatting based on `contentType`.
+     */
+    onValue(value: unknown, channel: ChannelDefinition): void;
+    /**
+     * Optional. Append-mode only. Invoked by the dispatcher when a
+     * `clear` event with a matching `target` arrives. The renderer
+     * is responsible for clearing its rendered output (DOM container,
+     * terminal region). The state store is reset by the dispatcher
+     * before this hook fires.
+     */
+    onClear?(target: string): void;
+    /**
+     * Optional. Invoked when CMGT is applied. Use for one-time setup
+     * (DOM scaffolding, asset preload, audio context init). NOT for
+     * state restoration — that comes via `applyTurnPacket` replays.
+     *
+     * On the first `applyCmgt` of a `Renderer`'s lifetime this is the
+     * only setup hook called. On subsequent invocations, `onDestroy`
+     * is called first, then `onCmgt` is called again to set up a
+     * fresh session.
+     */
+    onCmgt?(channel: ChannelDefinition, manifest: CmgtPacket): void;
+    /**
+     * Optional. Invoked when a fresh `applyCmgt` is about to reset
+     * this `Renderer`. Releases resources allocated in `onCmgt` (Web
+     * Audio context, IntersectionObserver, etc.). Symmetric with
+     * `onCmgt`. Not called when the host platform itself is shutting
+     * down (process exit, page unload) — the platform handles that.
+     */
+    onDestroy?(): void;
+}
+/**
+ * Channel state store shape (ADR-165 §5).
+ *
+ * Replace channels store the latest scalar (or `null`); append
+ * channels store an accumulated `unknown[]`; event channels and
+ * never-emitted channels have no entry.
+ *
+ * The dispatcher owns mutation. Renderers read; they do not write.
+ */
+export interface ChannelStateStore {
+    [channelId: string]: unknown | unknown[] | undefined;
+}
+/**
+ * Opaque handle to a layout slot (ADR-165 §7).
+ *
+ * Concrete renderer hosts narrow to their output medium:
+ *  - browser: `HTMLElement`
+ *  - CLI: a small `{ write, clear }` adapter
+ *  - canvas: a draw-group reference
+ *
+ * The `Renderer` itself is medium-agnostic — it stores and returns
+ * whatever the host registers.
+ */
+export type SlotHandle = unknown;
+/**
+ * Top-level renderer handle the consumer drives (ADR-165 §2).
+ *
+ * One instance per session. The consumer:
+ *  1. Constructs a `Renderer`.
+ *  2. Calls `registerRenderer(channelId, renderer)` for each
+ *     channel it wants to display (platform defaults register
+ *     during platform boot; stories register during story init).
+ *  3. Calls `applyCmgt(cmgt)` once when the engine emits the
+ *     manifest.
+ *  4. Calls `applyTurnPacket(packet)` per turn the engine emits.
+ *  5. Subscribes to `onCommand(handler)` to feed commands back.
+ */
+export interface Renderer {
+    /**
+     * Apply a CMGT packet (ADR-165 §4).
+     *
+     * On second-and-subsequent invocations:
+     *   1. Runs `onDestroy` for every renderer in the prior manifest.
+     *   2. Resets every channel state store.
+     *   3. Updates the current manifest.
+     *   4. Runs `onCmgt` for every renderer in the new manifest, in
+     *      manifest order.
+     *
+     * On the first invocation, step 1 is skipped.
+     */
+    applyCmgt(packet: CmgtPacket): void;
+    /**
+     * Dispatch a turn packet (ADR-165 §4). Iterates the current
+     * manifest in registration order; for each manifest entry that
+     * has a payload value, updates the state store and invokes the
+     * registered renderer's `onValue`. `clear` events trigger the
+     * append-channel truncation path.
+     *
+     * Synchronous: every dispatched callback completes before the
+     * call returns.
+     */
+    applyTurnPacket(packet: TurnPacket): void;
+    /**
+     * Register a `ChannelRenderer` against a channel id. Last-write-
+     * wins per ADR-165 §3 — re-registering with the same id replaces
+     * the prior renderer. Platform-default renderers register first;
+     * story overrides replace them.
+     */
+    registerRenderer(channelId: string, renderer: ChannelRenderer): void;
+    /**
+     * Subscribe to `CommandPacket`s emitted by channel renderers.
+     * The consumer's host loop pumps these back to the engine.
+     * Multiple subscribers all receive each emission.
+     */
+    onCommand(handler: (cmd: CommandPacket) => void): void;
+    /**
+     * Emit a `CommandPacket`. Channel renderers call this when a UI
+     * gesture (hotspot click, drag-drop, custom widget) should
+     * advance the engine (ADR-163 §10).
+     */
+    emitCommand(text: string): void;
+    /**
+     * Register a slot (ADR-165 §7). Stories that replace the
+     * platform-default layout call this for each region of their
+     * custom layout.
+     */
+    registerSlot(name: string, handle: SlotHandle): void;
+    /**
+     * Resolve a slot handle, or `null` if the slot is not registered.
+     */
+    getSlot(name: string): SlotHandle | null;
+    /**
+     * Snapshot of the channel state store for testing and AC-7
+     * (re-emission identity round-trip). Returns a deep-cloned copy;
+     * the caller may mutate freely.
+     */
+    getStateSnapshot(): ChannelStateStore;
+}
+//# sourceMappingURL=types.d.ts.map

package/renderer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/channel-service/src/renderer/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,UAAU,EACX,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE1D;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAEhE;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAEpC;;;;;;;;;OASG;IACH,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAE1C;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAErE;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAC;IAEvD;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAErD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAEzC;;;;OAIG;IACH,gBAAgB,IAAI,iBAAiB,CAAC;CACvC"}

package/renderer/types.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * @sharpee/channel-service/renderer — consumer-side type contracts.
+ *
+ * Owner context: consumer side of channel-I/O. Defines the
+ * `ChannelRenderer` plug-in shape, the `Renderer` host that drives
+ * packets into renderers, and the small `SlotHandle` abstraction the
+ * default layouts use to address output regions.
+ *
+ * Public interface (per ADR-165 §1, §2, §5, §7):
+ *  - `ChannelRenderer` — per-channel rendering contract; only
+ *    `onValue` is required.
+ *  - `Renderer` — top-level host the consumer drives.
+ *  - `ChannelStateStore` — in-memory state per channel id (replace
+ *    keeps latest, append accumulates, event has no entry).
+ *  - `SlotHandle` — opaque handle the default layouts use; concrete
+ *    consumers narrow to `HTMLElement` (DOM), terminal region (CLI),
+ *    or whatever their output medium uses.
+ *
+ * No implementation lives here. Pure types so renderer-host packages
+ * (browser, CLI, multi-user) and channel-renderer authors share a
+ * single contract.
+ *
+ * @see ADR-165 — Renderer Architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/renderer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/channel-service/src/renderer/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/utils/flatten.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @sharpee/channel-service/utils — text-content flattening helper.
+ *
+ * Owner context: platform package. Small utility used by consumers
+ * (renderers, debug logs, custom extractors) that need to project an
+ * `ITextBlock`'s decorated content tree into a plain string.
+ *
+ * Public interface:
+ *  - `flattenContent(content)` — recursive concat of string nodes,
+ *    stripping decoration wrappers (preserving their inner content).
+ *
+ * Originally lived inside `platform-rules.ts`; extracted here as part
+ * of the ADR-163 R1 rewrite (rule machinery removed; this helper kept
+ * because consumers may still want a one-liner string projection).
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §14
+ */
+import type { TextContent } from "../../text-blocks/index";
+/**
+ * Flatten a `TextContent` array to a plain string.
+ *
+ * Recursively concatenates string nodes and strips decoration wrappers
+ * (preserving their inner content). Side-effect-free; safe to call
+ * inside producer closures.
+ */
+export declare function flattenContent(content: ReadonlyArray<TextContent>): string;
+//# sourceMappingURL=flatten.d.ts.map

package/utils/flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/channel-service/src/utils/flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAU1E"}

package/utils/flatten.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * @sharpee/channel-service/utils — text-content flattening helper.
+ *
+ * Owner context: platform package. Small utility used by consumers
+ * (renderers, debug logs, custom extractors) that need to project an
+ * `ITextBlock`'s decorated content tree into a plain string.
+ *
+ * Public interface:
+ *  - `flattenContent(content)` — recursive concat of string nodes,
+ *    stripping decoration wrappers (preserving their inner content).
+ *
+ * Originally lived inside `platform-rules.ts`; extracted here as part
+ * of the ADR-163 R1 rewrite (rule machinery removed; this helper kept
+ * because consumers may still want a one-liner string projection).
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §14
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenContent = flattenContent;
+/**
+ * Flatten a `TextContent` array to a plain string.
+ *
+ * Recursively concatenates string nodes and strips decoration wrappers
+ * (preserving their inner content). Side-effect-free; safe to call
+ * inside producer closures.
+ */
+function flattenContent(content) {
+    let out = '';
+    for (const node of content) {
+        if (typeof node === 'string') {
+            out += node;
+        }
+        else {
+            out += flattenContent(node.content);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=flatten.js.map

package/utils/flatten.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/channel-service/src/utils/flatten.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAWH,wCAUC;AAjBD;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,OAAmC;IAChE,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,GAAG,IAAI,IAAI,CAAC;QACd,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/wire/decoder.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @sharpee/channel-service/wire — client-side decoder
+ *
+ * Owner context: wire-protocol module. A small state machine the
+ * consumer feeds incoming packets through. Enforces the ordering
+ * invariants from ADR-163 §11 / AC-11:
+ *
+ *   1. The first server-bound packet a consumer accepts is `cmgt`.
+ *   2. `turn` packets are accepted only after `cmgt`.
+ *   3. `hello` and `command` are not server-bound — receiving one is a
+ *      protocol error.
+ *
+ * The decoder does NOT render — it only validates ordering and exposes
+ * the negotiated manifest. Renderer dispatch is the consumer's
+ * concern (per ADR-165).
+ *
+ * @see ADR-163 §11 — bootstrap order invariants
+ */
+import type { CmgtPacket, TurnPacket, WirePacket } from "../../if-domain/index";
+/**
+ * State exposed by the decoder after each `ingest` call.
+ *
+ * - `'awaiting-cmgt'` — initial state. Consumer has dispatched a hello
+ *   and is awaiting the server's CMGT manifest.
+ * - `'live'` — CMGT received; turn packets are now accepted.
+ * - `'error'` — protocol violation. The decoder does not recover; the
+ *   consumer must drop the connection (or, in single-bundle, surface
+ *   the error and reset the producer).
+ */
+export type DecoderState = {
+    readonly status: 'awaiting-cmgt';
+} | {
+    readonly status: 'live';
+    readonly cmgt: CmgtPacket;
+} | {
+    readonly status: 'error';
+    readonly reason: string;
+};
+/**
+ * Decoder handle. The consumer reads `state` after each `ingest`.
+ * `lastTurn` is set when a turn is accepted and cleared when the
+ * decoder transitions to `error`.
+ */
+export interface Decoder {
+    readonly state: DecoderState;
+    /**
+     * Most recently accepted `turn` packet, or `null` if none has been
+     * accepted in the current session. Reset on every `ingest`.
+     */
+    readonly lastTurn: TurnPacket | null;
+    /**
+     * Feed a packet to the decoder. After this returns, `state` reflects
+     * the new state. Returns the same handle for chaining.
+     */
+    ingest(packet: WirePacket): Decoder;
+}
+/**
+ * Create a fresh client-side decoder in the `awaiting-cmgt` state.
+ */
+export declare function createDecoder(): Decoder;
+//# sourceMappingURL=decoder.d.ts.map

package/wire/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/channel-service/src/wire/decoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;CACrC;AAoDD;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}