@guidekit/react 0.1.0-beta.1

package/dist/testing.d.ts

@@ -0,0 +1,133 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { AgentState, GuideKitErrorType, GuideKitStore } from '@guidekit/core';
+export { AgentState, GuideKitErrorType, GuideKitStore } from '@guidekit/core';
+
+/** @internal */
+declare class TestStore {
+    private listeners;
+    private _state;
+    constructor(initial?: Partial<GuideKitStore['status']>);
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => GuideKitStore;
+    setState(updater: (prev: GuideKitStore) => GuideKitStore): void;
+    /** Replace the state entirely. */
+    setStateDirectly(next: GuideKitStore): void;
+    private emitChange;
+}
+/** Initial state for the mock provider. */
+interface MockInitialState {
+    isReady?: boolean;
+    agentState?: AgentState;
+    error?: GuideKitErrorType | null;
+}
+/** Mock action implementations to inject into the provider. */
+interface MockActions {
+    sendText?: (text: string) => Promise<string>;
+    highlight?: (params: {
+        sectionId?: string;
+        selector?: string;
+        tooltip?: string;
+        position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    }) => void;
+    dismissHighlight?: () => void;
+    scrollToSection?: (sectionId: string, offset?: number) => void;
+    startTour?: (sectionIds: string[], mode?: 'auto' | 'manual') => void;
+    navigate?: (href: string) => Promise<boolean>;
+    setPageContext?: (context: Record<string, unknown>) => void;
+    registerAction?: (actionId: string, action: {
+        description: string;
+        parameters: Record<string, unknown>;
+        handler: (params: Record<string, unknown>) => Promise<unknown>;
+    }) => void;
+    startListening?: () => Promise<void>;
+    stopListening?: () => void;
+}
+/** Props for MockGuideKitProvider. */
+interface MockGuideKitProviderProps {
+    initialState?: MockInitialState;
+    actions?: MockActions;
+    children: ReactNode;
+}
+/**
+ * A mock provider for testing components that use GuideKit hooks.
+ *
+ * Instead of creating a real GuideKitCore instance (which requires API keys,
+ * browser APIs, etc.), this provider supplies a lightweight mock object that
+ * satisfies the context contract used by all hooks in `@guidekit/react`.
+ *
+ * All actions default to noops but can be overridden with mock functions
+ * (e.g. `vi.fn()`).
+ *
+ * The provider injects the mock into the same `GuideKitContext` that the
+ * real hooks read from (imported from `./_context.js`), so hooks like
+ * `useGuideKitStatus`, `useGuideKitVoice`, etc. work seamlessly.
+ *
+ * @example
+ * ```tsx
+ * import { MockGuideKitProvider } from '@guidekit/react/testing';
+ *
+ * render(
+ *   <MockGuideKitProvider
+ *     initialState={{ isReady: true, agentState: { status: 'idle' } }}
+ *     actions={{ sendText: vi.fn() }}
+ *   >
+ *     <ComponentUnderTest />
+ *   </MockGuideKitProvider>
+ * );
+ * ```
+ */
+declare function MockGuideKitProvider({ initialState, actions, children, }: MockGuideKitProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Simulates an assistant response being added to the agent state.
+ * Sets the agent state to `{ status: 'speaking', utterance: text }`.
+ *
+ * Subscribers (e.g. hooks using `useSyncExternalStore`) are notified
+ * synchronously, so assertions can run immediately after this call.
+ */
+declare function simulateAgentResponse(text: string): void;
+/**
+ * Simulates a voice transcript arriving (as if the user spoke).
+ * Sets the agent state to `{ status: 'processing', transcript: text }`
+ * and marks `voice.isListening` as `false`.
+ */
+declare function simulateVoiceInput(text: string): void;
+/**
+ * Simulates an error occurring in the agent.
+ * Sets the agent state to `{ status: 'error', error }` and populates
+ * the store-level `error` field.
+ */
+declare function simulateError(error: GuideKitErrorType): void;
+/**
+ * Returns the current mock store state. Useful for assertions in tests.
+ *
+ * @example
+ * ```ts
+ * const state = getGuideKitTestState();
+ * expect(state.status.isReady).toBe(true);
+ * ```
+ */
+declare function getGuideKitTestState(): GuideKitStore;
+/**
+ * Resets the agent state back to idle and clears any error.
+ * Useful for cleaning up between simulate* calls in a test.
+ */
+declare function resetAgentState(): void;
+/**
+ * Sets the `isReady` flag on the mock store. Useful to simulate the SDK
+ * finishing initialization.
+ */
+declare function simulateReady(isReady?: boolean): void;
+/**
+ * Returns the raw TestStore instance for advanced use cases (e.g.,
+ * subscribing to changes directly or calling `setState` with a custom
+ * updater). Returns `null` if no MockGuideKitProvider is mounted.
+ */
+declare function getTestStore_UNSAFE(): TestStore | null;
+/**
+ * Cleans up the global test store reference. Call this in `afterEach` or
+ * `afterAll` to prevent state leaking between tests.
+ */
+declare function cleanupTestStore(): void;
+
+export { type MockActions, MockGuideKitProvider, type MockGuideKitProviderProps, type MockInitialState, TestStore, cleanupTestStore, getGuideKitTestState, getTestStore_UNSAFE, resetAgentState, simulateAgentResponse, simulateError, simulateReady, simulateVoiceInput };

package/dist/testing.js

@@ -0,0 +1,185 @@
+import { GuideKitContext } from './chunk-4NUEGCBT.js';
+import { useRef } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var DEFAULT_STORE = {
+  status: {
+    isReady: false,
+    agentState: { status: "idle" },
+    error: null
+  }};
+var TestStore = class {
+  listeners = /* @__PURE__ */ new Set();
+  _state;
+  constructor(initial) {
+    this._state = {
+      status: {
+        isReady: initial?.isReady ?? DEFAULT_STORE.status.isReady,
+        agentState: initial?.agentState ?? DEFAULT_STORE.status.agentState,
+        error: initial?.error ?? DEFAULT_STORE.status.error
+      },
+      voice: {
+        isListening: false,
+        isSpeaking: false
+      }
+    };
+  }
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  getSnapshot = () => {
+    return this._state;
+  };
+  setState(updater) {
+    const next = updater(this._state);
+    if (next !== this._state) {
+      this._state = next;
+      this.emitChange();
+    }
+  }
+  /** Replace the state entirely. */
+  setStateDirectly(next) {
+    if (next !== this._state) {
+      this._state = next;
+      this.emitChange();
+    }
+  }
+  emitChange() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+};
+var _testStore = null;
+function requireTestStore() {
+  if (!_testStore) {
+    throw new Error(
+      "[GuideKit Testing] No MockGuideKitProvider is mounted. Wrap your component in <MockGuideKitProvider> before calling simulate* functions."
+    );
+  }
+  return _testStore;
+}
+var noopVoid = () => {
+};
+var noopAsync = () => Promise.resolve();
+var noopAsyncString = () => Promise.resolve("");
+var noopAsyncBool = () => Promise.resolve(true);
+function MockGuideKitProvider({
+  initialState,
+  actions,
+  children
+}) {
+  const storeRef = useRef(null);
+  if (storeRef.current === null) {
+    storeRef.current = new TestStore(initialState);
+  }
+  _testStore = storeRef.current;
+  const store = storeRef.current;
+  const mockCoreRef = useRef(null);
+  if (mockCoreRef.current === null) {
+    mockCoreRef.current = {
+      // Store protocol (useSyncExternalStore)
+      subscribe: store.subscribe,
+      getSnapshot: store.getSnapshot,
+      // Actions
+      sendText: actions?.sendText ?? noopAsyncString,
+      highlight: actions?.highlight ?? noopVoid,
+      dismissHighlight: actions?.dismissHighlight ?? noopVoid,
+      scrollToSection: actions?.scrollToSection ?? noopVoid,
+      startTour: actions?.startTour ?? noopVoid,
+      navigate: actions?.navigate ?? noopAsyncBool,
+      setPageContext: actions?.setPageContext ?? noopVoid,
+      registerAction: actions?.registerAction ?? noopVoid,
+      startListening: actions?.startListening ?? noopAsync,
+      stopListening: actions?.stopListening ?? noopVoid,
+      // Read-only properties
+      hasVoice: false,
+      instanceId: "mock-test-instance",
+      isReady: initialState?.isReady ?? false,
+      agentState: initialState?.agentState ?? { status: "idle" },
+      // i18n stub (used by the widget internals)
+      i18n: { t: (key) => key },
+      // Lifecycle stubs
+      init: noopAsync,
+      destroy: noopAsync
+    };
+  }
+  return /* @__PURE__ */ jsx(GuideKitContext.Provider, { value: mockCoreRef.current, children });
+}
+function simulateAgentResponse(text) {
+  const store = requireTestStore();
+  store.setState((prev) => ({
+    ...prev,
+    status: {
+      ...prev.status,
+      agentState: { status: "speaking", utterance: text }
+    }
+  }));
+}
+function simulateVoiceInput(text) {
+  const store = requireTestStore();
+  store.setState((prev) => ({
+    ...prev,
+    status: {
+      ...prev.status,
+      agentState: { status: "processing", transcript: text }
+    },
+    voice: {
+      ...prev.voice,
+      isListening: false
+    }
+  }));
+}
+function simulateError(error) {
+  const store = requireTestStore();
+  store.setState((prev) => ({
+    ...prev,
+    status: {
+      ...prev.status,
+      agentState: { status: "error", error },
+      error
+    }
+  }));
+}
+function getGuideKitTestState() {
+  const store = requireTestStore();
+  return store.getSnapshot();
+}
+function resetAgentState() {
+  const store = requireTestStore();
+  store.setState((prev) => ({
+    ...prev,
+    status: {
+      ...prev.status,
+      agentState: { status: "idle" },
+      error: null
+    },
+    voice: {
+      isListening: false,
+      isSpeaking: false
+    }
+  }));
+}
+function simulateReady(isReady = true) {
+  const store = requireTestStore();
+  store.setState((prev) => ({
+    ...prev,
+    status: {
+      ...prev.status,
+      isReady
+    }
+  }));
+}
+function getTestStore_UNSAFE() {
+  return _testStore;
+}
+function cleanupTestStore() {
+  _testStore = null;
+}
+
+export { MockGuideKitProvider, TestStore, cleanupTestStore, getGuideKitTestState, getTestStore_UNSAFE, resetAgentState, simulateAgentResponse, simulateError, simulateReady, simulateVoiceInput };
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.tsx"],"names":[],"mappings":"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","file":"testing.js","sourcesContent":["// ---------------------------------------------------------------------------\n// @guidekit/react/testing — Testing utilities for apps using GuideKit\n// ---------------------------------------------------------------------------\n//\n// Provides MockGuideKitProvider and simulate* helpers so consumers can test\n// components that depend on GuideKit hooks without spinning up a real\n// GuideKitCore instance.\n//\n// Usage:\n//   import { MockGuideKitProvider, simulateAgentResponse } from '@guidekit/react/testing';\n//\n//   render(\n//     <MockGuideKitProvider initialState={{ isReady: true }}>\n//       <MyComponent />\n//     </MockGuideKitProvider>\n//   );\n//\n//   simulateAgentResponse('Hello from the agent!');\n// ---------------------------------------------------------------------------\n\nimport { useRef } from 'react';\nimport type { ReactNode } from 'react';\nimport type { AgentState, GuideKitStore, GuideKitErrorType } from '@guidekit/core';\n\nimport { GuideKitContext } from './_context.js';\n\n// ---------------------------------------------------------------------------\n// Default store snapshot\n// ---------------------------------------------------------------------------\n\nconst DEFAULT_STORE: GuideKitStore = {\n  status: {\n    isReady: false,\n    agentState: { status: 'idle' },\n    error: null,\n  },\n  voice: {\n    isListening: false,\n    isSpeaking: false,\n  },\n};\n\n// ---------------------------------------------------------------------------\n// TestStore — a minimal external store compatible with useSyncExternalStore\n// ---------------------------------------------------------------------------\n\n/** @internal */\nexport class TestStore {\n  private listeners = new Set<() => void>();\n  private _state: GuideKitStore;\n\n  constructor(initial?: Partial<GuideKitStore['status']>) {\n    this._state = {\n      status: {\n        isReady: initial?.isReady ?? DEFAULT_STORE.status.isReady,\n        agentState: initial?.agentState ?? DEFAULT_STORE.status.agentState,\n        error: initial?.error ?? DEFAULT_STORE.status.error,\n      },\n      voice: {\n        isListening: false,\n        isSpeaking: false,\n      },\n    };\n  }\n\n  subscribe = (listener: () => void): (() => void) => {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  };\n\n  getSnapshot = (): GuideKitStore => {\n    return this._state;\n  };\n\n  setState(updater: (prev: GuideKitStore) => GuideKitStore): void {\n    const next = updater(this._state);\n    if (next !== this._state) {\n      this._state = next;\n      this.emitChange();\n    }\n  }\n\n  /** Replace the state entirely. */\n  setStateDirectly(next: GuideKitStore): void {\n    if (next !== this._state) {\n      this._state = next;\n      this.emitChange();\n    }\n  }\n\n  private emitChange(): void {\n    for (const listener of this.listeners) {\n      listener();\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Global test store — shared across simulate* functions\n// ---------------------------------------------------------------------------\n\nlet _testStore: TestStore | null = null;\n\nfunction requireTestStore(): TestStore {\n  if (!_testStore) {\n    throw new Error(\n      '[GuideKit Testing] No MockGuideKitProvider is mounted. ' +\n        'Wrap your component in <MockGuideKitProvider> before calling simulate* functions.',\n    );\n  }\n  return _testStore;\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Initial state for the mock provider. */\nexport interface MockInitialState {\n  isReady?: boolean;\n  agentState?: AgentState;\n  error?: GuideKitErrorType | null;\n}\n\n/** Mock action implementations to inject into the provider. */\nexport interface MockActions {\n  sendText?: (text: string) => Promise<string>;\n  highlight?: (params: {\n    sectionId?: string;\n    selector?: string;\n    tooltip?: string;\n    position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';\n  }) => void;\n  dismissHighlight?: () => void;\n  scrollToSection?: (sectionId: string, offset?: number) => void;\n  startTour?: (sectionIds: string[], mode?: 'auto' | 'manual') => void;\n  navigate?: (href: string) => Promise<boolean>;\n  setPageContext?: (context: Record<string, unknown>) => void;\n  registerAction?: (\n    actionId: string,\n    action: {\n      description: string;\n      parameters: Record<string, unknown>;\n      handler: (params: Record<string, unknown>) => Promise<unknown>;\n    },\n  ) => void;\n  startListening?: () => Promise<void>;\n  stopListening?: () => void;\n}\n\n/** Props for MockGuideKitProvider. */\nexport interface MockGuideKitProviderProps {\n  initialState?: MockInitialState;\n  actions?: MockActions;\n  children: ReactNode;\n}\n\n// ---------------------------------------------------------------------------\n// Noop stubs\n// ---------------------------------------------------------------------------\n\nconst noopVoid = () => {};\nconst noopAsync = () => Promise.resolve();\nconst noopAsyncString = () => Promise.resolve('');\nconst noopAsyncBool = () => Promise.resolve(true);\n\n// ---------------------------------------------------------------------------\n// MockGuideKitProvider\n// ---------------------------------------------------------------------------\n\n/**\n * A mock provider for testing components that use GuideKit hooks.\n *\n * Instead of creating a real GuideKitCore instance (which requires API keys,\n * browser APIs, etc.), this provider supplies a lightweight mock object that\n * satisfies the context contract used by all hooks in `@guidekit/react`.\n *\n * All actions default to noops but can be overridden with mock functions\n * (e.g. `vi.fn()`).\n *\n * The provider injects the mock into the same `GuideKitContext` that the\n * real hooks read from (imported from `./_context.js`), so hooks like\n * `useGuideKitStatus`, `useGuideKitVoice`, etc. work seamlessly.\n *\n * @example\n * ```tsx\n * import { MockGuideKitProvider } from '@guidekit/react/testing';\n *\n * render(\n *   <MockGuideKitProvider\n *     initialState={{ isReady: true, agentState: { status: 'idle' } }}\n *     actions={{ sendText: vi.fn() }}\n *   >\n *     <ComponentUnderTest />\n *   </MockGuideKitProvider>\n * );\n * ```\n */\nexport function MockGuideKitProvider({\n  initialState,\n  actions,\n  children,\n}: MockGuideKitProviderProps) {\n  // Create a TestStore on first render, keep it stable across re-renders.\n  const storeRef = useRef<TestStore | null>(null);\n  if (storeRef.current === null) {\n    storeRef.current = new TestStore(initialState);\n  }\n\n  // Register as the global test store so simulate* functions can find it.\n  _testStore = storeRef.current;\n\n  const store = storeRef.current;\n\n  // Build the mock object that duck-types as GuideKitCore.\n  // Kept stable via a ref so the context value identity does not change.\n  const mockCoreRef = useRef<Record<string, unknown> | null>(null);\n  if (mockCoreRef.current === null) {\n    mockCoreRef.current = {\n      // Store protocol (useSyncExternalStore)\n      subscribe: store.subscribe,\n      getSnapshot: store.getSnapshot,\n\n      // Actions\n      sendText: actions?.sendText ?? noopAsyncString,\n      highlight: actions?.highlight ?? noopVoid,\n      dismissHighlight: actions?.dismissHighlight ?? noopVoid,\n      scrollToSection: actions?.scrollToSection ?? noopVoid,\n      startTour: actions?.startTour ?? noopVoid,\n      navigate: actions?.navigate ?? noopAsyncBool,\n      setPageContext: actions?.setPageContext ?? noopVoid,\n      registerAction: actions?.registerAction ?? noopVoid,\n      startListening: actions?.startListening ?? noopAsync,\n      stopListening: actions?.stopListening ?? noopVoid,\n\n      // Read-only properties\n      hasVoice: false,\n      instanceId: 'mock-test-instance',\n      isReady: initialState?.isReady ?? false,\n      agentState: initialState?.agentState ?? { status: 'idle' as const },\n\n      // i18n stub (used by the widget internals)\n      i18n: { t: (key: string) => key },\n\n      // Lifecycle stubs\n      init: noopAsync,\n      destroy: noopAsync,\n    };\n  }\n\n  // Provide the mock into the same GuideKitContext that the real hooks\n  // consume, so useGuideKitStatus, useGuideKitVoice, etc. all work.\n  return (\n    <GuideKitContext.Provider value={mockCoreRef.current as any}>\n      {children}\n    </GuideKitContext.Provider>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// simulate* functions — update the global test store\n// ---------------------------------------------------------------------------\n\n/**\n * Simulates an assistant response being added to the agent state.\n * Sets the agent state to `{ status: 'speaking', utterance: text }`.\n *\n * Subscribers (e.g. hooks using `useSyncExternalStore`) are notified\n * synchronously, so assertions can run immediately after this call.\n */\nexport function simulateAgentResponse(text: string): void {\n  const store = requireTestStore();\n\n  store.setState((prev) => ({\n    ...prev,\n    status: {\n      ...prev.status,\n      agentState: { status: 'speaking', utterance: text } as AgentState,\n    },\n  }));\n}\n\n/**\n * Simulates a voice transcript arriving (as if the user spoke).\n * Sets the agent state to `{ status: 'processing', transcript: text }`\n * and marks `voice.isListening` as `false`.\n */\nexport function simulateVoiceInput(text: string): void {\n  const store = requireTestStore();\n\n  store.setState((prev) => ({\n    ...prev,\n    status: {\n      ...prev.status,\n      agentState: { status: 'processing', transcript: text } as AgentState,\n    },\n    voice: {\n      ...prev.voice,\n      isListening: false,\n    },\n  }));\n}\n\n/**\n * Simulates an error occurring in the agent.\n * Sets the agent state to `{ status: 'error', error }` and populates\n * the store-level `error` field.\n */\nexport function simulateError(error: GuideKitErrorType): void {\n  const store = requireTestStore();\n\n  store.setState((prev) => ({\n    ...prev,\n    status: {\n      ...prev.status,\n      agentState: { status: 'error', error } as AgentState,\n      error,\n    },\n  }));\n}\n\n/**\n * Returns the current mock store state. Useful for assertions in tests.\n *\n * @example\n * ```ts\n * const state = getGuideKitTestState();\n * expect(state.status.isReady).toBe(true);\n * ```\n */\nexport function getGuideKitTestState(): GuideKitStore {\n  const store = requireTestStore();\n  return store.getSnapshot();\n}\n\n// ---------------------------------------------------------------------------\n// Additional helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Resets the agent state back to idle and clears any error.\n * Useful for cleaning up between simulate* calls in a test.\n */\nexport function resetAgentState(): void {\n  const store = requireTestStore();\n\n  store.setState((prev) => ({\n    ...prev,\n    status: {\n      ...prev.status,\n      agentState: { status: 'idle' } as AgentState,\n      error: null,\n    },\n    voice: {\n      isListening: false,\n      isSpeaking: false,\n    },\n  }));\n}\n\n/**\n * Sets the `isReady` flag on the mock store. Useful to simulate the SDK\n * finishing initialization.\n */\nexport function simulateReady(isReady: boolean = true): void {\n  const store = requireTestStore();\n\n  store.setState((prev) => ({\n    ...prev,\n    status: {\n      ...prev.status,\n      isReady,\n    },\n  }));\n}\n\n/**\n * Returns the raw TestStore instance for advanced use cases (e.g.,\n * subscribing to changes directly or calling `setState` with a custom\n * updater). Returns `null` if no MockGuideKitProvider is mounted.\n */\nexport function getTestStore_UNSAFE(): TestStore | null {\n  return _testStore;\n}\n\n/**\n * Cleans up the global test store reference. Call this in `afterEach` or\n * `afterAll` to prevent state leaking between tests.\n */\nexport function cleanupTestStore(): void {\n  _testStore = null;\n}\n\n// ---------------------------------------------------------------------------\n// Re-export types for convenience\n// ---------------------------------------------------------------------------\n\nexport type { AgentState, GuideKitStore, GuideKitErrorType };\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@guidekit/react",
+  "version": "0.1.0-beta.1",
+  "description": "React bindings for GuideKit SDK — Provider, hooks, and Widget",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./devtools": {
+      "types": "./dist/devtools.d.ts",
+      "import": "./dist/devtools.js",
+      "require": "./dist/devtools.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "../../LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@guidekit/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsup": "^8.4.0",
+    "vitest": "^3.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}