@sharpee/channel-service 1.0.0

package/channel-service.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @sharpee/channel-service — `ChannelService` class.
+ *
+ * Owner context: platform package — runs in-process wherever the engine
+ * runs (Node CLI, multi-user server, browser zifmia, platform-browser).
+ *
+ * Public interface (per ADR-163 §6, §13, §14):
+ *
+ * - `ChannelService` — concrete runtime. Constructor takes an
+ *   `IChannelRegistry` plus the client's `ClientCapabilities`.
+ *   - `buildManifest()` — returns a `CmgtPacket` listing the
+ *     capability-filtered channel definitions.
+ *   - `build({ world, events, blocks, turn })` — walks the registry,
+ *     calls each `IOChannel.produce` closure, applies mode + emit-policy
+ *     semantics, and returns a `TurnPacket`.
+ *
+ * Lifecycle (ADR-163 §13): instances are cheap. A new session (engine
+ * restart, story switch, RESTART command) creates a fresh
+ * `ChannelService`. There is no global session state — `prevValues`
+ * lives on the instance.
+ *
+ * Bootstrap-order invariants (engine-enforced, not service-enforced):
+ * the engine emits `channel:manifest` before any `channel:packet`
+ * because it calls `buildManifest()` once during `start()` before
+ * entering the turn loop. This service does not throw on
+ * out-of-order calls; engineers reading the engine code can trace the
+ * order from the engine's startup sequence.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §11, §13, §14
+ * @see ADR-165 — Renderer Architecture (consumer side)
+ */
+import type { IChannelRegistry, ClientCapabilities, CmgtPacket, TurnPacket } from "../if-domain/index";
+import type { ITextBlock } from "../text-blocks/index";
+import type { ISemanticEvent } from "../core/index";
+/**
+ * Wire-protocol version emitted in every CMGT manifest. Bumped on
+ * breaking shape changes to packet kinds or `ChannelDefinition` fields.
+ * Additive channels do not bump version.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Input to {@link ChannelService.build}.
+ *
+ * `world` is typed `unknown` here for consistency with
+ * `ChannelProduceContext` (if-domain cannot import `IWorldModel`).
+ * Engine call sites pass an `IWorldModel`; closures cast at the
+ * boundary.
+ */
+export interface BuildInput {
+    readonly world: unknown;
+    readonly events: readonly ISemanticEvent[];
+    readonly blocks: readonly ITextBlock[];
+    /** Monotonic turn count supplied by the engine. Used for `turn_id`. */
+    readonly turn: number;
+}
+/**
+ * The channel-service runtime.
+ *
+ * One instance per session. Composes a channel registry (typically
+ * `@sharpee/stdlib`'s `channelRegistry`) with the negotiated client
+ * capabilities. Holds per-channel previous-value state for sparse-emit
+ * change detection and `always`-mode replace re-emission.
+ */
+export declare class ChannelService {
+    private readonly registry;
+    private readonly capabilities;
+    /**
+     * Per-channel previous emitted value. Replace-mode channels store the
+     * latest emitted value (used both for sparse change detection and for
+     * `always`-mode idle-turn re-emission). Append-mode channels store the
+     * total accumulated entry count (for diagnostics; the renderer owns
+     * accumulation per ADR-165 §5). Event-mode channels do not consult
+     * prevValue.
+     */
+    private readonly prevValues;
+    constructor(registry: IChannelRegistry, capabilities: ClientCapabilities);
+    /**
+     * Build the per-client CMGT manifest (ADR-163 §11).
+     *
+     * Walks every registered channel. Capability-gated channels
+     * (`IOChannel.gatedBy`) are filtered out when the named capability is
+     * not declared `true` for this client. Returns a fresh manifest each
+     * call; safe to invoke multiple times (the engine calls it once
+     * during `start()`).
+     */
+    buildManifest(): CmgtPacket;
+    /**
+     * Build the turn packet for the turn just executed (ADR-163 §1, §5).
+     *
+     * For each registered, non-gated channel:
+     *  1. Builds a {@link ChannelProduceContext} with the channel's
+     *     `prevValue` from this instance's cache.
+     *  2. Calls `channel.produce(ctx)`.
+     *  3. Applies mode + emit-policy semantics to the return value to
+     *     decide whether the channel appears in this turn's payload and
+     *     what value it carries.
+     *  4. Updates the per-channel `prevValue` cache.
+     *
+     * Returns a `TurnPacket` whose `payload` contains only the channels
+     * that emitted this turn. Sparse channels stay quiet on no-change;
+     * always channels appear every turn.
+     */
+    build(input: BuildInput): TurnPacket;
+    /**
+     * True if the channel's `gatedBy` flag is set and the client did not
+     * declare that capability as `true`. Gated-out channels appear neither
+     * in the manifest nor in turn packets.
+     */
+    private isGatedOut;
+    /**
+     * Apply mode + emit-policy semantics to a closure's return value.
+     *
+     * Mutates `payload` (sets `payload[channel.id]` if the channel
+     * emits) and `this.prevValues` (records the new value for sparse
+     * compare and idle re-emission).
+     *
+     * Mode semantics (ADR-163 §4, §6):
+     *
+     *  - `replace`:
+     *     * `undefined` — `always` re-emits prevValue (idle turn);
+     *       `sparse` skips.
+     *     * `null` — emit `null` (hide / stop signal); cache `null`.
+     *     * value — `always` emits unconditionally; `sparse` emits only
+     *       on change. Cache the new value.
+     *
+     *  - `append`:
+     *     * `undefined` — skip (no new entries this turn).
+     *     * `null` — treated as "no new entries"; skip.
+     *     * scalar — wrapped into a single-element array (closure
+     *       convenience: `produce: () => 'line'` works without `[]`).
+     *     * array (possibly empty) — `always` emits the array as-is;
+     *       `sparse` emits only when non-empty. The renderer owns
+     *       accumulation per ADR-165 §5.
+     *
+     *  - `event`:
+     *     * `undefined` / `null` — skip (event channels emit only on
+     *       fire). Emit policy is informative only — `event` mode is
+     *       inherently sparse.
+     *     * value — emit the value (transient signal).
+     *
+     * The closure return type `T | T[] | undefined | null` allows append
+     * mode to return entries directly while replace and event return a
+     * scalar. Append's scalar-as-shortcut is documented above.
+     */
+    private applyEmission;
+}
+//# sourceMappingURL=channel-service.d.ts.map

package/channel-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-service.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/channel-service/src/channel-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAEhB,kBAAkB,EAGlB,UAAU,EACV,UAAU,EACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IAYvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAZ/B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;gBAGtC,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,kBAAkB;IAGnD;;;;;;;;OAQG;IACH,aAAa,IAAI,UAAU;IAa3B;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IA0BpC;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,OAAO,CAAC,aAAa;CAmDtB"}

package/channel-service.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * @sharpee/channel-service — `ChannelService` class.
+ *
+ * Owner context: platform package — runs in-process wherever the engine
+ * runs (Node CLI, multi-user server, browser zifmia, platform-browser).
+ *
+ * Public interface (per ADR-163 §6, §13, §14):
+ *
+ * - `ChannelService` — concrete runtime. Constructor takes an
+ *   `IChannelRegistry` plus the client's `ClientCapabilities`.
+ *   - `buildManifest()` — returns a `CmgtPacket` listing the
+ *     capability-filtered channel definitions.
+ *   - `build({ world, events, blocks, turn })` — walks the registry,
+ *     calls each `IOChannel.produce` closure, applies mode + emit-policy
+ *     semantics, and returns a `TurnPacket`.
+ *
+ * Lifecycle (ADR-163 §13): instances are cheap. A new session (engine
+ * restart, story switch, RESTART command) creates a fresh
+ * `ChannelService`. There is no global session state — `prevValues`
+ * lives on the instance.
+ *
+ * Bootstrap-order invariants (engine-enforced, not service-enforced):
+ * the engine emits `channel:manifest` before any `channel:packet`
+ * because it calls `buildManifest()` once during `start()` before
+ * entering the turn loop. This service does not throw on
+ * out-of-order calls; engineers reading the engine code can trace the
+ * order from the engine's startup sequence.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §11, §13, §14
+ * @see ADR-165 — Renderer Architecture (consumer side)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelService = exports.PROTOCOL_VERSION = void 0;
+/**
+ * Wire-protocol version emitted in every CMGT manifest. Bumped on
+ * breaking shape changes to packet kinds or `ChannelDefinition` fields.
+ * Additive channels do not bump version.
+ */
+exports.PROTOCOL_VERSION = 1;
+/**
+ * The channel-service runtime.
+ *
+ * One instance per session. Composes a channel registry (typically
+ * `@sharpee/stdlib`'s `channelRegistry`) with the negotiated client
+ * capabilities. Holds per-channel previous-value state for sparse-emit
+ * change detection and `always`-mode replace re-emission.
+ */
+class ChannelService {
+    registry;
+    capabilities;
+    /**
+     * Per-channel previous emitted value. Replace-mode channels store the
+     * latest emitted value (used both for sparse change detection and for
+     * `always`-mode idle-turn re-emission). Append-mode channels store the
+     * total accumulated entry count (for diagnostics; the renderer owns
+     * accumulation per ADR-165 §5). Event-mode channels do not consult
+     * prevValue.
+     */
+    prevValues = new Map();
+    constructor(registry, capabilities) {
+        this.registry = registry;
+        this.capabilities = capabilities;
+    }
+    /**
+     * Build the per-client CMGT manifest (ADR-163 §11).
+     *
+     * Walks every registered channel. Capability-gated channels
+     * (`IOChannel.gatedBy`) are filtered out when the named capability is
+     * not declared `true` for this client. Returns a fresh manifest each
+     * call; safe to invoke multiple times (the engine calls it once
+     * during `start()`).
+     */
+    buildManifest() {
+        const channels = [];
+        for (const channel of this.registry.all()) {
+            if (this.isGatedOut(channel))
+                continue;
+            channels.push(toDefinition(channel));
+        }
+        return {
+            kind: 'cmgt',
+            protocol_version: exports.PROTOCOL_VERSION,
+            channels,
+        };
+    }
+    /**
+     * Build the turn packet for the turn just executed (ADR-163 §1, §5).
+     *
+     * For each registered, non-gated channel:
+     *  1. Builds a {@link ChannelProduceContext} with the channel's
+     *     `prevValue` from this instance's cache.
+     *  2. Calls `channel.produce(ctx)`.
+     *  3. Applies mode + emit-policy semantics to the return value to
+     *     decide whether the channel appears in this turn's payload and
+     *     what value it carries.
+     *  4. Updates the per-channel `prevValue` cache.
+     *
+     * Returns a `TurnPacket` whose `payload` contains only the channels
+     * that emitted this turn. Sparse channels stay quiet on no-change;
+     * always channels appear every turn.
+     */
+    build(input) {
+        const payload = {};
+        for (const channel of this.registry.all()) {
+            if (this.isGatedOut(channel))
+                continue;
+            const prevValue = this.prevValues.get(channel.id);
+            const ctx = {
+                world: input.world,
+                events: input.events,
+                blocks: input.blocks,
+                turn: input.turn,
+                prevValue,
+            };
+            const produced = channel.produce(ctx);
+            this.applyEmission(channel, produced, prevValue, payload);
+        }
+        return {
+            kind: 'turn',
+            turn_id: `turn-${input.turn}`,
+            payload,
+        };
+    }
+    /**
+     * True if the channel's `gatedBy` flag is set and the client did not
+     * declare that capability as `true`. Gated-out channels appear neither
+     * in the manifest nor in turn packets.
+     */
+    isGatedOut(channel) {
+        if (channel.gatedBy === undefined)
+            return false;
+        return this.capabilities[channel.gatedBy] !== true;
+    }
+    /**
+     * Apply mode + emit-policy semantics to a closure's return value.
+     *
+     * Mutates `payload` (sets `payload[channel.id]` if the channel
+     * emits) and `this.prevValues` (records the new value for sparse
+     * compare and idle re-emission).
+     *
+     * Mode semantics (ADR-163 §4, §6):
+     *
+     *  - `replace`:
+     *     * `undefined` — `always` re-emits prevValue (idle turn);
+     *       `sparse` skips.
+     *     * `null` — emit `null` (hide / stop signal); cache `null`.
+     *     * value — `always` emits unconditionally; `sparse` emits only
+     *       on change. Cache the new value.
+     *
+     *  - `append`:
+     *     * `undefined` — skip (no new entries this turn).
+     *     * `null` — treated as "no new entries"; skip.
+     *     * scalar — wrapped into a single-element array (closure
+     *       convenience: `produce: () => 'line'` works without `[]`).
+     *     * array (possibly empty) — `always` emits the array as-is;
+     *       `sparse` emits only when non-empty. The renderer owns
+     *       accumulation per ADR-165 §5.
+     *
+     *  - `event`:
+     *     * `undefined` / `null` — skip (event channels emit only on
+     *       fire). Emit policy is informative only — `event` mode is
+     *       inherently sparse.
+     *     * value — emit the value (transient signal).
+     *
+     * The closure return type `T | T[] | undefined | null` allows append
+     * mode to return entries directly while replace and event return a
+     * scalar. Append's scalar-as-shortcut is documented above.
+     */
+    applyEmission(channel, produced, prevValue, payload) {
+        const emit = channel.emit;
+        switch (channel.mode) {
+            case 'replace': {
+                if (produced === undefined) {
+                    if (emit === 'always' && prevValue !== undefined) {
+                        payload[channel.id] = prevValue;
+                    }
+                    return;
+                }
+                // `produced` is either a real value or `null` (hide signal).
+                // Both go through the same change-detection path: sparse
+                // channels only emit on transition; always channels emit each
+                // turn. The cached prevValue tracks `null` so a subsequent
+                // null-return on a sparse channel is recognized as no-change.
+                if (emit === 'always' || !valueEquals(produced, prevValue)) {
+                    payload[channel.id] = produced;
+                }
+                this.prevValues.set(channel.id, produced);
+                return;
+            }
+            case 'append': {
+                if (produced === undefined || produced === null)
+                    return;
+                const entries = Array.isArray(produced) ? produced : [produced];
+                if (emit === 'always') {
+                    payload[channel.id] = entries;
+                }
+                else if (entries.length > 0) {
+                    payload[channel.id] = entries;
+                }
+                // Track entry count for diagnostics; renderer owns the buffer.
+                const prevCount = typeof prevValue === 'number' ? prevValue : 0;
+                this.prevValues.set(channel.id, prevCount + entries.length);
+                return;
+            }
+            case 'event': {
+                if (produced === undefined || produced === null)
+                    return;
+                // Multi-firing in one turn collapses to the closure's last
+                // return value — the closure itself is the single fire site.
+                payload[channel.id] = produced;
+                return;
+            }
+        }
+    }
+}
+exports.ChannelService = ChannelService;
+/**
+ * Project an `IOChannel` into a wire-shaped `ChannelDefinition`.
+ *
+ * The closure does not cross the wire; only identity and configuration.
+ */
+function toDefinition(channel) {
+    return {
+        id: channel.id,
+        contentType: channel.contentType,
+        mode: channel.mode,
+        emit: channel.emit,
+    };
+}
+/**
+ * Deep value equality for sparse-emit change detection.
+ *
+ * Uses `JSON.stringify` for object/array compares — adequate for the
+ * value shapes carried over the wire (scalars, plain objects, arrays
+ * of scalars or text content nodes). Not safe for cyclic graphs, but
+ * those cannot cross the JSON wire anyway.
+ */
+function valueEquals(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === 'object') {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+}
+//# sourceMappingURL=channel-service.js.map

package/channel-service.js.map

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

package/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @sharpee/channel-service
+ *
+ * Channel-I/O wire producer for Sharpee surfaces (ADR-163,
+ * closure-per-channel model — 2026-05-02 rewrite + 2026-05-03 refinement).
+ *
+ * Owner context: platform package — runs in-process wherever the engine
+ * runs (Node CLI, multi-user server, browser zifmia, platform-browser).
+ *
+ * Public interface:
+ *
+ * - **`ChannelService`** — concrete runtime class. Constructor takes an
+ *   `IChannelRegistry` plus the client's `ClientCapabilities`.
+ *   - `buildManifest()` returns a `CmgtPacket` (capability-filtered).
+ *   - `build({ world, events, blocks, turn })` walks the registry,
+ *     calls each `IOChannel.produce`, and returns a `TurnPacket`.
+ * - **Channel + wire types** are re-exported from `@sharpee/if-domain`
+ *   for caller convenience. `if-domain` is the single canonical home
+ *   for these contracts (CLAUDE.md rule 7b).
+ * - **Wire decoder** ships here (`createDecoder`, `Decoder`,
+ *   `DecoderState`) for clients that receive packets and need
+ *   bootstrap-order enforcement.
+ * - **`flattenContent`** utility for projecting `TextContent` arrays
+ *   to plain strings (used by closures and renderers).
+ *
+ * Standard channel definitions (`main`, `prompt`, `score`, `turn`,
+ * `location`, media channels, etc.) live in `@sharpee/stdlib` per
+ * ADR-163 §7, §14. This package is domain-agnostic — it does not know
+ * what `scoring` means or what `room.name` means.
+ *
+ * @see ADR-163 — Channel-Service Platform
+ * @see ADR-165 — Renderer Architecture (consumer side)
+ */
+export { ChannelService, PROTOCOL_VERSION } from './channel-service';
+export type { BuildInput } from './channel-service';
+export type { IOChannel, IChannelRegistry, ChannelProduceContext, ChannelContentType, ChannelMode, ChannelEmitPolicy, ClientCapabilities, CapabilityFlag, ChannelDefinition, HelloPacket, CmgtPacket, TurnPacket, CommandPacket, WirePacket, } from "../if-domain/index";
+export { createDecoder, type Decoder, type DecoderState } from './wire';
+export { flattenContent } from './utils/flatten';
+export { renderToString, renderStatusLine } from './render-to-string';
+export type { CLIRenderOptions } from './render-to-string';
+export { Renderer, createRenderer, createJsonTreeFallbackFactory, type RendererOptions, type FallbackOutputSink, type FallbackWarningSink, } from './renderer';
+export type { ChannelRenderer, IRenderer, ChannelStateStore, SlotHandle, } from './renderer';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/channel-service/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,GACX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAExE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQjD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EACL,QAAQ,EACR,cAAc,EACd,6BAA6B,EAC7B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/index.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * @sharpee/channel-service
+ *
+ * Channel-I/O wire producer for Sharpee surfaces (ADR-163,
+ * closure-per-channel model — 2026-05-02 rewrite + 2026-05-03 refinement).
+ *
+ * Owner context: platform package — runs in-process wherever the engine
+ * runs (Node CLI, multi-user server, browser zifmia, platform-browser).
+ *
+ * Public interface:
+ *
+ * - **`ChannelService`** — concrete runtime class. Constructor takes an
+ *   `IChannelRegistry` plus the client's `ClientCapabilities`.
+ *   - `buildManifest()` returns a `CmgtPacket` (capability-filtered).
+ *   - `build({ world, events, blocks, turn })` walks the registry,
+ *     calls each `IOChannel.produce`, and returns a `TurnPacket`.
+ * - **Channel + wire types** are re-exported from `@sharpee/if-domain`
+ *   for caller convenience. `if-domain` is the single canonical home
+ *   for these contracts (CLAUDE.md rule 7b).
+ * - **Wire decoder** ships here (`createDecoder`, `Decoder`,
+ *   `DecoderState`) for clients that receive packets and need
+ *   bootstrap-order enforcement.
+ * - **`flattenContent`** utility for projecting `TextContent` arrays
+ *   to plain strings (used by closures and renderers).
+ *
+ * Standard channel definitions (`main`, `prompt`, `score`, `turn`,
+ * `location`, media channels, etc.) live in `@sharpee/stdlib` per
+ * ADR-163 §7, §14. This package is domain-agnostic — it does not know
+ * what `scoring` means or what `room.name` means.
+ *
+ * @see ADR-163 — Channel-Service Platform
+ * @see ADR-165 — Renderer Architecture (consumer side)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJsonTreeFallbackFactory = exports.createRenderer = exports.Renderer = exports.renderStatusLine = exports.renderToString = exports.flattenContent = exports.createDecoder = exports.PROTOCOL_VERSION = exports.ChannelService = void 0;
+var channel_service_1 = require("./channel-service");
+Object.defineProperty(exports, "ChannelService", { enumerable: true, get: function () { return channel_service_1.ChannelService; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return channel_service_1.PROTOCOL_VERSION; } });
+var wire_1 = require("./wire");
+Object.defineProperty(exports, "createDecoder", { enumerable: true, get: function () { return wire_1.createDecoder; } });
+var flatten_1 = require("./utils/flatten");
+Object.defineProperty(exports, "flattenContent", { enumerable: true, get: function () { return flatten_1.flattenContent; } });
+// Display flatteners (ADR-174 Phase 2 — `renderToString` / `renderStatusLine`
+// migrated here from `@sharpee/text-service` per OQ-1 resolution).
+// Used by transcript tooling, dev scripts, and chat overlays that need a
+// single string projection of an `ITextBlock[]`. `flattenContent` (above)
+// is the lower-level helper used inside producer closures; `renderToString`
+// adds smart block-joining, ANSI translation, and status-block filtering.
+var render_to_string_1 = require("./render-to-string");
+Object.defineProperty(exports, "renderToString", { enumerable: true, get: function () { return render_to_string_1.renderToString; } });
+Object.defineProperty(exports, "renderStatusLine", { enumerable: true, get: function () { return render_to_string_1.renderStatusLine; } });
+// Consumer-side renderer (ADR-165) — see ./renderer.
+var renderer_1 = require("./renderer");
+Object.defineProperty(exports, "Renderer", { enumerable: true, get: function () { return renderer_1.Renderer; } });
+Object.defineProperty(exports, "createRenderer", { enumerable: true, get: function () { return renderer_1.createRenderer; } });
+Object.defineProperty(exports, "createJsonTreeFallbackFactory", { enumerable: true, get: function () { return renderer_1.createJsonTreeFallbackFactory; } });
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/channel-service/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AAEH,qDAAqE;AAA5D,iHAAA,cAAc,OAAA;AAAE,mHAAA,gBAAgB,OAAA;AAoBzC,+BAAwE;AAA/D,qGAAA,aAAa,OAAA;AAEtB,2CAAiD;AAAxC,yGAAA,cAAc,OAAA;AAEvB,8EAA8E;AAC9E,mEAAmE;AACnE,yEAAyE;AACzE,0EAA0E;AAC1E,4EAA4E;AAC5E,0EAA0E;AAC1E,uDAAsE;AAA7D,kHAAA,cAAc,OAAA;AAAE,oHAAA,gBAAgB,OAAA;AAGzC,qDAAqD;AACrD,uCAOoB;AANlB,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,yHAAA,6BAA6B,OAAA"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sharpee/channel-service",
+  "version": "1.0.0",
+  "description": "Channel-service platform — universal channel-I/O wire producer (ADR-163)",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@sharpee/core": "^1.0.0",
+    "@sharpee/if-domain": "^1.0.0",
+    "@sharpee/text-blocks": "^1.0.0",
+    "@sharpee/world-model": "^1.0.0"
+  },
+  "keywords": [
+    "interactive-fiction",
+    "if",
+    "text-adventure",
+    "sharpee",
+    "channel-service",
+    "channel-io",
+    "wire-protocol"
+  ],
+  "author": "Sharpee Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChicagoDave/sharpee.git",
+    "directory": "packages/channel-service"
+  },
+  "homepage": "https://github.com/ChicagoDave/sharpee#readme",
+  "bugs": {
+    "url": "https://github.com/ChicagoDave/sharpee/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/render-to-string.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `renderToString` and `renderStatusLine` — flatten an `ITextBlock[]`
+ * to a single display string.
+ *
+ * Owner context: `@sharpee/channel-service`. Block-flattening helpers
+ * consumed by transcript tooling, chat overlays, and dev scripts.
+ * Channel-service is downstream of engine and upstream of clients —
+ * the right dependency position for a helper that walks ITextBlock[]
+ * for display.
+ *
+ * Public interface:
+ *  - `renderToString(blocks, options?)` — flatten blocks to a joined
+ *    string with smart separators between same-key vs different-key
+ *    block transitions. Decorations translate to ANSI codes when
+ *    `options.ansi === true`, or to bracket-stripped plain text
+ *    otherwise.
+ *  - `renderStatusLine(blocks, options?)` — render `status.*` blocks
+ *    to a single pipe-separated line for status-bar display.
+ *  - `CLIRenderOptions` — option shape (ansi, blockSeparator,
+ *    colors, includeStatus). Name preserved from the prior
+ *    `@sharpee/text-service` home; not CLI-specific in practice
+ *    (zifmia uses `renderToString` for browser chat bubbles).
+ *
+ * Ported from `@sharpee/text-service/src/cli-renderer.ts` per ADR-174
+ * Phase 2 (OQ-1 resolution, 2026-05-10). The original file remains
+ * compilable in text-service through Phase 2 for zifmia's sake; Phase
+ * 3 deletes the package.
+ *
+ * @see ADR-174 — Decoration Architecture and Engine-Internal Prose Pipeline
+ * @see ADR-163 — Channel-Service Platform
+ */
+import type { ITextBlock } from "../text-blocks/index";
+/**
+ * CLI render options
+ */
+export interface CLIRenderOptions {
+    /** Enable ANSI color codes (default: false) */
+    ansi?: boolean;
+    /** Separator between blocks (default: '\n\n') */
+    blockSeparator?: string;
+    /** Story-defined color mappings */
+    colors?: Record<string, string>;
+    /** Include status blocks in output (default: false) */
+    includeStatus?: boolean;
+}
+/**
+ * Render `ITextBlock[]` to string for display.
+ *
+ * Uses smart joining: single newline between consecutive blocks of the
+ * same key, double newline (or `options.blockSeparator`) between blocks
+ * of different keys. This keeps related output together (e.g., multiple
+ * "Taken." messages) while separating distinct sections.
+ *
+ * @example
+ * const output = renderToString(blocks, { ansi: true });
+ * console.log(output);
+ */
+export declare function renderToString(blocks: ITextBlock[], options?: CLIRenderOptions): string;
+/**
+ * Render status blocks to a single line (for status bar display).
+ *
+ * @example
+ * const status = renderStatusLine(blocks);
+ * // "West of House | Score: 0 | Turns: 1"
+ */
+export declare function renderStatusLine(blocks: ITextBlock[], options?: CLIRenderOptions): string;
+//# sourceMappingURL=render-to-string.d.ts.map

package/render-to-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-to-string.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/channel-service/src/render-to-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA4B,MAAM,sBAAsB,CAAC;AAGjF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,uDAAuD;IACvD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAqJD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CA+BR;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CA6BR"}