@hienlh/ppm 0.22.10 → 0.23.0

package/src/web/components/design/history/design-history-panel.tsx

@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useState } from "react";
+import { toast } from "sonner";
+import { History, Loader2, RotateCcw, X } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { formatRelativeDate } from "@/lib/format-date";
+import { formatSize } from "@/components/os-explorer/format-file-meta";
+import { listDesignHistory, restoreDesignSnapshot } from "@/lib/design/api-designs";
+import { DesignResponsiveDialog } from "../dialogs/design-responsive-dialog";
+import { useDesignTab } from "../design-tab-context";
+import type { DesignSnapshotInfo, DesignSnapshotReason } from "../../../../shared/design-types";
+
+/**
+ * The design's snapshot history, newest first, with restore.
+ *
+ * Refreshed by `design:history_changed`, never by file events: `.design/` is deliberately
+ * not watched. Restore replaces the working files, so it is confirmed first and refused
+ * while the design's chat is mid-turn — the agent would keep writing over the restored copy.
+ * The server snapshots the current state before restoring, so a restore is itself undoable
+ * from this list.
+ */
+
+const REASON_LABEL: Record<DesignSnapshotReason, string> = {
+  turn: "After an AI turn",
+  "pre-restore": "Before a restore",
+  "before-edit": "Before a canvas edit",
+  manual: "Saved",
+};
+
+export function DesignHistoryPanel({ onClose, onRestored }: { onClose: () => void; onRestored: () => void }) {
+  const { projectName, slug, isStreaming } = useDesignTab();
+  const [items, setItems] = useState<DesignSnapshotInfo[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [confirm, setConfirm] = useState<DesignSnapshotInfo | null>(null);
+  const [restoring, setRestoring] = useState(false);
+
+  const load = useCallback(() => {
+    listDesignHistory(projectName, slug)
+      .then((list) => { setItems(list); setError(null); })
+      .catch((e) => setError((e as Error).message || "Could not load the history"));
+  }, [projectName, slug]);
+
+  useEffect(() => {
+    load();
+    const onChanged = (e: Event) => {
+      const d = (e as CustomEvent<{ projectName?: string; slug?: string }>).detail;
+      if (d?.projectName === projectName && d.slug === slug) load();
+    };
+    window.addEventListener("design:history_changed", onChanged);
+    return () => window.removeEventListener("design:history_changed", onChanged);
+  }, [load, projectName, slug]);
+
+  const restore = useCallback(async () => {
+    if (!confirm) return;
+    setRestoring(true);
+    try {
+      await restoreDesignSnapshot(projectName, slug, confirm.id);
+      toast.success("Version restored", { description: "The previous state was saved to the history first." });
+      setConfirm(null);
+      onRestored();
+    } catch (e) {
+      toast.error("Could not restore this version", { description: (e as Error).message });
+    } finally {
+      setRestoring(false);
+    }
+  }, [confirm, projectName, slug, onRestored]);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-panel">
+      <div className="flex h-9 shrink-0 items-center gap-2 border-b border-border px-2">
+        <History className="size-4 text-text-subtle" />
+        <span className="flex-1 text-xs font-semibold">Version history</span>
+        <button type="button" onClick={onClose} aria-label="Close history"
+          className="flex size-11 items-center justify-center rounded-md text-text-subtle hover:bg-surface-elevated md:size-7">
+          <X className="size-4" />
+        </button>
+      </div>
+      {isStreaming && (
+        <p className="border-b border-border px-3 py-2 text-xs text-text-subtle">Restoring is paused while the AI is working on this design.</p>
+      )}
+      <div className="min-h-0 flex-1 overflow-y-auto p-1">
+        {error ? (
+          <div className="p-3 text-xs text-destructive">
+            {error} <button type="button" className="text-primary underline" onClick={load}>Retry</button>
+          </div>
+        ) : items === null ? (
+          <div className="flex justify-center py-6"><Loader2 className="size-4 animate-spin text-primary" /></div>
+        ) : items.length === 0 ? (
+          <p className="p-3 text-xs text-text-subtle">No versions yet. One is saved after every AI turn that changes the design.</p>
+        ) : items.map((s) => (
+          <div key={s.id} className="flex items-center gap-2 rounded-md px-2 py-1.5">
+            <div className="min-w-0 flex-1">
+              <p className="truncate text-sm">{REASON_LABEL[s.reason] ?? s.reason}</p>
+              <p className="truncate text-xs text-text-subtle" title={s.createdAt}>
+                {formatRelativeDate(s.createdAt)} · {s.fileCount} files · {formatSize(s.bytes)}
+              </p>
+            </div>
+            <button type="button" disabled={isStreaming} onClick={() => setConfirm(s)}
+              aria-label="Restore this version" title="Restore this version"
+              className="flex size-11 shrink-0 items-center justify-center rounded-md text-text-subtle hover:bg-surface-elevated hover:text-foreground disabled:opacity-40 md:size-8">
+              <RotateCcw className="size-4" />
+            </button>
+          </div>
+        ))}
+      </div>
+      <DesignResponsiveDialog
+        open={!!confirm}
+        onClose={() => { if (!restoring) setConfirm(null); }}
+        title="Restore this version?"
+        description={confirm ? `The design's files are replaced with the version from ${formatRelativeDate(confirm.createdAt)}. The current state is saved to the history first, so you can go back.` : undefined}
+        footer={<>
+          <Button variant="outline" onClick={() => setConfirm(null)} disabled={restoring}>Cancel</Button>
+          <Button onClick={restore} disabled={restoring || isStreaming}>
+            {restoring && <Loader2 className="size-4 animate-spin" />} Restore
+          </Button>
+        </>}
+      />
+    </div>
+  );
+}

package/src/web/components/design/transform/design-undo-stack.ts

@@ -0,0 +1,90 @@
+import { useCallback, useState, useSyncExternalStore } from "react";
+import { toast } from "sonner";
+import { undoDesignEdit } from "@/lib/design/api-design-edits";
+
+/**
+ * The canvas's Undo: a per-tab stack of the server's undo ids, newest last.
+ *
+ * Every canvas write (a move or resize, a tweak Apply) pushes the id the server returned.
+ * Undo sends the newest one; the server reverts exactly that write, and only if the text it
+ * left is still there. When it is not (an AI turn rewrote that spot, the server restarted
+ * and lost its journal), that one entry is dropped and the ones below it stay usable: they
+ * are independent edits, each checked on its own. In memory only, like the server journal.
+ */
+
+export const MAX_UNDO_DEPTH = 50;
+
+const stacks = new Map<string, string[]>();
+const listeners = new Set<() => void>();
+const emit = () => { for (const fn of listeners) fn(); };
+
+export function pushDesignUndo(tabId: string, undoId: string): void {
+  const stack = [...(stacks.get(tabId) ?? []), undoId].slice(-MAX_UNDO_DEPTH);
+  stacks.set(tabId, stack);
+  emit();
+}
+
+export function peekDesignUndo(tabId: string): string | null {
+  const stack = stacks.get(tabId);
+  return stack && stack.length ? stack[stack.length - 1]! : null;
+}
+
+/** Removes that id wherever it is, leaving every other entry in place. */
+export function dropDesignUndo(tabId: string, undoId: string): void {
+  const stack = stacks.get(tabId);
+  if (!stack || !stack.includes(undoId)) return;
+  stacks.set(tabId, stack.filter((id) => id !== undoId));
+  emit();
+}
+
+export function designUndoDepth(tabId: string): number {
+  return stacks.get(tabId)?.length ?? 0;
+}
+
+export function subscribeDesignUndo(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+
+export function useDesignUndo(
+  tab: { projectName: string; slug: string; tabId: string; isStreaming: boolean },
+  opts: { openHistory: () => void },
+) {
+  const { projectName, slug, tabId, isStreaming } = tab;
+  const depth = useSyncExternalStore(subscribeDesignUndo, () => designUndoDepth(tabId));
+  const [busy, setBusy] = useState(false);
+  const { openHistory } = opts;
+
+  const undo = useCallback(async () => {
+    const id = peekDesignUndo(tabId);
+    if (!id || busy) return;
+    setBusy(true);
+    try {
+      const out = await undoDesignEdit(projectName, slug, id);
+      dropDesignUndo(tabId, id);
+      if (out.status === "undone") {
+        toast.success("Canvas edit undone");
+      } else {
+        toast.warning(out.status === "unknown" ? "That edit can no longer be undone" : "Cannot undo: the file changed since", {
+          description: "Version history still has the design as it was before that edit.",
+          action: { label: "History", onClick: openHistory },
+        });
+      }
+    } catch (e) {
+      // A network failure says nothing about the edit, so it stays on the stack.
+      toast.error("Could not undo", { description: (e as Error).message });
+    } finally {
+      setBusy(false);
+    }
+  }, [projectName, slug, tabId, busy, openHistory]);
+
+  return {
+    depth,
+    busy,
+    // An agent may be writing the same file; its turn ends before an undo is worth trying.
+    canUndo: depth > 0 && !busy && !isStreaming,
+    undo: () => { void undo(); },
+  };
+}
+
+export type DesignUndoFeature = ReturnType<typeof useDesignUndo>;

package/src/web/components/design/transform/transform-readout.tsx

@@ -0,0 +1,50 @@
+import { Loader2, Move, X } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import type { CanvasTransformFeature } from "./use-canvas-transform";
+
+/**
+ * What Move mode is doing, drawn over the canvas: the target's position and size while it
+ * moves, what to do when nothing is selected yet, and — only in a browser that cannot report
+ * user activation — Save/Discard for a change the parent could not tie to a gesture. A tap
+ * on this readout is itself a gesture the parent saw, which is what makes Save trustworthy.
+ *
+ * Bottom-left on desktop; at the top on a phone, where the bottom of the canvas belongs to
+ * the selected element's action bar.
+ */
+export function TransformReadout({ feature, isMobile }: { feature: CanvasTransformFeature; isMobile: boolean }) {
+  if (!feature.moveOn) return null;
+  const { live, target } = feature;
+  const r = live?.rect;
+  const text = !target
+    ? isMobile ? "Tap an element twice to select it, then drag it or its handles." : "Select an element to move or resize it."
+    : !live ? "Getting the element…"
+    : !r ? "That element is not on the page any more."
+    : `x ${Math.round(r.x)}  y ${Math.round(r.y)}  ·  w ${Math.round(r.w)}  h ${Math.round(r.h)}`;
+  const btn = cn("flex shrink-0 items-center justify-center rounded-md text-xs font-medium", isMobile ? "min-h-11 px-3" : "h-7 px-2");
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      onPointerDown={feature.markGesture}
+      className={cn(
+        "absolute z-20 flex items-center gap-2 rounded-lg border border-border bg-popover px-2 py-1 text-xs text-text-2 shadow-md",
+        isMobile ? "left-2 right-12 top-2" : "bottom-2 left-2 max-w-[calc(100%-1rem)]",
+      )}
+    >
+      {feature.saving ? <Loader2 className="size-4 shrink-0 animate-spin" /> : <Move className="size-4 shrink-0 text-text-subtle" />}
+      <span className="min-w-0 flex-1 truncate font-mono tabular-nums">{feature.confirm ? "Save this change to the design?" : text}</span>
+      {feature.confirm ? (
+        <>
+          <button type="button" onClick={feature.confirmSave} className={cn(btn, "bg-primary text-primary-foreground")}>Save</button>
+          <button type="button" onClick={feature.discard} className={cn(btn, "hover:bg-surface-elevated")}>Discard</button>
+        </>
+      ) : (
+        <button type="button" onClick={feature.stop} aria-label="Stop moving" title="Stop moving"
+          className={cn(btn, "text-text-subtle hover:bg-surface-elevated hover:text-foreground", isMobile ? "min-w-11" : "w-7 px-0")}>
+          <X className="size-4" />
+        </button>
+      )}
+    </div>
+  );
+}

package/src/web/components/design/transform/use-canvas-transform.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useRef, useState, type KeyboardEvent } from "react";
+import { toast } from "sonner";
+import { postDesignStyle } from "@/lib/design/api-design-edits";
+import { decideTransformProposal, readUserActivation } from "@/lib/design/design-transform-proposal";
+import type { ChildMessage } from "../../../../shared/design-bridge-protocol";
+import type { BridgeRect } from "../../../../shared/design-bridge-messages-picker";
+import type { TransformBox } from "../../../../shared/design-bridge-messages-transform";
+import type { DesignTabContextValue } from "../design-tab-context";
+import type { DesignBridge } from "../canvas/use-design-bridge";
+import type { ElementPicker } from "../comments/use-element-picker";
+import { pushDesignUndo } from "./design-undo-stack";
+
+/**
+ * Move mode for one design tab: which element has handles, what the frame proposes, and
+ * which proposals become writes.
+ *
+ * The target is the element the picker selected, remembered here rather than read from the
+ * picker: a write reloads the canvas, the picker drops its selection on every new document,
+ * but the patched element keeps its start offset and so its id. Each `ready` replays Move
+ * mode and the target, which is what puts the handles back after the reload. A proposal is
+ * only written after `decideTransformProposal` says so; anything else is answered with
+ * `transform-cancel`, which puts the frame's live style back.
+ */
+
+type Commit = Extract<ChildMessage, { type: "transform-commit" }>;
+interface Target { ppmId: number; tag: string; file: string }
+const ARROWS: Record<string, [number, number]> = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] };
+
+export function useCanvasTransform(tab: DesignTabContextValue, bridge: DesignBridge, picker: ElementPicker, scale: number, reloadCanvas: () => void) {
+  const { projectName, slug, tabId, isStreaming } = tab;
+  const { send, ready } = bridge;
+  const [moveOn, setMoveOn] = useState(false);
+  const [target, setTargetState] = useState<Target | null>(null);
+  const [live, setLive] = useState<{ rect: BridgeRect | null; box: TransformBox | null } | null>(null);
+  const [confirm, setConfirm] = useState<Commit | null>(null);
+  const [saving, setSaving] = useState(false);
+  const state = useRef({ moveOn, target, ready, isStreaming, scale });
+  state.current = { moveOn, target, ready, isStreaming, scale };
+  const lastGesture = useRef<number | null>(null);
+  const lastRefusalToast = useRef(0);
+  const reloaded = useRef(false);
+  // The gen our own last write produced, for proposals made before the canvas reloaded.
+  const ownWrite = useRef<{ from: string; to: string } | null>(null);
+  const queue = useRef<Promise<void>>(Promise.resolve());
+
+  const setTarget = useCallback((next: Target | null) => {
+    setTargetState(next);
+    setLive(null);
+    send(next ? { type: "transform-target", ppmId: next.ppmId, tag: next.tag } : { type: "transform-target", ppmId: null, tag: "" });
+  }, [send]);
+
+  const disabled = isStreaming || !ready || !ready.instrumented;
+
+  const setMove = useCallback((on: boolean) => {
+    setMoveOn(on);
+    setConfirm(null);
+    send({ type: "transform-mode", on, scale: state.current.scale });
+    if (!on) { setTarget(null); return; }
+    if (!picker.on) picker.setOn(true);
+    const sel = picker.selected;
+    setTarget(sel && sel.ppmId !== null && sel.file === state.current.ready?.file ? { ppmId: sel.ppmId, tag: sel.tag, file: sel.file } : null);
+  }, [send, picker, setTarget]);
+
+  // Writes are off while the design's turn runs, and an uninstrumented file has no ids. A
+  // reload (no `ready` for a moment) is not a reason: the next `ready` replays Move mode.
+  const mustStop = isStreaming || ready?.instrumented === false;
+  useEffect(() => { if (moveOn && mustStop) setMove(false); }, [moveOn, mustStop, setMove]);
+  useEffect(() => { if (state.current.moveOn) send({ type: "transform-mode", on: true, scale }); }, [scale, send]);
+
+  // Follow the picker; a selection that vanished because the document reloaded is kept.
+  useEffect(() => {
+    const sel = picker.selected;
+    if (sel) reloaded.current = false;
+    if (!state.current.moveOn) return;
+    if (sel) setTarget(sel.ppmId === null ? null : { ppmId: sel.ppmId, tag: sel.tag, file: sel.file });
+    else if (!reloaded.current) setTarget(null);
+  }, [picker.selected, setTarget]);
+
+  const commit = useCallback((m: Commit) => {
+    queue.current = queue.current.then(async () => {
+      const own = ownWrite.current;
+      const gen = own && own.from === m.gen ? own.to : m.gen;
+      setSaving(true);
+      try {
+        const out = await postDesignStyle(projectName, slug, { file: m.file, gen, ppmId: m.ppmId, tag: m.tag, props: m.props });
+        if (out.status === "written") {
+          ownWrite.current = { from: m.gen, to: out.gen };
+          if (out.undoId) pushDesignUndo(tabId, out.undoId);
+          return;
+        }
+        send({ type: "transform-cancel" });
+        toast.warning(out.status === "rate-limited" ? out.message : "The design changed; the canvas is reloading", {
+          description: out.status === "element-moved" ? out.message : undefined,
+        });
+        if (out.status !== "rate-limited") reloadCanvas();
+      } catch (e) {
+        send({ type: "transform-cancel" });
+        toast.error("Could not save the change", { description: (e as Error).message });
+      } finally {
+        setSaving(false);
+      }
+    });
+  }, [projectName, slug, tabId, send, reloadCanvas]);
+
+  const decide = useCallback((m: Commit) => {
+    const s = state.current;
+    return decideTransformProposal(m, {
+      moveOn: s.moveOn, streaming: s.isStreaming, target: s.target, ready: s.ready,
+      activation: readUserActivation(typeof navigator === "undefined" ? null : navigator),
+      lastParentGestureAt: lastGesture.current, now: Date.now(),
+    });
+  }, []);
+
+  useEffect(() => {
+    const offs = [
+      bridge.on("transform-live", (m) => {
+        const t = state.current.target;
+        if (state.current.moveOn && t && m.ppmId === t.ppmId) setLive({ rect: m.rect, box: m.box });
+      }),
+      bridge.on("transform-commit", (m) => {
+        const verdict = decide(m);
+        if (verdict.kind === "write") commit(m);
+        else if (verdict.kind === "confirm") setConfirm(m);
+        else {
+          send({ type: "transform-cancel" });
+          // Throttled: the page's own scripts can post proposals, and must not be able to flood toasts.
+          if (verdict.reason === "no-gesture" && Date.now() - lastRefusalToast.current > 5000) {
+            lastRefusalToast.current = Date.now();
+            toast.info("Not saved: the change did not follow a click or key press here");
+          }
+        }
+      }),
+      bridge.onReplay((replaySend, next) => {
+        reloaded.current = true;
+        ownWrite.current = null;
+        setLive(null);
+        setConfirm(null);
+        const s = state.current;
+        if (!s.moveOn) return;
+        replaySend({ type: "transform-mode", on: true, scale: s.scale });
+        if (s.target && s.target.file === next.file) replaySend({ type: "transform-target", ppmId: s.target.ppmId, tag: s.target.tag });
+      }),
+    ];
+    return () => { for (const off of offs) off(); };
+  }, [bridge.on, bridge.onReplay, decide, commit, send]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const markGesture = useCallback(() => { lastGesture.current = Date.now(); }, []);
+
+  /** Arrow keys in the focused canvas pane: forwarded to the frame, which coalesces them. */
+  const onPaneKeyDown = useCallback((e: KeyboardEvent) => {
+    const step = ARROWS[e.key];
+    if (!step || !state.current.moveOn || !state.current.target) return;
+    e.preventDefault();
+    markGesture();
+    const n = e.shiftKey ? 10 : 1;
+    send({ type: "transform-nudge", dx: step[0] * n, dy: step[1] * n });
+  }, [send, markGesture]);
+
+  const confirmSave = useCallback(() => {
+    const m = confirm;
+    setConfirm(null);
+    markGesture();
+    if (m && decide(m).kind === "write") commit(m);
+    else if (m) send({ type: "transform-cancel" });
+  }, [confirm, markGesture, decide, commit, send]);
+
+  const discard = useCallback(() => {
+    setConfirm(null);
+    send({ type: "transform-cancel" });
+  }, [send]);
+
+  return {
+    moveOn, disabled, target, live, confirm: confirm !== null, saving,
+    toggle: () => setMove(!moveOn), stop: () => setMove(false),
+    confirmSave, discard, markGesture, onPaneKeyDown,
+    /** Shown on the selected element's bar when it cannot be moved at all. */
+    hint: moveOn && picker.selected?.ppmId === null ? "Created by a script, so it cannot be moved" : null,
+  };
+}
+
+export type CanvasTransformFeature = ReturnType<typeof useCanvasTransform>;

package/src/web/components/design/tweaks/tweak-control.tsx

@@ -0,0 +1,94 @@
+import { useEffect, useId, useState } from "react";
+import { AlertTriangle } from "@/lib/icons";
+import { Input } from "@/components/ui/input";
+import { hexForColorInput, rangeNumberOf } from "@/lib/design/design-tweaks-model";
+import {
+  COLOR_VALUE_RE, formatRangeValue, type ColorTweak, type RangeTweak, type SelectTweak, type TweakDef,
+} from "../../../../shared/design-tweaks";
+import type { TweakWinner } from "../../../../shared/design-bridge-messages-tweaks";
+
+/**
+ * One tweak's control, labelled above its input (design guideline 8): a slider with a
+ * readout, a colour well with a hex field, or a native `<select>`. Every input is at least
+ * 44px tall on touch screens. A control only ever reports a value its type allows; a hex
+ * field mid-typing reports nothing until it holds a whole colour.
+ */
+
+interface ControlProps<T extends TweakDef> {
+  def: T;
+  value: string;
+  onChange: (value: string) => void;
+  inputId: string;
+}
+
+function RangeControl({ def, value, onChange, inputId }: ControlProps<RangeTweak>) {
+  return (
+    <div className="flex items-center gap-3">
+      <input id={inputId} type="range" min={def.min} max={def.max} step={def.step} value={rangeNumberOf(def, value)}
+        onChange={(e) => onChange(formatRangeValue(def, Number(e.target.value)))}
+        className="h-11 min-w-0 flex-1 cursor-pointer accent-primary md:h-8" />
+      <output htmlFor={inputId} className="w-16 shrink-0 truncate text-right text-xs tabular-nums text-text-subtle">{value}</output>
+    </div>
+  );
+}
+
+function ColorControl({ def, value, onChange, inputId }: ControlProps<ColorTweak>) {
+  const [text, setText] = useState(value);
+  useEffect(() => setText(value), [value]);
+  const invalid = !COLOR_VALUE_RE.test(text.trim());
+  return (
+    <div className="flex items-center gap-2">
+      <input id={inputId} type="color" value={hexForColorInput(value, def.default)} onChange={(e) => onChange(e.target.value)}
+        className="h-11 w-14 shrink-0 cursor-pointer rounded-md border border-border bg-transparent p-1 md:h-8" />
+      <Input value={text} aria-label={`${def.label} hex value`} aria-invalid={invalid} spellCheck={false} maxLength={9}
+        onChange={(e) => {
+          setText(e.target.value);
+          const next = e.target.value.trim();
+          if (COLOR_VALUE_RE.test(next)) onChange(next);
+        }}
+        className="h-11 font-mono md:h-8" />
+    </div>
+  );
+}
+
+function SelectControl({ def, value, onChange, inputId }: ControlProps<SelectTweak>) {
+  const known = def.options.some((o) => o.value === value);
+  return (
+    <select id={inputId} value={known ? value : ""} onChange={(e) => onChange(e.target.value)}
+      className="h-11 w-full rounded-lg border border-border bg-surface px-2 text-base text-foreground md:h-8 md:text-sm">
+      {!known && <option value="" disabled>{value ? `Current: ${value}` : "Choose…"}</option>}
+      {def.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+    </select>
+  );
+}
+
+export function TweakControl({ def, value, winner, overridden, onChange }: {
+  def: TweakDef;
+  value: string;
+  winner?: TweakWinner;
+  overridden: boolean;
+  onChange: (value: string) => void;
+}) {
+  const inputId = useId();
+  const note = overridden
+    ? "A later or more specific rule overrides this tweak, so the page does not show the applied value."
+    : winner === "conditional"
+      ? "This variable is set last inside a conditional rule; Apply may not be able to change it."
+      : null;
+  return (
+    <div className="flex flex-col gap-1 px-3 py-2">
+      <label htmlFor={inputId} className="flex items-baseline gap-2 text-sm">
+        <span className="min-w-0 flex-1 truncate">{def.label}</span>
+        <code className="shrink-0 text-[11px] text-text-subtle">{def.var}</code>
+      </label>
+      {def.type === "range" && <RangeControl def={def} value={value} onChange={onChange} inputId={inputId} />}
+      {def.type === "color" && <ColorControl def={def} value={value} onChange={onChange} inputId={inputId} />}
+      {def.type === "select" && <SelectControl def={def} value={value} onChange={onChange} inputId={inputId} />}
+      {note && (
+        <p className="flex items-start gap-1 text-xs leading-relaxed text-warning">
+          <AlertTriangle className="mt-0.5 size-3.5 shrink-0" /> {note}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/web/components/design/tweaks/tweaks-panel.tsx

@@ -0,0 +1,99 @@
+import { useState } from "react";
+import { AlertTriangle, ChevronDown, ChevronRight, Loader2, RotateCcw, Sparkles, SlidersHorizontal, X } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { deliverToDesignChat } from "@/lib/design/deliver-to-design-chat";
+import { buildAddTweaksPrompt, buildFixTweaksPrompt, shownValue } from "@/lib/design/design-tweaks-model";
+import { TweakControl } from "./tweak-control";
+import type { DesignTweaksFeature } from "./use-design-tweaks";
+
+/**
+ * The Tweaks panel: one control per tweak `design.json` declares, live on the canvas as
+ * they move, written to the design only on Apply. A desktop side column; on a phone the
+ * same body sits in a bottom sheet with Reset and Apply at its foot, in the thumb zone.
+ *
+ * Skipped entries are counted in a badge that unfolds their reasons, with a way to hand
+ * them to the AI; a design with no tweaks at all offers to ask the AI for some. Neither
+ * sends anything: the brief lands in the design chat's composer for the user to send.
+ */
+
+export function TweaksPanel({ feature, tabId, slug }: { feature: DesignTweaksFeature; tabId: string; slug: string }) {
+  const [showErrors, setShowErrors] = useState(false);
+  const { info, loadError, rendered, edits, winners, overridden } = feature;
+  const errors = info?.errors ?? [];
+  const tweaks = info?.tweaks ?? [];
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-panel">
+      <div className="flex h-9 shrink-0 items-center gap-2 border-b border-border px-2">
+        <SlidersHorizontal className="size-4 text-text-subtle" />
+        <span className="flex-1 text-xs font-semibold">Tweaks</span>
+        <button type="button" onClick={feature.closePanel} aria-label="Close tweaks"
+          className="flex size-11 items-center justify-center rounded-md text-text-subtle hover:bg-surface-elevated md:size-7">
+          <X className="size-4" />
+        </button>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto py-1">
+        {loadError ? (
+          <p className="p-3 text-xs text-destructive">{loadError}</p>
+        ) : info === null ? (
+          <div className="flex justify-center py-6"><Loader2 className="size-4 animate-spin text-primary" /></div>
+        ) : (
+          <>
+            {errors.length > 0 && (
+              <div className="mx-2 mb-1 rounded-md border border-warning/40 bg-warning/10">
+                <button type="button" onClick={() => setShowErrors((v) => !v)} aria-expanded={showErrors}
+                  className="flex min-h-11 w-full items-center gap-1 px-2 text-left text-xs font-medium text-warning md:min-h-8">
+                  {showErrors ? <ChevronDown className="size-4" /> : <ChevronRight className="size-4" />}
+                  <AlertTriangle className="size-3.5" />
+                  {errors.length === 1 ? "1 tweak ignored" : `${errors.length} tweaks ignored`}
+                </button>
+                {showErrors && (
+                  <div className="px-3 pb-2">
+                    <ul className="list-disc space-y-1 pl-4 text-xs leading-relaxed text-text-subtle">
+                      {errors.map((e, i) => <li key={i} className="break-words">{e}</li>)}
+                    </ul>
+                    <button type="button" onClick={() => deliverToDesignChat(tabId, buildFixTweaksPrompt(slug, errors), "Fix tweaks")}
+                      className="mt-1 min-h-11 text-xs text-primary underline md:min-h-7">Ask AI to fix them</button>
+                  </div>
+                )}
+              </div>
+            )}
+            {tweaks.length === 0 ? (
+              <div className="flex flex-col items-start gap-2 p-3">
+                <p className="text-xs leading-relaxed text-text-subtle">
+                  This design declares no tweaks yet. Tweaks are sliders, colours and choices bound to the design's CSS variables.
+                </p>
+                <Button variant="outline" className="min-h-11 md:min-h-8"
+                  onClick={() => deliverToDesignChat(tabId, buildAddTweaksPrompt(slug), "Add tweaks")}>
+                  <Sparkles className="size-4" /> Ask AI to add tweaks
+                </Button>
+              </div>
+            ) : (
+              tweaks.map((def) => (
+                <TweakControl key={def.id} def={def} value={shownValue(def, edits, rendered)} winner={winners[def.var]}
+                  overridden={overridden.includes(def.var)} onChange={(v) => feature.setValue(def.var, v)} />
+              ))
+            )}
+          </>
+        )}
+      </div>
+      {tweaks.length > 0 && (
+        <div className="shrink-0 border-t border-border p-2 pb-[max(0.5rem,env(safe-area-inset-bottom))]">
+          {feature.isStreaming && feature.dirtyCount > 0 && (
+            <p className="px-1 pb-1 text-xs text-text-subtle">Apply is available once the AI finishes its turn.</p>
+          )}
+          <div className="flex gap-2">
+            <Button variant="outline" className="min-h-11 flex-1 md:min-h-9" onClick={feature.reset}
+              disabled={Object.keys(edits).length === 0 || feature.applying}>
+              <RotateCcw className="size-4" /> Reset
+            </Button>
+            <Button className="min-h-11 flex-1 md:min-h-9" onClick={feature.apply} disabled={!feature.canApply}>
+              {feature.applying ? <Loader2 className="size-4 animate-spin" /> : null}
+              {feature.dirtyCount > 1 ? `Apply ${feature.dirtyCount}` : "Apply"}
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}