@agent-native/core 0.163.4 → 0.164.1

package/corpus/templates/design/app/pages/design-editor/derive/design-breakpoints.ts

@@ -0,0 +1,56 @@
+export interface DesignBreakpointOption {
+  id: string;
+  label: string;
+  widthPx: number;
+}
+
+/**
+ * Reads `designs.data.breakpointSet` (§6.4) into the sorted option list the
+ * breakpoint controls render. Unlabelled widths fall back to a size bucket.
+ */
+export function deriveDesignBreakpoints(
+  designDataJson: Record<string, unknown>,
+): DesignBreakpointOption[] {
+  try {
+    const raw = (designDataJson as Record<string, unknown>)?.breakpointSet;
+    if (
+      raw &&
+      typeof raw === "object" &&
+      !Array.isArray(raw) &&
+      Array.isArray((raw as Record<string, unknown>).breakpoints)
+    ) {
+      const parsed = (
+        raw as {
+          breakpoints: Array<{
+            id?: unknown;
+            widthPx?: unknown;
+            label?: unknown;
+          }>;
+        }
+      ).breakpoints
+        .filter(
+          (bp) =>
+            typeof bp?.id === "string" &&
+            typeof bp?.widthPx === "number" &&
+            Number.isFinite(bp.widthPx),
+        )
+        .map((bp) => ({
+          id: bp.id as string,
+          widthPx: bp.widthPx as number,
+          label:
+            typeof bp.label === "string" && bp.label.trim()
+              ? (bp.label as string)
+              : (bp.widthPx as number) >= 1024
+                ? "Desktop"
+                : (bp.widthPx as number) >= 600
+                  ? "Tablet"
+                  : "Mobile",
+        }));
+      return parsed.sort((a, b) => a.widthPx - b.widthPx);
+    }
+    // coercion-ok: an unreadable breakpointSet means "none configured", which the empty list already expresses to the caller.
+  } catch {
+    // ignore malformed design data
+  }
+  return [];
+}

package/corpus/templates/design/app/pages/design-editor/derive/overview-screens.ts

@@ -0,0 +1,146 @@
+import { isBoardFile } from "@shared/board-file";
+
+import { normalizedDesignFileType } from "../canvas-primitive-insert";
+import { getDesignDataRecord } from "../design-data-geometry-utils";
+import type { DesignFile } from "../types";
+
+export interface OverviewScreen {
+  id: string;
+  filename: string;
+  content: string;
+  updatedAt: string;
+  sourceType?: string;
+  source?: string;
+  sourceFile?: string;
+  connectionId?: string;
+  lod?: string;
+  previewState?: string;
+  status?: string;
+  title?: string;
+  layoutGroupId?: string;
+  width?: number;
+  height?: number;
+  heightPinned: boolean;
+  url?: string;
+  previewUrl?: string;
+  bridgeUrl?: string;
+  previewToken?: string;
+  breakpointWidths?: number[];
+  activeBreakpointWidth?: number;
+}
+
+export interface DeriveOverviewScreensArgs {
+  designDataJson: Record<string, unknown>;
+  files: DesignFile[];
+  activeBreakpointWidthState: number | undefined;
+  breakpointFramesHidden: boolean;
+  /**
+   * Heights pinned in this session but not yet round-tripped through
+   * `designs.data`. Without them the content-fit pass regrows a screen the
+   * user just sized.
+   */
+  locallyPinnedHeightIds: ReadonlySet<string>;
+}
+
+export function deriveOverviewScreens({
+  designDataJson,
+  files,
+  activeBreakpointWidthState,
+  breakpointFramesHidden,
+  locallyPinnedHeightIds,
+}: DeriveOverviewScreensArgs): OverviewScreen[] {
+  const metadataByFileId = getDesignDataRecord(
+    designDataJson,
+    "screenMetadata",
+  );
+  // §6.4 — breakpoint set stored in designs.data.breakpointSet as a
+  // BreakpointSet { id, breakpoints: BreakpointDefinition[] }.
+  // Each BreakpointDefinition has { id, label, widthPx, prefix }.
+  const breakpointSet = (() => {
+    try {
+      const raw = (designDataJson as Record<string, unknown>)?.breakpointSet;
+      if (
+        raw &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        Array.isArray((raw as Record<string, unknown>).breakpoints)
+      ) {
+        return raw as {
+          id: string;
+          breakpoints: Array<{
+            id: string;
+            widthPx: number;
+            label?: string;
+            prefix?: string;
+          }>;
+        };
+      }
+      // coercion-ok: an unreadable breakpointSet means "none configured", which the undefined return already expresses to the caller.
+    } catch {
+      // ignore
+    }
+    return undefined;
+  })();
+  const bpWidths =
+    !breakpointFramesHidden &&
+    breakpointSet &&
+    breakpointSet.breakpoints.length > 0
+      ? breakpointSet.breakpoints.map((bp) => bp.widthPx)
+      : undefined;
+
+  // Exclude the board file — it is rendered by its own DesignCanvas instance
+  // in MultiScreenCanvas and must not appear as a screen frame.  Support files
+  // such as CSS are editable files, not visual screens.
+  return files
+    .filter(
+      (file) =>
+        normalizedDesignFileType(file.fileType) === "html" &&
+        !isBoardFile(file.filename),
+    )
+    .map((file) => {
+      const metadata = getDesignDataRecord(metadataByFileId, file.id);
+      const stringValue = (key: string) =>
+        typeof metadata[key] === "string"
+          ? (metadata[key] as string)
+          : undefined;
+      const numberValue = (key: string) =>
+        typeof metadata[key] === "number" && Number.isFinite(metadata[key])
+          ? (metadata[key] as number)
+          : undefined;
+      return {
+        id: file.id,
+        filename: file.filename,
+        content: file.content,
+        updatedAt: file.updatedAt,
+        sourceType: stringValue("sourceType"),
+        source: stringValue("source"),
+        sourceFile: stringValue("sourceFile"),
+        connectionId: stringValue("connectionId"),
+        lod: stringValue("lod"),
+        previewState: stringValue("previewState"),
+        status: stringValue("status"),
+        title: stringValue("title"),
+        layoutGroupId: stringValue("variantSetId"),
+        width: numberValue("width"),
+        height: numberValue("height"),
+        // Without this the pin never reaches the canvas and the content-fit
+        // pass grows a deliberately-sized screen straight back.
+        heightPinned:
+          metadata.heightPinned === true || locallyPinnedHeightIds.has(file.id),
+        url: stringValue("url"),
+        previewUrl: stringValue("previewUrl"),
+        bridgeUrl: stringValue("bridgeUrl"),
+        previewToken: stringValue("previewToken"),
+        // Breakpoint preview widths (§6.4). When non-empty, MultiScreenCanvas
+        // renders one iframe per width to the right of the primary frame.
+        breakpointWidths: bpWidths,
+        // Active breakpoint width tracked in component state; shared across all
+        // screens (a design has one active breakpoint set at a time in v1).
+        activeBreakpointWidth: bpWidths?.includes(
+          activeBreakpointWidthState ?? -1,
+        )
+          ? activeBreakpointWidthState
+          : undefined,
+      };
+    });
+}

package/corpus/templates/design/app/pages/design-editor/domains/use-tweaks.ts

@@ -0,0 +1,326 @@
+import {
+  tryCallActionKeepalive,
+  useReconciledState,
+} from "@agent-native/core/client/hooks";
+import type { TweakDefinition } from "@shared/api";
+import {
+  resolveTweaksToCssVars,
+  tweakSelectionsHash,
+  type TweakSelections,
+} from "@shared/resolve-tweaks";
+import type { QueryClient } from "@tanstack/react-query";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type Dispatch,
+  type RefObject,
+  type SetStateAction,
+} from "react";
+
+import {
+  createDesignSaveOutboxEntry,
+  journalDesignSaveOutboxEntry,
+  type DesignSaveOutboxEntry,
+} from "@/lib/design-save-outbox";
+import {
+  runPersistTweakSave,
+  type PersistTweakSaveArgs,
+} from "@/pages/design-editor/commands/persist-tweak-save";
+import {
+  areTweakSelectionsEqual,
+  buildAuthoritativeTweakSelections,
+} from "@/pages/design-editor/design-data-geometry-utils";
+import {
+  createQueuedTweakSave,
+  sendJournaledTweakSaveKeepalive,
+  type PendingTweakSave,
+} from "@/pages/design-editor/tweak-save";
+
+interface UseTweaksArgs {
+  acknowledgeOutboxEntry: PersistTweakSaveArgs["acknowledgeOutboxEntry"];
+  applyTweaksAsync: PersistTweakSaveArgs["applyTweaksAsync"];
+  canEditDesign: boolean;
+  canEditDesignRef: RefObject<boolean>;
+  design: { data?: string | null } | null;
+  designSaveActorScope: string;
+  designSaveOperationSourceRef: RefObject<string>;
+  id: string | undefined;
+  queryClient: QueryClient;
+  t: PersistTweakSaveArgs["t"];
+  warnChangesWillRetry: () => void;
+}
+
+export interface UseTweaksResult {
+  cssVarValues: Record<string, string>;
+  flushPendingTweakSave: () => void;
+  handleTweakChange: (
+    tweakId: string,
+    value: string | number | boolean,
+  ) => void;
+  setTweakSelections: Dispatch<SetStateAction<TweakSelections>>;
+  tweakSelections: TweakSelections;
+  tweaks: TweakDefinition[];
+}
+
+/**
+ * Owns the tweak (visual-knob) domain: the parsed definitions, the reconciled
+ * selection state, the CSS-var projection for the canvas iframe, and the
+ * debounced save queue that persists selections into designs.data.
+ *
+ * Every dependency array below is byte-identical to the inline version this
+ * replaced. The keepalive/unload effect must stay in this hook so the 600 ms
+ * debounce is flushed before the keyed editor instance unmounts.
+ */
+export function useTweaks({
+  acknowledgeOutboxEntry,
+  applyTweaksAsync,
+  canEditDesign,
+  canEditDesignRef,
+  design,
+  designSaveActorScope,
+  designSaveOperationSourceRef,
+  id,
+  queryClient,
+  t,
+  warnChangesWillRetry,
+}: UseTweaksArgs): UseTweaksResult {
+  const [tweakSaveActive, setTweakSaveActive] = useState(false);
+  const pendingTweakSaveRef = useRef<PendingTweakSave | null>(null);
+  const tweakSaveTimerRef = useRef<number | null>(null);
+  const tweakSaveRevisionRef = useRef(0);
+  const tweakSaveChainRef = useRef<Promise<void>>(Promise.resolve());
+  const tweakSaveInFlightRef = useRef(false);
+  const confirmedTweakSelectionsHashRef = useRef(tweakSelectionsHash({}));
+  const journalTweakOutboxEntry = useCallback(
+    async (entry: DesignSaveOutboxEntry) => {
+      try {
+        await journalDesignSaveOutboxEntry(entry);
+        return true;
+      } catch {
+        // coercion-ok: `false` is the typed "not journaled" result, never
+        // mistakable for success. Do not claim an offline retry exists when
+        // IndexedDB itself failed — the mutation path uses this to tell
+        // durable retries from edits that must stay in this tab's memory.
+        return false;
+      }
+    },
+    [],
+  );
+  const createTweakSaveOutboxEntry = useCallback(
+    (pending: PendingTweakSave) => {
+      if (!id) return null;
+      return createDesignSaveOutboxEntry({
+        designId: id ?? "",
+        actorScope: designSaveActorScope,
+        actionName: "apply-tweaks",
+        resourceId: id,
+        operationSource: designSaveOperationSourceRef.current,
+        operationRevision: pending.revision,
+        payload: {
+          designId: id,
+          selections: pending.selections,
+          expectedSelectionsHash: pending.expectedSelectionsHash,
+        },
+      });
+    },
+    [designSaveActorScope, id],
+  );
+  const persistTweakSave = useCallback(
+    (pending: PendingTweakSave) =>
+      runPersistTweakSave(
+        {
+          acknowledgeOutboxEntry,
+          applyTweaksAsync,
+          canEditDesignRef,
+          confirmedTweakSelectionsHashRef,
+          createTweakSaveOutboxEntry,
+          id,
+          journalTweakOutboxEntry,
+          pendingTweakSaveRef,
+          queryClient,
+          setTweakSaveActive,
+          t,
+          tweakSaveChainRef,
+          tweakSaveInFlightRef,
+          tweakSaveRevisionRef,
+          warnChangesWillRetry,
+        },
+        pending,
+      ),
+    [
+      acknowledgeOutboxEntry,
+      applyTweaksAsync,
+      createTweakSaveOutboxEntry,
+      id,
+      journalTweakOutboxEntry,
+      queryClient,
+      t,
+      warnChangesWillRetry,
+    ],
+  );
+  const flushPendingTweakSave = useCallback(() => {
+    if (tweakSaveTimerRef.current !== null) {
+      window.clearTimeout(tweakSaveTimerRef.current);
+      tweakSaveTimerRef.current = null;
+    }
+    const pending = pendingTweakSaveRef.current;
+    pendingTweakSaveRef.current = null;
+    if (pending) persistTweakSave(pending);
+  }, [persistTweakSave]);
+  const queueTweakSave = useCallback(
+    (selections: TweakSelections) => {
+      if (!id || !canEditDesignRef.current) return;
+      const revision = tweakSaveRevisionRef.current + 1;
+      tweakSaveRevisionRef.current = revision;
+      setTweakSaveActive(true);
+      const pending = createQueuedTweakSave(
+        selections,
+        revision,
+        confirmedTweakSelectionsHashRef.current,
+        pendingTweakSaveRef.current,
+      );
+      pendingTweakSaveRef.current = pending;
+      const entry = createTweakSaveOutboxEntry(pending);
+      if (entry) void journalTweakOutboxEntry(entry);
+      if (tweakSaveTimerRef.current !== null) {
+        window.clearTimeout(tweakSaveTimerRef.current);
+      }
+      tweakSaveTimerRef.current = window.setTimeout(flushPendingTweakSave, 600);
+    },
+    [
+      createTweakSaveOutboxEntry,
+      flushPendingTweakSave,
+      id,
+      journalTweakOutboxEntry,
+    ],
+  );
+
+  useEffect(() => {
+    const handlePageHide = () => {
+      const pending = pendingTweakSaveRef.current;
+      if (!id || !pending || !canEditDesignRef.current) return;
+      if (tweakSaveInFlightRef.current) return;
+      // Keep the normal timer/pending entry intact for bfcache restores. The
+      // keepalive is the unload safety net; if the page survives, the regular
+      // mutation still settles state and confirms persistence.
+      const entry = createTweakSaveOutboxEntry(pending);
+      if (!entry) return;
+      void sendJournaledTweakSaveKeepalive({
+        journal: () => journalTweakOutboxEntry(entry),
+        send: () =>
+          tryCallActionKeepalive("apply-tweaks", entry.payload as any),
+        acknowledge: () => acknowledgeOutboxEntry(entry),
+      }).catch(() => {});
+    };
+    const handleOnline = () => {
+      if (pendingTweakSaveRef.current && !tweakSaveInFlightRef.current) {
+        flushPendingTweakSave();
+      }
+    };
+    window.addEventListener("pagehide", handlePageHide);
+    window.addEventListener("online", handleOnline);
+    return () => {
+      window.removeEventListener("pagehide", handlePageHide);
+      window.removeEventListener("online", handleOnline);
+      // Client-side navigation used to cancel the 600 ms debounce and drop
+      // the user's final knob position. Flush it synchronously into the
+      // mutation pipeline before this keyed editor instance unmounts.
+      flushPendingTweakSave();
+    };
+  }, [
+    acknowledgeOutboxEntry,
+    createTweakSaveOutboxEntry,
+    flushPendingTweakSave,
+    id,
+    journalTweakOutboxEntry,
+  ]);
+
+  // Parse design.data for agent-supplied tweaks. The agent writes a JSON blob
+  // to designs.data containing { tweaks: TweakDefinition[], ... }; we surface
+  // the tweaks as live controls bound to the design's CSS custom properties.
+  const tweaks: TweakDefinition[] = useMemo(() => {
+    if (!design?.data) return [];
+    try {
+      const parsed = JSON.parse(design.data);
+      if (Array.isArray(parsed?.tweaks)) return parsed.tweaks;
+      return [];
+      // coercion-ok: unreadable design data means "no tweaks configured", which the empty list already expresses.
+    } catch {
+      return [];
+    }
+  }, [design?.data]);
+
+  // Persisted user knob values live in designs.data.tweakSelections (written by
+  // the apply-tweaks action). Restoring them on load is what makes the
+  // visual-tune round-trip survive a refresh and feed the snapshot/handoff.
+  const persistedSelections: TweakSelections = useMemo(() => {
+    if (!design?.data) return {};
+    try {
+      const parsed = JSON.parse(design.data);
+      const sel = parsed?.tweakSelections;
+      return sel && typeof sel === "object" && !Array.isArray(sel) ? sel : {};
+      // coercion-ok: unreadable design data means "no tweak selections", which the empty object already expresses.
+    } catch {
+      return {};
+    }
+  }, [design?.data]);
+  useLayoutEffect(() => {
+    if (
+      !tweakSaveActive &&
+      !tweakSaveInFlightRef.current &&
+      pendingTweakSaveRef.current === null
+    ) {
+      confirmedTweakSelectionsHashRef.current =
+        tweakSelectionsHash(persistedSelections);
+    }
+  }, [persistedSelections, tweakSaveActive]);
+
+  // Tweak values are keyed by tweak id while in the panel, then mapped to
+  // CSS-var -> value for the iframe so the design's :root block picks them up.
+  // Persisted selections are authoritative for agent edits; a local queued
+  // save temporarily pauses adoption so stale refetches don't clobber a drag.
+  const authoritativeTweakSelections = useMemo(
+    () => buildAuthoritativeTweakSelections(tweaks, persistedSelections),
+    [tweaks, persistedSelections],
+  );
+  const [tweakSelections, setTweakSelections] = useReconciledState(
+    authoritativeTweakSelections,
+    {
+      active: tweakSaveActive,
+      equals: areTweakSelectionsEqual,
+    },
+  );
+
+  // Map tweak selections (id -> value) to CSS-var assignments (--var -> value)
+  // for the iframe bridge. Shared with the snapshot/handoff actions via
+  // `@shared/resolve-tweaks` so the UI and external agents resolve identically.
+  const cssVarValues = useMemo(
+    () => resolveTweaksToCssVars(tweaks, tweakSelections),
+    [tweaks, tweakSelections],
+  );
+
+  const handleTweakChange = useCallback(
+    (tweakId: string, value: string | number | boolean) => {
+      setTweakSelections((prev) => {
+        if (!canEditDesign) return prev;
+        const next = { ...prev, [tweakId]: value };
+        queueTweakSave(next);
+        return next;
+      });
+    },
+    [canEditDesign, queueTweakSave],
+  );
+
+  return {
+    cssVarValues,
+    flushPendingTweakSave,
+    handleTweakChange,
+    setTweakSelections,
+    tweakSelections,
+    tweaks,
+  };
+}

package/corpus/templates/design/app/pages/design-editor/editor-constants.ts

@@ -0,0 +1,54 @@
+export const MAX_GENERATION_ATTEMPTS = 3;
+export const AUTO_RETRY_DELAY_MS = 1200;
+export const HOST_CHAT_SLOT_MESSAGE = "agentNative.chatSlot";
+export const HOST_TURN_START_TIMEOUT_MS = 15_000;
+export const STORED_RUN_LIVENESS_GRACE_MS = 20_000;
+
+export const OVERVIEW_ZOOM_THRESHOLD = 60;
+export const MOTION_DOCK_TRANSITION_MS = 200;
+export const MOTION_DOCK_EXIT_SETTLE_MS = 80;
+export const MOTION_DOCK_EXIT_FALLBACK_MS = MOTION_DOCK_TRANSITION_MS * 2 + 600;
+export const MOTION_AUTOSAVE_DELAY_MS = 500;
+export const DESIGN_SELECTION_ZOOM_SAVE_DELAY_MS = 150;
+
+/** Retry window for dropping an untouched text node whose screen content has
+ *  not caught up with the insert yet — see removeEmptyTextNodeWithRetry. */
+export const EMPTY_TEXT_CLEANUP_RETRY_MS = 400;
+
+/** Floor for an inspector-typed frame size, matching the frame tool's own
+ *  drawing minimum (see getDraftGeometryForTool). */
+export const MIN_FRAME_SIZE_PX = 24;
+export const BOARD_SURFACE_SIZE = 131_072;
+
+/** Gates non-essential diagnostic console.warn calls (e.g. the cross-screen
+ * anchor-stamp fallback warning) so production consoles stay quiet while
+ * dev builds keep the signal. Real correctness-guard warnings (frame
+ * geometry rejection, poisoned-coord normalization) stay unconditional —
+ * this flag is only for lower-signal "known degraded path taken" notices. */
+export const DESIGN_EDITOR_DEBUG_LOGS = import.meta.env.DEV;
+
+/** Extensions that the localhost bridge allows to be written back to source. */
+export const LOCALHOST_WRITE_EXTENSIONS = new Set([".html", ".htm", ".css"]);
+
+/**
+ * Compiled framework route extensions we can *detect* as local source but
+ * cannot yet write back to (React/TS component files require build-time
+ * source mapping, not a raw HTML/CSS write). "Apply to source" shows as a
+ * disabled affordance with an explanatory tooltip for these instead of
+ * disappearing entirely.
+ */
+export const LOCALHOST_COMPILED_SOURCE_EXTENSIONS = new Set([".jsx", ".tsx"]);
+
+export const NO_LOCALHOST_WRITE_CONTENT_MESSAGE =
+  "No content to write. Open the screen first."; /* i18n-ignore */
+export const NO_LOCALHOST_CONNECTION_MESSAGE =
+  "No localhost connection for this screen. Reconnect and try again."; /* i18n-ignore */
+export const NO_LOCALHOST_WRITE_PATH_MESSAGE =
+  "Can't determine the source file for this screen."; /* i18n-ignore */
+export const TWEAK_CONTROLS_EDIT_ACCESS_MESSAGE =
+  "You need edit access to add tweak controls."; /* i18n-ignore */
+
+export const PENDING_STRUCTURE_VERIFICATION_TIMEOUT_MS = 60_000;
+export const PENDING_STRUCTURE_RUNTIME_TIMEOUT_MS = 15_000;
+export const PENDING_STRUCTURE_SOURCE_POLL_MS = 750;
+export const PENDING_STRUCTURE_RUNTIME_POLL_MS = 150;