@lumencast/protocol 0.1.0

package/dist/conformance/placeholders.js

@@ -0,0 +1,40 @@
+// Placeholder substitution for scenarios.
+//
+// Two placeholder families :
+//   - $TOKEN_OPERATOR / $TOKEN_VIEWER / $TOKEN_SERVICE / $TOKEN_TEST / $TOKEN_INVALID
+//     → live token strings supplied by the harness via /test/setup
+//   - $BUNDLE.<id>.hash
+//     → sha256:<hex> of the inline bundle declared in scenario.bundles
+//
+// Unknown placeholders pass through verbatim. Some scenarios rely on this
+// (auth-denied uses $TOKEN_INVALID literally because the server should reject
+// any value the harness substitutes — cleaner to send the literal string).
+const TOKEN_PREFIX = "$TOKEN_";
+const BUNDLE_PREFIX = "$BUNDLE.";
+const BUNDLE_SUFFIX = ".hash";
+export function substitute(value, tokens, bundleHashes) {
+    if (typeof value === "string") {
+        if (value.startsWith(TOKEN_PREFIX)) {
+            const replacement = tokens[value];
+            return replacement ?? value;
+        }
+        if (value.startsWith(BUNDLE_PREFIX) && value.endsWith(BUNDLE_SUFFIX)) {
+            const id = value.slice(BUNDLE_PREFIX.length, value.length - BUNDLE_SUFFIX.length);
+            const hash = bundleHashes[id];
+            return hash ?? value;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => substitute(v, tokens, bundleHashes));
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = substitute(v, tokens, bundleHashes);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=placeholders.js.map

package/dist/conformance/placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.js","sourceRoot":"","sources":["../../src/conformance/placeholders.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,6BAA6B;AAC7B,sFAAsF;AACtF,mEAAmE;AACnE,wBAAwB;AACxB,uEAAuE;AACvE,EAAE;AACF,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAE3E,MAAM,YAAY,GAAG,SAAS,CAAC;AAC/B,MAAM,aAAa,GAAG,UAAU,CAAC;AACjC,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B,MAAM,UAAU,UAAU,CACxB,KAAc,EACd,MAA8B,EAC9B,YAAoC;IAEpC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACnC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAClC,OAAO,WAAW,IAAI,KAAK,CAAC;QAC9B,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;YACrE,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;YAClF,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;YAC9B,OAAO,IAAI,IAAI,KAAK,CAAC;QACvB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/conformance/scenario.d.ts

@@ -0,0 +1,33 @@
+export type Tag = "required" | "recommended" | "extended";
+export type Target = "any" | "server" | "runtime";
+export type StepKind = "client-sends" | "server-sends" | "server-emits" | "expect-runtime-state" | "expect-server-state" | "expect-no-frame-for" | "expect-client-action";
+export type ClientAction = "close-with-reason" | "reconnect";
+export interface Step {
+    kind: StepKind;
+    /** client-sends, server-sends */
+    frame?: Record<string, unknown>;
+    /** expect-runtime-state, expect-server-state */
+    state?: Record<string, unknown>;
+    /** expect-no-frame-for */
+    duration_ms?: number;
+    /** expect-client-action */
+    action?: ClientAction;
+    reason?: string;
+}
+export interface BundleDecl {
+    id: string;
+    inline: Record<string, unknown>;
+    /** sha256:<hex> — populated lazily by computeBundleHashes(). */
+    hash?: string;
+}
+export interface Scenario {
+    name: string;
+    description: string;
+    tag: Tag;
+    target: Target;
+    spec_refs?: string[];
+    bundles?: BundleDecl[];
+    steps: Step[];
+}
+export declare function parseScenario(raw: string): Scenario;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/conformance/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../src/conformance/scenario.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC;AAC1D,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,MAAM,MAAM,QAAQ,GAChB,cAAc,GACd,cAAc,GACd,cAAc,GACd,sBAAsB,GACtB,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,WAAW,CAAC;AAE7D,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAoBnD"}

package/dist/conformance/scenario.js

@@ -0,0 +1,26 @@
+// Scenario YAML loader. Mirrors the Go reference at
+// lumencast-go/conformance/scenario.go and the contract in
+// lumencast-protocol/conformance/v1/SCENARIO-FORMAT.md.
+import { parse as parseYaml } from "yaml";
+export function parseScenario(raw) {
+    const obj = parseYaml(raw);
+    if (!obj || typeof obj !== "object") {
+        throw new Error("scenario: not a YAML mapping");
+    }
+    if (!obj.name)
+        throw new Error("scenario: missing name");
+    if (!Array.isArray(obj.steps))
+        throw new Error("scenario: missing steps[]");
+    const tag = obj.tag ?? "required";
+    const target = obj.target ?? "any";
+    return {
+        name: obj.name,
+        description: obj.description ?? "",
+        tag,
+        target,
+        ...(obj.spec_refs ? { spec_refs: obj.spec_refs } : {}),
+        ...(obj.bundles ? { bundles: obj.bundles } : {}),
+        steps: obj.steps,
+    };
+}
+//# sourceMappingURL=scenario.js.map

package/dist/conformance/scenario.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../../src/conformance/scenario.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,2DAA2D;AAC3D,wDAAwD;AAExD,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AA8C1C,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAkC,CAAC;IAC5D,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAE5E,MAAM,GAAG,GAAS,GAAG,CAAC,GAAuB,IAAI,UAAU,CAAC;IAC5D,MAAM,MAAM,GAAY,GAAG,CAAC,MAA6B,IAAI,KAAK,CAAC;IAEnE,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;QAClC,GAAG;QACH,MAAM;QACN,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAuB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,KAAK,EAAE,GAAG,CAAC,KAAe;KAC3B,CAAC;AACJ,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,66 @@
+import { type Cause, type DeltaFrame, type ErrorCode, type ErrorFrame, type InputFrame, type LeafPath, type LeafValue, type Patch, type PingFrame, type PongFrame, type SceneChangedFrame, type SceneId, type SceneTransition, type SceneVersion, type SessionId, type SnapshotFrame, type SubscribeFrame, type UnsubscribeFrame } from "./types.js";
+export interface SnapshotInit {
+    seq: number;
+    scene_id: SceneId;
+    scene_version: SceneVersion;
+    state: Record<LeafPath, LeafValue>;
+    ts?: string;
+}
+export declare function snapshot(init: SnapshotInit): SnapshotFrame;
+export interface DeltaInit {
+    seq: number;
+    patches: Patch[];
+    ts?: string;
+    /** LSDP/1.1 §3.2.3 — optional provenance metadata. */
+    cause?: Cause;
+}
+export declare function delta(init: DeltaInit): DeltaFrame;
+export interface SceneChangedInit {
+    seq: number;
+    scene_id: SceneId;
+    scene_version: SceneVersion;
+    ts?: string;
+    /** LSDP/1.1 §3.3.1 — previously active scene id. */
+    from_scene_id?: SceneId;
+    /** LSDP/1.1 §3.3.1 — show-level scene transition. */
+    transition?: SceneTransition;
+}
+export declare function sceneChanged(init: SceneChangedInit): SceneChangedFrame;
+export interface ErrorInit {
+    seq: number;
+    code: ErrorCode;
+    message: string;
+    recoverable: boolean;
+    /**
+     * REQUIRED for path-scoped codes (`WRITE_FORBIDDEN`, `UNKNOWN_PATH`,
+     * `INVALID_VALUE`) per LSDP/1.0.1 §3.4.1.
+     */
+    path?: LeafPath;
+    retry_after_ms?: number;
+    requested_version?: string;
+    supported_version?: string;
+    session?: string;
+    ts?: string;
+}
+export declare function errorFrame(init: ErrorInit): ErrorFrame;
+export declare function pong(nonce?: string): PongFrame;
+export interface SubscribeInit {
+    token: string;
+    scene?: SceneId;
+    session?: SessionId;
+    /** LSDP/1.1 §4.1 — incremental resume from a known last-seen seq. */
+    since_sequence?: number;
+}
+export declare function subscribe(init: SubscribeInit): SubscribeFrame;
+export interface InputInit {
+    patches: Patch[];
+    /** LSDP/1.1 §4.2 — optimistic-UI correlation tag. */
+    client_msg_id?: string;
+}
+export declare function input(patches: Patch[], init?: {
+    client_msg_id?: string;
+}): InputFrame;
+export declare function ping(nonce?: string): PingFrame;
+/** LSDP/1.1 §4.4 — clean teardown signal. */
+export declare function unsubscribe(): UnsubscribeFrame;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

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

package/dist/envelope.js

@@ -0,0 +1,111 @@
+// Envelope helpers — convenience constructors that stamp `v` automatically.
+// Useful when emitting frames from a server or test fixture.
+import { PROTOCOL_VERSION, } from "./types.js";
+export function snapshot(init) {
+    const frame = {
+        v: PROTOCOL_VERSION,
+        type: "snapshot",
+        seq: init.seq,
+        scene_id: init.scene_id,
+        scene_version: init.scene_version,
+        state: init.state,
+    };
+    if (init.ts !== undefined)
+        frame.ts = init.ts;
+    return frame;
+}
+export function delta(init) {
+    if (init.patches.length === 0) {
+        throw new Error("delta.patches must be non-empty");
+    }
+    const frame = {
+        v: PROTOCOL_VERSION,
+        type: "delta",
+        seq: init.seq,
+        patches: init.patches,
+    };
+    if (init.ts !== undefined)
+        frame.ts = init.ts;
+    if (init.cause !== undefined)
+        frame.cause = init.cause;
+    return frame;
+}
+export function sceneChanged(init) {
+    const frame = {
+        v: PROTOCOL_VERSION,
+        type: "scene_changed",
+        seq: init.seq,
+        scene_id: init.scene_id,
+        scene_version: init.scene_version,
+    };
+    if (init.ts !== undefined)
+        frame.ts = init.ts;
+    if (init.from_scene_id !== undefined)
+        frame.from_scene_id = init.from_scene_id;
+    if (init.transition !== undefined)
+        frame.transition = init.transition;
+    return frame;
+}
+export function errorFrame(init) {
+    const frame = {
+        v: PROTOCOL_VERSION,
+        type: "error",
+        seq: init.seq,
+        code: init.code,
+        message: init.message,
+        recoverable: init.recoverable,
+    };
+    if (init.path !== undefined)
+        frame.path = init.path;
+    if (init.retry_after_ms !== undefined)
+        frame.retry_after_ms = init.retry_after_ms;
+    if (init.requested_version !== undefined)
+        frame.requested_version = init.requested_version;
+    if (init.supported_version !== undefined)
+        frame.supported_version = init.supported_version;
+    if (init.session !== undefined)
+        frame.session = init.session;
+    if (init.ts !== undefined)
+        frame.ts = init.ts;
+    return frame;
+}
+export function pong(nonce) {
+    const frame = { v: PROTOCOL_VERSION, type: "pong" };
+    if (nonce !== undefined)
+        frame.nonce = nonce;
+    return frame;
+}
+export function subscribe(init) {
+    const frame = {
+        v: PROTOCOL_VERSION,
+        type: "subscribe",
+        token: init.token,
+    };
+    if (init.scene !== undefined)
+        frame.scene = init.scene;
+    if (init.session !== undefined)
+        frame.session = init.session;
+    if (init.since_sequence !== undefined)
+        frame.since_sequence = init.since_sequence;
+    return frame;
+}
+export function input(patches, init) {
+    if (patches.length === 0) {
+        throw new Error("input.patches must be non-empty");
+    }
+    const frame = { v: PROTOCOL_VERSION, type: "input", patches };
+    if (init?.client_msg_id !== undefined)
+        frame.client_msg_id = init.client_msg_id;
+    return frame;
+}
+export function ping(nonce) {
+    const frame = { v: PROTOCOL_VERSION, type: "ping" };
+    if (nonce !== undefined)
+        frame.nonce = nonce;
+    return frame;
+}
+/** LSDP/1.1 §4.4 — clean teardown signal. */
+export function unsubscribe() {
+    return { v: PROTOCOL_VERSION, type: "unsubscribe" };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+import type { ErrorCode } from "./types.js";
+export declare function isProtocolErrorCode(value: unknown): value is ErrorCode;
+export interface LumencastErrorInit {
+    code: ErrorCode;
+    message: string;
+    recoverable: boolean;
+    /**
+     * REQUIRED for path-scoped codes (`WRITE_FORBIDDEN`, `UNKNOWN_PATH`,
+     * `INVALID_VALUE`) per LSDP/1.0.1 §3.4.1.
+     */
+    path?: string;
+    retry_after_ms?: number;
+}
+/**
+ * Typed runtime exception. Mirrors the shape of an LSDP `error` frame so that
+ * runtime hosts can match `error.code` against the closed taxonomy.
+ */
+export declare class LumencastError extends Error {
+    readonly code: ErrorCode;
+    readonly recoverable: boolean;
+    readonly path: string | undefined;
+    readonly retry_after_ms: number | undefined;
+    constructor(init: LumencastErrorInit);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAiB5C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAEtE;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEhC,IAAI,EAAE,kBAAkB;CAQrC"}

package/dist/errors.js

@@ -0,0 +1,38 @@
+// Error helpers — typed exception + code-set membership check.
+// Code semantics live in lumencast-protocol/spec/ERROR-CODES.md.
+const ERROR_CODES = new Set([
+    "AUTH_DENIED",
+    "WRITE_FORBIDDEN",
+    "SCENE_NOT_FOUND",
+    "BUNDLE_FETCH_FAILED",
+    "BUNDLE_INCOMPATIBLE",
+    "VERSION_GAP",
+    "VERSION_MISMATCH",
+    "UNKNOWN_PATH",
+    "INVALID_VALUE",
+    "RATE_LIMIT",
+    "TEST_SESSION_EXPIRED",
+    "INTERNAL",
+]);
+export function isProtocolErrorCode(value) {
+    return typeof value === "string" && ERROR_CODES.has(value);
+}
+/**
+ * Typed runtime exception. Mirrors the shape of an LSDP `error` frame so that
+ * runtime hosts can match `error.code` against the closed taxonomy.
+ */
+export class LumencastError extends Error {
+    code;
+    recoverable;
+    path;
+    retry_after_ms;
+    constructor(init) {
+        super(init.message);
+        this.name = "LumencastError";
+        this.code = init.code;
+        this.recoverable = init.recoverable;
+        this.path = init.path;
+        this.retry_after_ms = init.retry_after_ms;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,iEAAiE;AAIjE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAY;IACrC,aAAa;IACb,iBAAiB;IACjB,iBAAiB;IACjB,qBAAqB;IACrB,qBAAqB;IACrB,aAAa;IACb,kBAAkB;IAClB,cAAc;IACd,eAAe;IACf,YAAY;IACZ,sBAAsB;IACtB,UAAU;CACX,CAAC,CAAC;AAEH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,WAAW,CAAC,GAAG,CAAC,KAAkB,CAAC,CAAC;AAC1E,CAAC;AAcD;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAY;IAChB,WAAW,CAAU;IACrB,IAAI,CAAqB;IACzB,cAAc,CAAqB;IAE5C,YAAY,IAAwB;QAClC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;IAC5C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { PROTOCOL_VERSION, WS_SUBPROTOCOL, WS_SUBPROTOCOL_V1_1, WS_SUBPROTOCOLS, type Cause, type ClientFrame, type DeltaFrame, type ErrorCode, type ErrorFrame, type InputFrame, type LeafPath, type LeafValue, type Patch, type PingFrame, type PongFrame, type SceneChangedFrame, type SceneId, type SceneTransition, type SceneVersion, type ServerFrame, type SessionId, type SnapshotFrame, type SubscribeFrame, type TransitionSpec, type UnsubscribeFrame, } from "./types.js";
+export { LumencastError, isProtocolErrorCode, type LumencastErrorInit } from "./errors.js";
+export { encodeFrame, decodeServerFrame, decodeClientFrame } from "./codec.js";
+export { SequenceTracker, type SequenceObservation } from "./sequence.js";
+export { RESERVED_NAMESPACES, type ReservedNamespace, parseLeafPath, formatLeafPath, isReservedPath, isUnknownReservedPath, substituteScope, } from "./leaf-path.js";
+export { snapshot, delta, sceneChanged, errorFrame, pong, subscribe, input, ping, unsubscribe, type SnapshotInit, type DeltaInit, type SceneChangedInit, type ErrorInit, type SubscribeInit, type InputInit, } from "./envelope.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EACL,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,aAAa,EACb,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,SAAS,EACT,KAAK,EACL,IAAI,EACJ,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public surface of @lumencast/protocol.
+export { PROTOCOL_VERSION, WS_SUBPROTOCOL, WS_SUBPROTOCOL_V1_1, WS_SUBPROTOCOLS, } from "./types.js";
+export { LumencastError, isProtocolErrorCode } from "./errors.js";
+export { encodeFrame, decodeServerFrame, decodeClientFrame } from "./codec.js";
+export { SequenceTracker } from "./sequence.js";
+export { RESERVED_NAMESPACES, parseLeafPath, formatLeafPath, isReservedPath, isUnknownReservedPath, substituteScope, } from "./leaf-path.js";
+export { snapshot, delta, sceneChanged, errorFrame, pong, subscribe, input, ping, unsubscribe, } from "./envelope.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AAEzC,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,eAAe,GAsBhB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAA2B,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,eAAe,EAA4B,MAAM,eAAe,CAAC;AAE1E,OAAO,EACL,mBAAmB,EAEnB,aAAa,EACb,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,SAAS,EACT,KAAK,EACL,IAAI,EACJ,WAAW,GAOZ,MAAM,eAAe,CAAC"}

package/dist/leaf-path.d.ts

@@ -0,0 +1,21 @@
+import type { LeafPath } from "./types.js";
+/** Reserved top-level namespaces per LSDP/1 §10. */
+export declare const RESERVED_NAMESPACES: readonly ["__inputs", "__system", "__test", "__schema"];
+export type ReservedNamespace = (typeof RESERVED_NAMESPACES)[number];
+/** Parse a `LeafPath` string into its segments. Throws on malformed input. */
+export declare function parseLeafPath(path: LeafPath): string[];
+/** Format an array of segments back to a `LeafPath`. */
+export declare function formatLeafPath(segments: string[]): LeafPath;
+/** True if the path begins with a reserved namespace (`__inputs`, `__system`, ...). */
+export declare function isReservedPath(path: LeafPath): boolean;
+/** True if the path begins with `__` but is NOT one of the four declared namespaces. */
+export declare function isUnknownReservedPath(path: LeafPath): boolean;
+/**
+ * Substitute `{scope}` placeholders inside a path template.
+ * Used by `repeat` primitives to bind per-item paths.
+ *
+ * Example: `substituteScope("{player}.score", { player: "players.0" })`
+ *   → "players.0.score"
+ */
+export declare function substituteScope(template: LeafPath, scopes: Record<string, string>): LeafPath;
+//# sourceMappingURL=leaf-path.d.ts.map

package/dist/leaf-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-path.d.ts","sourceRoot":"","sources":["../src/leaf-path.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK3C,oDAAoD;AACpD,eAAO,MAAM,mBAAmB,yDAA0D,CAAC;AAC3F,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAStD;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,CAE3D;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAGtD;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,QAAQ,CAQ5F"}

package/dist/leaf-path.js

@@ -0,0 +1,51 @@
+// LeafPath canonical form + scope substitution.
+// Reference: LSDP/1 §10 (reserved namespaces) and LSML 1.0 §7 (repeat scope).
+/** A path segment is alphanumeric + underscore. Numeric indices are decimal. */
+const SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$|^[0-9]+$/;
+/** Reserved top-level namespaces per LSDP/1 §10. */
+export const RESERVED_NAMESPACES = ["__inputs", "__system", "__test", "__schema"];
+/** Parse a `LeafPath` string into its segments. Throws on malformed input. */
+export function parseLeafPath(path) {
+    if (path.length === 0)
+        throw new Error("leaf-path is empty");
+    const segs = path.split(".");
+    for (const s of segs) {
+        if (!SEGMENT_RE.test(s)) {
+            throw new Error(`leaf-path segment is not valid: ${s}`);
+        }
+    }
+    return segs;
+}
+/** Format an array of segments back to a `LeafPath`. */
+export function formatLeafPath(segments) {
+    return segments.join(".");
+}
+/** True if the path begins with a reserved namespace (`__inputs`, `__system`, ...). */
+export function isReservedPath(path) {
+    const head = path.split(".", 1)[0];
+    return RESERVED_NAMESPACES.includes(head ?? "");
+}
+/** True if the path begins with `__` but is NOT one of the four declared namespaces. */
+export function isUnknownReservedPath(path) {
+    if (!path.startsWith("__"))
+        return false;
+    const head = path.split(".", 1)[0] ?? "";
+    return !RESERVED_NAMESPACES.includes(head);
+}
+/**
+ * Substitute `{scope}` placeholders inside a path template.
+ * Used by `repeat` primitives to bind per-item paths.
+ *
+ * Example: `substituteScope("{player}.score", { player: "players.0" })`
+ *   → "players.0.score"
+ */
+export function substituteScope(template, scopes) {
+    return template.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+        const replacement = scopes[name];
+        if (replacement === undefined) {
+            throw new Error(`unknown scope identifier in path template: ${name}`);
+        }
+        return replacement;
+    });
+}
+//# sourceMappingURL=leaf-path.js.map

package/dist/leaf-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-path.js","sourceRoot":"","sources":["../src/leaf-path.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,8EAA8E;AAI9E,gFAAgF;AAChF,MAAM,UAAU,GAAG,mCAAmC,CAAC;AAEvD,oDAAoD;AACpD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC;AAG3F,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,IAAc;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,OAAQ,mBAAyC,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,qBAAqB,CAAC,IAAc;IAClD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,OAAO,CAAE,mBAAyC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,QAAkB,EAAE,MAA8B;IAChF,OAAO,QAAQ,CAAC,OAAO,CAAC,+BAA+B,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE;QAC3E,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/sequence.d.ts

@@ -0,0 +1,25 @@
+export type SequenceObservation = {
+    kind: "in-order";
+    seq: number;
+} | {
+    kind: "duplicate";
+    seq: number;
+    lastSeq: number;
+} | {
+    kind: "gap";
+    seq: number;
+    lastSeq: number;
+};
+export declare class SequenceTracker {
+    private lastSeq;
+    /** Observe an incoming server seq. Returns the classification. */
+    observe(seq: number): SequenceObservation;
+    /** Rebase the tracker to a snapshot's seq. Called after scene_changed
+     * or back-pressure recovery — the tracker takes the snapshot value as
+     * the new baseline regardless of previous state. */
+    observeSnapshot(seq: number): void;
+    /** Reset the tracker. Called on reconnect with no resume. */
+    reset(): void;
+    get last(): number;
+}
+//# sourceMappingURL=sequence.d.ts.map

package/dist/sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../src/sequence.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAK;IAEpB,kEAAkE;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB;IAqBzC;;wDAEoD;IACpD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMlC,6DAA6D;IAC7D,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/sequence.js

@@ -0,0 +1,51 @@
+// Monotonic sequence tracker with gap detection.
+// LSDP/1.1 §18.1.1: seq is per-scene, NOT per-subscription. The first
+// frame of a fresh subscription can carry any seq >= 1 (late-joining
+// subscribers see the current scene seq). The tracker rebases to the
+// snapshot value after scene_changed via observeSnapshot.
+//
+// Receiver rules:
+//   - first frame on a fresh tracker → establish baseline (any seq >= 1)
+//   - seq > last + 1                 → gap, runtime MUST close + reconnect
+//   - seq <= last                    → replay, runtime MUST drop silently
+//   - seq == last + 1                → in-order, accept
+export class SequenceTracker {
+    lastSeq = 0;
+    /** Observe an incoming server seq. Returns the classification. */
+    observe(seq) {
+        if (!Number.isInteger(seq) || seq < 1) {
+            // Treat malformed seq as a gap so the runtime reconnects.
+            return { kind: "gap", seq, lastSeq: this.lastSeq };
+        }
+        if (this.lastSeq === 0) {
+            // Fresh tracker — any seq >= 1 establishes the baseline
+            // (LSDP/1.1 §18.1.1).
+            this.lastSeq = seq;
+            return { kind: "in-order", seq };
+        }
+        if (seq <= this.lastSeq) {
+            return { kind: "duplicate", seq, lastSeq: this.lastSeq };
+        }
+        if (seq > this.lastSeq + 1) {
+            return { kind: "gap", seq, lastSeq: this.lastSeq };
+        }
+        this.lastSeq = seq;
+        return { kind: "in-order", seq };
+    }
+    /** Rebase the tracker to a snapshot's seq. Called after scene_changed
+     * or back-pressure recovery — the tracker takes the snapshot value as
+     * the new baseline regardless of previous state. */
+    observeSnapshot(seq) {
+        if (Number.isInteger(seq) && seq >= 1) {
+            this.lastSeq = seq;
+        }
+    }
+    /** Reset the tracker. Called on reconnect with no resume. */
+    reset() {
+        this.lastSeq = 0;
+    }
+    get last() {
+        return this.lastSeq;
+    }
+}
+//# sourceMappingURL=sequence.js.map

package/dist/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../src/sequence.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,sEAAsE;AACtE,qEAAqE;AACrE,qEAAqE;AACrE,0DAA0D;AAC1D,EAAE;AACF,kBAAkB;AAClB,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,wDAAwD;AAOxD,MAAM,OAAO,eAAe;IAClB,OAAO,GAAG,CAAC,CAAC;IAEpB,kEAAkE;IAClE,OAAO,CAAC,GAAW;QACjB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACtC,0DAA0D;YAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACrD,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACvB,wDAAwD;YACxD,sBAAsB;YACtB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;YACnB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QACnC,CAAC;QACD,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3D,CAAC;QACD,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACrD,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;IACnC,CAAC;IAED;;wDAEoD;IACpD,eAAe,CAAC,GAAW;QACzB,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACrB,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}