nudge-ui 0.2.0

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

@@ -0,0 +1,231 @@
+import type { ComponentOverride } from "../componentSemantics/types.js";
+import type { RenderedInstanceOverride } from "../changes/editModel.js";
+export declare const PROTOCOL_VERSION = 15;
+export interface FrameMessage {
+    type: string;
+    protocolVersion: number;
+}
+/**
+ * Pre-identity solicitation from a renderer whose bootstrap finished after
+ * the controller's load-time parent-ready (or whose document never received
+ * one). Carries no FrameIdentity: the whole point is that the renderer does
+ * not have one yet. The controller answers with ParentReadyMessage.
+ */
+export interface RendererHelloMessage extends FrameMessage {
+    type: "renderer-hello";
+}
+export interface FrameIdentity {
+    projectId: string;
+    workspaceId: string;
+    cardId: string;
+}
+export interface ParentReadyMessage extends FrameMessage {
+    type: "parent-ready";
+    projectId: string;
+    workspaceId: string;
+    cardId: string;
+}
+export interface RendererMessage extends FrameMessage, FrameIdentity {
+}
+export interface FrameReadyMessage extends RendererMessage {
+    type: "frame-ready";
+    url: string;
+    title: string;
+}
+export interface FrameMetadataMessage extends RendererMessage {
+    type: "frame-metadata";
+    url?: string;
+    title?: string;
+}
+export interface FrameLoadError extends RendererMessage {
+    type: "frame-error";
+    message: string;
+}
+export interface ReplaceStylesMessage extends FrameMessage {
+    type: "replace-styles";
+    projectId: string;
+    workspaceId: string;
+    cardId: string;
+    css: string;
+    revision: number;
+    /** Controller-owned durable targets; the renderer derives local markers. */
+    instanceOverrides: RenderedInstanceOverride[];
+    /** Controller-owned structural intent; renderers never own this change log. */
+    structuralChanges: import("../projection/structuralProjection.js").StructuralChange[];
+    /** Controller-owned durable rendered text intent. */
+    textContentChanges: import("../changes/types.js").TextContentChangeRecord[];
+    /** Controller-owned semantic component overrides for Canvas runtimes. */
+    componentOverrides: ComponentOverride[];
+}
+/** Renderer acknowledgement that one complete controller snapshot is applied. */
+export interface ProjectionAppliedMessage extends RendererMessage {
+    type: "projection-applied";
+    revision: number;
+}
+/**
+ * Renderer-local outcomes for one controller snapshot. This is diagnostic
+ * data only: accepting it never changes controller-owned structural intent.
+ */
+export interface StructuralProjectionReportMessage extends RendererMessage {
+    type: "structural-projection-report";
+    revision: number;
+    reports: import("../projection/structuralProjection.js").StructuralProjectionReport[];
+}
+/** Renderer-local CSS-instance outcomes for one controller snapshot. */
+export interface RenderedInstanceProjectionReportMessage extends RendererMessage {
+    type: "rendered-instance-projection-report";
+    revision: number;
+    reports: import("../projection/renderedInstance.js").DocumentProjectionReport[];
+}
+/** Renderer-local outcomes for one controller-owned text snapshot. */
+export interface TextProjectionReportMessage extends RendererMessage {
+    type: "text-projection-report";
+    revision: number;
+    reports: import("../projection/textProjection.js").TextProjectionReport[];
+}
+export interface NavigationIntentMessage extends RendererMessage {
+    type: "navigation-intent";
+    url: string;
+}
+export interface ElementHoverMessage extends RendererMessage {
+    type: "element-hover";
+    cid: string;
+    selector: string;
+    src: string;
+    elementId: string;
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | null;
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    } | null;
+    borders: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    } | null;
+}
+/** Modifier state stays inside one renderer frame; the parent never infers it
+ * from its own keyboard events because focus lives in the iframe. */
+export interface ElementMeasureStateMessage extends RendererMessage {
+    type: "element-measure-state";
+    altKey: boolean;
+    pointerOverPage: boolean;
+}
+export interface ElementClickMessage extends RendererMessage {
+    type: "element-click";
+    cid: string;
+    selector: string;
+    src: string;
+    elementId: string;
+    file: string;
+    line: number;
+    component: string;
+    /** True for a Shift-click that toggles this target in the selection group. */
+    additive?: boolean;
+}
+/** Renderer request to clear the controller-owned element selection. */
+export interface ElementDeselectMessage extends RendererMessage {
+    type: "element-deselect";
+}
+export interface ElementDragStartMessage extends RendererMessage {
+    type: "element-drag-start";
+    cid: string;
+    src: string;
+    elementId: string;
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export interface ElementDragMoveMessage extends RendererMessage {
+    type: "element-drag-move";
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export interface ElementDragEndMessage extends RendererMessage {
+    type: "element-drag-end";
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export interface ElementDeleteMessage extends RendererMessage {
+    type: "element-delete";
+    cid: string;
+    src: string;
+    elementId: string;
+}
+export interface ElementNudgeMessage extends RendererMessage {
+    type: "element-nudge";
+    cid: string;
+    src: string;
+    elementId: string;
+    key: "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight";
+}
+/** A renderer may request history navigation; only the parent changes history. */
+export interface HistoryRequestMessage extends RendererMessage {
+    type: "history-request";
+    action: "undo" | "redo";
+}
+export interface ExternalNavigationMessage extends RendererMessage {
+    type: "external-navigation";
+    url: string;
+}
+export interface PanStartMessage extends RendererMessage {
+    type: "pan-start";
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export interface PanMoveMessage extends RendererMessage {
+    type: "pan-move";
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export interface PanEndMessage extends RendererMessage {
+    type: "pan-end";
+}
+/** Keeps iframe pointer handling in sync when Space is held in the controller. */
+export interface PanModifierMessage extends RendererMessage {
+    type: "pan-modifier";
+    spaceHeld: boolean;
+}
+/** Proxies modified wheel gestures that originate inside an iframe card. */
+export interface ZoomMessage extends RendererMessage {
+    type: "zoom";
+    deltaY: number;
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export type FrameProtocolMessage = ParentReadyMessage | RendererHelloMessage | FrameReadyMessage | FrameMetadataMessage | FrameLoadError | ReplaceStylesMessage | ProjectionAppliedMessage | StructuralProjectionReportMessage | RenderedInstanceProjectionReportMessage | TextProjectionReportMessage | NavigationIntentMessage | ElementHoverMessage | ElementMeasureStateMessage | ElementClickMessage | ElementDeselectMessage | ElementDragStartMessage | ElementDragMoveMessage | ElementDragEndMessage | ElementDeleteMessage | ElementNudgeMessage | HistoryRequestMessage | ExternalNavigationMessage | PanStartMessage | PanMoveMessage | PanEndMessage | PanModifierMessage | ZoomMessage;
+export declare function setRendererIdentity(identity: FrameIdentity): void;
+export declare function clearRendererIdentity(expected?: FrameIdentity): void;
+export declare function getRendererIdentity(): FrameIdentity | null;
+export declare function isRendererMessageFor(value: unknown, identity: FrameIdentity): value is RendererMessage;
+/** Strict JSON-only schema for selecting an element from a renderer frame. */
+export declare function isElementClickMessage(value: unknown, identity: FrameIdentity): value is ElementClickMessage;
+/** Strict JSON-only schema for renderer diagnostics before the parent records them. */
+export declare function isStructuralProjectionReportMessage(value: unknown, identity: FrameIdentity): value is StructuralProjectionReportMessage;
+/** Strict JSON-only schema for renderer CSS-instance diagnostics. */
+export declare function isRenderedInstanceProjectionReportMessage(value: unknown, identity: FrameIdentity): value is RenderedInstanceProjectionReportMessage;
+/** Strict JSON-only schema for renderer rendered-text diagnostics. */
+export declare function isTextProjectionReportMessage(value: unknown, identity: FrameIdentity): value is TextProjectionReportMessage;
+/** Strict JSON-only acknowledgement for a fully applied Canvas snapshot. */
+export declare function isProjectionAppliedMessage(value: unknown, identity: FrameIdentity): value is ProjectionAppliedMessage;
+export declare function isComponentOverrideList(value: unknown): value is ComponentOverride[];
+export declare function sendToParent(msg: FrameProtocolMessage): void;

package/dist/inspector/canvas/frameProtocol.js

@@ -0,0 +1,165 @@
+import { isDocumentProjectionReport } from "../projection/renderedInstance.js";
+import { isTextProjectionReport } from "../projection/textProjection.js";
+import { isStructuralProjectionReport } from "../projection/structuralProjectionBoundary.js";
+// v15 adds renderer-to-controller element deselection for Canvas frames. v14
+// adds border widths to hover geometry so containment measurements can exclude
+// the container border. v13 adds source-parent-aware structural moves and
+// bounded structural failure reasons to the full projection snapshot. v12
+// added the projection-applied acknowledgement: the controller can avoid
+// rereading a Canvas iframe until the renderer has applied its revision. v11
+// added the renderer-hello handshake solicitation for runtimes whose boot
+// completes after the controller's load-time parent-ready.
+export const PROTOCOL_VERSION = 15;
+let rendererIdentity = null;
+export function setRendererIdentity(identity) {
+    rendererIdentity = identity;
+}
+export function clearRendererIdentity(expected) {
+    if (expected === undefined || rendererIdentity === expected)
+        rendererIdentity = null;
+}
+export function getRendererIdentity() {
+    return rendererIdentity;
+}
+export function isRendererMessageFor(value, identity) {
+    if (!value || typeof value !== "object")
+        return false;
+    const message = value;
+    return message.protocolVersion === PROTOCOL_VERSION
+        && message.projectId === identity.projectId
+        && message.workspaceId === identity.workspaceId
+        && message.cardId === identity.cardId;
+}
+/** Strict JSON-only schema for selecting an element from a renderer frame. */
+export function isElementClickMessage(value, identity) {
+    if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
+        return false;
+    if (!hasOnlyKeys(value, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId",
+        "cid", "selector", "src", "elementId", "file", "line", "component", "additive",
+    ]))
+        return false;
+    const line = ownValue(value, "line");
+    const additive = ownValue(value, "additive");
+    return ownValue(value, "type") === "element-click"
+        && typeof ownValue(value, "cid") === "string"
+        && typeof ownValue(value, "selector") === "string"
+        && typeof ownValue(value, "src") === "string"
+        && typeof ownValue(value, "elementId") === "string"
+        && typeof ownValue(value, "file") === "string"
+        && typeof line === "number" && Number.isSafeInteger(line) && line >= 0
+        && typeof ownValue(value, "component") === "string"
+        && (additive === undefined || typeof additive === "boolean");
+}
+/** Strict JSON-only schema for renderer diagnostics before the parent records them. */
+export function isStructuralProjectionReportMessage(value, identity) {
+    if (!isRendererMessageFor(value, identity) || !value || typeof value !== "object")
+        return false;
+    const message = value;
+    if (!hasOnlyKeys(message, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId", "revision", "reports",
+    ]))
+        return false;
+    return message.type === "structural-projection-report"
+        && Number.isSafeInteger(message.revision)
+        && message.revision >= 0
+        && Array.isArray(message.reports)
+        && message.reports.every(isStructuralProjectionReport);
+}
+/** Strict JSON-only schema for renderer CSS-instance diagnostics. */
+export function isRenderedInstanceProjectionReportMessage(value, identity) {
+    if (!isRendererMessageFor(value, identity) || !value || typeof value !== "object")
+        return false;
+    const message = value;
+    if (!hasOnlyKeys(message, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId", "revision", "reports",
+    ]))
+        return false;
+    return message.type === "rendered-instance-projection-report"
+        && Number.isSafeInteger(message.revision)
+        && message.revision >= 0
+        && Array.isArray(message.reports)
+        && message.reports.every(isDocumentProjectionReport);
+}
+/** Strict JSON-only schema for renderer rendered-text diagnostics. */
+export function isTextProjectionReportMessage(value, identity) {
+    if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
+        return false;
+    if (!hasOnlyKeys(value, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId", "revision", "reports",
+    ]))
+        return false;
+    const type = ownValue(value, "type");
+    const revision = ownValue(value, "revision");
+    const reports = ownValue(value, "reports");
+    return type === "text-projection-report"
+        && typeof revision === "number" && Number.isSafeInteger(revision) && revision >= 0
+        && Array.isArray(reports)
+        && reports.every(isTextProjectionReport);
+}
+/** Strict JSON-only acknowledgement for a fully applied Canvas snapshot. */
+export function isProjectionAppliedMessage(value, identity) {
+    if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
+        return false;
+    if (!hasOnlyKeys(value, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId", "revision",
+    ]))
+        return false;
+    const type = ownValue(value, "type");
+    const revision = ownValue(value, "revision");
+    return type === "projection-applied"
+        && typeof revision === "number"
+        && Number.isSafeInteger(revision)
+        && revision >= 0;
+}
+export function isComponentOverrideList(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((candidate) => {
+        if (!isProtocolObject(candidate)
+            || !hasOnlyKeys(candidate, ["framework", "callsiteId", "prop", "value"]))
+            return false;
+        const framework = ownValue(candidate, "framework");
+        const callsiteId = ownValue(candidate, "callsiteId");
+        const prop = ownValue(candidate, "prop");
+        const overrideValue = ownValue(candidate, "value");
+        return framework === "react"
+            && typeof callsiteId === "string" && callsiteId.length > 0
+            && typeof prop === "string" && prop.length > 0
+            && (typeof overrideValue === "string"
+                || typeof overrideValue === "number" && Number.isFinite(overrideValue)
+                || typeof overrideValue === "boolean");
+    });
+}
+function isProtocolObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function ownValue(value, key) {
+    switch (key) {
+        case "additive": return value.additive;
+        case "cardId": return value.cardId;
+        case "cid": return value.cid;
+        case "callsiteId": return value.callsiteId;
+        case "framework": return value.framework;
+        case "elementId": return value.elementId;
+        case "file": return value.file;
+        case "line": return value.line;
+        case "prop": return value.prop;
+        case "projectId": return value.projectId;
+        case "protocolVersion": return value.protocolVersion;
+        case "reports": return value.reports;
+        case "revision": return value.revision;
+        case "type": return value.type;
+        case "selector": return value.selector;
+        case "src": return value.src;
+        case "component": return value.component;
+        case "value": return value.value;
+        case "workspaceId": return value.workspaceId;
+    }
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+export function sendToParent(msg) {
+    window.parent.postMessage(msg, window.location.origin);
+}

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

@@ -0,0 +1,8 @@
+export declare function findClosestAnchor(target: EventTarget | null): HTMLAnchorElement | null;
+export declare function isEligibleNavigation(anchor: HTMLAnchorElement, event: MouseEvent): boolean;
+export declare function hasDifferentRoute(anchor: HTMLAnchorElement): boolean;
+/**
+ * Returns whether the renderer should leave an anchor's browser behavior
+ * intact instead of consuming it as an editing click.
+ */
+export declare function shouldPreserveNativeLinkActivation(anchor: HTMLAnchorElement, event: MouseEvent): boolean;

package/dist/inspector/canvas/linkEligibility.js

@@ -0,0 +1,68 @@
+export function findClosestAnchor(target) {
+    if (!(target instanceof Element))
+        return null;
+    if (target instanceof HTMLAnchorElement)
+        return target;
+    return target.closest("a");
+}
+export function isEligibleNavigation(anchor, event) {
+    if (event.ctrlKey || event.metaKey || event.shiftKey)
+        return false;
+    if (anchor.hasAttribute("download"))
+        return false;
+    if (anchor.target && anchor.target !== "" && anchor.target !== "_self")
+        return false;
+    if (anchor.protocol !== "http:" && anchor.protocol !== "https:")
+        return false;
+    try {
+        const url = new URL(anchor.href);
+        if (url.origin !== window.location.origin)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+export function hasDifferentRoute(anchor) {
+    try {
+        const url = new URL(anchor.href);
+        if (url.pathname !== window.location.pathname)
+            return true;
+        if (url.search !== window.location.search)
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns whether the renderer should leave an anchor's browser behavior
+ * intact instead of consuming it as an editing click.
+ */
+export function shouldPreserveNativeLinkActivation(anchor, event) {
+    // Command/Ctrl-click is the deep-selection gesture. Shift makes it the
+    // explicit application-activation gesture instead.
+    if (event.metaKey || event.ctrlKey)
+        return event.shiftKey;
+    // Shift-click is the additive inspector-selection gesture. Do not let a
+    // link navigate or preserve its native activation in that mode.
+    if (event.shiftKey)
+        return false;
+    if (anchor.hasAttribute("download"))
+        return true;
+    if (anchor.target && anchor.target !== "" && anchor.target !== "_self")
+        return true;
+    if (anchor.protocol !== "http:" && anchor.protocol !== "https:")
+        return true;
+    try {
+        const url = new URL(anchor.href);
+        if (url.origin !== window.location.origin)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    return !hasDifferentRoute(anchor);
+}

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

@@ -0,0 +1,8 @@
+import type { MeasurementSegment } from "../overlay/measurementGeometry.js";
+import type { Rect } from "../overlay/overlayGeometry.js";
+/**
+ * Maps iframe-local measurement geometry into the Canvas board's screen
+ * coordinate system. Distances deliberately remain in local CSS pixels so
+ * their labels stay meaningful regardless of the board zoom.
+ */
+export declare function projectMeasurementSegments(iframeRect: Rect, segments: MeasurementSegment[], zoom: number): MeasurementSegment[];

package/dist/inspector/canvas/measurementProjection.js

@@ -0,0 +1,16 @@
+/**
+ * Maps iframe-local measurement geometry into the Canvas board's screen
+ * coordinate system. Distances deliberately remain in local CSS pixels so
+ * their labels stay meaningful regardless of the board zoom.
+ */
+export function projectMeasurementSegments(iframeRect, segments, zoom) {
+    const projectPoint = (point) => ({
+        x: iframeRect.left + point.x * zoom,
+        y: iframeRect.top + point.y * zoom,
+    });
+    return segments.map((segment) => ({
+        ...segment,
+        from: projectPoint(segment.from),
+        to: projectPoint(segment.to),
+    }));
+}

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

@@ -0,0 +1,7 @@
+export interface NormalizedUrl {
+    origin: string;
+    pathname: string;
+    search: string;
+}
+export declare function normalizeUrl(url: string): NormalizedUrl | null;
+export declare function normalizedUrlKey(normalized: NormalizedUrl): string;

package/dist/inspector/canvas/normalizeUrl.js

@@ -0,0 +1,27 @@
+export function normalizeUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return {
+            origin: parsed.origin,
+            pathname: parsed.pathname,
+            search: parsed.search,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizedUrlKey(normalized) {
+    return `${normalized.origin}${canonicalRoutePath(normalized.pathname)}${normalized.search}`;
+}
+/**
+ * Directory-index pages resolve to the directory URL: `/` and `/index.html`
+ * are one route served from one file on every supported dev server, so card
+ * deduplication must treat them as the same key or link discovery spawns a
+ * duplicate card for the page already on the board.
+ */
+function canonicalRoutePath(pathname) {
+    // "/docs/index.html" becomes the directory form "/docs/"; a bare
+    // "/index.html" becomes "/".
+    return pathname.replace(/\/index\.html?$/i, "/");
+}

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

@@ -0,0 +1,41 @@
+import type { CanvasCard } from "./canvasStore.js";
+import { type PreviewDocument } from "../changes/previewDiagnostics.js";
+import { type CompiledManagedStyles } from "../projection/workspaceProjection.js";
+export declare const PROJECT_ID: string;
+export declare const WORKSPACE_ID: `${string}-${string}-${string}-${string}-${string}`;
+export interface CanvasProjectionStatus {
+    sentRevision: number;
+    appliedRevision: number;
+}
+/** Returns the current value-based identity for one Canvas card document. */
+export declare function getCanvasPreviewDocument(cardId: string): PreviewDocument;
+/** Invalidates a card's current document before its iframe is replaced. */
+export declare function invalidateCanvasPreviewDocument(cardId: string): void;
+export declare function computeProjection(): {
+    css: string;
+    revision: number;
+    sourceRevision: number;
+    managedStyles: CompiledManagedStyles;
+    instanceOverrides: readonly import("../changes/editModel.js").RenderedInstanceOverride[];
+    structuralChanges: readonly import("../changes/structuralTypes.js").StructuralChange[];
+    textContentChanges: readonly import("../changes/editModel.js").TextContentChangeRecord[];
+    componentOverrides: readonly import("../componentSemantics/types.js").ComponentOverride[];
+};
+export declare function resetProjectionRevision(): void;
+export declare function sendProjectionToCard(card: CanvasCard, iframe: HTMLIFrameElement): void;
+export declare function registerCardFrameSource(cardId: string, iframe: HTMLIFrameElement): void;
+export declare function registerCardFrame(cardId: string, iframe: HTMLIFrameElement): void;
+export declare function unregisterCardFrame(cardId: string): void;
+export declare function getRegisteredFrames(): ReadonlyMap<string, HTMLIFrameElement>;
+export declare function findCanvasFrameBySource(source: MessageEventSource | null): {
+    cardId: string;
+    iframe: HTMLIFrameElement;
+} | null;
+export declare function subscribeFrameRegistry(listener: () => void): () => void;
+/** Records the highest complete projection revision accepted by one frame. */
+export declare function recordCanvasProjectionApplied(cardId: string, appliedRevision: number): void;
+/** Returns projection progress for the document containing a selected element. */
+export declare function getCanvasProjectionStatus(doc: Document): CanvasProjectionStatus | null;
+export declare function subscribeCanvasProjectionAcknowledgements(listener: () => void): () => void;
+export declare function getCanvasProjectionAcknowledgementVersion(): number;
+export declare function projectToAllReadyCards(): void;