Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Default mode is `observe` (report only); `guard` is opt-in; `heal` is experiment
| `demos/` | six demo apps with a chaos backend and Playwright trials; `bench/heal/` runs them per mode |
| `packages/mcp/` | `@genclass/mcp`: the MCP server for coding agents (bridge on 127.0.0.1:47357, store, explore verdicts, replays, regression-test generation, 9 tools incl. `genclass_scan`, which runs the runtime CLI's `scan`); no runtime deps; `test/e2e/race.e2e.mjs` is the real-browser check (not in CI's main job). `plugin/` is the Claude Code plugin (also an Agent Plugins package); `server.json`, the plugin, `.claude-plugin/`, `.cursor-plugin/`, `gemini-extension.json`, `llms-install.md` and the READMEs pin its version (`npm run sync -w @genclass/mcp` after a version bump; `test/manifests.test.ts` fails otherwise); `scripts/plugin-repo.mjs` assembles genclass-dev/genclass-plugin (the plugin at a repository root with its marketplace files and the released server vendored from npm under `server/`, which `.mcp.json` and the hook there run with `node` from `${CLAUDE_PLUGIN_ROOT}`, for the Claude directory's 50 MiB archive limit and its holds on `npx` launchers and lockfiles, Codex, Gemini CLI, `gh skill`; that repository re-syncs daily from main and is never edited by hand) |
| `packages/cli/` | `genclass` (`npx genclass`): the one way to set GenClass up, `genclass dashboard` (one app, whole, in the terminal) and `genclass suggest`. Plain ESM `.mjs` in `src/` (`main.mjs` names the command to the runtime CLI's modules, which it reuses from `packages/runtime/bin/lib`: sign-in, project detection, `init`; `state.mjs` reads the seven steps of a project from disk and from genclass.dev (account, runtime, dashboard, test workflow, GitHub App, coding agent, suggestions); `setup.mjs` and `actions.mjs` walk them, one Enter each, in a short view that `d` expands; `art.mjs` is the opening wordmark; `app.mjs` is `genclass dashboard`, which reads `GET /api/cli/app` (the dashboard's own numbers; a CLI session approved before the approval page said so is asked to sign in again); `views.mjs` is the rest of the dashboard from the same answer (`problems`, `analytics`, `events`, `health`, `agent`, `report`); `kinds.mjs` holds the dashboard page's own texts for each kind and its fix prompts (a test reads `telemetry-worker/src/pages.ts` and fails when a sentence differs); `fix.mjs` hands a problem to the person's coding agent with that prompt (it starts `claude`, `codex`, `cursor-agent` or `gemini` on a key press, or copies or prints; GenClass changes no code); `ask.mjs` is a question to genclass.dev's model; `manage.mjs` is the account's side (`apps`, `plan`, `team`, `connections`, `export`, `funnels`, `agent link`) over the routes a newer approval lists, with `session.mjs` saying why a call was refused and what to do next; `home.mjs` is the prompt the command stays open on after the walk (a command, or a sentence that is a question); `name.mjs` makes every screen say `genclass` once it is installed, `npx genclass` until then; `suggest/` measures the repository and the live site (`repo.mjs`, `site.mjs`), runs the catalog of checks (`checks.mjs`) and asks genclass.dev to order and explain what failed (`digest.mjs` is everything that is sent); `tui.mjs` is the look); `build.mjs` bundles it into one file with no dependencies (`dist/genclass.mjs`) with the runtime and MCP versions it installs; tests in `test/` (`server.test.ts` runs it against the collector in process). The server side is `telemetry-worker/src/cli.ts`, `suggest.ts` (rule 11) and `ask.ts` (rule 12). On npm as `genclass` since 2026-11-12, released by `release-cli.yml` on a `cli-v*` tag; it is the first install line the README names |
| `packages/sv/` | `@genclass/sv`: the Svelte CLI community add-on (`npx sv add @genclass`): adds the runtime, the `/auto` import first in `src/hooks.client`, the dev-only overlay and (default) the telemetry opt-out meta in `src/app.html`, all with the `genclass:init` marker so `remove` undoes it; bundles `@sveltejs/sv-utils`, `sv` is a peer; `test/e2e/` runs sv's add-on harness (pnpm, Chromium) |
| `packages/sv/` | `@genclass/sv`: the Svelte CLI community add-on (`npx sv add @genclass`): adds the runtime, the `/auto` import first in `src/hooks.client` (never the devtools overlay) and (default) the telemetry opt-out meta in `src/app.html`, all with the `genclass:init` marker so `remove` undoes it; bundles `@sveltejs/sv-utils`, `sv` is a peer; `test/e2e/` runs sv's add-on harness (pnpm, Chromium) |
| `packages/playwright/` | `@genclass/playwright`: the fixture (`src/fixture.ts`, `install.ts`, `page.ts`, `chaos.ts`, `races.ts`: puts the runtime's script-tag build on every `page` in observe mode with telemetry off, seeded chaos that holds matched fetch/XHR requests with `page.route` and `route.fallback()`, witnesses through the agent entry with every hold off, one `genclass-races/1` file per test in `test-results/genclass/`, with where the test is declared (`location`), which the GitHub App's inline comments use) and the reporter + pure summariser that read those files and write `genclass-report.md` for the PR; peer deps only (`@playwright/test`, `@genclass/runtime`); zero-edit mode (`src/register.ts`, `wrap.ts`, `worker.ts`, `run.ts`: the command `genclass-playwright-run` gives an unmodified suite the same instrumentation by wrapping public Playwright objects in the worker process; `docs/github-app/workflows/genclass.yml` is the one file a repository adds); `test/e2e/run.mjs` is the real-browser check of both (its own workflow) |
| `packages/nuxt/`, `packages/astro/` | `@genclass/nuxt` (a Nuxt module, `@nuxt/kit`, built with `@nuxt/module-builder`) and `@genclass/astro` (an Astro integration, `injectScript("page", ...)`): from options `{ mode, token?, telemetry?, devtools? }` they generate the runtime's own one line (`/auto` or `/auto/guard`) plus a `window.GENCLASS_CONFIG` module imported before it; browser only, nothing on the server; `@genclass/runtime` is a peer dependency. The generated code is pure (`src/source.ts`, `src/index.ts`) and the tests check it exactly, then build one fixture app. Workflow: `integrations.yml` (Node 24) |
| `docs/adoption/listings/` | how the framework packages and templates get listed (nuxt.com/modules entry and steps, astro.build/integrations, sveltesociety.dev, awesome-vue and Angular lists): research and draft entries; nothing is submitted from the repo |
Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ To add only the runtime, with no account:
npx @genclass/runtime@beta init # finds your framework and shows the diff before it writes anything
```

Once you approve, `init` installs the package, adds one import first in your entry file (plus a line that loads the
devtools overlay in development only) and creates your app's dashboard token (`--no-token` skips it; every flag:
[INSTALL.md](docs/runtime/INSTALL.md)).
Once you approve, `init` installs the package, adds one import first in your entry file and creates your app's
dashboard token (`--no-token` skips it; every flag: [INSTALL.md](docs/runtime/INSTALL.md)). It draws nothing on
your pages.

Or by hand: `npm install @genclass/runtime@beta`, then first in your entry file (any bundler; Next.js 15.3 or later:
`instrumentation-client.ts`, earlier versions: a client component in the root layout or `pages/_app`):
Expand Down Expand Up @@ -157,7 +157,7 @@ The full tables, with every false-intervention rate next to its recall, are unde
- Then possibly nothing for a while. Observe mode reports only salient situations (a response landing over newer
data, a repeat, a failure streak, a broken relation, an error), and the first response of each kind after a page
load is never a delivery decision: the runtime first has to see what that request writes.
- The devtools overlay: `Alt+Shift+G` on localhost (the `init` command loads it in development only).
- Nothing on the page itself: GenClass draws nothing there.
- The first-visit cost, measured on one pilot app with runtime 0.1.0-beta.3 and model 0.2.0
([RESULTS.md](https://github.com/genclass-dev/GenClass/blob/main/docs/runtime/RESULTS.md) §17): about 13 MB
downloaded from jsDelivr on WASM (12.7 MB measured, with the q8 model at 9.45 MB as recorded, ONNX Runtime's wasm
Expand Down Expand Up @@ -327,7 +327,7 @@ very heavy page can cause a long task, which the runtime records as a `perf` eve
Sentry, PostHog, Datadog, Slack or a signed webhook.
- **Product analytics.** Analytics count what users do; GenClass reports what the app got wrong while they did it.
- **Tests and linters.** These bugs depend on response order and user timing. A test on a fast, ordered network can
pass while production shows the bug. Use GenClass next to your tests, in development (the devtools overlay) and in
pass while production shows the bug. Use GenClass next to your tests, in development (the console) and in
production.
- **AbortController, request ids, TanStack Query or SWR deduplication, idempotency keys.** These are the fixes, and
they work where they are used. GenClass reports places where one is missing; in `guard` it can discard a stale
Expand Down Expand Up @@ -511,7 +511,7 @@ a new tag and regenerated data (`training/curriculum/rt.py` mirrors the renderer
| [`packages/mcp`](packages/mcp) | `@genclass/mcp` (`0.2.0` on npm), the MCP server for coding agents: pages connect through `@genclass/runtime/agent`; the agent gets findings in causal order, replays, explore verdicts, generated regression tests and, with `genclass_scan`, the page audit ([AGENT.md](docs/runtime/AGENT.md)). [README](packages/mcp/README.md) · [CHANGELOG](packages/mcp/CHANGELOG.md) |
| [`packages/playwright`](packages/playwright) | `@genclass/playwright` (unreleased), GenClass for Playwright: a fixture that puts the runtime on every page under test (observe mode, seeded network chaos with `page.route`, the model skipped by default) and writes one race file per test, and a reporter that turns those files into one markdown report for the pull request, with the evidence line and what reproduced across seeds. [README](packages/playwright/README.md) |
| [`packages/nuxt`](packages/nuxt), [`packages/astro`](packages/astro) | `@genclass/nuxt` and `@genclass/astro` (unreleased): the runtime as a Nuxt module and as an Astro integration, one line in the framework's config, with options for the mode, the token, telemetry and the devtools overlay; browser only. [Nuxt README](packages/nuxt/README.md) · [Astro README](packages/astro/README.md) |
| [`packages/sv`](packages/sv) | `@genclass/sv` (unreleased), a community add-on for the Svelte CLI: `npx sv add @genclass` sets up GenClass in a SvelteKit app (the dependency, its import first in `src/hooks.client`, the devtools overlay in development). [README](packages/sv/README.md) |
| [`packages/sv`](packages/sv) | `@genclass/sv` (unreleased), a community add-on for the Svelte CLI: `npx sv add @genclass` sets up GenClass in a SvelteKit app (the dependency and its import first in `src/hooks.client`). [README](packages/sv/README.md) |
| [`docs/runtime`](docs/runtime) | [Docs index](docs/runtime/README.md) · [Results](docs/runtime/RESULTS.md) · [Coding agents](docs/runtime/AGENT.md) · [API](docs/runtime/API.md) · [Architecture](docs/runtime/ARCHITECTURE.md) · [Build contract](docs/runtime/CONTRACT.md) · [Threat model](docs/runtime/THREAT-MODEL.md) |
| [`compat`](compat), [`templates`](templates) | Framework compatibility matrix (7 apps, 15 data layers, every mode; [RESULTS.md](compat/RESULTS.md)) and eight starter templates with the one line (React + Vite, Next.js, Vue + Vite, SvelteKit, Astro, Nuxt, React Router, Angular; [templates/README.md](templates/README.md)) |
| [`demos`](demos), [`bench`](bench) | Six demo apps (typeahead, autosave, checkout, flaky dashboard, live kanban, real-time decisions) with a Service Worker chaos backend and Playwright trials; [`bench/heal`](bench/heal) runs them per mode, [`bench/visual`](bench/visual) measures the visual checks |
Expand Down
12 changes: 7 additions & 5 deletions compat/templates-check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
// own build, type check included), then in headless Chromium:
// prod the production server: the model loads, the search box works, no console errors, no overlay;
// with ?genclass=off nothing is installed
// dev the dev server: the devtools overlay mounts, no console errors
// dev the dev server: the same without the ?genclass=off visit, and a 5 s wait for a late overlay mount (a
// template draws nothing on the page; the devtools overlay is opt-in)
// Linux only (the VM). Telemetry is opted out through localStorage["genclass.telemetry"] = "off" (the template code
// is not changed); every request to another host is blocked, the model is served from COMPAT_MODEL_DIR.
//
Expand Down Expand Up @@ -94,7 +95,7 @@ async function serve(cmd, cwd) {
throw new Error(`server did not start: ${cmd}\n${out.slice(-1500)}`);
}

async function visit(browser, url, { type = false, wantOverlay = null }) {
async function visit(browser, url, { type = false, overlayWaitMs = 0 }) {
const ctx = await browser.newContext();
const blocked = [];
await ctx.route((u) => u.hostname !== "127.0.0.1" && u.hostname !== "localhost", (r) => {
Expand Down Expand Up @@ -133,7 +134,8 @@ async function visit(browser, url, { type = false, wantOverlay = null }) {
await sleep(2500);
r.results = await page.$$eval("li", (els) => els.map((e) => e.textContent));
} else await sleep(3000);
if (wantOverlay !== null) r.overlay = !!(await page.waitForSelector("genclass-devtools", { state: "attached", timeout: wantOverlay ? 30_000 : 1_500 }).catch(() => null));
// the overlay must stay absent: waits this long for a late mount before calling it absent
if (overlayWaitMs) r.overlay = !!(await page.waitForSelector("genclass-devtools", { state: "attached", timeout: overlayWaitMs }).catch(() => null));
r.disabled = consoleLines.some((l) => /\[GenClass\] Disabled by \?genclass=off/.test(l));
} catch (e) {
r.error = String(e?.message ?? e).slice(0, 800);
Expand Down Expand Up @@ -191,11 +193,11 @@ async function checkTemplate(name, browser) {
let s;
try {
s = await serve(t[kind], dir);
const main = await visit(browser, `${s.url}/`, { type: true, wantOverlay: kind === "dev" });
const main = await visit(browser, `${s.url}/`, { type: true, overlayWaitMs: kind === "dev" ? 5_000 : 1_500 });
const off = kind === "prod" ? await visit(browser, `${s.url}/?genclass=off`, { type: false }) : null;
rec[kind] = { main, off };
rec[kind].pass =
!main.error && main.modelReady && (main.results ?? []).length > 0 && main.errors.length === 0 && main.blocked.length === 0 && main.overlay === (kind === "dev") && (!off || (off.disabled && off.errors.length === 0));
!main.error && main.modelReady && (main.results ?? []).length > 0 && main.errors.length === 0 && main.blocked.length === 0 && main.overlay === false && (!off || (off.disabled && off.errors.length === 0));
} catch (e) {
rec[kind] = { pass: false, error: String(e?.message ?? e).slice(0, 1500) };
} finally {
Expand Down
4 changes: 2 additions & 2 deletions docs/adoption/listings/svelte.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ on the form itself; check them when submitting.

Longer description, if the form has one:

> A community add-on for the Svelte CLI. `npx sv add @genclass` adds `@genclass/runtime`, imports it first in
> `src/hooks.client`, and loads the GenClass overlay in development only. GenClass watches fetch, XHR, WebSocket,
> A community add-on for the Svelte CLI. `npx sv add @genclass` adds `@genclass/runtime` and imports it first in
> `src/hooks.client`; nothing is drawn on the page. GenClass watches fetch, XHR, WebSocket,
> EventSource and user input in the browser and reports stale responses, duplicate requests, retries and failure
> storms; it starts in observe mode, which never changes a request. Its model (about 13 MB, cached) is downloaded from
> jsDelivr on a browser's first visit. The add-on writes GenClass's telemetry opt-out unless you choose to send
Expand Down
4 changes: 4 additions & 0 deletions docs/runtime/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -1019,6 +1019,10 @@ look"; there is no Sentry, PostHog or Datadog adapter in the free runtime), `@ge
From 0.3.0-beta.1 (npm dist-tag `beta`) the devtools overlay is in genclass.dev's black design whatever the page's theme
(`theme: "dark"`, the new default; `"light"` is the same design on white, `"auto"` follows `prefers-color-scheme`).
0.3.0-beta.0 and 0.2.x use their earlier design and default to `"auto"`.
Nothing GenClass sets up mounts the overlay: you add it yourself (`mountDevtools`, `devtools` in the page
configuration, `data-devtools` on the script tag). `init` adds it only with `--devtools`, `@genclass/nuxt` and
`@genclass/astro` only with `devtools: "dev"` or `"always"` (default `"never"`), and the Svelte CLI add-on, the
`genclass` command and the starter templates never; `init` of 0.3.0-beta.6 and earlier added it by default.

To integrate another state library use:

Expand Down
11 changes: 6 additions & 5 deletions docs/runtime/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ default ([CHANGELOG](../../packages/runtime/CHANGELOG.md)).
## How do I install it with one command?

`init` finds your framework and package manager, installs the package, adds one import as the first line of your
entry file (plus a line that loads the devtools overlay in development only), and shows you the diff before writing
anything. Running it again changes nothing; running it with another `--mode` switches the import it added. All of
entry file, and shows you the diff before writing anything. It draws nothing on your pages (the devtools overlay
only with `--devtools`). Running it again changes nothing; running it with another `--mode` switches the import it added. All of
the ways below start the same runtime, in observe mode unless you choose otherwise.

```bash
Expand Down Expand Up @@ -59,7 +59,7 @@ Content-Security-Policy (`next.config` headers, a proxy or middleware, a `<meta
| `--yes`, `-y` | both | apply without asking |
| `--dry-run` | both | show what would change; write nothing, send nothing |
| `--no-install` | init | do not run the package manager |
| `--no-devtools` | init | do not add the dev-only devtools overlay |
| `--devtools` | init | also add the devtools overlay, in development builds only (off by default; `init` of 0.3.0-beta.6 and earlier added it unless `--no-devtools`, which is still accepted and changes nothing) |
| `--cwd <dir>` | both | the project directory (default: the current directory) |
| `--from <spec>` | init | install `@genclass/runtime` from this spec (a version, tag or tarball path) |
| `--cdn <url>` | init | plain HTML: the script URL (default: jsDelivr, this version, with an SRI hash; this version's unpkg URL gets one too; other URLs get no hash) |
Expand Down Expand Up @@ -162,11 +162,12 @@ During SSR or in Node, `/auto` installs nothing and returns an inert runtime.
**One script tag** (no build step), first in `<head>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@genclass/runtime@0.3.0-beta.0" data-mode="observe" data-devtools="local"></script>
<script src="https://cdn.jsdelivr.net/npm/@genclass/runtime@0.3.0-beta.0" data-mode="observe"></script>
```

It exposes `window.GenClass` (since `0.3.0` also `window.GenClass.protect`), discovers the app's state like the
import does, and loads the model worker, ONNX Runtime Web and the overlay on demand from the same version on the CDN.
import does, and loads the model worker and ONNX Runtime Web on demand from the same version on the CDN (and the
devtools overlay, only with `data-devtools`).
Its `data-*` attributes configure it ([every attribute](#which-attributes-does-the-script-tag-take)). Keep the
version pinned in production; the plain-HTML path of `init` writes a pinned jsDelivr URL with SRI.

Expand Down
Loading
Loading