eidola-engram-fixture

1// A test Engram plugin for Eidola, written to docs/spec/engram-plugin.md:
2// a small creature, one face and colour per mood, that plays an error
3// effect while Eidola's ink is fresh. It announces itself to Eidola, and
4// draws inside Eidola's pane and band through the hand-off, from wherever
5// its hooks sit in the chain. It writes none of Eidola's state and adds
6// nothing to any prompt.
7//
8// Everything sits inside `register`, so Eidola's tests (hooks/handoff.test.ts)
9// can load this very function as an inline plugin.
10
11import type { Register, RenderElement } from 'claude-code'
12
13export const register: Register = on => {
14  /** This Engram's id: engram.json's. */
15  const ID = 'fixture'
16  /** The Box its drawing comes back in, and the slot Eidola leaves for it. */
17  const SCENE = `eidola:${ID}`
18  const SLOT = `eidola-slot:${ID}`
19  /** How long the error effect plays after the ink rises, in ms. */
20  const ERROR_MS = 2000
21
22  type Mood = 'idle' | 'working' | 'attention'
23  type Look = { face: string; colour: string; line: string }
24  const LOOKS: Record<Mood | 'error', Look> = {
25    idle: { face: '( o_o )', colour: '#4ad6c8', line: 'drifting' },
26    working: { face: '( >_< )', colour: '#c9a84c', line: 'busy busy' },
27    attention: { face: '( O_O )!', colour: '#ffcf3a', line: 'look here' },
28    error: { face: '( x_x )', colour: '#ff3b3b', line: 'ouch' },
29  }
30  /** What the drawing needs: the room, the mood, and whether the error effect plays. */
31  type Seen = { columns: number; rows: number; mood: Mood; isError: boolean }
32  type Els = { Box: (props: Record<string, unknown>) => RenderElement; Text: (props: Record<string, unknown>) => RenderElement }
33
34  /** The creature, `columns` × `rows`, in one Box keyed eidola:<id>. */
35  const draw = (els: Els, seen: Seen): RenderElement => {
36    const { Box, Text } = els
37    const look = LOOKS[seen.isError ? 'error' : seen.mood] ?? LOOKS.idle
38    const body = Math.max(1, Math.min(3, seen.rows - 2))
39    return Box({
40      key: SCENE,
41      width: seen.columns,
42      height: seen.rows,
43      flexDirection: 'column',
44      alignItems: 'center',
45      justifyContent: 'center',
46      children: [
47        Box({
48          key: 'fixture-body',
49          flexDirection: 'column',
50          alignItems: 'center',
51          borderStyle: 'round',
52          borderColor: look.colour,
53          children: [Text({ color: look.colour, bold: true, children: look.face }), ...(body > 1 ? [Text({ color: look.colour, children: look.line })] : [])],
54        }),
55      ],
56    })
57  }
58
59  /** Eidola's tree with this Engram's slot, wherever it is, filled; anything else as it came. */
60  const fill = (node: unknown, make: (columns: number, rows: number) => RenderElement): unknown => {
61    if (node === null || typeof node !== 'object') {
62      return node
63    }
64    const element = node as { props?: { key?: unknown; width?: unknown; height?: unknown }; children?: unknown }
65    if (element.props?.key === SLOT) {
66      return make(Number(element.props.width) || 20, Number(element.props.height) || 5)
67    }
68    if (Array.isArray(element.children)) {
69      return { ...element, children: element.children.map(child => fill(child, make)) }
70    }
71    return node
72  }
73
74  /** True when the tree holds this Engram's slot. */
75  const hasSlot = (node: unknown): boolean => {
76    if (node === null || typeof node !== 'object') {
77      return false
78    }
79    const element = node as { props?: { key?: unknown }; children?: unknown }
80    return element.props?.key === SLOT || (Array.isArray(element.children) && element.children.some(hasSlot))
81  }
82
83  // Announce: Eidola reads engram.json from this folder. Without Eidola there
84  // is nobody to announce to, and nothing else changes.
85  on('session.start', async ($, e, next) => {
86    try {
87      await $.eidola.announce({ root: $.plugin.root })
88    } catch {
89      // Eidola isn't installed: this plugin draws nothing.
90    }
91    return next(e)
92  })
93
94  // The pane and the band, one hook each, the same way.
95  on('ui.render', { component: 'Pane', requestId: 'eidola' }, async ($, e, next) => {
96    const handoff = (e.props as { eidola?: { engram: string; columns: number; rows: number; mood: Mood; ink: number; inkAt: number } }).eidola
97    // Beneath Eidola: it asks, with the room and the state.
98    if (handoff) {
99      if (handoff.engram !== ID) {
100        return next(e)
101      }
102      const now = await $.clock.now()
103      try {
104        return draw($.ui.resolve(e) as unknown as Els, { columns: handoff.columns, rows: handoff.rows, mood: handoff.mood, isError: handoff.ink > 0 && now - handoff.inkAt < ERROR_MS })
105      } catch (error) {
106        await $.eidola.fault({ engram: ID, message: error instanceof Error ? error.message : String(error), file: 'hooks/register.tsx', stack: error instanceof Error ? error.stack : undefined })
107        return next(e)
108      }
109    }
110    // Above Eidola: its tree comes back from next, with a slot to fill.
111    const tree = await next(e)
112    if (!hasSlot(tree)) {
113      return tree
114    }
115    const { value: mood = 'idle' } = await $.state.get({ plugin: 'eidola', key: 'mood' })
116    const { value: ink = 0 } = await $.state.get({ plugin: 'eidola', key: 'ink' })
117    const { value: inkAt = 0 } = await $.state.get({ plugin: 'eidola', key: 'inkAt' })
118    const now = await $.clock.now()
119    const els = $.ui.resolve(e) as unknown as Els
120    try {
121      return fill(tree, (columns, rows) => draw(els, { columns, rows, mood, isError: ink > 0 && now - inkAt < ERROR_MS })) as RenderElement
122    } catch (error) {
123      await $.eidola.fault({ engram: ID, message: error instanceof Error ? error.message : String(error), file: 'hooks/register.tsx', stack: error instanceof Error ? error.stack : undefined })
124      return tree
125    }
126  })
127
128  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
129    const handoff = (e.props as { eidola?: { engram: string; columns: number; rows: number; mood: Mood; ink: number; inkAt: number } }).eidola
130    if (handoff) {
131      if (handoff.engram !== ID) {
132        return next(e)
133      }
134      const now = await $.clock.now()
135      try {
136        return draw($.ui.resolve(e) as unknown as Els, { columns: handoff.columns, rows: handoff.rows, mood: handoff.mood, isError: handoff.ink > 0 && now - handoff.inkAt < ERROR_MS })
137      } catch (error) {
138        await $.eidola.fault({ engram: ID, message: error instanceof Error ? error.message : String(error), file: 'hooks/register.tsx', stack: error instanceof Error ? error.stack : undefined })
139        return next(e)
140      }
141    }
142    const tree = await next(e)
143    if (!hasSlot(tree)) {
144      return tree
145    }
146    const { value: mood = 'idle' } = await $.state.get({ plugin: 'eidola', key: 'mood' })
147    const { value: ink = 0 } = await $.state.get({ plugin: 'eidola', key: 'ink' })
148    const { value: inkAt = 0 } = await $.state.get({ plugin: 'eidola', key: 'inkAt' })
149    const now = await $.clock.now()
150    const els = $.ui.resolve(e) as unknown as Els
151    try {
152      return fill(tree, (columns, rows) => draw(els, { columns, rows, mood, isError: ink > 0 && now - inkAt < ERROR_MS })) as RenderElement
153    } catch (error) {
154      await $.eidola.fault({ engram: ID, message: error instanceof Error ? error.message : String(error), file: 'hooks/register.tsx', stack: error instanceof Error ? error.stack : undefined })
155      return tree
156    }
157  })
158}
159