@stigmer/react 3.4.0 → 3.4.1

package/src/session/NewSessionViewer.tsx

@@ -1,7 +1,6 @@
 "use client";
 
 import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
-import { cn } from "@stigmer/theme";
 import type { ResourceRef } from "@stigmer/sdk";
 import type { UseGitHubConnectionReturn } from "../github/useGitHubConnection.js";
 import type { WorkspaceFileLister } from "../workspace/WorkspaceFileLister.js";
@@ -10,7 +9,7 @@ import type { WorkspaceContentSearcher } from "../workspace/WorkspaceContentSear
 import type { InteractionModeOption } from "../composer/index.js";
 import { SessionComposer } from "../composer/index.js";
 import type { HarnessOption } from "../models/harness.js";
-import { ResizableSplit } from "../internal/ResizableSplit.js";
+import { SessionViewerLayout } from "./SessionViewerLayout.js";
 import { useWorkspaceEditors } from "../internal/store/index.js";
 import { WorkspaceSurface } from "../workspace/WorkspaceSurface.js";
 import type { SetupTabProps } from "./facets/SetupTab.js";
@@ -383,68 +382,56 @@ export function NewSessionViewer({
   );
 
   return (
-    <div className={cn("relative flex h-full w-full flex-col", className)}>
-      {/* Persistent chrome: the chip is always mounted, matching SessionViewer
-          (DD-016) rather than the launcher's earlier progressively-revealed
-          inspector. A toggle that appears/disappears with attached context
-          reads as instability and, worse, unmounts the open panel's only
-          collapse control when the last context item is removed. Always-on is
-          the predictable, discoverable shape; opening homes on the Config
-          facet, which carries useful defaults (harness/model) pre-session.
-          Guests are the exception: the panel exposes configuration a visitor
-          has no business with, so the chip (the panel's only toggle) is
-          simply absent and the panel can never open. */}
-      {!isGuest && (
-        <div className="absolute top-2 right-6 z-10">
+    // The launcher renders the same SessionViewerLayout as SessionViewer
+    // (DD-016) — the shared frame is what makes "the two viewers behave
+    // identically" structural rather than hand-synchronized.
+    <SessionViewerLayout
+      className={className}
+      resizeAriaLabel="Resize composer panel"
+      splitStorageKey="stgm-new-session-chat-width"
+      // Persistent chrome: the chip is always mounted, matching SessionViewer
+      // (DD-016) rather than the launcher's earlier progressively-revealed
+      // inspector. A toggle that appears/disappears with attached context
+      // reads as instability and, worse, unmounts the open panel's only
+      // collapse control when the last context item is removed. Always-on is
+      // the predictable, discoverable shape; opening homes on the Config
+      // facet, which carries useful defaults (harness/model) pre-session.
+      // Guests are the exception: the panel exposes configuration a visitor
+      // has no business with, so the chip (the panel's only toggle) is
+      // simply absent and the panel can never open.
+      chip={
+        !isGuest ? (
           <SessionPanelChip
             isOpen={panel.isOpen}
             onToggle={panel.isOpen ? panel.closePanel : panel.openPanel}
           />
-        </div>
-      )}
-
-      {/* Same unified-panel layout as SessionViewer (DD-016): collapsed by
-          default (composer fills the row); opening makes the composer the
-          fixed narrow pane and hands the flexible region to the surface.
-          Collapse goes through the split's `collapsedPane` (CSS, not
-          conditional structure), so the composer never remounts across an
-          open/close toggle. */}
-      <ResizableSplit
-        resizablePane="primary"
-        collapsedPane={panel.isOpen ? "none" : "secondary"}
-        defaultSize={420}
-        minSize={320}
-        maxSize={640}
-        storageKey="stgm-new-session-chat-width"
-        responsiveCollapse={panel.isOpen ? "primary" : "none"}
-        ariaLabel="Resize composer panel"
-        className="min-h-0 flex-1"
-        primary={composerNode}
-        secondary={
-          panel.isOpen ? (
-            <WorkspaceSurface
-              entries={flow.workspace.entries}
-              lister={workspaceFileLister}
-              reader={workspaceFileReader}
-              searcher={workspaceContentSearcher}
-              view={panel.view}
-              onViewChange={panel.setView}
-              extraViews={railViews}
-              onRemoveEntry={flow.workspace.remove}
-              onAddLocalFolder={canAddLocalFolder ? handleAddLocalFolder : undefined}
-              editors={editors}
-              selectedFile={activeFile}
-              onOpenFile={panel.openFile}
-              onActivateEditor={panel.activateEditor}
-              onPinEditor={panel.pinEditor}
-              onCloseEditor={panel.closeEditor}
-              onCollapse={panel.closePanel}
-              reveal={activeReveal}
-              className="h-full"
-            />
-          ) : null
-        }
-      />
-    </div>
+        ) : undefined
+      }
+      conversation={composerNode}
+      panel={
+        panel.isOpen ? (
+          <WorkspaceSurface
+            entries={flow.workspace.entries}
+            lister={workspaceFileLister}
+            reader={workspaceFileReader}
+            searcher={workspaceContentSearcher}
+            view={panel.view}
+            onViewChange={panel.setView}
+            extraViews={railViews}
+            onRemoveEntry={flow.workspace.remove}
+            onAddLocalFolder={canAddLocalFolder ? handleAddLocalFolder : undefined}
+            editors={editors}
+            selectedFile={activeFile}
+            onOpenFile={panel.openFile}
+            onActivateEditor={panel.activateEditor}
+            onPinEditor={panel.pinEditor}
+            onCloseEditor={panel.closeEditor}
+            onCollapse={panel.closePanel}
+            reveal={activeReveal}
+            className="h-full"
+          />
+        ) : null
+      }
+    />
   );
 }

package/src/session/SessionViewer.tsx

@@ -19,7 +19,7 @@ import {
 } from "../workspace/WorkspaceSurface.js";
 import type { InteractionModeOption, SessionComposerHandle, SessionComposerSubmitContext } from "../composer/index.js";
 import type { ApplyResourceResult } from "../library/useApplyResource.js";
-import { ResizableSplit } from "../internal/ResizableSplit.js";
+import { SessionViewerLayout } from "./SessionViewerLayout.js";
 import { useWorkspaceEditors, isVirtualEntryId } from "../internal/store/index.js";
 import { isTerminalPhase } from "../execution/execution-phases.js";
 import { MessageThread, type MessageThreadSlots } from "../execution/MessageThread.js";
@@ -267,7 +267,8 @@ export interface SessionViewerProps {
  *   to a top-right chip; opening a file (tree, search, or a transcript path)
  *   expands it.
  *
- * Connected via `ResizableSplit` with persisted chat width.
+ * Both regions render inside {@link SessionViewerLayout} — the frame shared
+ * with {@link NewSessionViewer} — with the chat width persisted per viewer.
  *
  * Framework-agnostic — no Next.js, no Tauri, no routing deps. Host
  * apps inject platform-specific values via props (DD-004/DD-016).
@@ -552,101 +553,85 @@ export function SessionViewer({
   }
 
   return (
-    <div className={cn("relative flex h-full w-full flex-col", className)}>
-      {/* Top-right controls: host actions + the panel chip. The chip is the
-          panel's always-mounted toggle; while collapsed it carries only the
-          pending-item count. Execution status is never surfaced as header
-          chrome — the thread itself communicates run state. Guests get no
-          chip: the panel exposes session configuration a visitor has no
-          business with, so its only toggle is simply absent. */}
-      <div className="absolute top-2 right-6 z-10 flex items-center gap-2">
-        {headerActions}
-        {!isGuest && (
+    <SessionViewerLayout
+      className={className}
+      // Top-right controls: host actions + the panel chip. The chip is the
+      // panel's always-mounted toggle; while collapsed it carries only the
+      // pending-item count. Execution status is never surfaced as header
+      // chrome — the thread itself communicates run state. Guests get no
+      // chip: the panel exposes session configuration a visitor has no
+      // business with, so its only toggle is simply absent.
+      headerActions={headerActions}
+      chip={
+        !isGuest ? (
           <SessionPanelChip
             isOpen={panel.isOpen}
             onToggle={panel.isOpen ? panel.closePanel : panel.openPanel}
             badgeCount={writeBackCount + artifactCount}
           />
-        )}
-      </div>
-
-      {/* One layout, collapsed by default: chat fills the row until the panel
-          opens, then becomes the fixed narrow pane on the left while the
-          panel takes the flexible region. Collapsing goes through the
-          split's `collapsedPane` (CSS, not conditional structure), so the
-          conversation is always the same first child and an open/close never
-          remounts it (invariant 1). */}
-      <ResizableSplit
-        resizablePane="primary"
-        collapsedPane={panel.isOpen ? "none" : "secondary"}
-        defaultSize={420}
-        minSize={320}
-        maxSize={640}
-        storageKey="stgm-session-chat-width"
-        responsiveCollapse={panel.isOpen ? "primary" : "none"}
-        ariaLabel="Resize chat panel"
-        className="min-h-0 flex-1"
-        primary={
-          <ConversationColumn
+        ) : undefined
+      }
+      splitStorageKey="stgm-session-chat-width"
+      conversation={
+        <ConversationColumn
+          flow={flow}
+          modelId={modelId}
+          setModelId={setModelId}
+          interactionMode={interactionMode}
+          setInteractionMode={setInteractionMode}
+          composerRef={composerRef}
+          org={org}
+          gitHubConnection={gitHubConnection}
+          enableGitHub={enableGitHub}
+          enableLocal={enableLocal}
+          onBrowseLocalFolder={onBrowseLocalFolder}
+          onBuildFromPlan={handleBuildFromPlan}
+          onOpenPlan={handleOpenPlan}
+          isBuildingFromPlan={isBuildingFromPlan}
+          planAttachFailed={planAttachFailed}
+          onDismissPlanAttachFailed={() => setPlanAttachFailed(false)}
+          onFilePathClick={handleTranscriptFilePathClick}
+          isCurated={isCurated}
+          isGuest={isGuest}
+          isObserver={isObserver}
+          threadSlots={threadSlots}
+        />
+      }
+      panel={
+        panel.isOpen && !isGuest ? (
+          <SessionPanelRegion
             flow={flow}
-            modelId={modelId}
-            setModelId={setModelId}
-            interactionMode={interactionMode}
-            setInteractionMode={setInteractionMode}
-            composerRef={composerRef}
             org={org}
-            gitHubConnection={gitHubConnection}
-            enableGitHub={enableGitHub}
+            panel={panel}
+            // Observers cannot manage access (no can_grant_access /
+            // can_view_access on a channel session) — the control is
+            // withheld rather than left to fail server-side.
+            accessSlot={isObserver ? undefined : accessSlot}
+            onApplied={onApplied}
+            // Implementing a plan submits an execution — a write an
+            // observer cannot make (can_create_execution_in is
+            // owner/viewer-only).
+            onImplementPlan={isObserver ? undefined : handleBuildFromPlan}
+            implementPlanDisabled={
+              isObserver || !conv.canSendFollowUp || isBuildingFromPlan
+            }
+            sessionPlan={sessionPlan}
+            streamingPlan={streamingPlan}
+            planDraft={planDraft}
+            openPlanExecutionId={openPlanExecutionId}
+            onOpenPlan={handleOpenPlan}
+            onOpenArtifact={handleOpenArtifact}
+            onActivateArtifact={handleActivateArtifact}
             enableLocal={enableLocal}
             onBrowseLocalFolder={onBrowseLocalFolder}
-            onBuildFromPlan={handleBuildFromPlan}
-            onOpenPlan={handleOpenPlan}
-            isBuildingFromPlan={isBuildingFromPlan}
-            planAttachFailed={planAttachFailed}
-            onDismissPlanAttachFailed={() => setPlanAttachFailed(false)}
-            onFilePathClick={handleTranscriptFilePathClick}
+            workspaceFileLister={workspaceFileLister}
+            workspaceFileReader={workspaceFileReader}
+            workspaceContentSearcher={workspaceContentSearcher}
             isCurated={isCurated}
-            isGuest={isGuest}
-            isObserver={isObserver}
-            threadSlots={threadSlots}
           />
-        }
-        secondary={
-          panel.isOpen && !isGuest ? (
-            <SessionPanelRegion
-              flow={flow}
-              org={org}
-              panel={panel}
-              // Observers cannot manage access (no can_grant_access /
-              // can_view_access on a channel session) — the control is
-              // withheld rather than left to fail server-side.
-              accessSlot={isObserver ? undefined : accessSlot}
-              onApplied={onApplied}
-              // Implementing a plan submits an execution — a write an
-              // observer cannot make (can_create_execution_in is
-              // owner/viewer-only).
-              onImplementPlan={isObserver ? undefined : handleBuildFromPlan}
-              implementPlanDisabled={
-                isObserver || !conv.canSendFollowUp || isBuildingFromPlan
-              }
-              sessionPlan={sessionPlan}
-              streamingPlan={streamingPlan}
-              planDraft={planDraft}
-              openPlanExecutionId={openPlanExecutionId}
-              onOpenPlan={handleOpenPlan}
-              onOpenArtifact={handleOpenArtifact}
-              onActivateArtifact={handleActivateArtifact}
-              enableLocal={enableLocal}
-              onBrowseLocalFolder={onBrowseLocalFolder}
-              workspaceFileLister={workspaceFileLister}
-              workspaceFileReader={workspaceFileReader}
-              workspaceContentSearcher={workspaceContentSearcher}
-              isCurated={isCurated}
-            />
-          ) : null
-        }
-      />
-    </div>
+        ) : null
+      }
+    />
   );
 }
 

package/src/session/SessionViewerLayout.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import { ResizableSplit } from "../internal/ResizableSplit.js";
+
+/** Props for {@link SessionViewerLayout}. */
+export interface SessionViewerLayoutProps {
+  /**
+   * The conversation column — the layout's primary (left) pane. Stays
+   * mounted at a stable tree position across every panel open/close, so
+   * streaming and scroll state survive the toggle.
+   */
+  readonly conversation: ReactNode;
+  /**
+   * The session panel content, or `null` while the panel is collapsed.
+   * This is the single source of truth for the collapsed state: passing
+   * `null` collapses the split (the conversation fills the row) and hides
+   * the drag separator; passing content expands the panel into the
+   * flexible region. Hosts derive it from their panel controller, e.g.
+   * `panel.isOpen ? <WorkspaceSurface … /> : null`.
+   */
+  readonly panel: ReactNode | null;
+  /**
+   * The panel's toggle chip, rendered in the layout's top-right corner
+   * (typically the session panel chip, {@link PanelChip}). Omit it to
+   * render no toggle — how hosts express audiences that must never open
+   * the panel (the guest case in {@link SessionViewer} and
+   * {@link NewSessionViewer}).
+   */
+  readonly chip?: ReactNode;
+  /**
+   * Host-injected header actions, rendered beside the chip in the
+   * top-right corner (slot injection, as {@link SessionViewerProps.headerActions}).
+   */
+  readonly headerActions?: ReactNode;
+  /**
+   * `localStorage` key persisting the chat pane's drag-resized width
+   * across sessions. Each host passes its own key so the two shipped
+   * viewers keep distinct widths. **Omit it in deterministic hosts**
+   * (documentation embeds, video export): with no key the width always
+   * starts at the default, so every render of the same input is
+   * pixel-identical instead of depending on previously persisted state.
+   */
+  readonly splitStorageKey?: string;
+  /**
+   * Whether the conversation pane collapses below the `lg` breakpoint
+   * while the panel is open, leaving the panel full-width — the shipped
+   * console behavior on narrow windows.
+   *
+   * Pass `false` in fixed-canvas hosts, where the media query is
+   * meaningless or actively wrong: a documentation embed renders in an
+   * iframe whose viewport is the docs column (below `lg` on most pages),
+   * so the default would hide the conversation on exactly the beats that
+   * open the panel.
+   *
+   * @default true
+   */
+  readonly responsive?: boolean;
+  /**
+   * Accessible label for the split's drag separator. Name the pane being
+   * resized in the host's vocabulary (the session viewer's chat pane vs
+   * the launcher's composer pane).
+   *
+   * @default "Resize chat panel"
+   */
+  readonly resizeAriaLabel?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * The one conversation-plus-panel frame every session viewer shares —
+ * {@link SessionViewer} and {@link NewSessionViewer} both render it, so the
+ * two surfaces cannot drift apart (their behave-identically contract), and
+ * platform builders composing a custom session surface from
+ * {@link WorkspaceSurface}, {@link PanelChip}, and the session facets get
+ * the same geometry the shipped console uses.
+ *
+ * The layout owns exactly three things:
+ *
+ * - **The top-right control corner** — the host's `headerActions` beside
+ *   the panel toggle `chip`, absolutely positioned over the conversation.
+ * - **The split geometry** — chat fills the row while the panel is
+ *   collapsed; opening makes the chat the fixed, drag-resizable pane
+ *   (420px default, 320–640px) and hands the flexible region to the panel.
+ * - **The collapse mechanics** — collapse goes through the split's
+ *   `collapsedPane` (CSS, not conditional structure), so the conversation
+ *   is always the same first child and an open/close toggle never
+ *   remounts it.
+ *
+ * Everything rendered inside the panes belongs to the host: the layout
+ * takes opaque `ReactNode`s and never inspects them.
+ */
+export function SessionViewerLayout({
+  conversation,
+  panel,
+  chip,
+  headerActions,
+  splitStorageKey,
+  responsive = true,
+  resizeAriaLabel = "Resize chat panel",
+  className,
+}: SessionViewerLayoutProps) {
+  const isPanelOpen = panel != null;
+
+  return (
+    <div className={cn("relative flex h-full w-full flex-col", className)}>
+      {(headerActions != null || chip != null) && (
+        <div className="absolute top-2 right-6 z-10 flex items-center gap-2">
+          {headerActions}
+          {chip}
+        </div>
+      )}
+
+      <ResizableSplit
+        resizablePane="primary"
+        collapsedPane={isPanelOpen ? "none" : "secondary"}
+        defaultSize={420}
+        minSize={320}
+        maxSize={640}
+        storageKey={splitStorageKey}
+        responsiveCollapse={responsive && isPanelOpen ? "primary" : "none"}
+        ariaLabel={resizeAriaLabel}
+        className="min-h-0 flex-1"
+        primary={conversation}
+        secondary={panel}
+      />
+    </div>
+  );
+}

package/src/session/__tests__/SessionViewerLayout.test.tsx

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { SessionViewerLayout } from "../SessionViewerLayout";
+
+// ---------------------------------------------------------------------------
+// The one conversation-plus-panel frame both shipped viewers render
+// (SessionViewer + NewSessionViewer), so the two surfaces cannot drift.
+// The contract under test:
+//   - `panel` is the single source of truth for collapsed state
+//   - the conversation never remounts across an open/close toggle
+//   - `responsive={false}` disables the below-`lg` conversation collapse
+//     (fixed-canvas hosts: docs embeds, video export)
+//   - no `splitStorageKey` means no localStorage read (deterministic hosts)
+// ---------------------------------------------------------------------------
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  localStorage.clear();
+});
+
+function conversation() {
+  return <div data-testid="conversation">chat</div>;
+}
+
+function panel() {
+  return <div data-testid="panel">panel</div>;
+}
+
+describe("SessionViewerLayout", () => {
+  it("collapsed (panel null): conversation renders, panel absent, no separator exposed", () => {
+    render(<SessionViewerLayout conversation={conversation()} panel={null} />);
+    expect(screen.getByTestId("conversation").textContent).toBe("chat");
+    expect(screen.queryByTestId("panel")).toBeNull();
+    // The drag separator is CSS-hidden and aria-hidden while collapsed.
+    expect(screen.queryByRole("separator")).toBeNull();
+  });
+
+  it("open (panel provided): panel renders and the separator is operable", () => {
+    render(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    expect(screen.getByTestId("panel").textContent).toBe("panel");
+    const separator = screen.getByRole("separator", { name: "Resize chat panel" });
+    expect(separator.getAttribute("tabindex")).toBe("0");
+  });
+
+  it("resizeAriaLabel names the separator in the host's vocabulary", () => {
+    render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={panel()}
+        resizeAriaLabel="Resize composer panel"
+      />,
+    );
+    expect(
+      screen.queryByRole("separator", { name: "Resize composer panel" }),
+    ).not.toBeNull();
+  });
+
+  it("never remounts the conversation across an open/close toggle", () => {
+    const { rerender } = render(
+      <SessionViewerLayout conversation={conversation()} panel={null} />,
+    );
+    const node = screen.getByTestId("conversation");
+
+    rerender(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    expect(screen.getByTestId("conversation")).toBe(node);
+
+    rerender(<SessionViewerLayout conversation={conversation()} panel={null} />);
+    expect(screen.getByTestId("conversation")).toBe(node);
+  });
+
+  it("open panel sizes the conversation pane at the shared default width", () => {
+    render(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    const pane = screen.getByTestId("conversation").parentElement!;
+    expect(pane.style.width).toBe("420px");
+  });
+
+  it("responsive (default): the open-panel conversation pane collapses below lg", () => {
+    const { container } = render(
+      <SessionViewerLayout conversation={conversation()} panel={panel()} />,
+    );
+    const pane = screen.getByTestId("conversation").parentElement!;
+    expect(pane.className).toContain("max-lg:hidden");
+    // The separator hides with it, so the panel is the full row below lg.
+    expect(container.querySelectorAll('[class*="max-lg:hidden"]').length).toBe(2);
+  });
+
+  it("responsive={false}: no below-lg collapse anywhere (fixed-canvas hosts)", () => {
+    const { container } = render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={panel()}
+        responsive={false}
+      />,
+    );
+    expect(container.querySelector('[class*="max-lg:hidden"]')).toBeNull();
+  });
+
+  it("reads no localStorage without a splitStorageKey (deterministic hosts)", () => {
+    const getItem = vi.spyOn(Storage.prototype, "getItem");
+    render(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    expect(getItem).not.toHaveBeenCalled();
+  });
+
+  it("seeds the pane width from the host's splitStorageKey when given", () => {
+    localStorage.setItem("stgm-test-chat-width", "512");
+    render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={panel()}
+        splitStorageKey="stgm-test-chat-width"
+      />,
+    );
+    const pane = screen.getByTestId("conversation").parentElement!;
+    expect(pane.style.width).toBe("512px");
+  });
+
+  it("renders headerActions beside the chip in the top-right corner", () => {
+    render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={null}
+        headerActions={<button type="button">Share</button>}
+        chip={<button type="button">Toggle panel</button>}
+      />,
+    );
+    const actions = screen.getByRole("button", { name: "Share" });
+    const chip = screen.getByRole("button", { name: "Toggle panel" });
+    expect(actions.parentElement).toBe(chip.parentElement);
+  });
+
+  it("renders no control corner when both chip and headerActions are omitted", () => {
+    const { container } = render(
+      <SessionViewerLayout conversation={conversation()} panel={null} />,
+    );
+    // The corner is the only `top-2`-positioned element in the layout (the
+    // separator's inner hit target is also `absolute`, so match the corner).
+    expect(container.querySelector('[class*="top-2"]')).toBeNull();
+  });
+});

package/src/session/index.ts

@@ -109,6 +109,12 @@ export type { SessionViewerProps } from "./SessionViewer.js";
 export { NewSessionViewer } from "./NewSessionViewer.js";
 export type { NewSessionViewerProps } from "./NewSessionViewer.js";
 
+// SessionViewerLayout — the conversation-plus-panel frame both viewers
+// share, exported for platform builders composing a custom session surface
+// at the shipped console's geometry.
+export { SessionViewerLayout } from "./SessionViewerLayout.js";
+export type { SessionViewerLayoutProps } from "./SessionViewerLayout.js";
+
 // Unified session-panel controller — drives the WorkspaceSurface open-editor
 // group, the collapsed/open state, and the rail-view FSM (for platform
 // builders embedding the surface directly).
@@ -118,6 +124,14 @@ export type {
   UseSessionPanelOptions,
 } from "./useSessionPanel.js";
 
+// Session rail views — composes the session facets (Config / Changes /
+// Artifacts / Usage) as the panel's rail, with the console's own labels,
+// icons, badges, and contextual-visibility rules. Exported so custom
+// session surfaces inherit the rail by construction instead of
+// re-declaring it.
+export { useSessionRailViews } from "./useSessionRailViews.js";
+export type { UseSessionRailViewsOptions } from "./useSessionRailViews.js";
+
 // Plan draft — viewer-owned in-place edit of the session's current plan
 // (edit-as-input; the published plan.md artifact is never mutated).
 export { usePlanDraft, planDraftKey } from "./usePlanDraft.js";

package/src/session/useSessionRailViews.tsx

@@ -55,13 +55,13 @@ export interface UseSessionRailViewsOptions {
    * (a cloud session with git workspace entries). When `true` the Changes
    * facet is offered from the start — with an honest pre-push state — instead
    * of only materializing once a write-back exists, so "where does my work
-   * go?" always has an answer. See {@link ChangesTabProps.expectsWriteBack}.
+   * go?" always has an answer (the facet's `expectsWriteBack` prop).
    * @default false
    */
   readonly expectsWriteBack?: boolean;
   /**
    * Whether the session's latest execution is settled (terminal) — forwarded
-   * to the Changes facet's pre-push states. See {@link ChangesTabProps.isSettled}.
+   * to the Changes facet's pre-push states (its `isSettled` prop).
    * @default false
    */
   readonly changesSettled?: boolean;

package/src/skill/useSkillCount.ts

@@ -17,6 +17,8 @@ export interface UseSkillCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useSkillCount}. */