nudge-ui 0.2.2 → 0.2.3

package/dist/inspector/canvas/agentPresentation.d.ts

@@ -1,5 +1,5 @@
-import { type CanvasCommand, type CanvasCommandResult, type CanvasState } from "../../internal/agent-protocol.js";
-import { type CanvasCard, type CanvasComparisonGroup } from "./canvasStore.js";
+import { type CanvasCommand, type CanvasCommandResult, type CanvasGroup, type CanvasState } from "../../internal/agent-protocol.js";
+import { type CanvasCard } from "./canvasStore.js";
 /**
  * Renderer acknowledgements are deliberately shorter than the companion's
  * request timeout. A controller can therefore receive a useful partial-failure
@@ -24,7 +24,7 @@ export interface AgentPresentationRoute {
     label?: string;
 }
 export type AgentPresentationRouteInput = string | AgentPresentationRoute;
-export interface PresentAgentComparisonGroupInput {
+export interface PresentAgentRoutesInput {
     label: string;
     routes?: readonly AgentPresentationRouteInput[];
     /** Convenience spelling for direct browser callers. */
@@ -35,8 +35,8 @@ export interface PresentAgentComparisonGroupInput {
     agentId?: string;
     readyTimeoutMs?: number;
 }
-export interface AgentComparisonGroupPresentation {
-    group: CanvasComparisonGroup;
+export interface AgentRoutesPresentation {
+    group: CanvasGroup;
     cards: CanvasCard[];
     readiness: AgentRendererReadiness;
 }
@@ -54,8 +54,8 @@ export declare function forgetAgentRendererReadiness(cardIds: readonly string[])
 export declare function waitForAgentRendererReadiness(cardIds: readonly string[], timeoutMs?: number): Promise<AgentRendererReadiness>;
 /** Returns the compact state shape shared with the companion bridge. */
 export declare function readCanvasState(): CanvasState;
-export declare function presentAgentComparisonGroup(input: PresentAgentComparisonGroupInput): Promise<AgentComparisonGroupPresentation>;
-export declare function focusAgentComparisonGroup(groupId: string, viewport?: {
+export declare function presentAgentRoutes(input: PresentAgentRoutesInput): Promise<AgentRoutesPresentation>;
+export declare function focusAgentGroup(groupId: string, viewport?: {
     width: number;
     height: number;
 }): AgentPresentationState;
@@ -63,7 +63,7 @@ export declare function fitAgentCanvas(viewport?: {
     width: number;
     height: number;
 }): AgentPresentationState;
-export declare function removeOwnAgentComparisonGroup(groupId: string, agentId?: string): AgentPresentationState;
+export declare function removeOwnAgentGroup(groupId: string, agentId?: string): AgentPresentationState;
 /** The only command vocabulary accepted by the browser presentation adapter. */
 export type AgentPresentationCommand = CanvasCommand;
 export type AgentPresentationCommandResponse = CanvasCommandResult;

package/dist/inspector/canvas/agentPresentation.js

@@ -1,8 +1,11 @@
+import { contentSourceUrl } from "./frameContent.js";
 import { AGENT_PROTOCOL_LIMITS, isCanvasCommand, validateRoutes, } from "../../internal/agent-protocol.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 import { canWriteWorkspace } from "./workspaceLease.js";
-import { appendCanvasComparisonGroup, fitAllCards, focusCard, focusCanvasCards, getCanvasCards, getCanvasComparisonGroup, getCanvasComparisonGroups, getCanvasMode, getFocusedCardId, removeCanvasComparisonGroup, setCanvasMode, } from "./canvasStore.js";
+import { removeFrame } from "../workspace/commands.js";
+import { appendAgentRouteCards, getFrameGroup, getFrameGroups, setFrameGroup, removeFrameGroup, batchCanvasChanges, fitAllCards, focusCard, focusCanvasCards, getCanvasCards, getFocusedCardId, } from "./canvasStore.js";
+import { getCanvasMode, setCanvasMode } from "./viewStore.js";
 /**
  * Renderer acknowledgements are deliberately shorter than the companion's
  * request timeout. A controller can therefore receive a useful partial-failure
@@ -45,11 +48,11 @@ function createGroupId() {
 }
 function validateLabel(value) {
     if (!isNonEmptyString(value)) {
-        throw new AgentPresentationError("invalid-label", "A comparison group label is required.");
+        throw new AgentPresentationError("invalid-label", "A route group label is required.");
     }
     const label = value.trim();
     if (label.length > MAX_GROUP_LABEL_LENGTH || /[\u0000-\u001f\u007f]/.test(label)) {
-        throw new AgentPresentationError("invalid-label", `Comparison group labels must be between 1 and ${MAX_GROUP_LABEL_LENGTH} printable characters.`);
+        throw new AgentPresentationError("invalid-label", `Route group labels must be between 1 and ${MAX_GROUP_LABEL_LENGTH} printable characters.`);
     }
     return label;
 }
@@ -57,17 +60,17 @@ function routeForValidation(value) {
     if (typeof value === "string")
         return { url: value };
     if (!isRecord(value)) {
-        throw new AgentPresentationError("invalid-route", "Each comparison route must be a URL object.");
+        throw new AgentPresentationError("invalid-route", "Each presented route must be a URL object.");
     }
     return value;
 }
 function normalizeRoutes(input) {
     const rawRoutes = input.routes ?? input.urls;
     if (!rawRoutes || rawRoutes.length === 0) {
-        throw new AgentPresentationError("invalid-route", "At least one comparison route is required.");
+        throw new AgentPresentationError("invalid-route", "At least one presented route is required.");
     }
     if (rawRoutes.length > MAX_PRESENTATION_ROUTES) {
-        throw new AgentPresentationError("too-many-routes", `A comparison group may contain at most ${MAX_PRESENTATION_ROUTES} routes.`);
+        throw new AgentPresentationError("too-many-routes", `A route group may contain at most ${MAX_PRESENTATION_ROUTES} routes.`);
     }
     try {
         return validateRoutes(rawRoutes.map((route) => {
@@ -80,7 +83,7 @@ function normalizeRoutes(input) {
         }), window.location.origin);
     }
     catch (error) {
-        throw new AgentPresentationError("invalid-route", error instanceof Error ? error.message : "Comparison routes must be same-origin URLs.");
+        throw new AgentPresentationError("invalid-route", error instanceof Error ? error.message : "Presented routes must be same-origin URLs.");
     }
 }
 function ensureDevelopment() {
@@ -187,18 +190,24 @@ export function waitForAgentRendererReadiness(cardIds, timeoutMs = DEFAULT_RENDE
         settleReadinessWaiters();
     });
 }
-function toProtocolGroup(group) {
+function toProtocolGroup(groupId) {
+    const group = getFrameGroup(groupId);
     return {
-        id: group.id,
-        label: group.label,
+        id: groupId,
+        label: group?.label ?? "",
         owner: "agent",
-        routes: group.routes.map((route) => ({
+        routes: (group?.routes ?? []).map((route) => ({
             url: route.url,
             ...(route.title === undefined || route.title === null ? {} : { title: route.title }),
             ...(route.label === undefined ? {} : { label: route.label }),
         })),
     };
 }
+function groupCardIds(groupId) {
+    return getCanvasCards()
+        .filter((card) => card.groupId === groupId)
+        .map((card) => card.id);
+}
 /** Returns the compact state shape shared with the companion bridge. */
 export function readCanvasState() {
     const focusedCardId = getFocusedCardId();
@@ -207,12 +216,16 @@ export function readCanvasState() {
         : undefined;
     return {
         mode: getCanvasMode(),
-        groups: getCanvasComparisonGroups().map(toProtocolGroup),
-        focusedGroupId: focusedCard?.comparisonGroupId ?? null,
-        focusedRouteUrl: focusedCard?.url ?? null,
+        groups: getFrameGroups().map((group) => group.id)
+            .filter((groupId) => groupCardIds(groupId).length > 0)
+            .map(toProtocolGroup),
+        focusedGroupId: focusedCard?.groupId && getFrameGroup(focusedCard.groupId)?.kind === "agent"
+            ? focusedCard.groupId
+            : null,
+        focusedRouteUrl: focusedCard ? contentSourceUrl(focusedCard.content) : null,
     };
 }
-export async function presentAgentComparisonGroup(input) {
+export async function presentAgentRoutes(input) {
     ensureDevelopment();
     ensureWritable();
     if (activePresentation) {
@@ -228,53 +241,50 @@ export async function presentAgentComparisonGroup(input) {
         }
         const groupId = input.groupId ?? createGroupId();
         if (!isNonEmptyString(groupId) || groupId.length > AGENT_PROTOCOL_LIMITS.groupId) {
-            throw new AgentPresentationError("invalid-command", "A comparison group ID is required.");
+            throw new AgentPresentationError("invalid-command", "A route group ID is required.");
         }
-        if (getCanvasComparisonGroup(groupId)) {
-            throw new AgentPresentationError("group-id-conflict", `Comparison group ${groupId} already exists.`);
+        const collides = getFrameGroup(groupId) !== undefined
+            || getCanvasCards().some((card) => card.groupId === groupId);
+        if (collides) {
+            throw new AgentPresentationError("group-id-conflict", `Route group ${groupId} already exists.`);
         }
         const readyTimeoutMs = clampReadyTimeout(input.readyTimeoutMs);
         // Opening Canvas for an agent group appends only the requested routes. It
         // never creates or repositions the current Inspect route.
         setCanvasMode("canvas");
-        const appended = appendCanvasComparisonGroup({
-            id: groupId,
-            label,
-            owner: "agent",
-            agentId,
-            routes: routes.map((route) => ({
+        const cards = batchCanvasChanges(() => {
+            setFrameGroup({ id: groupId, kind: "agent", label, agentId, routes: routes.map((route) => ({ ...route })) });
+            return appendAgentRouteCards(groupId, routes.map((route) => ({
                 url: route.url,
                 ...(route.title === undefined ? {} : { title: route.title }),
-                ...(route.label === undefined ? {} : { label: route.label }),
-            })),
+            })));
         });
-        if (!appended) {
-            throw new AgentPresentationError("group-id-conflict", `Comparison group ${groupId} already exists.`);
+        if (!cards) {
+            throw new AgentPresentationError("group-id-conflict", `Route group ${groupId} already exists.`);
         }
-        const cardIds = appended.cards.map((card) => card.id);
+        const cardIds = cards.map((card) => card.id);
         beginRendererReadiness(cardIds);
         const readiness = await waitForAgentRendererReadiness(cardIds, readyTimeoutMs);
-        return { ...appended, readiness };
+        return { group: toProtocolGroup(groupId), cards, readiness };
     }
     finally {
         activePresentation = false;
     }
 }
 function groupCards(groupId) {
-    const group = getCanvasComparisonGroup(groupId);
-    if (!group)
-        throw new AgentPresentationError("group-not-found", `Comparison group ${groupId} was not found.`);
-    const cardIds = new Set(group.cardIds);
-    const cards = getCanvasCards().filter((card) => cardIds.has(card.id));
+    const group = getFrameGroup(groupId);
+    if (group?.kind !== "agent")
+        throw new AgentPresentationError("group-not-found", `Route group ${groupId} was not found.`);
+    const cards = getCanvasCards().filter((card) => card.groupId === groupId);
     if (cards.length === 0) {
-        throw new AgentPresentationError("group-not-found", `Comparison group ${groupId} has no cards.`);
+        throw new AgentPresentationError("group-not-found", `Route group ${groupId} has no cards.`);
     }
-    return { group, cards };
+    return cards;
 }
-export function focusAgentComparisonGroup(groupId, viewport) {
+export function focusAgentGroup(groupId, viewport) {
     ensureDevelopment();
     ensureWritable();
-    const { cards } = groupCards(groupId);
+    const cards = groupCards(groupId);
     focusCard(cards[0].id);
     focusCanvasCards(cards.map((card) => card.id), viewport);
     return readCanvasState();
@@ -285,17 +295,19 @@ export function fitAgentCanvas(viewport) {
     fitAllCards(viewport);
     return readCanvasState();
 }
-export function removeOwnAgentComparisonGroup(groupId, agentId = DEFAULT_AGENT_ID) {
+export function removeOwnAgentGroup(groupId, agentId = DEFAULT_AGENT_ID) {
     ensureDevelopment();
     ensureWritable();
-    const group = getCanvasComparisonGroup(groupId);
-    if (!group)
-        throw new AgentPresentationError("group-not-found", `Comparison group ${groupId} was not found.`);
-    if (group.owner !== "agent" || group.agentId !== agentId) {
-        throw new AgentPresentationError("not-group-owner", `Agent ${agentId} cannot remove comparison group ${groupId}.`);
+    const group = getFrameGroup(groupId);
+    if (group?.kind !== "agent")
+        throw new AgentPresentationError("group-not-found", `Route group ${groupId} was not found.`);
+    if (group.agentId !== agentId) {
+        throw new AgentPresentationError("not-group-owner", `Agent ${agentId} cannot remove route group ${groupId}.`);
     }
-    const cardIds = [...group.cardIds];
-    removeCanvasComparisonGroup(groupId);
+    const cardIds = groupCardIds(groupId);
+    for (const cardId of cardIds)
+        removeFrame(cardId);
+    removeFrameGroup(groupId);
     forgetAgentRendererReadiness(cardIds);
     return readCanvasState();
 }
@@ -329,7 +341,7 @@ async function executeCanvasCommand(command, agentId) {
             ensureDevelopment();
             return { commandId: command.commandId, ok: true, state: readCanvasState() };
         case "present-routes": {
-            const presentation = await presentAgentComparisonGroup({
+            const presentation = await presentAgentRoutes({
                 groupId: command.groupId,
                 label: command.label,
                 routes: command.routes,
@@ -341,7 +353,7 @@ async function executeCanvasCommand(command, agentId) {
                     commandId: command.commandId,
                     ok: true,
                     state,
-                    group: toProtocolGroup(presentation.group),
+                    group: presentation.group,
                 };
             }
             const failed = presentation.readiness.failedCardIds.length > 0;
@@ -349,7 +361,7 @@ async function executeCanvasCommand(command, agentId) {
                 commandId: command.commandId,
                 ok: false,
                 state,
-                group: toProtocolGroup(presentation.group),
+                group: presentation.group,
                 error: {
                     code: failed ? "renderer-error" : "renderer-timeout",
                     message: failed
@@ -362,7 +374,7 @@ async function executeCanvasCommand(command, agentId) {
             return {
                 commandId: command.commandId,
                 ok: true,
-                state: focusAgentComparisonGroup(command.groupId),
+                state: focusAgentGroup(command.groupId),
             };
         case "fit-all":
             return {
@@ -374,7 +386,7 @@ async function executeCanvasCommand(command, agentId) {
             return {
                 commandId: command.commandId,
                 ok: true,
-                state: removeOwnAgentComparisonGroup(command.groupId, agentId),
+                state: removeOwnAgentGroup(command.groupId, agentId),
             };
     }
 }

package/dist/inspector/canvas/canvasGestures.d.ts

@@ -1,4 +1,4 @@
-import { type CanvasCamera } from "./canvasStore.js";
+import { type CanvasCamera } from "./viewStore.js";
 export declare const ZOOM_WHEEL_FACTOR = 1.02;
 export interface ClientPoint {
     x: number;

package/dist/inspector/canvas/canvasGestures.js

@@ -1,4 +1,4 @@
-import { MAX_CAMERA_ZOOM, MIN_CAMERA_ZOOM, } from "./canvasStore.js";
+import { MAX_CAMERA_ZOOM, MIN_CAMERA_ZOOM } from "./viewStore.js";
 export const ZOOM_WHEEL_FACTOR = 1.02;
 export function zoomCameraAtPointer(camera, pointer, boardRect, deltaY) {
     const pointerX = pointer.x - boardRect.left;

package/dist/inspector/canvas/canvasStore.d.ts

@@ -1,84 +1,54 @@
+import type { FrameContent } from "./frameContent.js";
+import { type CanvasCamera, type CanvasMode, type CanvasPresentation } from "./viewStore.js";
 import { type NormalizedUrl } from "./normalizeUrl.js";
-export type CanvasMode = "inspect" | "canvas";
-export type CanvasPresentation = "focus" | "canvas";
-export interface CanvasCard {
-    id: string;
-    url: string;
-    /** A controller-requested document load. Renderer metadata must not set this. */
-    navigationUrl?: string;
-    title: string | null;
+export interface FrameGeometry {
     x: number;
     y: number;
     width: number;
     height: number;
-    /** The agent-created comparison group that owns this card, when present. */
-    comparisonGroupId?: string;
 }
-/** A durable, agent-owned collection of Canvas cards. */
-export interface CanvasComparisonGroup {
+export interface CanvasCard extends FrameGeometry {
     id: string;
-    label: string;
-    /** Public protocol marker. Canvas currently exposes only agent-created groups. */
-    owner: "agent";
-    /** Pairing identity used to authorize removal of this group. */
-    agentId: string;
-    cardIds: string[];
-    routes: CanvasComparisonGroupRoute[];
+    content: FrameContent;
+    entrance?: "linked" | "iteration";
+    /** Directly placed iterations skip entrance animation, including on redo. */
+    animateEntrance?: boolean;
+    groupId?: string;
+    title: string | null;
 }
-export interface CanvasComparisonGroupRoute {
-    url: string;
-    title?: string | null;
-    label?: string;
+export interface FrameGroup {
+    readonly id: string;
+    readonly kind: "agent";
+    readonly label: string;
+    readonly agentId: string;
+    readonly routes: readonly {
+        url: string;
+        title?: string;
+        label?: string;
+    }[];
 }
-export interface CanvasCamera {
-    x: number;
-    y: number;
-    zoom: number;
-}
-export declare const MIN_CAMERA_ZOOM = 0.25;
-export declare const MAX_CAMERA_ZOOM = 3;
+export declare function setFrameGroup(group: FrameGroup): void;
+export declare function getFrameGroup(id: string): FrameGroup | undefined;
+export declare function removeFrameGroup(id: string): void;
+export declare function getFrameGroups(): readonly FrameGroup[];
+export declare function isFrameGroup(value: unknown): value is FrameGroup;
 export declare const CARD_GAP = 40;
 export declare const FIT_ALL_PADDING = 80;
 export declare const PRIMARY_CARD_INSET = 40;
 declare function subscribe(cb: () => void): () => void;
-declare function getMode(): CanvasMode;
 declare function getCards(): CanvasCard[];
-declare function getComparisonGroups(): CanvasComparisonGroup[];
-export declare function setCanvasMode(newMode: CanvasMode): void;
-/**
- * Changes how the mounted iframe workspace is presented.
- *
- * Canvas starts from the active card centered in the supplied viewport. Card
- * geometry remains durable, but the camera does not carry over from a prior
- * Canvas session.
- */
-export declare function setCanvasPresentation(next: CanvasPresentation, viewport?: {
-    width: number;
-    height: number;
-}): void;
+export declare function batchCanvasChanges<T>(operation: () => T): T;
 /** Adds one card while retaining the existing placement policy. */
 export declare function addCanvasCard(url: string, title?: string): CanvasCard;
-/**
- * Appends an agent-created comparison group without disturbing existing cards.
- * Callers validate route URLs and labels at the command boundary; this store
- * function only enforces the durable identity and placement invariants.
- */
-export declare function appendCanvasComparisonGroup(input: {
-    id: string;
-    label: string;
-    agentId: string;
-    owner?: "agent";
-    routes: readonly CanvasComparisonGroupRoute[];
-}): {
-    group: CanvasComparisonGroup;
-    cards: CanvasCard[];
-} | null;
-export declare function getCanvasComparisonGroup(id: string): CanvasComparisonGroup | undefined;
-/** Removes a group and exactly the cards owned by that group. */
-export declare function removeCanvasComparisonGroup(id: string): CanvasComparisonGroup | null;
-/** Clears group metadata while leaving ordinary cards intact. */
-export declare function clearCanvasComparisonGroups(): void;
-export declare function removeCanvasCard(id: string): void;
+export declare function appendAgentRouteCards(groupId: string, routes: readonly {
+    url: string;
+    title?: string | null;
+}[]): CanvasCard[] | null;
+/** Connects canvas replay to the draft controller without coupling the stores. */
+export declare function setCanvasHistoryActivator(activate: (cardId: string) => void): void;
+export declare function removeCanvasCard(id: string, { undoable }?: {
+    undoable?: boolean;
+}): void;
 /**
  * Opens one editor target in the iframe workspace without replacing restored
  * cards or their dimensions.
@@ -86,33 +56,30 @@ export declare function removeCanvasCard(id: string): void;
 export declare function activateIframeWorkspace(url: string, viewport: {
     width: number;
     height: number;
+}, options?: {
+    replaceActiveCard?: boolean;
+    preserveIterationFocus?: boolean;
 }): CanvasCard | null;
 export declare function updateCardTitle(id: string, title: string): void;
 export declare function updateCardUrl(id: string, url: string): void;
 export declare function duplicateCard(sourceId: string): CanvasCard | null;
+export declare function addCanvasIteration(sourceId: string, artifactId: string, position?: {
+    x: number;
+    y: number;
+}, animateEntrance?: boolean): CanvasCard | null;
 export declare function resizeCard(id: string, width: number, height: number, position?: {
     readonly x: number;
     readonly y: number;
 }): void;
-export declare function getBoardCamera(): CanvasCamera;
-export declare function setBoardCamera(camera: CanvasCamera): void;
-export declare function updateBoardCamera(partial: Partial<CanvasCamera>): void;
 export declare function fitAllCards(viewport?: {
     width: number;
     height: number;
 }): void;
-/** Fits a selected set of cards while preserving cards outside that set. */
-export declare function fitCanvasCards(cardIds: readonly string[], viewport?: {
-    width: number;
-    height: number;
-}): boolean;
 /** Centers a selected set of cards without changing the current zoom. */
 export declare function focusCanvasCards(cardIds: readonly string[], viewport?: {
     width: number;
     height: number;
 }): boolean;
-export declare function hasFitAllRan(): boolean;
-export declare function resetFitAllFlag(): void;
 export declare function findCardByNormalizedUrl(normalized: NormalizedUrl): CanvasCard | undefined;
 export declare function focusCard(id: string): void;
 export declare function getFocusedCardId(): string | null;
@@ -122,11 +89,8 @@ export declare function getSelectedCardId(): string | null;
 export declare function useSelectedCardId(): string | null;
 export declare function useFocusedCardId(): string | null;
 export declare function setCardPosition(id: string, x: number, y: number): void;
-export declare function hydrateCanvasStore(newMode: CanvasMode, newCards: CanvasCard[], newCamera: CanvasCamera, newComparisonGroups?: CanvasComparisonGroup[], restoredFocusedCardId?: string | null): void;
-export { subscribe, getMode, getCards, getComparisonGroups, getMode as getCanvasMode, getCards as getCanvasCards, getComparisonGroups as getCanvasComparisonGroups, };
-export declare function useCanvasMode(): CanvasMode;
-export declare function useCanvasPresentation(): CanvasPresentation;
-export declare function useCanvasPresentationTransitioning(): boolean;
+export declare function hydrateCanvasStore(newMode: CanvasMode, newCards: CanvasCard[], newCamera: CanvasCamera, restoredFocusedCardId?: string | null, restoredPresentation?: CanvasPresentation, restoredGroups?: readonly FrameGroup[]): void;
+export { subscribe, getCards, getCards as getCanvasCards, };
 export declare function useCanvasCards(): CanvasCard[];
-export declare function useCanvasComparisonGroups(): CanvasComparisonGroup[];
-export declare function useBoardCamera(): CanvasCamera;
+/** Returns a route-based label that distinguishes copies and HTML iterations. */
+export declare function getCanvasCardLabel(card: CanvasCard, frameCards?: readonly CanvasCard[]): string;