@vinaverse/react 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/agent.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+var agent = require('@vinaverse/client/agent');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/agent.tsx
+var RuntimeContext = /* @__PURE__ */ react.createContext(null);
+function AgentRuntimeProvider(props) {
+  return /* @__PURE__ */ jsxRuntime.jsx(RuntimeContext.Provider, { value: props.runtime, children: props.children });
+}
+function useAgentRuntime() {
+  const runtime = react.useContext(RuntimeContext);
+  if (!runtime)
+    throw new Error("Agent hooks render inside <AgentRuntimeProvider>.");
+  return runtime;
+}
+function useAgentConversation(key, open = {}) {
+  const runtime = useAgentRuntime();
+  const keyRef = react.useRef(key);
+  keyRef.current = key;
+  const k = agent.agentKey(key);
+  const read = react.useCallback(() => runtime.peek(keyRef.current), [runtime, k]);
+  const conversation = react.useSyncExternalStore(runtime.subscribe, read, read);
+  const openRef = react.useRef(open);
+  openRef.current = open;
+  react.useLayoutEffect(() => conversation.show(openRef.current), [conversation]);
+  const { place, entryPoint } = open;
+  const screen = place?.screen;
+  const entityType = place?.entity?.type;
+  const entityId = place?.entity?.id;
+  react.useLayoutEffect(() => {
+    conversation.tell(openRef.current);
+  }, [conversation, screen, entityType, entityId, entryPoint]);
+  const state = react.useSyncExternalStore(
+    conversation.subscribe,
+    conversation.getState,
+    conversation.getState
+  );
+  const startNew = react.useCallback(
+    () => runtime.startNew(keyRef.current),
+    [runtime]
+  );
+  return { conversation, state, startNew };
+}
+function useAgentStatus() {
+  const runtime = useAgentRuntime();
+  react.useEffect(() => {
+    runtime.status().catch(() => void 0);
+  }, [runtime]);
+  return react.useSyncExternalStore(
+    runtime.subscribe,
+    runtime.getStatus,
+    runtime.getStatus
+  );
+}
+function useAgentName(fallback) {
+  const runtime = useAgentRuntime();
+  return react.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 };
+}
+function greetedKey(subject, mode) {
+  return `vinaverse.agent.greeted.${subject ?? "guest"}:${mode}`;
+}
+var MEMORY = /* @__PURE__ */ new Map();
+var memory = {
+  getItem: (k) => MEMORY.get(k) ?? null,
+  setItem: (k, v) => void MEMORY.set(k, v)
+};
+function useAgentLauncher(options) {
+  const runtime = useAgentRuntime();
+  const status = useAgentStatus();
+  const { subject, mode, onOpen } = options;
+  const storage = options.storage ?? memory;
+  const shows = status?.launcher === true && options.visible !== false;
+  const key = (options.storageKey ?? greetedKey)(subject, mode);
+  const [greeted, setGreeted] = react.useState(
+    null
+  );
+  const [due, setDue] = react.useState(null);
+  react.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;
+  react.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 = react.useCallback(() => {
+    setGreeted({ key, done: true });
+    void Promise.resolve(storage.setItem(key, "1")).catch(() => void 0);
+  }, [storage, key]);
+  const open = react.useCallback(() => {
+    done();
+    runtime.emit({ type: "launcher_opened" });
+    onOpen();
+  }, [done, runtime, onOpen]);
+  const dismiss = react.useCallback(() => {
+    done();
+    runtime.emit({ type: "greeting_closed" });
+  }, [done, runtime]);
+  react.useEffect(() => {
+    if (shows) runtime.emit({ type: "launcher_shown" });
+  }, [shows, runtime]);
+  return { shows, greets: pending && due === key, open, dismiss };
+}
+
+exports.AgentRuntimeProvider = AgentRuntimeProvider;
+exports.greetedKey = greetedKey;
+exports.useAgentConversation = useAgentConversation;
+exports.useAgentFeatures = useAgentFeatures;
+exports.useAgentLauncher = useAgentLauncher;
+exports.useAgentName = useAgentName;
+exports.useAgentProfile = useAgentProfile;
+exports.useAgentRuntime = useAgentRuntime;
+exports.useAgentStatus = useAgentStatus;
+//# sourceMappingURL=agent.cjs.map
+//# sourceMappingURL=agent.cjs.map

package/dist/agent.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent.tsx"],"names":["jsx","useContext","useRef","agentKey","useCallback","useSyncExternalStore","useLayoutEffect","useEffect","useState"],"mappings":"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","file":"agent.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} from '@vinaverse/client/agent';\nimport { agentKey } 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  // 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  }, [conversation, screen, entityType, entityId, entryPoint]);\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/** 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/** Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). */\nexport interface GreetingStorage {\n  getItem(key: string): string | null | Promise<string | null>;\n  setItem(key: string, value: 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 function greetedKey(subject: string | null, mode: string): string {\n  return `vinaverse.agent.greeted.${subject ?? 'guest'}:${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};\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  const storage = options.storage ?? 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/agent.d.cts

@@ -0,0 +1,69 @@
+import { AgentRuntime, AgentConversation, AgentConversationState, AgentKey, AgentPlace, AgentStatus } from '@vinaverse/client/agent';
+import { ReactNode } from 'react';
+
+/** The app's agent runtime, made once (module level, or memoized) and given to everything below. */
+declare function AgentRuntimeProvider(props: {
+    readonly runtime: AgentRuntime;
+    readonly children?: ReactNode;
+}): ReactNode;
+declare function useAgentRuntime(): AgentRuntime;
+interface UseAgentConversation {
+    readonly conversation: AgentConversation;
+    readonly state: AgentConversationState;
+    /** A new conversation for this key (the old one let go and forgotten). */
+    readonly startNew: () => void;
+}
+/**
+ * The key's conversation, shown while the component is mounted (kept across screens; released when it unmounts), told
+ * the place and the way in as they change. A start over or its end hands the component the key's next conversation.
+ */
+declare function useAgentConversation(key: AgentKey, open?: {
+    readonly place?: AgentPlace | null;
+    readonly entryPoint?: string | null;
+}): UseAgentConversation;
+/** The agent's status (read once, then at most every few minutes); null until the first read. */
+declare function useAgentStatus(): AgentStatus | null;
+/** The agent's name: the newest session's, else the status's, else `fallback`. */
+declare function useAgentName(fallback: string): string;
+/** What the agent can do, from the status (all off until it is read, and when the agent is off). */
+declare function useAgentFeatures(): AgentStatus['features'] & {
+    readonly available: boolean;
+    readonly launcher: boolean;
+};
+/** The agent as an entry shows it before any session: its name (`fallback` until known) and avatar. */
+declare function useAgentProfile(fallback: string): {
+    readonly name: string;
+    readonly avatarUrl: string | null;
+};
+/** Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). */
+interface GreetingStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+}
+/** Where the greeting is remembered, per person and mode: the default the storage sees, unless the app maps its own. */
+declare function greetedKey(subject: string | null, mode: string): string;
+interface UseAgentLauncher {
+    /** The status offers the launcher, and the app shows it here. */
+    readonly shows: boolean;
+    /** Its greeting bubble: once per person and mode, a moment after the launcher shows. */
+    readonly greets: boolean;
+    /** The person opens the agent (the greeting is done too). */
+    readonly open: () => void;
+    /** The person closes the greeting. */
+    readonly dismiss: () => void;
+}
+/** The floating launcher's state: whether it shows and greets, and its two actions. */
+declare function useAgentLauncher(options: {
+    readonly subject: string | null;
+    readonly mode: string;
+    /** The app's own rule (the tabs it shows on, no keyboard up…); default true. */
+    readonly visible?: boolean;
+    readonly storage?: GreetingStorage;
+    /** The storage's key for a person and mode, to reuse a record the app already keeps. Default `greetedKey`. */
+    readonly storageKey?: (subject: string | null, mode: string) => string;
+    /** How long after showing the greeting appears. Default 1200 ms. */
+    readonly delayMs?: number;
+    readonly onOpen: () => void;
+}): UseAgentLauncher;
+
+export { AgentRuntimeProvider, type GreetingStorage, type UseAgentConversation, type UseAgentLauncher, greetedKey, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus };

package/dist/agent.d.ts

@@ -0,0 +1,69 @@
+import { AgentRuntime, AgentConversation, AgentConversationState, AgentKey, AgentPlace, AgentStatus } from '@vinaverse/client/agent';
+import { ReactNode } from 'react';
+
+/** The app's agent runtime, made once (module level, or memoized) and given to everything below. */
+declare function AgentRuntimeProvider(props: {
+    readonly runtime: AgentRuntime;
+    readonly children?: ReactNode;
+}): ReactNode;
+declare function useAgentRuntime(): AgentRuntime;
+interface UseAgentConversation {
+    readonly conversation: AgentConversation;
+    readonly state: AgentConversationState;
+    /** A new conversation for this key (the old one let go and forgotten). */
+    readonly startNew: () => void;
+}
+/**
+ * The key's conversation, shown while the component is mounted (kept across screens; released when it unmounts), told
+ * the place and the way in as they change. A start over or its end hands the component the key's next conversation.
+ */
+declare function useAgentConversation(key: AgentKey, open?: {
+    readonly place?: AgentPlace | null;
+    readonly entryPoint?: string | null;
+}): UseAgentConversation;
+/** The agent's status (read once, then at most every few minutes); null until the first read. */
+declare function useAgentStatus(): AgentStatus | null;
+/** The agent's name: the newest session's, else the status's, else `fallback`. */
+declare function useAgentName(fallback: string): string;
+/** What the agent can do, from the status (all off until it is read, and when the agent is off). */
+declare function useAgentFeatures(): AgentStatus['features'] & {
+    readonly available: boolean;
+    readonly launcher: boolean;
+};
+/** The agent as an entry shows it before any session: its name (`fallback` until known) and avatar. */
+declare function useAgentProfile(fallback: string): {
+    readonly name: string;
+    readonly avatarUrl: string | null;
+};
+/** Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). */
+interface GreetingStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+}
+/** Where the greeting is remembered, per person and mode: the default the storage sees, unless the app maps its own. */
+declare function greetedKey(subject: string | null, mode: string): string;
+interface UseAgentLauncher {
+    /** The status offers the launcher, and the app shows it here. */
+    readonly shows: boolean;
+    /** Its greeting bubble: once per person and mode, a moment after the launcher shows. */
+    readonly greets: boolean;
+    /** The person opens the agent (the greeting is done too). */
+    readonly open: () => void;
+    /** The person closes the greeting. */
+    readonly dismiss: () => void;
+}
+/** The floating launcher's state: whether it shows and greets, and its two actions. */
+declare function useAgentLauncher(options: {
+    readonly subject: string | null;
+    readonly mode: string;
+    /** The app's own rule (the tabs it shows on, no keyboard up…); default true. */
+    readonly visible?: boolean;
+    readonly storage?: GreetingStorage;
+    /** The storage's key for a person and mode, to reuse a record the app already keeps. Default `greetedKey`. */
+    readonly storageKey?: (subject: string | null, mode: string) => string;
+    /** How long after showing the greeting appears. Default 1200 ms. */
+    readonly delayMs?: number;
+    readonly onOpen: () => void;
+}): UseAgentLauncher;
+
+export { AgentRuntimeProvider, type GreetingStorage, type UseAgentConversation, type UseAgentLauncher, greetedKey, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus };

package/dist/agent.js

@@ -0,0 +1,137 @@
+import { agentKey } 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;
+  useLayoutEffect(() => {
+    conversation.tell(openRef.current);
+  }, [conversation, screen, entityType, entityId, 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 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 };
+}
+function greetedKey(subject, mode) {
+  return `vinaverse.agent.greeted.${subject ?? "guest"}:${mode}`;
+}
+var MEMORY = /* @__PURE__ */ new Map();
+var memory = {
+  getItem: (k) => MEMORY.get(k) ?? null,
+  setItem: (k, v) => void MEMORY.set(k, v)
+};
+function useAgentLauncher(options) {
+  const runtime = useAgentRuntime();
+  const status = useAgentStatus();
+  const { subject, mode, onOpen } = options;
+  const storage = options.storage ?? 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, greetedKey, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus };
+//# sourceMappingURL=agent.js.map
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +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} from '@vinaverse/client/agent';\nimport { agentKey } 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  // 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  }, [conversation, screen, entityType, entityId, entryPoint]);\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/** 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/** Where the launcher remembers that it greeted a person in a mode (sync or async; the app's preferences store). */\nexport interface GreetingStorage {\n  getItem(key: string): string | null | Promise<string | null>;\n  setItem(key: string, value: 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 function greetedKey(subject: string | null, mode: string): string {\n  return `vinaverse.agent.greeted.${subject ?? 'guest'}:${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};\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  const storage = options.storage ?? 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/index.cjs

@@ -5,10 +5,10 @@ var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
 // src/index.ts
-var CopyContext = react.createContext({
+var CopyContext = /* @__PURE__ */ react.createContext({
   locale: void 0,
   direction: "ltr",
-  t: copy.createTranslate(void 0)
+  t: /* @__PURE__ */ copy.createTranslate(void 0)
 });
 function CopyProvider(props) {
   const { locale, copy: copy$1, children } = props;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":["createContext","createTranslate","copy","useMemo","textDirection","jsx","useContext","useSyncExternalStore","useRef","useCallback"],"mappings":";;;;;;;AAgBA,IAAM,cAAcA,mBAAA,CAAgC;AAAA,EAClD,MAAA,EAAQ,MAAA;AAAA,EACR,SAAA,EAAW,KAAA;AAAA,EACX,CAAA,EAAGC,qBAAgB,MAAS;AAC9B,CAAC,CAAA;AAEM,SAAS,aAAa,KAAA,EAIf;AACZ,EAAA,MAAM,EAAE,MAAA,QAAQC,MAAA,EAAM,QAAA,EAAS,GAAI,KAAA;AACnC,EAAA,MAAM,KAAA,GAAQC,aAAA;AAAA,IACZ,OAAO;AAAA,MACL,MAAA;AAAA,MACA,SAAA,EAAWC,mBAAc,MAAM,CAAA;AAAA,MAC/B,CAAA,EAAGH,oBAAA,CAAgB,MAAA,EAAQC,MAAI;AAAA,KACjC,CAAA;AAAA,IACA,CAAC,QAAQA,MAAI;AAAA,GACf;AACA,EAAA,uBAAOG,cAAA,CAAC,WAAA,CAAY,QAAA,EAAZ,EAAqB,OAAe,QAAA,EAAS,CAAA;AACvD;AAGO,SAAS,OAAA,GAA4B;AAC1C,EAAA,OAAOC,iBAAW,WAAW,CAAA;AAC/B;ACxBO,SAAS,gBAAgB,MAAA,EAA8C;AAC5E,EAAA,OAAOC,0BAAA;AAAA,IACL,MAAA,CAAO,SAAA;AAAA,IACP,MAAA,CAAO,WAAA;AAAA,IACP,MAAA,CAAO;AAAA,GACT;AACF;AAMO,SAAS,uBAAA,CACd,MAAA,EACA,QAAA,EACA,OAAA,GAAmC,OAAO,EAAA,EACvC;AACH,EAAA,MAAM,IAAA,GAAOC,aAAoD,IAAI,CAAA;AACrE,EAAA,MAAM,MAAA,GAASA,aAAO,QAAQ,CAAA;AAC9B,EAAA,MAAA,CAAO,OAAA,GAAU,QAAA;AACjB,EAAA,MAAM,OAAA,GAAUA,aAAO,OAAO,CAAA;AAC9B,EAAA,OAAA,CAAQ,OAAA,GAAU,OAAA;AAClB,EAAA,MAAM,GAAA,GAAMC,kBAAY,MAAS;AAC/B,IAAA,MAAM,IAAA,GAAO,OAAO,WAAA,EAAY;AAChC,IAAA,MAAM,OAAO,IAAA,CAAK,OAAA;AAClB,IAAA,IAAI,IAAA,EAAM,IAAA,KAAS,IAAA,EAAM,OAAO,IAAA,CAAK,KAAA;AACrC,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA;AACjC,IAAA,IAAI,QAAQ,OAAA,CAAQ,OAAA,CAAQ,IAAA,CAAK,KAAA,EAAO,KAAK,CAAA,EAAG;AAC9C,MAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAO,KAAK,KAAA,EAAM;AACzC,MAAA,OAAO,IAAA,CAAK,KAAA;AAAA,IACd;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAM;AAC7B,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AACX,EAAA,OAAOF,0BAAA,CAAqB,MAAA,CAAO,SAAA,EAAW,GAAA,EAAK,GAAG,CAAA;AACxD;AAMO,SAAS,gBAAA,CACd,QACA,GAAA,EACe;AACf,EAAA,MAAM,GAAA,GAAME,kBAAY,MAAM;AAC5B,IAAA,MAAM,SAAA,GAAY,OAAO,YAAA,EAAa;AACtC,IAAA,OAAO,SAAA,EAAW,GAAA,KAAQ,GAAA,GAAM,SAAA,CAAU,IAAA,GAAO,IAAA;AAAA,EACnD,CAAA,EAAG,CAAC,MAAA,EAAQ,GAAG,CAAC,CAAA;AAChB,EAAA,OAAOF,0BAAA,CAAqB,MAAA,CAAO,kBAAA,EAAoB,GAAA,EAAK,GAAG,CAAA;AACjE","file":"index.cjs","sourcesContent":["// The copy a component tree uses, from a provider: the locale's built-in words with the tenant's overrides on top.\n\nimport {\n  type CopyOverrides,\n  createTranslate,\n  type Translate,\n  textDirection,\n} from '@vinaverse/tokens/copy';\nimport { createContext, type ReactNode, useContext, useMemo } from 'react';\n\nexport interface CopyContextValue {\n  readonly locale: string | undefined;\n  readonly direction: 'ltr' | 'rtl';\n  readonly t: Translate;\n}\n\nconst CopyContext = createContext<CopyContextValue>({\n  locale: undefined,\n  direction: 'ltr',\n  t: createTranslate(undefined),\n});\n\nexport function CopyProvider(props: {\n  readonly locale?: string | undefined;\n  readonly copy?: CopyOverrides | undefined;\n  readonly children?: ReactNode;\n}): ReactNode {\n  const { locale, copy, children } = props;\n  const value = useMemo<CopyContextValue>(\n    () => ({\n      locale,\n      direction: textDirection(locale),\n      t: createTranslate(locale, copy),\n    }),\n    [locale, copy],\n  );\n  return <CopyContext.Provider value={value}>{children}</CopyContext.Provider>;\n}\n\n/** The translator, the locale and its text direction. */\nexport function useCopy(): CopyContextValue {\n  return useContext(CopyContext);\n}\n","// The React bindings of the conversation store: thin by design. Every protocol rule lives in @vinaverse/client; these\n// hooks only subscribe, and re-render a component when the slice it reads changed.\n\nimport type {\n  ConversationView,\n  StreamingText,\n} from '@vinaverse/client/conversation';\nimport { useCallback, useRef, useSyncExternalStore } from 'react';\n\n/** What the hooks read: a conversation store, or anything with the same four members (a test's fake). */\nexport interface ConversationSource {\n  getSnapshot(): ConversationView;\n  subscribe(listener: () => void): () => void;\n  getStreaming(): StreamingText | null;\n  subscribeStreaming(listener: () => void): () => void;\n}\n\n/** The whole view; re-renders on every change of it. Prefer `useConversationSelector` in anything drawn often. */\nexport function useConversation(source: ConversationSource): ConversationView {\n  return useSyncExternalStore(\n    source.subscribe,\n    source.getSnapshot,\n    source.getSnapshot,\n  );\n}\n\n/**\n * A slice of the view; re-renders only when the slice changed by `isEqual` (default `Object.is`). The view is\n * structurally shared, so selecting `items`, one item, or a field compares by identity.\n */\nexport function useConversationSelector<T>(\n  source: ConversationSource,\n  selector: (view: ConversationView) => T,\n  isEqual: (a: T, b: T) => boolean = Object.is,\n): T {\n  const last = useRef<{ view: ConversationView; value: T } | null>(null);\n  const select = useRef(selector);\n  select.current = selector;\n  const compare = useRef(isEqual);\n  compare.current = isEqual;\n  const get = useCallback((): T => {\n    const view = source.getSnapshot();\n    const held = last.current;\n    if (held?.view === view) return held.value;\n    const value = select.current(view);\n    if (held && compare.current(held.value, value)) {\n      last.current = { view, value: held.value };\n      return held.value;\n    }\n    last.current = { view, value };\n    return value;\n  }, [source]);\n  return useSyncExternalStore(source.subscribe, get, get);\n}\n\n/**\n * The streamed text of the message with this `key`, or null when it is not the one streaming: only the streaming\n * bubble calls it, and only it re-renders as the reply arrives (at most once per frame).\n */\nexport function useStreamingText(\n  source: ConversationSource,\n  key: string,\n): string | null {\n  const get = useCallback(() => {\n    const streaming = source.getStreaming();\n    return streaming?.key === key ? streaming.text : null;\n  }, [source, key]);\n  return useSyncExternalStore(source.subscribeStreaming, get, get);\n}\n"]}
+{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":["createContext","copy","useMemo","textDirection","createTranslate","jsx","useContext","useSyncExternalStore","useRef","useCallback"],"mappings":";;;;;;;AAgBA,IAAM,8BAA8BA,mBAAA,CAAgC;AAAA,EAClE,MAAA,EAAQ,MAAA;AAAA,EACR,SAAA,EAAW,KAAA;AAAA,EACX,CAAA,uCAAmC,MAAS;AAC9C,CAAC,CAAA;AAEM,SAAS,aAAa,KAAA,EAIf;AACZ,EAAA,MAAM,EAAE,MAAA,QAAQC,MAAA,EAAM,QAAA,EAAS,GAAI,KAAA;AACnC,EAAA,MAAM,KAAA,GAAQC,aAAA;AAAA,IACZ,OAAO;AAAA,MACL,MAAA;AAAA,MACA,SAAA,EAAWC,mBAAc,MAAM,CAAA;AAAA,MAC/B,CAAA,EAAGC,oBAAA,CAAgB,MAAA,EAAQH,MAAI;AAAA,KACjC,CAAA;AAAA,IACA,CAAC,QAAQA,MAAI;AAAA,GACf;AACA,EAAA,uBAAOI,cAAA,CAAC,WAAA,CAAY,QAAA,EAAZ,EAAqB,OAAe,QAAA,EAAS,CAAA;AACvD;AAGO,SAAS,OAAA,GAA4B;AAC1C,EAAA,OAAOC,iBAAW,WAAW,CAAA;AAC/B;ACxBO,SAAS,gBAAgB,MAAA,EAA8C;AAC5E,EAAA,OAAOC,0BAAA;AAAA,IACL,MAAA,CAAO,SAAA;AAAA,IACP,MAAA,CAAO,WAAA;AAAA,IACP,MAAA,CAAO;AAAA,GACT;AACF;AAMO,SAAS,uBAAA,CACd,MAAA,EACA,QAAA,EACA,OAAA,GAAmC,OAAO,EAAA,EACvC;AACH,EAAA,MAAM,IAAA,GAAOC,aAAoD,IAAI,CAAA;AACrE,EAAA,MAAM,MAAA,GAASA,aAAO,QAAQ,CAAA;AAC9B,EAAA,MAAA,CAAO,OAAA,GAAU,QAAA;AACjB,EAAA,MAAM,OAAA,GAAUA,aAAO,OAAO,CAAA;AAC9B,EAAA,OAAA,CAAQ,OAAA,GAAU,OAAA;AAClB,EAAA,MAAM,GAAA,GAAMC,kBAAY,MAAS;AAC/B,IAAA,MAAM,IAAA,GAAO,OAAO,WAAA,EAAY;AAChC,IAAA,MAAM,OAAO,IAAA,CAAK,OAAA;AAClB,IAAA,IAAI,IAAA,EAAM,IAAA,KAAS,IAAA,EAAM,OAAO,IAAA,CAAK,KAAA;AACrC,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA;AACjC,IAAA,IAAI,QAAQ,OAAA,CAAQ,OAAA,CAAQ,IAAA,CAAK,KAAA,EAAO,KAAK,CAAA,EAAG;AAC9C,MAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAO,KAAK,KAAA,EAAM;AACzC,MAAA,OAAO,IAAA,CAAK,KAAA;AAAA,IACd;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAM;AAC7B,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AACX,EAAA,OAAOF,0BAAA,CAAqB,MAAA,CAAO,SAAA,EAAW,GAAA,EAAK,GAAG,CAAA;AACxD;AAMO,SAAS,gBAAA,CACd,QACA,GAAA,EACe;AACf,EAAA,MAAM,GAAA,GAAME,kBAAY,MAAM;AAC5B,IAAA,MAAM,SAAA,GAAY,OAAO,YAAA,EAAa;AACtC,IAAA,OAAO,SAAA,EAAW,GAAA,KAAQ,GAAA,GAAM,SAAA,CAAU,IAAA,GAAO,IAAA;AAAA,EACnD,CAAA,EAAG,CAAC,MAAA,EAAQ,GAAG,CAAC,CAAA;AAChB,EAAA,OAAOF,0BAAA,CAAqB,MAAA,CAAO,kBAAA,EAAoB,GAAA,EAAK,GAAG,CAAA;AACjE","file":"index.cjs","sourcesContent":["// The copy a component tree uses, from a provider: the locale's built-in words with the tenant's overrides on top.\n\nimport {\n  type CopyOverrides,\n  createTranslate,\n  type Translate,\n  textDirection,\n} from '@vinaverse/tokens/copy';\nimport { createContext, type ReactNode, useContext, useMemo } from 'react';\n\nexport interface CopyContextValue {\n  readonly locale: string | undefined;\n  readonly direction: 'ltr' | 'rtl';\n  readonly t: Translate;\n}\n\nconst CopyContext = /* @__PURE__ */ createContext<CopyContextValue>({\n  locale: undefined,\n  direction: 'ltr',\n  t: /* @__PURE__ */ createTranslate(undefined),\n});\n\nexport function CopyProvider(props: {\n  readonly locale?: string | undefined;\n  readonly copy?: CopyOverrides | undefined;\n  readonly children?: ReactNode;\n}): ReactNode {\n  const { locale, copy, children } = props;\n  const value = useMemo<CopyContextValue>(\n    () => ({\n      locale,\n      direction: textDirection(locale),\n      t: createTranslate(locale, copy),\n    }),\n    [locale, copy],\n  );\n  return <CopyContext.Provider value={value}>{children}</CopyContext.Provider>;\n}\n\n/** The translator, the locale and its text direction. */\nexport function useCopy(): CopyContextValue {\n  return useContext(CopyContext);\n}\n","// The React bindings of the conversation store: thin by design. Every protocol rule lives in @vinaverse/client; these\n// hooks only subscribe, and re-render a component when the slice it reads changed.\n\nimport type {\n  ConversationView,\n  StreamingText,\n} from '@vinaverse/client/conversation';\nimport { useCallback, useRef, useSyncExternalStore } from 'react';\n\n/** What the hooks read: a conversation store, or anything with the same four members (a test's fake). */\nexport interface ConversationSource {\n  getSnapshot(): ConversationView;\n  subscribe(listener: () => void): () => void;\n  getStreaming(): StreamingText | null;\n  subscribeStreaming(listener: () => void): () => void;\n}\n\n/** The whole view; re-renders on every change of it. Prefer `useConversationSelector` in anything drawn often. */\nexport function useConversation(source: ConversationSource): ConversationView {\n  return useSyncExternalStore(\n    source.subscribe,\n    source.getSnapshot,\n    source.getSnapshot,\n  );\n}\n\n/**\n * A slice of the view; re-renders only when the slice changed by `isEqual` (default `Object.is`). The view is\n * structurally shared, so selecting `items`, one item, or a field compares by identity.\n */\nexport function useConversationSelector<T>(\n  source: ConversationSource,\n  selector: (view: ConversationView) => T,\n  isEqual: (a: T, b: T) => boolean = Object.is,\n): T {\n  const last = useRef<{ view: ConversationView; value: T } | null>(null);\n  const select = useRef(selector);\n  select.current = selector;\n  const compare = useRef(isEqual);\n  compare.current = isEqual;\n  const get = useCallback((): T => {\n    const view = source.getSnapshot();\n    const held = last.current;\n    if (held?.view === view) return held.value;\n    const value = select.current(view);\n    if (held && compare.current(held.value, value)) {\n      last.current = { view, value: held.value };\n      return held.value;\n    }\n    last.current = { view, value };\n    return value;\n  }, [source]);\n  return useSyncExternalStore(source.subscribe, get, get);\n}\n\n/**\n * The streamed text of the message with this `key`, or null when it is not the one streaming: only the streaming\n * bubble calls it, and only it re-renders as the reply arrives (at most once per frame).\n */\nexport function useStreamingText(\n  source: ConversationSource,\n  key: string,\n): string | null {\n  const get = useCallback(() => {\n    const streaming = source.getStreaming();\n    return streaming?.key === key ? streaming.text : null;\n  }, [source, key]);\n  return useSyncExternalStore(source.subscribeStreaming, get, get);\n}\n"]}

package/dist/index.js

@@ -1,13 +1,13 @@
 import { createTranslate, textDirection } from '@vinaverse/tokens/copy';
 export { AI_MARK, BANNED_WORDS, COPY, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
-import { createContext, useMemo, useContext, useSyncExternalStore, useRef, useCallback } from 'react';
+import { useMemo, useContext, useSyncExternalStore, useRef, useCallback, createContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 // src/index.ts
-var CopyContext = createContext({
+var CopyContext = /* @__PURE__ */ createContext({
   locale: void 0,
   direction: "ltr",
-  t: createTranslate(void 0)
+  t: /* @__PURE__ */ createTranslate(void 0)
 });
 function CopyProvider(props) {
   const { locale, copy, children } = props;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":[],"mappings":";;;;;;AAgBA,IAAM,cAAc,aAAA,CAAgC;AAAA,EAClD,MAAA,EAAQ,MAAA;AAAA,EACR,SAAA,EAAW,KAAA;AAAA,EACX,CAAA,EAAG,gBAAgB,MAAS;AAC9B,CAAC,CAAA;AAEM,SAAS,aAAa,KAAA,EAIf;AACZ,EAAA,MAAM,EAAE,MAAA,EAAQ,IAAA,EAAM,QAAA,EAAS,GAAI,KAAA;AACnC,EAAA,MAAM,KAAA,GAAQ,OAAA;AAAA,IACZ,OAAO;AAAA,MACL,MAAA;AAAA,MACA,SAAA,EAAW,cAAc,MAAM,CAAA;AAAA,MAC/B,CAAA,EAAG,eAAA,CAAgB,MAAA,EAAQ,IAAI;AAAA,KACjC,CAAA;AAAA,IACA,CAAC,QAAQ,IAAI;AAAA,GACf;AACA,EAAA,uBAAO,GAAA,CAAC,WAAA,CAAY,QAAA,EAAZ,EAAqB,OAAe,QAAA,EAAS,CAAA;AACvD;AAGO,SAAS,OAAA,GAA4B;AAC1C,EAAA,OAAO,WAAW,WAAW,CAAA;AAC/B;ACxBO,SAAS,gBAAgB,MAAA,EAA8C;AAC5E,EAAA,OAAO,oBAAA;AAAA,IACL,MAAA,CAAO,SAAA;AAAA,IACP,MAAA,CAAO,WAAA;AAAA,IACP,MAAA,CAAO;AAAA,GACT;AACF;AAMO,SAAS,uBAAA,CACd,MAAA,EACA,QAAA,EACA,OAAA,GAAmC,OAAO,EAAA,EACvC;AACH,EAAA,MAAM,IAAA,GAAO,OAAoD,IAAI,CAAA;AACrE,EAAA,MAAM,MAAA,GAAS,OAAO,QAAQ,CAAA;AAC9B,EAAA,MAAA,CAAO,OAAA,GAAU,QAAA;AACjB,EAAA,MAAM,OAAA,GAAU,OAAO,OAAO,CAAA;AAC9B,EAAA,OAAA,CAAQ,OAAA,GAAU,OAAA;AAClB,EAAA,MAAM,GAAA,GAAM,YAAY,MAAS;AAC/B,IAAA,MAAM,IAAA,GAAO,OAAO,WAAA,EAAY;AAChC,IAAA,MAAM,OAAO,IAAA,CAAK,OAAA;AAClB,IAAA,IAAI,IAAA,EAAM,IAAA,KAAS,IAAA,EAAM,OAAO,IAAA,CAAK,KAAA;AACrC,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA;AACjC,IAAA,IAAI,QAAQ,OAAA,CAAQ,OAAA,CAAQ,IAAA,CAAK,KAAA,EAAO,KAAK,CAAA,EAAG;AAC9C,MAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAO,KAAK,KAAA,EAAM;AACzC,MAAA,OAAO,IAAA,CAAK,KAAA;AAAA,IACd;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAM;AAC7B,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AACX,EAAA,OAAO,oBAAA,CAAqB,MAAA,CAAO,SAAA,EAAW,GAAA,EAAK,GAAG,CAAA;AACxD;AAMO,SAAS,gBAAA,CACd,QACA,GAAA,EACe;AACf,EAAA,MAAM,GAAA,GAAM,YAAY,MAAM;AAC5B,IAAA,MAAM,SAAA,GAAY,OAAO,YAAA,EAAa;AACtC,IAAA,OAAO,SAAA,EAAW,GAAA,KAAQ,GAAA,GAAM,SAAA,CAAU,IAAA,GAAO,IAAA;AAAA,EACnD,CAAA,EAAG,CAAC,MAAA,EAAQ,GAAG,CAAC,CAAA;AAChB,EAAA,OAAO,oBAAA,CAAqB,MAAA,CAAO,kBAAA,EAAoB,GAAA,EAAK,GAAG,CAAA;AACjE","file":"index.js","sourcesContent":["// The copy a component tree uses, from a provider: the locale's built-in words with the tenant's overrides on top.\n\nimport {\n  type CopyOverrides,\n  createTranslate,\n  type Translate,\n  textDirection,\n} from '@vinaverse/tokens/copy';\nimport { createContext, type ReactNode, useContext, useMemo } from 'react';\n\nexport interface CopyContextValue {\n  readonly locale: string | undefined;\n  readonly direction: 'ltr' | 'rtl';\n  readonly t: Translate;\n}\n\nconst CopyContext = createContext<CopyContextValue>({\n  locale: undefined,\n  direction: 'ltr',\n  t: createTranslate(undefined),\n});\n\nexport function CopyProvider(props: {\n  readonly locale?: string | undefined;\n  readonly copy?: CopyOverrides | undefined;\n  readonly children?: ReactNode;\n}): ReactNode {\n  const { locale, copy, children } = props;\n  const value = useMemo<CopyContextValue>(\n    () => ({\n      locale,\n      direction: textDirection(locale),\n      t: createTranslate(locale, copy),\n    }),\n    [locale, copy],\n  );\n  return <CopyContext.Provider value={value}>{children}</CopyContext.Provider>;\n}\n\n/** The translator, the locale and its text direction. */\nexport function useCopy(): CopyContextValue {\n  return useContext(CopyContext);\n}\n","// The React bindings of the conversation store: thin by design. Every protocol rule lives in @vinaverse/client; these\n// hooks only subscribe, and re-render a component when the slice it reads changed.\n\nimport type {\n  ConversationView,\n  StreamingText,\n} from '@vinaverse/client/conversation';\nimport { useCallback, useRef, useSyncExternalStore } from 'react';\n\n/** What the hooks read: a conversation store, or anything with the same four members (a test's fake). */\nexport interface ConversationSource {\n  getSnapshot(): ConversationView;\n  subscribe(listener: () => void): () => void;\n  getStreaming(): StreamingText | null;\n  subscribeStreaming(listener: () => void): () => void;\n}\n\n/** The whole view; re-renders on every change of it. Prefer `useConversationSelector` in anything drawn often. */\nexport function useConversation(source: ConversationSource): ConversationView {\n  return useSyncExternalStore(\n    source.subscribe,\n    source.getSnapshot,\n    source.getSnapshot,\n  );\n}\n\n/**\n * A slice of the view; re-renders only when the slice changed by `isEqual` (default `Object.is`). The view is\n * structurally shared, so selecting `items`, one item, or a field compares by identity.\n */\nexport function useConversationSelector<T>(\n  source: ConversationSource,\n  selector: (view: ConversationView) => T,\n  isEqual: (a: T, b: T) => boolean = Object.is,\n): T {\n  const last = useRef<{ view: ConversationView; value: T } | null>(null);\n  const select = useRef(selector);\n  select.current = selector;\n  const compare = useRef(isEqual);\n  compare.current = isEqual;\n  const get = useCallback((): T => {\n    const view = source.getSnapshot();\n    const held = last.current;\n    if (held?.view === view) return held.value;\n    const value = select.current(view);\n    if (held && compare.current(held.value, value)) {\n      last.current = { view, value: held.value };\n      return held.value;\n    }\n    last.current = { view, value };\n    return value;\n  }, [source]);\n  return useSyncExternalStore(source.subscribe, get, get);\n}\n\n/**\n * The streamed text of the message with this `key`, or null when it is not the one streaming: only the streaming\n * bubble calls it, and only it re-renders as the reply arrives (at most once per frame).\n */\nexport function useStreamingText(\n  source: ConversationSource,\n  key: string,\n): string | null {\n  const get = useCallback(() => {\n    const streaming = source.getStreaming();\n    return streaming?.key === key ? streaming.text : null;\n  }, [source, key]);\n  return useSyncExternalStore(source.subscribeStreaming, get, get);\n}\n"]}
+{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":[],"mappings":";;;;;;AAgBA,IAAM,8BAA8B,aAAA,CAAgC;AAAA,EAClE,MAAA,EAAQ,MAAA;AAAA,EACR,SAAA,EAAW,KAAA;AAAA,EACX,CAAA,kCAAmC,MAAS;AAC9C,CAAC,CAAA;AAEM,SAAS,aAAa,KAAA,EAIf;AACZ,EAAA,MAAM,EAAE,MAAA,EAAQ,IAAA,EAAM,QAAA,EAAS,GAAI,KAAA;AACnC,EAAA,MAAM,KAAA,GAAQ,OAAA;AAAA,IACZ,OAAO;AAAA,MACL,MAAA;AAAA,MACA,SAAA,EAAW,cAAc,MAAM,CAAA;AAAA,MAC/B,CAAA,EAAG,eAAA,CAAgB,MAAA,EAAQ,IAAI;AAAA,KACjC,CAAA;AAAA,IACA,CAAC,QAAQ,IAAI;AAAA,GACf;AACA,EAAA,uBAAO,GAAA,CAAC,WAAA,CAAY,QAAA,EAAZ,EAAqB,OAAe,QAAA,EAAS,CAAA;AACvD;AAGO,SAAS,OAAA,GAA4B;AAC1C,EAAA,OAAO,WAAW,WAAW,CAAA;AAC/B;ACxBO,SAAS,gBAAgB,MAAA,EAA8C;AAC5E,EAAA,OAAO,oBAAA;AAAA,IACL,MAAA,CAAO,SAAA;AAAA,IACP,MAAA,CAAO,WAAA;AAAA,IACP,MAAA,CAAO;AAAA,GACT;AACF;AAMO,SAAS,uBAAA,CACd,MAAA,EACA,QAAA,EACA,OAAA,GAAmC,OAAO,EAAA,EACvC;AACH,EAAA,MAAM,IAAA,GAAO,OAAoD,IAAI,CAAA;AACrE,EAAA,MAAM,MAAA,GAAS,OAAO,QAAQ,CAAA;AAC9B,EAAA,MAAA,CAAO,OAAA,GAAU,QAAA;AACjB,EAAA,MAAM,OAAA,GAAU,OAAO,OAAO,CAAA;AAC9B,EAAA,OAAA,CAAQ,OAAA,GAAU,OAAA;AAClB,EAAA,MAAM,GAAA,GAAM,YAAY,MAAS;AAC/B,IAAA,MAAM,IAAA,GAAO,OAAO,WAAA,EAAY;AAChC,IAAA,MAAM,OAAO,IAAA,CAAK,OAAA;AAClB,IAAA,IAAI,IAAA,EAAM,IAAA,KAAS,IAAA,EAAM,OAAO,IAAA,CAAK,KAAA;AACrC,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA;AACjC,IAAA,IAAI,QAAQ,OAAA,CAAQ,OAAA,CAAQ,IAAA,CAAK,KAAA,EAAO,KAAK,CAAA,EAAG;AAC9C,MAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAO,KAAK,KAAA,EAAM;AACzC,MAAA,OAAO,IAAA,CAAK,KAAA;AAAA,IACd;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,EAAE,IAAA,EAAM,KAAA,EAAM;AAC7B,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AACX,EAAA,OAAO,oBAAA,CAAqB,MAAA,CAAO,SAAA,EAAW,GAAA,EAAK,GAAG,CAAA;AACxD;AAMO,SAAS,gBAAA,CACd,QACA,GAAA,EACe;AACf,EAAA,MAAM,GAAA,GAAM,YAAY,MAAM;AAC5B,IAAA,MAAM,SAAA,GAAY,OAAO,YAAA,EAAa;AACtC,IAAA,OAAO,SAAA,EAAW,GAAA,KAAQ,GAAA,GAAM,SAAA,CAAU,IAAA,GAAO,IAAA;AAAA,EACnD,CAAA,EAAG,CAAC,MAAA,EAAQ,GAAG,CAAC,CAAA;AAChB,EAAA,OAAO,oBAAA,CAAqB,MAAA,CAAO,kBAAA,EAAoB,GAAA,EAAK,GAAG,CAAA;AACjE","file":"index.js","sourcesContent":["// The copy a component tree uses, from a provider: the locale's built-in words with the tenant's overrides on top.\n\nimport {\n  type CopyOverrides,\n  createTranslate,\n  type Translate,\n  textDirection,\n} from '@vinaverse/tokens/copy';\nimport { createContext, type ReactNode, useContext, useMemo } from 'react';\n\nexport interface CopyContextValue {\n  readonly locale: string | undefined;\n  readonly direction: 'ltr' | 'rtl';\n  readonly t: Translate;\n}\n\nconst CopyContext = /* @__PURE__ */ createContext<CopyContextValue>({\n  locale: undefined,\n  direction: 'ltr',\n  t: /* @__PURE__ */ createTranslate(undefined),\n});\n\nexport function CopyProvider(props: {\n  readonly locale?: string | undefined;\n  readonly copy?: CopyOverrides | undefined;\n  readonly children?: ReactNode;\n}): ReactNode {\n  const { locale, copy, children } = props;\n  const value = useMemo<CopyContextValue>(\n    () => ({\n      locale,\n      direction: textDirection(locale),\n      t: createTranslate(locale, copy),\n    }),\n    [locale, copy],\n  );\n  return <CopyContext.Provider value={value}>{children}</CopyContext.Provider>;\n}\n\n/** The translator, the locale and its text direction. */\nexport function useCopy(): CopyContextValue {\n  return useContext(CopyContext);\n}\n","// The React bindings of the conversation store: thin by design. Every protocol rule lives in @vinaverse/client; these\n// hooks only subscribe, and re-render a component when the slice it reads changed.\n\nimport type {\n  ConversationView,\n  StreamingText,\n} from '@vinaverse/client/conversation';\nimport { useCallback, useRef, useSyncExternalStore } from 'react';\n\n/** What the hooks read: a conversation store, or anything with the same four members (a test's fake). */\nexport interface ConversationSource {\n  getSnapshot(): ConversationView;\n  subscribe(listener: () => void): () => void;\n  getStreaming(): StreamingText | null;\n  subscribeStreaming(listener: () => void): () => void;\n}\n\n/** The whole view; re-renders on every change of it. Prefer `useConversationSelector` in anything drawn often. */\nexport function useConversation(source: ConversationSource): ConversationView {\n  return useSyncExternalStore(\n    source.subscribe,\n    source.getSnapshot,\n    source.getSnapshot,\n  );\n}\n\n/**\n * A slice of the view; re-renders only when the slice changed by `isEqual` (default `Object.is`). The view is\n * structurally shared, so selecting `items`, one item, or a field compares by identity.\n */\nexport function useConversationSelector<T>(\n  source: ConversationSource,\n  selector: (view: ConversationView) => T,\n  isEqual: (a: T, b: T) => boolean = Object.is,\n): T {\n  const last = useRef<{ view: ConversationView; value: T } | null>(null);\n  const select = useRef(selector);\n  select.current = selector;\n  const compare = useRef(isEqual);\n  compare.current = isEqual;\n  const get = useCallback((): T => {\n    const view = source.getSnapshot();\n    const held = last.current;\n    if (held?.view === view) return held.value;\n    const value = select.current(view);\n    if (held && compare.current(held.value, value)) {\n      last.current = { view, value: held.value };\n      return held.value;\n    }\n    last.current = { view, value };\n    return value;\n  }, [source]);\n  return useSyncExternalStore(source.subscribe, get, get);\n}\n\n/**\n * The streamed text of the message with this `key`, or null when it is not the one streaming: only the streaming\n * bubble calls it, and only it re-renders as the reply arrives (at most once per frame).\n */\nexport function useStreamingText(\n  source: ConversationSource,\n  key: string,\n): string | null {\n  const get = useCallback(() => {\n    const streaming = source.getStreaming();\n    return streaming?.key === key ? streaming.text : null;\n  }, [source, key]);\n  return useSyncExternalStore(source.subscribeStreaming, get, get);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinaverse/react",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "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.",
@@ -29,6 +29,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./agent": {
+      "import": {
+        "types": "./dist/agent.d.ts",
+        "default": "./dist/agent.js"
+      },
+      "require": {
+        "types": "./dist/agent.d.cts",
+        "default": "./dist/agent.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
@@ -38,8 +48,8 @@
     "dist"
   ],
   "dependencies": {
-    "@vinaverse/client": "0.1.0-alpha.4",
-    "@vinaverse/tokens": "0.1.0-alpha.4"
+    "@vinaverse/client": "0.1.0-alpha.6",
+    "@vinaverse/tokens": "0.1.0-alpha.6"
   },
   "peerDependencies": {
     "react": ">=19.1"
@@ -57,11 +67,32 @@
         "react",
         "react/jsx-runtime",
         "@vinaverse/client",
-        "@vinaverse/tokens/copy"
+        "@vinaverse/tokens/copy",
+        "@vinaverse/client/agent"
+      ],
+      "limit": "1.5 kB"
+    },
+    {
+      "name": "@vinaverse/react/agent (ESM, everything; react and the other @vinaverse packages excluded)",
+      "path": "dist/agent.js",
+      "import": "*",
+      "ignore": [
+        "react",
+        "react/jsx-runtime",
+        "@vinaverse/client",
+        "@vinaverse/tokens/copy",
+        "@vinaverse/client/agent"
       ],
       "limit": "1.5 kB"
     }
   ],
+  "typesVersions": {
+    "*": {
+      "agent": [
+        "./dist/agent.d.cts"
+      ]
+    }
+  },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit -p tsconfig.json",