@sharpee/stdlib 0.9.113 → 1.0.0

package/channels/keys.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * @sharpee/stdlib/channels — block-key sets used by standard channels.
+ *
+ * Owner context: stdlib language layer. The standard `main` channel's
+ * closure routes prose-shaped blocks (room descriptions, action
+ * results, banners, etc.) into the append-mode main transcript.
+ * `MAIN_KEYS` names every `CORE_BLOCK_KEYS` entry that should land in
+ * the main channel.
+ *
+ * Block keys not in this set are NOT routed to main automatically —
+ * stories override or extend by registering their own `IOChannel`
+ * (last-write-wins on channel id) per ADR-163 §6.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §7, §14
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAIN_KEYS = void 0;
+const text_blocks_1 = require("../../text-blocks/index.js");
+/**
+ * Block keys whose content flows into the `main` channel (append mode,
+ * decoration-preserving). Status blocks (`status.score`, `status.turns`,
+ * `status.room`) are intentionally absent — those values are now read
+ * from world state directly by the score/turn/location channels.
+ */
+exports.MAIN_KEYS = new Set([
+    text_blocks_1.CORE_BLOCK_KEYS.ROOM_NAME,
+    text_blocks_1.CORE_BLOCK_KEYS.ROOM_DESCRIPTION,
+    text_blocks_1.CORE_BLOCK_KEYS.ROOM_CONTENTS,
+    text_blocks_1.CORE_BLOCK_KEYS.ACTION_RESULT,
+    text_blocks_1.CORE_BLOCK_KEYS.ACTION_BLOCKED,
+    text_blocks_1.CORE_BLOCK_KEYS.ERROR,
+    text_blocks_1.CORE_BLOCK_KEYS.GAME_MESSAGE,
+    text_blocks_1.CORE_BLOCK_KEYS.GAME_BANNER,
+]);
+//# sourceMappingURL=keys.js.map

package/channels/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/stdlib/src/channels/keys.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,sDAAuD;AAEvD;;;;;GAKG;AACU,QAAA,SAAS,GAAwB,IAAI,GAAG,CAAS;IAC5D,6BAAe,CAAC,SAAS;IACzB,6BAAe,CAAC,gBAAgB;IAChC,6BAAe,CAAC,aAAa;IAC7B,6BAAe,CAAC,aAAa;IAC7B,6BAAe,CAAC,cAAc;IAC9B,6BAAe,CAAC,KAAK;IACrB,6BAAe,CAAC,YAAY;IAC5B,6BAAe,CAAC,WAAW;CAC5B,CAAC,CAAC"}

package/channels/media.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @sharpee/stdlib/channels — media `IOChannel` definitions.
+ *
+ * Owner context: stdlib language layer. The platform media-channel
+ * vocabulary from ADR-163 §7. Each channel is capability-gated; the
+ * `ChannelService` filters gated channels out of the per-client
+ * manifest using `IOChannel.gatedBy`.
+ *
+ * Closures listen for the corresponding `media.*` event type on the
+ * turn's `events` array and project the event's payload (with the two
+ * ADR-163 §7 renames: `media.sound.play` `channel?` → `bus?`;
+ * `media.image.show` hotspots `action` → `command`; and the §9 drop
+ * of `media.animation.play.onComplete`).
+ *
+ * Hide/stop events (`media.image.hide`, `media.music.stop`,
+ * `media.ambient.stop`) emit `null` on the corresponding replace-mode
+ * media channel — the renderer interprets `null` as "hide / stop".
+ *
+ * **Dynamic channels** — `image:<layer>` (custom layer beyond
+ * `image:background`/`image:main`/`image:overlay`) and `ambient:<id>`
+ * are NOT registered here. Stories register them through their own
+ * `Story.registerChannels` hook; `createAmbientChannel(id)` and
+ * `createImageChannel(layer)` are convenience builders.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §7, §9
+ */
+import type { IOChannel } from "../../if-domain/index";
+import type { ISemanticEvent } from "../../core/index";
+/**
+ * Media event types from ADR-101 (folded into channel emissions per
+ * ADR-163 §7).
+ */
+export declare const MEDIA_EVENT_TYPES: {
+    readonly IMAGE_SHOW: "media.image.show";
+    readonly IMAGE_HIDE: "media.image.hide";
+    readonly IMAGE_PRELOAD: "media.image.preload";
+    readonly SOUND_PLAY: "media.sound.play";
+    readonly MUSIC_PLAY: "media.music.play";
+    readonly MUSIC_STOP: "media.music.stop";
+    readonly AMBIENT_PLAY: "media.ambient.play";
+    readonly AMBIENT_STOP: "media.ambient.stop";
+    readonly ANIMATION_PLAY: "media.animation.play";
+    readonly ANIMATE: "media.animate";
+    readonly TRANSITION: "media.transition";
+    readonly LAYOUT_CONFIGURE: "media.layout.configure";
+    readonly CLEAR: "media.clear";
+};
+export type MediaEventType = (typeof MEDIA_EVENT_TYPES)[keyof typeof MEDIA_EVENT_TYPES];
+/**
+ * Resolve the `image:<layer>` channel id from a `media.image.show` /
+ * `media.image.hide` event payload. Defaults to `image:main`.
+ */
+export declare function imageChannelIdFromEvent(event: ISemanticEvent): string;
+/**
+ * Construct an `image:<layer>` `IOChannel`. Standard layers
+ * (`background`, `main`, `overlay`) are pre-registered; stories add
+ * additional layers via this builder.
+ */
+export declare function createImageChannel(layer: string): IOChannel;
+export declare const imageBackgroundChannel: IOChannel;
+export declare const imageMainChannel: IOChannel;
+export declare const imageOverlayChannel: IOChannel;
+/**
+ * `image:preload` — event-mode preload trigger. Renderers download
+ * the asset; not displayed.
+ */
+export declare const imagePreloadChannel: IOChannel;
+/**
+ * `sound` — event-mode sound effect.
+ */
+export declare const soundChannel: IOChannel;
+/**
+ * `music` — replace-mode music track. `null` emission (from
+ * `media.music.stop`) signals "stop".
+ */
+export declare const musicChannel: IOChannel;
+/**
+ * Construct an `ambient:<id>` `IOChannel`. Ambient channels are
+ * inherently story-defined (ADR-163 §7) — the platform has no
+ * predetermined ambient ids. Stories call this once per ambient
+ * layer they need.
+ *
+ * @param ambientId — suffix portion (e.g., `'wind'` registers
+ *   `ambient:wind`).
+ */
+export declare function createAmbientChannel(ambientId: string): IOChannel;
+/**
+ * `animation` — event-mode CSS-style animation. Drops `onComplete`
+ * per ADR-163 §9.
+ */
+export declare const animationChannel: IOChannel;
+/**
+ * `animate` — event-mode generic animation directive.
+ */
+export declare const animateChannel: IOChannel;
+/**
+ * `transition` — event-mode scene transition.
+ */
+export declare const transitionChannel: IOChannel;
+/**
+ * `layout` — replace-mode layout configuration. Persistent across
+ * mid-session joins so a late-joining renderer sees the current
+ * layout without waiting for a re-emission.
+ */
+export declare const layoutChannel: IOChannel;
+/**
+ * `clear` — event-mode truncation signal. Operates on append-mode
+ * channels (notably `main`); ungated because every renderer needs to
+ * be able to reset accumulated prose.
+ */
+export declare const clearChannel: IOChannel;
+/**
+ * Static media channels in iteration order — the ones the platform
+ * pre-registers regardless of story. Dynamic image layers (beyond
+ * the three above) and ambient channels are story-registered.
+ */
+export declare const MEDIA_CHANNELS: ReadonlyArray<IOChannel>;
+/**
+ * Channel id literals for the static media set.
+ */
+export declare const MEDIA_CHANNEL_IDS: {
+    readonly IMAGE_PRELOAD: "image:preload";
+    readonly IMAGE_BACKGROUND: "image:background";
+    readonly IMAGE_MAIN: "image:main";
+    readonly IMAGE_OVERLAY: "image:overlay";
+    readonly SOUND: "sound";
+    readonly MUSIC: "music";
+    readonly ANIMATION: "animation";
+    readonly ANIMATE: "animate";
+    readonly TRANSITION: "transition";
+    readonly LAYOUT: "layout";
+    readonly CLEAR: "clear";
+};
+export type MediaChannelId = (typeof MEDIA_CHANNEL_IDS)[keyof typeof MEDIA_CHANNEL_IDS];
+//# sourceMappingURL=media.d.ts.map

package/channels/media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/stdlib/src/channels/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,oBAAoB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;CAcpB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AA4E7D;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAIrE;AA2BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAS3D;AAED,eAAO,MAAM,sBAAsB,EAAE,SAA4C,CAAC;AAClF,eAAO,MAAM,gBAAgB,EAAE,SAAsC,CAAC;AACtE,eAAO,MAAM,mBAAmB,EAAE,SAAyC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAUjC,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,SAW1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,SAmB1B,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAwBjE;AAMD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAW9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,SAU5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAU/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAU3B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAU1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,CAYnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;CAYpB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC"}

package/channels/media.js

@@ -0,0 +1,397 @@
+"use strict";
+/**
+ * @sharpee/stdlib/channels — media `IOChannel` definitions.
+ *
+ * Owner context: stdlib language layer. The platform media-channel
+ * vocabulary from ADR-163 §7. Each channel is capability-gated; the
+ * `ChannelService` filters gated channels out of the per-client
+ * manifest using `IOChannel.gatedBy`.
+ *
+ * Closures listen for the corresponding `media.*` event type on the
+ * turn's `events` array and project the event's payload (with the two
+ * ADR-163 §7 renames: `media.sound.play` `channel?` → `bus?`;
+ * `media.image.show` hotspots `action` → `command`; and the §9 drop
+ * of `media.animation.play.onComplete`).
+ *
+ * Hide/stop events (`media.image.hide`, `media.music.stop`,
+ * `media.ambient.stop`) emit `null` on the corresponding replace-mode
+ * media channel — the renderer interprets `null` as "hide / stop".
+ *
+ * **Dynamic channels** — `image:<layer>` (custom layer beyond
+ * `image:background`/`image:main`/`image:overlay`) and `ambient:<id>`
+ * are NOT registered here. Stories register them through their own
+ * `Story.registerChannels` hook; `createAmbientChannel(id)` and
+ * `createImageChannel(layer)` are convenience builders.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §7, §9
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEDIA_CHANNEL_IDS = exports.MEDIA_CHANNELS = exports.clearChannel = exports.layoutChannel = exports.transitionChannel = exports.animateChannel = exports.animationChannel = exports.musicChannel = exports.soundChannel = exports.imagePreloadChannel = exports.imageOverlayChannel = exports.imageMainChannel = exports.imageBackgroundChannel = exports.MEDIA_EVENT_TYPES = void 0;
+exports.imageChannelIdFromEvent = imageChannelIdFromEvent;
+exports.createImageChannel = createImageChannel;
+exports.createAmbientChannel = createAmbientChannel;
+/**
+ * Media event types from ADR-101 (folded into channel emissions per
+ * ADR-163 §7).
+ */
+exports.MEDIA_EVENT_TYPES = {
+    IMAGE_SHOW: 'media.image.show',
+    IMAGE_HIDE: 'media.image.hide',
+    IMAGE_PRELOAD: 'media.image.preload',
+    SOUND_PLAY: 'media.sound.play',
+    MUSIC_PLAY: 'media.music.play',
+    MUSIC_STOP: 'media.music.stop',
+    AMBIENT_PLAY: 'media.ambient.play',
+    AMBIENT_STOP: 'media.ambient.stop',
+    ANIMATION_PLAY: 'media.animation.play',
+    ANIMATE: 'media.animate',
+    TRANSITION: 'media.transition',
+    LAYOUT_CONFIGURE: 'media.layout.configure',
+    CLEAR: 'media.clear',
+};
+/**
+ * Find the most recent event of the given type in this turn's events,
+ * or `undefined` if none. Last-wins per turn (replace mode) — when an
+ * action fires the same media event twice in one turn, the renderer
+ * sees the second one.
+ */
+function lastEventOfType(ctx, type) {
+    let last;
+    for (const event of ctx.events) {
+        if (event.type === type)
+            last = event;
+    }
+    return last;
+}
+/**
+ * Iterate every event of the given type — used by event-mode media
+ * channels where multiple firings within one turn collapse to the
+ * last (event channels carry the closure's last return value per
+ * ChannelService). For these the iteration order is irrelevant —
+ * `lastEventOfType` is sufficient.
+ */
+const _firstEventOfType = lastEventOfType;
+void _firstEventOfType;
+/**
+ * `media.sound.play` payload rename: `channel?` field on the event
+ * becomes `bus?` on the wire. Other fields pass through. The rename
+ * avoids confusion with the wire's "channel" concept (ADR-163 §7).
+ */
+function renameSoundChannelToBus(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    const record = data;
+    if (!('channel' in record))
+        return record;
+    const { channel, ...rest } = record;
+    return { ...rest, bus: channel };
+}
+/**
+ * `media.image.show` hotspot rename: `hotspots[].action` → `command`
+ * (ADR-163 §7). Other hotspot and payload fields pass through.
+ */
+function renameImageHotspotsActionToCommand(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    const record = data;
+    const hotspots = record.hotspots;
+    if (!Array.isArray(hotspots))
+        return record;
+    return {
+        ...record,
+        hotspots: hotspots.map((h) => {
+            if (!h || typeof h !== 'object')
+                return h;
+            const hotspot = h;
+            if (!('action' in hotspot))
+                return hotspot;
+            const { action, ...rest } = hotspot;
+            return { ...rest, command: action };
+        }),
+    };
+}
+/**
+ * `media.animation.play` payload drop: remove `onComplete`. ADR-163
+ * §9 declares triggers one-way; the engine doesn't track UI
+ * completion, so the field has no semantic carrier.
+ */
+function dropOnComplete(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    const record = data;
+    if (!('onComplete' in record))
+        return record;
+    const { onComplete: _drop, ...rest } = record;
+    return rest;
+}
+/**
+ * Resolve the `image:<layer>` channel id from a `media.image.show` /
+ * `media.image.hide` event payload. Defaults to `image:main`.
+ */
+function imageChannelIdFromEvent(event) {
+    const data = event.data;
+    const layer = data?.layer ?? 'main';
+    return `image:${layer}`;
+}
+// ────────────────────────────────────────────────────────────────────
+//  Standard image-layer channels (image:background / :main / :overlay)
+// ────────────────────────────────────────────────────────────────────
+function imageLayerProduce(layer) {
+    const channelId = `image:${layer}`;
+    return (ctx) => {
+        let lastShow;
+        let lastHide;
+        for (const event of ctx.events) {
+            if (event.type === exports.MEDIA_EVENT_TYPES.IMAGE_SHOW) {
+                if (imageChannelIdFromEvent(event) === channelId)
+                    lastShow = event;
+            }
+            else if (event.type === exports.MEDIA_EVENT_TYPES.IMAGE_HIDE) {
+                if (imageChannelIdFromEvent(event) === channelId)
+                    lastHide = event;
+            }
+        }
+        // Hide-after-show within the same turn → hide wins.
+        if (lastHide && (!lastShow || ctx.events.indexOf(lastHide) > ctx.events.indexOf(lastShow))) {
+            return null;
+        }
+        if (lastShow)
+            return renameImageHotspotsActionToCommand(lastShow.data);
+        return undefined;
+    };
+}
+/**
+ * Construct an `image:<layer>` `IOChannel`. Standard layers
+ * (`background`, `main`, `overlay`) are pre-registered; stories add
+ * additional layers via this builder.
+ */
+function createImageChannel(layer) {
+    return {
+        id: `image:${layer}`,
+        contentType: 'json',
+        mode: 'replace',
+        emit: 'always',
+        gatedBy: 'images',
+        produce: imageLayerProduce(layer),
+    };
+}
+exports.imageBackgroundChannel = createImageChannel('background');
+exports.imageMainChannel = createImageChannel('main');
+exports.imageOverlayChannel = createImageChannel('overlay');
+/**
+ * `image:preload` — event-mode preload trigger. Renderers download
+ * the asset; not displayed.
+ */
+exports.imagePreloadChannel = {
+    id: 'image:preload',
+    contentType: 'json',
+    mode: 'event',
+    emit: 'sparse',
+    gatedBy: 'images',
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.IMAGE_PRELOAD);
+        return event ? event.data : undefined;
+    },
+};
+// ────────────────────────────────────────────────────────────────────
+//  Audio channels
+// ────────────────────────────────────────────────────────────────────
+/**
+ * `sound` — event-mode sound effect.
+ */
+exports.soundChannel = {
+    id: 'sound',
+    contentType: 'json',
+    mode: 'event',
+    emit: 'sparse',
+    gatedBy: 'sound',
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.SOUND_PLAY);
+        if (!event)
+            return undefined;
+        return renameSoundChannelToBus(event.data);
+    },
+};
+/**
+ * `music` — replace-mode music track. `null` emission (from
+ * `media.music.stop`) signals "stop".
+ */
+exports.musicChannel = {
+    id: 'music',
+    contentType: 'json',
+    mode: 'replace',
+    emit: 'always',
+    gatedBy: 'music',
+    produce: (ctx) => {
+        let lastPlay;
+        let lastStop;
+        for (const event of ctx.events) {
+            if (event.type === exports.MEDIA_EVENT_TYPES.MUSIC_PLAY)
+                lastPlay = event;
+            else if (event.type === exports.MEDIA_EVENT_TYPES.MUSIC_STOP)
+                lastStop = event;
+        }
+        if (lastStop && (!lastPlay || ctx.events.indexOf(lastStop) > ctx.events.indexOf(lastPlay))) {
+            return null;
+        }
+        if (lastPlay)
+            return lastPlay.data;
+        return undefined;
+    },
+};
+// ────────────────────────────────────────────────────────────────────
+//  Ambient channels — dynamic, story-registered
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Construct an `ambient:<id>` `IOChannel`. Ambient channels are
+ * inherently story-defined (ADR-163 §7) — the platform has no
+ * predetermined ambient ids. Stories call this once per ambient
+ * layer they need.
+ *
+ * @param ambientId — suffix portion (e.g., `'wind'` registers
+ *   `ambient:wind`).
+ */
+function createAmbientChannel(ambientId) {
+    const channelId = `ambient:${ambientId}`;
+    return {
+        id: channelId,
+        contentType: 'json',
+        mode: 'replace',
+        emit: 'always',
+        gatedBy: 'sound',
+        produce: (ctx) => {
+            let lastPlay;
+            let lastStop;
+            for (const event of ctx.events) {
+                const data = event.data;
+                if (data?.channel !== ambientId)
+                    continue;
+                if (event.type === exports.MEDIA_EVENT_TYPES.AMBIENT_PLAY)
+                    lastPlay = event;
+                else if (event.type === exports.MEDIA_EVENT_TYPES.AMBIENT_STOP)
+                    lastStop = event;
+            }
+            if (lastStop && (!lastPlay || ctx.events.indexOf(lastStop) > ctx.events.indexOf(lastPlay))) {
+                return null;
+            }
+            if (lastPlay)
+                return lastPlay.data;
+            return undefined;
+        },
+    };
+}
+// ────────────────────────────────────────────────────────────────────
+//  Animation / transition / layout / clear
+// ────────────────────────────────────────────────────────────────────
+/**
+ * `animation` — event-mode CSS-style animation. Drops `onComplete`
+ * per ADR-163 §9.
+ */
+exports.animationChannel = {
+    id: 'animation',
+    contentType: 'json',
+    mode: 'event',
+    emit: 'sparse',
+    gatedBy: 'animations',
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.ANIMATION_PLAY);
+        if (!event)
+            return undefined;
+        return dropOnComplete(event.data);
+    },
+};
+/**
+ * `animate` — event-mode generic animation directive.
+ */
+exports.animateChannel = {
+    id: 'animate',
+    contentType: 'json',
+    mode: 'event',
+    emit: 'sparse',
+    gatedBy: 'animations',
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.ANIMATE);
+        return event ? event.data : undefined;
+    },
+};
+/**
+ * `transition` — event-mode scene transition.
+ */
+exports.transitionChannel = {
+    id: 'transition',
+    contentType: 'json',
+    mode: 'event',
+    emit: 'sparse',
+    gatedBy: 'transitions',
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.TRANSITION);
+        return event ? event.data : undefined;
+    },
+};
+/**
+ * `layout` — replace-mode layout configuration. Persistent across
+ * mid-session joins so a late-joining renderer sees the current
+ * layout without waiting for a re-emission.
+ */
+exports.layoutChannel = {
+    id: 'layout',
+    contentType: 'json',
+    mode: 'replace',
+    emit: 'always',
+    gatedBy: 'splitPane',
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.LAYOUT_CONFIGURE);
+        return event ? event.data : undefined;
+    },
+};
+/**
+ * `clear` — event-mode truncation signal. Operates on append-mode
+ * channels (notably `main`); ungated because every renderer needs to
+ * be able to reset accumulated prose.
+ */
+exports.clearChannel = {
+    id: 'clear',
+    contentType: 'json',
+    mode: 'event',
+    emit: 'sparse',
+    // Intentionally not gated — clear must be available on every surface.
+    produce: (ctx) => {
+        const event = lastEventOfType(ctx, exports.MEDIA_EVENT_TYPES.CLEAR);
+        return event ? (event.data ?? {}) : undefined;
+    },
+};
+/**
+ * Static media channels in iteration order — the ones the platform
+ * pre-registers regardless of story. Dynamic image layers (beyond
+ * the three above) and ambient channels are story-registered.
+ */
+exports.MEDIA_CHANNELS = [
+    exports.imagePreloadChannel,
+    exports.imageBackgroundChannel,
+    exports.imageMainChannel,
+    exports.imageOverlayChannel,
+    exports.soundChannel,
+    exports.musicChannel,
+    exports.animationChannel,
+    exports.animateChannel,
+    exports.transitionChannel,
+    exports.layoutChannel,
+    exports.clearChannel,
+];
+/**
+ * Channel id literals for the static media set.
+ */
+exports.MEDIA_CHANNEL_IDS = {
+    IMAGE_PRELOAD: 'image:preload',
+    IMAGE_BACKGROUND: 'image:background',
+    IMAGE_MAIN: 'image:main',
+    IMAGE_OVERLAY: 'image:overlay',
+    SOUND: 'sound',
+    MUSIC: 'music',
+    ANIMATION: 'animation',
+    ANIMATE: 'animate',
+    TRANSITION: 'transition',
+    LAYOUT: 'layout',
+    CLEAR: 'clear',
+};
+//# sourceMappingURL=media.js.map

package/channels/media.js.map

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

package/channels/registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @sharpee/stdlib/channels — channel registry instance.
+ *
+ * Owner context: stdlib language layer. Hosts the canonical
+ * `IChannelRegistry` instance for Sharpee's channel-I/O system.
+ * Engine bootstrap imports this instance, lets stories register their
+ * channels onto it (`Story.registerChannels?.(registry)`), then hands
+ * it to a fresh `ChannelService` (per ADR-163 §13, §14).
+ *
+ * The instance is populated at module init with the ten standard
+ * channels and the eleven static media channels. The `Story.registerChannels`
+ * hook may add story-specific channels or override standards by
+ * re-registering with the same id (last-write-wins per ADR-163 §6).
+ *
+ * Lifecycle: a fresh `ChannelService` is created per session
+ * (engine restart, RESTART command). The registry itself is reused —
+ * stdlib's standard channels stay registered across sessions, and the
+ * `ChannelService`'s per-session `prevValues` map provides the
+ * isolation. The Story.registerChannels hook is invoked once per
+ * engine bootstrap; if a story overrides a standard channel, that
+ * override persists for the lifetime of the engine instance.
+ *
+ * Tests can construct their own `IChannelRegistry` instance for
+ * isolation (unit tests should not depend on this singleton's
+ * pre-populated state for behavior-specific assertions).
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §7, §13, §14
+ */
+import type { IChannelRegistry, IOChannel } from "../../if-domain/index";
+/**
+ * In-memory `IChannelRegistry` implementation. Last-write-wins on
+ * `add(channel)` by `channel.id` — which is how stories override
+ * platform standards (ADR-163 §6).
+ */
+export declare class StdlibChannelRegistry implements IChannelRegistry {
+    private readonly channels;
+    add(channel: IOChannel): void;
+    get(id: string): IOChannel | undefined;
+    all(): readonly IOChannel[];
+    /**
+     * Test-only helper: snapshot the current channel ids. Stable
+     * iteration order matches insertion order (Map semantics).
+     */
+    ids(): readonly string[];
+}
+/**
+ * The canonical channel registry instance for Sharpee. Pre-populated
+ * with ten standard channels (`main`, `prompt`, `score`, `turn`,
+ * `location`, `info`, `ifid`, `death`, `endgame`, `score_notify`)
+ * plus eleven static media channels (`image:preload`,
+ * `image:background`, `image:main`, `image:overlay`, `sound`,
+ * `music`, `animation`, `animate`, `transition`, `layout`, `clear`).
+ *
+ * Engine bootstrap consumes this directly; stories extend through
+ * the `Story.registerChannels?(registry)` hook.
+ */
+export declare const channelRegistry: IChannelRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/channels/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/stdlib/src/channels/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAKtE;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IAEzD,GAAG,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;IAI7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAItC,GAAG,IAAI,SAAS,SAAS,EAAE;IAI3B;;;OAGG;IACH,GAAG,IAAI,SAAS,MAAM,EAAE;CAGzB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,gBAY1B,CAAC"}