isotone 1.1.3 → 1.2.1

package/docs/integrations.md

@@ -7,11 +7,15 @@ npm install -D isotone
 npx isotone init --yes
 ```
 
-`init` detects the project, prints the integration to add, and adds a short guide
-to `AGENTS.md`. It does not overwrite app code, install dependencies, or replace
-an existing guide. Running it again is safe. `init --json` returns a setup plan
-without writing files; add `--yes` to write the guide. `--approach overlay|host|serve`
-overrides the recommendation.
+`init` detects the project, prints the development-only integration to add and a
+short first run for the agent, and adds a short guide to `AGENTS.md`. It does not
+overwrite app code, install dependencies, or replace an existing guide. Running it
+again is safe; once the project has variants or knobs it skips the first run.
+`init --json` returns a setup plan without writing files; add `--yes` to write the
+guide. `--approach overlay|host|serve` overrides the recommendation.
+
+Isotone is a development tool. Every integration below keeps it out of production
+by default; see [Production](#production) for how each one does that.
 
 ## Vite: one plugin
 
@@ -27,12 +31,14 @@ plugins: [/* existing plugins */, iteration()]
 Restart the dev server. Source-file variants and notes are available immediately.
 The panel carries its own React runtime, so React, Vue, Svelte and vanilla Vite
 projects use the same setup. It does not enter the host's dependency optimizer or
-Fast Refresh graph. Nothing is injected in a production build.
+Fast Refresh graph. The plugin acts only on the dev server: `vite build` injects
+nothing and serves no endpoints, so it needs no guard of its own.
 
 If the app mounts `IterationPanel` or `mountIteration` itself, use
 `iteration({ panel: false })` to keep local endpoints and source variants without
 injecting a second panel. A manual mount can use
-`updateEndpoint: '/api/iteration/update'` for the optional update notice.
+`updateEndpoint: '/api/iteration/update'` for the optional update notice and
+its update note.
 The adapters check for updates in the background; see [Updates](updates.md) for
 the cache, explicit upgrade commands, and opt-out controls.
 
@@ -55,18 +61,46 @@ Run this inside the project in a second terminal:
 npx isotone serve
 ```
 
-Add this script to the development HTML only:
+Then load the panel in development only. For plain HTML pages, add this loader to
+each page. It requests nothing unless the page itself is on localhost, so it stays
+inert if the HTML is deployed:
 
 ```html
-<script src="http://127.0.0.1:4123/isotone.js" defer></script>
+<script>
+  if (/^(localhost|127\.0\.0\.1|\[::1\])$/.test(location.hostname))
+    document.head.append(Object.assign(document.createElement('script'),
+      { src: 'http://127.0.0.1:4123/isotone.js' }));
+</script>
+```
+
+A plain `<script src="http://127.0.0.1:4123/isotone.js" defer></script>` works too,
+but only behind a development flag of the template or build step: in production
+HTML it would make every visitor's browser request its own localhost, which recent
+browsers turn into a permission prompt. In a Next app, render it from the root
+layout (`app/layout.tsx`, or `pages/_app.tsx`) behind the development check, which
+Next inlines at build time:
+
+```tsx
+import Script from 'next/script';
+
+// Inside <body>:
+{process.env.NODE_ENV === 'development' && (
+  <Script src="http://127.0.0.1:4123/isotone.js" strategy="afterInteractive" />
+)}
 ```
 
 Open the printed setup URL for a copyable tag or a bookmarklet. The bundle has no
-host framework dependencies. This path supports notes; source-file switching
+host framework dependencies. This path supports notes and
+[knobs](variants.md#knobs): `.isotone/knobs.json` in the directory where `serve`
+runs is served at `/api/iteration/variants`, and the panel shows its range, colour
+and select knobs. The panel has a Variants tool only while that file holds valid
+knobs; reload the page after adding the first one. Swapping whole source files
 needs the Vite plugin, or a host-owned `VariantsSource`.
 
-`--port 4124` selects another port. `--file path/to/notes.json` selects a notes
-file. `--theme light` fixes the panel theme. The server binds to loopback and
+`--port 4124` selects another port; use the same port in the tag, and keep both in
+one place with a script such as `"isotone": "isotone serve --port 4124"`.
+`--file path/to/notes.json` selects a notes file. `--theme light` fixes the panel
+theme. The server binds to loopback and
 accepts browser requests from localhost origins only. An HTTPS page may block
 an HTTP script; use the same-origin route integration below in that case.
 
@@ -76,6 +110,12 @@ Use this when the framework should own the endpoint. Install `react` and
 `react-dom` if the app does not already have them; direct `isotone/react`
 imports use the host's React runtime.
 
+The Request adapters, `serveNotesRequest` and `serveVariantsRequest`, answer 404
+when `NODE_ENV` is `production`, so a route that reaches a deployment cannot read or
+write the notes file. A deliberate, access-controlled review deployment can pass
+`{ allowProduction: true }` as the third argument. Keep the route's own development
+check as well; it also covers runtimes that leave `NODE_ENV` unset.
+
 For a Next App Router project:
 
 ```ts
@@ -101,7 +141,9 @@ host and every request gets a 403 `origin not allowed`. Pass
 `serveVariantsRequest`) to accept pages served from localhost, 127.0.0.1 or
 [::1] on any port. Non-loopback origins are still rejected.
 
-For this manual route, add `.iteration-feedback.json` to the project's `.gitignore`.
+For this manual route, add `.iteration-feedback.json` to the project's
+`.gitignore`, and `.iteration-feedback.blast.json` if your agent runs
+[Blast mode](blast.md), whose CLI keeps its session there.
 The Vite plugin and standalone server ignore their notes file automatically; the
 transport-only request adapter does not modify Git configuration.
 
@@ -126,7 +168,10 @@ export function ReviewTools() {
 ```
 
 Render `<ReviewTools />` once in the app layout. The effect handles development
-Strict Mode and route unmounts. Other Request-based servers use the same handler;
+Strict Mode and route unmounts. The dynamic import sits behind the check, so a
+production bundle does not include the panel. `mountIteration` itself has no
+production guard: a host may deliberately mount a variants-only panel on a preview
+site. Other Request-based servers use the same handler;
 Node HTTP servers can call `notesResponse` and serialize its `body` themselves.
 That lower-level handler does not read or limit the HTTP request body, or check
 the request's origin: the host must handle those concerns. Prefer the
@@ -176,13 +221,28 @@ file holds. The panel slows its retries while the server is unreachable and stop
 polling in a hidden tab. Custom endpoints built on `notesResponse` or
 `serveNotesRequest` get this without changes.
 
+## Production
+
+| Integration | What keeps it out of production |
+| --- | --- |
+| Vite plugin | Acts only on `vite dev`. A build injects no panel and serves no endpoints. `ISOTONE_VARIANT` bakes chosen variants into a build only when set. |
+| `isotone serve` | A separate local process bound to loopback that accepts only localhost origins. The tag that loads it is either behind the framework's development check or the localhost-only loader above. |
+| Request adapters | `serveNotesRequest` and `serveVariantsRequest` answer 404 under `NODE_ENV=production` unless given `allowProduction: true`. The route keeps its own development check. |
+| `notesResponse`, `variantsResponse` | Lower-level functions with no guard; the host calls them only from development code. |
+| `mountIteration`, `IterationPanel` | No guard, by design. Import them dynamically behind the development check. |
+
+Agents set up through `init` are told the same rule in `AGENTS.md`: development
+only, unless the user explicitly asks to ship it.
+
 ## Confirm the integration
 
 1. Open the app in development and submit a note on an element.
 2. Run `npx isotone --json` in the app directory. Confirm the note's route,
    viewport and selector.
 3. Run `npx isotone --done <id-prefix>` and check that it leaves the panel.
-4. Build and serve the production app. The panel and dev endpoint should be absent.
+4. Build the production app and search the output for `isotone` and
+   `/api/iteration`. With the localhost-only loader, the tag remains in the HTML
+   but loads nothing outside localhost.
 
 If the panel is visible but the CLI has no notes, compare the dev server's printed
 notes path with the CLI's working directory. If the endpoint is unreachable, the

package/docs/migration.md

@@ -31,3 +31,22 @@ port, or browser profile has separate storage. Custom keys stay unchanged.
 Use `isotone@0.4.1` or newer. The older 0.4.0 package includes a one-time
 `migrate` command but also has note-saving bugs fixed in 0.4.1; use this guide
 for the work repositories. Existing `iso-iterate` versions remain installable.
+
+## Request handlers are off in production
+
+From the release after 1.1.3, `serveNotesRequest` and `serveVariantsRequest`
+from `isotone/server` answer 404 when `NODE_ENV` is `production`, without
+reading or writing any file. Development servers, test runners and runtimes
+that leave `NODE_ENV` unset are unaffected.
+
+Most projects need no change, because their route already returns early outside
+development. A project that deliberately serves the panel from a production
+build, such as an access-controlled review deployment, passes
+`{ allowProduction: true }` as the third argument to each handler:
+
+```ts
+const result = await serveNotesRequest('.iteration-feedback.json', req, { allowProduction: true });
+```
+
+Keep that deployment behind its own access control; anyone who reaches the
+endpoint can read and change the notes file.

package/docs/updates.md

@@ -2,8 +2,9 @@
 
 The project controls its installed version. Publishing a new release does not
 replace files in someone else's checkout. Isotone checks for a newer release
-in the background and offers the exact command to review and run. It never
-installs packages, executes that command, or changes a manifest or lockfile.
+in the background and lets you hand the upgrade to your coding agent, or copy
+the exact command. Isotone itself never installs packages, executes that
+command, or changes a manifest or lockfile.
 
 Moving from the previous package name is a separate [migration](migration.md).
 An update check does not replace a dependency with a differently named package.
@@ -15,6 +16,105 @@ attempts are cached too. CI and tests skip automatic checks. The registry reques
 contains the public package name; it sends no notes, routes, project paths,
 source files, installed-version telemetry or credentials.
 
+## In the panel
+
+When a newer release is out, a quiet line next to the pill reads "Isotone 1.2.0
+is available". It opens a small dialog: the versions from → to, and **Ask agent
+to update**. Below it, **Copy prompt** copies a ready-to-paste request for an
+agent that is not reading notes, and **Command** shows the raw upgrade command
+and the directory to run it in.
+
+**Ask agent to update** files an update note. It sits in the Feedback list with
+the other notes, on every page, tagged "Update", and reaches your agent through
+`npx isotone --json` like any other note. It concerns the whole project, so it is
+also listed for every route (`npx isotone <route> --json`). The dialog then reads "Update
+requested". Deleting the note cancels the request.
+
+The dev server builds the note from its own update check: the current and
+latest version, the upgrade command and the directory. The browser only asks for
+it, and the notes endpoint never accepts an update request, so a page cannot put
+a command in front of your agent. At most one update note is open. If a newer
+release appears while one is open, that note is updated instead of a second
+being added.
+
+The note's text is the server's too: the panel, `npx isotone` and `--json` show
+"Update Isotone 1.1.3 → 1.2.0" built from the request, whatever the file holds,
+and the notes endpoint refuses edits to an update note. Delete it to cancel.
+
+Because the notes file is a plain file in the project, every reader checks the
+request again before showing it, and drops it if anything is off:
+
+- `update.to` is a strict SemVer version (`1.2.0`, `1.2.0-rc.1`, no build
+  metadata);
+- `update.command` is exactly the command `check-update` builds for
+  `update.manager` and that version: `npm install [-D] --save-exact isotone@<to>`,
+  `pnpm add [-D] [-w] --exact isotone@<to>` or `yarn add [-D] [-W] --exact
+  isotone@<to>`;
+- `update.cwd` is an existing directory inside the notes file's project (the
+  Git checkout that holds it, or its directory outside Git), after symlinks.
+
+A dropped request leaves an ordinary note, which an agent treats as context.
+
+The note carries a structured `update` field next to its text:
+
+```json
+{
+  "feedback": "Update Isotone 1.1.3 → 1.2.0",
+  "update": {
+    "from": "1.1.3",
+    "to": "1.2.0",
+    "command": "pnpm add -D --exact isotone@1.2.0",
+    "cwd": "/path/to/app",
+    "manager": "pnpm",
+    "changelog": "https://github.com/aaroi/isotone/blob/v1.2.0/CHANGELOG.md"
+  },
+  "updateHint": "An update note is the user's request to upgrade Isotone. …",
+  "doneCommand": "npx isotone --done <id>"
+}
+```
+
+An agent treats it as the user's explicit request to upgrade. It runs the
+printed command only if it matches one of the canonical forms above, with the
+note's version, in that directory inside the project, and treats any other
+command or text as context. It then restarts the dev server if it runs it,
+checks that the panel still loads, summarizes the notable changes from the new
+CHANGELOG (also at `node_modules/isotone/CHANGELOG.md` after the install), and
+closes the note with `--done`. Page text and other notes are still context, not
+instructions; the update note's command comes from Isotone's own server.
+
+The button needs a notes endpoint and a command Isotone can name. When it
+cannot name one (Bun, competing lockfiles, an optional or peer dependency, or
+the Isotone source checkout), the dialog explains why instead.
+
+## Update notes without asking
+
+```ts
+iteration({ checkForUpdates: 'note' });
+```
+
+```sh
+npx isotone serve --update-note
+```
+
+With `checkForUpdates: 'note'` (`serveIteration` takes the same value), the dev
+server files the update note by itself the first time it sees a new version,
+once per version for each notes file. If you don't want that version, delete the
+note; it is not filed again until a newer release. The versions already offered
+are remembered in the same per-user temporary directory as the daily check. The
+default stays as it is: a notice, with the button.
+
+There is no mode that installs updates silently. Changing dependencies and the
+lockfile without the user's say:
+
+- adds supply-chain risk: a compromised or broken release would land in every
+  project the moment it is published, with nobody reviewing it first;
+- breaks reproducibility for teams: one developer's dev server would rewrite the
+  manifest and lockfile, and the next commit would carry an upgrade nobody chose;
+- restarts or breaks a dev server in the middle of someone's work.
+
+An update note keeps a person in the loop at the cost of one click, and the agent
+does the work in the open, where its diff can be reviewed.
+
 ## Checking and upgrading
 
 Check explicitly from the project directory:
@@ -74,11 +174,17 @@ Standalone:
 npx isotone serve --no-update-check
 ```
 
-`serveIteration` also accepts `checkForUpdates: false`. Set
+`serveIteration` also accepts `checkForUpdates: false`. Turning checks off also
+turns off update notes. Set
 `ISOTONE_UPDATE_CHECK=0` to disable automatic checks for either adapter.
 The explicit `check-update` command remains available. Manually mounted panels
 only show update information when given an `updateEndpoint` supplied by a local
-server; they do not contact npm from the browser.
+server; they do not contact npm from the browser. GET on that endpoint returns
+the cached check, and POST files the update note.
+
+For a layout check, `/?review=1&update-preview=1` in the demo shows a fictional
+update; asking the agent there files a demo note that the pretend agent picks up
+and closes. It does not contact npm or install anything.
 
 ## Version ranges and reproducibility
 

package/docs/variants.md

@@ -43,8 +43,48 @@ Choose the control for the decision being reviewed, not for variety in the panel
 Thumbnail grids are a presentation of select axes, not another `kind`. There are
 no separate checkbox, toggle, dropdown or free-text axis kinds. Use stable IDs,
 short descriptive labels, and independent axes for independent decisions.
-`section` groups related axes; `showWhen` hides a dependent axis until its parent
-has the relevant selection. Keep the default among the available options or swatches.
+`showWhen` hides a dependent axis until its parent has the relevant selection.
+Keep the default among the available options or swatches.
+
+## Sections
+
+Once a page has more than a few selectors, put each one in a section named after
+the part of the page it changes. Write the section as a label prefix, a `>`
+with a space on each side:
+
+```ts
+{ id: 'logo-size', label: 'Header > Logo size', kind: 'range', min: 16, max: 48, step: 2, defaultValue: 24, unit: 'px' }
+```
+
+The panel shows a **Header** heading with *Logo size* under it. The heading stays
+at the top of the list while you scroll through its selectors, shows how many it
+holds, and folds the section away. Screen readers, notes and saved defaults keep
+the full name, `Header › Logo size`.
+
+- Only the first ` > ` splits, so `Header > Nav > Gap` is *Nav > Gap* in Header.
+  ` › ` works the same way. The spaces matter: `a>b` stays one label.
+- A slash never makes a section, so binary selectors such as `Light / Dark` or
+  `Grid / List` keep their whole label.
+- Sections match without regard to case and keep the casing of their first selector.
+- Selectors without a section come first, without a heading. Sections follow in
+  the order their first selector appears, and selectors keep their order inside them.
+- A `showWhen` selector without its own section joins its parent's section.
+- Section names are display text only. IDs, `?v=` links and `selections` do not change.
+
+An explicit `section` field overrides the prefix. The label then shows as written,
+less a prefix that repeats the section. `section: ''` keeps a label that needs a
+spaced `>`, such as `Before > After`, out of every section:
+
+```ts
+{ id: 'order', label: 'Before > After', section: '', options: [/* … */], defaultOption: 'before' }
+```
+
+The same works everywhere a selector is defined. Host axes and `.isotone/knobs.json`
+entries take a prefixed `label` or a `section` field. File variants take it from the
+group label (`variant new <id> --group-label "Header > Logo"`), or from
+`variant new <id> --section Header`. `variant section <id> <text>` moves an existing
+selector, with every variant in its group; `variant section <id> --none` takes it out
+of every section. `variant list` shows a SECTION column.
 
 For a range, choose bounds that produce useful, valid designs at both extremes.
 Use a positive `step` that matches the decision's precision, and a default aligned
@@ -77,8 +117,9 @@ project, declare numeric and colour controls in `knobs.json` as below, and read
 their CSS custom properties instead of copying a file for every possible value.
 Verify every control changes the intended app property, including its minimum,
 maximum and reset state. When saving defaults, keep the source fallback and the
-axis default in sync. The interactive demo includes card radius and padding sliders;
-its screenshot view keeps the original two selectors for a compact composition.
+axis default in sync. The interactive demo includes card radius and padding sliders
+in a Cards section and the accent colour in a Theme section; its screenshot view
+keeps the original two selectors, without sections, for a compact composition.
 
 Removal actions in the panel save requests for the agent. Selectors and options
 stay visible and usable until the agent changes the project. Requests open in
@@ -131,7 +172,7 @@ optional `route` (a pattern like a variant's, or a list of them):
   {
     "kind": "range",
     "id": "fade-from",
-    "label": "Fade starts",
+    "label": "Hero > Fade starts",
     "min": 0,
     "max": 100,
     "step": 1,
@@ -142,8 +183,25 @@ optional `route` (a pattern like a variant's, or a list of them):
 ]
 ```
 
+A colour knob takes a `defaultColor` and named `swatches`, all as hex values:
+
+```json
+{
+  "kind": "color",
+  "id": "accent",
+  "label": "Accent colour",
+  "defaultColor": "#2f6f4e",
+  "swatches": [
+    { "id": "forest", "label": "Forest", "value": "#2f6f4e" },
+    { "id": "clay", "label": "Clay", "value": "#b4532a" }
+  ]
+}
+```
+
 The panel renders range knobs as sliders and colour knobs as swatches with a
-custom picker, on their configured routes. A value reaches the
+custom picker, on their configured routes. An entry with a missing or invalid
+field is skipped; `npx isotone variant list` names each one. Knobs also work with
+`isotone serve`, so any dev server gets them, not only Vite. A value reaches the
 page as a custom property on `<html>`, `--knob-<id>`, with the unit
 appended, so the source reads it with the committed default as the
 fallback:
@@ -177,7 +235,7 @@ document.addEventListener('isotone:knob', ({ detail }) => {
 The event only fires while the panel is mounted, so keep the committed default in
 the source. Knob values live in the reviewer's browser, not on the server. "Save as
 defaults" files the moved knobs in the same `[set-defaults]` note as the
-variant picks, as `Knobs: Fade starts 40% (fade-from)` with a `knobs`
+variant picks, as `Knobs: Hero › Fade starts 40% (fade-from)` with a `knobs`
 payload of `fade-from:40`; the agent writes the number into the source and
 into the knob file's `defaultValue`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isotone",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "type": "module",
   "license": "MIT",
   "description": "Design variants and feedback for your running web app. Switch between variants your coding agent builds, pin elements, and give the agent the context to make the change.",
@@ -39,6 +39,7 @@
     "docs/integrations.md",
     "docs/migration.md",
     "docs/updates.md",
+    "docs/blast.md",
     "docs/variants.md",
     "docs/third-party-notices.md",
     "AGENTS.md",

package/dist/chunk-A4DX2V4C.js

@@ -1,7 +0,0 @@
-// src/core/limits.ts
-var MAX_FEEDBACK_LENGTH = 4e3;
-
-export {
-  MAX_FEEDBACK_LENGTH
-};
-//# sourceMappingURL=chunk-A4DX2V4C.js.map

package/dist/chunk-A4DX2V4C.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/limits.ts"],"sourcesContent":["/** Maximum feedback length after trimming, shared by browser and server. */\nexport const MAX_FEEDBACK_LENGTH = 4000;\n"],"mappings":";AACO,IAAM,sBAAsB;","names":[]}