@player-ui/external-state-plugin 0.15.4--canary.881.37421

package/dist/cjs/index.cjs

@@ -0,0 +1,196 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ExternalStateError: () => ExternalStateError,
+  ExternalStatePlugin: () => ExternalStatePlugin
+});
+module.exports = __toCommonJS(src_exports);
+var import_partial_match_registry = require("@player-ui/partial-match-registry");
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/symbols.ts
+var ExternalStatePluginSymbol = Symbol.for(
+  "@player-ui/ExternalStatePlugin"
+);
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/ExternalStateError.ts
+var import_player = require("@player-ui/player");
+var ExternalStateError = class _ExternalStateError extends Error {
+  constructor(message, metadata) {
+    super(message);
+    this.type = import_player.ErrorTypes.EXTERNAL_STATE;
+    this.severity = import_player.ErrorSeverity.ERROR;
+    this.metadata = metadata;
+  }
+  /** No handler was registered for the EXTERNAL state's ref. */
+  static missingHandler(ref) {
+    return new _ExternalStateError(
+      `No handler found for external state with ref: "${ref}". Ensure a handler is registered for this state.`,
+      { ref, reason: "missing-handler" }
+    );
+  }
+  /** A handler ran but returned no transition value. */
+  static missingTransitionValue(ref) {
+    return new _ExternalStateError(
+      `Handler for external state with ref: "${ref}" did not return a transition value. Ensure the handler returns the name of a valid transition.`,
+      { ref, reason: "missing-transition-value" }
+    );
+  }
+};
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts
+function isExternal(state) {
+  return state.state_type === "EXTERNAL";
+}
+function isInProgress(state) {
+  return state.status === "in-progress";
+}
+var _ExternalStatePlugin = class _ExternalStatePlugin {
+  /** Creates a new ExternalStatePlugin */
+  constructor(handlers) {
+    this.name = "ExternalStatePlugin";
+    this.symbol = _ExternalStatePlugin.Symbol;
+    this.handlers = handlers;
+  }
+  apply(player) {
+    const isFirstInstance = this.createRegistry(player);
+    this.registerHandlers(player);
+    if (!isFirstInstance) {
+      return;
+    }
+    player.hooks.errorController.tap(this.name, (errorController) => {
+      this.errorController = errorController;
+    });
+    player.hooks.flowController.tap(this.name, (flowController) => {
+      flowController.hooks.flow.tap(this.name, (flow) => {
+        flow.hooks.afterTransition.tap(this.name, (flowInstance) => {
+          this.handleAfterTransition(player, flowInstance);
+        });
+      });
+    });
+  }
+  /**
+   * Resolve an EXTERNAL state transition.
+   */
+  async handleAfterTransition(player, flowInstance) {
+    const toState = flowInstance.currentState;
+    const currentState = player.getState();
+    if (!toState || !toState.value || !isExternal(toState.value) || !isInProgress(currentState)) {
+      return;
+    }
+    try {
+      const handler = this.registry?.get(toState.value);
+      if (!handler) {
+        this.reportError(
+          player,
+          ExternalStateError.missingHandler(toState.value.ref)
+        );
+        return;
+      }
+      const transitionValue = await handler(
+        toState.value,
+        currentState.controllers
+      );
+      if (!transitionValue) {
+        this.reportError(
+          player,
+          ExternalStateError.missingTransitionValue(toState.value.ref)
+        );
+        return;
+      }
+      const latestState = player.getState();
+      if (isInProgress(latestState) && latestState.controllers.flow.current?.currentState?.name === toState.name) {
+        latestState.controllers.flow.transition(transitionValue);
+      } else {
+        player.logger.warn(
+          `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        currentState.fail(error);
+      }
+    }
+  }
+  /**
+   * Report an ExternalStateError via the errorController.
+   */
+  reportError(player, error) {
+    if (!this.errorController) {
+      player.logger.error(
+        `${error.message} (errorController was unexpectedly undefined; it should always be set by the time this code runs)`
+      );
+      return;
+    }
+    this.errorController.captureError(error);
+  }
+  /**
+   * Create or share the registry for this plugin instance.
+   *
+   * Uses the Player's plugin registry to find if another instance of ExternalStatePlugin
+   * has already been registered. If found, this instance will share that plugin's registry.
+   * Otherwise, this instance creates a new registry.
+   */
+  createRegistry(player) {
+    const existing = player.findPlugin(
+      ExternalStatePluginSymbol
+    );
+    if (existing && existing !== this) {
+      this.registry = existing.registry;
+      return false;
+    }
+    this.registry = new import_partial_match_registry.Registry(
+      void 0,
+      player.logger
+    );
+    return true;
+  }
+  /**
+   * Register this plugin's handlers to the shared registry.
+   *
+   * If a handler with the same specificity already exists, it will be replaced
+   * and a debug log will be emitted (accessible via player.logger.debug).
+   */
+  registerHandlers(player) {
+    for (const handler of this.handlers) {
+      if (handler.match?.ref) {
+        player.logger.warn(
+          `An ExternalStateHandler contains a superfluous 'match.ref' property. 'match.ref' will be ignored. 'ref' will be used instead. Handler: ${JSON.stringify({ ref: handler.ref, match: handler.match })}`
+        );
+        delete handler.match?.["ref"];
+        continue;
+      }
+      this.registry?.set(
+        { ref: handler.ref, ...handler.match },
+        handler.handlerFunction
+      );
+    }
+  }
+};
+/** Symbol used to identify and find existing instances of this plugin */
+_ExternalStatePlugin.Symbol = ExternalStatePluginSymbol;
+var ExternalStatePlugin = _ExternalStatePlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExternalStateError,
+  ExternalStatePlugin
+});
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts","../../../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/symbols.ts","../../../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/ExternalStateError.ts"],"sourcesContent":["import type {\n  Player,\n  PlayerPlugin,\n  InProgressState,\n  PlayerFlowState,\n  NavigationFlowState,\n  NavigationFlowExternalState,\n  ErrorController,\n  FlowInstance,\n} from \"@player-ui/player\";\nimport { Registry } from \"@player-ui/partial-match-registry\";\nimport { ExternalStatePluginSymbol } from \"./symbols.js\";\nimport { ExternalStateError } from \"./ExternalStateError.js\";\n\nexport { ExternalStateError } from \"./ExternalStateError.js\";\nexport type { ExternalStateErrorMetadata } from \"./ExternalStateError.js\";\n\nexport type ExternalStateHandlerMatch = Record<string, unknown>;\n\nexport type ExternalStateHandlerFunction = (\n  state: NavigationFlowExternalState,\n  options: InProgressState[\"controllers\"],\n) => string | undefined | Promise<string | undefined>;\n\nexport type ExternalStateHandler = {\n  /** The name of the external state. This will appear as it's \"ref\" property in the DSL. */\n  ref: string;\n  /** Additional properties to match against the external state. */\n  match?: ExternalStateHandlerMatch;\n  /** The function to run when the external state is transitioned to. This should return the `ref` of the next state to transition to. */\n  handlerFunction: ExternalStateHandlerFunction;\n};\n\nfunction isExternal(\n  state: NavigationFlowState,\n): state is NavigationFlowExternalState {\n  return state.state_type === \"EXTERNAL\";\n}\n\nfunction isInProgress(state: PlayerFlowState): state is InProgressState {\n  return state.status === \"in-progress\";\n}\n\n/**\n * A plugin to handle external states\n *\n * This plugin uses a registry-based approach to match external states to handler functions.\n * Multiple plugins can be registered, and handlers are matched using partial object matching\n * with specificity ordering (more specific matches take precedence).\n */\nexport class ExternalStatePlugin implements PlayerPlugin {\n  name = \"ExternalStatePlugin\";\n\n  /** Symbol used to identify and find existing instances of this plugin */\n  static Symbol: symbol = ExternalStatePluginSymbol;\n  public readonly symbol: symbol = ExternalStatePlugin.Symbol;\n\n  /**\n   * The shared registry that maps external states to handlers.\n   * All plugin instances use the same registry.\n   */\n  private registry?: Registry<ExternalStateHandlerFunction>;\n\n  /**\n   * The handlers for this plugin instance.\n   */\n  private readonly handlers: ExternalStateHandler[];\n\n  /** The error controller to use for this plugin.\n   * Only the first instance of the plugin should tap the error controller hook.\n   */\n  private errorController?: ErrorController;\n\n  /** Creates a new ExternalStatePlugin */\n  constructor(handlers: ExternalStateHandler[]) {\n    this.handlers = handlers;\n  }\n\n  apply(player: Player): void {\n    const isFirstInstance = this.createRegistry(player);\n    this.registerHandlers(player);\n\n    // Only the first instance should tap the hooks to avoid redundant taps\n    if (!isFirstInstance) {\n      return;\n    }\n\n    player.hooks.errorController.tap(this.name, (errorController) => {\n      this.errorController = errorController;\n    });\n\n    player.hooks.flowController.tap(this.name, (flowController) => {\n      flowController.hooks.flow.tap(this.name, (flow) => {\n        flow.hooks.afterTransition.tap(this.name, (flowInstance) => {\n          this.handleAfterTransition(player, flowInstance);\n        });\n      });\n    });\n  }\n\n  /**\n   * Resolve an EXTERNAL state transition.\n   */\n  private async handleAfterTransition(\n    player: Player,\n    flowInstance: FlowInstance,\n  ): Promise<void> {\n    const toState = flowInstance.currentState;\n    const currentState = player.getState();\n\n    if (\n      !toState ||\n      !toState.value ||\n      !isExternal(toState.value) ||\n      !isInProgress(currentState)\n    ) {\n      return;\n    }\n\n    try {\n      const handler = this.registry?.get(toState.value);\n\n      if (!handler) {\n        this.reportError(\n          player,\n          ExternalStateError.missingHandler(toState.value.ref),\n        );\n        return;\n      }\n\n      const transitionValue = await handler(\n        toState.value,\n        currentState.controllers,\n      );\n\n      if (!transitionValue) {\n        this.reportError(\n          player,\n          ExternalStateError.missingTransitionValue(toState.value.ref),\n        );\n        return;\n      }\n\n      const latestState = player.getState();\n\n      // Ensure the Player is still in the same state after waiting for transitionValue\n      if (\n        isInProgress(latestState) &&\n        latestState.controllers.flow.current?.currentState?.name ===\n          toState.name\n      ) {\n        latestState.controllers.flow.transition(transitionValue);\n      } else {\n        player.logger.warn(\n          `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`,\n        );\n      }\n    } catch (error) {\n      // Thrown errors are treated as purposefully unrecoverable: fail the flow rather than\n      // routing through captureError.\n      if (error instanceof Error) {\n        currentState.fail(error);\n      }\n    }\n  }\n\n  /**\n   * Report an ExternalStateError via the errorController.\n   */\n  private reportError(player: Player, error: ExternalStateError): void {\n    // The compiler believes errorController could be nil, but in practice it should always\n    // be set by the time this method runs. The logger fallback exists only as defense\n    // against an unexpected lifecycle regression — if it ever fires, that's a bug to\n    // investigate, not normal operation.\n    if (!this.errorController) {\n      player.logger.error(\n        `${error.message} (errorController was unexpectedly undefined; it should always be set by the time this code runs)`,\n      );\n      return;\n    }\n\n    this.errorController.captureError(error);\n  }\n\n  /**\n   * Create or share the registry for this plugin instance.\n   *\n   * Uses the Player's plugin registry to find if another instance of ExternalStatePlugin\n   * has already been registered. If found, this instance will share that plugin's registry.\n   * Otherwise, this instance creates a new registry.\n   */\n  private createRegistry(player: Player): boolean {\n    // Find the first instance of this plugin registered to the Player\n    const existing = player.findPlugin<ExternalStatePlugin>(\n      ExternalStatePluginSymbol,\n    );\n\n    // If we found a plugin and it's not ourselves, we are not the first plugin instance\n    if (existing && existing !== this) {\n      // Use the first plugin's registry\n      this.registry = existing.registry;\n      return false;\n    }\n\n    // We are the first plugin instance, create the registry\n    this.registry = new Registry<ExternalStateHandlerFunction>(\n      undefined,\n      player.logger,\n    );\n    return true;\n  }\n\n  /**\n   * Register this plugin's handlers to the shared registry.\n   *\n   * If a handler with the same specificity already exists, it will be replaced\n   * and a debug log will be emitted (accessible via player.logger.debug).\n   */\n  private registerHandlers(player: Player): void {\n    for (const handler of this.handlers) {\n      // Runtime check for 'ref' property is necessary despite TypeScript constraint because\n      // the Swift bridge allows improperly formatted objects to bypass TypeScript validation.\n      // We log this here and not in the constructor because the Logger is not yet available in the constructor.\n      if (handler.match?.ref) {\n        player.logger.warn(\n          `An ExternalStateHandler contains a superfluous 'match.ref' property. 'match.ref' will be ignored. 'ref' will be used instead. Handler: ${JSON.stringify({ ref: handler.ref, match: handler.match })}`,\n        );\n        delete handler.match?.[\"ref\"];\n        continue;\n      }\n      // Registry will handle keeping only the last handlerFunction for each match\n      this.registry?.set(\n        { ref: handler.ref, ...handler.match },\n        handler.handlerFunction,\n      );\n    }\n  }\n}\n","// We prefix with \"@player-ui\" to avoid conflicts with symbols from other packages\nexport const ExternalStatePluginSymbol: symbol = Symbol.for(\n  \"@player-ui/ExternalStatePlugin\",\n);\n","import type { ErrorMetadata, PlayerErrorMetadata } from \"@player-ui/player\";\nimport { ErrorSeverity, ErrorTypes } from \"@player-ui/player\";\n\nexport type ExternalStateErrorReason =\n  | \"missing-handler\"\n  | \"missing-transition-value\";\n\nexport interface ExternalStateErrorMetadata extends ErrorMetadata {\n  /** The `ref` of the EXTERNAL state that produced the error */\n  ref: string;\n  /** Which failure mode this error represents */\n  reason: ExternalStateErrorReason;\n}\n\nexport class ExternalStateError\n  extends Error\n  implements PlayerErrorMetadata<ExternalStateErrorMetadata>\n{\n  readonly type: string = ErrorTypes.EXTERNAL_STATE;\n  readonly severity: ErrorSeverity = ErrorSeverity.ERROR;\n  readonly metadata: ExternalStateErrorMetadata;\n\n  private constructor(message: string, metadata: ExternalStateErrorMetadata) {\n    super(message);\n    this.metadata = metadata;\n  }\n\n  /** No handler was registered for the EXTERNAL state's ref. */\n  static missingHandler(ref: string): ExternalStateError {\n    return new ExternalStateError(\n      `No handler found for external state with ref: \"${ref}\". ` +\n        `Ensure a handler is registered for this state.`,\n      { ref, reason: \"missing-handler\" },\n    );\n  }\n\n  /** A handler ran but returned no transition value. */\n  static missingTransitionValue(ref: string): ExternalStateError {\n    return new ExternalStateError(\n      `Handler for external state with ref: \"${ref}\" did not return a transition value. ` +\n        `Ensure the handler returns the name of a valid transition.`,\n      { ref, reason: \"missing-transition-value\" },\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.legacy-esm.js

@@ -0,0 +1,170 @@
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts
+import { Registry } from "@player-ui/partial-match-registry";
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/symbols.ts
+var ExternalStatePluginSymbol = Symbol.for(
+  "@player-ui/ExternalStatePlugin"
+);
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/ExternalStateError.ts
+import { ErrorSeverity, ErrorTypes } from "@player-ui/player";
+var ExternalStateError = class _ExternalStateError extends Error {
+  constructor(message, metadata) {
+    super(message);
+    this.type = ErrorTypes.EXTERNAL_STATE;
+    this.severity = ErrorSeverity.ERROR;
+    this.metadata = metadata;
+  }
+  /** No handler was registered for the EXTERNAL state's ref. */
+  static missingHandler(ref) {
+    return new _ExternalStateError(
+      `No handler found for external state with ref: "${ref}". Ensure a handler is registered for this state.`,
+      { ref, reason: "missing-handler" }
+    );
+  }
+  /** A handler ran but returned no transition value. */
+  static missingTransitionValue(ref) {
+    return new _ExternalStateError(
+      `Handler for external state with ref: "${ref}" did not return a transition value. Ensure the handler returns the name of a valid transition.`,
+      { ref, reason: "missing-transition-value" }
+    );
+  }
+};
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts
+function isExternal(state) {
+  return state.state_type === "EXTERNAL";
+}
+function isInProgress(state) {
+  return state.status === "in-progress";
+}
+var _ExternalStatePlugin = class _ExternalStatePlugin {
+  /** Creates a new ExternalStatePlugin */
+  constructor(handlers) {
+    this.name = "ExternalStatePlugin";
+    this.symbol = _ExternalStatePlugin.Symbol;
+    this.handlers = handlers;
+  }
+  apply(player) {
+    const isFirstInstance = this.createRegistry(player);
+    this.registerHandlers(player);
+    if (!isFirstInstance) {
+      return;
+    }
+    player.hooks.errorController.tap(this.name, (errorController) => {
+      this.errorController = errorController;
+    });
+    player.hooks.flowController.tap(this.name, (flowController) => {
+      flowController.hooks.flow.tap(this.name, (flow) => {
+        flow.hooks.afterTransition.tap(this.name, (flowInstance) => {
+          this.handleAfterTransition(player, flowInstance);
+        });
+      });
+    });
+  }
+  /**
+   * Resolve an EXTERNAL state transition.
+   */
+  async handleAfterTransition(player, flowInstance) {
+    const toState = flowInstance.currentState;
+    const currentState = player.getState();
+    if (!toState || !toState.value || !isExternal(toState.value) || !isInProgress(currentState)) {
+      return;
+    }
+    try {
+      const handler = this.registry?.get(toState.value);
+      if (!handler) {
+        this.reportError(
+          player,
+          ExternalStateError.missingHandler(toState.value.ref)
+        );
+        return;
+      }
+      const transitionValue = await handler(
+        toState.value,
+        currentState.controllers
+      );
+      if (!transitionValue) {
+        this.reportError(
+          player,
+          ExternalStateError.missingTransitionValue(toState.value.ref)
+        );
+        return;
+      }
+      const latestState = player.getState();
+      if (isInProgress(latestState) && latestState.controllers.flow.current?.currentState?.name === toState.name) {
+        latestState.controllers.flow.transition(transitionValue);
+      } else {
+        player.logger.warn(
+          `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        currentState.fail(error);
+      }
+    }
+  }
+  /**
+   * Report an ExternalStateError via the errorController.
+   */
+  reportError(player, error) {
+    if (!this.errorController) {
+      player.logger.error(
+        `${error.message} (errorController was unexpectedly undefined; it should always be set by the time this code runs)`
+      );
+      return;
+    }
+    this.errorController.captureError(error);
+  }
+  /**
+   * Create or share the registry for this plugin instance.
+   *
+   * Uses the Player's plugin registry to find if another instance of ExternalStatePlugin
+   * has already been registered. If found, this instance will share that plugin's registry.
+   * Otherwise, this instance creates a new registry.
+   */
+  createRegistry(player) {
+    const existing = player.findPlugin(
+      ExternalStatePluginSymbol
+    );
+    if (existing && existing !== this) {
+      this.registry = existing.registry;
+      return false;
+    }
+    this.registry = new Registry(
+      void 0,
+      player.logger
+    );
+    return true;
+  }
+  /**
+   * Register this plugin's handlers to the shared registry.
+   *
+   * If a handler with the same specificity already exists, it will be replaced
+   * and a debug log will be emitted (accessible via player.logger.debug).
+   */
+  registerHandlers(player) {
+    for (const handler of this.handlers) {
+      if (handler.match?.ref) {
+        player.logger.warn(
+          `An ExternalStateHandler contains a superfluous 'match.ref' property. 'match.ref' will be ignored. 'ref' will be used instead. Handler: ${JSON.stringify({ ref: handler.ref, match: handler.match })}`
+        );
+        delete handler.match?.["ref"];
+        continue;
+      }
+      this.registry?.set(
+        { ref: handler.ref, ...handler.match },
+        handler.handlerFunction
+      );
+    }
+  }
+};
+/** Symbol used to identify and find existing instances of this plugin */
+_ExternalStatePlugin.Symbol = ExternalStatePluginSymbol;
+var ExternalStatePlugin = _ExternalStatePlugin;
+export {
+  ExternalStateError,
+  ExternalStatePlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs

@@ -0,0 +1,170 @@
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts
+import { Registry } from "@player-ui/partial-match-registry";
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/symbols.ts
+var ExternalStatePluginSymbol = Symbol.for(
+  "@player-ui/ExternalStatePlugin"
+);
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/ExternalStateError.ts
+import { ErrorSeverity, ErrorTypes } from "@player-ui/player";
+var ExternalStateError = class _ExternalStateError extends Error {
+  constructor(message, metadata) {
+    super(message);
+    this.type = ErrorTypes.EXTERNAL_STATE;
+    this.severity = ErrorSeverity.ERROR;
+    this.metadata = metadata;
+  }
+  /** No handler was registered for the EXTERNAL state's ref. */
+  static missingHandler(ref) {
+    return new _ExternalStateError(
+      `No handler found for external state with ref: "${ref}". Ensure a handler is registered for this state.`,
+      { ref, reason: "missing-handler" }
+    );
+  }
+  /** A handler ran but returned no transition value. */
+  static missingTransitionValue(ref) {
+    return new _ExternalStateError(
+      `Handler for external state with ref: "${ref}" did not return a transition value. Ensure the handler returns the name of a valid transition.`,
+      { ref, reason: "missing-transition-value" }
+    );
+  }
+};
+
+// ../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts
+function isExternal(state) {
+  return state.state_type === "EXTERNAL";
+}
+function isInProgress(state) {
+  return state.status === "in-progress";
+}
+var _ExternalStatePlugin = class _ExternalStatePlugin {
+  /** Creates a new ExternalStatePlugin */
+  constructor(handlers) {
+    this.name = "ExternalStatePlugin";
+    this.symbol = _ExternalStatePlugin.Symbol;
+    this.handlers = handlers;
+  }
+  apply(player) {
+    const isFirstInstance = this.createRegistry(player);
+    this.registerHandlers(player);
+    if (!isFirstInstance) {
+      return;
+    }
+    player.hooks.errorController.tap(this.name, (errorController) => {
+      this.errorController = errorController;
+    });
+    player.hooks.flowController.tap(this.name, (flowController) => {
+      flowController.hooks.flow.tap(this.name, (flow) => {
+        flow.hooks.afterTransition.tap(this.name, (flowInstance) => {
+          this.handleAfterTransition(player, flowInstance);
+        });
+      });
+    });
+  }
+  /**
+   * Resolve an EXTERNAL state transition.
+   */
+  async handleAfterTransition(player, flowInstance) {
+    const toState = flowInstance.currentState;
+    const currentState = player.getState();
+    if (!toState || !toState.value || !isExternal(toState.value) || !isInProgress(currentState)) {
+      return;
+    }
+    try {
+      const handler = this.registry?.get(toState.value);
+      if (!handler) {
+        this.reportError(
+          player,
+          ExternalStateError.missingHandler(toState.value.ref)
+        );
+        return;
+      }
+      const transitionValue = await handler(
+        toState.value,
+        currentState.controllers
+      );
+      if (!transitionValue) {
+        this.reportError(
+          player,
+          ExternalStateError.missingTransitionValue(toState.value.ref)
+        );
+        return;
+      }
+      const latestState = player.getState();
+      if (isInProgress(latestState) && latestState.controllers.flow.current?.currentState?.name === toState.name) {
+        latestState.controllers.flow.transition(transitionValue);
+      } else {
+        player.logger.warn(
+          `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        currentState.fail(error);
+      }
+    }
+  }
+  /**
+   * Report an ExternalStateError via the errorController.
+   */
+  reportError(player, error) {
+    if (!this.errorController) {
+      player.logger.error(
+        `${error.message} (errorController was unexpectedly undefined; it should always be set by the time this code runs)`
+      );
+      return;
+    }
+    this.errorController.captureError(error);
+  }
+  /**
+   * Create or share the registry for this plugin instance.
+   *
+   * Uses the Player's plugin registry to find if another instance of ExternalStatePlugin
+   * has already been registered. If found, this instance will share that plugin's registry.
+   * Otherwise, this instance creates a new registry.
+   */
+  createRegistry(player) {
+    const existing = player.findPlugin(
+      ExternalStatePluginSymbol
+    );
+    if (existing && existing !== this) {
+      this.registry = existing.registry;
+      return false;
+    }
+    this.registry = new Registry(
+      void 0,
+      player.logger
+    );
+    return true;
+  }
+  /**
+   * Register this plugin's handlers to the shared registry.
+   *
+   * If a handler with the same specificity already exists, it will be replaced
+   * and a debug log will be emitted (accessible via player.logger.debug).
+   */
+  registerHandlers(player) {
+    for (const handler of this.handlers) {
+      if (handler.match?.ref) {
+        player.logger.warn(
+          `An ExternalStateHandler contains a superfluous 'match.ref' property. 'match.ref' will be ignored. 'ref' will be used instead. Handler: ${JSON.stringify({ ref: handler.ref, match: handler.match })}`
+        );
+        delete handler.match?.["ref"];
+        continue;
+      }
+      this.registry?.set(
+        { ref: handler.ref, ...handler.match },
+        handler.handlerFunction
+      );
+    }
+  }
+};
+/** Symbol used to identify and find existing instances of this plugin */
+_ExternalStatePlugin.Symbol = ExternalStatePluginSymbol;
+var ExternalStatePlugin = _ExternalStatePlugin;
+export {
+  ExternalStateError,
+  ExternalStatePlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/index.ts","../../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/symbols.ts","../../../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/plugins/external-state/core/src/ExternalStateError.ts"],"sourcesContent":["import type {\n  Player,\n  PlayerPlugin,\n  InProgressState,\n  PlayerFlowState,\n  NavigationFlowState,\n  NavigationFlowExternalState,\n  ErrorController,\n  FlowInstance,\n} from \"@player-ui/player\";\nimport { Registry } from \"@player-ui/partial-match-registry\";\nimport { ExternalStatePluginSymbol } from \"./symbols.js\";\nimport { ExternalStateError } from \"./ExternalStateError.js\";\n\nexport { ExternalStateError } from \"./ExternalStateError.js\";\nexport type { ExternalStateErrorMetadata } from \"./ExternalStateError.js\";\n\nexport type ExternalStateHandlerMatch = Record<string, unknown>;\n\nexport type ExternalStateHandlerFunction = (\n  state: NavigationFlowExternalState,\n  options: InProgressState[\"controllers\"],\n) => string | undefined | Promise<string | undefined>;\n\nexport type ExternalStateHandler = {\n  /** The name of the external state. This will appear as it's \"ref\" property in the DSL. */\n  ref: string;\n  /** Additional properties to match against the external state. */\n  match?: ExternalStateHandlerMatch;\n  /** The function to run when the external state is transitioned to. This should return the `ref` of the next state to transition to. */\n  handlerFunction: ExternalStateHandlerFunction;\n};\n\nfunction isExternal(\n  state: NavigationFlowState,\n): state is NavigationFlowExternalState {\n  return state.state_type === \"EXTERNAL\";\n}\n\nfunction isInProgress(state: PlayerFlowState): state is InProgressState {\n  return state.status === \"in-progress\";\n}\n\n/**\n * A plugin to handle external states\n *\n * This plugin uses a registry-based approach to match external states to handler functions.\n * Multiple plugins can be registered, and handlers are matched using partial object matching\n * with specificity ordering (more specific matches take precedence).\n */\nexport class ExternalStatePlugin implements PlayerPlugin {\n  name = \"ExternalStatePlugin\";\n\n  /** Symbol used to identify and find existing instances of this plugin */\n  static Symbol: symbol = ExternalStatePluginSymbol;\n  public readonly symbol: symbol = ExternalStatePlugin.Symbol;\n\n  /**\n   * The shared registry that maps external states to handlers.\n   * All plugin instances use the same registry.\n   */\n  private registry?: Registry<ExternalStateHandlerFunction>;\n\n  /**\n   * The handlers for this plugin instance.\n   */\n  private readonly handlers: ExternalStateHandler[];\n\n  /** The error controller to use for this plugin.\n   * Only the first instance of the plugin should tap the error controller hook.\n   */\n  private errorController?: ErrorController;\n\n  /** Creates a new ExternalStatePlugin */\n  constructor(handlers: ExternalStateHandler[]) {\n    this.handlers = handlers;\n  }\n\n  apply(player: Player): void {\n    const isFirstInstance = this.createRegistry(player);\n    this.registerHandlers(player);\n\n    // Only the first instance should tap the hooks to avoid redundant taps\n    if (!isFirstInstance) {\n      return;\n    }\n\n    player.hooks.errorController.tap(this.name, (errorController) => {\n      this.errorController = errorController;\n    });\n\n    player.hooks.flowController.tap(this.name, (flowController) => {\n      flowController.hooks.flow.tap(this.name, (flow) => {\n        flow.hooks.afterTransition.tap(this.name, (flowInstance) => {\n          this.handleAfterTransition(player, flowInstance);\n        });\n      });\n    });\n  }\n\n  /**\n   * Resolve an EXTERNAL state transition.\n   */\n  private async handleAfterTransition(\n    player: Player,\n    flowInstance: FlowInstance,\n  ): Promise<void> {\n    const toState = flowInstance.currentState;\n    const currentState = player.getState();\n\n    if (\n      !toState ||\n      !toState.value ||\n      !isExternal(toState.value) ||\n      !isInProgress(currentState)\n    ) {\n      return;\n    }\n\n    try {\n      const handler = this.registry?.get(toState.value);\n\n      if (!handler) {\n        this.reportError(\n          player,\n          ExternalStateError.missingHandler(toState.value.ref),\n        );\n        return;\n      }\n\n      const transitionValue = await handler(\n        toState.value,\n        currentState.controllers,\n      );\n\n      if (!transitionValue) {\n        this.reportError(\n          player,\n          ExternalStateError.missingTransitionValue(toState.value.ref),\n        );\n        return;\n      }\n\n      const latestState = player.getState();\n\n      // Ensure the Player is still in the same state after waiting for transitionValue\n      if (\n        isInProgress(latestState) &&\n        latestState.controllers.flow.current?.currentState?.name ===\n          toState.name\n      ) {\n        latestState.controllers.flow.transition(transitionValue);\n      } else {\n        player.logger.warn(\n          `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`,\n        );\n      }\n    } catch (error) {\n      // Thrown errors are treated as purposefully unrecoverable: fail the flow rather than\n      // routing through captureError.\n      if (error instanceof Error) {\n        currentState.fail(error);\n      }\n    }\n  }\n\n  /**\n   * Report an ExternalStateError via the errorController.\n   */\n  private reportError(player: Player, error: ExternalStateError): void {\n    // The compiler believes errorController could be nil, but in practice it should always\n    // be set by the time this method runs. The logger fallback exists only as defense\n    // against an unexpected lifecycle regression — if it ever fires, that's a bug to\n    // investigate, not normal operation.\n    if (!this.errorController) {\n      player.logger.error(\n        `${error.message} (errorController was unexpectedly undefined; it should always be set by the time this code runs)`,\n      );\n      return;\n    }\n\n    this.errorController.captureError(error);\n  }\n\n  /**\n   * Create or share the registry for this plugin instance.\n   *\n   * Uses the Player's plugin registry to find if another instance of ExternalStatePlugin\n   * has already been registered. If found, this instance will share that plugin's registry.\n   * Otherwise, this instance creates a new registry.\n   */\n  private createRegistry(player: Player): boolean {\n    // Find the first instance of this plugin registered to the Player\n    const existing = player.findPlugin<ExternalStatePlugin>(\n      ExternalStatePluginSymbol,\n    );\n\n    // If we found a plugin and it's not ourselves, we are not the first plugin instance\n    if (existing && existing !== this) {\n      // Use the first plugin's registry\n      this.registry = existing.registry;\n      return false;\n    }\n\n    // We are the first plugin instance, create the registry\n    this.registry = new Registry<ExternalStateHandlerFunction>(\n      undefined,\n      player.logger,\n    );\n    return true;\n  }\n\n  /**\n   * Register this plugin's handlers to the shared registry.\n   *\n   * If a handler with the same specificity already exists, it will be replaced\n   * and a debug log will be emitted (accessible via player.logger.debug).\n   */\n  private registerHandlers(player: Player): void {\n    for (const handler of this.handlers) {\n      // Runtime check for 'ref' property is necessary despite TypeScript constraint because\n      // the Swift bridge allows improperly formatted objects to bypass TypeScript validation.\n      // We log this here and not in the constructor because the Logger is not yet available in the constructor.\n      if (handler.match?.ref) {\n        player.logger.warn(\n          `An ExternalStateHandler contains a superfluous 'match.ref' property. 'match.ref' will be ignored. 'ref' will be used instead. Handler: ${JSON.stringify({ ref: handler.ref, match: handler.match })}`,\n        );\n        delete handler.match?.[\"ref\"];\n        continue;\n      }\n      // Registry will handle keeping only the last handlerFunction for each match\n      this.registry?.set(\n        { ref: handler.ref, ...handler.match },\n        handler.handlerFunction,\n      );\n    }\n  }\n}\n","// We prefix with \"@player-ui\" to avoid conflicts with symbols from other packages\nexport const ExternalStatePluginSymbol: symbol = Symbol.for(\n  \"@player-ui/ExternalStatePlugin\",\n);\n","import type { ErrorMetadata, PlayerErrorMetadata } from \"@player-ui/player\";\nimport { ErrorSeverity, ErrorTypes } from \"@player-ui/player\";\n\nexport type ExternalStateErrorReason =\n  | \"missing-handler\"\n  | \"missing-transition-value\";\n\nexport interface ExternalStateErrorMetadata extends ErrorMetadata {\n  /** The `ref` of the EXTERNAL state that produced the error */\n  ref: string;\n  /** Which failure mode this error represents */\n  reason: ExternalStateErrorReason;\n}\n\nexport class ExternalStateError\n  extends Error\n  implements PlayerErrorMetadata<ExternalStateErrorMetadata>\n{\n  readonly type: string = ErrorTypes.EXTERNAL_STATE;\n  readonly severity: ErrorSeverity = ErrorSeverity.ERROR;\n  readonly metadata: ExternalStateErrorMetadata;\n\n  private constructor(message: string, metadata: ExternalStateErrorMetadata) {\n    super(message);\n    this.metadata = metadata;\n  }\n\n  /** No handler was registered for the EXTERNAL state's ref. */\n  static missingHandler(ref: string): ExternalStateError {\n    return new ExternalStateError(\n      `No handler found for external state with ref: \"${ref}\". ` +\n        `Ensure a handler is registered for this state.`,\n      { ref, reason: \"missing-handler\" },\n    );\n  }\n\n  /** A handler ran but returned no transition value. */\n  static missingTransitionValue(ref: string): ExternalStateError {\n    return new ExternalStateError(\n      `Handler for external state with ref: \"${ref}\" did not return a transition value. ` +\n        `Ensure the handler returns the name of a valid transition.`,\n      { ref, reason: \"missing-transition-value\" },\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "types"
+  ],
+  "name": "@player-ui/external-state-plugin",
+  "version": "0.15.4--canary.881.37421",
+  "main": "dist/cjs/index.cjs",
+  "dependencies": {
+    "@player-ui/partial-match-registry": "0.15.4--canary.881.37421",
+    "tslib": "^2.6.2"
+  },
+  "peerDependencies": {
+    "@player-ui/player": "0.15.4--canary.881.37421"
+  },
+  "module": "dist/index.legacy-esm.js",
+  "types": "types/index.d.ts",
+  "bundle": "dist/ExternalStatePlugin.native.js",
+  "exports": {
+    "./package.json": "./package.json",
+    "./dist/index.css": "./dist/index.css",
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/cjs/index.cjs"
+    }
+  }
+}

package/src/ExternalStateError.ts

@@ -0,0 +1,45 @@
+import type { ErrorMetadata, PlayerErrorMetadata } from "@player-ui/player";
+import { ErrorSeverity, ErrorTypes } from "@player-ui/player";
+
+export type ExternalStateErrorReason =
+  | "missing-handler"
+  | "missing-transition-value";
+
+export interface ExternalStateErrorMetadata extends ErrorMetadata {
+  /** The `ref` of the EXTERNAL state that produced the error */
+  ref: string;
+  /** Which failure mode this error represents */
+  reason: ExternalStateErrorReason;
+}
+
+export class ExternalStateError
+  extends Error
+  implements PlayerErrorMetadata<ExternalStateErrorMetadata>
+{
+  readonly type: string = ErrorTypes.EXTERNAL_STATE;
+  readonly severity: ErrorSeverity = ErrorSeverity.ERROR;
+  readonly metadata: ExternalStateErrorMetadata;
+
+  private constructor(message: string, metadata: ExternalStateErrorMetadata) {
+    super(message);
+    this.metadata = metadata;
+  }
+
+  /** No handler was registered for the EXTERNAL state's ref. */
+  static missingHandler(ref: string): ExternalStateError {
+    return new ExternalStateError(
+      `No handler found for external state with ref: "${ref}". ` +
+        `Ensure a handler is registered for this state.`,
+      { ref, reason: "missing-handler" },
+    );
+  }
+
+  /** A handler ran but returned no transition value. */
+  static missingTransitionValue(ref: string): ExternalStateError {
+    return new ExternalStateError(
+      `Handler for external state with ref: "${ref}" did not return a transition value. ` +
+        `Ensure the handler returns the name of a valid transition.`,
+      { ref, reason: "missing-transition-value" },
+    );
+  }
+}