From a8be0ecc5758aef654e3d8eed76f5881fb35779d Mon Sep 17 00:00:00 2001 From: Mehar Khanna Date: Mon, 16 Nov 2026 02:07:43 -0500 Subject: [PATCH] Make the devtools overlay opt-in everywhere: nothing GenClass sets up draws on a page - runtime init: no overlay line unless --devtools (--no-devtools still accepted, a no-op); a re-run on a setup that still loads the overlay names the file and what to delete - @genclass/nuxt, @genclass/astro: devtools defaults to "never" ("dev" / "always" opt in) - @genclass/sv: never adds the overlay line - templates: overlay lines removed, opt-in notes in their READMEs; compat/templates-check.mjs expects no overlay - docs, changelogs and tests updated Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- README.md | 12 +- compat/templates-check.mjs | 12 +- docs/adoption/listings/svelte.md | 4 +- docs/runtime/API.md | 4 + docs/runtime/INSTALL.md | 11 +- packages/astro/CHANGELOG.md | 6 +- packages/astro/README.md | 6 +- packages/astro/src/index.ts | 16 +- packages/astro/test/integration.test.ts | 25 +-- packages/nuxt/CHANGELOG.md | 6 +- packages/nuxt/README.md | 6 +- packages/nuxt/src/module.ts | 6 +- packages/nuxt/src/source.ts | 15 +- packages/nuxt/test/module.test.ts | 28 ++-- packages/runtime/CHANGELOG.md | 8 + packages/runtime/README.md | 22 +-- packages/runtime/bin/genclass-runtime.mjs | 4 +- packages/runtime/bin/lib/init.mjs | 47 ++++-- .../test/install/INSTALL-README-SNIPPET.md | 6 +- packages/runtime/test/install/account.test.ts | 2 +- .../runtime/test/install/cli-sinks.test.ts | 8 +- packages/runtime/test/install/cli.test.ts | 145 ++++++++++++++---- packages/runtime/test/install/frameworks.mjs | 22 +-- packages/sv/CHANGELOG.md | 8 +- packages/sv/README.md | 10 +- packages/sv/package.json | 2 +- packages/sv/src/edit.ts | 71 +++------ packages/sv/src/index.ts | 8 +- packages/sv/test/e2e/addon.test.ts | 11 +- packages/sv/test/edit.test.ts | 71 ++++----- templates/README.md | 13 +- templates/angular/README.md | 23 +-- templates/angular/src/app/search.ts | 5 +- templates/angular/src/main.ts | 6 +- templates/astro/README.md | 24 +-- templates/astro/astro.config.mjs | 4 +- templates/astro/src/pages/index.astro | 4 +- templates/nextjs/README.md | 23 +-- templates/nextjs/app/page.tsx | 2 +- templates/nextjs/app/search.tsx | 2 +- templates/nextjs/instrumentation-client.ts | 7 +- templates/nuxt/README.md | 28 ++-- templates/nuxt/app.vue | 5 +- templates/nuxt/nuxt.config.ts | 6 +- templates/react-router/README.md | 21 +-- templates/react-router/app/entry.client.tsx | 5 +- templates/react-router/app/routes/home.tsx | 5 +- templates/react-vite/README.md | 25 +-- templates/react-vite/src/App.tsx | 4 +- templates/react-vite/src/main.tsx | 5 +- templates/sveltekit/README.md | 21 +-- templates/sveltekit/src/hooks.client.ts | 5 +- templates/sveltekit/src/routes/+page.svelte | 4 +- templates/vue-vite/README.md | 23 +-- templates/vue-vite/src/App.vue | 4 +- templates/vue-vite/src/main.ts | 5 +- 57 files changed, 485 insertions(+), 398 deletions(-) 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(` <script src="https://example.test/g.js" data-devtools="local"></script> <!-- genclass:init -->`); + expect(sync["index.html"]).toContain(` <script src="https://example.test/g.js"></script> <!-- genclass:init -->`); 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"></script> <!-- genclass:init -->`); + expect(html["index.html"]).toContain(` data-mode="${mode}"></script> <!-- genclass:init -->`); + // 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"></script> <!-- genclass:init -->`); } 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"></script> <!-- genclass:init -->`); 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<string, Record<string, string>> = { + 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 <html>\n <body>{children}</body>\n </html>\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": "<h1>hi</h1>\n" }, + nuxt: { "package.json": pkg({ nuxt: "^4.0.0" }), "app/app.vue": "<template><div/></template>\n" }, + astro: { "package.json": pkg({ astro: "^5" }), "src/layouts/Layout.astro": `<html>\n\t<head>\n\t\t<title>x\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 @@