diff --git a/AGENTS.md b/AGENTS.md
index edf0ff38..9414d039 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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 |
diff --git a/README.md b/README.md
index c4539a09..056cc428 100644
--- a/README.md
+++ b/README.md
@@ -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`):
@@ -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
@@ -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
@@ -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 |
diff --git a/compat/templates-check.mjs b/compat/templates-check.mjs
index f27cf2ac..be5bd2eb 100644
--- a/compat/templates-check.mjs
+++ b/compat/templates-check.mjs
@@ -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.
//
@@ -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) => {
@@ -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);
@@ -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 {
diff --git a/docs/adoption/listings/svelte.md b/docs/adoption/listings/svelte.md
index 70824eb9..621e80f3 100644
--- a/docs/adoption/listings/svelte.md
+++ b/docs/adoption/listings/svelte.md
@@ -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
diff --git a/docs/runtime/API.md b/docs/runtime/API.md
index 01b5ac03..7f24284f 100644
--- a/docs/runtime/API.md
+++ b/docs/runtime/API.md
@@ -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:
diff --git a/docs/runtime/INSTALL.md b/docs/runtime/INSTALL.md
index 1cc2c4ef..4dcd8482 100644
--- a/docs/runtime/INSTALL.md
+++ b/docs/runtime/INSTALL.md
@@ -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
@@ -59,7 +59,7 @@ Content-Security-Policy (`next.config` headers, a proxy or middleware, a `` | both | the project directory (default: the current directory) |
| `--from ` | init | install `@genclass/runtime` from this spec (a version, tag or tarball path) |
| `--cdn ` | 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) |
@@ -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 ``:
```html
-
+
```
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.
diff --git a/packages/astro/CHANGELOG.md b/packages/astro/CHANGELOG.md
index c8995c1d..8a578236 100644
--- a/packages/astro/CHANGELOG.md
+++ b/packages/astro/CHANGELOG.md
@@ -6,9 +6,9 @@
[`@genclass/runtime`](https://www.npmjs.com/package/@genclass/runtime) the recommended way, in the browser only.
In `astro:config:setup` it injects, as a `page` script on every page, the runtime's own zero-code entry
(`@genclass/runtime/auto`, or `/auto/guard` for `mode: "guard"`); `token` and `telemetry` are written to
- `window.GENCLASS_CONFIG` by a virtual module imported before the runtime. The devtools overlay loads under
- `astro dev` only (`devtools: "dev"`, the default), also in builds with `"always"`, never with `"never"`. Nothing runs
- on the server. `astro` (4 or later; tested with 7.4) and `@genclass/runtime` (`>=0.3.0-beta.1`, the newest
+ `window.GENCLASS_CONFIG` by a virtual module imported before the runtime. Nothing is drawn on the page by
+ default (`devtools: "never"`, owner, 2026-11-16); the devtools overlay is opt-in: `"dev"` loads it under `astro dev`
+ only, `"always"` also in builds. Nothing runs on the server. `astro` (4 or later; tested with 7.4) and `@genclass/runtime` (`>=0.3.0-beta.1`, the newest
line: `npm install @genclass/runtime@beta`; npm's `latest`, 0.2.x, does not satisfy it) are peer dependencies. Keywords `astro-integration` and `withastro` for the integrations library and `astro add`.
- The runtime modules the script imports are added to Vite's `optimizeDeps.include`: the injected script is a virtual
module Vite's dependency scan does not see, and without this `astro dev` discovered them on the first page request
diff --git a/packages/astro/README.md b/packages/astro/README.md
index 8578c0c4..bf136bd2 100644
--- a/packages/astro/README.md
+++ b/packages/astro/README.md
@@ -7,7 +7,7 @@ state, and reports them while they happen.
GenClass is a browser library with a small local model (ONNX, in a Web Worker). It observes what your pages do at the
network boundary (fetch, XHR, WebSocket, EventSource), user actions, timers and errors, and asks the model about the
situations that matter: a response that arrives after newer data, two identical requests in flight, a request storm.
-In the default `observe` mode it reports (one console line per finding, the devtools overlay) and changes nothing;
+In the default `observe` mode it reports (one console line per finding; nothing is drawn on the page) and changes nothing;
`guard` mode, opt-in, lets it drop a stale response or reuse a duplicate's result when the model is confident. It is
Apache-2.0, runs on-device, and never sends page content unless you opt in. What it finds and how often, with the
false-intervention rate next to every recall number, is in the runtime's
@@ -51,7 +51,7 @@ export default defineConfig({
genclass({
mode: "observe", // or "guard"
telemetry: false, // no anonymous diagnostics
- devtools: "dev", // "always" | "never"
+ devtools: "never", // the default: nothing drawn on the page; "dev" | "always" add the overlay
token: "gc_...", // your app's dashboard token (optional)
}),
],
@@ -65,7 +65,7 @@ export default defineConfig({
| `mode` | `"observe"`, `"guard"` | `"observe"` | `observe` reports what GenClass finds and never holds, delays or changes anything. `guard` also prevents failures with small, reversible actions (drop a stale response, reuse a duplicate's result) when the model is confident. The script imports `@genclass/runtime/auto` or `@genclass/runtime/auto/guard` accordingly. |
| `token` | `"gc_..."` | none | Your app's token from [genclass.dev](https://genclass.dev) or `npx @genclass/runtime@beta login`; with telemetry on, findings also reach your dashboard. Needs `@genclass/runtime` 0.3.0 or later (0.2.x ignores it). |
| `telemetry` | `true`, `false` | the runtime's default | Anonymous, redacted diagnostics to the GenClass maintainers ([TELEMETRY.md](https://github.com/genclass-dev/GenClass/blob/main/packages/runtime/TELEMETRY.md)). Unset: on from public hosts, off on localhost and private networks. `false`: off. `true`: an explicit opt-in that also sends from local hosts. |
-| `devtools` | `"dev"`, `"always"`, `"never"` | `"dev"` | The devtools overlay (detections, actions, the evidence behind each decision, a mode switch). `"dev"` loads it under `astro dev` only; a production build carries no reference to it. `"always"` loads it in production too. The overlay is a lazy chunk, never part of the first load. |
+| `devtools` | `"never"`, `"dev"`, `"always"` | `"never"` | The devtools overlay, opt-in. `"never"`: nothing is drawn on the page; findings go to the browser console (and to your dashboard with a `token`). `"dev"` loads the overlay under `astro dev` only, and a production build carries no reference to it; `"always"` loads it in production too. The overlay is a lazy chunk, never part of the first load. |
`token` and `telemetry` are passed to the runtime as `window.GENCLASS_CONFIG`, the page configuration it documents, by
a virtual module the script imports before the runtime. Everything else GenClass offers (`policy`, `sinks`, `routes`,
diff --git a/packages/astro/src/index.ts b/packages/astro/src/index.ts
index f95aaf5b..5d70323f 100644
--- a/packages/astro/src/index.ts
+++ b/packages/astro/src/index.ts
@@ -4,15 +4,16 @@
// that sets `window.GENCLASS_CONFIG` (token, telemetry). Invariants: browser only (a page script never runs on the
// server, and the integration itself runs at config time only); GenClass behaves exactly as with the one-line install
// (observe by default, automatic state discovery for React islands, the `?genclass=off` kill switch, a
-// `` tag still read); the devtools overlay line is injected in `astro dev` only unless
-// `devtools: "always"` asks for it. The generated code is pure (pageScript, configSource), so the tests check it exactly.
+// `` tag still read); nothing is drawn on the page by default (`devtools: "never"`): the
+// overlay line is injected only when `devtools` asks for it ("dev" under `astro dev`, "always"). The generated code is
+// pure (pageScript, configSource), so the tests check it exactly.
import type { AstroIntegration } from "astro";
/** Options of `genclass(options)` in astro.config. */
export interface GenClassOptions {
/**
- * "observe" (default): GenClass reports what it finds (one console line per finding, the devtools overlay) and
+ * "observe" (default): GenClass reports what it finds (one console line per finding) and
* never holds, delays or changes anything. "guard": it may also take small, reversible actions (drop a stale
* response, reuse a duplicate's result) when its model is confident.
*/
@@ -29,8 +30,9 @@ export interface GenClassOptions {
*/
telemetry?: boolean;
/**
- * The devtools overlay: "dev" (default) loads it in `astro dev` only, "always" also in production builds, "never"
- * not at all. The overlay is a lazy chunk that is never part of the first load.
+ * The devtools overlay: "never" (default) adds nothing that draws on the page; findings go to the browser console
+ * (and the dashboard with a token). "dev" loads the overlay in `astro dev` only, "always" also in production builds.
+ * The overlay is a lazy chunk that is never part of the first load.
*/
devtools?: "dev" | "always" | "never";
}
@@ -71,9 +73,9 @@ export function entryFor(mode: GenClassOptions["mode"]): string {
return mode === "guard" ? "@genclass/runtime/auto/guard" : "@genclass/runtime/auto";
}
-/** Whether the overlay loads: "always", or "dev" under `astro dev`. */
+/** Whether the overlay loads: "always", or "dev" under `astro dev`; never by default (unset or "never"). */
export function overlayFor(devtools: GenClassOptions["devtools"], dev: boolean): boolean {
- return devtools === "always" || ((devtools ?? "dev") === "dev" && dev);
+ return devtools === "always" || (devtools === "dev" && dev);
}
/** The virtual config module: sets window.GENCLASS_CONFIG. Keys already set on the page (a head script) win. */
diff --git a/packages/astro/test/integration.test.ts b/packages/astro/test/integration.test.ts
index e5f3984f..12ac72c7 100644
--- a/packages/astro/test/integration.test.ts
+++ b/packages/astro/test/integration.test.ts
@@ -30,9 +30,8 @@ function runHook(options: Parameters[0], command: "dev" | "buil
}
describe("pageScript: the script injected into every page", () => {
- it("defaults: /auto, no config import, the overlay under astro dev only", () => {
- const dev = pageScript({}, true);
- expect(dev).toBe('import genclass from "@genclass/runtime/auto";\nimport("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));\n');
+ it("defaults: /auto, no config import, and nothing drawn on the page (no overlay, not even under astro dev)", () => {
+ expect(pageScript({}, true)).toBe('import "@genclass/runtime/auto";\n');
expect(pageScript({}, false)).toBe('import "@genclass/runtime/auto";\n');
});
@@ -42,10 +41,14 @@ describe("pageScript: the script injected into every page", () => {
expect(pageScript({ mode: "guard" }, false)).toBe('import "@genclass/runtime/auto/guard";\n');
});
- it("devtools: always loads the overlay in builds too, never not even in dev", () => {
+ it("devtools (opt-in): dev loads the overlay under astro dev only, always in builds too; unset or never not at all", () => {
expect(overlayFor("always", false)).toBe(true);
expect(overlayFor("never", true)).toBe(false);
+ expect(overlayFor("dev", true)).toBe(true);
+ expect(overlayFor("dev", false)).toBe(false);
+ expect(overlayFor(undefined, true)).toBe(false);
expect(overlayFor(undefined, false)).toBe(false);
+ expect(pageScript({ devtools: "dev" }, true)).toBe('import genclass from "@genclass/runtime/auto";\nimport("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));\n');
expect(pageScript({ devtools: "always" }, false)).toContain("mountDevtools");
expect(pageScript({ devtools: "never" }, true)).not.toContain("devtools");
});
@@ -77,18 +80,20 @@ describe("the astro:config:setup hook", () => {
expect(optimize).toEqual(["@genclass/runtime/auto"]);
});
- it("under astro dev the script also mounts the overlay; under build it does not", () => {
- expect(runHook({}, "dev").scripts[0].content).toContain("mountDevtools");
- expect(runHook({}, "build").scripts[0].content).not.toContain("devtools");
- expect(runHook({}, "preview").scripts[0].content).not.toContain("devtools");
+ it("by default the script mounts no overlay under dev, build or preview; devtools: dev mounts it under astro dev only", () => {
+ for (const command of ["dev", "build", "preview"] as const) expect(runHook({}, command).scripts[0].content).not.toContain("devtools");
+ expect(runHook({ devtools: "dev" }, "dev").scripts[0].content).toContain("mountDevtools");
+ expect(runHook({ devtools: "dev" }, "build").scripts[0].content).not.toContain("devtools");
expect(runHook({ devtools: "always" }, "build").scripts[0].content).toContain("mountDevtools");
});
it("pre-declares the runtime modules the script imports for Vite's dependency optimizer", () => {
expect(runtimeImports({}, false)).toEqual(["@genclass/runtime/auto"]);
- expect(runtimeImports({}, true)).toEqual(["@genclass/runtime/auto", "@genclass/runtime/devtools"]);
+ expect(runtimeImports({}, true)).toEqual(["@genclass/runtime/auto"]);
+ expect(runtimeImports({ devtools: "dev" }, true)).toEqual(["@genclass/runtime/auto", "@genclass/runtime/devtools"]);
expect(runtimeImports({ mode: "guard", devtools: "never" }, true)).toEqual(["@genclass/runtime/auto/guard"]);
- expect(runHook({}, "dev").optimize).toEqual(["@genclass/runtime/auto", "@genclass/runtime/devtools"]);
+ expect(runHook({}, "dev").optimize).toEqual(["@genclass/runtime/auto"]);
+ expect(runHook({ devtools: "dev" }, "dev").optimize).toEqual(["@genclass/runtime/auto", "@genclass/runtime/devtools"]);
expect(runHook({ mode: "guard" }, "build").optimize).toEqual(["@genclass/runtime/auto/guard"]);
});
diff --git a/packages/nuxt/CHANGELOG.md b/packages/nuxt/CHANGELOG.md
index e26337c3..c1e47b11 100644
--- a/packages/nuxt/CHANGELOG.md
+++ b/packages/nuxt/CHANGELOG.md
@@ -7,8 +7,8 @@
From the `genclass` key of `nuxt.config` (`mode`, `token`, `telemetry`, `devtools`) it generates one client-only
plugin that imports the runtime's own zero-code entry (`@genclass/runtime/auto`, or `/auto/guard` for
`mode: "guard"`) first, before the app's own plugins; `token` and `telemetry` are written to
- `window.GENCLASS_CONFIG` by a module imported before the runtime. The devtools overlay loads in `nuxt dev` only
- (`devtools: "dev"`, the default), also in production with `"always"`, never with `"never"`. Nothing runs on the
- server. `@genclass/runtime` is a peer dependency (`>=0.3.0-beta.1`, the newest line: `npm install @genclass/runtime@beta`;
+ `window.GENCLASS_CONFIG` by a module imported before the runtime. Nothing is drawn on the page by default
+ (`devtools: "never"`, owner, 2026-11-16); the devtools overlay is opt-in: `"dev"` loads it in `nuxt dev` only,
+ `"always"` also in production. Nothing runs on the server. `@genclass/runtime` is a peer dependency (`>=0.3.0-beta.1`, the newest line: `npm install @genclass/runtime@beta`;
npm's `latest`, 0.2.x, has no token, dashboard or analytics and does not satisfy it). Tested with Nuxt 4.6; the
module declares `nuxt: ">=3.17.0"`.
diff --git a/packages/nuxt/README.md b/packages/nuxt/README.md
index d55af5ab..52bfce5d 100644
--- a/packages/nuxt/README.md
+++ b/packages/nuxt/README.md
@@ -7,7 +7,7 @@ and inconsistent state, and reports them while they happen.
GenClass is a browser library with a small local model (ONNX, in a Web Worker). It observes what your app does at
the network boundary (fetch, XHR, WebSocket, EventSource), user actions, timers and errors, and asks the model about
the situations that matter: a response that arrives after newer data, two identical requests in flight, a request
-storm. In the default `observe` mode it reports (one console line per finding, the devtools overlay) and changes
+storm. In the default `observe` mode it reports (one console line per finding; nothing is drawn on the page) and changes
nothing; `guard` mode, opt-in, lets it drop a stale response or reuse a duplicate's result when the model is confident.
It is Apache-2.0, runs on-device, and never sends page content unless you opt in. What it finds and how often, with
the false-intervention rate next to every recall number, is in the runtime's
@@ -42,7 +42,7 @@ export default defineNuxtConfig({
genclass: {
mode: "observe", // or "guard"
telemetry: false, // no anonymous diagnostics
- devtools: "dev", // "always" | "never"
+ devtools: "never", // the default: nothing drawn on the page; "dev" | "always" add the overlay
token: "gc_...", // your app's dashboard token (optional)
},
});
@@ -55,7 +55,7 @@ export default defineNuxtConfig({
| `mode` | `"observe"`, `"guard"` | `"observe"` | `observe` reports what GenClass finds and never holds, delays or changes anything. `guard` also prevents failures with small, reversible actions (drop a stale response, reuse a duplicate's result) when the model is confident. The plugin imports `@genclass/runtime/auto` or `@genclass/runtime/auto/guard` accordingly. |
| `token` | `"gc_..."` | none | Your app's token from [genclass.dev](https://genclass.dev) or `npx @genclass/runtime@beta login`; with telemetry on, findings also reach your dashboard. Needs `@genclass/runtime` 0.3.0 or later (0.2.x ignores it). |
| `telemetry` | `true`, `false` | the runtime's default | Anonymous, redacted diagnostics to the GenClass maintainers ([TELEMETRY.md](https://github.com/genclass-dev/GenClass/blob/main/packages/runtime/TELEMETRY.md)). Unset: on from public hosts, off on localhost and private networks. `false`: off. `true`: an explicit opt-in that also sends from local hosts. |
-| `devtools` | `"dev"`, `"always"`, `"never"` | `"dev"` | The devtools overlay (detections, actions, the evidence behind each decision, a mode switch). `"dev"` loads it in `nuxt dev` only; a production build carries no reference to it. `"always"` loads it in production too. The overlay is a lazy chunk, never part of the first load. |
+| `devtools` | `"never"`, `"dev"`, `"always"` | `"never"` | The devtools overlay, opt-in. `"never"`: nothing is drawn on the page; findings go to the browser console (and to your dashboard with a `token`). `"dev"` loads the overlay in `nuxt dev` only, and a production build carries no reference to it; `"always"` loads it in production too. The overlay is a lazy chunk, never part of the first load. |
`token` and `telemetry` are passed to the runtime as `window.GENCLASS_CONFIG`, the page configuration it documents, by
a small module the plugin imports before the runtime. Everything else GenClass offers (`policy`, `sinks`, `routes`,
diff --git a/packages/nuxt/src/module.ts b/packages/nuxt/src/module.ts
index cbe506f6..7496f942 100644
--- a/packages/nuxt/src/module.ts
+++ b/packages/nuxt/src/module.ts
@@ -3,8 +3,8 @@
// imports before the runtime. Invariants: nothing runs on the server (the plugin is client-only, so the server build
// never imports @genclass/runtime); the module only chooses the runtime's documented entry (`/auto` or `/auto/guard`)
// and its documented page configuration (`window.GENCLASS_CONFIG`), so GenClass behaves exactly as with the one-line
-// install; the devtools overlay loads in `nuxt dev` only unless `devtools: "always"` asks for it. The generated code
-// is in source.ts, where the tests check it.
+// install; nothing is drawn on the page unless `devtools` asks for the overlay ("dev": `nuxt dev` only, "always").
+// The generated code is in source.ts, where the tests check it.
import { addPluginTemplate, addTemplate, defineNuxtModule } from "@nuxt/kit";
import { configSource, pageConfig, pluginSource, validate, type ModuleOptions } from "./source";
@@ -17,7 +17,7 @@ export default defineNuxtModule({
configKey: "genclass",
compatibility: { nuxt: ">=3.17.0" },
},
- defaults: { mode: "observe", devtools: "dev" },
+ defaults: { mode: "observe", devtools: "never" },
setup(options, nuxt) {
validate(options);
const cfg = pageConfig(options);
diff --git a/packages/nuxt/src/source.ts b/packages/nuxt/src/source.ts
index 570f0545..667a1fb6 100644
--- a/packages/nuxt/src/source.ts
+++ b/packages/nuxt/src/source.ts
@@ -5,13 +5,13 @@
// discovery, the `?genclass=off` kill switch, a `` tag still read); the options that are not the
// import path (token, telemetry) travel as `window.GENCLASS_CONFIG`, the page configuration the runtime documents, in a
// module imported before the runtime (an ES module's imports evaluate before its own body, so the config is set when
-// the runtime starts); the devtools overlay line is only generated when the overlay should load, so a production
-// build carries no reference to it unless `devtools: "always"` asks for one.
+// the runtime starts); nothing is drawn on the page by default (`devtools: "never"`): the overlay line is only
+// generated when `devtools` asks for it ("dev" in `nuxt dev`, "always"), so a build carries no reference to it.
/** Options of the `genclass` key in nuxt.config. */
export interface ModuleOptions {
/**
- * "observe" (default): GenClass reports what it finds (one console line per finding, the devtools overlay) and
+ * "observe" (default): GenClass reports what it finds (one console line per finding) and
* never holds, delays or changes anything. "guard": it may also take small, reversible actions (drop a stale
* response, reuse a duplicate's result) when its model is confident.
*/
@@ -28,8 +28,9 @@ export interface ModuleOptions {
*/
telemetry?: boolean;
/**
- * The devtools overlay: "dev" (default) loads it in `nuxt dev` only, "always" also in production builds, "never"
- * not at all. The overlay is a lazy chunk that is never part of the first load.
+ * The devtools overlay: "never" (default) adds nothing that draws on the page; findings go to the browser console
+ * (and the dashboard with a token). "dev" loads the overlay in `nuxt dev` only, "always" also in production builds.
+ * The overlay is a lazy chunk that is never part of the first load.
*/
devtools?: "dev" | "always" | "never";
}
@@ -66,9 +67,9 @@ export function entryFor(mode: ModuleOptions["mode"]): string {
return mode === "guard" ? "@genclass/runtime/auto/guard" : "@genclass/runtime/auto";
}
-/** Whether the overlay loads: "always", or "dev" on a development server. */
+/** Whether the overlay loads: "always", or "dev" on a development server; never by default (unset or "never"). */
export function overlayFor(devtools: ModuleOptions["devtools"], dev: boolean): boolean {
- return devtools === "always" || ((devtools ?? "dev") === "dev" && dev);
+ return devtools === "always" || (devtools === "dev" && dev);
}
/** `#build/genclass.config.mjs`: sets window.GENCLASS_CONFIG. Keys already set on the page (a head script) win. */
diff --git a/packages/nuxt/test/module.test.ts b/packages/nuxt/test/module.test.ts
index e9a06285..13cde8b7 100644
--- a/packages/nuxt/test/module.test.ts
+++ b/packages/nuxt/test/module.test.ts
@@ -20,15 +20,16 @@ function readAll(dir: string, re: RegExp): string {
}
describe("source: the plugin and config modules the module generates", () => {
- it("defaults: /auto, no config import, the overlay in development only", () => {
- const dev = pluginSource({}, true);
- expect(dev).toContain('import genclass from "@genclass/runtime/auto";');
- expect(dev).not.toContain("#build/genclass.config.mjs");
- expect(dev).toContain('import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));');
- const prod = pluginSource({}, false);
- expect(prod).toContain('import "@genclass/runtime/auto";');
- expect(prod).not.toContain("devtools");
- expect(prod).toContain("export default defineNuxtPlugin(() => {});");
+ it("defaults: /auto, no config import, and nothing drawn on the page (no overlay, not even in nuxt dev)", () => {
+ for (const dev of [true, false]) {
+ const plugin = pluginSource({}, dev);
+ expect(plugin).toContain('import "@genclass/runtime/auto";');
+ expect(plugin).not.toContain("#build/genclass.config.mjs");
+ expect(plugin).not.toContain("devtools");
+ expect(plugin).toContain("export default defineNuxtPlugin(() => {});");
+ }
+ // the module's own default says the same (owner, 2026-11-16: nothing GenClass sets up is drawn on a page)
+ expect(readFileSync(fileURLToPath(new URL("../src/module.ts", import.meta.url)), "utf8")).toContain('defaults: { mode: "observe", devtools: "never" }');
});
it("mode guard imports /auto/guard", () => {
@@ -38,12 +39,17 @@ describe("source: the plugin and config modules the module generates", () => {
expect(pluginSource({ mode: "guard" }, false)).toContain('import "@genclass/runtime/auto/guard";');
});
- it("devtools: always loads the overlay in production too, never not even in development", () => {
+ it("devtools (opt-in): dev loads the overlay in development only, always in production too; unset or never not at all", () => {
expect(overlayFor("always", false)).toBe(true);
expect(overlayFor("never", true)).toBe(false);
expect(overlayFor("dev", true)).toBe(true);
expect(overlayFor("dev", false)).toBe(false);
- expect(overlayFor(undefined, true)).toBe(true);
+ expect(overlayFor(undefined, true)).toBe(false);
+ expect(overlayFor(undefined, false)).toBe(false);
+ const dev = pluginSource({ devtools: "dev" }, true);
+ expect(dev).toContain('import genclass from "@genclass/runtime/auto";');
+ expect(dev).toContain('import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));');
+ expect(pluginSource({ devtools: "dev" }, false)).not.toContain("devtools");
expect(pluginSource({ devtools: "always" }, false)).toContain("mountDevtools");
expect(pluginSource({ devtools: "never" }, true)).not.toContain("devtools");
});
diff --git a/packages/runtime/CHANGELOG.md b/packages/runtime/CHANGELOG.md
index dbb78186..509314f7 100644
--- a/packages/runtime/CHANGELOG.md
+++ b/packages/runtime/CHANGELOG.md
@@ -2,6 +2,14 @@
## Unreleased
+- **`init` no longer adds the devtools overlay** (owner, 2026-11-16: nothing GenClass sets up is drawn on a page;
+ findings go to the console, the dashboard and the terminal). The overlay is opt-in: `init --devtools` adds the
+ dev-only line as before. `--no-devtools` is still accepted and changes nothing. Running `init` again on a setup
+ that still loads the overlay (made by `init` 0.3.0-beta.6 or earlier) names the file and says what to delete: the
+ statement that imports `@genclass/runtime/devtools`, or `data-devtools="local"` on a script tag; `remove` still
+ takes out the rest. The hand-install help shows the script tag without `data-devtools`. The overlay itself, and
+ `mountDevtools`, `devtools` / `data-devtools` in the page configuration, are unchanged (`bin/lib/init.mjs`).
+
- `scan --hosted`: on a computer signed in to genclass.dev (`login`), the page check is asked on genclass.dev with
that sign-in, so an account with Pro gets the whole report (since 2026-11-15 the page check's score and findings
are Pro's). Without Pro the report is the free view: how many problems and how serious, one finding in full, and
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
index a600a5ce..6d5388f7 100644
--- a/packages/runtime/README.md
+++ b/packages/runtime/README.md
@@ -467,7 +467,8 @@ For a site whose performance budget has no room in the page load, there is the
[lite install](#lite-install-after-the-page-has-loaded): GenClass after the page has loaded, on a share of page loads.
**1. 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 dev-only devtools line), and shows you the diff before writing anything.
+first line of your entry file, and shows you the diff before writing anything. It draws nothing on your pages: the
+devtools overlay is added only with `--devtools` (development builds only).
```bash
npx @genclass/runtime@beta init # observe; shows the diff, asks, then writes
@@ -478,7 +479,10 @@ npx @genclass/runtime@beta remove # undo exactly what init added
Other flags: `--yes`, `--no-telemetry` (`--telemetry` undoes it on a later run and writes no telemetry option, so
the default applies: on, but off on local hosts), `--no-token`, `--token gc_...`, `--sink`, `--model-url`, `--no-install`,
-`--no-devtools`, and from `0.3.0-beta.2` `--no-network` and `--sync` (plain HTML).
+`--devtools`, and from `0.3.0-beta.2` `--no-network` and `--sync` (plain HTML). `init` of 0.3.0-beta.6 and earlier
+added the overlay by default (`--no-devtools` left it out; it is still accepted and changes nothing); running `init`
+again on such a setup names the file, and deleting the one statement that imports `@genclass/runtime/devtools`
+(`data-devtools="local"` on a script tag) takes it out.
**Which version** (from `0.3.0-beta.2`). `init` (and `login`, `connect`) first prints its own version and the npm
dist-tag it came from, asks npm's dist-tags once (`npm view @genclass/runtime dist-tags`, at most 3 s; never with
@@ -519,7 +523,7 @@ Options go in `window.GENCLASS_CONFIG = { ... }` (any `InitOptions`, set before
**3. One script tag** (no build step), first in ``:
```html
-
+
```
It exposes `window.GenClass` and loads the model worker and the overlay on demand from the same version; `data-mode`,
@@ -527,8 +531,9 @@ It exposes `window.GenClass` and loads the model worker and the overlay on deman
([every attribute](https://github.com/genclass-dev/GenClass/blob/main/docs/runtime/INSTALL.md#which-attributes-does-the-script-tag-take)).
Keep the version pinned: the unversioned URL serves npm's `latest` (the older `0.2.x` until `0.3.0` is stable); on a
plain HTML page `init` writes a pinned jsDelivr URL with SRI and, from `0.3.0-beta.2`, `defer`.
-`data-devtools="local"` shows the overlay on local hosts (loopback with or without a port, `*.localhost`, `*.local`,
-`*.test` and `file:`), so also in a Capacitor, Tauri or Electron build that ships it: set it per environment.
+Nothing is drawn on the page unless you ask: `data-devtools="local"` adds the overlay on local hosts (loopback with
+or without a port, `*.localhost`, `*.local`, `*.test` and `file:`), so also in a Capacitor, Tauri or Electron build
+that ships it: set it per environment.
**4. By hand:** `npm install @genclass/runtime@beta`, then first in your entry file:
@@ -580,12 +585,7 @@ export {};
```ts
// genclass.ts, next to instrumentation-client.ts
import "./genclass.config"; // optional: sets window.GENCLASS_CONFIG, so it comes before the runtime
-import genclass from "@genclass/runtime/auto";
-
-// the devtools overlay, in development only (optional)
-if (process.env.NODE_ENV === "development") {
- import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));
-}
+import "@genclass/runtime/auto";
```
Build with `NEXT_PUBLIC_GENCLASS=on next build` (the same for `next dev`), or set it in `.env.production`; any other
diff --git a/packages/runtime/bin/genclass-runtime.mjs b/packages/runtime/bin/genclass-runtime.mjs
index 6136d940..6b7f6044 100755
--- a/packages/runtime/bin/genclass-runtime.mjs
+++ b/packages/runtime/bin/genclass-runtime.mjs
@@ -1,7 +1,7 @@
#!/usr/bin/env node
// genclass-runtime CLI (Node >= 20, no dependencies). Also runs as `npx @genclass/runtime `.
//
-// genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] [--yes] [--dry-run] [--no-install] [--no-devtools]
+// genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] [--yes] [--dry-run] [--no-install] [--devtools]
// genclass-runtime remove [--yes] [--dry-run] [--keep-package]
// Set GenClass up in a project (framework detection, install, one marked import in the entry file, an app token
// and private dashboard link from genclass.dev) and take it out again. Implemented in bin/lib/ (owner: INSTALL).
@@ -57,7 +57,7 @@ const ORT_FILES = {
const ROLES = ["tokenizer", "calibration", "meta"];
const USAGE = `Usage:
- genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] [--yes] [--dry-run] [--no-install] [--no-devtools]
+ genclass-runtime init [--mode observe|guard|heal] [--token | --no-token] [--yes] [--dry-run] [--no-install] [--devtools]
genclass-runtime remove [--yes] [--dry-run] [--keep-package]
genclass-runtime login [--yes] [--no-browser] [--no-connect]
genclass-runtime connect [--app ] [--name ] [--yes] [--dry-run] [--no-install]
diff --git a/packages/runtime/bin/lib/init.mjs b/packages/runtime/bin/lib/init.mjs
index 7003cd07..130c36bb 100644
--- a/packages/runtime/bin/lib/init.mjs
+++ b/packages/runtime/bin/lib/init.mjs
@@ -1,9 +1,9 @@
// `genclass-runtime init` and `genclass-runtime remove` (also `npx @genclass/runtime init|remove`).
//
// init: detects the project, installs @genclass/runtime, adds the auto import as the first statement of the entry
-// file (plus a dev-only devtools line), shows the diff and asks before writing. Every added line or created file
-// carries the marker `genclass:init`, so `remove` can take out exactly that and nothing else (and refuses when a
-// marked line or block was edited). Running init twice changes nothing; running it again with another --mode
+// file, shows the diff and asks before writing. Nothing it adds draws on a page unless --devtools asks for the
+// dev-only overlay. Every added line or created file carries the marker `genclass:init`, so `remove` can take out
+// exactly that and nothing else (and refuses when a marked line or block was edited). Running init twice changes nothing; running it again with another --mode
// switches the marked import (or the script tag's data-mode) to that mode in place.
//
// Signed in (`login`, account.mjs), init asks before anything is sent whether a new app goes into the account
@@ -46,14 +46,14 @@ export const USAGE = `Usage:
genclass-runtime init [--mode observe|guard|heal] [--token | --no-token]
[--no-telemetry | --telemetry] [--model-url ]
[--sink console-json|webhook:]
- [--yes] [--dry-run] [--no-install] [--no-devtools] [--no-network] [--cwd ]
+ [--yes] [--dry-run] [--no-install] [--devtools] [--no-network] [--cwd ]
genclass-runtime remove [--yes] [--dry-run] [--keep-package] [--cwd ]
init finds your framework, installs ${PKG} (this version, ${VERSION}; an older one already in the
- project is upgraded), adds one import to your entry file (and a dev-only devtools line), shows
- the diff and asks before writing. Running it again changes nothing; with another --mode it
- switches the import init added to that mode. It prints its own version and asks npm's dist-tags
- (at most 3 s) whether a newer release exists.
+ project is upgraded), adds one import to your entry file, shows the diff and asks before
+ writing. It draws nothing on your pages unless you pass --devtools. Running it again changes
+ nothing; with another --mode it switches the import init added to that mode. It prints its own
+ version and asks npm's dist-tags (at most 3 s) whether a newer release exists.
remove takes out exactly what init added (the lines and blocks marked "${MARK}"; it changes nothing if
one of them was edited, though attributes added to its script tag, such as defer, are fine) and
uninstalls the package if nothing else imports it.
@@ -85,7 +85,8 @@ remove takes out exactly what init added (the lines and blocks marked "${MARK}
--yes, -y apply without asking
--dry-run show what would change; write nothing
--no-install do not run the package manager
- --no-devtools do not add the dev-only devtools overlay
+ --devtools also add the devtools overlay on your dev pages (off by default; --no-devtools
+ is still accepted and changes nothing)
--no-network do not ask npm for newer releases (--dry-run, --no-token and --no-telemetry do not
ask either)
--keep-package remove: leave ${PKG} installed
@@ -104,6 +105,7 @@ const BOOL = {
y: "yes",
"dry-run": "dryRun",
"no-install": "noInstall",
+ devtools: "devtools",
"no-devtools": "noDevtools",
"no-network": "noNetwork",
"keep-package": "keepPackage",
@@ -266,7 +268,7 @@ function manualHelp(project) {
out(` Add GenClass by hand: one import as the ${c.bold("first")} line of your entry file`);
out(` ${c.cyan(`import "${AUTO()}";`)}`);
out(` or, without a bundler, one tag first in `);
- out(` ${c.cyan(scriptTag({ devtools: true }, PKG_DIR, VERSION).replace(/ integrity="[^"]*" crossorigin="anonymous"/, ""))}`);
+ out(` ${c.cyan(scriptTag({}, PKG_DIR, VERSION).replace(/ integrity="[^"]*" crossorigin="anonymous"/, ""))}`);
if (project?.pkg) out(` and install it: ${c.cyan(installArgs(project.pm ?? "npm", installSpec({})).flat().join(" "))}`);
out();
}
@@ -830,6 +832,24 @@ function olderRuntime(project, cwd) {
return have && compareVersions(have, VERSION) === -1 ? have : null;
}
+// the devtools overlay in what init added: an import of the devtools entry, or a script tag's data-devtools
+const OVERLAY_RE = /["']@genclass\/runtime\/devtools["']|\sdata-devtools\b/;
+
+/**
+ * The files init set up that still load the devtools overlay: init of @genclass/runtime 0.3.0-beta.6 and earlier
+ * added it by default (since then only with --devtools), so a re-run says how to take it out.
+ */
+export function overlayFiles(marked) {
+ return marked.filter((f) => OVERLAY_RE.test(readText(f) ?? ""));
+}
+
+/** The one-row hint for overlayFiles(), or null when there is nothing to say. */
+export function overlayHint(project, rels) {
+ if (!rels.length) return null;
+ const how = project.framework === "html" ? `delete data-devtools="local" from its script tag` : `delete the statement that imports @genclass/runtime/devtools`;
+ return `${rels.join(", ")} still ${rels.length === 1 ? "draws" : "draw"} the devtools overlay on dev pages. GenClass no longer adds it. To drop it, ${how}.`;
+}
+
/** What init finds in the project directory (no writes, no network). */
export function inspectProject(o) {
const cwd = projectDir(o);
@@ -948,6 +968,8 @@ export async function init(o, ctx = {}) {
out();
telemetryNotice(isEmptyConfig(cfg) ? currentConfig(marked) : { ...currentConfig(marked), ...cfg }, null);
tokenRow(tk);
+ const overlay = o.devtools && !HOST_CLI ? null : overlayHint(project, overlayFiles(marked).map((f) => posix(relative(cwd, f))));
+ if (overlay) row("Overlay", overlay, c.yellow(sym.warn));
if (tk.token && !tk.app && !ctx.creds && readCredentials()) more(c.gray(`Signed in: ${CMD} connect adds this app to your account if it is not there yet.`));
sinksNotice(cfg, null);
cspAdvice(project, files, cfg);
@@ -978,8 +1000,9 @@ export async function init(o, ctx = {}) {
return spawn(...installArgs(project.pm, spec), cwd) ? 0 : 1;
}
- // nothing GenClass sets up through a host CLI (genclass) is drawn on a page: the overlay is left out there
- const devtools = !o.noDevtools && !HOST_CLI;
+ // nothing init sets up is drawn on a page unless asked for (--devtools; never through a host CLI such as genclass):
+ // findings go to the console and the dashboard. --no-devtools, the opt-out of 0.3.0-beta.6 and earlier, is a no-op
+ const devtools = !!o.devtools && !o.noDevtools && !HOST_CLI;
const planFor = (config) => planInit(project, { mode: o.mode, devtools, cdn: o.cdn, sri: !o.noSri, sync: !!o.sync, strategy: o.strategy, config }, { pkgDir: PKG_DIR, version: VERSION });
const plan = planFor(cfg);
if (plan.manual || !plan.changes.length) {
diff --git a/packages/runtime/test/install/INSTALL-README-SNIPPET.md b/packages/runtime/test/install/INSTALL-README-SNIPPET.md
index e110f8d2..17665090 100644
--- a/packages/runtime/test/install/INSTALL-README-SNIPPET.md
+++ b/packages/runtime/test/install/INSTALL-README-SNIPPET.md
@@ -9,7 +9,7 @@ npx @genclass/runtime@beta init
```
It finds your framework and package manager, installs `@genclass/runtime`, and adds one import as the first line of
-your entry file, plus a line that loads the devtools overlay in development only. It shows the diff and asks before
+your entry file. It draws nothing on your pages (the devtools overlay only with `--devtools`). It shows the diff and asks before
writing anything. Running it again changes nothing; running it with another `--mode` switches the import it added to
that mode. It sets up observe mode (reports only, never changes anything) unless you pass `--mode guard` or `--mode heal`.
@@ -20,7 +20,7 @@ npx @genclass/runtime@beta init --dry-run # show the diff, write nothing
npx @genclass/runtime@beta remove # undo exactly what init added (refuses if you edited those lines)
```
-Other flags: `--no-install` (don't run the package manager), `--no-devtools`, `--cwd `, `--cdn ` and
+Other flags: `--no-install` (don't run the package manager), `--devtools`, `--cwd `, `--cdn ` and
`--no-sri` and `--sync` (plain HTML: the tag is written with `defer` unless `--sync`), `remove --keep-package`.
`init` only edits browser apps: a project whose only build tool is esbuild, rollup, parcel or webpack needs an
@@ -76,7 +76,7 @@ like:
**3. One script tag** (no build step)
```html
-
+
```
Put it first in `` so it sees the page's first requests. It sets `window.GenClass` (`GenClass.runtime`,
diff --git a/packages/runtime/test/install/account.test.ts b/packages/runtime/test/install/account.test.ts
index 602501d2..5eced6d4 100644
--- a/packages/runtime/test/install/account.test.ts
+++ b/packages/runtime/test/install/account.test.ts
@@ -346,7 +346,7 @@ describe("connect: the app in this folder and an app of the account", () => {
expect(r.code, r.out).toBe(0);
expect(routes(r.calls)).toEqual(["GET /api/me", "POST /api/account/projects"]);
expect(configOf(dir)).toContain(`token: "${NEW_TOKEN}"`);
- expect(readFileSync(join(dir, "src/main.ts"), "utf8").split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import genclass from "@genclass/runtime/auto"; // genclass:init`]);
+ expect(readFileSync(join(dir, "src/main.ts"), "utf8").split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import "@genclass/runtime/auto"; // genclass:init`]);
});
it("a setup made by init --sink keeps its sinks when connect adds the token", () => {
diff --git a/packages/runtime/test/install/cli-sinks.test.ts b/packages/runtime/test/install/cli-sinks.test.ts
index 409287f1..2b43df7c 100644
--- a/packages/runtime/test/install/cli-sinks.test.ts
+++ b/packages/runtime/test/install/cli-sinks.test.ts
@@ -109,7 +109,7 @@ describe("init --sink: findings on the developer's own side", () => {
expect(r.out).toMatch(/Findings\s+webhook:\/genclass \(--sink, written to src\/genclass\.config\.js\)/);
expect(r.out).toContain("batched POSTs of the records to your endpoint");
const after = roundTrip(dir, "--sink", "webhook:/genclass");
- expect(after["src/main.js"].split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import genclass from "@genclass/runtime/auto"; // genclass:init`]);
+ expect(after["src/main.js"].split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import "@genclass/runtime/auto"; // genclass:init`]);
expect(after["src/genclass.config.js"]).toContain(`globalThis.GENCLASS_CONFIG = { sinks: ["webhook:/genclass"] };`);
expect(after["src/genclass.config.js"]).toContain("genclass:init start");
expect(after["src/genclass.config.js"].split("\n").filter((l) => l.startsWith("import "))).toEqual([]);
@@ -200,7 +200,7 @@ describe("init --sink: findings on the developer's own side", () => {
expect(r.out).toContain("sinks webhook:/genclass");
const cfg = join(dir, "src/genclass.config.js");
expect(readFileSync(cfg, "utf8")).toContain(`GENCLASS_CONFIG = { sinks: ["webhook:/genclass"] };`);
- expect(readFileSync(join(dir, "src/main.js"), "utf8").split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import genclass from "@genclass/runtime/auto"; // genclass:init`]);
+ expect(readFileSync(join(dir, "src/main.js"), "utf8").split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import "@genclass/runtime/auto"; // genclass:init`]);
expect(cli(dir, "init", "--yes", "--no-install", "--no-telemetry").code).toBe(0);
expect(readFileSync(cfg, "utf8")).toContain(`GENCLASS_CONFIG = { telemetry: false, sinks: ["webhook:/genclass"] };`);
expect(cli(dir, "init", "--yes", "--no-install", "--sink", "console-json,webhook:/collect").code).toBe(0);
@@ -212,7 +212,7 @@ describe("init --sink: findings on the developer's own side", () => {
it("plain HTML: data-sink on the script tag (what the tag parses back); Astro: sink=a+b in the meta line (what the meta parser reads back)", () => {
const html = roundTrip(project({ "index.html": PAGE }), "--sink", "console-json,webhook:/genclass", "--no-sri");
- expect(html["index.html"]).toContain(` data-devtools="local" data-sink="console-json,webhook:/genclass"> `);
+ expect(html["index.html"]).toContain(` defer data-sink="console-json,webhook:/genclass"> `);
expect(fromDataset({ sink: "console-json,webhook:/genclass" })).toEqual({ sinks: ["console-json", "webhook:/genclass"] });
const dir = project({ "index.html": PAGE });
cli(dir, "init", "--yes", "--no-install", "--sink", "console-json", "--no-sri");
@@ -220,7 +220,7 @@ describe("init --sink: findings on the developer's own side", () => {
expect(readFileSync(join(dir, "index.html"), "utf8")).toContain(`data-sink="webhook:/genclass"`);
expect(readFileSync(join(dir, "index.html"), "utf8")).not.toContain(`data-sink="console-json"`);
const layout = roundTrip(astro(), "--sink", "console-json,webhook:/genclass")["src/layouts/Layout.astro"];
- expect(layout).toMatch(/\t\t \n\t\t\n \n\n`;
describe("init / remove on fixture projects", () => {
- it("Vite + React (TS, single quotes, no semicolons): one import on top, dev overlay at the end", () => {
+ it("Vite + React (TS, single quotes, no semicolons): one import on top; with --devtools, the dev overlay at the end", () => {
const dir = project({
"package.json": pkg({ react: "^19.0.0", vite: "^7.0.0", "@vitejs/plugin-react": "^5" }),
"tsconfig.json": "{}\n",
@@ -117,13 +117,13 @@ describe("init / remove on fixture projects", () => {
expect(r.out).toContain("Vite + React");
expect(r.out).toContain("Dry run");
expect(r.out).toContain("useGenClassState");
- const after = roundTrip(dir);
+ const after = roundTrip(dir, "--devtools");
const main = after["src/main.tsx"];
expect(main.split("\n")[0]).toBe(`import genclass from '@genclass/runtime/auto' // genclass:init`);
expect(main.trimEnd().split("\n").pop()).toBe(`if (import.meta.env.DEV) import('@genclass/runtime/devtools').then((d) => d.mountDevtools(genclass)) // genclass:init`);
});
- it("--mode observe uses /auto/observe; --no-devtools adds a bare import only", () => {
+ it("--mode observe uses /auto/observe; --no-devtools (a no-op since the overlay is opt-in) adds a bare import only", () => {
const dir = project({ "package.json": pkg({ vue: "^3", vite: "^7" }), "index.html": VITE_HTML.replace("main.tsx", "main.js"), "src/main.js": `import { createApp } from "vue";\nimport App from "./App.vue";\n\ncreateApp(App).mount("#app");\n` });
const after = roundTrip(dir, "--mode", "observe", "--no-devtools");
expect(after["src/main.js"]).toBe(`import "@genclass/runtime/auto/observe"; // genclass:init\nimport { createApp } from "vue";\nimport App from "./App.vue";\n\ncreateApp(App).mount("#app");\n`);
@@ -145,7 +145,7 @@ describe("init / remove on fixture projects", () => {
"src/app/layout.tsx": `export default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n`,
"src/app/page.tsx": `export default function Page() { return hi; }\n`,
});
- const after = roundTrip(dir);
+ const after = roundTrip(dir, "--devtools");
const f = after["src/instrumentation-client.ts"];
expect(f).toContain(`import genclass from "@genclass/runtime/auto";`);
expect(f).toContain(`if (process.env.NODE_ENV === "development") {`);
@@ -172,7 +172,7 @@ describe("init / remove on fixture projects", () => {
"pages/_app.js": `import "../styles/globals.css";\n\nexport default function App({ Component, pageProps }) {\n return ;\n}\n`,
"pages/index.js": `export default function Home() { return null; }\n`,
});
- const a = roundTrip(withApp);
+ const a = roundTrip(withApp, "--devtools");
expect(a["pages/_app.js"]).toContain(`typeof window !== "undefined"`);
const noApp = project({ "package.json": pkg({ next: "14.2.0" }), "pages/index.js": `export default function Home() { return null; }\n` });
const b = roundTrip(noApp);
@@ -181,9 +181,9 @@ describe("init / remove on fixture projects", () => {
it("SvelteKit: creates src/hooks.client.ts, or edits an existing one", () => {
const dir = project({ "package.json": pkg({ "@sveltejs/kit": "^2" }), "tsconfig.json": "{}\n", "src/routes/+page.svelte": "
hi
\n" });
- expect(roundTrip(dir)["src/hooks.client.ts"]).toContain("import.meta.env.DEV");
+ expect(roundTrip(dir, "--devtools")["src/hooks.client.ts"]).toContain("import.meta.env.DEV");
const dir2 = project({ "package.json": pkg({ "@sveltejs/kit": "^2" }), "src/hooks.client.js": `export const handleError = ({ error }) => console.error(error);` });
- const after = roundTrip(dir2); // no final newline: restored exactly
+ const after = roundTrip(dir2, "--devtools"); // no final newline: restored exactly
expect(after["src/hooks.client.js"].split("\n")[0]).toBe(`import genclass from "@genclass/runtime/auto"; // genclass:init`);
});
@@ -191,7 +191,7 @@ describe("init / remove on fixture projects", () => {
const n3 = project({ "package.json": pkg({ nuxt: "^3.13.0" }), "tsconfig.json": "{}\n", "app.vue": "\n" });
expect(roundTrip(n3)["plugins/genclass.client.ts"]).toContain("defineNuxtPlugin");
const n4 = project({ "package.json": pkg({ nuxt: "^4.0.0" }), "tsconfig.json": "{}\n", "app/app.vue": "\n" });
- expect(roundTrip(n4)["app/plugins/genclass.client.ts"]).toContain("import.meta.dev");
+ expect(roundTrip(n4, "--devtools")["app/plugins/genclass.client.ts"]).toContain("import.meta.dev");
// the plugins/ directory init created is gone again
expect(() => statSync(join(n4, "app/plugins"))).toThrow();
});
@@ -202,18 +202,18 @@ describe("init / remove on fixture projects", () => {
"src/layouts/Layout.astro": `---\nconst { title } = Astro.props;\n---\n\n\t\n\t\t{title}\n\t\n\t\n\n`,
"src/pages/index.astro": `---\nimport Layout from "../layouts/Layout.astro";\n---\n
hi
\n`,
});
- const after = roundTrip(dir);
+ const after = roundTrip(dir, "--devtools");
expect(after["src/layouts/Layout.astro"]).toContain(`\t\t");
});
it("Angular, CRA, Remix root, React Router entry.client, webpack", () => {
- const ng = roundTrip(project({ "package.json": pkg({ "@angular/core": "^20" }), "src/main.ts": `import { bootstrapApplication } from '@angular/platform-browser';\nimport { App } from './app/app';\n\nbootstrapApplication(App).catch((err) => console.error(err));\n` }));
+ const ng = roundTrip(project({ "package.json": pkg({ "@angular/core": "^20" }), "src/main.ts": `import { bootstrapApplication } from '@angular/platform-browser';\nimport { App } from './app/app';\n\nbootstrapApplication(App).catch((err) => console.error(err));\n` }), "--devtools");
expect(ng["src/main.ts"]).toContain(`import { isDevMode as genclassDevMode } from '@angular/core'; // genclass:init`);
- const cra = roundTrip(project({ "package.json": pkg({ "react-scripts": "5.0.1", react: "^18" }), "src/index.js": `import React from 'react';\n` }));
+ const cra = roundTrip(project({ "package.json": pkg({ "react-scripts": "5.0.1", react: "^18" }), "src/index.js": `import React from 'react';\n` }), "--devtools");
expect(cra["src/index.js"]).toContain(`process.env.NODE_ENV === "development"`);
- const remix = roundTrip(project({ "package.json": pkg({ "@remix-run/react": "^2", vite: "^5" }), "app/root.tsx": `export default function App() { return null; }\n` }));
+ const remix = roundTrip(project({ "package.json": pkg({ "@remix-run/react": "^2", vite: "^5" }), "app/root.tsx": `export default function App() { return null; }\n` }), "--devtools");
expect(remix["app/root.tsx"]).toContain(`import.meta.env.DEV && typeof window !== "undefined"`);
const rr = roundTrip(project({ "package.json": pkg({ "@react-router/dev": "^7" }), "app/entry.client.tsx": `import { HydratedRouter } from "react-router/dom";\n`, "app/root.tsx": "x\n" }));
expect(rr["app/entry.client.tsx"].split("\n")[0]).toContain("@genclass/runtime/auto");
@@ -228,16 +228,17 @@ describe("init / remove on fixture projects", () => {
"about.html": `About`,
"app.js": "fetch('/api');\n",
});
- const after = roundTrip(dir, "--mode", "observe", "--cdn", "https://example.test/genclass.global.min.js", "--no-sri");
+ const after = roundTrip(dir, "--mode", "observe", "--cdn", "https://example.test/genclass.global.min.js", "--no-sri", "--devtools");
expect(after["index.html"]).toContain(`\r\n \r\n `);
expect(after["about.html"]).toContain(``);
});
it("plain HTML: --sync writes the blocking tag of earlier versions; the tag with SRI keeps defer after crossorigin (issue 94)", () => {
const sync = roundTrip(project({ "index.html": PAGE }), "--sync", "--no-sri", "--cdn", "https://example.test/g.js");
- expect(sync["index.html"]).toContain(` `);
+ expect(sync["index.html"]).toContain(` `);
const r = cli(project({ "index.html": PAGE }), "init", "--dry-run");
- expect(r.out).toMatch(/crossorigin="anonymous" defer data-devtools="local"><\/script>/);
+ expect(r.out).toMatch(/crossorigin="anonymous" defer><\/script>/);
+ expect(cli(project({ "index.html": PAGE }), "init", "--dry-run", "--devtools").out).toMatch(/crossorigin="anonymous" defer data-devtools="local"><\/script>/);
});
it("remove tolerates attributes added by hand to the tag init wrote (defer, async, nonce, type), on a line or inline (issue 94)", () => {
@@ -409,9 +410,12 @@ describe("modes: observe is the default; --mode guard / heal install those modes
it("--mode guard / heal write /auto/guard, /auto/heal and data-mode on the script tag", () => {
for (const mode of ["guard", "heal"]) {
const after = roundTrip(viteVue(), "--mode", mode);
- expect(after["src/main.js"].split("\n")[0]).toBe(`import genclass from "@genclass/runtime/auto/${mode}"; // genclass:init`);
+ expect(after["src/main.js"].split("\n")[0]).toBe(`import "@genclass/runtime/auto/${mode}"; // genclass:init`);
const html = roundTrip(project({ "index.html": PAGE }), "--mode", mode, "--no-sri");
- expect(html["index.html"]).toContain(` data-mode="${mode}" data-devtools="local"> `);
+ expect(html["index.html"]).toContain(` data-mode="${mode}"> `);
+ // the mode goes before an opted-in data-devtools, as init has always written it
+ const dev = roundTrip(project({ "index.html": PAGE }), "--mode", mode, "--no-sri", "--devtools");
+ expect(dev["index.html"]).toContain(` data-mode="${mode}" data-devtools="local"> `);
}
const plain = roundTrip(project({ "index.html": PAGE }), "--no-sri");
expect(plain["index.html"]).not.toContain("data-mode");
@@ -449,7 +453,7 @@ describe("modes: observe is the default; --mode guard / heal install those modes
const g = cli(dir, "init", "--yes", "--no-install", "--mode", "guard");
expect(g.code, g.out).toBe(0);
expect(g.out).not.toContain("Nothing to do");
- expect(main().split("\n")[0]).toBe(`import genclass from "@genclass/runtime/auto/guard"; // genclass:init`);
+ expect(main().split("\n")[0]).toBe(`import "@genclass/runtime/auto/guard"; // genclass:init`);
expect(main().replace("/auto/guard", "/auto")).toBe(plainObserve);
expect(cli(dir, "init", "--yes", "--no-install", "--mode", "guard").out).toContain("Nothing to do");
// a dry run shows the switch and writes nothing
@@ -461,7 +465,7 @@ describe("modes: observe is the default; --mode guard / heal install those modes
expect(snapshot(dir)).toEqual(before);
const site = project({ "index.html": PAGE });
- expect(cli(site, "init", "--yes", "--no-sri").code).toBe(0);
+ expect(cli(site, "init", "--yes", "--no-sri", "--devtools").code).toBe(0);
expect(cli(site, "init", "--yes", "--mode", "heal").code).toBe(0);
expect(readFileSync(join(site, "index.html"), "utf8")).toContain(`data-mode="heal" data-devtools="local"> `);
expect(cli(site, "remove", "--yes").code).toBe(0);
@@ -493,11 +497,93 @@ describe("modes: observe is the default; --mode guard / heal install those modes
});
});
+describe("the devtools overlay is opt-in (owner, 2026-11-16: nothing init sets up is drawn on a page)", () => {
+ const apps: Record> = {
+ vite: { "package.json": pkg({ react: "^19", vite: "^7" }), "index.html": VITE_HTML, "src/main.tsx": `console.log(1);\n` },
+ next16: { "package.json": pkg({ next: "16.0.0", react: "^19" }), "node_modules/next/package.json": JSON.stringify({ name: "next", version: "16.0.1" }), "app/page.tsx": `export default function P() { return null; }\n` },
+ next15layout: { "package.json": pkg({ next: "15.1.0" }), "app/layout.tsx": `export default function L({ children }) {\n return (\n \n {children}\n \n );\n}\n` },
+ next14pages: { "package.json": pkg({ next: "14.2.0" }), "pages/index.js": `export default function Home() { return null; }\n` },
+ sveltekit: { "package.json": pkg({ "@sveltejs/kit": "^2" }), "src/routes/+page.svelte": "
hi
\n" },
+ nuxt: { "package.json": pkg({ nuxt: "^4.0.0" }), "app/app.vue": "\n" },
+ astro: { "package.json": pkg({ astro: "^5" }), "src/layouts/Layout.astro": `\n\t\n\t\tx\n\t\n\t\n\n` },
+ angular: { "package.json": pkg({ "@angular/core": "^20" }), "src/main.ts": `bootstrapApplication(App);\n` },
+ cra: { "package.json": pkg({ "react-scripts": "5.0.1", react: "^18" }), "src/index.js": `import React from 'react';\n` },
+ remix: { "package.json": pkg({ "@remix-run/react": "^2", vite: "^5" }), "app/root.tsx": `export default function App() { return null; }\n` },
+ webpack: { "package.json": pkg({ webpack: "^5", "html-webpack-plugin": "^5" }), "src/index.ts": `console.log(1);\n` },
+ html: { "index.html": PAGE },
+ };
+
+ it("init without --devtools writes nothing that loads the overlay, in every kind of project; --no-devtools changes nothing", () => {
+ for (const [name, files] of Object.entries(apps)) {
+ const dir = project(files);
+ const r = cli(dir, "init", "--yes", "--no-install", "--no-sri");
+ expect(r.code, `${name}: ${r.out}`).toBe(0);
+ const after = snapshot(dir);
+ expect(after, name).not.toEqual(snapshot(project(files)));
+ for (const [file, text] of Object.entries(after)) expect(text, `${name}: ${file}`).not.toMatch(/devtools|mountDevtools/);
+ expect(r.out, name).not.toContain("An overlay at the bottom right");
+ // the opt-out of 0.3.0-beta.6 and earlier is still accepted (the genclass command passes it) and writes the same
+ const old = project(files);
+ expect(cli(old, "init", "--yes", "--no-install", "--no-sri", "--no-devtools").code, name).toBe(0);
+ expect(snapshot(old), name).toEqual(after);
+ }
+ });
+
+ it("--devtools adds the dev-only overlay and says where it shows", () => {
+ const dir = project(apps.vite);
+ const r = cli(dir, "init", "--yes", "--no-install", "--devtools");
+ expect(r.code, r.out).toBe(0);
+ expect(readFileSync(join(dir, "src/main.tsx"), "utf8")).toContain(`if (import.meta.env.DEV) import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass)); // genclass:init`);
+ expect(r.out).toContain("An overlay at the bottom right of dev pages");
+ });
+
+ it("init again on a setup that still loads the overlay says how to take it out and changes nothing; that advice leaves a setup remove takes out", () => {
+ for (const name of ["vite", "nuxt"]) {
+ const dir = project(apps[name]);
+ const before = snapshot(dir);
+ expect(cli(dir, "init", "--yes", "--no-install", "--devtools").code, name).toBe(0);
+ const withOverlay = snapshot(dir);
+ const file = name === "vite" ? "src/main.tsx" : "app/plugins/genclass.client.js";
+ const r = cli(dir, "init", "--yes", "--no-install");
+ expect(r.code, r.out).toBe(0);
+ expect(r.out).toMatch(new RegExp(`Overlay\\s+${file.replace(/[./]/g, "\\$&")} still draws the devtools overlay on dev pages`));
+ expect(r.out).toContain("delete the statement that imports @genclass/runtime/devtools");
+ expect(snapshot(dir)).toEqual(withOverlay);
+ expect(cli(dir, "init", "--yes", "--no-install", "--devtools").out).not.toContain("still draws");
+ // the advice: delete that one statement. What is left is init's own, so remove still gives the files back
+ const f = join(dir, file);
+ writeFileSync(f, readFileSync(f, "utf8").split("\n").filter((l) => !l.includes("@genclass/runtime/devtools")).join("\n"));
+ expect(cli(dir, "init", "--yes", "--no-install").out).not.toContain("still draws");
+ const rm = cli(dir, "remove", "--yes");
+ expect(rm.code, rm.out).toBe(0);
+ expect(snapshot(dir)).toEqual(before);
+ }
+ const site = project({ "index.html": PAGE });
+ expect(cli(site, "init", "--yes", "--no-sri", "--devtools").code).toBe(0);
+ const h = cli(site, "init", "--yes");
+ expect(h.out).toContain("index.html still draws the devtools overlay on dev pages");
+ expect(h.out).toContain(`delete data-devtools="local" from its script tag`);
+ writeFileSync(join(site, "index.html"), readFileSync(join(site, "index.html"), "utf8").replace(` data-devtools="local"`, ""));
+ expect(cli(site, "init", "--yes").out).not.toContain("still draws");
+ expect(cli(site, "remove", "--yes").code).toBe(0);
+ expect(readFileSync(join(site, "index.html"), "utf8")).toBe(PAGE);
+ });
+
+ it("help names --devtools, and the hand-install help shows a tag without data-devtools", () => {
+ const help = cli(project({}), "init", "--help").out;
+ expect(help).toContain("--devtools");
+ expect(help).toContain("It draws nothing on your pages unless you pass --devtools.");
+ const manual = cli(project({ "package.json": pkg({}) }), "init", "--yes", "--no-install");
+ expect(manual.out).toContain("one tag first in ");
+ expect(manual.out).not.toContain("data-devtools");
+ });
+});
+
describe("remove after a formatter rewrapped init's lines", () => {
it("takes out a Prettier-wrapped devtools statement whole (byte for byte)", () => {
const dir = viteVue();
const before = snapshot(dir);
- expect(cli(dir, "init", "--yes", "--no-install").code).toBe(0);
+ expect(cli(dir, "init", "--yes", "--no-install", "--devtools").code).toBe(0);
const f = join(dir, "src/main.js");
const added = readFileSync(f, "utf8");
const wrapped = added.replace(
@@ -543,7 +629,8 @@ describe("remove never deletes code init did not write", () => {
const dir = project({ "package.json": pkg({ "@sveltejs/kit": "^2" }), "src/routes/+page.svelte": "x\n" });
expect(cli(dir, "init", "--yes", "--no-install").code).toBe(0);
const f = join(dir, "src/hooks.client.js");
- const edited = readFileSync(f, "utf8").replace(`import genclass from "@genclass/runtime/auto";\n`, `import genclass from "@genclass/runtime/auto";\nexport const handleError = () => {};\n`);
+ const edited = readFileSync(f, "utf8").replace(`import "@genclass/runtime/auto";\n`, `import "@genclass/runtime/auto";\nexport const handleError = () => {};\n`);
+ expect(edited).not.toBe(readFileSync(f, "utf8"));
writeFileSync(f, edited);
const snap = snapshot(dir);
const r = cli(dir, "remove", "--yes");
@@ -742,14 +829,14 @@ describe("init options: --no-telemetry / --telemetry / --model-url (Troy trial,
const after = roundTrip(viteVue(), "--no-telemetry");
const lines = after["src/main.js"].split("\n");
expect(lines[0]).toBe(`import "./genclass.config"; // genclass:init`);
- expect(lines[1]).toBe(`import genclass from "@genclass/runtime/auto"; // genclass:init`);
+ expect(lines[1]).toBe(`import "@genclass/runtime/auto"; // genclass:init`);
expect(after["src/genclass.config.js"]).toContain(`globalThis.GENCLASS_CONFIG = { telemetry: false };`);
expect(after["src/genclass.config.js"]).toContain("genclass:init start");
});
it("Next.js 16: the options import goes into instrumentation-client.ts, the file is TypeScript", () => {
const after = roundTrip(next16(), "--no-telemetry", "--model-url", "/genclass-model");
- expect(after["instrumentation-client.ts"]).toMatch(/import "\.\/genclass\.config";\nimport genclass from "@genclass\/runtime\/auto";/);
+ expect(after["instrumentation-client.ts"]).toMatch(/import "\.\/genclass\.config";\nimport "@genclass\/runtime\/auto";/);
expect(after["genclass.config.ts"]).toContain(
`(globalThis as { GENCLASS_CONFIG?: object }).GENCLASS_CONFIG = { telemetry: false, model: { baseUrl: "/genclass-model/", ortWasmPaths: "/genclass-model/ort/" } };`,
);
@@ -772,7 +859,7 @@ describe("init options: --no-telemetry / --telemetry / --model-url (Troy trial,
const r = cli(dir, "init", "--yes", "--no-install", "--no-telemetry");
expect(r.code, r.out).toBe(0);
expect(r.out).toContain("telemetry off");
- expect(readFileSync(join(dir, "src/main.js"), "utf8").split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import genclass from "@genclass/runtime/auto"; // genclass:init`]);
+ expect(readFileSync(join(dir, "src/main.js"), "utf8").split("\n").slice(0, 2)).toEqual([`import "./genclass.config"; // genclass:init`, `import "@genclass/runtime/auto"; // genclass:init`]);
// --telemetry takes the opt-out out (back to the default) and never writes `telemetry: true`, which would be an
// explicit opt-in that also sends from local hosts
expect(cli(dir, "init", "--yes", "--no-install", "--telemetry").code).toBe(0);
@@ -798,7 +885,7 @@ describe("init options: --no-telemetry / --telemetry / --model-url (Troy trial,
it("plain HTML: data-telemetry=\"off\" on the script tag; --telemetry takes it off again", () => {
const after = roundTrip(project({ "index.html": PAGE }), "--no-telemetry", "--no-sri");
- expect(after["index.html"]).toContain(` data-devtools="local" data-telemetry="off"> `);
+ expect(after["index.html"]).toContain(` defer data-telemetry="off"> `);
const dir = project({ "index.html": PAGE });
cli(dir, "init", "--yes", "--no-install", "--no-telemetry", "--no-sri");
cli(dir, "init", "--yes", "--no-install", "--telemetry");
@@ -811,7 +898,7 @@ describe("init options: --no-telemetry / --telemetry / --model-url (Troy trial,
"src/layouts/Layout.astro": `---\n---\n\n\t\n\t\tx\n\t\n\t\n\n`,
});
const after = roundTrip(dir, "--no-telemetry");
- expect(after["src/layouts/Layout.astro"]).toMatch(/\t\t \n\t\t `);
+ expect(snapshot(html)["index.html"]).toContain(` `);
expect(cli(html, "remove", "--yes").code).toBe(0);
expect(snapshot(html)["index.html"]).toBe(`\n\n x\n\n\n\n`);
});
diff --git a/packages/runtime/test/install/frameworks.mjs b/packages/runtime/test/install/frameworks.mjs
index ce670d24..4d0f69f0 100644
--- a/packages/runtime/test/install/frameworks.mjs
+++ b/packages/runtime/test/install/frameworks.mjs
@@ -70,10 +70,10 @@ const FRAMEWORKS = {
nuxt: { build: "npm run build", prod: "node .output/server/index.mjs", dev: "npx nuxi dev --port {port} --host 127.0.0.1", env: { PORT: "{port}", HOST: "127.0.0.1", NITRO_PORT: "{port}", NITRO_HOST: "127.0.0.1" } },
"react-router": { build: "npm run build", prod: "npx react-router-serve ./build/server/index.js", dev: "npx react-router dev --port {port} --host 127.0.0.1", env: { PORT: "{port}", HOST: "127.0.0.1" } },
angular: { build: "npx ng build", prod: { static: "dist/*/browser" }, dev: "npx ng serve --port {port} --host 127.0.0.1" },
- "plain-html": { build: null, prod: { static: "." }, dev: null, prodDevtools: true, init: ["--cdn", `${cdn.url}/pkg/dist/genclass.global.min.js`] },
+ "plain-html": { build: null, prod: { static: "." }, dev: null, init: ["--cdn", `${cdn.url}/pkg/dist/genclass.global.min.js`] },
// app tokens: the token goes into genclass.config.ts (bundlers) or data-token (script tag); remove takes it out
"vite-react-ts-token": { scaffold: "vite-react-ts", token: true, build: "npm run build", prod: vitePreview, dev: viteDev },
- "plain-html-token": { scaffold: "plain-html", token: true, build: null, prod: { static: "." }, dev: null, prodDevtools: true, init: ["--cdn", `${cdn.url}/pkg/dist/genclass.global.min.js`] },
+ "plain-html-token": { scaffold: "plain-html", token: true, build: null, prod: { static: "." }, dev: null, init: ["--cdn", `${cdn.url}/pkg/dist/genclass.global.min.js`] },
};
// -------------------------------------------------------------------------------------------- helpers
@@ -176,7 +176,7 @@ async function startServer(spec, cwd, env = {}) {
}
let browser;
-async function visit(url, { expectDevtools }) {
+async function visit(url) {
const ctx = await browser.newContext();
await ctx.route(/^https:\/\/cdn\.jsdelivr\.net\/npm\//, (r) => {
const u = new URL(r.request().url());
@@ -203,8 +203,8 @@ async function visit(url, { expectDevtools }) {
await page.goto(url, { waitUntil: "load", timeout: 120_000 });
const t0 = Date.now();
while (Date.now() - t0 < 120_000 && !lines.some((l) => l.includes("[GenClass] Model ready") || l.includes("[GenClass] Model unavailable"))) await page.waitForTimeout(500);
- if (expectDevtools) await page.waitForSelector("genclass-devtools", { timeout: 30_000, state: "attached" }).catch(() => undefined);
- else await page.waitForTimeout(1500);
+ // nothing init sets up is drawn on a page: wait long enough that a late overlay mount would be seen
+ await page.waitForTimeout(5000);
Object.assign(
r,
await page.evaluate(() => ({
@@ -274,7 +274,7 @@ async function runOne(name) {
try {
const s = await startServer(fw.prod, dir, fw.env);
try {
- res.steps.prod = await visit(`${s.url}/`, { expectDevtools: false });
+ res.steps.prod = await visit(`${s.url}/`);
} finally {
await s.stop();
}
@@ -288,8 +288,8 @@ async function runOne(name) {
try {
// A dev server's first load may re-optimize newly added dependencies and reload (Vite); judge a warm load
// and keep the cold one's errors in the results.
- const cold = await visit(`${s.url}/`, { expectDevtools: true });
- res.steps.dev = await visit(`${s.url}/`, { expectDevtools: true });
+ const cold = await visit(`${s.url}/`);
+ res.steps.dev = await visit(`${s.url}/`);
res.steps.dev.coldErrors = cold.errors;
res.steps.dev.coldWorkers = cold.workers.length;
} finally {
@@ -316,9 +316,9 @@ async function runOne(name) {
function verdict(r) {
if (r.skipped) return "SKIP";
const s = r.steps;
- // production builds never mount the overlay; the plain-HTML tag uses data-devtools="local", which does on 127.0.0.1
- const prodOk = s.prod && !s.prod.error && s.prod.modelReady && s.prod.fetchWrapped && s.prod.devtools === !!FRAMEWORKS[r.name].prodDevtools && s.prod.errors.length === 0;
- const devOk = !s.dev || (!s.dev.error && s.dev.devtools && s.dev.fetchWrapped && s.dev.errors.length === 0);
+ // init adds no overlay (only with --devtools, which this suite does not pass): none in production or development
+ const prodOk = s.prod && !s.prod.error && s.prod.modelReady && s.prod.fetchWrapped && !s.prod.devtools && s.prod.errors.length === 0;
+ const devOk = !s.dev || (!s.dev.error && !s.dev.devtools && s.dev.fetchWrapped && s.dev.errors.length === 0);
const tokenOk = s.init?.noProject && (!FRAMEWORKS[r.name].token || s.init?.tokenWritten);
const ok = s.init?.ok && tokenOk && s.idempotent?.ok && (s.build === undefined || s.build.ok) && prodOk && devOk && s.remove?.ok && s.remove?.restored;
return ok ? "PASS" : "FAIL";
diff --git a/packages/sv/CHANGELOG.md b/packages/sv/CHANGELOG.md
index b2103514..1c9dc76d 100644
--- a/packages/sv/CHANGELOG.md
+++ b/packages/sv/CHANGELOG.md
@@ -6,10 +6,10 @@
SvelteKit only (`unsupported("Requires SvelteKit")` elsewhere).
- Adds `@genclass/runtime` `^0.3.0-beta.1` to `dependencies` (a project that lists it under `devDependencies`
keeps it there; a stricter existing range stays).
-- `src/hooks.client.(ts|js)`: `import genclass from "@genclass/runtime/auto"` (`/auto/guard` with `mode: guard`)
- as the first statement and the devtools overlay behind `import.meta.env.DEV` at the end. A missing file is created
- as one marked block; an existing file keeps its code. An existing `/auto` import is re-pointed at the chosen mode
- and given a binding instead of being duplicated.
+- `src/hooks.client.(ts|js)`: `import "@genclass/runtime/auto"` (`/auto/guard` with `mode: guard`) as the first
+ statement, and nothing else: the add-on never adds the devtools overlay (owner, 2026-11-16: nothing GenClass sets
+ up is drawn on a page). A missing file is created as one marked block; an existing file keeps its code. An existing
+ `/auto` import is re-pointed at the chosen mode instead of being duplicated.
- `src/app.html`: `` unless `telemetry: yes` (default `no`). An
existing genclass meta tag gets `telemetry=off` added instead.
- Everything added carries the `genclass:init` marker, so `npx @genclass/runtime remove` takes it out byte for byte.
diff --git a/packages/sv/README.md b/packages/sv/README.md
index 0a9ba23c..b7ff4a92 100644
--- a/packages/sv/README.md
+++ b/packages/sv/README.md
@@ -29,12 +29,12 @@ Svelte + Vite project it stops with "Requires SvelteKit".
| file | change |
|---|---|
| `package.json` | adds `@genclass/runtime` `^0.3.0-beta.1` to `dependencies` (the release the GenClass README documents; the range takes later 0.3.0 betas and 0.3.x) |
-| `src/hooks.client.ts` (or `.js`) | `import genclass from "@genclass/runtime/auto";` as the first line, and at the end `if (import.meta.env.DEV) import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));`. Creates the file if the app has none; an existing file keeps all its code |
+| `src/hooks.client.ts` (or `.js`) | `import "@genclass/runtime/auto";` as the first line. Creates the file if the app has none; an existing file keeps all its code |
| `src/app.html` | with telemetry off (the default): `` in `` |
SvelteKit runs `src/hooks.client` in the browser before the app starts, so GenClass is installed before your
-components and stores. Server rendering, hydration and your server code are not touched. The overlay import sits
-behind `import.meta.env.DEV`, so it is never in a production build.
+components and stores. Server rendering, hydration and your server code are not touched. Nothing is drawn on your
+pages: the add-on never adds GenClass's devtools overlay.
Every line it adds carries the `genclass:init` marker that `npx @genclass/runtime@beta init` writes, so GenClass's own
CLI recognises the setup and can take it out again. Running the add-on twice adds nothing twice; running it again
@@ -51,7 +51,7 @@ with other answers switches the mode or the telemetry line in place.
npx sv add @genclass="mode:guard+telemetry:no"
```
-Start in observe, watch the console and the overlay on real traffic, then switch to guard. The runtime also has an
+Start in observe, watch the console on real traffic, then switch to guard. The runtime also has an
experimental `heal` mode, which this add-on does not offer: change the import to `@genclass/runtime/auto/heal`
yourself.
@@ -63,7 +63,7 @@ yourself.
not load it and observe without it. For a strict Content-Security-Policy or to serve the model yourself, see
[self-hosting](https://github.com/genclass-dev/GenClass/blob/main/packages/runtime/README.md#content-security-policy-and-self-hosting).
- **The console.** One line when the model is ready (`[GenClass] Model ready (...). Mode: observe.`), then one
- plain-English line per finding. The overlay (development only) sits bottom right; `Alt+Shift+G` toggles it.
+ plain-English line per finding. Nothing is drawn on the page.
- **What it sees in Svelte.** Automatic state discovery covers React, Redux and Zustand, not Svelte runes or stores
yet, so in SvelteKit GenClass works from the network and user input. To compare a late response with newer data in
your state, register that state (`genclass.atom(...)`, see
diff --git a/packages/sv/package.json b/packages/sv/package.json
index 772a2c74..2f4d950e 100644
--- a/packages/sv/package.json
+++ b/packages/sv/package.json
@@ -1,7 +1,7 @@
{
"name": "@genclass/sv",
"version": "0.1.0",
- "description": "A community add-on for the Svelte CLI: npx sv add @genclass sets up GenClass in a SvelteKit app (the @genclass/runtime dependency, its import first in src/hooks.client, the devtools overlay in development). GenClass reports race conditions in the browser: stale responses, duplicate requests, failure storms.",
+ "description": "A community add-on for the Svelte CLI: npx sv add @genclass sets up GenClass in a SvelteKit app (the @genclass/runtime dependency and its import first in src/hooks.client; nothing drawn on the page). GenClass reports race conditions in the browser: stale responses, duplicate requests, failure storms.",
"type": "module",
"license": "Apache-2.0",
"repository": {
diff --git a/packages/sv/src/edit.ts b/packages/sv/src/edit.ts
index bf4224e8..f9f9d903 100644
--- a/packages/sv/src/edit.ts
+++ b/packages/sv/src/edit.ts
@@ -2,11 +2,13 @@
// and writes through sv's API). They write what `npx @genclass/runtime init` writes for SvelteKit, with the same
// `genclass:init` marker, so `npx @genclass/runtime remove` takes it out again and `init` recognises the setup:
// - a new src/hooks.client.(ts|js) is one marked block (remove deletes the file);
-// - an existing one gets the /auto import first and the dev-only overlay line last, each marked on its line;
+// - an existing one gets the /auto import first, marked on its line;
+// - nothing that draws on the page: the devtools overlay is never added (owner, 2026-11-16; a developer can add it
+// by hand, see the README);
// - the telemetry opt-out is one marked `` line in src/app.html.
// Every edit is idempotent: a second run with the same options returns `false` (nothing to write).
-import { Walker, minimizeDiff, transforms, type AstTypes } from "@sveltejs/sv-utils";
+import { minimizeDiff, transforms, type AstTypes } from "@sveltejs/sv-utils";
/** The modes the add-on offers: observe (the runtime's default) and guard. heal stays a hand edit (experimental). */
export type Mode = "observe" | "guard";
@@ -20,8 +22,6 @@ export const RUNTIME_RANGE = "^0.3.0-beta.1";
/** @genclass/runtime's CLI marker (packages/runtime/bin/lib/edit.mjs): `remove` deletes exactly the marked code. */
export const MARK = "genclass:init";
-const DEVTOOLS = "@genclass/runtime/devtools";
-const DEV_COND = "import.meta.env.DEV";
const AUTO_RE = /^@genclass\/runtime\/auto(?:\/(observe|guard|heal))?$/;
const META_RE = /]*\bname\s*=\s*["']genclass["'][^>]*>/i;
const CONTENT_RE = /\bcontent\s*=\s*(["'])(.*?)\1/i;
@@ -36,87 +36,52 @@ export function modeOf(specifier: string): string | null {
return m ? (m[1] ?? "observe") : null;
}
-const devLine = (q: string, local: string) => `if (${DEV_COND}) import(${q}${DEVTOOLS}${q}).then((d) => d.mountDevtools(${local}));`;
-
/** The client hooks file when the app has none: one marked block, as `init` creates it. */
export function newHooksFile(mode: Mode): string {
return [
`// ${MARK} start: GenClass Runtime, added by \`npx sv add @genclass\` (\`npx @genclass/runtime remove\` takes it out)`,
- `import genclass from "${autoSpecifier(mode)}";`,
- devLine('"', "genclass"),
+ `import "${autoSpecifier(mode)}";`,
`// ${MARK} end`,
"",
].join("\n");
}
/**
- * An existing client hooks file with GenClass added: the /auto import as the first statement (or, if the file
- * already imports /auto, that import re-pointed at `mode` and given a default binding), then the dev-only overlay
- * line at the end unless the file already imports the devtools. `false` when there is nothing to change.
+ * An existing client hooks file with GenClass added: the /auto import as the first statement, or, if the file
+ * already imports /auto, that import re-pointed at `mode` (its bindings kept). Nothing else: the devtools overlay is
+ * never added, and a devtools line the developer wrote stays as it is. `false` when there is nothing to change.
*/
export function editHooks(content: string, mode: Mode): string | false {
let addedTop = false;
- let addedEnd = false;
const out = transforms.script(({ ast, comments, js }) => {
let changed = false;
- const mark = (node: AstTypes.Node) => comments.add(node, { type: "Line", value: ` ${MARK}` }, { position: "trailing" });
- let local = "genclass";
const auto = js.imports.findAll(ast, { from: AUTO_RE }).find((f) => f.kind === "static");
if (!auto) {
- // addDefault inserts at the top of the module, so GenClass is installed before the app's other imports run
- js.imports.addDefault(ast, { from: autoSpecifier(mode), as: local });
- mark(ast.body[0]);
+ // addEmpty inserts at the top of the module, so GenClass is installed before the app's other imports run
+ js.imports.addEmpty(ast, { from: autoSpecifier(mode) });
+ comments.add(ast.body[0] as AstTypes.Node, { type: "Line", value: ` ${MARK}` }, { position: "trailing" });
changed = addedTop = true;
- } else {
- if (modeOf(auto.source) !== mode) {
- js.imports.setSource(auto, autoSpecifier(mode));
- changed = true;
- }
- const decl = auto.node as AstTypes.ImportDeclaration;
- const named = decl.specifiers.find((s) => s.type === "ImportDefaultSpecifier" || s.type === "ImportNamespaceSpecifier");
- if (named?.type === "ImportDefaultSpecifier") local = named.local.name;
- else if (named?.type === "ImportNamespaceSpecifier") local = `${named.local.name}.default`;
- else {
- // `import "@genclass/runtime/auto"` (or named imports only): the overlay needs the runtime, so bind it
- decl.specifiers.unshift({ type: "ImportDefaultSpecifier", local: { type: "Identifier", name: local } });
- changed = true;
- }
- }
- if (js.imports.findAll(ast, { from: DEVTOOLS }).length === 0) {
- const statement = js.common.parseStatement(devLine('"', local));
- // without their source text, the printer quotes the new strings the way the rest of the file does
- Walker.walk(statement as AstTypes.Node, null, {
- Literal(node) {
- delete node.raw;
- },
- });
- js.common.appendStatement(ast, { statement });
- mark(statement);
- changed = addedEnd = true;
+ } else if (modeOf(auto.source) !== mode) {
+ js.imports.setSource(auto, autoSpecifier(mode));
+ changed = true;
}
if (!changed) return false;
})(content);
if (out === false) return false;
// the printer reformats the whole module; keep the developer's lines as they were (sv's engine does the same)
- return tighten(minimizeDiff(content, out), content, addedTop, addedEnd);
+ return tighten(minimizeDiff(content, out), content, addedTop);
}
/**
- * The printer sets the lines it added apart from the developer's code with a blank line and drops the final line
- * break. `init` adds no blank line, and `remove` takes out only the marked lines, so those blank lines go and the
+ * The printer sets the line it added apart from the developer's code with a blank line and drops the final line
+ * break. `init` adds no blank line, and `remove` takes out only the marked line, so that blank line goes and the
* file's final line break stays: remove then gives the file back byte for byte.
*/
-function tighten(out: string, original: string, top: boolean, end: boolean): string {
+function tighten(out: string, original: string, top: boolean): string {
const eol = out.includes("\r\n") ? "\r\n" : "\n";
const lines = out.split(eol);
const orig = original.split(/\r?\n/);
if (top && lines[0].includes(MARK) && lines[1] === "" && orig[0] !== "") lines.splice(1, 1);
- if (end) {
- let i = lines.length - 1;
- while (i > 0 && lines[i] === "") i--;
- const lastOrig = orig.length - (orig[orig.length - 1] === "" ? 2 : 1);
- if (lines[i].includes(MARK) && lines[i - 1] === "" && orig[lastOrig] !== "") lines.splice(i - 1, 1);
- }
const text = lines.join(eol);
// the printer ends the module without a line break; keep the file's own
return original.endsWith("\n") && !text.endsWith("\n") ? text + eol : text;
diff --git a/packages/sv/src/index.ts b/packages/sv/src/index.ts
index 1db3f036..782413a8 100644
--- a/packages/sv/src/index.ts
+++ b/packages/sv/src/index.ts
@@ -1,9 +1,9 @@
// @genclass/sv: a community add-on for the Svelte CLI. `npx sv add @genclass` (or `npx sv create --add @genclass`)
// sets GenClass up in a SvelteKit app the way the GenClass docs and `npx @genclass/runtime init` do:
// - `@genclass/runtime` as a dependency, at the release the GenClass README documents;
-// - `import genclass from "@genclass/runtime/auto"` first in src/hooks.client.(ts|js) (SvelteKit runs client hooks
-// in the browser before the app starts; created when missing, existing code kept), `/auto/guard` for mode guard;
-// - the devtools overlay behind `import.meta.env.DEV`, so it is never in a production bundle;
+// - `import "@genclass/runtime/auto"` first in src/hooks.client.(ts|js) (SvelteKit runs client hooks in the
+// browser before the app starts; created when missing, existing code kept), `/auto/guard` for mode guard;
+// - nothing drawn on the page: findings go to the browser console (and the dashboard), never an overlay;
// - unless the developer opts in, the telemetry opt-out in src/app.html (``).
// Running it again changes nothing, or only what a different answer changes. All edits are in edit.ts; everything
// is marked so `npx @genclass/runtime remove` undoes it. The add-on never runs code in the app and sends nothing.
@@ -81,7 +81,7 @@ export default defineAddon({
nextSteps: ({ options, packageManager, directory }) => {
const dev = packageManager === "deno" ? "deno task dev" : `${packageManager ?? "npm"} run dev`;
return [
- `Run ${color.command(dev)}: GenClass reports in the browser console, and in development its overlay sits bottom right (${color.command("Alt+Shift+G")}).`,
+ `Run ${color.command(dev)}: GenClass reports in the browser console, one [GenClass] line per finding. It draws nothing on your pages.`,
options.mode === "guard"
? `Mode guard: GenClass may act (reuse a duplicate's result, back off) when its model is confident; every action is logged with its evidence.`
: `Mode observe: GenClass reports only and never holds, drops or changes a request.`,
diff --git a/packages/sv/test/e2e/addon.test.ts b/packages/sv/test/e2e/addon.test.ts
index cd885c41..60bdde7f 100644
--- a/packages/sv/test/e2e/addon.test.ts
+++ b/packages/sv/test/e2e/addon.test.ts
@@ -6,7 +6,7 @@
// - runs the app's type check (`pnpm check`: svelte-check, in TypeScript or JSDoc);
// - builds the app, serves the production build and loads it once in Chromium: the runtime must be installed in
// the page (GenClass marks the fetch it wraps) and its model must load in a worker (downloaded from jsDelivr, as
-// in a real app), the telemetry choice must be in , the overlay must not be in the production build, and
+// in a real app), the telemetry choice must be in , no devtools overlay may be on the page, and
// the console must show no errors and no uncaught exceptions;
// - runs `genclass-runtime remove` from the installed runtime and checks that it takes out what the add-on wrote.
// Two kinds: `observe` (defaults: observe, telemetry off, no hooks file before) and `guard` (guard, telemetry on,
@@ -88,11 +88,10 @@ test.concurrent.for(testCases)("@genclass/sv $kind.type $variant", async (testCa
const hooks = read(cwd, hooksFile);
if (guard) {
const lines = hooks.split("\n");
- expect(lines[0]).toBe("import genclass from '@genclass/runtime/auto/guard'; // genclass:init");
+ expect(lines[0]).toBe("import '@genclass/runtime/auto/guard'; // genclass:init");
expect(hooks).toContain(EXISTING_HOOKS[e].trimEnd());
- expect(hooks.trimEnd().split("\n").at(-1)).toBe(
- "if (import.meta.env.DEV) import('@genclass/runtime/devtools').then((d) => d.mountDevtools(genclass)); // genclass:init",
- );
+ // nothing drawn on the page: the add-on never adds the devtools overlay
+ expect(hooks).not.toMatch(/devtools/);
} else {
expect(hooks).toBe(newHooksFile("observe"));
}
@@ -128,7 +127,7 @@ test.concurrent.for(testCases)("@genclass/sv $kind.type $variant", async (testCa
expect((await modelReady).text()).toContain(`Mode: ${testCase.kind.options[addon.id].mode}.`);
const meta = await page.evaluate(() => document.head.querySelector('meta[name="genclass"]')?.getAttribute("content") ?? null);
expect(meta).toBe(guard ? null : "telemetry=off");
- // the overlay is development only
+ // nothing GenClass set up is drawn on the page
expect(await page.evaluate(() => document.querySelectorAll("[data-genclass-devtools]").length)).toBe(0);
expect(problems).toEqual([]);
diff --git a/packages/sv/test/edit.test.ts b/packages/sv/test/edit.test.ts
index 5cb8acfd..baae5900 100644
--- a/packages/sv/test/edit.test.ts
+++ b/packages/sv/test/edit.test.ts
@@ -33,17 +33,17 @@ const apply = (content: string, edit: (c: string) => string | false) => {
};
describe("new client hooks file", () => {
- it("is one marked block with the /auto import and the dev-only overlay", () => {
+ it("is one marked block with the /auto import and nothing that draws on the page (no devtools overlay)", () => {
expect(newHooksFile("observe")).toBe(
[
"// genclass:init start: GenClass Runtime, added by `npx sv add @genclass` (`npx @genclass/runtime remove` takes it out)",
- 'import genclass from "@genclass/runtime/auto";',
- 'if (import.meta.env.DEV) import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));',
+ 'import "@genclass/runtime/auto";',
"// genclass:init end",
"",
].join("\n"),
);
- expect(newHooksFile("guard")).toContain('import genclass from "@genclass/runtime/auto/guard";');
+ expect(newHooksFile("guard")).toContain('import "@genclass/runtime/auto/guard";');
+ expect(newHooksFile("guard")).not.toMatch(/devtools/);
});
it("is deleted whole by `npx @genclass/runtime remove`", () => {
@@ -60,28 +60,24 @@ describe("new client hooks file", () => {
it("switches mode in place, keeping the block valid for remove", () => {
const guard = editHooks(newHooksFile("observe"), "guard");
expect(guard).not.toBe(false);
- expect(guard).toContain('"@genclass/runtime/auto/guard"');
- expect(guard).not.toContain('"@genclass/runtime/auto";');
+ // (with no other string in the block, the printer picks its own quotes; remove compares without them)
+ expect(guard).toMatch(/import ["']@genclass\/runtime\/auto\/guard["'];/);
+ expect(guard).not.toMatch(/@genclass\/runtime\/auto["']/);
expect(guard).toContain("// genclass:init start");
expect(guard).toContain("// genclass:init end");
expect(planRemoval(guard as string)).toEqual({ text: "", problems: [] });
// and back
const observe = editHooks(guard as string, "observe");
- expect(observe).toContain('"@genclass/runtime/auto"');
+ expect(observe).toMatch(/import ["']@genclass\/runtime\/auto["'];/);
expect(planRemoval(observe as string)).toEqual({ text: "", problems: [] });
});
});
describe("existing client hooks file", () => {
- it("gets the /auto import first and the overlay line last, each marked, and keeps the code", () => {
+ it("gets the /auto import first, marked, keeps the code and adds nothing else (no overlay line)", () => {
const out = editHooks(SENTRY_HOOKS, "observe") as string;
- const lines = out.split("\n");
- expect(lines[0]).toBe("import genclass from '@genclass/runtime/auto'; // genclass:init");
- expect(out).toContain(SENTRY_HOOKS.trimEnd().split("\n").slice(0, 2).join("\n"));
- expect(out).toContain("export const handleError = handleErrorWithSentry();");
- expect(out.trimEnd().split("\n").at(-1)).toBe(
- "if (import.meta.env.DEV) import('@genclass/runtime/devtools').then((d) => d.mountDevtools(genclass)); // genclass:init",
- );
+ expect(out).toBe(`import '@genclass/runtime/auto'; // genclass:init\n${SENTRY_HOOKS}`);
+ expect(out).not.toMatch(/devtools/);
});
it("is idempotent: a second run with the same mode writes nothing and never duplicates an import", () => {
@@ -89,7 +85,7 @@ describe("existing client hooks file", () => {
expect(editHooks(once, "observe")).toBe(false);
const guard = editHooks(once, "guard") as string;
expect(guard.match(/@genclass\/runtime\/auto/g)).toHaveLength(1);
- expect(guard.match(/@genclass\/runtime\/devtools/g)).toHaveLength(1);
+ expect(guard).not.toMatch(/devtools/);
expect(guard).toContain("'@genclass/runtime/auto/guard'");
expect(editHooks(guard, "guard")).toBe(false);
});
@@ -106,43 +102,34 @@ describe("existing client hooks file", () => {
}
});
- it("binds the runtime on the README's one-line import instead of adding a second import", () => {
+ it("leaves the README's one-line import as it is (no second import, no binding added)", () => {
const src = 'import "@genclass/runtime/auto";\nimport { dev } from "$app/environment";\n';
- const out = editHooks(src, "observe") as string;
- expect(out.match(/@genclass\/runtime\/auto/g)).toHaveLength(1);
- expect(out.split("\n")[0]).toBe('import genclass from "@genclass/runtime/auto";');
- expect(out).toContain('import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass))');
- expect(editHooks(out, "observe")).toBe(false);
+ expect(editHooks(src, "observe")).toBe(false);
+ const guard = editHooks(src, "guard") as string;
+ expect(guard).toBe('import "@genclass/runtime/auto/guard";\nimport { dev } from "$app/environment";\n');
});
- it("quotes both added lines the way the file quotes its strings", () => {
+ it("quotes the added import the way the file quotes its strings", () => {
const single = "/** @type {import('@sveltejs/kit/hooks').HandleClientError} */\nexport const handleError = () => ({ message: 'Oops' });\n";
- const out = editHooks(single, "observe") as string;
- expect(out).toContain("import genclass from '@genclass/runtime/auto'; // genclass:init");
- expect(out).toContain("import('@genclass/runtime/devtools')");
+ expect(editHooks(single, "observe") as string).toContain("import '@genclass/runtime/auto'; // genclass:init");
const double = editHooks('export const handleError = () => ({ message: "Oops" });\n', "observe") as string;
- expect(double).toContain('import genclass from "@genclass/runtime/auto"; // genclass:init');
- expect(double).toContain('import("@genclass/runtime/devtools")');
+ expect(double).toContain('import "@genclass/runtime/auto"; // genclass:init');
});
- it("uses the name an existing default import already has", () => {
+ it("keeps the name an existing default import already has", () => {
const src = "import rt from '@genclass/runtime/auto/observe';\n\nexport const init = () => {};\n";
- const out = editHooks(src, "observe") as string;
- expect(out).toContain("import rt from '@genclass/runtime/auto/observe';");
- expect(out).toContain("d.mountDevtools(rt)");
+ expect(editHooks(src, "observe")).toBe(false);
+ expect(editHooks(src, "guard")).toBe("import rt from '@genclass/runtime/auto/guard';\n\nexport const init = () => {};\n");
});
- it("leaves the GenClass SvelteKit template's hooks file alone (it already has the import and the overlay)", () => {
- const template = `// GenClass, in the browser only.
-import genclass from '@genclass/runtime/auto';
-
-// The devtools overlay, in development only (not in your production bundle).
-if (import.meta.env.DEV) import('@genclass/runtime/devtools').then((d) => d.mountDevtools(genclass));
-`;
+ it("leaves the GenClass SvelteKit template's hooks file alone, and a devtools line the developer wrote stays as it is", () => {
+ const template = readFileSync(new URL("../../../templates/sveltekit/src/hooks.client.ts", import.meta.url), "utf8");
+ expect(template).not.toMatch(/devtools/);
expect(editHooks(template, "observe")).toBe(false);
- const guard = editHooks(template, "guard") as string;
- expect(guard).toContain("import genclass from '@genclass/runtime/auto/guard';");
- expect(guard.match(/devtools/g)).toHaveLength(2); // the comment and the one import
+ expect(editHooks(template, "guard") as string).toContain("import '@genclass/runtime/auto/guard';");
+ const own = `import genclass from '@genclass/runtime/auto';\n\nif (import.meta.env.DEV) import('@genclass/runtime/devtools').then((d) => d.mountDevtools(genclass));\n`;
+ expect(editHooks(own, "observe")).toBe(false);
+ expect(editHooks(own, "guard")).toBe(own.replace("/auto'", "/auto/guard'"));
});
it("is recognised by init's mode switch", () => {
diff --git a/templates/README.md b/templates/README.md
index 11e73f18..6f5c7e97 100644
--- a/templates/README.md
+++ b/templates/README.md
@@ -1,9 +1,8 @@
# Starter templates
-Copy-paste starters with [`@genclass/runtime`](https://www.npmjs.com/package/@genclass/runtime) already installed
-the recommended way (the one line, the dev-only devtools overlay). Each is a fresh app from the framework's own
-generator, trimmed to one page with a search box and a mock API that answers out of order, so you can see GenClass
-work within a minute.
+Copy-paste starters with [`@genclass/runtime`](https://www.npmjs.com/package/@genclass/runtime) already installed the
+recommended way: the one line. Each is a fresh app from the framework's own generator, trimmed to one page with a
+search box and a mock API that answers out of order, so you can see GenClass work within a minute.
| template | the one line goes in | run |
|---|---|---|
@@ -25,10 +24,10 @@ cd my-app && npm install && npm run dev
Every template:
-- **starts in observe mode**: GenClass reports what it finds (devtools overlay, one console line per finding) and
- changes nothing. Switch the import to `@genclass/runtime/auto/guard` (in astro and nuxt: `mode: "guard"` in the
+- **starts in observe mode**: GenClass reports what it finds (one browser console line per finding) and changes
+ nothing. Switch the import to `@genclass/runtime/auto/guard` (in astro and nuxt: `mode: "guard"` in the
integration's or module's options) to let it act when its model is confident;
-- **loads the devtools overlay in development only**;
+- **draws nothing on the page**: the devtools overlay is opt-in (each README shows how to turn it on);
- **can be turned off per page load** with `?genclass=off` in the URL;
- sends anonymous, redacted diagnostics by default; each README shows the one-line opt-out.
diff --git a/templates/angular/README.md b/templates/angular/README.md
index 93ed5ac5..3e2c3858 100644
--- a/templates/angular/README.md
+++ b/templates/angular/README.md
@@ -6,21 +6,20 @@ first in `src/main.ts`.
```bash
npm install
-npm run dev # http://localhost:4200, with the GenClass devtools overlay
-npm run build && npm run serve:ssr # production build (no overlay), http://localhost:4000
+npm run dev # http://localhost:4200
+npm run build && npm run serve:ssr # production build, http://localhost:4000
```
Type a city quickly in the search box. The API (`/api/search` in `src/server.ts`, the Express server Angular
generates) answers in a random 50-900 ms, so an older answer can overwrite a newer one: the classic stale typeahead.
-Open the overlay (bottom right) to see what GenClass noticed; the browser console has one plain-English line per
-finding.
+Open the browser console to see what GenClass noticed: one plain-English `[GenClass]` line per finding.
## The one line
`src/main.ts` starts with:
```ts
-import genclass from "@genclass/runtime/auto";
+import "@genclass/runtime/auto";
```
It goes first so GenClass is installed before Angular bootstraps and before your app's first requests. GenClass runs
@@ -46,19 +45,21 @@ Decisions that compare a late response with newer data already in your state nee
| guard | `@genclass/runtime/auto/guard` | also prevents failures with small, reversible actions (reuse a duplicate's result, back off) when its model is confident |
| heal (experimental) | `@genclass/runtime/auto/heal` | also retries, serves cached data, blocks a runaway request |
-Start in observe, watch the overlay and the console for a while on real traffic, then switch the import to
-`/auto/guard`. Every action is logged with its evidence, and the overlay can undo it.
+Start in observe, watch the console for a while on real traffic, then switch the import to `/auto/guard`. Every action
+is logged with its evidence.
-## Devtools overlay
+## Devtools overlay (opt-in)
-The last line of `src/main.ts` loads the overlay in development only:
+The template draws nothing on the page. To see the devtools overlay while you develop, name the import and add the
+overlay line at the end of `src/main.ts`:
```ts
+import genclass from "@genclass/runtime/auto";
+import { isDevMode } from "@angular/core";
+// ...
if (isDevMode()) import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));
```
-`isDevMode()` is false in a production build, so the line is dropped from it.
-
## Turning it off
- For one page load: add `?genclass=off` to the URL (nothing is installed).
diff --git a/templates/angular/src/app/search.ts b/templates/angular/src/app/search.ts
index 683eb560..77edd4ef 100644
--- a/templates/angular/src/app/search.ts
+++ b/templates/angular/src/app/search.ts
@@ -1,7 +1,6 @@
// A search box written the way a lot of code is: every keystroke subscribes, and whichever answer arrives last wins
// (no switchMap). The API (src/server.ts) answers in a random 50-900 ms, so type quickly and an older answer can
-// overwrite a newer one. GenClass watches this with no code here: open the overlay (bottom right, development only)
-// to see what it finds.
+// overwrite a newer one. GenClass watches this with no code here: open the browser console to see what it finds.
import { HttpClient } from "@angular/common/http";
import { Component, inject, signal } from "@angular/core";
@@ -10,7 +9,7 @@ import { Component, inject, signal } from "@angular/core";
template: `
GenClass + Angular
-
Type a city quickly, for example “san”, then look at the GenClass overlay.
+
Type a city quickly, for example “san”, then look at the browser console.
@for (r of results(); track r) {
diff --git a/templates/angular/src/main.ts b/templates/angular/src/main.ts
index b19978ab..66081fc7 100644
--- a/templates/angular/src/main.ts
+++ b/templates/angular/src/main.ts
@@ -1,13 +1,9 @@
// GenClass goes first, before Angular, so it is installed before your app and its first requests.
// "@genclass/runtime/auto" observes (reports what it sees, never changes anything). To let it act, switch to
// "@genclass/runtime/auto/guard". Add ?genclass=off to the URL to turn it off for a page load.
-import genclass from "@genclass/runtime/auto";
-import { isDevMode } from "@angular/core";
+import "@genclass/runtime/auto";
import { bootstrapApplication } from "@angular/platform-browser";
import { App } from "./app/app";
import { appConfig } from "./app/app.config";
bootstrapApplication(App, appConfig).catch((err) => console.error(err));
-
-// The devtools overlay, in development only (isDevMode() is false in a production build, so this is dropped from it).
-if (isDevMode()) import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));
diff --git a/templates/astro/README.md b/templates/astro/README.md
index 1038efad..449252f3 100644
--- a/templates/astro/README.md
+++ b/templates/astro/README.md
@@ -6,13 +6,13 @@ line in `astro.config.mjs`.
```bash
npm install
-npm run dev # http://localhost:4321, with the GenClass devtools overlay
-npm run build && npm start # production build (no overlay), served by the Node adapter
+npm run dev # http://localhost:4321
+npm run build && npm start # production build, served by the Node adapter
```
-Type a city quickly in the search box. The API route (`src/pages/api/search.ts`) answers in a random 50-900 ms, so
-an older answer can overwrite a newer one: the classic stale typeahead. Open the overlay (bottom right) to see what
-GenClass noticed; the browser console has one plain-English line per finding.
+Type a city quickly in the search box. The API route (`src/pages/api/search.ts`) answers in a random 50-900 ms, so an
+older answer can overwrite a newer one: the classic stale typeahead. Open the browser console to see what GenClass
+noticed: one plain-English `[GenClass]` line per finding.
## The one line
@@ -45,13 +45,17 @@ or a React island, whose state is discovered.
| observe (default) | `genclass()` | reports what it finds; never holds, drops or changes anything |
| guard | `genclass({ mode: "guard" })` | also prevents failures with small, reversible actions (drop a stale response, reuse a duplicate's result) when its model is confident |
-Start in observe, watch the overlay and the console for a while on real traffic, then switch to `guard`. Every action
-is logged with its evidence, and the overlay can undo it.
+Start in observe, watch the console for a while on real traffic, then switch to `guard`. Every action is logged with
+its evidence.
-## Devtools overlay
+## Devtools overlay (opt-in)
-The integration loads the overlay under `astro dev` only (`devtools: "dev"`, the default); a production build carries
-no reference to it. `genclass({ devtools: "always" })` loads it in production too, `"never"` not at all.
+The integration draws nothing on the page. To see the devtools overlay under `astro dev` only, pass the option in
+`astro.config.mjs`:
+
+```js
+integrations: [genclass({ devtools: "dev" })],
+```
## Turning it off
diff --git a/templates/astro/astro.config.mjs b/templates/astro/astro.config.mjs
index a29e592f..1dcf46e1 100644
--- a/templates/astro/astro.config.mjs
+++ b/templates/astro/astro.config.mjs
@@ -4,8 +4,8 @@ import genclass from "@genclass/astro";
import { defineConfig } from "astro/config";
// GenClass, in the browser only: the integration injects the runtime's one line into every page. genclass() observes
-// (reports what it sees, never changes anything) and loads the devtools overlay under `astro dev` only. To let it act,
-// use genclass({ mode: "guard" }). Add ?genclass=off to the URL to turn it off for a page load.
+// (reports what it sees, never changes anything) and draws nothing on the page. To let it act, use
+// genclass({ mode: "guard" }). Add ?genclass=off to the URL to turn it off for a page load.
// The Node adapter is here so the mock API route (src/pages/api/search.ts) also runs in the production build.
export default defineConfig({
integrations: [genclass()],
diff --git a/templates/astro/src/pages/index.astro b/templates/astro/src/pages/index.astro
index 30de443f..9171e75c 100644
--- a/templates/astro/src/pages/index.astro
+++ b/templates/astro/src/pages/index.astro
@@ -2,7 +2,7 @@
// One page with a search box written the way a lot of code is: every keystroke fetches, and whichever answer arrives
// last wins. The API route (src/pages/api/search.ts) answers in a random 50-900 ms, so type quickly and an older
// answer can overwrite a newer one. GenClass watches this with no code here (the integration in astro.config.mjs
-// injects its one line into every page): open the overlay (bottom right, development only) to see what it finds.
+// injects its one line into every page): open the browser console to see what it finds.
---
@@ -14,7 +14,7 @@
GenClass + Astro
-
Type a city quickly, for example “san”, then look at the GenClass overlay.
+
Type a city quickly, for example “san”, then look at the browser console.
diff --git a/templates/nextjs/README.md b/templates/nextjs/README.md
index e9ec6b4c..4920c246 100644
--- a/templates/nextjs/README.md
+++ b/templates/nextjs/README.md
@@ -5,20 +5,20 @@ recommended way: one import in `instrumentation-client.ts`.
```bash
npm install
-npm run dev # http://localhost:3000, with the GenClass devtools overlay
-npm run build && npm start # production build (no overlay)
+npm run dev # http://localhost:3000
+npm run build && npm start # production build
```
-Type a city quickly in the search box. The API route (`app/api/search/route.ts`) answers in a random 50-900 ms, so
-an older answer can overwrite a newer one: the classic stale typeahead. Open the overlay (bottom right) to see what
-GenClass noticed; the browser console has one plain-English line per finding.
+Type a city quickly in the search box. The API route (`app/api/search/route.ts`) answers in a random 50-900 ms, so an
+older answer can overwrite a newer one: the classic stale typeahead. Open the browser console to see what GenClass
+noticed: one plain-English `[GenClass]` line per finding.
## The one line
`instrumentation-client.ts` (Next.js 15.3 and later runs it in the browser before your app's code):
```ts
-import genclass from "@genclass/runtime/auto";
+import "@genclass/runtime/auto";
```
That is all the setup. GenClass runs in the browser only: on the server (SSR, route handlers) the import is inert,
@@ -35,14 +35,17 @@ small client component in the root layout instead).
| guard | `@genclass/runtime/auto/guard` | also prevents failures with small, reversible actions (drop a stale response, reuse a duplicate's result) when its model is confident |
| heal (experimental) | `@genclass/runtime/auto/heal` | also retries, serves cached data, rolls back |
-Start in observe, watch the overlay and the console for a while on real traffic, then switch the import to
-`/auto/guard`. Every action is logged with its evidence, and the overlay can undo it.
+Start in observe, watch the console for a while on real traffic, then switch the import to `/auto/guard`. Every action
+is logged with its evidence.
-## Devtools overlay
+## Devtools overlay (opt-in)
-`instrumentation-client.ts` also loads the overlay when `NODE_ENV` is `development`:
+The template draws nothing on the page. To see the devtools overlay while you develop, name the import and add the
+overlay line at the end of `instrumentation-client.ts`:
```ts
+import genclass from "@genclass/runtime/auto";
+
if (process.env.NODE_ENV === "development") {
import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));
}
diff --git a/templates/nextjs/app/page.tsx b/templates/nextjs/app/page.tsx
index ad9b9a17..d780b7a9 100644
--- a/templates/nextjs/app/page.tsx
+++ b/templates/nextjs/app/page.tsx
@@ -4,7 +4,7 @@ export default function Page() {
return (
GenClass + Next.js
-
Type a city quickly, for example “san”, then look at the GenClass overlay.
+
Type a city quickly, for example “san”, then look at the browser console.
);
diff --git a/templates/nextjs/app/search.tsx b/templates/nextjs/app/search.tsx
index e647cb13..5570a6a0 100644
--- a/templates/nextjs/app/search.tsx
+++ b/templates/nextjs/app/search.tsx
@@ -1,7 +1,7 @@
"use client";
// A search box written the way a lot of code is: every keystroke fetches, and whichever answer arrives last wins.
// The API route answers in a random 50-900 ms, so type quickly and an older answer can overwrite a newer one.
-// GenClass watches this with no code here: open the overlay (bottom right, development only) to see what it finds.
+// GenClass watches this with no code here: open the browser console to see what it finds.
import { useEffect, useState } from "react";
export default function Search() {
diff --git a/templates/nextjs/instrumentation-client.ts b/templates/nextjs/instrumentation-client.ts
index 0bbf43e0..871a3e70 100644
--- a/templates/nextjs/instrumentation-client.ts
+++ b/templates/nextjs/instrumentation-client.ts
@@ -1,9 +1,4 @@
// GenClass, in the browser only: Next.js (>= 15.3) runs instrumentation-client before your app's code.
// "@genclass/runtime/auto" observes (reports what it sees, never changes anything). To let it act, switch to
// "@genclass/runtime/auto/guard". Add ?genclass=off to the URL to turn it off for a page load.
-import genclass from "@genclass/runtime/auto";
-
-// The devtools overlay, in development only.
-if (process.env.NODE_ENV === "development") {
- import("@genclass/runtime/devtools").then((d) => d.mountDevtools(genclass));
-}
+import "@genclass/runtime/auto";
diff --git a/templates/nuxt/README.md b/templates/nuxt/README.md
index da827f5f..6cc978dd 100644
--- a/templates/nuxt/README.md
+++ b/templates/nuxt/README.md
@@ -6,13 +6,13 @@ way for Nuxt: the [`@genclass/nuxt`](https://www.npmjs.com/package/@genclass/nux
```bash
npm install
-npm run dev # http://localhost:3000, with the GenClass devtools overlay
-npm run build && node .output/server/index.mjs # production build (no overlay)
+npm run dev # http://localhost:3000
+npm run build && node .output/server/index.mjs # production build
```
-Type a city quickly in the search box. The API route (`server/api/search.get.ts`) answers in a random 50-900 ms, so
-an older answer can overwrite a newer one: the classic stale typeahead. Open the overlay (bottom right) to see what
-GenClass noticed; the browser console has one plain-English line per finding.
+Type a city quickly in the search box. The API route (`server/api/search.get.ts`) answers in a random 50-900 ms, so an
+older answer can overwrite a newer one: the classic stale typeahead. Open the browser console to see what GenClass
+noticed: one plain-English `[GenClass]` line per finding.
## The one line
@@ -41,15 +41,19 @@ stalls. Decisions that compare a late response with newer data already in your s
| observe (default) | `genclass: {}` | reports what it finds; never holds, drops or changes anything |
| guard | `genclass: { mode: "guard" }` | also prevents failures with small, reversible actions (reuse a duplicate's result, back off) when its model is confident |
-Start in observe, watch the overlay and the console for a while on real traffic, then switch to `guard`. Every action
-is logged with its evidence, and the overlay can undo it.
+Start in observe, watch the console for a while on real traffic, then switch to `guard`. Every action is logged with
+its evidence.
-## Devtools overlay
+## Devtools overlay (opt-in)
-The module loads the overlay in `nuxt dev` only (`devtools: "dev"`, the default); a production build carries no
-reference to it. `genclass: { devtools: "always" }` loads it in production too, `"never"` not at all. Nuxt's own
-devtools are turned off in this starter's `nuxt.config.ts` so the page shows one overlay; turn them back on if you
-like.
+The module draws nothing on the page. To see the devtools overlay under `nuxt dev` only, set the option in
+`nuxt.config.ts`:
+
+```ts
+genclass: { devtools: "dev" },
+```
+
+Nuxt's own devtools are off in this starter so the page shows only the app; turn them back on if you like.
## Turning it off
diff --git a/templates/nuxt/app.vue b/templates/nuxt/app.vue
index 0473d509..9478fd5f 100644
--- a/templates/nuxt/app.vue
+++ b/templates/nuxt/app.vue
@@ -1,8 +1,7 @@