@agent-native/core 0.136.4 → 0.137.0

package/corpus/templates/design/app/components/design/inspector/design-icons.tsx

@@ -4,34 +4,50 @@ interface IconProps {
   className?: string;
 }
 
-// Gap icon: ]·[ — two inward-facing C-brackets with a center dot
+/** Text tool / text node. A serif T with end and foot serifs — the plain
+ *  letterform reads as a letter, this reads as type. */
+export function IconText({ className }: IconProps) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn("size-4", className)}
+      aria-hidden="true"
+    >
+      <path d="M3 4H21" />
+      <path d="M3 4V8" />
+      <path d="M21 4V8" />
+      <path d="M12 4V20" />
+      <path d="M7 20H17" />
+    </svg>
+  );
+}
+
+// Gap: two items with a measured space between them.
 export function IconGap({ className }: IconProps) {
   return (
     <svg
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={2}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-4", className)}
       aria-hidden="true"
     >
-      {/* Left bracket ] — vertical bar on right side, serifs pointing right */}
-      <line x1="9" y1="7" x2="6" y2="7" />
-      <line x1="6" y1="7" x2="6" y2="17" />
-      <line x1="6" y1="17" x2="9" y2="17" />
-      {/* Center dot */}
-      <circle cx="12" cy="12" r="1" fill="currentColor" stroke="none" />
-      {/* Right bracket [ — vertical bar on left side, serifs pointing left */}
-      <line x1="15" y1="7" x2="18" y2="7" />
-      <line x1="18" y1="7" x2="18" y2="17" />
-      <line x1="18" y1="17" x2="15" y2="17" />
+      <rect x="2.5" y="5" width="6" height="14" rx="1" />
+      <rect x="15.5" y="5" width="6" height="14" rx="1" />
+      <path d="M12 7.5V16.5" />
     </svg>
   );
 }
 
-// Padding horizontal: square with thick left and right edges
+// Padding: frame with the two insets for that axis marked.
 export function IconPaddingHorizontal({ className }: IconProps) {
   return (
     <svg
@@ -44,33 +60,13 @@ export function IconPaddingHorizontal({ className }: IconProps) {
       className={cn("size-4", className)}
       aria-hidden="true"
     >
-      {/* Outer frame */}
-      <rect x="3" y="4" width="18" height="16" rx="1.5" strokeWidth={1.5} />
-      {/* Thick left edge fill */}
-      <rect
-        x="3"
-        y="4"
-        width="4"
-        height="16"
-        rx="1.5"
-        fill="currentColor"
-        stroke="none"
-      />
-      {/* Thick right edge fill */}
-      <rect
-        x="17"
-        y="4"
-        width="4"
-        height="16"
-        rx="1.5"
-        fill="currentColor"
-        stroke="none"
-      />
+      <rect x="3" y="4" width="18" height="16" rx="1.5" />
+      <path d="M7.5 8V16" />
+      <path d="M16.5 8V16" />
     </svg>
   );
 }
 
-// Padding vertical: square with thick top and bottom edges
 export function IconPaddingVertical({ className }: IconProps) {
   return (
     <svg
@@ -83,34 +79,19 @@ export function IconPaddingVertical({ className }: IconProps) {
       className={cn("size-4", className)}
       aria-hidden="true"
     >
-      {/* Outer frame */}
-      <rect x="4" y="3" width="16" height="18" rx="1.5" strokeWidth={1.5} />
-      {/* Thick top edge fill */}
-      <rect
-        x="4"
-        y="3"
-        width="16"
-        height="4"
-        rx="1.5"
-        fill="currentColor"
-        stroke="none"
-      />
-      {/* Thick bottom edge fill */}
-      <rect
-        x="4"
-        y="17"
-        width="16"
-        height="4"
-        rx="1.5"
-        fill="currentColor"
-        stroke="none"
-      />
+      <rect x="4" y="3" width="16" height="18" rx="1.5" />
+      <path d="M8 7.5H16" />
+      <path d="M8 16.5H16" />
     </svg>
   );
 }
 
-// Flow horizontal: item + arrow. Keep the arrow — two symmetric boxes read as
-// "this axis" but not "this direction", forcing a tooltip hover to disambiguate.
+/** Shared item square. Every flow glyph must stay on this one grid and stroke
+ *  weight; a filled bar or container frame among them reads as a different
+ *  control and stops the four segments comparing at a glance. */
+const FLOW_ITEM = { width: 8, height: 8, rx: 1 } as const;
+
+// Flow horizontal: two items side by side, arrow running left → right beneath.
 export function IconFlowHorizontal({ className }: IconProps) {
   return (
     <svg
@@ -123,26 +104,15 @@ export function IconFlowHorizontal({ className }: IconProps) {
       className={cn("size-4", className)}
       aria-hidden="true"
     >
-      {/* Outer container — wide landscape frame */}
-      <rect x="2" y="6" width="20" height="12" rx="2" strokeWidth={1.5} />
-      {/* First item */}
-      <rect
-        x="4.5"
-        y="9"
-        width="4"
-        height="6"
-        rx="1"
-        fill="currentColor"
-        stroke="none"
-      />
-      {/* Direction arrow — left to right */}
-      <path d="M11 12H18.5" />
-      <path d="M16.3 9.8 18.5 12 16.3 14.2" />
+      <rect x="3" y="3" {...FLOW_ITEM} />
+      <rect x="13" y="3" {...FLOW_ITEM} />
+      <path d="M3 17H19.4" />
+      <path d="M17 14.8 19.4 17 17 19.2" />
     </svg>
   );
 }
 
-// Flow vertical: an item plus a downward arrow — see IconFlowHorizontal.
+// Flow vertical: items stacked, arrow running top → bottom alongside.
 export function IconFlowVertical({ className }: IconProps) {
   return (
     <svg
@@ -155,21 +125,29 @@ export function IconFlowVertical({ className }: IconProps) {
       className={cn("size-4", className)}
       aria-hidden="true"
     >
-      {/* Outer container — tall portrait frame */}
-      <rect x="6" y="2" width="12" height="20" rx="2" strokeWidth={1.5} />
-      {/* First item */}
-      <rect
-        x="9"
-        y="4.5"
-        width="6"
-        height="4"
-        rx="1"
-        fill="currentColor"
-        stroke="none"
-      />
-      {/* Direction arrow — top to bottom */}
-      <path d="M12 11V18.5" />
-      <path d="M9.8 16.3 12 18.5 14.2 16.3" />
+      <rect x="3" y="3" {...FLOW_ITEM} />
+      <rect x="3" y="13" {...FLOW_ITEM} />
+      <path d="M17 3V19.4" />
+      <path d="M14.8 17 17 19.4 19.2 17" />
+    </svg>
+  );
+}
+
+// Flow normal: two items placed freely, no axis and no direction arrow.
+export function IconFlowNormal({ className }: IconProps) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn("size-4", className)}
+      aria-hidden="true"
+    >
+      <rect x="3" y="3" {...FLOW_ITEM} />
+      <rect x="13" y="13" {...FLOW_ITEM} />
     </svg>
   );
 }
@@ -199,7 +177,7 @@ export function IconFlowWrap({ className }: IconProps) {
   );
 }
 
-// Flow grid: 2×2 equal grid of boxes
+// Flow grid: the same item square in a 2×2.
 export function IconFlowGrid({ className }: IconProps) {
   return (
     <svg
@@ -212,14 +190,10 @@ export function IconFlowGrid({ className }: IconProps) {
       className={cn("size-4", className)}
       aria-hidden="true"
     >
-      {/* Top-left */}
-      <rect x="2" y="2" width="9" height="9" rx="1.5" strokeWidth={1.5} />
-      {/* Top-right */}
-      <rect x="13" y="2" width="9" height="9" rx="1.5" strokeWidth={1.5} />
-      {/* Bottom-left */}
-      <rect x="2" y="13" width="9" height="9" rx="1.5" strokeWidth={1.5} />
-      {/* Bottom-right */}
-      <rect x="13" y="13" width="9" height="9" rx="1.5" strokeWidth={1.5} />
+      <rect x="3" y="3" {...FLOW_ITEM} />
+      <rect x="13" y="3" {...FLOW_ITEM} />
+      <rect x="3" y="13" {...FLOW_ITEM} />
+      <rect x="13" y="13" {...FLOW_ITEM} />
     </svg>
   );
 }
@@ -580,7 +554,7 @@ export function IconSizingFixed({ className }: IconProps) {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={1.6}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-3.5", className)}
@@ -603,7 +577,7 @@ export function IconSizingHug({ className }: IconProps) {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={1.6}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-3.5", className)}
@@ -624,7 +598,7 @@ export function IconSizingFill({ className }: IconProps) {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={1.6}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-3.5", className)}
@@ -649,7 +623,7 @@ export function IconSizingMin({ className }: IconProps) {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={1.6}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-3.5", className)}
@@ -673,7 +647,7 @@ export function IconSizingMax({ className }: IconProps) {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={1.6}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-3.5", className)}
@@ -697,7 +671,7 @@ export function IconSizingVariable({ className }: IconProps) {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={1.6}
+      strokeWidth={1.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       className={cn("size-3.5", className)}

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

@@ -196,6 +196,10 @@ export interface MultiScreenCanvasProps {
   }) => void;
   onCreateScreenFrame?: (geometry: FrameGeometry) => void;
   onDeleteSelection?: (ids: string[]) => boolean | void;
+  /** Return false to keep the arrow key: the host's real selection is an
+   * element inside a screen, and this canvas still lists that screen in
+   * `selectedIds`. Same veto `onDeleteSelection` uses. */
+  onNudgeSelection?: (ids: string[]) => boolean | void;
   onZoomChange?: (zoom: number) => void;
   renderScreenContent?: (
     screen: ScreenFile,

package/corpus/templates/design/app/hooks/use-editor-preferences.ts

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  DEFAULT_EDITOR_PREFERENCES,
+  DESIGN_EDITOR_PREFERENCES_STORAGE_KEY,
+  parseEditorPreferences,
+  serializeEditorPreferences,
+  type DesignEditorPreferences,
+} from "@/pages/design-editor/editor-preferences";
+
+function readStoredPreferences(): DesignEditorPreferences {
+  if (typeof window === "undefined") return DEFAULT_EDITOR_PREFERENCES;
+  let raw: string | null;
+  try {
+    raw = window.localStorage.getItem(DESIGN_EDITOR_PREFERENCES_STORAGE_KEY);
+  } catch {
+    return DEFAULT_EDITOR_PREFERENCES;
+  }
+  const result = parseEditorPreferences(raw);
+  if (result.status === "invalid") {
+    console.warn(
+      `[design] discarding corrupt editor preferences: ${result.reason}`,
+    );
+    try {
+      window.localStorage.removeItem(DESIGN_EDITOR_PREFERENCES_STORAGE_KEY);
+    } catch (error) {
+      console.warn("[design] could not clear editor preferences", error);
+    }
+  }
+  return result.preferences;
+}
+
+export interface UseEditorPreferences {
+  preferences: DesignEditorPreferences;
+  setPreferences: (next: DesignEditorPreferences) => void;
+}
+
+/** Editor-chrome preferences (nudge amounts today) live in localStorage, not
+ * SQL: they are per-device input tuning, and a shared design opened by a
+ * collaborator must keep that collaborator's own nudge amounts. */
+export function useEditorPreferences(): UseEditorPreferences {
+  const [preferences, setPreferencesState] = useState<DesignEditorPreferences>(
+    DEFAULT_EDITOR_PREFERENCES,
+  );
+
+  useEffect(() => {
+    setPreferencesState(readStoredPreferences());
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onStorage = (event: StorageEvent) => {
+      if (event.key !== DESIGN_EDITOR_PREFERENCES_STORAGE_KEY) return;
+      setPreferencesState(readStoredPreferences());
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, []);
+
+  const setPreferences = useCallback((next: DesignEditorPreferences) => {
+    const serialized = serializeEditorPreferences(next);
+    setPreferencesState(parseEditorPreferences(serialized).preferences);
+    if (typeof window === "undefined") return;
+    try {
+      window.localStorage.setItem(
+        DESIGN_EDITOR_PREFERENCES_STORAGE_KEY,
+        serialized,
+      );
+    } catch (error) {
+      console.warn("[design] could not persist editor preferences", error);
+    }
+  }, []);
+
+  return { preferences, setPreferences };
+}

package/corpus/templates/design/app/i18n-data.ts

@@ -746,6 +746,14 @@ const enUS = {
       close: "Close keyboard shortcuts",
       codeContext: "Code",
       screenContext: "Screen",
+      nudgeAmount: {
+        title: "Nudge amount",
+        small: "Small nudge",
+        big: "Big nudge",
+        unit: "px",
+        description:
+          "Arrow keys move by the small amount and Shift+arrow by the big one. Inside an auto layout frame, arrows reorder the layer instead of moving it.",
+      },
       keys: {
         or: "or",
         command: "Command",

package/corpus/templates/design/app/i18n-keyboard-shortcuts.ts

@@ -12,6 +12,10 @@ interface KeyboardShortcutLabels {
   hideUiDescription: string;
   undoDescription: string;
   redoDescription: string;
+  nudgeAmountTitle: string;
+  nudgeAmountSmall: string;
+  nudgeAmountBig: string;
+  nudgeAmountDescription: string;
 }
 
 interface KeyboardKeyLabels {
@@ -50,6 +54,11 @@ export const keyboardShortcutLabels = {
     hideUiDescription: "立即按下以快速隱藏面板並專注於工作",
     undoDescription: "逐步回復最近的設計變更",
     redoDescription: "還原剛才復原的設計變更",
+    nudgeAmountTitle: "微調距離",
+    nudgeAmountSmall: "小距離",
+    nudgeAmountBig: "大距離",
+    nudgeAmountDescription:
+      "方向鍵以小距離移動，Shift+方向鍵以大距離移動。在自動版面配置框架內，方向鍵改為調整圖層順序。",
   },
   "zh-CN": {
     title: "键盘快捷键",
@@ -63,6 +72,11 @@ export const keyboardShortcutLabels = {
     hideUiDescription: "立即按下以快速隐藏面板并专注于工作",
     undoDescription: "逐步撤销最近的设计更改",
     redoDescription: "恢复刚刚撤销的设计更改",
+    nudgeAmountTitle: "微调距离",
+    nudgeAmountSmall: "小距离",
+    nudgeAmountBig: "大距离",
+    nudgeAmountDescription:
+      "方向键以小距离移动，Shift+方向键以大距离移动。在自动布局框架内，方向键改为调整图层顺序。",
   },
   "es-ES": {
     title: "Atajos de teclado",
@@ -77,6 +91,11 @@ export const keyboardShortcutLabels = {
       "Púlsalo ahora para ocultar los paneles y concentrarte en tu trabajo",
     undoDescription: "Retrocede por el cambio de diseño más reciente",
     redoDescription: "Restaura el cambio de diseño que acabas de deshacer",
+    nudgeAmountTitle: "Cantidad de desplazamiento",
+    nudgeAmountSmall: "Desplazamiento pequeño",
+    nudgeAmountBig: "Desplazamiento grande",
+    nudgeAmountDescription:
+      "Las flechas mueven la cantidad pequeña y Mayús+flecha la grande. Dentro de un marco de autodiseño, las flechas reordenan la capa.",
   },
   "fr-FR": {
     title: "Raccourcis clavier",
@@ -92,6 +111,11 @@ export const keyboardShortcutLabels = {
     undoDescription: "Revenez sur votre dernière modification de design",
     redoDescription:
       "Restaurez la modification de design que vous venez d’annuler",
+    nudgeAmountTitle: "Valeur de déplacement",
+    nudgeAmountSmall: "Petit déplacement",
+    nudgeAmountBig: "Grand déplacement",
+    nudgeAmountDescription:
+      "Les flèches déplacent de la petite valeur et Maj+flèche de la grande. Dans un cadre en disposition automatique, les flèches réorganisent le calque.",
   },
   "de-DE": {
     title: "Tastenkürzel",
@@ -107,6 +131,11 @@ export const keyboardShortcutLabels = {
     undoDescription: "Mache die letzte Designänderung rückgängig",
     redoDescription:
       "Stelle die soeben rückgängig gemachte Designänderung wieder her",
+    nudgeAmountTitle: "Verschiebeschrittweite",
+    nudgeAmountSmall: "Kleiner Schritt",
+    nudgeAmountBig: "Großer Schritt",
+    nudgeAmountDescription:
+      "Pfeiltasten verschieben um den kleinen Wert, Umschalt+Pfeil um den großen. In einem Auto-Layout-Rahmen ordnen die Pfeiltasten die Ebene neu an.",
   },
   "ja-JP": {
     title: "キーボードショートカット",
@@ -120,6 +149,11 @@ export const keyboardShortcutLabels = {
     hideUiDescription: "今すぐ押してパネルを隠し、作業に集中できます",
     undoDescription: "直前のデザイン変更を元に戻します",
     redoDescription: "元に戻したデザイン変更を復元します",
+    nudgeAmountTitle: "移動量",
+    nudgeAmountSmall: "小さい移動量",
+    nudgeAmountBig: "大きい移動量",
+    nudgeAmountDescription:
+      "矢印キーは小さい移動量、Shift+矢印キーは大きい移動量で移動します。オートレイアウトフレーム内では、矢印キーはレイヤーの順序を変更します。",
   },
   "ko-KR": {
     title: "키보드 단축키",
@@ -133,6 +167,11 @@ export const keyboardShortcutLabels = {
     hideUiDescription: "지금 눌러 패널을 빠르게 숨기고 작업에 집중하세요",
     undoDescription: "가장 최근 디자인 변경을 되돌립니다",
     redoDescription: "방금 실행 취소한 디자인 변경을 복원합니다",
+    nudgeAmountTitle: "이동 간격",
+    nudgeAmountSmall: "작은 이동",
+    nudgeAmountBig: "큰 이동",
+    nudgeAmountDescription:
+      "화살표 키는 작은 간격으로, Shift+화살표 키는 큰 간격으로 이동합니다. 오토 레이아웃 프레임 안에서는 화살표 키가 레이어 순서를 변경합니다.",
   },
   "pt-BR": {
     title: "Atalhos de teclado",
@@ -148,6 +187,11 @@ export const keyboardShortcutLabels = {
     undoDescription: "Desfaça a alteração de design mais recente",
     redoDescription:
       "Restaure a alteração de design que você acabou de desfazer",
+    nudgeAmountTitle: "Distância de deslocamento",
+    nudgeAmountSmall: "Deslocamento pequeno",
+    nudgeAmountBig: "Deslocamento grande",
+    nudgeAmountDescription:
+      "As setas movem pela distância pequena e Shift+seta pela grande. Dentro de um frame com layout automático, as setas reordenam a camada.",
   },
   "hi-IN": {
     title: "कीबोर्ड शॉर्टकट",
@@ -161,6 +205,11 @@ export const keyboardShortcutLabels = {
     hideUiDescription: "पैनल तुरंत छिपाकर अपने काम पर ध्यान देने के लिए इसे अभी दबाएँ",
     undoDescription: "सबसे हाल के डिज़ाइन बदलाव को वापस करें",
     redoDescription: "अभी वापस किए गए डिज़ाइन बदलाव को फिर से लागू करें",
+    nudgeAmountTitle: "नज की दूरी",
+    nudgeAmountSmall: "छोटी नज",
+    nudgeAmountBig: "बड़ी नज",
+    nudgeAmountDescription:
+      "ऐरो कुंजियाँ छोटी दूरी से और Shift+ऐरो बड़ी दूरी से ले जाती हैं। ऑटो लेआउट फ़्रेम के अंदर ऐरो कुंजियाँ लेयर का क्रम बदलती हैं।",
   },
   "ar-SA": {
     title: "اختصارات لوحة المفاتيح",
@@ -174,6 +223,11 @@ export const keyboardShortcutLabels = {
     hideUiDescription: "اضغطه الآن لإخفاء اللوحات بسرعة والتركيز على عملك",
     undoDescription: "تراجع عن أحدث تغيير في التصميم",
     redoDescription: "استعد تغيير التصميم الذي تراجعت عنه للتو",
+    nudgeAmountTitle: "مقدار الإزاحة",
+    nudgeAmountSmall: "إزاحة صغيرة",
+    nudgeAmountBig: "إزاحة كبيرة",
+    nudgeAmountDescription:
+      "تحرّك مفاتيح الأسهم بالمقدار الصغير، وShift+سهم بالمقدار الكبير. داخل إطار التخطيط التلقائي، تعيد مفاتيح الأسهم ترتيب الطبقة.",
   },
 } satisfies Record<Exclude<LocaleCode, "en-US">, KeyboardShortcutLabels>;
 
@@ -483,6 +537,13 @@ export function attachLocalizedKeyboardShortcuts<
         close: `${d.close}: ${labels.title}`,
         codeContext: edit.sections.codeConfidence,
         screenContext: layers.screens,
+        nudgeAmount: {
+          title: labels.nudgeAmountTitle,
+          small: labels.nudgeAmountSmall,
+          big: labels.nudgeAmountBig,
+          unit: "px",
+          description: labels.nudgeAmountDescription,
+        },
         keys: keyLabels,
         descriptions: {
           toggleUi: labels.hideUiDescription,

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

@@ -0,0 +1,98 @@
+import { DEFAULT_NUDGE_AMOUNTS, type NudgeAmounts } from "./nudge-intent";
+
+export const DESIGN_EDITOR_PREFERENCES_STORAGE_KEY =
+  "agent-native.design.editor-preferences";
+
+export interface DesignEditorPreferences {
+  nudge: NudgeAmounts;
+}
+
+export const DEFAULT_EDITOR_PREFERENCES: DesignEditorPreferences = {
+  nudge: DEFAULT_NUDGE_AMOUNTS,
+};
+
+/** Figma allows 1-1000 for both nudge amounts and rejects 0 — a 0 nudge makes
+ * the arrow keys look broken rather than doing nothing on purpose. */
+export const MIN_NUDGE_AMOUNT = 1;
+export const MAX_NUDGE_AMOUNT = 1000;
+
+export function normalizeNudgeAmount(value: unknown, fallback: number): number {
+  const parsed = typeof value === "string" ? Number(value) : value;
+  if (typeof parsed !== "number" || !Number.isFinite(parsed)) return fallback;
+  return Math.min(
+    MAX_NUDGE_AMOUNT,
+    Math.max(MIN_NUDGE_AMOUNT, Math.round(parsed)),
+  );
+}
+
+export type ParseEditorPreferencesResult =
+  | { status: "absent"; preferences: DesignEditorPreferences }
+  | { status: "ok"; preferences: DesignEditorPreferences }
+  | {
+      status: "invalid";
+      preferences: DesignEditorPreferences;
+      reason: string;
+    };
+
+/** Never collapses "nothing stored yet" and "stored value is corrupt" into the
+ * same result: the caller must be able to tell a first run from a store it
+ * should overwrite rather than keep re-reading. */
+export function parseEditorPreferences(
+  raw: string | null | undefined,
+): ParseEditorPreferencesResult {
+  if (raw === null || raw === undefined || raw === "") {
+    return { status: "absent", preferences: DEFAULT_EDITOR_PREFERENCES };
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(raw);
+  } catch (error) {
+    return {
+      status: "invalid",
+      preferences: DEFAULT_EDITOR_PREFERENCES,
+      reason: String(error),
+    };
+  }
+  if (typeof decoded !== "object" || decoded === null) {
+    return {
+      status: "invalid",
+      preferences: DEFAULT_EDITOR_PREFERENCES,
+      reason: "expected an object",
+    };
+  }
+  const nudge = (decoded as { nudge?: unknown }).nudge;
+  if (nudge !== undefined && (typeof nudge !== "object" || nudge === null)) {
+    return {
+      status: "invalid",
+      preferences: DEFAULT_EDITOR_PREFERENCES,
+      reason: "expected nudge to be an object",
+    };
+  }
+  const source = (nudge ?? {}) as { small?: unknown; big?: unknown };
+  return {
+    status: "ok",
+    preferences: {
+      nudge: {
+        small: normalizeNudgeAmount(source.small, DEFAULT_NUDGE_AMOUNTS.small),
+        big: normalizeNudgeAmount(source.big, DEFAULT_NUDGE_AMOUNTS.big),
+      },
+    },
+  };
+}
+
+export function serializeEditorPreferences(
+  preferences: DesignEditorPreferences,
+): string {
+  return JSON.stringify({
+    nudge: {
+      small: normalizeNudgeAmount(
+        preferences.nudge.small,
+        DEFAULT_NUDGE_AMOUNTS.small,
+      ),
+      big: normalizeNudgeAmount(
+        preferences.nudge.big,
+        DEFAULT_NUDGE_AMOUNTS.big,
+      ),
+    },
+  });
+}