@hienlh/ppm 0.22.11 → 0.23.1

package/src/web/components/layout/tab-bar.tsx

@@ -48,6 +48,7 @@ import { downloadFile } from "@/lib/file-download";
 import { copyToClipboard } from "@/lib/clipboard";
 import { FileActions } from "@/components/explorer/file-actions";
 import { getTabIcon } from "@/lib/tab-type-icons";
+import { tabSessionId } from "@/lib/tab-session-id";
 import {
   ContextMenu as BarContextMenu,
   ContextMenuContent as BarContextMenuContent,
@@ -83,7 +84,7 @@ export const TabBar = memo(function TabBar({ panelId }: TabBarProps) {
   const [sessionTagMap, setSessionTagMap] = useState<Record<string, { id: number; name: string; color: string }>>({});
 
   // Fetch session tags for open chat tabs
-  const chatSessionIds = tabs.filter((t) => t.type === "chat" && t.metadata?.sessionId).map((t) => t.metadata!.sessionId as string);
+  const chatSessionIds = tabs.map(tabSessionId).filter((id): id is string => !!id);
   useEffect(() => {
     if (!activeProject?.name || chatSessionIds.length === 0) return;
     api.get<{ sessions: { id: string; tag?: { id: number; name: string; color: string } | null }[] }>(
@@ -344,7 +345,7 @@ export const TabBar = memo(function TabBar({ panelId }: TabBarProps) {
       >
         <div className={tabRowClass(editorTabStyle, tabWrap)}>
           {tabs.map((tab, i) => {
-            const sessionId = tab.type === "chat" ? (tab.metadata?.sessionId as string) : undefined;
+            const sessionId = tabSessionId(tab);
             const entry = sessionId ? notifications.get(sessionId) : undefined;
             const notiType = entry && entry.count > 0 ? entry.type : null;
             const notiManual = !!entry?.manual;

package/src/web/components/layout/tab-content.tsx

@@ -89,6 +89,11 @@ const TAB_COMPONENTS: Record<TabType, React.LazyExoticComponent<React.ComponentT
       default: m.ProblemsPanel,
     })),
   ),
+  design: lazy(() =>
+    import("@/components/design/design-tab").then((m) => ({
+      default: m.DesignTab,
+    })),
+  ),
 };
 
 function LoadingFallback() {

package/src/web/components/layout/tab-pool.tsx

@@ -44,6 +44,7 @@ const TAB_COMPONENTS: Record<TabType, React.LazyExoticComponent<React.ComponentT
   "ai-resource": lazy(() => import("@/components/ai-resources/ai-resource-editor").then((m) => ({ default: m.AiResourceEditor }))),
   group: lazy(() => import("@/components/group-chat/group-chat-tab").then((m) => ({ default: m.GroupChatTab }))),
   problems: lazy(() => import("@/components/problems/problems-panel").then((m) => ({ default: m.ProblemsPanel }))),
+  design: lazy(() => import("@/components/design/design-tab").then((m) => ({ default: m.DesignTab }))),
 };
 
 const HIDDEN_CONTAINER_STYLE: React.CSSProperties = {

package/src/web/components/onboarding/onboarding-quick-orientation.tsx

@@ -14,6 +14,7 @@ export function openQuickOrientation(): void {
 const descriptions: Record<string, string> = {
   history: "Return to earlier AI conversations and continue where you left off.",
   teams: "Find group conversations with multiple AI agents.",
+  designs: "Design pages and slide decks with AI beside a live preview.",
   explorer: "Browse files and folders in the selected project.",
   search: "Find words across your project's files.",
   git: "Review changed files and diffs before committing your work.",

package/src/web/hooks/use-chat.ts

@@ -5,6 +5,7 @@ import { api, projectUrl } from "@/lib/api-client";
 import { flattenWithExpansions, prefixPreCompactIds } from "@/lib/flatten-expansions";
 import { useStreamingStore } from "@/stores/streaming-store";
 import { usePanelStore } from "@/stores/panel-store";
+import { tabSessionId } from "@/lib/tab-session-id";
 import { playNotificationSound } from "@/lib/notification-sounds";
 import { toast } from "sonner";
 import type { ChatMessage, ChatEvent } from "../../types/chat";
@@ -114,7 +115,7 @@ function isSessionTabActive(sid: string): boolean {
   const { panels } = usePanelStore.getState();
   for (const panel of Object.values(panels)) {
     const activeTab = panel.tabs.find((t) => t.id === panel.activeTabId);
-    if (activeTab?.type === "chat" && activeTab.metadata?.sessionId === sid) return true;
+    if (tabSessionId(activeTab) === sid) return true;
   }
   return false;
 }
@@ -466,9 +467,12 @@ export function useChat(
           // rate limit, usage cap or auth. Say so now rather than at the next usage poll.
           setLiveAccount({ id: ev.accountId, label: ev.accountLabel });
         }
-        // Clear previous streaming events (error text from failed attempt)
-        // and start fresh with only the retry notification
-        streamingEventsRef.current = [ev as ChatEvent];
+        // Append, never reset. A retry can land mid-turn — after tool calls and text that
+        // are already in the transcript — and the provider resumes that same turn, so
+        // clearing here hid everything before the retry until `done` reloaded history.
+        // The failed attempt itself adds nothing to clear: the provider swallows the
+        // error message instead of streaming it as text.
+        streamingEventsRef.current.push(ev as ChatEvent);
         syncMessages();
         break;
       }

package/src/web/hooks/use-design-session-redirect.ts

@@ -0,0 +1,39 @@
+import { useEffect } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { usePanelStore } from "@/stores/panel-store";
+import { openDesignTab } from "@/lib/design/open-design-tab";
+
+/**
+ * A plain chat tab that turns out to hold a design session hands itself over to that
+ * design's tab.
+ *
+ * Every surface that opens a session as a chat — a notification, a link, a list that does
+ * not know the session is a design one — would otherwise take it out of design mode: no
+ * canvas, and a history the design tab no longer owns. Asking once per session here covers
+ * all of them, including ones added later, instead of trusting each caller to route itself.
+ * The design tab is opened first (in the same panel) so the panel is never left empty.
+ */
+export function useDesignSessionRedirect(input: {
+  tabId?: string;
+  sessionId: string | null;
+  designSlug?: string;
+  projectName?: string;
+  providerId?: string;
+}) {
+  const { tabId, sessionId, designSlug, projectName, providerId } = input;
+  useEffect(() => {
+    if (!tabId || !sessionId || designSlug || !projectName) return;
+    const panel = usePanelStore.getState().getPanelForTab(tabId);
+    if (panel?.tabs.find((t) => t.id === tabId)?.type !== "chat") return;
+    let cancelled = false;
+    api.get<{ designSlug: string | null }>(`${projectUrl(projectName)}/chat/sessions/${encodeURIComponent(sessionId)}/design`)
+      .then(({ designSlug: slug }) => {
+        if (cancelled || !slug) return;
+        const panelId = usePanelStore.getState().getPanelForTab(tabId)?.id;
+        openDesignTab({ projectName, slug, sessionId, providerId, panelId });
+        usePanelStore.getState().closeTab(tabId, panelId);
+      })
+      .catch(() => { /* an unknown session stays a plain chat */ });
+    return () => { cancelled = true; };
+  }, [tabId, sessionId, designSlug, projectName, providerId]);
+}

package/src/web/hooks/use-design-session-state.ts

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useState } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { getAISettings } from "@/lib/api-settings";
+import { resolveNewChatProvider } from "@/lib/new-chat-provider";
+import { listDesignProviders } from "@/lib/design/api-designs";
+import { patchTabMetadata } from "@/lib/patch-tab-metadata";
+import { nextChatEpoch } from "@/lib/design/open-design-tab";
+import type { ChatForkRequest } from "@/components/chat/chat-tab";
+import type { SessionListResponse } from "../../types/chat";
+
+/**
+ * Which chat session a design tab's embedded chat runs, and on which provider.
+ *
+ * Settled before the chat mounts, for two reasons. A tab opened from a deep link knows only
+ * the slug, so its latest session is looked up (once — `designSessionChecked`) rather than a
+ * fresh one silently started beside it. And the provider must be one that carries design
+ * instructions: the chat's own new-tab gate would pick the default provider whatever it is.
+ *
+ * The chat is keyed on `designChatEpoch`, so replacing its session (a fork, a new session,
+ * a pick from history elsewhere) is a metadata write plus an epoch bump, never a second tab.
+ */
+
+export type DesignSessionStatus = "resolving" | "ready" | "no-provider" | "error";
+
+/** Sessions scanned for the design's latest one; the list is newest-first. */
+const ADOPT_SCAN_LIMIT = 200;
+
+export function useDesignSessionState(tabId: string, metadata: Record<string, unknown>) {
+  const [status, setStatus] = useState<DesignSessionStatus>("resolving");
+  const [attempt, setAttempt] = useState(0);
+  const projectName = String(metadata.projectName ?? "");
+  const slug = String(metadata.designSlug ?? "");
+  const sessionId = typeof metadata.sessionId === "string" ? metadata.sessionId : undefined;
+  const checked = metadata.designSessionChecked === true;
+  const pending = metadata.providerPending === true || typeof metadata.providerId !== "string";
+  const epoch = typeof metadata.designChatEpoch === "number" ? metadata.designChatEpoch : 0;
+
+  useEffect(() => {
+    if (!projectName || !slug) return;
+    let cancelled = false;
+    const run = async () => {
+      if (!sessionId && !checked) {
+        const params = new URLSearchParams({ limit: String(ADOPT_SCAN_LIMIT), offset: "0" });
+        const data = await api.get<SessionListResponse>(`${projectUrl(projectName)}/chat/sessions?${params}`);
+        if (cancelled) return;
+        const latest = data.sessions.find((s) => s.designSlug === slug);
+        patchTabMetadata(tabId, {
+          designSessionChecked: true,
+          ...(latest ? {
+            sessionId: latest.id, providerId: latest.providerId, providerPending: undefined,
+            designChatEpoch: epoch + 1,
+          } : {}),
+        });
+        return; // the write re-runs this effect with the new metadata
+      }
+      if (pending) {
+        const [settings, providers] = await Promise.all([getAISettings(), listDesignProviders(projectName)]);
+        if (cancelled) return;
+        const preferred = resolveNewChatProvider(settings);
+        const pick = providers.find((p) => p.id === preferred) ?? providers[0];
+        if (!pick) { setStatus("no-provider"); return; }
+        patchTabMetadata(tabId, { providerId: pick.id, providerPending: undefined });
+        return;
+      }
+      setStatus("ready");
+    };
+    setStatus((s) => (s === "ready" && !pending && (sessionId || checked) ? s : "resolving"));
+    run().catch((e) => {
+      console.warn(`[design] could not prepare the chat for ${slug}: ${(e as Error).message}`);
+      if (!cancelled) setStatus("error");
+    });
+    return () => { cancelled = true; };
+  }, [tabId, projectName, slug, sessionId, checked, pending, attempt]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const retry = useCallback(() => setAttempt((n) => n + 1), []);
+
+  /** `/clear` inside the design: the next session starts in this tab, in design mode. */
+  const startNewSession = useCallback((clearedFrom?: string) => {
+    patchTabMetadata(tabId, {
+      sessionId: undefined, pendingMessage: undefined, clearedFrom,
+      designSessionChecked: true, designChatEpoch: nextChatEpoch({ designChatEpoch: epoch }),
+    });
+  }, [tabId, epoch]);
+
+  /** A fork stays in the design: swap it in and let the remounted chat resend the message. */
+  const adoptFork = useCallback((fork: ChatForkRequest) => {
+    patchTabMetadata(tabId, {
+      sessionId: fork.sessionId, providerId: fork.providerId, pendingMessage: fork.pendingMessage,
+      designChatEpoch: nextChatEpoch({ designChatEpoch: epoch }),
+    });
+  }, [tabId, epoch]);
+
+  return { status, retry, epoch, sessionId: sessionId ?? null, startNewSession, adoptFork };
+}

package/src/web/hooks/use-global-events.ts

@@ -25,6 +25,9 @@ import { syncRunningSessions } from "@/lib/sync-running-sessions";
  * - `jira:*` → re-dispatched as window events.
  * - `tunnel:*` → re-dispatched as window events (named-tunnel setup flow —
  *   login URL/state, setup progress/done/pending/error).
+ * - `design:*` → re-dispatched as window events (`design:history_changed`,
+ *   `design:comments_changed`). A design's `.design/` folder is not watched, so these
+ *   are the only signal that its snapshots or comments changed.
  *
  * Also tells the server which project to watch, so file watching follows the
  * active project instead of depending on a chat socket existing.
@@ -95,7 +98,7 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
         return;
       }
 
-      if (type.startsWith("jira:") || type.startsWith("tunnel:")) {
+      if (type.startsWith("jira:") || type.startsWith("tunnel:") || type.startsWith("design:")) {
         window.dispatchEvent(new CustomEvent(type, { detail: data }));
       }
     });

package/src/web/hooks/use-session-history.ts

@@ -1,6 +1,6 @@
 import { useState, useEffect, useCallback, useRef } from "react";
 import { api, projectUrl } from "@/lib/api-client";
-import { useTabStore } from "@/stores/tab-store";
+import { openSessionInItsTab } from "@/lib/design/open-design-tab";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
 import { compareSessionsByActivity, type SessionInfo, type SessionListResponse, type ProjectTag } from "../../types/chat";
 
@@ -40,7 +40,6 @@ export function useSessionHistory({
   const [tagCounts, setTagCounts] = useState<Record<number, number>>({});
   const [showTagSettings, setShowTagSettings] = useState(false);
   const editInputRef = useRef<HTMLInputElement>(null);
-  const openTab = useTabStore((s) => s.openTab);
 
   const load = useCallback(async (query?: string) => {
     if (!projectName) return;
@@ -99,16 +98,11 @@ export function useSessionHistory({
   useEffect(() => { load(debouncedSearch || undefined); }, [debouncedSearch]); // eslint-disable-line react-hooks/exhaustive-deps
 
   function openSession(session: SessionInfo) {
-    if (onSelectSession) {
+    if (onSelectSession && !session.designSlug) {
       onSelectSession(session);
     } else {
-      openTab({
-        type: "chat",
-        title: session.title || "Chat",
-        projectId: projectName ?? null,
-        metadata: { projectName, sessionId: session.id, providerId: session.providerId },
-        closable: true,
-      });
+      // A design session opens in its design tab, where it stays in design mode.
+      openSessionInItsTab(session, projectName);
     }
   }
 

package/src/web/hooks/use-url-sync.ts

@@ -3,6 +3,8 @@ import { useTabStore, type TabType } from "@/stores/tab-store";
 import { useWindowStore } from "@/components/floating-window/window-store";
 import { openSettings } from "@/components/settings/open-settings";
 import { isMobileDevice } from "@/hooks/use-is-mobile";
+import { isValidDesignSlug } from "../../services/design/design-slug";
+import { designTabMetadata } from "@/lib/design/design-tab-metadata";
 
 // ---------------------------------------------------------------------------
 // URL state types
@@ -18,7 +20,7 @@ export interface UrlState {
 const VALID_TAB_TYPES: TabType[] = [
   "terminal", "chat", "editor", "database", "sqlite",
   "postgres", "git-diff", "settings",
-  "extension", "group",
+  "extension", "group", "design",
 ];
 
 // ---------------------------------------------------------------------------
@@ -110,7 +112,7 @@ export function tabIdFromUrl(tabType: TabType, tabIdentifier: string | null): st
 // Auto-open tab from URL
 // ---------------------------------------------------------------------------
 
-function buildMetadataFromUrl(
+export function buildMetadataFromUrl(
   type: TabType, identifier: string | null, projectName: string,
 ): Record<string, unknown> | null {
   switch (type) {
@@ -139,6 +141,11 @@ function buildMetadataFromUrl(
     }
     case "extension": return identifier ? { viewType: identifier, projectName } : null;
     case "group": return identifier ? { groupId: identifier, projectName } : null;
+    // The URL names the design only. The provider is resolved by the design tab itself,
+    // among the providers that can carry design instructions, which is why it is pending.
+    case "design": return isValidDesignSlug(identifier)
+      ? designTabMetadata({ projectName, designSlug: identifier })
+      : null;
     default: return null;
   }
 }
@@ -159,6 +166,7 @@ function buildTitleFromUrl(type: TabType, identifier: string | null): string {
       return identifier.split("-").map(w => (w[0]?.toUpperCase() ?? "") + w.slice(1)).join(" ");
     }
     case "group": return "Group";
+    case "design": return "Design";
     default: return type;
   }
 }

package/src/web/lib/design/api-design-comments.ts

@@ -0,0 +1,42 @@
+import { api, projectUrl } from "@/lib/api-client";
+import type { CommentAnchor, CommentQuote, DesignComment } from "../../../shared/design-comment-types";
+
+/**
+ * `/api/project/:name/designs/:slug/comments`. The server builds each element's snippet
+ * from the source file itself; nothing the page reported about its own markup is sent.
+ */
+
+const base = (projectName: string, slug: string) =>
+  `${projectUrl(projectName)}/designs/${encodeURIComponent(slug)}/comments`;
+
+export interface CommentPatch {
+  body?: string;
+  resolved?: boolean;
+  sent?: true;
+  anchor?: { ppmId: number; gen: string };
+}
+
+/** Normalised at the boundary: callers render the list straight away. */
+export async function listDesignComments(projectName: string, slug: string): Promise<DesignComment[]> {
+  const data = await api.get<DesignComment[] | null>(base(projectName, slug));
+  return Array.isArray(data) ? data : [];
+}
+
+export function createDesignComment(projectName: string, slug: string, anchor: CommentAnchor, body: string): Promise<DesignComment> {
+  return api.post<DesignComment>(base(projectName, slug), { file: anchor.file, anchor, body });
+}
+
+export function updateDesignComment(projectName: string, slug: string, id: string, patch: CommentPatch): Promise<DesignComment> {
+  return api.patch<DesignComment>(`${base(projectName, slug)}/${encodeURIComponent(id)}`, patch);
+}
+
+export function deleteDesignComment(projectName: string, slug: string, id: string): Promise<void> {
+  return api.del(`${base(projectName, slug)}/${encodeURIComponent(id)}`);
+}
+
+/** The server-built snippet for one element, without saving a comment. */
+export function designElementContext(
+  projectName: string, slug: string, anchor: CommentAnchor,
+): Promise<{ snippet: string | null; quote: CommentQuote }> {
+  return api.post<{ snippet: string | null; quote: CommentQuote }>(`${base(projectName, slug)}/context`, { anchor });
+}

package/src/web/lib/design/api-design-edits.ts

@@ -0,0 +1,62 @@
+import { getAuthToken, projectUrl } from "@/lib/api-client";
+import type { TransformProps } from "../../../shared/design-bridge-messages-transform";
+
+/**
+ * `/designs/:slug/style` (a move or resize from the canvas) and `/designs/:slug/undo`.
+ *
+ * Both do their own fetch, like the tweak commit: a 409 and a 429 are expected answers that
+ * the canvas reacts to (reload, reselect, slow down, point at History), and the shared
+ * client would turn their bodies into a bare `Error`.
+ */
+
+export type StylePatchOutcome =
+  | { status: "written"; gen: string; undoId: string | null }
+  | { status: "stale" | "element-moved"; message: string }
+  | { status: "rate-limited"; message: string };
+
+export type UndoOutcome =
+  | { status: "undone"; gen: string }
+  | { status: "cannot-undo" | "unknown"; message: string };
+
+const base = (projectName: string, slug: string) => `${projectUrl(projectName)}/designs/${encodeURIComponent(slug)}`;
+
+async function postJson(url: string, body: unknown): Promise<{ status: number; json: { ok?: boolean; error?: string; data?: Record<string, unknown> } }> {
+  const token = getAuthToken();
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-ppm-client": "web", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+    body: JSON.stringify(body),
+  });
+  try {
+    return { status: res.status, json: await res.json() };
+  } catch {
+    throw new Error(`Server error (HTTP ${res.status})`);
+  }
+}
+
+export async function postDesignStyle(
+  projectName: string,
+  slug: string,
+  body: { file: string; gen: string; ppmId: number; tag: string; props: TransformProps },
+): Promise<StylePatchOutcome> {
+  const { status, json } = await postJson(`${base(projectName, slug)}/style`, body);
+  const message = json.error || `HTTP ${status}`;
+  if (status === 409 && (json.data?.reason === "stale" || json.data?.reason === "element-moved")) {
+    return { status: json.data.reason, message };
+  }
+  if (status === 429) return { status: "rate-limited", message };
+  if (status >= 400 || json.ok === false) throw new Error(message);
+  const gen = json.data?.gen;
+  const undoId = json.data?.undoId;
+  if (typeof gen !== "string") throw new Error("The server did not say what it wrote");
+  return { status: "written", gen, undoId: typeof undoId === "string" ? undoId : null };
+}
+
+export async function undoDesignEdit(projectName: string, slug: string, undoId: string): Promise<UndoOutcome> {
+  const { status, json } = await postJson(`${base(projectName, slug)}/undo`, { undoId });
+  const message = json.error || `HTTP ${status}`;
+  if (status === 409) return { status: "cannot-undo", message };
+  if (status === 404) return { status: "unknown", message };
+  if (status >= 400 || json.ok === false) throw new Error(message);
+  return { status: "undone", gen: typeof json.data?.gen === "string" ? json.data.gen : "" };
+}

package/src/web/lib/design/api-design-tweaks.ts

@@ -0,0 +1,64 @@
+import { api, getAuthToken, projectUrl } from "@/lib/api-client";
+import type { TweakDef } from "../../../shared/design-tweaks";
+
+/**
+ * `/api/project/:name/designs/:slug/tweaks`. The commit carries variable names and values
+ * only; the server decides which declaration each one lands in.
+ *
+ * The commit does its own fetch (like `fs-api.ts`) because a stale gen is an expected
+ * answer, not a failure: the shared client turns every non-ok body into a bare `Error` and
+ * would drop the file and gen the 409 names.
+ */
+
+export interface DesignTweaksInfo {
+  manifestValid: boolean;
+  tweaks: TweakDef[];
+  errors: string[];
+}
+
+export type TweakCommitOutcome =
+  | { status: "applied"; gens: Record<string, string>; undoId: string | null }
+  | { status: "stale"; file: string; currentGen: string };
+
+const base = (projectName: string, slug: string) =>
+  `${projectUrl(projectName)}/designs/${encodeURIComponent(slug)}/tweaks`;
+
+/** Normalised at the boundary, so the panel can render whatever comes back. */
+export async function getDesignTweaks(projectName: string, slug: string): Promise<DesignTweaksInfo> {
+  const data = await api.get<Partial<DesignTweaksInfo> | null>(base(projectName, slug));
+  return {
+    manifestValid: data?.manifestValid === true,
+    tweaks: Array.isArray(data?.tweaks) ? data.tweaks : [],
+    errors: Array.isArray(data?.errors) ? data.errors.filter((e): e is string => typeof e === "string") : [],
+  };
+}
+
+export async function commitDesignTweaks(
+  projectName: string,
+  slug: string,
+  body: { entry: string; gens: Record<string, string>; values: Record<string, string> },
+): Promise<TweakCommitOutcome> {
+  const token = getAuthToken();
+  const res = await fetch(base(projectName, slug), {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-ppm-client": "web", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+    body: JSON.stringify(body),
+  });
+  let json: { ok?: boolean; error?: string; data?: Record<string, unknown> };
+  try {
+    json = await res.json();
+  } catch {
+    throw new Error(`Server error (HTTP ${res.status})`);
+  }
+  if (res.status === 409 && typeof json.data?.file === "string" && typeof json.data.currentGen === "string") {
+    return { status: "stale", file: json.data.file, currentGen: json.data.currentGen };
+  }
+  if (!res.ok || json.ok === false) throw new Error(json.error || `HTTP ${res.status}`);
+  const gens = json.data?.gens;
+  const undoId = json.data?.undoId;
+  return {
+    status: "applied",
+    gens: gens && typeof gens === "object" ? (gens as Record<string, string>) : {},
+    undoId: typeof undoId === "string" ? undoId : null,
+  };
+}

package/src/web/lib/design/api-designs.ts

@@ -0,0 +1,81 @@
+import { api, projectUrl } from "@/lib/api-client";
+import type {
+  DesignKind, DesignSnapshotInfo, DesignSummary, DesignSystemStatus,
+} from "../../../shared/design-types";
+import type { RestoreResult } from "../../../services/design/design-restore.service";
+
+/**
+ * The design REST surface (`/api/project/:name/designs`) and the canvas's preview-token
+ * calls (`/api/design-preview`). Paths are built from a project name and a slug only; the
+ * server derives every filesystem path itself.
+ */
+
+export interface DesignList {
+  designs: DesignSummary[];
+  system: DesignSystemStatus;
+}
+
+export interface DesignPreviewCapability {
+  /** Path of the entry page, without the per-load `?n=` nonce. */
+  url: string;
+  token: string;
+  expiresAt: number;
+  /** True when a refresh handed back a successor token (and URL) for the next load. */
+  rotated: boolean;
+}
+
+export interface DesignProvider {
+  id: string;
+  name: string;
+  supportsDesignInstructions?: boolean;
+}
+
+const base = (projectName: string) => `${projectUrl(projectName)}/designs`;
+const one = (projectName: string, slug: string) => `${base(projectName)}/${encodeURIComponent(slug)}`;
+
+/** Normalised at the boundary: every caller renders `designs` straight into a list. */
+export async function listDesigns(projectName: string): Promise<DesignList> {
+  const data = await api.get<Partial<DesignList> | null>(base(projectName));
+  return {
+    designs: Array.isArray(data?.designs) ? data.designs : [],
+    system: { designMd: !!data?.system?.designMd, tokensCss: !!data?.system?.tokensCss },
+  };
+}
+
+export function getDesign(projectName: string, slug: string): Promise<DesignSummary> {
+  return api.get<DesignSummary>(one(projectName, slug));
+}
+
+export function createDesign(projectName: string, input: { title: string; kind: DesignKind }): Promise<DesignSummary> {
+  return api.post<DesignSummary>(base(projectName), input);
+}
+
+export function renameDesign(projectName: string, slug: string, title: string): Promise<DesignSummary> {
+  return api.patch<DesignSummary>(one(projectName, slug), { title });
+}
+
+/** The server re-checks `confirm` against the slug, so a stray request cannot delete. */
+export function deleteDesign(projectName: string, slug: string): Promise<void> {
+  return api.del(`${one(projectName, slug)}?confirm=${encodeURIComponent(slug)}`);
+}
+
+export function listDesignHistory(projectName: string, slug: string): Promise<DesignSnapshotInfo[]> {
+  return api.get<DesignSnapshotInfo[]>(`${one(projectName, slug)}/history`);
+}
+
+export function restoreDesignSnapshot(projectName: string, slug: string, id: string): Promise<RestoreResult> {
+  return api.post<RestoreResult>(`${one(projectName, slug)}/history/${encodeURIComponent(id)}/restore`);
+}
+
+/** Mint a canvas token, or refresh `token` (which may hand back a rotated successor). */
+export function requestCanvasPreview(projectName: string, slug: string, token?: string): Promise<DesignPreviewCapability> {
+  return api.post<DesignPreviewCapability>("/api/design-preview", {
+    projectName, slug, purpose: "canvas", ...(token ? { token } : {}),
+  });
+}
+
+/** Providers that can host a design session: only they deliver the design instructions. */
+export async function listDesignProviders(projectName: string): Promise<DesignProvider[]> {
+  const providers = await api.get<DesignProvider[]>(`${projectUrl(projectName)}/chat/providers`);
+  return providers.filter((p) => p.supportsDesignInstructions === true);
+}

package/src/web/lib/design/deliver-to-design-chat.ts

@@ -0,0 +1,63 @@
+import { SEND_TO_CHAT_ACK_EVENT, SEND_TO_CHAT_EVENT, type SendToChatAck, type SendToChatDetail } from "@/lib/send-to-chat";
+import { patchTabMetadata } from "@/lib/patch-tab-metadata";
+
+/**
+ * Put text into ONE design tab's composer, for the user to review and send. Nothing the
+ * user asked for is ever sent on their behalf; the only message PPM sends by itself is the
+ * canvas self-check's report ({@link autoSendToDesignChat}).
+ *
+ * The composer answers an addressed "send to chat" event with an attachment chip; the
+ * event carries the design tab's own id because its embedded chat composer is keyed by it.
+ * A composer that is not mounted yet (the chat is still resolving its provider) gets the
+ * text as `pendingMessage` instead, which it shows as the input's prefill on mount.
+ *
+ * `DESIGN_SHOW_CHAT_EVENT` asks the tab to bring its chat into view, which on a phone means
+ * switching from the canvas to the chat pane.
+ */
+
+export const DESIGN_SHOW_CHAT_EVENT = "ppm:design-show-chat";
+
+export interface DesignShowChatDetail {
+  tabId: string;
+}
+
+export function deliverToDesignChat(tabId: string, text: string, label: string): void {
+  if (!tabId || !text.trim()) return;
+  let handled = false;
+  const onAck = () => { handled = true; };
+  window.addEventListener(SEND_TO_CHAT_ACK_EVENT, onAck);
+  try {
+    window.dispatchEvent(new CustomEvent<SendToChatDetail>(SEND_TO_CHAT_EVENT, {
+      detail: { text, label, targetTabId: tabId },
+    }));
+  } finally {
+    window.removeEventListener(SEND_TO_CHAT_ACK_EVENT, onAck);
+  }
+  if (!handled) patchTabMetadata(tabId, { pendingMessage: text });
+  showDesignChat(tabId);
+}
+
+/**
+ * PPM's own follow-up after a turn (the canvas self-check): sent straight into the design
+ * chat when its composer is idle and empty, so it lands in the transcript like any message;
+ * a chip beside whatever the user is typing otherwise, since their draft is theirs to send.
+ * `none` means no composer is mounted, and nothing was delivered.
+ */
+export function autoSendToDesignChat(tabId: string, text: string, label: string): "sent" | "chip" | "none" {
+  if (!tabId || !text.trim()) return "none";
+  let outcome: "sent" | "chip" | "none" = "none";
+  const onAck = (e: Event) => { outcome = (e as CustomEvent<SendToChatAck>).detail?.sent ? "sent" : "chip"; };
+  window.addEventListener(SEND_TO_CHAT_ACK_EVENT, onAck);
+  try {
+    window.dispatchEvent(new CustomEvent<SendToChatDetail>(SEND_TO_CHAT_EVENT, {
+      detail: { text, label, targetTabId: tabId, autoSend: true },
+    }));
+  } finally {
+    window.removeEventListener(SEND_TO_CHAT_ACK_EVENT, onAck);
+  }
+  return outcome;
+}
+
+export function showDesignChat(tabId: string): void {
+  window.dispatchEvent(new CustomEvent<DesignShowChatDetail>(DESIGN_SHOW_CHAT_EVENT, { detail: { tabId } }));
+}