@stigmer/react 3.1.1 → 3.1.2

package/src/execution/PlanArtifactCard.tsx

@@ -14,6 +14,12 @@ export interface PlanArtifactCardProps {
   readonly executionId: string;
   /** The published `plan.md` artifact (from `findPlanArtifact`). */
   readonly artifact: ExecutionArtifact;
+  /**
+   * 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 full" modal (the shared
    * {@link ArtifactPreviewModal} uses it for its detection/apply pipeline and
@@ -23,33 +29,36 @@ export interface PlanArtifactCardProps {
   readonly org?: string;
   /** Called when the user clicks "Build from plan". 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 full" secondary with "Open plan" (one review
+   * affordance, not two). When omitted (hosts without a session panel) the
+   * modal remains.
+   */
+  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.
- *
- * 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.
+ * 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.
  *
- * 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.
+ * Anatomy: a document-style identity block (plan icon, the plan's title, a
+ * `plan.md · size` meta line) with the actions trailing — **Open plan** and
+ * **Download** as subdued secondaries and one prominent, themeable primary,
+ * **Build from plan** — so the next step is unmistakable.
  *
- * 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,9 +66,12 @@ export interface PlanArtifactCardProps {
 export const PlanArtifactCard = memo(function PlanArtifactCard({
   executionId,
   artifact,
+  title,
   org,
   onImplement,
+  onOpenPlan,
   disabled,
+  buildPending,
   className,
 }: PlanArtifactCardProps) {
   const [previewOpen, setPreviewOpen] = useState(false);
@@ -69,35 +81,55 @@ export const PlanArtifactCard = memo(function PlanArtifactCard({
   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 && (
+        {onOpenPlan ? (
           <button
             type="button"
-            onClick={() => setPreviewOpen(true)}
+            onClick={onOpenPlan}
             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
+            Open plan
           </button>
+        ) : (
+          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>
+          )
         )}
         <button
           type="button"
@@ -125,7 +157,7 @@ export const PlanArtifactCard = memo(function PlanArtifactCard({
             )}
           >
             <ImplementIcon />
-            Build from plan
+            {buildPending ? "Starting build…" : "Build from plan"}
           </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,137 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+import { PLAN_ARTIFACT_NAME } from "../library/detect-plan-artifact.js";
+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,
+ * `plan.md · size` meta, trailing actions) so the completion handoff reads as
+ * the same card settling, not a new element appearing.
+ *
+ * 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">
+          {PLAN_ARTIFACT_NAME}
+          <span aria-hidden="true"> · </span>
+          <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",
+          )}
+        >
+          <ExpandIcon />
+          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>
+  );
+}
+
+function ExpandIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 12 12"
+      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" />
+    </svg>
+  );
+}

package/src/execution/__tests__/ArtifactContentRenderer.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { render, screen, fireEvent, cleanup } from "@testing-library/react";
 import { ArtifactContentRenderer } from "../ArtifactContentRenderer";
 
@@ -60,3 +60,82 @@ describe("ArtifactContentRenderer — markdown", () => {
     ).toBeGreaterThan(0);
   });
 });
+
+describe("ArtifactContentRenderer — reveal (jump-to-line)", () => {
+  let scrollIntoView: ReturnType<typeof vi.fn>;
+  beforeEach(() => {
+    // happy-dom lacks a real scrollIntoView; the hook calls it optionally.
+    scrollIntoView = vi.fn();
+    Element.prototype.scrollIntoView =
+      scrollIntoView as unknown as typeof Element.prototype.scrollIntoView;
+  });
+
+  it("renders addressable lines and highlights the target row for plain text", () => {
+    const { container } = render(
+      <ArtifactContentRenderer
+        content={"one\ntwo\nthree"}
+        fileName="notes.txt"
+        reveal={{ line: 2, nonce: 1 }}
+      />,
+    );
+
+    // Every line is addressable; exactly the target row carries the highlight.
+    expect(container.querySelectorAll("[data-line]").length).toBe(3);
+    const target = container.querySelector('[data-line="2"]');
+    expect(target?.className).toContain("bg-primary-subtle");
+    expect(container.querySelectorAll(".bg-primary-subtle").length).toBe(1);
+  });
+
+  it("does not highlight anything when the target line is out of range", () => {
+    const { container } = render(
+      <ArtifactContentRenderer
+        content={"one\ntwo"}
+        fileName="notes.txt"
+        reveal={{ line: 99, nonce: 1 }}
+      />,
+    );
+    expect(container.querySelectorAll(".bg-primary-subtle").length).toBe(0);
+  });
+
+  it("forces Markdown to its Source (line-faithful) view when revealing", () => {
+    const { container } = render(
+      <ArtifactContentRenderer
+        content={"# Heading\n\ntext"}
+        fileName="doc.md"
+        reveal={{ line: 1, nonce: 1 }}
+      />,
+    );
+    // Source is line-numbered <pre>, not the rendered <h1>.
+    expect(container.querySelector("h1")).toBeNull();
+    expect(container.querySelector("pre")).not.toBeNull();
+    expect(container.querySelector('[data-line="1"]')).not.toBeNull();
+    // The Rendered/Source toggle is still offered.
+    expect(screen.getByRole("tab", { name: "Source" })).toBeTruthy();
+  });
+
+  it("renders JSON raw (not reformatted) when revealing, so line numbers hold", () => {
+    // Minified single-line JSON: pretty-printing would expand it to many lines
+    // and shift line 1. Raw rendering keeps it one addressable row.
+    const { container } = render(
+      <ArtifactContentRenderer
+        content={'{"a":1,"b":2}'}
+        fileName="data.json"
+        reveal={{ line: 1, nonce: 1 }}
+      />,
+    );
+    const rows = container.querySelectorAll("[data-line]");
+    expect(rows.length).toBe(1);
+    expect(rows[0].textContent).toContain('{"a":1,"b":2}');
+  });
+
+  it("scrolls the target line into view", () => {
+    render(
+      <ArtifactContentRenderer
+        content={"one\ntwo\nthree"}
+        fileName="notes.txt"
+        reveal={{ line: 3, nonce: 1 }}
+      />,
+    );
+    expect(scrollIntoView).toHaveBeenCalled();
+  });
+});

package/src/execution/__tests__/FilePathLink.test.tsx

@@ -5,6 +5,7 @@ import {
   WorkspaceEntrySchema,
   WorkspaceSourceSchema,
   LocalPathSourceSchema,
+  GitRepoSourceSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import { FilePathLink } from "../FilePathLink";
@@ -89,4 +90,90 @@ describe("FilePathLink interaction", () => {
     expect(onFilePathClick.mock.calls[0][0]).toBe("src/main.go");
     expect(onFilePathClick.mock.calls[0][1].action).toBe("copy");
   });
+
+  it("falls back to copy when a copy-action handler declines (returns false)", async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+    const onFilePathClick = vi.fn().mockReturnValue(false);
+    render(
+      <FilePathContext.Provider value={{ workspaceEntries: [], onFilePathClick }}>
+        <FilePathLink path="src/main.go" />
+      </FilePathContext.Provider>,
+    );
+    fireEvent.click(screen.getByRole("button"));
+    expect(onFilePathClick).toHaveBeenCalledTimes(1);
+    expect(writeText).toHaveBeenCalledWith("src/main.go");
+    vi.unstubAllGlobals();
+  });
+
+  it("suppresses the copy default when a copy-action handler returns void", () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+    const onFilePathClick = vi.fn(); // returns undefined -> handled
+    render(
+      <FilePathContext.Provider value={{ workspaceEntries: [], onFilePathClick }}>
+        <FilePathLink path="src/main.go" />
+      </FilePathContext.Provider>,
+    );
+    fireEvent.click(screen.getByRole("button"));
+    expect(onFilePathClick).toHaveBeenCalledTimes(1);
+    expect(writeText).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});
+
+describe("FilePathLink link-action with an injected handler", () => {
+  const gitEntries = [
+    create(WorkspaceEntrySchema, {
+      name: "acme/app",
+      source: create(WorkspaceSourceSchema, {
+        source: {
+          case: "gitRepo",
+          value: create(GitRepoSourceSchema, {
+            url: "https://github.com/acme/app.git",
+            branch: "main",
+          }),
+        },
+      }),
+    }),
+  ];
+
+  it("renders a real <a href> even when a handler is present (native link semantics)", () => {
+    const onFilePathClick = vi.fn().mockReturnValue(true);
+    render(
+      <FilePathContext.Provider value={{ workspaceEntries: gitEntries, onFilePathClick }}>
+        <FilePathLink path="src/main.go" />
+      </FilePathContext.Provider>,
+    );
+    const anchor = screen.getByRole("link");
+    expect(anchor.getAttribute("href")).toBe(
+      "https://github.com/acme/app/blob/main/src/main.go",
+    );
+  });
+
+  it("prevents native navigation when the handler opens it in-app (returns true)", () => {
+    const onFilePathClick = vi.fn().mockReturnValue(true);
+    render(
+      <FilePathContext.Provider value={{ workspaceEntries: gitEntries, onFilePathClick }}>
+        <FilePathLink path="src/main.go" />
+      </FilePathContext.Provider>,
+    );
+    const evt = new MouseEvent("click", { bubbles: true, cancelable: true });
+    screen.getByRole("link").dispatchEvent(evt);
+    expect(onFilePathClick).toHaveBeenCalledTimes(1);
+    expect(evt.defaultPrevented).toBe(true);
+  });
+
+  it("leaves native navigation intact when the handler declines (returns false)", () => {
+    const onFilePathClick = vi.fn().mockReturnValue(false);
+    render(
+      <FilePathContext.Provider value={{ workspaceEntries: gitEntries, onFilePathClick }}>
+        <FilePathLink path="src/main.go" />
+      </FilePathContext.Provider>,
+    );
+    const evt = new MouseEvent("click", { bubbles: true, cancelable: true });
+    screen.getByRole("link").dispatchEvent(evt);
+    expect(onFilePathClick).toHaveBeenCalledTimes(1);
+    expect(evt.defaultPrevented).toBe(false);
+  });
 });