nudge-ui 0.2.0

package/dist/inspector/canvas/staleChangeDetector.js

@@ -0,0 +1,217 @@
+import { isPreviewableChange, isTokenChange, } from "../changes/changesLog.js";
+import { changeKey } from "../changes/model.js";
+import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, notifyPreviewDiagnostics, publishPreviewDiagnostic, } from "../changes/previewDiagnostics.js";
+import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
+import { getCanvasPreviewDocument, getRegisteredFrames } from "./projection.js";
+import { findCanvasFrameBySource, PROJECT_ID, WORKSPACE_ID } from "./projection.js";
+import { getCanvasCards } from "./canvasStore.js";
+import { isRendererMessageFor } from "./frameProtocol.js";
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+const VERIFICATION_TIMEOUT_MS = 5000;
+const STALE_CHECK_DEBOUNCE_MS = 100;
+let verificationTimer = null;
+let debounceTimer = null;
+let pendingChanges = null;
+let pendingAttempts = new Map();
+function checkSelectorInDocument(doc, selector) {
+    try {
+        return doc.querySelectorAll(selector).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function checkSelectorInFrame(iframe, selector) {
+    try {
+        const doc = iframe.contentDocument;
+        if (!doc)
+            return false;
+        return checkSelectorInDocument(doc, selector);
+    }
+    catch {
+        return false;
+    }
+}
+function getRequestedValue(change) {
+    if (isTokenChange(change))
+        return change.rawValue;
+    if (change.newToken) {
+        return change.newToken.cssValue ?? `var(${change.newToken.cssName ?? change.newToken.name})`;
+    }
+    return change.rawValue ?? "";
+}
+function buildStaleResult(selector, requestedValue) {
+    return {
+        requestedValue,
+        computedValue: "",
+        status: "conflict",
+        reason: "target-missing",
+    };
+}
+function checkTokenDrift(change) {
+    const { tokenCatalog } = getNudgeUiRuntimeConfig();
+    const def = tokenCatalog.find((d) => d.name === change.tokenName || d.cssName === change.tokenName);
+    if (!def) {
+        return {
+            requestedValue: change.rawValue,
+            computedValue: "",
+            status: "conflict",
+            reason: "token-drift",
+        };
+    }
+    const primaryDecl = def.declarations[0];
+    if (!primaryDecl) {
+        return {
+            requestedValue: change.rawValue,
+            computedValue: "",
+            status: "conflict",
+            reason: "token-drift",
+        };
+    }
+    if (primaryDecl.value !== change.oldRawValue) {
+        return {
+            requestedValue: change.rawValue,
+            computedValue: primaryDecl.value,
+            status: "conflict",
+            reason: "token-drift",
+        };
+    }
+    return null;
+}
+function getPreviewDocuments() {
+    const documents = [getHostPreviewDocument()];
+    const frames = getRegisteredFrames();
+    for (const card of getCanvasCards()) {
+        if (frames.has(card.id))
+            documents.push(getCanvasPreviewDocument(card.id));
+    }
+    return documents;
+}
+function beginPreviewAttempts() {
+    const attempts = new Map();
+    const revision = getWorkspaceChanges().revision;
+    for (const document of getPreviewDocuments()) {
+        const attempt = beginPreviewAttempt(document, revision);
+        if (attempt)
+            attempts.set(document.logicalDocument, attempt);
+    }
+    return attempts;
+}
+function gatherMatchEvidence(changes) {
+    const evidence = new Map();
+    const hostDocument = getHostPreviewDocument();
+    for (let i = 0; i < changes.length; i++) {
+        const change = changes[i];
+        if (isTokenChange(change))
+            continue;
+        if (checkSelectorInDocument(document, change.selector)) {
+            const routes = evidence.get(i) ?? [];
+            routes.push(hostDocument);
+            evidence.set(i, routes);
+        }
+    }
+    const frames = getRegisteredFrames();
+    const cards = getCanvasCards();
+    for (const card of cards) {
+        const frame = frames.get(card.id);
+        if (!frame || !frame.contentWindow)
+            continue;
+        for (let i = 0; i < changes.length; i++) {
+            const change = changes[i];
+            if (isTokenChange(change))
+                continue;
+            if (checkSelectorInFrame(frame, change.selector)) {
+                const routes = evidence.get(i) ?? [];
+                routes.push(getCanvasPreviewDocument(card.id));
+                evidence.set(i, routes);
+            }
+        }
+    }
+    return evidence;
+}
+function applyStaleResults(changes, attempts) {
+    const evidence = gatherMatchEvidence(changes);
+    const hostAttempt = attempts.get(getHostPreviewDocument().logicalDocument);
+    for (let i = 0; i < changes.length; i++) {
+        const change = changes[i];
+        if (isTokenChange(change)) {
+            const drift = checkTokenDrift(change);
+            if (drift && hostAttempt)
+                publishPreviewDiagnostic(hostAttempt, changeKey(change), drift);
+            continue;
+        }
+        const routes = evidence.get(i);
+        // A document that does not contain the target says nothing about
+        // staleness. Publish target-missing only when the change matches nowhere;
+        // a Canvas-only match is verified, not a host conflict. When nowhere,
+        // every live document reports the same miss.
+        if (!routes || routes.length === 0) {
+            for (const attempt of attempts.values()) {
+                publishPreviewDiagnostic(attempt, changeKey(change), buildStaleResult(change.selector, getRequestedValue(change)));
+            }
+        }
+    }
+}
+function scheduleStaleCheck() {
+    if (debounceTimer)
+        clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+        if (pendingChanges) {
+            pendingAttempts = beginPreviewAttempts();
+            clearPreviewDiagnostics(pendingChanges.map(changeKey));
+            applyStaleResults(pendingChanges, pendingAttempts);
+        }
+    }, STALE_CHECK_DEBOUNCE_MS);
+}
+export function startStaleDetection(changes) {
+    const previewableChanges = changes.filter(isPreviewableChange);
+    if (previewableChanges.length === 0)
+        return;
+    clearPreviewDiagnostics(previewableChanges.map(changeKey));
+    pendingAttempts = beginPreviewAttempts();
+    pendingChanges = previewableChanges;
+    if (verificationTimer)
+        clearTimeout(verificationTimer);
+    verificationTimer = setTimeout(() => {
+        if (pendingChanges) {
+            applyStaleResults(pendingChanges, pendingAttempts);
+            pendingChanges = null;
+        }
+        pendingAttempts = new Map();
+        verificationTimer = null;
+        notifyPreviewDiagnostics();
+    }, VERIFICATION_TIMEOUT_MS);
+    window.addEventListener("message", handleFrameReady);
+}
+function handleFrameReady(event) {
+    if (event.origin !== window.location.origin)
+        return;
+    const msg = event.data;
+    const frame = findCanvasFrameBySource(event.source);
+    if (!frame || !isRendererMessageFor(msg, {
+        projectId: PROJECT_ID,
+        workspaceId: WORKSPACE_ID,
+        cardId: frame.cardId,
+    }) || msg.type !== "frame-ready")
+        return;
+    if (!pendingChanges)
+        return;
+    scheduleStaleCheck();
+}
+export function cancelStaleDetection() {
+    if (verificationTimer) {
+        clearTimeout(verificationTimer);
+        verificationTimer = null;
+    }
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+    }
+    pendingChanges = null;
+    pendingAttempts = new Map();
+    window.removeEventListener("message", handleFrameReady);
+    notifyPreviewDiagnostics();
+}
+export function isVerificationPending() {
+    return pendingChanges !== null && verificationTimer !== null;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Keep canvas card controls usable while the board is zoomed out without
+ * letting them grow without bound relative to the card.
+ */
+export declare const CANVAS_TOOLBAR_MAX_SCALE = 2;
+export declare const CANVAS_TOOLBAR_SCALE_CAP_ZOOM: number;
+export declare function getCanvasToolbarScale(zoom: number): number;

package/dist/inspector/canvas/toolbarScale.js

@@ -0,0 +1,11 @@
+/**
+ * Keep canvas card controls usable while the board is zoomed out without
+ * letting them grow without bound relative to the card.
+ */
+export const CANVAS_TOOLBAR_MAX_SCALE = 2;
+export const CANVAS_TOOLBAR_SCALE_CAP_ZOOM = 1 / CANVAS_TOOLBAR_MAX_SCALE;
+export function getCanvasToolbarScale(zoom) {
+    if (!Number.isFinite(zoom) || zoom <= 0)
+        return CANVAS_TOOLBAR_MAX_SCALE;
+    return Math.min(1 / zoom, CANVAS_TOOLBAR_MAX_SCALE);
+}

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

@@ -0,0 +1,26 @@
+export interface WorkspaceLease {
+    ownerId: string;
+    projectId: string;
+    acquiredAt: number;
+    lastHeartbeat: number;
+}
+export declare function readLeaseRaw(): WorkspaceLease | null;
+export declare function isLeaseExpired(lease: WorkspaceLease, now?: number): boolean;
+export declare function acquireLease(): boolean;
+export declare function requestTakeover(): boolean;
+/** Enable lease checks for state-changing controller actions in this document. */
+export declare function enableWriteGuard(): void;
+/**
+ * Unit-level modules are also used without the browser controller bootstrap.
+ * Once the controller enables the guard, only the current lease owner may
+ * mutate or persist its canonical workspace state.
+ */
+export declare function canWriteWorkspace(): boolean;
+export declare function releaseLease(): void;
+export declare function hasWriteLease(): boolean;
+export declare function getActiveLeaseOwner(): {
+    ownerId: string;
+    acquiredAt: number;
+} | null;
+export declare function getOwnerId(): string | null;
+export declare function subscribeOwnership(listener: (hasLease: boolean) => void): () => void;

package/dist/inspector/canvas/workspaceLease.js

@@ -0,0 +1,214 @@
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+const LEASE_KEY_PREFIX = "nudge-ui:";
+const HEARTBEAT_INTERVAL_MS = 5000;
+const LEASE_EXPIRY_MS = 15000;
+function leaseKey() {
+    return `${LEASE_KEY_PREFIX}${getNudgeUiRuntimeConfig().projectId}:lease`;
+}
+function generateOwnerId() {
+    return (crypto.randomUUID?.() ??
+        `owner-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+}
+export function readLeaseRaw() {
+    try {
+        const raw = localStorage.getItem(leaseKey());
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object")
+            return null;
+        // SAFETY: JSON.parse returns unknown; we narrow only the known lease fields below.
+        const l = parsed;
+        if (typeof l.ownerId !== "string" ||
+            typeof l.projectId !== "string" ||
+            typeof l.acquiredAt !== "number" ||
+            typeof l.lastHeartbeat !== "number") {
+            return null;
+        }
+        return {
+            ownerId: l.ownerId,
+            projectId: l.projectId,
+            acquiredAt: l.acquiredAt,
+            lastHeartbeat: l.lastHeartbeat,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeLease(lease) {
+    try {
+        localStorage.setItem(leaseKey(), JSON.stringify(lease));
+    }
+    catch {
+        /* storage unavailable */
+    }
+}
+function deleteLease() {
+    try {
+        localStorage.removeItem(leaseKey());
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function isLeaseExpired(lease, now = Date.now()) {
+    return now - lease.lastHeartbeat > LEASE_EXPIRY_MS;
+}
+let currentOwnerId = null;
+let heartbeatTimer = null;
+let ownsLease = false;
+let writeGuardEnabled = false;
+const ownershipListeners = new Set();
+function notifyOwnershipListeners() {
+    const snapshot = ownsLease;
+    for (const listener of ownershipListeners) {
+        try {
+            listener(snapshot);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+function startHeartbeat() {
+    if (heartbeatTimer)
+        return;
+    heartbeatTimer = setInterval(() => {
+        if (!currentOwnerId || !ownsLease)
+            return;
+        const existing = readLeaseRaw();
+        if (!existing || existing.ownerId !== currentOwnerId) {
+            loseOwnership();
+            return;
+        }
+        existing.lastHeartbeat = Date.now();
+        writeLease(existing);
+    }, HEARTBEAT_INTERVAL_MS);
+}
+function stopHeartbeat() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+}
+function loseOwnership() {
+    ownsLease = false;
+    stopHeartbeat();
+    notifyOwnershipListeners();
+}
+function createLease() {
+    return {
+        ownerId: currentOwnerId,
+        projectId: getNudgeUiRuntimeConfig().projectId,
+        acquiredAt: Date.now(),
+        lastHeartbeat: Date.now(),
+    };
+}
+export function acquireLease() {
+    if (currentOwnerId) {
+        const existing = readLeaseRaw();
+        if (existing &&
+            existing.ownerId === currentOwnerId &&
+            !isLeaseExpired(existing)) {
+            if (!ownsLease) {
+                ownsLease = true;
+                startHeartbeat();
+                notifyOwnershipListeners();
+            }
+            return true;
+        }
+        loseOwnership();
+    }
+    currentOwnerId = generateOwnerId();
+    const existing = readLeaseRaw();
+    if (existing && !isLeaseExpired(existing)) {
+        return false;
+    }
+    const lease = createLease();
+    writeLease(lease);
+    ownsLease = true;
+    startHeartbeat();
+    window.addEventListener("storage", handleStorageEvent);
+    notifyOwnershipListeners();
+    return true;
+}
+export function requestTakeover() {
+    if (!currentOwnerId) {
+        currentOwnerId = generateOwnerId();
+    }
+    const lease = createLease();
+    writeLease(lease);
+    ownsLease = true;
+    startHeartbeat();
+    window.addEventListener("storage", handleStorageEvent);
+    notifyOwnershipListeners();
+    return true;
+}
+/** Enable lease checks for state-changing controller actions in this document. */
+export function enableWriteGuard() {
+    writeGuardEnabled = true;
+}
+/**
+ * Unit-level modules are also used without the browser controller bootstrap.
+ * Once the controller enables the guard, only the current lease owner may
+ * mutate or persist its canonical workspace state.
+ */
+export function canWriteWorkspace() {
+    return !writeGuardEnabled || hasWriteLease();
+}
+export function releaseLease() {
+    if (!ownsLease)
+        return;
+    stopHeartbeat();
+    window.removeEventListener("storage", handleStorageEvent);
+    const existing = readLeaseRaw();
+    if (existing && existing.ownerId === currentOwnerId) {
+        deleteLease();
+    }
+    ownsLease = false;
+    currentOwnerId = null;
+    notifyOwnershipListeners();
+}
+export function hasWriteLease() {
+    if (!ownsLease)
+        return false;
+    const existing = readLeaseRaw();
+    if (!existing ||
+        existing.ownerId !== currentOwnerId ||
+        isLeaseExpired(existing)) {
+        loseOwnership();
+        return false;
+    }
+    return true;
+}
+export function getActiveLeaseOwner() {
+    const existing = readLeaseRaw();
+    if (!existing || isLeaseExpired(existing))
+        return null;
+    return { ownerId: existing.ownerId, acquiredAt: existing.acquiredAt };
+}
+export function getOwnerId() {
+    return currentOwnerId;
+}
+export function subscribeOwnership(listener) {
+    ownershipListeners.add(listener);
+    return () => {
+        ownershipListeners.delete(listener);
+    };
+}
+function handleStorageEvent(event) {
+    if (event.key !== leaseKey())
+        return;
+    if (!ownsLease)
+        return;
+    if (event.newValue === null) {
+        const lease = createLease();
+        writeLease(lease);
+        return;
+    }
+    const lease = readLeaseRaw();
+    if (!lease || lease.ownerId === currentOwnerId)
+        return;
+    loseOwnership();
+}

package/dist/inspector/changes/changesLog.d.ts

@@ -0,0 +1,46 @@
+import type { StyleRule } from "../projection/managedStylesheet.js";
+import type { ChangeRecord } from "./types.js";
+import { type CommitResult } from "./workspaceChanges.js";
+import type { StructuralChange } from "./structuralTypes.js";
+export { isComponentChange, isElementChange, isTextContentChange, isTextContentChangeValue, isPreviewableChange, isTokenChange, } from "./types.js";
+export type { ChangeRecord, ComponentChangeRecord, ElementChangeRecord, PreviewableChangeRecord, TextContentChangeRecord, TokenChangeRecord, RuntimeElementEvidence, } from "./types.js";
+export interface AppendChangesOptions {
+    /** The rendered target captured for each change key at commit time. */
+    verificationTargets?: ReadonlyMap<string, HTMLElement | null>;
+}
+declare function subscribe(cb: () => void): () => void;
+declare function getChangesSnapshot(): ChangeRecord[];
+export declare function getPendingRules(): StyleRule[];
+/** Append records and report whether canonical workspace state changed. */
+export declare function appendChanges(incoming: ChangeRecord[], options?: AppendChangesOptions): CommitResult;
+export declare function appendChange(change: ChangeRecord): CommitResult;
+export declare function revertChange(change: ChangeRecord): void;
+/**
+ * Removes source-verified records without allowing older undo snapshots to
+ * resurrect their managed previews.
+ *
+ * Agent handoff revisions identify records by the same stable key used by the
+ * canonical change model. Verification can therefore reconcile a subset while
+ * preserving newer, unsent edits and their remaining undo history.
+ */
+export declare function reconcileVerifiedChanges(verifiedKeys: ReadonlySet<string>): number;
+/** Atomically reconciles ordinary and structural intent from one agent handoff. */
+export declare function reconcileVerifiedWorkspaceChanges(verifiedKeys: ReadonlySet<string>, verifiedStructuralIds: ReadonlySet<string>): number;
+export declare function discardChangesForSelector(selector: string): void;
+/** Relink removes every CSS declaration owned by one durable rendered target. */
+export declare function discardChangesForInstanceOverride(overrideId: string): void;
+export declare function undo(): boolean;
+export declare function redo(): boolean;
+/**
+ * Replaces ordinary records while preserving structural intent. Restoring any
+ * dimension is terminal for the unified workspace timeline, so undo and redo
+ * history are reset for both dimensions.
+ */
+export declare function restoreChangeRecords(incoming: ChangeRecord[]): void;
+/** Restores every canonical workspace intent as one subscriber-visible snapshot. */
+export declare function loadWorkspaceChanges(incoming: readonly ChangeRecord[], structuralChanges: readonly StructuralChange[]): void;
+/** Clears all workspace intent and its unified undo/redo timeline. */
+export declare function clearWorkspace(): void;
+export declare function getChangesList(): ChangeRecord[];
+export { subscribe as subscribeChanges, getChangesSnapshot as getChanges };
+export declare function useChanges(): ChangeRecord[];