@stigmer/react 3.1.1 → 3.1.2

package/src/composer/__tests__/SessionComposer-contract.test.tsx

@@ -125,7 +125,7 @@ describe("SessionComposer — public contract", () => {
   });
 });
 
-describe("SessionComposer — imperative submit (Implement plan)", () => {
+describe("SessionComposer — imperative submit (Build from plan)", () => {
   it("submits a message with the interactionMode override, even when the picker is 'plan'", async () => {
     const ref = createRef<SessionComposerHandle>();
     const { onSubmit } = renderComposer({
@@ -134,13 +134,13 @@ describe("SessionComposer — imperative submit (Implement plan)", () => {
       interactionMode: "plan",
     });
 
-    ref.current!.submit("Implement the plan above", { interactionMode: "agent" });
+    ref.current!.submit("Build from plan", { interactionMode: "agent" });
 
     await waitFor(() => {
       expect(onSubmit).toHaveBeenCalledOnce();
     });
     const [message, , context] = onSubmit.mock.calls[0];
-    expect(message).toBe("Implement the plan above");
+    expect(message).toBe("Build from plan");
     // The override must win over the current picker value ("plan") so the
     // implement run executes in Agent mode regardless of render timing.
     expect(context?.interactionMode).toBe("agent");
@@ -150,7 +150,7 @@ describe("SessionComposer — imperative submit (Implement plan)", () => {
     const ref = createRef<SessionComposerHandle>();
     const { onSubmit } = renderComposer({ ref, disabled: true });
 
-    ref.current!.submit("Implement the plan above", { interactionMode: "agent" });
+    ref.current!.submit("Build from plan", { interactionMode: "agent" });
 
     expect(onSubmit).not.toHaveBeenCalled();
   });
@@ -163,4 +163,58 @@ describe("SessionComposer — imperative submit (Implement plan)", () => {
 
     expect(onSubmit).not.toHaveBeenCalled();
   });
+
+  it("carries caller-supplied attachments into the submit context (approved plan.md)", async () => {
+    const ref = createRef<SessionComposerHandle>();
+    const { onSubmit } = renderComposer({ ref });
+
+    const planAttachment = {
+      filename: "plan.md",
+      storageKey: "attachments/01ABC/plan.md",
+      mountPath: ".stigmer/inputs/plan.md",
+      contentType: "text/markdown",
+    };
+    ref.current!.submit("Build from plan", {
+      interactionMode: "agent",
+      attachments: [planAttachment],
+    });
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.attachments).toEqual([planAttachment]);
+    expect(context?.interactionMode).toBe("agent");
+  });
+
+  it("carries the buildFromPlan flag into the submit context", async () => {
+    const ref = createRef<SessionComposerHandle>();
+    const { onSubmit } = renderComposer({ ref });
+
+    ref.current!.submit("Build from plan", {
+      interactionMode: "agent",
+      buildFromPlan: true,
+    });
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.buildFromPlan).toBe(true);
+    expect(context?.interactionMode).toBe("agent");
+  });
+
+  it("leaves buildFromPlan unset for ordinary submissions", async () => {
+    const { onSubmit } = renderComposer();
+
+    const textarea = screen.getByRole("textbox");
+    fireEvent.change(textarea, { target: { value: "Hello world" } });
+    fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.buildFromPlan).toBeUndefined();
+  });
 });

package/src/execution/ArtifactContentRenderer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo, useState, type ReactNode } from "react";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
 import Markdown from "react-markdown";
 import { cn } from "@stigmer/theme";
 import {
@@ -8,6 +8,7 @@ import {
   REMARK_PLUGINS,
   unwrapEnclosingMarkdownFence,
 } from "../internal/markdown-components.js";
+import { useRevealLine, type RevealTarget } from "../internal/useRevealLine.js";
 import {
   getArtifactRenderMode,
   type ArtifactRenderMode,
@@ -29,6 +30,15 @@ export interface ArtifactContentRendererProps {
   readonly contentType?: string | null;
   /** When `true`, shows a truncation warning below the content. */
   readonly isTruncated?: boolean;
+  /**
+   * Optional jump-to-line request. When set, the content is rendered
+   * **line-faithfully** so the line number maps to the file's real rows —
+   * Markdown defaults to its Source view (a line only exists in source) and
+   * JSON renders raw rather than pretty-printed (reformatting would shift line
+   * numbers) — and the target line is scrolled into view and highlighted. Absent
+   * (the default), rendering is unchanged. See {@link RevealTarget}.
+   */
+  readonly reveal?: RevealTarget;
   /** Additional CSS classes for the root element. */
   readonly className?: string;
 }
@@ -76,6 +86,7 @@ export function ArtifactContentRenderer({
   fileName,
   contentType,
   isTruncated = false,
+  reveal,
   className,
 }: ArtifactContentRendererProps) {
   const mode = getArtifactRenderMode(fileName, contentType);
@@ -83,13 +94,19 @@ export function ArtifactContentRenderer({
   return (
     <div className={cn(className)}>
       {mode === "markdown" ? (
-        <MarkdownView content={content} />
+        <MarkdownView content={content} reveal={reveal} />
       ) : mode === "yaml" ? (
-        <YamlView content={content} />
+        <YamlView content={content} reveal={reveal} />
       ) : mode === "json" ? (
-        <JsonView content={content} />
+        // A reveal needs raw, line-faithful JSON: pretty-printing reformats the
+        // file and would shift the target line off its real row.
+        reveal ? (
+          <LineNumberedPre content={content} reveal={reveal} />
+        ) : (
+          <JsonView content={content} />
+        )
       ) : (
-        <PlainTextView content={content} />
+        <PlainTextView content={content} reveal={reveal} />
       )}
 
       {isTruncated && <TruncationWarning />}
@@ -103,8 +120,21 @@ export function ArtifactContentRenderer({
 
 type MarkdownTab = "rendered" | "source";
 
-function MarkdownView({ content }: { readonly content: string }) {
-  const [tab, setTab] = useState<MarkdownTab>("rendered");
+function MarkdownView({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  // A reveal targets a source line (the rendered HTML has no line concept), so
+  // default to — and, on every new reveal, return to — the Source view.
+  const [tab, setTab] = useState<MarkdownTab>(reveal ? "source" : "rendered");
+  // Keyed on the reveal nonce: each fresh jump-to-line returns to Source (where
+  // the line exists); switching to Rendered afterward sticks until the next hit.
+  useEffect(() => {
+    if (reveal) setTab("source");
+  }, [reveal?.nonce]);
 
   // A `.md` whose entire body is one ```markdown fence (e.g. a model-wrapped
   // plan) would render flat. Unwrap for the Rendered view only — Source stays
@@ -145,7 +175,7 @@ function MarkdownView({ content }: { readonly content: string }) {
           </Markdown>
         </div>
       ) : (
-        <LineNumberedPre content={content} />
+        <LineNumberedPre content={content} reveal={reveal} />
       )}
     </div>
   );
@@ -197,15 +227,6 @@ function TabButton({
  *
  * Values and block scalar content render in the default `text-foreground`.
  */
-function highlightYaml(content: string): ReactNode {
-  return content.split("\n").map((line, i) => (
-    <span key={i}>
-      {i > 0 && "\n"}
-      {highlightYamlLine(line)}
-    </span>
-  ));
-}
-
 function highlightYamlLine(line: string): ReactNode {
   if (!line.trim()) return line;
 
@@ -253,10 +274,38 @@ function highlightYamlValue(value: string): ReactNode {
   return <>{value}</>;
 }
 
-function YamlView({ content }: { readonly content: string }) {
+function YamlView({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  const { containerRef, isRevealed } = useRevealLine(reveal);
+  const lines = content.split("\n");
+
   return (
     <pre className="overflow-x-auto p-4 font-mono text-xs leading-relaxed text-foreground">
-      <code>{highlightYaml(content)}</code>
+      <code ref={containerRef}>
+        {lines.map((line, i) => (
+          <span
+            key={i}
+            data-line={i + 1}
+            className={cn(
+              // Transparent left border by default so revealing a line only
+              // changes its color — never shifts the text (no layout jump).
+              "block border-l-2 border-transparent",
+              isRevealed(i + 1) && "border-primary bg-primary-subtle",
+            )}
+          >
+            {/* whitespace-pre inner + `\n` fallback preserves indentation and
+                the height of blank lines, mirroring LineNumberedPre. */}
+            <span className="whitespace-pre">
+              {line.trim() ? highlightYamlLine(line) : "\n"}
+            </span>
+          </span>
+        ))}
+      </code>
     </pre>
   );
 }
@@ -345,19 +394,47 @@ function JsonView({ content }: { readonly content: string }) {
 // Plain text view (monospace + line numbers)
 // ---------------------------------------------------------------------------
 
-function PlainTextView({ content }: { readonly content: string }) {
-  return <LineNumberedPre content={content} />;
+function PlainTextView({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  return <LineNumberedPre content={content} reveal={reveal} />;
 }
 
-function LineNumberedPre({ content }: { readonly content: string }) {
+/**
+ * Line-numbered monospace view. The single line-faithful primitive behind plain
+ * text, Markdown Source, and reveal-mode JSON: every row is addressable
+ * (`data-line`), so a {@link RevealTarget} can scroll to and highlight a line
+ * (via {@link useRevealLine}). Absent a reveal it renders exactly as before.
+ */
+function LineNumberedPre({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  const { containerRef, isRevealed } = useRevealLine(reveal);
   const lines = content.split("\n");
   const gutterWidth = String(lines.length).length;
 
   return (
     <pre className="overflow-x-auto font-mono text-xs leading-relaxed text-foreground">
-      <code>
+      <code ref={containerRef}>
         {lines.map((line, i) => (
-          <span key={i} className="flex">
+          <span
+            key={i}
+            data-line={i + 1}
+            className={cn(
+              // Transparent left border by default so a reveal only recolors the
+              // row — never shifts its text (no layout jump).
+              "flex border-l-2 border-transparent",
+              isRevealed(i + 1) && "border-primary bg-primary-subtle",
+            )}
+          >
             <span
               className="sticky left-0 select-none bg-background pr-4 text-right text-muted-foreground"
               style={{ minWidth: `${gutterWidth + 2}ch` }}

package/src/execution/FilePathContext.tsx

@@ -18,11 +18,18 @@ export interface FilePathContextValue {
    * `FilePathLink` delegates to this callback instead of opening
    * a URL or copying to clipboard. Platform builders use this to
    * integrate their own file viewer or navigation.
+   *
+   * Return `false` to **decline** a specific path — `FilePathLink` then falls
+   * back to its default action (open the GitHub link / copy the path), so a
+   * handler that can only open *some* paths (e.g. resolvable workspace files)
+   * leaves the rest behaving as before. Returning `true` or `void` means the
+   * click was fully handled and the default is suppressed — preserving the
+   * behavior of existing `void`-returning handlers.
    */
   readonly onFilePathClick?: (
     path: string,
     resolved: ResolvedPathAction,
-  ) => void;
+  ) => boolean | void;
 }
 
 const DEFAULT_VALUE: FilePathContextValue = {

package/src/execution/FilePathLink.tsx

@@ -92,15 +92,26 @@ export function FilePathLink({
       // (ToolCallItem's role=button header); copying/opening a path must not
       // also expand the row.
       e.stopPropagation();
+
+      // Offer the click to the injected handler first. It returns `false` to
+      // DECLINE (e.g. an in-app viewer that can't open this particular path),
+      // in which case we fall through to the default action below. A `true`/
+      // `void` return means it fully handled the click.
       if (onFilePathClick) {
-        e.preventDefault();
-        onFilePathClick(path, resolved);
-        return;
+        const handled = onFilePathClick(path, resolved);
+        if (handled !== false) {
+          // For a link, also stop the browser from navigating (the file opened
+          // in-app instead). A modifier/middle-click bypasses this onClick, so
+          // the real <a href> still opens the target in a new tab.
+          if (resolved.action === "link") e.preventDefault();
+          return;
+        }
       }
+
       if (resolved.action === "copy") {
         handleCopy();
       }
-      // For "link" action the <a> default navigation handles it.
+      // For a declined/un-handled "link", the <a>'s native navigation runs.
     },
     [onFilePathClick, path, resolved, handleCopy],
   );
@@ -125,13 +136,18 @@ export function FilePathLink({
     </>
   );
 
-  if (resolved.action === "link" && !onFilePathClick) {
+  // A link-action path always renders a real anchor — even when an
+  // `onFilePathClick` handler is present — so native link affordances
+  // (middle-click, open-in-new-tab, copy-link-address) survive. `handleClick`
+  // intercepts a plain left-click to route it through the handler (e.g. into an
+  // in-app viewer) and only calls `preventDefault` when the handler took it.
+  if (resolved.action === "link") {
     return (
       <a
         href={resolved.url}
         target="_blank"
         rel="noopener noreferrer"
-        onClick={(e) => e.stopPropagation()}
+        onClick={handleClick}
         aria-label={ariaLabel}
         title={title}
         className={cn(sharedClasses, "group/fpl")}

package/src/execution/MessageEntry.tsx

@@ -3,12 +3,17 @@
 import { memo, useMemo, useState } from "react";
 import { Streamdown } from "streamdown";
 import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  MessageType,
+  type InteractionMode,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 import {
   MARKDOWN_COMPONENTS,
   unwrapEnclosingMarkdownFence,
 } from "../internal/markdown-components.js";
+import { InteractionModeBadge } from "./InteractionModeBadge.js";
+import { PlanDocumentMessage } from "./PlanDocumentMessage.js";
 import { useRenderTracer } from "../internal/dev/index.js";
 
 /** Props for {@link MessageEntry}. */
@@ -24,6 +29,34 @@ export interface MessageEntryProps {
    * this message for editing. Ignored for non-human messages.
    */
   readonly onEdit?: () => void;
+  /**
+   * Renders a `MESSAGE_AI` entry as a first-class plan document
+   * ({@link PlanDocumentMessage}) instead of a chat bubble. Set by the thread
+   * builder only on the NO-ARTIFACT fallback path: a completed Plan turn that
+   * never published `plan.md` (older executions, failed upload) keeps its
+   * plan inline — the message is the only copy of the plan. A turn that
+   * published the artifact collapses the message into the compact plan card
+   * instead (the document lives in the panel's plan tab). Ignored for non-AI
+   * messages.
+   */
+  readonly isPlanDocument?: boolean;
+  /**
+   * The turn's interaction mode, stamped by the thread builder on the
+   * synthetic prompt bubble (`MESSAGE_HUMAN`). Renders the
+   * {@link InteractionModeBadge} for non-default modes (a "Plan" pill), so
+   * the transcript reads unambiguously after mode switches. Ignored for
+   * non-human messages.
+   */
+  readonly interactionMode?: InteractionMode;
+  /**
+   * Renders a `MESSAGE_HUMAN` entry as a compact "Build from plan" chip
+   * instead of a prompt bubble. Stamped by the thread builder from
+   * `execution_config.build_from_plan`: the turn's message is a short label
+   * (the implement instruction is runner-injected), so a full-width bubble
+   * would dignify machine plumbing as user prose. Ignored for non-human
+   * messages.
+   */
+  readonly isBuildFromPlan?: boolean;
 }
 
 /**
@@ -54,6 +87,9 @@ export const MessageEntry = memo(function MessageEntry({
   message,
   className,
   onEdit,
+  isPlanDocument,
+  interactionMode,
+  isBuildFromPlan,
 }: MessageEntryProps) {
   useRenderTracer("MessageEntry", {
     messageType: message.type,
@@ -63,14 +99,27 @@ export const MessageEntry = memo(function MessageEntry({
 
   switch (message.type) {
     case MessageType.MESSAGE_HUMAN:
+      if (isBuildFromPlan) {
+        return (
+          <BuildFromPlanChip content={message.content} className={className} />
+        );
+      }
       return (
         <HumanMessage
           content={message.content}
           className={className}
           onEdit={onEdit}
+          interactionMode={interactionMode}
         />
       );
     case MessageType.MESSAGE_AI:
+      // A completed Plan turn's plan is a document, not a bubble. The flag is
+      // only ever set on a settled message, so the streaming path is untouched.
+      if (isPlanDocument) {
+        return (
+          <PlanDocumentMessage content={message.content} className={className} />
+        );
+      }
       return (
         <AiMessage
           content={message.content}
@@ -97,10 +146,12 @@ function HumanMessage({
   content,
   className,
   onEdit,
+  interactionMode,
 }: {
   content: string;
   className?: string;
   onEdit?: () => void;
+  interactionMode?: InteractionMode;
 }) {
   return (
     <div
@@ -111,6 +162,11 @@ function HumanMessage({
         className,
       )}
     >
+      {/* The badge renders only for non-default modes (a "Plan" pill), so
+          ordinary Agent turns carry no extra chrome. */}
+      {interactionMode !== undefined && (
+        <InteractionModeBadge mode={interactionMode} className="mb-1.5" />
+      )}
       <p className="text-sm text-foreground whitespace-pre-wrap">{content}</p>
       {onEdit && (
         <button
@@ -133,6 +189,60 @@ function HumanMessage({
   );
 }
 
+/**
+ * The Build-from-plan turn's user entry: a compact pill in the user-turn
+ * position (right-aligned, like the prompt bubble it replaces) carrying the
+ * plan glyph and the turn's short label. Deliberately not editable — the
+ * label is not user prose to rephrase; refining the plan happens in the plan
+ * document, and the build is re-triggered from its card.
+ */
+function BuildFromPlanChip({
+  content,
+  className,
+}: {
+  content: string;
+  className?: string;
+}) {
+  return (
+    <div
+      role="article"
+      aria-label="Build from plan"
+      className={cn("flex justify-end", className)}
+    >
+      <span
+        className={cn(
+          "inline-flex items-center gap-1.5 rounded-full border border-border",
+          "bg-muted-subtle px-3 py-1.5 text-xs font-medium text-foreground",
+        )}
+      >
+        <BuildFromPlanIcon />
+        {content}
+      </span>
+    </div>
+  );
+}
+
+/** The plan-card glyph (document lines + implement arrow) at chip scale. */
+function BuildFromPlanIcon() {
+  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 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>
+  );
+}
+
 function EditIcon() {
   return (
     <svg