@inerrata-corporation/errata 2.0.17-dev.3571 → 2.0.17-dev.3576

package/resources/claude-mods/errata-minimap/hooks/register.tsx

@@ -0,0 +1,484 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register, Timer } from 'claude-code'
+
+import type { Burst, MapGraph, Verdict } from '../types'
+import {
+  colorOf,
+  DARK_BG,
+  FULL,
+  LIGHT_BG,
+  displayName,
+  glyphOf,
+  hex,
+  JUDGMENT_STYLE,
+  layoutBurst,
+  parseJudgments,
+  resolveJudgmentRef,
+  neighborIds,
+  parseAgentBurst,
+  parseAgentSearch,
+  parseFileRecall,
+  parsePromptPrime,
+  rasterize,
+  SCOPE_COLOR,
+  SCOPE_ORDER,
+  seedNode,
+  relPath,
+  shortName,
+  statusLine,
+  textsOf,
+} from './minimap'
+import type { Frame, HandleTable, JudgmentKind, RasterOptions } from './minimap'
+
+const PANE = 'errata-minimap'
+const ERRATA = 'errata'
+const ENRICH_MAX = 8
+const TOP_ITEMS = 3
+
+const focus = atom({ plugin: 'errata-minimap', key: 'focus' } as const, '')
+const burst = atom({ plugin: 'errata-minimap', key: 'burst' } as const, null as Burst | null)
+const graph = atom({ plugin: 'errata-minimap', key: 'graph' } as const, { title: '', nodes: [], edges: [], at: 0 } as MapGraph)
+const verdicts = atom({ plugin: 'errata-minimap', key: 'verdicts' } as const, [] as Verdict[])
+
+const FILE_TOOLS = new Set(['Read', 'Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+const BURST_FILE = /\.errata\/g\/burst\/([^/]+)/
+
+const ORIGIN_LABEL = { agent: 'agent burst', 'daemon-file': 'file recall', 'daemon-prompt': 'prompt prime' } as const
+
+// Module-level on purpose: a reload starts by redrawing whatever burst the session holds.
+const pending = { isRefreshing: false, drawnAt: -1 }
+
+/**
+ * Where the pane sits decides the UI. Docked beside the transcript (a wide
+ * fullscreen terminal) it is the full map; anywhere else — waiting undrawn on a
+ * narrow terminal, behind another tab, closed — the map collapses into the
+ * status line. A pane the surface would only seat inline above the prompt is
+ * closed unless the person asked for it with /minimap.
+ */
+const view = { placement: undefined as 'dock' | 'inline' | undefined, isAsked: false, isDocked: false, status: undefined as string | undefined }
+
+const GROW_MS = 1200
+const TYPE_MS = 600
+const FRAME_MS = 33
+const HOLD_MS = 700
+const PULSE_MS = 180
+
+/**
+ * The reveal and the highlight run on blits, not render passes: a new map's
+ * routes grow out ring by ring, then its names type out; a prior the agent
+ * bursts off pulses (its route to the seed lit) until the fresh results replace
+ * the map. Only while docked — the status line has nothing to animate.
+ */
+const MARK_MS = 4000
+/** How long a verdict stays in the footer and on the status line. */
+const VERDICT_SHOWN_MS = 10 * 60 * 1000
+const VERDICT_STATUS_MS = 60 * 1000
+const VERDICTS_KEPT = 6
+
+const motion = {
+  /** Priors the agent just judged → their verdict, pulsing until `markUntil`. */
+  marks: {} as Record<string, JudgmentKind>,
+  markUntil: 0,
+  isMarkOn: true,
+  graphAt: -1,
+  start: 0,
+  frame: FULL as Frame,
+  highlight: undefined as string | undefined,
+  highlightStart: 0,
+  isPulseOn: true,
+  raster: undefined as { columns: number; rows: number } | undefined,
+  bg: DARK_BG,
+  timer: undefined as Timer | undefined,
+}
+
+function rasterOptions(map: MapGraph): RasterOptions {
+  return {
+    frame: motion.graphAt === map.at ? motion.frame : FULL,
+    bg: motion.bg,
+    highlight: motion.highlight,
+    isPulseOn: motion.isPulseOn,
+    marks: motion.marks,
+    isMarkOn: motion.isMarkOn,
+  }
+}
+
+async function animate($: EngineInterface): Promise<void> {
+  const now = await $.clock.now()
+  const t = now - motion.start
+  const isRevealing = motion.frame.type < 1
+  if (isRevealing) {
+    motion.frame = { grow: Math.min(1, t / GROW_MS), type: Math.max(0, Math.min(1, (t - GROW_MS) / TYPE_MS)) }
+  }
+  if (motion.highlight) motion.isPulseOn = Math.floor((now - motion.highlightStart) / PULSE_MS) % 2 === 0
+  const isMarking = Object.keys(motion.marks).length > 0 && now < motion.markUntil
+  if (isMarking) motion.isMarkOn = Math.floor((now - (motion.markUntil - MARK_MS)) / PULSE_MS) % 2 === 0
+  else motion.marks = {}
+  const map = await read($, graph)
+  if (motion.raster && map.nodes.length > 0) {
+    const { columns, rows } = motion.raster
+    await $.ui.blit({ requestId: PANE, key: 'map', columns, rows, cells: rasterize(map, columns, rows, rasterOptions(map)) }).catch(() => undefined)
+  }
+  if (!isRevealing && !motion.highlight && !isMarking) {
+    motion.timer?.cancel()
+    motion.timer = undefined
+  }
+}
+
+function startMotion($: EngineInterface): void {
+  motion.timer ??= $.clock.every(FRAME_MS, () => void animate($))
+}
+
+/** Lights the prior the agent is about to burst off, if the map shows it. */
+async function highlightSeed($: EngineInterface, id: string): Promise<boolean> {
+  const map = await read($, graph)
+  if (!view.isDocked || !map.nodes.some(n => !n.isSeed && n.id === id)) return false
+  motion.highlight = id
+  motion.highlightStart = await $.clock.now()
+  motion.isPulseOn = true
+  startMotion($)
+  return true
+}
+
+/** Holds the highlight at least HOLD_MS, so the target reads before the map moves on. */
+async function holdHighlight($: EngineInterface): Promise<void> {
+  if (!motion.highlight) return
+  const left = HOLD_MS - ((await $.clock.now()) - motion.highlightStart)
+  if (left > 0) await $.clock.sleep(left)
+}
+
+/**
+ * The agent's reply judged some priors (cite / confirm / fix / refute tags):
+ * record each, and pulse the ones on the map in their verdict's colour. Refs
+ * that resolve to no node — `[id]` in prose ABOUT the protocol — are ignored.
+ */
+async function recordJudgments($: EngineInterface, text: string): Promise<void> {
+  const judgments = parseJudgments(text)
+  if (judgments.length === 0) return
+  const handles = await primingHandles($)
+  const map = await read($, graph)
+  const now = await $.clock.now()
+  const fresh: Verdict[] = []
+  for (const j of judgments) {
+    const id = resolveJudgmentRef(j.ref, handles)
+    if (!id) continue
+    const onMap = map.nodes.find(n => n.id === id)
+    fresh.push({ id, kind: j.kind, name: onMap ? displayName(onMap.label, onMap.name) : j.ref, at: now })
+    if (onMap) motion.marks[id] = j.kind
+  }
+  if (fresh.length === 0) return
+  await update($, verdicts, list => [...fresh, ...list.filter(v => !fresh.some(f => f.id === v.id))].slice(0, VERDICTS_KEPT))
+  if (Object.keys(motion.marks).length > 0 && view.isDocked) {
+    motion.markUntil = now + MARK_MS
+    motion.isMarkOn = true
+    startMotion($)
+  }
+}
+
+async function themeBackground($: EngineInterface): Promise<number> {
+  const row = (await $.config.list().catch(() => [])).find(r => r.key === 'theme')
+  return String(row?.value ?? '').includes('light') ? LIGHT_BG : DARK_BG
+}
+
+async function tick($: EngineInterface): Promise<void> {
+  await refresh($)
+  await syncLayout($)
+}
+
+async function syncLayout($: EngineInterface): Promise<void> {
+  const mine = (await $.ui.panes()).find(p => p.id === PANE)
+  if (mine?.isPlaced && view.placement === 'inline' && !view.isAsked) {
+    await $.ui.close({ id: PANE })
+    view.placement = undefined
+  }
+  const isDocked = !!mine?.isPlaced && mine.isShown && view.placement === 'dock'
+  view.isDocked = isDocked
+  const latest = (await read($, verdicts))[0]
+  const now = await $.clock.now()
+  const verdictNote =
+    latest && now - latest.at < VERDICT_STATUS_MS
+      ? ` · ${JUDGMENT_STYLE[latest.kind].glyph} ${JUDGMENT_STYLE[latest.kind].verb} ${shortName(latest.name, 32)}`
+      : ''
+  const base = isDocked ? undefined : statusLine(await read($, graph))
+  const text = base === undefined ? undefined : base + verdictNote
+  if (text !== view.status) {
+    view.status = text
+    $.ui.status(text)
+  }
+}
+
+/**
+ * Draws a burst the moment it lands and starts its reveal. Enrichment waits:
+ * the first cut walked up to 12 neighbor calls before drawing anything, so an
+ * MCP burst showed up seconds after the agent had already read it.
+ */
+async function draw($: EngineInterface, b: Burst): Promise<void> {
+  const laid = layoutBurst(b)
+  // Set the reveal up before the graph lands, so its first render is frame 0, not a flash of the finished map.
+  motion.highlight = undefined
+  if (view.isDocked) {
+    motion.graphAt = laid.at
+    motion.start = await $.clock.now()
+    motion.frame = { grow: 0, type: 0 }
+    startMotion($)
+  }
+  await update($, graph, () => laid)
+  pending.drawnAt = b.at
+}
+
+/** Catches up a burst not drawn yet, then fills in the real edges among what it delivered. */
+async function refresh($: EngineInterface): Promise<void> {
+  if (pending.isRefreshing) return
+  const current = await read($, burst)
+  if (!current) return
+  pending.isRefreshing = true
+  try {
+    if (current.at !== pending.drawnAt) await draw($, current)
+    if (current.isEnriched) return
+    // Background, after the draw: the seed's real name first (cheap, visible), then the cross edges.
+    const named = (await resolveSeed($, current)) ?? current
+    if (named !== current) {
+      if ((await read($, burst))?.at !== current.at) return
+      await update($, burst, () => named)
+      await update($, graph, () => layoutBurst(named))
+    }
+    const enriched = { ...named, extra: await crossEdges($, named), isEnriched: true }
+    // A newer burst landed while we walked: it is drawn already; drop this one.
+    const latest = await read($, burst)
+    if (latest && latest.at !== current.at) return
+    await update($, burst, () => enriched)
+    // Same `at`, same positions: the cross edges appear in place, the reveal keeps running.
+    await update($, graph, () => layoutBurst(enriched))
+  } catch (err) {
+    await update($, graph, g => ({ ...g, note: `minimap: ${String(err).slice(0, 80)}` }))
+  } finally {
+    pending.isRefreshing = false
+  }
+}
+
+async function crossEdges($: EngineInterface, b: Burst): Promise<[string, string][]> {
+  const ids = new Set([b.seed.id, ...b.nodes.map(n => n.id)])
+  const answers = await Promise.all(
+    b.nodes.slice(0, ENRICH_MAX).map(n =>
+      $.mcp.call(ERRATA, 'errata_neighbors', { nodeId: n.id, limit: 30 }).then(
+        res => [n.id, res] as const,
+        () => [n.id, undefined] as const,
+      ),
+    ),
+  )
+  const out: [string, string][] = []
+  for (const [id, res] of answers) {
+    if (!res || res.isError) continue
+    for (const hop of neighborIds(textsOf(res.content))) {
+      if (ids.has(hop.id) && hop.id !== id) out.push([id, hop.id])
+    }
+  }
+  return out
+}
+
+/** A burst names its seed by id (`file_fb8c…`): ask the graph what that node is. */
+async function resolveSeed($: EngineInterface, b: Burst | null): Promise<Burst | null> {
+  if (!b || b.seed.label !== 'Seed') return b
+  const res = await $.mcp.call(ERRATA, 'errata_neighbors', { nodeId: b.seed.id, limit: 1 }).catch(() => undefined)
+  const node = res && !res.isError ? seedNode(textsOf(res.content)) : undefined
+  return node ? { ...b, seed: { id: b.seed.id, label: node.label, name: node.name } } : b
+}
+
+/** Sets the burst the map shows and draws it now; the next tick enriches it. */
+async function show($: EngineInterface, next: Burst | null): Promise<void> {
+  if (!next) return
+  await update($, burst, () => next)
+  await draw($, next)
+}
+
+async function primingHandles($: EngineInterface): Promise<HandleTable> {
+  const cwd = await $.session.cwd()
+  const text = await $.fs.read(`${cwd}/.errata/priming-handles.json`).catch(() => '{}')
+  return JSON.parse(String(text)) as HandleTable
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'minimap', description: 'Open the errata minimap: the latest burst neighborhood that entered context' })
+    void $.ui.open({ id: PANE, title: 'errata' })
+    motion.bg = await themeBackground($)
+    $.clock.every(1500, () => void tick($))
+    return next(e)
+  })
+
+  on('config.set', { key: 'theme' }, async ($, e, next) => {
+    const done = await next(e)
+    motion.bg = await themeBackground($)
+    return done
+  })
+
+  on('command.run', { command: 'minimap' }, async $ => {
+    view.isAsked = true
+    const opened = await $.ui.open({ id: PANE, title: 'errata', columns: 56 })
+    pending.drawnAt = -1
+    void refresh($)
+    return { text: opened.isPlaced ? 'errata minimap opened.' : `minimap waits: ${opened.reason}` }
+  })
+
+  // The agent bursts through MCP: the result IS the neighborhood that entered its context.
+  on('tool.call', { tool: 'mcp__errata__errata_burst' }, async ($, e, next) => {
+    const input = e as unknown as Record<string, unknown>
+    const seed = String(input['nodeId'] ?? input['qname'] ?? '')
+    // Bursting off a prior the map already shows: light it while the burst runs.
+    await highlightSeed($, seed)
+    const ran = await next(e)
+    if (ran.deny !== undefined || ran.isError) {
+      motion.highlight = undefined
+      return ran
+    }
+    // No MCP call before the draw: the seed's name is looked up on the next tick (refresh).
+    const fresh = parseAgentBurst(textsOf([ran.text, ran.result]), seed)
+    await holdHighlight($)
+    await show($, fresh)
+    return ran
+  })
+
+  // A search is a neighborhood too: the hits that entered context, ringed around the query.
+  on('tool.call', { tool: 'mcp__errata__errata_search' }, async ($, e, next) => {
+    const ran = await next(e)
+    if (ran.deny !== undefined || ran.isError) return ran
+    const query = String((e as unknown as Record<string, unknown>)['query'] ?? '')
+    await show($, parseAgentSearch(textsOf([ran.text, ran.result]), query))
+    return ran
+  })
+
+  on('tool.call', async ($, e, next) => {
+    if (!FILE_TOOLS.has(String(e.tool))) return next(e)
+    const input = e as unknown as Record<string, unknown>
+    const abs = String(input['file_path'] ?? input['notebook_path'] ?? '')
+    const path = abs ? relPath(abs, await $.session.cwd()) : ''
+    // The daemon's file recall rides this call's hook context and names no file: remember which one.
+    if (path) await update($, focus, () => path)
+
+    const ran = await next(e)
+    if (!path || ran.deny !== undefined || ran.isError) return ran
+
+    // The agent bursting through the file surface: ask the same burst as structure.
+    const viaFile = BURST_FILE.exec(path)
+    if (e.tool === 'Read' && viaFile) {
+      const seed = decodeURIComponent(viaFile[1]!)
+      const args = /^[A-Za-z]+_[0-9a-f]{8,}|^(dprob|dfix|dcause|projn|motif)_/.test(seed) ? { nodeId: seed } : { qname: seed }
+      await highlightSeed($, seed)
+      const res = await $.mcp.call(ERRATA, 'errata_burst', args).catch(() => undefined)
+      const fresh = res && !res.isError ? parseAgentBurst(textsOf(res.content), seed) : null
+      await holdHighlight($)
+      if (fresh) await show($, fresh)
+      else motion.highlight = undefined
+    }
+    return ran
+  })
+
+  // The daemon's bursts arrive as injected rows: a file recall on a touch, the context block on a prompt.
+  on('session.append', async ($, e, next) => {
+    // The agent's own reply: its inline tags judge the priors it was shown.
+    // Text blocks only — tool inputs (a test fixture, a file being written) can
+    // carry tag syntax that judges nothing.
+    if (e.door === 'response' && !e.agentId) {
+      const said = e.message.content
+        .flatMap(b => {
+          const text: unknown = (b as { text?: unknown }).text
+          return b.type === 'text' && typeof text === 'string' ? [text] : []
+        })
+        .join('\n')
+      if (said) await recordJudgments($, said)
+    }
+    if (e.door !== 'response' && e.door !== 'prompt' && !e.agentId) {
+      const text = textsOf(e.message.content).join('\n')
+      if (text.includes('recorded on this file')) {
+        await show($, parseFileRecall(text, await read($, focus)))
+      } else if (text.includes('## Errata context')) {
+        await show($, parsePromptPrime(text, await primingHandles($)))
+      }
+    }
+    return next(e)
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    // The surface's word on where it seated us drives the status-line collapse (syncLayout).
+    if (e.surface === 'terminal') view.placement = e.props.placement
+    const width = Math.max(24, e.props.bodyColumns)
+    const height = Math.max(14, (e.viewport?.rows ?? 30) - 4)
+    const map = await read($, graph)
+
+    const delivered = map.nodes.filter(n => !n.isSeed).sort((a, b) => b.score - a.score)
+    const counts = new Map<string, number>()
+    for (const n of delivered) counts.set(n.label, (counts.get(n.label) ?? 0) + 1)
+    const legend = [...counts].sort((a, b) => b[1] - a[1])
+    const legendRows = Math.ceil(legend.reduce((w, [l, c]) => w + l.length + String(c).length + 6, 0) / width)
+    const tiers = SCOPE_ORDER.filter(s => delivered.some(n => n.scope === s))
+    const now = await $.clock.now()
+    const recent = (await read($, verdicts)).filter(v => now - v.at < VERDICT_SHOWN_MS).slice(0, 3)
+    const footRows =
+      legendRows + (tiers.length > 0 ? 1 : 0) + Math.min(TOP_ITEMS, delivered.length) + recent.length
+    const mapRows = Math.max(5, height - footRows - 2)
+    // Blits must match the mounted size: remember what this pass mounts.
+    motion.raster = { columns: width, rows: mapRows }
+
+    const minimap =
+      e.surface === 'terminal' && map.nodes.length > 0
+        ? (() => {
+            const { Raster } = $.ui.resolve(e)
+            return <Raster key="map" columns={width} rows={mapRows} cells={rasterize(map, width, mapRows, rasterOptions(map))} />
+          })()
+        : (
+            <Box height={mapRows}>
+              <Text dimColor>
+                {map.note ?? (map.nodes.length === 0 ? 'no burst yet — touch a file or burst a seed' : 'map draws in the terminal')}
+              </Text>
+            </Box>
+          )
+
+    return (
+      <Box flexDirection="column" width={width}>
+        <Text bold wrap="truncate-end">
+          {map.origin ? ORIGIN_LABEL[map.origin] : 'burst'}
+          <Text dimColor> · {delivered.length} in context · </Text>
+          <Text color="#ffd75f">◉ </Text>
+          <Text>{shortName(map.title, Math.max(8, width - 30))}</Text>
+          <Text dimColor> {map.seedLabel ?? ''}</Text>
+        </Text>
+        {minimap}
+        {tiers.length > 0 && (
+          <Text wrap="truncate-end">
+            {tiers.map(s => (
+              <Text>
+                <Text color={hex(SCOPE_COLOR[s])}>━━</Text>
+                <Text dimColor> {s}  </Text>
+              </Text>
+            ))}
+          </Text>
+        )}
+        {legend.length > 0 && (
+          <Text wrap="wrap">
+            {legend.map(([label, count]) => (
+              <Text>
+                <Text color={hex(colorOf(label))}>{String.fromCodePoint(glyphOf(label))}</Text>
+                <Text dimColor> {count} {label}   </Text>
+              </Text>
+            ))}
+          </Text>
+        )}
+        {recent.map(v => (
+          <Text wrap="truncate-end">
+            <Text color={hex(JUDGMENT_STYLE[v.kind].color)} bold>
+              {JUDGMENT_STYLE[v.kind].glyph} {JUDGMENT_STYLE[v.kind].verb}{' '}
+            </Text>
+            <Text>{v.name}</Text>
+          </Text>
+        ))}
+        {delivered.slice(0, TOP_ITEMS).map(n => (
+          <Text wrap="truncate-end">
+            <Text color={hex(colorOf(n.label))}>{String.fromCodePoint(glyphOf(n.label))} </Text>
+            <Text dimColor>{displayName(n.label, n.name)}</Text>
+          </Text>
+        ))}
+      </Box>
+    )
+  })
+}
+

package/resources/claude-mods/errata-minimap/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json"
+}

package/resources/claude-mods/errata-minimap/types/index.d.ts

@@ -0,0 +1,74 @@
+/** Who burst: the agent through the MCP tool or the `.errata/g/burst` file, or the daemon priming a file touch / a prompt. */
+export type BurstOrigin = 'agent' | 'daemon-file' | 'daemon-prompt'
+
+/** Which membrane a prior lives in: this machine only, or the project / team / org membrane, or the public Errata Network. */
+export type Scope = 'machine' | 'project' | 'team' | 'org' | 'public'
+
+export type BurstNode = {
+  id: string
+  label: string
+  name: string
+  /** Burst relevance; daemon-delivered nodes get a rank-derived stand-in. */
+  score: number
+  hops: number
+  /** The node the walk reached this one from, and by which edge. */
+  parent?: string
+  edge?: string
+  /** Absent when no client-visible signal says. */
+  scope?: Scope
+}
+
+/** One neighborhood that entered the agent's context. */
+export type Burst = {
+  origin: BurstOrigin
+  seed: { id: string; label: string; name: string }
+  nodes: BurstNode[]
+  /** Real edges among the delivered nodes, found after the fact. */
+  extra: [string, string][]
+  isEnriched: boolean
+  at: number
+}
+
+export type MapNode = {
+  id: string
+  label: string
+  name: string
+  isSeed: boolean
+  score: number
+  /** Rings out from the seed (0 for the seed): the order the reveal grows in. */
+  hops: number
+  scope?: Scope
+  x: number
+  y: number
+}
+
+export type MapGraph = {
+  title: string
+  /** The seed's node type (File, Function, Prompt, ...). */
+  seedLabel?: string
+  origin?: BurstOrigin
+  nodes: MapNode[]
+  /** Index pairs into `nodes`; `true` = an edge of the walk, `false` = a cross edge. */
+  edges: [number, number, boolean][]
+  at: number
+  note?: string
+}
+
+/** One judgment the agent made on a prior in its reply: cited, confirmed, resolved or refuted. */
+export type Verdict = {
+  id: string
+  kind: 'cite' | 'confirm' | 'fix' | 'refute'
+  name: string
+  at: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'errata-minimap': {
+      focus: string
+      burst: Burst | null
+      graph: MapGraph
+      verdicts: Verdict[]
+    }
+  }
+}