@vinaverse/react 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/agent.js

@@ -1,160 +1,3 @@
-import { greetedKey, agentKey } from '@vinaverse/client/agent';
-export { greetedKey } from '@vinaverse/client/agent';
-import { useContext, useRef, useCallback, useSyncExternalStore, useLayoutEffect, useEffect, useState, createContext } from 'react';
-import { jsx } from 'react/jsx-runtime';
-
-// src/agent.tsx
-var RuntimeContext = /* @__PURE__ */ createContext(null);
-function AgentRuntimeProvider(props) {
-  return /* @__PURE__ */ jsx(RuntimeContext.Provider, { value: props.runtime, children: props.children });
-}
-function useAgentRuntime() {
-  const runtime = useContext(RuntimeContext);
-  if (!runtime)
-    throw new Error("Agent hooks render inside <AgentRuntimeProvider>.");
-  return runtime;
-}
-function useAgentConversation(key, open = {}) {
-  const runtime = useAgentRuntime();
-  const keyRef = useRef(key);
-  keyRef.current = key;
-  const k = agentKey(key);
-  const read = useCallback(() => runtime.peek(keyRef.current), [runtime, k]);
-  const conversation = useSyncExternalStore(runtime.subscribe, read, read);
-  const openRef = useRef(open);
-  openRef.current = open;
-  useLayoutEffect(() => conversation.show(openRef.current), [conversation]);
-  const { place, entryPoint } = open;
-  const screen = place?.screen;
-  const entityType = place?.entity?.type;
-  const entityId = place?.entity?.id;
-  const filters = place?.filters ? JSON.stringify(place.filters) : null;
-  const cleared = place === null;
-  useLayoutEffect(() => {
-    conversation.tell(openRef.current);
-  }, [
-    conversation,
-    screen,
-    entityType,
-    entityId,
-    filters,
-    cleared,
-    entryPoint
-  ]);
-  const state = useSyncExternalStore(
-    conversation.subscribe,
-    conversation.getState,
-    conversation.getState
-  );
-  const startNew = useCallback(
-    () => runtime.startNew(keyRef.current),
-    [runtime]
-  );
-  return { conversation, state, startNew };
-}
-function useAgentStatus() {
-  const runtime = useAgentRuntime();
-  useEffect(() => {
-    runtime.status().catch(() => void 0);
-  }, [runtime]);
-  return useSyncExternalStore(
-    runtime.subscribe,
-    runtime.getStatus,
-    runtime.getStatus
-  );
-}
-function useAgentStatusState() {
-  const runtime = useAgentRuntime();
-  useEffect(() => {
-    runtime.status().catch(() => void 0);
-  }, [runtime]);
-  return useSyncExternalStore(
-    runtime.subscribe,
-    runtime.getStatusState,
-    runtime.getStatusState
-  );
-}
-function useAgentName(fallback) {
-  const runtime = useAgentRuntime();
-  return useSyncExternalStore(runtime.subscribe, runtime.getName, runtime.getName) ?? fallback;
-}
-function useAgentFeatures() {
-  const status = useAgentStatus();
-  return {
-    available: status?.available === true,
-    launcher: status?.launcher === true,
-    history: status?.features.history === true,
-    memory: status?.features.memory === true,
-    businessAgent: status?.features.businessAgent === true,
-    businessSetup: status?.features.businessSetup === true
-  };
-}
-function useAgentProfile(fallback) {
-  const status = useAgentStatus();
-  return { name: useAgentName(fallback), avatarUrl: status?.avatarUrl ?? null };
-}
-async function forgetGreeting(storage, subject, modes, storageKey = greetedKey) {
-  for (const mode of modes) await storage.removeItem(storageKey(subject, mode));
-}
-var MEMORY = /* @__PURE__ */ new Map();
-var memory = {
-  getItem: (k) => MEMORY.get(k) ?? null,
-  setItem: (k, v) => void MEMORY.set(k, v),
-  removeItem: (k) => void MEMORY.delete(k)
-};
-function useAgentLauncher(options) {
-  const runtime = useAgentRuntime();
-  const status = useAgentStatus();
-  const { subject, mode, onOpen } = options;
-  const storage = options.storage ?? runtime.greetings ?? memory;
-  const shows = status?.launcher === true && options.visible !== false;
-  const key = (options.storageKey ?? greetedKey)(subject, mode);
-  const [greeted, setGreeted] = useState(
-    null
-  );
-  const [due, setDue] = useState(null);
-  useEffect(() => {
-    let live = true;
-    Promise.resolve(storage.getItem(key)).then(
-      (value) => {
-        if (live) setGreeted({ key, done: value === "1" });
-      },
-      () => {
-        if (live) setGreeted({ key, done: false });
-      }
-    );
-    return () => {
-      live = false;
-    };
-  }, [storage, key]);
-  const pending = shows && greeted?.key === key && !greeted.done;
-  useEffect(() => {
-    if (!pending) return;
-    const timer = setTimeout(() => {
-      setDue(key);
-      runtime.emit({ type: "launcher_greeted" });
-    }, options.delayMs ?? 1200);
-    return () => clearTimeout(timer);
-  }, [pending, key, runtime, options.delayMs]);
-  const done = useCallback(() => {
-    setGreeted({ key, done: true });
-    void Promise.resolve(storage.setItem(key, "1")).catch(() => void 0);
-  }, [storage, key]);
-  const open = useCallback(() => {
-    done();
-    runtime.emit({ type: "launcher_opened" });
-    onOpen();
-  }, [done, runtime, onOpen]);
-  const dismiss = useCallback(() => {
-    done();
-    runtime.emit({ type: "greeting_closed" });
-  }, [done, runtime]);
-  useEffect(() => {
-    if (shows) runtime.emit({ type: "launcher_shown" });
-  }, [shows, runtime]);
-  return { shows, greets: pending && due === key, open, dismiss };
-}
-
-export { AgentRuntimeProvider, forgetGreeting, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus, useAgentStatusState };
+export { AgentRuntimeProvider, forgetGreeting, greetedKey, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus, useAgentStatusState } from './chunk-V4UBOVTK.js';
 //# sourceMappingURL=agent.js.map
 //# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/agent.tsx"],"names":[],"mappings":"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","file":"agent.js","sourcesContent":["// React bindings of the agent runtime (@vinaverse/client/agent): a provider and hooks, thin by design. The runtime holds\n// every rule; these subscribe, show a conversation while a component is mounted, and read the launcher's state. No\n// react-native or DOM import.\nimport type {\n  AgentConversation,\n  AgentConversationState,\n  AgentKey,\n  AgentPlace,\n  AgentRuntime,\n  AgentStatus,\n  AgentStatusState,\n} from '@vinaverse/client/agent';\nimport { agentKey, greetedKey } from '@vinaverse/client/agent';\nimport {\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\n\nconst RuntimeContext = /* @__PURE__ */ createContext<AgentRuntime | null>(null);\n\n/** The app's agent runtime, made once (module level, or memoized) and given to everything below. */\nexport function AgentRuntimeProvider(props: {\n  readonly runtime: AgentRuntime;\n  readonly children?: ReactNode;\n}): ReactNode {\n  return (\n    <RuntimeContext.Provider value={props.runtime}>\n      {props.children}\n    </RuntimeContext.Provider>\n  );\n}\n\nexport function useAgentRuntime(): AgentRuntime {\n  const runtime = useContext(RuntimeContext);\n  if (!runtime)\n    throw new Error('Agent hooks render inside <AgentRuntimeProvider>.');\n  return runtime;\n}\n\nexport interface UseAgentConversation {\n  readonly conversation: AgentConversation;\n  readonly state: AgentConversationState;\n  /** A new conversation for this key (the old one let go and forgotten). */\n  readonly startNew: () => void;\n}\n\n/**\n * The key's conversation, shown while the component is mounted (kept across screens; released when it unmounts), told\n * the place and the way in as they change. A start over or its end hands the component the key's next conversation.\n */\nexport function useAgentConversation(\n  key: AgentKey,\n  open: {\n    readonly place?: AgentPlace | null;\n    readonly entryPoint?: string | null;\n  } = {},\n): UseAgentConversation {\n  const runtime = useAgentRuntime();\n  const keyRef = useRef(key);\n  keyRef.current = key;\n  const k = agentKey(key);\n  // biome-ignore lint/correctness/useExhaustiveDependencies: the key's string reads it again when the key changes\n  const read = useCallback(() => runtime.peek(keyRef.current), [runtime, k]);\n  const conversation = useSyncExternalStore(runtime.subscribe, read, read);\n  const openRef = useRef(open);\n  openRef.current = open;\n  // Layout effects: they run before any passive effect, a child's included, so a chat below that starts the\n  // conversation early (`VinaverseChat`) finds it shown and told the place.\n  useLayoutEffect(() => conversation.show(openRef.current), [conversation]);\n  const { place, entryPoint } = open;\n  const screen = place?.screen;\n  const entityType = place?.entity?.type;\n  const entityId = place?.entity?.id;\n  const filters = place?.filters ? JSON.stringify(place.filters) : null;\n  const cleared = place === null;\n  // biome-ignore lint/correctness/useExhaustiveDependencies: told by value, so a place made again each render is the same\n  useLayoutEffect(() => {\n    conversation.tell(openRef.current);\n  }, [\n    conversation,\n    screen,\n    entityType,\n    entityId,\n    filters,\n    cleared,\n    entryPoint,\n  ]);\n  const state = useSyncExternalStore(\n    conversation.subscribe,\n    conversation.getState,\n    conversation.getState,\n  );\n  const startNew = useCallback(\n    () => runtime.startNew(keyRef.current),\n    [runtime],\n  );\n  return { conversation, state, startNew };\n}\n\n/** The agent's status (read once, then at most every few minutes); null until the first read. */\nexport function useAgentStatus(): AgentStatus | null {\n  const runtime = useAgentRuntime();\n  useEffect(() => {\n    runtime.status().catch(() => undefined); // an unread status is no agent: the launcher stays hidden\n  }, [runtime]);\n  return useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getStatus,\n    runtime.getStatus,\n  );\n}\n\n/**\n * The status with where its read stands (`{ status, reading, failed }`): a screen tells \"still reading\" from \"could\n * not read\" and draws each its own way. Reads the status, as `useAgentStatus` does.\n */\nexport function useAgentStatusState(): AgentStatusState {\n  const runtime = useAgentRuntime();\n  useEffect(() => {\n    runtime.status().catch(() => undefined); // said through `failed`\n  }, [runtime]);\n  return useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getStatusState,\n    runtime.getStatusState,\n  );\n}\n\n/** The agent's name: the newest session's, else the status's, else `fallback`. */\nexport function useAgentName(fallback: string): string {\n  const runtime = useAgentRuntime();\n  return (\n    useSyncExternalStore(runtime.subscribe, runtime.getName, runtime.getName) ??\n    fallback\n  );\n}\n\n/** What the agent can do, from the status (all off until it is read, and when the agent is off). */\nexport function useAgentFeatures(): AgentStatus['features'] & {\n  readonly available: boolean;\n  readonly launcher: boolean;\n} {\n  const status = useAgentStatus();\n  return {\n    available: status?.available === true,\n    launcher: status?.launcher === true,\n    history: status?.features.history === true,\n    memory: status?.features.memory === true,\n    businessAgent: status?.features.businessAgent === true,\n    businessSetup: status?.features.businessSetup === true,\n  };\n}\n\n/** The agent as an entry shows it before any session: its name (`fallback` until known) and avatar. */\nexport function useAgentProfile(fallback: string): {\n  readonly name: string;\n  readonly avatarUrl: string | null;\n} {\n  const status = useAgentStatus();\n  return { name: useAgentName(fallback), avatarUrl: status?.avatarUrl ?? null };\n}\n\n/**\n * Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). A\n * sign-out keeps it on purpose (a person is not greeted again after signing back in). Given to the runtime as\n * `greetingStorage`, `runtime.erase()` erases it; `forgetGreeting` is the low-level helper for a storage of the app's.\n */\nexport interface GreetingStorage {\n  getItem(key: string): string | null | Promise<string | null>;\n  setItem(key: string, value: string): void | Promise<void>;\n  /** Erasure removes the record, never leaves a key that names the person. */\n  removeItem(key: string): void | Promise<void>;\n}\n\n/** Where the greeting is remembered, per person and mode: the default the storage sees, unless the app maps its own. */\nexport { greetedKey };\n\n/** Removes the launcher's record of greeting this person in these modes (`runtime.erase()` does it for `greetingStorage`). */\nexport async function forgetGreeting(\n  storage: GreetingStorage,\n  subject: string | null,\n  modes: readonly string[],\n  storageKey: (subject: string | null, mode: string) => string = greetedKey,\n): Promise<void> {\n  for (const mode of modes) await storage.removeItem(storageKey(subject, mode));\n}\n\nconst MEMORY = new Map<string, string>();\nconst memory: GreetingStorage = {\n  getItem: (k) => MEMORY.get(k) ?? null,\n  setItem: (k, v) => void MEMORY.set(k, v),\n  removeItem: (k) => void MEMORY.delete(k),\n};\n\nexport interface UseAgentLauncher {\n  /** The status offers the launcher, and the app shows it here. */\n  readonly shows: boolean;\n  /** Its greeting bubble: once per person and mode, a moment after the launcher shows. */\n  readonly greets: boolean;\n  /** The person opens the agent (the greeting is done too). */\n  readonly open: () => void;\n  /** The person closes the greeting. */\n  readonly dismiss: () => void;\n}\n\n/** The floating launcher's state: whether it shows and greets, and its two actions. */\nexport function useAgentLauncher(options: {\n  readonly subject: string | null;\n  readonly mode: string;\n  /** The app's own rule (the tabs it shows on, no keyboard up…); default true. */\n  readonly visible?: boolean;\n  readonly storage?: GreetingStorage;\n  /** The storage's key for a person and mode, to reuse a record the app already keeps. Default `greetedKey`. */\n  readonly storageKey?: (subject: string | null, mode: string) => string;\n  /** How long after showing the greeting appears. Default 1200 ms. */\n  readonly delayMs?: number;\n  readonly onOpen: () => void;\n}): UseAgentLauncher {\n  const runtime = useAgentRuntime();\n  const status = useAgentStatus();\n  const { subject, mode, onOpen } = options;\n  // The app's own store, else the runtime's (`greetingStorage`: fenced by a sign-out, reached by `erase()`).\n  const storage = options.storage ?? runtime.greetings ?? memory;\n  const shows = status?.launcher === true && options.visible !== false;\n  const key = (options.storageKey ?? greetedKey)(subject, mode);\n  const [greeted, setGreeted] = useState<{ key: string; done: boolean } | null>(\n    null,\n  );\n  const [due, setDue] = useState<string | null>(null);\n  useEffect(() => {\n    let live = true;\n    Promise.resolve(storage.getItem(key)).then(\n      (value) => {\n        if (live) setGreeted({ key, done: value === '1' });\n      },\n      () => {\n        if (live) setGreeted({ key, done: false });\n      },\n    );\n    return () => {\n      live = false;\n    };\n  }, [storage, key]);\n  const pending = shows && greeted?.key === key && !greeted.done;\n  useEffect(() => {\n    if (!pending) return;\n    const timer = setTimeout(() => {\n      setDue(key);\n      runtime.emit({ type: 'launcher_greeted' });\n    }, options.delayMs ?? 1200);\n    return () => clearTimeout(timer);\n  }, [pending, key, runtime, options.delayMs]);\n  const done = useCallback(() => {\n    setGreeted({ key, done: true });\n    void Promise.resolve(storage.setItem(key, '1')).catch(() => undefined);\n  }, [storage, key]);\n  const open = useCallback(() => {\n    done();\n    runtime.emit({ type: 'launcher_opened' });\n    onOpen();\n  }, [done, runtime, onOpen]);\n  const dismiss = useCallback(() => {\n    done();\n    runtime.emit({ type: 'greeting_closed' });\n  }, [done, runtime]);\n  useEffect(() => {\n    if (shows) runtime.emit({ type: 'launcher_shown' });\n  }, [shows, runtime]);\n  return { shows, greets: pending && due === key, open, dismiss };\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent.js"}

package/dist/chunk-V4UBOVTK.js

@@ -0,0 +1,160 @@
+import { greetedKey, agentKey } from '@vinaverse/client/agent';
+export { greetedKey } from '@vinaverse/client/agent';
+import { useContext, useRef, useCallback, useSyncExternalStore, useLayoutEffect, useEffect, useState, createContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/agent.tsx
+var RuntimeContext = /* @__PURE__ */ createContext(null);
+function AgentRuntimeProvider(props) {
+  return /* @__PURE__ */ jsx(RuntimeContext.Provider, { value: props.runtime, children: props.children });
+}
+function useAgentRuntime() {
+  const runtime = useContext(RuntimeContext);
+  if (!runtime)
+    throw new Error("Agent hooks render inside <AgentRuntimeProvider>.");
+  return runtime;
+}
+function useAgentConversation(key, open = {}) {
+  const runtime = useAgentRuntime();
+  const keyRef = useRef(key);
+  keyRef.current = key;
+  const k = agentKey(key);
+  const read = useCallback(() => runtime.peek(keyRef.current), [runtime, k]);
+  const conversation = useSyncExternalStore(runtime.subscribe, read, read);
+  const openRef = useRef(open);
+  openRef.current = open;
+  useLayoutEffect(() => conversation.show(openRef.current), [conversation]);
+  const { place, entryPoint } = open;
+  const screen = place?.screen;
+  const entityType = place?.entity?.type;
+  const entityId = place?.entity?.id;
+  const filters = place?.filters ? JSON.stringify(place.filters) : null;
+  const cleared = place === null;
+  useLayoutEffect(() => {
+    conversation.tell(openRef.current);
+  }, [
+    conversation,
+    screen,
+    entityType,
+    entityId,
+    filters,
+    cleared,
+    entryPoint
+  ]);
+  const state = useSyncExternalStore(
+    conversation.subscribe,
+    conversation.getState,
+    conversation.getState
+  );
+  const startNew = useCallback(
+    () => runtime.startNew(keyRef.current),
+    [runtime]
+  );
+  return { conversation, state, startNew };
+}
+function useAgentStatus() {
+  const runtime = useAgentRuntime();
+  useEffect(() => {
+    runtime.status().catch(() => void 0);
+  }, [runtime]);
+  return useSyncExternalStore(
+    runtime.subscribe,
+    runtime.getStatus,
+    runtime.getStatus
+  );
+}
+function useAgentStatusState() {
+  const runtime = useAgentRuntime();
+  useEffect(() => {
+    runtime.status().catch(() => void 0);
+  }, [runtime]);
+  return useSyncExternalStore(
+    runtime.subscribe,
+    runtime.getStatusState,
+    runtime.getStatusState
+  );
+}
+function useAgentName(fallback) {
+  const runtime = useAgentRuntime();
+  return useSyncExternalStore(runtime.subscribe, runtime.getName, runtime.getName) ?? fallback;
+}
+function useAgentFeatures() {
+  const status = useAgentStatus();
+  return {
+    available: status?.available === true,
+    launcher: status?.launcher === true,
+    history: status?.features.history === true,
+    memory: status?.features.memory === true,
+    businessAgent: status?.features.businessAgent === true,
+    businessSetup: status?.features.businessSetup === true
+  };
+}
+function useAgentProfile(fallback) {
+  const status = useAgentStatus();
+  return { name: useAgentName(fallback), avatarUrl: status?.avatarUrl ?? null };
+}
+async function forgetGreeting(storage, subject, modes, storageKey = greetedKey) {
+  for (const mode of modes) await storage.removeItem(storageKey(subject, mode));
+}
+var MEMORY = /* @__PURE__ */ new Map();
+var memory = {
+  getItem: (k) => MEMORY.get(k) ?? null,
+  setItem: (k, v) => void MEMORY.set(k, v),
+  removeItem: (k) => void MEMORY.delete(k)
+};
+function useAgentLauncher(options) {
+  const runtime = useAgentRuntime();
+  const status = useAgentStatus();
+  const { subject, mode, onOpen } = options;
+  const storage = options.storage ?? runtime.greetings ?? memory;
+  const shows = status?.launcher === true && options.visible !== false;
+  const key = (options.storageKey ?? greetedKey)(subject, mode);
+  const [greeted, setGreeted] = useState(
+    null
+  );
+  const [due, setDue] = useState(null);
+  useEffect(() => {
+    let live = true;
+    Promise.resolve(storage.getItem(key)).then(
+      (value) => {
+        if (live) setGreeted({ key, done: value === "1" });
+      },
+      () => {
+        if (live) setGreeted({ key, done: false });
+      }
+    );
+    return () => {
+      live = false;
+    };
+  }, [storage, key]);
+  const pending = shows && greeted?.key === key && !greeted.done;
+  useEffect(() => {
+    if (!pending) return;
+    const timer = setTimeout(() => {
+      setDue(key);
+      runtime.emit({ type: "launcher_greeted" });
+    }, options.delayMs ?? 1200);
+    return () => clearTimeout(timer);
+  }, [pending, key, runtime, options.delayMs]);
+  const done = useCallback(() => {
+    setGreeted({ key, done: true });
+    void Promise.resolve(storage.setItem(key, "1")).catch(() => void 0);
+  }, [storage, key]);
+  const open = useCallback(() => {
+    done();
+    runtime.emit({ type: "launcher_opened" });
+    onOpen();
+  }, [done, runtime, onOpen]);
+  const dismiss = useCallback(() => {
+    done();
+    runtime.emit({ type: "greeting_closed" });
+  }, [done, runtime]);
+  useEffect(() => {
+    if (shows) runtime.emit({ type: "launcher_shown" });
+  }, [shows, runtime]);
+  return { shows, greets: pending && due === key, open, dismiss };
+}
+
+export { AgentRuntimeProvider, forgetGreeting, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus, useAgentStatusState };
+//# sourceMappingURL=chunk-V4UBOVTK.js.map
+//# sourceMappingURL=chunk-V4UBOVTK.js.map

package/dist/chunk-V4UBOVTK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent.tsx"],"names":[],"mappings":"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","file":"chunk-V4UBOVTK.js","sourcesContent":["// React bindings of the agent runtime (@vinaverse/client/agent): a provider and hooks, thin by design. The runtime holds\n// every rule; these subscribe, show a conversation while a component is mounted, and read the launcher's state. No\n// react-native or DOM import.\nimport type {\n  AgentConversation,\n  AgentConversationState,\n  AgentKey,\n  AgentPlace,\n  AgentRuntime,\n  AgentStatus,\n  AgentStatusState,\n} from '@vinaverse/client/agent';\nimport { agentKey, greetedKey } from '@vinaverse/client/agent';\nimport {\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\n\nconst RuntimeContext = /* @__PURE__ */ createContext<AgentRuntime | null>(null);\n\n/** The app's agent runtime, made once (module level, or memoized) and given to everything below. */\nexport function AgentRuntimeProvider(props: {\n  readonly runtime: AgentRuntime;\n  readonly children?: ReactNode;\n}): ReactNode {\n  return (\n    <RuntimeContext.Provider value={props.runtime}>\n      {props.children}\n    </RuntimeContext.Provider>\n  );\n}\n\nexport function useAgentRuntime(): AgentRuntime {\n  const runtime = useContext(RuntimeContext);\n  if (!runtime)\n    throw new Error('Agent hooks render inside <AgentRuntimeProvider>.');\n  return runtime;\n}\n\nexport interface UseAgentConversation {\n  readonly conversation: AgentConversation;\n  readonly state: AgentConversationState;\n  /** A new conversation for this key (the old one let go and forgotten). */\n  readonly startNew: () => void;\n}\n\n/**\n * The key's conversation, shown while the component is mounted (kept across screens; released when it unmounts), told\n * the place and the way in as they change. A start over or its end hands the component the key's next conversation.\n */\nexport function useAgentConversation(\n  key: AgentKey,\n  open: {\n    readonly place?: AgentPlace | null;\n    readonly entryPoint?: string | null;\n  } = {},\n): UseAgentConversation {\n  const runtime = useAgentRuntime();\n  const keyRef = useRef(key);\n  keyRef.current = key;\n  const k = agentKey(key);\n  // biome-ignore lint/correctness/useExhaustiveDependencies: the key's string reads it again when the key changes\n  const read = useCallback(() => runtime.peek(keyRef.current), [runtime, k]);\n  const conversation = useSyncExternalStore(runtime.subscribe, read, read);\n  const openRef = useRef(open);\n  openRef.current = open;\n  // Layout effects: they run before any passive effect, a child's included, so a chat below that starts the\n  // conversation early (`VinaverseChat`) finds it shown and told the place.\n  useLayoutEffect(() => conversation.show(openRef.current), [conversation]);\n  const { place, entryPoint } = open;\n  const screen = place?.screen;\n  const entityType = place?.entity?.type;\n  const entityId = place?.entity?.id;\n  const filters = place?.filters ? JSON.stringify(place.filters) : null;\n  const cleared = place === null;\n  // biome-ignore lint/correctness/useExhaustiveDependencies: told by value, so a place made again each render is the same\n  useLayoutEffect(() => {\n    conversation.tell(openRef.current);\n  }, [\n    conversation,\n    screen,\n    entityType,\n    entityId,\n    filters,\n    cleared,\n    entryPoint,\n  ]);\n  const state = useSyncExternalStore(\n    conversation.subscribe,\n    conversation.getState,\n    conversation.getState,\n  );\n  const startNew = useCallback(\n    () => runtime.startNew(keyRef.current),\n    [runtime],\n  );\n  return { conversation, state, startNew };\n}\n\n/** The agent's status (read once, then at most every few minutes); null until the first read. */\nexport function useAgentStatus(): AgentStatus | null {\n  const runtime = useAgentRuntime();\n  useEffect(() => {\n    runtime.status().catch(() => undefined); // an unread status is no agent: the launcher stays hidden\n  }, [runtime]);\n  return useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getStatus,\n    runtime.getStatus,\n  );\n}\n\n/**\n * The status with where its read stands (`{ status, reading, failed }`): a screen tells \"still reading\" from \"could\n * not read\" and draws each its own way. Reads the status, as `useAgentStatus` does.\n */\nexport function useAgentStatusState(): AgentStatusState {\n  const runtime = useAgentRuntime();\n  useEffect(() => {\n    runtime.status().catch(() => undefined); // said through `failed`\n  }, [runtime]);\n  return useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getStatusState,\n    runtime.getStatusState,\n  );\n}\n\n/** The agent's name: the newest session's, else the status's, else `fallback`. */\nexport function useAgentName(fallback: string): string {\n  const runtime = useAgentRuntime();\n  return (\n    useSyncExternalStore(runtime.subscribe, runtime.getName, runtime.getName) ??\n    fallback\n  );\n}\n\n/** What the agent can do, from the status (all off until it is read, and when the agent is off). */\nexport function useAgentFeatures(): AgentStatus['features'] & {\n  readonly available: boolean;\n  readonly launcher: boolean;\n} {\n  const status = useAgentStatus();\n  return {\n    available: status?.available === true,\n    launcher: status?.launcher === true,\n    history: status?.features.history === true,\n    memory: status?.features.memory === true,\n    businessAgent: status?.features.businessAgent === true,\n    businessSetup: status?.features.businessSetup === true,\n  };\n}\n\n/** The agent as an entry shows it before any session: its name (`fallback` until known) and avatar. */\nexport function useAgentProfile(fallback: string): {\n  readonly name: string;\n  readonly avatarUrl: string | null;\n} {\n  const status = useAgentStatus();\n  return { name: useAgentName(fallback), avatarUrl: status?.avatarUrl ?? null };\n}\n\n/**\n * Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). A\n * sign-out keeps it on purpose (a person is not greeted again after signing back in). Given to the runtime as\n * `greetingStorage`, `runtime.erase()` erases it; `forgetGreeting` is the low-level helper for a storage of the app's.\n */\nexport interface GreetingStorage {\n  getItem(key: string): string | null | Promise<string | null>;\n  setItem(key: string, value: string): void | Promise<void>;\n  /** Erasure removes the record, never leaves a key that names the person. */\n  removeItem(key: string): void | Promise<void>;\n}\n\n/** Where the greeting is remembered, per person and mode: the default the storage sees, unless the app maps its own. */\nexport { greetedKey };\n\n/** Removes the launcher's record of greeting this person in these modes (`runtime.erase()` does it for `greetingStorage`). */\nexport async function forgetGreeting(\n  storage: GreetingStorage,\n  subject: string | null,\n  modes: readonly string[],\n  storageKey: (subject: string | null, mode: string) => string = greetedKey,\n): Promise<void> {\n  for (const mode of modes) await storage.removeItem(storageKey(subject, mode));\n}\n\nconst MEMORY = new Map<string, string>();\nconst memory: GreetingStorage = {\n  getItem: (k) => MEMORY.get(k) ?? null,\n  setItem: (k, v) => void MEMORY.set(k, v),\n  removeItem: (k) => void MEMORY.delete(k),\n};\n\nexport interface UseAgentLauncher {\n  /** The status offers the launcher, and the app shows it here. */\n  readonly shows: boolean;\n  /** Its greeting bubble: once per person and mode, a moment after the launcher shows. */\n  readonly greets: boolean;\n  /** The person opens the agent (the greeting is done too). */\n  readonly open: () => void;\n  /** The person closes the greeting. */\n  readonly dismiss: () => void;\n}\n\n/** The floating launcher's state: whether it shows and greets, and its two actions. */\nexport function useAgentLauncher(options: {\n  readonly subject: string | null;\n  readonly mode: string;\n  /** The app's own rule (the tabs it shows on, no keyboard up…); default true. */\n  readonly visible?: boolean;\n  readonly storage?: GreetingStorage;\n  /** The storage's key for a person and mode, to reuse a record the app already keeps. Default `greetedKey`. */\n  readonly storageKey?: (subject: string | null, mode: string) => string;\n  /** How long after showing the greeting appears. Default 1200 ms. */\n  readonly delayMs?: number;\n  readonly onOpen: () => void;\n}): UseAgentLauncher {\n  const runtime = useAgentRuntime();\n  const status = useAgentStatus();\n  const { subject, mode, onOpen } = options;\n  // The app's own store, else the runtime's (`greetingStorage`: fenced by a sign-out, reached by `erase()`).\n  const storage = options.storage ?? runtime.greetings ?? memory;\n  const shows = status?.launcher === true && options.visible !== false;\n  const key = (options.storageKey ?? greetedKey)(subject, mode);\n  const [greeted, setGreeted] = useState<{ key: string; done: boolean } | null>(\n    null,\n  );\n  const [due, setDue] = useState<string | null>(null);\n  useEffect(() => {\n    let live = true;\n    Promise.resolve(storage.getItem(key)).then(\n      (value) => {\n        if (live) setGreeted({ key, done: value === '1' });\n      },\n      () => {\n        if (live) setGreeted({ key, done: false });\n      },\n    );\n    return () => {\n      live = false;\n    };\n  }, [storage, key]);\n  const pending = shows && greeted?.key === key && !greeted.done;\n  useEffect(() => {\n    if (!pending) return;\n    const timer = setTimeout(() => {\n      setDue(key);\n      runtime.emit({ type: 'launcher_greeted' });\n    }, options.delayMs ?? 1200);\n    return () => clearTimeout(timer);\n  }, [pending, key, runtime, options.delayMs]);\n  const done = useCallback(() => {\n    setGreeted({ key, done: true });\n    void Promise.resolve(storage.setItem(key, '1')).catch(() => undefined);\n  }, [storage, key]);\n  const open = useCallback(() => {\n    done();\n    runtime.emit({ type: 'launcher_opened' });\n    onOpen();\n  }, [done, runtime, onOpen]);\n  const dismiss = useCallback(() => {\n    done();\n    runtime.emit({ type: 'greeting_closed' });\n  }, [done, runtime]);\n  useEffect(() => {\n    if (shows) runtime.emit({ type: 'launcher_shown' });\n  }, [shows, runtime]);\n  return { shows, greets: pending && due === key, open, dismiss };\n}\n"]}

package/dist/history.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+var history = require('@vinaverse/client/history');
+var react = require('react');
+require('@vinaverse/client/agent');
+require('react/jsx-runtime');
+
+// src/history.tsx
+var RuntimeContext = /* @__PURE__ */ react.createContext(null);
+function useAgentRuntime() {
+  const runtime = react.useContext(RuntimeContext);
+  if (!runtime)
+    throw new Error("Agent hooks render inside <AgentRuntimeProvider>.");
+  return runtime;
+}
+
+// src/history.tsx
+function useAgentHistory(options) {
+  const runtime = useAgentRuntime();
+  const { subject, mode, thread, pageSize } = options;
+  const scope = options.scope ?? null;
+  const agent = options.agent ?? null;
+  const history$1 = react.useMemo(
+    () => history.createAgentHistory({
+      runtime,
+      mode,
+      scope,
+      agent,
+      ...pageSize === void 0 ? {} : { pageSize }
+    }),
+    [runtime, mode, scope, agent, pageSize]
+  );
+  const state = react.useSyncExternalStore(
+    history$1.subscribe,
+    history$1.getSnapshot,
+    history$1.getSnapshot
+  );
+  react.useEffect(() => {
+    if (!state.started) history$1.refresh();
+  }, [history$1, state.started]);
+  const keyOf = react.useCallback(
+    (conversation) => history.continueKey(conversation, subject, thread),
+    [subject, thread]
+  );
+  return {
+    state,
+    refresh: history$1.refresh,
+    loadMore: history$1.loadMore,
+    retry: history$1.retry,
+    keyOf,
+    remove: react.useCallback(
+      (conversation) => history$1.remove(keyOf(conversation), conversation.id),
+      [history$1, keyOf]
+    ),
+    continue: react.useCallback(
+      (conversation) => runtime.continue(keyOf(conversation), conversation.id),
+      [runtime, keyOf]
+    )
+  };
+}
+function useAgentTranscript(conversationId, options = {}) {
+  const runtime = useAgentRuntime();
+  const { pageSize } = options;
+  const transcript = react.useMemo(
+    () => history.createAgentTranscript({
+      runtime,
+      conversationId,
+      ...pageSize === void 0 ? {} : { pageSize }
+    }),
+    [runtime, conversationId, pageSize]
+  );
+  const state = react.useSyncExternalStore(
+    transcript.subscribe,
+    transcript.getSnapshot,
+    transcript.getSnapshot
+  );
+  react.useEffect(() => {
+    if (!state.started) transcript.load();
+  }, [transcript, state.started]);
+  return {
+    state,
+    load: transcript.load,
+    loadEarlier: transcript.loadEarlier,
+    retry: transcript.retry
+  };
+}
+
+exports.useAgentHistory = useAgentHistory;
+exports.useAgentTranscript = useAgentTranscript;
+//# sourceMappingURL=history.cjs.map
+//# sourceMappingURL=history.cjs.map

package/dist/history.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent.tsx","../src/history.tsx"],"names":["useContext","history","useMemo","createAgentHistory","useSyncExternalStore","useEffect","useCallback","continueKey","createAgentTranscript"],"mappings":"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","file":"history.cjs","sourcesContent":["// React bindings of the agent runtime (@vinaverse/client/agent): a provider and hooks, thin by design. The runtime holds\n// every rule; these subscribe, show a conversation while a component is mounted, and read the launcher's state. No\n// react-native or DOM import.\nimport type {\n  AgentConversation,\n  AgentConversationState,\n  AgentKey,\n  AgentPlace,\n  AgentRuntime,\n  AgentStatus,\n  AgentStatusState,\n} from '@vinaverse/client/agent';\nimport { agentKey, greetedKey } from '@vinaverse/client/agent';\nimport {\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\n\nconst RuntimeContext = /* @__PURE__ */ createContext<AgentRuntime | null>(null);\n\n/** The app's agent runtime, made once (module level, or memoized) and given to everything below. */\nexport function AgentRuntimeProvider(props: {\n  readonly runtime: AgentRuntime;\n  readonly children?: ReactNode;\n}): ReactNode {\n  return (\n    <RuntimeContext.Provider value={props.runtime}>\n      {props.children}\n    </RuntimeContext.Provider>\n  );\n}\n\nexport function useAgentRuntime(): AgentRuntime {\n  const runtime = useContext(RuntimeContext);\n  if (!runtime)\n    throw new Error('Agent hooks render inside <AgentRuntimeProvider>.');\n  return runtime;\n}\n\nexport interface UseAgentConversation {\n  readonly conversation: AgentConversation;\n  readonly state: AgentConversationState;\n  /** A new conversation for this key (the old one let go and forgotten). */\n  readonly startNew: () => void;\n}\n\n/**\n * The key's conversation, shown while the component is mounted (kept across screens; released when it unmounts), told\n * the place and the way in as they change. A start over or its end hands the component the key's next conversation.\n */\nexport function useAgentConversation(\n  key: AgentKey,\n  open: {\n    readonly place?: AgentPlace | null;\n    readonly entryPoint?: string | null;\n  } = {},\n): UseAgentConversation {\n  const runtime = useAgentRuntime();\n  const keyRef = useRef(key);\n  keyRef.current = key;\n  const k = agentKey(key);\n  // biome-ignore lint/correctness/useExhaustiveDependencies: the key's string reads it again when the key changes\n  const read = useCallback(() => runtime.peek(keyRef.current), [runtime, k]);\n  const conversation = useSyncExternalStore(runtime.subscribe, read, read);\n  const openRef = useRef(open);\n  openRef.current = open;\n  // Layout effects: they run before any passive effect, a child's included, so a chat below that starts the\n  // conversation early (`VinaverseChat`) finds it shown and told the place.\n  useLayoutEffect(() => conversation.show(openRef.current), [conversation]);\n  const { place, entryPoint } = open;\n  const screen = place?.screen;\n  const entityType = place?.entity?.type;\n  const entityId = place?.entity?.id;\n  const filters = place?.filters ? JSON.stringify(place.filters) : null;\n  const cleared = place === null;\n  // biome-ignore lint/correctness/useExhaustiveDependencies: told by value, so a place made again each render is the same\n  useLayoutEffect(() => {\n    conversation.tell(openRef.current);\n  }, [\n    conversation,\n    screen,\n    entityType,\n    entityId,\n    filters,\n    cleared,\n    entryPoint,\n  ]);\n  const state = useSyncExternalStore(\n    conversation.subscribe,\n    conversation.getState,\n    conversation.getState,\n  );\n  const startNew = useCallback(\n    () => runtime.startNew(keyRef.current),\n    [runtime],\n  );\n  return { conversation, state, startNew };\n}\n\n/** The agent's status (read once, then at most every few minutes); null until the first read. */\nexport function useAgentStatus(): AgentStatus | null {\n  const runtime = useAgentRuntime();\n  useEffect(() => {\n    runtime.status().catch(() => undefined); // an unread status is no agent: the launcher stays hidden\n  }, [runtime]);\n  return useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getStatus,\n    runtime.getStatus,\n  );\n}\n\n/**\n * The status with where its read stands (`{ status, reading, failed }`): a screen tells \"still reading\" from \"could\n * not read\" and draws each its own way. Reads the status, as `useAgentStatus` does.\n */\nexport function useAgentStatusState(): AgentStatusState {\n  const runtime = useAgentRuntime();\n  useEffect(() => {\n    runtime.status().catch(() => undefined); // said through `failed`\n  }, [runtime]);\n  return useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getStatusState,\n    runtime.getStatusState,\n  );\n}\n\n/** The agent's name: the newest session's, else the status's, else `fallback`. */\nexport function useAgentName(fallback: string): string {\n  const runtime = useAgentRuntime();\n  return (\n    useSyncExternalStore(runtime.subscribe, runtime.getName, runtime.getName) ??\n    fallback\n  );\n}\n\n/** What the agent can do, from the status (all off until it is read, and when the agent is off). */\nexport function useAgentFeatures(): AgentStatus['features'] & {\n  readonly available: boolean;\n  readonly launcher: boolean;\n} {\n  const status = useAgentStatus();\n  return {\n    available: status?.available === true,\n    launcher: status?.launcher === true,\n    history: status?.features.history === true,\n    memory: status?.features.memory === true,\n    businessAgent: status?.features.businessAgent === true,\n    businessSetup: status?.features.businessSetup === true,\n  };\n}\n\n/** The agent as an entry shows it before any session: its name (`fallback` until known) and avatar. */\nexport function useAgentProfile(fallback: string): {\n  readonly name: string;\n  readonly avatarUrl: string | null;\n} {\n  const status = useAgentStatus();\n  return { name: useAgentName(fallback), avatarUrl: status?.avatarUrl ?? null };\n}\n\n/**\n * Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). A\n * sign-out keeps it on purpose (a person is not greeted again after signing back in). Given to the runtime as\n * `greetingStorage`, `runtime.erase()` erases it; `forgetGreeting` is the low-level helper for a storage of the app's.\n */\nexport interface GreetingStorage {\n  getItem(key: string): string | null | Promise<string | null>;\n  setItem(key: string, value: string): void | Promise<void>;\n  /** Erasure removes the record, never leaves a key that names the person. */\n  removeItem(key: string): void | Promise<void>;\n}\n\n/** Where the greeting is remembered, per person and mode: the default the storage sees, unless the app maps its own. */\nexport { greetedKey };\n\n/** Removes the launcher's record of greeting this person in these modes (`runtime.erase()` does it for `greetingStorage`). */\nexport async function forgetGreeting(\n  storage: GreetingStorage,\n  subject: string | null,\n  modes: readonly string[],\n  storageKey: (subject: string | null, mode: string) => string = greetedKey,\n): Promise<void> {\n  for (const mode of modes) await storage.removeItem(storageKey(subject, mode));\n}\n\nconst MEMORY = new Map<string, string>();\nconst memory: GreetingStorage = {\n  getItem: (k) => MEMORY.get(k) ?? null,\n  setItem: (k, v) => void MEMORY.set(k, v),\n  removeItem: (k) => void MEMORY.delete(k),\n};\n\nexport interface UseAgentLauncher {\n  /** The status offers the launcher, and the app shows it here. */\n  readonly shows: boolean;\n  /** Its greeting bubble: once per person and mode, a moment after the launcher shows. */\n  readonly greets: boolean;\n  /** The person opens the agent (the greeting is done too). */\n  readonly open: () => void;\n  /** The person closes the greeting. */\n  readonly dismiss: () => void;\n}\n\n/** The floating launcher's state: whether it shows and greets, and its two actions. */\nexport function useAgentLauncher(options: {\n  readonly subject: string | null;\n  readonly mode: string;\n  /** The app's own rule (the tabs it shows on, no keyboard up…); default true. */\n  readonly visible?: boolean;\n  readonly storage?: GreetingStorage;\n  /** The storage's key for a person and mode, to reuse a record the app already keeps. Default `greetedKey`. */\n  readonly storageKey?: (subject: string | null, mode: string) => string;\n  /** How long after showing the greeting appears. Default 1200 ms. */\n  readonly delayMs?: number;\n  readonly onOpen: () => void;\n}): UseAgentLauncher {\n  const runtime = useAgentRuntime();\n  const status = useAgentStatus();\n  const { subject, mode, onOpen } = options;\n  // The app's own store, else the runtime's (`greetingStorage`: fenced by a sign-out, reached by `erase()`).\n  const storage = options.storage ?? runtime.greetings ?? memory;\n  const shows = status?.launcher === true && options.visible !== false;\n  const key = (options.storageKey ?? greetedKey)(subject, mode);\n  const [greeted, setGreeted] = useState<{ key: string; done: boolean } | null>(\n    null,\n  );\n  const [due, setDue] = useState<string | null>(null);\n  useEffect(() => {\n    let live = true;\n    Promise.resolve(storage.getItem(key)).then(\n      (value) => {\n        if (live) setGreeted({ key, done: value === '1' });\n      },\n      () => {\n        if (live) setGreeted({ key, done: false });\n      },\n    );\n    return () => {\n      live = false;\n    };\n  }, [storage, key]);\n  const pending = shows && greeted?.key === key && !greeted.done;\n  useEffect(() => {\n    if (!pending) return;\n    const timer = setTimeout(() => {\n      setDue(key);\n      runtime.emit({ type: 'launcher_greeted' });\n    }, options.delayMs ?? 1200);\n    return () => clearTimeout(timer);\n  }, [pending, key, runtime, options.delayMs]);\n  const done = useCallback(() => {\n    setGreeted({ key, done: true });\n    void Promise.resolve(storage.setItem(key, '1')).catch(() => undefined);\n  }, [storage, key]);\n  const open = useCallback(() => {\n    done();\n    runtime.emit({ type: 'launcher_opened' });\n    onOpen();\n  }, [done, runtime, onOpen]);\n  const dismiss = useCallback(() => {\n    done();\n    runtime.emit({ type: 'greeting_closed' });\n  }, [done, runtime]);\n  useEffect(() => {\n    if (shows) runtime.emit({ type: 'launcher_shown' });\n  }, [shows, runtime]);\n  return { shows, greets: pending && due === key, open, dismiss };\n}\n","// React bindings of a person's history (@vinaverse/client/history): the list of their past conversations and one\n// read back, each a store subscribed to while a component is mounted; delete and continue through the runtime. An\n// entry of its own, so an app that draws no history ships none of it. No react-native or DOM import.\nimport type { AgentConversation, AgentKey } from '@vinaverse/client/agent';\nimport {\n  type AgentHistory,\n  type AgentHistoryState,\n  type AgentTranscript,\n  type AgentTranscriptState,\n  type ConversationSummary,\n  continueKey,\n  createAgentHistory,\n  createAgentTranscript,\n} from '@vinaverse/client/history';\nimport { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';\nimport { useAgentRuntime } from './agent.js';\n\nexport interface UseAgentHistoryOptions {\n  /** The person signed in (null for a guest): the key a conversation continues or is deleted under. */\n  readonly subject: string | null;\n  /** The app's side: `customer` or `business`. */\n  readonly mode: string;\n  /** The business acted for, with `business`. */\n  readonly scope?: string | null;\n  /** The agent, for a backend that serves more than one. */\n  readonly agent?: string | null;\n  /** The thread a continued conversation runs in; default `chat`. */\n  readonly thread?: string;\n  /** Conversations per page (1–50). Default 20. */\n  readonly pageSize?: number;\n}\n\nexport interface UseAgentHistory {\n  readonly state: AgentHistoryState;\n  /** Reads the first page anew (after a failure, or to see what changed). */\n  readonly refresh: () => void;\n  /** The next older page, when there is one and none is being read. */\n  readonly loadMore: () => void;\n  /** Reads again the page that failed: the first, or the next. */\n  readonly retry: () => void;\n  /** The key the conversation continues under for this person (`continueKey`). */\n  readonly keyOf: (conversation: ConversationSummary) => AgentKey;\n  /**\n   * Deletes the conversation at the backend and drops its row; the device forgets it only where its key still\n   * continues it. One already gone is dropped too; any other failure is thrown, the row kept.\n   */\n  readonly remove: (conversation: ConversationSummary) => Promise<void>;\n  /**\n   * The person goes on with a past conversation: pinned for its key and opened through the backend's resume when the\n   * app shows it (`AgentChat` with `keyOf(conversation)`, or `show()` on what this returns).\n   */\n  readonly continue: (conversation: ConversationSummary) => AgentConversation;\n}\n\n/** The person's past conversations, read as the component mounts, newest activity first. */\nexport function useAgentHistory(\n  options: UseAgentHistoryOptions,\n): UseAgentHistory {\n  const runtime = useAgentRuntime();\n  const { subject, mode, thread, pageSize } = options;\n  const scope = options.scope ?? null;\n  const agent = options.agent ?? null;\n  const history = useMemo<AgentHistory>(\n    () =>\n      createAgentHistory({\n        runtime,\n        mode,\n        scope,\n        agent,\n        ...(pageSize === undefined ? {} : { pageSize }),\n      }),\n    [runtime, mode, scope, agent, pageSize],\n  );\n  const state = useSyncExternalStore(\n    history.subscribe,\n    history.getSnapshot,\n    history.getSnapshot,\n  );\n  useEffect(() => {\n    if (!state.started) history.refresh();\n  }, [history, state.started]);\n  const keyOf = useCallback(\n    (conversation: ConversationSummary) =>\n      continueKey(conversation, subject, thread),\n    [subject, thread],\n  );\n  return {\n    state,\n    refresh: history.refresh,\n    loadMore: history.loadMore,\n    retry: history.retry,\n    keyOf,\n    remove: useCallback(\n      (conversation: ConversationSummary) =>\n        history.remove(keyOf(conversation), conversation.id),\n      [history, keyOf],\n    ),\n    continue: useCallback(\n      (conversation: ConversationSummary) =>\n        runtime.continue(keyOf(conversation), conversation.id),\n      [runtime, keyOf],\n    ),\n  };\n}\n\nexport interface UseAgentTranscript {\n  readonly state: AgentTranscriptState;\n  /** Reads the newest page anew. */\n  readonly load: () => void;\n  /** The page before the earliest read, prepended. */\n  readonly loadEarlier: () => void;\n  /** Reads again the page that failed: the newest, or the earlier one. */\n  readonly retry: () => void;\n}\n\n/** A past conversation read back, newest page first, as the component mounts. */\nexport function useAgentTranscript(\n  conversationId: string,\n  options: { readonly pageSize?: number } = {},\n): UseAgentTranscript {\n  const runtime = useAgentRuntime();\n  const { pageSize } = options;\n  const transcript = useMemo<AgentTranscript>(\n    () =>\n      createAgentTranscript({\n        runtime,\n        conversationId,\n        ...(pageSize === undefined ? {} : { pageSize }),\n      }),\n    [runtime, conversationId, pageSize],\n  );\n  const state = useSyncExternalStore(\n    transcript.subscribe,\n    transcript.getSnapshot,\n    transcript.getSnapshot,\n  );\n  useEffect(() => {\n    if (!state.started) transcript.load();\n  }, [transcript, state.started]);\n  return {\n    state,\n    load: transcript.load,\n    loadEarlier: transcript.loadEarlier,\n    retry: transcript.retry,\n  };\n}\n"]}

package/dist/history.d.cts

@@ -0,0 +1,55 @@
+import { AgentKey, AgentConversation } from '@vinaverse/client/agent';
+import { AgentHistoryState, ConversationSummary, AgentTranscriptState } from '@vinaverse/client/history';
+
+interface UseAgentHistoryOptions {
+    /** The person signed in (null for a guest): the key a conversation continues or is deleted under. */
+    readonly subject: string | null;
+    /** The app's side: `customer` or `business`. */
+    readonly mode: string;
+    /** The business acted for, with `business`. */
+    readonly scope?: string | null;
+    /** The agent, for a backend that serves more than one. */
+    readonly agent?: string | null;
+    /** The thread a continued conversation runs in; default `chat`. */
+    readonly thread?: string;
+    /** Conversations per page (1–50). Default 20. */
+    readonly pageSize?: number;
+}
+interface UseAgentHistory {
+    readonly state: AgentHistoryState;
+    /** Reads the first page anew (after a failure, or to see what changed). */
+    readonly refresh: () => void;
+    /** The next older page, when there is one and none is being read. */
+    readonly loadMore: () => void;
+    /** Reads again the page that failed: the first, or the next. */
+    readonly retry: () => void;
+    /** The key the conversation continues under for this person (`continueKey`). */
+    readonly keyOf: (conversation: ConversationSummary) => AgentKey;
+    /**
+     * Deletes the conversation at the backend and drops its row; the device forgets it only where its key still
+     * continues it. One already gone is dropped too; any other failure is thrown, the row kept.
+     */
+    readonly remove: (conversation: ConversationSummary) => Promise<void>;
+    /**
+     * The person goes on with a past conversation: pinned for its key and opened through the backend's resume when the
+     * app shows it (`AgentChat` with `keyOf(conversation)`, or `show()` on what this returns).
+     */
+    readonly continue: (conversation: ConversationSummary) => AgentConversation;
+}
+/** The person's past conversations, read as the component mounts, newest activity first. */
+declare function useAgentHistory(options: UseAgentHistoryOptions): UseAgentHistory;
+interface UseAgentTranscript {
+    readonly state: AgentTranscriptState;
+    /** Reads the newest page anew. */
+    readonly load: () => void;
+    /** The page before the earliest read, prepended. */
+    readonly loadEarlier: () => void;
+    /** Reads again the page that failed: the newest, or the earlier one. */
+    readonly retry: () => void;
+}
+/** A past conversation read back, newest page first, as the component mounts. */
+declare function useAgentTranscript(conversationId: string, options?: {
+    readonly pageSize?: number;
+}): UseAgentTranscript;
+
+export { type UseAgentHistory, type UseAgentHistoryOptions, type UseAgentTranscript, useAgentHistory, useAgentTranscript };

package/dist/history.d.ts

@@ -0,0 +1,55 @@
+import { AgentKey, AgentConversation } from '@vinaverse/client/agent';
+import { AgentHistoryState, ConversationSummary, AgentTranscriptState } from '@vinaverse/client/history';
+
+interface UseAgentHistoryOptions {
+    /** The person signed in (null for a guest): the key a conversation continues or is deleted under. */
+    readonly subject: string | null;
+    /** The app's side: `customer` or `business`. */
+    readonly mode: string;
+    /** The business acted for, with `business`. */
+    readonly scope?: string | null;
+    /** The agent, for a backend that serves more than one. */
+    readonly agent?: string | null;
+    /** The thread a continued conversation runs in; default `chat`. */
+    readonly thread?: string;
+    /** Conversations per page (1–50). Default 20. */
+    readonly pageSize?: number;
+}
+interface UseAgentHistory {
+    readonly state: AgentHistoryState;
+    /** Reads the first page anew (after a failure, or to see what changed). */
+    readonly refresh: () => void;
+    /** The next older page, when there is one and none is being read. */
+    readonly loadMore: () => void;
+    /** Reads again the page that failed: the first, or the next. */
+    readonly retry: () => void;
+    /** The key the conversation continues under for this person (`continueKey`). */
+    readonly keyOf: (conversation: ConversationSummary) => AgentKey;
+    /**
+     * Deletes the conversation at the backend and drops its row; the device forgets it only where its key still
+     * continues it. One already gone is dropped too; any other failure is thrown, the row kept.
+     */
+    readonly remove: (conversation: ConversationSummary) => Promise<void>;
+    /**
+     * The person goes on with a past conversation: pinned for its key and opened through the backend's resume when the
+     * app shows it (`AgentChat` with `keyOf(conversation)`, or `show()` on what this returns).
+     */
+    readonly continue: (conversation: ConversationSummary) => AgentConversation;
+}
+/** The person's past conversations, read as the component mounts, newest activity first. */
+declare function useAgentHistory(options: UseAgentHistoryOptions): UseAgentHistory;
+interface UseAgentTranscript {
+    readonly state: AgentTranscriptState;
+    /** Reads the newest page anew. */
+    readonly load: () => void;
+    /** The page before the earliest read, prepended. */
+    readonly loadEarlier: () => void;
+    /** Reads again the page that failed: the newest, or the earlier one. */
+    readonly retry: () => void;
+}
+/** A past conversation read back, newest page first, as the component mounts. */
+declare function useAgentTranscript(conversationId: string, options?: {
+    readonly pageSize?: number;
+}): UseAgentTranscript;
+
+export { type UseAgentHistory, type UseAgentHistoryOptions, type UseAgentTranscript, useAgentHistory, useAgentTranscript };

package/dist/history.js

@@ -0,0 +1,77 @@
+import { useAgentRuntime } from './chunk-V4UBOVTK.js';
+import { createAgentHistory, continueKey, createAgentTranscript } from '@vinaverse/client/history';
+import { useMemo, useSyncExternalStore, useEffect, useCallback } from 'react';
+
+function useAgentHistory(options) {
+  const runtime = useAgentRuntime();
+  const { subject, mode, thread, pageSize } = options;
+  const scope = options.scope ?? null;
+  const agent = options.agent ?? null;
+  const history = useMemo(
+    () => createAgentHistory({
+      runtime,
+      mode,
+      scope,
+      agent,
+      ...pageSize === void 0 ? {} : { pageSize }
+    }),
+    [runtime, mode, scope, agent, pageSize]
+  );
+  const state = useSyncExternalStore(
+    history.subscribe,
+    history.getSnapshot,
+    history.getSnapshot
+  );
+  useEffect(() => {
+    if (!state.started) history.refresh();
+  }, [history, state.started]);
+  const keyOf = useCallback(
+    (conversation) => continueKey(conversation, subject, thread),
+    [subject, thread]
+  );
+  return {
+    state,
+    refresh: history.refresh,
+    loadMore: history.loadMore,
+    retry: history.retry,
+    keyOf,
+    remove: useCallback(
+      (conversation) => history.remove(keyOf(conversation), conversation.id),
+      [history, keyOf]
+    ),
+    continue: useCallback(
+      (conversation) => runtime.continue(keyOf(conversation), conversation.id),
+      [runtime, keyOf]
+    )
+  };
+}
+function useAgentTranscript(conversationId, options = {}) {
+  const runtime = useAgentRuntime();
+  const { pageSize } = options;
+  const transcript = useMemo(
+    () => createAgentTranscript({
+      runtime,
+      conversationId,
+      ...pageSize === void 0 ? {} : { pageSize }
+    }),
+    [runtime, conversationId, pageSize]
+  );
+  const state = useSyncExternalStore(
+    transcript.subscribe,
+    transcript.getSnapshot,
+    transcript.getSnapshot
+  );
+  useEffect(() => {
+    if (!state.started) transcript.load();
+  }, [transcript, state.started]);
+  return {
+    state,
+    load: transcript.load,
+    loadEarlier: transcript.loadEarlier,
+    retry: transcript.retry
+  };
+}
+
+export { useAgentHistory, useAgentTranscript };
+//# sourceMappingURL=history.js.map
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/history.tsx"],"names":[],"mappings":"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","file":"history.js","sourcesContent":["// React bindings of a person's history (@vinaverse/client/history): the list of their past conversations and one\n// read back, each a store subscribed to while a component is mounted; delete and continue through the runtime. An\n// entry of its own, so an app that draws no history ships none of it. No react-native or DOM import.\nimport type { AgentConversation, AgentKey } from '@vinaverse/client/agent';\nimport {\n  type AgentHistory,\n  type AgentHistoryState,\n  type AgentTranscript,\n  type AgentTranscriptState,\n  type ConversationSummary,\n  continueKey,\n  createAgentHistory,\n  createAgentTranscript,\n} from '@vinaverse/client/history';\nimport { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';\nimport { useAgentRuntime } from './agent.js';\n\nexport interface UseAgentHistoryOptions {\n  /** The person signed in (null for a guest): the key a conversation continues or is deleted under. */\n  readonly subject: string | null;\n  /** The app's side: `customer` or `business`. */\n  readonly mode: string;\n  /** The business acted for, with `business`. */\n  readonly scope?: string | null;\n  /** The agent, for a backend that serves more than one. */\n  readonly agent?: string | null;\n  /** The thread a continued conversation runs in; default `chat`. */\n  readonly thread?: string;\n  /** Conversations per page (1–50). Default 20. */\n  readonly pageSize?: number;\n}\n\nexport interface UseAgentHistory {\n  readonly state: AgentHistoryState;\n  /** Reads the first page anew (after a failure, or to see what changed). */\n  readonly refresh: () => void;\n  /** The next older page, when there is one and none is being read. */\n  readonly loadMore: () => void;\n  /** Reads again the page that failed: the first, or the next. */\n  readonly retry: () => void;\n  /** The key the conversation continues under for this person (`continueKey`). */\n  readonly keyOf: (conversation: ConversationSummary) => AgentKey;\n  /**\n   * Deletes the conversation at the backend and drops its row; the device forgets it only where its key still\n   * continues it. One already gone is dropped too; any other failure is thrown, the row kept.\n   */\n  readonly remove: (conversation: ConversationSummary) => Promise<void>;\n  /**\n   * The person goes on with a past conversation: pinned for its key and opened through the backend's resume when the\n   * app shows it (`AgentChat` with `keyOf(conversation)`, or `show()` on what this returns).\n   */\n  readonly continue: (conversation: ConversationSummary) => AgentConversation;\n}\n\n/** The person's past conversations, read as the component mounts, newest activity first. */\nexport function useAgentHistory(\n  options: UseAgentHistoryOptions,\n): UseAgentHistory {\n  const runtime = useAgentRuntime();\n  const { subject, mode, thread, pageSize } = options;\n  const scope = options.scope ?? null;\n  const agent = options.agent ?? null;\n  const history = useMemo<AgentHistory>(\n    () =>\n      createAgentHistory({\n        runtime,\n        mode,\n        scope,\n        agent,\n        ...(pageSize === undefined ? {} : { pageSize }),\n      }),\n    [runtime, mode, scope, agent, pageSize],\n  );\n  const state = useSyncExternalStore(\n    history.subscribe,\n    history.getSnapshot,\n    history.getSnapshot,\n  );\n  useEffect(() => {\n    if (!state.started) history.refresh();\n  }, [history, state.started]);\n  const keyOf = useCallback(\n    (conversation: ConversationSummary) =>\n      continueKey(conversation, subject, thread),\n    [subject, thread],\n  );\n  return {\n    state,\n    refresh: history.refresh,\n    loadMore: history.loadMore,\n    retry: history.retry,\n    keyOf,\n    remove: useCallback(\n      (conversation: ConversationSummary) =>\n        history.remove(keyOf(conversation), conversation.id),\n      [history, keyOf],\n    ),\n    continue: useCallback(\n      (conversation: ConversationSummary) =>\n        runtime.continue(keyOf(conversation), conversation.id),\n      [runtime, keyOf],\n    ),\n  };\n}\n\nexport interface UseAgentTranscript {\n  readonly state: AgentTranscriptState;\n  /** Reads the newest page anew. */\n  readonly load: () => void;\n  /** The page before the earliest read, prepended. */\n  readonly loadEarlier: () => void;\n  /** Reads again the page that failed: the newest, or the earlier one. */\n  readonly retry: () => void;\n}\n\n/** A past conversation read back, newest page first, as the component mounts. */\nexport function useAgentTranscript(\n  conversationId: string,\n  options: { readonly pageSize?: number } = {},\n): UseAgentTranscript {\n  const runtime = useAgentRuntime();\n  const { pageSize } = options;\n  const transcript = useMemo<AgentTranscript>(\n    () =>\n      createAgentTranscript({\n        runtime,\n        conversationId,\n        ...(pageSize === undefined ? {} : { pageSize }),\n      }),\n    [runtime, conversationId, pageSize],\n  );\n  const state = useSyncExternalStore(\n    transcript.subscribe,\n    transcript.getSnapshot,\n    transcript.getSnapshot,\n  );\n  useEffect(() => {\n    if (!state.started) transcript.load();\n  }, [transcript, state.started]);\n  return {\n    state,\n    load: transcript.load,\n    loadEarlier: transcript.loadEarlier,\n    retry: transcript.retry,\n  };\n}\n"]}

package/dist/index.cjs

@@ -88,6 +88,10 @@ Object.defineProperty(exports, "formatDate", {
   enumerable: true,
   get: function () { return copy.formatDate; }
 });
+Object.defineProperty(exports, "formatDateTime", {
+  enumerable: true,
+  get: function () { return copy.formatDateTime; }
+});
 Object.defineProperty(exports, "formatDayTime", {
   enumerable: true,
   get: function () { return copy.formatDayTime; }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Translate, CopyOverrides } from '@vinaverse/tokens/copy';
-export { AI_MARK, BANNED_WORDS, COPY, Copy, CopyKey, CopyOverrides, Translate, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatDayTime, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
+export { AI_MARK, BANNED_WORDS, COPY, Copy, CopyKey, CopyOverrides, Translate, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatDateTime, formatDayTime, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
 import { ReactNode } from 'react';
 import { ConversationView, StreamingText } from '@vinaverse/client/conversation';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Translate, CopyOverrides } from '@vinaverse/tokens/copy';
-export { AI_MARK, BANNED_WORDS, COPY, Copy, CopyKey, CopyOverrides, Translate, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatDayTime, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
+export { AI_MARK, BANNED_WORDS, COPY, Copy, CopyKey, CopyOverrides, Translate, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatDateTime, formatDayTime, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
 import { ReactNode } from 'react';
 import { ConversationView, StreamingText } from '@vinaverse/client/conversation';
 

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createTranslate, textDirection } from '@vinaverse/tokens/copy';
-export { AI_MARK, BANNED_WORDS, COPY, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatDayTime, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
+export { AI_MARK, BANNED_WORDS, COPY, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatDateTime, formatDayTime, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
 import { useMemo, useContext, useSyncExternalStore, useRef, useCallback, createContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinaverse/react",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "description": "Vinaverse for React: hooks over the conversation store, and the copy and formatting every Vinaverse React UI shares. No react-native or DOM import.",
   "license": "Apache-2.0",
   "author": "Vinaverse, Inc.",
@@ -47,6 +47,20 @@
         "default": "./dist/agent.cjs"
       }
     },
+    "./history": {
+      "react-native": {
+        "types": "./dist/history.d.cts",
+        "default": "./dist/history.cjs"
+      },
+      "import": {
+        "types": "./dist/history.d.ts",
+        "default": "./dist/history.js"
+      },
+      "require": {
+        "types": "./dist/history.d.cts",
+        "default": "./dist/history.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
@@ -56,8 +70,8 @@
     "dist"
   ],
   "dependencies": {
-    "@vinaverse/client": "0.1.0-alpha.10",
-    "@vinaverse/tokens": "0.1.0-alpha.10"
+    "@vinaverse/client": "0.1.0-alpha.12",
+    "@vinaverse/tokens": "0.1.0-alpha.12"
   },
   "peerDependencies": {
     "react": ">=19.1"
@@ -76,7 +90,8 @@
         "react/jsx-runtime",
         "@vinaverse/client",
         "@vinaverse/tokens/copy",
-        "@vinaverse/client/agent"
+        "@vinaverse/client/agent",
+        "@vinaverse/client/history"
       ],
       "limit": "1.5 kB"
     },
@@ -89,7 +104,22 @@
         "react/jsx-runtime",
         "@vinaverse/client",
         "@vinaverse/tokens/copy",
-        "@vinaverse/client/agent"
+        "@vinaverse/client/agent",
+        "@vinaverse/client/history"
+      ],
+      "limit": "1.5 kB"
+    },
+    {
+      "name": "@vinaverse/react/history (ESM, everything; react and the other @vinaverse packages excluded)",
+      "path": "dist/history.js",
+      "import": "*",
+      "ignore": [
+        "react",
+        "react/jsx-runtime",
+        "@vinaverse/client",
+        "@vinaverse/tokens/copy",
+        "@vinaverse/client/agent",
+        "@vinaverse/client/history"
       ],
       "limit": "1.5 kB"
     }
@@ -98,6 +128,9 @@
     "*": {
       "agent": [
         "./dist/agent.d.cts"
+      ],
+      "history": [
+        "./dist/history.d.cts"
       ]
     }
   },