@vinaverse/react 0.0.0-stage → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @vinaverse/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React bindings of the Vinaverse conversation store (`@vinaverse/client/conversation`), and the copy and formatting
+every Vinaverse React UI shares. No `react-native` or DOM import: the same hooks serve React Native and the web. The
+styled React Native kit is `@vinaverse/react-native`.
+
+```tsx
+import { createConversation } from '@vinaverse/client/conversation';
+import { CopyProvider, useConversationSelector, useStreamingText } from '@vinaverse/react';
+
+const conversation = createConversation({ getSession: (req) => api.vinaverseSession(req), locale: 'es-US' });
+conversation.start();
+
+function Messages() {
+  const items = useConversationSelector(conversation, (v) => v.items); // re-renders only when items change
+  return items.map((item) => <Row key={item.key} item={item} />);
+}
+
+function Streaming({ id }: { id: string }) {
+  return <Text>{useStreamingText(conversation, id)}</Text>; // only this re-renders as the reply arrives
+}
+```
+
+- `useConversationSelector`, `useStreamingText`, `useConversation`: subscriptions, nothing more; every protocol rule
+  is in the store.
+- `CopyProvider` / `useCopy`: the words in English, Spanish and Brazilian Portuguese with the tenant's overrides on
+  top, from `@vinaverse/tokens/copy` (shared with the Angular kit and re-exported here with `createTranslate`,
+  `formatMoney`, `formatTimeRange`, `formatDate` and `textDirection`). The AI disclosure is never reworded in a
+  built-in language, and in another language only by a translation that still discloses.
+
+How it fits with the other kits: [docs/architecture/ui-kits.md](../../docs/architecture/ui-kits.md).
+
+## Install
+
+```sh
+npm install @vinaverse/react@alpha @vinaverse/client@alpha
+```
+
+Alphas are published under the `alpha` tag. Keep every `@vinaverse/*` package on the same version, so your app and the
+hooks share one copy of `@vinaverse/client`.
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+var copy = require('@vinaverse/tokens/copy');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/index.ts
+var CopyContext = react.createContext({
+  locale: void 0,
+  direction: "ltr",
+  t: copy.createTranslate(void 0)
+});
+function CopyProvider(props) {
+  const { locale, copy: copy$1, children } = props;
+  const value = react.useMemo(
+    () => ({
+      locale,
+      direction: copy.textDirection(locale),
+      t: copy.createTranslate(locale, copy$1)
+    }),
+    [locale, copy$1]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(CopyContext.Provider, { value, children });
+}
+function useCopy() {
+  return react.useContext(CopyContext);
+}
+function useConversation(source) {
+  return react.useSyncExternalStore(
+    source.subscribe,
+    source.getSnapshot,
+    source.getSnapshot
+  );
+}
+function useConversationSelector(source, selector, isEqual = Object.is) {
+  const last = react.useRef(null);
+  const select = react.useRef(selector);
+  select.current = selector;
+  const compare = react.useRef(isEqual);
+  compare.current = isEqual;
+  const get = react.useCallback(() => {
+    const view = source.getSnapshot();
+    const held = last.current;
+    if (held?.view === view) return held.value;
+    const value = select.current(view);
+    if (held && compare.current(held.value, value)) {
+      last.current = { view, value: held.value };
+      return held.value;
+    }
+    last.current = { view, value };
+    return value;
+  }, [source]);
+  return react.useSyncExternalStore(source.subscribe, get, get);
+}
+function useStreamingText(source, key) {
+  const get = react.useCallback(() => {
+    const streaming = source.getStreaming();
+    return streaming?.key === key ? streaming.text : null;
+  }, [source, key]);
+  return react.useSyncExternalStore(source.subscribeStreaming, get, get);
+}
+
+Object.defineProperty(exports, "AI_MARK", {
+  enumerable: true,
+  get: function () { return copy.AI_MARK; }
+});
+Object.defineProperty(exports, "BANNED_WORDS", {
+  enumerable: true,
+  get: function () { return copy.BANNED_WORDS; }
+});
+Object.defineProperty(exports, "COPY", {
+  enumerable: true,
+  get: function () { return copy.COPY; }
+});
+Object.defineProperty(exports, "bannedWordsIn", {
+  enumerable: true,
+  get: function () { return copy.bannedWordsIn; }
+});
+Object.defineProperty(exports, "builtInCopy", {
+  enumerable: true,
+  get: function () { return copy.builtInCopy; }
+});
+Object.defineProperty(exports, "createTranslate", {
+  enumerable: true,
+  get: function () { return copy.createTranslate; }
+});
+Object.defineProperty(exports, "formatDate", {
+  enumerable: true,
+  get: function () { return copy.formatDate; }
+});
+Object.defineProperty(exports, "formatMoney", {
+  enumerable: true,
+  get: function () { return copy.formatMoney; }
+});
+Object.defineProperty(exports, "formatTimeRange", {
+  enumerable: true,
+  get: function () { return copy.formatTimeRange; }
+});
+Object.defineProperty(exports, "textDirection", {
+  enumerable: true,
+  get: function () { return copy.textDirection; }
+});
+exports.CopyProvider = CopyProvider;
+exports.useConversation = useConversation;
+exports.useConversationSelector = useConversationSelector;
+exports.useCopy = useCopy;
+exports.useStreamingText = useStreamingText;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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"]}

package/dist/index.d.cts

@@ -0,0 +1,39 @@
+import { Translate, CopyOverrides } from '@vinaverse/tokens/copy';
+export { AI_MARK, BANNED_WORDS, COPY, Copy, CopyKey, CopyOverrides, Translate, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
+import { ReactNode } from 'react';
+import { ConversationView, StreamingText } from '@vinaverse/client/conversation';
+
+interface CopyContextValue {
+    readonly locale: string | undefined;
+    readonly direction: 'ltr' | 'rtl';
+    readonly t: Translate;
+}
+declare function CopyProvider(props: {
+    readonly locale?: string | undefined;
+    readonly copy?: CopyOverrides | undefined;
+    readonly children?: ReactNode;
+}): ReactNode;
+/** The translator, the locale and its text direction. */
+declare function useCopy(): CopyContextValue;
+
+/** What the hooks read: a conversation store, or anything with the same four members (a test's fake). */
+interface ConversationSource {
+    getSnapshot(): ConversationView;
+    subscribe(listener: () => void): () => void;
+    getStreaming(): StreamingText | null;
+    subscribeStreaming(listener: () => void): () => void;
+}
+/** The whole view; re-renders on every change of it. Prefer `useConversationSelector` in anything drawn often. */
+declare function useConversation(source: ConversationSource): ConversationView;
+/**
+ * A slice of the view; re-renders only when the slice changed by `isEqual` (default `Object.is`). The view is
+ * structurally shared, so selecting `items`, one item, or a field compares by identity.
+ */
+declare function useConversationSelector<T>(source: ConversationSource, selector: (view: ConversationView) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * The streamed text of the message with this `key`, or null when it is not the one streaming: only the streaming
+ * bubble calls it, and only it re-renders as the reply arrives (at most once per frame).
+ */
+declare function useStreamingText(source: ConversationSource, key: string): string | null;
+
+export { type ConversationSource, type CopyContextValue, CopyProvider, useConversation, useConversationSelector, useCopy, useStreamingText };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { Translate, CopyOverrides } from '@vinaverse/tokens/copy';
+export { AI_MARK, BANNED_WORDS, COPY, Copy, CopyKey, CopyOverrides, Translate, bannedWordsIn, builtInCopy, createTranslate, formatDate, formatMoney, formatTimeRange, textDirection } from '@vinaverse/tokens/copy';
+import { ReactNode } from 'react';
+import { ConversationView, StreamingText } from '@vinaverse/client/conversation';
+
+interface CopyContextValue {
+    readonly locale: string | undefined;
+    readonly direction: 'ltr' | 'rtl';
+    readonly t: Translate;
+}
+declare function CopyProvider(props: {
+    readonly locale?: string | undefined;
+    readonly copy?: CopyOverrides | undefined;
+    readonly children?: ReactNode;
+}): ReactNode;
+/** The translator, the locale and its text direction. */
+declare function useCopy(): CopyContextValue;
+
+/** What the hooks read: a conversation store, or anything with the same four members (a test's fake). */
+interface ConversationSource {
+    getSnapshot(): ConversationView;
+    subscribe(listener: () => void): () => void;
+    getStreaming(): StreamingText | null;
+    subscribeStreaming(listener: () => void): () => void;
+}
+/** The whole view; re-renders on every change of it. Prefer `useConversationSelector` in anything drawn often. */
+declare function useConversation(source: ConversationSource): ConversationView;
+/**
+ * A slice of the view; re-renders only when the slice changed by `isEqual` (default `Object.is`). The view is
+ * structurally shared, so selecting `items`, one item, or a field compares by identity.
+ */
+declare function useConversationSelector<T>(source: ConversationSource, selector: (view: ConversationView) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * The streamed text of the message with this `key`, or null when it is not the one streaming: only the streaming
+ * bubble calls it, and only it re-renders as the reply arrives (at most once per frame).
+ */
+declare function useStreamingText(source: ConversationSource, key: string): string | null;
+
+export { type ConversationSource, type CopyContextValue, CopyProvider, useConversation, useConversationSelector, useCopy, useStreamingText };

package/dist/index.js

@@ -0,0 +1,64 @@
+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 { jsx } from 'react/jsx-runtime';
+
+// src/index.ts
+var CopyContext = createContext({
+  locale: void 0,
+  direction: "ltr",
+  t: createTranslate(void 0)
+});
+function CopyProvider(props) {
+  const { locale, copy, children } = props;
+  const value = useMemo(
+    () => ({
+      locale,
+      direction: textDirection(locale),
+      t: createTranslate(locale, copy)
+    }),
+    [locale, copy]
+  );
+  return /* @__PURE__ */ jsx(CopyContext.Provider, { value, children });
+}
+function useCopy() {
+  return useContext(CopyContext);
+}
+function useConversation(source) {
+  return useSyncExternalStore(
+    source.subscribe,
+    source.getSnapshot,
+    source.getSnapshot
+  );
+}
+function useConversationSelector(source, selector, isEqual = Object.is) {
+  const last = useRef(null);
+  const select = useRef(selector);
+  select.current = selector;
+  const compare = useRef(isEqual);
+  compare.current = isEqual;
+  const get = useCallback(() => {
+    const view = source.getSnapshot();
+    const held = last.current;
+    if (held?.view === view) return held.value;
+    const value = select.current(view);
+    if (held && compare.current(held.value, value)) {
+      last.current = { view, value: held.value };
+      return held.value;
+    }
+    last.current = { view, value };
+    return value;
+  }, [source]);
+  return useSyncExternalStore(source.subscribe, get, get);
+}
+function useStreamingText(source, key) {
+  const get = useCallback(() => {
+    const streaming = source.getStreaming();
+    return streaming?.key === key ? streaming.text : null;
+  }, [source, key]);
+  return useSyncExternalStore(source.subscribeStreaming, get, get);
+}
+
+export { CopyProvider, useConversation, useConversationSelector, useCopy, useStreamingText };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@vinaverse/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.2",
+  "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.",
+  "homepage": "https://github.com/vinaverse-ai/vinaverse-js/tree/develop/packages/react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vinaverse-ai/vinaverse-js.git",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/vinaverse-ai/vinaverse-js/issues",
+  "keywords": [
+    "vinaverse",
+    "react",
+    "hooks"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@vinaverse/client": "0.1.0-alpha.2",
+    "@vinaverse/tokens": "0.1.0-alpha.2"
+  },
+  "peerDependencies": {
+    "react": ">=19.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "size-limit": [
+    {
+      "name": "@vinaverse/react (ESM, everything; react and the other @vinaverse packages excluded)",
+      "path": "dist/index.js",
+      "import": "*",
+      "ignore": [
+        "react",
+        "react/jsx-runtime",
+        "@vinaverse/client",
+        "@vinaverse/tokens/copy"
+      ],
+      "limit": "1.5 kB"
+    }
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "package:check": "publint --strict && attw --pack . && size-limit"
+  }
 }