nudge-ui 0.2.0

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

@@ -0,0 +1,108 @@
+import { type NormalizedUrl } from "./normalizeUrl.js";
+export type CanvasMode = "inspect" | "canvas";
+export interface CanvasCard {
+    id: string;
+    url: string;
+    title: string | null;
+    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 {
+    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[];
+}
+export interface CanvasComparisonGroupRoute {
+    url: string;
+    title?: string | null;
+    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 const CARD_GAP = 40;
+export declare const FIT_ALL_PADDING = 80;
+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;
+export declare function enterCanvas(): void;
+export declare function exitCanvas(): void;
+/** Return to inspect mode on a canvas card's route. */
+export declare function exitCanvasToCard(card: CanvasCard): void;
+/** 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 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 resizeCard(id: string, width: number, height: 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;
+export declare function selectCard(id: string): void;
+export declare function deselectCard(): void;
+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[]): void;
+export { subscribe, getMode, getCards, getComparisonGroups, getMode as getCanvasMode, getCards as getCanvasCards, getComparisonGroups as getCanvasComparisonGroups, };
+export declare function useCanvasMode(): CanvasMode;
+export declare function useCanvasCards(): CanvasCard[];
+export declare function useCanvasComparisonGroups(): CanvasComparisonGroup[];
+export declare function useBoardCamera(): CanvasCamera;

package/dist/inspector/canvas/canvasStore.js

@@ -0,0 +1,448 @@
+import { useSyncExternalStore } from "react";
+import { normalizeUrl, normalizedUrlKey } from "./normalizeUrl.js";
+export const MIN_CAMERA_ZOOM = 0.25;
+export const MAX_CAMERA_ZOOM = 3;
+export const CARD_GAP = 40;
+export const FIT_ALL_PADDING = 80;
+const DEFAULT_CAMERA = { x: 0, y: 0, zoom: 1 };
+function defaultViewportSize() {
+    return {
+        width: window.innerWidth || 1024,
+        height: window.innerHeight || 768,
+    };
+}
+let mode = "inspect";
+let cards = [];
+let comparisonGroups = [];
+let focusedCardId = null;
+let selectedCardId = null;
+let cardIdCounter = 0;
+let cachedBoardCamera = { ...DEFAULT_CAMERA };
+let lastUsedCardSize = null;
+let fitAllRan = false;
+const listeners = new Set();
+function subscribe(cb) {
+    listeners.add(cb);
+    return () => {
+        listeners.delete(cb);
+    };
+}
+function getMode() {
+    return mode;
+}
+function getCards() {
+    return cards;
+}
+function getComparisonGroups() {
+    return comparisonGroups;
+}
+function notify() {
+    listeners.forEach((l) => l());
+}
+function computeNewCardPosition(existingCards, gap) {
+    if (existingCards.length === 0)
+        return { x: 0, y: 0 };
+    let rightmostEdge = -Infinity;
+    for (const c of existingCards) {
+        const edge = c.x + c.width + gap;
+        if (edge > rightmostEdge)
+            rightmostEdge = edge;
+    }
+    const rowY = existingCards[0].y;
+    return { x: rightmostEdge, y: rowY };
+}
+function boundsOf(cards) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const card of cards) {
+        minX = Math.min(minX, card.x);
+        minY = Math.min(minY, card.y);
+        maxX = Math.max(maxX, card.x + card.width);
+        maxY = Math.max(maxY, card.y + card.height);
+    }
+    return { minX, minY, maxX, maxY };
+}
+export function setCanvasMode(newMode) {
+    if (mode === newMode)
+        return;
+    mode = newMode;
+    notify();
+}
+export function enterCanvas() {
+    if (mode === "canvas")
+        return;
+    mode = "canvas";
+    if (cards.length === 0) {
+        const size = lastUsedCardSize ?? defaultViewportSize();
+        const card = {
+            id: `card-${++cardIdCounter}`,
+            url: window.location.href,
+            title: document.title,
+            x: 0,
+            y: 0,
+            width: size.width,
+            height: size.height,
+        };
+        cards = [card];
+        lastUsedCardSize = { width: size.width, height: size.height };
+        cachedBoardCamera = { ...DEFAULT_CAMERA };
+        fitAllRan = false;
+    }
+    else {
+        const currentRoute = normalizeUrl(window.location.href);
+        const existing = currentRoute ? findCardByNormalizedUrl(currentRoute) : undefined;
+        if (existing) {
+            focusCard(existing.id);
+        }
+        else {
+            const added = addCanvasCard(window.location.href, document.title);
+            focusCard(added.id);
+            fitAllRan = false;
+        }
+    }
+    notify();
+}
+export function exitCanvas() {
+    if (mode === "inspect")
+        return;
+    mode = "inspect";
+    notify();
+}
+/** Return to inspect mode on a canvas card's route. */
+export function exitCanvasToCard(card) {
+    exitCanvas();
+    resetFitAllFlag();
+    if (card.url !== window.location.href) {
+        window.location.href = card.url;
+    }
+}
+/** Adds one card while retaining the existing placement policy. */
+export function addCanvasCard(url, title) {
+    const size = lastUsedCardSize ?? defaultViewportSize();
+    const pos = computeNewCardPosition(cards, CARD_GAP);
+    const card = {
+        id: `card-${++cardIdCounter}`,
+        url,
+        title: title ?? null,
+        x: pos.x,
+        y: pos.y,
+        width: size.width,
+        height: size.height,
+    };
+    cards = [...cards, card];
+    lastUsedCardSize = { width: size.width, height: size.height };
+    notify();
+    return card;
+}
+/**
+ * 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 function appendCanvasComparisonGroup(input) {
+    if (!input.id || !input.label || !input.agentId || input.routes.length === 0)
+        return null;
+    if (comparisonGroups.some((group) => group.id === input.id))
+        return null;
+    const nextCards = [];
+    let nextCardsSnapshot = cards;
+    for (const route of input.routes) {
+        const size = lastUsedCardSize ?? defaultViewportSize();
+        const pos = computeNewCardPosition(nextCardsSnapshot, CARD_GAP);
+        const card = {
+            id: `card-${++cardIdCounter}`,
+            url: route.url,
+            title: route.title ?? null,
+            x: pos.x,
+            y: pos.y,
+            width: size.width,
+            height: size.height,
+            comparisonGroupId: input.id,
+        };
+        nextCards.push(card);
+        nextCardsSnapshot = [...nextCardsSnapshot, card];
+        lastUsedCardSize = { width: size.width, height: size.height };
+    }
+    const group = {
+        id: input.id,
+        label: input.label,
+        owner: "agent",
+        agentId: input.agentId,
+        cardIds: nextCards.map((card) => card.id),
+        routes: input.routes.map((route) => ({ ...route })),
+    };
+    cards = [...cards, ...nextCards];
+    comparisonGroups = [...comparisonGroups, group];
+    notify();
+    return { group, cards: nextCards };
+}
+export function getCanvasComparisonGroup(id) {
+    return comparisonGroups.find((group) => group.id === id);
+}
+/** Removes a group and exactly the cards owned by that group. */
+export function removeCanvasComparisonGroup(id) {
+    const group = getCanvasComparisonGroup(id);
+    if (!group)
+        return null;
+    const groupCardIds = new Set(group.cardIds);
+    cards = cards.filter((card) => !groupCardIds.has(card.id));
+    comparisonGroups = comparisonGroups.filter((candidate) => candidate.id !== id);
+    if (groupCardIds.has(selectedCardId ?? ""))
+        selectedCardId = null;
+    if (groupCardIds.has(focusedCardId ?? ""))
+        focusedCardId = null;
+    if (cards.length === 0 && mode === "canvas")
+        mode = "inspect";
+    notify();
+    return group;
+}
+/** Clears group metadata while leaving ordinary cards intact. */
+export function clearCanvasComparisonGroups() {
+    if (comparisonGroups.length === 0 && !cards.some((card) => card.comparisonGroupId))
+        return;
+    cards = cards.map(({ comparisonGroupId: _comparisonGroupId, ...card }) => card);
+    comparisonGroups = [];
+    notify();
+}
+/**
+ * Finds the route paired with `cardId` inside the agent group `groupId` and
+ * replaces that group with `patchGroup`, which receives the paired route
+ * index.
+ */
+function updateComparisonGroupRoutes(groupId, cardId, patchGroup) {
+    comparisonGroups = comparisonGroups.map((group) => {
+        if (group.id !== groupId)
+            return group;
+        const routeIndex = group.cardIds.indexOf(cardId);
+        if (routeIndex < 0)
+            return group;
+        return patchGroup(group, routeIndex);
+    });
+}
+export function removeCanvasCard(id) {
+    const removed = cards.find((card) => card.id === id);
+    cards = cards.filter((c) => c.id !== id);
+    if (selectedCardId === id) {
+        selectedCardId = null;
+    }
+    if (focusedCardId === id) {
+        focusedCardId = null;
+    }
+    if (removed?.comparisonGroupId) {
+        updateComparisonGroupRoutes(removed.comparisonGroupId, id, (group, routeIndex) => ({
+            ...group,
+            cardIds: group.cardIds.filter((_cardId, index) => index !== routeIndex),
+            routes: group.routes.filter((_route, index) => index !== routeIndex),
+        }));
+        comparisonGroups = comparisonGroups.filter((group) => group.cardIds.length > 0);
+    }
+    if (cards.length === 0 && mode === "canvas") {
+        mode = "inspect";
+    }
+    notify();
+}
+export function updateCardTitle(id, title) {
+    const card = cards.find((candidate) => candidate.id === id);
+    cards = cards.map((c) => (c.id === id ? { ...c, title } : c));
+    if (card?.comparisonGroupId) {
+        updateComparisonGroupRoutes(card.comparisonGroupId, id, (group, routeIndex) => ({
+            ...group,
+            routes: group.routes.map((route, index) => index === routeIndex ? { ...route, title } : route),
+        }));
+    }
+    notify();
+}
+export function updateCardUrl(id, url) {
+    const card = cards.find((candidate) => candidate.id === id);
+    cards = cards.map((c) => (c.id === id ? { ...c, url } : c));
+    if (card?.comparisonGroupId) {
+        updateComparisonGroupRoutes(card.comparisonGroupId, id, (group, routeIndex) => ({
+            ...group,
+            routes: group.routes.map((route, index) => index === routeIndex ? { ...route, url } : route),
+        }));
+    }
+    notify();
+}
+export function duplicateCard(sourceId) {
+    const source = cards.find((c) => c.id === sourceId);
+    if (!source)
+        return null;
+    const size = lastUsedCardSize ?? { width: source.width, height: source.height };
+    const pos = computeNewCardPosition(cards, CARD_GAP);
+    const card = {
+        id: `card-${++cardIdCounter}`,
+        url: source.url,
+        title: source.title,
+        x: pos.x,
+        y: pos.y,
+        width: size.width,
+        height: size.height,
+    };
+    cards = [...cards, card];
+    lastUsedCardSize = { width: size.width, height: size.height };
+    notify();
+    return card;
+}
+export function resizeCard(id, width, height) {
+    cards = cards.map((c) => (c.id === id ? { ...c, width, height } : c));
+    lastUsedCardSize = { width, height };
+    notify();
+}
+export function getBoardCamera() {
+    return cachedBoardCamera;
+}
+export function setBoardCamera(camera) {
+    cachedBoardCamera = {
+        x: camera.x,
+        y: camera.y,
+        zoom: Math.max(MIN_CAMERA_ZOOM, Math.min(MAX_CAMERA_ZOOM, camera.zoom)),
+    };
+    notify();
+}
+export function updateBoardCamera(partial) {
+    const next = { ...cachedBoardCamera, ...partial };
+    if (partial.zoom !== undefined) {
+        next.zoom = Math.max(MIN_CAMERA_ZOOM, Math.min(MAX_CAMERA_ZOOM, partial.zoom));
+    }
+    cachedBoardCamera = next;
+    notify();
+}
+export function fitAllCards(viewport) {
+    fitCanvasCards(cards.map((card) => card.id), viewport);
+}
+/** Fits a selected set of cards while preserving cards outside that set. */
+export function fitCanvasCards(cardIds, viewport) {
+    const selectedIds = new Set(cardIds);
+    const selectedCards = cards.filter((card) => selectedIds.has(card.id));
+    if (selectedCards.length === 0)
+        return false;
+    const { minX, minY, maxX, maxY } = boundsOf(selectedCards);
+    const contentW = maxX - minX;
+    const contentH = maxY - minY;
+    if (contentW <= 0 || contentH <= 0) {
+        cachedBoardCamera = { ...DEFAULT_CAMERA };
+        fitAllRan = true;
+        notify();
+        return true;
+    }
+    const viewW = Math.max(1, (viewport?.width ?? window.innerWidth) - FIT_ALL_PADDING * 2);
+    const viewH = Math.max(1, (viewport?.height ?? window.innerHeight) - FIT_ALL_PADDING * 2);
+    const zoomX = viewW / contentW;
+    const zoomY = viewH / contentH;
+    const zoom = Math.max(MIN_CAMERA_ZOOM, Math.min(zoomX, zoomY, MAX_CAMERA_ZOOM));
+    const contentCenterX = minX + contentW / 2;
+    const contentCenterY = minY + contentH / 2;
+    cachedBoardCamera = {
+        x: -(contentCenterX * zoom) + (viewport?.width ?? window.innerWidth) / 2,
+        y: -(contentCenterY * zoom) + (viewport?.height ?? window.innerHeight) / 2,
+        zoom,
+    };
+    fitAllRan = true;
+    notify();
+    return true;
+}
+/** Centers a selected set of cards without changing the current zoom. */
+export function focusCanvasCards(cardIds, viewport) {
+    const selectedIds = new Set(cardIds);
+    const selectedCards = cards.filter((card) => selectedIds.has(card.id));
+    if (selectedCards.length === 0)
+        return false;
+    const { minX, minY, maxX, maxY } = boundsOf(selectedCards);
+    const viewW = viewport?.width ?? window.innerWidth;
+    const viewH = viewport?.height ?? window.innerHeight;
+    const contentCenterX = minX + (maxX - minX) / 2;
+    const contentCenterY = minY + (maxY - minY) / 2;
+    cachedBoardCamera = {
+        x: -(contentCenterX * cachedBoardCamera.zoom) + viewW / 2,
+        y: -(contentCenterY * cachedBoardCamera.zoom) + viewH / 2,
+        zoom: cachedBoardCamera.zoom,
+    };
+    fitAllRan = true;
+    notify();
+    return true;
+}
+export function hasFitAllRan() {
+    return fitAllRan;
+}
+export function resetFitAllFlag() {
+    fitAllRan = false;
+}
+export function findCardByNormalizedUrl(normalized) {
+    return cards.find((c) => {
+        const n = normalizeUrl(c.url);
+        if (!n)
+            return false;
+        return normalizedUrlKey(n) === normalizedUrlKey(normalized);
+    });
+}
+export function focusCard(id) {
+    focusedCardId = id;
+    selectedCardId = id;
+    notify();
+}
+export function getFocusedCardId() {
+    return focusedCardId;
+}
+export function selectCard(id) {
+    selectedCardId = id;
+    notify();
+}
+export function deselectCard() {
+    selectedCardId = null;
+    notify();
+}
+export function getSelectedCardId() {
+    return selectedCardId;
+}
+export function useSelectedCardId() {
+    return useSyncExternalStore(subscribe, getSelectedCardId, getSelectedCardId);
+}
+export function useFocusedCardId() {
+    return useSyncExternalStore(subscribe, getFocusedCardId, getFocusedCardId);
+}
+export function setCardPosition(id, x, y) {
+    cards = cards.map((c) => (c.id === id ? { ...c, x, y } : c));
+    notify();
+}
+export function hydrateCanvasStore(newMode, newCards, newCamera, newComparisonGroups = []) {
+    mode = newMode;
+    cards = newCards.map((card) => ({ ...card }));
+    comparisonGroups = newComparisonGroups.map((group) => ({
+        ...group,
+        owner: "agent",
+        cardIds: [...group.cardIds],
+        routes: group.routes.map((route) => ({ ...route })),
+    }));
+    focusedCardId = null;
+    selectedCardId = null;
+    cachedBoardCamera = { ...newCamera };
+    if (newCards.length > 0) {
+        let maxNum = 0;
+        for (const c of newCards) {
+            const match = /^card-(\d+)$/.exec(c.id);
+            if (match) {
+                const n = Number(match[1]);
+                if (n > maxNum)
+                    maxNum = n;
+            }
+        }
+        cardIdCounter = Math.max(cardIdCounter, maxNum);
+    }
+    fitAllRan = true;
+    notify();
+}
+export { subscribe, getMode, getCards, getComparisonGroups, getMode as getCanvasMode, getCards as getCanvasCards, getComparisonGroups as getCanvasComparisonGroups, };
+export function useCanvasMode() {
+    return useSyncExternalStore(subscribe, getMode, getMode);
+}
+export function useCanvasCards() {
+    return useSyncExternalStore(subscribe, getCards, getCards);
+}
+export function useCanvasComparisonGroups() {
+    return useSyncExternalStore(subscribe, getComparisonGroups, getComparisonGroups);
+}
+export function useBoardCamera() {
+    return useSyncExternalStore(subscribe, getBoardCamera, getBoardCamera);
+}