isotone 0.4.1 → 1.0.0

package/dist/serve.js

@@ -11,7 +11,7 @@ import {
 import {
   UPDATE_ENDPOINT,
   startUpdateCheck
-} from "./chunk-UMVPMPVE.js";
+} from "./chunk-BJ4UI73I.js";
 import {
   NOTES_ENDPOINT,
   ensureFileIgnored,

package/dist/server.js

@@ -10,10 +10,10 @@ import {
   readActive,
   variantsResponse,
   writeActive
-} from "./chunk-ZBULKB3S.js";
+} from "./chunk-DD6BKC3R.js";
 import {
   VARIANTS_ENDPOINT
-} from "./chunk-SNGBNVH2.js";
+} from "./chunk-OSETWKGE.js";
 import {
   NOTES_ENDPOINT,
   PAYLOAD_MAX,

package/dist/vite-plugin.js

@@ -15,14 +15,14 @@ import {
   resolveOverride,
   variantsDir,
   variantsResponse
-} from "./chunk-ZBULKB3S.js";
+} from "./chunk-DD6BKC3R.js";
 import {
   VARIANTS_ENDPOINT
-} from "./chunk-SNGBNVH2.js";
+} from "./chunk-OSETWKGE.js";
 import {
   UPDATE_ENDPOINT,
   startUpdateCheck
-} from "./chunk-UMVPMPVE.js";
+} from "./chunk-BJ4UI73I.js";
 import {
   NOTES_ENDPOINT,
   ensureDirIgnored,

package/docs/migration.md

@@ -12,8 +12,10 @@ its coding agent. The package and CLI are now `isotone`; the exported API names,
    CLI commands, standalone script URLs (`/isotone.js`), environment variables
    (`ISOTONE_UPDATE_CHECK` and `ISOTONE_VARIANT`), and agent instructions.
    Keep API names such as `iteration`, `IterationPanel`, and `mountIteration`.
-4. If the project has local variants, move `.iso-iterate/variants/` to
-   `.isotone/variants/` and update ignore rules. Check each variant preview
+4. Move the entire `.iso-iterate/` directory to `.isotone/`, including
+   `knobs.json`, `active.json`, and any local variants. Update ignore rules,
+   including a `.git/info/exclude` entry for `.isotone/active.json` if the
+   old active file was ignored there. Check each variant preview
    before promotion: a stored base snapshot containing the old package import
    can appear stale after the rename. Recreate or sync that variant against the
    renamed source rather than promoting it blindly. Leave
@@ -26,6 +28,6 @@ On the same browser origin, Isotone carries forward the previous default
 storage keys for offline notes, drafts, and knob selections. A different host,
 port, or browser profile has separate storage. Custom keys stay unchanged.
 
-The published `isotone@0.4.0` includes a one-time `migrate` command. Later
-versions use this guide; there is no migration command to maintain. Existing
-`iso-iterate` versions remain installable.
+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.

package/docs/updates.md

@@ -35,9 +35,9 @@ The suggested command pins the specific version you just checked, rather than a
 `latest` tag that could move before installation. For example:
 
 ```sh
-npm install -D --save-exact isotone@0.4.1
-pnpm add -D --exact isotone@0.4.1
-yarn add -D --exact isotone@0.4.1
+npm install -D --save-exact isotone@1.0.0
+pnpm add -D --exact isotone@1.0.0
+yarn add -D --exact isotone@1.0.0
 ```
 
 These examples illustrate the syntax; use the version reported by your check.
@@ -86,8 +86,9 @@ A lockfile records the selected dependency tree. `npm ci` installs that tree
 without updating the manifest or lockfile; publishing another version does not
 change it. [npm ci](https://docs.npmjs.com/cli/v11/commands/npm-ci/)
 
-`npm update` respects the declared range. Before 1.0, `^0.3.4` accepts patch
-releases below `0.4.0`; it does not adopt `0.4.0`. `^0.0.4` stays below `0.0.5`.
+`npm update` respects the declared range. `^1.0.0` accepts compatible minor
+and patch releases below `2.0.0`. Older `^0.3.4` installs stay below `0.4.0`;
+they do not adopt `1.0.0`. `^0.0.4` stays below `0.0.5`.
 An explicit install of a new version deliberately changes that choice.
 [npm's range examples](https://docs.npmjs.com/cli/v11/commands/npm-update/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isotone",
-  "version": "0.4.1",
+  "version": "1.0.0",
   "type": "module",
   "license": "MIT",
   "description": "Local feedback and design variants for your running web app. Pin elements, leave notes, and give your coding agent the context to make the change.",
@@ -35,7 +35,12 @@
   },
   "files": [
     "dist",
-    "docs",
+    "docs/assets/preview.jpg",
+    "docs/integrations.md",
+    "docs/migration.md",
+    "docs/updates.md",
+    "docs/variants.md",
+    "docs/third-party-notices.md",
     "AGENTS.md",
     "CHANGELOG.md"
   ],

package/docs/design.md

@@ -1,213 +0,0 @@
-# Instrument design
-
-Instrument is the single design for Isotone: a horizontal pill with feedback
-and variant panels above it. Light and dark mode share components, geometry,
-typography, interaction states and motion. Only their paint tokens differ.
-
-The panel should feel like a small physical control placed on the host page.
-Depth explains function; decoration should not compete with the app being
-reviewed.
-
-## Materials and states
-
-| Role | Light | Dark |
-| --- | --- | --- |
-| Panel surface | White with a light edge and crisp contact shadow | Dark neutral surface with a quiet edge and shadow |
-| Recessed field or selector slot | Gray fill and one crisp inset border | Deeper background with a restrained inset shadow |
-| Raised action or persistent selection | White face, gray border and unblurred gray bottom shadow | Lighter face, edge highlight and contact shadow |
-| Hover | Stronger text or edge within the existing material | Stronger text or a subtle lighter face |
-
-Gray means recessed in light mode. In the default design, selection means raised. Saved notes being
-edited, selected segments and thumbnails, the element picker toggle and open
-pill buttons indicate persistent selection. Segments, thumbnails and the picker
-use the shared selection recipe; pill buttons use Clean Highlight's simpler
-face, fine border and crisp contact shadow. A selected colour swatch
-keeps its represented colour inside that raised frame.
-
-Save as defaults, Send and other raised actions share their normal and hover
-recipes. Do not create a special Save button material, stack several inset
-borders, or use a brightness filter that also washes out the border. Hover must
-remain less prominent than a persistent selection.
-
-Idle pill icons and the count badge use the same muted visual hierarchy. The
-badge is part of the control, not a contrasting notification bubble. All icons
-come through the shared `Icon` component.
-
-Keyboard focus uses the common visible outline. The text field is an intentional
-exception: focusing it reveals the caret without changing the field's border,
-fill or bottom edge. Clicking any noninteractive area of the composer focuses
-the textarea. Its buttons retain their own actions. Disabled controls keep their
-shape and material, reduce opacity and do not receive hover treatment.
-
-## Geometry and content
-
-The layout constants live in `styles.ts`. Current anchors are:
-
-| Measure | Value |
-| --- | --- |
-| Panel inset and regular section spacing | 12px |
-| Space between panels and between panel and pill | 8px |
-| Composer inset | 10px, derived from the panel inset |
-| Composer controls | 24px faces, 14px icons, 28px hit areas |
-| Collapsed pill | 44 × 44px |
-| Expanded pill with two tools | 76 × 44px |
-| Tool faces | 28px, with 4px between faces and around them |
-| Saved note padding | 6px vertically, 11px horizontally; background extends 1px past the composer on each side |
-
-The expanded pill is the same material stretched horizontally. Preserve its
-lower surrounding rim, inset and proportions. Panels stay anchored above it;
-opening one must not move the pill or scale the text in another. Save as defaults
-sits at the bottom left of the variants panel and appears only when needed.
-
-Slider label spacing accounts for the thumb's inset within its hit area, so its
-visible edge has the same 6px gap below the header as other controls. Range
-inputs use block layout to avoid extra inline baseline space.
-
-Selector labels and their action-dialog titles share one font rule. Opening a
-dialog must not make the same label heavier. Selected and unselected options
-use the same font weight; their material and text colour indicate selection. The host's `--font-sans` may provide
-the typeface; component weights and sizing stay in the shared stylesheet.
-
-Saved feedback uses one row with inline references and no extra gap between rows.
-Note text sits 3px outside the composer text inset. References use at most 42%
-of the row, leaving the note the remaining width. The delete action floats over
-the top-right corner with a 24px hit target; it reserves no column. Show it on
-hover, keyboard focus or selection, and always on touch devices.
-References name the pinned element or selector rather than displaying a route
-and pin count. Defaults and feedback references use the same compact tag shape,
-typeface, border and shadow. A single tag may use all available width; multiple
-tags receive compact width limits. Preserve the full accessible text when
-clipping it visually.
-
-Composer tags share a horizontal strip. At rest their first and last edges align
-with the field's inset. While scrolling they can reach the field edges; there is
-no permanent side padding or dark fade in front of them. Editing and selector
-reference tags follow this same rule.
-
-Selector action dialogs show feedback first, then individual choices without
-an “Options” heading, followed by Reset to default, Keep default only, and
-removal last.
-
-Selector action dialogs have a 260px minimum height and reserve 360px in their
-parent panel when space allows, even for a selector with only one action. The viewport remains the upper
-bound; short screens scroll instead of pushing controls off-screen.
-
-Removal actions create readable, editable requests for the coding agent. They do
-not hide or mutate selectors, options or dependent controls. Cancel a pending
-request from its feedback note; selectors do not add a status or Undo row. Pending actions are
-disabled in the menu to avoid duplicate requests. Cancelling a pending request
-leaves the preview unchanged. Once an agent applies a source change, deleting the
-request does not undo that change.
-
-Native tooltips are reserved for brief icon-only hints and labels that actually
-overflow. Do not put full feedback notes, readable labels or internal selectors
-in `title` attributes. Check label overflow on pointer entry, without observing
-or measuring every row during render. Accessible labels retain the full text.
-
-## Scrolling
-
-Keep native scrolling, wheel/trackpad input and keyboard focus reveal. Hide
-scrollbar chrome without disabling overflow.
-
-Content passing under a fixed area fades into the actual surface. This applies
-to the Save footer, selector action-dialog header, conditional error footer and
-both edges of the saved-note list and the top of scrolled composer text. List
-padding lets its first and last rows scroll fully clear of the fades. The textarea top
-mask appears only after scrolling, preserving its first line at rest. Without
-reference tags, the textarea extends through the field's top inset: that space
-scrolls away with the content, and the fade reaches the field edge. With tags,
-the gap below the reference strip also belongs to the scrolling text area;
-scrolled text fades directly beneath the strip. Use the shared surface token or a mask so the
-fade also works over dark gradients. Do not create a hard clipping edge inside
-an otherwise empty inset. The first and last item must remain fully reachable;
-reserve scroll padding for fixed controls and keyboard outlines.
-
-## Theme configuration
-
-`theme` accepts four values on the React panel, mount and integrations:
-
-| Value | Meaning |
-| --- | --- |
-| `auto` (default) | Follow the actual page background near the dock |
-| `system` | Follow the OS colour preference, independent of the host page |
-| `light` | Always use the light palette |
-| `dark` | Always use the dark palette |
-
-Automatic detection ignores the overlay itself, composites transparent page
-backgrounds and follows page changes without polling. An unpainted canvas uses
-CSS `color-scheme`, or white when no dark canvas is declared. Open shadow roots
-at the sample point are included where the browser exposes them.
-
-Image and gradient backgrounds, closed shadow roots and CSSOM-only changes
-without a DOM or browser event cannot be reliably inferred. Those hosts should
-pass an explicit theme or use `system`. Keep detection in `theme.ts`; do not add
-component-level checks of page classes, media queries or background colour.
-
-## Motion
-
-Motion explains opening, closing and layout changes. Keyboard-initiated actions
-are immediate. Reduced motion removes spatial movement. Pointer hover stays
-brief. The launcher expands on mouse or hovering-pen entry, including on hybrid
-devices whose primary pointer reports as coarse. Touch still opens it by tap.
-The pill has a continuous hit surface across its rim and the gap between icons.
-
-`motion.ts` owns the shared timings: 200ms entry, 125ms exit and 180ms list reflow,
-with `cubic-bezier(.23,1,.32,1)`. Reuse these values instead of adding timing
-literals. There is no stagger across a queue of controls.
-
-Panel and list movement uses transforms and opacity through the Web Animations
-API. Text, corners and hit targets retain their natural size. Read positions
-before writing styles, retarget interrupted movement, and cancel animations on
-cleanup. The small pill width transition is bounded to the dock itself; do not
-extend width or height animation to long content lists.
-
-Lists above `MAX_ANIMATED_ITEMS` (40) update immediately. Large panels also skip
-cloned exit snapshots. Hidden lists do not measure every render, and typing in
-the composer must not remeasure unchanged selectors or notes.
-
-## Where changes belong
-
-| File | Responsibility |
-| --- | --- |
-| `src/react/appearance.ts` | Complete light/dark palettes and the shared material recipe |
-| `src/react/styles.ts` | Geometry, typography, shared control classes and state selectors |
-| `src/react/feedback-layout.ts`, `pill-active.ts` | Small material/layout recipes that can be independently previewed as overlays |
-| `src/react/UpdateNotice.tsx` | Quiet local update snapshot and explicit upgrade instructions |
-| `src/react/icons.tsx` | Icon choices, optical size and stroke |
-| `src/react/NoteSummary.tsx` | Saved feedback/defaults summaries and their shared tag rendering |
-| `src/react/IterationPanel.tsx` | Dock, composer, feedback and element-picking behavior |
-| `src/react/VariantsView.tsx` | Selectors, action dialogs and Save as defaults |
-| `src/react/theme.ts` | Theme resolution, observation and cleanup |
-| `src/react/motion.ts` | Motion timing and work limits |
-| `src/react/useDockMotion.ts`, `useLayoutMotion.ts` | Measured movement and interruption handling |
-
-To add a control, choose its semantic role first: surface, well, raised action or
-selection. Reuse that recipe and an existing control class where possible.
-Add any new state selector once in `styles.ts`. A new paint token must exist in
-both palettes; a spacing or behavior change never belongs in a theme branch.
-Extract repeated markup when it has shared behavior or content rules, as with
-summary tags, rather than copying a component for another theme.
-
-## Verification
-
-Inspect the same content in both themes: collapsed and expanded pill, empty and
-saved feedback, editing, pinned references, selectors, action dialogs, hover,
-keyboard focus, disabled actions and scrolling edges. Include a narrow viewport,
-long unbroken labels, many notes and many selector options. Exercise rapid
-open/close, keyboard shortcuts and reduced motion.
-
-The style tests reject theme-specific component/state rules and missing or
-circular paint tokens. React tests cover shared interactions, theme changes and
-async state preservation. Run `pnpm check` before a release. For screenshots,
-use synthetic demo content; never include local feedback files, personal notes
-or a real project's private interface.
-
-## Accepted design choices
-
-Inline references is the feedback layout. Clean Highlight is the active-pill
-material: a slightly lighter solid face, fine border and crisp 1px contact
-shadow. Both themes use the same recipe in `pill-active.ts`.
-
-Earlier list alternatives and the default, ring, dot, recessed and inset pill
-experiments have been removed. New alternatives should start from this baseline
-and remain separate until explicitly chosen.

package/docs/development.md

@@ -1,86 +0,0 @@
-# Development
-
-The runtime is TypeScript throughout. The expensive work is DOM traversal, disk
-access, and redundant updates; avoiding that work matters more here than adding
-a second language or runtime.
-
-## Boundaries
-
-| Layer | Responsibility |
-| --- | --- |
-| `src/core` | Note descriptors, browser persistence, variant sources and selection rules. No React or Vite. |
-| `src/react` | Shadow-root panel, shared materials, controls, themes and motion. |
-| `src/store.ts`, `src/file-store.ts` | Validated note storage, atomic writes and serialized updates. |
-| `src/variants-store.ts` | Manifests, file alternatives, path guards, activation and promotion. |
-| `src/server` | Request adapters, bounded bodies and origin checks. |
-| `src/vite`, `src/serve` | Development-server integration and self-contained panel delivery. |
-| `src/cli` | Setup, feedback and variant commands over the same stores. |
-| `src/standalone` | Private bundled React runtime for hosts without React. |
-
-Public entry points are `react`, `core`, `server`, `serve`, `vite`, and `cli`.
-Keep browser code out of server entries and keep React/Vite optional for CLI and
-standalone consumers. The build bundles only the icons used by the panel.
-
-## Local workflow
-
-`pnpm dev` starts the fictional demo at `http://127.0.0.1:4173`. Its top bar
-provides the theme settings:
-
-| Control | What it changes |
-| --- | --- |
-| Page | The mock app's actual light or dark background |
-| Panel | Automatic page detection, system preference, or an explicit theme |
-
-The sample app's Spacing, Accent colour, Card radius and Card padding selectors
-remain inside the panel. Clean Highlight is the product default; there is no
-active-pill design switcher.
-
-`/preview.html` composes real components in both themes for the README image.
-Demo feedback uses seeded files in a temporary
-directory, separate from project notes; the server removes them when it closes.
-Open `/?stress=1` for 500 selectors and 500 notes, including long labels and large
-feedback.
-
-`pnpm check` runs types, lint, build, and the test suite. `pnpm check:package`
-exercises the packed artifact in a clean consumer. Tests focus on observable
-behaviour, transport/store failures, lifecycle cleanup, and design boundaries.
-Use small regression cases for bugs; avoid tests that merely duplicate code.
-
-## Performance
-
-Selector dependencies are walked iteratively in linear time; long chains do not
-consume the JavaScript call stack. DOM descriptors read sibling metadata only
-where a selector needs it. Variant status uses an in-process Git-compatible blob
-hash rather than launching a process per file.
-
-Theme events and picker geometry are coalesced per frame. Note and selector layout
-animation runs only when the collection changes; collections above 40 items skip
-per-item motion. Reads precede writes, interrupted animations start from the
-visible position, and reduced-motion or keyboard actions remove movement.
-
-Do not add virtualization or a new runtime without a measured bottleneck and a
-clear benefit. Preserve native scrolling and keyboard access. Before changing
-performance-sensitive code, include large collections and failure/retry paths in
-validation; a fast happy path is insufficient.
-
-## UI changes
-
-Follow [the design language](design.md). Use shared semantic materials and
-components rather than selector-specific theme overrides. Check both themes,
-selected/hover/focus/disabled states, long labels, empty and populated feedback,
-sticky fades, narrow viewports, and reduced motion. Context must remain accessible
-even when a label is visually truncated.
-
-`src/react/feedback-layout.ts` holds the accepted inline-reference layout.
-`src/react/pill-active.ts` holds the accepted Clean Highlight recipe. Future
-review alternatives belong under `.isotone/variants/`.
-Edit the copied recipe when developing an alternative; keep shared geometry,
-theme tokens and unrelated controls in the main stylesheet.
-
-The panel's auto theme samples rendered background colours, not pixels from
-images. A host can pass `light` or `dark` when those samples do not represent the
-page. `system` deliberately ignores the host theme.
-
-For notice layout checks, `/?review=1&update-preview=1` supplies a fictional
-update result. It does not contact npm or install anything. `/?review=1` keeps
-feedback open across variant reloads.

package/docs/releasing.md

@@ -1,87 +0,0 @@
-# Releasing
-
-A push runs CI; it does not publish. Publishing a stable GitHub Release starts
-`.github/workflows/publish.yml`. Its tag must be exactly `v` followed by the
-version in `package.json`. Prereleases are skipped.
-
-## Before making the repository public
-
-Review the tracked tree and Git history, including deleted files, for private
-notes, credentials, internal URLs, screenshots and personal machine paths.
-Check the actual npm archive too: source maps contain source text. Keep demo
-content fictional and keep local feedback and scratch files out of Git and npm.
-A clean current tree does not prove that old commits are suitable for publication.
-
-Keep the MIT copyright notice and [third-party license notices](third-party-notices.md). Public author
-attribution and the intended repository/package links are deliberate; do not
-remove them as part of privacy cleanup. If history needs cleanup, agree on that
-separately before changing it or opening the repository.
-
-## Prepare a release
-
-1. Update the package version and changelog. Preserve the lockfile's resolved
-   versions unless the release intentionally changes dependencies.
-2. Run `pnpm install --frozen-lockfile`, `pnpm check`, and `pnpm check:package`.
-   Inspect both themes in the demo and confirm a production Vite build contains
-   no panel. Manual integrations must also guard their endpoints in production.
-3. Inspect `npm pack --dry-run --json`. Expect the built entries, declarations,
-   source maps, documentation and licenses. Check that the README preview image
-   exists and uses fictional content.
-4. After approval to release, commit the reviewed changes and publish a GitHub
-   Release at `v<version>`. Do not reuse a version already published to npm.
-
-The release check job rebuilds and tests the tagged checkout, then creates an
-archive. A separate job downloads that archive and publishes it with provenance.
-Only that job has OIDC permission; it does not install dependencies or run project
-scripts. CI also checks the packed runtime on Node 20 and full development checks
-on Node 22 and 24.
-
-## npm setup outside the repository
-
-In the package's npm settings, verify the trusted publisher names the intended
-GitHub owner, repository and **`publish.yml`**. Allow direct `npm publish`; new
-configurations can default to staged publishing only. This workflow has no GitHub
-environment name, so the configured publisher must not require one. An existing
-working publisher does not need replacing. A new configuration must complete its
-first publish within two days. The workflow uses GitHub-hosted runners, Node 24,
-and checks for npm 11.5.1 or newer. No long-lived publish token is needed.
-See [npm's trusted publishing guide](https://docs.npmjs.com/trusted-publishers/).
-
-The intended repository and package must be public for provenance, and
-`package.json`'s repository URL must match the publishing repository. Opening the
-repository and changing npm settings are separate maintainer actions. The local
-checks do not verify account-side configuration or prove that publication will
-succeed. See [npm's provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).
-
-After publishing, verify the new version, README image, exports and provenance
-on npm, then try the documented quick start in a clean project.
-
-## First release under the Isotone name
-
-Renaming the GitHub repository does not rename an npm package or change existing
-installs. npm requires publishing under the new name. Keep `iso-iterate`
-available so its existing lockfiles remain installable; deprecate it only after
-the new package and migration have been verified. See npm's
-[rename guidance](https://docs.npmjs.com/unpublishing-packages-from-the-registry/)
-and [deprecation guidance](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions/).
-
-Before tagging the first release, confirm that the publishing account can use
-`isotone`. A registry 404 or an unpublished-package record does not establish
-ownership or permission to publish. A successful local build establishes neither.
-If npm does not offer settings for the new package yet, establish it using an
-authenticated, maintainer-approved first publication before relying on its
-trusted publisher. Do not create a release tag on the assumption that the old
-package's publisher configuration applies to the new name.
-
-Configure the new package's publisher for `aaroi/isotone` and `publish.yml`, and
-verify its repository metadata. Then test both a clean install and the
-[migration](migration.md) in a copy of an existing project. Only after those pass,
-an authorized maintainer can set the old package's deprecation message:
-
-```sh
-npm deprecate iso-iterate "Renamed to isotone. Migration: https://github.com/aaroi/isotone/blob/main/docs/migration.md"
-```
-
-Deprecation displays guidance during installation; it does not migrate files,
-change dependencies, or remove existing installations. Do not unpublish the old
-package as part of the rename.