@agent-native/core 0.92.7 → 0.92.8

package/corpus/templates/design/app/components/design/design-canvas/external-preview.ts

@@ -0,0 +1,137 @@
+export function liveEditEndpointUrl(
+  bridgeUrl: string,
+  previewUrl: string,
+  options: {
+    previewToken: string;
+    includeEditorBridge?: boolean;
+    bridgeKey?: string;
+  },
+): string {
+  const endpoint = new URL("/live-edit", bridgeUrl);
+  endpoint.searchParams.set("url", previewUrl);
+  endpoint.searchParams.set("previewToken", options.previewToken);
+  if (options?.includeEditorBridge === false) {
+    endpoint.searchParams.set("bridge", "0");
+  } else if (options?.bridgeKey) {
+    endpoint.searchParams.set("bridgeKey", options.bridgeKey);
+  }
+  return endpoint.toString();
+}
+
+export function resolveLiveEditPreviewUrl(args: {
+  sourceType: string | undefined;
+  bridgeUrl: string | undefined;
+  previewToken: string | undefined;
+  previewUrl: string | null | undefined;
+  bridgeKey: string;
+  registeredBridgeKey: string | null;
+}): string | null {
+  if (
+    args.sourceType !== "localhost" ||
+    !args.bridgeUrl ||
+    !args.previewToken ||
+    !args.previewUrl
+  ) {
+    return null;
+  }
+  // Every localhost mode registers a keyed injected script before rendering:
+  // editable modes include editor chrome, while Interact/read-only modes use
+  // the gesture-only bridge. Waiting for the matching key prevents a raw URL
+  // load followed by a second proxied load (the flash/state-loss regression).
+  if (args.registeredBridgeKey !== args.bridgeKey) return null;
+  return liveEditEndpointUrl(args.bridgeUrl, args.previewUrl, {
+    previewToken: args.previewToken,
+    bridgeKey: args.bridgeKey,
+  });
+}
+
+export function shouldUseIframeLoadReadyFallback(
+  usesLiveEditEditorBridge: boolean,
+): boolean {
+  return !usesLiveEditEditorBridge;
+}
+
+export function shouldFetchExternalSourceSnapshot(args: {
+  sourceType: string | undefined;
+  bridgeUrl: string | undefined;
+  previewToken: string | undefined;
+  previewUrl: string | null | undefined;
+  hasSnapshotConsumer: boolean;
+}): boolean {
+  return Boolean(
+    args.sourceType === "localhost" &&
+    args.bridgeUrl &&
+    args.previewToken &&
+    args.previewUrl &&
+    args.hasSnapshotConsumer,
+  );
+}
+
+const SCRIPT_TAG_RE = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
+const SCRIPT_SRC_RE = /\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+
+function isKnownDevRuntimeScriptSource(value: string): boolean {
+  try {
+    const parsed = new URL(value, "http://localhost");
+    return (
+      parsed.pathname === "/@vite/client" ||
+      parsed.pathname === "/@react-refresh" ||
+      parsed.pathname.includes("/__x00__react-refresh")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove development-server HTML transforms before treating a live snapshot as
+ * writable source. Vite injects its HMR client and React Refresh preamble into
+ * the served document; persisting either back to index.html corrupts the real
+ * source and can duplicate refresh runtimes on every Apply-to-source cycle.
+ * User-authored module scripts and inline application scripts are preserved.
+ */
+export function sanitizeLocalhostSourceSnapshotHtml(html: string): string {
+  return html.replace(
+    SCRIPT_TAG_RE,
+    (fullScript, rawAttributes: string, inlineBody: string) => {
+      const srcMatch = rawAttributes.match(SCRIPT_SRC_RE);
+      const src = srcMatch?.[1] ?? srcMatch?.[2] ?? srcMatch?.[3] ?? "";
+      if (src && isKnownDevRuntimeScriptSource(src)) return "";
+
+      const knownRefreshPreamble =
+        inlineBody.includes("/@react-refresh") ||
+        inlineBody.includes("RefreshRuntime.injectIntoGlobalHook") ||
+        inlineBody.includes("__vite_plugin_react_preamble_installed__");
+      const knownViteClientInjection =
+        inlineBody.includes("/@vite/client") &&
+        (inlineBody.includes("import") || inlineBody.includes("__vite"));
+      return knownRefreshPreamble || knownViteClientInjection ? "" : fullScript;
+    },
+  );
+}
+
+const EXTERNAL_PREVIEW_IFRAME_SANDBOX =
+  "allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-same-origin";
+const EDITABLE_INLINE_IFRAME_SANDBOX =
+  "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-same-origin";
+const READ_ONLY_INLINE_IFRAME_SANDBOX =
+  "allow-scripts allow-popups allow-popups-to-escape-sandbox";
+
+export function getDesignCanvasIframeSandbox(args: {
+  externalPreview: boolean;
+  readOnly: boolean;
+}): string {
+  if (args.externalPreview) return EXTERNAL_PREVIEW_IFRAME_SANDBOX;
+  return args.readOnly
+    ? READ_ONLY_INLINE_IFRAME_SANDBOX
+    : EDITABLE_INLINE_IFRAME_SANDBOX;
+}
+
+const SNAPSHOT_RETRY_BASE_DELAY_MS = 1500;
+const SNAPSHOT_RETRY_MAX_DELAY_MS = 15000;
+
+export function getSnapshotRetryDelayMs(attempt: number): number {
+  const safeAttempt = Number.isFinite(attempt) ? Math.max(0, attempt) : 0;
+  const delay = SNAPSHOT_RETRY_BASE_DELAY_MS * 2 ** safeAttempt;
+  return Math.min(SNAPSHOT_RETRY_MAX_DELAY_MS, delay);
+}

package/corpus/templates/design/app/components/design/design-canvas/file-drop.ts

@@ -0,0 +1,10 @@
+export function isOsFileDragEvent(event: {
+  dataTransfer: { types: readonly string[] | DOMStringList } | null;
+}): boolean {
+  const types = event.dataTransfer?.types;
+  if (!types) return false;
+  for (let index = 0; index < types.length; index += 1) {
+    if (types[index] === "Files") return true;
+  }
+  return false;
+}

package/corpus/templates/design/app/components/design/design-canvas/hit-test.ts

@@ -0,0 +1,23 @@
+import { hitTestBridgeScript } from "../../../../.generated/bridge/hit-test.generated";
+
+export const LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT = `
+<script data-agent-native-hit-test-bridge>
+${hitTestBridgeScript}
+</script>
+`;
+
+export function appendHitTestResponder(html: string): string {
+  if (html.includes("</body>")) {
+    return html.replace(
+      "</body>", // i18n-ignore generated iframe HTML marker
+      LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT + "</body>", // i18n-ignore generated iframe HTML injection
+    );
+  }
+  if (html.includes("</html>")) {
+    return html.replace(
+      "</html>", // i18n-ignore generated iframe HTML marker
+      LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT + "</html>", // i18n-ignore generated iframe HTML injection
+    );
+  }
+  return html + LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT;
+}

package/corpus/templates/design/app/components/design/design-canvas/iframe-events.ts

@@ -0,0 +1,23 @@
+import type { ElementInfo } from "../types";
+
+export interface IframeHotkeyPayload {
+  key: string;
+  code: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+  repeat: boolean;
+}
+
+export interface IframeFigmaClipboardPastePayload {
+  content: string;
+}
+
+export interface IframeContextMenuPayload {
+  clientX: number;
+  clientY: number;
+  viewportClientX?: number;
+  viewportClientY?: number;
+  info?: ElementInfo | null;
+}

package/corpus/templates/design/app/components/design/design-canvas/iframe-pan.ts

@@ -0,0 +1,177 @@
+const MAX_IFRAME_PAN_COORDINATE = 100_000;
+const MAX_MOUSE_BUTTONS_MASK = 31;
+
+export type EmbeddedCanvasPanPhase = "start" | "move" | "end" | "cancel";
+
+export interface EmbeddedCanvasPanSession {
+  pointerId: number;
+  button: 0 | 1;
+}
+
+interface EmbeddedCanvasPanMessage {
+  type: "embedded-canvas-pan";
+  phase: EmbeddedCanvasPanPhase;
+  pointerId: number;
+  button: 0 | 1;
+  buttons: number;
+  clientX: number;
+  clientY: number;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+}
+
+export interface ForwardEmbeddedCanvasPanResult {
+  handled: boolean;
+  session: EmbeddedCanvasPanSession | null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function parseEmbeddedCanvasPanMessage(
+  value: unknown,
+): EmbeddedCanvasPanMessage | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const candidate = value as Record<string, unknown>;
+  if (candidate.type !== "embedded-canvas-pan") return null;
+  const phase = candidate.phase;
+  if (
+    phase !== "start" &&
+    phase !== "move" &&
+    phase !== "end" &&
+    phase !== "cancel"
+  ) {
+    return null;
+  }
+  const pointerId = finiteNumber(candidate.pointerId);
+  const rawButton = finiteNumber(candidate.button);
+  const buttons = finiteNumber(candidate.buttons);
+  const clientX = finiteNumber(candidate.clientX);
+  const clientY = finiteNumber(candidate.clientY);
+  if (
+    pointerId === null ||
+    !Number.isInteger(pointerId) ||
+    pointerId < 0 ||
+    pointerId > 0x7fffffff ||
+    (rawButton !== 0 && rawButton !== 1) ||
+    buttons === null ||
+    clientX === null ||
+    clientY === null
+  ) {
+    return null;
+  }
+  return {
+    type: "embedded-canvas-pan",
+    phase,
+    pointerId,
+    button: rawButton,
+    buttons: clamp(Math.trunc(buttons), 0, MAX_MOUSE_BUTTONS_MASK),
+    clientX: clamp(
+      clientX,
+      -MAX_IFRAME_PAN_COORDINATE,
+      MAX_IFRAME_PAN_COORDINATE,
+    ),
+    clientY: clamp(
+      clientY,
+      -MAX_IFRAME_PAN_COORDINATE,
+      MAX_IFRAME_PAN_COORDINATE,
+    ),
+    ctrlKey: Boolean(candidate.ctrlKey),
+    metaKey: Boolean(candidate.metaKey),
+    shiftKey: Boolean(candidate.shiftKey),
+    altKey: Boolean(candidate.altKey),
+  };
+}
+
+/**
+ * Replays a trusted iframe bridge pan message through the parent document's
+ * existing mouse-drag path. The synthetic mousedown bubbles from the iframe
+ * element, so single-screen DesignCanvas and overview MultiScreenCanvas keep
+ * one authoritative pan implementation; move/end events go to `window`, where
+ * both implementations already install their lifetime drag listeners.
+ *
+ * The caller owns `session` and must only call this after validating the
+ * MessageEvent's source window + origin. Session matching rejects injected or
+ * reordered move/end packets before they can disturb another active gesture.
+ */
+export function forwardEmbeddedCanvasPanMessage({
+  data,
+  iframe,
+  hostWindow,
+  session,
+}: {
+  data: unknown;
+  iframe: HTMLIFrameElement;
+  hostWindow: Window;
+  session: EmbeddedCanvasPanSession | null;
+}): ForwardEmbeddedCanvasPanResult {
+  const message = parseEmbeddedCanvasPanMessage(data);
+  if (!message) return { handled: false, session };
+
+  if (message.phase === "start") {
+    if (session) return { handled: false, session };
+  } else if (
+    !session ||
+    session.pointerId !== message.pointerId ||
+    session.button !== message.button
+  ) {
+    return { handled: false, session };
+  }
+
+  const frameRect = iframe.getBoundingClientRect();
+  const scaleX =
+    iframe.clientWidth > 0 && Number.isFinite(frameRect.width)
+      ? frameRect.width / iframe.clientWidth
+      : 1;
+  const scaleY =
+    iframe.clientHeight > 0 && Number.isFinite(frameRect.height)
+      ? frameRect.height / iframe.clientHeight
+      : 1;
+  const clientX = frameRect.left + message.clientX * scaleX;
+  const clientY = frameRect.top + message.clientY * scaleY;
+  const eventType =
+    message.phase === "start"
+      ? "mousedown"
+      : message.phase === "move"
+        ? "mousemove"
+        : "mouseup";
+  const HostMouseEvent = (hostWindow as Window & typeof globalThis).MouseEvent;
+  const forwarded = new HostMouseEvent(eventType, {
+    bubbles: true,
+    cancelable: true,
+    view: hostWindow,
+    button: message.button,
+    buttons:
+      message.phase === "end" || message.phase === "cancel"
+        ? 0
+        : message.buttons,
+    clientX,
+    clientY,
+    ctrlKey: message.ctrlKey,
+    metaKey: message.metaKey,
+    shiftKey: message.shiftKey,
+    altKey: message.altKey,
+  });
+
+  if (message.phase === "start") {
+    iframe.dispatchEvent(forwarded);
+    return {
+      handled: true,
+      session: { pointerId: message.pointerId, button: message.button },
+    };
+  }
+
+  hostWindow.dispatchEvent(forwarded);
+  return {
+    handled: true,
+    session: message.phase === "move" ? session : null,
+  };
+}

package/corpus/templates/design/app/components/design/design-canvas/motion-types.ts

@@ -0,0 +1,7 @@
+export interface MotionTrackWire {
+  targetNodeId: string;
+  property: string;
+  keyframes: Array<{ t: number; value: string; ease?: string }>;
+  delayMs?: number;
+  durationMs?: number;
+}

package/corpus/templates/design/app/components/design/design-canvas/pending-text-edit.ts

@@ -0,0 +1,62 @@
+export type PendingTextEditKeyAction =
+  | { action: "buffer"; char: string }
+  | { action: "drop-last" }
+  | { action: "swallow" }
+  | { action: "clear-and-swallow" }
+  | { action: "pass" };
+
+/**
+ * Run text-edit activation immediately unless it was requested from inside a
+ * pointer gesture's mouseup handler. Browsers dispatch the trailing `click`
+ * after mouseup; focusing the new editable before that click makes the click
+ * immediately blur it again. Deferring one task preserves the already-armed
+ * keystroke buffer while letting that trailing click finish first.
+ */
+export function schedulePendingTextEditActivation(
+  activate: () => void,
+  options: {
+    afterPointerGesture?: boolean;
+    schedule?: (callback: () => void, delayMs: number) => void;
+  } = {},
+): void {
+  if (!options.afterPointerGesture) {
+    activate();
+    return;
+  }
+  const schedule =
+    options.schedule ??
+    ((callback: () => void, delayMs: number) =>
+      window.setTimeout(callback, delayMs));
+  schedule(activate, POINTER_TEXT_EDIT_ACTIVATION_DELAY_MS);
+}
+
+export function routePendingTextEditKey(event: {
+  key: string;
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  isComposing?: boolean;
+}): PendingTextEditKeyAction {
+  if (event.isComposing) return { action: "pass" };
+  if (event.metaKey || event.ctrlKey) return { action: "pass" };
+  if (event.key === "Escape") return { action: "clear-and-swallow" };
+  if (event.key === "Backspace") return { action: "drop-last" };
+  if (
+    event.key === "Delete" ||
+    event.key === "Enter" ||
+    event.key === "Tab" ||
+    event.key.startsWith("Arrow")
+  ) {
+    return { action: "swallow" };
+  }
+  if (event.key.length === 1) return { action: "buffer", char: event.key };
+  return { action: "pass" };
+}
+
+export const PENDING_TEXT_EDIT_TIMEOUT_MS = 3000;
+
+// Overview creation patches the target iframe document after persistence.
+// Waiting through that bounded replacement avoids opening an edit session in
+// the outgoing DOM (visible caret blink, then lost focus). Keystrokes remain
+// lossless because DesignCanvas arms its pending buffer before scheduling.
+export const POINTER_TEXT_EDIT_ACTIVATION_DELAY_MS = 300;

package/corpus/templates/design/app/components/design/index.ts

@@ -1,9 +1,9 @@
 export { DesignCanvas } from "./DesignCanvas";
+export type { MotionTrackWire } from "./design-canvas/motion-types";
 export type {
-  MotionTrackWire,
   IframeHotkeyPayload,
   IframeContextMenuPayload,
-} from "./DesignCanvas";
+} from "./design-canvas/iframe-events";
 export { DeviceFrame } from "./DeviceFrame";
 export { DrawOverlay } from "./DrawOverlay";
 export { EditPanel } from "./EditPanel";

package/corpus/templates/design/app/components/design/multi-screen/canvas-tools.ts

@@ -0,0 +1,100 @@
+import type { MultiScreenCanvasTool, DraftCreationTool } from "./types";
+
+export function normalizeCanvasTool(
+  tool: MultiScreenCanvasTool,
+): MultiScreenCanvasTool {
+  return tool === "rectangle" ? "rect" : tool;
+}
+
+export function getDraftCreationTool(
+  tool: MultiScreenCanvasTool,
+): DraftCreationTool | null {
+  if (
+    tool === "frame" ||
+    tool === "rect" ||
+    tool === "line" ||
+    tool === "arrow" ||
+    tool === "ellipse" ||
+    tool === "polygon" ||
+    tool === "star" ||
+    tool === "text" ||
+    tool === "pen"
+  ) {
+    return tool;
+  }
+  return null;
+}
+
+export function isDirectScreenHoverTarget(
+  target: EventTarget | null,
+  currentTarget: HTMLElement,
+) {
+  if (target === currentTarget) return true;
+  const element =
+    target && typeof (target as Element).closest === "function"
+      ? (target as Element)
+      : null;
+  return !!element && !element.closest("[data-screen-content]");
+}
+
+/** True only for native OS file drags, not internal HTML drag operations. */
+export function isOsFileDrag(event: {
+  dataTransfer: { types: readonly string[] | DOMStringList } | null;
+}): boolean {
+  const types = event.dataTransfer?.types;
+  if (!types) return false;
+  for (let index = 0; index < types.length; index += 1) {
+    if (types[index] === "Files") return true;
+  }
+  return false;
+}
+
+export function shouldBoardSurfaceCapturePointerEvents(args: {
+  tool: string;
+  gestureActive?: boolean;
+}) {
+  if (args.gestureActive) return false;
+  const tool = normalizeCanvasTool(args.tool as MultiScreenCanvasTool);
+  return (
+    !getDraftCreationTool(tool) &&
+    tool !== "hand" &&
+    tool !== "comment" &&
+    tool !== "draw"
+  );
+}
+
+export function shouldBeginCanvasPan(args: { button: number; tool: string }) {
+  return (
+    args.button === 1 ||
+    (args.button === 0 &&
+      normalizeCanvasTool(args.tool as MultiScreenCanvasTool) === "hand")
+  );
+}
+
+export function shouldShowFrameFullViewButton(args: {
+  emphasized: boolean;
+  showFullView?: boolean;
+  childHoverActive?: boolean;
+}) {
+  return args.emphasized || !!args.showFullView || !!args.childHoverActive;
+}
+
+export function shouldShowBreakpointMenuAffordance(args: {
+  canEdit: boolean;
+  hasRemoveOrChangeWidth: boolean;
+  isActive: boolean;
+  menuOpen: boolean;
+}): boolean {
+  return (
+    args.canEdit &&
+    args.hasRemoveOrChangeWidth &&
+    (args.isActive || args.menuOpen)
+  );
+}
+
+export function shouldClearSelectionOnEmptyCanvasClick(gesture: {
+  hasMoved: boolean;
+  additive: boolean;
+}): boolean {
+  return !gesture.hasMoved && !gesture.additive;
+}

package/corpus/templates/design/app/components/design/multi-screen/coordinate-transforms.ts

@@ -0,0 +1,81 @@
+import { rotatePoint } from "@shared/canvas-math";
+
+import type { FrameGeometry, Point } from "./types";
+
+export interface ScreenViewport {
+  width: number;
+  height: number;
+}
+
+function frameCenter(frame: FrameGeometry): Point {
+  return {
+    x: frame.x + frame.width / 2,
+    y: frame.y + frame.height / 2,
+  };
+}
+
+/** Maps a point from an iframe/screen's local pixel space into board space. */
+export function screenLocalPointToBoardPoint(
+  point: Point,
+  frame: FrameGeometry,
+  viewport: ScreenViewport,
+): Point {
+  const unrotated = {
+    x: frame.x + point.x * (frame.width / Math.max(1, viewport.width)),
+    y: frame.y + point.y * (frame.height / Math.max(1, viewport.height)),
+  };
+  return rotatePoint(unrotated, frameCenter(frame), frame.rotation ?? 0);
+}
+
+/** Maps a board-space point into an iframe/screen's local pixel space. */
+export function boardPointToScreenLocalPoint(
+  point: Point,
+  frame: FrameGeometry,
+  viewport: ScreenViewport,
+): Point {
+  const unrotated = rotatePoint(
+    point,
+    frameCenter(frame),
+    -(frame.rotation ?? 0),
+  );
+  return {
+    x: (unrotated.x - frame.x) * (viewport.width / Math.max(1, frame.width)),
+    y: (unrotated.y - frame.y) * (viewport.height / Math.max(1, frame.height)),
+  };
+}
+
+/**
+ * Maps an axis-aligned screen-local rect into the board. The returned geometry
+ * keeps width/height in the screen's local axes and carries the screen's
+ * rotation, matching the CSS box needed to render/hit-test it on the board.
+ */
+export function screenLocalRectToBoardGeometry(
+  rect: { left: number; top: number; width: number; height: number },
+  frame: FrameGeometry,
+  viewport: ScreenViewport,
+  minSize = 1,
+): FrameGeometry {
+  const scaleX = frame.width / Math.max(1, viewport.width);
+  const scaleY = frame.height / Math.max(1, viewport.height);
+  const width = Math.max(minSize, rect.width * scaleX);
+  const height = Math.max(minSize, rect.height * scaleY);
+  const unrotatedCenter = {
+    // Preserve the historical local-left/local-top mapping even when a tiny
+    // rect's rendered board size is clamped up to minSize.
+    x: frame.x + rect.left * scaleX + width / 2,
+    y: frame.y + rect.top * scaleY + height / 2,
+  };
+  const center = rotatePoint(
+    unrotatedCenter,
+    frameCenter(frame),
+    frame.rotation ?? 0,
+  );
+  const rotation = frame.rotation ?? 0;
+  return {
+    x: center.x - width / 2,
+    y: center.y - height / 2,
+    width,
+    height,
+    ...(rotation ? { rotation } : {}),
+  };
+}