nudge-ui 0.2.0

package/dist/inspector/changes/changesLog.js

@@ -0,0 +1,209 @@
+import { useSyncExternalStore } from "react";
+import { getSelectedElement } from "../selection/selectionStore.js";
+import { changeKey, } from "./model.js";
+import { buildManagedStyleRules, verifyManagedStyleProjection, } from "./managedStyleProjection.js";
+import { isPreviewableChange } from "./types.js";
+import { cancelInlineTextForClear } from "../inline-text/inlineTextLifecycle.js";
+import { workspaceChangeStore, } from "./workspaceChanges.js";
+import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, publishPreviewDiagnostic, } from "./previewDiagnostics.js";
+import { clearStructuralProjectionReports, pruneStructuralProjectionReports } from "../projection/structuralProjection.js";
+import { applyHostWorkspaceProjection, compileWorkspaceProjection, } from "../projection/workspaceProjection.js";
+export { isComponentChange, isElementChange, isTextContentChange, isTextContentChangeValue, isPreviewableChange, isTokenChange, } from "./types.js";
+/**
+ * Deferred delta verification (0044). Only the keys touched by a mutation are
+ * re-verified, and the probe work runs coalesced off the synchronous commit
+ * path (requestIdleCallback, falling back to rAF / a macrotask).
+ */
+let pendingVerificationTargets = new Map();
+let verificationHandle = null;
+function subscribe(cb) {
+    return workspaceChangeStore.subscribe(cb);
+}
+function getChangesSnapshot() {
+    // SAFETY: The public change model is the concrete record union stored by
+    // the workspace snapshot; this module preserves the mutable array facade.
+    return workspaceChangeStore.getSnapshot().changes;
+}
+export function getPendingRules() {
+    return buildManagedStyleRules(getChangesSnapshot());
+}
+function reapply(workspace) {
+    applyHostWorkspaceProjection(compileWorkspaceProjection(workspace));
+}
+function flushVerification() {
+    verificationHandle = null;
+    const targets = pendingVerificationTargets;
+    pendingVerificationTargets = new Map();
+    if (targets.size === 0)
+        return;
+    const current = getChangesSnapshot();
+    const attempt = beginPreviewAttempt(getHostPreviewDocument(), workspaceChangeStore.getSnapshot().revision);
+    if (!attempt)
+        return;
+    for (let i = 0; i < current.length; i++) {
+        const change = current[i];
+        if (!isPreviewableChange(change))
+            continue;
+        const key = changeKey(change);
+        if (!targets.has(key))
+            continue;
+        const result = verifyManagedStyleProjection(change, targets.get(key) ?? null);
+        if (result) {
+            publishPreviewDiagnostic(attempt, key, result);
+        }
+    }
+}
+function scheduleVerification() {
+    if (verificationHandle !== null)
+        return;
+    const view = typeof window !== "undefined" ? window : undefined;
+    if (view && typeof view.requestIdleCallback === "function") {
+        verificationHandle = view.requestIdleCallback(() => {
+            flushVerification();
+        }, { timeout: 200 });
+    }
+    else if (view && typeof view.requestAnimationFrame === "function") {
+        verificationHandle = view.requestAnimationFrame(() => {
+            flushVerification();
+        });
+    }
+    else {
+        verificationHandle = setTimeout(() => {
+            flushVerification();
+        }, 0);
+    }
+}
+/**
+ * Marks the given change keys for deferred re-verification. Undo/redo/revert
+ * re-verify the surviving set (their sheet projection changed globally).
+ * A plain commit re-verifies the full surviving set as well: a new rule can
+ * change cascade/specificity for earlier changes, so verifying only incoming
+ * records would drop their conflict warnings.
+ */
+function markForVerification(keys, verificationTargets) {
+    const selectedElement = getSelectedElement()?.domElement ?? null;
+    let added = false;
+    for (const key of keys) {
+        if (!pendingVerificationTargets.has(key))
+            added = true;
+        // Keep the latest commit context for a merged key. The element may be in
+        // an iframe, so this is also the document boundary for verification.
+        pendingVerificationTargets.set(key, verificationTargets?.get(key) ?? selectedElement);
+    }
+    if (added)
+        scheduleVerification();
+}
+/** Append records and report whether canonical workspace state changed. */
+export function appendChanges(incoming, options = {}) {
+    const result = workspaceChangeStore.commitChangeRecords(incoming);
+    if (result !== "applied")
+        return result;
+    reapply(workspaceChangeStore.getSnapshot());
+    // Re-verify the full surviving set so earlier diagnostics are refreshed at
+    // the new revision instead of being orphaned at the old one.
+    markForVerification(getChangesSnapshot().map(changeKey), options.verificationTargets);
+    return result;
+}
+export function appendChange(change) {
+    return appendChanges([change]);
+}
+export function revertChange(change) {
+    if (!workspaceChangeStore.revertChangeRecord(change))
+        return;
+    reapply(workspaceChangeStore.getSnapshot());
+    markForVerification(getChangesSnapshot().map(changeKey));
+}
+/**
+ * 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 function reconcileVerifiedChanges(verifiedKeys) {
+    const removed = reconcileVerifiedWorkspaceChanges(verifiedKeys, new Set());
+    if (removed === 0)
+        return 0;
+    return removed;
+}
+/** Atomically reconciles ordinary and structural intent from one agent handoff. */
+export function reconcileVerifiedWorkspaceChanges(verifiedKeys, verifiedStructuralIds) {
+    const removed = workspaceChangeStore.reconcileWorkspaceChanges(verifiedKeys, verifiedStructuralIds);
+    if (removed === 0)
+        return 0;
+    reapply(workspaceChangeStore.getSnapshot());
+    pruneStructuralProjectionReports(verifiedStructuralIds);
+    markForVerification(getChangesSnapshot().map(changeKey));
+    return removed;
+}
+export function discardChangesForSelector(selector) {
+    if (!workspaceChangeStore.discardChangeRecords({ kind: "selector", selector }))
+        return;
+    reapply(workspaceChangeStore.getSnapshot());
+    markForVerification(getChangesSnapshot().map(changeKey));
+}
+/** Relink removes every CSS declaration owned by one durable rendered target. */
+export function discardChangesForInstanceOverride(overrideId) {
+    if (!workspaceChangeStore.discardChangeRecords({ kind: "instance-override", id: overrideId }))
+        return;
+    reapply(workspaceChangeStore.getSnapshot());
+    markForVerification(getChangesSnapshot().map(changeKey));
+}
+export function undo() {
+    const undone = workspaceChangeStore.undoWorkspaceChange();
+    if (undone)
+        reapply(workspaceChangeStore.getSnapshot());
+    if (undone)
+        markForVerification(getChangesSnapshot().map(changeKey));
+    return undone;
+}
+export function redo() {
+    const redone = workspaceChangeStore.redoWorkspaceChange();
+    if (redone)
+        reapply(workspaceChangeStore.getSnapshot());
+    if (redone)
+        markForVerification(getChangesSnapshot().map(changeKey));
+    return redone;
+}
+/**
+ * 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 function restoreChangeRecords(incoming) {
+    // A restored session replaces the change set and may also switch the active
+    // document. Do not let a deferred verification from the previous session
+    // inspect a newly loaded record with its old selection context.
+    pendingVerificationTargets.clear();
+    clearPreviewDiagnostics();
+    const workspace = workspaceChangeStore.getSnapshot();
+    workspaceChangeStore.restoreWorkspaceChanges({ changes: incoming, structuralChanges: workspace.structuralChanges });
+    reapply(workspaceChangeStore.getSnapshot());
+}
+/** Restores every canonical workspace intent as one subscriber-visible snapshot. */
+export function loadWorkspaceChanges(incoming, structuralChanges) {
+    pendingVerificationTargets.clear();
+    clearPreviewDiagnostics();
+    clearStructuralProjectionReports();
+    workspaceChangeStore.restoreWorkspaceChanges({ changes: incoming, structuralChanges });
+    reapply(workspaceChangeStore.getSnapshot());
+}
+/** Clears all workspace intent and its unified undo/redo timeline. */
+export function clearWorkspace() {
+    // A pending blur/composition timer must not be able to append a draft after
+    // the canonical set has been cleared.
+    cancelInlineTextForClear();
+    pendingVerificationTargets.clear();
+    clearPreviewDiagnostics();
+    clearStructuralProjectionReports();
+    workspaceChangeStore.clearWorkspaceChanges();
+    reapply(workspaceChangeStore.getSnapshot());
+}
+export function getChangesList() {
+    return [...getChangesSnapshot()];
+}
+export { subscribe as subscribeChanges, getChangesSnapshot as getChanges };
+export function useChanges() {
+    return useSyncExternalStore(subscribe, getChangesSnapshot, getChangesSnapshot);
+}

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

@@ -0,0 +1,98 @@
+import type { TokenEntry } from "../../css/model/index.js";
+import type { ComponentChangeRecord, ComponentChangeTarget, ComponentInvocationEvidence, ComponentPropBaseline, ComponentPropValue } from "../componentSemantics/types.js";
+import type { EditScope, RenderedInstanceOverride, StyleRuleContext, TextBindingEvidence, TextContentChangeRecord, TextProjectionTarget } from "./editModel.js";
+import { type ChangeRecord, type ElementChangeRecord, type TokenChangeRecord } from "./types.js";
+/** The token fields that are safe to retain in a durable change record. */
+export interface SerializableTokenRef {
+    name: string;
+    value: string;
+    source: string;
+    cssValue?: string;
+    cssName?: string;
+    adapter?: string;
+    origin?: TokenEntry["origin"];
+}
+export interface SerializableElementChange {
+    kind?: "element";
+    cid: string;
+    file: string;
+    line: number;
+    column?: number;
+    selector: string;
+    property: string;
+    sourceProperty?: string;
+    sourceAuthoredValue?: string;
+    oldToken: SerializableTokenRef | null;
+    newToken: SerializableTokenRef | null;
+    rawValue?: string;
+    oldRawValue?: string;
+    source: {
+        file: string;
+        line: number;
+        component: string;
+    };
+    runtimeEvidence?: NonNullable<ElementChangeRecord["runtimeEvidence"]>;
+    scope?: EditScope;
+    instanceOverride?: RenderedInstanceOverride;
+    state?: NonNullable<ElementChangeRecord["state"]>;
+}
+export interface SerializableTokenChange {
+    kind: "token";
+    tokenName: string;
+    file: string;
+    line: number;
+    selector: string;
+    property: string;
+    rawValue: string;
+    oldRawValue: string;
+    important?: boolean;
+    context: StyleRuleContext;
+    contextLabel: string;
+    source: {
+        file: string;
+        line: number;
+        component: string;
+    };
+}
+export interface SerializableComponentChange {
+    kind: "component-prop";
+    target: ComponentChangeTarget;
+    property: string;
+    before: ComponentPropBaseline;
+    after: ComponentPropValue;
+    authoredAs: ComponentChangeRecord["authoredAs"];
+    scope?: EditScope;
+    evidence?: ComponentInvocationEvidence;
+}
+export interface SerializableTextContentChange {
+    kind: "text-content";
+    id: string;
+    target: TextProjectionTarget;
+    source: {
+        file: string;
+        line: number;
+        column: number;
+        component: string;
+    };
+    selector: string;
+    before: string;
+    after: string;
+    authoredAs: TextContentChangeRecord["authoredAs"];
+    scope?: EditScope;
+    evidence?: TextBindingEvidence;
+}
+export type SerializableChange = SerializableElementChange | SerializableTokenChange | SerializableComponentChange | SerializableTextContentChange;
+export declare function isSerializableChange(value: unknown): value is SerializableChange;
+export declare function isSerializableElementChangeValue(value: unknown): value is SerializableElementChange;
+export declare function isSerializableTokenChangeValue(value: unknown): value is SerializableTokenChange;
+export declare function isSerializableComponentChangeValue(value: unknown): value is SerializableComponentChange;
+export declare function serializeChange(change: ChangeRecord): SerializableChange | null;
+export declare function serializeElementChange(change: ElementChangeRecord): SerializableElementChange | null;
+export declare function serializeTokenChange(change: TokenChangeRecord): SerializableTokenChange;
+export declare function serializeComponentChange(change: ComponentChangeRecord): SerializableComponentChange;
+export declare function serializeTextContentChange(change: TextContentChangeRecord): SerializableTextContentChange;
+export declare function deserializeChange(serialized: SerializableChange): ChangeRecord;
+export declare function deserializeElementChange(serialized: SerializableElementChange): ElementChangeRecord;
+export declare function deserializeTokenChange(serialized: SerializableTokenChange): TokenChangeRecord;
+export declare function deserializeComponentChange(serialized: SerializableComponentChange): ComponentChangeRecord;
+export declare function deserializeTextContentChange(serialized: SerializableTextContentChange): TextContentChangeRecord;