@player-ui/player 1.1.0-next.2 → 1.1.0-next.3

package/package.json

@@ -6,12 +6,12 @@
     "types"
   ],
   "name": "@player-ui/player",
-  "version": "1.1.0-next.2",
+  "version": "1.1.0-next.3",
   "main": "dist/cjs/index.cjs",
   "dependencies": {
-    "@player-ui/partial-match-registry": "1.1.0-next.2",
-    "@player-ui/make-flow": "1.1.0-next.2",
-    "@player-ui/types": "1.1.0-next.2",
+    "@player-ui/partial-match-registry": "1.1.0-next.3",
+    "@player-ui/make-flow": "1.1.0-next.3",
+    "@player-ui/types": "1.1.0-next.3",
     "@types/dlv": "^1.1.4",
     "dequal": "^2.0.2",
     "dlv": "^1.1.3",

package/src/__tests__/transform-content.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test, vitest } from "vitest";
+import { Player } from "..";
+import type { Flow, PlayerPlugin, InProgressState } from "..";
+
+/** Minimal Flow used to short-circuit setupFlow. */
+const flowFor = (id: string): Flow => ({
+  id,
+  views: [{ id: "v1", type: "text", value: "hi" }],
+  data: {},
+  navigation: {
+    BEGIN: "F",
+    F: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        state_type: "VIEW",
+        ref: "v1",
+        transitions: { "*": "END" },
+      },
+      END: { state_type: "END", outcome: "done" },
+    },
+  },
+});
+
+describe("transformContent hook", () => {
+  test("default format 'player' passes the payload through unchanged", async () => {
+    const player = new Player();
+    const flow = flowFor("plain");
+    player.start(flow);
+    const state = player.getState() as InProgressState;
+    expect(state.flow).toBe(flow);
+  });
+
+  test("a plugin tapping for a custom format transforms the payload", async () => {
+    const greetPlugin: PlayerPlugin = {
+      name: "greet",
+      apply(p) {
+        p.hooks.transformContent.tap("greet", (content, meta) => {
+          if (meta.format !== "greet") return undefined;
+          const { message } = content as { message: string };
+          return { ...flowFor("greet"), data: { message } };
+        });
+      },
+    };
+
+    const player = new Player({ plugins: [greetPlugin] });
+    player.start({ message: "Hello world" }, { format: "greet" });
+
+    const state = player.getState() as InProgressState;
+    await vitest.waitFor(() =>
+      expect(state.controllers.view.currentView?.lastUpdate).toBeDefined(),
+    );
+    expect(state.controllers.data.get("message")).toBe("Hello world");
+  });
+
+  test("fires before resolveFlowContent", async () => {
+    const order: string[] = [];
+
+    const orderPlugin: PlayerPlugin = {
+      name: "order",
+      apply(p) {
+        p.hooks.transformContent.tap("order", () => {
+          order.push("transformContent");
+          // Return undefined so Player's default "player" handler claims it.
+          return undefined;
+        });
+        p.hooks.resolveFlowContent.tap("order", (c) => {
+          order.push("resolveFlowContent");
+          return c;
+        });
+      },
+    };
+
+    const player = new Player({ plugins: [orderPlugin] });
+    player.start(flowFor("order"));
+
+    expect(order).toEqual(["transformContent", "resolveFlowContent"]);
+  });
+
+  test("multiple format plugins coexist — only matching one transforms", async () => {
+    const aPlugin: PlayerPlugin = {
+      name: "a",
+      apply(p) {
+        p.hooks.transformContent.tap("a", (c, meta) =>
+          meta.format === "a" ? flowFor("from-a") : undefined,
+        );
+      },
+    };
+    const bPlugin: PlayerPlugin = {
+      name: "b",
+      apply(p) {
+        p.hooks.transformContent.tap("b", (c, meta) =>
+          meta.format === "b" ? flowFor("from-b") : undefined,
+        );
+      },
+    };
+
+    const player = new Player({ plugins: [aPlugin, bPlugin] });
+    player.start({ raw: true }, { format: "b" });
+
+    const state = player.getState() as InProgressState;
+    expect(state.flow.id).toBe("from-b");
+  });
+
+  test("version is plumbed from StartOptions to the hook's meta arg", () => {
+    const versions: Array<string | undefined> = [];
+    const probe: PlayerPlugin = {
+      name: "probe",
+      apply(p) {
+        p.hooks.transformContent.tap("probe", (c, meta) => {
+          versions.push(meta.version);
+          // For format !== "demo", return undefined so the default path runs.
+          if (meta.format !== "demo") return undefined;
+          return flowFor("demo");
+        });
+      },
+    };
+
+    const player = new Player({ plugins: [probe] });
+    player.start({ x: 1 }, { format: "demo", version: "2" });
+    player.start({ x: 1 }, { format: "demo", version: "1" });
+    player.start(flowFor("noversion"));
+
+    expect(versions).toEqual(["2", "1", undefined]);
+  });
+
+  test("errors when no tap transforms an unknown format into a Flow", async () => {
+    const player = new Player();
+    const result = player.start({ some: "content" }, { format: "unknown" });
+    await expect(result).rejects.toThrow(/format "unknown"/);
+  });
+});

package/src/controllers/data/utils.ts

@@ -12,7 +12,7 @@ export class ReadOnlyDataController
     this.controller = controller;
   }
 
-  get(binding: BindingLike, options?: DataModelOptions | undefined) {
+  get(binding: BindingLike, options?: DataModelOptions | undefined): any {
     return this.controller.get(binding, options);
   }
 }

package/src/player.ts

@@ -3,7 +3,7 @@ import deferred from "p-defer";
 import type { Flow, FlowResult } from "@player-ui/types";
 import queueMicrotask from "queue-microtask";
 
-import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { SyncBailHook, SyncHook, SyncWaterfallHook } from "tapable-ts";
 import type { Logger } from "./logger";
 import { TapableLogger } from "./logger";
 import type { ExpressionType } from "./expressions";
@@ -29,6 +29,8 @@ import type {
   CompletedState,
   ErrorState,
   PlayerHooks,
+  ContentMeta,
+  StartOptions,
 } from "./types";
 import { NOT_STARTED_STATE } from "./types";
 
@@ -125,6 +127,7 @@ export class Player {
     onStart: new SyncHook<[Flow]>(),
     onEnd: new SyncHook<[]>(),
     resolveFlowContent: new SyncWaterfallHook<[Flow]>(),
+    transformContent: new SyncBailHook<[unknown, ContentMeta], Flow>(),
   };
 
   constructor(config?: PlayerConfigOptions) {
@@ -141,6 +144,13 @@ export class Player {
     this.config.plugins?.forEach((plugin) => {
       plugin.apply(this);
     });
+
+    // Default content handler: a `"player"`-format payload is already a `Flow`.
+    // Registered after plugins so a format plugin gets first claim on the bail
+    // hook; this is the fallback that lets `start()` require a `Flow` out.
+    this.hooks.transformContent.tap("player", (payload, meta) =>
+      meta.format === "player" ? (payload as Flow) : undefined,
+    );
   }
 
   /**  Returns currently registered plugins */
@@ -513,8 +523,21 @@ export class Player {
     };
   }
 
-  public async start(payload: Flow): Promise<CompletedState> {
-    const ref = Symbol(payload?.id ?? "payload");
+  public async start(
+    payload: unknown,
+    options?: StartOptions,
+  ): Promise<CompletedState> {
+    const meta: ContentMeta = {
+      format: options?.format ?? "player",
+      version: options?.version,
+    };
+    const flow = this.hooks.transformContent.call(payload, meta);
+    if (!flow) {
+      throw new Error(
+        `Player.start received content with format "${meta.format}" that no plugin transformed into a Flow.`,
+      );
+    }
+    const ref = Symbol(flow.id ?? "payload");
 
     /** A check to avoid updating the state for a flow that's not the current one */
     const maybeUpdateState = <T extends PlayerFlowState>(newState: T) => {
@@ -537,7 +560,7 @@ export class Player {
     });
 
     try {
-      const { state, start } = this.setupFlow(payload);
+      const { state, start } = this.setupFlow(flow);
       this.setState({
         ref,
         ...state,
@@ -564,7 +587,7 @@ export class Player {
       const errorState: ErrorState = {
         status: "error",
         ref,
-        flow: payload,
+        flow,
         error,
       };
 

package/src/types.ts

@@ -11,9 +11,39 @@ import type {
   ErrorController,
 } from "./controllers";
 import type { ReadOnlyDataController } from "./controllers/data/utils";
-import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { SyncBailHook, SyncHook, SyncWaterfallHook } from "tapable-ts";
 import { ViewInstance } from "./view";
 
+/**
+ * Metadata describing the incoming content to `Player.start()`. Passed
+ * alongside the raw payload through the `transformContent` hook so plugins
+ * can decide whether to claim/convert it.
+ */
+export interface ContentMeta {
+  /**
+   * Content format identifier. `"player"` (default) means the input is
+   * already a `Flow` and needs no conversion. Anything else is a free-form
+   * string a plugin can recognize.
+   */
+  format: string;
+  /**
+   * Optional format version (e.g., `"0.9"`). Free-form — plugins decide the
+   * convention. Lets a single format plugin dispatch across major/minor
+   * versions without the caller picking a different `format` string.
+   */
+  version?: string;
+}
+
+/**
+ * Options passed to `Player.start()` alongside the payload.
+ */
+export interface StartOptions {
+  /** Identifier of the input content's format. Default: `"player"`. */
+  format?: string;
+  /** Optional content-format version. See `ContentMeta.version`. */
+  version?: string;
+}
+
 /**
  * Public Player Hooks
  */
@@ -47,6 +77,16 @@ export interface PlayerHooks {
     [Flow<Asset<string>>],
     Record<string, any>
   >;
+  /**
+   * Transform raw input content into a Player `Flow` before any state is set
+   * up. Fires at the top of `Player.start()` — after plugins are applied,
+   * before `resolveFlowContent`. Being a bail hook, taps inspect `meta.format`
+   * (and optionally `meta.version`) and return a `Flow` to claim the content;
+   * returning `undefined` passes to the next tap. Player registers a default
+   * tap for the `"player"` format that returns the payload as-is, so the hook
+   * is guaranteed to yield a `Flow` and `start()` needs no type-casting.
+   */
+  transformContent: SyncBailHook<[unknown, ContentMeta], Flow<Asset<string>>>;
 }
 
 /** The status for a flow's execution state */

package/types/player.d.ts

@@ -1,8 +1,7 @@
-import type { Flow } from "@player-ui/types";
 import type { Logger } from "./logger";
 import { TapableLogger } from "./logger";
 import { ConstantsController } from "./controllers";
-import type { PlayerFlowState, CompletedState, PlayerHooks } from "./types";
+import type { PlayerFlowState, CompletedState, PlayerHooks, StartOptions } from "./types";
 /**
 Variables injected at build time
 */
@@ -75,7 +74,7 @@ export declare class Player {
     private setState;
     /** Start Player with the given flow */
     private setupFlow;
-    start(payload: Flow): Promise<CompletedState>;
+    start(payload: unknown, options?: StartOptions): Promise<CompletedState>;
 }
 export {};
 //# sourceMappingURL=player.d.ts.map

package/types/types.d.ts

@@ -5,8 +5,36 @@ import type { ExpressionEvaluator } from "./expressions";
 import type { Logger } from "./logger";
 import type { ViewController, DataController, ValidationController, FlowController, ErrorController } from "./controllers";
 import type { ReadOnlyDataController } from "./controllers/data/utils";
-import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { SyncBailHook, SyncHook, SyncWaterfallHook } from "tapable-ts";
 import { ViewInstance } from "./view";
+/**
+ * Metadata describing the incoming content to `Player.start()`. Passed
+ * alongside the raw payload through the `transformContent` hook so plugins
+ * can decide whether to claim/convert it.
+ */
+export interface ContentMeta {
+    /**
+     * Content format identifier. `"player"` (default) means the input is
+     * already a `Flow` and needs no conversion. Anything else is a free-form
+     * string a plugin can recognize.
+     */
+    format: string;
+    /**
+     * Optional format version (e.g., `"0.9"`). Free-form — plugins decide the
+     * convention. Lets a single format plugin dispatch across major/minor
+     * versions without the caller picking a different `format` string.
+     */
+    version?: string;
+}
+/**
+ * Options passed to `Player.start()` alongside the payload.
+ */
+export interface StartOptions {
+    /** Identifier of the input content's format. Default: `"player"`. */
+    format?: string;
+    /** Optional content-format version. See `ContentMeta.version`. */
+    version?: string;
+}
 /**
  * Public Player Hooks
  */
@@ -39,6 +67,16 @@ export interface PlayerHooks {
     resolveFlowContent: SyncWaterfallHook<[
         Flow<Asset<string>>
     ], Record<string, any>>;
+    /**
+     * Transform raw input content into a Player `Flow` before any state is set
+     * up. Fires at the top of `Player.start()` — after plugins are applied,
+     * before `resolveFlowContent`. Being a bail hook, taps inspect `meta.format`
+     * (and optionally `meta.version`) and return a `Flow` to claim the content;
+     * returning `undefined` passes to the next tap. Player registers a default
+     * tap for the `"player"` format that returns the payload as-is, so the hook
+     * is guaranteed to yield a `Flow` and `start()` needs no type-casting.
+     */
+    transformContent: SyncBailHook<[unknown, ContentMeta], Flow<Asset<string>>>;
 }
 /** The status for a flow's execution state */
 export type PlayerFlowStatus = "not-started" | "in-progress" | "completed" | "error";