@try-works/dsh-recursive-mode 0.2.2 → 0.2.4

package/src/client/inspector.tsx

@@ -4,9 +4,10 @@
  * toggle, and solid status pills. All from the live host-route snapshot.
  * useBoardTheme is hoisted ABOVE the not-found early return.
  */
-import { createElement, type ReactNode } from 'react'
+import { createElement, useState, type ReactNode } from 'react'
 import type { LiveProjectionValue } from './contract.ts'
 import { cardFacts, expandPhaseRows, cardPill, phaseStatusPill, PILL_LABELS } from './derive.ts'
+import { DocViewer } from './doc-viewer.tsx'
 import { useBoardTheme, ThemeToggle } from './theme.ts'
 import type { BoardTheme } from './theme.ts'
 
@@ -44,6 +45,7 @@ function detailShell(runId: string, onBackToToolDetails: () => void, onClose: ((
 
 export function Inspector({ runId, worktreeRoot, snapshot, onBackToToolDetails, onClose }: InspectorProps) {
   const { theme, toggle } = useBoardTheme()
+  const [openFileName, setOpenFileName] = useState<string | null>(null)
   const card = snapshot?.projection?.[worktreeRoot]?.[runId]
   if (card === undefined) {
     return detailShell(runId, onBackToToolDetails, onClose, null,
@@ -55,13 +57,22 @@ export function Inspector({ runId, worktreeRoot, snapshot, onBackToToolDetails,
   const rows = expandPhaseRows(card)
   const pill = cardPill(card)
   const headerExtra = solidPill(pill)
-  const body = createElement('section', { className: 'rec-detail-section' },
+  const body = openFileName !== null
+    ? createElement(DocViewer, { runId, worktreeRoot, fileName: openFileName, theme, onClose: () => setOpenFileName(null) })
+    : createElement('section', { className: 'rec-detail-section' },
     createElement('h3', {}, 'Phases'),
     rows.map((row) => createElement('div', { key: row.phase, className: 'rec-phase-row' },
       createElement('span', { className: 'rec-phase-id' }, row.phase),
       createElement('span', { className: 'rec-phase-name' }, row.fileName ?? '—'),
       solidPill(phaseStatusPill(row.status)),
       row.lockHash !== undefined && createElement('code', { className: 'rec-lockhash' }, '#' + row.lockHash.slice(0, 8)),
+      row.present && row.fileName !== null && createElement('button', {
+        type: 'button',
+        className: 'rec-phase-view',
+        onClick: () => setOpenFileName(row.fileName!),
+        title: 'View phase doc',
+        'aria-label': 'View phase doc',
+      }, 'View phase'),
     )),
     facts.gateBlocked && createElement('div', { className: 'rec-detail-section' },
       createElement('h3', {}, 'Gate'),

package/src/client/slots.ts

@@ -64,11 +64,54 @@ export function RecursiveLauncherGate({ useSessions }: { useSessions: SnapshotSe
   return createElement('button', { className: 'rec-launcher', title: 'Recursive runs', onClick: () => boardState.openBoard() }, '⧉')
 }
 
+/**
+ * RecursiveView: the conversation.view tab body. Renders the run board INLINE
+ * (fills the view area) keyed on the CURRENT workspace, and swaps to the
+ * inspector modal when a run is opened. Read-only (R9): uses the live host
+ * route. No preset gate — the tab is discoverable in any session.
+ */
+export function RecursiveView({ useSessions, useWorkspaces }: { useSessions: SnapshotSelectorHook<SessionListStateLike>; useWorkspaces: SnapshotSelectorHook<WorkspaceListStateLike> }): ReactNode {
+  const board = useBoardState()
+  const sessions = useRecursiveSessions(useSessions)
+  const workspaces: WorkspaceListStateLike = useWorkspaces((s) => s) ?? { items: [], recentWorkspaceId: undefined }
+  const wsPath = currentWorkspacePath(workspaces, sessions)
+  const scope = { cwd: wsPath }
+  const snapshot = useLiveProjection(scope)
+  // Inspector drill-down (modal over the inline board) when a run is selected.
+  if (board.selection !== null) {
+    return createElement(Inspector, {
+      runId: board.selection.runId,
+      worktreeRoot: board.selection.worktreeRoot,
+      snapshot,
+      onBackToToolDetails: () => boardState.backToBoard(),
+      onClose: () => boardState.close(),
+    })
+  }
+  return createElement(Board, { snapshot, workspacePath: wsPath, variant: 'view', onOpenInspector: (sel) => boardState.openInspector(sel) })
+}
+
 export function registerSlots(ctx: ClientContext): () => void {
   const disposers: (() => void)[] = []
   // Run 15: inject the one-shot theme-token stylesheet once per document (idempotent).
   disposers.push(injectBoardStyles())
 
+  // Conversation view tab (Chat | Trajectory | Recursive): the recursive run
+  // board as a first-class tab in the conversation header, rendered INLINE in
+  // the view area (not a fixed overlay). Order 20 places it to the RIGHT of
+  // Trajectory (order 10). Always present — no recursive-preset gate, so the
+  // entry point is discoverable in any session.
+  disposers.push(ctx.slots.inject('conversation.view', () => ctx.slots.register({
+    name: 'conversation.view',
+    id: 'recursive',
+    order: 20,
+    label: 'Recursive',
+  }, (props: RootSlotProps) => {
+    const useSessions = props?.useSessions
+    const useWorkspaces = props?.useWorkspaces
+    if (useSessions === undefined || useWorkspaces === undefined) return null
+    return createElement(RecursiveView, { useSessions, useWorkspaces })
+  })))
+
   // Board launcher in the sidebar footer action list — OPENS the shared board store (run 08 R1).
   // Run 11 (UX gate): the seat is root-scoped (visible in every session), but the board it
   // opens is recursive-preset-gated. In a code/other session the icon was a dead click — a

package/src/client/styles.ts

@@ -136,6 +136,17 @@ const BOARD_CSS = `
   overflow: hidden;
 }
 
+/* Inline board (conversation.view tab): fills its parent view area, not fixed. */
+.rec-board-view {
+  position: relative;
+  inset: auto;
+  z-index: auto;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  flex: 1;
+}
+
 .rec-board-header {
   display: flex;
   align-items: center;
@@ -521,6 +532,316 @@ const BOARD_CSS = `
   color: var(--board-muted-fg);
 }
 
+/* ===== Per-phase doc viewer (0.2.4, inside the inspector detail body) ===== */
+
+/* View phase ghost button on each present phase row. */
+.rec-phase-view {
+  flex: none;
+  padding: 3px 10px;
+  font-size: var(--board-text-xs);
+  color: var(--board-info);
+  background: transparent;
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-phase-view:hover {
+  background: var(--board-accent);
+}
+
+/* Viewer shell: fills the inspector detail body (the panel owns data-theme). */
+.rec-doc {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  gap: var(--board-space-12);
+  color: var(--board-fg);
+  font-family: var(--board-font-sans);
+  background: var(--board-bg);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-xl);
+  overflow: hidden;
+}
+
+.rec-doc-header {
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-12);
+  padding: var(--board-space-12) var(--board-space-16);
+  border-bottom: 1px solid var(--board-border);
+  flex: none;
+}
+
+.rec-doc-heading {
+  display: flex;
+  align-items: baseline;
+  gap: var(--board-space-12);
+  flex: 1;
+  min-width: 0;
+}
+
+.rec-doc-badge {
+  flex: none;
+  padding: 2px 10px;
+  font-size: 11px;
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  border-radius: 999px;
+  background: var(--board-accent);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-title {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: var(--board-tracking-tight);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.rec-doc-run {
+  flex: none;
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-btn {
+  flex: none;
+  padding: 5px 12px;
+  font-size: var(--board-text-xs);
+  color: var(--board-fg);
+  background: transparent;
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-doc-btn:hover {
+  background: var(--board-accent);
+}
+
+/* Search bar (/ to open). */
+.rec-doc-search {
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-12);
+  padding: var(--board-space-8) var(--board-space-16);
+  border-bottom: 1px solid var(--board-border);
+  flex: none;
+}
+
+.rec-doc-search-input {
+  flex: 1 1 auto;
+  background: var(--board-muted);
+  color: var(--board-fg);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  padding: 5px 10px;
+  font-size: var(--board-text-xs);
+  font-family: inherit;
+  min-width: 0;
+}
+
+.rec-doc-search-input::placeholder {
+  color: var(--board-muted-fg);
+  opacity: 1;
+}
+
+.rec-doc-search-count {
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  white-space: nowrap;
+}
+
+/* Body: scrollable line list. */
+.rec-doc-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: var(--board-space-12) var(--board-space-16) var(--board-space-16);
+}
+
+.rec-doc-line {
+  font-size: var(--board-text-sm);
+  line-height: 1.7;
+  padding: 0 6px;
+  border-left: 2px solid transparent;
+}
+
+.rec-doc-line-current {
+  background: var(--board-muted);
+  border-left-color: var(--board-info);
+}
+
+.rec-doc-blank {
+  height: 10px;
+}
+
+.rec-doc-plain {
+  white-space: pre-wrap;
+}
+
+.rec-doc-h1 {
+  font-size: 22px;
+  font-weight: 700;
+  margin: 8px 0 6px;
+  line-height: 1.3;
+}
+
+.rec-doc-h2 {
+  font-size: 18px;
+  font-weight: 600;
+  margin: 12px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-h3 {
+  font-size: 15px;
+  font-weight: 600;
+  margin: 10px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-h4 {
+  font-size: 14px;
+  font-weight: 600;
+  margin: 8px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-li {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  font-size: var(--board-text-sm);
+  line-height: 1.65;
+  margin: 0 0 4px;
+}
+
+.rec-doc-bullet {
+  flex: none;
+  color: var(--board-muted-fg);
+  width: 14px;
+  text-align: center;
+}
+
+.rec-doc-li-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.rec-doc-pre {
+  margin: 6px 0;
+  padding: var(--board-space-12);
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  overflow-x: auto;
+}
+
+.rec-doc-code,
+.rec-doc-inline-code {
+  font-family: var(--board-font-mono);
+  font-size: 12.5px;
+  letter-spacing: var(--board-tracking-mono);
+}
+
+.rec-doc-inline-code {
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: 4px;
+  padding: 0 4px;
+}
+
+.rec-doc-inline-link {
+  color: var(--board-info);
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.rec-doc-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 6px 0;
+  font-size: var(--board-text-xs);
+}
+
+.rec-doc-table th,
+.rec-doc-table td {
+  border: 1px solid var(--board-border);
+  padding: 4px 8px;
+  text-align: left;
+}
+
+.rec-doc-table th {
+  background: var(--board-muted);
+  color: var(--board-muted-fg);
+  font-weight: var(--board-fw-semibold);
+}
+
+/* Footer: status + key hints. */
+.rec-doc-footer {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-16);
+  padding: var(--board-space-8) var(--board-space-16);
+  border-top: 1px solid var(--board-border);
+  flex-wrap: wrap;
+}
+
+.rec-doc-status {
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  min-width: 120px;
+}
+
+.rec-doc-status-error {
+  color: var(--board-error);
+}
+
+.rec-doc-status-ok {
+  color: var(--board-success);
+}
+
+.rec-doc-hints {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex-wrap: wrap;
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-hints kbd {
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-family: inherit;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--board-fg);
+  margin: 0 3px 0 8px;
+}
+
+.rec-doc-text {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-error {
+  color: var(--board-error);
+}
+
 /* ===== Strip (session dock) — keeps the shell --dsw-* theme ===== */
 .rec-badge {
   flex: none;

package/src/live-route.ts

@@ -17,7 +17,10 @@
  * would be both wrong and a crash).
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
 import type { RecursiveProjection } from './types.ts'
+import { RUN_ARTIFACT_SEQUENCE } from './status.ts'
 
 /** API prefix the board/strip fetch. */
 export const RECURSIVE_API_PREFIX = '/.recursive/api'
@@ -65,8 +68,72 @@ function queryOf(req: IncomingMessage, name: string): string {
   return new URLSearchParams(url.slice(q + 1)).get(name) ?? ''
 }
 
+/** Phase-doc basename allowlist (the run artifact sequence: single *.md, no subdirs). */
+const PHASE_DOC_FILES = new Set(RUN_ARTIFACT_SEQUENCE)
+
+/** runId/file safety: alphanumerics, dot, underscore, dash only; no '..', no separators. */
+const DOC_SAFE_RE = /^[A-Za-z0-9._-]+$/
+
+/** Invalid runId or file name (path traversal / subdir / non-phase doc) — reject. */
+function docTargetError(runId: string, file: string): string | null {
+  if (!DOC_SAFE_RE.test(runId) || runId.includes('..')) return 'invalid runId'
+  if (!DOC_SAFE_RE.test(file) || file.includes('..') || file.includes('/') || file.includes('\\')) return 'invalid file'
+  if (!file.endsWith('.md')) return 'invalid file: must be a .md phase doc'
+  if (!PHASE_DOC_FILES.has(file)) return 'invalid file: not a phase doc'
+  return null
+}
+
+/**
+ * The lazy per-phase doc route (0.2.4): GET the raw markdown of one run phase
+ * doc, read ON DEMAND from the filesystem. NOT part of the /state or /events
+ * projection payloads (they stay fold-only). Same browser-marker tripwire as
+ * state/events; the client root is re-validated by the host (never trusted:
+ * an unknown root -> 400), then the resolved doc path is containment-checked
+ * under join(root, '.recursive', 'run', runId).
+ */
+function docRoute(host: RecursiveRouteHost) {
+  return {
+    kind: 'exact' as const,
+    path: RECURSIVE_API_PREFIX + '/doc',
+    handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+      if (req.method !== 'GET') { res.writeHead(405); res.end(); return }
+      if (!browserMarker(req)) { res.writeHead(403); res.end(); return }
+      const root = queryOf(req, 'root')
+      const runId = queryOf(req, 'runId')
+      const file = queryOf(req, 'file')
+      const targetError = docTargetError(runId, file)
+      if (root === '' || targetError !== null) {
+        json(res, 400, { ok: false, error: targetError ?? 'missing root' })
+        return
+      }
+      // Root validation: the client passes back what the host already resolved.
+      // Re-resolve via the host and require a canonical match — never accept an
+      // arbitrary path (registry know-it or headless cwd pass-through).
+      const resolvedRoot = await host.resolveRoot(undefined, root)
+      if (resolvedRoot === null || resolve(resolvedRoot) !== resolve(root)) {
+        json(res, 400, { ok: false, error: 'root is not a known workspace' })
+        return
+      }
+      // Containment: the doc must stay under join(root, .recursive, run, runId).
+      const runBase = resolve(root, '.recursive', 'run', runId)
+      const docPath = resolve(runBase, file)
+      if (docPath === runBase || !docPath.startsWith(runBase + sep)) {
+        json(res, 400, { ok: false, error: 'doc path escapes the run dir' })
+        return
+      }
+      if (!existsSync(docPath)) {
+        json(res, 404, { ok: false, error: 'phase doc not found' })
+        return
+      }
+      const text = readFileSync(docPath, 'utf8')
+      res.writeHead(200, { 'content-type': 'text/markdown; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(text)
+    },
+  }
+}
+
 /**
- * Build the two read-only routes. Returns [state, events] in registration order.
+ * Build the read-only routes. Returns [state, events, doc] in registration order.
  * @param host - the resolved-root + fs-fold seam (the RecursiveRuntime adapter).
  */
 export function makeRecursiveRoutes(host: RecursiveRouteHost): readonly { kind: 'exact'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void> }[] {
@@ -109,7 +176,7 @@ export function makeRecursiveRoutes(host: RecursiveRouteHost): readonly { kind:
       await push()
     },
   }
-  return [state, events]
+  return [state, events, docRoute(host)]
 }
 
 /**