@agent-native/core 0.92.11 → 0.93.0

package/corpus/templates/design/app/lib/desktop-design-preview.ts

@@ -0,0 +1,423 @@
+import { getFrameOrigin } from "@agent-native/core/client";
+import { useEffect, useRef, useState, type RefObject } from "react";
+
+const REQUEST_TYPE = "agentNative.designPreview.request";
+const STATE_TYPE = "agentNative.designPreview.state";
+const HEARTBEAT_MS = 750;
+
+type PreviewState = {
+  state?: string;
+  screenId?: string;
+  generation?: number;
+  reason?: string;
+  url?: string;
+  version?: number;
+  width?: number;
+  height?: number;
+  devicePixelRatio?: number;
+  mimeType?: string;
+  bytes?: unknown;
+};
+
+type PreviewRequest = {
+  action: "update" | "destroy" | "snapshot-ready";
+  appId: "design";
+  workspaceId: string;
+  connectionId: string;
+  screenId: string;
+  generation: number;
+  [key: string]: unknown;
+};
+
+interface DesktopPreviewBridge {
+  request(request: PreviewRequest): void;
+  onState(callback: (state: PreviewState) => void): () => void;
+}
+
+let lastGeneration = 0;
+
+function nextGeneration(): number {
+  lastGeneration = Math.max(lastGeneration + 1, Math.floor(Date.now() * 1_000));
+  return lastGeneration;
+}
+
+function getDirectBridge(): DesktopPreviewBridge | null {
+  const desktop = (
+    window as typeof window & {
+      agentNativeDesktop?: { designPreview?: DesktopPreviewBridge };
+    }
+  ).agentNativeDesktop;
+  return desktop?.designPreview ?? null;
+}
+
+function postRequest(request: PreviewRequest): void {
+  const direct = getDirectBridge();
+  if (direct) {
+    direct.request(request);
+    return;
+  }
+  const frameOrigin = getFrameOrigin();
+  if (!frameOrigin || window.parent === window) return;
+  window.parent.postMessage({ type: REQUEST_TYPE, data: request }, frameOrigin);
+}
+
+function connectionIdForUrl(url: string): string | null {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveDesktopDesignPreviewConnectionId(
+  connectionId: string | undefined,
+  url: string,
+): string | null {
+  const explicit = connectionId?.trim();
+  // Legacy URL screens predate connection metadata. Origin is a conservative
+  // compatibility fallback; current localhost/Fusion screens must pass their
+  // stable connection id so same-origin projects remain session-isolated.
+  return explicit || connectionIdForUrl(url);
+}
+
+function isIframeObscured(iframe: HTMLIFrameElement, rect: DOMRect): boolean {
+  const inset = 1;
+  const points = [
+    [rect.left + inset, rect.top + inset],
+    [rect.right - inset, rect.top + inset],
+    [rect.left + inset, rect.bottom - inset],
+    [rect.right - inset, rect.bottom - inset],
+    [rect.left + rect.width / 2, rect.top + rect.height / 2],
+  ];
+  return points.some(([x, y]) => {
+    if (x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight) {
+      return true;
+    }
+    return document.elementFromPoint(x, y) !== iframe;
+  });
+}
+
+export interface DesktopDesignNativePreviewOptions {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  url: string | null;
+  workspaceId?: string;
+  connectionId?: string;
+  screenId?: string;
+  enabled: boolean;
+  active?: boolean;
+  mode: "interact" | "edit" | "draw" | "comment";
+  presentation: "focused" | "overview";
+  scale: number;
+  rotationDegrees?: number;
+}
+
+export interface DesktopDesignNativePreviewSnapshot {
+  url: string;
+  version: number;
+  width: number;
+  height: number;
+  devicePixelRatio: number;
+  acknowledge(): void;
+}
+
+export function resolveDesktopDesignSnapshotLayer(options: {
+  hasSnapshot: boolean;
+  interactMode: boolean;
+  editMode: boolean;
+  hasLiveEditorBridge: boolean;
+}): "none" | "handoff" | "page" {
+  if (!options.hasSnapshot || options.interactMode) return "none";
+  if (options.editMode) {
+    return options.hasLiveEditorBridge ? "handoff" : "none";
+  }
+  return "page";
+}
+
+function normalizeSnapshotBytes(value: unknown): Uint8Array | null {
+  if (value instanceof Uint8Array) return Uint8Array.from(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
+  if (Array.isArray(value) && value.every((item) => Number.isInteger(item))) {
+    return Uint8Array.from(value as number[]);
+  }
+  if (
+    value &&
+    typeof value === "object" &&
+    Array.isArray((value as { data?: unknown }).data)
+  ) {
+    return Uint8Array.from((value as { data: number[] }).data);
+  }
+  return null;
+}
+
+/**
+ * Reports a focused URL-backed Interact surface to the desktop app. Browsers
+ * without the desktop bridge continue using the iframe unchanged. Electron's
+ * main process remains authoritative for eligibility, sender, URL, bounds,
+ * session, and generation validation.
+ */
+export function useDesktopDesignNativePreview(
+  options: DesktopDesignNativePreviewOptions,
+): DesktopDesignNativePreviewSnapshot | null {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [snapshot, setSnapshot] =
+    useState<DesktopDesignNativePreviewSnapshot | null>(null);
+  const snapshotUrlRef = useRef<string | null>(null);
+  const snapshotVersionRef = useRef(0);
+  const reportRef = useRef<(() => void) | null>(null);
+
+  const clearSnapshot = () => {
+    if (snapshotUrlRef.current) URL.revokeObjectURL(snapshotUrlRef.current);
+    snapshotUrlRef.current = null;
+    snapshotVersionRef.current = 0;
+    setSnapshot(null);
+  };
+
+  useEffect(() => {
+    const initial = optionsRef.current;
+    if (initial.active === false) return;
+    const connectionId = initial.url
+      ? resolveDesktopDesignPreviewConnectionId(
+          initial.connectionId,
+          initial.url,
+        )
+      : null;
+    if (!initial.workspaceId || !initial.screenId || !connectionId) return;
+
+    const base = {
+      appId: "design" as const,
+      workspaceId: initial.workspaceId,
+      connectionId,
+      screenId: initial.screenId,
+    };
+    let frame = 0;
+    let disposed = false;
+
+    const report = () => {
+      if (disposed) return;
+      const current = optionsRef.current;
+      const iframe = current.iframeRef.current;
+      const currentConnectionId = current.url
+        ? resolveDesktopDesignPreviewConnectionId(
+            current.connectionId,
+            current.url,
+          )
+        : null;
+      if (
+        !iframe ||
+        !current.url ||
+        !current.workspaceId ||
+        !current.screenId ||
+        current.workspaceId !== base.workspaceId ||
+        current.screenId !== base.screenId ||
+        currentConnectionId !== base.connectionId
+      ) {
+        postRequest({
+          action: "destroy",
+          ...base,
+          generation: nextGeneration(),
+        });
+        return;
+      }
+
+      const rect = iframe.getBoundingClientRect();
+      const visible =
+        current.enabled &&
+        document.visibilityState === "visible" &&
+        rect.width > 0 &&
+        rect.height > 0 &&
+        rect.right > 0 &&
+        rect.bottom > 0 &&
+        rect.left < window.innerWidth &&
+        rect.top < window.innerHeight;
+      const borderRadius = Number.parseFloat(
+        window.getComputedStyle(iframe).borderTopLeftRadius,
+      );
+      postRequest({
+        action: "update",
+        ...base,
+        generation: nextGeneration(),
+        url: current.url,
+        previewBounds: {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height,
+        },
+        clipBounds: {
+          x: 0,
+          y: 0,
+          width: window.innerWidth,
+          height: window.innerHeight,
+        },
+        mode: current.mode,
+        presentation: current.presentation,
+        scale: current.scale,
+        rotationDegrees: current.rotationDegrees ?? 0,
+        borderRadius: Number.isFinite(borderRadius) ? borderRadius : 0,
+        devicePixelRatio: window.devicePixelRatio || 1,
+        obscured: visible ? isIframeObscured(iframe, rect) : false,
+        visible,
+      });
+    };
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(report);
+    };
+    reportRef.current = schedule;
+
+    const iframe = initial.iframeRef.current;
+    const observer = new ResizeObserver(schedule);
+    if (iframe) observer.observe(iframe);
+    window.addEventListener("resize", schedule);
+    window.addEventListener("scroll", schedule, true);
+    document.addEventListener("visibilitychange", schedule);
+    window.visualViewport?.addEventListener("resize", schedule);
+    window.visualViewport?.addEventListener("scroll", schedule);
+    const heartbeat = window.setInterval(report, HEARTBEAT_MS);
+    schedule();
+
+    return () => {
+      disposed = true;
+      reportRef.current = null;
+      cancelAnimationFrame(frame);
+      window.clearInterval(heartbeat);
+      observer.disconnect();
+      window.removeEventListener("resize", schedule);
+      window.removeEventListener("scroll", schedule, true);
+      document.removeEventListener("visibilitychange", schedule);
+      window.visualViewport?.removeEventListener("resize", schedule);
+      window.visualViewport?.removeEventListener("scroll", schedule);
+      postRequest({
+        action: "destroy",
+        ...base,
+        generation: nextGeneration(),
+      });
+    };
+  }, [
+    options.active,
+    options.connectionId,
+    options.screenId,
+    options.url,
+    options.workspaceId,
+  ]);
+
+  useEffect(() => {
+    reportRef.current?.();
+  }, [
+    options.enabled,
+    options.mode,
+    options.presentation,
+    options.rotationDegrees,
+    options.scale,
+  ]);
+
+  useEffect(() => {
+    clearSnapshot();
+  }, [options.screenId, options.url]);
+
+  useEffect(() => {
+    if (options.enabled && options.mode === "interact") clearSnapshot();
+  }, [options.enabled, options.mode]);
+
+  useEffect(
+    () => () => {
+      if (snapshotUrlRef.current) URL.revokeObjectURL(snapshotUrlRef.current);
+      snapshotUrlRef.current = null;
+    },
+    [],
+  );
+
+  useEffect(() => {
+    const direct = getDirectBridge();
+    const handleState = (state: PreviewState) => {
+      if (
+        state.state === "snapshot" &&
+        state.screenId === optionsRef.current.screenId &&
+        state.mimeType === "image/png" &&
+        typeof state.version === "number" &&
+        typeof state.width === "number" &&
+        typeof state.height === "number" &&
+        typeof state.devicePixelRatio === "number"
+      ) {
+        if (state.version <= snapshotVersionRef.current) return;
+        const bytes = normalizeSnapshotBytes(state.bytes);
+        if (
+          !bytes ||
+          bytes.byteLength === 0 ||
+          bytes.byteLength > 8 * 1024 * 1024
+        ) {
+          clearSnapshot();
+          return;
+        }
+        const blobBytes = new Uint8Array(bytes.byteLength);
+        blobBytes.set(bytes);
+        const blobUrl = URL.createObjectURL(
+          new Blob([blobBytes.buffer], { type: "image/png" }),
+        );
+        if (snapshotUrlRef.current) URL.revokeObjectURL(snapshotUrlRef.current);
+        snapshotUrlRef.current = blobUrl;
+        snapshotVersionRef.current = state.version;
+        const current = optionsRef.current;
+        const connectionId = current.url
+          ? resolveDesktopDesignPreviewConnectionId(
+              current.connectionId,
+              current.url,
+            )
+          : null;
+        setSnapshot({
+          url: blobUrl,
+          version: state.version,
+          width: state.width,
+          height: state.height,
+          devicePixelRatio: state.devicePixelRatio,
+          acknowledge: () => {
+            if (!connectionId || !current.workspaceId || !current.screenId) {
+              return;
+            }
+            postRequest({
+              action: "snapshot-ready",
+              appId: "design",
+              workspaceId: current.workspaceId,
+              connectionId,
+              screenId: current.screenId,
+              generation: nextGeneration(),
+              version: state.version!,
+            });
+          },
+        });
+        return;
+      }
+      if (
+        state.state !== "blocked-navigation" ||
+        state.screenId !== optionsRef.current.screenId
+      ) {
+        return;
+      }
+      window.dispatchEvent(
+        new CustomEvent("agent-native:design-preview-navigation-blocked", {
+          detail: state,
+        }),
+      );
+    };
+    if (direct) return direct.onState(handleState);
+    if (window.parent === window) return;
+    const onMessage = (event: MessageEvent) => {
+      const frameOrigin = getFrameOrigin();
+      if (
+        !frameOrigin ||
+        event.source !== window.parent ||
+        event.origin !== frameOrigin ||
+        event.data?.type !== STATE_TYPE ||
+        !event.data.data
+      ) {
+        return;
+      }
+      handleState(event.data.data as PreviewState);
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+
+  return snapshot;
+}

package/corpus/templates/design/app/lib/figma-clipboard.ts

@@ -11,23 +11,31 @@
  * `extractFigmeta` tries both, defensively, and never throws — any malformed
  * input just means "not a decodable Figma paste".
  *
- * Important caveat carried through to the server: `figmeta` has no node ids
- * (only a `fileKey`), and `pasteID` is an ephemeral, server-side identifier
- * that isn't resolvable to a node through the public REST API. So a plain
- * clipboard paste can only ever get an exact node import on a best-effort,
- * heuristic match (see `server/lib/figma-clipboard-match.ts`) — a copied
- * frame LINK (which carries a real `node-id`) is the only guaranteed-exact
- * path (`import-figma-frame`).
+ * Current Figma web clipboard payloads also include `selectedNodeData`. Each
+ * comma-delimited entry starts with the selected REST node id, followed by
+ * Figma-private metadata (for example `40:45|4|0`). This field is not part of
+ * Figma's public API contract, so we parse it conservatively and keep the
+ * existing heuristic fallback for older clients or future format changes.
  */
 
 export interface FigmetaPayload {
   fileKey: string;
   pasteID?: number;
   dataType?: string;
+  environment?: string;
+  selectedNodeData?: string;
+  selectedNodeIds?: string[];
+  selectedNodeIdsTruncated?: boolean;
 }
 
+export const MAX_FIGMA_CLIPBOARD_NODE_IDS = 100;
 const FIGMETA_MARKER_RE = /\(figmeta\)([^(]*?)\(\/figmeta\)/i;
 const DATA_METADATA_ATTR_RE = /\bdata-metadata\s*=\s*(["'])([\s\S]*?)\1/i;
+const FIGMA_DATA_BUFFER_ELEMENT_RE =
+  /<([a-z][\w:-]*)\b[^>]*\bdata-buffer\s*=\s*(["'])[\s\S]*?\2[^>]*>[\s\S]*?<\/\1\s*>/gi;
+const FIGMA_BUFFER_COMMENT_RE = /<!--\s*\(figma\)[\s\S]*?\(\/figma\)\s*-->/gi;
+const ESCAPED_FIGMA_BUFFER_COMMENT_RE =
+  /&lt;!--\s*\(figma\)[\s\S]*?\(\/figma\)\s*--&gt;/gi;
 
 function decodeBase64Json(raw: string): unknown {
   const trimmed = raw.trim();
@@ -53,9 +61,57 @@ function normalizeFigmetaPayload(value: FigmetaPayload): FigmetaPayload {
   const payload: FigmetaPayload = { fileKey: value.fileKey.trim() };
   if (typeof value.pasteID === "number") payload.pasteID = value.pasteID;
   if (typeof value.dataType === "string") payload.dataType = value.dataType;
+  if (typeof value.environment === "string") {
+    payload.environment = value.environment;
+  }
+  if (typeof value.selectedNodeData === "string") {
+    payload.selectedNodeData = value.selectedNodeData;
+    const { ids, truncated } = parseSelectedNodeIds(value.selectedNodeData);
+    if (ids.length > 0) payload.selectedNodeIds = ids;
+    if (truncated) payload.selectedNodeIdsTruncated = true;
+  }
   return payload;
 }
 
+function parseSelectedNodeIds(value: string): {
+  ids: string[];
+  truncated: boolean;
+} {
+  const allIds = Array.from(
+    new Set(
+      value
+        .split(",")
+        .map((entry) => entry.split("|", 1)[0]?.trim() ?? "")
+        .filter((id) => /^\d+:\d+$/.test(id)),
+    ),
+  );
+  return {
+    ids: allIds.slice(0, MAX_FIGMA_CLIPBOARD_NODE_IDS),
+    truncated: allIds.length > MAX_FIGMA_CLIPBOARD_NODE_IDS,
+  };
+}
+
+/**
+ * Extract REST node ids from Figma's current `selectedNodeData` clipboard
+ * field. Unknown or malformed entries are ignored so a format change falls
+ * back to the existing matcher instead of breaking paste entirely.
+ */
+export function extractSelectedNodeIds(value: string): string[] {
+  return parseSelectedNodeIds(value).ids;
+}
+
+/**
+ * Exact node ids make Figma's private binary transfer payload unnecessary.
+ * Remove only that hidden buffer before the action call, retaining figmeta
+ * provenance and any browser-readable HTML for an honest fallback.
+ */
+export function stripFigmaBinaryClipboardBuffer(html: string): string {
+  return html
+    .replace(FIGMA_DATA_BUFFER_ELEMENT_RE, "")
+    .replace(FIGMA_BUFFER_COMMENT_RE, "")
+    .replace(ESCAPED_FIGMA_BUFFER_COMMENT_RE, "");
+}
+
 /**
  * Extracts and decodes the `figmeta` payload from a clipboard's raw HTML (or
  * plain text), if present. Returns `null` for anything that isn't a
@@ -114,6 +170,8 @@ export type FigmaPasteImportCall =
       action: "import-figma-clipboard";
       payload: {
         figmetaFileKey: string;
+        selectedNodeIds?: string[];
+        selectedNodeIdsTruncated?: boolean;
         clipboardHtml: string;
         originalName?: string;
       };
@@ -150,7 +208,15 @@ export function resolveFigmaPasteImportCall(
     action: "import-figma-clipboard",
     payload: {
       figmetaFileKey: figmeta!.fileKey,
-      clipboardHtml: content,
+      ...(figmeta!.selectedNodeIds
+        ? { selectedNodeIds: figmeta!.selectedNodeIds }
+        : {}),
+      ...(figmeta!.selectedNodeIdsTruncated
+        ? { selectedNodeIdsTruncated: true }
+        : {}),
+      clipboardHtml: figmeta!.selectedNodeIds?.length
+        ? stripFigmaBinaryClipboardBuffer(content)
+        : content,
       originalName,
     },
   };

package/corpus/templates/design/app/lib/figma-connection.ts

@@ -0,0 +1,161 @@
+import { agentNativePath, callAction } from "@agent-native/core/client";
+
+export const FIGMA_ACCESS_TOKEN_SECRET_KEY = "FIGMA_ACCESS_TOKEN";
+
+interface RegisteredSecretStatus {
+  key: string;
+  label: string;
+  description?: string;
+  docsUrl?: string;
+  status: "set" | "unset" | "invalid";
+  last4?: string;
+  updatedAt?: number;
+}
+
+export interface FigmaConnectionStatus {
+  connected: boolean;
+  status: RegisteredSecretStatus["status"];
+  key: typeof FIGMA_ACCESS_TOKEN_SECRET_KEY;
+  label: string;
+  description?: string;
+  docsUrl?: string;
+  last4?: string;
+  updatedAt?: number;
+  /** True when the runtime supplies Figma without a user-vault token. */
+  managed?: boolean;
+}
+
+const SECRETS_ENDPOINT = agentNativePath("/_agent-native/secrets");
+
+async function responseError(
+  response: Response,
+  fallback: string,
+): Promise<string> {
+  const payload = (await response.json().catch(() => null)) as {
+    error?: unknown;
+  } | null;
+  return typeof payload?.error === "string" && payload.error.trim()
+    ? payload.error
+    : `${fallback} (${response.status})`;
+}
+
+function notifySecretsChanged(): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(
+    new CustomEvent("agent-engine:configured-changed", {
+      detail: { source: "secrets", key: FIGMA_ACCESS_TOKEN_SECRET_KEY },
+    }),
+  );
+}
+
+function redactSubmittedSecret(message: string, secret: string): string {
+  const encoded = encodeURIComponent(secret);
+  const jsonEscaped = JSON.stringify(secret).slice(1, -1);
+  return [secret, encoded, jsonEscaped]
+    .filter(
+      (candidate, index, values) =>
+        Boolean(candidate) && values.indexOf(candidate) === index,
+    )
+    .reduce(
+      (sanitized, candidate) => sanitized.split(candidate).join("[redacted]"),
+      message,
+    );
+}
+
+/**
+ * Read Figma connection metadata without ever returning the token value.
+ * Both the chat URL affordance and Import panel should share this helper.
+ */
+export async function getFigmaConnectionStatus(options?: {
+  signal?: AbortSignal;
+}): Promise<FigmaConnectionStatus> {
+  const response = await fetch(SECRETS_ENDPOINT, {
+    method: "GET",
+    credentials: "same-origin",
+    signal: options?.signal,
+  });
+  if (!response.ok) {
+    throw new Error(
+      await responseError(response, "Could not check the Figma connection"),
+    );
+  }
+
+  const secrets = (await response.json()) as RegisteredSecretStatus[];
+  const figma = secrets.find(
+    (secret) => secret.key === FIGMA_ACCESS_TOKEN_SECRET_KEY,
+  );
+  if (!figma) {
+    throw new Error("Figma connection is not registered for this app.");
+  }
+
+  // An invalid user-vault token wins over any managed fallback because the
+  // importer resolves that scoped row first. Prompt the user to replace it.
+  // For an unset vault row, ask the authenticated runtime whether it has a
+  // usable managed credential. This returns only a boolean and follows the
+  // same request-scoped resolver as Figma imports.
+  const managedAvailable =
+    figma.status === "unset"
+      ? await callAction<{ available: boolean }>(
+          "get-figma-connection-status",
+          {},
+          { method: "GET", signal: options?.signal },
+        )
+          .then((result) => result.available)
+          .catch(() => false)
+      : false;
+
+  return {
+    connected: figma.status === "set" || managedAvailable,
+    status: managedAvailable ? "set" : figma.status,
+    key: FIGMA_ACCESS_TOKEN_SECRET_KEY,
+    label: figma.label,
+    description: figma.description,
+    docsUrl: figma.docsUrl,
+    last4: figma.last4,
+    updatedAt: figma.updatedAt,
+    managed: managedAvailable || undefined,
+  };
+}
+
+/**
+ * Validate and save a user-scoped Figma token through the encrypted secrets
+ * route. This deliberately is not an action: action arguments can appear in
+ * tool/run ledgers, while secret values must never enter agent context.
+ */
+export async function saveFigmaAccessToken(
+  value: string,
+): Promise<FigmaConnectionStatus> {
+  const token = value.trim();
+  if (!token) throw new Error("Enter a Figma access token.");
+
+  let response: Response;
+  try {
+    response = await fetch(
+      `${SECRETS_ENDPOINT}/${FIGMA_ACCESS_TOKEN_SECRET_KEY}`,
+      {
+        method: "POST",
+        credentials: "same-origin",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ value: token }),
+      },
+    );
+  } catch (reason) {
+    // Transport errors can be constructed by an intermediary and may reflect
+    // request headers or bodies. Redact the raw, encoded, and JSON-escaped
+    // submitted token before the message can reach a toast or error boundary.
+    const message =
+      reason instanceof Error && reason.message.trim()
+        ? reason.message
+        : "Could not connect Figma.";
+    throw new Error(redactSubmittedSecret(message, token));
+  }
+  if (!response.ok) {
+    const message = await responseError(response, "Could not connect Figma");
+    // The server already redacts validator/storage errors. Keep a final client
+    // boundary so a misbehaving intermediary cannot reflect the submitted key.
+    throw new Error(redactSubmittedSecret(message, token));
+  }
+
+  notifySecretsChanged();
+  return getFigmaConnectionStatus();
+}