@voidhash/mimic-react 0.0.1-alpha.10

package/dist/zustand-commander/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["DEFAULT_OPTIONS: Required<CommanderOptions>","_storeApi: StoreApi<TStore & CommanderSlice> | null","ctx: CommandContext<TStore & CommanderSlice>","entry: UndoEntry<TParams, TReturn>","ctx: CommandContext<TStore>","newEntry: UndoEntry","dispatch: CommandDispatch<TStore>","ctx: CommandContext<TStore>"],"sources":["../../src/zustand-commander/types.ts","../../src/zustand-commander/commander.ts","../../src/zustand-commander/hooks.ts"],"sourcesContent":["/**\n * @voidhash/mimic-react/zustand-commander\n *\n * Type definitions for the zustand-commander package.\n *\n * @since 0.0.1\n */\n\nimport type { Schema } from \"effect\";\nimport type { StoreApi, UseBoundStore } from \"zustand\";\n\n// =============================================================================\n// Schema Types\n// =============================================================================\n\n/**\n * Any Effect Schema type (used for type constraints).\n */\nexport type AnyEffectSchema = Schema.Schema<any, any, any>;\n\n/**\n * Infer the Type from an Effect Schema.\n */\nexport type InferSchemaType<T> = T extends Schema.Schema<infer A, any, any>\n  ? A\n  : never;\n\n// =============================================================================\n// Command Symbol & Type Guard\n// =============================================================================\n\n/**\n * Symbol used to identify Command objects at runtime.\n */\nexport const COMMAND_SYMBOL = Symbol.for(\"zustand-commander/command\");\n\n/**\n * Symbol used to identify UndoableCommand objects at runtime.\n */\nexport const UNDOABLE_COMMAND_SYMBOL = Symbol.for(\n  \"zustand-commander/undoable-command\"\n);\n\n// =============================================================================\n// Command Context\n// =============================================================================\n\n/**\n * Context provided to command functions.\n * Gives access to store state and dispatch capabilities.\n */\nexport interface CommandContext<TStore> {\n  /**\n   * Get the current store state.\n   */\n  readonly getState: () => TStore;\n\n  /**\n   * Set partial store state (for local/browser state updates).\n   */\n  readonly setState: (partial: Partial<TStore>) => void;\n\n  /**\n   * Dispatch another command.\n   * Returns the result of the dispatched command.\n   *\n   * @example\n   * dispatch(otherCommand)({ param: \"value\" });\n   */\n  readonly dispatch: CommandDispatch<TStore>;\n}\n\n// =============================================================================\n// Command Function Types\n// =============================================================================\n\n/**\n * The function signature for a command handler.\n */\nexport type CommandFn<TStore, TParams, TReturn> = (\n  ctx: CommandContext<TStore>,\n  params: TParams\n) => TReturn;\n\n/**\n * The function signature for an undoable command's revert handler.\n * Receives the original params and the result from the forward execution.\n */\nexport type RevertFn<TStore, TParams, TReturn> = (\n  ctx: CommandContext<TStore>,\n  params: TParams,\n  result: TReturn\n) => void;\n\n// =============================================================================\n// Command Types\n// =============================================================================\n\n/**\n * A command that can be dispatched to modify store state.\n * Regular commands do not support undo/redo.\n */\nexport interface Command<TStore, TParams, TReturn> {\n  readonly [COMMAND_SYMBOL]: true;\n  readonly fn: CommandFn<TStore, TParams, TReturn>;\n  readonly paramsSchema: AnyEffectSchema | null;\n}\n\n/**\n * An undoable command that supports undo/redo.\n * Must provide a revert function that knows how to undo the change.\n */\nexport interface UndoableCommand<TStore, TParams, TReturn>\n  extends Command<TStore, TParams, TReturn> {\n  readonly [UNDOABLE_COMMAND_SYMBOL]: true;\n  readonly revert: RevertFn<TStore, TParams, TReturn>;\n}\n\n/**\n * Any command type (regular or undoable).\n */\nexport type AnyCommand = Command<any, any, any>;\n\n/**\n * Any undoable command type.\n */\nexport type AnyUndoableCommand = UndoableCommand<any, any, any>;\n\n// =============================================================================\n// Command Dispatch\n// =============================================================================\n\n/**\n * Dispatch function that accepts commands and returns a function to call with params.\n * Returns the result of the command execution.\n *\n * @example\n * const result = dispatch(myCommand)({ param: \"value\" });\n */\nexport type CommandDispatch<TStore> = <TParams, TReturn>(\n  command: Command<TStore, TParams, TReturn>\n) => (params: TParams) => TReturn;\n\n// =============================================================================\n// Undo/Redo Stack Types\n// =============================================================================\n\n/**\n * An entry in the undo/redo stack.\n * Contains all information needed to revert or redo a command.\n */\nexport interface UndoEntry<TParams = unknown, TReturn = unknown> {\n  /** The undoable command that was executed */\n  readonly command: AnyUndoableCommand;\n  /** The parameters that were passed to the command */\n  readonly params: TParams;\n  /** The result returned by the command (passed to revert) */\n  readonly result: TReturn;\n  /** Timestamp when the command was executed */\n  readonly timestamp: number;\n}\n\n/**\n * State slice for undo/redo functionality.\n */\nexport interface CommanderSlice {\n  readonly _commander: {\n    /** Stack of commands that can be undone */\n    readonly undoStack: ReadonlyArray<UndoEntry>;\n    /** Stack of commands that can be redone */\n    readonly redoStack: ReadonlyArray<UndoEntry>;\n  };\n}\n\n// =============================================================================\n// Commander Types\n// =============================================================================\n\n/**\n * Options for creating a commander.\n */\nexport interface CommanderOptions {\n  /**\n   * Maximum number of undo entries to keep.\n   * @default 100\n   */\n  readonly maxUndoStackSize?: number;\n}\n\n/**\n * A commander instance bound to a specific store type.\n * Used to create commands and the middleware.\n */\nexport interface Commander<TStore> {\n  /**\n   * Create a regular command (no undo support).\n   *\n   * @example\n   * // With params schema\n   * const addItem = commander.action(\n   *   Schema.Struct({ name: Schema.String }),\n   *   (ctx, params) => {\n   *     // modify state\n   *   }\n   * );\n   *\n   * // Without params\n   * const clearAll = commander.action((ctx) => {\n   *   // modify state\n   * });\n   */\n  readonly action: {\n    // With params schema\n    <TParamsSchema extends AnyEffectSchema, TReturn = void>(\n      paramsSchema: TParamsSchema,\n      fn: CommandFn<TStore, InferSchemaType<TParamsSchema>, TReturn>\n    ): Command<TStore, InferSchemaType<TParamsSchema>, TReturn>;\n\n    // Without params (void)\n    <TReturn = void>(\n      fn: CommandFn<TStore, void, TReturn>\n    ): Command<TStore, void, TReturn>;\n  };\n\n  /**\n   * Create an undoable command with undo/redo support.\n   * The revert function is called when undoing the command.\n   *\n   * @example\n   * const moveItem = commander.undoableAction(\n   *   Schema.Struct({ id: Schema.String, toIndex: Schema.Number }),\n   *   (ctx, params) => {\n   *     const fromIndex = // get current index\n   *     // perform move\n   *     return { fromIndex }; // return data needed for revert\n   *   },\n   *   (ctx, params, result) => {\n   *     // revert: move back to original position\n   *     ctx.dispatch(moveItem)({ id: params.id, toIndex: result.fromIndex });\n   *   }\n   * );\n   */\n  readonly undoableAction: {\n    // With params schema\n    <TParamsSchema extends AnyEffectSchema, TReturn>(\n      paramsSchema: TParamsSchema,\n      fn: CommandFn<TStore, InferSchemaType<TParamsSchema>, TReturn>,\n      revert: RevertFn<TStore, InferSchemaType<TParamsSchema>, TReturn>\n    ): UndoableCommand<TStore, InferSchemaType<TParamsSchema>, TReturn>;\n\n    // Without params (void)\n    <TReturn>(\n      fn: CommandFn<TStore, void, TReturn>,\n      revert: RevertFn<TStore, void, TReturn>\n    ): UndoableCommand<TStore, void, TReturn>;\n  };\n\n  /**\n   * Zustand middleware that adds commander functionality.\n   * Adds undo/redo stacks to the store state.\n   */\n  readonly middleware: CommanderMiddleware<TStore>;\n}\n\n/**\n * Type for the commander middleware.\n * Note: TStore is intentionally unused here to match the Commander interface signature.\n * The middleware is generic over T (the inner store type) and adds CommanderSlice.\n */\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nexport type CommanderMiddleware<_TStore> = <T extends object>(\n  config: (\n    set: StoreApi<T & CommanderSlice>[\"setState\"],\n    get: StoreApi<T & CommanderSlice>[\"getState\"],\n    api: StoreApi<T & CommanderSlice>\n  ) => T\n) => (\n  set: StoreApi<T & CommanderSlice>[\"setState\"],\n  get: StoreApi<T & CommanderSlice>[\"getState\"],\n  api: StoreApi<T & CommanderSlice>\n) => T & CommanderSlice;\n\n// =============================================================================\n// Type Helpers\n// =============================================================================\n\n/**\n * Extract the params type from a command.\n */\nexport type CommandParams<T> = T extends Command<any, infer P, any> ? P : never;\n\n/**\n * Extract the return type from a command.\n */\nexport type CommandReturn<T> = T extends Command<any, any, infer R>\n  ? R\n  : undefined;\n\n/**\n * Extract the store type from a command.\n */\nexport type CommandStore<T> = T extends Command<infer S, any, any> ? S : never;\n\n// =============================================================================\n// Type Guards\n// =============================================================================\n\n/**\n * Type guard to check if a value is a Command.\n */\nexport function isCommand(value: unknown): value is AnyCommand {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    COMMAND_SYMBOL in value &&\n    value[COMMAND_SYMBOL] === true\n  );\n}\n\n/**\n * Type guard to check if a command is undoable.\n */\nexport function isUndoableCommand(\n  value: unknown\n): value is AnyUndoableCommand {\n  return (\n    isCommand(value) &&\n    UNDOABLE_COMMAND_SYMBOL in value &&\n    value[UNDOABLE_COMMAND_SYMBOL] === true\n  );\n}\n\n// =============================================================================\n// Store Type Helper\n// =============================================================================\n\n/**\n * Helper type to extract the state type from a zustand store.\n */\nexport type ExtractState<TStore> = TStore extends UseBoundStore<\n  StoreApi<infer S>\n>\n  ? S\n  : TStore extends StoreApi<infer S>\n    ? S\n    : never;\n\n","/**\n * @voidhash/mimic-react/zustand-commander\n *\n * Commander creation and command definition.\n *\n * @since 0.0.1\n */\n\nimport type { StoreApi } from \"zustand\";\nimport {\n  COMMAND_SYMBOL,\n  UNDOABLE_COMMAND_SYMBOL,\n  isUndoableCommand,\n  type AnyEffectSchema,\n  type Command,\n  type Commander,\n  type CommanderOptions,\n  type CommanderSlice,\n  type CommandContext,\n  type CommandDispatch,\n  type CommandFn,\n  type InferSchemaType,\n  type RevertFn,\n  type UndoableCommand,\n  type UndoEntry,\n} from \"./types.js\";\n\n// =============================================================================\n// Default Options\n// =============================================================================\n\nconst DEFAULT_OPTIONS: Required<CommanderOptions> = {\n  maxUndoStackSize: 100,\n};\n\n// =============================================================================\n// Commander Implementation\n// =============================================================================\n\n/**\n * Creates a commander instance bound to a specific store type.\n *\n * @example\n * ```ts\n * // Create commander for your store type\n * const commander = createCommander<StoreState>();\n *\n * // Define commands\n * const addItem = commander.action(\n *   Schema.Struct({ name: Schema.String }),\n *   (ctx, params) => {\n *     const { mimic } = ctx.getState();\n *     mimic.document.transaction(root => {\n *       // add item\n *     });\n *   }\n * );\n *\n * // Create store with middleware\n * const useStore = create(\n *   commander.middleware(\n *     mimic(document, (set, get) => ({\n *       // your state\n *     }))\n *   )\n * );\n * ```\n */\nexport function createCommander<TStore extends object>(\n  options: CommanderOptions = {}\n): Commander<TStore & CommanderSlice> {\n  const { maxUndoStackSize } = { ...DEFAULT_OPTIONS, ...options };\n\n  // Track the store API once middleware is applied\n  let _storeApi: StoreApi<TStore & CommanderSlice> | null = null;\n\n  /**\n   * Creates the dispatch function for use within command handlers.\n   */\n  const createDispatch = (): CommandDispatch<TStore & CommanderSlice> => {\n    return <TParams, TReturn>(\n      command: Command<TStore & CommanderSlice, TParams, TReturn>\n    ) => {\n      return (params: TParams): TReturn => {\n        if (!_storeApi) {\n          throw new Error(\n            \"Commander: Store not initialized. Make sure to use the commander middleware.\"\n          );\n        }\n\n        // Create context for the command\n        const ctx: CommandContext<TStore & CommanderSlice> = {\n          getState: () => _storeApi!.getState(),\n          setState: (partial) => _storeApi!.setState(partial as any),\n          dispatch: createDispatch(),\n        };\n\n        // Execute the command\n        const result = command.fn(ctx, params);\n\n        // If it's an undoable command, add to undo stack\n        if (isUndoableCommand(command)) {\n          const entry: UndoEntry<TParams, TReturn> = {\n            command,\n            params,\n            result,\n            timestamp: Date.now(),\n          };\n\n          _storeApi.setState((state: TStore & CommanderSlice) => {\n            const { undoStack, redoStack } = state._commander;\n\n            // Add to undo stack, respecting max size\n            const newUndoStack = [...undoStack, entry].slice(-maxUndoStackSize);\n\n            // Clear redo stack when a new command is executed\n            return {\n              ...state,\n              _commander: {\n                undoStack: newUndoStack,\n                redoStack: [],\n              },\n            };\n          });\n        }\n\n        return result;\n      };\n    };\n  };\n\n  /**\n   * Create a regular command (no undo support).\n   */\n  function action<TParamsSchema extends AnyEffectSchema, TReturn = void>(\n    paramsSchema: TParamsSchema,\n    fn: CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>\n  ): Command<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>;\n  function action<TReturn = void>(\n    fn: CommandFn<TStore & CommanderSlice, void, TReturn>\n  ): Command<TStore & CommanderSlice, void, TReturn>;\n  function action<TParamsSchema extends AnyEffectSchema, TReturn = void>(\n    paramsSchemaOrFn:\n      | TParamsSchema\n      | CommandFn<TStore & CommanderSlice, void, TReturn>,\n    maybeFn?: CommandFn<\n      TStore & CommanderSlice,\n      InferSchemaType<TParamsSchema>,\n      TReturn\n    >\n  ): Command<TStore & CommanderSlice, any, TReturn> {\n    // Check if we have two arguments (schema + fn) or just one (fn only)\n    if (maybeFn !== undefined) {\n      // First arg is schema, second is fn\n      return {\n        [COMMAND_SYMBOL]: true,\n        fn: maybeFn,\n        paramsSchema: paramsSchemaOrFn as TParamsSchema,\n      };\n    }\n\n    // Single argument - must be the action function (no params schema)\n    if (typeof paramsSchemaOrFn !== \"function\") {\n      throw new Error(\"Commander: action requires a function\");\n    }\n\n    return {\n      [COMMAND_SYMBOL]: true,\n      fn: paramsSchemaOrFn as CommandFn<TStore & CommanderSlice, void, TReturn>,\n      paramsSchema: null,\n    };\n  }\n\n  /**\n   * Create an undoable command with undo/redo support.\n   */\n  function undoableAction<TParamsSchema extends AnyEffectSchema, TReturn>(\n    paramsSchema: TParamsSchema,\n    fn: CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>,\n    revert: RevertFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>\n  ): UndoableCommand<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>;\n  function undoableAction<TReturn>(\n    fn: CommandFn<TStore & CommanderSlice, void, TReturn>,\n    revert: RevertFn<TStore & CommanderSlice, void, TReturn>\n  ): UndoableCommand<TStore & CommanderSlice, void, TReturn>;\n  function undoableAction<TParamsSchema extends AnyEffectSchema, TReturn>(\n    paramsSchemaOrFn:\n      | TParamsSchema\n      | CommandFn<TStore & CommanderSlice, void, TReturn>,\n    fnOrRevert:\n      | CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>\n      | RevertFn<TStore & CommanderSlice, void, TReturn>,\n    maybeRevert?: RevertFn<\n      TStore & CommanderSlice,\n      InferSchemaType<TParamsSchema>,\n      TReturn\n    >\n  ): UndoableCommand<TStore & CommanderSlice, any, TReturn> {\n    // Check if we have three arguments (schema + fn + revert) or two (fn + revert)\n    if (maybeRevert !== undefined) {\n      // First arg is schema, second is fn, third is revert\n      return {\n        [COMMAND_SYMBOL]: true,\n        [UNDOABLE_COMMAND_SYMBOL]: true,\n        fn: fnOrRevert as CommandFn<\n          TStore & CommanderSlice,\n          InferSchemaType<TParamsSchema>,\n          TReturn\n        >,\n        paramsSchema: paramsSchemaOrFn as TParamsSchema,\n        revert: maybeRevert,\n      };\n    }\n\n    // Two arguments - fn + revert (no params schema)\n    if (typeof paramsSchemaOrFn !== \"function\") {\n      throw new Error(\"Commander: undoableAction requires a function\");\n    }\n\n    return {\n      [COMMAND_SYMBOL]: true,\n      [UNDOABLE_COMMAND_SYMBOL]: true,\n      fn: paramsSchemaOrFn as CommandFn<TStore & CommanderSlice, void, TReturn>,\n      paramsSchema: null,\n      revert: fnOrRevert as RevertFn<TStore & CommanderSlice, void, TReturn>,\n    };\n  }\n\n  /**\n   * Zustand middleware that adds commander functionality.\n   */\n  const middleware = <T extends object>(\n    config: (\n      set: StoreApi<T & CommanderSlice>[\"setState\"],\n      get: StoreApi<T & CommanderSlice>[\"getState\"],\n      api: StoreApi<T & CommanderSlice>\n    ) => T\n  ) => {\n    return (\n      set: StoreApi<T & CommanderSlice>[\"setState\"],\n      get: StoreApi<T & CommanderSlice>[\"getState\"],\n      api: StoreApi<T & CommanderSlice>\n    ): T & CommanderSlice => {\n      // Store the API reference for dispatch\n      _storeApi = api as unknown as StoreApi<TStore & CommanderSlice>;\n\n      // Get user's state\n      const userState = config(set, get, api);\n\n      // Add commander slice\n      return {\n        ...userState,\n        _commander: {\n          undoStack: [],\n          redoStack: [],\n        },\n      };\n    };\n  };\n\n  return {\n    action,\n    undoableAction,\n    middleware: middleware as Commander<TStore & CommanderSlice>[\"middleware\"],\n  };\n}\n\n// =============================================================================\n// Undo/Redo Functions\n// =============================================================================\n\n/**\n * Perform an undo operation on the store.\n * Returns true if an undo was performed, false if undo stack was empty.\n */\nexport function performUndo<TStore extends CommanderSlice>(\n  storeApi: StoreApi<TStore>\n): boolean {\n  const state = storeApi.getState();\n  const { undoStack, redoStack } = state._commander;\n\n  // Pop the last entry from undo stack\n  const entry = undoStack[undoStack.length - 1];\n  if (!entry) {\n    return false;\n  }\n\n  const newUndoStack = undoStack.slice(0, -1);\n\n  // Create context for the revert function\n  const ctx: CommandContext<TStore> = {\n    getState: () => storeApi.getState(),\n    setState: (partial) => storeApi.setState(partial as any),\n    dispatch: createDispatchForUndo(storeApi),\n  };\n\n  // Execute the revert function\n  entry.command.revert(ctx, entry.params, entry.result);\n\n  // Move entry to redo stack\n  storeApi.setState((state: TStore) => ({\n    ...state,\n    _commander: {\n      undoStack: newUndoStack,\n      redoStack: [...redoStack, entry],\n    },\n  }));\n\n  return true;\n}\n\n/**\n * Perform a redo operation on the store.\n * Returns true if a redo was performed, false if redo stack was empty.\n */\nexport function performRedo<TStore extends CommanderSlice>(\n  storeApi: StoreApi<TStore>\n): boolean {\n  const state = storeApi.getState();\n  const { undoStack, redoStack } = state._commander;\n\n  // Pop the last entry from redo stack\n  const entry = redoStack[redoStack.length - 1];\n  if (!entry) {\n    return false;\n  }\n\n  const newRedoStack = redoStack.slice(0, -1);\n\n  // Create context for re-executing the command\n  const ctx: CommandContext<TStore> = {\n    getState: () => storeApi.getState(),\n    setState: (partial) => storeApi.setState(partial as any),\n    dispatch: createDispatchForUndo(storeApi),\n  };\n\n  // Re-execute the command\n  const result = entry.command.fn(ctx, entry.params);\n\n  // Create new entry with potentially new result\n  const newEntry: UndoEntry = {\n    command: entry.command,\n    params: entry.params,\n    result,\n    timestamp: Date.now(),\n  };\n\n  // Move entry back to undo stack\n  storeApi.setState((state: TStore) => ({\n    ...state,\n    _commander: {\n      undoStack: [...undoStack, newEntry],\n      redoStack: newRedoStack,\n    },\n  }));\n\n  return true;\n}\n\n/**\n * Creates a dispatch function for use during undo/redo operations.\n * This dispatch does NOT add to undo stack (to avoid infinite loops).\n */\nfunction createDispatchForUndo<TStore>(\n  storeApi: StoreApi<TStore>\n): CommandDispatch<TStore> {\n  return <TParams, TReturn>(command: Command<TStore, TParams, TReturn>) => {\n    return (params: TParams): TReturn => {\n      const ctx: CommandContext<TStore> = {\n        getState: () => storeApi.getState(),\n        setState: (partial) => storeApi.setState(partial as any),\n        dispatch: createDispatchForUndo(storeApi),\n      };\n\n      // Execute without adding to undo stack\n      return command.fn(ctx, params);\n    };\n  };\n}\n\n/**\n * Clear the undo and redo stacks.\n */\nexport function clearUndoHistory<TStore extends CommanderSlice>(\n  storeApi: StoreApi<TStore>\n): void {\n  storeApi.setState((state: TStore) => ({\n    ...state,\n    _commander: {\n      undoStack: [],\n      redoStack: [],\n    },\n  }));\n}\n\n","/**\n * @voidhash/mimic-react/zustand-commander\n *\n * React hooks for zustand-commander.\n *\n * @since 0.0.1\n */\n\nimport { useCallback, useEffect, useMemo } from \"react\";\nimport { useStore, type StoreApi, type UseBoundStore } from \"zustand\";\nimport { performRedo, performUndo, clearUndoHistory } from \"./commander\";\nimport {\n  isUndoableCommand,\n  type Command,\n  type CommandContext,\n  type CommandDispatch,\n  type CommanderSlice,\n  type ExtractState,\n} from \"./types.js\";\n\n// =============================================================================\n// useCommander Hook\n// =============================================================================\n\n/**\n * Creates a dispatch function for commands.\n * This is for use outside of React components (e.g., in command handlers).\n */\nfunction createDispatchFromApi<TStore extends CommanderSlice>(\n  storeApi: StoreApi<TStore>,\n  maxUndoStackSize = 100\n): CommandDispatch<TStore> {\n  const dispatch: CommandDispatch<TStore> = <TParams, TReturn>(\n    command: Command<TStore, TParams, TReturn>\n  ) => {\n    return (params: TParams): TReturn => {\n      // Create context for the command\n      const ctx: CommandContext<TStore> = {\n        getState: () => storeApi.getState(),\n        setState: (partial) => storeApi.setState(partial as Partial<TStore>),\n        dispatch,\n      };\n\n      // Execute the command\n      const result = command.fn(ctx, params);\n\n      // If it's an undoable command, add to undo stack\n      if (isUndoableCommand(command)) {\n        storeApi.setState((state: TStore) => {\n          const { undoStack } = state._commander;\n\n          // Add to undo stack, respecting max size\n          const newUndoStack = [\n            ...undoStack,\n            {\n              command,\n              params,\n              result,\n              timestamp: Date.now(),\n            },\n          ].slice(-maxUndoStackSize);\n\n          // Clear redo stack when a new command is executed\n          return {\n            ...state,\n            _commander: {\n              undoStack: newUndoStack,\n              redoStack: [],\n            },\n          } as TStore;\n        });\n      }\n\n      return result;\n    };\n  };\n\n  return dispatch;\n}\n\n/**\n * React hook to get a dispatch function for commands.\n * The dispatch function executes commands and manages undo/redo state.\n *\n * @example\n * ```tsx\n * const dispatch = useCommander(useStore);\n *\n * const handleClick = () => {\n *   dispatch(addCard)({ columnId: \"col-1\", title: \"New Card\" });\n * };\n * ```\n */\nexport function useCommander<TStore extends CommanderSlice>(\n  store: UseBoundStore<StoreApi<TStore>>\n): CommandDispatch<TStore> {\n  // Get the store API\n  const storeApi = useMemo(() => {\n    // UseBoundStore has the StoreApi attached\n    return store as unknown as StoreApi<TStore>;\n  }, [store]);\n\n  // Create a stable dispatch function\n  const dispatch = useMemo(\n    () => createDispatchFromApi<TStore>(storeApi),\n    [storeApi]\n  );\n\n  return dispatch as CommandDispatch<TStore>;\n}\n\n// =============================================================================\n// useUndoRedo Hook\n// =============================================================================\n\n/**\n * State and actions for undo/redo functionality.\n */\nexport interface UndoRedoState {\n  /** Whether there are actions that can be undone */\n  readonly canUndo: boolean;\n  /** Whether there are actions that can be redone */\n  readonly canRedo: boolean;\n  /** Number of items in the undo stack */\n  readonly undoCount: number;\n  /** Number of items in the redo stack */\n  readonly redoCount: number;\n  /** Undo the last action */\n  readonly undo: () => boolean;\n  /** Redo the last undone action */\n  readonly redo: () => boolean;\n  /** Clear the undo/redo history */\n  readonly clear: () => void;\n}\n\n/**\n * React hook for undo/redo functionality.\n * Provides state (canUndo, canRedo) and actions (undo, redo, clear).\n *\n * @example\n * ```tsx\n * const { canUndo, canRedo, undo, redo } = useUndoRedo(useStore);\n *\n * return (\n *   <>\n *     <button onClick={undo} disabled={!canUndo}>Undo</button>\n *     <button onClick={redo} disabled={!canRedo}>Redo</button>\n *   </>\n * );\n * ```\n */\nexport function useUndoRedo<TStore extends CommanderSlice>(\n  store: UseBoundStore<StoreApi<TStore>>\n): UndoRedoState {\n  // Get the store API\n  const storeApi = useMemo(() => {\n    return store as unknown as StoreApi<TStore>;\n  }, [store]);\n\n  // Subscribe to commander state\n  const commanderState = useStore(\n    store,\n    (state: TStore) => state._commander\n  );\n\n  const canUndo = commanderState.undoStack.length > 0;\n  const canRedo = commanderState.redoStack.length > 0;\n  const undoCount = commanderState.undoStack.length;\n  const redoCount = commanderState.redoStack.length;\n\n  const undo = useCallback(() => {\n    return performUndo(storeApi);\n  }, [storeApi]);\n\n  const redo = useCallback(() => {\n    return performRedo(storeApi);\n  }, [storeApi]);\n\n  const clear = useCallback(() => {\n    clearUndoHistory(storeApi);\n  }, [storeApi]);\n\n  return {\n    canUndo,\n    canRedo,\n    undoCount,\n    redoCount,\n    undo,\n    redo,\n    clear,\n  };\n}\n\n// =============================================================================\n// Keyboard Shortcut Hook\n// =============================================================================\n\n/**\n * Options for the keyboard shortcut hook.\n */\nexport interface UseUndoRedoKeyboardOptions {\n  /** Enable Ctrl/Cmd+Z for undo (default: true) */\n  readonly enableUndo?: boolean;\n  /** Enable Ctrl/Cmd+Shift+Z or Ctrl+Y for redo (default: true) */\n  readonly enableRedo?: boolean;\n}\n\n/**\n * React hook that adds keyboard shortcuts for undo/redo.\n * Listens for Ctrl/Cmd+Z (undo) and Ctrl/Cmd+Shift+Z or Ctrl+Y (redo).\n *\n * @example\n * ```tsx\n * // In your app component\n * useUndoRedoKeyboard(useStore);\n * ```\n */\nexport function useUndoRedoKeyboard<TStore extends CommanderSlice>(\n  store: UseBoundStore<StoreApi<TStore>>,\n  options: UseUndoRedoKeyboardOptions = {}\n): void {\n  const { enableUndo = true, enableRedo = true } = options;\n\n  const storeApi = useMemo(() => {\n    return store as unknown as StoreApi<TStore>;\n  }, [store]);\n\n  // Set up keyboard listener\n  useEffect(() => {\n    if (typeof window === \"undefined\") {\n      return;\n    }\n\n    const handleKeyDown = (event: KeyboardEvent) => {\n      const isMac = navigator.platform.toUpperCase().indexOf(\"MAC\") >= 0;\n      const modKey = isMac ? event.metaKey : event.ctrlKey;\n\n      if (!modKey) return;\n\n      // Undo: Ctrl/Cmd + Z (without Shift)\n      if (enableUndo && event.key === \"z\" && !event.shiftKey) {\n        event.preventDefault();\n        performUndo(storeApi);\n        return;\n      }\n\n      // Redo: Ctrl/Cmd + Shift + Z or Ctrl + Y\n      if (enableRedo) {\n        if ((event.key === \"z\" && event.shiftKey) || event.key === \"y\") {\n          event.preventDefault();\n          performRedo(storeApi);\n        }\n      }\n    };\n\n    window.addEventListener(\"keydown\", handleKeyDown);\n    return () => window.removeEventListener(\"keydown\", handleKeyDown);\n  }, [storeApi, enableUndo, enableRedo]);\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@voidhash/mimic-react",
+  "version": "0.0.1-alpha.10",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voidhashcom/mimic",
+    "directory": "packages/mimic-react"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts",
+      "require": "./dist/index.cjs"
+    },
+    "./zustand": {
+      "import": "./dist/zustand/index.mjs",
+      "types": "./dist/zustand/index.d.mts",
+      "require": "./dist/zustand/index.cjs"
+    },
+    "./zustand-commander": {
+      "import": "./dist/zustand-commander/index.mjs",
+      "types": "./dist/zustand-commander/index.d.mts",
+      "require": "./dist/zustand-commander/index.cjs"
+    }
+  },
+  "dependencies": {
+    "zustand": "^5.0.9"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.26.0",
+    "@types/react": "^19.0.0",
+    "effect": "^3.16.0",
+    "react": "^19.0.0",
+    "tsdown": "^0.18.2",
+    "typescript": "5.8.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4",
+    "@voidhash/tsconfig": "0.0.1-alpha.10"
+  },
+  "peerDependencies": {
+    "effect": "^3.16.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "@voidhash/mimic": "0.0.1-alpha.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run -c vitest.mts"
+  }
+}

package/src/zustand/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @voidhash/mimic-react/zustand
+ *
+ * Zustand middleware for integrating mimic ClientDocument with reactive state.
+ *
+ * @since 0.0.1
+ */
+
+// =============================================================================
+// Middleware
+// =============================================================================
+
+export { mimic } from "./middleware.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  MimicObject,
+  MimicSlice,
+  MimicMiddlewareOptions,
+  MimicStateCreator,
+} from "./types.js";

package/src/zustand/middleware.ts

@@ -0,0 +1,171 @@
+import type { StateCreator, StoreMutatorIdentifier } from "zustand";
+import type { ClientDocument } from "@voidhash/mimic/client";
+import type { Primitive, Presence } from "@voidhash/mimic";
+import type {
+  MimicSlice,
+  MimicObject,
+  MimicMiddlewareOptions,
+} from "./types.js";
+
+// =============================================================================
+// Middleware Implementation
+// =============================================================================
+
+type MimicMiddleware = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined,
+  T extends object = object,
+  Mps extends [StoreMutatorIdentifier, unknown][] = [],
+  Mcs extends [StoreMutatorIdentifier, unknown][] = [],
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>,
+  config: StateCreator<T & MimicSlice<TSchema, TPresence>, Mps, Mcs, T>,
+  options?: MimicMiddlewareOptions
+) => StateCreator<T & MimicSlice<TSchema, TPresence>, Mps, Mcs, T & MimicSlice<TSchema, TPresence>>;
+
+type MimicMiddlewareImpl = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined,
+  T extends object = object,
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>,
+  config: StateCreator<T & MimicSlice<TSchema, TPresence>, [], [], T>,
+  options?: MimicMiddlewareOptions
+) => StateCreator<T & MimicSlice<TSchema, TPresence>, [], [], T & MimicSlice<TSchema, TPresence>>;
+
+/**
+ * Creates a MimicObject from the current document state.
+ */
+const createMimicObject = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>
+): MimicObject<TSchema, TPresence> => {
+  const presence = document.presence
+    ? {
+        selfId: document.presence.selfId(),
+        self: document.presence.self(),
+        // Important: clone Maps to ensure zustand selectors re-render
+        // when presence changes (the underlying ClientDocument mutates Maps in-place).
+        others: new Map(document.presence.others()),
+        all: new Map(document.presence.all()),
+      }
+    : undefined;
+
+  return {
+    document,
+    snapshot: document.root.toSnapshot() as Primitive.InferSnapshot<TSchema>,
+    presence: presence as MimicObject<TSchema, TPresence>["presence"],
+    isConnected: document.isConnected(),
+    isReady: document.isReady(),
+    pendingCount: document.getPendingCount(),
+    hasPendingChanges: document.hasPendingChanges(),
+  };
+};
+
+/**
+ * Implementation of the mimic middleware.
+ */
+const mimicImpl: MimicMiddlewareImpl = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined,
+  _T extends object = object
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>,
+  config: any,
+  options: MimicMiddlewareOptions = {}
+) => {
+  const { autoSubscribe = true, autoConnect = true } = options;
+
+  return (set: any, get: any, api: any) => {
+    // Create initial mimic slice
+    const initialMimic = createMimicObject(document);
+
+    // Helper to update mimic state
+    const updateMimicState = () => {
+      const newMimic = createMimicObject(document);
+      set(
+        (state: any) => ({
+          ...state,
+          mimic: newMimic,
+        }),
+        false
+      );
+    };
+
+    // Subscribe to document changes
+    if (autoSubscribe) {
+      document.subscribe({
+        onStateChange: () => {
+          updateMimicState();
+        },
+        onConnectionChange: () => {
+          updateMimicState();
+        },
+        onReady: () => {
+          updateMimicState();
+        },
+      });
+
+      // Subscribe to presence changes (if presence schema is enabled)
+      document.presence?.subscribe({
+        onPresenceChange: () => {
+          updateMimicState();
+        },
+      });
+    }
+
+    if (autoConnect) {
+      document.connect();
+    }
+
+    // Get user's state - pass through set/get/api directly
+    // The user's set calls won't affect mimic state since we update it separately
+    const userState = config(set, get, api);
+
+    // Combine user state with mimic slice
+    return {
+      ...userState,
+      mimic: initialMimic,
+    };
+  };
+};
+
+/**
+ * Zustand middleware that integrates a ClientDocument.
+ * 
+ * Adds a `mimic` object to the store containing:
+ * - `document`: The ClientDocument instance for performing transactions
+ * - `snapshot`: Read-only snapshot of the document state (reactive)
+ * - `presence`: Reactive presence snapshot (self + others). Undefined if presence is not enabled on the ClientDocument.
+ * - `isConnected`: Connection status
+ * - `isReady`: Ready status
+ * - `pendingCount`: Number of pending transactions
+ * - `hasPendingChanges`: Whether there are pending changes
+ * 
+ * @example
+ * ```ts
+ * import { create } from 'zustand'
+ * import { mimic } from '@voidhash/mimic-react/zustand'
+ * 
+ * const useStore = create(
+ *   mimic(clientDocument, (set, get) => ({
+ *     // Your additional store state
+ *   }))
+ * )
+ * 
+ * // Read snapshot (reactive)
+ * const snapshot = useStore(state => state.mimic.snapshot)
+ * 
+ * // Read presence (reactive, if enabled)
+ * const myPresence = useStore(state => state.mimic.presence?.self)
+ * const othersPresence = useStore(state => state.mimic.presence?.others)
+ * 
+ * // Write via document
+ * store.getState().mimic.document.transaction(root => {
+ *   root.name.set("New Name")
+ * })
+ * ```
+ */
+export const mimic = mimicImpl as unknown as MimicMiddleware;

package/src/zustand/types.ts

@@ -0,0 +1,117 @@
+import type { StateCreator, StoreMutatorIdentifier } from "zustand";
+import type { ClientDocument } from "@voidhash/mimic/client";
+import type { Primitive, Presence } from "@voidhash/mimic";
+
+// =============================================================================
+// Mimic State Types
+// =============================================================================
+
+/**
+ * Presence data exposed on the zustand store (reactive snapshot).
+ */
+export interface MimicPresence<TPresence extends Presence.AnyPresence> {
+  /**
+   * This client's connection ID (set after receiving presence snapshot).
+   * Undefined before the snapshot is received.
+   */
+  readonly selfId: string | undefined;
+
+  /**
+   * This client's current presence data.
+   * Undefined if not set.
+   */
+  readonly self: Presence.Infer<TPresence> | undefined;
+
+  /**
+   * Other clients' presence entries (connectionId -> entry).
+   */
+  readonly others: ReadonlyMap<
+    string,
+    Presence.PresenceEntry<Presence.Infer<TPresence>>
+  >;
+
+  /**
+   * All presence entries including self (connectionId -> entry).
+   */
+  readonly all: ReadonlyMap<
+    string,
+    Presence.PresenceEntry<Presence.Infer<TPresence>>
+  >;
+}
+
+/**
+ * The mimic object containing the document and client state.
+ * This is added to the zustand store by the middleware.
+ */
+export interface MimicObject<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+> {
+  /** The ClientDocument instance for performing transactions */
+  readonly document: ClientDocument.ClientDocument<TSchema, TPresence>;
+  /** Read-only snapshot of the document state */
+  readonly snapshot: Primitive.InferSnapshot<TSchema>;
+  /**
+   * Reactive presence snapshot (self + others).
+   * Undefined when the ClientDocument was created without a presence schema.
+   */
+  readonly presence: TPresence extends Presence.AnyPresence
+    ? MimicPresence<TPresence>
+    : undefined;
+  /** Whether the client is connected to the server */
+  readonly isConnected: boolean;
+  /** Whether the client is fully initialized and ready */
+  readonly isReady: boolean;
+  /** Number of pending transactions */
+  readonly pendingCount: number;
+  /** Whether there are pending changes */
+  readonly hasPendingChanges: boolean;
+}
+
+/**
+ * The state slice added by the mimic middleware.
+ */
+export interface MimicSlice<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+> {
+  /** The mimic object containing document and state */
+  readonly mimic: MimicObject<TSchema, TPresence>;
+}
+
+// =============================================================================
+// Middleware Types
+// =============================================================================
+
+/**
+ * Type for the mimic middleware mutator.
+ */
+export type MimicMutator<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+> = [
+  "mimic",
+  TSchema,
+  TPresence
+];
+
+/**
+ * Type for state creator with mimic slice merged.
+ */
+export type MimicStateCreator<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined,
+  T,
+  Mps extends [StoreMutatorIdentifier, unknown][] = [],
+  Mcs extends [StoreMutatorIdentifier, unknown][] = [],
+> = StateCreator<T & MimicSlice<TSchema, TPresence>, Mps, Mcs, T>;
+
+/**
+ * Options for the mimic middleware.
+ */
+export interface MimicMiddlewareOptions {
+  /** If true, automatically subscribe when store is created (default: true) */
+  readonly autoSubscribe?: boolean;
+  /** If true, automatically attempt to connect the document to the remote server */
+  readonly autoConnect?: boolean;
+}