@qorejs/qore 0.7.0 → 0.7.2

package/README.md

@@ -1,24 +1,62 @@
 # Qore
 
-Qore 的灵魂只有四个字：`流式响应`。
-
-它不是把数据当快照，而是把数据当河流。token 一段一段地到来，UI 就应该一段一段地响应，不需要手动拼字符串，不需要到处补 `loading`，也不需要把 partial render 当成特例处理。
+[![npm version](https://img.shields.io/npm/v/%40qorejs%2Fqore?color=0f766e&label=npm)](https://www.npmjs.com/package/@qorejs/qore)
+[![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)
+[![publish github packages](https://github.com/qorejs/qore/actions/workflows/publish-github-packages.yml/badge.svg)](https://github.com/qorejs/qore/actions/workflows/publish-github-packages.yml)
+[![GitHub Packages](https://img.shields.io/badge/GitHub-Packages-181717?logo=github)](https://github.com/qorejs/qore/packages)
+[![node >= 18](https://img.shields.io/badge/node-%3E%3D18-1f6feb)](https://nodejs.org/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-0f766e)](https://github.com/qorejs/qore/blob/main/LICENSE)
+
+Qore is a streaming-response framework where `stream = signal`.
+
+Instead of treating data as a snapshot, Qore treats it like a river. Tokens arrive piece by piece, and the UI should respond piece by piece too. No manual string accumulation. No scattered loading state. No partial rendering workaround layered on top of a snapshot-first mental model.
+
+Quick links:
+
+- [npm package](https://www.npmjs.com/package/@qorejs/qore)
+- [GitHub Packages](https://github.com/qorejs/qore/packages)
+- [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)
+- [continuous integration](https://github.com/qorejs/qore/actions/workflows/ci.yml)
+- [release workflow](https://github.com/qorejs/qore/actions/workflows/release-check.yml)
+- [contributing guide](https://github.com/qorejs/qore/blob/main/CONTRIBUTING.md)
+- [security policy](https://github.com/qorejs/qore/blob/main/SECURITY.md)
 
 ## Installation
 
+From npm:
+
 ```bash
 npm i @qorejs/qore
 ```
 
+From GitHub Packages:
+
+```bash
+echo "@qorejs:registry=https://npm.pkg.github.com" >> .npmrc
+npm i @qorejs/qore
+```
+
+GitHub Packages installs require an authenticated session against `https://npm.pkg.github.com`.
+
 - Package name: `@qorejs/qore`
 - Module format: `ESM`
 - Supported runtime: `Node >= 18`
+- CI coverage: `Node 18`, `20`, and `22`
+- Browser regression: Playwright desktop + mobile smoke coverage for the homepage, focused demo, and benchmark page
+- Registries:
+  - 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)
 
 ## Core Idea
 
-`stream` 是数据流动的方式，`signal` 是 UI 响应变化的方式。
+`stream` is how data flows.
+`signal` is how the UI reacts.
 
-在 Qore 里，这两者是同一个 primitive 的两面：
+In Qore, they are two sides of the same primitive:
 
 ```js
 import { createOpenAI, h, stream, text } from '@qorejs/qore';
@@ -29,18 +67,18 @@ const answer = stream(openai.chat('hello'));
 return h('div', {}, text(() => answer()));
 ```
 
-这里的 `answer` 同时是：
+Here, `answer` is all of the following at once:
 
-- 一个只读 `signal`，`answer()` 拿到当前累积值
-- 一个 `AsyncIterable`，可以继续 `for await...of`
-- 一个带生命周期的流状态，支持 `status()`、`streaming()`、`error()`、`chunks()`
+- A read-only `signal`, so `answer()` returns the current accumulated value
+- An `AsyncIterable`, so you can still use `for await...of`
+- A lifecycle-aware streaming state, with `status()`, `streaming()`, `error()`, and `chunks()`
 
 ## Why Qore
 
-- React 把 stream 当成特殊情况，需要额外心智去补
-- SolidJS 的 signal 很强，但没有原生 stream primitive
-- Vue 的 ref 很顺手，但 stream 依旧是外置概念
-- Qore 直接把 `stream = signal` 做成核心 API
+- React treats streaming as a special case that needs extra machinery
+- SolidJS has excellent signals, but no native stream primitive
+- Vue has ergonomic refs, but stream handling still lives outside the core model
+- Qore makes `stream = signal` the core API from the start
 
 ## Quick Start
 
@@ -48,15 +86,15 @@ return h('div', {}, text(() => answer()));
 import { h, mount, stream, text } from '@qorejs/qore';
 
 const answer = stream(async function* () {
-  yield '流';
-  yield '式';
-  yield '响应';
+  yield 'stream';
+  yield ' = ';
+  yield 'signal';
 }());
 
 mount('#app', () => h('div', { className: 'answer' }, text(() => answer())));
 ```
 
-上面这个例子只会更新那一个 text node，不会 whole tree 重绘。
+This updates only the text node that depends on the stream. It does not re-render the whole tree.
 
 ## Providers
 
@@ -88,7 +126,7 @@ const answer = stream(anthropic.chat('Why should stream be signal?'));
 
 ### `createSSEAdapter(options?)`
 
-如果你的后端本来就已经在吐 SSE，Qore 也可以直接把它收编进同一个 story：
+If your backend already streams `text/event-stream`, Qore can adopt it directly:
 
 ```js
 import { createSSEAdapter, stream } from '@qorejs/qore';
@@ -113,25 +151,25 @@ const provider = createSSEAdapter({
 const answer = stream(provider.chat('hello'));
 ```
 
-这让 `stream(provider.chat(...))` 不再绑定某一家 SDK，而是成为一个通用入口。
+That makes `stream(provider.chat(...))` a general entry point instead of something tied to a single SDK.
 
 ## API Shape
 
 ### `stream(source, options?)`
 
-默认把 chunk 累积成文本 signal：
+By default, `stream(...)` accumulates chunks into a text signal:
 
 ```js
 const answer = stream(openai.chat('hello'));
 
-answer();           // 当前文本
+answer();           // current text
 answer.status();    // idle | pending | streaming | completed | error | aborted
 answer.streaming(); // boolean
-answer.chunks();    // 原始 chunk 列表
-await answer.ready; // 等待结束
+answer.chunks();    // raw chunks
+await answer.ready; // wait for completion
 ```
 
-如果你需要结构化流：
+If you need structured streams:
 
 ```js
 const events = stream.list(eventSource);
@@ -148,17 +186,17 @@ const answer = stream.withBackpressure(openai.chat('hello'), {
 });
 ```
 
-backpressure 现在不只是“睡一下”：
+Backpressure is not just a delay wrapper:
 
-- `interval`：chunk 进入 signal / UI 之间的最小间隔
-- `buffer`：在 UI 前面最多允许排队多少个 chunk
-- `overflow`：缓冲区满了以后怎么办，可选 `wait` / `drop-oldest` / `drop-newest` / `error`
+- `interval`: the minimum spacing between chunk delivery into the signal and UI
+- `buffer`: the maximum number of queued chunks before the UI catches up
+- `overflow`: what to do when the buffer is full: `wait`, `drop-oldest`, `drop-newest`, or `error`
 
-你还可以直接观察压力状态：
+You can also observe stream pressure directly:
 
 ```js
-answer.buffered(); // 当前还有多少 chunk 在排队
-answer.dropped();  // 因 overflow 策略被丢掉了多少 chunk
+answer.buffered(); // how many chunks are queued right now
+answer.dropped();  // how many chunks were dropped by the overflow policy
 ```
 
 ### `signal`, `computed`, `effect`
@@ -172,42 +210,122 @@ const length = computed(() => answer().length);
 
 ### `response`
 
-`response` 仍然保留，但它更像底层状态机 escape hatch，适合复杂 reducer 或自定义聚合。
+`response` still exists, but it is closer to a lower-level state machine escape hatch for custom reducers and aggregators.
 
-如果你的目标是“把流直接接进 UI”，优先使用 `stream(...)`。
+If your goal is to pipe a stream directly into the UI, prefer `stream(...)`.
 
 ## Demos
 
-仓库里带了完整 landing page 和 focused demo：
+The repository includes a landing page and a focused streaming demo:
 
 - [Landing Page Source](https://github.com/qorejs/qore/blob/main/index.html)
-- [Homepage Logic](https://github.com/qorejs/qore/blob/main/examples/showcase.js)
+- [Homepage Logic](https://github.com/qorejs/qore/blob/main/examples/showcase.ts)
 - [Homepage Styles](https://github.com/qorejs/qore/blob/main/examples/showcase.css)
+- [Benchmark Page](https://github.com/qorejs/qore/blob/main/examples/benchmark.html)
+- [Benchmark Logic](https://github.com/qorejs/qore/blob/main/examples/benchmark-page.ts)
+- [Benchmark Core](https://github.com/qorejs/qore/blob/main/examples/benchmark-core.ts)
 - [Focused Demo](https://github.com/qorejs/qore/blob/main/examples/streaming-response.html)
-- [Focused Chat Logic](https://github.com/qorejs/qore/blob/main/examples/qore-chat.js)
-- [React Compare](https://github.com/qorejs/qore/blob/main/examples/react-chat.jsx)
+- [Focused Chat Logic](https://github.com/qorejs/qore/blob/main/examples/qore-chat.ts)
+- [React Compare](https://github.com/qorejs/qore/blob/main/examples/react-chat.ts)
+
+## Project Layout
+
+```text
+src/
+  core/       stream, signal, response, iterable
+  dom/        app mounting and DOM bindings
+  providers/  OpenAI, Anthropic, generic SSE adapters
+  shared/     runtime utilities
+  index.ts    public entrypoint
+
+dist/
+  src/        compiled package output
+  examples/   built showcase scripts for local preview
+  test/       compiled test output
+```
 
-本地预览：
+For a local preview:
 
 ```bash
 git clone git@github.com:qorejs/qore.git
 cd qore
+npm install
+npm run build
 python3 -m http.server 4173
 ```
 
-然后打开 [http://127.0.0.1:4173/](http://127.0.0.1:4173/)。
+Then open [http://127.0.0.1:4173/](http://127.0.0.1:4173/).
+
+## Browser Regression
+
+Install the browser binary once:
+
+```bash
+npm run browsers:install
+```
+
+Then run the browser smoke suite:
+
+```bash
+npm run test:browser
+```
+
+It validates:
+
+- the homepage stream demo
+- the focused streaming chat demo
+- the dedicated benchmark page
+
+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.
+
+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`.
+
+## Benchmark Methodology
+
+Qore now includes a reproducible browser benchmark that compares two rendering paths against the same workload:
+
+- `Qore stream = signal`: mount the transcript shell once and advance the same live text node as chunks arrive
+- `Snapshot rerender baseline`: rebuild the transcript shell from a snapshot string on every chunk
+
+Both paths use the same transcript history, the same chunk list, and the same final answer text. The benchmark reports first paint time, mutation records, node churn, and regenerated markup so the difference is visible instead of rhetorical.
+
+## GitHub Packages
+
+The repository includes GitHub Actions workflows for both release validation and GitHub Packages publishing.
+
+- Release validation: `.github/workflows/release-check.yml`
+- GitHub Packages publish: `.github/workflows/publish-github-packages.yml`
+- Both workflows can be triggered manually from the Actions tab
+- Publishing a GitHub Release triggers both the release check and the GitHub Packages publish flow
+- The publish workflow validates the release tag, changelog, test suite, and tarball before it pushes the package
+- The publish workflow uses the repository `GITHUB_TOKEN`, which GitHub documents as the recommended way to publish packages from the workflow repository
+- GitHub Packages starts new packages as private by default, so you may want to switch the package visibility to public after the first publish
+
+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.
+
+## Project Hygiene
+
+The repository also includes:
+
+- `CONTRIBUTING.md` for contributor expectations and release flow
+- `SECURITY.md` for responsible disclosure
+- issue templates for bugs and feature requests
+- a pull request template
+- `.github/release.yml` to keep GitHub release notes structured
 
 ## Package Boundary
 
-Qore 核心包不内置 Button、Dialog、Tabs 这类 UI primitives。
+Qore does not ship a built-in catalog of buttons, dialogs, tabs, or other UI primitives.
 
-核心包只做三件事：
+The core package does only three things:
 
-- 让流进入状态
-- 让状态进入 UI
-- 让整个过程保持细粒度响应
+- Move streams into state
+- Move state into the UI
+- Keep the whole process finely reactive
 
-一切不服务于 `流式响应` 的东西，都应该放到实验层或者外围仓库。
+Anything that does not serve `streaming response` belongs in an experimental layer or a separate package.
 
 ## Testing
 
@@ -215,14 +333,14 @@ Qore 核心包不内置 Button、Dialog、Tabs 这类 UI primitives。
 npm test
 ```
 
-当前测试覆盖了：
+The current test suite covers:
 
-- signal / computed / effect
-- stream = signal 的核心行为
-- response 与 async iterable 的兼容
-- OpenAI / Anthropic / generic SSE adapters
+- `signal`, `computed`, and `effect`
+- The core `stream = signal` behavior
+- `response` interoperability with async iterables
+- OpenAI, Anthropic, and generic SSE adapters
 
 ## Roadmap
 
-- 围绕服务端流式渲染收敛 hydration 模型
-- 做公开 benchmark，把 Qore 和 React/Vercel AI SDK 的差异变成可重复的数据
+- Tighten the hydration model around server-streamed rendering
+- Publish repeatable benchmarks that compare Qore with React and the Vercel AI SDK

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

@@ -0,0 +1 @@
+export declare function toAsyncIterable<T>(source: T | Iterable<T> | AsyncIterable<T> | null | undefined): AsyncIterable<T>;

package/dist/src/core/iterable.js

@@ -0,0 +1,17 @@
+// Normalize values, iterables, and async iterables into one async iterable shape.
+export function toAsyncIterable(source) {
+    if (source == null) {
+        return (async function* empty() { })();
+    }
+    if (typeof source[Symbol.asyncIterator] === 'function') {
+        return source;
+    }
+    if (typeof source[Symbol.iterator] === 'function') {
+        return (async function* fromIterable() {
+            yield* source;
+        })();
+    }
+    return (async function* fromValue() {
+        yield source;
+    })();
+}

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

@@ -0,0 +1,2 @@
+import type { CreateResponseOptions, ResponseState } from './response-types.js';
+export declare function createResponse<TChunk, TValue>(options: CreateResponseOptions<TChunk, TValue>): ResponseState<TChunk, TValue>;

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

@@ -0,0 +1,233 @@
+import { batch } from './signal.js';
+import { toAsyncIterable } from './iterable.js';
+import { createResponseState, isTerminalStatus } from './response-state.js';
+import { normalizeError } from '../shared/utils.js';
+function isResponseSourceFactory(source) {
+    const callableSource = source;
+    return typeof source === 'function'
+        && typeof callableSource[Symbol.asyncIterator] !== 'function'
+        && typeof callableSource.peek !== 'function';
+}
+// Build a response state machine that accumulates chunks into a reactive value.
+export function createResponse(options) {
+    const { seed, reduce } = options;
+    const state = createResponseState(seed);
+    const { status, value, error, chunks, startedAt, finishedAt, pending, streaming, completed, failed, aborted, chunkCount } = state;
+    let activeController = null;
+    let runId = 0;
+    let api;
+    // Abort the active executor when a new run supersedes it.
+    function supersedeActiveRun(reason = 'Response superseded by a new run') {
+        if (!activeController) {
+            return;
+        }
+        activeController.abort(reason);
+        activeController = null;
+    }
+    // Reset the response to its initial seed and clear all lifecycle markers.
+    function reset(nextSeed = seed) {
+        supersedeActiveRun('Response reset');
+        batch(() => {
+            status('idle');
+            value(nextSeed);
+            error(null);
+            chunks([]);
+            startedAt(null);
+            finishedAt(null);
+        });
+        return nextSeed;
+    }
+    // Push a chunk through the reducer and advance the response into streaming state.
+    function push(chunk) {
+        const currentStatus = status.peek();
+        if (isTerminalStatus(currentStatus)) {
+            return value.peek();
+        }
+        const index = chunks.peek().length;
+        const nextValue = reduce(value.peek(), chunk, index);
+        batch(() => {
+            if (status.peek() === 'idle' || status.peek() === 'pending') {
+                status('streaming');
+            }
+            chunks([...chunks.peek(), chunk]);
+            value(nextValue);
+        });
+        return nextValue;
+    }
+    // Mark the response as completed and freeze the current accumulated value.
+    function complete() {
+        const currentStatus = status.peek();
+        if (isTerminalStatus(currentStatus)) {
+            return value.peek();
+        }
+        activeController = null;
+        batch(() => {
+            status('completed');
+            finishedAt(Date.now());
+        });
+        return value.peek();
+    }
+    // Capture an error unless the response is already closed.
+    function fail(reason) {
+        const currentStatus = status.peek();
+        const normalizedError = normalizeError(reason);
+        if (isTerminalStatus(currentStatus)) {
+            return currentStatus === 'error'
+                ? error.peek() ?? normalizedError
+                : value.peek();
+        }
+        activeController = null;
+        batch(() => {
+            status('error');
+            error(normalizedError);
+            finishedAt(Date.now());
+        });
+        return normalizedError;
+    }
+    // Abort an in-flight response while keeping the value accumulated so far.
+    function abort(reason = 'Response aborted') {
+        const currentStatus = status.peek();
+        if (currentStatus !== 'pending' && currentStatus !== 'streaming') {
+            return value.peek();
+        }
+        activeController?.abort(reason);
+        activeController = null;
+        batch(() => {
+            status('aborted');
+            finishedAt(Date.now());
+        });
+        return value.peek();
+    }
+    // Run an async executor and guard every lifecycle method to the active run only.
+    async function run(executor, options = {}) {
+        const { resetValue = true, nextSeed = seed } = options;
+        supersedeActiveRun();
+        runId += 1;
+        const currentRunId = runId;
+        const controller = new AbortController();
+        activeController = controller;
+        // A response may outlive older executors, so every write must prove it still owns the run.
+        const isCurrentRun = () => (currentRunId === runId
+            && activeController === controller
+            && !controller.signal.aborted);
+        const settleExitedRun = () => {
+            if (currentRunId !== runId) {
+                return value.peek();
+            }
+            if (status.peek() === 'error') {
+                throw error.peek() ?? new Error('Response failed');
+            }
+            return value.peek();
+        };
+        batch(() => {
+            if (resetValue) {
+                value(nextSeed);
+                chunks([]);
+            }
+            error(null);
+            status('pending');
+            startedAt(Date.now());
+            finishedAt(null);
+        });
+        // Expose guarded lifecycle helpers so stale executors cannot leak writes into the latest run.
+        const context = {
+            get signal() {
+                return controller.signal;
+            },
+            response: api,
+            push(chunk) {
+                if (!isCurrentRun()) {
+                    return value.peek();
+                }
+                return push(chunk);
+            },
+            complete() {
+                if (!isCurrentRun()) {
+                    return value.peek();
+                }
+                return complete();
+            },
+            fail(reason) {
+                if (!isCurrentRun()) {
+                    return status.peek() === 'error'
+                        ? error.peek() ?? normalizeError(reason)
+                        : value.peek();
+                }
+                return fail(reason);
+            },
+            abort(reason) {
+                if (!isCurrentRun()) {
+                    return value.peek();
+                }
+                return abort(reason);
+            }
+        };
+        try {
+            await executor(context);
+            if (!isCurrentRun()) {
+                return settleExitedRun();
+            }
+            return complete();
+        }
+        catch (reason) {
+            if (!isCurrentRun()) {
+                return settleExitedRun();
+            }
+            throw fail(reason);
+        }
+        finally {
+            if (currentRunId === runId && activeController === controller) {
+                activeController = null;
+            }
+        }
+    }
+    // Consume any async iterable-like source and route each chunk through the guarded writer.
+    async function consume(source, options = {}) {
+        return run(async ({ signal: abortSignal, push: write }) => {
+            const resolvedSource = isResponseSourceFactory(source)
+                ? await source({ signal: abortSignal, response: api })
+                : await source;
+            for await (const chunk of toAsyncIterable(resolvedSource)) {
+                if (abortSignal.aborted) {
+                    break;
+                }
+                write(chunk);
+            }
+        }, options);
+    }
+    // Return a plain snapshot suitable for inspection without exposing mutable internals.
+    function snapshot() {
+        return {
+            status: status.peek(),
+            value: value.peek(),
+            error: error.peek(),
+            chunks: [...chunks.peek()],
+            startedAt: startedAt.peek(),
+            finishedAt: finishedAt.peek(),
+            chunkCount: chunks.peek().length
+        };
+    }
+    api = {
+        status,
+        value,
+        error,
+        chunks,
+        startedAt,
+        finishedAt,
+        pending,
+        streaming,
+        completed,
+        failed,
+        aborted,
+        chunkCount,
+        reset,
+        push,
+        complete,
+        fail,
+        abort,
+        run,
+        consume,
+        snapshot
+    };
+    return api;
+}

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

@@ -0,0 +1,3 @@
+import type { ResponseReactiveState, ResponseStatus } from './response-types.js';
+export declare function isTerminalStatus(currentStatus: ResponseStatus): boolean;
+export declare function createResponseState<TChunk, TValue>(seed: TValue): ResponseReactiveState<TChunk, TValue>;

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

@@ -0,0 +1,37 @@
+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';
+}
+// 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 startedAt = signal(null);
+    const finishedAt = signal(null);
+    const pending = computed(() => {
+        const currentStatus = status();
+        return currentStatus === 'pending' || currentStatus === 'streaming';
+    });
+    const streaming = computed(() => status() === 'streaming');
+    const completed = computed(() => status() === 'completed');
+    const failed = computed(() => status() === 'error');
+    const aborted = computed(() => status() === 'aborted');
+    const chunkCount = computed(() => chunks().length);
+    return {
+        status,
+        value,
+        error,
+        chunks,
+        startedAt,
+        finishedAt,
+        pending,
+        streaming,
+        completed,
+        failed,
+        aborted,
+        chunkCount
+    };
+}