nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/workspace/handoff.js

@@ -7,10 +7,11 @@ import { getCommentsForTarget, markCommentsHandedOff } from "../comments/store.j
 import { applicationTarget } from "../drafts/model.js";
 import { prepareHtmlIterationHandoff } from "../iterations/coordinator.js";
 import { getRegisteredFrames } from "../canvas/projection.js";
-import { getDraftChanges } from "../changes/draftChanges.js";
+import { getDraftChanges } from "../drafts/store.js";
 import { recordClipboardHandoff } from "../prompt/clipboardHandoff.js";
 import { copyToClipboard } from "../prompt/copyToClipboard.js";
 import { generatePrompt } from "../prompt/generatePrompt.js";
+import { withPromptContext } from "../prompt/promptDocument.js";
 import { createSketchAttachments, createSketchHandoffSnapshot, sketchMetadataForHandoff, } from "../sketch/handoff.js";
 import { markSketchesDispatching, markSketchesHandingOff, settleSketchDispatch } from "../sketch/store.js";
 async function prepareDraftHandoff(request) {
@@ -35,7 +36,7 @@ export async function prepareHandoff(request) {
     const generated = generatePrompt([...changes], hints, structuralChanges, request.customInstructions, sketchMetadata, comments);
     const prompt = target.kind === "html"
         ? htmlIterationPrompt(target.artifactId, generated, changes.length + structuralChanges.length + comments.length === 0, sketchMetadata.length > 0, request.customInstructions)
-        : `Page: ${target.route}\nApply the requested changes to this page. Shared source may affect other pages.\n\n${generated}`;
+        : withPromptContext([`Page: ${target.route}`, "Apply the requested changes to this page."], generated);
     return { ...handoff, prompt };
 }
 export async function prepareIterationImplementationPrompt(request) {
@@ -61,11 +62,7 @@ export async function copyHandoff(handoff) {
         recordClipboardHandoff(changes, structuralChanges, owner);
     }
 }
-/**
- * Sends the prompt to a connected agent, or copies it when no agent is given.
- * A failed send without sketches falls back to the clipboard; a failed sketch
- * send is returned so the user can choose to copy without the images.
- */
+/** Falls back to the clipboard; a failed sketch send returns so the caller can copy without the images. */
 export async function deliverHandoff(handoff, projectId, agent) {
     if (agent) {
         const outcome = await dispatchHandoff(handoff, projectId, agent);

package/dist/inspector/workspace/sentItems.d.ts

@@ -1,4 +1,4 @@
-import { type ChangeRecord } from "../changes/changesLog.js";
+import type { ChangeRecord } from "../changes/types.js";
 import type { StructuralChange } from "../changes/structuralTypes.js";
 import { type HandoffSnapshot } from "../agent/verification.js";
 import { type ElementComment } from "../comments/store.js";
@@ -12,8 +12,5 @@ export interface SentItems {
 }
 export declare function getSentItems(draftId: string, target: DraftTarget, agentDispatch: HandoffSnapshot | null): SentItems;
 export declare function sentItemCount(items: SentItems): number;
-/**
- * Removes sent items from the active draft as one undoable edit. Returns a
- * restore callback, or null when the draft is not active or nothing changed.
- */
-export declare function clearSentItems(items: SentItems): (() => void) | null;
+/** Removes sent items and their draft history, preserving newer, unsent edits. */
+export declare function clearSentItems(items: SentItems): void;

package/dist/inspector/workspace/sentItems.js

@@ -1,9 +1,8 @@
 import { changeKey } from "../changes/model.js";
-import { commitDraftContents } from "../changes/changesLog.js";
-import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
+import { canEditDraft, getActiveDraftChanges, reconcileDraftChanges } from "../drafts/store.js";
 import { unchangedHandoffRecords } from "../agent/verification.js";
 import { getClipboardHandoffRecords } from "../prompt/clipboardHandoff.js";
-import { getComments, getCommentsForTarget, removeComment, saveComment } from "../comments/store.js";
+import { getCommentsForTarget, removeComment } from "../comments/store.js";
 export function getSentItems(draftId, target, agentDispatch) {
     const clipboard = getClipboardHandoffRecords(draftId);
     const agent = agentDispatch?.owner.draftId === draftId
@@ -21,31 +20,14 @@ export function getSentItems(draftId, target, agentDispatch) {
 export function sentItemCount(items) {
     return items.changes.length + items.structuralChanges.length + items.comments.length;
 }
-/**
- * Removes sent items from the active draft as one undoable edit. Returns a
- * restore callback, or null when the draft is not active or nothing changed.
- */
+/** Removes sent items and their draft history, preserving newer, unsent edits. */
 export function clearSentItems(items) {
     const current = getActiveDraftChanges();
-    if (current.draftId !== items.draftId || sentItemCount(items) === 0)
-        return null;
+    if (current.draftId !== items.draftId || !canEditDraft(items.draftId) || sentItemCount(items) === 0)
+        return;
     const keys = new Set(items.changes.map(changeKey));
     const ids = new Set(items.structuralChanges.map((change) => change.id));
-    const draftChanged = items.changes.length + items.structuralChanges.length > 0;
-    if (draftChanged && !commitDraftContents(current.changes.filter((change) => !keys.has(changeKey(change))), current.structuralChanges.filter((change) => !ids.has(change.id))))
-        return null;
+    reconcileDraftChanges(items.draftId, keys, ids);
     for (const comment of items.comments)
         removeComment(comment.id);
-    return () => {
-        const draft = getDraftChanges(items.draftId);
-        if (draftChanged && getActiveDraftChanges().draftId === items.draftId) {
-            const present = new Set(draft.changes.map(changeKey));
-            const presentIds = new Set(draft.structuralChanges.map((change) => change.id));
-            commitDraftContents([...draft.changes, ...items.changes.filter((change) => !present.has(changeKey(change)))], [...draft.structuralChanges, ...items.structuralChanges.filter((change) => !presentIds.has(change.id))]);
-        }
-        const existing = new Set(getComments().map((comment) => comment.id));
-        for (const comment of items.comments)
-            if (!existing.has(comment.id))
-                saveComment(comment);
-    };
 }

package/dist/inspector/workspace/timeline.d.ts

@@ -1,11 +1,15 @@
-import type { DraftContents } from "../changes/draftChanges.js";
+import type { DraftContents } from "../drafts/model.js";
 export interface EditHistoryEntry {
     readonly kind: "edit";
     readonly draftId: string;
     readonly group?: symbol;
     readonly before: DraftContents;
     readonly after: DraftContents;
-    readonly activate?: () => void;
+    /** Where replay should take the user: the draft's owning frame, when one was known. */
+    readonly focus?: {
+        readonly draftId: string;
+        readonly cardId?: string;
+    };
 }
 export interface CanvasHistoryEntry {
     readonly kind: "canvas";
@@ -14,17 +18,30 @@ export interface CanvasHistoryEntry {
     readonly redo: () => void;
     readonly dispose: () => void;
 }
-export declare function subscribeTimeline(listener: () => void): () => void;
-export declare function timelineStatus(): {
-    canUndo: boolean;
-    canRedo: boolean;
-};
-export declare function recordEdit(entry: Omit<EditHistoryEntry, "kind" | "group">, equal: (a: DraftContents, b: DraftContents) => boolean): void;
+type ContentsEqual = (a: DraftContents, b: DraftContents) => boolean;
+/** Session undo: one ordered history shared by draft edits and Canvas operations. */
+export interface Timeline {
+    subscribe(listener: () => void): () => void;
+    status(): {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    recordEdit(entry: Omit<EditHistoryEntry, "kind" | "group">, equal: ContentsEqual): void;
+    recordCanvasChange(entry: Omit<CanvasHistoryEntry, "kind">): void;
+    replay(direction: "undo" | "redo", applyEdit: (entry: EditHistoryEntry, contents: DraftContents) => void): boolean;
+    pruneDraftHistory(draftId: string, retain: (contents: DraftContents) => DraftContents, equal: ContentsEqual): void;
+    discardDraftHistory(draftId: string): void;
+    discardCanvasHistory(cardId: string): void;
+    clear(): void;
+    releaseDetachedIterations(): void;
+    createGroup(): (update: () => void) => void;
+}
+export declare function createTimeline(): Timeline;
+export declare const sessionTimeline: Timeline;
 export declare function recordCanvasChange(entry: Omit<CanvasHistoryEntry, "kind">): void;
-export declare function replayTimeline(direction: "undo" | "redo", applyEdit: (entry: EditHistoryEntry, contents: DraftContents) => void): boolean;
-export declare function pruneDraftHistory(draftId: string, retain: (contents: DraftContents) => DraftContents, equal: (a: DraftContents, b: DraftContents) => boolean): void;
-export declare function discardDraftHistory(draftId: string): void;
 export declare function discardCanvasHistory(cardId: string): void;
+export declare function discardDraftHistory(draftId: string): void;
 export declare function clearSessionUndoHistory(): void;
 export declare function releaseDetachedIterations(): void;
 export declare function createChangeHistoryGroup(): (update: () => void) => void;
+export {};

package/dist/inspector/workspace/timeline.js

@@ -1,108 +1,129 @@
-let undoStack = [];
-let redoStack = [];
-let activeGroup;
-const listeners = new Set();
-function notify() {
-    for (const listener of listeners)
-        listener();
-}
-function discardRedo() {
-    const discarded = redoStack;
-    redoStack = [];
-    for (const entry of discarded)
-        if (entry.kind === "canvas")
-            entry.dispose();
-}
-export function subscribeTimeline(listener) {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-}
-export function timelineStatus() {
-    return { canUndo: undoStack.length > 0, canRedo: redoStack.length > 0 };
-}
-export function recordEdit(entry, equal) {
-    const previous = undoStack.at(-1);
-    const grouped = activeGroup && previous?.kind === "edit" && previous.draftId === entry.draftId && previous.group === activeGroup;
-    const next = { kind: "edit", ...entry, before: grouped ? previous.before : entry.before, group: activeGroup };
-    if (grouped)
-        undoStack.pop();
-    if (!equal(next.before, next.after))
-        undoStack.push(next);
-    discardRedo();
-    notify();
+export function createTimeline() {
+    let undoStack = [];
+    let redoStack = [];
+    let activeGroup;
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const discardRedo = () => {
+        const discarded = redoStack;
+        redoStack = [];
+        for (const entry of discarded)
+            if (entry.kind === "canvas")
+                entry.dispose();
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        status: () => ({ canUndo: undoStack.length > 0, canRedo: redoStack.length > 0 }),
+        recordEdit(entry, equal) {
+            const previous = undoStack.at(-1);
+            const grouped = activeGroup && previous?.kind === "edit" && previous.draftId === entry.draftId && previous.group === activeGroup;
+            const next = { kind: "edit", ...entry, before: grouped ? previous.before : entry.before, group: activeGroup };
+            if (grouped)
+                undoStack.pop();
+            if (!equal(next.before, next.after))
+                undoStack.push(next);
+            discardRedo();
+            notify();
+        },
+        recordCanvasChange(entry) {
+            discardRedo();
+            undoStack.push({ kind: "canvas", ...entry });
+            notify();
+        },
+        replay(direction, applyEdit) {
+            const source = direction === "undo" ? undoStack : redoStack;
+            const destination = direction === "undo" ? redoStack : undoStack;
+            const entry = source.pop();
+            if (!entry)
+                return false;
+            if (entry.kind === "edit")
+                applyEdit(entry, direction === "undo" ? entry.before : entry.after);
+            else
+                entry[direction]();
+            destination.push(entry);
+            notify();
+            return true;
+        },
+        pruneDraftHistory(draftId, retain, equal) {
+            const prune = (entries) => entries.flatMap((entry) => {
+                if (entry.kind !== "edit" || entry.draftId !== draftId)
+                    return [entry];
+                const next = { ...entry, before: retain(entry.before), after: retain(entry.after) };
+                return equal(next.before, next.after) ? [] : [next];
+            });
+            undoStack = prune(undoStack);
+            redoStack = prune(redoStack);
+            notify();
+        },
+        discardDraftHistory(draftId) {
+            const retain = (entry) => entry.kind !== "edit" || entry.draftId !== draftId;
+            undoStack = undoStack.filter(retain);
+            redoStack = redoStack.filter(retain);
+            notify();
+        },
+        discardCanvasHistory(cardId) {
+            const retain = (entry) => entry.kind !== "canvas" || !entry.cardIds.includes(cardId);
+            undoStack = undoStack.filter(retain);
+            const discarded = redoStack.filter((entry) => !retain(entry));
+            redoStack = redoStack.filter(retain);
+            for (const entry of discarded)
+                if (entry.kind === "canvas")
+                    entry.dispose();
+            notify();
+        },
+        clear() {
+            const discarded = [...undoStack, ...redoStack];
+            undoStack = [];
+            redoStack = [];
+            for (const entry of discarded)
+                if (entry.kind === "canvas")
+                    entry.dispose();
+            notify();
+        },
+        releaseDetachedIterations() {
+            discardRedo();
+            for (const entry of undoStack)
+                if (entry.kind === "canvas")
+                    entry.dispose();
+            notify();
+        },
+        createGroup() {
+            const group = Symbol("change-history-group");
+            return (update) => {
+                const previous = activeGroup;
+                activeGroup = group;
+                try {
+                    update();
+                }
+                finally {
+                    activeGroup = previous;
+                }
+            };
+        },
+    };
 }
+export const sessionTimeline = createTimeline();
 export function recordCanvasChange(entry) {
-    discardRedo();
-    undoStack.push({ kind: "canvas", ...entry });
-    notify();
-}
-export function replayTimeline(direction, applyEdit) {
-    const source = direction === "undo" ? undoStack : redoStack;
-    const destination = direction === "undo" ? redoStack : undoStack;
-    const entry = source.pop();
-    if (!entry)
-        return false;
-    if (entry.kind === "edit")
-        applyEdit(entry, direction === "undo" ? entry.before : entry.after);
-    else
-        entry[direction]();
-    destination.push(entry);
-    notify();
-    return true;
+    sessionTimeline.recordCanvasChange(entry);
 }
-export function pruneDraftHistory(draftId, retain, equal) {
-    const prune = (entries) => entries.flatMap((entry) => {
-        if (entry.kind !== "edit" || entry.draftId !== draftId)
-            return [entry];
-        const next = { ...entry, before: retain(entry.before), after: retain(entry.after) };
-        return equal(next.before, next.after) ? [] : [next];
-    });
-    undoStack = prune(undoStack);
-    redoStack = prune(redoStack);
-    notify();
+export function discardCanvasHistory(cardId) {
+    sessionTimeline.discardCanvasHistory(cardId);
 }
 export function discardDraftHistory(draftId) {
-    const retain = (entry) => entry.kind !== "edit" || entry.draftId !== draftId;
-    undoStack = undoStack.filter(retain);
-    redoStack = redoStack.filter(retain);
-    notify();
-}
-export function discardCanvasHistory(cardId) {
-    const retain = (entry) => entry.kind !== "canvas" || !entry.cardIds.includes(cardId);
-    undoStack = undoStack.filter(retain);
-    const discarded = redoStack.filter((entry) => !retain(entry));
-    redoStack = redoStack.filter(retain);
-    for (const entry of discarded)
-        if (entry.kind === "canvas")
-            entry.dispose();
-    notify();
+    sessionTimeline.discardDraftHistory(draftId);
 }
 export function clearSessionUndoHistory() {
-    const discarded = [...undoStack, ...redoStack];
-    undoStack = [];
-    redoStack = [];
-    for (const entry of discarded)
-        if (entry.kind === "canvas")
-            entry.dispose();
-    notify();
+    sessionTimeline.clear();
 }
 export function releaseDetachedIterations() {
-    discardRedo();
-    for (const entry of undoStack)
-        if (entry.kind === "canvas")
-            entry.dispose();
-    notify();
+    sessionTimeline.releaseDetachedIterations();
 }
 export function createChangeHistoryGroup() {
-    const group = Symbol("change-history-group");
-    return (update) => {
-        const previous = activeGroup;
-        activeGroup = group;
-        try {
-            update();
-        }
-        finally {
-            activeGroup = previous;
-        }
-    };
+    return sessionTimeline.createGroup();
 }

package/dist/internal/agent-protocol.d.ts

@@ -1,12 +1,5 @@
-/**
- * Public, host-neutral contracts shared by the Nudge browser inspector and
- * its local MCP companion.
- *
- * This module deliberately has no Node, browser, MCP SDK, or framework
- * imports. Hosts can use the same validation and message shapes without
- * pulling the companion into a browser bundle.
- */
-export declare const AGENT_PROTOCOL_VERSION: 2;
+/** Host-neutral contracts shared by the browser inspector and the local MCP companion; no Node, browser, MCP SDK, or framework imports. */
+export declare const AGENT_PROTOCOL_VERSION: 3;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
     readonly workspaceRoot: 4096;
@@ -35,16 +28,21 @@ export declare const AGENT_PROTOCOL_LIMITS: {
     readonly routeTitle: 512;
     readonly routeCount: 64;
     readonly canvasCardCount: 128;
+    readonly agentClientName: 120;
 };
-/**
- * Returns the default project-specific loopback port used by the CLI.
- *
- * The value is deterministic so a browser can probe the companion without a
- * port file, while the range stays high enough to avoid common dev servers.
- * Callers may still override it with an explicit port when a collision occurs.
- */
-export declare function defaultBridgePort(projectId: string): number;
 export type AgentProtocolVersion = typeof AGENT_PROTOCOL_VERSION;
+/** Stable loopback endpoint names shared by the browser client and the MCP bridge. */
+export declare const BRIDGE_ENDPOINTS: {
+    readonly health: "/health";
+    readonly pair: "/pair";
+    readonly takeover: "/takeover";
+    readonly events: "/events";
+    readonly prompt: "/prompt";
+    readonly status: "/status";
+    readonly canvasAcknowledgement: "/canvas/ack";
+    readonly disconnect: "/disconnect";
+};
+export type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
 /** A project identity is the pairing boundary for one companion process. */
 export interface AgentProjectIdentity {
     readonly projectId: string;
@@ -61,14 +59,12 @@ export interface AgentRoute {
 }
 /** The owner marker lets the browser remove only groups created by the agent. */
 export type CanvasGroupOwner = "agent" | "user";
-/** A browser-reported comparison group. */
 export interface CanvasGroup {
     readonly id: string;
     readonly label: string;
     readonly owner: CanvasGroupOwner;
     readonly routes: readonly AgentRoute[];
 }
-/** A compact, serialisable Canvas snapshot returned by the browser. */
 export interface CanvasState {
     readonly mode: "inspect" | "canvas";
     readonly groups: readonly CanvasGroup[];
@@ -164,14 +160,14 @@ export interface AgentSketchAttachment extends AgentSketchMetadata {
 export interface AgentDeliveredPrompt extends AgentPromptRequest {
     readonly attachments?: readonly AgentSketchAttachment[];
 }
-export type AgentRequestStatus = "working" | "completed" | "failed" | "interrupted";
+export type AgentRequestStatus = "delivered" | "working" | "completed" | "failed" | "interrupted";
 export interface AgentRequestOutcome {
     readonly requestId: string;
-    readonly status: AgentRequestStatus;
+    readonly status: Exclude<AgentRequestStatus, "delivered">;
     readonly summary?: string;
     readonly error?: string;
 }
-export type AgentConnectionState = "offline" | "listening" | "paired" | "working";
+export type AgentConnectionState = "offline" | "listening" | "paired" | "delivered" | "working";
 export interface AgentStatusSnapshot {
     readonly protocolVersion: AgentProtocolVersion;
     readonly projectId: string;
@@ -269,7 +265,7 @@ export interface StatusEventRequest {
 }
 export interface AgentStatusUpdate {
     readonly requestId: string;
-    readonly status: AgentRequestStatus;
+    readonly status: Exclude<AgentRequestStatus, "delivered">;
     readonly summary?: string;
     readonly error?: string;
 }
@@ -277,26 +273,33 @@ export interface ProtocolErrorShape {
     readonly code: string;
     readonly message: string;
 }
-/**
- * Returns a canonical origin or null. Credentials, paths, and fragments are
- * rejected so the browser cannot broaden the pairing boundary accidentally.
- */
+/** Options a development host passes to the optional project bridge. */
+export interface ProjectBridgeStartOptions {
+    readonly appRoot: string;
+    readonly projectId: string;
+    readonly origin: string;
+    /** Other explicit browser origins, such as loopback aliases on the same port. */
+    readonly allowedOrigins?: readonly string[];
+}
+/** The started project bridge as seen by the development host that owns it. */
+export interface ProjectBridgeHandle {
+    readonly browser: {
+        readonly projectId: string;
+        readonly origin: string;
+        readonly bridgeUrl: string;
+    };
+    close(): Promise<void>;
+}
+/** The `@nudge-ui/mcp/project` export; hosts load it dynamically, so this is the only compile-time link between the packages. */
+export type StartProjectBridge = (options: ProjectBridgeStartOptions) => Promise<ProjectBridgeHandle>;
+/** Canonical origin or null; credentials, paths, and fragments are rejected so pairing cannot broaden accidentally. */
 export declare function canonicalOrigin(value: unknown): string | null;
-/** Returns true only for exact, canonical HTTP(S) origins. */
 export declare function isCanonicalOrigin(value: unknown): value is string;
-/**
- * Checks an origin against an explicit allow-list. An empty allow-list does
- * not mean wildcard access; callers must choose an origin before pairing.
- */
+/** An empty allow-list is not wildcard access; callers must choose an origin before pairing. */
 export declare function isAllowedOrigin(value: unknown, allowedOrigins: readonly string[]): value is string;
-/**
- * Validates an agent route and ensures it belongs to the paired origin.
- * Fragments are retained because they are useful initial Canvas locations.
- */
+/** Fragments are retained because they are useful initial Canvas locations. */
 export declare function isSameOriginRoute(value: unknown, origin: string): value is AgentRoute;
-/** Validates and normalises route values for a presentation command. */
 export declare function validateRoutes(value: unknown, origin: string): AgentRoute[];
-/** Validates the fields shared by every companion message. */
 export declare function isProtocolVersion(value: unknown): value is AgentProtocolVersion;
 export declare function isProjectIdentity(value: unknown): value is AgentProjectIdentity;
 export declare function isAgentSketchCaptureMetadata(value: unknown): value is AgentSketchCaptureMetadata;
@@ -309,5 +312,17 @@ export declare function isAgentStatusUpdate(value: unknown): value is AgentStatu
 export declare function isCanvasState(value: unknown): value is CanvasState;
 export declare function isCanvasGroup(value: unknown): value is CanvasGroup;
 export declare function isCanvasCommand(value: unknown): value is CanvasCommand;
+export declare function isAgentDeliveredPrompt(value: unknown): value is AgentDeliveredPrompt;
+/** A successful result never carries an error. */
+export declare function isCanvasCommandResult(value: unknown): value is CanvasCommandResult;
+export declare function deriveConnectionState(status: Pick<AgentStatusSnapshot, "listenerActive" | "paired" | "request">): AgentConnectionState;
+/** Unknown fields are dropped and the connection state is recomputed, so a snapshot cannot claim a state its own fields contradict. */
+export declare function decodeAgentStatusSnapshot(value: unknown): AgentStatusSnapshot | null;
+/** A Canvas command is passed through as received: the Canvas controller validates it so a malformed command still receives an error acknowledgement. */
+export declare function decodeBridgeEvent(value: unknown): BridgeEvent | null;
+/** Decodes a pairing or takeover response for the exact project and origin requested. */
+export declare function decodePairingResponse(value: unknown, expected: Pick<PairingRequest, "projectId" | "origin">): PairingResponse | null;
+/** Decodes the accepted-prompt response for the project that dispatched it. */
+export declare function decodePromptDispatchResponse(value: unknown, projectId: string): PromptDispatchResponse | null;
 /** Creates a stable protocol error shape without exposing thrown values. */
 export declare function protocolError(code: string, message: string): ProtocolErrorShape;