nudge-ui 0.2.0

package/dist/inspector/canvas/resizeHandleScale.js

@@ -0,0 +1,20 @@
+import { MAX_CAMERA_ZOOM } from "./canvasStore.js";
+import { CANVAS_TOOLBAR_MAX_SCALE } from "./toolbarScale.js";
+/**
+ * Keep the resize handle usable while the board is zoomed without allowing
+ * inverse scaling to make it disproportionately large or small.
+ */
+export const CANVAS_RESIZE_HANDLE_MIN_SCALE = 1 / MAX_CAMERA_ZOOM;
+export const CANVAS_RESIZE_HANDLE_MAX_SCALE = CANVAS_TOOLBAR_MAX_SCALE;
+/**
+ * Returns the scale to apply inside the board's zoomed coordinate space.
+ *
+ * The lower bound matches the inverse of the largest supported camera zoom,
+ * and the upper bound follows the toolbar compensation policy.
+ */
+export function getCanvasResizeHandleScale(zoom) {
+    if (!Number.isFinite(zoom) || zoom <= 0) {
+        return CANVAS_RESIZE_HANDLE_MAX_SCALE;
+    }
+    return Math.max(CANVAS_RESIZE_HANDLE_MIN_SCALE, Math.min(1 / zoom, CANVAS_RESIZE_HANDLE_MAX_SCALE));
+}

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

@@ -0,0 +1,5 @@
+export declare const CANVAS_RENDERER_ATTR = "data-nudge-ui-canvas-renderer";
+export type NudgeUiRole = "controller" | "renderer";
+export declare function detectRole(): NudgeUiRole;
+export declare function isCanvasRenderer(): boolean;
+export declare function isTopLevelController(): boolean;

package/dist/inspector/canvas/roleDetection.js

@@ -0,0 +1,21 @@
+export const CANVAS_RENDERER_ATTR = "data-nudge-ui-canvas-renderer";
+export function detectRole() {
+    try {
+        const frameEl = window.frameElement;
+        if (!frameEl)
+            return "controller";
+        if (frameEl.hasAttribute?.(CANVAS_RENDERER_ATTR)) {
+            return "renderer";
+        }
+    }
+    catch {
+        // frameElement access may throw if cross-origin
+    }
+    return "controller";
+}
+export function isCanvasRenderer() {
+    return detectRole() === "renderer";
+}
+export function isTopLevelController() {
+    return detectRole() === "controller";
+}

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

@@ -0,0 +1,71 @@
+import { type SerializableChange } from "../changes/codecs.js";
+import { type CanvasMode } from "./canvasStore.js";
+import { type StructuralChange } from "../projection/structuralProjection.js";
+import { type ClipboardHandoffSnapshot } from "../prompt/clipboardHandoff.js";
+declare const SCHEMA_VERSION = 12;
+declare function storageKey(projectId: string): string;
+export interface SerializableCard {
+    id: string;
+    url: string;
+    title: string | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    comparisonGroupId?: string;
+}
+export interface SerializableComparisonGroup {
+    id: string;
+    label: string;
+    owner: "agent";
+    agentId: string;
+    cardIds: string[];
+    routes: Array<{
+        url: string;
+        title?: string | null;
+        label?: string;
+    }>;
+}
+export interface DurableSession {
+    schemaVersion: typeof SCHEMA_VERSION;
+    projectId: string;
+    mode: CanvasMode;
+    inspectUrl: string;
+    cards: SerializableCard[];
+    comparisonGroups: SerializableComparisonGroup[];
+    camera: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    changes: SerializableChange[];
+    structuralChanges: StructuralChange[];
+    clipboardHandoff: ClipboardHandoffSnapshot | null;
+}
+export type { SerializableChange, SerializableComponentChange, SerializableElementChange, SerializableTextContentChange, SerializableTokenChange, SerializableTokenRef, } from "../changes/codecs.js";
+export interface HydrationResult {
+    restored: boolean;
+    changeCount: number;
+}
+export declare function serializeSession(): DurableSession;
+export declare function persistSession(): boolean;
+export declare function hydrateSession(): HydrationResult;
+export declare function clearSession(): void;
+export declare function enableAutoSave(): void;
+/**
+ * Coalesces the synchronous full-session `JSON.stringify` + `localStorage`
+ * write behind a trailing timer so commits never block on persistence. A
+ * refresh or close inside the debounce window still flushes on `beforeunload`.
+ */
+export declare function scheduleAutoSave(): void;
+/**
+ * Canvas mode/card/camera changes persist immediately (synchronous) so a
+ * refresh always restores the workspace, even inside the edit-autosave
+ * debounce window. Edit autosave stays coalesced behind the trailing timer.
+ */
+export declare function scheduleCanvasSave(): void;
+export declare function getRestoreCount(): number;
+export declare function setRestoreCount(count: number): void;
+export declare function clearRestoreCount(): void;
+export declare function resetAutoSave(): void;
+export { storageKey, SCHEMA_VERSION, type SerializableCard as HydratedCard };

package/dist/inspector/canvas/sessionStore.js

@@ -0,0 +1,453 @@
+import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
+import { loadWorkspaceChanges } from "../changes/changesLog.js";
+import { deserializeChange, isSerializableChange, serializeChange, } from "../changes/codecs.js";
+import { getCanvasMode, getCanvasCards, getCanvasComparisonGroups, getBoardCamera, setBoardCamera, hydrateCanvasStore, removeCanvasCard, } from "./canvasStore.js";
+import { applyRules } from "../projection/managedStylesheet.js";
+import { clearWorkspace as clearWorkspaceLog } from "../changes/changesLog.js";
+import { removeManagedSheet } from "../projection/managedStylesheet.js";
+import { clearInspectorLayout } from "../shell/panelLayout.js";
+import { setSelectedElement } from "../selection/selectionStore.js";
+import { canWriteWorkspace } from "./workspaceLease.js";
+import { isStructuralChange, resetStructuralDeleteProjection, } from "../projection/structuralProjection.js";
+import { projectToAllReadyCards } from "./projection.js";
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+import { clearClipboardHandoff, getClipboardHandoffSnapshot, hydrateClipboardHandoff, isClipboardHandoffSnapshot, } from "../prompt/clipboardHandoff.js";
+// v12 is the first durable-session schema after the edit model and preview
+// diagnostic split. Previous session shapes are intentionally incompatible.
+const SCHEMA_VERSION = 12;
+const STORAGE_PREFIX = "nudge-ui";
+function projectId() {
+    return getNudgeUiRuntimeConfig().projectId;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isSameOriginUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return new URL(value).origin === window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function isSerializableComparisonGroup(value) {
+    if (!isRecord(value)
+        || !hasOnlyKeys(value, ["id", "label", "owner", "agentId", "cardIds", "routes"])
+        || typeof value.id !== "string"
+        || value.id.length === 0
+        || value.id.length > 256
+        || typeof value.label !== "string"
+        || value.label.length === 0
+        || value.label.length > 160
+        || value.owner !== "agent"
+        || typeof value.agentId !== "string"
+        || value.agentId.length === 0
+        || value.agentId.length > 256
+        || !Array.isArray(value.cardIds)
+        || value.cardIds.length === 0
+        || value.cardIds.length > 64
+        || !Array.isArray(value.routes)
+        || value.routes.length === 0
+        || value.routes.length > 64) {
+        return false;
+    }
+    if (!value.cardIds.every((cardId) => typeof cardId === "string" && cardId.length > 0 && cardId.length <= 256)) {
+        return false;
+    }
+    return value.routes.every((route) => {
+        if (!isRecord(route)
+            || !hasOnlyKeys(route, ["url", "title", "label"])
+            || !isSameOriginUrl(route.url)
+            || (route.title !== undefined && route.title !== null
+                && (typeof route.title !== "string" || route.title.length > 512))
+            || (route.label !== undefined
+                && (typeof route.label !== "string" || route.label.length > 160))) {
+            return false;
+        }
+        return true;
+    });
+}
+function storageKey(projectId) {
+    return `${STORAGE_PREFIX}:${projectId}:v${SCHEMA_VERSION}`;
+}
+function buildSession() {
+    const workspace = getWorkspaceChanges();
+    const changes = workspace.changes;
+    const serializableChanges = [];
+    for (const change of changes) {
+        const serialized = serializeChange(change);
+        // serializeChange already fails closed, but re-validate here so a future
+        // serializer skew can never poison the whole durable session.
+        if (serialized && isSerializableChange(serialized))
+            serializableChanges.push(serialized);
+    }
+    const cards = getCanvasCards();
+    const comparisonGroups = getCanvasComparisonGroups();
+    const camera = getBoardCamera();
+    const mode = getCanvasMode();
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        projectId: projectId(),
+        mode,
+        inspectUrl: window.location.href,
+        cards: cards.map((c) => ({
+            id: c.id,
+            url: c.url,
+            title: c.title,
+            x: c.x,
+            y: c.y,
+            width: c.width,
+            height: c.height,
+            ...(c.comparisonGroupId ? { comparisonGroupId: c.comparisonGroupId } : {}),
+        })),
+        comparisonGroups: comparisonGroups.map((group) => ({
+            id: group.id,
+            label: group.label,
+            owner: "agent",
+            agentId: group.agentId,
+            cardIds: [...group.cardIds],
+            routes: group.routes.map((route) => ({
+                url: route.url,
+                ...(route.title === undefined ? {} : { title: route.title }),
+                ...(route.label === undefined ? {} : { label: route.label }),
+            })),
+        })),
+        camera: { x: camera.x, y: camera.y, zoom: camera.zoom },
+        changes: serializableChanges,
+        structuralChanges: workspace.structuralChanges.map((change) => ({ ...change })),
+        clipboardHandoff: getClipboardHandoffSnapshot(),
+    };
+}
+export function serializeSession() {
+    return buildSession();
+}
+export function persistSession() {
+    if (!canWriteWorkspace())
+        return false;
+    return persistSessionUnchecked();
+}
+/**
+ * Serializes and writes the session without the write-lease gate. The public
+ * persistence path checks the lease before calling this helper.
+ */
+function persistSessionUnchecked() {
+    if (!projectId())
+        return false;
+    try {
+        const session = buildSession();
+        localStorage.setItem(storageKey(projectId()), JSON.stringify(session));
+        return true;
+    }
+    catch {
+        // Storage unavailable or quota exceeded — silently ignore
+        return false;
+    }
+}
+export function hydrateSession() {
+    if (!projectId())
+        return { restored: false, changeCount: 0 };
+    let raw = null;
+    try {
+        raw = localStorage.getItem(storageKey(projectId()));
+    }
+    catch {
+        return { restored: false, changeCount: 0 };
+    }
+    if (!raw)
+        return { restored: false, changeCount: 0 };
+    let session;
+    try {
+        session = JSON.parse(raw);
+    }
+    catch {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    if (!session || typeof session !== "object") {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const s = session;
+    if (typeof s.schemaVersion !== "number" || s.schemaVersion !== SCHEMA_VERSION) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    if (typeof s.projectId !== "string" || s.projectId !== projectId()) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    if (typeof s.mode !== "string" || (s.mode !== "inspect" && s.mode !== "canvas")) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    if (!isSameOriginUrl(s.inspectUrl)) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const inspectRouteChanged = s.mode === "inspect" && s.inspectUrl !== window.location.href;
+    const cards = Array.isArray(s.cards) ? s.cards : null;
+    if (!cards) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const serializableCards = [];
+    for (const card of cards) {
+        const candidate = card;
+        if (!card || typeof card !== "object" ||
+            typeof candidate.id !== "string" ||
+            !isSameOriginUrl(candidate.url) ||
+            !isFiniteNumber(candidate.x) ||
+            !isFiniteNumber(candidate.y) ||
+            !isFiniteNumber(candidate.width) ||
+            !isFiniteNumber(candidate.height) ||
+            candidate.width <= 0 ||
+            candidate.height <= 0) {
+            safeDiscard();
+            return { restored: false, changeCount: 0 };
+        }
+        const c = card;
+        serializableCards.push({
+            id: c.id,
+            url: c.url,
+            title: typeof c.title === "string" ? c.title : null,
+            x: c.x,
+            y: c.y,
+            width: c.width,
+            height: c.height,
+            ...(typeof c.comparisonGroupId === "string"
+                ? { comparisonGroupId: c.comparisonGroupId }
+                : {}),
+        });
+    }
+    if (new Set(serializableCards.map((card) => card.id)).size !== serializableCards.length) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const comparisonGroupsRaw = s.comparisonGroups;
+    if (!Array.isArray(comparisonGroupsRaw) || comparisonGroupsRaw.length > 128) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const serializableComparisonGroups = [];
+    for (const group of comparisonGroupsRaw) {
+        if (!isSerializableComparisonGroup(group)) {
+            safeDiscard();
+            return { restored: false, changeCount: 0 };
+        }
+        serializableComparisonGroups.push({
+            id: group.id,
+            label: group.label,
+            owner: "agent",
+            agentId: group.agentId,
+            cardIds: [...group.cardIds],
+            routes: group.routes.map((route) => ({ ...route })),
+        });
+    }
+    if (new Set(serializableComparisonGroups.map((group) => group.id)).size
+        !== serializableComparisonGroups.length) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const cardsById = new Map(serializableCards.map((card) => [card.id, card]));
+    const groupedCardIds = new Set();
+    for (const group of serializableComparisonGroups) {
+        if (group.cardIds.length !== group.routes.length) {
+            safeDiscard();
+            return { restored: false, changeCount: 0 };
+        }
+        for (const [routeIndex, cardId] of group.cardIds.entries()) {
+            const card = cardsById.get(cardId);
+            const route = group.routes[routeIndex];
+            if (!card || !route || card.comparisonGroupId !== group.id || groupedCardIds.has(cardId)
+                || card.url !== route.url) {
+                safeDiscard();
+                return { restored: false, changeCount: 0 };
+            }
+            groupedCardIds.add(cardId);
+        }
+    }
+    for (const card of serializableCards) {
+        if (card.comparisonGroupId && !serializableComparisonGroups.some((group) => group.id === card.comparisonGroupId)) {
+            safeDiscard();
+            return { restored: false, changeCount: 0 };
+        }
+    }
+    const cameraRaw = s.camera;
+    if (!cameraRaw || typeof cameraRaw !== "object" ||
+        !isFiniteNumber(cameraRaw.x) ||
+        !isFiniteNumber(cameraRaw.y) ||
+        !isFiniteNumber(cameraRaw.zoom)) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const changesRaw = s.changes;
+    if (!Array.isArray(changesRaw)) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const deserializedChanges = [];
+    const textChangeIds = new Set();
+    for (const c of changesRaw) {
+        if (!isSerializableChange(c)) {
+            safeDiscard();
+            return { restored: false, changeCount: 0 };
+        }
+        if (c.kind === "text-content") {
+            if (textChangeIds.has(c.id)) {
+                safeDiscard();
+                return { restored: false, changeCount: 0 };
+            }
+            textChangeIds.add(c.id);
+        }
+        try {
+            deserializedChanges.push(deserializeChange(c));
+        }
+        catch {
+            safeDiscard();
+            return { restored: false, changeCount: 0 };
+        }
+    }
+    const structuralChanges = s.structuralChanges;
+    if (!Array.isArray(structuralChanges) || !structuralChanges.every(isStructuralChange)) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const clipboardHandoff = s.clipboardHandoff;
+    if (!isClipboardHandoffSnapshot(clipboardHandoff)) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    const camera = {
+        x: cameraRaw.x,
+        y: cameraRaw.y,
+        zoom: cameraRaw.zoom,
+    };
+    hydrateCanvasStore(s.mode, serializableCards, camera, serializableComparisonGroups);
+    // Structural intent and instance evidence become visible atomically. The
+    // projection layer preserves structural-first document application order.
+    loadWorkspaceChanges(deserializedChanges, structuralChanges);
+    hydrateClipboardHandoff(clipboardHandoff);
+    // A different URL means the user intentionally navigated while Inspect was
+    // active. Keep the durable edits, but adopt the new route instead of
+    // sending the user back to the previous page. On refresh, the URLs already
+    // match and restoration remains unchanged.
+    if (inspectRouteChanged)
+        persistSessionUnchecked();
+    projectToAllReadyCards();
+    return { restored: true, changeCount: deserializedChanges.length + structuralChanges.length };
+}
+function safeDiscard() {
+    try {
+        localStorage.removeItem(storageKey(projectId()));
+    }
+    catch {
+        // ignore
+    }
+}
+export function clearSession() {
+    if (!canWriteWorkspace())
+        return;
+    try {
+        localStorage.removeItem(storageKey(projectId()));
+    }
+    catch {
+        // ignore
+    }
+    clearWorkspaceLog();
+    clearClipboardHandoff();
+    resetStructuralDeleteProjection();
+    removeManagedSheet();
+    setSelectedElement(null);
+    clearInspectorLayout();
+    for (const card of getCanvasCards()) {
+        removeCanvasCard(card.id);
+    }
+    setBoardCamera({ x: 0, y: 0, zoom: 1 });
+    applyRules([]);
+    autoSaveDirty = false;
+    if (autosaveTimer !== null) {
+        clearTimeout(autosaveTimer);
+        autosaveTimer = null;
+    }
+}
+let autoSaveEnabled = false;
+let autosaveTimer = null;
+let autoSaveDirty = false;
+const AUTOSAVE_DEBOUNCE_MS = 500;
+export function enableAutoSave() {
+    if (autoSaveEnabled)
+        return;
+    autoSaveEnabled = true;
+    window.addEventListener("beforeunload", flushAutoSave);
+}
+/**
+ * Coalesces the synchronous full-session `JSON.stringify` + `localStorage`
+ * write behind a trailing timer so commits never block on persistence. A
+ * refresh or close inside the debounce window still flushes on `beforeunload`.
+ */
+export function scheduleAutoSave() {
+    if (!autoSaveEnabled)
+        return;
+    autoSaveDirty = true;
+    if (autosaveTimer !== null)
+        clearTimeout(autosaveTimer);
+    autosaveTimer = setTimeout(() => {
+        autosaveTimer = null;
+        if (!autoSaveDirty)
+            return;
+        if (persistSession())
+            autoSaveDirty = false;
+    }, AUTOSAVE_DEBOUNCE_MS);
+}
+/**
+ * Canvas mode/card/camera changes persist immediately (synchronous) so a
+ * refresh always restores the workspace, even inside the edit-autosave
+ * debounce window. Edit autosave stays coalesced behind the trailing timer.
+ */
+export function scheduleCanvasSave() {
+    if (!autoSaveEnabled)
+        return;
+    if (persistSession())
+        autoSaveDirty = false;
+}
+function flushAutoSave() {
+    if (autosaveTimer !== null) {
+        clearTimeout(autosaveTimer);
+        autosaveTimer = null;
+    }
+    if (!autoSaveDirty)
+        return;
+    // Keep the normal lease gate on the unload path. The controller registers
+    // this listener before releaseLease, so a current owner can flush a first
+    // write without allowing a stale tab to overwrite the new owner's session.
+    if (persistSession())
+        autoSaveDirty = false;
+}
+let restoreCount = 0;
+export function getRestoreCount() {
+    return restoreCount;
+}
+export function setRestoreCount(count) {
+    restoreCount = count;
+}
+export function clearRestoreCount() {
+    restoreCount = 0;
+}
+export function resetAutoSave() {
+    autoSaveEnabled = false;
+    autoSaveDirty = false;
+    if (autosaveTimer !== null) {
+        clearTimeout(autosaveTimer);
+        autosaveTimer = null;
+    }
+    window.removeEventListener("beforeunload", flushAutoSave);
+}
+export { storageKey, SCHEMA_VERSION };

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

@@ -0,0 +1,11 @@
+import type { ChangeRecord } from "../changes/changesLog.js";
+export type StaleChangeStatus = "unverified" | "verified" | "stale" | "token-drift";
+export interface StaleChangeInfo {
+    index: number;
+    status: StaleChangeStatus;
+    matchedRoutes: string[];
+    driftMessage?: string;
+}
+export declare function startStaleDetection(changes: ChangeRecord[]): void;
+export declare function cancelStaleDetection(): void;
+export declare function isVerificationPending(): boolean;