nudge-ui 0.2.4 → 0.2.5

package/dist/inspector/workspace/timeline.js

@@ -1,108 +1,130 @@
-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;
+                }
+            };
+        },
+    };
 }
+/** The Workspace's session timeline. */
+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

@@ -6,7 +6,7 @@
  * 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;
+export declare const AGENT_PROTOCOL_VERSION: 3;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
     readonly workspaceRoot: 4096;
@@ -35,15 +35,8 @@ 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;
 /** A project identity is the pairing boundary for one companion process. */
 export interface AgentProjectIdentity {
@@ -164,14 +157,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 +262,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,6 +270,29 @@ export interface ProtocolErrorShape {
     readonly code: string;
     readonly message: string;
 }
+/** 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 `startProjectBridge` export of `@nudge-ui/mcp/project`. Hosts load it
+ * dynamically from the application's own dependencies, so this type is the
+ * only compile-time link between the two packages.
+ */
+export type StartProjectBridge = (options: ProjectBridgeStartOptions) => Promise<ProjectBridgeHandle>;
 /**
  * Returns a canonical origin or null. Credentials, paths, and fragments are
  * rejected so the browser cannot broaden the pairing boundary accidentally.
@@ -309,5 +325,26 @@ 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 Canvas acknowledgement or result; a successful one never carries an error. */
+export declare function isCanvasCommandResult(value: unknown): value is CanvasCommandResult;
+/** The connection state shown for a pairing, a listener, and the current request. */
+export declare function deriveConnectionState(status: Pick<AgentStatusSnapshot, "listenerActive" | "paired" | "request">): AgentConnectionState;
+/**
+ * Decodes a status snapshot from any peer. Unknown fields are dropped and the
+ * connection state is recomputed, so a snapshot can never claim a state its
+ * own fields contradict.
+ */
+export declare function decodeAgentStatusSnapshot(value: unknown): AgentStatusSnapshot | null;
+/**
+ * Decodes the event inside a bridge envelope. A Canvas command is passed
+ * through as received: the Canvas controller validates it so a malformed
+ * command still receives an error acknowledgement instead of a timeout.
+ */
+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;

package/dist/internal/agent-protocol.js

@@ -6,7 +6,7 @@
  * imports. Hosts can use the same validation and message shapes without
  * pulling the companion into a browser bundle.
  */
-export const AGENT_PROTOCOL_VERSION = 2;
+export const AGENT_PROTOCOL_VERSION = 3;
 export const AGENT_PROTOCOL_LIMITS = {
     projectId: 256,
     workspaceRoot: 4096,
@@ -35,25 +35,8 @@ export const AGENT_PROTOCOL_LIMITS = {
     routeTitle: 512,
     routeCount: 64,
     canvasCardCount: 128,
+    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 function defaultBridgePort(projectId) {
-    if (!nonEmptyString(projectId, AGENT_PROTOCOL_LIMITS.projectId)) {
-        throw new TypeError("projectId must be a bounded non-empty string");
-    }
-    let hash = 2_166_136_261;
-    for (let index = 0; index < projectId.length; index += 1) {
-        hash ^= projectId.charCodeAt(index);
-        hash = Math.imul(hash, 16_777_619);
-    }
-    return 30_000 + ((hash >>> 0) % 20_000);
-}
 export const CANVAS_COMMAND_TYPES = [
     "read-state",
     "present-routes",
@@ -421,6 +404,149 @@ export function isCanvasCommand(value) {
             return false;
     }
 }
+export function isAgentDeliveredPrompt(value) {
+    if (!isRecord(value))
+        return false;
+    const { attachments, ...request } = value;
+    return isAgentPromptRequest(request)
+        && (attachments === undefined || (Array.isArray(attachments)
+            && attachments.length <= AGENT_PROTOCOL_LIMITS.sketchCount
+            && attachments.every(isAgentSketchAttachment)));
+}
+function isCanvasCommandError(value) {
+    return isRecord(value) && hasOnlyKeys(value, ["code", "message"])
+        && nonEmptyString(value.code, 128)
+        && typeof value.message === "string" && value.message.length <= AGENT_PROTOCOL_LIMITS.prompt;
+}
+/** A Canvas acknowledgement or result; a successful one never carries an error. */
+export function isCanvasCommandResult(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["commandId", "ok", "state", "group", "error"]))
+        return false;
+    return nonEmptyString(value.commandId, AGENT_PROTOCOL_LIMITS.commandId)
+        && typeof value.ok === "boolean"
+        && (value.state === undefined || isCanvasState(value.state))
+        && (value.group === undefined || isCanvasGroup(value.group))
+        && (value.error === undefined || (!value.ok && isCanvasCommandError(value.error)));
+}
+/** The connection state shown for a pairing, a listener, and the current request. */
+export function deriveConnectionState(status) {
+    if (status.request?.status === "delivered")
+        return "delivered";
+    if (status.request?.status === "working")
+        return "working";
+    if (status.paired)
+        return "paired";
+    if (status.listenerActive)
+        return "listening";
+    return "offline";
+}
+function isRequestStatus(value) {
+    return value === "delivered" || value === "working" || value === "completed" || value === "failed" || value === "interrupted";
+}
+function decodeStatusRequest(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!isRecord(value))
+        return undefined;
+    const { status, summary, error, ...request } = value;
+    if (!isRequestStatus(status) || !isAgentPromptRequest(request)
+        || !optionalString(summary, AGENT_PROTOCOL_LIMITS.prompt)
+        || !optionalString(error, AGENT_PROTOCOL_LIMITS.prompt))
+        return undefined;
+    return {
+        ...request,
+        status,
+        ...(summary === undefined ? {} : { summary }),
+        ...(error === undefined ? {} : { error }),
+    };
+}
+/**
+ * Decodes a status snapshot from any peer. Unknown fields are dropped and the
+ * connection state is recomputed, so a snapshot can never claim a state its
+ * own fields contradict.
+ */
+export function decodeAgentStatusSnapshot(value) {
+    if (!isRecord(value)
+        || value.protocolVersion !== AGENT_PROTOCOL_VERSION
+        || !nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
+        || (value.connection !== "offline" && value.connection !== "listening"
+            && value.connection !== "paired" && value.connection !== "delivered" && value.connection !== "working")
+        || typeof value.listenerActive !== "boolean"
+        || typeof value.paired !== "boolean"
+        || !(value.pageUrl === undefined || value.pageUrl === null
+            || nonEmptyString(value.pageUrl, AGENT_PROTOCOL_LIMITS.routeUrl)))
+        return null;
+    const request = decodeStatusRequest(value.request);
+    if (request === undefined)
+        return null;
+    const fields = { listenerActive: value.listenerActive, paired: value.paired, request };
+    return {
+        protocolVersion: AGENT_PROTOCOL_VERSION,
+        projectId: value.projectId,
+        connection: deriveConnectionState(fields),
+        ...fields,
+        ...(value.pageUrl === undefined ? {} : { pageUrl: value.pageUrl }),
+        ...(typeof value.agentClientName === "string" && value.agentClientName.length > 0
+            ? { agentClientName: value.agentClientName.slice(0, AGENT_PROTOCOL_LIMITS.agentClientName) }
+            : {}),
+    };
+}
+/**
+ * Decodes the event inside a bridge envelope. A Canvas command is passed
+ * through as received: the Canvas controller validates it so a malformed
+ * command still receives an error acknowledgement instead of a timeout.
+ */
+export function decodeBridgeEvent(value) {
+    if (!isRecord(value))
+        return null;
+    switch (value.type) {
+        case "status":
+        case "connected": {
+            const status = decodeAgentStatusSnapshot(value.status);
+            return status ? { type: value.type, status } : null;
+        }
+        case "disconnected":
+            return {
+                type: "disconnected",
+                ...(nonEmptyString(value.reason, AGENT_PROTOCOL_LIMITS.prompt) ? { reason: value.reason } : {}),
+            };
+        case "activity":
+            return isAgentActivity(value.activity) ? { type: "activity", activity: value.activity } : null;
+        case "canvas-command":
+            // SAFETY: the Canvas controller validates the command before acting on it.
+            return isRecord(value.command) ? { type: "canvas-command", command: value.command } : null;
+        default:
+            return null;
+    }
+}
+/** Decodes a pairing or takeover response for the exact project and origin requested. */
+export function decodePairingResponse(value, expected) {
+    if (!isRecord(value)
+        || value.protocolVersion !== AGENT_PROTOCOL_VERSION
+        || value.projectId !== expected.projectId
+        || value.origin !== expected.origin
+        || !nonEmptyString(value.sessionToken, AGENT_PROTOCOL_LIMITS.sessionToken)
+        || !(value.pageUrl === undefined || nonEmptyString(value.pageUrl, AGENT_PROTOCOL_LIMITS.routeUrl)))
+        return null;
+    const status = decodeAgentStatusSnapshot(value.status);
+    if (!status)
+        return null;
+    return {
+        protocolVersion: AGENT_PROTOCOL_VERSION,
+        projectId: expected.projectId,
+        origin: expected.origin,
+        sessionToken: value.sessionToken,
+        ...(value.pageUrl === undefined ? {} : { pageUrl: value.pageUrl }),
+        status,
+    };
+}
+/** Decodes the accepted-prompt response for the project that dispatched it. */
+export function decodePromptDispatchResponse(value, projectId) {
+    if (!isRecord(value) || (value.status !== "delivered" && value.status !== "working") || !isAgentPromptRequest(value.request)
+        || value.request.projectId !== projectId)
+        return null;
+    return { request: value.request, status: value.status };
+}
 /** Creates a stable protocol error shape without exposing thrown values. */
 export function protocolError(code, message) {
     if (!nonEmptyString(code, 128) || !nonEmptyString(message, AGENT_PROTOCOL_LIMITS.prompt)) {