@takazudo/zdtp 0.4.13 → 0.4.15

package/dist/picker/alt-click-picker.d.ts

@@ -11,7 +11,7 @@
  *   - keyup/window-blur disarm the picker.
  *   - a fixed-position box + label track the hovered element with RAF.
  */
-import type { JSX } from 'preact';
+import type { Ref } from 'preact';
 export interface AltClickPickerClassNames {
     /** Highlight box class. */
     box: string;
@@ -48,4 +48,12 @@ export interface AltClickPickerProps {
     /** Gap between the element box and its label tag. */
     labelGap?: number;
 }
-export declare function AltClickPicker({ enabled, featureId, onElementPicked, onArmingRevoked, claimArmingOnEnable, getLabelText, ariaLiveMessage, excludeSelector, classNames, zIndex, labelGap, }: AltClickPickerProps): JSX.Element;
+export interface AltClickPickerHandle {
+    /** Arm this picker without synthesizing an Alt keyboard gesture. */
+    arm(): void;
+    /** Disarm this picker and release coordinator ownership. */
+    disarm(): void;
+}
+export declare const AltClickPicker: import("preact").FunctionalComponent<import("react-dom/src").PropsWithoutRef<AltClickPickerProps> & {
+    ref?: Ref<AltClickPickerHandle> | undefined;
+}>;

package/dist/picker/arming-coordinator.d.ts

@@ -9,6 +9,8 @@ export interface ArmingOwner {
     /** Called when another feature takes over the Alt gesture. */
     onArmingRevoked: () => void;
 }
+/** Stable coordinator id reserved for the element-inspect picker. */
+export declare const ELEMENT_INSPECT_PICKER_FEATURE_ID = "element-inspect";
 export declare function registerArmingOwner(featureId: string, owner: ArmingOwner): () => void;
 export declare function requestArming(featureId: string): void;
 export declare function releaseArming(featureId: string): void;

package/dist/picker/index.d.ts

@@ -1,4 +1,4 @@
 export { AltClickPicker } from './alt-click-picker';
-export type { AltClickPickerClassNames, AltClickPickerProps, } from './alt-click-picker';
-export { registerArmingOwner, requestArming, releaseArming, } from './arming-coordinator';
+export type { AltClickPickerClassNames, AltClickPickerHandle, AltClickPickerProps, } from './alt-click-picker';
+export { ELEMENT_INSPECT_PICKER_FEATURE_ID, registerArmingOwner, requestArming, releaseArming, } from './arming-coordinator';
 export type { ArmingOwner } from './arming-coordinator';

package/dist/search/command-palette.d.ts

@@ -0,0 +1,21 @@
+import type { PanelConfig } from '../config/panel-config';
+import type { TweakState } from '../state/tweak-state';
+import type { TokenAddress } from '../utils/token-index';
+export interface CommandPaletteAction {
+    id: string;
+    label: string;
+    onSelect: () => void;
+    disabled?: boolean;
+    disabledReason?: string;
+}
+export interface CommandPaletteProps {
+    open: boolean;
+    onOpen: () => void;
+    onClose: () => void;
+    config: PanelConfig;
+    state?: TweakState | null;
+    actions: readonly CommandPaletteAction[];
+    onSelectToken: (address: TokenAddress) => void;
+}
+/** In-shell command palette with dismiss-layer Escape arbitration. */
+export declare function CommandPalette({ open, onOpen, onClose, config, state, actions, onSelectToken, }: CommandPaletteProps): import("preact").JSX.Element | null;

package/dist/search/contribution.d.ts

@@ -0,0 +1,7 @@
+import type { RowContribution } from '../tabs/flat/types';
+/**
+ * S3 contribution used by every flat token tab. FlatTab still owns rendering
+ * and section omission; this contribution only supplies the query predicate.
+ */
+export declare function tokenSearchContribution(query: string): RowContribution;
+export declare const createTokenSearchContribution: typeof tokenSearchContribution;

package/dist/search/fuzzy.d.ts

@@ -0,0 +1,10 @@
+/** Small dependency-free fuzzy matcher used by the command palette. */
+/**
+ * Return true when every character in `query` occurs in `value` in order.
+ * Matching is case-insensitive and intentionally does not score or reorder
+ * results; the manifest's declaration order remains the stable ordering.
+ */
+export declare function fuzzySubsequence(query: string, value: string): boolean;
+/** Friendly aliases for callers that describe this operation as a match. */
+export declare const fuzzyMatch: typeof fuzzySubsequence;
+export declare const isSubsequence: typeof fuzzySubsequence;

package/dist/search/index.d.ts

@@ -0,0 +1,4 @@
+export { fuzzyMatch, fuzzySubsequence, isSubsequence } from './fuzzy';
+export { createTokenSearchContribution, tokenSearchContribution } from './contribution';
+export { buildSearchTokens, filterTokenEntries, filterTokenIndex, fuzzyFilterTokens, matchesSearchFields, matchesTokenEntry, searchFieldsForEntry, stringifySearchValue, } from './token-search';
+export type { SearchToken, TokenSearchFields } from './token-search';

package/dist/search/match-bar.d.ts

@@ -0,0 +1,14 @@
+import type { TabConfig } from '../tokens/tier-model';
+export interface SearchTabCount {
+    tab: TabConfig;
+    matches: number;
+    total: number;
+}
+export interface SearchMatchBarProps {
+    query: string;
+    activeTabId: string;
+    counts: readonly SearchTabCount[];
+    onSelectTab: (tabId: string) => void;
+}
+/** The compact cross-tab result summary below the tab strip. */
+export declare function SearchMatchBar({ query, activeTabId, counts, onSelectTab, }: SearchMatchBarProps): import("preact").JSX.Element;

package/dist/search/search-header.d.ts

@@ -0,0 +1,7 @@
+export interface SearchHeaderProps {
+    query: string;
+    onQueryChange: (query: string) => void;
+    onOpenPalette: () => void;
+}
+/** Header-region search control. The compact affordance opens the palette. */
+export declare function SearchHeader({ query, onQueryChange, onOpenPalette }: SearchHeaderProps): import("preact").JSX.Element;

package/dist/search/token-search.d.ts

@@ -0,0 +1,36 @@
+import type { TweakState } from '../state/tweak-state';
+import { type TokenAddress, type TokenIndex, type TokenIndexEntry } from '../utils/token-index';
+import type { PanelConfig } from '../config/panel-config';
+/** The fields intentionally mirror the header-filter contract. */
+export interface TokenSearchFields {
+    cssVar: string;
+    id: string;
+    label: string;
+    value: string;
+    tierLabel: string;
+}
+/** A command-palette token carries its stable S2 address and display fields. */
+export interface SearchToken {
+    kind: 'token';
+    address: TokenAddress;
+    tabLabel: string;
+    tierLabel: string;
+    cssVar: string;
+    label: string;
+    value: string;
+    source: TokenIndexEntry['source'];
+}
+/** Normalize values from the S2 SemanticValue union for matching/display. */
+export declare function stringifySearchValue(value: unknown): string;
+/** Build the five searchable fields for one indexed token. */
+export declare function searchFieldsForEntry(entry: TokenIndexEntry, state?: TweakState, cfg?: PanelConfig): TokenSearchFields;
+/** Case-insensitive substring search used by the header filter. */
+export declare function matchesSearchFields(fields: TokenSearchFields, query: string): boolean;
+export declare function matchesTokenEntry(entry: TokenIndexEntry, query: string, state?: TweakState, cfg?: PanelConfig): boolean;
+/** Filter an S2 index while preserving manifest order. */
+export declare function filterTokenIndex(index: TokenIndex, query: string, state?: TweakState, cfg?: PanelConfig): TokenIndexEntry[];
+export declare const filterTokenEntries: typeof filterTokenIndex;
+/** Build command-palette token rows from the current registered manifest. */
+export declare function buildSearchTokens(cfg: PanelConfig, state?: TweakState): SearchToken[];
+/** Fuzzy-filter command-palette token rows over address + labels + value. */
+export declare function fuzzyFilterTokens(tokens: readonly SearchToken[], query: string): SearchToken[];

package/dist/server/create-apply-handler.d.ts

@@ -1,3 +1,4 @@
+import { type ApplyHunk } from '../apply/compute-hunks';
 import type { ApplyRoutingMap } from '../config/panel-config';
 export interface ApplyHandlerOptions {
     /**
@@ -29,6 +30,38 @@ export interface PerFileResult {
      */
     unknownOutsideBlock: string[];
 }
+export interface ApplyRequestBody {
+    tokens: Record<string, string>;
+    dryRun?: true;
+    /** Digests returned by a preceding dry run, keyed by response `file`. */
+    expectDigests?: Record<string, string>;
+}
+export interface ApplyDryRunFileResult extends PerFileResult {
+    blockKind: 'root' | 'theme';
+    /** SHA-256 of the exact on-disk bytes used to compute this preview. */
+    digest: string;
+    hunks: ApplyHunk[];
+}
+export interface ApplyDryRunResponse {
+    ok: true;
+    dryRun: true;
+    files: ApplyDryRunFileResult[];
+    rejected: string[];
+    rejectedReasons: string[];
+}
+export interface ApplyWriteResponse {
+    ok: true;
+    updated: PerFileResult[];
+    unknownCssVars: string[];
+    unchangedCssVars: string[];
+    unknownOutsideBlockCssVars: string[];
+}
+export interface ApplyStaleFileResponse {
+    ok: false;
+    reason: 'stale-file';
+    files: string[];
+}
+export type ApplySuccessResponse = ApplyDryRunResponse | ApplyWriteResponse;
 /**
  * Create a framework-agnostic Fetch API handler for the design-token apply
  * endpoint.

package/dist/server/index.d.ts

@@ -17,7 +17,8 @@
  * ```
  */
 export { createApplyHandler } from './create-apply-handler';
-export type { ApplyHandlerOptions, PerFileResult } from './create-apply-handler';
+export type { ApplyDryRunFileResult, ApplyDryRunResponse, ApplyHandlerOptions, ApplyRequestBody, ApplyStaleFileResponse, ApplySuccessResponse, ApplyWriteResponse, PerFileResult, } from './create-apply-handler';
 export { serializeFileWrite } from './serialize-write';
+export type { ApplyHunk } from '../apply/compute-hunks';
 export { CSS_VAR_NAME_RE, isPathSafe, isValidCssVarName, validateAndSanitizeTokens, } from './path-safety';
 export { loadRoutingFromFile, type ApplyRoutingMap } from './load-routing';

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { C as s, c as i, i as l, a as r, l as t, s as o, v as d } from "../load-routing-D4H2VOl5.js";
+import { C as s, c as i, i as l, a as r, l as t, s as o, v as d } from "../load-routing-BtCE1hGI.js";
 export {
   s as CSS_VAR_NAME_RE,
   i as createApplyHandler,

package/dist/shell/dock-mode-switch.d.ts

@@ -0,0 +1,6 @@
+import type { DockMode } from '../state/tweak-state';
+export declare function DockModeSwitch({ value, onChange, compact, }: {
+    value: DockMode;
+    onChange: (mode: DockMode) => void;
+    compact?: boolean;
+}): import("preact").JSX.Element;

package/dist/shell/footer.d.ts

@@ -0,0 +1 @@
+export declare function ShellFooter(): import("preact").JSX.Element | null;

package/dist/shell/ghost-idle.d.ts

@@ -0,0 +1,24 @@
+import type { RefObject } from 'preact';
+/** Time the pointer must stay outside the shell before it becomes translucent. */
+export declare const GHOST_IDLE_DELAY_MS = 700;
+/** Class applied to a shell that is currently ghosted. */
+export declare const GHOST_IDLE_CLASS = "is-ghosted";
+/** The opacity used by the panel CSS while the shell is ghosted. */
+export declare const GHOST_IDLE_OPACITY = 0.35;
+/** Per-panel persisted preference key. */
+export declare function storageKey_ghostIdle(storagePrefix: string): string;
+/** Read the persisted ghost-when-idle preference, defaulting to off. */
+export declare function loadGhostIdle(storagePrefix: string): boolean;
+/** Persist the ghost-when-idle preference without making storage mandatory. */
+export declare function saveGhostIdle(storagePrefix: string, enabled: boolean): void;
+/**
+ * Install ghost-when-idle behavior on a shell element.
+ *
+ * The shell is deliberately observed from the document as well as with
+ * pointerenter/leave listeners. A pointer can enter the host page before it
+ * ever enters the fixed panel, so a document-level pointermove is needed to
+ * start the idle timer reliably. Focus-within and layer activity always win:
+ * an open popover/modal must never become translucent underneath the user's
+ * keyboard focus.
+ */
+export declare function useGhostIdle<T extends HTMLElement>(targetRef: RefObject<T>, enabled: boolean, layerActive: boolean, delayMs?: number): void;

package/dist/shell/header.d.ts

@@ -0,0 +1,5 @@
+import { type JSX } from 'preact';
+export declare function ShellHeader({ width, onMouseDown, }: {
+    width: number;
+    onMouseDown: JSX.MouseEventHandler<HTMLDivElement>;
+}): JSX.Element;

package/dist/shell/layer-activity.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentChildren } from 'preact';
+export declare function LayerActivityProvider({ children }: {
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+export declare function useLayerActivity(): boolean;
+export declare function useLayerRegistration(id: string, active: boolean): void;

package/dist/shell/mini-pill.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentChildren, JSX, RefObject } from 'preact';
+/** Slots intentionally stay small so changed-state and history features can
+ * add their own controls without making the dock-mode shell depend on them. */
+export interface MiniPillProps {
+    rootRef?: RefObject<HTMLDivElement>;
+    onApply: () => void;
+    applyDisabled?: boolean;
+    applyDisabledReason?: string;
+    onExpand: () => void;
+    changedCount?: number | undefined;
+    undo?: ComponentChildren;
+}
+/**
+ * Compact replacement for the full panel shell in `dockMode === 'mini'`.
+ *
+ * The changed-count and undo regions are extension slots for later panel
+ * features. Keeping the wrappers in this component gives those features a
+ * stable place to contribute while the mini dock mode itself remains usable
+ * on the foundation branch.
+ */
+export declare function MiniPill({ rootRef, onApply, applyDisabled, applyDisabledReason, onExpand, changedCount, undo, }: MiniPillProps): JSX.Element;

package/dist/shell/regions.d.ts

@@ -0,0 +1,26 @@
+import type { ComponentChildren } from 'preact';
+import type { ActionsMenuAction } from '../controls/actions-menu-popover';
+export type ShellRegion = 'header-actions' | 'header-right' | 'tabbar-extras' | 'footer';
+export interface ShellRegionRenderContext {
+    compact: boolean;
+    closeCompactMenu: () => void;
+}
+export interface ShellRegionItem {
+    id: string;
+    order?: number;
+    render: (context: ShellRegionRenderContext) => ComponentChildren;
+    compactAction?: ActionsMenuAction;
+    renderInCompactMenu?: boolean;
+}
+type RegionItems = Record<ShellRegion, readonly ShellRegionItem[]>;
+interface ShellRegionsValue {
+    items: RegionItems;
+    registerRegionItem: (region: ShellRegion, item: ShellRegionItem) => () => void;
+}
+export declare function ShellRegionsProvider({ initialItems, children, }: {
+    initialItems?: Partial<RegionItems>;
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+export declare function useShellRegions(): ShellRegionsValue;
+export declare function useRegisterRegionItem(region: ShellRegion, item: ShellRegionItem): void;
+export {};

package/dist/shell/shortcut-dispatcher.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentChildren, RefObject } from 'preact';
+export interface ShortcutBinding {
+    key: string | readonly string[];
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+    when?: (event: KeyboardEvent) => boolean;
+}
+type ShortcutHandler = (event: KeyboardEvent) => void;
+export declare function ShortcutProvider({ shellRef, enabled, children, }: {
+    shellRef: RefObject<HTMLDivElement>;
+    enabled: boolean;
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+export declare function useShortcut(binding: ShortcutBinding, handler: ShortcutHandler, enabled?: boolean): void;
+export {};

package/dist/shell/tab-bar.d.ts

@@ -0,0 +1,17 @@
+import { type RefObject } from 'preact';
+import type { PanelDensity } from '../state/tweak-state';
+export interface ShellTab {
+    id: string;
+    label: string;
+}
+export declare function ShellTabBar({ tabs, activeTab, onActiveTabChange, ariaIdScope, tabRefs, density, onDensityChange, open, changedCounts, }: {
+    tabs: readonly ShellTab[];
+    activeTab: string;
+    onActiveTabChange: (id: string) => void;
+    ariaIdScope: string;
+    tabRefs: RefObject<Record<string, HTMLDivElement | null>>;
+    density: PanelDensity;
+    onDensityChange: (density: PanelDensity) => void;
+    open: boolean;
+    changedCounts?: Readonly<Record<string, number>>;
+}): import("preact").JSX.Element;

package/dist/shell/tab-overflow-popover.d.ts

@@ -0,0 +1,13 @@
+import type { JSX } from 'preact';
+import type { ShellTab } from './tab-bar';
+interface TabOverflowPopoverProps {
+    tabs: readonly ShellTab[];
+    activeTab: string;
+    anchorRef: React.RefObject<HTMLDivElement>;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSelect: (id: string) => void;
+    ariaIdScope: string;
+}
+export declare function TabOverflowPopover(props: TabOverflowPopoverProps): JSX.Element;
+export {};

package/dist/specimen/on-page-specimen.d.ts

@@ -0,0 +1,19 @@
+import type { PanelConfig } from '../config/panel-config';
+import type { TabConfig, TierItem } from '../tokens/tier-model';
+import type { SpecimenState } from './specimen-state';
+/** The host-mutation owner suffix for a panel's page-level specimen node. */
+export declare function onPageSpecimenMutationOwner(cfg: PanelConfig): string;
+interface OnPageSpecimenProps {
+    enabled: boolean;
+    tab: TabConfig;
+    state: SpecimenState;
+    valueFor: (item: TierItem) => string;
+    instanceConfig: PanelConfig;
+}
+/**
+ * Render the read-only font specimen into the host document while enabled.
+ * The mount itself is registry-owned, so destroy/Astro cleanup can remove it
+ * even when the Preact tree no longer has a live root to run effect cleanup.
+ */
+export default function OnPageSpecimen(props: OnPageSpecimenProps): import("preact").VNode<any> | null;
+export {};

package/dist/specimen/preview-glyphs.d.ts

@@ -0,0 +1,2 @@
+import type { RowContribution } from '../tabs/flat/types';
+export declare function previewGlyphContribution(): RowContribution;

package/dist/specimen/specimen-state.d.ts

@@ -0,0 +1,12 @@
+import type { PanelConfig } from '../config/panel-config';
+export type SpecimenPreset = 'latin' | 'ja' | 'mixed';
+export interface SpecimenState {
+    text: string;
+    preset: SpecimenPreset;
+    overridden: boolean;
+    width: number;
+}
+export declare const SPECIMEN_PRESETS: Readonly<Record<SpecimenPreset, string>>;
+export declare const DEFAULT_SPECIMEN_STATE: SpecimenState;
+export declare function loadSpecimenState(cfg: PanelConfig): SpecimenState;
+export declare function saveSpecimenState(cfg: PanelConfig, state: SpecimenState): void;

package/dist/specimen/specimen-tab-body.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentChildren } from 'preact';
+import type { CSSProperties } from 'preact/compat';
+import type { TabConfig, TierConfig, TierItem } from '../tokens/tier-model';
+import type { SharedRowRenderer } from '../tabs/flat/tier-section';
+import type { RowContribution } from '../tabs/flat/types';
+import type { SpecimenState } from './specimen-state';
+interface SpecimenRendererOptions {
+    tab: TabConfig;
+    state: SpecimenState;
+    valueFor: (item: TierItem) => string;
+    /** Hide the rendered sample while keeping the editable row controls. */
+    onPage?: boolean;
+}
+/** Resolve the font family/weight applied to every type specimen sample. */
+export declare function specimenFontStyle(tab: TabConfig, valueFor: (item: TierItem) => string): CSSProperties;
+export declare function createSpecimenContribution({ tab, state, valueFor, onPage }: SpecimenRendererOptions): RowContribution;
+export declare function renderSpecimenTierBody(tier: TierConfig, renderRow: SharedRowRenderer, options: SpecimenRendererOptions): ComponentChildren;
+export {};

package/dist/specimen/specimen-toolbar.d.ts

@@ -0,0 +1,10 @@
+import type { SpecimenState } from './specimen-state';
+interface SpecimenToolbarProps {
+    state: SpecimenState;
+    showWidth: boolean;
+    onChange: (next: SpecimenState) => void;
+    renderOnPage?: boolean;
+    onRenderOnPageChange?: (enabled: boolean) => void;
+}
+export default function SpecimenToolbar({ state, showWidth, onChange, renderOnPage, onRenderOnPageChange, }: SpecimenToolbarProps): import("preact").JSX.Element;
+export {};

package/dist/specimen/specimen-values.d.ts

@@ -0,0 +1,9 @@
+import type { TabConfig, TierConfig, TierItem } from '../tokens/tier-model';
+export interface ResolvedPreviewLength {
+    value: string;
+    px: number | null;
+}
+export declare function lengthToPx(value: string): number | null;
+export declare function resolvePreviewValue(tab: TabConfig, tier: TierConfig, item: TierItem, valueFor: (item: TierItem) => string): string;
+export declare function resolvePreviewLength(tab: TabConfig, tier: TierConfig, item: TierItem, valueFor: (item: TierItem) => string): ResolvedPreviewLength;
+export declare function findLineHeightBasePx(tab: TabConfig, tier: TierConfig, valueFor: (item: TierItem) => string): number;

package/dist/state/history.d.ts

@@ -0,0 +1,64 @@
+import type { TweakState } from './tweak-state';
+export declare const HISTORY_LIMIT = 100;
+export declare const HISTORY_COALESCE_MS = 500;
+export interface TweakHistoryEntry {
+    reason: string;
+    address?: string;
+    identity: string;
+    before: TweakState;
+    after: TweakState;
+    timestamp: number;
+}
+export interface HistoryRestoreResult {
+    entry: TweakHistoryEntry | null;
+    skippedReason?: string;
+}
+export interface TweakHistorySnapshot {
+    entries: readonly TweakHistoryEntry[];
+    cursor: number;
+    canUndo: boolean;
+    canRedo: boolean;
+    lastSkippedReason: string | null;
+}
+type Restore = (state: TweakState) => void;
+/** In-memory, identity-aware history for one mounted panel instance. */
+export declare class TweakHistory {
+    private items;
+    private cursor;
+    private restore;
+    private getCurrentState;
+    private getIdentity;
+    private listeners;
+    private lastSkippedReason;
+    configure(options: {
+        restore: Restore;
+        getCurrentState: () => TweakState | null;
+        getIdentity: () => string;
+    }): void;
+    getSnapshot(): TweakHistorySnapshot;
+    subscribe(listener: () => void): () => void;
+    clear(): void;
+    record(entry: TweakHistoryEntry, options?: {
+        reset?: boolean;
+        force?: boolean;
+    }): void;
+    undo(): HistoryRestoreResult;
+    redo(): HistoryRestoreResult;
+    /** Restore the state after entry `index`; `-1` means the pre-history state. */
+    jumpTo(index: number): HistoryRestoreResult;
+    private restoreEntry;
+    private emit;
+}
+export declare function createTweakHistory(): TweakHistory;
+/** Reactive facade consumed by the later history UI. */
+export declare function useHistory(history: TweakHistory): {
+    undo: () => HistoryRestoreResult;
+    redo: () => HistoryRestoreResult;
+    jumpTo: (index: number) => HistoryRestoreResult;
+    entries: readonly TweakHistoryEntry[];
+    cursor: number;
+    canUndo: boolean;
+    canRedo: boolean;
+    lastSkippedReason: string | null;
+};
+export {};

package/dist/state/persist.d.ts

@@ -1,16 +1,15 @@
 /**
- * `usePersist` hook — orchestrates setState + DOM apply + localStorage write
- * for the design-token panel. Each callback is a persist pipeline:
+ * `usePersist` hook — adapts slice updaters to the panel's single state
+ * transaction path. Each callback is a persist pipeline:
  *
- *   updater  →  setState(updater)  →  applyFullState(next)  →  savePersistedState(next)
+ *   updater  →  commitTweakState('persist', updater)
  *
  * The slice-specific helpers (`persistColor`, `persistSpacing`, etc.) wrap a
  * slice updater into a full-state updater so callers don't have to thread the
  * whole envelope themselves.
  *
- * Framework-agnostic wrt. the setState function: pass any
- * `(updater) => void` that propagates `updater(prev)` to the caller's state.
- * In practice the panel passes Preact's `setState` from `useState`.
+ * The transaction owns apply/save/setState ordering and history recording;
+ * this hook only lifts legacy slice callbacks into whole-state updaters.
  *
  * `persistColor`'s updater is `(prev: ColorTweakState) => ColorTweakState`, so
  * the widened `ColorTweakState.semanticMappings: Record<string, SemanticValue>`
@@ -21,18 +20,15 @@
  */
 import { type ColorTweakState, type TabOverrides, type TokenOverrides, type TweakState } from './tweak-state';
 import type { PanelConfig } from '../config/panel-config';
-type SetState<T> = (updater: (prev: T | null) => T | null) => void;
+import type { CommitTweakStateOptions, TweakStateUpdater } from './transaction';
+type CommitTweakState = (reason: string, updater: TweakStateUpdater, options?: CommitTweakStateOptions) => void;
 /**
  * `usePersist` hook.
  *
- * Accepts an optional `cfg` — the panel instance config. When supplied its
- * `applySink` (if any) routes every CSS-var write through the sink instead
- * of `document.documentElement`, AND its `storagePrefix` scopes the persisted
- * envelope to THIS instance's storage key (multi-instance, #357). Omitting
- * `cfg` resolves the default instance via `getPanelConfig()` inside both
- * `applyFullState` and `savePersistedState`, preserving the single-panel path.
+ * `cfg` remains accepted for API compatibility; instance scoping is owned by
+ * the supplied transaction.
  */
-export declare function usePersist(setState: SetState<TweakState>, cfg?: PanelConfig): {
+export declare function usePersist(commitTweakState: CommitTweakState, cfg?: PanelConfig): {
     persist: (updater: (prev: TweakState) => TweakState) => void;
     persistTab: (tabId: string, updater: (prev: TabOverrides) => TabOverrides) => void;
     persistColor: (updater: (prev: ColorTweakState) => ColorTweakState) => void;

package/dist/state/transaction.d.ts

@@ -0,0 +1,24 @@
+import type { PanelConfig } from '../config/panel-config';
+import { type TweakHistory } from './history';
+import { type TweakState } from './tweak-state';
+export type TweakStateUpdater = TweakState | ((previous: TweakState) => TweakState);
+type SetState = (updater: (previous: TweakState | null) => TweakState | null) => void;
+export interface CommitTweakStateOptions {
+    address?: string;
+    record?: boolean;
+    forceRecord?: boolean;
+    resetHistory?: boolean;
+    timestamp?: number;
+    beforeApply?: () => void;
+    apply?: false | ((next: TweakState) => void);
+    save?: false | ((next: TweakState) => void);
+}
+/**
+ * The sole state-mutation pipeline for a mounted panel. Side effects retain
+ * the established order: apply, persist, then publish component state.
+ */
+export declare function useTweakStateTransaction(state: TweakState | null, setState: SetState, cfg: PanelConfig): {
+    commitTweakState: (reason: string, next: TweakStateUpdater, opts?: CommitTweakStateOptions) => void;
+    history: TweakHistory;
+};
+export {};

package/dist/state/tweak-state.d.ts

@@ -90,6 +90,22 @@ export declare function getOpenKey(cfg?: PanelConfig): string;
 export declare function getPositionKey(cfg?: PanelConfig): string;
 export declare function getSizeKey(cfg?: PanelConfig): string;
 export declare function getDensityKey(cfg?: PanelConfig): string;
+export declare function getSnapshotKey(slot: 'a' | 'b', cfg?: PanelConfig): string;
+export declare function getSnapshotAKey(cfg?: PanelConfig): string;
+export declare function getSnapshotBKey(cfg?: PanelConfig): string;
+export type DockMode = 'float' | 'right' | 'bottom' | 'mini';
+export interface DockSize {
+    right: number;
+    bottom: number;
+}
+export declare const DEFAULT_DOCK_MODE: DockMode;
+export declare const DEFAULT_DOCK_SIZE: DockSize;
+export declare function getDockKey(cfg?: PanelConfig): string;
+export declare function getDockSizeKey(cfg?: PanelConfig): string;
+export declare function loadDockMode(cfg?: PanelConfig, storage?: StorageLike): DockMode;
+export declare function saveDockMode(mode: DockMode, cfg?: PanelConfig, storage?: StorageLike): void;
+export declare function loadDockSize(cfg?: PanelConfig, storage?: StorageLike): DockSize;
+export declare function saveDockSize(size: DockSize, cfg?: PanelConfig, storage?: StorageLike): void;
 export interface PanelPosition {
     top: number;
     left: number;

package/dist/styles/z-index-tokens.d.ts

@@ -28,6 +28,8 @@ export declare const Z: {
     readonly colorPicker: 2147482993;
     /** DOM tooltip portaled to document.body. */
     readonly tooltip: 2147482994;
+    /** Command palette overlay rendered inside the shell. */
+    readonly commandPalette: 2147482995;
     /** Element-path inspector box (body-mounted). */
     readonly inspectorBox: 2147483000;
     /** Element-path toast (body-mounted). */