isotone 1.1.3 → 1.2.1

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`
@@ -394,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 {
@@ -486,4 +576,4 @@ declare function createIterationStore(cfg?: IterationStoreConfig): {
     readonly hasUnsyncedNotes: boolean;
 };
 
-export { type ColorSwatch, type ColorVariantAxis, type IterationElement, type IterationNote, type IterationStoreConfig, KNOBS_EVENT, 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,15 +3,17 @@ import {
   describeIterationElement,
   elementAsNode,
   isRouteVisible
-} from "./chunk-K5RAC2BT.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,
@@ -26,19 +28,22 @@ import {
   overlayAxes,
   overlayGroups,
   parseVariantParam,
+  sectionAxes,
   serializeVariantParam,
+  splitSectionLabel,
   variantAppliesTo,
   visibleAxes
-} from "./chunk-RKZWO37H.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,
@@ -57,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;