@qorejs/qore 0.7.2 → 0.9.0

package/README.md

@@ -1,6 +1,7 @@
 # Qore
 
 [![npm version](https://img.shields.io/npm/v/%40qorejs%2Fqore?color=0f766e&label=npm)](https://www.npmjs.com/package/@qorejs/qore)
+[![latest release](https://img.shields.io/github/v/release/qorejs/qore?color=0f766e&label=release)](https://github.com/qorejs/qore/releases/latest)
 [![ci](https://github.com/qorejs/qore/actions/workflows/ci.yml/badge.svg)](https://github.com/qorejs/qore/actions/workflows/ci.yml)
 [![browser smoke](https://img.shields.io/badge/browser-smoke-playwright-45ba63)](#browser-regression)
 [![release checks](https://github.com/qorejs/qore/actions/workflows/release-check.yml/badge.svg)](https://github.com/qorejs/qore/actions/workflows/release-check.yml)
@@ -16,7 +17,9 @@ Instead of treating data as a snapshot, Qore treats it like a river. Tokens arri
 Quick links:
 
 - [npm package](https://www.npmjs.com/package/@qorejs/qore)
+- [latest release](https://github.com/qorejs/qore/releases/latest)
 - [GitHub Packages](https://github.com/qorejs/qore/packages)
+- [migration notes](./MIGRATION.md)
 - [landing page source](https://github.com/qorejs/qore/blob/main/index.html)
 - [streaming demo source](https://github.com/qorejs/qore/blob/main/examples/streaming-response.html)
 - [benchmark page](https://github.com/qorejs/qore/blob/main/examples/benchmark.html)
@@ -42,6 +45,15 @@ npm i @qorejs/qore
 
 GitHub Packages installs require an authenticated session against `https://npm.pkg.github.com`.
 
+For maintainers, the local npm release path now includes a fast preflight:
+
+```bash
+npm run publish:preflight
+npm run publish:npm
+```
+
+The preflight checks npm auth, confirms the changelog matches `package.json`, and fails early if that exact version is already published.
+
 - Package name: `@qorejs/qore`
 - Module format: `ESM`
 - Supported runtime: `Node >= 18`
@@ -51,6 +63,19 @@ GitHub Packages installs require an authenticated session against `https://npm.p
   - npm: [npmjs.com/package/@qorejs/qore](https://www.npmjs.com/package/@qorejs/qore)
   - GitHub Packages: [github.com/qorejs/qore/packages](https://github.com/qorejs/qore/packages)
 
+## Compatibility Matrix
+
+| Surface | Status | Notes |
+| --- | --- | --- |
+| Node runtime | Supported | `Node >= 18` |
+| Browser runtime | Supported | browser DOM entrypoints require `document` |
+| Reactive core | Supported | `signal`, `computed`, `effect`, `batch`, `createRoot`, `onCleanup` |
+| Stream runtime | Supported | includes backpressure, retry, orchestration, async iteration, and abort |
+| Provider adapters | Supported | OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, generic SSE, generic line-stream |
+| Browser DOM layer | Supported | `h`, `text`, `dynamic`, `list`, `mount`, `createApp(...).mount(...)` |
+| SSR | Not supported | explicit browser-only DOM boundary in `1.0.x` |
+| Hydration | Not supported | deferred until a fully proven implementation exists |
+
 ## Core Idea
 
 `stream` is how data flows.
@@ -73,6 +98,17 @@ Here, `answer` is all of the following at once:
 - An `AsyncIterable`, so you can still use `for await...of`
 - A lifecycle-aware streaming state, with `status()`, `streaming()`, `error()`, and `chunks()`
 
+## Performance Model
+
+Qore keeps the streaming hot path narrow:
+
+- chunk commits append into an internal log instead of cloning the full history on every token
+- public `chunks()` reads still return defensive copies, so consumers cannot corrupt runtime state
+- `chunkCount()` tracks the internal log version directly, so status UIs can stay cheap during long generations
+- DOM bindings update only the nodes that read the stream signal
+
+That means a long AI answer can keep flowing through one signal and one text node without turning every token into a full transcript rewrite.
+
 ## Why Qore
 
 - React treats streaming as a special case that needs extra machinery
@@ -124,6 +160,57 @@ const anthropic = createAnthropic({
 const answer = stream(anthropic.chat('Why should stream be signal?'));
 ```
 
+### `createOpenRouter(options?)`
+
+```js
+import { createOpenRouter, stream } from '@qorejs/qore';
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: 'openai/gpt-4.1-mini'
+});
+
+const answer = stream(openrouter.chat('Why should stream be signal?'));
+```
+
+### `createDeepSeek(options?)`
+
+```js
+import { createDeepSeek, stream } from '@qorejs/qore';
+
+const deepseek = createDeepSeek({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  model: 'deepseek-chat'
+});
+
+const answer = stream(deepseek.chat('Why should stream be signal?'));
+```
+
+Provider adapters also accept a request `signal` so you can cancel in-flight streams explicitly:
+
+```js
+const controller = new AbortController();
+const answer = stream(openrouter.chat('Keep streaming', {
+  signal: controller.signal
+}));
+
+controller.abort('user navigated away');
+```
+
+### `createOllama(options?)`
+
+If you want a local-first provider path, Qore can stream directly from Ollama:
+
+```js
+import { createOllama, stream } from '@qorejs/qore';
+
+const ollama = createOllama({
+  model: 'llama3.2'
+});
+
+const answer = stream(ollama.chat('Why should stream be signal?'));
+```
+
 ### `createSSEAdapter(options?)`
 
 If your backend already streams `text/event-stream`, Qore can adopt it directly:
@@ -153,6 +240,63 @@ const answer = stream(provider.chat('hello'));
 
 That makes `stream(provider.chat(...))` a general entry point instead of something tied to a single SDK.
 
+### `createLineAdapter(options?)`
+
+If your backend streams newline-delimited JSON instead of `text/event-stream`, Qore can adopt that too:
+
+```js
+import { createLineAdapter, stream } from '@qorejs/qore';
+
+const provider = createLineAdapter({
+  name: 'Local NDJSON Chat',
+  url: 'http://localhost:11434/api/chat',
+  buildRequest(request) {
+    return {
+      method: 'POST',
+      body: JSON.stringify(request)
+    };
+  },
+  buildChatRequest(input) {
+    return {
+      model: 'llama3.2',
+      messages: [{ role: 'user', content: input }]
+    };
+  },
+  lineToText(event) {
+    return typeof event.data?.message?.content === 'string'
+      ? event.data.message.content
+      : undefined;
+  }
+});
+
+const answer = stream(provider.chat('hello'));
+```
+
+## Provider Support Matrix
+
+| Adapter | Transport | Status | Notes |
+| --- | --- | --- | --- |
+| `createOpenAI(...)` | SSE | Supported | OpenAI Responses streaming |
+| `createAnthropic(...)` | SSE | Supported | Anthropic Messages streaming |
+| `createOpenRouter(...)` | SSE | Supported | chat-completions style SSE |
+| `createDeepSeek(...)` | SSE | Supported | chat-completions style SSE |
+| `createOllama(...)` | line-stream / NDJSON | Supported | local-first model path |
+| `createSSEAdapter(...)` | SSE | Supported | generic hosted or self-managed SSE |
+| `createLineAdapter(...)` | line-stream / NDJSON | Supported | generic line-delimited transport |
+
+Common guarantees across supported adapters:
+
+- async iterable text streaming
+- request `signal` support for cancellation
+- typed event streaming on provider-specific surfaces
+- package smoke coverage
+
+Additional hosted SSE guarantees:
+
+- retry contract support
+- `Last-Event-ID` resume support
+- normalized metadata helpers for usage, finish reason, response id, and model identity
+
 ## API Shape
 
 ### `stream(source, options?)`
@@ -176,6 +320,80 @@ const events = stream.list(eventSource);
 const latest = stream.latest(modelEvents);
 ```
 
+For append-heavy DOM lists such as chat transcripts, pass a stable key:
+
+```js
+list(messages, (message) => h('article', {}, message.body), {
+  key: (message) => message.id
+});
+```
+
+## Server-Side SSE
+
+If you want Qore to produce the server stream as well:
+
+```js
+import { createSSEResponse } from '@qorejs/qore';
+
+export function handler() {
+  return createSSEResponse(['hello', ' world']);
+}
+```
+
+If you need orchestration:
+
+```js
+const merged = stream.merge([openai.chat('a'), anthropic.chat('b')]);
+const scripted = stream.concat([retrieve.chat('a'), summarize.chat('a')]);
+const pipeline = stream.pipe(openai.chat('hello'), [
+  (draft) => review.chat(draft),
+  (reviewed) => format.chat(reviewed)
+]);
+const fastest = stream.race([openai.chat('hello'), openrouter.chat('hello')]);
+const resilient = stream.retryable(() => openai.chat('retry me'), {
+  maxRetries: 2,
+  backoff: 'exponential'
+});
+const liveAnswer = stream.switchMap(promptChanges, (prompt) => openai.chat(prompt));
+```
+
+Provider adapters can also retry dropped SSE connections and resume from the last event id:
+
+```js
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  retry: {
+    maxAttempts: 3,
+    backoff: 'exponential'
+  }
+});
+```
+
+Provider metadata can be normalized into one shared shape:
+
+```js
+import {
+  collectProviderMetadata,
+  extractAnthropicMetadata,
+  extractOpenAIMetadata
+} from '@qorejs/qore';
+
+const openaiMetadata = await collectProviderMetadata(
+  'OpenAI',
+  openai.responses.stream({ input: 'hello' }),
+  extractOpenAIMetadata
+);
+
+const anthropicMetadata = await collectProviderMetadata(
+  'Anthropic',
+  anthropic.messages.stream({ messages: [{ role: 'user', content: 'hello' }] }),
+  extractAnthropicMetadata
+);
+
+openaiMetadata.usage?.totalTokens;
+anthropicMetadata.finishReason;
+```
+
 ### Backpressure
 
 ```js
@@ -199,13 +417,24 @@ answer.buffered(); // how many chunks are queued right now
 answer.dropped();  // how many chunks were dropped by the overflow policy
 ```
 
-### `signal`, `computed`, `effect`
+### `signal`, `computed`, `effect`, `createRoot`, `onCleanup`
 
 ```js
-import { computed, signal, stream } from '@qorejs/qore';
+import { computed, createRoot, effect, onCleanup, signal, stream } from '@qorejs/qore';
 
 const answer = stream(openai.chat('hello'));
 const length = computed(() => answer().length);
+
+const dispose = createRoot((dispose) => {
+  effect(() => {
+    console.log(length());
+    onCleanup(() => console.log('effect disposed'));
+  });
+
+  return dispose;
+});
+
+dispose();
 ```
 
 ### `response`
@@ -234,7 +463,7 @@ The repository includes a landing page and a focused streaming demo:
 src/
   core/       stream, signal, response, iterable
   dom/        app mounting and DOM bindings
-  providers/  OpenAI, Anthropic, generic SSE adapters
+  providers/  OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, SSE, and line-stream adapters
   shared/     runtime utilities
   index.ts    public entrypoint
 
@@ -256,6 +485,43 @@ python3 -m http.server 4173
 
 Then open [http://127.0.0.1:4173/](http://127.0.0.1:4173/).
 
+## Server And SSR
+
+Qore's reactive core and stream runtime work in Node and browser environments today.
+
+The DOM layer is intentionally browser-only right now:
+
+- `signal`, `computed`, `effect`, `stream`, and provider adapters work in Node and the browser
+- `h`, `text`, `mount`, and `createApp(...).mount(...)` require a browser-like `document`
+- `canUseDOM()` is exported so integrations can branch cleanly before touching DOM APIs
+- `assertCanUseDOM(name?)` is exported if you want to fail fast with the same browser-boundary error shape Qore uses internally
+- the published entrypoint is checked against a frozen public API snapshot before release so accidental export drift fails CI early
+
+If you call DOM helpers without a browser-like runtime, Qore throws an entrypoint-specific error instead of failing later with a generic reference error. For example:
+
+- `h() requires a browser-like environment`
+- `mount() requires a browser-like environment`
+- `createApp(...).mount(...) requires a browser-like environment`
+
+Example:
+
+```js
+import { assertCanUseDOM, canUseDOM } from '@qorejs/qore';
+
+if (canUseDOM()) {
+  // Safe to call mount(), h(), text(), and other DOM entrypoints.
+}
+
+assertCanUseDOM('chat shell hydration');
+```
+
+That means the current `1.0.0` path is:
+
+- stable reactive runtime
+- stable streaming runtime
+- explicit browser DOM boundary
+- streaming SSR and hydration as a post-`1.0.0` expansion area unless the implementation is fully proven first
+
 ## Browser Regression
 
 Install the browser binary once:
@@ -278,10 +544,16 @@ It validates:
 
 The suite checks desktop and mobile layouts, watches for runtime console errors, exercises the primary interactions, and runs inside `release:check`.
 
-CI also uploads the browser regression evidence as workflow artifacts. The bundle includes viewport screenshots, focused page-surface screenshots, the Playwright HTML report, and a `benchmark-suite.json` attachment from the dedicated benchmark page.
+CI also uploads the browser regression evidence as workflow artifacts. The bundle includes viewport screenshots, focused page-surface screenshots, the Playwright HTML report, a `benchmark-suite.json` attachment from the dedicated benchmark page, and a human-readable benchmark summary markdown file from the benchmark gate.
 
 If a locked-down local shell cannot launch a supported headless browser, the script will defer to CI unless you force a hard local failure with `QORE_BROWSER_SMOKE_REQUIRED=1`.
 
+Local preview ports can also be pinned when another process is already using the default range:
+
+```bash
+QORE_STATIC_PORT=4300 QORE_STATIC_PORT_END=4400 npm run test:browser
+```
+
 ## Benchmark Methodology
 
 Qore now includes a reproducible browser benchmark that compares two rendering paths against the same workload:
@@ -305,6 +577,23 @@ The repository includes GitHub Actions workflows for both release validation and
 
 Because the package already includes the correct `repository` field in `package.json`, GitHub Packages can link the package back to `qorejs/qore` when the workflow publishes it.
 
+## Release Checklist
+
+The canonical release checklist lives in [`RELEASE.md`](./RELEASE.md).
+
+For every release candidate or stable release, the minimum local gate is:
+
+```bash
+npm ci
+npm run release:check
+```
+
+For npm publishing from a local shell, run:
+
+```bash
+npm run publish:preflight
+```
+
 ## Project Hygiene
 
 The repository also includes:
@@ -338,7 +627,7 @@ The current test suite covers:
 - `signal`, `computed`, and `effect`
 - The core `stream = signal` behavior
 - `response` interoperability with async iterables
-- OpenAI, Anthropic, and generic SSE adapters
+- OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, and generic streaming adapters
 
 ## Roadmap
 

package/dist/src/core/owner.d.ts

@@ -0,0 +1,14 @@
+import type { Cleanup } from './signal-types.js';
+interface OwnerNode {
+    parent: OwnerNode | null;
+    children: Set<OwnerNode>;
+    cleanups: Cleanup[];
+    active: boolean;
+}
+export declare function withOwner<T>(owner: OwnerNode | null, fn: () => T): T;
+export declare function createOwnedScope(): OwnerNode;
+export declare function resetOwner(owner: OwnerNode): void;
+export declare function disposeOwner(owner: OwnerNode | null | undefined): void;
+export declare function createRoot<T>(fn: (dispose: Cleanup) => T): T;
+export declare function onCleanup(cleanup: Cleanup): void;
+export {};

package/dist/src/core/owner.js

@@ -0,0 +1,66 @@
+let activeOwner = null;
+function createOwner(parent) {
+    const owner = {
+        parent,
+        children: new Set(),
+        cleanups: [],
+        active: true
+    };
+    parent?.children.add(owner);
+    return owner;
+}
+function disposeOwnerContents(owner) {
+    const children = Array.from(owner.children);
+    owner.children.clear();
+    for (let index = children.length - 1; index >= 0; index -= 1) {
+        disposeOwner(children[index]);
+    }
+    for (let index = owner.cleanups.length - 1; index >= 0; index -= 1) {
+        try {
+            const cleanup = owner.cleanups[index];
+            if (cleanup) {
+                cleanup();
+            }
+        }
+        catch {
+            // Keep unwinding the owner tree even if one cleanup throws.
+        }
+    }
+    owner.cleanups.length = 0;
+}
+export function withOwner(owner, fn) {
+    const previousOwner = activeOwner;
+    activeOwner = owner;
+    try {
+        return fn();
+    }
+    finally {
+        activeOwner = previousOwner;
+    }
+}
+export function createOwnedScope() {
+    return createOwner(activeOwner);
+}
+export function resetOwner(owner) {
+    if (!owner.active) {
+        return;
+    }
+    disposeOwnerContents(owner);
+}
+export function disposeOwner(owner) {
+    if (!owner || !owner.active) {
+        return;
+    }
+    owner.active = false;
+    disposeOwnerContents(owner);
+    owner.parent?.children.delete(owner);
+    owner.parent = null;
+}
+export function createRoot(fn) {
+    const owner = createOwner(activeOwner);
+    const dispose = () => disposeOwner(owner);
+    return withOwner(owner, () => fn(dispose));
+}
+export function onCleanup(cleanup) {
+    activeOwner?.cleanups.push(cleanup);
+}

package/dist/src/core/response-runtime.js

@@ -1,6 +1,6 @@
 import { batch } from './signal.js';
 import { toAsyncIterable } from './iterable.js';
-import { createResponseState, isTerminalStatus } from './response-state.js';
+import { appendResponseChunk, createResponseState, getResponseChunkCount, isTerminalStatus, snapshotResponseChunks } from './response-state.js';
 import { normalizeError } from '../shared/utils.js';
 function isResponseSourceFactory(source) {
     const callableSource = source;
@@ -43,13 +43,13 @@ export function createResponse(options) {
         if (isTerminalStatus(currentStatus)) {
             return value.peek();
         }
-        const index = chunks.peek().length;
+        const index = getResponseChunkCount(chunks);
         const nextValue = reduce(value.peek(), chunk, index);
         batch(() => {
             if (status.peek() === 'idle' || status.peek() === 'pending') {
                 status('streaming');
             }
-            chunks([...chunks.peek(), chunk]);
+            appendResponseChunk(chunks, chunk);
             value(nextValue);
         });
         return nextValue;
@@ -201,10 +201,10 @@ export function createResponse(options) {
             status: status.peek(),
             value: value.peek(),
             error: error.peek(),
-            chunks: [...chunks.peek()],
+            chunks: snapshotResponseChunks(chunks),
             startedAt: startedAt.peek(),
             finishedAt: finishedAt.peek(),
-            chunkCount: chunks.peek().length
+            chunkCount: getResponseChunkCount(chunks)
         };
     }
     api = {

package/dist/src/core/response-state.d.ts

@@ -1,3 +1,7 @@
+import { type Signal } from './signal.js';
 import type { ResponseReactiveState, ResponseStatus } from './response-types.js';
 export declare function isTerminalStatus(currentStatus: ResponseStatus): boolean;
+export declare function appendResponseChunk<T>(chunks: Signal<T[]>, chunk: T): number;
+export declare function getResponseChunkCount<T>(chunks: Signal<T[]>): number;
+export declare function snapshotResponseChunks<T>(chunks: Signal<T[]>): T[];
 export declare function createResponseState<TChunk, TValue>(seed: TValue): ResponseReactiveState<TChunk, TValue>;

package/dist/src/core/response-state.js

@@ -1,14 +1,79 @@
+import { READ } from './signal-context.js';
 import { computed, signal } from './signal.js';
 // Treat these states as closed so late writes cannot mutate a finished response.
 export function isTerminalStatus(currentStatus) {
     return currentStatus === 'completed' || currentStatus === 'error' || currentStatus === 'aborted';
 }
+function isChunkSignal(value) {
+    return typeof value.append === 'function'
+        && typeof value.count === 'function'
+        && typeof value.peekCount === 'function'
+        && typeof value.snapshot === 'function';
+}
+// Store the live chunk log behind a version signal so token commits do not copy
+// the full history on every push. Public reads still receive defensive copies.
+function createChunkSignal() {
+    let items = [];
+    const version = signal(0);
+    const notify = () => version(version.peek() + 1);
+    const chunks = ((nextValue = READ) => {
+        if (nextValue === READ) {
+            version();
+            return [...items];
+        }
+        items = [...nextValue];
+        notify();
+        return [...items];
+    });
+    chunks.set = (nextValue) => {
+        items = [...nextValue];
+        notify();
+        return [...items];
+    };
+    chunks.update = (updater) => chunks.set(updater([...items]));
+    chunks.peek = () => [...items];
+    chunks.subscribe = (listener, options = {}) => {
+        const { immediate = true } = options;
+        if (immediate) {
+            listener([...items]);
+        }
+        return version.subscribe(() => listener([...items]), { immediate: false });
+    };
+    chunks.append = (chunk) => {
+        const index = items.length;
+        items.push(chunk);
+        notify();
+        return index;
+    };
+    chunks.count = () => {
+        version();
+        return items.length;
+    };
+    chunks.peekCount = () => items.length;
+    chunks.snapshot = () => [...items];
+    return chunks;
+}
+export function appendResponseChunk(chunks, chunk) {
+    if (isChunkSignal(chunks)) {
+        return chunks.append(chunk);
+    }
+    const currentChunks = chunks.peek();
+    const index = currentChunks.length;
+    chunks([...currentChunks, chunk]);
+    return index;
+}
+export function getResponseChunkCount(chunks) {
+    return isChunkSignal(chunks) ? chunks.peekCount() : chunks.peek().length;
+}
+export function snapshotResponseChunks(chunks) {
+    return isChunkSignal(chunks) ? chunks.snapshot() : [...chunks.peek()];
+}
 // Create the reactive state bundle that powers a response lifecycle.
 export function createResponseState(seed) {
     const status = signal('idle');
     const value = signal(seed);
     const error = signal(null);
-    const chunks = signal([]);
+    const chunks = createChunkSignal();
     const startedAt = signal(null);
     const finishedAt = signal(null);
     const pending = computed(() => {
@@ -19,7 +84,7 @@ export function createResponseState(seed) {
     const completed = computed(() => status() === 'completed');
     const failed = computed(() => status() === 'error');
     const aborted = computed(() => status() === 'aborted');
-    const chunkCount = computed(() => chunks().length);
+    const chunkCount = computed(() => chunks.count());
     return {
         status,
         value,

package/dist/src/core/signal-context.js

@@ -3,6 +3,7 @@ export const READ = Symbol('qore.signal.read');
 let activeObserver = null;
 let batchDepth = 0;
 const pendingObservers = new Set();
+let flushingObservers = false;
 export function getActiveObserver() {
     return activeObserver;
 }
@@ -31,24 +32,33 @@ export function scheduleObserver(observer) {
     if (!observer.active) {
         return;
     }
-    if (batchDepth > 0) {
-        pendingObservers.add(observer);
+    pendingObservers.add(observer);
+    if (batchDepth > 0 || flushingObservers) {
         return;
     }
-    observer.schedule();
+    flushObservers();
 }
 export function removePendingObserver(observer) {
     pendingObservers.delete(observer);
 }
 // Flush batched observer work in FIFO-like waves until the queue is empty.
 function flushObservers() {
-    while (pendingObservers.size > 0) {
-        const queue = Array.from(pendingObservers);
-        pendingObservers.clear();
-        for (const observer of queue) {
-            observer.schedule();
+    flushingObservers = true;
+    try {
+        while (pendingObservers.size > 0) {
+            const queue = Array.from(pendingObservers);
+            pendingObservers.clear();
+            queue.sort((left, right) => left.level - right.level);
+            for (const observer of queue) {
+                if (observer.active) {
+                    observer.schedule();
+                }
+            }
         }
     }
+    finally {
+        flushingObservers = false;
+    }
 }
 // Batch synchronous updates so dependent observers only re-run once afterward.
 export function batch(fn) {
@@ -58,7 +68,7 @@ export function batch(fn) {
     }
     finally {
         batchDepth -= 1;
-        if (batchDepth === 0) {
+        if (batchDepth === 0 && !flushingObservers) {
             flushObservers();
         }
     }