nudge-ui 0.2.2 → 0.2.4

package/dist/inspector/workspace/controller.js

@@ -0,0 +1,66 @@
+import { getCanvasCards, getFocusedCardId, getSelectedCardId, subscribe as subscribeCanvas, setCanvasHistoryActivator, } from "../canvas/canvasStore.js";
+import { subscribeCanvasView } from "../canvas/viewStore.js";
+import { loadComments } from "../comments/store.js";
+import { loadDrafts, activateDraft, activateDraftForCard, draftIdForCard, subscribeDrafts } from "../drafts/store.js";
+import { applicationTarget, targetKey } from "../drafts/model.js";
+import { getActiveDraftChanges } from "../changes/draftChanges.js";
+import { hydrateSession, enableAutoSave, scheduleAutoSave, flushAutoSave, resetAutoSave, } from "../canvas/sessionStore.js";
+import { releaseLease } from "../canvas/workspaceLease.js";
+import { subscribeClipboardHandoff } from "../prompt/clipboardHandoff.js";
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+import { releaseDetachedIterations } from "./timeline.js";
+export function startWorkspaceController() {
+    const config = getNudgeUiRuntimeConfig();
+    const persistent = config.demo !== true;
+    loadComments();
+    loadDrafts(config.projectId, { persistent });
+    const result = persistent ? hydrateSession() : { restored: false };
+    const save = persistent ? scheduleAutoSave : () => undefined;
+    let active = "";
+    const synchronize = () => {
+        const cardId = getSelectedCardId() ?? getFocusedCardId() ?? getCanvasCards()[0]?.id;
+        const draftId = (cardId && draftIdForCard(cardId)) || targetKey(applicationTarget());
+        const next = `${cardId ?? ""}\n${draftId}`;
+        if (next === active && getActiveDraftChanges().draftId === draftId)
+            return;
+        active = next;
+        activateDraft(draftId, cardId);
+    };
+    synchronize();
+    setCanvasHistoryActivator(activateDraftForCard);
+    if (persistent)
+        enableAutoSave();
+    const stopCanvas = subscribeCanvas(() => {
+        synchronize();
+        save();
+    });
+    const stopView = subscribeCanvasView(save);
+    const stopDrafts = subscribeDrafts(save);
+    const stopClipboard = subscribeClipboardHandoff(save);
+    const beforeunload = () => {
+        flushAutoSave();
+        releaseLease();
+    };
+    const pagehide = (event) => {
+        flushAutoSave();
+        if (!event.persisted)
+            releaseDetachedIterations();
+    };
+    if (persistent)
+        window.addEventListener("beforeunload", beforeunload);
+    window.addEventListener("pagehide", pagehide);
+    return {
+        restored: result.restored,
+        dispose() {
+            flushAutoSave();
+            stopCanvas();
+            stopView();
+            stopDrafts();
+            stopClipboard();
+            window.removeEventListener("beforeunload", beforeunload);
+            window.removeEventListener("pagehide", pagehide);
+            setCanvasHistoryActivator(() => undefined);
+            resetAutoSave();
+        },
+    };
+}

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

@@ -0,0 +1,42 @@
+import { type AgentClient } from "../agent/client.js";
+import type { AgentSketchMetadata } from "../agent/protocol.js";
+import { type HandoffSnapshot } from "../agent/verification.js";
+import { type ElementComment } from "../comments/store.js";
+import { type FrameworkHints } from "../prompt/generatePrompt.js";
+import { type SketchClipboardHandoffSnapshot } from "../sketch/handoff.js";
+import type { SketchQueueItem } from "../sketch/model.js";
+export interface HandoffRequest {
+    readonly cardId: string | null;
+    readonly hints: FrameworkHints;
+    readonly customInstructions: string;
+    readonly pendingSketches: readonly SketchQueueItem[];
+}
+export interface PreparedHandoff extends HandoffSnapshot {
+    readonly prompt: string;
+    readonly comments: readonly ElementComment[];
+    readonly sketches: SketchClipboardHandoffSnapshot | null;
+    readonly sketchMetadata: readonly AgentSketchMetadata[];
+}
+export type HandoffOutcome = {
+    readonly kind: "sent";
+} | {
+    readonly kind: "copied";
+}
+/** The agent rejected sketch attachments; the prompt can still be copied. */
+ | {
+    readonly kind: "sketch-failed";
+    readonly handoff: PreparedHandoff;
+    readonly error: string;
+};
+type PromptDispatcher = Pick<AgentClient, "dispatchPrompt" | "getSnapshot">;
+export declare function prepareHandoff(request: HandoffRequest): Promise<PreparedHandoff>;
+export declare function prepareIterationImplementationPrompt(request: HandoffRequest): Promise<string>;
+/** Copies a prompt and records the checkpoint that later clipboard verification reconciles. */
+export declare function copyHandoff(handoff: PreparedHandoff): Promise<void>;
+/**
+ * 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.
+ */
+export declare function deliverHandoff(handoff: PreparedHandoff, projectId: string, agent: PromptDispatcher | null): Promise<HandoffOutcome>;
+export {};

package/dist/inspector/workspace/handoff.js

@@ -0,0 +1,115 @@
+import { beginActivityDispatch } from "../agent/activity.js";
+import { createPromptRevision } from "../agent/client.js";
+import { captureHandoffOwner, discardAgentDispatch, recordAgentDispatch } from "../agent/verification.js";
+import { htmlIterationImplementationPrompt, htmlIterationPrompt } from "../iterations/prompt.js";
+import { getCanvasCardLabel, getCanvasCards } from "../canvas/canvasStore.js";
+import { getCommentsForTarget, markCommentsHandedOff } from "../comments/store.js";
+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 { recordClipboardHandoff } from "../prompt/clipboardHandoff.js";
+import { copyToClipboard } from "../prompt/copyToClipboard.js";
+import { generatePrompt } from "../prompt/generatePrompt.js";
+import { createSketchAttachments, createSketchHandoffSnapshot, sketchMetadataForHandoff, } from "../sketch/handoff.js";
+import { markSketchesDispatching, markSketchesHandingOff, settleSketchDispatch } from "../sketch/store.js";
+async function prepareDraftHandoff(request) {
+    const owner = captureHandoffOwner(request.cardId);
+    const target = owner.target;
+    const comments = [...getCommentsForTarget(target)];
+    let { changes, structuralChanges } = getDraftChanges(owner.draftId);
+    if (target.kind === "html") {
+        const frame = request.cardId ? getRegisteredFrames().get(request.cardId) : undefined;
+        if (!request.cardId || !frame)
+            throw new Error("The HTML iteration is still loading. Try again when the frame is ready.");
+        ({ changes, structuralChanges } = await prepareHtmlIterationHandoff(request.cardId, target.artifactId, frame));
+    }
+    const sketches = createSketchHandoffSnapshot(request.pendingSketches);
+    const sketchMetadata = sketchMetadataForHandoff(sketches);
+    return { owner, changes: [...changes], structuralChanges: [...structuralChanges], comments, sketches, sketchMetadata };
+}
+export async function prepareHandoff(request) {
+    const handoff = await prepareDraftHandoff(request);
+    const { owner: { target }, changes, structuralChanges, sketchMetadata, comments } = handoff;
+    const hints = target.kind === "html" ? { ...request.hints, framework: "HTML" } : request.hints;
+    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}`;
+    return { ...handoff, prompt };
+}
+export async function prepareIterationImplementationPrompt(request) {
+    const cards = getCanvasCards();
+    const card = cards.find((candidate) => candidate.id === request.cardId);
+    if (card?.content.kind !== "iteration")
+        throw new Error("Select an HTML iteration to implement in the app.");
+    const label = getCanvasCardLabel(card, cards);
+    const page = applicationTarget(card.content.sourceUrl).route;
+    const { changes, structuralChanges, sketchMetadata, comments } = await prepareDraftHandoff(request);
+    const instructions = request.customInstructions.trim();
+    const generated = changes.length + structuralChanges.length + sketchMetadata.length + comments.length > 0
+        ? generatePrompt([...changes], request.hints, structuralChanges, instructions, sketchMetadata, comments)
+        : instructions ? `## Custom instructions\n\n${instructions}` : "";
+    return htmlIterationImplementationPrompt(card.content.artifactId, label, page, generated);
+}
+/** Copies a prompt and records the checkpoint that later clipboard verification reconciles. */
+export async function copyHandoff(handoff) {
+    await copyToClipboard(handoff.prompt);
+    markCommentsHandedOff(handoff.comments);
+    const { owner, changes, structuralChanges } = handoff;
+    if (owner.target.kind === "application" && changes.length + structuralChanges.length > 0) {
+        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.
+ */
+export async function deliverHandoff(handoff, projectId, agent) {
+    if (agent) {
+        const outcome = await dispatchHandoff(handoff, projectId, agent);
+        if (outcome)
+            return outcome;
+    }
+    await copyHandoff(handoff);
+    return { kind: "copied" };
+}
+async function dispatchHandoff(handoff, projectId, agent) {
+    const { owner, changes, structuralChanges, sketches } = handoff;
+    const revision = createPromptRevision(changes, structuralChanges, [...handoff.sketchMetadata, ...handoff.comments]);
+    const entries = sketches?.entries.map((entry) => ({ id: entry.id, revision: entry.revision })) ?? [];
+    recordAgentDispatch(revision, changes, structuralChanges, owner);
+    const clientDispatchId = sketches?.localBatchId ?? `dispatch-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    try {
+        let attachments = undefined;
+        if (sketches) {
+            await markSketchesDispatching(entries, revision, sketches.localBatchId);
+            attachments = await createSketchAttachments(sketches);
+        }
+        beginActivityDispatch(projectId, clientDispatchId, owner.frameIds, owner.target);
+        const response = await agent.dispatchPrompt(handoff.prompt, revision, {
+            clientDispatchId,
+            ...(attachments === undefined ? {} : { attachments }),
+        });
+        if (response) {
+            markCommentsHandedOff(handoff.comments);
+            if (sketches)
+                await markSketchesHandingOff(entries, revision, sketches.localBatchId, response.request.requestId);
+            return { kind: "sent" };
+        }
+        discardAgentDispatch(revision);
+        if (!sketches)
+            return null;
+        await settleSketchDispatch(revision, "failed", undefined, sketches.localBatchId);
+        const latest = agent.getSnapshot();
+        return { kind: "sketch-failed", handoff, error: latest.request?.error ?? latest.error ?? "The agent did not accept the sketch attachments." };
+    }
+    catch (error) {
+        discardAgentDispatch(revision);
+        if (!sketches)
+            return null;
+        await settleSketchDispatch(revision, "failed", undefined, sketches.localBatchId).catch(() => undefined);
+        return { kind: "sketch-failed", handoff, error: error instanceof Error ? error.message : "The sketch could not be sent to the agent." };
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type ChangeRecord } from "../changes/changesLog.js";
+import type { StructuralChange } from "../changes/structuralTypes.js";
+import { type HandoffSnapshot } from "../agent/verification.js";
+import { type ElementComment } from "../comments/store.js";
+import type { DraftTarget } from "../drafts/model.js";
+/** Handed-off work that verification has not confirmed and the user has not changed since. */
+export interface SentItems {
+    readonly draftId: string;
+    readonly changes: readonly ChangeRecord[];
+    readonly structuralChanges: readonly StructuralChange[];
+    readonly comments: readonly ElementComment[];
+}
+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;

package/dist/inspector/workspace/sentItems.js

@@ -0,0 +1,51 @@
+import { changeKey } from "../changes/model.js";
+import { commitDraftContents } from "../changes/changesLog.js";
+import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
+import { unchangedHandoffRecords } from "../agent/verification.js";
+import { getClipboardHandoffRecords } from "../prompt/clipboardHandoff.js";
+import { getComments, getCommentsForTarget, removeComment, saveComment } from "../comments/store.js";
+export function getSentItems(draftId, target, agentDispatch) {
+    const clipboard = getClipboardHandoffRecords(draftId);
+    const agent = agentDispatch?.owner.draftId === draftId
+        ? unchangedHandoffRecords(agentDispatch)
+        : { changes: [], structuralChanges: [] };
+    const changes = new Map([...clipboard.changes, ...agent.changes].map((change) => [changeKey(change), change]));
+    const structuralChanges = new Map([...clipboard.structuralChanges, ...agent.structuralChanges].map((change) => [change.id, change]));
+    return {
+        draftId,
+        changes: [...changes.values()],
+        structuralChanges: [...structuralChanges.values()],
+        comments: getCommentsForTarget(target).filter((comment) => comment.handedOff),
+    };
+}
+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.
+ */
+export function clearSentItems(items) {
+    const current = getActiveDraftChanges();
+    if (current.draftId !== items.draftId || sentItemCount(items) === 0)
+        return null;
+    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;
+    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

@@ -0,0 +1,30 @@
+import type { DraftContents } from "../changes/draftChanges.js";
+export interface EditHistoryEntry {
+    readonly kind: "edit";
+    readonly draftId: string;
+    readonly group?: symbol;
+    readonly before: DraftContents;
+    readonly after: DraftContents;
+    readonly activate?: () => void;
+}
+export interface CanvasHistoryEntry {
+    readonly kind: "canvas";
+    readonly cardIds: readonly string[];
+    readonly undo: () => void;
+    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;
+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 clearSessionUndoHistory(): void;
+export declare function releaseDetachedIterations(): void;
+export declare function createChangeHistoryGroup(): (update: () => void) => void;

package/dist/inspector/workspace/timeline.js

@@ -0,0 +1,108 @@
+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 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;
+}
+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 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();
+}
+export function clearSessionUndoHistory() {
+    const discarded = [...undoStack, ...redoStack];
+    undoStack = [];
+    redoStack = [];
+    for (const entry of discarded)
+        if (entry.kind === "canvas")
+            entry.dispose();
+    notify();
+}
+export function releaseDetachedIterations() {
+    discardRedo();
+    for (const entry of undoStack)
+        if (entry.kind === "canvas")
+            entry.dispose();
+    notify();
+}
+export function createChangeHistoryGroup() {
+    const group = Symbol("change-history-group");
+    return (update) => {
+        const previous = activeGroup;
+        activeGroup = group;
+        try {
+            update();
+        }
+        finally {
+            activeGroup = previous;
+        }
+    };
+}

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

@@ -177,6 +177,8 @@ export interface AgentStatusSnapshot {
     readonly projectId: string;
     readonly connection: AgentConnectionState;
     readonly listenerActive: boolean;
+    /** MCP client name supplied during initialization; absent for older adapters. */
+    readonly agentClientName?: string;
     readonly paired: boolean;
     /** The last paired page, retained only for this process lifetime. */
     readonly pageUrl?: string | null;
@@ -186,7 +188,7 @@ export interface AgentStatusSnapshot {
         readonly error?: string;
     }) | null;
 }
-export type BridgeEventType = "status" | "canvas-command" | "connected" | "disconnected";
+export type BridgeEventType = "activity" | "status" | "canvas-command" | "connected" | "disconnected";
 export interface BridgeStatusEvent {
     readonly type: "status";
     readonly status: AgentStatusSnapshot;
@@ -203,8 +205,23 @@ export interface BridgeCanvasCommandEvent {
     readonly type: "canvas-command";
     readonly command: CanvasCommand;
 }
+/** Temporary attribution for one file operation in an authoritative request. */
+export interface AgentActivity {
+    readonly requestId: string;
+    /** Workspace-relative source path. */
+    readonly file: string;
+    readonly operation: "read" | "edit";
+    readonly line?: number;
+    readonly endLine?: number;
+    readonly componentId?: string;
+}
+export declare function isAgentActivity(value: unknown): value is AgentActivity;
+export interface BridgeActivityEvent {
+    readonly type: "activity";
+    readonly activity: AgentActivity;
+}
 /** Payload delivered to a browser SSE connection. */
-export type BridgeEvent = BridgeStatusEvent | BridgeConnectedEvent | BridgeDisconnectedEvent | BridgeCanvasCommandEvent;
+export type BridgeEvent = BridgeActivityEvent | BridgeStatusEvent | BridgeConnectedEvent | BridgeDisconnectedEvent | BridgeCanvasCommandEvent;
 export interface BridgeEnvelope {
     readonly protocolVersion: AgentProtocolVersion;
     readonly projectId: string;

package/dist/internal/agent-protocol.js

@@ -61,6 +61,19 @@ export const CANVAS_COMMAND_TYPES = [
     "fit-all",
     "remove-group",
 ];
+export function isAgentActivity(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "file", "operation", "line", "endLine", "componentId"]))
+        return false;
+    const line = (value) => Number.isSafeInteger(value) && Number(value) > 0 && Number(value) <= 10_000_000;
+    return nonEmptyString(value.requestId, AGENT_PROTOCOL_LIMITS.requestId)
+        && nonEmptyString(value.file, AGENT_PROTOCOL_LIMITS.workspaceRoot)
+        && !/^(?:[\\/]|[a-z]:)/i.test(value.file) && !/[\\\u0000-\u001f]/.test(value.file)
+        && !value.file.split("/").some((part, index, parts) => !part || part === "." || (part === ".." && parts.slice(0, index).some((previous) => previous !== "..")))
+        && (value.operation === "read" || value.operation === "edit")
+        && (value.line === undefined || line(value.line))
+        && (value.endLine === undefined || (line(value.endLine) && line(value.line) && Number(value.endLine) >= Number(value.line)))
+        && (value.componentId === undefined || nonEmptyString(value.componentId, 512));
+}
 const ORIGIN_PROTOCOLS = new Set(["http:", "https:"]);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);