@hienlh/ppm 0.22.10 → 0.23.0

package/src/web/components/design/design-split-layout.tsx

@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useRef, useState, type ReactNode, type RefObject } from "react";
+import { Group, Panel, Separator, type Layout } from "react-resizable-panels";
+import { cn } from "@/lib/utils";
+import {
+  clampChatPercent, loadDesignViewPrefs, saveDesignViewPrefs, withChatPercent,
+} from "@/lib/design/design-view-prefs";
+import type { DesignLayoutControls } from "./design-tab-context";
+import { DesignChatPaneHeader } from "./design-layout-controls";
+import { DesignMobilePaneBar } from "./design-mobile-layout";
+
+const CHAT_PANEL_ID = "design-chat";
+
+/**
+ * The design tab's one layout tree, for every width: chat and canvas side by side in a
+ * resizable group, or one of them alone, with the phone's bar under it on a phone.
+ *
+ * Nothing here is ever mounted conditionally around the two panes. Moving an iframe in the
+ * DOM reloads the design and unmounting the chat drops its socket (and any message still
+ * waiting for it), so a change of layout only changes classes: the pane not shown is
+ * `display: none`, which the library's panel wrapper can only be given through a descendant
+ * rule, because its inline `display: flex` takes no class. The group is disabled while one
+ * pane shows, which also takes the hidden separator out of the library's hit testing.
+ *
+ * While the handle is dragged the iframe must not see the pointer — an iframe swallows the
+ * `pointermove`s the split listens for, and the handle drops out from under the cursor. The
+ * root carries `data-design-resizing` for that long, and the canvas turns pointer events off
+ * under it.
+ */
+export function DesignTabLayout({ rootRef, layout, chat, canvas }: {
+  rootRef: RefObject<HTMLDivElement | null>;
+  layout: DesignLayoutControls;
+  chat: ReactNode;
+  canvas: (more: { open: boolean; onClose: () => void }) => ReactNode;
+}) {
+  const [chatPercent] = useState(() => loadDesignViewPrefs().chatPercent);
+  const [resizing, setResizing] = useState(false);
+  const [moreOpen, setMoreOpen] = useState(false);
+  // Read by the layout callback, which must not record a share while a pane is hidden.
+  const splitRef = useRef(layout.split);
+  splitRef.current = layout.split;
+
+  useEffect(() => {
+    if (!resizing) return;
+    const stop = () => setResizing(false);
+    window.addEventListener("pointerup", stop);
+    window.addEventListener("pointercancel", stop);
+    return () => {
+      window.removeEventListener("pointerup", stop);
+      window.removeEventListener("pointercancel", stop);
+    };
+  }, [resizing]);
+
+  const onPointerDownCapture = useCallback((e: React.PointerEvent) => {
+    if (splitRef.current && (e.target as Element | null)?.closest?.("[data-separator]")) setResizing(true);
+  }, []);
+
+  const onLayoutChanged = useCallback((next: Layout) => {
+    const pct = next[CHAT_PANEL_ID];
+    if (splitRef.current && typeof pct === "number") saveDesignViewPrefs(withChatPercent(loadDesignViewPrefs(), pct));
+  }, []);
+
+  const { split, pane } = layout;
+  // One pane shows no separator, so the library's hold on touch gestures (`pan-y` for a
+  // horizontal group) would only stop a design from scrolling sideways under a finger.
+  const panelTouch = split ? undefined : "touch-auto!";
+  return (
+    <div ref={rootRef}
+      className={cn(
+        "flex h-full min-h-0 flex-col",
+        !split && pane === "canvas" && "[&_[data-design-pane=chat]]:hidden!",
+        !split && pane === "chat" && "[&_[data-design-pane=canvas]]:hidden!",
+      )}
+      data-design-view={split ? "split" : pane}
+      data-design-resizing={resizing ? "" : undefined}
+      onPointerDownCapture={onPointerDownCapture}>
+      <div className="min-h-0 flex-1">
+        <Group orientation="horizontal" disabled={!split} onLayoutChanged={onLayoutChanged} style={{ height: "100%" }}>
+          {/* Sizes are percentage strings: bare numbers mean pixels in this library. */}
+          <Panel id={CHAT_PANEL_ID} data-design-pane="chat" className={panelTouch}
+            defaultSize={`${clampChatPercent(chatPercent)}%`} minSize="20%" maxSize="70%">
+            <div className={cn("flex h-full min-w-0 flex-col", split && "border-r border-border")}>
+              {layout.switcher === "toolbar" && <DesignChatPaneHeader layout={layout} />}
+              <div className="min-h-0 flex-1" data-design-chat-slot="">{chat}</div>
+            </div>
+          </Panel>
+          <Separator disabled={!split}
+            className={cn("w-1 cursor-col-resize bg-border/30 transition-colors hover:bg-primary/30 active:bg-primary/50", !split && "hidden")} />
+          <Panel data-design-pane="canvas" className={panelTouch} minSize="25%">
+            {canvas({ open: moreOpen, onClose: () => setMoreOpen(false) })}
+          </Panel>
+        </Group>
+      </div>
+      {layout.switcher === "phone" && (
+        <DesignMobilePaneBar pane={pane} onPaneChange={layout.setPane}
+          onMore={() => { layout.setPane("canvas"); setMoreOpen(true); }} />
+      )}
+    </div>
+  );
+}

package/src/web/components/design/design-tab-context.ts

@@ -0,0 +1,44 @@
+import { createContext, useContext } from "react";
+import type { DesignSummary } from "../../../shared/design-types";
+import type { DesignLayout, DesignLayoutOverride, DesignPane } from "@/lib/design/design-layout-mode";
+
+/** The tab's layout as resolved for its width, and the ways to change it. */
+export interface DesignLayoutControls extends DesignLayout {
+  /** Picks a layout from the menu and remembers it on this device. */
+  setOverride: (layout: DesignLayoutOverride) => void;
+  /** Which pane a single-pane layout shows; not remembered. */
+  setPane: (pane: DesignPane) => void;
+  setExpanded: (expanded: boolean) => void;
+}
+
+/**
+ * What every part of a design tab shares: which design, which tab, which session, and the
+ * few tab-level actions the canvas and toolbar need (bring the chat into view, refetch the
+ * manifest).
+ */
+export interface DesignTabContextValue {
+  projectName: string;
+  slug: string;
+  tabId: string;
+  design: DesignSummary;
+  /** The session the embedded chat is on, or null before its first message. */
+  sessionId: string | null;
+  /** True while that session's turn is running; restoring history waits for it. */
+  isStreaming: boolean;
+  /** True while this tab is the visible tab of its panel. */
+  isActive: boolean;
+  /** Phone viewport; a narrow tab on a desktop is not one (see `layout`). */
+  isMobile: boolean;
+  layout: DesignLayoutControls;
+  /** Brings the chat into view: leaves the expanded canvas and, in one pane, switches to it. */
+  showChat: () => void;
+  refreshDesign: () => void;
+}
+
+export const DesignTabContext = createContext<DesignTabContextValue | null>(null);
+
+export function useDesignTab(): DesignTabContextValue {
+  const value = useContext(DesignTabContext);
+  if (!value) throw new Error("useDesignTab() used outside a design tab");
+  return value;
+}

package/src/web/components/design/design-tab.tsx

@@ -0,0 +1,116 @@
+import { useEffect, useMemo } from "react";
+import { Loader2, Palette } from "@/lib/icons";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { usePanelStore } from "@/stores/panel-store";
+import { useStreamingStore } from "@/stores/streaming-store";
+import { useSettingsStore } from "@/stores/settings-store";
+import { useDesignSessionState } from "@/hooks/use-design-session-state";
+import { DESIGN_SHOW_CHAT_EVENT, type DesignShowChatDetail } from "@/lib/design/deliver-to-design-chat";
+import { DESIGNS_CHANGED_EVENT } from "@/lib/design/design-ui-events";
+import { DesignTabContext, type DesignTabContextValue } from "./design-tab-context";
+import { DesignChatPane } from "./design-chat-pane";
+import { DesignCanvasPane } from "./canvas/design-canvas-pane";
+import { DesignTabLayout } from "./design-split-layout";
+import { useDesignLayout } from "./use-design-layout";
+import { useDesignSummary } from "./use-design-summary";
+
+/**
+ * A design tab: the design's chat beside its live canvas.
+ *
+ * Loaded lazily by the tab pool, so none of this reaches the entry bundle. Everything the
+ * two halves share goes through {@link DesignTabContext}.
+ */
+export function DesignTab({ metadata, tabId }: { metadata?: Record<string, unknown>; tabId?: string }) {
+  const projectName = typeof metadata?.projectName === "string" ? metadata.projectName : "";
+  const slug = typeof metadata?.designSlug === "string" ? metadata.designSlug : "";
+  const { state, refresh } = useDesignSummary(projectName, slug);
+
+  if (!tabId || !metadata) return null;
+  if (state.status === "loading") {
+    return (
+      <div className="flex h-full items-center justify-center gap-2 text-sm text-text-subtle" role="status">
+        <Loader2 className="size-4 animate-spin" /> Opening design…
+      </div>
+    );
+  }
+  if (state.status !== "ready") {
+    return <DesignEmptyState slug={slug} message={state.status === "error" ? state.message : undefined} onRetry={refresh} />;
+  }
+  return <DesignTabBody tabId={tabId} metadata={metadata} design={state.design} refreshDesign={refresh} />;
+}
+
+function DesignTabBody({ tabId, metadata, design, refreshDesign }: {
+  tabId: string;
+  metadata: Record<string, unknown>;
+  design: DesignTabContextValue["design"];
+  refreshDesign: () => void;
+}) {
+  const isMobile = useIsMobile();
+  const session = useDesignSessionState(tabId, metadata);
+  const isActive = usePanelStore((s) => Object.values(s.panels).some((p) => p.activeTabId === tabId));
+  const { rootRef, layout, showChat } = useDesignLayout({ isPhone: isMobile, isActive });
+  const isStreaming = useStreamingStore((s) => (session.sessionId ? s.sessions.has(session.sessionId) : false));
+  const projectName = String(metadata.projectName);
+
+  // The tab is named after the design; a rename or a tab opened from history catches up here.
+  useEffect(() => {
+    const tab = usePanelStore.getState().getPanelForTab(tabId)?.tabs.find((t) => t.id === tabId);
+    if (tab && tab.title !== design.title) usePanelStore.getState().updateTab(tabId, { title: design.title });
+  }, [tabId, design.title]);
+
+  useEffect(() => {
+    const onShow = (e: Event) => {
+      if ((e as CustomEvent<DesignShowChatDetail>).detail?.tabId === tabId) showChat();
+    };
+    // A rename from the sidebar changes the manifest; the watcher only reports it while this
+    // project is the active one, so the announcement is the reliable signal.
+    const onDesignsChanged = (e: Event) => {
+      if ((e as CustomEvent<{ projectName?: string }>).detail?.projectName === projectName) refreshDesign();
+    };
+    window.addEventListener(DESIGN_SHOW_CHAT_EVENT, onShow);
+    window.addEventListener(DESIGNS_CHANGED_EVENT, onDesignsChanged);
+    return () => {
+      window.removeEventListener(DESIGN_SHOW_CHAT_EVENT, onShow);
+      window.removeEventListener(DESIGNS_CHANGED_EVENT, onDesignsChanged);
+    };
+  }, [tabId, projectName, refreshDesign, showChat]);
+
+  const ctx = useMemo<DesignTabContextValue>(() => ({
+    projectName, slug: design.slug, tabId, design, sessionId: session.sessionId,
+    isStreaming, isActive, isMobile, layout, showChat, refreshDesign,
+  }), [projectName, design, tabId, session.sessionId, isStreaming, isActive, isMobile, layout, showChat, refreshDesign]);
+
+  // One layout for every width and device: swapping layout components would remount (and
+  // so reload) the canvas and drop the chat's socket.
+  return (
+    <DesignTabContext.Provider value={ctx}>
+      <DesignTabLayout
+        rootRef={rootRef}
+        layout={layout}
+        chat={<DesignChatPane tabId={tabId} metadata={metadata} session={session} />}
+        canvas={(more) => <DesignCanvasPane moreOpen={more.open} onMoreClose={more.onClose} />}
+      />
+    </DesignTabContext.Provider>
+  );
+}
+
+function DesignEmptyState({ slug, message, onRetry }: { slug: string; message?: string; onRetry: () => void }) {
+  const openDesigns = () => {
+    const settings = useSettingsStore.getState();
+    settings.setSidebarActiveTab("designs");
+    if (settings.sidebarCollapsed) settings.toggleSidebar();
+  };
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center" role="status">
+      <Palette className="size-8 text-text-subtle" />
+      <p className="text-sm font-medium">{message ? "Could not open this design" : "This design no longer exists"}</p>
+      <p className="max-w-sm text-xs text-text-subtle">
+        {message ?? `There is no design folder named “${slug}” in this project. It may have been deleted or renamed on disk.`}
+      </p>
+      <div className="flex gap-2">
+        {message && <button type="button" onClick={onRetry} className="min-h-11 px-3 text-sm text-primary underline">Retry</button>}
+        <button type="button" onClick={openDesigns} className="min-h-11 px-3 text-sm text-primary underline">Show designs</button>
+      </div>
+    </div>
+  );
+}

package/src/web/components/design/design-toolbar-list.tsx

@@ -0,0 +1,36 @@
+import { cn } from "@/lib/utils";
+import { DEVICE_FRAMES } from "./canvas/device-frame-presets";
+import { FRAME_ICONS, ToolbarBadge, visibleItems, type DesignToolbarContext } from "./design-toolbar";
+
+/** The same frames and items as full-width rows, for the phone's More sheet. */
+export function DesignToolbarList({ ctx, onDone }: { ctx: DesignToolbarContext; onDone: () => void }) {
+  const row = "flex min-h-11 w-full items-center gap-3 rounded-md px-3 text-left text-sm hover:bg-surface-elevated disabled:opacity-40";
+  return (
+    <div className="flex flex-col gap-1 px-2 pb-2">
+      <p className="px-3 pt-1 text-xs font-semibold uppercase tracking-wide text-text-subtle">Device frame</p>
+      <div role="radiogroup" aria-label="Device frame" className="grid grid-cols-4 gap-2 px-1">
+        {DEVICE_FRAMES.map((f) => {
+          const Icon = FRAME_ICONS[f.id];
+          const on = ctx.frame === f.id;
+          return (
+            <button key={f.id} type="button" role="radio" aria-checked={on}
+              onClick={() => { ctx.setFrame(f.id); onDone(); }}
+              className={cn("flex min-h-14 flex-col items-center justify-center gap-1 rounded-md border text-xs",
+                on ? "border-primary text-foreground" : "border-border text-text-subtle")}>
+              <Icon className="size-5" /> {f.label}
+            </button>
+          );
+        })}
+      </div>
+      <div className="my-1 h-px bg-border" />
+      {visibleItems(ctx).map((item) => (
+        <button key={item.id} type="button" className={row} disabled={item.isDisabled?.(ctx)}
+          aria-pressed={item.isActive ? item.isActive(ctx) : undefined}
+          onClick={() => { onDone(); item.run(ctx); }}>
+          <item.icon className="size-5 text-text-subtle" /> <span className="flex-1">{item.label}</span>
+          <ToolbarBadge count={item.badge?.(ctx)} />
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/web/components/design/design-toolbar.tsx

@@ -0,0 +1,200 @@
+import type { ElementType, ReactNode } from "react";
+import {
+  Code, Columns2, Download, History, Maximize2, MessageSquarePlus, Monitor, MoreHorizontal, MousePointerClick, Move,
+  Presentation, RefreshCw, SlidersHorizontal, Smartphone, Sparkles, Tablet, Undo2,
+} from "@/lib/icons";
+import {
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { cn } from "@/lib/utils";
+import { deliverToDesignChat } from "@/lib/design/deliver-to-design-chat";
+import { buildDesignSystemInitPrompt } from "../../../shared/design-system-init-prompt";
+import { DEVICE_FRAMES, type DeviceFrameId } from "./canvas/device-frame-presets";
+import type { DesignTabContextValue } from "./design-tab-context";
+import type { DesignCanvasState } from "./canvas/use-design-canvas";
+import type { DesignCommentsFeature } from "./comments/use-design-comments-feature";
+import type { DesignTweaksFeature } from "./tweaks/use-design-tweaks";
+import type { CanvasTransformFeature } from "./transform/use-canvas-transform";
+import type { DesignUndoFeature } from "./transform/design-undo-stack";
+import type { DesignExportFeature } from "./export/use-design-export";
+import { ExportMenuButton } from "./export/export-menu";
+import { DesignLayoutMenu, DesignPaneSwitch } from "./design-layout-controls";
+
+/**
+ * The canvas toolbar and its registry.
+ *
+ * Features add a button by appending to {@link DESIGN_TOOLBAR_ITEMS}; nothing else in this
+ * file needs to change. `bar` items get a button on desktop, `more` items live in the
+ * overflow menu, and a `bar` item with `renderBar` draws its own control (a dropdown). On a
+ * phone every item is in the More sheet (the thumb-zone bar only holds Canvas / Chat / More),
+ * which renders the same list through `DesignToolbarList` and calls `run`.
+ */
+
+export interface DesignToolbarContext extends DesignTabContextValue {
+  canvas: DesignCanvasState;
+  frame: DeviceFrameId;
+  setFrame: (frame: DeviceFrameId) => void;
+  historyOpen: boolean;
+  toggleHistory: () => void;
+  comments: DesignCommentsFeature;
+  tweaks: DesignTweaksFeature;
+  transform: CanvasTransformFeature;
+  undo: DesignUndoFeature;
+  exports: DesignExportFeature;
+}
+
+export interface DesignToolbarItem {
+  id: string;
+  label: string;
+  icon: ElementType;
+  placement: "bar" | "more";
+  isActive?: (ctx: DesignToolbarContext) => boolean;
+  isDisabled?: (ctx: DesignToolbarContext) => boolean;
+  /** Left out of the bar, the menu and the phone sheet while true. */
+  isHidden?: (ctx: DesignToolbarContext) => boolean;
+  /** A count shown on the button, e.g. open comments; nothing when 0 or null. */
+  badge?: (ctx: DesignToolbarContext) => number | null;
+  /** Desktop bar only: a control of its own in place of the plain button. */
+  renderBar?: (ctx: DesignToolbarContext, className: string) => ReactNode;
+  run: (ctx: DesignToolbarContext) => void;
+}
+
+export const DESIGN_TOOLBAR_ITEMS: DesignToolbarItem[] = [
+  { id: "reload", label: "Reload canvas", icon: RefreshCw, placement: "bar", run: (ctx) => ctx.canvas.reload() },
+  {
+    id: "history", label: "Version history", icon: History, placement: "bar",
+    isActive: (ctx) => ctx.historyOpen, run: (ctx) => ctx.toggleHistory(),
+  },
+  {
+    // Fills the composer and waits: the user reviews the brief and sends it themselves.
+    id: "design-system", label: "Set up design system", icon: Sparkles, placement: "more",
+    run: (ctx) => deliverToDesignChat(ctx.tabId, buildDesignSystemInitPrompt(), "Set up design system"),
+  },
+  {
+    // Picking needs element ids, which a file served without instrumentation does not have.
+    id: "select", label: "Select element", icon: MousePointerClick, placement: "bar",
+    isActive: (ctx) => ctx.comments.picker.on,
+    isDisabled: (ctx) => ctx.canvas.bridge.ready?.instrumented === false,
+    run: (ctx) => ctx.comments.picker.setOn(!ctx.comments.picker.on),
+  },
+  {
+    id: "comments", label: "Comments", icon: MessageSquarePlus, placement: "bar",
+    isActive: (ctx) => ctx.comments.panelOpen,
+    badge: (ctx) => ctx.comments.openCount || null,
+    run: (ctx) => ctx.comments.togglePanel(),
+  },
+  {
+    // Offered whenever design.json parses; with no tweaks declared the panel asks the AI for some.
+    id: "tweaks", label: "Tweaks", icon: SlidersHorizontal, placement: "bar",
+    isHidden: (ctx) => !ctx.tweaks.available,
+    isActive: (ctx) => ctx.tweaks.panelOpen,
+    badge: (ctx) => ctx.tweaks.dirtyCount || null,
+    run: (ctx) => ctx.tweaks.togglePanel(),
+  },
+  {
+    // Writes need element ids and a quiet chat: an agent editing the same file would race it.
+    id: "move", label: "Move and resize", icon: Move, placement: "bar",
+    isActive: (ctx) => ctx.transform.moveOn,
+    isDisabled: (ctx) => !ctx.transform.moveOn && ctx.transform.disabled,
+    run: (ctx) => ctx.transform.toggle(),
+  },
+  {
+    // Reverts the newest canvas write only, exactly; AI turns since then stay.
+    id: "undo", label: "Undo canvas edit", icon: Undo2, placement: "bar",
+    isDisabled: (ctx) => !ctx.undo.canUndo,
+    run: (ctx) => ctx.undo.undo(),
+  },
+  {
+    // Desktop: a dropdown of its own. Phone: the More sheet's row opens the export sheet.
+    id: "export", label: "Export", icon: Download, placement: "bar",
+    renderBar: (ctx, className) => <ExportMenuButton key="export" feature={ctx.exports} className={className} />,
+    run: (ctx) => ctx.exports.setSheetOpen(true),
+  },
+  {
+    // Starts a new, ordinary chat with the brief as a draft; never the design chat.
+    id: "handoff", label: "Hand off to code", icon: Code, placement: "more",
+    run: (ctx) => ctx.exports.handOff(),
+  },
+  {
+    // The canvas over the whole window; the chat keeps running underneath.
+    id: "expand", label: "Expand canvas", icon: Maximize2, placement: "bar",
+    isActive: (ctx) => ctx.layout.expanded,
+    run: (ctx) => ctx.layout.setExpanded(!ctx.layout.expanded),
+  },
+  {
+    // Desktop only, as a menu of its own: a phone always shows one pane. Hidden while the
+    // canvas is expanded, where hiding the canvas pane would take the expanded view with it.
+    id: "layout", label: "Layout", icon: Columns2, placement: "bar",
+    isHidden: (ctx) => ctx.isMobile || ctx.layout.expanded,
+    renderBar: (ctx, className) => <DesignLayoutMenu key="layout" layout={ctx.layout} className={className} />,
+    run: (ctx) => ctx.layout.setOverride("auto"),
+  },
+];
+
+export const visibleItems = (ctx: DesignToolbarContext) => DESIGN_TOOLBAR_ITEMS.filter((i) => !i.isHidden?.(ctx));
+
+export function ToolbarBadge({ count, className }: { count: number | null | undefined; className?: string }) {
+  if (!count) return null;
+  return (
+    <span className={cn("flex h-4 min-w-4 items-center justify-center rounded-full bg-primary px-1 text-[10px] font-semibold leading-none text-primary-foreground", className)}>
+      {count > 99 ? "99+" : count}
+    </span>
+  );
+}
+
+export const FRAME_ICONS: Record<DeviceFrameId, ElementType> = {
+  desktop: Monitor, tablet: Tablet, phone: Smartphone, slide: Presentation,
+};
+
+const iconBtn = "flex size-8 items-center justify-center rounded-md text-text-subtle hover:bg-surface-elevated hover:text-foreground disabled:opacity-40";
+
+/** Desktop toolbar: frame picker on the left, registry items on the right. */
+export function DesignToolbar({ ctx }: { ctx: DesignToolbarContext }) {
+  const items = visibleItems(ctx);
+  const bar = items.filter((i) => i.placement === "bar");
+  const more = items.filter((i) => i.placement === "more");
+  return (
+    <div className="flex min-h-9 shrink-0 items-center gap-1 border-b border-border bg-panel px-2">
+      {ctx.layout.switcher === "toolbar" && <DesignPaneSwitch layout={ctx.layout} />}
+      <div role="radiogroup" aria-label="Device frame" className="flex items-center gap-0.5">
+        {DEVICE_FRAMES.map((f) => {
+          const Icon = FRAME_ICONS[f.id];
+          const on = ctx.frame === f.id;
+          return (
+            <button key={f.id} type="button" role="radio" aria-checked={on} title={f.label} aria-label={f.label}
+              onClick={() => ctx.setFrame(f.id)}
+              className={cn(iconBtn, on && "bg-surface-elevated text-foreground")}>
+              <Icon className="size-4" />
+            </button>
+          );
+        })}
+      </div>
+      <span className="mx-2 min-w-0 flex-1 truncate text-xs text-text-subtle" title={ctx.design.title}>{ctx.design.title}</span>
+      {bar.map((item) => item.renderBar ? item.renderBar(ctx, iconBtn) : (
+        <button key={item.id} type="button" title={item.label} aria-label={item.label}
+          aria-pressed={item.isActive ? item.isActive(ctx) : undefined}
+          disabled={item.isDisabled?.(ctx)} onClick={() => item.run(ctx)}
+          className={cn(iconBtn, "relative", item.isActive?.(ctx) && "bg-surface-elevated text-foreground")}>
+          <item.icon className="size-4" />
+          <ToolbarBadge count={item.badge?.(ctx)} className="absolute -right-1 -top-1" />
+        </button>
+      ))}
+      {more.length > 0 && (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button type="button" className={iconBtn} aria-label="More canvas actions" title="More">
+              <MoreHorizontal className="size-4" />
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            {more.map((item) => (
+              <DropdownMenuItem key={item.id} disabled={item.isDisabled?.(ctx)} onSelect={() => item.run(ctx)}>
+                <item.icon className="size-4" /> {item.label}
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+    </div>
+  );
+}

package/src/web/components/design/designs-sidebar-panel.tsx

@@ -0,0 +1,117 @@
+import { useCallback, useEffect, useState } from "react";
+import { FileCode, Loader2, Palette, Pencil, Plus, Presentation, Trash2 } from "@/lib/icons";
+import { useProjectStore } from "@/stores/project-store";
+import {
+  ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger,
+} from "@/components/ui/adaptive-context-menu";
+import { formatRelativeDate } from "@/lib/format-date";
+import { listDesigns, type DesignList } from "@/lib/design/api-designs";
+import { openDesignTab } from "@/lib/design/open-design-tab";
+import { DESIGNS_CHANGED_EVENT, requestNewDesign } from "@/lib/design/design-ui-events";
+import { RenameDesignDialog } from "./dialogs/rename-design-dialog";
+import { DeleteDesignDialog } from "./dialogs/delete-design-dialog";
+import type { DesignSummary } from "../../../shared/design-types";
+
+/** Sidebar "Designs" section: the project's designs, newest first; tap to open. */
+export function DesignsSidebarPanel({ onNavigate }: { onNavigate?: () => void }) {
+  const projectName = useProjectStore((s) => s.activeProject?.name ?? "");
+  const [data, setData] = useState<DesignList | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [renaming, setRenaming] = useState<DesignSummary | null>(null);
+  const [deleting, setDeleting] = useState<DesignSummary | null>(null);
+
+  const load = useCallback(() => {
+    if (!projectName) return;
+    listDesigns(projectName)
+      .then((d) => { setData(d); setError(null); })
+      .catch((e) => setError((e as Error).message || "Could not load designs"));
+  }, [projectName]);
+
+  // Refetch after this client changes a design, and when design folders change on disk
+  // (an agent, a git checkout). Debounced: a new design arrives as a burst of file events.
+  useEffect(() => {
+    setData(null);
+    load();
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const later = () => { if (timer) clearTimeout(timer); timer = setTimeout(load, 500); };
+    const onFile = (e: Event) => {
+      const d = (e as CustomEvent<{ projectName?: string; path?: string }>).detail;
+      if (d?.projectName === projectName && /^designs\/[^/]+(\/(design\.json|index\.html))?$/.test(d.path ?? "")) later();
+    };
+    const onChanged = (e: Event) => {
+      if ((e as CustomEvent<{ projectName?: string }>).detail?.projectName === projectName) load();
+    };
+    window.addEventListener("file:changed", onFile);
+    window.addEventListener(DESIGNS_CHANGED_EVENT, onChanged);
+    return () => {
+      if (timer) clearTimeout(timer);
+      window.removeEventListener("file:changed", onFile);
+      window.removeEventListener(DESIGNS_CHANGED_EVENT, onChanged);
+    };
+  }, [projectName, load]);
+
+  const open = (d: DesignSummary) => {
+    openDesignTab({ projectName, slug: d.slug, title: d.title });
+    onNavigate?.();
+  };
+
+  if (!projectName) {
+    return <p className="p-4 text-center text-xs text-text-subtle">Select a project to see its designs</p>;
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex h-9 shrink-0 items-center justify-between border-b border-border px-2">
+        <span className="text-xs font-semibold uppercase tracking-wide text-text-secondary">Designs</span>
+        <button type="button" onClick={() => { requestNewDesign(projectName); onNavigate?.(); }} aria-label="New design"
+          className="flex size-11 items-center justify-center rounded-md text-text-subtle hover:bg-surface-elevated hover:text-foreground md:size-7">
+          <Plus className="size-4" />
+        </button>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto p-1">
+        {error ? (
+          <p className="px-2 py-3 text-xs text-destructive">{error}</p>
+        ) : data === null ? (
+          <div className="flex justify-center py-6"><Loader2 className="size-4 animate-spin text-primary" /></div>
+        ) : data.designs.length === 0 ? (
+          <div className="flex flex-col items-center gap-2 px-3 py-6 text-center text-xs text-text-subtle">
+            <Palette className="size-6" />
+            No designs yet. Start one and describe what you want; the AI builds it beside a live preview.
+            <button type="button" onClick={() => requestNewDesign(projectName)} className="min-h-11 px-3 text-sm text-primary underline">
+              New design
+            </button>
+          </div>
+        ) : data.designs.map((d) => {
+          const Icon = d.kind === "slides" ? Presentation : FileCode;
+          return (
+            <ContextMenu key={d.slug}>
+              <ContextMenuTrigger asChild>
+                <button type="button" onClick={() => open(d)}
+                  className="flex w-full min-h-11 select-none items-center gap-2 rounded-md px-2 py-1.5 text-left hover:bg-surface-elevated md:min-h-9">
+                  <Icon className="size-4 shrink-0 text-text-subtle" />
+                  <span className="min-w-0 flex-1">
+                    <span className="block truncate text-sm text-text-secondary">{d.title}</span>
+                    <span className="block truncate text-xs text-text-subtle">{formatRelativeDate(d.updatedAt)}</span>
+                  </span>
+                </button>
+              </ContextMenuTrigger>
+              <ContextMenuContent>
+                <ContextMenuItem onClick={() => open(d)}><Palette className="size-4" /> Open</ContextMenuItem>
+                <ContextMenuItem onClick={() => setRenaming(d)}><Pencil className="size-4" /> Rename</ContextMenuItem>
+                <ContextMenuSeparator />
+                <ContextMenuItem variant="destructive" onClick={() => setDeleting(d)}><Trash2 className="size-4" /> Delete</ContextMenuItem>
+              </ContextMenuContent>
+            </ContextMenu>
+          );
+        })}
+        {data && !data.system.designMd && data.designs.length > 0 && (
+          <p className="px-2 py-3 text-xs text-text-subtle">
+            No design system yet. Open a design and choose “Set up design system” to learn this project's look.
+          </p>
+        )}
+      </div>
+      {renaming && <RenameDesignDialog projectName={projectName} design={renaming} onClose={() => setRenaming(null)} />}
+      {deleting && <DeleteDesignDialog projectName={projectName} design={deleting} onClose={() => setDeleting(null)} />}
+    </div>
+  );
+}