@stigmer/react 3.1.17 → 3.2.0

package/src/workflow/useWorkflowExecutionGraph.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useMemo } from "react";
 import type { Node, Edge } from "@xyflow/react";
 import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import type { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
@@ -41,16 +41,6 @@ export interface UseWorkflowExecutionGraphOptions {
    */
   readonly taskStates?: ReadonlyMap<string, DerivedTaskState>;
 
-  /**
-   * Callback invoked once when the hook auto-selects a failed task
-   * on a terminal execution. The parent can wire this to its own
-   * `setSelectedTaskName` to keep the inspector in sync.
-   *
-   * Without this, auto-selection only affects the hook's internal
-   * `selectedTaskName` state and is invisible to sibling components.
-   */
-  readonly onAutoSelectTask?: (taskName: string) => void;
-
   /**
    * When `true`, non-sentinel nodes are marked `draggable: true` so
    * the parent component can allow ephemeral drag repositioning.
@@ -68,10 +58,6 @@ export interface UseWorkflowExecutionGraphReturn {
   readonly edges: Edge[];
   /** Current execution lifecycle phase. */
   readonly executionPhase: ExecutionPhase | undefined;
-  /** Currently selected task name in the graph. */
-  readonly selectedTaskName: string | null;
-  /** Set the selected task in the graph. */
-  readonly setSelectedTaskName: (name: string | null) => void;
   /** `true` while the graph model is being loaded (workflow fetch + parse). */
   readonly isLoading: boolean;
   /** Error from workflow fetch or graph building. */
@@ -87,13 +73,10 @@ export interface UseWorkflowExecutionGraphReturn {
    * the current definition as a fallback but this is an imprecise view.
    */
   readonly versionResolutionFailed: boolean;
-  /** Task states from the event stream (for the inspector). */
+  /** Task states from the event stream (for the graph's status overlays). */
   readonly taskStates: ReadonlyMap<string, DerivedTaskState>;
 }
 
-const EMPTY_TASK_STATES: ReadonlyMap<string, DerivedTaskState> = new Map();
-const TERMINAL_PHASES = new Set([3, 4, 5, 6]);
-
 type WorkflowFetchResult = {
   yaml: string;
   isVersionPinned: boolean;
@@ -130,11 +113,9 @@ async function fetchLiveWorkflowFallback(
 export function useWorkflowExecutionGraph(
   options: UseWorkflowExecutionGraphOptions,
 ): UseWorkflowExecutionGraphReturn {
-  const { executionId, onAutoSelectTask, nodesDraggable = false } = options;
+  const { executionId, nodesDraggable = false } = options;
   const stigmer = useStigmer();
 
-  const [selectedTaskName, setSelectedTaskName] = useState<string | null>(null);
-
   // ── Execution data: use external or fetch own ────────────────────
 
   const ownExecution = useWorkflowExecution(
@@ -377,31 +358,10 @@ export function useWorkflowExecutionGraph(
     ?? (!isLoading && !baseElements && effectiveWorkflowId ? "Unable to build workflow graph" : null)
     ?? null;
 
-  // ── Auto-select failed task (fires once on terminal phase) ───────
-
-  const didAutoSelectRef = useRef(false);
-
-  useEffect(() => {
-    if (didAutoSelectRef.current) return;
-    if (!phase || !TERMINAL_PHASES.has(phase)) return;
-    if (selectedTaskName) return;
-
-    for (const [name, state] of taskStates) {
-      if (state.status === "failed") {
-        didAutoSelectRef.current = true;
-        setSelectedTaskName(name);
-        onAutoSelectTask?.(name);
-        return;
-      }
-    }
-  }, [phase, taskStates, selectedTaskName, onAutoSelectTask]);
-
   return {
     nodes: nodesWithExecution,
     edges: edgesWithExecution,
     executionPhase: phase,
-    selectedTaskName,
-    setSelectedTaskName,
     isLoading,
     error,
     versionMismatch,

package/src/workflow/useWorkflowExecutionPanel.ts

@@ -0,0 +1,292 @@
+"use client";
+
+// State + actions for the workflow execution viewer's WorkspaceSurface panel.
+// Domain: workflow (the lean analog of session/useSessionPanel).
+
+import { useCallback, useMemo, useState } from "react";
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  useWorkspaceEditorsStoreRef,
+  type OpenFileOptions,
+  type WorkspaceEditorsStore,
+} from "../internal/store/index.js";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "../execution/artifact-document.js";
+import {
+  FILE_CHANGE_DOCUMENT_ENTRY_ID,
+  fileChangeTabPath,
+} from "../execution/file-change-document.js";
+import {
+  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
+  agentExecutionTabPath,
+} from "../execution/agent-execution-document.js";
+import {
+  DIAGNOSIS_DOCUMENT_ENTRY_ID,
+  DIAGNOSIS_DOCUMENT_PATH,
+} from "./diagnosis-document.js";
+
+/**
+ * The identity of a workflow artifact's document tab within the shared
+ * artifact-document family — the workflow analog of the session's
+ * `artifactKey`. Prefixed with the `Artifact` resource id (immutable,
+ * append-only store → a stable, unique identity) and suffixed with the
+ * display name because the editor tab's LABEL is the path's basename: a bare
+ * id would label the tab `art_01h…` instead of `report.json`.
+ */
+export function workflowArtifactTabPath(artifact: Artifact): string {
+  const id = artifact.metadata?.id ?? "";
+  const name =
+    artifact.spec?.displayName || artifact.metadata?.name || "Unnamed";
+  return `${id}/${name}`;
+}
+
+/**
+ * State + actions for the workflow execution panel — the SINGLE right-side
+ * `WorkspaceSurface` of `WorkflowExecutionViewer` (facets on the rail,
+ * documents in the editor area). Collapsed by default (thread-dominant);
+ * `isOpen` + `view` describe it fully.
+ *
+ * Deliberately NOT a shared extraction with `useSessionPanel`: the two
+ * controllers share the same primitives (the generic
+ * {@link WorkspaceEditorsStore} and the surface itself), but their document
+ * families and view semantics are domain-specific.
+ */
+export interface WorkflowExecutionPanelController {
+  /** The open-editor group store; subscribe with `useWorkspaceEditors`. */
+  readonly editorsStore: WorkspaceEditorsStore;
+  /** Whether the panel is expanded or collapsed to the chip. */
+  readonly isOpen: boolean;
+  /** The active rail view id (an injected facet — `"artifacts"` today). */
+  readonly view: string;
+  /** Expand the panel. */
+  readonly openPanel: () => void;
+  /** Collapse the panel to the chip, preserving editors and view. */
+  readonly closePanel: () => void;
+  /** Explicit view pick from the rail. */
+  readonly setView: (viewId: string) => void;
+  /**
+   * Open (or focus) the AI-diagnosis conversation as a pinned editor-pane
+   * document tab and expand the panel — the singleton analog of the
+   * session's `openPlanDocument`. Idempotent: the tab (not an owner-level
+   * boolean) is the single source of truth for "diagnosis is active", so
+   * re-invoking Diagnose focuses the existing conversation.
+   */
+  readonly openDiagnosis: () => void;
+  /**
+   * Open a file as a preview tab and expand the panel. Unused until a
+   * workspace-source slice wires a lister, but part of the controller's
+   * stable surface so the viewer's editor wiring never changes shape.
+   */
+  readonly openFile: (
+    entryId: string,
+    path: string,
+    options?: OpenFileOptions,
+  ) => void;
+  /** Focus an already-open editor tab. */
+  readonly activateEditor: (entryId: string, path: string) => void;
+  /** Pin an editor tab (clear its preview state). */
+  readonly pinEditor: (entryId: string, path: string) => void;
+  /** Close an editor tab. The panel stays open when the group empties. */
+  readonly closeEditor: (entryId: string, path: string) => void;
+  /**
+   * Open (or focus) an artifact as an editor-pane document tab and expand the
+   * panel. Uses the PREVIEW slot — casual artifact browsing reuses one tab
+   * (single-click) and double-clicking pins it, matching the session panel's
+   * artifact-tab semantics.
+   */
+  readonly openArtifact: (artifact: Artifact) => void;
+  /**
+   * Pin an artifact's tab — the double-click half of the open/activate split.
+   * A no-op if the artifact is not open.
+   */
+  readonly pinArtifact: (artifact: Artifact) => void;
+  /**
+   * Open (or focus) a file change's diff as an editor-pane document tab and
+   * expand the panel. Same preview-slot semantics as {@link openArtifact} —
+   * the slot is shared across families, so casually browsing changes and
+   * artifacts reuses one tab (true VS Code behavior).
+   */
+  readonly openFileChange: (change: FileChange) => void;
+  /**
+   * Pin a file change's diff tab — the double-click half of the
+   * open/activate split. A no-op if the change is not open.
+   */
+  readonly pinFileChange: (change: FileChange) => void;
+  /**
+   * Open (or focus) a child AgentExecution's transcript as an editor-pane
+   * document tab and expand the panel — the S4 in-place expansion. Same
+   * preview-slot semantics as {@link openArtifact}: casually stepping
+   * through agent calls reuses one tab; pinning keeps one around.
+   */
+  readonly openAgentExecution: (
+    childExecutionId: string,
+    taskName: string,
+  ) => void;
+  /**
+   * Pin a child AgentExecution's transcript tab — the double-click half of
+   * the open/activate split. A no-op if the transcript is not open.
+   */
+  readonly pinAgentExecution: (
+    childExecutionId: string,
+    taskName: string,
+  ) => void;
+}
+
+/** Options for {@link useWorkflowExecutionPanel}. */
+export interface UseWorkflowExecutionPanelOptions {
+  /**
+   * The panel's home view. Defaults to `"artifacts"` — the one facet this
+   * panel carries today (there is no workspace file source yet, so no
+   * built-in Explorer to land on).
+   * @default "artifacts"
+   */
+  readonly defaultView?: string;
+}
+
+/**
+ * Create a {@link WorkflowExecutionPanelController} for a viewer instance.
+ */
+export function useWorkflowExecutionPanel({
+  defaultView = "artifacts",
+}: UseWorkflowExecutionPanelOptions = {}): WorkflowExecutionPanelController {
+  const editorsStore = useWorkspaceEditorsStoreRef();
+  const [isOpen, setIsOpen] = useState(false);
+  const [view, setViewState] = useState(defaultView);
+
+  const openPanel = useCallback(() => setIsOpen(true), []);
+  const closePanel = useCallback(() => setIsOpen(false), []);
+
+  const setView = useCallback((viewId: string) => setViewState(viewId), []);
+
+  const openDiagnosis = useCallback(() => {
+    editorsStore.openPinned(
+      DIAGNOSIS_DOCUMENT_ENTRY_ID,
+      DIAGNOSIS_DOCUMENT_PATH,
+    );
+    setIsOpen(true);
+  }, [editorsStore]);
+
+  const openFile = useCallback(
+    (entryId: string, path: string, options?: OpenFileOptions) => {
+      editorsStore.openPreview(entryId, path, options);
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const openArtifact = useCallback(
+    (artifact: Artifact) => {
+      editorsStore.openPreview(
+        ARTIFACT_DOCUMENT_ENTRY_ID,
+        workflowArtifactTabPath(artifact),
+      );
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const pinArtifact = useCallback(
+    (artifact: Artifact) => {
+      editorsStore.pin(
+        ARTIFACT_DOCUMENT_ENTRY_ID,
+        workflowArtifactTabPath(artifact),
+      );
+    },
+    [editorsStore],
+  );
+
+  const openFileChange = useCallback(
+    (change: FileChange) => {
+      editorsStore.openPreview(
+        FILE_CHANGE_DOCUMENT_ENTRY_ID,
+        fileChangeTabPath(change),
+      );
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const pinFileChange = useCallback(
+    (change: FileChange) => {
+      editorsStore.pin(FILE_CHANGE_DOCUMENT_ENTRY_ID, fileChangeTabPath(change));
+    },
+    [editorsStore],
+  );
+
+  const openAgentExecution = useCallback(
+    (childExecutionId: string, taskName: string) => {
+      editorsStore.openPreview(
+        AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
+        agentExecutionTabPath(childExecutionId, taskName),
+      );
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const pinAgentExecution = useCallback(
+    (childExecutionId: string, taskName: string) => {
+      editorsStore.pin(
+        AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
+        agentExecutionTabPath(childExecutionId, taskName),
+      );
+    },
+    [editorsStore],
+  );
+
+  const activateEditor = useCallback(
+    (entryId: string, path: string) => editorsStore.activate(entryId, path),
+    [editorsStore],
+  );
+
+  const pinEditor = useCallback(
+    (entryId: string, path: string) => editorsStore.pin(entryId, path),
+    [editorsStore],
+  );
+
+  const closeEditor = useCallback(
+    (entryId: string, path: string) => editorsStore.close(entryId, path),
+    [editorsStore],
+  );
+
+  return useMemo(
+    () => ({
+      editorsStore,
+      isOpen,
+      view,
+      openPanel,
+      closePanel,
+      setView,
+      openDiagnosis,
+      openFile,
+      activateEditor,
+      pinEditor,
+      closeEditor,
+      openArtifact,
+      pinArtifact,
+      openFileChange,
+      pinFileChange,
+      openAgentExecution,
+      pinAgentExecution,
+    }),
+    [
+      editorsStore,
+      isOpen,
+      view,
+      openPanel,
+      closePanel,
+      setView,
+      openDiagnosis,
+      openFile,
+      activateEditor,
+      pinEditor,
+      closeEditor,
+      openArtifact,
+      pinArtifact,
+      openFileChange,
+      pinFileChange,
+      openAgentExecution,
+      pinAgentExecution,
+    ],
+  );
+}

package/src/workflow/useWorkflowExecutionRailViews.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+// Assembles the workflow execution panel's facets as WorkspaceSurface rail
+// views. Domain: workflow (the analog of session/useSessionRailViews).
+
+import { useMemo } from "react";
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type {
+  DerivedCostSummary,
+  DerivedTaskState,
+} from "../internal/store/workflow-execution-event-store.js";
+import type { SurfaceRailView } from "../workspace/WorkspaceSurface.js";
+import { WorkflowArtifactsTab } from "./facets/WorkflowArtifactsTab.js";
+import { WorkflowChangesTab } from "./facets/WorkflowChangesTab.js";
+import { WorkflowUsageTab } from "./facets/WorkflowUsageTab.js";
+
+/** Options for {@link useWorkflowExecutionRailViews}. */
+export interface UseWorkflowExecutionRailViewsOptions {
+  /** Artifacts produced by the execution — drives the Artifacts facet. */
+  readonly artifacts: readonly Artifact[];
+  /** Open an artifact as an editor-pane document tab (preview slot). */
+  readonly onOpenArtifact: (artifact: Artifact) => void;
+  /** Pin an artifact's document tab — the double-click half of open/activate. */
+  readonly onActivateArtifact?: (artifact: Artifact) => void;
+  /** Net file changes across all tasks — drives the Changes facet. */
+  readonly fileChanges: readonly FileChange[];
+  /** First-load state of the file-change rollup (Changes facet skeleton). */
+  readonly fileChangesLoading?: boolean;
+  /** Background-refresh state of the file-change rollup. */
+  readonly fileChangesRefetching?: boolean;
+  /** Child-fetch error for the Changes facet, or `null`. */
+  readonly fileChangesError?: Error | null;
+  /** Tab path of the active file-change diff document (active-row highlight). */
+  readonly activeFileChangePath?: string | null;
+  /** Open a file change's diff as an editor-pane document tab (preview slot). */
+  readonly onOpenFileChange: (change: FileChange) => void;
+  /** Execution-level cost/budget rollup — drives the Usage facet's summary. */
+  readonly costSummary: DerivedCostSummary;
+  /** Per-task derived states — drives the Usage facet's per-task breakdown. */
+  readonly taskStates: ReadonlyMap<string, DerivedTaskState>;
+}
+
+/**
+ * Composes the workflow execution facets as {@link SurfaceRailView}s for the
+ * workspace surface's activity rail — the workflow-domain half of the panel,
+ * mirroring `useSessionRailViews` (domain-specific assembler over the
+ * domain-pure surface).
+ *
+ * The panel carries the execution-level facets only (Artifacts / Changes /
+ * Usage): per-task detail lives on the thread cards, the single home for a
+ * task's data (T06 — the Inspect drill-down is gone). The facets are ALWAYS
+ * offered while the panel renders (the session gates its execution facets
+ * behind `includeExecutionFacets` only for the pre-session launcher — the
+ * workflow viewer has no such pre-execution state). Empty data is handled by
+ * each facet's empty state, not by dropping the view: an empty rail would
+ * strand the surface's view fallback on nothing.
+ */
+export function useWorkflowExecutionRailViews({
+  artifacts,
+  onOpenArtifact,
+  onActivateArtifact,
+  fileChanges,
+  fileChangesLoading,
+  fileChangesRefetching,
+  fileChangesError,
+  activeFileChangePath,
+  onOpenFileChange,
+  costSummary,
+  taskStates,
+}: UseWorkflowExecutionRailViewsOptions): readonly SurfaceRailView[] {
+  return useMemo(
+    (): readonly SurfaceRailView[] => [
+      {
+        id: "artifacts",
+        label: "Artifacts",
+        icon: <ArtifactsIcon />,
+        badge: artifacts.length > 0 ? artifacts.length : undefined,
+        content: (
+          <WorkflowArtifactsTab
+            artifacts={artifacts}
+            onOpen={onOpenArtifact}
+            onActivate={onActivateArtifact}
+          />
+        ),
+      },
+      {
+        id: "changes",
+        label: "Changes",
+        icon: <ChangesIcon />,
+        badge: fileChanges.length > 0 ? fileChanges.length : undefined,
+        content: (
+          <WorkflowChangesTab
+            fileChanges={fileChanges}
+            isLoading={fileChangesLoading}
+            isRefetching={fileChangesRefetching}
+            error={fileChangesError}
+            activePath={activeFileChangePath}
+            onOpen={onOpenFileChange}
+          />
+        ),
+      },
+      {
+        // No badge (matching the session's Usage view) — cost is a
+        // continuous quantity, not a countable collection.
+        id: "usage",
+        label: "Usage",
+        icon: <UsageIcon />,
+        content: (
+          <WorkflowUsageTab costSummary={costSummary} taskStates={taskStates} />
+        ),
+      },
+    ],
+    [
+      artifacts,
+      onOpenArtifact,
+      onActivateArtifact,
+      fileChanges,
+      fileChangesLoading,
+      fileChangesRefetching,
+      fileChangesError,
+      activeFileChangePath,
+      onOpenFileChange,
+      costSummary,
+      taskStates,
+    ],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons — monochrome, `currentColor`-tinted (DD-005; SDK
+// independence — no lucide dependency). Same glyph as the session rail's
+// Artifacts view, so the two panels read identically.
+// ---------------------------------------------------------------------------
+
+function ArtifactsIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M21 8l-9-5-9 5v8l9 5 9-5z" />
+      <path d="M3 8l9 5 9-5" />
+      <path d="M12 13v9" />
+    </svg>
+  );
+}
+
+/**
+ * File-diff glyph (document with +/- lines) — deliberately NOT the session
+ * rail's branch glyph: that Changes view shows git write-backs, while this
+ * one shows file diffs, and reusing the glyph would imply the same content.
+ */
+function ChangesIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M14 3H7a1 1 0 0 0-1 1v16a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V7z" />
+      <path d="M14 3v4h4" />
+      <path d="M10 11h4" />
+      <path d="M12 9v4" />
+      <path d="M10 16.5h4" />
+    </svg>
+  );
+}
+
+function UsageIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M3 20h18" />
+      <path d="M6 20v-6" />
+      <path d="M11 20V9" />
+      <path d="M16 20v-9" />
+      <path d="M21 20V5" />
+    </svg>
+  );
+}

package/src/workspace/FileViewer.tsx

@@ -27,7 +27,7 @@ import {
   type WorkspaceFileReader,
 } from "./WorkspaceFileReader.js";
 
-/** Line-skeleton widths, mirroring `FileContentStateView` in `ArtifactPreviewModal`. */
+/** Line-skeleton widths, mirroring `ArtifactFileContent` in `execution/`. */
 const SKELETON_LINE_WIDTHS = [85, 72, 90, 65, 78, 88, 70, 82] as const;
 
 /** Props for {@link FileViewer}. */
@@ -97,7 +97,7 @@ export interface FileViewerHandle {
  * {@link useWorkspaceFileContent}, and — for displayable text — delegates to
  * the shared {@link ArtifactContentRenderer} (markdown / YAML / JSON /
  * line-numbered text). Its state body deliberately mirrors
- * `FileContentStateView` in `ArtifactPreviewModal` (same skeleton, error, and
+ * `ArtifactFileContent` in `execution/` (same skeleton, error, and
  * delegation), extended with the three states an execution artifact never
  * has — binary, too-large, and unsupported-substrate. The two are **not**
  * merged into one shared component: their surrounding chrome (an artifact's
@@ -326,7 +326,7 @@ function ViewerModeToggle({
 }
 
 // ---------------------------------------------------------------------------
-// Body — exactly one state, mirroring FileContentStateView + workspace extras
+// Body — exactly one state, mirroring ArtifactFileContent + workspace extras
 // ---------------------------------------------------------------------------
 
 /**

package/src/workspace/PanelChip.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+// The always-mounted toggle chip for a collapsible WorkspaceSurface panel.
+// Domain: workspace (shared by the session and workflow execution viewers).
+
+import { useEffect, useRef } from "react";
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link PanelChip}. */
+export interface PanelChipProps {
+  /** Whether the panel is currently expanded. */
+  readonly isOpen: boolean;
+  /** Toggles the panel open/collapsed. */
+  readonly onToggle: () => void;
+  /**
+   * Aggregate count of panel items awaiting the user (write-backs +
+   * artifacts on the session side; artifacts on the workflow side). Rendered
+   * as a dot-count while collapsed — the panel's only "something arrived"
+   * signal, since arrivals never auto-open the panel.
+   */
+  readonly badgeCount?: number;
+}
+
+/**
+ * The always-mounted toggle for a collapsible workspace panel — the Cursor
+ * "Show panel" chip. Collapsed, it carries the pending-item count; open, it
+ * is the hide affordance. Being a small leaf, it is also the one place that
+ * may safely carry per-arrival re-renders while the panel subtree is
+ * unmounted. Execution status deliberately does not surface here (or
+ * anywhere else in viewer chrome) — the thread/graph itself communicates run
+ * state.
+ *
+ * All visual properties flow through `--stgm-*` tokens (DD-005).
+ */
+export function PanelChip({ isOpen, onToggle, badgeCount }: PanelChipProps) {
+  const showCount = !isOpen && badgeCount != null && badgeCount > 0;
+
+  // Focus restoration: collapsing unmounts the panel subtree, so keyboard
+  // focus that lived inside it (rail, tabs, viewer) falls to <body>. Reclaim
+  // it here — the chip is the collapse's logical origin. Focus resting
+  // anywhere else (e.g. the composer) is respected. Opening deliberately does
+  // NOT move focus: the chip is a standard disclosure trigger.
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const prevOpenRef = useRef(isOpen);
+  useEffect(() => {
+    if (prevOpenRef.current && !isOpen && document.activeElement === document.body) {
+      buttonRef.current?.focus();
+    }
+    prevOpenRef.current = isOpen;
+  }, [isOpen]);
+
+  return (
+    <button
+      ref={buttonRef}
+      type="button"
+      onClick={onToggle}
+      aria-expanded={isOpen}
+      aria-label={isOpen ? "Hide panel" : "Show panel"}
+      title={isOpen ? "Hide panel" : "Show panel"}
+      className={cn(
+        "flex items-center gap-1.5 rounded-md border border-border bg-card px-1.5 py-1",
+        "text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      )}
+    >
+      {showCount && (
+        <span
+          aria-label={`${badgeCount} new items`}
+          className="inline-flex min-w-[1rem] items-center justify-center rounded-full bg-primary px-1 py-px text-[10px] font-medium leading-none text-primary-foreground"
+        >
+          {badgeCount}
+        </span>
+      )}
+      <PanelIcon open={isOpen} />
+    </button>
+  );
+}
+
+/**
+ * Panel-layout glyph: a frame with its right region filled while the panel is
+ * open, hollow while collapsed — mirroring the state it toggles to at a glance.
+ */
+function PanelIcon({ open }: { readonly open: boolean }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="1.5" y="2.5" width="13" height="11" rx="1.5" />
+      <path d="M9.5 2.5v11" />
+      {open && (
+        <rect x="9.5" y="2.5" width="5" height="11" rx="1.5" fill="currentColor" stroke="none" />
+      )}
+    </svg>
+  );
+}