isotone 1.1.2 → 1.2.0

package/dist/core.d.ts

@@ -1,3 +1,32 @@
+/** Read-only snapshot from the local development server. */
+interface UpdateInfo {
+    currentVersion: string;
+    latestVersion: string | null;
+    status: 'checking' | 'available' | 'current' | 'ahead' | 'unavailable' | 'disabled';
+    upgrade: {
+        manager: 'npm' | 'pnpm' | 'yarn';
+        command: string;
+        cwd: string;
+    } | null;
+    message?: string;
+}
+/**
+ * The user's request to upgrade Isotone, carried by one feedback note. The
+ * local server builds it from its own update check; the browser only asks for
+ * it, so the versions and command never come from page content.
+ */
+interface UpdateRequest {
+    from: string;
+    to: string;
+    /** The exact command `check-update` suggests, pinned to `to`. */
+    command: string;
+    /** The directory to run it in: the manifest that declares Isotone. */
+    cwd: string;
+    manager: 'npm' | 'pnpm' | 'yarn';
+    /** The release's changelog, to summarize for the user afterwards. */
+    changelog?: string;
+}
+
 /**
  * isotone — variants: the framework-free model.
  *
@@ -44,7 +73,12 @@ interface SelectVariantAxis {
     /** The primary option; what a host renders when nothing is selected. */
     defaultOption: string;
     showWhen?: VariantAxisCondition;
-    /** Panel grouping: a hairline separates consecutive different sections. */
+    /**
+     * The part of the page the selector belongs to, shown as a section header in
+     * the panel. Usually written as a label prefix instead (`"Header > Logo size"`);
+     * see {@link axisSection}. When set, it wins over the prefix, and `''` keeps the
+     * selector out of every section with its label shown as written.
+     */
     section?: string;
 }
 interface RangeVariantAxis {
@@ -86,6 +120,42 @@ interface VariantAction {
     action: 'remove-option' | 'remove-axis' | 'keep-default';
     optionId?: string;
 }
+/** How a section and its selector are joined for display: `Header › Logo size`. */
+declare const SECTION_SEPARATOR = " \u203A ";
+interface SectionedLabel {
+    /** The section's display name, or `null` for a selector without one. */
+    section: string | null;
+    /** What the panel prints under the section header. */
+    label: string;
+    /** Section and label together, for assistive technology, notes and the CLI. */
+    fullLabel: string;
+}
+/**
+ * Split a selector label into its section and its own name. `"Header > Logo size"`
+ * is the Logo size selector in the Header section. The first separator wins, so
+ * `"Header > Nav > Gap"` is `Nav > Gap` in Header. An explicit `section` overrides
+ * the prefix: the label then shows as written, less a prefix that repeats the
+ * section, and `''` means no section at all.
+ */
+declare function splitSectionLabel(label: string, section?: string): SectionedLabel;
+declare function axisSection(axis: Pick<VariantAxis, 'label' | 'section'>): SectionedLabel;
+interface VariantSection<T extends VariantAxis = VariantAxis> {
+    /** Display name, from the section's first selector; `null` for selectors without one. */
+    name: string | null;
+    /** Case-insensitive identity: `"Header"` and `"header"` are one section. */
+    key: string;
+    axes: (SectionedLabel & {
+        axis: T;
+    })[];
+}
+/**
+ * Group axes for the panel. Selectors without a section come first, without a
+ * header; sections follow in the order their first selector appears, and every
+ * selector keeps its relative order. A dependent axis (`showWhen`) without its
+ * own section joins its parent's, so it never jumps away from the control that
+ * reveals it. Linear in the number of axes.
+ */
+declare function sectionAxes<T extends VariantAxis>(axes: T[]): VariantSection<T>[];
 /** The primary value of an axis, as the selection string. */
 declare function axisDefault(axis: VariantAxis): string;
 /** True when `value` is legal for the axis. */
@@ -190,6 +260,9 @@ interface OverlayVariant {
     group?: string;
     /** What the panel calls the group's selector. Any member may carry it. */
     groupLabel?: string;
+    /** The panel section the group's selector sits in, like an axis `section`.
+     *  Any member may carry it; a `groupLabel` prefix (`"Header > Logo"`) also works. */
+    section?: string;
     createdAt: string;
     /**
      * Repo-relative source path → what the override was derived from. `base`
@@ -212,7 +285,7 @@ interface OverlayVariantStatus extends OverlayVariant {
     missing: string[];
 }
 /**
- * A knob: a range or colour axis the host declares in `.isotone/knobs.json`
+ * A knob: a range, colour or select axis the host declares in `.isotone/knobs.json`
  * next to its overlay variants. The panel renders it as a slider (or a colour
  * pick) on the routes it names, and the value reaches the page as a CSS
  * custom property on `<html>`, `--knob-<id>`, with the axis unit appended
@@ -220,8 +293,12 @@ interface OverlayVariantStatus extends OverlayVariant {
  * committed default: `var(--knob-fade-from, 0%)`. "Save as defaults" files
  * the moved knobs in the same `[set-defaults]` note as the variant picks, so
  * the agent writes the numbers into the source and the knob file.
+ *
+ * A select knob's value is its option id, which CSS cannot branch on through a
+ * custom property, so it also lands as `data-knob-<id>` on `<html>`. Code that
+ * draws for itself listens for {@link KNOBS_EVENT} on the document.
  */
-type KnobAxis = (RangeVariantAxis | ColorVariantAxis) & {
+type KnobAxis = (RangeVariantAxis | ColorVariantAxis | SelectVariantAxis) & {
     /** Route pattern(s) the knob belongs on, like a variant's `route`; absent means every route. */
     route?: string | string[];
 };
@@ -235,7 +312,11 @@ interface OverlayVariantsList {
 }
 /** The custom property a knob writes: `--knob-<id>`. */
 declare function knobVar(id: string): string;
-/** The property's value: a range carries its unit, a colour is its hex. */
+/** Fired on `<html>`, bubbling, when a knob's value changes. `detail` is
+ *  `{ id, value }` with the same value the custom property holds, or `null`
+ *  when the knob went back to its default. */
+declare const KNOBS_EVENT = "isotone:knob";
+/** The property's value: a range carries its unit, a colour is its hex, a select is the option id. */
 declare function knobCssValue(axis: KnobAxis, value: string): string;
 /** The knobs that belong on `route`. */
 declare function knobsFor(knobs: KnobAxis[] | undefined, route: string): KnobAxis[];
@@ -245,6 +326,10 @@ declare function applyKnobValues(knobs: KnobAxis[], values: VariantSelections, r
         setProperty(name: string, value: string): void;
         removeProperty(name: string): void;
     };
+    setAttribute?(name: string, value: string): void;
+    removeAttribute?(name: string): void;
+    getAttribute?(name: string): string | null;
+    dispatchEvent?(event: Event): boolean;
 }): void;
 /** The knobs that sit off their default, with the value the panel showed. */
 declare function knobDelta(knobs: KnobAxis[], values: VariantSelections): {
@@ -344,8 +429,25 @@ interface IterationElement {
     tag: string;
     /** Trimmed text-content snippet (may be empty for visual elements). */
     text: string;
-    /** Best-effort CSS path for locating the element in code. */
+    /** CSS path to the element. A pin made in a browser matches only this element. */
     selector: string;
+    /** Identifying attributes: role, name, aria-label, data-*, class and so on. */
+    attributes?: Record<string, string>;
+    /** React components around the element, outermost first. */
+    component?: string[];
+    /** `file:line` of the JSX, where the host's React still records it. */
+    source?: string;
+    /** Labelled or headed ancestors, outermost first. */
+    within?: string[];
+    /** The closest ancestor's text, for an element with none of its own. */
+    near?: string;
+    /** Where it sat on the page when pinned, in CSS pixels from the document's corner. */
+    rect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
 }
 /** A durable reference to a selector or one of its options, not a DOM path. */
 interface VariantReference {
@@ -365,6 +467,23 @@ interface NoteContext {
     variantAction?: VariantRemoval;
     elements?: IterationElement[];
     variant?: VariantReference | null;
+    /** The user's request to upgrade Isotone, built by the local server from
+     *  its own update check. At most one is open at a time. */
+    update?: UpdateRequest;
+    /** The agent's question or remark about the note, written with
+     *  `isotone --reply <id> "<text>"`. Only the CLI writes it; the panel shows it
+     *  under the note, and the reviewer answers by editing the note. */
+    reply?: NoteReply;
+}
+interface NoteReply {
+    text: string;
+    at: string;
+    /** A fingerprint of the note as it was when the agent asked. Until the
+     *  reviewer edits the note, Blast does not hand it out again. */
+    about?: string;
+    /** Set when the note has changed since the agent asked: the reviewer's
+     *  edit answered the question, so it is no longer pending. */
+    answered?: boolean;
 }
 /** A note written in the panel, read and answered by the coding agent. */
 interface IterationNote extends NoteContext {
@@ -399,12 +518,18 @@ interface NodeLike {
     textContent?: string | null;
     /** One-based child position, when the adapter can provide it cheaply. */
     indexInParent?: number;
+    /** Whether a selector finds this node and nothing else. Without one, the
+     *  path stops at an id or the depth cap, unchecked. */
+    isOnlyMatch?(selector: string): boolean;
+    /** What else identifies the node, beyond its path. */
+    context?(): Partial<IterationElement>;
 }
 /**
- * Best-effort descriptor of a picked element for locating it in code. Walks
- * up the tree collecting `#id` (preferred) or `tag:nth-child(n)` segments up
- * to a shallow depth, stopping at `BODY` or the depth cap. Kept framework-free
- * so it is unit-testable.
+ * Descriptor of a picked element for locating it in code. Walks up the tree
+ * collecting `#id` (preferred) or `tag:nth-child(n)` segments. The panel finds
+ * pins again with `querySelector`, which takes the first match, so with a real
+ * DOM the walk goes on past `maxDepth` until the path matches this element
+ * alone. Kept framework-free so it is unit-testable.
  */
 declare function describeIterationElement(el: NodeLike, maxDepth?: number): IterationElement;
 declare function elementAsNode(el: Element): NodeLike;
@@ -451,4 +576,4 @@ declare function createIterationStore(cfg?: IterationStoreConfig): {
     readonly hasUnsyncedNotes: boolean;
 };
 
-export { type ColorSwatch, type ColorVariantAxis, type IterationElement, type IterationNote, type IterationStoreConfig, KNOBS_STORAGE_KEY, type KnobAxis, type LiveVariantSelection, type NodeLike, type NoteContext, OVERLAY_DEFAULT_OPTION, OVERLAY_GROUP_ID, type OverlayGroup, type OverlayVariant, type OverlayVariantStatus, type OverlayVariantsList, type RangeVariantAxis, type RouteGateOptions, type SaveLocation, type SelectVariantAxis, VARIANTS_ENDPOINT, type VariantAction, type VariantAxis, type VariantAxisCondition, type VariantOption, type VariantReference, type VariantRemoval, type VariantSelections, type VariantsSource, applyKnobValues, axisDefault, createIterationStore, createOverlayVariantsSource, createVariantsSource, defaultSelections, describeIterationElement, elementAsNode, formatRangeValue, isAxisVisible, isDirty, isRouteVisible, isValidSelection, knobCssValue, knobDelta, knobVar, knobsFor, overlayAxes, overlayGroups, parseVariantParam, serializeVariantParam, variantAppliesTo, visibleAxes };
+export { type ColorSwatch, type ColorVariantAxis, type IterationElement, type IterationNote, type IterationStoreConfig, KNOBS_EVENT, KNOBS_STORAGE_KEY, type KnobAxis, type LiveVariantSelection, type NodeLike, type NoteContext, type NoteReply, OVERLAY_DEFAULT_OPTION, OVERLAY_GROUP_ID, type OverlayGroup, type OverlayVariant, type OverlayVariantStatus, type OverlayVariantsList, type RangeVariantAxis, type RouteGateOptions, SECTION_SEPARATOR, type SaveLocation, type SectionedLabel, type SelectVariantAxis, type UpdateInfo, type UpdateRequest, VARIANTS_ENDPOINT, type VariantAction, type VariantAxis, type VariantAxisCondition, type VariantOption, type VariantReference, type VariantRemoval, type VariantSection, type VariantSelections, type VariantsSource, applyKnobValues, axisDefault, axisSection, createIterationStore, createOverlayVariantsSource, createVariantsSource, defaultSelections, describeIterationElement, elementAsNode, formatRangeValue, isAxisVisible, isDirty, isRouteVisible, isValidSelection, knobCssValue, knobDelta, knobVar, knobsFor, overlayAxes, overlayGroups, parseVariantParam, sectionAxes, serializeVariantParam, splitSectionLabel, variantAppliesTo, visibleAxes };

package/dist/core.js

@@ -3,14 +3,17 @@ import {
   describeIterationElement,
   elementAsNode,
   isRouteVisible
-} from "./chunk-FKEKBZ3E.js";
+} from "./chunk-2FY2JNPG.js";
 import {
+  KNOBS_EVENT,
   KNOBS_STORAGE_KEY,
   OVERLAY_DEFAULT_OPTION,
   OVERLAY_GROUP_ID,
+  SECTION_SEPARATOR,
   VARIANTS_ENDPOINT,
   applyKnobValues,
   axisDefault,
+  axisSection,
   createOverlayVariantsSource,
   createVariantsSource,
   defaultSelections,
@@ -25,18 +28,22 @@ import {
   overlayAxes,
   overlayGroups,
   parseVariantParam,
+  sectionAxes,
   serializeVariantParam,
+  splitSectionLabel,
   variantAppliesTo,
   visibleAxes
-} from "./chunk-PUXQGUMQ.js";
-import "./chunk-A4DX2V4C.js";
+} from "./chunk-BTJHQXF7.js";
 export {
+  KNOBS_EVENT,
   KNOBS_STORAGE_KEY,
   OVERLAY_DEFAULT_OPTION,
   OVERLAY_GROUP_ID,
+  SECTION_SEPARATOR,
   VARIANTS_ENDPOINT,
   applyKnobValues,
   axisDefault,
+  axisSection,
   createIterationStore,
   createOverlayVariantsSource,
   createVariantsSource,
@@ -55,7 +62,9 @@ export {
   overlayAxes,
   overlayGroups,
   parseVariantParam,
+  sectionAxes,
   serializeVariantParam,
+  splitSectionLabel,
   variantAppliesTo,
   visibleAxes
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { I as IterationShortcut } from './IterationPanel-phJRYtUO.js';
-export { a as IterationPanel, b as IterationPanelProps } from './IterationPanel-phJRYtUO.js';
+import { I as IterationShortcut } from './IterationPanel-Bq77d5NT.js';
+export { a as IterationPanel, b as IterationPanelProps } from './IterationPanel-Bq77d5NT.js';
 import { VariantsSource, RouteGateOptions, VariantReference, VariantAction } from './core.js';
-export { ColorSwatch, ColorVariantAxis, IterationElement, IterationNote, IterationStoreConfig, KNOBS_STORAGE_KEY, KnobAxis, NodeLike, NoteContext, OVERLAY_DEFAULT_OPTION, OVERLAY_GROUP_ID, OverlayGroup, OverlayVariant, OverlayVariantStatus, OverlayVariantsList, RangeVariantAxis, SelectVariantAxis, VARIANTS_ENDPOINT, VariantAxis, VariantAxisCondition, VariantOption, VariantRemoval, VariantSelections, applyKnobValues, axisDefault, createOverlayVariantsSource, createVariantsSource, defaultSelections, describeIterationElement, elementAsNode, formatRangeValue, isAxisVisible, isDirty, isRouteVisible, isValidSelection, knobCssValue, knobDelta, knobVar, knobsFor, overlayAxes, overlayGroups, parseVariantParam, serializeVariantParam, visibleAxes } from './core.js';
+export { ColorSwatch, ColorVariantAxis, IterationElement, IterationNote, IterationStoreConfig, KNOBS_STORAGE_KEY, KnobAxis, NodeLike, NoteContext, NoteReply, OVERLAY_DEFAULT_OPTION, OVERLAY_GROUP_ID, OverlayGroup, OverlayVariant, OverlayVariantStatus, OverlayVariantsList, RangeVariantAxis, SECTION_SEPARATOR, SectionedLabel, SelectVariantAxis, UpdateRequest, VARIANTS_ENDPOINT, VariantAxis, VariantAxisCondition, VariantOption, VariantRemoval, VariantSection, VariantSelections, applyKnobValues, axisDefault, axisSection, createOverlayVariantsSource, createVariantsSource, defaultSelections, describeIterationElement, elementAsNode, formatRangeValue, isAxisVisible, isDirty, isRouteVisible, isValidSelection, knobCssValue, knobDelta, knobVar, knobsFor, overlayAxes, overlayGroups, parseVariantParam, sectionAxes, serializeVariantParam, splitSectionLabel, visibleAxes } from './core.js';
 import { I as IterationTheme } from './theme-BWv_ZNhC.js';
 import * as react from 'react';
 
@@ -19,9 +19,14 @@ interface MountIterationOptions {
     /**
      * Variants for the panel. A `VariantsSource` is rendered as-is; `'overlay'`
      * builds the overlay adapter against the Vite plugin's same-origin
-     * endpoint. With neither this nor `endpoint`, nothing mounts.
+     * endpoint. `'knobs'` is the same adapter for a server that has knobs but no
+     * file variants (`isotone serve`), and its empty list says so. With neither
+     * this nor `endpoint`, nothing mounts.
      */
-    variants?: VariantsSource | 'overlay';
+    variants?: VariantsSource | 'overlay' | 'knobs';
+    /** Where `'overlay'` reads variants and knobs. Defaults to the Vite plugin's
+     *  same-origin endpoint; `isotone serve` passes its own absolute URL. */
+    variantsEndpoint?: string;
     /** Which tab a tabbed panel opens on until the reviewer picks one. */
     defaultTab?: 'variants' | 'notes';
     /** Optional localStorage namespace for multi-app origins. */
@@ -34,31 +39,9 @@ interface MountIterationOptions {
      *  IterationPanelProps.getPayload. */
     getPayload?: () => unknown;
 }
-/**
- * Self-mount the Iteration panel into a shadow root on `document.body`,
- * outside any app tree, tracking `window.location.pathname` so it needs no
- * router integration.
- *
- * The shadow root is what makes this safe to drop into an app nobody vetted:
- * the host's resets, its `button` and `textarea` rules, its stacking and its
- * global handlers stop at the boundary, so the panel looks the same in every
- * app. Inherited properties and custom properties still cross, which is
- * deliberate — the panel reads `--font-sans` and `--foreground` from the host
- * so it matches the surrounding theme.
- *
- * The host element carries `data-isotone`, and that is load-bearing:
- * `document.elementFromPoint` retargets to the host for anything inside a
- * shadow root, so the element picker's self-exclusion matches on it.
- *
- * The host is created at runtime by `mountIteration` (never part of any HTML
- * React hydrates) and is watched by a MutationObserver: if a whole-document
- * render — a React Router hydration failure made worse by an extension, for
- * instance — replaces `<body>` and drops the host, it is re-appended to the
- * new body, shadow root and all, instead of a fresh mount losing panel state.
- */
 declare function mountIteration(opts: MountIterationOptions): () => void;
 
-declare function VariantsView({ source, showTitle, active, onFeedback, onClose, onSaved, onManage, pendingActions, }: {
+declare function VariantsView({ source, showTitle, active, onFeedback, onClose, onSaved, onManage, pendingActions, emptyText, }: {
     source: VariantsSource;
     showTitle?: boolean;
     active?: boolean;
@@ -67,6 +50,8 @@ declare function VariantsView({ source, showTitle, active, onFeedback, onClose,
     onSaved?: () => void;
     onManage?: (action: VariantAction, reference: VariantReference) => Promise<void>;
     pendingActions?: VariantAction[];
+    /** What the list says when this page has no selectors. */
+    emptyText?: string;
 }): react.JSX.Element;
 
 declare const PANEL_CSS: string;