@player-ui/context-plugin 0.16.0--canary.891.38194

package/src/store.ts

@@ -0,0 +1,205 @@
+import type {
+  ContextEntryDescriptor,
+  ContextKey,
+  ContextTransform,
+  FrozenContextEntry,
+  FrozenContextSnapshot,
+} from "./types";
+import { nameOfContextKey } from "./key";
+
+type Entry = {
+  key: ContextKey;
+  hasLiteral: boolean;
+  literal?: unknown;
+  transform?: ContextTransform<unknown>;
+};
+
+const deepFreezeEntry = (entry: FrozenContextEntry): FrozenContextEntry => {
+  Object.freeze(entry);
+  return entry;
+};
+
+/**
+ * A poisoned stand-in for a function captured into a history snapshot. The
+ * key and description survive in the snapshot — the capability *existed* —
+ * but the callable is dead: invoking it throws because the flow it was bound
+ * to has ended. This preserves the distinction between "context that never
+ * held this action" and "an action that is no longer valid".
+ */
+const tombstone = (description: string) => (): never => {
+  throw new Error(
+    `[ContextPlugin] Action "${description}" is no longer valid — its flow has ended`,
+  );
+};
+
+/**
+ * Recursively replace every function in [value] (top-level or nested) with a
+ * {@link tombstone}, so a frozen history snapshot carries no live callables.
+ */
+const tombstoneFunctions = (value: unknown, description: string): unknown => {
+  if (typeof value === "function") {
+    return tombstone(description);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => tombstoneFunctions(item, description));
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = tombstoneFunctions(v, description);
+    }
+    return out;
+  }
+  return value;
+};
+
+/**
+ * Mutable per-flow context store. Owned by a single flow lifecycle; the plugin
+ * rotates the store on flow end and freezes the prior one into a snapshot.
+ */
+export class ContextStore {
+  private entries = new Map<symbol, Entry>();
+  /** source symbol -> set of target symbols (reverse index for invalidation). */
+  private dependents = new Map<symbol, Set<symbol>>();
+
+  register(key: ContextKey): boolean {
+    if (this.entries.has(key.symbol)) {
+      return false;
+    }
+    this.entries.set(key.symbol, { key, hasLiteral: false });
+    return true;
+  }
+
+  set<Value>(key: ContextKey<Value>, value: Value): void {
+    const existing = this.entries.get(key.symbol);
+    if (existing) {
+      existing.hasLiteral = true;
+      existing.literal = value;
+      existing.key = key;
+    } else {
+      this.entries.set(key.symbol, {
+        key,
+        hasLiteral: true,
+        literal: value,
+      });
+    }
+  }
+
+  registerTransform<Value>(
+    key: ContextKey<Value>,
+    transform: ContextTransform<Value>,
+  ): { previousSources?: ReadonlyArray<ContextKey> } {
+    const existing = this.entries.get(key.symbol);
+    const previousSources = existing?.transform?.sources;
+
+    if (previousSources) {
+      for (const src of previousSources) {
+        this.dependents.get(src.symbol)?.delete(key.symbol);
+      }
+    }
+
+    const stored: ContextTransform<unknown> = {
+      sources: transform.sources,
+      compute: transform.compute as ContextTransform<unknown>["compute"],
+    };
+
+    if (existing) {
+      existing.transform = stored;
+      existing.key = key;
+    } else {
+      this.entries.set(key.symbol, {
+        key,
+        hasLiteral: false,
+        transform: stored,
+      });
+    }
+
+    for (const src of transform.sources) {
+      let set = this.dependents.get(src.symbol);
+      if (!set) {
+        set = new Set();
+        this.dependents.set(src.symbol, set);
+      }
+      set.add(key.symbol);
+    }
+
+    return { previousSources };
+  }
+
+  get<Value>(key: ContextKey<Value>): Value | undefined {
+    return this.compute(key.symbol) as Value | undefined;
+  }
+
+  has(key: ContextKey): boolean {
+    const entry = this.entries.get(key.symbol);
+    return Boolean(entry && (entry.hasLiteral || entry.transform));
+  }
+
+  /** Return the keys that depend on the given source key (direct dependents only). */
+  dependentsOf(sourceSymbol: symbol): ReadonlyArray<ContextKey> {
+    const set = this.dependents.get(sourceSymbol);
+    if (!set || set.size === 0) {
+      return [];
+    }
+    const out: ContextKey[] = [];
+    for (const targetSymbol of set) {
+      const target = this.entries.get(targetSymbol);
+      if (target) {
+        out.push(target.key);
+      }
+    }
+    return out;
+  }
+
+  list(): ReadonlyArray<ContextEntryDescriptor> {
+    const out: ContextEntryDescriptor[] = [];
+    for (const entry of this.entries.values()) {
+      out.push({
+        symbol: entry.key.symbol,
+        description: entry.key.description,
+        hasValue: entry.hasLiteral,
+        hasTransform: Boolean(entry.transform),
+      });
+    }
+    return out;
+  }
+
+  freeze(meta: { flowId?: string; endedAt: number }): FrozenContextSnapshot {
+    const frozenEntries: FrozenContextEntry[] = [];
+    for (const entry of this.entries.values()) {
+      if (!entry.hasLiteral && !entry.transform) {
+        continue;
+      }
+      const computed = this.compute(entry.key.symbol);
+      const value = tombstoneFunctions(computed, entry.key.description);
+      frozenEntries.push(
+        deepFreezeEntry({
+          symbol: entry.key.symbol,
+          name: nameOfContextKey(entry.key),
+          description: entry.key.description,
+          value,
+        }),
+      );
+    }
+    const bySymbol = new Map(frozenEntries.map((e) => [e.symbol, e.value]));
+    const snapshot: FrozenContextSnapshot = {
+      flowId: meta.flowId,
+      endedAt: meta.endedAt,
+      entries: Object.freeze(frozenEntries),
+      get<Value>(key: ContextKey<Value>): Value | undefined {
+        return bySymbol.get(key.symbol) as Value | undefined;
+      },
+    };
+    return Object.freeze(snapshot);
+  }
+
+  private compute(sym: symbol): unknown {
+    const entry = this.entries.get(sym);
+    if (!entry) return undefined;
+    if (entry.hasLiteral) return entry.literal;
+    if (!entry.transform) return undefined;
+    const reader = <V>(otherKey: { symbol: symbol }): V | undefined =>
+      this.compute(otherKey.symbol) as V | undefined;
+    return entry.transform.compute(reader);
+  }
+}

package/src/symbols.ts

@@ -0,0 +1 @@
+export const ContextPluginSymbol = Symbol.for("ContextPlugin");

package/src/types.ts

@@ -0,0 +1,57 @@
+export type ContextKey<Value = unknown> = {
+  readonly symbol: symbol;
+  readonly description: string;
+  /** Phantom marker so TS can infer `Value` from a key. Not present at runtime. */
+  readonly __value?: Value;
+};
+
+export type ContextReader = <Value>(
+  key: ContextKey<Value>,
+) => Value | undefined;
+
+export type ContextTransform<Value> = {
+  /** Source keys whose updates should invalidate (and notify subscribers of) this target. */
+  sources: ReadonlyArray<ContextKey>;
+  /** Compute the target value, reading from other context entries. */
+  compute: (read: ContextReader) => Value | undefined;
+};
+
+export type ContextSubscriber<Value> = (
+  value: Value | undefined,
+  key: ContextKey<Value>,
+) => void;
+
+export type ContextGlobalSubscriber = (value: unknown, key: ContextKey) => void;
+
+export type ContextEntryDescriptor = {
+  symbol: symbol;
+  description: string;
+  hasValue: boolean;
+  hasTransform: boolean;
+};
+
+export type SubscriptionToken = `ctx_${number}`;
+
+export type FrozenContextEntry = {
+  readonly symbol: symbol;
+  /**
+   * The entry's key name (from `nameOfContextKey`), or `undefined` for
+   * non-namespaced keys. Unlike `symbol`, this is a plain string that survives
+   * the native bridge, so native consumers read snapshot entries by name.
+   */
+  readonly name: string | undefined;
+  readonly description: string;
+  readonly value: unknown;
+};
+
+export type FrozenContextSnapshot = {
+  readonly flowId?: string;
+  readonly endedAt: number;
+  readonly entries: ReadonlyArray<FrozenContextEntry>;
+  /**
+   * Read a frozen entry by its key — the same typed access as live context.
+   * Returns `undefined` if the key was not present when the snapshot froze.
+   * Function-valued entries return their tombstone (a throwing callable).
+   */
+  get<Value>(key: ContextKey<Value>): Value | undefined;
+};

package/src/utils.ts

@@ -0,0 +1,17 @@
+import type { Player } from "@player-ui/player";
+import { ContextPlugin } from "./plugin";
+import { ContextPluginSymbol } from "./symbols";
+
+/**
+ * Returns the existing ContextPlugin or creates and registers a new one.
+ */
+export function getContextPlugin(player: Player): ContextPlugin {
+  const existing = player.findPlugin<ContextPlugin>(ContextPluginSymbol);
+  const plugin = existing ?? new ContextPlugin();
+
+  if (!existing) {
+    player.registerPlugin(plugin);
+  }
+
+  return plugin;
+}

package/types/history.d.ts

@@ -0,0 +1,13 @@
+import type { FrozenContextSnapshot } from "./types";
+/**
+ * Append-only stack of frozen per-flow snapshots. The plugin pushes one
+ * snapshot on each flow end; consumers read via `entries()`.
+ */
+export declare class ContextHistory {
+    private stack;
+    push(snapshot: FrozenContextSnapshot): void;
+    entries(): ReadonlyArray<FrozenContextSnapshot>;
+    size(): number;
+    clear(): void;
+}
+//# sourceMappingURL=history.d.ts.map

package/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./plugin";
+export * from "./symbols";
+export * from "./types";
+export * from "./key";
+export * from "./utils";
+export * from "./state-plugin";
+//# sourceMappingURL=index.d.ts.map

package/types/key.d.ts

@@ -0,0 +1,20 @@
+import type { ContextKey } from "./types";
+/**
+ * Create a typed, globally-identifiable context key.
+ *
+ * Identity is backed by `Symbol.for`, so two keys created with the same `name`
+ * in different bundles refer to the same store entry. The `description` is the
+ * human-readable label used by introspection consumers.
+ */
+export declare const defineContextKey: <Value>(name: string, description: string) => ContextKey<Value>;
+/**
+ * Resolve the global symbol for a context key name. Used by native wrappers
+ * that cross the JS bridge with string names instead of JS symbols.
+ */
+export declare const resolveContextKeySymbol: (name: string) => symbol;
+/**
+ * Reverse-derive the name from a key created via `defineContextKey`. Returns
+ * `undefined` if the key's symbol was not created in the context namespace.
+ */
+export declare const nameOfContextKey: (key: ContextKey) => string | undefined;
+//# sourceMappingURL=key.d.ts.map

package/types/plugin.d.ts

@@ -0,0 +1,64 @@
+import type { Player, PlayerPlugin } from "@player-ui/player";
+import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { ContextStore } from "./store";
+import { ContextHistory } from "./history";
+import type { ContextEntryDescriptor, ContextGlobalSubscriber, ContextKey, ContextSubscriber, ContextTransform, FrozenContextSnapshot, SubscriptionToken } from "./types";
+/**
+ * Maintains a per-flow store of context entries keyed by symbol, with
+ * registered transforms for derived values and a subscription API for
+ * external consumers. On flow end the active store is frozen into a snapshot
+ * and pushed onto a history stack; a fresh store is created for the next flow,
+ * with transforms re-applied. Subscribers persist across flow rotations.
+ */
+export declare class ContextPlugin implements PlayerPlugin {
+    name: string;
+    static Symbol: symbol;
+    readonly symbol: symbol;
+    readonly hooks: {
+        onSet: SyncHook<[ContextKey, unknown], Record<string, any>>;
+        resolveValue: SyncWaterfallHook<[unknown, ContextKey], Record<string, any>>;
+        onRegister: SyncHook<[ContextKey], Record<string, any>>;
+        onFlowFrozen: SyncHook<[FrozenContextSnapshot], Record<string, any>>;
+    };
+    protected store: ContextStore;
+    protected historyStack: ContextHistory;
+    private transforms;
+    private perKeySubs;
+    private globalSubs;
+    private tokenIndex;
+    private currentFlowId;
+    constructor();
+    apply(player: Player): void;
+    register<Value>(key: ContextKey<Value>): void;
+    set<Value>(key: ContextKey<Value>, value: Value): void;
+    get<Value>(key: ContextKey<Value>): Value | undefined;
+    has(key: ContextKey): boolean;
+    registerTransform<Value>(key: ContextKey<Value>, transform: ContextTransform<Value>): void;
+    subscribe<Value>(key: ContextKey<Value>, handler: ContextSubscriber<Value>): SubscriptionToken;
+    subscribeAll(handler: ContextGlobalSubscriber): SubscriptionToken;
+    unsubscribe(token: SubscriptionToken): void;
+    list(): ReadonlyArray<ContextEntryDescriptor>;
+    history(): ReadonlyArray<FrozenContextSnapshot>;
+    snapshot(): FrozenContextSnapshot;
+    /**
+     * Bridge-friendly: set a value by string name. Used by native wrappers that
+     * cannot construct a `ContextKey` object directly.
+     */
+    setByName(name: string, description: string, value: unknown): void;
+    /** Bridge-friendly: get a value by string name. */
+    getByName(name: string): unknown;
+    /** Bridge-friendly: check presence by string name. */
+    hasByName(name: string): boolean;
+    /** Bridge-friendly: subscribe by string name. */
+    subscribeByName(name: string, description: string, handler: (value: unknown, name: string) => void): SubscriptionToken;
+    /**
+     * Bridge-friendly: subscribe to all updates. The handler receives the
+     * key's resolved name (or undefined for non-namespaced keys).
+     */
+    subscribeAllByName(handler: (value: unknown, name: string | undefined, description: string) => void): SubscriptionToken;
+    private ensureNamedKey;
+    private notify;
+    private rotateStore;
+    private nextToken;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/types/state-plugin.d.ts

@@ -0,0 +1,92 @@
+import type { Player, PlayerPlugin } from "@player-ui/player";
+import type { ContextKey } from "./types";
+/** Set a single binding in the Player data model. */
+export type SetDataAction = (binding: string, value: unknown) => void;
+/** Transition the running flow using the given transition value. */
+export type TransitionAction = (transition: string) => void;
+/** A single validation, projected to its serializable fields. */
+export type ContextValidation = {
+    severity: "error" | "warning";
+    message: string;
+    displayTarget?: "page" | "section" | "field";
+    blocking?: boolean | "once";
+};
+/** Validation state for the running view, keyed by binding. */
+export type ValidationContext = {
+    /** Whether the view has no blocking validations (derived, no side effects). */
+    canTransition: boolean;
+    /** Active validations per binding string. */
+    byBinding: Record<string, ReadonlyArray<ContextValidation>>;
+};
+/** Identifier of the currently-running flow. */
+export declare const flowIdContextKey: ContextKey<string>;
+/** Name of the current FSM state within the running flow. */
+export declare const flowStateContextKey: ContextKey<string>;
+/** Identifier of the view currently resolved by the ViewController. */
+export declare const viewIdContextKey: ContextKey<string>;
+/** Full resolved view object for the current FSM state. */
+export declare const viewContextKey: ContextKey<unknown>;
+/** Full data model tree for the running flow. */
+export declare const dataContextKey: ContextKey<unknown>;
+/** Player flow status: not-started, in-progress, completed, or error. */
+export declare const playerStatusContextKey: ContextKey<string>;
+/** Validation state for the running view, keyed by binding. */
+export declare const validationContextKey: ContextKey<ValidationContext>;
+/**
+ * Action entry whose value is a callable that sets a binding in the data
+ * model. Read via `ctx.get(setDataActionKey)`; absent until a flow is running.
+ */
+export declare const setDataActionKey: ContextKey<SetDataAction>;
+/**
+ * Action entry whose value is a callable that transitions the running flow.
+ * Read via `ctx.get(transitionActionKey)`; absent until a flow is running.
+ */
+export declare const transitionActionKey: ContextKey<TransitionAction>;
+/**
+ * Aggregated snapshot composed from every other StateContextPlugin key.
+ *
+ * Actions are scoped to the construct they operate on — `transition` lives
+ * under `flow`, `set` under `data` — rather than in a flat actions bag. Each
+ * is bound to the live controller and is absent until a flow is in-progress.
+ */
+export type PlayerStateContext = {
+    status?: string;
+    flow: {
+        id?: string;
+        state?: string;
+        /** Transition the running flow (e.g. 'Next'). */
+        transition?: TransitionAction;
+    };
+    view: {
+        id?: string;
+        resolved?: unknown;
+    };
+    data: {
+        /** Full data model tree for the running flow. */
+        model?: unknown;
+        /** Set a value in the data model at the given binding. */
+        set?: SetDataAction;
+    };
+    /** Validation state for the running view, keyed by binding. */
+    validation: ValidationContext;
+};
+/**
+ * Single roll-up key that aggregates every other [[StateContextPlugin]] entry
+ * into one object. Backed by a transform — reading recomputes from the latest
+ * source values, and subscribers fire whenever any source updates.
+ */
+export declare const playerStateContextKey: ContextKey<PlayerStateContext>;
+/**
+ * A consumer plugin that mirrors Player runtime state into the ContextPlugin
+ * store. Registers a small, opinionated set of context entries (flow id,
+ * current FSM state, view id, full view, data model, status) so external
+ * automation/devtools can observe the running Player without tapping every
+ * controller hook themselves.
+ *
+ * Auto-registers a [[ContextPlugin]] if one isn't already on the player.
+ */
+export declare class StateContextPlugin implements PlayerPlugin {
+    name: string;
+    apply(player: Player): void;
+}
+//# sourceMappingURL=state-plugin.d.ts.map

package/types/store.d.ts

@@ -0,0 +1,26 @@
+import type { ContextEntryDescriptor, ContextKey, ContextTransform, FrozenContextSnapshot } from "./types";
+/**
+ * Mutable per-flow context store. Owned by a single flow lifecycle; the plugin
+ * rotates the store on flow end and freezes the prior one into a snapshot.
+ */
+export declare class ContextStore {
+    private entries;
+    /** source symbol -> set of target symbols (reverse index for invalidation). */
+    private dependents;
+    register(key: ContextKey): boolean;
+    set<Value>(key: ContextKey<Value>, value: Value): void;
+    registerTransform<Value>(key: ContextKey<Value>, transform: ContextTransform<Value>): {
+        previousSources?: ReadonlyArray<ContextKey>;
+    };
+    get<Value>(key: ContextKey<Value>): Value | undefined;
+    has(key: ContextKey): boolean;
+    /** Return the keys that depend on the given source key (direct dependents only). */
+    dependentsOf(sourceSymbol: symbol): ReadonlyArray<ContextKey>;
+    list(): ReadonlyArray<ContextEntryDescriptor>;
+    freeze(meta: {
+        flowId?: string;
+        endedAt: number;
+    }): FrozenContextSnapshot;
+    private compute;
+}
+//# sourceMappingURL=store.d.ts.map

package/types/symbols.d.ts

@@ -0,0 +1,2 @@
+export declare const ContextPluginSymbol: unique symbol;
+//# sourceMappingURL=symbols.d.ts.map

package/types/types.d.ts

@@ -0,0 +1,45 @@
+export type ContextKey<Value = unknown> = {
+    readonly symbol: symbol;
+    readonly description: string;
+    /** Phantom marker so TS can infer `Value` from a key. Not present at runtime. */
+    readonly __value?: Value;
+};
+export type ContextReader = <Value>(key: ContextKey<Value>) => Value | undefined;
+export type ContextTransform<Value> = {
+    /** Source keys whose updates should invalidate (and notify subscribers of) this target. */
+    sources: ReadonlyArray<ContextKey>;
+    /** Compute the target value, reading from other context entries. */
+    compute: (read: ContextReader) => Value | undefined;
+};
+export type ContextSubscriber<Value> = (value: Value | undefined, key: ContextKey<Value>) => void;
+export type ContextGlobalSubscriber = (value: unknown, key: ContextKey) => void;
+export type ContextEntryDescriptor = {
+    symbol: symbol;
+    description: string;
+    hasValue: boolean;
+    hasTransform: boolean;
+};
+export type SubscriptionToken = `ctx_${number}`;
+export type FrozenContextEntry = {
+    readonly symbol: symbol;
+    /**
+     * The entry's key name (from `nameOfContextKey`), or `undefined` for
+     * non-namespaced keys. Unlike `symbol`, this is a plain string that survives
+     * the native bridge, so native consumers read snapshot entries by name.
+     */
+    readonly name: string | undefined;
+    readonly description: string;
+    readonly value: unknown;
+};
+export type FrozenContextSnapshot = {
+    readonly flowId?: string;
+    readonly endedAt: number;
+    readonly entries: ReadonlyArray<FrozenContextEntry>;
+    /**
+     * Read a frozen entry by its key — the same typed access as live context.
+     * Returns `undefined` if the key was not present when the snapshot froze.
+     * Function-valued entries return their tombstone (a throwing callable).
+     */
+    get<Value>(key: ContextKey<Value>): Value | undefined;
+};
+//# sourceMappingURL=types.d.ts.map

package/types/utils.d.ts

@@ -0,0 +1,7 @@
+import type { Player } from "@player-ui/player";
+import { ContextPlugin } from "./plugin";
+/**
+ * Returns the existing ContextPlugin or creates and registers a new one.
+ */
+export declare function getContextPlugin(player: Player): ContextPlugin;
+//# sourceMappingURL=utils.d.ts.map