@stigmer/react 3.1.2 → 3.1.4

package/src/internal/file-tree/FileTreeNode.tsx

@@ -102,7 +102,15 @@ export function FileTreeNode({
   );
 
   return (
-    <li role="treeitem" aria-expanded={isFolder ? expanded : undefined}>
+    <li
+      role="treeitem"
+      // Depth conveys tree nesting to assistive tech (indentation is visual
+      // only). aria-level is 1-based; `depth` is 0-based. aria-expanded stays on
+      // the treeitem (the <li>) — its child group is nested here, so this is the
+      // element a tree-aware screen reader reads expandability from.
+      aria-level={depth + 1}
+      aria-expanded={isFolder ? expanded : undefined}
+    >
       <button
         type="button"
         onClick={handleClick}
@@ -123,7 +131,10 @@ export function FileTreeNode({
         aria-current={isSelected ? "true" : undefined}
       >
         {isFolder && (
-          <span className="text-[10px] text-muted-foreground-subtle">
+          <span
+            aria-hidden="true"
+            className="text-[10px] text-muted-foreground-subtle"
+          >
             {expanded ? "▼" : "▶"}
           </span>
         )}

package/src/internal/markdown-components.tsx

@@ -1,10 +1,12 @@
-import type { ComponentProps, JSX } from "react";
+import { isValidElement, type ComponentProps, type JSX, type ReactNode } from "react";
 import type { Components } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { cn } from "@stigmer/theme";
 import { highlightToReact } from "./code-highlight.js";
+import { MermaidDiagram } from "./MermaidDiagram.js";
 
 const LANGUAGE_CLASS_PREFIX = "language-";
+const MERMAID_LANGUAGE_CLASS = "language-mermaid";
 
 type MdProps<T extends keyof JSX.IntrinsicElements> = ComponentProps<T>;
 
@@ -119,6 +121,30 @@ export function extractLeadingH1(markdown: string): {
   return { title: match[1], body: trimmed.slice(match[0].length) };
 }
 
+/**
+ * Returns the mermaid source when a `pre` element's children are a single
+ * fenced code block explicitly tagged `mermaid`, or `null` otherwise.
+ *
+ * Both renderers (Streamdown for chat, react-markdown for artifacts/skills)
+ * hand `pre` exactly one `<code>` child whose `className` carries the fence's
+ * info string as `language-*` and whose children are the raw source text.
+ * Anything that deviates from that shape — a different language, a missing
+ * tag, non-string children — is not a mermaid fence and keeps the ordinary
+ * code-block rendering. Only the explicit `mermaid` tag qualifies:
+ * inspecting fence bodies to guess diagram intent is the kind of fuzzy
+ * heuristic this codebase avoids.
+ */
+function extractMermaidSource(children: ReactNode): string | null {
+  if (!isValidElement(children)) return null;
+  const { className, children: code } = children.props as {
+    className?: unknown;
+    children?: unknown;
+  };
+  if (typeof className !== "string") return null;
+  if (!className.split(/\s+/).includes(MERMAID_LANGUAGE_CLASS)) return null;
+  return typeof code === "string" ? code : null;
+}
+
 /**
  * Styled react-markdown component overrides for SDK markdown surfaces.
  *
@@ -208,6 +234,15 @@ export const MARKDOWN_COMPONENTS: Components = {
   },
 
   pre({ children, ...props }: MdProps<"pre">) {
+    // A ```mermaid fence renders as a diagram, not a code block. The check
+    // lives here (not in the `code` override) because the diagram must
+    // replace the <pre> wrapper too — a block-level diagram container inside
+    // <pre> is invalid HTML and would inherit code-block chrome.
+    const mermaidSource = extractMermaidSource(children);
+    if (mermaidSource !== null) {
+      return <MermaidDiagram chart={mermaidSource} />;
+    }
+
     return (
       <pre
         className="mb-3 last:mb-0 overflow-x-auto rounded-md bg-muted p-3"

package/src/internal/mermaid-loader.ts

@@ -0,0 +1,44 @@
+/**
+ * Lazy loader for the `mermaid` library, isolated in its own module — the
+ * same seam pattern as `workflow/layout/elk-layout-engine.ts` — so
+ * {@link file://./MermaidDiagram.tsx} stays a pure presentation component and
+ * tests can mock the load outcome (resolve, reject) without touching module
+ * registries.
+ *
+ * `mermaid` is an optional peer dependency (DD-013): it is large, so it must
+ * never sit on the synchronous bundle path, and a host that has not installed
+ * it must degrade gracefully (the caller falls back to a code block).
+ */
+
+/**
+ * The mermaid API surface the SDK consumes, typed from the package itself so
+ * it stays in lockstep with the installed version.
+ */
+export type MermaidModule = typeof import("mermaid").default;
+
+/**
+ * Holds the in-flight import promise so concurrent diagrams share one load.
+ * A failed import clears the cache: rejections are often transient (a
+ * chunk-load hiccup mid-deploy), and caching one would break every diagram
+ * for the rest of the session.
+ */
+let mermaidImport: Promise<MermaidModule> | null = null;
+
+/**
+ * Dynamically imports `mermaid`, sharing one in-flight import across callers.
+ *
+ * @returns The mermaid default export.
+ * @throws If `mermaid` cannot be imported (not installed, or the async chunk
+ *   failed to load). Callers treat this as "diagrams unavailable" and render
+ *   the fenced source as a plain code block.
+ */
+export function loadMermaid(): Promise<MermaidModule> {
+  mermaidImport ??= import("mermaid").then(
+    (module) => module.default,
+    (error: unknown) => {
+      mermaidImport = null;
+      throw error;
+    },
+  );
+  return mermaidImport;
+}

package/src/internal/mermaid-theme-css.ts

@@ -0,0 +1,178 @@
+/**
+ * Token-driven `themeCSS` for Mermaid diagram interiors.
+ *
+ * Mermaid's built-in `default`/`dark` themes color a diagram's SVG interior
+ * with a fixed palette that ignores the host's `--stgm-*` preset (Corporate,
+ * Fintech, ...). The obvious fix — feeding resolved tokens into Mermaid's
+ * `themeVariables` — is blocked: our tokens are authored in `oklch()`, and
+ * Mermaid's color engine (`khroma`) parses only hex/rgb/hsl/keyword, so it
+ * throws or NaNs on `oklch(...)`. (Mermaid also gates every `themeVariables`
+ * value through the allowlist `^[\d "#%(),.;A-Za-z]+$`, which excludes `-` and
+ * would blank any `var(--...)`.)
+ *
+ * Instead we hand Mermaid this CSS via `initialize({ themeCSS })`. Mermaid
+ * injects it into the diagram's own `<style>` block, scoped under the render
+ * id (`#stgm-mermaid-N`), *after* the theme palette it computes. Because every
+ * selector in that block is id-prefixed, our rules and the palette's rules sit
+ * at equal specificity, so ours win by source order — and `!important` makes
+ * that bulletproof against the few palette rules that are themselves important
+ * or inlined. Crucially, `themeCSS` never passes through khroma, so the
+ * `oklch()`-backed `var(--stgm-*)` references flow straight to the browser,
+ * which resolves them against the `.stgm` scope the SVG lives in. That is why
+ * interiors track the active preset *and* color mode live, with no JS color
+ * reading and no re-render on theme change.
+ *
+ * `initialize({ theme })` still selects the built-in `default`/`dark` theme as
+ * the base, so any element or diagram type we do not target here degrades to
+ * Mermaid's stock palette — never a blank or mis-colored diagram.
+ *
+ * Palette intent (subtle surfaces + brand accents — legibility over brand
+ * saturation): node/actor bodies sit on a muted surface with quiet
+ * token-colored borders and edges; labels use the standard foreground; the
+ * brand `--stgm-primary` is reserved for structural headers (subgraph/cluster
+ * titles, sequence loop/section titles, the sequence-number badge).
+ *
+ * Coverage is the two families agents emit overwhelmingly — flowchart and
+ * sequence — plus the shared marker/edge-label chrome. Both label render paths
+ * are handled: SVG `text`/`tspan` (via `fill`) and HTML labels inside
+ * `foreignObject` (via `color`).
+ */
+export const MERMAID_THEME_CSS = `
+  /* Shared: edge arrowheads / markers */
+  .marker {
+    fill: var(--stgm-border) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .marker.cross {
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Flowchart: node bodies */
+  .node rect,
+  .node circle,
+  .node ellipse,
+  .node polygon,
+  .node path {
+    fill: var(--stgm-muted) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .node .neo-node {
+    stroke: var(--stgm-border) !important;
+  }
+  .node .katex path {
+    fill: var(--stgm-foreground) !important;
+    stroke: var(--stgm-foreground) !important;
+  }
+
+  /* Flowchart: node labels (SVG text and HTML spans) */
+  .label {
+    color: var(--stgm-foreground) !important;
+  }
+  .label text,
+  .label span {
+    fill: var(--stgm-foreground) !important;
+    color: var(--stgm-foreground) !important;
+  }
+
+  /* Flowchart: edges */
+  .edgePath .path,
+  .flowchart-link {
+    stroke: var(--stgm-border) !important;
+  }
+  .arrowheadPath,
+  .root .anchor path {
+    fill: var(--stgm-border) !important;
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Flowchart: edge labels sit on the diagram surface for legibility */
+  .edgeLabel,
+  .edgeLabel p,
+  .edgeLabel rect,
+  .labelBkg {
+    background-color: var(--stgm-card) !important;
+    fill: var(--stgm-card) !important;
+  }
+
+  /* Flowchart: subgraph clusters — muted surface, brand-accent title */
+  .cluster rect {
+    fill: var(--stgm-muted-subtle) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .cluster-label text,
+  .cluster text {
+    fill: var(--stgm-primary) !important;
+  }
+  .cluster-label span,
+  .cluster span {
+    color: var(--stgm-primary) !important;
+  }
+
+  /* Sequence: actors and lifelines */
+  .actor {
+    fill: var(--stgm-muted) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  text.actor > tspan {
+    fill: var(--stgm-foreground) !important;
+  }
+  .actor-line {
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Sequence: messages */
+  .messageLine0,
+  .messageLine1 {
+    stroke: var(--stgm-border) !important;
+  }
+  [id$="-arrowhead"] path,
+  [id$="-crosshead"] path {
+    fill: var(--stgm-border) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .messageText {
+    fill: var(--stgm-foreground) !important;
+  }
+
+  /* Sequence: number badge — brand accent with its paired foreground */
+  [id$="-sequencenumber"] {
+    fill: var(--stgm-primary) !important;
+  }
+  .sequenceNumber {
+    fill: var(--stgm-primary-foreground) !important;
+  }
+
+  /* Sequence: alt/opt/loop boxes and labels */
+  .labelBox {
+    fill: var(--stgm-muted-subtle) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .labelText,
+  .labelText > tspan {
+    fill: var(--stgm-foreground) !important;
+  }
+  .loopText,
+  .loopText > tspan,
+  .sectionTitle,
+  .sectionTitle > tspan {
+    fill: var(--stgm-primary) !important;
+  }
+  .loopLine {
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Sequence: notes and activations */
+  .note {
+    fill: var(--stgm-muted-subtle) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .noteText,
+  .noteText > tspan {
+    fill: var(--stgm-foreground) !important;
+  }
+  .activation0,
+  .activation1 {
+    fill: var(--stgm-muted) !important;
+    stroke: var(--stgm-border) !important;
+  }
+`;

package/src/internal/slug.ts

@@ -7,23 +7,27 @@
  *
  * Rules (applied in order):
  * 1. Convert to lowercase
- * 2. Replace spaces with hyphens
+ * 2. Replace spaces and dots (namespace separators) with hyphens
  * 3. Strip everything except `a-z`, `0-9`, and `-`
  * 4. Collapse consecutive hyphens into one
  * 5. Trim leading / trailing hyphens
  *
+ * Dots are treated as namespace separators (e.g. `platform.sara` → `platform-sara`),
+ * matching the backend generators, so namespace-scoped names stay readable.
+ *
  * @example
  * ```ts
- * generateSlug("My Cool Agent")  // "my-cool-agent"
- * generateSlug("Acme Corp!")     // "acme-corp"
- * generateSlug("  --hello-- ")   // "hello"
- * generateSlug("")               // ""
+ * generateSlug("My Cool Agent")             // "my-cool-agent"
+ * generateSlug("Acme Corp!")                // "acme-corp"
+ * generateSlug("  --hello-- ")              // "hello"
+ * generateSlug("platform.planton-arch")     // "platform-planton-arch"
+ * generateSlug("")                          // ""
  * ```
  */
 export function generateSlug(name: string): string {
   return name
     .toLowerCase()
-    .replace(/ /g, "-")
+    .replace(/[ .]/g, "-")
     .replace(/[^a-z0-9-]/g, "")
     .replace(/-{2,}/g, "-")
     .replace(/^-+|-+$/g, "");

package/src/library/__tests__/detect-plan-artifact.test.ts

@@ -9,6 +9,7 @@ import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agente
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import {
   isPlanArtifact,
+  isPlanArtifactName,
   findPlanArtifact,
   findLatestSessionPlan,
   PLAN_ARTIFACT_NAME,
@@ -35,11 +36,31 @@ function executionWithId(id: string, ...artifacts: ReturnType<typeof artifact>[]
   });
 }
 
+describe("isPlanArtifactName", () => {
+  it("accepts the legacy exact name and any *.plan.md", () => {
+    expect(isPlanArtifactName(PLAN_ARTIFACT_NAME)).toBe(true);
+    expect(isPlanArtifactName("feature_x.plan.md")).toBe(true);
+    // The runner's current shape: hyphenated slug + content-hash discriminator.
+    expect(isPlanArtifactName("fix-the-download-ux_a1b2c3d4.plan.md")).toBe(true);
+    expect(isPlanArtifactName("a1b2c3d4.plan.md")).toBe(true);
+  });
+
+  it("rejects non-plan filenames", () => {
+    expect(isPlanArtifactName("report.md")).toBe(false);
+    expect(isPlanArtifactName("plan.txt")).toBe(false);
+    expect(isPlanArtifactName("myplan.md")).toBe(false);
+  });
+});
+
 describe("isPlanArtifact", () => {
   it("is true for a FILE artifact named plan.md", () => {
     expect(isPlanArtifact(artifact({ name: PLAN_ARTIFACT_NAME }))).toBe(true);
   });
 
+  it("is true for a FILE artifact named <slug>_<id>.plan.md", () => {
+    expect(isPlanArtifact(artifact({ name: "plan-card-ux-cleanup_a1b2c3d4.plan.md" }))).toBe(true);
+  });
+
   it("is false for a directory named plan.md", () => {
     expect(
       isPlanArtifact(artifact({ name: "plan.md", kind: ExecutionArtifactKind.DIRECTORY })),

package/src/library/detect-plan-artifact.ts

@@ -3,26 +3,48 @@ import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agent
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 /**
- * The session's current plan: the published `plan.md` artifact of the most
- * recent execution that produced one, plus the execution it belongs to
- * (artifact content RPCs are execution-scoped).
+ * The session's current plan: the published plan artifact (a `*.plan.md` FILE)
+ * of the most recent execution that produced one, plus the execution it belongs
+ * to (artifact content RPCs are execution-scoped).
  */
 export interface SessionPlan {
   /** ID of the execution that published the plan. */
   readonly executionId: string;
-  /** The published `plan.md` artifact. */
+  /** The published plan artifact (`*.plan.md`). */
   readonly artifact: ExecutionArtifact;
 }
 
 /**
- * Canonical filename a Plan-mode execution publishes its plan under. Kept in
- * sync with the runner's `publishPlanArtifact` (shared/plan-artifact.ts).
+ * Legacy plan filename. Detection-only: {@link isPlanArtifactName} still
+ * accepts this exact name so plans published before named artifacts existed
+ * keep working. The runner never freshly emits it (a titleless plan falls back
+ * to a bare `<id>.plan.md`). Kept in sync with the runner's
+ * `PLAN_ARTIFACT_NAME` (shared/plan-artifact.ts).
  */
 export const PLAN_ARTIFACT_NAME = "plan.md";
 
 /**
- * Returns `true` when an artifact is the published plan: a FILE artifact named
- * `plan.md`.
+ * Suffix every named plan artifact carries (`<slug>_<id>.plan.md`, or a bare
+ * `<id>.plan.md` when untitled). The runner derives the slug from the plan's
+ * title and the `<id>` from its content hash; detection keys on this suffix.
+ * Kept in sync with the runner's `PLAN_ARTIFACT_SUFFIX` (shared/plan-artifact.ts)
+ * — the runner and browser SDK have disjoint module graphs, so the constant is
+ * duplicated by design, mirroring {@link PLAN_ARTIFACT_NAME}.
+ */
+export const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+
+/**
+ * Returns `true` when a filename is a plan's: the legacy exact `plan.md`, or
+ * any `*.plan.md`. Accepting the legacy name keeps plans published before named
+ * artifacts existed detectable.
+ */
+export function isPlanArtifactName(name: string): boolean {
+  return name === PLAN_ARTIFACT_NAME || name.endsWith(PLAN_ARTIFACT_SUFFIX);
+}
+
+/**
+ * Returns `true` when an artifact is the published plan: a FILE artifact whose
+ * name satisfies {@link isPlanArtifactName}.
  *
  * Detection is by convention — the same lightweight, content-free approach used
  * for skill packages ({@link isSkillPackage}) — so the UI never needs an extra
@@ -32,7 +54,7 @@ export const PLAN_ARTIFACT_NAME = "plan.md";
 export function isPlanArtifact(artifact: ExecutionArtifact): boolean {
   return (
     artifact.kind === ExecutionArtifactKind.FILE &&
-    artifact.name === PLAN_ARTIFACT_NAME
+    isPlanArtifactName(artifact.name)
   );
 }
 
@@ -56,7 +78,7 @@ export function findPlanArtifact(
 
 /**
  * Finds the session's LATEST plan across all executions — the plan the panel's
- * plan document tab edits and "Build from plan" implements. Executions are
+ * plan document tab edits and the "Build" action implements. Executions are
  * scanned newest-first (the array is chronological), mirroring the thread's
  * latest-plan-owns-the-build-action rule so every surface agrees on which
  * plan is current.

package/src/library/index.ts

@@ -26,9 +26,11 @@ export type { SkillPackageDetection } from "./detect-skill-package.js";
 
 export {
   isPlanArtifact,
+  isPlanArtifactName,
   findPlanArtifact,
   findLatestSessionPlan,
   PLAN_ARTIFACT_NAME,
+  PLAN_ARTIFACT_SUFFIX,
 } from "./detect-plan-artifact.js";
 export type { SessionPlan } from "./detect-plan-artifact.js";
 

package/src/session/PlanEditor.tsx

@@ -203,7 +203,7 @@ export function PlanEditor({
               >
                 <ImplementIcon />
                 <span className="truncate">
-                  {buildDisabled ? "Starting build…" : "Build from plan"}
+                  {buildDisabled ? "Starting build…" : "Build"}
                 </span>
               </button>
             )