@qorejs/qore 1.0.6 → 2.0.0

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Qore is a small runtime with four layers.
+Qore owns streamed state. Host frameworks own rendering and component lifecycle.
 
 ```text
 Provider / AsyncIterable
@@ -9,49 +9,51 @@ Provider / AsyncIterable
 Qore Stream Runtime
         |
         v
-Readonly Signal
+Readonly state + subscriptions
         |
-        v
-DOM Binding
+        +--> React adapter --> React components
+        +--> Host framework integration
+        +--> Optional DOM renderer --> text nodes
 ```
 
-## Provider / AsyncIterable
-
-Providers expose streaming data as async iterables. Qore ships adapters for OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, generic SSE, and generic line-delimited streams.
-
-Adapters should run on the server or another trusted runtime when they need API keys.
-
-## Stream Runtime
+## Package boundaries
 
-The stream runtime owns:
+- `@qorejs/qore`: accumulation, stream lifecycle, event projections, backpressure,
+  async iteration, and stream inspection.
+- `@qorejs/qore/react`: React external-store hooks with cached snapshots and cleanup.
+- `@qorejs/qore/dom`: optional browser-only rendering, lists, mounting and DOM properties.
+- `@qorejs/qore/signals`: optional mutable signals, computed values, effects and scopes.
+- `@qorejs/qore/providers`: optional vendor and generic SSE/NDJSON adapters.
+- `@qorejs/qore/server`: optional SSE response serialization.
 
-- lifecycle: `idle`, `streaming`, `completed`, `failed`, `aborted`
-- abort propagation
-- retry and resume contracts for hosted SSE providers
-- backpressure buffering
-- async iterator bridging
-- reducer-based accumulation
-- development-time stream inspection through `globalThis.__QORE_DEVTOOLS__`
+These are independently importable subpaths in one package. Core has no runtime
+import of DOM, provider, server or React entrypoints. React is an optional peer,
+so non-React users do not need to install it.
 
-## Readonly Signal
-
-Every `QoreStream` is a readonly signal:
-
-```js
-const answer = stream(model.chat('hello'));
-answer();
-```
+## Internal state
 
-Users can observe stream state, but they cannot mutate runtime-owned fields such as `status`, `chunks`, or `error`.
+The runtime still uses the existing reactive engine internally. Moving its public
+UI primitives to `/signals` avoids requiring applications to adopt a second state
+API. It does not claim that dependency tracking has been removed from the runtime.
+The DOM renderer and stream core share the same engine instance.
 
-## DOM Binding
+Streams expose readonly values through `answer()`, `peek()` and `subscribe()`;
+applications cannot write the runtime-owned lifecycle fields. Subscription cleanup
+and stream cancellation are distinct: observing an externally owned stream does
+not transfer ownership. The React managed hook aborts the streams it creates.
 
-The DOM layer is intentionally direct. `text(() => answer())` subscribes to the signal and updates a text node.
+## Integration boundaries
 
-There is no virtual DOM path on the hot streaming update.
+Provider API keys belong on a server or trusted runtime. Browsers consume an
+application endpoint. `/server` can serialize that endpoint as SSE.
 
-## Server Boundary
+React supplies its renderer and hydration. Managed hooks start work in client
+effects; snapshot hooks provide deterministic server fallbacks. Qore's optional
+DOM renderer has no SSR or hydration implementation, and adding a full framework
+stack is outside the current roadmap.
 
-Qore includes `createSSEResponse(...)` so applications can produce server-side streams and consume them with the same client runtime.
+## Resource limits
 
-The DOM layer is browser-only in `1.0.x`; SSR and hydration are explicit future work.
+`maxItems` bounds collection values, not full chunk history or iterator backlog.
+Backpressure governs the producer buffer. Do not treat either option as a total
+memory bound; retention and multicasting semantics remain separate runtime work.

package/docs/comparisons.md

@@ -1,35 +1,38 @@
 # Comparisons
 
-Qore's target is not "another UI framework." Its target is streamed interface state.
+Qore focuses on streamed interface state and integrates with existing UI frameworks.
 
 ## React / Vercel AI SDK
 
-React and the Vercel AI SDK are strong tools for React applications. They still normally route streamed data through React state and render scheduling.
+The Qore React adapter exposes streams through `useSyncExternalStore`. Updates
+still use React rendering and reconciliation. Qore adds stream lifecycle and event
+projection contracts; it does not make React render like a direct DOM renderer.
 
-```text
-React / Vercel AI SDK:
-Token -> Hook state -> Component render -> Reconcile
+The optional `/dom` renderer can update a dependent text node directly. That is a
+separate integration path, not a property of all Qore integrations.
 
-Qore:
-Token -> Stream signal -> Text node
-```
+## Solid and Vue
 
-Qore avoids snapshot-style transcript rewrites. That is the runtime distinction.
-
-## Solid
-
-Solid has excellent fine-grained reactivity. Qore's difference is the native stream primitive: a stream is already a signal and an async iterable.
-
-## Vue
-
-Vue refs are ergonomic, but provider streams still need to be adapted into state by user code. Qore makes that adaptation the default primitive.
+Their reactive systems already own application state and rendering. Applications
+can bridge Qore subscriptions into native signals or refs and dispose subscriptions
+with their framework lifecycle. They do not need Qore's optional `/signals` or
+`/dom` APIs. Qore's responsibility is stream consumption and lifecycle.
 
 ## RxJS
 
-RxJS is a powerful observable toolkit. Qore is smaller and UI-directed: the result of stream composition is still a readonly signal that can bind directly to a DOM node.
+Stream composition overlaps with observable libraries. Qore's particular contract
+combines the current accumulated value, subscriptions, async iteration and lifecycle.
+Choose based on required stream semantics and integration costs.
 
 ## When Not To Use Qore
 
-Do not use Qore as a replacement for a full app framework if you need routing, forms, UI component catalogs, or a large ecosystem surface.
+An existing application with adequate stream handling may not need another runtime.
+Qore does not provide routing, forms, an application component ecosystem, or its own
+SSR/hydration stack. The standalone DOM renderer is optional.
+
+## Benchmark Language
 
-Use Qore where the hard part is streamed data becoming reactive interface state.
+The current benchmark compares fine-grained stream updates with snapshot-style
+transcript rewrites. It is not an optimized React, Vue or Solid comparison and does
+not establish a framework-wide performance ranking. Measure real workloads,
+including parsing, rendering, interaction latency and retained memory.

package/docs/concepts.md

@@ -10,19 +10,9 @@ A stream is how data moves. A signal is how UI reacts. Qore treats them as one r
 
 ## The Problem
 
-Most UI frameworks start with a snapshot model:
-
-```text
-fetch -> state snapshot -> render
-```
-
-AI and realtime interfaces are different. The useful data often arrives as a sequence:
-
-```text
-token -> token -> tool event -> status -> token -> done
-```
-
-If each chunk has to be copied into component state, reconciled, and rerendered as a transcript snapshot, the runtime path becomes wider than the problem needs.
+AI and realtime interfaces receive sequences of tokens, tool events, status,
+diffs and terminal events. A runtime can centralize accumulation and lifecycle
+while the existing UI framework continues to manage components and rendering.
 
 ## The Qore Model
 
@@ -43,9 +33,11 @@ The same value is:
 - an async iterable
 - a lifecycle-aware stream state
 
-That means a UI can bind directly to streamed data:
+The optional `@qorejs/qore/dom` renderer can bind directly to streamed data:
 
 ```js
+import { h, text } from '@qorejs/qore/dom';
+
 h('article', {}, text(() => answer()));
 ```
 

package/docs/providers.md

@@ -45,7 +45,8 @@ Supported adapters:
 ## Example
 
 ```js
-import { createOpenAI, stream } from '@qorejs/qore';
+import { createOpenAI } from '@qorejs/qore/providers';
+import { stream } from '@qorejs/qore';
 
 const openai = createOpenAI({
   apiKey: process.env.OPENAI_API_KEY,
@@ -56,3 +57,20 @@ const answer = stream(openai.chat('Explain stream = signal'));
 ```
 
 Keep this code on the server when it uses real secrets.
+
+
+## Server Boundary
+
+Provider adapters are designed for server-side or otherwise trusted runtimes. A browser application should not receive provider API keys. The recommended production path is:
+
+```text
+Browser UI -> your SSE / NDJSON endpoint -> provider adapter -> model provider
+```
+
+Then the browser consumes your endpoint as a Qore stream:
+
+```ts
+const answer = stream(fetch('/api/agent').then((response) => response.body));
+```
+
+For a complete application boundary example, see [`examples/server-sse-to-qore-client.ts`](../examples/server-sse-to-qore-client.ts).

package/docs/react.md

@@ -2,11 +2,11 @@
 
 Qore's core runtime is framework-neutral. The React adapter lets React apps consume Qore streams without treating streaming as a special rendering case.
 
-> Status: the adapter is release-ready in [`packages/react`](../packages/react), but the npm package is not published yet. Publishing currently fails with npm `E404` for `@qorejs/react`, which means the `@qorejs` npm scope/package access still needs to be provisioned before the install command below becomes valid.
+The hooks ship with Qore 2 at `@qorejs/qore/react`. The separate
+`@qorejs/react` package is an unpublished compatibility wrapper, not an installation requirement.
 
 ```bash
-# Available after npm package access is provisioned.
-npm i @qorejs/qore @qorejs/react
+npm i @qorejs/qore react react-dom
 ```
 
 ## Why It Exists
@@ -30,7 +30,7 @@ Use `useQoreStream` when a component owns the stream lifecycle.
 
 ```tsx
 import { stream } from '@qorejs/qore';
-import { useQoreStream } from '@qorejs/react';
+import { useQoreStream } from '@qorejs/qore/react';
 
 export function Answer({ prompt }: { prompt: string }) {
   const answer = useQoreStream(
@@ -57,7 +57,7 @@ Use `useQoreStreamSnapshot` when the stream is created outside React and the com
 
 ```tsx
 import type { QoreStream } from '@qorejs/qore';
-import { useQoreStreamSnapshot } from '@qorejs/react';
+import { useQoreStreamSnapshot } from '@qorejs/qore/react';
 
 export function Transcript({ answer }: { answer: QoreStream<string, string> }) {
   const snapshot = useQoreStreamSnapshot(answer, { initialValue: '' });
@@ -74,7 +74,7 @@ Use `useQoreSignalSelector` when a React component only needs one derived slice
 
 ```tsx
 import type { QoreStream } from '@qorejs/qore';
-import { useQoreSignalSelector } from '@qorejs/react';
+import { useQoreSignalSelector } from '@qorejs/qore/react';
 
 function TokenCounter({ answer }: { answer: QoreStream<string, string> }) {
   const tokenCount = useQoreSignalSelector(answer.chunks, (chunks) => chunks.length);
@@ -90,7 +90,7 @@ Use `useQoreSignal` for any Qore readonly signal.
 
 ```tsx
 import type { ReadonlySignal } from '@qorejs/qore';
-import { useQoreSignal } from '@qorejs/react';
+import { useQoreSignal } from '@qorejs/qore/react';
 
 export function Counter({ count }: { count: ReadonlySignal<number> }) {
   const value = useQoreSignal(count);
@@ -103,3 +103,19 @@ export function Counter({ count }: { count: ReadonlySignal<number> }) {
 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.
+
+## Snapshot and rendering contract
+
+The adapter caches emitted snapshots so repeated React reads receive the same
+reference, including stream chunk arrays. Subscription setup reads the current
+source through immediate delivery, covering updates between render and subscribe.
+Selectors may use `isEqual` to retain an equivalent selected value.
+
+`useQoreStreamSnapshot` uses `initialValue` and idle lifecycle fields during server
+rendering and hydration. Network work for `useQoreStream` starts in an effect on the
+client. For `useQoreSignal` and selectors, supply `getServerSnapshot` when the server
+value differs from the client source. Keep request-specific streams out of shared
+server globals. These hooks do not bypass React rendering.
+
+`maxItems` bounds a collection's displayed value, not its retained chunk history
+or iterator queue. This release does not introduce bounded total stream memory.

package/docs/runtime.md

@@ -50,6 +50,55 @@ stream.switchMap(promptChanges, (prompt) => openai.chat(prompt));
 
 The composed result is still a stream signal.
 
+## Structured JSON
+
+AI providers increasingly return structured output as streamed text. Keep that
+boundary reactive too:
+
+```ts
+const result = stream.json<{ title: string; items: string[] }>(provider.chat(prompt), {
+  validate(value): value is { title: string; items: string[] } {
+    return typeof value === 'object'
+      && value !== null
+      && 'title' in value
+      && 'items' in value;
+  }
+});
+
+result(); // null until valid JSON is available, then the parsed object
+```
+
+`stream.json()` parses the accumulated text after each chunk. It publishes valid
+JSON as signal state and fails the stream if the source completes without valid
+JSON. It intentionally does not pretend that arbitrary half-written JSON can be
+parsed safely.
+
+For event streams that arrive as line-delimited JSON, use `stream.ndjson()`:
+
+```ts
+const events = stream.ndjson<{ type: string; value: unknown }>(agentEvents);
+
+events(); // accumulated structured events
+```
+
+Each valid line is published as a chunk and added to the signal array. Blank
+lines are ignored, and an invalid final line fails the stream while keeping the
+events that were already safely published.
+
+## Bounded Collections
+
+Agent timelines, logs, and tool-event feeds can run much longer than a chat
+answer. Use `maxItems` when the UI only needs the latest window:
+
+```ts
+const timeline = stream.events(agent.run(task), { maxItems: 200 });
+const logs = stream.ndjson(logSource, { maxItems: 500 });
+const rows = stream.list(rowSource, { maxItems: 100 });
+```
+
+The current signal value keeps the newest items. Async iteration, chunk history,
+and `chunkCount()` still reflect the full stream lifecycle.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qorejs/qore",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "description": "Qore is a reactive stream runtime for AI-native interfaces.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -10,14 +10,35 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./signals": {
+      "types": "./dist/src/signals.d.ts",
+      "import": "./dist/src/signals.js"
+    },
+    "./dom": {
+      "types": "./dist/src/dom.d.ts",
+      "import": "./dist/src/dom.js"
+    },
+    "./providers": {
+      "types": "./dist/src/providers.d.ts",
+      "import": "./dist/src/providers.js"
+    },
+    "./server": {
+      "types": "./dist/src/server.d.ts",
+      "import": "./dist/src/server.js"
+    },
+    "./react": {
+      "types": "./dist/src/react.d.ts",
+      "import": "./dist/src/react.js"
+    }
   },
   "files": [
     "dist/src",
     "README.md",
     "README.zh-CN.md",
     "docs",
-    "LICENSE"
+    "LICENSE",
+    "MIGRATION.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -58,7 +79,6 @@
     "anthropic",
     "deepseek",
     "ollama",
-    "framework",
     "async-iterable"
   ],
   "homepage": "https://qorejs.dev/",
@@ -77,7 +97,18 @@
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.25.12",
     "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }