@stigmer/react 3.0.9-dev.20260615145121 → 3.0.9-dev.20260615153829

package/src/execution/use-build-from-plan-hotkey.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { useCallback, type KeyboardEvent } from "react";
+
+/**
+ * Card-scoped `Cmd/Ctrl+Enter` accelerator for the "Build from plan" action.
+ *
+ * Returns an `onKeyDown` handler for a plan card's root element. Because it is
+ * attached to the card (not `window`), it fires only when the keystroke
+ * originates from within the card — so the SDK never installs a global listener
+ * that could hijack a host application's keyboard shortcuts (an embeddable-a11y
+ * requirement). The card's primary button stays natively activatable with
+ * Enter/Space when focused; this adds the power-user accelerator on top.
+ *
+ * No-op when there is no action wired or the action is disabled.
+ *
+ * Shared by {@link PlanArtifactCard} and {@link PlanCompletionCard} so the
+ * accelerator's behavior lives in exactly one place and cannot drift between
+ * the two cards.
+ */
+export function useBuildFromPlanHotkey(
+  onImplement: (() => void) | undefined,
+  disabled: boolean | undefined,
+): (event: KeyboardEvent<HTMLElement>) => void {
+  return useCallback(
+    (event) => {
+      if (
+        onImplement &&
+        !disabled &&
+        event.key === "Enter" &&
+        (event.metaKey || event.ctrlKey)
+      ) {
+        event.preventDefault();
+        onImplement();
+      }
+    },
+    [onImplement, disabled],
+  );
+}

package/src/internal/__tests__/markdown-components.test.tsx

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { unwrapEnclosingMarkdownFence } from "../markdown-components";
+
+describe("unwrapEnclosingMarkdownFence", () => {
+  describe("unwraps a whole-message markdown fence", () => {
+    it.each([
+      ["```markdown tag", "```markdown\n# Plan\n- step\n```", "# Plan\n- step"],
+      ["```md tag", "```md\n# Plan\n```", "# Plan"],
+      ["case-insensitive tag", "```Markdown\n# Plan\n```", "# Plan"],
+      ["uppercase md", "```MD\n# Plan\n```", "# Plan"],
+      [
+        "tilde-free body with inner code fence preserved",
+        "```markdown\n# Plan\n```ts\nconst x = 1;\n```\n```",
+        "# Plan\n```ts\nconst x = 1;\n```",
+      ],
+      [
+        "surrounding whitespace is ignored",
+        "\n\n```markdown\n# Plan\n```\n\n",
+        "# Plan",
+      ],
+      [
+        "longer-than-three backtick fence",
+        "````markdown\n# Plan\n````",
+        "# Plan",
+      ],
+    ])("%s", (_label, input, expected) => {
+      expect(unwrapEnclosingMarkdownFence(input)).toBe(expected);
+    });
+  });
+
+  describe("leaves everything else untouched (returns the original)", () => {
+    it.each([
+      ["plain markdown (no fence)", "# Plan\n\n- step one\n- step two"],
+      ["a bare ``` fence (ambiguous — could be code)", "```\n# Plan\n```"],
+      ["a language-tagged code block", "```js\nconsole.log('hi');\n```"],
+      ["an unclosed fence (mid-stream)", "```markdown\n# Plan in progr"],
+      ["trailing content after the fence", "```markdown\n# Plan\n```\nthen more"],
+      ["leading content before the fence", "intro\n```markdown\n# Plan\n```"],
+      ["a richer info string than markdown", "```markdown title\n# Plan\n```"],
+      ["an empty fenced block", "```markdown\n```"],
+      ["plain prose", "Here is the plan you asked for."],
+      ["empty string", ""],
+    ])("%s", (_label, input) => {
+      expect(unwrapEnclosingMarkdownFence(input)).toBe(input);
+    });
+  });
+
+  it("is idempotent — a once-unwrapped plan is left alone", () => {
+    const wrapped = "```markdown\n# Plan\n- a\n```";
+    const once = unwrapEnclosingMarkdownFence(wrapped);
+    expect(unwrapEnclosingMarkdownFence(once)).toBe(once);
+  });
+});

package/src/internal/markdown-components.tsx

@@ -26,6 +26,42 @@ export function stripFrontmatter(content: string): string {
   return content.replace(FRONTMATTER_RE, "");
 }
 
+/**
+ * Matches content whose ENTIRE body is a single fenced code block tagged
+ * `markdown` / `md`. Capture group 1 is the opening backtick run (so the close
+ * must use the same run via the `\1` backreference); group 2 is the inner body.
+ *
+ * Deliberately strict: the info string must be exactly `markdown`/`md` and the
+ * fence must span the whole (trimmed) string. A bare ``` ``` ``` fence is NOT
+ * matched — without the explicit language tag we cannot tell wrapped markdown
+ * from a legitimate single code block, and guessing by inspecting the body is
+ * the kind of fuzzy heuristic this codebase avoids.
+ */
+const ENCLOSING_MARKDOWN_FENCE_RE =
+  /^(`{3,})[ \t]*(?:markdown|md)[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/i;
+
+/**
+ * Unwraps a message the model wrapped entirely in a ```markdown / ```md fence.
+ *
+ * Some models emit their whole markdown reply inside one fenced block (a
+ * Plan-mode plan is the common case). Rendered as-is that becomes a single flat
+ * code block instead of rich markdown — headings, lists, and tables collapse to
+ * monospace text. This returns the inner markdown in exactly that case and is a
+ * no-op for everything else (already-rich markdown, prose, or a reply that is
+ * legitimately a single code block).
+ *
+ * Render-time only: callers pass it the text right before handing it to the
+ * markdown renderer, so the transcript and the raw artifact stay faithful to
+ * what the agent produced — a single source of truth for the unwrap, with no
+ * duplicated logic in the runner. While streaming, the closing fence has not
+ * arrived yet, so this no-ops and the live text renders as typed; it unwraps
+ * once the block closes.
+ */
+export function unwrapEnclosingMarkdownFence(content: string): string {
+  const match = ENCLOSING_MARKDOWN_FENCE_RE.exec(content.trim());
+  return match ? match[2] : content;
+}
+
 /**
  * Styled react-markdown component overrides for SDK markdown surfaces.
  *

package/src/portal-container.ts

@@ -5,12 +5,15 @@ import { createContext, useContext } from "react";
 /**
  * React context that holds a reference to the managed portal container.
  *
- * `StigmerProvider` creates a `<div>` appended to `document.body` with
- * the same scoping attributes (`class="stgm [preset]"`,
- * `data-stgm-color-mode`) as the main provider container. This ensures
- * that portaled content (popovers, dialogs, menus) inherits the correct
- * design token values — including dark-mode overrides — even though it
- * lives outside the provider's DOM subtree.
+ * `StigmerProvider` creates a `<div>` appended to `document.body` that
+ * carries the identical theme scope as the main provider container —
+ * the same class (`stgm` + preset class + any host `className`) and the
+ * same `data-stgm-color-mode`. Both containers derive this from a single
+ * source (`useThemeScope` in `provider.tsx`), so they cannot drift apart.
+ * This ensures portaled content (popovers, dialogs, menus) inherits the
+ * correct design token values — including dark-mode overrides and host
+ * `className`-scoped token overrides — even though it lives outside the
+ * provider's DOM subtree (where the cascade would otherwise not reach it).
  *
  * Defaults to `null` so components rendered outside a `StigmerProvider`
  * fall back to the browser's default portal target (`document.body`).

package/src/provider.tsx

@@ -1,6 +1,13 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import type { Stigmer, DeploymentMode } from "@stigmer/sdk";
 import { cn, resolvePresetClass } from "@stigmer/theme";
 import type { ThemePresetId } from "@stigmer/theme";
@@ -174,7 +181,8 @@ export function StigmerProvider({
 
   const presetClass = preset ? resolvePresetClass(preset) : "";
 
-  const portalContainer = usePortalContainer(resolvedMode, presetClass);
+  const scope = useThemeScope(resolvedMode, presetClass, className);
+  const portalContainer = usePortalContainer(scope);
   const registryState = useModelRegistryFetch(client);
   const taskKindRegistryState = useTaskKindRegistryFetch(client);
 
@@ -188,8 +196,8 @@ export function StigmerProvider({
                 <TaskKindRegistryContext.Provider value={taskKindRegistryState}>
                   <PortalContainerContext.Provider value={portalContainer}>
                     <div
-                      className={cn("stgm", presetClass, className)}
-                      data-stgm-color-mode={resolvedMode}
+                      className={scope.className}
+                      data-stgm-color-mode={scope.colorMode}
                     >
                       {children}
                     </div>
@@ -480,33 +488,72 @@ function useTaskKindRegistryFetch(client: Stigmer): TaskKindRegistryState {
   return { ...state, refetch };
 }
 
+/**
+ * The single scoping contract every Stigmer surface must carry so that
+ * `--stgm-*` tokens, preset overrides, dark-mode values, AND host
+ * `className` overrides resolve identically — whether a surface renders
+ * inline in the provider subtree or is portaled onto `document.body`.
+ */
+interface ThemeScope {
+  /** Class string: `stgm` + preset class + host `className`. */
+  readonly className: string;
+  /** Resolved color mode set as `data-stgm-color-mode`. */
+  readonly colorMode: ResolvedColorMode;
+}
+
+/**
+ * Computes the {@link ThemeScope} once per render input.
+ *
+ * Both the in-tree provider container and the managed portal container
+ * derive their class + `data-stgm-color-mode` from this single source,
+ * so the two can never drift apart — the cause of #182, where the portal
+ * container omitted the host `className` and portaled surfaces (popovers,
+ * dialogs, menus) lost host token overrides scoped to that class.
+ *
+ * The returned object is referentially stable until an input changes,
+ * which keeps {@link usePortalContainer}'s sync effect from re-running
+ * on every render.
+ */
+function useThemeScope(
+  resolvedMode: ResolvedColorMode,
+  presetClass: string,
+  className: string | undefined,
+): ThemeScope {
+  return useMemo(
+    () => ({
+      className: cn("stgm", presetClass, className),
+      colorMode: resolvedMode,
+    }),
+    [resolvedMode, presetClass, className],
+  );
+}
+
 /**
  * Creates and manages a portal container `<div>` appended to
- * `document.body` that mirrors the scoping attributes of the main
- * provider container.
+ * `document.body` that carries the identical {@link ThemeScope} as the
+ * main provider container.
  *
- * Portaled content (popovers, dialogs, menus) that targets this
- * element will inherit the correct `--stgm-*` token values —
- * including dark-mode overrides — because the container carries
- * `data-stgm-color-mode` and the preset class.
+ * Portaled content (popovers, dialogs, menus) that targets this element
+ * inherits the correct `--stgm-*` token values — including dark-mode
+ * overrides and any host `className` token overrides — because the
+ * container carries the same class and `data-stgm-color-mode` attribute
+ * as the in-tree scope. The node lives outside the provider subtree, so
+ * these must be set on the node directly rather than inherited via the
+ * DOM cascade.
  *
- * The element is created once on mount and removed on unmount.
- * Attribute values are kept in sync with prop changes via a
- * separate effect.
+ * The element is created once on mount and removed on unmount. Scope
+ * values are kept in sync with `scope` changes via a separate effect.
  *
  * Returns `null` during SSR (no `document`).
  */
-function usePortalContainer(
-  colorMode: ResolvedColorMode,
-  presetClass: string,
-): HTMLElement | null {
+function usePortalContainer(scope: ThemeScope): HTMLElement | null {
   const elRef = useRef<HTMLDivElement | null>(null);
   const [container, setContainer] = useState<HTMLElement | null>(null);
 
   useEffect(() => {
     const el = document.createElement("div");
-    el.className = cn("stgm", presetClass);
-    el.setAttribute("data-stgm-color-mode", colorMode);
+    el.className = scope.className;
+    el.setAttribute("data-stgm-color-mode", scope.colorMode);
     el.setAttribute("data-stgm-portal", "");
     document.body.appendChild(el);
     elRef.current = el;
@@ -517,15 +564,15 @@ function usePortalContainer(
       elRef.current = null;
     };
   // Intentionally empty deps: create once on mount, remove on unmount.
-  // Attribute syncing is handled by the effect below.
+  // Scope syncing is handled by the effect below.
   }, []);
 
   useEffect(() => {
     const el = elRef.current;
     if (!el) return;
-    el.className = cn("stgm", presetClass);
-    el.setAttribute("data-stgm-color-mode", colorMode);
-  }, [colorMode, presetClass]);
+    el.className = scope.className;
+    el.setAttribute("data-stgm-color-mode", scope.colorMode);
+  }, [scope]);
 
   return container;
 }

package/src/session/inspector/__tests__/ArtifactsTab.test.tsx

@@ -58,32 +58,32 @@ function openPreviewFor(name: string) {
 
 afterEach(cleanup);
 
-describe("ArtifactsTab — plan Implement wiring", () => {
-  it("shows Implement in the preview of a plan.md artifact", () => {
+describe("ArtifactsTab — plan 'Build from plan' wiring", () => {
+  it("shows 'Build from plan' in the preview of a plan.md artifact", () => {
     renderTab(vi.fn());
 
     openPreviewFor("plan.md");
 
     const dialog = document.querySelector("dialog")!;
-    expect(within(dialog).getByText("Implement")).toBeTruthy();
+    expect(within(dialog).getByText("Build from plan")).toBeTruthy();
   });
 
-  it("does not show Implement in the preview of a non-plan artifact", () => {
+  it("does not show 'Build from plan' in the preview of a non-plan artifact", () => {
     renderTab(vi.fn());
 
     openPreviewFor("notes.md");
 
     const dialog = document.querySelector("dialog")!;
-    expect(within(dialog).queryByText("Implement")).toBeNull();
+    expect(within(dialog).queryByText("Build from plan")).toBeNull();
   });
 
-  it("invokes onImplementPlan when Implement is clicked for a plan", () => {
+  it("invokes onImplementPlan when 'Build from plan' is clicked for a plan", () => {
     const onImplementPlan = vi.fn();
     renderTab(onImplementPlan);
 
     openPreviewFor("plan.md");
     const dialog = document.querySelector("dialog")!;
-    fireEvent.click(within(dialog).getByText("Implement"));
+    fireEvent.click(within(dialog).getByText("Build from plan"));
 
     expect(onImplementPlan).toHaveBeenCalledTimes(1);
   });