@drawnagency/primitives 0.1.110 → 0.1.112

package/src/deck-builder/DeckChatPanel.tsx

@@ -0,0 +1,334 @@
+import { ChevronRight, SquarePen } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ChatComposer } from "../components/chat/ChatComposer";
+import { IconButton } from "../components/shared/IconButton";
+import { MD_STYLES, USER_BUBBLE_CLASS, assistantHtml } from "../components/chat/markdown";
+import { cn } from "../lib/cn";
+import { ensureSanitizer } from "../lib/sanitize";
+import type { Deck } from "../schemas/deck";
+import {
+  DECK_CHAT_ERROR_COPY,
+  deckChatCanRetry,
+  streamDeckChat,
+  type DeckChatMessage,
+} from "./deck-chat-client";
+import { clearDeckChat, loadDeckChat, saveDeckChat } from "./deck-chat-history";
+
+/**
+ * The Deck Builder's docked assistant (#35) — the surface that makes the
+ * builder an authoring tool rather than a viewer.
+ *
+ * It is the ChatPanel IDIOM (h-16 header, `p-3` log, the shared composer and
+ * markdown treatment) rendered as an in-flow column rather than as
+ * ChatPanel itself: that component is bound to `/api/chat`'s contract, to the
+ * viewer/editor chrome it positions against, and to a task selector and history
+ * archive a deck conversation has no use for. What the two genuinely share —
+ * the composer, the assistant-markdown rules, the bubble treatment — is
+ * imported, not copied.
+ *
+ * "Chat authors, direct manipulation adjusts": this pane is the ~80% path, and
+ * `busy` is what #39's inline editing will lock against.
+ */
+
+interface Props {
+  deck: Deck;
+  /** The identity digest the Deck Draft is keyed by — the transcript is scoped
+   *  the same way, so two people sharing a browser never read each other's. */
+  scope: string;
+  /**
+   * The deck as of RIGHT NOW, for send time. The `deck` prop above comes from
+   * React state, which lags the Deck Draft by one round-trip — and pressing Send
+   * blurs an open inline field, so the author's last edit is routinely in that
+   * gap. Grounding a turn on the prop would post a deck they had just changed.
+   */
+  getDeck?: () => Deck | null;
+  /** A deck that PARSED server-side. The caller stages it; this pane never writes. */
+  onDeck: (deck: Deck) => void;
+  /** Streaming state, lifted so the shell can lock publish and (later) editing. */
+  onBusyChange?: (busy: boolean) => void;
+  /**
+   * The OTHER half of that lock. The shell sets this while it is doing
+   * something that reads or rewrites the draft row (publish, reopen, delete):
+   * a turn landing inside a publish's round-trip would have its `putDeckDraft`
+   * overwritten by the baseline that publish writes on the way out, and the
+   * author would lose the turn with no error anywhere.
+   */
+  disabled?: boolean;
+  onClose: () => void;
+}
+
+export function DeckChatPanel({ deck, getDeck, scope, onDeck, onBusyChange, disabled = false, onClose }: Props) {
+  const [messages, setMessages] = useState<DeckChatMessage[]>([]);
+  const [input, setInput] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [updating, setUpdating] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [canRetry, setCanRetry] = useState(false);
+  const [mdReady, setMdReady] = useState(false);
+  const streamingRef = useRef("");
+  const abortRef = useRef<AbortController | null>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  const composerRef = useRef<HTMLTextAreaElement>(null);
+  // Bumped by every run and by anything that replaces the transcript under one.
+  // Every post-await write is keyed to the generation it started in, so a turn
+  // that finishes after "New conversation" cannot resurrect the old transcript.
+  const runGenRef = useRef(0);
+  // The deck as of THIS render, read at send time: a turn always posts what the
+  // author can currently see, including a change the previous turn just made.
+  const deckRef = useRef(deck);
+  deckRef.current = deck;
+  const getDeckRef = useRef(getDeck);
+  getDeckRef.current = getDeck;
+
+  const deckId = deck.id;
+
+  const freshDeck = useCallback((): Deck => {
+    const fresh = getDeckRef.current?.();
+    return fresh !== null && fresh !== undefined && fresh.id === deckId ? fresh : deckRef.current;
+  }, [deckId]);
+
+  useEffect(() => {
+    // Invalidate any in-flight turn: it was asked about the PREVIOUS deck, and
+    // its tail would otherwise write that answer into this deck's transcript
+    // (and hand `onDeck` a deck under the wrong id). Reached only by a deckId
+    // swap on a LIVE instance: navigating to the grid unmounts this panel, which
+    // does not abort the stream — the shell's `editBase` is id-tagged for
+    // exactly that reason, since this guard cannot see it —
+    // but the props allow it, and the guard is one line.
+    runGenRef.current++;
+    setMessages(loadDeckChat(scope, deckId));
+    setNotice(null);
+    setCanRetry(false);
+  }, [scope, deckId]);
+
+  useEffect(() => {
+    let alive = true;
+    // Failure just leaves mdReady false forever (plain-text messages) — never
+    // let it surface as an unhandled rejection.
+    void ensureSanitizer()
+      .then(() => {
+        if (alive) setMdReady(true);
+      })
+      .catch(() => {});
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  // Stick to the newest tokens. Simpler than ChatPanel's pinned/jump-pill
+  // machinery on purpose: this column is short, and a deck turn is a sentence.
+  useEffect(() => {
+    const el = listRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [messages, updating]);
+
+  useEffect(() => {
+    onBusyChange?.(busy);
+  }, [busy, onBusyChange]);
+
+  const run = useCallback(
+    async (history: DeckChatMessage[]) => {
+      const gen = ++runGenRef.current;
+      const superseded = () => runGenRef.current !== gen;
+      setNotice(null);
+      setCanRetry(false);
+      setBusy(true);
+      setUpdating(false);
+      setMessages([...history, { role: "assistant", content: "" }]);
+      streamingRef.current = "";
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      const result = await streamDeckChat(
+        // The getter wins when it answers for THIS deck; a mismatch means the
+        // shell has moved on and the render-time prop is the honest answer.
+        { deck: freshDeck(), messages: history },
+        {
+          onText: (delta) => {
+            if (superseded()) return;
+            streamingRef.current += delta;
+            setMessages([...history, { role: "assistant", content: streamingRef.current }]);
+          },
+          onRetry: () => {
+            if (superseded()) return;
+            // The failed attempt's prose is not an answer to anything — drop it
+            // and say what is actually happening.
+            streamingRef.current = "";
+            setUpdating(true);
+            setMessages([...history, { role: "assistant", content: "" }]);
+          },
+        },
+        controller.signal,
+      );
+
+      abortRef.current = null;
+      setBusy(false);
+      setUpdating(false);
+      if (superseded()) return;
+
+      if (!result.ok) {
+        // The deck is untouched — that is the whole point of validating server
+        // side — so the transcript keeps the user's line and drops the stub.
+        setMessages(history);
+        // Persisted too. Without this the line is on screen but not in storage,
+        // so a reload silently swallows what the author just typed — and the
+        // Try again path is exactly when someone is most likely to reload.
+        saveDeckChat(scope, deckId, history);
+        setNotice(DECK_CHAT_ERROR_COPY[result.error] ?? DECK_CHAT_ERROR_COPY.upstream_error);
+        setCanRetry(deckChatCanRetry(result.error));
+        return;
+      }
+      // A turn is allowed to be nothing but a tool call, and observed models do
+      // exactly that (the prompt asks for a line first; it is not a guarantee).
+      // Without this the transcript ends on the user's message while the preview
+      // silently changes underneath it.
+      const reply = streamingRef.current || (result.deck ? "Updated the deck." : "");
+      const finished: DeckChatMessage[] = reply ? [...history, { role: "assistant", content: reply }] : history;
+      setMessages(finished);
+      saveDeckChat(scope, deckId, finished);
+      if (result.deck) onDeck(result.deck);
+      if (result.truncated) setNotice("Some brand content didn't fit — the assistant may not know everything on this site.");
+    },
+    [deckId, freshDeck, onDeck, scope],
+  );
+
+  const send = useCallback(
+    (override?: string) => {
+      const text = (override ?? input).trim();
+      if (!text || busy || disabled) return;
+      if (override === undefined) setInput("");
+      void run([...messages, { role: "user", content: text }]);
+    },
+    [busy, disabled, input, messages, run],
+  );
+
+  function retry() {
+    if (busy || messages.length === 0 || messages[messages.length - 1].role !== "user") return;
+    void run(messages);
+  }
+
+  function newConversation() {
+    if (busy) abortRef.current?.abort();
+    runGenRef.current++;
+    setMessages([]);
+    setNotice(null);
+    setCanRetry(false);
+    clearDeckChat(scope, deckId);
+    composerRef.current?.focus();
+  }
+
+  const lastIndex = messages.length - 1;
+
+  return (
+    <aside
+      data-deck-chat=""
+      aria-label="Deck assistant"
+      className="flex w-[var(--chat-w)] shrink-0 flex-col border-l border-base-200 bg-base"
+    >
+      <div className="flex h-16 shrink-0 items-center justify-between gap-2 border-b border-base-200 px-3">
+        <span className="text-sm font-medium text-base-contrast">Deck assistant</span>
+        <div className="flex items-center gap-1">
+          {messages.length > 0 && (
+            <IconButton
+              icon={<SquarePen size={16} />}
+              label="New conversation"
+              onClick={newConversation}
+              className="rounded-inner hover:bg-base-accent"
+            />
+          )}
+          <IconButton
+            icon={<ChevronRight size={18} />}
+            label="Hide deck assistant"
+            onClick={onClose}
+            className="rounded-inner hover:bg-base-accent"
+          />
+        </div>
+      </div>
+
+      <div ref={listRef} role="log" aria-label="Conversation" className="min-h-0 flex-1 space-y-3 overflow-y-auto p-3">
+        {messages.length === 0 && (
+          <div className="flex h-full flex-col justify-end gap-2 pb-1">
+            <p className="text-sm text-base-contrast-light">
+              Describe the deck you need and I'll build it from this portal's brand content.
+            </p>
+            <div className="mt-1 flex flex-wrap gap-1.5">
+              {["Build a five-slide brand overview", "Add a slide about our color palette"].map((suggestion) => (
+                <button
+                  key={suggestion}
+                  type="button"
+                  onClick={() => send(suggestion)}
+                  disabled={disabled}
+                  className="cursor-pointer rounded-full border border-base-200 bg-base-accent px-2.5 py-1 text-xs text-base-contrast hover:border-primary disabled:cursor-default disabled:opacity-50"
+                >
+                  {suggestion}
+                </button>
+              ))}
+            </div>
+          </div>
+        )}
+        {messages.map((m, i) =>
+          m.role === "user" ? (
+            <div key={i} className={USER_BUBBLE_CLASS}>
+              {m.content}
+            </div>
+          ) : m.content === "" ? (
+            busy && i === lastIndex ? (
+              <div key={i} className="text-sm text-base-contrast-light motion-safe:animate-pulse">
+                {updating ? "Fixing the deck…" : "Working on your deck…"}
+              </div>
+            ) : null
+          ) : mdReady ? (
+            <div
+              key={i}
+              className={cn("text-sm leading-relaxed text-base-contrast", MD_STYLES)}
+              dangerouslySetInnerHTML={{ __html: assistantHtml(m.content) }}
+            />
+          ) : (
+            <div key={i} className="text-sm leading-relaxed whitespace-pre-wrap text-base-contrast">
+              {m.content}
+            </div>
+          ),
+        )}
+        {notice && (
+          <p className="text-xs text-base-contrast-light">
+            {notice}
+            {canRetry && !busy && (
+              <button
+                type="button"
+                onClick={retry}
+                className="ml-2 cursor-pointer text-primary underline underline-offset-2"
+              >
+                Try again
+              </button>
+            )}
+          </p>
+        )}
+      </div>
+
+      {/* `aria-live` rather than role="status": the shell already owns a status
+          region for publish/notice, and a second one would give the builder two
+          places a screen reader (and a test) has to disambiguate between. This
+          is a transient announcement, not a landmark. */}
+      <p aria-live="polite" className="sr-only">
+        {busy ? (updating ? "Fixing the deck" : "Updating the deck") : ""}
+      </p>
+
+      <ChatComposer
+        value={input}
+        onChange={setInput}
+        onSend={() => send()}
+        onStop={() => abortRef.current?.abort()}
+        busy={busy}
+        // The placeholder deliberately does NOT change: the shell's `busy`
+        // covers publish and reload-published, so any wording here would be
+        // wrong half the time, and the window is sub-second.
+        disabled={disabled}
+        placeholder="Describe the change…"
+        textareaRef={composerRef}
+      />
+      <p className="shrink-0 border-t border-base-200 px-3 py-1 text-[10px] text-base-contrast-light">
+        Deck drafts stage on this device until you publish.
+      </p>
+    </aside>
+  );
+}

package/src/deck-builder/DeckEditor.tsx

@@ -0,0 +1,258 @@
+import { ChevronLeftIcon, CopyIcon, MoveLeftIcon, MoveRightIcon, Trash2Icon } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { Button } from "../components/shared/Button";
+import { cn } from "../lib/cn";
+import type { DeckTextPath } from "../lib/deck-edit";
+import type { Deck, DeckMediaAsset, DeckSlide } from "../schemas/deck";
+import { DeckSlideSurface, type DeckTextEditor } from "./DeckSlideSurface";
+import { useSortableSlide } from "./useSortableSlide";
+
+/**
+ * The deck-editing view (prototype variant A's arrangement): a back-link to the
+ * grid, the deck's own head row, a 16:9 stage, and a horizontal filmstrip of
+ * slide thumbnails BELOW it.
+ *
+ * Direct manipulation is #39's scope, and its boundary is the product decision
+ * recorded in CONTEXT.md — "chat authors, direct manipulation adjusts". What is
+ * here: editing a text leaf in place on the stage, and reorder / duplicate /
+ * delete on the strip. What is deliberately NOT here, and must not be added
+ * without revisiting that decision: layout switching, adding or removing a Deck
+ * Component, and grid composition. Those belong to the assistant.
+ */
+interface Props {
+  deck: Deck;
+  mediaAssets: Record<string, DeckMediaAsset>;
+  currentSlide: number;
+  onSelectSlide: (index: number) => void;
+  onBack: () => void;
+  /** Draft-vs-published state, spelled out under the title. */
+  statusLine: string;
+  onEditText: (path: DeckTextPath, text: string) => void;
+  /** `to` is the destination index in the post-removal list. */
+  onMoveSlide: (from: number, to: number) => void;
+  onDuplicateSlide: (index: number) => void;
+  onDeleteSlide: (index: number) => void;
+  /**
+   * A chat turn is in flight. Every manual affordance goes inert: a turn
+   * rewrites the whole deck, so an edit landing mid-stream would be overwritten
+   * with nothing anywhere saying so.
+   */
+  locked: boolean;
+}
+
+export function DeckEditor({
+  deck,
+  mediaAssets,
+  currentSlide,
+  onSelectSlide,
+  onBack,
+  statusLine,
+  onEditText,
+  onMoveSlide,
+  onDuplicateSlide,
+  onDeleteSlide,
+  locked,
+}: Props) {
+  const index = Math.min(Math.max(currentSlide, 0), deck.slides.length - 1);
+  const slide = deck.slides[index];
+  const [confirmingDelete, setConfirmingDelete] = useState(false);
+
+  // A pending confirmation belongs to the slide it was opened on — moving away
+  // (or a turn rewriting the deck under it) must not leave it armed.
+  //
+  // Keyed to the slide's IDENTITY, not to the index: a drag that moves a
+  // DIFFERENT slide into the selected position changes neither the index nor
+  // the slide count, so an index-keyed reset left "Delete slide 2?" armed and
+  // pointing at a slide the author never named.
+  useEffect(() => {
+    setConfirmingDelete(false);
+  }, [slide.id, index, deck.slides.length, locked]);
+
+  // Memoised: this is a context value, so a fresh object each render would
+  // re-render every text leaf on the stage on every keystroke elsewhere.
+  const editor = useMemo<DeckTextEditor>(() => ({ onEditText, disabled: locked }), [onEditText, locked]);
+
+  return (
+    <div className="mx-auto grid w-full max-w-screen-xl gap-3.5 px-4 pt-8 pb-16">
+      <button
+        type="button"
+        onClick={onBack}
+        className="inline-flex cursor-pointer items-center gap-1 self-start text-xs font-medium text-base-contrast-light transition-colors hover:text-base-contrast"
+      >
+        <ChevronLeftIcon size={14} aria-hidden="true" />
+        All decks
+      </button>
+
+      <div className="flex flex-wrap items-center gap-2.5">
+        <h1 className="font-body text-lg font-semibold text-base-contrast">{deck.title}</h1>
+        <p className="text-xs text-base-contrast-light">{statusLine}</p>
+      </div>
+
+      {/* The stage never grows past 52vh tall, so the filmstrip under it is on
+          screen without scrolling on a laptop. The strip matches its width so
+          the two read as one object. */}
+      <div className="aspect-video w-[min(100%,calc(52vh*16/9))] overflow-hidden rounded-[var(--radius-outer)] border border-base-200 shadow-md">
+        <DeckSlideSurface slide={slide} mediaAssets={mediaAssets} className="h-full" editor={editor} />
+      </div>
+
+      {/* Announced, not merely styled: the lock arrives while the author's
+          attention is on the chat, and a field that silently stops responding
+          is the failure this line exists to prevent. `aria-live` rather than
+          role="status" deliberately — the shell's notice owns that role, and two
+          status regions in one view is one too many for a screen reader and for
+          `getByRole("status")`. */}
+      <p aria-live="polite" data-deck-edit-hint="" className="min-h-4 text-xs text-base-contrast-light">
+        {locked
+          ? "Editing is paused while the assistant works on this deck."
+          : "Click any text on the slide to edit it. Drag a thumbnail to reorder."}
+      </p>
+
+      <ul
+        aria-label={`${deck.title} slides`}
+        className="flex w-[min(100%,calc(52vh*16/9))] gap-2 overflow-x-auto p-0.5"
+      >
+        {deck.slides.map((s, i) => (
+          <SlideThumb
+            key={s.id}
+            slide={s}
+            index={i}
+            mediaAssets={mediaAssets}
+            selected={i === index}
+            enabled={!locked}
+            onSelect={onSelectSlide}
+            onReorder={onMoveSlide}
+          />
+        ))}
+      </ul>
+
+      {/* Slide-level operations, on the SELECTED slide. Deliberately not a
+          hover menu on each thumbnail: at filmstrip size a per-tile control
+          strip covers the thing it is describing, and the selected slide is
+          already the one on the stage. */}
+      <div className="flex w-[min(100%,calc(52vh*16/9))] flex-wrap items-center gap-2">
+        <span className="text-xs text-base-contrast-light">
+          Slide {index + 1} of {deck.slides.length}
+        </span>
+        <Button
+          variant="ghost"
+          onClick={() => onMoveSlide(index, index - 1)}
+          disabled={locked || index === 0}
+          aria-label="Move slide earlier"
+        >
+          <MoveLeftIcon size={14} className="mr-1.5" aria-hidden="true" />
+          Earlier
+        </Button>
+        <Button
+          variant="ghost"
+          onClick={() => onMoveSlide(index, index + 1)}
+          disabled={locked || index === deck.slides.length - 1}
+          aria-label="Move slide later"
+        >
+          <MoveRightIcon size={14} className="mr-1.5" aria-hidden="true" />
+          Later
+        </Button>
+        <Button variant="ghost" onClick={() => onDuplicateSlide(index)} disabled={locked} aria-label="Duplicate slide">
+          <CopyIcon size={14} className="mr-1.5" aria-hidden="true" />
+          Duplicate
+        </Button>
+
+        {confirmingDelete ? (
+          <span className="flex flex-wrap items-center gap-2">
+            <span className="text-xs text-base-contrast">Delete slide {index + 1}?</span>
+            <Button
+              variant="destructive"
+              onClick={() => {
+                setConfirmingDelete(false);
+                onDeleteSlide(index);
+              }}
+            >
+              Delete
+            </Button>
+            <Button variant="ghost" onClick={() => setConfirmingDelete(false)}>
+              Cancel
+            </Button>
+          </span>
+        ) : (
+          <Button
+            variant="ghost"
+            onClick={() => setConfirmingDelete(true)}
+            disabled={locked || deck.slides.length === 1}
+            aria-label="Delete slide"
+          >
+            <Trash2Icon size={14} className="mr-1.5" aria-hidden="true" />
+            Delete
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function SlideThumb({
+  slide,
+  index,
+  mediaAssets,
+  selected,
+  enabled,
+  onSelect,
+  onReorder,
+}: {
+  slide: DeckSlide;
+  index: number;
+  mediaAssets: Record<string, DeckMediaAsset>;
+  selected: boolean;
+  enabled: boolean;
+  onSelect: (index: number) => void;
+  onReorder: (from: number, to: number) => void;
+}) {
+  const { ref, isDragging, closestEdge } = useSortableSlide<HTMLLIElement>({ index, onReorder, enabled });
+
+  return (
+    <li ref={ref} className="relative shrink-0">
+      {closestEdge && (
+        <span
+          aria-hidden="true"
+          className={cn(
+            "absolute inset-y-0 z-[3] w-0.5 bg-primary",
+            closestEdge === "left" ? "-left-1" : "-right-1",
+          )}
+        />
+      )}
+      {/* role="button" rather than a <button>: a rendered slide can carry
+          real buttons (the image grid's tiles), and nesting them is
+          invalid. Same reason the deck cards' thumbnails are divs. */}
+      <div
+        role="button"
+        tabIndex={0}
+        aria-current={selected ? "true" : undefined}
+        aria-label={slide.title ? `Slide ${index + 1}: ${slide.title}` : `Slide ${index + 1}`}
+        onClick={() => onSelect(index)}
+        onKeyDown={(event) => {
+          if (event.key !== "Enter" && event.key !== " ") return;
+          event.preventDefault();
+          onSelect(index);
+        }}
+        className={cn(
+          "relative aspect-video w-30 cursor-pointer overflow-hidden rounded border bg-base-accent transition-colors",
+          selected ? "border-primary shadow-[0_0_0_1px_var(--color-primary)]" : "border-base-200 hover:border-base-300",
+          isDragging && "opacity-40",
+        )}
+      >
+        {/* The thumbnail carries NO edit seam — `editor` is omitted, so the
+            same renderer produces the read-only markup here. */}
+        <div className="pointer-events-none h-full">
+          <DeckSlideSurface slide={slide} mediaAssets={mediaAssets} className="h-full" />
+        </div>
+        <span
+          aria-hidden="true"
+          className={cn(
+            "absolute bottom-0 left-0 z-[2] rounded-tr bg-base px-1 py-px text-[0.625rem] font-semibold",
+            selected ? "text-primary" : "text-base-contrast-light",
+          )}
+        >
+          {String(index + 1).padStart(2, "0")}
+        </span>
+      </div>
+    </li>
+  );
+}