@stigmer/react 3.1.1 → 3.1.3

package/src/execution/PlanArtifactCard.tsx

@@ -1,10 +1,11 @@
 "use client";
 
-import { memo, useState } from "react";
+import { memo, useState, type ReactNode } from "react";
 import { cn } from "@stigmer/theme";
 import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { ArtifactPreviewModal } from "./ArtifactPreviewModal.js";
 import { formatArtifactSize } from "./artifact-utils.js";
+import { useArtifactCopy } from "./useArtifactCopy.js";
 import { useArtifactDownload } from "./useArtifactDownload.js";
 import { useBuildFromPlanHotkey } from "./use-build-from-plan-hotkey.js";
 
@@ -15,41 +16,56 @@ export interface PlanArtifactCardProps {
   /** The published `plan.md` artifact (from `findPlanArtifact`). */
   readonly artifact: ExecutionArtifact;
   /**
-   * Organization slug. Required for the "Open full" modal (the shared
+   * The plan's title (its leading `# H1`). The card is the plan's compact
+   * stand-in in the thread, so the title is what makes it recognizable.
+   * Falls back to "Plan" when omitted.
+   */
+  readonly title?: string;
+  /**
+   * Organization slug. Required for the open-in-modal fallback (the shared
    * {@link ArtifactPreviewModal} uses it for its detection/apply pipeline and
-   * to fetch the content). When omitted, "Open full" is hidden — the prominent
-   * "Build from plan" action and "Download" remain.
+   * to fetch the content). When omitted, that fallback is hidden — the
+   * prominent "Build" action and the download icon remain.
    */
   readonly org?: string;
-  /** Called when the user clicks "Build from plan". Hidden when omitted. */
+  /** Called when the user clicks "Build". Hidden when omitted. */
   readonly onImplement?: () => void;
+  /**
+   * Opens the plan in the session panel's plan document tab — the
+   * side-by-side review/refine surface. When provided it REPLACES the
+   * modal-based open fallback (one review affordance, not two). When
+   * omitted (hosts without a session panel) the same "Open plan" icon
+   * opens the preview modal instead.
+   */
+  readonly onOpenPlan?: () => void;
   /** Disables the primary CTA (e.g., while an execution is active). */
   readonly disabled?: boolean;
+  /** When true, the primary button reads "Starting build…" (upload in flight). */
+  readonly buildPending?: boolean;
   /** Additional CSS classes for the root element. */
   readonly className?: string;
 }
 
 /**
- * Action surface for a plan that a completed Plan-mode execution published as a
- * `plan.md` artifact.
+ * The compact plan card — a completed Plan turn's sole representation in the
+ * thread. The plan document itself lives in the session panel's plan tab
+ * (`PlanEditor`), Cursor-style: chat carries a recognizable, actionable card;
+ * the panel carries the document.
  *
- * It is rendered immediately below the plan message in the thread (which already
- * shows the plan as rich markdown — the message renderer unwraps a model's
- * enclosing markdown fence), so this card deliberately holds **no** plan
- * content: the message is the document and this is its action bar. Rendering
- * the plan a second time here would duplicate the same text the message and the
- * "Open full" modal already show.
+ * Anatomy: a document-style identity block (plan icon, the plan's title, a
+ * `<name> · size` meta line) with the actions trailing — open, copy, and
+ * download as icon-only secondaries (labelled via `aria-label`/`title`) and
+ * one prominent, themeable primary, **Build** — so the next step is
+ * unmistakable.
  *
- * The hierarchy is the point: one prominent, themeable primary action —
- * **Build from plan** — with **Open full** and **Download** as subdued
- * secondaries, so the next step is unmistakable. A small negative top margin
- * pulls the bar against the plan message so the two read as a single
- * first-class plan block.
+ * Action-label rule (shared with `PlanStreamingCard`, which keeps its
+ * labelled "Open plan"): a lone secondary keeps its text label; a row of
+ * secondaries competing with a primary collapses to icons, so the primary
+ * carries the card's one visible verb.
  *
- * Kept as its own thread item (not merged into the message) on purpose: merging
- * would change the streamed message item's identity at completion and remount
- * the just-streamed plan. Adjacent-and-attached gets the unified look with no
- * remount.
+ * Only the LATEST plan's card carries `onImplement`; a superseded plan's card
+ * is review-only (its `onOpenPlan` opens the document read-only), so a stale
+ * plan can never be implemented by accident.
  *
  * All visual properties flow through `--stgm-*` tokens; the component is
  * self-contained and embeddable.
@@ -57,67 +73,79 @@ export interface PlanArtifactCardProps {
 export const PlanArtifactCard = memo(function PlanArtifactCard({
   executionId,
   artifact,
+  title,
   org,
   onImplement,
+  onOpenPlan,
   disabled,
+  buildPending,
   className,
 }: PlanArtifactCardProps) {
   const [previewOpen, setPreviewOpen] = useState(false);
   const handleKeyDown = useBuildFromPlanHotkey(onImplement, disabled);
+  const { copy, isCopying, copied } = useArtifactCopy(executionId);
   const { download, isDownloading } = useArtifactDownload(executionId);
 
   return (
     <div
       role="region"
-      aria-label="Plan actions"
+      aria-label="Plan"
       onKeyDown={handleKeyDown}
       className={cn(
-        // `-mt-2` tightens the thread's `gap-4` so the bar attaches to the
-        // plan message above it, reading as one first-class plan block.
-        "mx-4 -mt-2 flex flex-wrap items-center gap-x-3 gap-y-2 rounded-md",
-        "border border-border-muted bg-muted-faint px-3 py-2",
+        "mx-4 flex flex-wrap items-center gap-x-3 gap-y-2 rounded-lg",
+        "border border-border-muted bg-card px-3 py-2.5",
         className,
       )}
     >
       <PlanIcon />
-      <span className="text-xs font-medium text-foreground">Plan</span>
-      <span className="text-xs tabular-nums text-muted-foreground-faint">
-        {formatArtifactSize(artifact.sizeBytes)}
-      </span>
+      <div className="min-w-0 flex-1 basis-48">
+        <div className="truncate text-sm font-medium text-foreground">
+          {title ?? "Plan"}
+        </div>
+        <div className="text-[0.65rem] text-muted-foreground-faint">
+          {artifact.name}
+          <span aria-hidden="true"> · </span>
+          <span className="tabular-nums">
+            {formatArtifactSize(artifact.sizeBytes)}
+          </span>
+        </div>
+      </div>
 
-      <div className="ml-auto flex flex-wrap items-center gap-x-3 gap-y-1.5">
-        {org && (
-          <button
-            type="button"
-            onClick={() => setPreviewOpen(true)}
-            className={cn(
-              "inline-flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground",
-              FOCUS_RING,
-            )}
-          >
-            <ExpandIcon />
-            Open full
-          </button>
+      <div className="ml-auto flex flex-wrap items-center gap-x-1.5 gap-y-1.5">
+        {onOpenPlan ? (
+          <IconAction
+            label="Open plan"
+            onClick={onOpenPlan}
+            icon={<EyeIcon />}
+          />
+        ) : (
+          org && (
+            <IconAction
+              label="Open plan"
+              onClick={() => setPreviewOpen(true)}
+              icon={<EyeIcon />}
+            />
+          )
         )}
-        <button
-          type="button"
+        <IconAction
+          label={copied ? "Copied" : isCopying ? "Copying…" : "Copy plan"}
+          onClick={() => copy(artifact.storageKey)}
+          disabled={isCopying}
+          icon={copied ? <CheckIcon /> : <CopyIcon />}
+        />
+        <IconAction
+          label={isDownloading ? "Preparing…" : `Download ${artifact.name}`}
           onClick={() => download(artifact.storageKey, artifact.name)}
           disabled={isDownloading}
-          className={cn(
-            "inline-flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground disabled:opacity-50",
-            FOCUS_RING,
-          )}
-        >
-          <DownloadIcon />
-          {isDownloading ? "Preparing…" : "Download"}
-        </button>
+          icon={<DownloadIcon />}
+        />
         {onImplement && (
           <button
             type="button"
             disabled={disabled}
             onClick={onImplement}
             className={cn(
-              "inline-flex items-center gap-1.5 rounded-md px-3 py-1.5",
+              "ml-1.5 inline-flex items-center gap-1.5 rounded-md px-3 py-1.5",
               "text-xs font-medium transition-colors",
               "bg-primary text-primary-foreground hover:bg-primary-hover",
               "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
@@ -125,13 +153,18 @@ export const PlanArtifactCard = memo(function PlanArtifactCard({
             )}
           >
             <ImplementIcon />
-            Build from plan
+            {buildPending ? "Starting build…" : "Build"}
           </button>
         )}
       </div>
 
-      {/* "Open full" reuses the shared artifact preview popup — the single place
-          that fetches/renders plan content (with Copy + Source/Rendered). */}
+      <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+        {copied && "Plan copied to clipboard"}
+      </div>
+
+      {/* The modal open fallback reuses the shared artifact preview popup —
+          the single place that fetches/renders plan content (with Copy +
+          Source/Rendered). */}
       {org && previewOpen && (
         <ArtifactPreviewModal
           artifact={artifact}
@@ -150,6 +183,41 @@ export const PlanArtifactCard = memo(function PlanArtifactCard({
 const FOCUS_RING =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:rounded-sm";
 
+/**
+ * An icon-only secondary action. The accessible name doubles as the hover
+ * tooltip (native `title` — the codebase's tooltip pattern), and the padded
+ * hit area keeps the target comfortable despite the compact glyph.
+ */
+function IconAction({
+  label,
+  onClick,
+  icon,
+  disabled,
+}: {
+  readonly label: string;
+  readonly onClick: () => void;
+  readonly icon: ReactNode;
+  readonly disabled?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      onClick={onClick}
+      disabled={disabled}
+      className={cn(
+        "inline-flex items-center rounded-md p-1.5 text-muted-foreground",
+        "transition-colors hover:bg-muted hover:text-foreground",
+        "disabled:pointer-events-none disabled:opacity-50",
+        FOCUS_RING,
+      )}
+    >
+      {icon}
+    </button>
+  );
+}
+
 function PlanIcon() {
   return (
     <svg
@@ -191,8 +259,8 @@ function ImplementIcon() {
 function DownloadIcon() {
   return (
     <svg
-      width="10"
-      height="10"
+      width="13"
+      height="13"
       viewBox="0 0 12 12"
       fill="none"
       stroke="currentColor"
@@ -209,21 +277,63 @@ function DownloadIcon() {
   );
 }
 
-function ExpandIcon() {
+function CopyIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0"
+      aria-hidden="true"
+    >
+      <rect x="4" y="4" width="6.5" height="6.5" rx="1" />
+      <path d="M8 4V2.5C8 1.95 7.55 1.5 7 1.5H2.5C1.95 1.5 1.5 1.95 1.5 2.5V7C1.5 7.55 1.95 8 2.5 8H4" />
+    </svg>
+  );
+}
+
+/** A check glyph — transient confirmation that the copy succeeded. */
+function CheckIcon() {
   return (
     <svg
-      width="10"
-      height="10"
+      width="13"
+      height="13"
       viewBox="0 0 12 12"
       fill="none"
       stroke="currentColor"
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
+      className="shrink-0 text-success"
+      aria-hidden="true"
+    >
+      <path d="M2 6.5L4.5 9L10 3" />
+    </svg>
+  );
+}
+
+/** An eye glyph — "view/open the plan to read it". */
+function EyeIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
       className="shrink-0"
       aria-hidden="true"
     >
-      <path d="M7 1.5h3.5V5M10.5 1.5L6.5 5.5M5 10.5H1.5V7M1.5 10.5l4-4" />
+      <path d="M1.5 8S4 3.5 8 3.5s6.5 4.5 6.5 4.5-2.5 4.5-6.5 4.5S1.5 8 1.5 8Z" />
+      <circle cx="8" cy="8" r="1.75" />
     </svg>
   );
 }

package/src/execution/PlanCompletionCard.tsx

@@ -6,7 +6,7 @@ import { useBuildFromPlanHotkey } from "./use-build-from-plan-hotkey.js";
 
 /** Props for {@link PlanCompletionCard}. */
 export interface PlanCompletionCardProps {
-  /** Called when the user clicks the "Build from plan" button. */
+  /** Called when the user clicks the "Build" button. */
   readonly onImplement?: () => void;
   /** Disables the CTA button (e.g., while an execution is active). */
   readonly disabled?: boolean;
@@ -20,9 +20,9 @@ export interface PlanCompletionCardProps {
  * a plan whose upload failed). When a plan artifact exists, the richer
  * `PlanArtifactCard` is shown instead.
  *
- * Mirrors `PlanArtifactCard`'s hierarchy — one prominent, themeable "Build from
- * plan" primary action with the same card-scoped `Cmd/Ctrl+Enter` accelerator —
- * so the two cards feel like the same affordance. The consumer wires the action
+ * Mirrors `PlanArtifactCard`'s hierarchy — one prominent, themeable "Build"
+ * primary action with the same card-scoped `Cmd/Ctrl+Enter` accelerator — so
+ * the two cards feel like the same affordance. The consumer wires the action
  * to switch the interaction mode to Agent and submit the implement turn.
  *
  * Renders nothing when `onImplement` is not provided, so the card is fully
@@ -67,7 +67,7 @@ export const PlanCompletionCard = memo(function PlanCompletionCard({
         )}
       >
         <ImplementIcon />
-        Build from plan
+        Build
       </button>
     </div>
   );

package/src/execution/PlanDocumentMessage.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { memo, useMemo } from "react";
+import { Streamdown } from "streamdown";
+import { cn } from "@stigmer/theme";
+import {
+  PLAN_DOCUMENT_MARKDOWN_COMPONENTS,
+  extractLeadingH1,
+  unwrapEnclosingMarkdownFence,
+} from "../internal/markdown-components.js";
+
+/** Props for {@link PlanDocumentMessage}. */
+export interface PlanDocumentMessageProps {
+  /** The plan message's markdown content (the agent's final Plan-mode reply). */
+  readonly content: string;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Renders a Plan-mode turn's plan as a first-class document instead of a chat
+ * bubble: a bordered card with a title header (the plan's leading `# H1`,
+ * lifted out of the prose) and document-grade typography
+ * ({@link PLAN_DOCUMENT_MARKDOWN_COMPONENTS}).
+ *
+ * This is the thread's NO-ARTIFACT fallback: a completed Plan turn that never
+ * published `plan.md` (older executions, a failed upload) keeps its plan
+ * inline via this component — the message is the only copy of the plan, so it
+ * must stay readable in place. A turn that DID publish the artifact collapses
+ * its plan message into the compact `PlanArtifactCard` instead, and the
+ * document renders in the session panel's plan tab (`PlanEditor`) with the
+ * same typography.
+ *
+ * Fence handling is plan-scoped: a plan wrapped in a whole-body fence is
+ * unwrapped even when the fence carries no language tag (`allowBareFence`) —
+ * a Plan turn's output is a markdown document by contract, so an enclosing
+ * bare fence is wrapping, not code. Render-time only; the transcript and the
+ * published artifact stay byte-faithful.
+ *
+ * Purely presentational — no data fetching, no state.
+ * All visual properties flow through `--stgm-*` tokens.
+ */
+export const PlanDocumentMessage = memo(function PlanDocumentMessage({
+  content,
+  className,
+}: PlanDocumentMessageProps) {
+  const { title, body } = useMemo(
+    () => extractLeadingH1(unwrapEnclosingMarkdownFence(content, true)),
+    [content],
+  );
+
+  return (
+    <div
+      role="article"
+      aria-label="Plan document"
+      className={cn("mx-4", className)}
+    >
+      <div className="overflow-hidden rounded-lg border border-border-muted bg-card">
+        <header className="flex items-center gap-2 border-b border-border-muted bg-muted-faint px-4 py-2.5">
+          <PlanDocIcon />
+          <span className="min-w-0 flex-1 truncate text-sm font-semibold text-foreground">
+            {title ?? "Plan"}
+          </span>
+        </header>
+        <div className="stgm-prose px-4 py-4">
+          <Streamdown
+            components={PLAN_DOCUMENT_MARKDOWN_COMPONENTS}
+            isAnimating={false}
+          >
+            {body}
+          </Streamdown>
+        </div>
+      </div>
+    </div>
+  );
+});
+
+function PlanDocIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M3 4h10M3 8h7M3 12h8" />
+      <path d="M12.5 10.5l1.5 1.5-1.5 1.5" />
+    </svg>
+  );
+}

package/src/execution/PlanStreamingCard.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+import { formatArtifactSize } from "./artifact-utils.js";
+
+/** Props for {@link PlanStreamingCard}. */
+export interface PlanStreamingCardProps {
+  /**
+   * The plan's title (its leading `# H1`), streaming in live. Falls back to
+   * "Writing plan…" until the title has arrived.
+   */
+  readonly title?: string;
+  /**
+   * Live size of the plan text streamed so far. An approximation (UTF-16
+   * length, not encoded bytes) — it exists to show growth while the agent
+   * writes, not to state the artifact's final size.
+   */
+  readonly sizeBytes: number;
+  /**
+   * Opens the panel's plan document tab, where the plan is rendering live.
+   * Always provided in practice: the thread only collapses a streaming plan
+   * behind this card when the host wired `onOpenPlan` (see `MessageThread`'s
+   * `collapseStreamingPlan` gate) — without a document surface there is
+   * nothing for the card to open, and the plan streams inline instead.
+   */
+  readonly onOpenPlan?: () => void;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+/**
+ * The live counterpart of {@link PlanArtifactCard} — a streaming Plan turn's
+ * compact stand-in in the thread while the plan document renders live in the
+ * session panel's plan tab. Same anatomy as the completed card (icon, title,
+ * a `Writing… · size` meta, trailing actions) so the completion handoff reads
+ * as the same card settling, not a new element appearing.
+ *
+ * The meta line deliberately omits a filename: the artifact's name is derived
+ * from the plan's title, which is still streaming in, so a name shown here
+ * would change under the user when the plan settles. The completed card
+ * introduces the final `<slug>_<id>.plan.md` name once it exists.
+ *
+ * Deliberately action-light: "Open plan" is the only affordance. Download and
+ * Build require the published artifact, which does not exist until the turn
+ * completes — at which point `buildThreadItems` swaps this item for the
+ * `plan-completion` item under the same list key.
+ *
+ * The pulsing icon is the progress affordance: a CSS animation inside `.stgm`,
+ * covered by the stylesheet's global `prefers-reduced-motion` rule (DD-015),
+ * and safe under virtualization (no `@starting-style`).
+ *
+ * All visual properties flow through `--stgm-*` tokens; the component is
+ * self-contained and embeddable.
+ */
+export const PlanStreamingCard = memo(function PlanStreamingCard({
+  title,
+  sizeBytes,
+  onOpenPlan,
+  className,
+}: PlanStreamingCardProps) {
+  return (
+    <div
+      role="region"
+      aria-label="Plan being written"
+      aria-busy="true"
+      className={cn(
+        "mx-4 flex flex-wrap items-center gap-x-3 gap-y-2 rounded-lg",
+        "border border-border-muted bg-card px-3 py-2.5",
+        className,
+      )}
+    >
+      <PlanIcon className="animate-pulse" />
+      <div className="min-w-0 flex-1 basis-48">
+        <div className="truncate text-sm font-medium text-foreground">
+          {title ?? "Writing plan…"}
+        </div>
+        <div className="text-[0.65rem] text-muted-foreground-faint">
+          <span role="status">Writing…</span>
+          <span aria-hidden="true"> · </span>
+          <span className="tabular-nums">{formatArtifactSize(sizeBytes)}</span>
+        </div>
+      </div>
+
+      {onOpenPlan && (
+        <button
+          type="button"
+          onClick={onOpenPlan}
+          className={cn(
+            "ml-auto inline-flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:rounded-sm",
+          )}
+        >
+          <EyeIcon />
+          Open plan
+        </button>
+      )}
+    </div>
+  );
+});
+
+function PlanIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn("shrink-0 text-muted-foreground-faint", className)}
+      aria-hidden="true"
+    >
+      <path d="M3 4h10M3 8h7M3 12h8" />
+      <path d="M12.5 10.5l1.5 1.5-1.5 1.5" />
+    </svg>
+  );
+}
+
+/** An eye glyph — "view/open the plan to read it" (matches PlanArtifactCard). */
+function EyeIcon() {
+  return (
+    <svg
+      width="11"
+      height="11"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0"
+      aria-hidden="true"
+    >
+      <path d="M1.5 8S4 3.5 8 3.5s6.5 4.5 6.5 4.5-2.5 4.5-6.5 4.5S1.5 8 1.5 8Z" />
+      <circle cx="8" cy="8" r="1.75" />
+    </svg>
+  );
+}