akarisp 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -15,8 +15,10 @@ Zero runtime dependencies. No framework, no agent abstraction.
 npm install akarisp@alpha
 ```
 
-The first release, `0.1.0-alpha.0`, is published under the `alpha` dist-tag. A plain
-`npm install akarisp` installs the `latest` tag, which will exist only after a stable release.
+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/).
 
 ## Usage
 
@@ -158,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`,
@@ -178,6 +222,8 @@ requirement only; the package itself runs in browsers.
 npm test       # node:test: core, browser and WebLLM adapters, boundary, packed-tarball consumer
 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
@@ -200,5 +246,19 @@ the diff.
 
 ### Release
 
-`npm publish` uses `publishConfig.tag` (`alpha`), so a pre-release never lands on `latest` by
-accident. `prepack` rebuilds `dist/` first.
+Each release states its intent before publishing and verifies the registry afterwards. Nothing
+relies on a configured default tag: with npm 10.9.2, a configured `publishConfig.tag` was
+observed not to be applied, so the tag is always named on the command line.
+
+1. Bump `version`, and write and commit `releases/<version>.json`, which names every intended
+   dist-tag target.
+2. Publish: `npm publish --tag <tag>` (`prepack` rebuilds `dist/` first).
+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`. 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.0",
+  "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": {
@@ -25,10 +25,9 @@
     "build": "tsc",
     "test": "node --test test/*.test.ts",
     "test:browser": "playwright test",
-    "prepack": "npm run build"
-  },
-  "publishConfig": {
-    "tag": "alpha"
+    "prepack": "npm run build",
+    "test:registry": "node --test test/registry/registry.test.ts",
+    "test:frameworks": "playwright test -c playwright.frameworks.config.ts"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",