@qorejs/qore 1.0.0 → 1.0.2

package/docs/react.md

@@ -0,0 +1,102 @@
+# React Adapter
+
+Qore's core runtime is framework-neutral. The React adapter lets React apps consume Qore streams without treating streaming as a special rendering case.
+
+```bash
+npm i @qorejs/qore @qorejs/react
+```
+
+## Why It Exists
+
+React is still the UI shell for many production AI products. Qore should not force those teams to switch renderers before they can use `stream = signal`.
+
+The adapter keeps Qore in the streaming runtime layer:
+
+```text
+Provider / AsyncIterable
+  -> QoreStream
+  -> React external store
+  -> Component view
+```
+
+A `QoreStream` remains the source of truth. React subscribes to it through `useSyncExternalStore`, which is the React-supported bridge for external reactive stores.
+
+## useQoreStream
+
+Use `useQoreStream` when a component owns the stream lifecycle.
+
+```tsx
+import { stream } from '@qorejs/qore';
+import { useQoreStream } from '@qorejs/react';
+
+export function Answer({ prompt }: { prompt: string }) {
+  const answer = useQoreStream(
+    () => stream(fetch(`/api/chat?prompt=${encodeURIComponent(prompt)}`).then((response) => response.body)),
+    [prompt],
+    { initialValue: '' }
+  );
+
+  return (
+    <article>
+      <p>{answer.value}</p>
+      <small>{answer.status}</small>
+      <button onClick={() => answer.abort()}>Stop</button>
+    </article>
+  );
+}
+```
+
+When dependencies change, the hook aborts the previous stream and starts a new one. When the component unmounts, the active stream is aborted. Pass `{ enabled: false }` to keep the hook subscribed to an idle snapshot without starting network work.
+
+## useQoreStreamSnapshot
+
+Use `useQoreStreamSnapshot` when the stream is created outside React and the component only needs a live snapshot.
+
+```tsx
+import type { QoreStream } from '@qorejs/qore';
+import { useQoreStreamSnapshot } from '@qorejs/react';
+
+export function Transcript({ answer }: { answer: QoreStream<string, string> }) {
+  const snapshot = useQoreStreamSnapshot(answer, { initialValue: '' });
+
+  return <p>{snapshot.value}</p>;
+}
+```
+
+The returned object includes the stream value plus lifecycle fields such as `status`, `error`, `chunks`, `streaming`, `completed`, `failed`, `aborted`, `buffered`, and `dropped`.
+
+## useQoreSignalSelector
+
+Use `useQoreSignalSelector` when a React component only needs one derived slice of a Qore signal. The selector keeps React renders focused on the value that component actually reads.
+
+```tsx
+import type { QoreStream } from '@qorejs/qore';
+import { useQoreSignalSelector } from '@qorejs/react';
+
+function TokenCounter({ answer }: { answer: QoreStream<string, string> }) {
+  const tokenCount = useQoreSignalSelector(answer.chunks, (chunks) => chunks.length);
+  return <span>{tokenCount}</span>;
+}
+```
+
+Pass `isEqual` when the selected value is an object and you want to preserve the previous reference until the meaningful fields change.
+
+## useQoreSignal
+
+Use `useQoreSignal` for any Qore readonly signal.
+
+```tsx
+import type { ReadonlySignal } from '@qorejs/qore';
+import { useQoreSignal } from '@qorejs/react';
+
+export function Counter({ count }: { count: ReadonlySignal<number> }) {
+  const value = useQoreSignal(count);
+  return <span>{value}</span>;
+}
+```
+
+## Safety Notes
+
+Provider adapters are still intended for server-side or trusted runtimes. In browser React apps, stream from your own SSE or NDJSON endpoint instead of exposing provider API keys.
+
+Keep dependency arrays honest. If the stream factory reads `prompt`, `model`, `conversationId`, or auth/session state, include those values in the dependency list.

package/docs/runtime.md

@@ -0,0 +1,86 @@
+# Runtime
+
+The stream runtime is the core of Qore.
+
+## Lifecycle
+
+Every `QoreStream` exposes readonly lifecycle signals:
+
+```js
+answer.status();     // idle | pending | streaming | completed | failed | aborted
+answer.error();      // Error | null
+answer.chunkCount(); // number
+answer.buffered();   // queued chunks
+answer.dropped();    // dropped chunks
+```
+
+Runtime-owned state is readonly from user code, so external callers cannot force inconsistent states.
+
+## Backpressure
+
+```js
+const answer = stream.withBackpressure(source, {
+  interval: 16,
+  buffer: 8,
+  overflow: 'drop-oldest'
+});
+```
+
+Backpressure controls how quickly chunks commit into the signal and UI.
+
+Overflow strategies:
+
+- `wait`
+- `drop-oldest`
+- `drop-newest`
+- `error`
+
+## Orchestration
+
+Qore includes stream composition primitives for agent and realtime flows:
+
+```js
+stream.merge([tokens, toolCalls, status]);
+stream.concat([retrieve, summarize, format]);
+stream.pipe(retrieve, [(docs) => summarize(docs), (summary) => format(summary)]);
+stream.race([openai.chat(q), anthropic.chat(q)]);
+stream.retryable(() => openai.chat(q), { maxRetries: 2 });
+stream.switchMap(promptChanges, (prompt) => openai.chat(prompt));
+```
+
+The composed result is still a stream signal.
+
+## Event Streams
+
+Provider streams are only the transport boundary. Agent interfaces need a richer runtime surface: text tokens, tool calls, status updates, reasoning notes, diffs, artifacts, retries, and errors can all be modeled as typed events.
+
+```js
+const events = stream.events(agent.run(task));
+
+const markdown = events.select('text', {
+  seed: '',
+  reduce: (current, event) => current + event.text
+});
+const toolCalls = events.select('tool_call');
+const status = events.select('status');
+const diffs = events.select('diff', {
+  seed: '',
+  reduce: (current, event) => current + event.patch
+});
+```
+
+The full event timeline remains available through `events()`. Each selector is also a stream signal, so one UI region can render the timeline while another region renders only the accumulated markdown or diff.
+
+A complete typed example lives in [`examples/agent-event-stream.ts`](../examples/agent-event-stream.ts). It projects one agent event timeline into markdown, status, tool-call, tool-result, diff, and artifact surfaces without creating separate state stores.
+
+## Abort
+
+Streams can be aborted from the Qore stream object or from provider request options:
+
+```js
+const controller = new AbortController();
+const answer = stream(openai.chat('hello', { signal: controller.signal }));
+
+controller.abort();
+answer.abort();
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qorejs/qore",
-  "version": "1.0.0",
-  "description": "Qore is a streaming-response framework where stream becomes signal.",
+  "version": "1.0.2",
+  "description": "Qore is a reactive stream runtime for AI-native interfaces.",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -15,6 +15,8 @@
   "files": [
     "dist/src",
     "README.md",
+    "README.zh-CN.md",
+    "docs",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -36,7 +38,9 @@
     "publish:preflight": "node ./scripts/publish-preflight.mjs",
     "publish:github": "npm publish --registry=https://npm.pkg.github.com",
     "publish:npm": "node ./scripts/publish-npm.mjs",
-    "prepublishOnly": "node ./scripts/release-check.mjs"
+    "prepublishOnly": "node ./scripts/release-check.mjs",
+    "smoke:react-package": "node ./scripts/react-package-smoke.mjs",
+    "check:npm-access": "node ./scripts/check-npm-access.mjs"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -72,6 +76,8 @@
   "devDependencies": {
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.6.0",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
     "typescript": "^6.0.3"
   }
 }