@player-devtools/plugin 0.0.7--canary.8.483

package/src/helpers/genDataChangeTransaction.ts

@@ -0,0 +1,39 @@
+import type {
+  DevtoolsDataChangeEvent,
+  Transaction,
+} from "@player-devtools/types";
+import type { Flow } from "@player-ui/player";
+
+const NOOP_ID = -1;
+
+/**
+ * Generates a data change transaction for the player devtools plugin.
+ *
+ * This function creates a transaction object that represents a change in data
+ * within a player devtools plugin. The transaction includes details such as the
+ * plugin ID, the changed data, and the player ID. It is used to communicate
+ * changes between the plugin and devtools.
+ */
+export const genDataChangeTransaction = ({
+  playerID,
+  data,
+  pluginID,
+}: {
+  playerID: string;
+  data: Flow["data"];
+  pluginID: string;
+}): Transaction<DevtoolsDataChangeEvent> => {
+  return {
+    id: NOOP_ID,
+    type: "PLAYER_DEVTOOLS_PLUGIN_DATA_CHANGE",
+    payload: {
+      pluginID,
+      data,
+    },
+    sender: playerID,
+    context: "player",
+    target: "player",
+    timestamp: Date.now(),
+    _messenger_: true,
+  };
+};

package/src/helpers/index.ts

@@ -0,0 +1,2 @@
+export { generateUUID } from "./uuid";
+export { genDataChangeTransaction } from "./genDataChangeTransaction";

package/src/helpers/uuid.ts

@@ -0,0 +1,22 @@
+export function generateUUID(): string {
+  // Public Domain/MIT
+  let d = new Date().getTime(); //Timestamp
+  let d2 =
+    (typeof performance !== "undefined" &&
+      performance.now &&
+      performance.now() * 1000) ||
+    0; //Time in microseconds since page-load or 0 if unsupported
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
+    let r = Math.random() * 16; //random number between 0 and 16
+    if (d > 0) {
+      //Use timestamp until depleted
+      r = (d + r) % 16 | 0;
+      d = Math.floor(d / 16);
+    } else {
+      //Use microseconds since page-load if supported
+      r = (d2 + r) % 16 | 0;
+      d2 = Math.floor(d2 / 16);
+    }
+    return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  DevtoolsPlugin,
+  type DevtoolsPluginOptions,
+  type PluginStore,
+  type DevtoolsHandler,
+} from "./plugin";
+export * from "./helpers";
+export { PLUGIN_INACTIVE_WARNING } from "./constants";

package/src/plugin.ts

@@ -0,0 +1,176 @@
+import type { Messenger } from "@player-devtools/messenger";
+import {
+  PluginData,
+  DevtoolsPluginsStore,
+  PlayerInitEvent,
+  ExtensionSupportedEvents,
+  Transaction,
+  DevtoolsPluginInteractionEvent,
+} from "@player-devtools/types";
+import { dsetAssign } from "@player-devtools/utils";
+import type { DataModel, Player, PlayerPlugin } from "@player-ui/player";
+import { produce } from "immer";
+import { useStateReducer, type Store, type Unsubscribe } from "./state";
+import { reducer } from "./reducer";
+import { PLUGIN_INACTIVE_WARNING, INTERACTIONS } from "./constants";
+import { genDataChangeTransaction } from "./helpers";
+import { dequal } from "dequal";
+
+export interface DevtoolsHandler {
+  // TODO: Could return bool to signifiy handled to avoid double processing?
+  processInteraction(interaction: DevtoolsPluginInteractionEvent): void;
+  checkIfDevtoolsIsActive(): boolean;
+  log?(message: string): void;
+}
+
+export interface DevtoolsPluginOptions {
+  playerID: string;
+  pluginData: PluginData;
+  handler: DevtoolsHandler;
+}
+
+const INITIAL_STATE: DevtoolsPluginsStore = {
+  messages: [],
+  plugins: {},
+  interactions: [],
+  currentPlayer: "",
+};
+
+// TODO: Rename to DevtoolsPluginStore? Need to rename DevtoolsPluginsStore to DevtoolsPluginState
+export type PluginStore = Store<
+  DevtoolsPluginsStore,
+  Transaction<ExtensionSupportedEvents>
+>;
+
+/** Entrypoint for devtools plugins with platform-agnostic components */
+export class DevtoolsPlugin implements PlayerPlugin, DevtoolsHandler {
+  name: string = "DevtoolsPlugin";
+
+  private loggedWarning = false;
+
+  store: PluginStore = useStateReducer(reducer, INITIAL_STATE);
+  protected lastProcessedInteraction = 0;
+
+  get pluginID(): string {
+    return this.options.pluginData.id;
+  }
+
+  get playerID(): string {
+    return this.options.playerID;
+  }
+
+  constructor(protected options: DevtoolsPluginOptions) {
+    this.store.subscribe(({ interactions }) => {
+      if (this.lastProcessedInteraction < (interactions.length ?? 0)) {
+        interactions
+          .slice(this.lastProcessedInteraction)
+          .forEach(this.processInteraction.bind(this));
+      }
+    });
+  }
+
+  registerMessenger(
+    messenger: Messenger<ExtensionSupportedEvents>,
+  ): Unsubscribe {
+    // Propagate new messages from state to devtools via the messenger
+    let lastMessageIndex = -1;
+    return this.store.subscribe(({ messages }) => {
+      const start = lastMessageIndex + 1;
+      if (messages.length > start) {
+        const newlyAdded = messages.slice(start);
+        lastMessageIndex = messages.length - 1;
+        for (const msg of newlyAdded) {
+          messenger.sendMessage(msg);
+        }
+      }
+    });
+  }
+
+  protected dispatchPlayerInit(): void {
+    // Initial plugin content
+    const transaction: Transaction<PlayerInitEvent> = {
+      id: -1,
+      type: "PLAYER_DEVTOOLS_PLAYER_INIT",
+      payload: {
+        plugins: {
+          [this.pluginID]: this.options.pluginData,
+        },
+      },
+      sender: this.options.playerID,
+      context: "player",
+      target: "player",
+      timestamp: Date.now(),
+      _messenger_: true,
+    };
+
+    this.store.dispatch(transaction);
+  }
+
+  // By default, we'll only write to the keys defined in data -- if undefined, data will be cleared
+  protected dispatchDataUpdate(data?: DataModel): void {
+    const state = this.store.getState();
+
+    const { plugins } = produce(this.store.getState(), (draft) => {
+      if (!data)
+        dsetAssign(draft, ["plugins", this.pluginID, "flow", "data"], data);
+      else
+        Object.entries(data).forEach(([key, value]) => {
+          dsetAssign(
+            draft,
+            ["plugins", this.pluginID, "flow", "data", key],
+            value,
+          );
+        });
+    });
+
+    const newData = plugins[this.pluginID]!.flow.data;
+    if (dequal(state.plugins[this.pluginID]?.flow?.data, newData)) return;
+
+    const transaction = genDataChangeTransaction({
+      playerID: this.playerID,
+      pluginID: this.pluginID,
+      data: newData,
+    });
+
+    this.store.dispatch(transaction);
+  }
+
+  checkIfDevtoolsIsActive(): boolean {
+    const isActive = this.options.handler.checkIfDevtoolsIsActive();
+    if (!isActive && !this.loggedWarning) {
+      this.options.handler.log?.(PLUGIN_INACTIVE_WARNING);
+      this.loggedWarning = true;
+    }
+
+    return isActive;
+  }
+
+  processInteraction(interaction: DevtoolsPluginInteractionEvent): void {
+    this.options.handler.processInteraction(interaction);
+
+    const {
+      payload: { type, payload },
+    } = interaction;
+
+    if (type === INTERACTIONS.PLAYER_SELECTED && payload) {
+      this.store.dispatch({
+        id: -1,
+        type: "PLAYER_DEVTOOLS_SELECTED_PLAYER_CHANGE",
+        payload: { playerID: payload },
+        sender: this.playerID,
+        context: "player",
+        target: this.playerID,
+        timestamp: Date.now(),
+        _messenger_: true,
+      });
+    }
+
+    this.lastProcessedInteraction += 1;
+  }
+
+  apply(player: Player): void {
+    if (!this.checkIfDevtoolsIsActive()) return;
+
+    this.dispatchPlayerInit();
+  }
+}

package/src/reducer.ts

@@ -0,0 +1,80 @@
+import { produce } from "immer";
+import { dequal } from "dequal";
+import type {
+  DevtoolsDataChangeEvent,
+  DevtoolsPluginsStore,
+  ExtensionSupportedEvents,
+  PlayerInitEvent,
+  Transaction,
+} from "@player-devtools/types";
+import { dsetAssign } from "@player-devtools/utils";
+
+const containsInteraction = (
+  interactions: DevtoolsPluginsStore["interactions"],
+  interaction: DevtoolsPluginsStore["interactions"][number],
+) => {
+  return interactions.filter((i) => dequal(i, interaction)).length > 0;
+};
+
+/** devtools plugin state reducer */
+export const reducer = (
+  state: DevtoolsPluginsStore,
+  transaction: Transaction<ExtensionSupportedEvents>,
+): DevtoolsPluginsStore => {
+  switch (transaction.type) {
+    case "PLAYER_DEVTOOLS_PLAYER_INIT":
+      return produce(state, (draft) => {
+        const { payload } = transaction;
+        dsetAssign(draft, ["plugins"], payload.plugins);
+
+        const message: PlayerInitEvent = {
+          type: "PLAYER_DEVTOOLS_PLAYER_INIT",
+          payload,
+        };
+
+        draft.messages.push(message);
+      });
+    case "PLAYER_DEVTOOLS_PLUGIN_DATA_CHANGE":
+      return produce(state, (draft) => {
+        const { payload } = transaction;
+
+        if (!payload.data) return state;
+
+        try {
+          dsetAssign(
+            draft,
+            ["plugins", transaction.payload.pluginID, "flow", "data"],
+            transaction.payload.data,
+          );
+        } catch {
+          console.error("error setting data:", transaction.payload.data);
+        }
+        const message: DevtoolsDataChangeEvent = {
+          type: "PLAYER_DEVTOOLS_PLUGIN_DATA_CHANGE",
+          payload,
+        };
+
+        draft.messages.push(message);
+      });
+    case "PLAYER_DEVTOOLS_PLUGIN_INTERACTION":
+      return produce(state, (draft) => {
+        if (containsInteraction(draft.interactions, transaction)) return state;
+
+        dsetAssign(
+          draft,
+          ["interactions"],
+          [...draft.interactions, transaction],
+        );
+      });
+    case "PLAYER_DEVTOOLS_SELECTED_PLAYER_CHANGE": {
+      const { playerID } = transaction.payload;
+
+      if (!playerID) return state;
+      return produce(state, (draft) => {
+        dsetAssign(draft, ["currentPlayer"], playerID);
+      });
+    }
+    default:
+      return state;
+  }
+};

package/src/state.ts

@@ -0,0 +1,43 @@
+export type Reducer<T, A> = (state: T, action: A) => T;
+export type Dispatch<A> = (action: A) => void;
+export type Subscriber<T> = (state: T) => void;
+export type Subscribe<T> = (subscriber: Subscriber<T>) => Unsubscribe;
+export type Unsubscribe = () => void;
+
+export interface Store<State, Action> {
+  getState: () => State;
+  subscribe: Subscribe<State>;
+  dispatch: Dispatch<Action>;
+}
+
+export const useStateReducer = <State, Action>(
+  reducer: Reducer<State, Action>,
+  initialState: State,
+): Store<State, Action> => {
+  let state = initialState;
+  const subscribers = new Set<Subscriber<State>>();
+  return {
+    getState: () => state,
+
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    subscribe(subscriber: Subscriber<State>): Unsubscribe {
+      subscribers.add(subscriber);
+      subscriber(state);
+      return () => subscribers.delete(subscriber);
+    },
+
+    /** Dispatch an action through the reducer, then run side-effects. */
+    dispatch(action: Action): void {
+      const prevState = state;
+      const nextState = reducer(prevState, action);
+
+      // Only proceed if state actually changed by reference
+      if (nextState !== prevState) {
+        state = nextState;
+
+        // Notify subscribers
+        for (const sub of subscribers) sub(state);
+      }
+    },
+  };
+};

package/types/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const INTERACTIONS: {
+    PLAYER_SELECTED: string;
+};
+export declare const PLUGIN_INACTIVE_WARNING = "The plugin has been registered, but the Player development tools are not active. If you are working in a production environment, it is recommended to remove the plugin. To activate, enable through the browser extension popup for web or configure the FlipperClient for mobile.";
+//# sourceMappingURL=constants.d.ts.map

package/types/helpers/genDataChangeTransaction.d.ts

@@ -0,0 +1,16 @@
+import type { DevtoolsDataChangeEvent, Transaction } from "@player-devtools/types";
+import type { Flow } from "@player-ui/player";
+/**
+ * Generates a data change transaction for the player devtools plugin.
+ *
+ * This function creates a transaction object that represents a change in data
+ * within a player devtools plugin. The transaction includes details such as the
+ * plugin ID, the changed data, and the player ID. It is used to communicate
+ * changes between the plugin and devtools.
+ */
+export declare const genDataChangeTransaction: ({ playerID, data, pluginID, }: {
+    playerID: string;
+    data: Flow["data"];
+    pluginID: string;
+}) => Transaction<DevtoolsDataChangeEvent>;
+//# sourceMappingURL=genDataChangeTransaction.d.ts.map

package/types/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export { generateUUID } from "./uuid";
+export { genDataChangeTransaction } from "./genDataChangeTransaction";
+//# sourceMappingURL=index.d.ts.map

package/types/helpers/uuid.d.ts

@@ -0,0 +1,2 @@
+export declare function generateUUID(): string;
+//# sourceMappingURL=uuid.d.ts.map

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export { DevtoolsPlugin, type DevtoolsPluginOptions, type PluginStore, type DevtoolsHandler, } from "./plugin";
+export * from "./helpers";
+export { PLUGIN_INACTIVE_WARNING } from "./constants";
+//# sourceMappingURL=index.d.ts.map

package/types/plugin.d.ts

@@ -0,0 +1,33 @@
+import type { Messenger } from "@player-devtools/messenger";
+import { PluginData, DevtoolsPluginsStore, ExtensionSupportedEvents, Transaction, DevtoolsPluginInteractionEvent } from "@player-devtools/types";
+import type { DataModel, Player, PlayerPlugin } from "@player-ui/player";
+import { type Store, type Unsubscribe } from "./state";
+export interface DevtoolsHandler {
+    processInteraction(interaction: DevtoolsPluginInteractionEvent): void;
+    checkIfDevtoolsIsActive(): boolean;
+    log?(message: string): void;
+}
+export interface DevtoolsPluginOptions {
+    playerID: string;
+    pluginData: PluginData;
+    handler: DevtoolsHandler;
+}
+export type PluginStore = Store<DevtoolsPluginsStore, Transaction<ExtensionSupportedEvents>>;
+/** Entrypoint for devtools plugins with platform-agnostic components */
+export declare class DevtoolsPlugin implements PlayerPlugin, DevtoolsHandler {
+    protected options: DevtoolsPluginOptions;
+    name: string;
+    private loggedWarning;
+    store: PluginStore;
+    protected lastProcessedInteraction: number;
+    get pluginID(): string;
+    get playerID(): string;
+    constructor(options: DevtoolsPluginOptions);
+    registerMessenger(messenger: Messenger<ExtensionSupportedEvents>): Unsubscribe;
+    protected dispatchPlayerInit(): void;
+    protected dispatchDataUpdate(data?: DataModel): void;
+    checkIfDevtoolsIsActive(): boolean;
+    processInteraction(interaction: DevtoolsPluginInteractionEvent): void;
+    apply(player: Player): void;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/types/reducer.d.ts

@@ -0,0 +1,4 @@
+import type { DevtoolsPluginsStore, ExtensionSupportedEvents, Transaction } from "@player-devtools/types";
+/** devtools plugin state reducer */
+export declare const reducer: (state: DevtoolsPluginsStore, transaction: Transaction<ExtensionSupportedEvents>) => DevtoolsPluginsStore;
+//# sourceMappingURL=reducer.d.ts.map

package/types/state.d.ts

@@ -0,0 +1,12 @@
+export type Reducer<T, A> = (state: T, action: A) => T;
+export type Dispatch<A> = (action: A) => void;
+export type Subscriber<T> = (state: T) => void;
+export type Subscribe<T> = (subscriber: Subscriber<T>) => Unsubscribe;
+export type Unsubscribe = () => void;
+export interface Store<State, Action> {
+    getState: () => State;
+    subscribe: Subscribe<State>;
+    dispatch: Dispatch<Action>;
+}
+export declare const useStateReducer: <State, Action>(reducer: Reducer<State, Action>, initialState: State) => Store<State, Action>;
+//# sourceMappingURL=state.d.ts.map