@agent-native/core 0.80.8 → 0.80.10

package/corpus/templates/design/app/components/design/EditPanel.tsx

@@ -1,4 +1,8 @@
-import { useT } from "@agent-native/core/client";
+import {
+  useActionMutation,
+  useActionQuery,
+  useT,
+} from "@agent-native/core/client";
 import type { TweakDefinition } from "@shared/api";
 import {
   alphaToOpacity,
@@ -14,13 +18,15 @@ import {
   IconAlignRight,
   IconArrowAutofitHeight,
   IconArrowAutofitWidth,
+  IconArrowRight,
   IconBackground,
   IconBlur,
   IconBorderStyle,
   IconBrush,
-  IconChevronDown,
   IconCode,
   IconComponents,
+  IconDeviceDesktop,
+  IconExternalLink,
   IconDroplet,
   IconEye,
   IconEyeOff,
@@ -29,6 +35,8 @@ import {
   IconFrame,
   IconLayoutDistributeHorizontal,
   IconLayoutGrid,
+  IconLoader2,
+  IconShieldCheck,
   IconSlice,
   IconLayoutAlignBottom,
   IconLayoutAlignCenter,
@@ -40,6 +48,7 @@ import {
   IconLetterSpacing,
   IconLineHeight,
   IconLink,
+  IconLock,
   IconMaximize,
   IconMinus,
   IconPalette,
@@ -51,9 +60,25 @@ import {
   IconUnlink,
   IconVector,
 } from "@tabler/icons-react";
-import { useCallback, useEffect, useState, type ReactNode } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { useParams } from "react-router";
 
 import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -75,6 +100,7 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 import { Slider } from "@/components/ui/slider";
+import { Switch } from "@/components/ui/switch";
 import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import {
   Tooltip,
@@ -100,18 +126,34 @@ import {
   type AutoLayoutSizingAxis,
   type ConstraintsValue,
   type ExportSettingsValue,
+  imageFillToBackgroundStyles,
   type DesignFillRow,
   type DesignFillRowPatch,
   type DesignGradientStop,
   type DesignGradientStopPatch,
   type DesignGradientType,
+  type ImageFillValue,
 } from "./inspector";
+import { IconLayoutSettings } from "./inspector/design-icons";
 import type { DesignPaintType } from "./inspector/DesignColorPicker";
+import { InspectorAiActions } from "./inspector/InspectorAiActions";
+import { ReviewPanel } from "./ReviewPanel";
+import type { ReviewPanelProps } from "./ReviewPanel";
+import { StatesPanel } from "./StatesPanel";
+import type { StatesPanelProps } from "./StatesPanel";
+import { TokensPanel } from "./TokensPanel";
 import { TweaksPanelContent } from "./TweaksPanel";
 import type { ElementInfo } from "./types";
 
 export type InspectorTab = "design" | "tweaks" | "extensions";
 
+/**
+ * Sub-tab within the Tweaks area: "tokens" = TokensPanel face (CSS-var
+ * editing through the Tweaks loop); "tweaks" = raw TweakDefinition controls.
+ * Defaults to "tokens" when a designId is provided, otherwise "tweaks".
+ */
+type TweaksSubTab = "tokens" | "tweaks";
+
 interface EditPanelProps {
   selectedElement: ElementInfo | null;
   pageStyles?: Record<string, string>;
@@ -127,8 +169,84 @@ interface EditPanelProps {
   onRequestTweaks?: (anchor: HTMLElement) => void;
   onStyleChange: (property: string, value: string) => void;
   onStylesChange?: (styles: Record<string, string>) => void;
+  onAutoLayoutConvert?: (
+    targetNodeId: string,
+    opts?: { direction?: "row" | "column"; gap?: string },
+  ) => void;
   onExport?: (settings: ExportSettingsValue[]) => void;
   exporting?: boolean;
+  readOnly?: boolean;
+  /** Active file id — forwarded to InspectorAiActions for agent context. */
+  fileId?: string;
+  /** Active file name (e.g. "index.html") — forwarded to InspectorAiActions. */
+  filename?: string;
+  // -------------------------------------------------------------------------
+  // Design Studio panels (§6.2, §6.4, §6.5)
+  // Pass `designId` to unlock Tokens, States, and Review sections.
+  // -------------------------------------------------------------------------
+  /** The active design's id — required to mount Tokens / States / Review. */
+  designId?: string;
+  /**
+   * Called after a token edit is applied so the parent can push the resolved
+   * CSS-var map into the iframe via the tweak-values postMessage.
+   */
+  onTokensApplied?: (resolvedCssVars: Record<string, string>) => void;
+  /** Props forwarded to the StatesPanel (§6.4). Requires `designId`. */
+  statesPanelProps?: Omit<StatesPanelProps, "designId">;
+  /** Props forwarded to the ReviewPanel (§6.5). */
+  reviewPanelProps?: Omit<ReviewPanelProps, "className">;
+  // -------------------------------------------------------------------------
+  // Component section (§6.1)
+  // When a component instance is selected, pass its node id here to unlock
+  // the contextual Component section at the top of the Design tab.
+  // -------------------------------------------------------------------------
+  /**
+   * The `data-agent-native-node-id` of the currently-selected component root
+   * element.  When provided (along with `designId`), a Component section is
+   * shown at the top of the Design tab with name, source path, prop controls,
+   * and an Edit component action.
+   */
+  componentNodeId?: string;
+  /**
+   * Source capabilities for the current design.  Used to gate the Edit
+   * component / jump-to-source affordances.  When absent all writes default
+   * to disabled (inline / Alpine tier behaviour).
+   */
+  sourceCapabilities?: string[];
+  // -------------------------------------------------------------------------
+  // Selection header quick actions ("Create component" + "Inspect code")
+  // -------------------------------------------------------------------------
+  /**
+   * Promote the current selection into a reusable component. Receives the
+   * (already-normalized-by-the-action) component name the user typed. When
+   * omitted the "Create component" button is disabled.
+   */
+  onCreateComponent?: (name: string) => void;
+  /** Suggested default name for the create-component dialog. */
+  defaultComponentName?: string;
+  /** Code-inspection data for the "Inspect code" popover. */
+  inspectCode?: InspectCodeData;
+}
+
+/**
+ * Data backing the "Inspect code" popover. The parent resolves the selected
+ * node's HTML and (for real-app sources) its source file location.
+ */
+export interface InspectCodeData {
+  /** Outer HTML of the selected element (inline / Alpine source). */
+  html?: string | null;
+  /**
+   * Resolved source file for real-app sources (localhost / fusion), when the
+   * resolveNodeToFile capability is available.
+   */
+  sourceLocation?: {
+    /** Absolute path on disk — used to build the vscode:// deep link. */
+    absolutePath: string;
+    line?: number;
+    column?: number;
+    /** Optional snippet to show above the Open-in-VS-Code button. */
+    snippet?: string;
+  } | null;
 }
 
 /**
@@ -238,6 +356,7 @@ function ColorInput({
   onChange,
   backgroundImage,
   onBackgroundImageChange,
+  onImageFillChange,
   blendMode,
   onBlendModeChange,
   supportsLayeredFills = false,
@@ -249,6 +368,7 @@ function ColorInput({
   onChange: (value: string) => void;
   backgroundImage?: string;
   onBackgroundImageChange?: (value: string) => void;
+  onImageFillChange?: (value: ImageFillValue) => void;
   blendMode?: string;
   onBlendModeChange?: (value: string) => void;
   supportsLayeredFills?: boolean;
@@ -558,9 +678,10 @@ function ColorInput({
       onPaintValueChange={
         supportsLayeredFills ? handlePaintValueChange : undefined
       }
+      onImageFillChange={onImageFillChange}
       blendMode={blendMode}
       onBlendModeChange={onBlendModeChange}
-      showBlendMode={supportsLayeredFills}
+      showBlendMode={Boolean(onBlendModeChange)}
       fillRows={fillRows}
       selectedFillId={selectedFillId}
       onFillSelect={supportsLayeredFills ? setSelectedFillId : undefined}
@@ -912,8 +1033,6 @@ function PropSlider({
   );
 }
 
-const EmptyScrubIcon = () => null;
-
 /**
  * design-editor inspector section. Matches the design editor "Design" panel chrome:
  *   - NO left collapse chevron (the design editor uses none).
@@ -1131,6 +1250,99 @@ const FONT_WEIGHT_OPTIONS = [
   { value: "900", key: "black" },
 ] as const;
 
+type TextResizeMode = "auto-width" | "auto-height" | "fixed";
+
+function cleanFontFamilyName(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function splitFontFamilyList(value: string | undefined): string[] {
+  const raw = value?.trim();
+  if (!raw) return [];
+
+  const families: string[] = [];
+  let token = "";
+  let quote: '"' | "'" | null = null;
+
+  for (let i = 0; i < raw.length; i += 1) {
+    const char = raw[i];
+    if ((char === '"' || char === "'") && raw[i - 1] !== "\\") {
+      if (quote === char) quote = null;
+      else if (!quote) quote = char;
+      token += char;
+      continue;
+    }
+    if (char === "," && !quote) {
+      const cleaned = cleanFontFamilyName(token);
+      if (cleaned) families.push(cleaned);
+      token = "";
+      continue;
+    }
+    token += char;
+  }
+
+  const cleaned = cleanFontFamilyName(token);
+  if (cleaned) families.push(cleaned);
+  return families;
+}
+
+function normalizeFontFamilyName(value: string): string {
+  return cleanFontFamilyName(value).replace(/\s+/g, " ").toLowerCase();
+}
+
+function normalizeFontFamilyStack(value: string): string {
+  return splitFontFamilyList(value).map(normalizeFontFamilyName).join(",");
+}
+
+function displayFontFamilyName(value: string | undefined): string {
+  const first = splitFontFamilyList(value)[0];
+  if (!first) return "Sans Serif"; // i18n-ignore design generic font label
+
+  const normalized = normalizeFontFamilyName(first);
+  if (normalized === "sans-serif") {
+    return "Sans Serif"; // i18n-ignore design generic font label
+  }
+  if (normalized === "serif") return "Serif"; // i18n-ignore design generic font label
+  if (normalized === "monospace") {
+    return "Monospace"; // i18n-ignore design generic font label
+  }
+  if (normalized === "system-ui" || normalized === "-apple-system") {
+    return "System UI"; // i18n-ignore design generic font label
+  }
+  if (normalized === "blinkmacsystemfont") {
+    return "Apple System"; // i18n-ignore design generic font label
+  }
+  return first;
+}
+
+function resolveFontFamilySelectValue(value: string | undefined): string {
+  const raw = value?.trim();
+  if (!raw) return "sans-serif";
+
+  const normalizedStack = normalizeFontFamilyStack(raw);
+  const exactOption = FONT_FAMILY_OPTIONS.find(
+    (option) => normalizeFontFamilyStack(option.value) === normalizedStack,
+  );
+  if (exactOption) return exactOption.value;
+
+  const firstFamily = normalizeFontFamilyName(
+    splitFontFamilyList(raw)[0] ?? "",
+  );
+  const firstFamilyOption = FONT_FAMILY_OPTIONS.find(
+    (option) =>
+      normalizeFontFamilyName(splitFontFamilyList(option.value)[0] ?? "") ===
+      firstFamily,
+  );
+  return firstFamilyOption?.value ?? raw;
+}
+
 const ALIGN_SELF_OPTIONS = [
   { value: "auto", key: "auto" },
   { value: "flex-start", key: "start" },
@@ -1282,6 +1494,8 @@ function ScrubStyleInput({
   step = 1,
   labelClassName,
   inputClassName,
+  ariaLabel,
+  tooltipLabel,
   hideIcon = true,
 }: {
   label: string;
@@ -1295,11 +1509,15 @@ function ScrubStyleInput({
   labelClassName?: string;
   inputClassName?: string;
   hideIcon?: boolean;
+  ariaLabel?: string;
+  tooltipLabel?: string;
 }) {
   return (
     <ScrubInput
       label={label}
-      icon={hideIcon ? EmptyScrubIcon : undefined}
+      ariaLabel={ariaLabel}
+      tooltipLabel={tooltipLabel}
+      icon={hideIcon ? null : undefined}
       value={value ? parseNumericValue(value) : (placeholder ?? 0)}
       onChange={onChange}
       unit={unit}
@@ -1650,6 +1868,33 @@ function inferElementSizing(
   return "fixed";
 }
 
+/**
+ * Return the element's geometric dimension on the given axis in CSS pixels.
+ *
+ * `getComputedStyle().width/height` always resolves to a computed px value
+ * (even for `width: auto` the browser returns e.g. "200px"). For rotated
+ * elements this is the pre-rotation CSS box size — what Figma shows in the
+ * inspector — while `getBoundingClientRect().width/height` would be the
+ * axis-aligned bounding box which is inflated by the rotation.
+ *
+ * Falls back to the bounding-rect dimension only when the computed style is
+ * missing or unparseable (e.g. the bridge hasn't populated it yet).
+ */
+function cssElementSize(
+  element: ElementInfo,
+  axis: AutoLayoutSizingAxis,
+): number {
+  const isHorizontal = axis === "horizontal";
+  const cssValue = isHorizontal
+    ? element.computedStyles.width
+    : element.computedStyles.height;
+  const parsed = parseFloat(cssValue || "");
+  const fallback = isHorizontal
+    ? element.boundingRect.width
+    : element.boundingRect.height;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 function commitElementSizing(
   element: ElementInfo,
   axis: AutoLayoutSizingAxis,
@@ -1659,12 +1904,10 @@ function commitElementSizing(
 ) {
   const isHorizontal = axis === "horizontal";
   const sizeProperty = isHorizontal ? "width" : "height";
-  const resolvedSize = Math.max(
-    1,
-    Math.round(
-      isHorizontal ? element.boundingRect.width : element.boundingRect.height,
-    ),
-  );
+  // Use CSS computed dimension (pre-rotation box size) as the seed for "fixed"
+  // sizing so a rotated element is locked to its actual CSS width/height rather
+  // than the inflated axis-aligned bounding rect.
+  const resolvedSize = Math.max(1, Math.round(cssElementSize(element, axis)));
   const parentDirection = parentFlexDirection(element);
   const isFlex = isParentFlex(element);
   const isGrid = isParentGrid(element);
@@ -1715,6 +1958,325 @@ function commitElementSizing(
   commitStylePatch(patch, onStyleChange, onStylesChange);
 }
 
+/**
+ * Small modal that prompts for a component name, then promotes the current
+ * selection into a reusable component via `onSubmit`.
+ */
+function CreateComponentDialog({
+  open,
+  onOpenChange,
+  defaultName,
+  onSubmit,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  defaultName: string;
+  onSubmit: (name: string) => void;
+}) {
+  const [name, setName] = useState(defaultName);
+
+  // Reset the field to the freshest default each time the dialog opens.
+  useEffect(() => {
+    if (open) setName(defaultName);
+  }, [open, defaultName]);
+
+  const commit = () => {
+    const trimmed = name.trim();
+    if (!trimmed) return;
+    onSubmit(trimmed);
+    onOpenChange(false);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-sm">
+        <DialogHeader>
+          <DialogTitle>
+            {"Create component" /* i18n-ignore design inspector action */}
+          </DialogTitle>
+          <DialogDescription>
+            {
+              "Name this element so it becomes a reusable component. The agent can then extract props and replace repeated instances." /* i18n-ignore design inspector copy */
+            }
+          </DialogDescription>
+        </DialogHeader>
+        <div className="space-y-1.5">
+          <Label
+            htmlFor="create-component-name"
+            className="text-[11px] font-medium text-muted-foreground"
+          >
+            {"Component name" /* i18n-ignore design inspector label */}
+          </Label>
+          <Input
+            id="create-component-name"
+            autoFocus
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") {
+                e.preventDefault();
+                commit();
+              }
+            }}
+            placeholder={
+              "PrimaryButton" /* i18n-ignore design inspector placeholder */
+            }
+          />
+        </div>
+        <DialogFooter>
+          <Button
+            type="button"
+            variant="ghost"
+            onClick={() => onOpenChange(false)}
+          >
+            {"Cancel" /* i18n-ignore design inspector action */}
+          </Button>
+          <Button type="button" onClick={commit} disabled={!name.trim()}>
+            {"Create" /* i18n-ignore design inspector action */}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/** Build a `vscode://file/...` deep link for an absolute path + position. */
+function vscodeDeepLink(
+  absolutePath: string,
+  line?: number,
+  column?: number,
+): string {
+  const base = `vscode://file/${absolutePath}`;
+  if (line == null) return base;
+  return column == null ? `${base}:${line}` : `${base}:${line}:${column}`;
+}
+
+/**
+ * Extract the *opening tag* from an element's outer HTML for an at-a-glance
+ * summary (e.g. `<main class="hero" data-x="y">`). Self-closing tags keep
+ * their `/>`. Returns `null` when no tag can be parsed.
+ *
+ * Pure — exported for tests.
+ */
+export function openingTagOf(html: string | null | undefined): string | null {
+  if (!html) return null;
+  const trimmed = html.trimStart();
+  // Match the first `<tag ...>` (greedy up to the first unquoted `>`), allowing
+  // quoted attribute values to contain `>`.
+  const match = /^<([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>])*?)\/?>/.exec(
+    trimmed,
+  );
+  if (!match) return null;
+  return match[0];
+}
+
+/**
+ * Collapse long attribute values in an opening tag so the at-a-glance summary
+ * stays readable. Values longer than `max` chars are truncated with an
+ * ellipsis (the surrounding quotes are preserved).
+ *
+ * Pure — exported for tests.
+ */
+export function truncateOpeningTag(openTag: string, max = 32): string {
+  return openTag.replace(
+    /("|')((?:\\.|(?!\1)[^\\])*)\1/g,
+    (full, quote, value) => {
+      if (typeof value !== "string" || value.length <= max) return full;
+      return `${quote}${value.slice(0, max - 1)}…${quote}`;
+    },
+  );
+}
+
+/**
+ * Parse the top-level `key: value` pairs from an Alpine `x-data` object literal
+ * (e.g. `{ variant: 'outline', size: 'lg', disabled: false }`).
+ *
+ * Best-effort: only handles a flat object of simple string / boolean / number
+ * literals — exactly the shape used for component variant + state props. Nested
+ * objects, methods, and computed expressions are ignored. Returns `null` when
+ * the value is not a recognizable flat object literal.
+ *
+ * Pure — exported for tests.
+ */
+export function parseAlpineDataObject(
+  xData: string | null | undefined,
+): Record<string, string> | null {
+  if (!xData) return null;
+  const trimmed = xData.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  if (!inner) return {};
+
+  const out: Record<string, string> = {};
+  // Split on top-level commas only (no nesting / quotes inside values here).
+  const pairRe =
+    /(?:^|,)\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*:\s*('[^']*'|"[^"]*"|true|false|-?\d+(?:\.\d+)?)/g;
+  let m: RegExpExecArray | null;
+  let matched = false;
+  while ((m = pairRe.exec(inner)) !== null) {
+    matched = true;
+    const key = m[1] ?? m[2] ?? m[3];
+    let raw = m[4]!;
+    // Unwrap quotes for string literals; keep booleans / numbers verbatim.
+    if (
+      (raw.startsWith("'") && raw.endsWith("'")) ||
+      (raw.startsWith('"') && raw.endsWith('"'))
+    ) {
+      raw = raw.slice(1, -1);
+    }
+    if (key) out[key] = raw;
+  }
+  // If there was content but nothing parsed, the shape is too complex to edit
+  // safely — bail so the caller falls back to attribute-based prop edits.
+  if (!matched) return null;
+  return out;
+}
+
+/**
+ * Re-serialize a flat Alpine data object back into an `x-data` literal,
+ * preserving boolean / number literals unquoted and single-quoting strings.
+ *
+ * Pure — exported for tests.
+ */
+export function serializeAlpineDataObject(obj: Record<string, string>): string {
+  const parts = Object.entries(obj).map(([key, value]) => {
+    const isBoolean = value === "true" || value === "false";
+    const isNumber = /^-?\d+(\.\d+)?$/.test(value);
+    const literal =
+      isBoolean || isNumber ? value : `'${value.replace(/'/g, "\\'")}'`;
+    return `${key}: ${literal}`;
+  });
+  return parts.length ? `{ ${parts.join(", ")} }` : "{}";
+}
+
+/** A boolean-ish prop value (`"true"` / `"false"`), case-insensitive. */
+export function isBooleanPropValue(value: string): boolean {
+  const v = value.trim().toLowerCase();
+  return v === "true" || v === "false";
+}
+
+/**
+ * Popover anchored to the "Inspect code" button showing the selected node's
+ * code.  Inline/Alpine sources show the element's outer HTML with a Copy
+ * button; real-app sources additionally render an "Open in VS Code" button.
+ *
+ * TODO: replace the read-only <pre> with an inline Monaco editor for richer
+ * (editable) code inspection once the editor bundle is wired into the inspector.
+ */
+function InspectCodePopover({
+  trigger,
+  data,
+}: {
+  trigger: ReactNode;
+  data: InspectCodeData;
+}) {
+  const [copied, setCopied] = useState(false);
+  const html = data.html ?? "";
+  const source = data.sourceLocation ?? null;
+  const snippet = source?.snippet || html;
+  // At-a-glance opening tag (tag name + attributes), truncated for readability.
+  const openingTag = (() => {
+    const raw = openingTagOf(html);
+    return raw ? truncateOpeningTag(raw) : null;
+  })();
+
+  const handleCopy = () => {
+    if (!snippet) return;
+    void navigator.clipboard
+      ?.writeText(snippet)
+      .then(() => {
+        setCopied(true);
+        window.setTimeout(() => setCopied(false), 1200);
+      })
+      .catch(() => {
+        /* clipboard may be unavailable; ignore */
+      });
+  };
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+      <PopoverContent align="end" className="w-80 space-y-2 p-2 text-[11px]">
+        <div className="flex items-center justify-between gap-2">
+          <span className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/70">
+            {"Inspect code" /* i18n-ignore design inspector label */}
+          </span>
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="h-6 px-2 text-[10px]"
+            onClick={handleCopy}
+            disabled={!snippet}
+          >
+            {
+              copied
+                ? "Copied" /* i18n-ignore design inspector action */
+                : "Copy" /* i18n-ignore design inspector action */
+            }
+          </Button>
+        </div>
+
+        {/* At-a-glance opening tag (tag name + attributes) above the full HTML. */}
+        {openingTag && (
+          <code
+            className="block truncate rounded bg-[var(--design-editor-control-bg)] px-2 py-1 font-mono text-[10px] text-foreground"
+            title={openingTag}
+          >
+            {openingTag}
+          </code>
+        )}
+
+        {source && (
+          <div
+            className="flex items-center gap-1 rounded bg-[var(--design-editor-control-bg)] px-2 py-1"
+            title={source.absolutePath}
+          >
+            <IconCode className="size-3 shrink-0 text-muted-foreground/60" />
+            <span className="min-w-0 flex-1 truncate font-mono text-[10px] text-muted-foreground">
+              {source.absolutePath}
+              {source.line != null ? `:${source.line}` : ""}
+            </span>
+          </div>
+        )}
+
+        {snippet ? (
+          <pre className="max-h-64 overflow-auto rounded bg-[var(--design-editor-control-bg)] p-2 font-mono text-[10px] leading-relaxed text-foreground">
+            <code>{snippet}</code>
+          </pre>
+        ) : (
+          <p className="px-1 py-2 text-muted-foreground">
+            {
+              "No source available for this element." /* i18n-ignore design inspector empty */
+            }
+          </p>
+        )}
+
+        {source && (
+          <a
+            href={vscodeDeepLink(
+              source.absolutePath,
+              source.line,
+              source.column,
+            )}
+            className="block"
+          >
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              className="h-7 w-full gap-1.5 text-[11px]"
+            >
+              <IconExternalLink className="size-3.5" />
+              {"Open in VS Code" /* i18n-ignore design inspector action */}
+            </Button>
+          </a>
+        )}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
 function elementTypeIcon(element: ElementInfo) {
   const tag = element.tagName || "element";
   if (TEXT_TAGS.has(tag)) return IconTypography;
@@ -1724,35 +2286,55 @@ function elementTypeIcon(element: ElementInfo) {
   return IconFrame;
 }
 
-function SelectionHeader({ element }: { element: ElementInfo | null }) {
+function SelectionHeader({
+  element,
+  onCreateComponent,
+  inspectCodePopover,
+}: {
+  element: ElementInfo | null;
+  /** Promote the current selection into a reusable component. Omit/undefined to disable. */
+  onCreateComponent?: () => void;
+  /**
+   * Render prop for the "Inspect code" affordance. Receives the trigger button
+   * so the parent can anchor a Popover to it; returns the full popover element.
+   * When omitted the button renders disabled.
+   */
+  inspectCodePopover?: (trigger: ReactNode) => ReactNode;
+}) {
   if (!element) return null;
 
   const title = inspectorObjectTitle(element);
   const TypeIcon = elementTypeIcon(element);
 
+  const inspectTrigger = (
+    <SectionIconButton
+      label={"Inspect code" /* i18n-ignore design inspector action */}
+      disabled={!inspectCodePopover}
+    >
+      <IconCode className="size-3.5" />
+    </SectionIconButton>
+  );
+
   return (
     <div className="flex min-h-8 shrink-0 items-center justify-between gap-2 border-b border-border/90 px-3">
-      {/* M3 · Node-type label + rename/type dropdown affordance (▾) */}
-      <button
-        type="button"
-        className="flex min-w-0 items-center gap-1.5 bg-transparent text-left text-[13px] font-semibold text-foreground"
-      >
+      {/* Node-type label. Rename lives in the layers panel and device sizing
+          lives elsewhere, so this is a plain non-interactive label. */}
+      <div className="flex min-w-0 items-center gap-1.5 text-left text-[13px] font-semibold text-foreground">
         <TypeIcon className="size-3.5 shrink-0 text-muted-foreground" />
         <span className="truncate">{title}</span>
-        <IconChevronDown className="size-2.5 shrink-0 text-muted-foreground" />
-      </button>
-      {/* M3 · Right-aligned quick actions: create-component + dev inspect (</>) */}
+      </div>
+      {/* Right-aligned quick actions: create-component + dev inspect (</>) */}
       <div className="flex shrink-0 items-center gap-0.5">
         <SectionIconButton
           label={"Create component" /* i18n-ignore design inspector action */}
+          disabled={!onCreateComponent}
+          onClick={onCreateComponent}
         >
           <IconComponents className="size-3.5" />
         </SectionIconButton>
-        <SectionIconButton
-          label={"Inspect code" /* i18n-ignore design inspector action */}
-        >
-          <IconCode className="size-3.5" />
-        </SectionIconButton>
+        {inspectCodePopover
+          ? inspectCodePopover(inspectTrigger)
+          : inspectTrigger}
       </div>
     </div>
   );
@@ -1770,7 +2352,7 @@ function InspectorTabsHeader({
   const t = useT();
 
   return (
-    <div className="flex min-h-8 shrink-0 items-center justify-between gap-1 border-b border-border/90 px-2">
+    <div className="flex min-h-8 shrink-0 items-center justify-between gap-1 border-b border-border/90 px-2 py-1">
       <Tabs
         value={activeTab}
         onValueChange={(value) => onActiveTabChange(value as InspectorTab)}
@@ -1912,12 +2494,113 @@ function InspectorIconButton({
 
 function InspectorSegment({ children }: { children: ReactNode }) {
   return (
-    <div className="flex min-w-0 overflow-hidden rounded-md bg-[var(--design-editor-control-bg)]">
+    <div className="flex w-fit max-w-full min-w-0 overflow-hidden rounded-md bg-[var(--design-editor-control-bg)]">
       {children}
     </div>
   );
 }
 
+function TextResizeControls({
+  resizeMode,
+  onResizeModeChange,
+}: {
+  resizeMode: TextResizeMode;
+  onResizeModeChange: (mode: TextResizeMode) => void;
+}) {
+  const t = useT();
+
+  return (
+    <InspectorSegment>
+      <InspectorIconButton
+        label={t("editPanel.textResize.autoWidth")}
+        active={resizeMode === "auto-width"}
+        onClick={() => onResizeModeChange("auto-width")}
+      >
+        <IconArrowAutofitWidth className="size-3.5" />
+      </InspectorIconButton>
+      <InspectorIconButton
+        label={t("editPanel.textResize.autoHeight")}
+        active={resizeMode === "auto-height"}
+        onClick={() => onResizeModeChange("auto-height")}
+      >
+        <IconArrowAutofitHeight className="size-3.5" />
+      </InspectorIconButton>
+      <InspectorIconButton
+        label={t("editPanel.textResize.fixed")}
+        active={resizeMode === "fixed"}
+        onClick={() => onResizeModeChange("fixed")}
+      >
+        <IconSquare className="size-3.5" />
+      </InspectorIconButton>
+    </InspectorSegment>
+  );
+}
+
+function TypographyDetailsPopover({
+  resizeMode,
+  onResizeModeChange,
+}: {
+  resizeMode: TextResizeMode;
+  onResizeModeChange: (mode: TextResizeMode) => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          aria-label={"Typography details" /* i18n-ignore design action */}
+          aria-pressed={open}
+          className={cn(
+            "h-6 min-w-6 cursor-pointer rounded-md text-muted-foreground hover:bg-[var(--design-editor-panel-raised-bg)] hover:text-foreground",
+            open &&
+              "bg-[var(--design-editor-accent-color)]/20 text-[var(--design-editor-accent-color)] hover:text-[var(--design-editor-accent-color)]",
+          )}
+        >
+          <IconLayoutSettings className="size-3.5" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent
+        side="left"
+        align="end"
+        sideOffset={8}
+        className="z-[100010] w-[360px] rounded-xl border-[var(--design-editor-control-border)] bg-[var(--design-editor-panel-bg)] p-0 text-foreground shadow-2xl"
+      >
+        <div className="flex items-center gap-1 border-b border-[var(--design-editor-control-border)] p-2.5">
+          <div className="flex rounded-md bg-[var(--design-editor-control-bg)] p-0.5">
+            <span className="rounded bg-[var(--design-editor-panel-raised-bg)] px-2.5 py-1 text-[11px] font-semibold text-foreground">
+              {"Basics" /* i18n-ignore design typography details tab */}
+            </span>
+            <span className="px-2.5 py-1 text-[11px] font-medium text-muted-foreground">
+              {"Details" /* i18n-ignore design typography details tab */}
+            </span>
+            <span className="px-2.5 py-1 text-[11px] font-medium text-muted-foreground">
+              {"Variable" /* i18n-ignore design typography details tab */}
+            </span>
+          </div>
+        </div>
+        <div className="space-y-3 p-4 text-[11px]">
+          <div className="flex h-20 items-center justify-center rounded-md bg-[var(--design-editor-control-bg)] text-[18px] text-muted-foreground/80">
+            {"Preview" /* i18n-ignore design typography details preview */}
+          </div>
+          <div className="flex items-center justify-between gap-3">
+            <span className="text-[11px] font-medium text-muted-foreground">
+              {"Text box" /* i18n-ignore design typography details label */}
+            </span>
+            <TextResizeControls
+              resizeMode={resizeMode}
+              onResizeModeChange={onResizeModeChange}
+            />
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
 function CornerRadiusControl({
   styles,
   onStyleChange,
@@ -2389,20 +3072,29 @@ function ShadowEffectRow({
 function PageProperties({
   styles,
   onStyleChange,
+  onStylesChange,
 }: {
   styles: Record<string, string>;
   onStyleChange: (property: string, value: string) => void;
+  onStylesChange?: (styles: Record<string, string>) => void;
 }) {
   const t = useT();
-  const fontFamilyOptions = FONT_FAMILY_OPTIONS.map((option) => ({
+  const baseFontFamilyOptions = FONT_FAMILY_OPTIONS.map((option) => ({
     value: option.value,
     label: t(`editPanel.fontFamilies.${option.key}`),
   }));
-  const fontFamily = FONT_FAMILY_OPTIONS.some(
-    (option) => option.value === styles.fontFamily,
+  const fontFamily = resolveFontFamilySelectValue(styles.fontFamily);
+  const fontFamilyOptions = FONT_FAMILY_OPTIONS.some(
+    (option) => option.value === fontFamily,
   )
-    ? styles.fontFamily
-    : "sans-serif";
+    ? baseFontFamilyOptions
+    : [
+        {
+          value: fontFamily,
+          label: displayFontFamilyName(styles.fontFamily || fontFamily),
+        },
+        ...baseFontFamilyOptions,
+      ];
 
   return (
     <div>
@@ -2413,6 +3105,13 @@ function PageProperties({
           onChange={(v) => onStyleChange("backgroundColor", v)}
           backgroundImage={styles.backgroundImage || ""}
           onBackgroundImageChange={(v) => onStyleChange("backgroundImage", v)}
+          onImageFillChange={(value) =>
+            commitStylePatch(
+              imageFillToBackgroundStyles(value),
+              onStyleChange,
+              onStylesChange,
+            )
+          }
           blendMode={styles.backgroundBlendMode || "normal"}
           onBlendModeChange={(v) => onStyleChange("backgroundBlendMode", v)}
           supportsLayeredFills
@@ -2445,10 +3144,22 @@ function TypographyProperties({
 }) {
   const t = useT();
   const styles = element.computedStyles;
-  const fontFamilyOptions = FONT_FAMILY_OPTIONS.map((option) => ({
+  const baseFontFamilyOptions = FONT_FAMILY_OPTIONS.map((option) => ({
     value: option.value,
     label: t(`editPanel.fontFamilies.${option.key}`),
   }));
+  const fontFamily = resolveFontFamilySelectValue(styles.fontFamily);
+  const fontFamilyOptions = FONT_FAMILY_OPTIONS.some(
+    (option) => option.value === fontFamily,
+  )
+    ? baseFontFamilyOptions
+    : [
+        {
+          value: fontFamily,
+          label: displayFontFamilyName(styles.fontFamily || fontFamily),
+        },
+        ...baseFontFamilyOptions,
+      ];
   const fontWeightOptions = FONT_WEIGHT_OPTIONS.map((option) => ({
     value: option.value,
     label: t(`editPanel.fontWeights.${option.key}`),
@@ -2463,7 +3174,7 @@ function TypographyProperties({
     !styles.width || styles.width === "auto" || styles.width === "max-content";
   const heightIsAuto = !styles.height || styles.height === "auto";
   const noWrap = styles.whiteSpace === "nowrap";
-  const resizeMode: "auto-width" | "auto-height" | "fixed" =
+  const resizeMode: TextResizeMode =
     widthIsAuto && noWrap
       ? "auto-width"
       : !heightIsAuto && !widthIsAuto
@@ -2471,7 +3182,7 @@ function TypographyProperties({
         : "auto-height";
   const currentWidth = styles.width && !widthIsAuto ? styles.width : "200px";
   const currentHeight = styles.height && !heightIsAuto ? styles.height : "48px";
-  const setResizeMode = (mode: "auto-width" | "auto-height" | "fixed") => {
+  const setResizeMode = (mode: TextResizeMode) => {
     if (mode === "auto-width") {
       onStyleChange("width", "auto");
       onStyleChange("height", "auto");
@@ -2521,51 +3232,36 @@ function TypographyProperties({
 
   return (
     <PanelSection title={t("editPanel.sections.typography")}>
-      {/* Row 0: text resizing (auto-width / auto-height / fixed) */}
-      <InspectorSegment>
-        <InspectorIconButton
-          label={"Auto width" /* i18n-ignore design text-resize mode */}
-          active={resizeMode === "auto-width"}
-          onClick={() => setResizeMode("auto-width")}
-        >
-          <IconArrowAutofitWidth className="size-3.5" />
-        </InspectorIconButton>
-        <InspectorIconButton
-          label={"Auto height" /* i18n-ignore design text-resize mode */}
-          active={resizeMode === "auto-height"}
-          onClick={() => setResizeMode("auto-height")}
-        >
-          <IconArrowAutofitHeight className="size-3.5" />
-        </InspectorIconButton>
-        <InspectorIconButton
-          label={"Fixed size" /* i18n-ignore design text-resize mode */}
-          active={resizeMode === "fixed"}
-          onClick={() => setResizeMode("fixed")}
+      {/* Row 1: font family full-width.
+          Wrapped in a height-constrained div so the SelectTrigger button's
+          hit-target is exactly h-6 (24 px) and cannot visually or physically
+          overlap the weight/size row below (bug: trigger extended ~12 px into
+          the next row, causing clicks meant for the size input to open this
+          dropdown instead). */}
+      <div className="h-6 overflow-hidden">
+        <Select
+          value={fontFamily}
+          onValueChange={(v) => onStyleChange("fontFamily", v)}
         >
-          <IconSquare className="size-3.5" />
-        </InspectorIconButton>
-      </InspectorSegment>
-
-      {/* Row 1: font family full-width */}
-      <Select
-        value={styles.fontFamily || "sans-serif"}
-        onValueChange={(v) => onStyleChange("fontFamily", v)}
-      >
-        <SelectTrigger className="h-6 w-full rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-[11px] shadow-none focus:ring-1 focus:ring-[var(--design-editor-accent-color)]">
-          <SelectValue />
-        </SelectTrigger>
-        <SelectContent>
-          {fontFamilyOptions.map((opt) => (
-            <SelectItem
-              key={opt.value}
-              value={opt.value}
-              className="text-[11px]"
-            >
-              {opt.label}
-            </SelectItem>
-          ))}
-        </SelectContent>
-      </Select>
+          <SelectTrigger
+            aria-label={t("editPanel.labels.font")}
+            className="h-6 w-full rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-[11px] shadow-none focus:ring-1 focus:ring-[var(--design-editor-accent-color)]"
+          >
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {fontFamilyOptions.map((opt) => (
+              <SelectItem
+                key={opt.value}
+                value={opt.value}
+                className="text-[11px]"
+              >
+                {opt.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
 
       {/* Row 2: weight + size side by side */}
       <div className="grid grid-cols-2 gap-1.5">
@@ -2639,7 +3335,7 @@ function TypographyProperties({
       </div>
 
       {/* Row 4: horizontal + vertical text alignment */}
-      <div className="grid grid-cols-2 gap-1.5">
+      <div className="flex items-center gap-1.5">
         <InspectorSegment>
           <InspectorIconButton
             label={t("editPanel.textAligns.left")}
@@ -2693,6 +3389,12 @@ function TypographyProperties({
             <IconLayoutAlignBottom className="size-3.5" />
           </InspectorIconButton>
         </InspectorSegment>
+        <div className="ml-auto shrink-0">
+          <TypographyDetailsPopover
+            resizeMode={resizeMode}
+            onResizeModeChange={setResizeMode}
+          />
+        </div>
       </div>
     </PanelSection>
   );
@@ -2703,10 +3405,15 @@ function FlexContainerControls({
   element,
   onStyleChange,
   onStylesChange,
+  onAutoLayoutConvert,
 }: {
   element: ElementInfo;
   onStyleChange: (property: string, value: string) => void;
   onStylesChange?: (styles: Record<string, string>) => void;
+  onAutoLayoutConvert?: (
+    targetNodeId: string,
+    opts?: { direction?: "row" | "column"; gap?: string },
+  ) => void;
 }) {
   const t = useT();
   const styles = element.computedStyles;
@@ -2719,12 +3426,55 @@ function FlexContainerControls({
   const isFlex = display.includes("flex");
   const flexDirection: AutoLayoutMatrixValue["direction"] =
     styles.flexDirection?.includes("column") ? "vertical" : "horizontal";
+  const mainGapAxis =
+    flexDirection === "horizontal" ? "horizontal" : "vertical";
   // When the element is in normal flow (not flex yet), picking any flow option
   // must first turn it into a flex container; otherwise setting flex-direction
   // alone is a no-op against a block element.
   const ensureFlex = () => {
     if (!isFlex) onStyleChange("display", "flex");
   };
+
+  /**
+   * Handle the Flow control switching between flex and normal-flow (block).
+   *
+   * For 'flex': ensures display:flex is set (ensureFlex path).
+   * For 'block': sets display:block and leaves children unchanged — mirrors
+   * the { kind:"autoLayout", enabled:false } substrate intent exactly.
+   */
+  const handleDisplayChange = (nextDisplay: "flex" | "block") => {
+    if (nextDisplay === "flex") {
+      ensureFlex();
+      return;
+    }
+    // Turn auto-layout off: set display:block, leaving children unchanged.
+    // This is the direct equivalent of the autoLayout substrate with enabled:false.
+    onStyleChange("display", "block");
+  };
+
+  /**
+   * "Convert to auto layout" — enables flex on a non-flex container and strips
+   * position:absolute from direct children (full reflow via the autoLayout
+   * substrate intent). Falls back to a style-only patch when no substrate
+   * handler is wired (e.g. read-only or non-editable contexts).
+   */
+  const handleConvertToAutoLayout = () => {
+    if (onAutoLayoutConvert && element.sourceId) {
+      onAutoLayoutConvert(element.sourceId, { direction: "row", gap: "8px" });
+      return;
+    }
+    // Fallback: set display:flex on the parent only (no child strip).
+    commitStylePatch(
+      {
+        display: "flex",
+        flexDirection: "row",
+        gap: "8px",
+        alignItems: "flex-start",
+      },
+      onStyleChange,
+      onStylesChange,
+    );
+  };
   const padding = {
     top: parseNumericValue(styles.paddingTop || "0"),
     right: parseNumericValue(styles.paddingRight || "0"),
@@ -2758,21 +3508,36 @@ function FlexContainerControls({
     },
     clipContent: styles.overflow === "hidden",
     resolvedSize: {
-      horizontal: element.boundingRect.width,
-      vertical: element.boundingRect.height,
+      horizontal: cssElementSize(element, "horizontal"),
+      vertical: cssElementSize(element, "vertical"),
     },
     // Forward the raw CSS display so the matrix can render the correct Flow
     // state (normal flow for block/grid, flex for flex/inline-flex). Added as an
     // optional contract field consumed by AutoLayoutMatrix; harmless when the
     // matrix ignores it.
     ...({ display } as Partial<AutoLayoutMatrixValue>),
+    spaceBetween: styles.justifyContent === "space-between",
   };
 
   return (
     <div className="space-y-2">
-      <AutoLayoutMatrix
-        value={autoLayoutValue}
-        onDirectionChange={(direction) => {
+      {/* Convert to auto layout — shown when the container is not yet flex */}
+      {!isFlex ? (
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-7 w-full gap-1.5 text-[11px]"
+          onClick={handleConvertToAutoLayout}
+        >
+          <IconLayoutSettings className="size-3.5 shrink-0" />
+          {"Convert to auto layout" /* i18n-ignore design inspector action */}
+        </Button>
+      ) : null}
+      <AutoLayoutMatrix
+        value={autoLayoutValue}
+        onDisplayChange={handleDisplayChange}
+        onDirectionChange={(direction) => {
           ensureFlex();
           onStyleChange(
             "flexDirection",
@@ -2823,16 +3588,20 @@ function FlexContainerControls({
           onStyleChange("overflow", clipContent ? "hidden" : "visible")
         }
         onDistribute={(axis) => {
-          const mainAxis =
-            autoLayoutValue.direction === "horizontal"
-              ? "horizontal"
-              : "vertical";
-          if (axis === mainAxis) {
+          if (axis === mainGapAxis) {
             onStyleChange("justifyContent", "space-between");
           } else if (autoLayoutValue.wrap === "wrap") {
             onStyleChange("alignContent", "space-between");
           }
         }}
+        onGapModeChange={(gapMode, axis) => {
+          if (axis !== mainGapAxis) return;
+          ensureFlex();
+          onStyleChange(
+            "justifyContent",
+            gapMode === "auto" ? "space-between" : "flex-start",
+          );
+        }}
         availableChildSizing={availableSizingForElement(element)}
         onChildSizingChange={(axis, sizing) => {
           commitElementSizing(
@@ -2843,6 +3612,9 @@ function FlexContainerControls({
             onStylesChange,
           );
         }}
+        onChildSizeChange={(axis, px) =>
+          onStyleChange(axis === "horizontal" ? "width" : "height", `${px}px`)
+        }
         onChildMinMaxChange={(axis, kind, val) =>
           commitElementMinMax(axis, kind, val, onStyleChange)
         }
@@ -2948,10 +3720,15 @@ function LayoutContextProperties({
   element,
   onStyleChange,
   onStylesChange,
+  onAutoLayoutConvert,
 }: {
   element: ElementInfo;
   onStyleChange: (property: string, value: string) => void;
   onStylesChange?: (styles: Record<string, string>) => void;
+  onAutoLayoutConvert?: (
+    targetNodeId: string,
+    opts?: { direction?: "row" | "column"; gap?: string },
+  ) => void;
 }) {
   const t = useT();
   const flexChild = isParentFlex(element);
@@ -2986,7 +3763,7 @@ function LayoutContextProperties({
             axis="W"
             sizingAxis="horizontal"
             value={inferElementSizing(element, "horizontal")}
-            resolvedSize={element.boundingRect.width}
+            resolvedSize={cssElementSize(element, "horizontal")}
             minMax={readElementMinMax(element, "horizontal")}
             options={availableSizing.horizontal ?? ["fixed"]}
             disabled={false}
@@ -2999,6 +3776,7 @@ function LayoutContextProperties({
                 onStylesChange,
               )
             }
+            onSizeChange={(px) => onStyleChange("width", `${px}px`)}
             onMinMaxChange={(axis, kind, val) =>
               commitElementMinMax(axis, kind, val, onStyleChange)
             }
@@ -3007,7 +3785,7 @@ function LayoutContextProperties({
             axis="H"
             sizingAxis="vertical"
             value={inferElementSizing(element, "vertical")}
-            resolvedSize={element.boundingRect.height}
+            resolvedSize={cssElementSize(element, "vertical")}
             minMax={readElementMinMax(element, "vertical")}
             options={availableSizing.vertical ?? ["fixed"]}
             disabled={false}
@@ -3020,6 +3798,7 @@ function LayoutContextProperties({
                 onStylesChange,
               )
             }
+            onSizeChange={(px) => onStyleChange("height", `${px}px`)}
             onMinMaxChange={(axis, kind, val) =>
               commitElementMinMax(axis, kind, val, onStyleChange)
             }
@@ -3042,6 +3821,7 @@ function LayoutContextProperties({
         element={element}
         onStyleChange={onStyleChange}
         onStylesChange={onStylesChange}
+        onAutoLayoutConvert={onAutoLayoutConvert}
       />
       {childControls}
     </PanelSection>
@@ -3372,6 +4152,8 @@ function PositionLayoutProperties({
         <div className="grid grid-cols-2 gap-2">
           <ScrubStyleInput
             label="X"
+            ariaLabel="X-position"
+            tooltipLabel="X-position"
             value={styles.left || ""}
             placeholder={element.boundingRect.x}
             inputClassName="h-6"
@@ -3379,6 +4161,8 @@ function PositionLayoutProperties({
           />
           <ScrubStyleInput
             label="Y"
+            ariaLabel="Y-position"
+            tooltipLabel="Y-position"
             value={styles.top || ""}
             placeholder={element.boundingRect.y}
             inputClassName="h-6"
@@ -3474,7 +4258,7 @@ function FillProperties({
     Record<string, string>
   >({});
   const stashKey = `${elementIdentityKey(element)}:${fillProperty}`;
-  const isHidden = fillValue === "transparent" || fillValue === "";
+  const isHidden = !colorHasVisibleAlpha(fillValue);
   const handleFillVisibilityToggle = () => {
     if (isHidden) {
       // Restore the stashed color, or fall back to a sensible default.
@@ -3629,8 +4413,17 @@ function FillProperties({
                 const opacity = gradient
                   ? averageGradientOpacity(gradient.stops)
                   : 100;
+                const layerStashKey = `${elementIdentityKey(element)}:layer:${index}`;
+                const stashedLayer = hiddenLayerStash[layerStashKey];
+                const hiddenImagePlaceholder = Boolean(
+                  stashedLayer && gradient && opacity <= 0,
+                );
                 const label = gradient
-                  ? `${gradientLabel(gradient.type)} ${index + 1}`
+                  ? hiddenImagePlaceholder
+                    ? `${"Image" /* i18n-ignore design inspector paint row */} ${
+                        index + 1
+                      }`
+                    : `${gradientLabel(gradient.type)} ${index + 1}`
                   : `${"Image" /* i18n-ignore design inspector paint row */} ${
                       index + 1
                     }`;
@@ -3728,10 +4521,6 @@ function FillProperties({
                           : t("editPanel.labels.hideLayer")
                       }
                       onClick={() => {
-                        if (!gradient) return;
-                        const layerStashKey = `${elementIdentityKey(
-                          element,
-                        )}:layer:${index}`;
                         if (opacity <= 0) {
                           // Show: restore the exact pre-hide layer if stashed,
                           // otherwise fall back to forcing every stop opaque.
@@ -3743,7 +4532,7 @@ function FillProperties({
                               delete next[layerStashKey];
                               return next;
                             });
-                          } else {
+                          } else if (gradient) {
                             replaceLayer(
                               buildGradientLayer(
                                 gradient.type,
@@ -3755,6 +4544,29 @@ function FillProperties({
                               ),
                             );
                           }
+                          return;
+                        }
+                        if (!gradient) {
+                          setHiddenLayerStash((prev) => ({
+                            ...prev,
+                            [layerStashKey]: layer,
+                          }));
+                          replaceLayer(
+                            buildGradientLayer("linear", [
+                              {
+                                id: "stop-0",
+                                color: "rgba(0, 0, 0, 0)",
+                                position: 0,
+                                opacity: 0,
+                              },
+                              {
+                                id: "stop-1",
+                                color: "rgba(0, 0, 0, 0)",
+                                position: 100,
+                                opacity: 0,
+                              },
+                            ]),
+                          );
                         } else {
                           // Hide: stash the current layer (with its real per-stop
                           // opacities) before zeroing every stop's alpha.
@@ -4357,6 +5169,580 @@ const TEXT_TAGS = new Set([
   "li",
 ]);
 
+// ─── Make it real — inline upgrade card (§3, §6.6) ──────────────────────────
+
+/**
+ * Payload shape returned by `connect-builder-app`.  Only the fields used by
+ * the card UI are typed here; the action may return additional fields.
+ */
+interface ConnectBuilderAppResult {
+  connected: boolean;
+  builderEnabled: boolean;
+  connectUrl: string;
+  appHost: string;
+  branchProjectId?: string;
+  cta: {
+    kind: "connect-builder" | "configure-project";
+    label: string;
+    description: string;
+    primaryAction: string;
+    connectUrl: string;
+  } | null;
+  message: string;
+}
+
+/**
+ * Inline "Make it real" upgrade card.
+ *
+ * Rendered wherever a real-app-only control is reached on an inline design
+ * (Component source jump, token write-back, live captures, etc.).  Queries
+ * `connect-builder-app` to determine the current connection state, then
+ * offers the appropriate CTA:
+ *
+ *   - Not connected → "Connect Builder.io" button (opens connectUrl)
+ *   - Connected, no project → "Open Builder settings" (configure project ID)
+ *   - Fully enabled → "Make it real" button (calls migrate-inline-design-to-app)
+ *
+ * The card is progressively disclosed: it only mounts when a gated control is
+ * actually reached, so it never appears for users who are already on a real-app
+ * source (`localhost` / `fusion`) or whose `sourceCapabilities` already include
+ * the needed capability.
+ *
+ * Matches the design-editor panel chrome: dashed-border, accent tint, small
+ * text at 10px — same idiom as the existing `ctaRequired` block in
+ * ComponentSection.
+ */
+function MakeItRealCard({
+  designId,
+  featureLabel,
+}: {
+  /** The active design id — required to call connect-builder-app. */
+  designId: string;
+  /**
+   * Short human-readable label for the gated feature (e.g. "token write-back",
+   * "component source jump", "live captures"). Shown in the card body so the
+   * user understands exactly what they're unlocking.
+   */
+  featureLabel: string;
+}) {
+  const { data, isLoading } = useActionQuery<ConnectBuilderAppResult>(
+    "connect-builder-app",
+    { designId },
+  );
+
+  const migrateMutation = useActionMutation("migrate-inline-design-to-app");
+
+  // While fetching status, show a muted placeholder that matches the card
+  // height so the inspector doesn't jump when the data arrives.
+  if (isLoading || !data) {
+    return (
+      <div className="rounded-md border border-dashed border-[var(--design-editor-accent-color)]/20 bg-[var(--design-editor-accent-color)]/3 px-2.5 py-2">
+        <div className="h-3 w-32 animate-pulse rounded bg-muted/40" />
+      </div>
+    );
+  }
+
+  // Determine which CTA to show.
+  const cta = data.cta;
+
+  // Already fully enabled — no CTA needed (caller should already have gated
+  // this component away, but guard here for safety).
+  if (!cta) return null;
+
+  const isPending = migrateMutation.isPending;
+  const migrateError = migrateMutation.error;
+
+  // "Make it real" primary action: open the connect URL or migrate.
+  const handlePrimary = () => {
+    if (cta.kind === "connect-builder") {
+      // Open the Builder OAuth connect flow in a new tab.  The user completes
+      // it there and comes back; the card will re-query on next render.
+      window.open(cta.connectUrl, "_blank", "noopener,noreferrer");
+      return;
+    }
+    if (cta.kind === "configure-project") {
+      window.open(cta.connectUrl, "_blank", "noopener,noreferrer");
+      return;
+    }
+  };
+
+  const handleMigrate = () => {
+    migrateMutation.mutate({ designId });
+  };
+
+  // Migration result — show branch link.
+  const migrateResult = migrateMutation.data as
+    | {
+        status: "processing";
+        branchName?: string;
+        url?: string;
+        message?: string;
+      }
+    | undefined;
+
+  if (migrateResult?.status === "processing" && migrateResult.url) {
+    return (
+      <div className="rounded-md border border-[var(--design-editor-accent-color)]/30 bg-[var(--design-editor-accent-color)]/8 px-2.5 py-2 space-y-1.5">
+        <p className="text-[10px] font-semibold text-[var(--design-editor-accent-color)]">
+          {"Builder is working on it" /* i18n-ignore make-it-real card */}
+        </p>
+        <p className="text-[10px] leading-snug text-muted-foreground">
+          {migrateResult.message ??
+            `Branch "${migrateResult.branchName}" is being generated.`}
+        </p>
+        <a
+          href={migrateResult.url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="inline-flex items-center gap-1 text-[10px] font-medium text-[var(--design-editor-accent-color)] hover:underline"
+        >
+          {"Open in Builder" /* i18n-ignore make-it-real card */}
+          <IconExternalLink className="size-2.5" />
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="rounded-md border border-dashed border-[var(--design-editor-accent-color)]/30 bg-[var(--design-editor-accent-color)]/5 px-2.5 py-2 space-y-1.5">
+      {/* Header */}
+      <p className="text-[10px] font-semibold text-foreground">
+        {"Make this a real app" /* i18n-ignore make-it-real card */}
+      </p>
+
+      {/* Body */}
+      <p className="text-[10px] leading-snug text-muted-foreground">
+        {cta.description}
+        {featureLabel ? (
+          <>
+            {" "}
+            <span className="italic">{featureLabel}</span>
+            {" requires a real-app source."}
+          </>
+        ) : null}
+      </p>
+
+      {/* Error */}
+      {migrateError ? (
+        <p className="text-[10px] text-destructive">
+          {migrateError instanceof Error
+            ? migrateError.message
+            : "Migration failed. Please try again."}
+        </p>
+      ) : null}
+
+      {/* Actions */}
+      <div className="flex items-center gap-1.5 flex-wrap">
+        <button
+          type="button"
+          onClick={handlePrimary}
+          className="inline-flex items-center gap-1 rounded px-2 py-1 text-[10px] font-medium bg-[var(--design-editor-accent-color)] text-white hover:opacity-90 transition-opacity"
+        >
+          {cta.primaryAction}
+          <IconArrowRight className="size-2.5" />
+        </button>
+
+        {/* When Builder is fully connected, also offer direct migration */}
+        {data.connected && data.builderEnabled && (
+          <button
+            type="button"
+            onClick={handleMigrate}
+            disabled={isPending}
+            className="inline-flex items-center gap-1 rounded border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-2 py-1 text-[10px] font-medium text-muted-foreground hover:text-foreground transition-colors disabled:cursor-wait disabled:opacity-60"
+          >
+            {isPending ? (
+              <>
+                <IconLoader2 className="size-2.5 animate-spin" />
+                {"Migrating…" /* i18n-ignore make-it-real card */}
+              </>
+            ) : (
+              <>{"Generate React app" /* i18n-ignore make-it-real card */}</>
+            )}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ─── Component section (§6.1) ─────────────────────────────────────────────────
+
+/**
+ * Shape returned by `get-component-details`.  Only the fields the UI needs are
+ * typed here; the action may return additional fields.
+ */
+interface ComponentDetailsResult {
+  name: string;
+  sourceType: string;
+  observedProps: Array<{ name: string; value: string }>;
+  persistedVariants: Record<string, string[]>;
+  sourceLocation?: { filePath: string; exportName?: string } | null;
+  /** Component instance shape, including the Alpine `x-data` expression. */
+  instance?: {
+    alpineData?: string | null;
+    nodeId?: string;
+    selector?: string;
+  } | null;
+  capabilities: {
+    canResolveToFile: boolean;
+    hasFullIndex: boolean;
+    canEditProps: boolean;
+    ctaRequired: boolean;
+    ctaMessage?: string;
+  };
+}
+
+/**
+ * Contextual COMPONENT section rendered inside the Design tab when the
+ * selected element is a component instance (carries
+ * `data-agent-native-component`).
+ *
+ * Shows: component name, source path (when capability available), observed
+ * prop values, variant/size/state controls from `get-component-details`, and
+ * an "Edit component source" action.  Real-app features are gated by the
+ * capabilities returned by the action; Alpine gets a lightweight read-only
+ * view plus a Connect-Builder CTA.
+ *
+ * Matches the workbench artboard spec in DESIGN-STUDIO-PLAN.md §6.1.
+ */
+function ComponentSection({
+  designId,
+  nodeId,
+  sourceCapabilities = [],
+}: {
+  designId: string;
+  nodeId: string;
+  /** Capability names advertised by the current source. */
+  sourceCapabilities?: string[];
+}) {
+  const queryClient = useQueryClient();
+  const detailsKey = ["action", "get-component-details", { designId, nodeId }];
+
+  const { data, isLoading, error } = useActionQuery<ComponentDetailsResult>(
+    "get-component-details",
+    { designId, nodeId },
+  );
+
+  const openSourceMutation = useActionMutation("open-component-source");
+  const applyPropMutation = useActionMutation("apply-component-prop-edit");
+
+  // Persist a single prop change through apply-component-prop-edit. The canvas
+  // re-renders from the freshly written design content (get-design refetch),
+  // so no postMessage into the iframe is needed. The get-component-details
+  // cache is optimistically patched so the control reflects the new value
+  // immediately, then reconciled with the server on settle.
+  const persistPropEdit = (
+    edit:
+      | { kind: "alpineData"; value: string }
+      | { kind: "attribute"; attribute: string; value: string },
+    optimistic: (prev: ComponentDetailsResult) => ComponentDetailsResult,
+  ) => {
+    queryClient.setQueryData<ComponentDetailsResult>(detailsKey, (prev) =>
+      prev ? optimistic(prev) : prev,
+    );
+    applyPropMutation.mutate(
+      { designId, nodeId, edit },
+      {
+        onSettled: () => {
+          // Re-render the canvas from the new content and re-read the props.
+          void queryClient.invalidateQueries({
+            queryKey: ["action", "get-design"],
+          });
+          void queryClient.invalidateQueries({ queryKey: detailsKey });
+        },
+      },
+    );
+  };
+
+  // While loading, show a compact skeleton that matches the section width.
+  if (isLoading) {
+    return (
+      <section className="shrink-0 border-t border-[var(--design-editor-control-border)] first:border-t-0">
+        <div className="flex min-h-9 items-center gap-2 px-3">
+          <div className="h-3 w-24 animate-pulse rounded bg-muted/50" />
+        </div>
+        <div className="space-y-1.5 px-3 pb-3 pt-0.5">
+          <div className="h-5 w-full animate-pulse rounded bg-muted/40" />
+          <div className="h-5 w-3/4 animate-pulse rounded bg-muted/40" />
+        </div>
+      </section>
+    );
+  }
+
+  // Hard error (node not found, no access, etc.) — collapse silently so
+  // the rest of the inspector is not disrupted.
+  if (error || !data) return null;
+
+  const {
+    name,
+    sourceType,
+    sourceLocation,
+    observedProps,
+    persistedVariants,
+    instance,
+    capabilities,
+  } = data;
+
+  // ── Editable prop model ───────────────────────────────────────────────────
+  // Inline/Alpine designs persist through apply-component-prop-edit. Two write
+  // surfaces:
+  //   • x-data keys      → kind "alpineData" (rewrites the whole object)
+  //   • data-prop-* attrs → kind "attribute"  (data-agent-native-prop-<kebab>)
+  // Real-app sources keep the deeper source-prop controls gated as-is, so for
+  // non-inline sources the controls are read-only here.
+  const isInline = sourceType === "inline";
+  const editingEnabled = isInline; // gated; real-app stays read-only for now
+  const alpineData = parseAlpineDataObject(instance?.alpineData);
+
+  // Each editable row: name + current value + how it persists + its options.
+  type PropRow = {
+    name: string;
+    value: string;
+    /** Variant/enum options when the prop is a known group. */
+    options?: string[];
+    /** Persist surface for this prop. */
+    surface: "alpineData" | "attribute";
+  };
+
+  const rows: PropRow[] = [];
+  const seen = new Set<string>();
+
+  // 1) Alpine x-data keys come first — they drive the live variant/state.
+  if (alpineData) {
+    for (const [key, value] of Object.entries(alpineData)) {
+      rows.push({
+        name: key,
+        value,
+        options: persistedVariants[key],
+        surface: "alpineData",
+      });
+      seen.add(key);
+    }
+  }
+
+  // 2) data-agent-native-prop-* attributes not already covered by x-data.
+  for (const prop of observedProps) {
+    if (seen.has(prop.name)) continue;
+    rows.push({
+      name: prop.name,
+      value: prop.value,
+      options: persistedVariants[prop.name],
+      surface: "attribute",
+    });
+    seen.add(prop.name);
+  }
+
+  // 3) persistedVariant groups with no observed value yet (default to first).
+  for (const [group, options] of Object.entries(persistedVariants)) {
+    if (seen.has(group)) continue;
+    rows.push({
+      name: group,
+      value: options[0] ?? "",
+      options,
+      surface: alpineData ? "alpineData" : "attribute",
+    });
+    seen.add(group);
+  }
+
+  const hasRows = rows.length > 0;
+
+  // Build the apply-component-prop-edit payload + optimistic cache patch for a
+  // single prop change.
+  const commitProp = (row: PropRow, nextValue: string) => {
+    if (!editingEnabled || nextValue === row.value) return;
+
+    if (row.surface === "alpineData") {
+      const nextData = { ...(alpineData ?? {}), [row.name]: nextValue };
+      const serialized = serializeAlpineDataObject(nextData);
+      persistPropEdit({ kind: "alpineData", value: serialized }, (prev) => ({
+        ...prev,
+        instance: { ...(prev.instance ?? {}), alpineData: serialized },
+        observedProps: prev.observedProps.map((p) =>
+          p.name === row.name ? { ...p, value: nextValue } : p,
+        ),
+      }));
+    } else {
+      // camelCase prop name → data-agent-native-prop-<kebab>
+      const kebab = row.name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+      persistPropEdit(
+        {
+          kind: "attribute",
+          attribute: `data-agent-native-prop-${kebab}`,
+          value: nextValue,
+        },
+        (prev) => {
+          const exists = prev.observedProps.some((p) => p.name === row.name);
+          return {
+            ...prev,
+            observedProps: exists
+              ? prev.observedProps.map((p) =>
+                  p.name === row.name ? { ...p, value: nextValue } : p,
+                )
+              : [...prev.observedProps, { name: row.name, value: nextValue }],
+          };
+        },
+      );
+    }
+  };
+
+  // ── Capability gates ──
+  const canJumpToSource =
+    capabilities.canResolveToFile &&
+    Boolean(sourceLocation?.filePath) &&
+    sourceCapabilities.includes("resolveNodeToFile");
+
+  // ── Source chip text ──
+  const sourceChip = sourceLocation?.exportName
+    ? `${sourceLocation.exportName} — ${sourceLocation.filePath}`
+    : (sourceLocation?.filePath ?? null);
+
+  return (
+    <section
+      className="shrink-0 border-t border-[var(--design-editor-control-border)] first:border-t-0"
+      data-testid="component-section"
+    >
+      {/* ── Section header ── */}
+      <div className="flex min-h-9 items-center gap-2 px-3">
+        {/* Accent diamond matching the workbench artboard component rows */}
+        <span
+          className="size-2 shrink-0 rotate-45 rounded-[2px] bg-[var(--design-editor-accent-color)]"
+          aria-hidden="true"
+        />
+        <h3 className="min-w-0 flex-1 truncate text-[11px] font-semibold text-foreground">
+          {name}
+        </h3>
+        {/* Jump-to-source action */}
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="size-6 rounded-md text-muted-foreground hover:text-foreground disabled:cursor-not-allowed disabled:opacity-40"
+              disabled={!canJumpToSource}
+              aria-label={
+                "Edit component source" /* i18n-ignore design inspector action */
+              }
+              onClick={() => {
+                openSourceMutation.mutate({ designId, nodeId });
+              }}
+            >
+              <IconExternalLink className="size-3.5" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent>
+            {
+              canJumpToSource
+                ? "Edit component source" /* i18n-ignore design inspector action */
+                : (capabilities.ctaMessage ??
+                  "Connect Builder to jump to component source") /* i18n-ignore design inspector tooltip */
+            }
+          </TooltipContent>
+        </Tooltip>
+      </div>
+
+      {/* ── Body ── */}
+      <div className="space-y-1.5 px-3 pb-3 pt-0.5 text-[11px]">
+        {/* Source path chip */}
+        {sourceChip && (
+          <div
+            className="flex items-center gap-1 rounded bg-[var(--design-editor-control-bg)] px-2 py-1"
+            title={sourceChip}
+          >
+            <IconCode className="size-3 shrink-0 text-muted-foreground/60" />
+            <span className="min-w-0 flex-1 truncate font-mono text-[10px] text-muted-foreground">
+              {sourceChip}
+            </span>
+          </div>
+        )}
+
+        {/* Typed prop controls. Inline/Alpine designs are editable and persist
+            through apply-component-prop-edit; real-app sources are read-only
+            until the deeper source-prop controls land. */}
+        {hasRows && (
+          <div className="space-y-1">
+            <p className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/70">
+              {"Props" /* i18n-ignore design inspector label */}
+            </p>
+            {rows.map((row) => {
+              const hasOptions = (row.options?.length ?? 0) > 0;
+              const isBoolean = !hasOptions && isBooleanPropValue(row.value);
+              return (
+                <div key={row.name} className="flex items-center gap-1.5">
+                  <Label className="w-[64px] shrink-0 truncate text-[11px] font-medium capitalize text-muted-foreground">
+                    {row.name}
+                  </Label>
+                  {hasOptions ? (
+                    // Dropdown for variant / enum groups.
+                    <Select
+                      value={row.value || row.options![0] || ""}
+                      onValueChange={(v) => commitProp(row, v)}
+                      disabled={!editingEnabled}
+                    >
+                      <SelectTrigger className="h-6 min-w-0 flex-1 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-[11px] shadow-none focus:ring-1 focus:ring-[var(--design-editor-accent-color)]">
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {row.options!.map((opt) => (
+                          <SelectItem
+                            key={opt}
+                            value={opt}
+                            className="text-[11px]"
+                          >
+                            {opt}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  ) : isBoolean ? (
+                    // Toggle for boolean props.
+                    <div className="flex min-w-0 flex-1 items-center">
+                      <Switch
+                        checked={row.value.trim().toLowerCase() === "true"}
+                        onCheckedChange={(checked) =>
+                          commitProp(row, checked ? "true" : "false")
+                        }
+                        disabled={!editingEnabled}
+                        className="h-4 w-7 [&>span]:size-3 [&>span]:data-[state=checked]:translate-x-3"
+                        aria-label={
+                          row.name /* i18n-ignore dynamic prop name */
+                        }
+                      />
+                    </div>
+                  ) : (
+                    // Text input for string props (e.g. a label).
+                    <Input
+                      defaultValue={row.value}
+                      key={`${row.name}:${row.value}`}
+                      disabled={!editingEnabled}
+                      onBlur={(e) => commitProp(row, e.target.value)}
+                      onKeyDown={(e) => {
+                        if (e.key === "Enter") {
+                          e.preventDefault();
+                          e.currentTarget.blur();
+                        }
+                      }}
+                      className="h-6 min-w-0 flex-1 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-[11px] shadow-none focus-visible:ring-1 focus-visible:ring-[var(--design-editor-accent-color)]"
+                    />
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        )}
+
+        {/* Connect-Builder CTA (inline, only when real-app features are gated) */}
+        {capabilities.ctaRequired && (
+          <MakeItRealCard
+            designId={designId}
+            featureLabel="component source jump and full prop controls"
+          />
+        )}
+      </div>
+    </section>
+  );
+}
+
 export function EditPanel({
   selectedElement,
   pageStyles = {},
@@ -4371,14 +5757,35 @@ export function EditPanel({
   onRequestTweaks,
   onStyleChange,
   onStylesChange,
+  onAutoLayoutConvert,
   onExport,
   exporting = false,
+  readOnly = false,
+  fileId,
+  filename,
+  designId,
+  onTokensApplied,
+  statesPanelProps,
+  reviewPanelProps,
+  componentNodeId,
+  sourceCapabilities = [],
+  onCreateComponent,
+  defaultComponentName = "Component",
+  inspectCode,
 }: EditPanelProps) {
   const t = useT();
+  const [createComponentOpen, setCreateComponentOpen] = useState(false);
   const [exportSettings, setExportSettings] = useState<ExportSettingsValue>(
     DEFAULT_EXPORT_SETTINGS,
   );
   const [showExportPreview, setShowExportPreview] = useState(false);
+  // Sub-tab within the Tweaks area: "tokens" (TokensPanel face) or "tweaks"
+  // (raw TweakDefinition controls). Always default to the existing "tweaks"
+  // controls so opening Tweaks lands on the user's TweakDefinition controls
+  // (and the + affordance) rather than auto-firing token indexing. "Tokens"
+  // remains available as a sub-tab the user can click when designId is set.
+  const [tweaksSubTab, setTweaksSubTab] = useState<TweaksSubTab>("tweaks");
+
   const selectedElementKey = selectedElement
     ? elementIdentityKey(selectedElement)
     : "none";
@@ -4395,12 +5802,66 @@ export function EditPanel({
     },
     [onTweakChange],
   );
+  // The "Add Tweaks" (+) flow lives only on the "tweaks" sub-tab. Switch to it
+  // before opening the prompt so the + button and the newly added control are
+  // visible (avoids leaving the user on the Tokens sub-tab where + isn't shown).
+  const handleRequestTweaks = useCallback(
+    (anchor: HTMLElement) => {
+      setTweaksSubTab("tweaks");
+      onRequestTweaks?.(anchor);
+    },
+    [onRequestTweaks],
+  );
 
   useEffect(() => {
     setExportSettings(DEFAULT_EXPORT_SETTINGS);
     setShowExportPreview(false);
   }, [selectedElementKey]);
 
+  // Scroll guard: suppress the click that fires immediately after a scroll
+  // gesture ends (rubber-band or normal scroll). Using onScroll instead of
+  // onPointerDown avoids side-effects like Radix DismissableLayer detecting a
+  // "pointerdown outside" and closing open popovers — which, during an
+  // over-scroll bounce, could briefly un-shield the canvas and allow a stray
+  // pointer event to deselect the selected canvas element (R3 regression).
+  const scrolledRecentlyRef = useRef(false);
+  const scrollTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  if (readOnly) {
+    return (
+      <div
+        className={cn(
+          "shrink-0 bg-[var(--design-editor-panel-bg)]",
+          "flex h-full min-h-0 flex-col overflow-hidden",
+        )}
+        style={{ width }}
+      >
+        <div className="flex min-h-8 shrink-0 items-center border-b border-border/90 px-3">
+          <h2 className="min-w-0 truncate text-[12px] font-semibold text-foreground">
+            {t("editPanel.properties")}
+          </h2>
+        </div>
+        <div className="flex min-h-0 flex-1 items-center justify-center px-5">
+          <div
+            className="max-w-[188px] text-center"
+            aria-live="polite"
+            aria-busy="true"
+          >
+            <div className="mx-auto mb-3 flex size-9 items-center justify-center rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] text-muted-foreground/60">
+              <IconLock className="size-4" aria-hidden="true" />
+            </div>
+            <h3 className="text-[12px] font-semibold leading-snug text-foreground">
+              {t("designEditor.inspectorLockedTitle")}
+            </h3>
+            <p className="mt-1.5 text-[11px] leading-snug text-muted-foreground/70">
+              {t("designEditor.inspectorLockedDescription")}
+            </p>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       className={cn(
@@ -4417,13 +5878,109 @@ export function EditPanel({
 
       {activeTab === "design" ? (
         <>
-          <SelectionHeader element={selectedElement} />
+          <SelectionHeader
+            element={selectedElement}
+            onCreateComponent={
+              onCreateComponent && selectedElement
+                ? () => setCreateComponentOpen(true)
+                : undefined
+            }
+            inspectCodePopover={
+              inspectCode && selectedElement
+                ? (trigger) => (
+                    <InspectCodePopover trigger={trigger} data={inspectCode} />
+                  )
+                : undefined
+            }
+          />
+          {onCreateComponent && (
+            <CreateComponentDialog
+              open={createComponentOpen}
+              onOpenChange={setCreateComponentOpen}
+              defaultName={defaultComponentName}
+              onSubmit={onCreateComponent}
+            />
+          )}
+
+          <div
+            className="design-inspector-scroll min-h-0 flex-1 overflow-y-auto overscroll-contain"
+            onScroll={() => {
+              // Mark that a scroll just happened so the click that some
+              // browsers fire at the end of a scroll gesture (or after an
+              // overscroll/rubber-band bounce) is suppressed. Crucially this
+              // runs on the scroll event — NOT on pointerdown — so it never
+              // triggers Radix's DismissableLayer "outside pointerdown"
+              // detection, which would close open inspector popovers and, once
+              // the shield is removed, allow a stray canvas pointer event to
+              // deselect the selected element (the R3 overscroll regression).
+              scrolledRecentlyRef.current = true;
+              if (scrollTimerRef.current !== null) {
+                clearTimeout(scrollTimerRef.current);
+              }
+              scrollTimerRef.current = setTimeout(() => {
+                scrolledRecentlyRef.current = false;
+                scrollTimerRef.current = null;
+              }, 300);
+            }}
+            onClickCapture={(e) => {
+              // Suppress spurious clicks (e.g. color-picker opening) that
+              // fire immediately after a scroll gesture ends. The 300ms
+              // window from the last scroll event covers both the synchronous
+              // scroll-end click and the delayed synthetic click that mobile
+              // browsers generate after a touch-scroll ends.
+              if (!scrolledRecentlyRef.current) return;
+              scrolledRecentlyRef.current = false;
+              if (scrollTimerRef.current !== null) {
+                clearTimeout(scrollTimerRef.current);
+                scrollTimerRef.current = null;
+              }
+              e.stopPropagation();
+              e.preventDefault();
+            }}
+            onKeyDown={(e) => {
+              // Trap Tab within the inspector panel so it never focuses the
+              // canvas iframe. When the canvas iframe gains focus it forwards
+              // a synthetic Tab keydown to the parent window, which is picked
+              // up by the design-editor hotkey handler as "cycle file" and
+              // causes apparent deselection / overview-mode switch (bug: Tab
+              // in a numeric field deselected the canvas element).
+              if (e.key !== "Tab") return;
+              const panel = e.currentTarget;
+              const focusable = Array.from(
+                panel.querySelectorAll<HTMLElement>(
+                  'input, button, select, textarea, [tabindex]:not([tabindex="-1"])',
+                ),
+              ).filter(
+                (el) =>
+                  !el.hasAttribute("disabled") &&
+                  el.tabIndex !== -1 &&
+                  !el.closest('[aria-hidden="true"]'),
+              );
+              if (focusable.length === 0) return;
+              e.preventDefault();
+              const current = document.activeElement as HTMLElement | null;
+              const idx = current ? focusable.indexOf(current) : -1;
+              const next = e.shiftKey
+                ? focusable[(idx - 1 + focusable.length) % focusable.length]
+                : focusable[(idx + 1) % focusable.length];
+              next?.focus();
+            }}
+          >
+            {/* §6.1 Component section — shown at the top when a component
+                instance is selected. Requires designId + componentNodeId. */}
+            {designId && componentNodeId && (
+              <ComponentSection
+                designId={designId}
+                nodeId={componentNodeId}
+                sourceCapabilities={sourceCapabilities}
+              />
+            )}
 
-          <div className="design-inspector-scroll min-h-0 flex-1 overflow-y-auto overscroll-contain">
             {!selectedElement && (
               <PageProperties
                 styles={pageStyles}
                 onStyleChange={onStyleChange}
+                onStylesChange={onStylesChange}
               />
             )}
 
@@ -4437,6 +5994,7 @@ export function EditPanel({
                   element={selectedElement}
                   onStyleChange={onStyleChange}
                   onStylesChange={onStylesChange}
+                  onAutoLayoutConvert={onAutoLayoutConvert}
                 />
                 <AppearanceProperties
                   element={selectedElement}
@@ -4473,6 +6031,17 @@ export function EditPanel({
                     onStyleChange={onStyleChange}
                   />
                 ) : null}
+                {/* AI edit request block — collapsible, collapsed by default */}
+                <section className="shrink-0 border-t border-[var(--design-editor-control-border)]">
+                  <InspectorAiActions
+                    selector={selectedElement.selector}
+                    sourceId={selectedElement.sourceId}
+                    designId={designId}
+                    fileId={fileId}
+                    filename={filename}
+                    canEdit={!readOnly}
+                  />
+                </section>
               </>
             )}
             {onExport ? (
@@ -4507,40 +6076,212 @@ export function EditPanel({
                 ) : null}
               </PanelSection>
             ) : null}
+
+            {/* §6.4 States & Responsive — contextual section in Design tab.
+                Collapsed by default so existing Design content is not buried.
+                Only mounts when designId is provided so there is something to
+                load; without it the panel would fire an action with no id. */}
+            {designId && statesPanelProps ? (
+              <PanelSection
+                title={"States" /* i18n-ignore design inspector section */}
+                defaultCollapsed
+                actions={
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        className="size-6 rounded-md text-muted-foreground hover:text-foreground"
+                        aria-label={
+                          "Breakpoints & states" /* i18n-ignore design inspector action */
+                        }
+                      >
+                        <IconDeviceDesktop className="size-3.5" />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>
+                      {
+                        "Breakpoints & states" /* i18n-ignore design inspector action */
+                      }
+                    </TooltipContent>
+                  </Tooltip>
+                }
+              >
+                <StatesPanel designId={designId} {...statesPanelProps} />
+                {/* §6.4 / §6.6 — live captures (real running-app data, route
+                    props, API responses) are a real-app capability. When
+                    canCapture is false (inline source) surface a compact
+                    "Make it real" CTA so the user knows it's one step away. */}
+                {!statesPanelProps.canCapture && (
+                  <MakeItRealCard
+                    designId={designId}
+                    featureLabel="live data captures and real-app states"
+                  />
+                )}
+              </PanelSection>
+            ) : null}
+
+            {/* §6.5 Review — contextual section in Design tab.
+                Collapsed by default. Renders when reviewPanelProps is provided,
+                no designId check needed since ReviewPanel is statically fed. */}
+            {reviewPanelProps ? (
+              <PanelSection
+                title={"Review" /* i18n-ignore design inspector section */}
+                defaultCollapsed
+                actions={
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        className="size-6 rounded-md text-muted-foreground hover:text-foreground"
+                        aria-label={
+                          "Accessibility & visual diff" /* i18n-ignore design inspector action */
+                        }
+                      >
+                        <IconShieldCheck className="size-3.5" />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>
+                      {
+                        "Accessibility & visual diff" /* i18n-ignore design inspector action */
+                      }
+                    </TooltipContent>
+                  </Tooltip>
+                }
+              >
+                {/* ReviewPanel manages its own scroll; no extra wrapper needed. */}
+                <ReviewPanel {...reviewPanelProps} />
+              </PanelSection>
+            ) : null}
           </div>
         </>
       ) : activeTab === "tweaks" ? (
         <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
-          <div className="flex h-10 shrink-0 items-center justify-between gap-2 border-b border-border/90 px-3">
-            <h3 className="min-w-0 flex-1 truncate text-[13px] font-semibold text-foreground">
-              {t("designEditor.tweaks")}
-            </h3>
-            {onRequestTweaks ? (
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    size="icon"
-                    className="size-7 rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
-                    aria-label={t("designEditor.addTweaks")}
-                    onClick={(event) => onRequestTweaks(event.currentTarget)}
-                  >
-                    <IconPlus className="size-3.5" />
-                  </Button>
-                </TooltipTrigger>
-                <TooltipContent>{t("designEditor.addTweaks")}</TooltipContent>
-              </Tooltip>
-            ) : null}
-          </div>
+          {/* Tweaks tab header: when designId is present show a Tokens | Tweaks
+              sub-tab switcher so the TokensPanel is the first-class face of
+              this area per §6.2. When there is no designId only the raw tweaks
+              title is shown (original behaviour). */}
+          {designId ? (
+            <div className="flex h-9 shrink-0 items-center gap-0.5 border-b border-border/90 px-2">
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                className={cn(
+                  "h-6 rounded-md px-2 text-[11px] font-semibold text-muted-foreground transition-colors hover:text-foreground",
+                  tweaksSubTab === "tokens" &&
+                    "bg-[var(--design-editor-panel-raised-bg)] text-foreground",
+                )}
+                onClick={() => setTweaksSubTab("tokens")}
+              >
+                <IconPalette className="mr-1 size-3" />
+                {"Tokens" /* i18n-ignore design inspector sub-tab */}
+              </Button>
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                className={cn(
+                  "h-6 rounded-md px-2 text-[11px] font-semibold text-muted-foreground transition-colors hover:text-foreground",
+                  tweaksSubTab === "tweaks" &&
+                    "bg-[var(--design-editor-panel-raised-bg)] text-foreground",
+                )}
+                onClick={() => setTweaksSubTab("tweaks")}
+              >
+                {t("designEditor.tweaks")}
+              </Button>
+            </div>
+          ) : (
+            <div className="flex h-10 shrink-0 items-center justify-between gap-2 border-b border-border/90 px-3">
+              <h3 className="min-w-0 flex-1 truncate text-[13px] font-semibold text-foreground">
+                {t("designEditor.tweaks")}
+              </h3>
+              {onRequestTweaks ? (
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="icon"
+                      className="size-7 rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+                      aria-label={t("designEditor.addTweaks")}
+                      onClick={(event) =>
+                        handleRequestTweaks(event.currentTarget)
+                      }
+                    >
+                      <IconPlus className="size-3.5" />
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent>{t("designEditor.addTweaks")}</TooltipContent>
+                </Tooltip>
+              ) : null}
+            </div>
+          )}
+
           <div className="design-inspector-scroll min-h-0 flex-1 overflow-y-auto overscroll-contain">
-            <TweaksPanelContent
-              tweaks={tweaks}
-              values={tweakValues}
-              onChange={handleTweakChange}
-              onRequestTweaks={onRequestTweaks}
-              className="px-3 py-3"
-            />
+            {designId && tweaksSubTab === "tokens" ? (
+              /* §6.2 Tokens face — first-class view of the Tweaks area.
+                 TokensPanel calls apply-design-token-edit which routes through
+                 the Tweaks loop (designs.data.tweakSelections persist). */
+              <>
+                <TokensPanel
+                  designId={designId}
+                  onTokensApplied={onTokensApplied}
+                />
+                {/* §5 / §6.6 — token write-back to source is a real-app
+                    capability. On inline sources (sourceCapabilities lacks
+                    "writeFile") show a compact "Make it real" CTA after the
+                    token list so the user knows write-back is one step away. */}
+                {!sourceCapabilities.includes("writeFile") && (
+                  <div className="px-3 pb-3 pt-1">
+                    <MakeItRealCard
+                      designId={designId}
+                      featureLabel="token write-back to source files"
+                    />
+                  </div>
+                )}
+              </>
+            ) : (
+              /* Raw TweakDefinition controls — shown when no designId, or when
+                 the user switches to the Tweaks sub-tab. */
+              <>
+                {designId && onRequestTweaks ? (
+                  /* When in sub-tab mode, show the add-tweaks action in the
+                     scrollable content area above the raw controls. */
+                  <div className="flex items-center justify-end px-3 pt-2">
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <Button
+                          type="button"
+                          variant="ghost"
+                          size="icon"
+                          className="size-7 rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+                          aria-label={t("designEditor.addTweaks")}
+                          onClick={(event) =>
+                            handleRequestTweaks(event.currentTarget)
+                          }
+                        >
+                          <IconPlus className="size-3.5" />
+                        </Button>
+                      </TooltipTrigger>
+                      <TooltipContent>
+                        {t("designEditor.addTweaks")}
+                      </TooltipContent>
+                    </Tooltip>
+                  </div>
+                ) : null}
+                <TweaksPanelContent
+                  tweaks={tweaks}
+                  values={tweakValues}
+                  onChange={handleTweakChange}
+                  onRequestTweaks={!designId ? handleRequestTweaks : undefined}
+                  className="px-3 py-3"
+                />
+              </>
+            )}
           </div>
         </div>
       ) : extensionContext ? (