nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/shell/InspectorPanel.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement, ReactNode } from "react";
+export interface InspectorPanelProps {
+    readonly isOpen: boolean;
+    readonly collapseDisabled?: boolean;
+    readonly toggleShortcut?: string;
+    readonly headerActions: ReactNode;
+    readonly prompt: ReactNode;
+    readonly children: ReactNode;
+    readonly onOpenChange: (open: boolean) => void;
+}
+/** Shared panel layout. The host supplies state, content, and commands. */
+export declare function InspectorPanel({ isOpen, collapseDisabled, toggleShortcut, headerActions, prompt, children, onOpenChange }: InspectorPanelProps): ReactElement;

package/dist/inspector/shell/InspectorPanel.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { IconLayoutSidebarRight } from "@tabler/icons-react";
+import { IconButton } from "../ui/IconButton.js";
+import { Tooltip } from "../ui/Tooltip.js";
+/** Shared panel layout. The host supplies state, content, and commands. */
+export function InspectorPanel({ isOpen, collapseDisabled, toggleShortcut, headerActions, prompt, children, onOpenChange }) {
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "panel", "data-open": isOpen ? "true" : "false", children: [_jsxs("div", { className: "panel__tabs", "aria-label": "Inspector controls", children: [_jsxs("div", { className: "panel__header-row", "data-test": "inspect-tab", children: [_jsx(Tooltip, { content: "Hide inspector", shortcut: toggleShortcut, stableTrigger: true, children: _jsx(IconButton, { variant: "quiet", label: "Collapse inspector", "data-test": "collapse-inspector", disabled: collapseDisabled, style: { marginLeft: "calc(var(--space-8) * -1)" }, onClick: () => onOpenChange(false), children: _jsx(IconLayoutSidebarRight, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) }) }), _jsx("div", { className: "panel__header-actions", children: headerActions })] }), _jsx("div", { className: "panel__copy-row", children: prompt })] }), _jsx("div", { className: "panel__body", children: children })] }), !isOpen ? (_jsx("div", { className: "panel__restore", children: _jsx(Tooltip, { children: _jsx(IconButton, { variant: "quiet", label: "Show inspector", className: "panel__restore-button", "data-test": "show-inspector", onClick: () => onOpenChange(true), children: _jsx(IconLayoutSidebarRight, { size: "var(--icon-size-small)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }) }) }) })) : null] }));
+}

package/dist/inspector/shell/InspectorSelection.d.ts

@@ -0,0 +1,24 @@
+import type { ReactElement, ReactNode } from "react";
+import type { InteractionState } from "./styleState.js";
+import type { ElementName } from "./elementName.js";
+export interface InspectorSelectionProps {
+    readonly identity?: {
+        readonly cid: string;
+        readonly src: string;
+    };
+    readonly count: number;
+    readonly name: ElementName | null;
+    /** The selection has editable component props, which links it like a shared source site does. */
+    readonly isComponent?: boolean;
+    /** Component props, shown between the name and the link status. */
+    readonly children?: ReactNode;
+    readonly editScope: "source-site" | "rendered-instance" | null;
+    readonly sourceSiteMatchCount: number;
+    readonly styleState: InteractionState;
+    readonly availableInteractionStates: readonly InteractionState[];
+    readonly onStyleStateChange: (state: InteractionState) => void;
+    readonly onRelink: () => void;
+    readonly onUnlink: () => void;
+}
+/** Presents selection scope and interaction states without reading the DOM. */
+export declare function InspectorSelection({ identity, count, name, isComponent, children, editScope, sourceSiteMatchCount, styleState, availableInteractionStates, onStyleStateChange, onRelink, onUnlink }: InspectorSelectionProps): ReactElement;

package/dist/inspector/shell/InspectorSelection.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { StatusCallout } from "../ui/StatusCallout.js";
+import { IconLink, IconSquareRotated, IconUnlink } from "@tabler/icons-react";
+import { IconButton } from "../ui/IconButton.js";
+import { FieldRow } from "../ui/FieldRow.js";
+import { Select } from "../ui/Select.js";
+import { formatInspectorLabel } from "../ui/labels.js";
+/** Presents selection scope and interaction states without reading the DOM. */
+export function InspectorSelection({ identity, count, name, isComponent = false, children, editScope, sourceSiteMatchCount, styleState, availableInteractionStates, onStyleStateChange, onRelink, onUnlink }) {
+    const showInteractionState = count === 1 && availableInteractionStates.length > 1;
+    const hasEditScopeCallout = count === 1 && (editScope === "rendered-instance" || sourceSiteMatchCount > 1);
+    return _jsx(_Fragment, { children: name || children || showInteractionState || hasEditScopeCallout ? (_jsxs("div", { className: `selection${hasEditScopeCallout ? "" : " selection--without-scope-callout"}`, "data-test": "selection", "data-selected-cid": identity?.cid, "data-selected-src": identity?.src, "data-selected-count": count, children: [name ? (_jsxs("div", { className: "editor__title-row selection__name", "data-test": "selection-name", children: [isComponent || (hasEditScopeCallout && editScope === "source-site") ? (_jsx(IconSquareRotated, { className: "selection__linked-icon", size: 14, stroke: 2, "aria-hidden": "true", "data-test": "selection-linked-icon" })) : null, _jsx("div", { className: "editor__title", children: name.title }), hasEditScopeCallout ? (_jsx(StatusCallout, { tone: editScope === "rendered-instance" ? "neutral" : "accent", className: "selection__scope", "data-test": "edit-scope", "data-lost": "false", children: editScope === "rendered-instance" ? (_jsxs("div", { className: "scope__unlinked", children: [_jsx("span", { children: "Unlinked" }), _jsx(IconButton, { variant: "quiet", label: "Relink element", className: "scope__action", "data-test": "relink-element", onClick: onRelink, children: _jsx(IconLink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] })) : (_jsxs("div", { className: "scope__linked", children: [_jsxs("span", { children: ["Linked (", sourceSiteMatchCount, ")"] }), _jsx(IconButton, { variant: "quiet", label: "Unlink element", "data-test": "unlink-element", onClick: onUnlink, children: _jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] })) })) : null] })) : null, children, showInteractionState ? (_jsx(FieldRow, { label: "State", className: "style-state", "data-test": "style-state", children: _jsx(Select, { value: styleState, "data-test": "style-state-select", "aria-label": "Style State", options: availableInteractionStates.map((state) => ({
+                            value: state,
+                            label: formatInspectorLabel(state),
+                        })), onValueChange: (state) => {
+                            const next = availableInteractionStates.find((candidate) => candidate === state);
+                            if (next)
+                                onStyleStateChange(next);
+                        } }) })) : null] })) : null });
+}

package/dist/inspector/shell/InspectorShell.js

@@ -1,37 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { InspectorPanel } from "./InspectorPanel.js";
+import { InspectorSelection } from "./InspectorSelection.js";
+import { describeElement } from "./elementName.js";
+import { InspectorEditors } from "./InspectorEditors.js";
 import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
-import { IconLayoutSidebarRight } from "@tabler/icons-react";
 import { useInspectorOpen, setInspectorOpen } from "./openStore.js";
 import { useSelectedElement, useSelectedElements, setSelectedElement, removeSelectedElement, } from "../selection/selectionStore.js";
 import { findTokenRow } from "../styleEditors/rowLookup.js";
 import { useBrowserCssInspection } from "../inspection/useBrowserCssInspection.js";
 import { resolveSelectionFromElement } from "../selection/resolveSelection.js";
 import { AgentStatusButton } from "./AgentStatusButton.js";
-import { SpacingBox } from "../styleEditors/SpacingBox.js";
-import { Typography } from "../styleEditors/Typography.js";
 import { isTextRelevant } from "../styleEditors/textRelevance.js";
-import { BackgroundEditor } from "../styleEditors/BackgroundEditor.js";
-import { ColorPicker } from "../styleEditors/ColorPicker.js";
-import { BorderEditor } from "../styleEditors/BorderEditor.js";
-import { AppearanceSection } from "../styleEditors/AppearanceSection.js";
-import { BoxShadowEditor } from "../styleEditors/BoxShadowEditor.js";
-import { LayoutSection } from "../styleEditors/LayoutSection.js";
 import { ChangesLog } from "./ChangesLog.js";
 import { discardChangesForInstanceOverride, undo, redo } from "../drafts/store.js";
 import { countSourceSiteMatches, getEditScope, relinkElement, sourceSiteSelector, unlinkElement } from "../selection/editScope.js";
 import { canEditStyles } from "../tokens/editActions.js";
-import { Button } from "../ui/Button.js";
 import { CopyPromptButton } from "./CopyPromptButton.js";
 import { PeekOriginalButton } from "./PeekOriginalButton.js";
+import { NudgeLogoIcon } from "./NudgeLogoIcon.js";
 import { StatusCallout } from "../ui/StatusCallout.js";
-import { IconButton } from "../ui/IconButton.js";
 import { UI_STYLES } from "../ui/styles.js";
 import { getActiveStyleState, setActiveStyleState } from "./styleState.js";
 import { useInteractionStatePreview } from "./interactionStatePreview.js";
 import { getInspectorToggleShortcutLabel, isEditableEvent } from "./shortcuts.js";
-import { formatInspectorLabel } from "../ui/labels.js";
-import { FieldRow } from "../ui/FieldRow.js";
-import { Select } from "../ui/Select.js";
 import { clearSelectedFrameChanges } from "../canvas/sessionStore.js";
 import { useFocusedCardId, useSelectedCardId, } from "../canvas/canvasStore.js";
 import { getActiveCanvasFrame } from "../canvas/activeCanvasDocument.js";
@@ -39,8 +30,7 @@ import { canvasFrameHost } from "../canvas/canvasFrame.js";
 import { getFrameRegistryVersion, subscribeFrameRegistry } from "../canvas/projection.js";
 import { getElementWindow } from "../runtime/domRealm.js";
 import { deleteElement, nudgeElement } from "../overlay/structuralGestures.js";
-import { AtRuleContextProvider } from "../ui/AtRuleContext.js";
-import { ComponentPropsSection } from "../componentSemantics/ComponentPropsSection.js";
+import { ComponentPropsSection, useComponentProps } from "../componentSemantics/ComponentPropsSection.js";
 import { cancelInlineTextEdit, isInlineTextEditingActive, useInlineTextDiagnostic, } from "../inline-text/inlineTextEditor.js";
 import { getInlineTextFeedback } from "../inline-text/inlineTextFeedback.js";
 import { useNudgeUiRuntimeConfig } from "../runtime/useRuntimeConfig.js";
@@ -51,7 +41,6 @@ import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { isDemoRuntime, isNudgeUiFeatureEnabled } from "../runtime/runtimeConfig.js";
 import { SketchWorkspace } from "../sketch/SketchWorkspace.js";
 import { useSketchInteractionActive } from "../sketch/interaction.js";
-import { Tooltip } from "../ui/Tooltip.js";
 import { InspectorStyle } from "../ui/InspectorStyle.js";
 function findFirstTokenRow(rows, properties) {
     for (const property of properties) {
@@ -101,6 +90,7 @@ export function InspectorShell() {
     const sketchHost = selectedCardId || focusedCardId ? canvasFrameHost(getActiveCanvasFrame()) : null;
     const selected = useSelectedElement();
     const selectedElements = useSelectedElements();
+    const componentProps = useComponentProps(selected);
     const inlineTextFeedback = getInlineTextFeedback(useInlineTextDiagnostic());
     const [settingsOpen, setSettingsOpen] = useState(false);
     const [settingsSection, setSettingsSection] = useState("instructions");
@@ -110,17 +100,14 @@ export function InspectorShell() {
     const cssInspection = useBrowserCssInspection(selectedElements, styleState);
     const isMultiSelection = selectedElements.length > 1;
     useEffect(() => {
-        // A new selection should never inherit an incidental state from the
-        // previous element. Base is the inspector's deliberate default.
+        // A new selection must not inherit an incidental state from the previous element; base is the deliberate default.
         setActiveStyleState("base");
         setStyleState("base");
     }, [selected?.domElement, isMultiSelection]);
     useEffect(() => {
         if (!selected)
             return;
-        // The selected element can live inside a card iframe (canvas mode); observe
-        // its own ownerDocument rather than the parent app's document, otherwise
-        // removal inside the iframe would never be noticed.
+        // In canvas mode the element can live in a card iframe, so observe its ownerDocument, not the parent app's.
         const observers = [];
         const roots = new Map();
         for (const target of selectedElements) {
@@ -184,8 +171,7 @@ export function InspectorShell() {
                 setSelectedElement(null);
                 return;
             }
-            // macOS labels the physical Backspace key as Delete, while browsers
-            // report it as "Backspace". Support both without stealing text edits.
+            // macOS labels the physical Backspace key as Delete; browsers report "Backspace". Support both.
             if (event.key === "Delete" || event.key === "Backspace") {
                 event.preventDefault();
                 if (!isMultiSelection && deleteElement(selected))
@@ -212,7 +198,6 @@ export function InspectorShell() {
     const tokenRows = useMemo(() => styleSelection ? [...styleSelection.primaryRows] : [], [styleSelection]);
     const availableInteractionStates = inspectionSnapshot?.availableStates ?? [];
     const showText = selectedElements.length > 0 && selectedElements.every((element, index) => isTextRelevant(element.domElement, cssInspection.elements[index]?.properties ?? []));
-    const showInteractionState = !isMultiSelection && availableInteractionStates.length > 1;
     const paintedBackgroundRow = findFirstTokenRow(tokenRows, ["background-color", "background"]);
     const backgroundTokenRow = useMemo(() => {
         if (!selected)
@@ -227,8 +212,6 @@ export function InspectorShell() {
     const sourceSiteMatchCount = selected && editScope === "source-site"
         ? countSourceSiteMatches(selected.domElement, scopeRevision)
         : 0;
-    const hasEditScopeCallout = !isMultiSelection
-        && (editScope === "rendered-instance" || sourceSiteMatchCount > 1);
     function refreshScopeState() {
         refreshScope((revision) => revision + 1);
     }
@@ -240,25 +223,20 @@ export function InspectorShell() {
         // Sketch persistence failures are reported by the sketch store in the panel.
         void clearSelectedFrameChanges().catch(() => undefined);
     }
-    return (_jsxs(_Fragment, { children: [_jsx(InspectorStyle, { testId: "inspector-styles", css: UI_STYLES }), _jsxs("div", { className: "panel", "data-open": isOpen ? "true" : "false", children: [_jsxs("div", { className: "panel__tabs", "aria-label": "Inspector controls", children: [_jsxs("div", { className: "panel__header-row", "data-test": "inspect-tab", children: [_jsx(Tooltip, { content: "Hide inspector", shortcut: getInspectorToggleShortcutLabel(), stableTrigger: true, children: _jsx(IconButton, { variant: "quiet", label: "Collapse inspector", "data-test": "collapse-inspector", disabled: sketchActive, style: { marginLeft: "calc(var(--space-8) * -1)" }, onClick: () => {
-                                                cancelInlineTextEdit();
-                                                setInspectorOpen(false);
-                                            }, children: _jsx(IconLayoutSidebarRight, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) }) }), _jsxs("div", { className: "panel__header-actions", children: [_jsx(PeekOriginalButton, {}), _jsx(AgentStatusButton, { onOpenSettings: openSettings })] })] }), _jsx("div", { className: "panel__copy-row", children: _jsx(CopyPromptButton, { settingsOpen: settingsOpen, settingsSection: settingsSection, onOpenSettings: openSettings, onSettingsOpenChange: setSettingsOpen }) })] }), _jsxs("div", { className: "panel__body", children: [inlineTextFeedback ? (_jsx(StatusCallout, { tone: "danger", className: "inline-text-diagnostic", "data-test": "inline-text-diagnostic", role: "status", "aria-live": "polite", "aria-atomic": "true", children: _jsx("span", { children: inlineTextFeedback.message }) })) : null, runtimeConfig.inspectionUnavailableReason ? (_jsxs(StatusCallout, { tone: "danger", "data-test": "page-inspection-error", role: "status", children: ["Can\u2019t load Nudge on this page due to ", runtimeConfig.inspectionUnavailableReason, "."] })) : selected ? (_jsxs(_Fragment, { children: [showInteractionState || hasEditScopeCallout ? (_jsxs("div", { className: `selection${hasEditScopeCallout ? "" : " selection--without-scope-callout"}`, "data-test": "selection", "data-selected-cid": selected.cid, "data-selected-src": selected.src, "data-selected-count": selectedElements.length, children: [hasEditScopeCallout ? (_jsx(StatusCallout, { tone: editScope === "rendered-instance" ? "neutral" : "accent", "data-test": "edit-scope", "data-lost": "false", children: editScope === "rendered-instance" ? (_jsxs("div", { className: "scope__unlinked", children: [_jsx("span", { children: "Element unlinked" }), _jsx(Button, { size: "compact", className: "scope__action", "data-test": "relink-element", onClick: () => {
-                                                                const overrideId = relinkElement(selected.domElement);
-                                                                if (overrideId)
-                                                                    discardChangesForInstanceOverride(overrideId);
-                                                                refreshScopeState();
-                                                            }, children: "Relink" })] })) : (_jsxs("div", { className: "scope__linked", children: [_jsxs("span", { children: ["Affects ", sourceSiteMatchCount, " elements."] }), _jsx(Button, { size: "compact", variant: "quiet", "data-test": "unlink-element", onClick: () => {
-                                                                unlinkElement(selected.domElement);
-                                                                refreshScopeState();
-                                                            }, children: "Unlink" })] })) })) : null, showInteractionState ? (_jsx(FieldRow, { label: "State", className: "style-state", "data-test": "style-state", children: _jsx(Select, { value: styleState, "data-test": "style-state-select", "aria-label": "Style State", options: availableInteractionStates.map((state) => ({
-                                                        value: state,
-                                                        label: formatInspectorLabel(state),
-                                                    })), onValueChange: (state) => {
-                                                        const nextState = availableInteractionStates.find((candidate) => candidate === state);
-                                                        if (!nextState)
-                                                            return;
-                                                        setActiveStyleState(nextState);
-                                                        setStyleState(nextState);
-                                                    } }) })) : null] })) : null, !isMultiSelection ? _jsx(ComponentPropsSection, { selected: selected }) : null, selectionEditable ? (_jsx(AtRuleContextProvider, { rows: tokenRows, children: _jsxs("div", { className: "style-editors", "data-test": "style-editors", children: [_jsx(LayoutSection, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRows: tokenRows }, `layout-${styleState}`), _jsx(SpacingBox, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRows: tokenRows }, `spacing-${styleState}`), _jsx(AppearanceSection, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRows: tokenRows }, `appearance-${styleState}`), showText ? _jsxs(_Fragment, { children: [_jsx(Typography, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRows: tokenRows }, `type-${styleState}`), _jsx(ColorPicker, { element: selected, selection: styleSelection, property: "color", entries: tokenEntries, tokenRow: findTokenRow(tokenRows, "color") }, `color-${styleState}`)] }) : null, _jsx(BackgroundEditor, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRow: backgroundTokenRow }, `background-${styleState}`), _jsx(BorderEditor, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRows: tokenRows }, `border-${styleState}`), _jsx(BoxShadowEditor, { element: selected, selection: styleSelection, entries: tokenEntries, tokenRows: tokenRows }, `box-shadow-${styleState}`)] }) })) : (_jsx(StatusCallout, { tone: "neutral", "data-test": "multi-selection-uneditable", children: "These repeated items are indistinguishable, so Nudge UI cannot safely target only part of the group. Select every repeated item to edit them together." }))] })) : (_jsx(EmptyState, {})), _jsx(ChangesLog, { onClearSession: clearInspectorSession })] })] }), sketchEnabled ? (_jsx(SketchWorkspace, { hostElement: sketchHost, projectId: runtimeConfig.projectId })) : null, !isOpen ? (_jsx("div", { className: "panel__restore", children: _jsx(Tooltip, { children: _jsx(IconButton, { variant: "quiet", label: "Show inspector", className: "panel__restore-button", "data-test": "show-inspector", onClick: () => setInspectorOpen(true), children: _jsx(IconLayoutSidebarRight, { size: "var(--icon-size-small)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }) }) }) })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(InspectorStyle, { testId: "inspector-styles", css: UI_STYLES }), _jsxs(InspectorPanel, { isOpen: isOpen, collapseDisabled: sketchActive, toggleShortcut: getInspectorToggleShortcutLabel(), onOpenChange: (open) => {
+                    if (!open)
+                        cancelInlineTextEdit();
+                    setInspectorOpen(open);
+                }, headerActions: _jsxs(_Fragment, { children: [_jsx(PeekOriginalButton, {}), _jsx(AgentStatusButton, { onOpenSettings: openSettings })] }), prompt: _jsx(CopyPromptButton, { settingsOpen: settingsOpen, settingsSection: settingsSection, onOpenSettings: openSettings, onSettingsOpenChange: setSettingsOpen, onClearChanges: clearInspectorSession }), children: [inlineTextFeedback ? (_jsx(StatusCallout, { tone: "danger", className: "inline-text-diagnostic", "data-test": "inline-text-diagnostic", role: "status", "aria-live": "polite", "aria-atomic": "true", children: _jsx("span", { children: inlineTextFeedback.message }) })) : null, runtimeConfig.inspectionUnavailableReason ? (_jsxs(StatusCallout, { tone: "danger", "data-test": "page-inspection-error", role: "status", children: ["Can\u2019t load Nudge on this page due to ", runtimeConfig.inspectionUnavailableReason, "."] })) : selected ? (_jsxs(_Fragment, { children: [_jsx(InspectorSelection, { identity: selected, count: selectedElements.length, isComponent: !isMultiSelection && componentProps !== null, name: isMultiSelection ? { title: `${selectedElements.length} elements` } : componentProps ? { title: componentProps.target.meta.componentName } : describeElement(selected.domElement), editScope: editScope, sourceSiteMatchCount: sourceSiteMatchCount, styleState: styleState, availableInteractionStates: availableInteractionStates, onStyleStateChange: (state) => {
+                                    setActiveStyleState(state);
+                                    setStyleState(state);
+                                }, onRelink: () => {
+                                    const overrideId = relinkElement(selected.domElement);
+                                    if (overrideId)
+                                        discardChangesForInstanceOverride(overrideId);
+                                    refreshScopeState();
+                                }, onUnlink: () => {
+                                    unlinkElement(selected.domElement);
+                                    refreshScopeState();
+                                }, children: !isMultiSelection ? _jsx(ComponentPropsSection, { selected: selected }) : null }), selectionEditable ? (_jsx(InspectorEditors, { selected: selected, styleSelection: styleSelection, tokenEntries: tokenEntries, tokenRows: tokenRows, styleState: styleState, showText: showText, backgroundTokenRow: backgroundTokenRow })) : (_jsx(StatusCallout, { tone: "neutral", "data-test": "multi-selection-uneditable", children: "These repeated items are indistinguishable, so Nudge UI cannot safely target only part of the group. Select every repeated item to edit them together." }))] })) : (_jsx(EmptyState, {})), _jsx(ChangesLog, { onClearSession: clearInspectorSession })] }), sketchEnabled ? (_jsx(SketchWorkspace, { hostElement: sketchHost, projectId: runtimeConfig.projectId })) : null] }));
 }

package/dist/inspector/shell/NudgeLogoIcon.d.ts

@@ -0,0 +1,5 @@
+import type { ReactElement } from "react";
+/** Same artwork as the extension and landing favicons. */
+export declare function NudgeLogoIcon({ size }: {
+    size?: string;
+}): ReactElement;

package/dist/inspector/shell/NudgeLogoIcon.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Same artwork as the extension and landing favicons. */
+export function NudgeLogoIcon({ size = "var(--icon-size-small)" }) {
+    return (_jsxs("svg", { viewBox: "5 4 35 35", width: size, height: size, fill: "currentColor", "aria-hidden": "true", children: [_jsx("path", { d: "M14.7742 6C27.6015 6 38 16.569 38 29.6066V38H30.7742V29.6066C30.7742 20.6251 23.6107 13.3443 14.7742 13.3443H13.2258V38H6V6H14.7742Z" }), _jsx("path", { d: "M39 15.6629C37 11.5 33 7 28.4919 5H39V15.6629Z" })] }));
+}

package/dist/inspector/shell/PeekOriginalButton.d.ts

@@ -1,7 +1,2 @@
 import { type ReactElement } from "react";
-/**
- * Press-and-hold button that previews the page without inspector changes
- * (NUD-30). Releasing restores the edited preview; canonical intent is never
- * cleared, so nothing is lost while held.
- */
 export declare function PeekOriginalButton(): ReactElement;

package/dist/inspector/shell/PeekOriginalButton.js

@@ -11,11 +11,6 @@ function useDraftChangeCount() {
         return snapshot.changes.length + snapshot.structuralChanges.length;
     }, () => 0);
 }
-/**
- * Press-and-hold button that previews the page without inspector changes
- * (NUD-30). Releasing restores the edited preview; canonical intent is never
- * cleared, so nothing is lost while held.
- */
 export function PeekOriginalButton() {
     const active = useOriginalPreviewActive();
     const changeCount = useDraftChangeCount();

package/dist/inspector/shell/PeekOriginalIcon.d.ts

@@ -1,7 +1,2 @@
 import type { ReactElement } from "react";
-/**
- * Before/after comparison glyph for the hold-to-view-original button.
- * Custom artwork rendered with the shared inspector icon tokens so it
- * matches the neighboring header icons.
- */
 export declare function PeekOriginalIcon(): ReactElement;

package/dist/inspector/shell/PeekOriginalIcon.js

@@ -1,9 +1,4 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * Before/after comparison glyph for the hold-to-view-original button.
- * Custom artwork rendered with the shared inspector icon tokens so it
- * matches the neighboring header icons.
- */
 export function PeekOriginalIcon() {
     return (_jsxs("svg", { viewBox: "0 0 24 24", width: "var(--icon-size-small)", height: "var(--icon-size-small)", "aria-hidden": "true", children: [_jsx("path", { d: "M8.66667 5L6 5C4.34315 5 3 6.34315 3 8L3 16C3 17.6569 4.34315 19 6 19L12 19", fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeWidth: "var(--icon-stroke-width)" }), _jsx("path", { d: "M13 5L18 5C19.6569 5 21 6.34315 21 8L21 16C21 17.6569 19.6569 19 18 19L16.3333 19", fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeWidth: "var(--icon-stroke-width)" }), _jsx("line", { x1: "13.7721", y1: "22.2984", x2: "8.29835", y2: "2.22788", fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeWidth: "var(--icon-stroke-width)" })] }));
 }

package/dist/inspector/shell/PromptActionButton.d.ts

@@ -0,0 +1,21 @@
+import { type ReactElement, type ReactNode } from "react";
+import { type ButtonProps } from "../ui/Button.js";
+export interface PromptActionButtonProps extends ButtonProps {
+    readonly copied?: boolean;
+    readonly agentState?: string;
+    readonly busy?: boolean;
+    readonly icon?: ReactNode;
+    readonly label?: ReactNode;
+    readonly badgeCount?: number;
+    readonly hasMenu?: boolean;
+}
+/** Presents a prompt action without owning clipboard or agent connections. */
+export declare const PromptActionButton: import("react").ForwardRefExoticComponent<PromptActionButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface PromptActionRowProps {
+    readonly children: ReactNode;
+    /** Clears the pending changes; the clear changes action stays beside the prompt action and disables without changes. */
+    readonly onClear?: () => void;
+    readonly hasChanges?: boolean;
+}
+/** A prompt action with a matching clear changes action beside it, disabled until there are changes. */
+export declare function PromptActionRow({ children, onClear, hasChanges }: PromptActionRowProps): ReactElement;

package/dist/inspector/shell/PromptActionButton.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { IconChevronDown, IconCopy, IconRestore } from "@tabler/icons-react";
+import { Button } from "../ui/Button.js";
+import { IconButton } from "../ui/IconButton.js";
+import { Tooltip } from "../ui/Tooltip.js";
+/** Presents a prompt action without owning clipboard or agent connections. */
+export const PromptActionButton = forwardRef(function PromptActionButton({ copied = false, agentState = "disconnected", busy = false, icon = _jsx(IconCopy, { size: "var(--icon-size-small)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), label = "Copy prompt", badgeCount = 0, hasMenu = false, ...props }, ref) {
+    return _jsxs(Button, { ref: ref, variant: "primary", className: "copy-prompt__main", "data-test": "copy-prompt", type: "button", "data-copied": copied ? "true" : "false", "data-agent-state": agentState, "aria-busy": busy ? "true" : undefined, ...props, children: [icon, label, badgeCount > 0 ? _jsx("span", { className: "copy-prompt__change-count", "data-test": "copy-prompt-change-count", children: badgeCount }) : null, hasMenu ? _jsx(IconChevronDown, { size: "var(--icon-size-small)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }) : null] });
+});
+/** A prompt action with a matching clear changes action beside it, disabled until there are changes. */
+export function PromptActionRow({ children, onClear, hasChanges = false }) {
+    return (_jsxs("div", { className: "copy-prompt__row", children: [children, onClear ? (_jsx(Tooltip, { children: _jsx(IconButton, { className: "copy-prompt__clear-changes", variant: "secondary", label: "Clear changes", "data-test": "copy-prompt-clear", disabled: !hasChanges, onClick: onClear, children: _jsx(IconRestore, { size: "var(--icon-size-small)", "aria-hidden": "true" }) }) })) : null] }));
+}

package/dist/inspector/shell/elementName.d.ts

@@ -0,0 +1,5 @@
+export interface ElementName {
+    readonly title: string;
+}
+/** The title is derived from the tag, with an accessible name when the author gave one. */
+export declare function describeElement(element: HTMLElement): ElementName;

package/dist/inspector/shell/elementName.js

@@ -0,0 +1,29 @@
+const TAG_LABELS = new Map([
+    ["a", "Link"],
+    ["article", "Article"],
+    ["aside", "Aside"],
+    ["button", "Button"],
+    ["footer", "Footer"],
+    ["form", "Form"],
+    ["header", "Header"],
+    ["img", "Image"],
+    ["input", "Input"],
+    ["label", "Label"],
+    ["li", "List item"],
+    ["main", "Main"],
+    ["nav", "Navigation"],
+    ["ol", "List"],
+    ["p", "Paragraph"],
+    ["section", "Section"],
+    ["select", "Select"],
+    ["svg", "Icon"],
+    ["textarea", "Text area"],
+    ["ul", "List"],
+]);
+/** The title is derived from the tag, with an accessible name when the author gave one. */
+export function describeElement(element) {
+    const tag = element.localName.toLowerCase();
+    const base = /^h[1-6]$/.test(tag) ? `Heading ${tag.slice(1)}` : TAG_LABELS.get(tag) ?? (tag.charAt(0).toUpperCase() + tag.slice(1));
+    const accessible = element.getAttribute("aria-label")?.trim();
+    return { title: accessible ? `${base} · ${accessible}` : base };
+}

package/dist/inspector/shell/interactionStatePreview.d.ts

@@ -1,9 +1,6 @@
 import { type InteractionState } from "./styleState.js";
 /** Matches native interaction states and the Inspector's temporary CSS state. */
 export declare function selectorForInteractionStatePreview(selector: string): string;
-/**
- * Projects CSS interaction states into the selected element's document.
- * This previews styles without dispatching events or changing application state.
- */
+/** Previews interaction states without dispatching events or changing application state. */
 export declare function startInteractionStatePreview(element: HTMLElement, state: InteractionState): () => void;
 export declare function useInteractionStatePreview(element: HTMLElement | null, state: InteractionState): void;

package/dist/inspector/shell/interactionStatePreview.js

@@ -11,8 +11,7 @@ export function selectorForInteractionStatePreview(selector) {
     for (const pseudo of [...selectorPseudoClasses(selector)].reverse()) {
         if (!interactionStates.has(pseudo.name))
             continue;
-        // Keep native states on other elements, but use the chosen state on the
-        // selected element. :where() keeps the original pseudo-class specificity.
+        // :where() keeps the replacement at the original pseudo-class specificity.
         const replacement = `:is(:${pseudo.name}:where(:not([${MARKER}])), [${MARKER}="${pseudo.name}"])`;
         transformed = transformed.slice(0, pseudo.start) + replacement + transformed.slice(pseudo.end);
     }
@@ -20,8 +19,7 @@ export function selectorForInteractionStatePreview(selector) {
 }
 function previewSelector(selector) {
     const transformed = selectorForInteractionStatePreview(selector);
-    // Add the same specificity to every copied branch. This preserves their
-    // relative cascade while overriding native pointer states on the target.
+    // Same added specificity on every branch preserves their relative cascade while overriding native pointer states.
     const scope = `:where([${MARKER}], [${MARKER}] *):is(#${STATE_PREVIEW_SHEET_ID}, *)`;
     // A scope must precede a pseudo-element, which cannot take an attribute.
     let parentheses = 0;
@@ -58,10 +56,7 @@ function previewSelector(selector) {
     }
     return transformed + scope;
 }
-/**
- * Projects CSS interaction states into the selected element's document.
- * This previews styles without dispatching events or changing application state.
- */
+/** Previews interaction states without dispatching events or changing application state. */
 export function startInteractionStatePreview(element, state) {
     if (state === "base")
         return () => undefined;

package/dist/inspector/shell/originalPreview.d.ts

@@ -1,10 +1,5 @@
 export declare function isOriginalPreviewActive(): boolean;
 export declare function subscribeOriginalPreview(listener: () => void): () => void;
 export declare function useOriginalPreviewActive(): boolean;
-/**
- * Hold-to-view-original (NUD-30). While active the host document shows the
- * page without any inspector changes; the draft preview owns that projection.
- * Canonical intent stays in the workspace, so releasing restores the edited
- * preview without loss.
- */
+/** While active the document shows the page without inspector changes; canonical intent is never cleared. */
 export declare function setOriginalPreviewActive(next: boolean): void;

package/dist/inspector/shell/originalPreview.js

@@ -13,12 +13,7 @@ export function subscribeOriginalPreview(listener) {
 export function useOriginalPreviewActive() {
     return useSyncExternalStore(subscribeOriginalPreview, () => previewingOriginal, () => false);
 }
-/**
- * Hold-to-view-original (NUD-30). While active the host document shows the
- * page without any inspector changes; the draft preview owns that projection.
- * Canonical intent stays in the workspace, so releasing restores the edited
- * preview without loss.
- */
+/** While active the document shows the page without inspector changes; canonical intent is never cleared. */
 export function setOriginalPreviewActive(next) {
     if (next === previewingOriginal)
         return;

package/dist/inspector/shell/stateValue.d.ts

@@ -1,3 +1,2 @@
-/** Read an inspector value from the selected authored state, falling back to
- * the browser only when CSSOM has no declaration to attribute. */
+/** Reads from the authored state; the browser is only the fallback when CSSOM has no declaration to attribute. */
 export declare function getStateStyleValue(el: HTMLElement, property: string, fallback?: string): string;

package/dist/inspector/shell/stateValue.js

@@ -1,14 +1,11 @@
 import { getActiveStyleState } from "./styleState.js";
 import { readInspectionSnapshot } from "../inspection/inspectionSnapshot.js";
 import { getElementComputedStyle } from "../runtime/domRealm.js";
-/** Read an inspector value from the selected authored state, falling back to
- * the browser only when CSSOM has no declaration to attribute. */
+/** Reads from the authored state; the browser is only the fallback when CSSOM has no declaration to attribute. */
 export function getStateStyleValue(el, property, fallback = "") {
     try {
         const state = getActiveStyleState();
-        // Keep the browser's exact computed value for ordinary Base inspection.
-        // Authored resolution is needed when the live element is transiently
-        // interacted with, or when the user explicitly selected another state.
+        // Base inspection uses the browser's computed value unless the element is transiently hovered or focused.
         const hasLiveInteraction = [":hover", ":active", ":focus", ":focus-visible"].some((selector) => {
             try {
                 return el.matches(selector);

package/dist/inspector/shell/styleState.d.ts

@@ -1,7 +1,6 @@
 export declare const INTERACTION_STATES: readonly ["hover", "active", "focus", "focus-visible", "disabled"];
 export type InteractionState = "base" | (typeof INTERACTION_STATES)[number];
-/** The selected authored interaction state. Kept outside React so edit actions
- * and history have the same context as the panel that initiated an edit. */
+/** Kept outside React so edit actions and history share the panel's context. */
 export declare function getActiveStyleState(): InteractionState;
 export declare function setActiveStyleState(state: InteractionState): void;
 export declare function selectorForInteractionState(selector: string, state: InteractionState): string;

package/dist/inspector/shell/styleState.js

@@ -1,7 +1,6 @@
 export const INTERACTION_STATES = ["hover", "active", "focus", "focus-visible", "disabled"];
 let activeState = "base";
-/** The selected authored interaction state. Kept outside React so edit actions
- * and history have the same context as the panel that initiated an edit. */
+/** Kept outside React so edit actions and history share the panel's context. */
 export function getActiveStyleState() {
     return activeState;
 }

package/dist/inspector/sketch/SketchEditor.js

@@ -273,7 +273,6 @@ export function SketchEditor({ open, document: sketchDocument, captured, onCance
             event.currentTarget.releasePointerCapture(event.pointerId);
         }
         catch {
-            // The pointer may already have been released by the browser.
         }
         if (draftPointLimitReached.current) {
             draftPointLimitReached.current = false;

package/dist/inspector/sketch/SketchFrameOverlay.js

@@ -8,13 +8,11 @@ import { sketchBelongsToCard, useDrafts } from "../drafts/store.js";
 export function sketchRouteKey(url) {
     try {
         const parsed = new URL(url);
-        // These parameters belong to the inspector host, not to the application
-        // route. Removing them lets a sketch follow the same page in Focus mode,
-        // the canvas, and a direct editor launch.
+        // Inspector-host params: removing them keeps one sketch attached across
+        // Focus mode, the canvas, and direct launch.
         parsed.searchParams.delete("__nudge_ui_direct");
         parsed.searchParams.delete("nudge-ui");
-        // Hashes identify an in-document location, not a different sketch canvas.
-        // Keep saved marks attached when navigation changes only the anchor.
+        // Hashes are in-document anchors, so marks stay attached when only the anchor changes.
         return `${parsed.origin}${parsed.pathname}${parsed.search}`;
     }
     catch {
@@ -43,9 +41,8 @@ export function projectSketchPoint(point, document, frameWindow, width, height)
     const viewportWidth = Math.max(1, frameWindow.innerWidth || width);
     const viewportHeight = Math.max(1, frameWindow.innerHeight || height);
     const scroll = getSketchScrollPosition(frameWindow);
-    // Preserve the point's relative horizontal position when the responsive
-    // iframe changes width. Apply the scroll delta separately so horizontal
-    // page scrolling still moves the sketch with the content.
+    // Horizontal position scales with the responsive iframe width; the scroll
+    // delta is applied separately.
     const captureLocalX = (point.x / imageWidth) * capture.viewportWidth;
     const currentLocalX = (captureLocalX / Math.max(1, capture.viewportWidth)) * viewportWidth
         - (scroll.x - capture.scrollX);
@@ -101,10 +98,9 @@ export function SketchFrameOverlay({ cardId, iframe, cardUrl, artifactId, ready
     const frameWindow = iframe?.contentWindow ?? null;
     const layers = useMemo(() => {
         if (!iframe || !frameWindow || documents.length === 0) {
-            return {
-                strokes: [],
-                annotations: [],
-            };
+            const strokes = [];
+            const annotations = [];
+            return { strokes, annotations };
         }
         const strokes = [];
         const annotations = [];

package/dist/inspector/sketch/SketchOverlay.js

@@ -13,7 +13,7 @@ import { isEditableEvent } from "../shell/shortcuts.js";
 import { ERASER_CURSOR, SKETCH_CURSOR } from "../ui/customCursors.js";
 import { useTemporaryAppInteraction } from "../canvas/viewStore.js";
 import { portalContainer } from "../ui/portalContainer.js";
-/** Eraser reach around the pointer in screen pixels, matching the cursor ring. */
+/** Screen-pixel eraser reach; must match the cursor ring. */
 const ERASER_RADIUS_PX = 8;
 function sketchCursor(tool) {
     if (tool === "eraser")
@@ -121,9 +121,8 @@ export function SketchOverlay({ open, hostElement, selectTarget, onCancel, onDon
         if (open)
             svgRef.current?.focus();
     }, [open]);
-    // Listen on the window rather than the dialog: the drawing options live in
-    // the canvas toolbar, so focus is often outside the dialog while sketching.
-    // Text fields keep their native undo.
+    // Window-level so shortcuts work while focus is in the canvas toolbar; text
+    // fields keep their native undo.
     useEffect(() => {
         if (!open)
             return;
@@ -165,8 +164,8 @@ export function SketchOverlay({ open, hostElement, selectTarget, onCancel, onDon
             || event.clientY < drawingViewport.offsetY || event.clientY > drawingViewport.offsetY + drawingViewport.displayHeight)
             return;
         const point = pointFromEvent(event, drawingViewport);
-        // Drawing cancels the browser's focus change, so move focus here
-        // explicitly; otherwise undo keeps going to the note or a toolbar button.
+        // Drawing cancels the browser's focus change, so move focus here or undo
+        // goes to the note or toolbar.
         event.preventDefault();
         svgRef.current?.focus({ preventScroll: true });
         pointerId.current = event.pointerId;

package/dist/inspector/sketch/SketchPromptPanel.d.ts

@@ -11,5 +11,4 @@ export interface SketchPromptPanelProps {
     readonly onDone: () => void | Promise<void>;
     readonly onCancel?: () => void;
 }
-/** The small note editor shared by a new live sketch and saved sketch layers. */
 export declare function SketchPromptPanel({ dataTest, className, description, error, disabled, saving, autoFocus, onDescriptionChange, onDone, onCancel, }: SketchPromptPanelProps): ReactElement;

package/dist/inspector/sketch/SketchPromptPanel.js

@@ -3,7 +3,6 @@ import { IconAlertTriangleFilled } from "@tabler/icons-react";
 import { useRef } from "react";
 import { Button } from "../ui/Button.js";
 import { SKETCH_LIMITS } from "./model.js";
-/** The small note editor shared by a new live sketch and saved sketch layers. */
 export function SketchPromptPanel({ dataTest, className, description, error = null, disabled = false, saving = false, autoFocus = false, onDescriptionChange, onDone, onCancel, }) {
     // Keep the last message while the banner collapses so its text does not vanish mid-animation.
     const lastError = useRef(error);