nudge-ui 0.2.0

package/dist/inspector/projection/workspaceProjection.d.ts

@@ -0,0 +1,43 @@
+import { type StyleRule } from "./managedStylesheet.js";
+import type { RenderedInstanceOverride } from "../changes/editModel.js";
+import { type StructuralChange } from "./structuralProjection.js";
+import type { ComponentOverride } from "../componentSemantics/types.js";
+import { type TextContentChangeRecord } from "../changes/types.js";
+import type { WorkspaceContents } from "../changes/workspaceChanges.js";
+export interface WorkspaceProjectionSource extends WorkspaceContents {
+    readonly revision: number;
+}
+export interface CompiledManagedStyles {
+    readonly rules: readonly StyleRule[];
+    readonly css: string;
+}
+export interface SerializedManagedStyles {
+    readonly css: string;
+}
+/** A complete, read-only projection for one document-local runtime. */
+export interface WorkspaceProjectionPlan<ManagedStyles> {
+    readonly sourceRevision: number;
+    readonly managedStyles: ManagedStyles;
+    readonly instanceOverrides: readonly RenderedInstanceOverride[];
+    readonly structuralChanges: readonly StructuralChange[];
+    readonly textContentChanges: readonly TextContentChangeRecord[];
+    readonly componentOverrides: readonly ComponentOverride[];
+}
+/** Applies every projection dimension to one document-local runtime. */
+export interface DocumentProjectionAdapter<ManagedStyles> {
+    applyStructural(changes: readonly StructuralChange[]): void;
+    applyRenderedInstances(overrides: readonly RenderedInstanceOverride[]): void;
+    applyText(changes: readonly TextContentChangeRecord[]): void;
+    applyComponents(overrides: readonly ComponentOverride[]): void;
+    applyManagedStyles(styles: ManagedStyles): void;
+}
+export declare function compileWorkspaceProjection(snapshot: WorkspaceProjectionSource): WorkspaceProjectionPlan<CompiledManagedStyles>;
+/**
+ * Replaces one document projection in the required order.
+ *
+ * Structural intent is applied first because later rendered-instance evidence
+ * can depend on the restored element order. Managed CSS is applied last so
+ * selectors can use the document-local instance markers installed above.
+ */
+export declare function applyWorkspaceProjection<ManagedStyles>(adapter: DocumentProjectionAdapter<ManagedStyles>, plan: WorkspaceProjectionPlan<ManagedStyles>): void;
+export declare function applyHostWorkspaceProjection(plan: WorkspaceProjectionPlan<CompiledManagedStyles>): void;

package/dist/inspector/projection/workspaceProjection.js

@@ -0,0 +1,58 @@
+import { applyRules, rulesToCssText } from "./managedStylesheet.js";
+import { applyRenderedInstanceProjection, collectRenderedInstanceOverrides, } from "./renderedInstance.js";
+import { applyStructuralProjection, } from "./structuralProjection.js";
+import { applyTextContentProjection, collectTextContentChanges, } from "./textProjection.js";
+import { replaceComponentOverrideProjection } from "../componentSemantics/index.js";
+import { componentChangeToOverride } from "../componentSemantics/changeModel.js";
+import { isComponentChange } from "../changes/types.js";
+import { buildManagedStyleRules } from "../changes/managedStyleProjection.js";
+export function compileWorkspaceProjection(snapshot) {
+    const changes = [...snapshot.changes];
+    const rules = buildManagedStyleRules(changes);
+    return {
+        sourceRevision: snapshot.revision,
+        managedStyles: {
+            rules,
+            css: rulesToCssText(rules),
+        },
+        instanceOverrides: collectRenderedInstanceOverrides(changes),
+        structuralChanges: [...snapshot.structuralChanges],
+        textContentChanges: collectTextContentChanges(changes),
+        componentOverrides: changes
+            .filter(isComponentChange)
+            .map(componentChangeToOverride)
+            .filter((override) => override !== null),
+    };
+}
+/**
+ * Replaces one document projection in the required order.
+ *
+ * Structural intent is applied first because later rendered-instance evidence
+ * can depend on the restored element order. Managed CSS is applied last so
+ * selectors can use the document-local instance markers installed above.
+ */
+export function applyWorkspaceProjection(adapter, plan) {
+    adapter.applyStructural(plan.structuralChanges);
+    adapter.applyRenderedInstances(plan.instanceOverrides);
+    adapter.applyText(plan.textContentChanges);
+    adapter.applyComponents(plan.componentOverrides);
+    adapter.applyManagedStyles(plan.managedStyles);
+}
+const hostDocumentProjectionAdapter = {
+    applyStructural: (changes) => {
+        applyStructuralProjection(document, changes);
+    },
+    applyRenderedInstances: (overrides) => {
+        applyRenderedInstanceProjection(document, overrides);
+    },
+    applyText: (changes) => {
+        applyTextContentProjection(document, changes);
+    },
+    applyComponents: replaceComponentOverrideProjection,
+    applyManagedStyles: (styles) => {
+        applyRules([...styles.rules]);
+    },
+};
+export function applyHostWorkspaceProjection(plan) {
+    applyWorkspaceProjection(hostDocumentProjectionAdapter, plan);
+}

package/dist/inspector/prompt/PromptSettingsDialog.d.ts

@@ -0,0 +1,15 @@
+import type { ReactElement, RefObject } from "react";
+export interface PromptSettingsDialogProps {
+    open: boolean;
+    value: string;
+    onChange: (value: string) => void;
+    onOpenChange: (open: boolean) => void;
+}
+export interface PromptSettingsFieldsProps {
+    value: string;
+    onChange: (value: string) => void;
+    instructionsRef?: RefObject<HTMLTextAreaElement | null>;
+}
+/** Edits the instructions appended to every generated prompt. */
+export declare function PromptSettingsFields({ value, onChange, instructionsRef, }: PromptSettingsFieldsProps): ReactElement;
+export declare function PromptSettingsDialog({ open, value, onChange, onOpenChange, }: PromptSettingsDialogProps): ReactElement;

package/dist/inspector/prompt/PromptSettingsDialog.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { Dialog } from "@base-ui/react/dialog";
+import { IconX } from "@tabler/icons-react";
+function portalContainer() {
+    return typeof document !== "undefined"
+        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
+        : null;
+}
+/** Edits the instructions appended to every generated prompt. */
+export function PromptSettingsFields({ value, onChange, instructionsRef, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "prompt-settings__field", children: _jsx("textarea", { ref: instructionsRef, id: "nudge-ui-custom-instructions", className: "prompt-settings__textarea", "data-test": "prompt-custom-instructions", "aria-label": "Custom instructions", rows: 6, value: value, onChange: (event) => onChange(event.currentTarget.value) }) }), _jsx("div", { className: "prompt-settings__actions", children: _jsx(Dialog.Close, { className: "button button--primary", "data-test": "prompt-settings-done", type: "button", children: "Done" }) })] }));
+}
+export function PromptSettingsDialog({ open, value, onChange, onOpenChange, }) {
+    const instructionsRef = useRef(null);
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "prompt-settings__backdrop", "data-test": "prompt-settings-backdrop" }), _jsxs(Dialog.Popup, { className: "prompt-settings__popup", "data-test": "prompt-settings-dialog", initialFocus: instructionsRef, children: [_jsxs("div", { className: "prompt-settings__header", children: [_jsx(Dialog.Title, { className: "prompt-settings__title", children: "Custom instructions" }), _jsx(Dialog.Close, { className: "icon-button icon-button--quiet prompt-settings__close", "aria-label": "Close custom instructions", "data-test": "prompt-settings-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(Dialog.Description, { className: "prompt-settings__description", children: "These instructions are added to the end of every copied prompt." }), _jsx(PromptSettingsFields, { value: value, onChange: onChange, instructionsRef: instructionsRef })] })] }) }));
+}

package/dist/inspector/prompt/clipboardHandoff.d.ts

@@ -0,0 +1,34 @@
+import { type ChangeRecord } from "../changes/changesLog.js";
+import { type StructuralChange } from "../projection/structuralProjection.js";
+export interface ClipboardHandoffFingerprint {
+    readonly key: string;
+    readonly fingerprint: string;
+}
+export interface ClipboardHandoffSnapshot {
+    readonly changes: readonly ClipboardHandoffFingerprint[];
+    readonly structuralChanges: readonly ClipboardHandoffFingerprint[];
+}
+/** Validates an origin-local persisted clipboard checkpoint. */
+export declare function isClipboardHandoffSnapshot(value: unknown): value is ClipboardHandoffSnapshot | null;
+/** Captures the exact records included in a successful clipboard copy. */
+export declare function recordClipboardHandoff(changes: readonly ChangeRecord[], structuralChanges?: readonly StructuralChange[]): void;
+/** Returns a defensive copy for durable-session serialization. */
+export declare function getClipboardHandoffSnapshot(): ClipboardHandoffSnapshot | null;
+/** Replaces the in-memory checkpoint from a validated durable session. */
+export declare function hydrateClipboardHandoff(value: ClipboardHandoffSnapshot | null): void;
+export declare function clearClipboardHandoff(): void;
+export declare function subscribeClipboardHandoff(listener: () => void): () => void;
+/** Monotonic external-store snapshot for persistence and React consumers. */
+export declare function getClipboardHandoffRevision(): number;
+export declare function getLastClipboardReconciledCount(): number;
+/**
+ * Checks a copied prompt against source-rendered output and reconciles only
+ * exact records that the browser can positively verify.
+ */
+export declare function reconcileClipboardHandoff(): Promise<number>;
+/**
+ * Watches source-driven document refreshes and page-return signals. The
+ * trailing debounce lets an HMR commit settle before verification lifts the
+ * inspector preview for two frames.
+ */
+export declare function startClipboardHandoffController(doc?: Document): () => void;

package/dist/inspector/prompt/clipboardHandoff.js

@@ -0,0 +1,212 @@
+import { changeKey } from "../changes/model.js";
+import { subscribeChanges, } from "../changes/changesLog.js";
+import {} from "../projection/structuralProjection.js";
+import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
+import { documentRevisions, subscribeDocumentRevision } from "../tokens/resolution/cssomCollector.js";
+import { handoffChangeFingerprint, handoffStructuralFingerprint, verifyAndReconcileHandoff, } from "../agent/verification.js";
+const MAX_HANDOFF_RECORDS = 10_000;
+const MAX_KEY_LENGTH = 16_384;
+const MAX_FINGERPRINT_LENGTH = 1_048_576;
+const RECONCILE_DEBOUNCE_MS = 450;
+let checkpoint = null;
+let revision = 0;
+let lastReconciledCount = 0;
+const listeners = new Set();
+function notify() {
+    revision += 1;
+    for (const listener of listeners)
+        listener();
+}
+function cloneSnapshot(snapshot) {
+    return {
+        changes: snapshot.changes.map((entry) => ({ ...entry })),
+        structuralChanges: snapshot.structuralChanges.map((entry) => ({ ...entry })),
+    };
+}
+function isFingerprint(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entry = value;
+    return Object.keys(entry).every((key) => key === "key" || key === "fingerprint")
+        && typeof entry.key === "string"
+        && entry.key.length > 0
+        && entry.key.length <= MAX_KEY_LENGTH
+        && typeof entry.fingerprint === "string"
+        && entry.fingerprint.length > 0
+        && entry.fingerprint.length <= MAX_FINGERPRINT_LENGTH;
+}
+/** Validates an origin-local persisted clipboard checkpoint. */
+export function isClipboardHandoffSnapshot(value) {
+    if (value === null)
+        return true;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (!Object.keys(candidate).every((key) => key === "changes" || key === "structuralChanges")
+        || !Array.isArray(candidate.changes)
+        || !Array.isArray(candidate.structuralChanges)
+        || candidate.changes.length + candidate.structuralChanges.length > MAX_HANDOFF_RECORDS
+        || !candidate.changes.every(isFingerprint)
+        || !candidate.structuralChanges.every(isFingerprint)) {
+        return false;
+    }
+    const changeKeys = candidate.changes.map((entry) => entry.key);
+    const structuralKeys = candidate.structuralChanges.map((entry) => entry.key);
+    return new Set(changeKeys).size === changeKeys.length
+        && new Set(structuralKeys).size === structuralKeys.length;
+}
+/** Captures the exact records included in a successful clipboard copy. */
+export function recordClipboardHandoff(changes, structuralChanges = []) {
+    checkpoint = {
+        changes: changes.map((change) => ({
+            key: changeKey(change),
+            fingerprint: handoffChangeFingerprint(change),
+        })),
+        structuralChanges: structuralChanges.map((change) => ({
+            key: change.id,
+            fingerprint: handoffStructuralFingerprint(change),
+        })),
+    };
+    lastReconciledCount = 0;
+    notify();
+}
+/** Returns a defensive copy for durable-session serialization. */
+export function getClipboardHandoffSnapshot() {
+    return checkpoint ? cloneSnapshot(checkpoint) : null;
+}
+/** Replaces the in-memory checkpoint from a validated durable session. */
+export function hydrateClipboardHandoff(value) {
+    if (!value && !checkpoint && lastReconciledCount === 0)
+        return;
+    checkpoint = value ? cloneSnapshot(value) : null;
+    lastReconciledCount = 0;
+    notify();
+}
+export function clearClipboardHandoff() {
+    if (!checkpoint && lastReconciledCount === 0)
+        return;
+    checkpoint = null;
+    lastReconciledCount = 0;
+    notify();
+}
+export function subscribeClipboardHandoff(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+/** Monotonic external-store snapshot for persistence and React consumers. */
+export function getClipboardHandoffRevision() {
+    return revision;
+}
+export function getLastClipboardReconciledCount() {
+    return lastReconciledCount;
+}
+function matchingChanges(snapshot) {
+    const expected = new Map(snapshot.changes.map((entry) => [entry.key, entry.fingerprint]));
+    return getWorkspaceChanges().changes.filter((change) => expected.get(changeKey(change)) === handoffChangeFingerprint(change));
+}
+function matchingStructuralChanges(snapshot) {
+    const expected = new Map(snapshot.structuralChanges.map((entry) => [entry.key, entry.fingerprint]));
+    return getWorkspaceChanges().structuralChanges.filter((change) => expected.get(change.id) === handoffStructuralFingerprint(change));
+}
+/** Drops checkpoint entries that no longer describe current canonical intent. */
+function pruneCheckpoint() {
+    if (!checkpoint)
+        return false;
+    const changes = matchingChanges(checkpoint);
+    const structuralChanges = matchingStructuralChanges(checkpoint);
+    if (changes.length === checkpoint.changes.length
+        && structuralChanges.length === checkpoint.structuralChanges.length) {
+        return false;
+    }
+    checkpoint = changes.length + structuralChanges.length === 0
+        ? null
+        : {
+            changes: changes.map((change) => ({
+                key: changeKey(change),
+                fingerprint: handoffChangeFingerprint(change),
+            })),
+            structuralChanges: structuralChanges.map((change) => ({
+                key: change.id,
+                fingerprint: handoffStructuralFingerprint(change),
+            })),
+        };
+    notify();
+    return true;
+}
+/**
+ * Checks a copied prompt against source-rendered output and reconciles only
+ * exact records that the browser can positively verify.
+ */
+export async function reconcileClipboardHandoff() {
+    const snapshot = checkpoint;
+    if (!snapshot)
+        return 0;
+    const changes = matchingChanges(snapshot);
+    const structuralChanges = matchingStructuralChanges(snapshot);
+    if (changes.length + structuralChanges.length === 0) {
+        pruneCheckpoint();
+        return 0;
+    }
+    const removed = await verifyAndReconcileHandoff({ changes, structuralChanges });
+    pruneCheckpoint();
+    if (removed > 0) {
+        lastReconciledCount = removed;
+        notify();
+    }
+    return removed;
+}
+/**
+ * Watches source-driven document refreshes and page-return signals. The
+ * trailing debounce lets an HMR commit settle before verification lifts the
+ * inspector preview for two frames.
+ */
+export function startClipboardHandoffController(doc = document) {
+    const ownerWindow = doc.defaultView;
+    let timer = null;
+    let checking = false;
+    let stopped = false;
+    const schedule = () => {
+        if (stopped || checking || !checkpoint)
+            return;
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            if (stopped || checking || !checkpoint)
+                return;
+            checking = true;
+            void reconcileClipboardHandoff()
+                .catch(() => undefined)
+                .finally(() => {
+                // Keep the guard through the MutationObserver microtask generated by
+                // restoring managed projections, preventing a verification loop.
+                setTimeout(() => { checking = false; }, 0);
+            });
+        }, RECONCILE_DEBOUNCE_MS);
+    };
+    const onCanonicalChange = () => {
+        pruneCheckpoint();
+    };
+    const onVisibilityChange = () => {
+        if (doc.visibilityState === "visible")
+            schedule();
+    };
+    // Initializes the document observer before registering the listener.
+    documentRevisions(doc);
+    const unsubscribeRevision = subscribeDocumentRevision(doc, schedule);
+    const unsubscribeChanges = subscribeChanges(onCanonicalChange);
+    ownerWindow?.addEventListener("focus", schedule);
+    ownerWindow?.addEventListener("pageshow", schedule);
+    doc.addEventListener("visibilitychange", onVisibilityChange);
+    schedule();
+    return () => {
+        stopped = true;
+        if (timer !== null)
+            clearTimeout(timer);
+        unsubscribeRevision();
+        unsubscribeChanges();
+        ownerWindow?.removeEventListener("focus", schedule);
+        ownerWindow?.removeEventListener("pageshow", schedule);
+        doc.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+}

package/dist/inspector/prompt/copyToClipboard.d.ts

@@ -0,0 +1 @@
+export declare function copyToClipboard(text: string): Promise<void>;

package/dist/inspector/prompt/copyToClipboard.js

@@ -0,0 +1,34 @@
+export async function copyToClipboard(text) {
+    if (typeof navigator !== "undefined" && navigator.clipboard && typeof navigator.clipboard.writeText === "function") {
+        try {
+            await navigator.clipboard.writeText(text);
+            return;
+        }
+        catch {
+            // fall through to legacy path
+        }
+    }
+    legacyCopy(text);
+}
+function legacyCopy(text) {
+    const doc = document;
+    const textarea = doc.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.style.position = "fixed";
+    textarea.style.top = "0";
+    textarea.style.left = "0";
+    textarea.style.opacity = "0";
+    doc.body.appendChild(textarea);
+    textarea.select();
+    let ok = false;
+    try {
+        ok = doc.execCommand("copy");
+    }
+    finally {
+        doc.body.removeChild(textarea);
+    }
+    if (!ok) {
+        throw new Error("copyToClipboard failed: clipboard API unavailable and execCommand returned false");
+    }
+}

package/dist/inspector/prompt/detectFramework.d.ts

@@ -0,0 +1,6 @@
+import type { TokenEntry } from "../../css/model/index.js";
+export interface DetectedFramework {
+    framework: string;
+    stylingSystem: string;
+}
+export declare function detectFramework(tokens: readonly TokenEntry[]): DetectedFramework;

package/dist/inspector/prompt/detectFramework.js

@@ -0,0 +1,4 @@
+import { detectStylingSystem } from "../runtime/runtimeConfig.js";
+export function detectFramework(tokens) {
+    return { framework: "React", stylingSystem: detectStylingSystem(tokens) };
+}

package/dist/inspector/prompt/generatePrompt.d.ts

@@ -0,0 +1,7 @@
+import type { ChangeRecord } from "../changes/changesLog.js";
+import type { StructuralChange } from "../projection/structuralProjection.js";
+export interface FrameworkHints {
+    framework?: string;
+    stylingSystem?: string;
+}
+export declare function generatePrompt(changes: ChangeRecord[], frameworkHints?: FrameworkHints, structuralChanges?: readonly StructuralChange[], customInstructions?: string): string;