akarisp 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -15,8 +15,8 @@ Zero runtime dependencies. No framework, no agent abstraction.
 npm install akarisp@alpha
 ```
 
-For the `0.1.0-alpha.1` release, both `alpha` and `latest` are intended to point to
-`0.1.0-alpha.1`, so `npm install akarisp` and `npm install akarisp@alpha` install the same
+For the `0.1.0-alpha.2` release, both `alpha` and `latest` are intended to point to
+`0.1.0-alpha.2`, so `npm install akarisp` and `npm install akarisp@alpha` install the same
 version. This does not define a permanent dist-tag policy. Each release records its intended and
 verified tags under [`releases/`](releases/).
 
@@ -160,6 +160,48 @@ The returned runtime is the same `Runtime`: `run`, `stream`, `snapshot`, `shutdo
   a cast. This is verified with TypeScript `moduleResolution: "bundler"`. WebLLM 0.2.85's own
   declarations do not resolve under `node16`/`nodenext`, where its types become `any`.
 
+## Using with frameworks
+
+AkariSP needs no framework-specific package. The component (or page) that creates a runtime
+owns it and calls `shutdown()` when it goes away. One rule matters in every framework:
+**`createRuntime()` is asynchronous, so the owner can be unmounted before it resolves.** A runtime
+that resolves after unmount must still be shut down. Otherwise it is never cleaned up. This
+happens in production on a fast unmount, and on every mount under React's development
+StrictMode.
+
+React (`useEffect`; the same pattern works for a Next.js client component):
+
+```jsx
+useEffect(() => {
+  let rt;
+  let cancelled = false; // set by cleanup; a runtime resolving afterwards is shut down at once
+  createRuntime().then((r) => {
+    if (cancelled) {
+      r.shutdown();
+      return;
+    }
+    rt = r;
+    setRuntime(r);
+  });
+  return () => {
+    cancelled = true;
+    rt?.shutdown();
+  };
+}, []);
+```
+
+- **Vue**: create in `onMounted`, and in `onBeforeUnmount` set `cancelled = true` and shut down.
+  Then check `cancelled` after `await createRuntime()`.
+- **Svelte**: the same pattern as React, inside `onMount` and the cleanup function it returns.
+- **Next.js (App Router)**: importing `akarisp` from server components is safe. **Create the
+  runtime only in client code**: a component marked `"use client"`, inside an effect. Creating
+  it in server-evaluated code fails with `ReferenceError: LanguageModel is not defined`.
+
+Development module replacement (HMR) caused no leaks in the tested versions. Validated with
+React 19.3, Vue 3.5, Svelte 5.57, Vite 8.3, and Next.js 16.3. The full applications are in
+[`fixtures/`](fixtures/), and the evidence is in
+[`specs/010-framework-compatibility-validation`](specs/010-framework-compatibility-validation/research.md).
+
 ## Package
 
 - Entry points: `akarisp` (`createRuntime`, `TaskError`, and the types `Runtime`,
@@ -181,6 +223,7 @@ npm test       # node:test: core, browser and WebLLM adapters, boundary, packed-
 npm run build  # tsc → dist/
 npm run test:browser  # Playwright: compatibility page on Chromium / Firefox / WebKit engines
 RELEASE=<version> npm run test:registry  # on demand, needs the network: the published package vs releases/<version>.json
+npm run test:frameworks  # on demand, needs the network: React/Vue/Svelte + Vite and Next.js fixtures, installed from npm
 ```
 
 ### Browser compatibility
@@ -213,6 +256,9 @@ observed not to be applied, so the tag is always named on the command line.
 3. For every other tag in the intent: `npm dist-tag add akarisp@<version> <tag>`.
 4. Verify: `RELEASE=<version> npm run test:registry`. It re-reads the registry for up to 10
    minutes while metadata propagates, then installs from the registry into clean consumers.
-   Commit the resulting `releases/<version>.verified.json`.
+   Commit the resulting `releases/<version>.verified.json`. It records one verification moment
+   and is not a golden file. Re-running the check for an older release after the tags have moved
+   overwrites it with a (correct) mismatch record. The committed release-time file is the
+   evidence, so discard such a rewrite with `git checkout -- releases/<version>.verified.json`.
 5. On a mismatch, fix forward: correct a tag with `npm dist-tag add` and re-run the check, or
    publish the next version for a content defect. Never unpublish.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akarisp",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Lightweight lifecycle runtime for browser LLM sessions: bounded queue, cancellation, and deterministic cleanup for the Chrome Prompt API and WebLLM",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,8 @@
     "test": "node --test test/*.test.ts",
     "test:browser": "playwright test",
     "prepack": "npm run build",
-    "test:registry": "node --test test/registry/registry.test.ts"
+    "test:registry": "node --test test/registry/registry.test.ts",
+    "test:frameworks": "playwright test -c playwright.frameworks.config.ts"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",