@storylet-studio/play-helpers 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,251 @@
+import { Engine, Flow, LogEntry, EngineLogEntry, BundleDescription, PropertySummary, PropertyScopeSummary, TraceEvent, EngineOptions } from '@storylet-studio/runtime';
+import { StateLoggerOptions, StateLogger, StateSnapshot, PropertyBag as PropertyBag$1 } from '@wildwinter/scoperegistry';
+export { StateChange, StateLogger, StateLoggerAdapter, StateLoggerOptions, StateSnapshot, createStateLogger as createKernelStateLogger, diffState } from '@wildwinter/scoperegistry';
+import { PropertyBag, SaveFile, Bundle } from '@storylet-studio/model';
+
+/** The full flattened snapshot of ONE FLOW's view - the shared partitions
+ *  plus that flow's own - straight off the save envelope, so "what the
+ *  snapshot sees" is by construction "what a save persists". @world is not
+ *  here for the same reason it is not in the envelope: the host owns that
+ *  container and mounts/saves it itself (createWorldContainer). */
+declare function snapshotState(engine: Engine, flow: Flow): StateSnapshot;
+/** The storylets state logger: the kernel core mounted on the SHARED bags
+ *  (engine.listBags()) and one flow's own (flow.listBags()) - the same
+ *  prefixes, one path space, names disjoint - plus the flow's turns /
+ *  cooldowns / board adapter. A host that wants @world lines mounts its
+ *  world container's bag through createKernelStateLogger itself. */
+declare function createStateLogger(engine: Engine, flow: Flow, opts?: StateLoggerOptions): StateLogger;
+
+/** The current engine state (and the host's @world values, if given) as
+ *  pretty-printed .storyletsave JSON. */
+declare function serializeState(engine: Engine, world?: PropertyBag): string;
+/**
+ * Capture the whole engine (and the host's @world values, if it keeps any) as
+ * the tagged save-file OBJECT.
+ *
+ * Four verbs, in Patterplay's pairing (`patter` play-helpers `save.ts`, and
+ * the same in all four of its runtimes): saveState / loadState work on the
+ * PARSED object, serializeState / deserializeState work on TEXT.
+ *
+ * This reference had a different shape until 2026-08-29 - `deserializeState`
+ * parsed and did not restore, `loadState` took text - so one name meant two
+ * things across the four Storylets runtimes, and neither matched the family.
+ * Godot and Unreal already had Patter's shape; these two were brought to it.
+ */
+declare function saveState(engine: Engine, world?: PropertyBag): SaveFile;
+/** Restore a {@link saveState} file into an engine. EVERY FLOW IS REBUILT, so
+ *  the Flow handles you held before are inert: re-take them with
+ *  `engine.getFlow(id)`, NOT `engine.openFlow(id)`. `openFlow` on an existing
+ *  id REPLACES it, which here throws away the hand the file just restored, and
+ *  the failure lands later, as `play()` refusing a card as "not dealt". (The
+ *  engine's `onReplacedFlow` hook reports exactly this.) Throws on a foreign or malformed
+ *  file, and the runtime's own project check still applies. Returns the file's
+ *  @world values, if any - the HOST applies them to its container; the engine
+ *  never touches them. */
+declare function loadState(engine: Engine, file: SaveFile): PropertyBag | undefined;
+/** Parse + restore a {@link serializeState} string: the TEXT twin of
+ *  loadState, as Patterplay pairs them. Throws on malformed JSON, a foreign
+ *  file or a project mismatch. Returns the file's @world values for the host. */
+declare function deserializeState(engine: Engine, json: string): PropertyBag | undefined;
+
+interface PropertyInspectorOptions {
+    /** Mount point; defaults to document.body. */
+    container?: HTMLElement;
+    title?: string;
+    /** Value-refresh poll; 0 disables polling. */
+    pollMs?: number;
+}
+interface PropertyInspector {
+    el: HTMLElement;
+    refresh(): void;
+    destroy(): void;
+}
+/** Inject the shared panel stylesheet once. Exported so the bundle inspector
+ *  (bundle-inspector.ts) renders in the same CSS grammar. */
+declare function ensureInspectorStyle(): void;
+/** One line per entry, `[turn]`-stamped where the event has a box context
+ *  (write lines share the state logger's `path: from -> to` reading). */
+declare function formatLogEntry(e: LogEntry | EngineLogEntry): string;
+declare function createPropertyInspector(engine: Engine, flow: Flow, opts?: PropertyInspectorOptions): PropertyInspector;
+
+interface BundleInspectorOptions {
+    /** Mount point; defaults to document.body. */
+    container?: HTMLElement;
+    title?: string;
+    /** Start the collapsible sections open (default true). */
+    open?: boolean;
+}
+interface BundleInspector {
+    el: HTMLElement;
+    /** The description this panel rendered (the API is the parity member). */
+    description: BundleDescription;
+    destroy(): void;
+}
+/** "name: type = default", plus enum/flags options where declared. */
+declare function formatPropertySummary(p: PropertySummary): string;
+/** The scope label a declaration block files under ("world", "box box",
+ *  "tag docks (zone)"). */
+declare function formatScopeLabel(scope: PropertyScopeSummary): string;
+/** Render a read-only summary of a compiled bundle: what an integrator may
+ *  call, with no session and no game running. */
+declare function createBundleInspector(bundle: Bundle, opts?: BundleInspectorOptions): BundleInspector;
+
+/** A minimal structural type for a WebSocket implementation (browsers and
+ *  Node 22+ have a global one). */
+interface LiveSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "open" | "close" | "error", listener: () => void): void;
+    /** Incoming editor messages (the pushed bundle). Optional so a bare
+     *  send-only socket still fits. */
+    addEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+}
+type LiveSocketCtor = new (url: string) => LiveSocketLike;
+interface LiveLinkOptions {
+    /** The running bundle's build identity: pass `bundle.content.hash`. The
+     *  editor compares it with its own compiled hash (in sync / stale). */
+    build: string;
+    /** Optional project name, shown in the editor's connect-chip tooltip. */
+    project?: string;
+    /** Editor WebSocket URL. Default `ws://127.0.0.1:4472`. */
+    url?: string;
+    /** A WebSocket constructor to use instead of the global one (tests with a
+     *  fake socket, or a host without a global WebSocket). */
+    WebSocket?: LiveSocketCtor;
+    /** Live refresh: the editor pushed a freshly compiled bundle. `data` is
+     *  the .storyletsc JSON; hand it (with your current Engine) to
+     *  `applyLiveBundle`, `attach` the engine it returns, then call
+     *  `link.setBuild(build)`. Never called with a malformed frame. */
+    onBundle?: (msg: {
+        build: string;
+        data: string;
+    }) => void;
+}
+interface LiveLink {
+    /** Start forwarding this ENGINE's trace: every flow's events, each frame
+     *  naming the flow it came from, so the editor can follow one participant
+     *  and switch. An earlier engine is detached first. Sends a board snapshot
+     *  per open flow straight away, queued behind the hello if the socket is
+     *  not open yet.
+     *
+     *  Flows are discovered rather than declared: the link diffs `engine.flows()`
+     *  whenever anything happens and emits `flowOpen` / `flowClose` itself. That
+     *  is a deliberate departure from Patterplay, whose host calls `FlowOpened`
+     *  by hand - it has no engine-level trace tap to hang the diff on and we do,
+     *  so the host has nothing to remember and cannot get the editor's flow list
+     *  wrong. The one cost: a flow that opens and then does nothing at all is not
+     *  announced until the next event anywhere in the run. */
+    attach(engine: Engine): void;
+    /** Stop forwarding. A refresh replaces the engine, so attach the new one
+     *  afterwards. */
+    detach(): void;
+    /** After applying a pushed bundle: report the build now running (re-hellos
+     *  with the new build and a fresh board snapshot, so the editor's chip goes
+     *  back to in sync and it stops re-pushing the same bundle). */
+    setBuild(build: string): void;
+    /** Close the link; every later call is a no-op. */
+    close(): void;
+}
+/** One game-to-editor frame, as the client serialises it. Exported for the
+ *  fixture test; hosts never build these by hand. */
+type LiveFrame = {
+    t: "hello";
+    v: 2;
+    build: string;
+    project?: string;
+    boxes?: string[];
+    flows: string[];
+} | {
+    t: "flowOpen";
+    flow: string;
+} | {
+    t: "flowClose";
+    flow: string;
+} | {
+    t: "trace";
+    flow: string;
+    event: TraceEvent;
+} | {
+    t: "board";
+    flow: string;
+    hands: Record<string, string[]>;
+    turns: Record<string, number>;
+};
+/** The cheap snapshot: hands by gameId holding card gameIds in dealt order,
+ *  and every box's clock by gameId. */
+declare function boardFrame(flow: Flow): Extract<LiveFrame, {
+    t: "board";
+}>;
+/**
+ * Open a Live Link to Storyletter. Returns a handle whose calls are no-ops once
+ * the editor disconnects or if it was never listening: safe to leave wired into
+ * a shipping build behind a flag.
+ */
+declare function createLiveLink(opts: LiveLinkOptions): LiveLink;
+
+type LiveBundleResult = 
+/** The new engine, carrying the old one's run (all flows), and the bundle
+ *  it runs. */
+{
+    ok: true;
+    engine: Engine;
+    bundle: Bundle;
+}
+/** Nothing changed: keep the engine you have. */
+ | {
+    ok: false;
+    error: string;
+};
+/**
+ * Apply a bundle the editor pushed over the Live Link: `new Engine(parsed,
+ * opts)` then `loadGame(engine.saveGame())`, returning the new engine. Never
+ * throws; a failure (unparseable JSON, a bundle the runtime rejects, a
+ * different project) comes back as `{ ok: false, error }` and the old engine
+ * is untouched.
+ *
+ * `opts` are the options the old engine was created with. An engine does
+ * not expose its seed, and it does not matter here: the save envelope carries
+ * each flow's PRNG state, so `loadGame` resumes the draw sequences exactly
+ * where they were and `seed` only shapes fresh flows. `log` does matter (the
+ * retained log is per flow), and so does `world` (the host's binding does not
+ * ride the envelope), so pass them if you had them.
+ */
+declare function applyLiveBundle(engine: Engine, bundleJson: string, opts?: EngineOptions): LiveBundleResult;
+
+type ScalarValue = boolean | number | string | string[];
+
+/**
+ * A scope backed by a host resolver rather than a static bag - the basis for
+ * *foreign* scopes (e.g. `@game` / `@world`) whose values live in a host or
+ * another engine and are read (and optionally written) at runtime. The
+ * evaluator treats a missing property the same as a bag does (the scope's
+ * missing-policy decides false-vs-throw). A scope entirely absent from the
+ * EvalContext still resolves to false regardless.
+ */
+interface ScopeResolver {
+    /** Read a property's value, or undefined if the scope does not have it. */
+    get(name: string): ScalarValue | undefined;
+    /** Write a property (omit for a read-only scope). The core never calls this;
+     *  it is for host/runtime effect application (e.g. a state container's `set`). */
+    set?(name: string, value: ScalarValue): void;
+}
+
+interface WorldContainer {
+    /** Pass as `new Engine(bundle, { world: container.resolver })`. */
+    resolver: ScopeResolver;
+    /** The kernel bag itself (subscribe, audit, rows live there) - mount it
+     *  into a state logger or examiner beside the engine's own bags. */
+    bag: PropertyBag$1;
+    /** The current values, for saving beside the engine's envelope. */
+    values(): PropertyBag;
+    /** Restore saved values over fresh defaults: orphaned keys drop, new
+     *  declarations keep their defaults - the same drift rule as loadGame. */
+    load(values: PropertyBag): void;
+}
+/** A world container seeded from the bundle's @world declarations. */
+declare function createWorldContainer(bundle: Bundle): WorldContainer;
+
+export { type BundleInspector, type BundleInspectorOptions, type LiveBundleResult, type LiveFrame, type LiveLink, type LiveLinkOptions, type LiveSocketLike, type PropertyInspector, type PropertyInspectorOptions, type WorldContainer, applyLiveBundle, boardFrame, createBundleInspector, createLiveLink, createPropertyInspector, createStateLogger, createWorldContainer, deserializeState, ensureInspectorStyle, formatLogEntry, formatPropertySummary, formatScopeLabel, loadState, saveState, serializeState, snapshotState };

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+import { Engine, Flow, LogEntry, EngineLogEntry, BundleDescription, PropertySummary, PropertyScopeSummary, TraceEvent, EngineOptions } from '@storylet-studio/runtime';
+import { StateLoggerOptions, StateLogger, StateSnapshot, PropertyBag as PropertyBag$1 } from '@wildwinter/scoperegistry';
+export { StateChange, StateLogger, StateLoggerAdapter, StateLoggerOptions, StateSnapshot, createStateLogger as createKernelStateLogger, diffState } from '@wildwinter/scoperegistry';
+import { PropertyBag, SaveFile, Bundle } from '@storylet-studio/model';
+
+/** The full flattened snapshot of ONE FLOW's view - the shared partitions
+ *  plus that flow's own - straight off the save envelope, so "what the
+ *  snapshot sees" is by construction "what a save persists". @world is not
+ *  here for the same reason it is not in the envelope: the host owns that
+ *  container and mounts/saves it itself (createWorldContainer). */
+declare function snapshotState(engine: Engine, flow: Flow): StateSnapshot;
+/** The storylets state logger: the kernel core mounted on the SHARED bags
+ *  (engine.listBags()) and one flow's own (flow.listBags()) - the same
+ *  prefixes, one path space, names disjoint - plus the flow's turns /
+ *  cooldowns / board adapter. A host that wants @world lines mounts its
+ *  world container's bag through createKernelStateLogger itself. */
+declare function createStateLogger(engine: Engine, flow: Flow, opts?: StateLoggerOptions): StateLogger;
+
+/** The current engine state (and the host's @world values, if given) as
+ *  pretty-printed .storyletsave JSON. */
+declare function serializeState(engine: Engine, world?: PropertyBag): string;
+/**
+ * Capture the whole engine (and the host's @world values, if it keeps any) as
+ * the tagged save-file OBJECT.
+ *
+ * Four verbs, in Patterplay's pairing (`patter` play-helpers `save.ts`, and
+ * the same in all four of its runtimes): saveState / loadState work on the
+ * PARSED object, serializeState / deserializeState work on TEXT.
+ *
+ * This reference had a different shape until 2026-08-29 - `deserializeState`
+ * parsed and did not restore, `loadState` took text - so one name meant two
+ * things across the four Storylets runtimes, and neither matched the family.
+ * Godot and Unreal already had Patter's shape; these two were brought to it.
+ */
+declare function saveState(engine: Engine, world?: PropertyBag): SaveFile;
+/** Restore a {@link saveState} file into an engine. EVERY FLOW IS REBUILT, so
+ *  the Flow handles you held before are inert: re-take them with
+ *  `engine.getFlow(id)`, NOT `engine.openFlow(id)`. `openFlow` on an existing
+ *  id REPLACES it, which here throws away the hand the file just restored, and
+ *  the failure lands later, as `play()` refusing a card as "not dealt". (The
+ *  engine's `onReplacedFlow` hook reports exactly this.) Throws on a foreign or malformed
+ *  file, and the runtime's own project check still applies. Returns the file's
+ *  @world values, if any - the HOST applies them to its container; the engine
+ *  never touches them. */
+declare function loadState(engine: Engine, file: SaveFile): PropertyBag | undefined;
+/** Parse + restore a {@link serializeState} string: the TEXT twin of
+ *  loadState, as Patterplay pairs them. Throws on malformed JSON, a foreign
+ *  file or a project mismatch. Returns the file's @world values for the host. */
+declare function deserializeState(engine: Engine, json: string): PropertyBag | undefined;
+
+interface PropertyInspectorOptions {
+    /** Mount point; defaults to document.body. */
+    container?: HTMLElement;
+    title?: string;
+    /** Value-refresh poll; 0 disables polling. */
+    pollMs?: number;
+}
+interface PropertyInspector {
+    el: HTMLElement;
+    refresh(): void;
+    destroy(): void;
+}
+/** Inject the shared panel stylesheet once. Exported so the bundle inspector
+ *  (bundle-inspector.ts) renders in the same CSS grammar. */
+declare function ensureInspectorStyle(): void;
+/** One line per entry, `[turn]`-stamped where the event has a box context
+ *  (write lines share the state logger's `path: from -> to` reading). */
+declare function formatLogEntry(e: LogEntry | EngineLogEntry): string;
+declare function createPropertyInspector(engine: Engine, flow: Flow, opts?: PropertyInspectorOptions): PropertyInspector;
+
+interface BundleInspectorOptions {
+    /** Mount point; defaults to document.body. */
+    container?: HTMLElement;
+    title?: string;
+    /** Start the collapsible sections open (default true). */
+    open?: boolean;
+}
+interface BundleInspector {
+    el: HTMLElement;
+    /** The description this panel rendered (the API is the parity member). */
+    description: BundleDescription;
+    destroy(): void;
+}
+/** "name: type = default", plus enum/flags options where declared. */
+declare function formatPropertySummary(p: PropertySummary): string;
+/** The scope label a declaration block files under ("world", "box box",
+ *  "tag docks (zone)"). */
+declare function formatScopeLabel(scope: PropertyScopeSummary): string;
+/** Render a read-only summary of a compiled bundle: what an integrator may
+ *  call, with no session and no game running. */
+declare function createBundleInspector(bundle: Bundle, opts?: BundleInspectorOptions): BundleInspector;
+
+/** A minimal structural type for a WebSocket implementation (browsers and
+ *  Node 22+ have a global one). */
+interface LiveSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "open" | "close" | "error", listener: () => void): void;
+    /** Incoming editor messages (the pushed bundle). Optional so a bare
+     *  send-only socket still fits. */
+    addEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+}
+type LiveSocketCtor = new (url: string) => LiveSocketLike;
+interface LiveLinkOptions {
+    /** The running bundle's build identity: pass `bundle.content.hash`. The
+     *  editor compares it with its own compiled hash (in sync / stale). */
+    build: string;
+    /** Optional project name, shown in the editor's connect-chip tooltip. */
+    project?: string;
+    /** Editor WebSocket URL. Default `ws://127.0.0.1:4472`. */
+    url?: string;
+    /** A WebSocket constructor to use instead of the global one (tests with a
+     *  fake socket, or a host without a global WebSocket). */
+    WebSocket?: LiveSocketCtor;
+    /** Live refresh: the editor pushed a freshly compiled bundle. `data` is
+     *  the .storyletsc JSON; hand it (with your current Engine) to
+     *  `applyLiveBundle`, `attach` the engine it returns, then call
+     *  `link.setBuild(build)`. Never called with a malformed frame. */
+    onBundle?: (msg: {
+        build: string;
+        data: string;
+    }) => void;
+}
+interface LiveLink {
+    /** Start forwarding this ENGINE's trace: every flow's events, each frame
+     *  naming the flow it came from, so the editor can follow one participant
+     *  and switch. An earlier engine is detached first. Sends a board snapshot
+     *  per open flow straight away, queued behind the hello if the socket is
+     *  not open yet.
+     *
+     *  Flows are discovered rather than declared: the link diffs `engine.flows()`
+     *  whenever anything happens and emits `flowOpen` / `flowClose` itself. That
+     *  is a deliberate departure from Patterplay, whose host calls `FlowOpened`
+     *  by hand - it has no engine-level trace tap to hang the diff on and we do,
+     *  so the host has nothing to remember and cannot get the editor's flow list
+     *  wrong. The one cost: a flow that opens and then does nothing at all is not
+     *  announced until the next event anywhere in the run. */
+    attach(engine: Engine): void;
+    /** Stop forwarding. A refresh replaces the engine, so attach the new one
+     *  afterwards. */
+    detach(): void;
+    /** After applying a pushed bundle: report the build now running (re-hellos
+     *  with the new build and a fresh board snapshot, so the editor's chip goes
+     *  back to in sync and it stops re-pushing the same bundle). */
+    setBuild(build: string): void;
+    /** Close the link; every later call is a no-op. */
+    close(): void;
+}
+/** One game-to-editor frame, as the client serialises it. Exported for the
+ *  fixture test; hosts never build these by hand. */
+type LiveFrame = {
+    t: "hello";
+    v: 2;
+    build: string;
+    project?: string;
+    boxes?: string[];
+    flows: string[];
+} | {
+    t: "flowOpen";
+    flow: string;
+} | {
+    t: "flowClose";
+    flow: string;
+} | {
+    t: "trace";
+    flow: string;
+    event: TraceEvent;
+} | {
+    t: "board";
+    flow: string;
+    hands: Record<string, string[]>;
+    turns: Record<string, number>;
+};
+/** The cheap snapshot: hands by gameId holding card gameIds in dealt order,
+ *  and every box's clock by gameId. */
+declare function boardFrame(flow: Flow): Extract<LiveFrame, {
+    t: "board";
+}>;
+/**
+ * Open a Live Link to Storyletter. Returns a handle whose calls are no-ops once
+ * the editor disconnects or if it was never listening: safe to leave wired into
+ * a shipping build behind a flag.
+ */
+declare function createLiveLink(opts: LiveLinkOptions): LiveLink;
+
+type LiveBundleResult = 
+/** The new engine, carrying the old one's run (all flows), and the bundle
+ *  it runs. */
+{
+    ok: true;
+    engine: Engine;
+    bundle: Bundle;
+}
+/** Nothing changed: keep the engine you have. */
+ | {
+    ok: false;
+    error: string;
+};
+/**
+ * Apply a bundle the editor pushed over the Live Link: `new Engine(parsed,
+ * opts)` then `loadGame(engine.saveGame())`, returning the new engine. Never
+ * throws; a failure (unparseable JSON, a bundle the runtime rejects, a
+ * different project) comes back as `{ ok: false, error }` and the old engine
+ * is untouched.
+ *
+ * `opts` are the options the old engine was created with. An engine does
+ * not expose its seed, and it does not matter here: the save envelope carries
+ * each flow's PRNG state, so `loadGame` resumes the draw sequences exactly
+ * where they were and `seed` only shapes fresh flows. `log` does matter (the
+ * retained log is per flow), and so does `world` (the host's binding does not
+ * ride the envelope), so pass them if you had them.
+ */
+declare function applyLiveBundle(engine: Engine, bundleJson: string, opts?: EngineOptions): LiveBundleResult;
+
+type ScalarValue = boolean | number | string | string[];
+
+/**
+ * A scope backed by a host resolver rather than a static bag - the basis for
+ * *foreign* scopes (e.g. `@game` / `@world`) whose values live in a host or
+ * another engine and are read (and optionally written) at runtime. The
+ * evaluator treats a missing property the same as a bag does (the scope's
+ * missing-policy decides false-vs-throw). A scope entirely absent from the
+ * EvalContext still resolves to false regardless.
+ */
+interface ScopeResolver {
+    /** Read a property's value, or undefined if the scope does not have it. */
+    get(name: string): ScalarValue | undefined;
+    /** Write a property (omit for a read-only scope). The core never calls this;
+     *  it is for host/runtime effect application (e.g. a state container's `set`). */
+    set?(name: string, value: ScalarValue): void;
+}
+
+interface WorldContainer {
+    /** Pass as `new Engine(bundle, { world: container.resolver })`. */
+    resolver: ScopeResolver;
+    /** The kernel bag itself (subscribe, audit, rows live there) - mount it
+     *  into a state logger or examiner beside the engine's own bags. */
+    bag: PropertyBag$1;
+    /** The current values, for saving beside the engine's envelope. */
+    values(): PropertyBag;
+    /** Restore saved values over fresh defaults: orphaned keys drop, new
+     *  declarations keep their defaults - the same drift rule as loadGame. */
+    load(values: PropertyBag): void;
+}
+/** A world container seeded from the bundle's @world declarations. */
+declare function createWorldContainer(bundle: Bundle): WorldContainer;
+
+export { type BundleInspector, type BundleInspectorOptions, type LiveBundleResult, type LiveFrame, type LiveLink, type LiveLinkOptions, type LiveSocketLike, type PropertyInspector, type PropertyInspectorOptions, type WorldContainer, applyLiveBundle, boardFrame, createBundleInspector, createLiveLink, createPropertyInspector, createStateLogger, createWorldContainer, deserializeState, ensureInspectorStyle, formatLogEntry, formatPropertySummary, formatScopeLabel, loadState, saveState, serializeState, snapshotState };