Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(console): draw pictures on Claude Code Desktop as Svg, decide by surface

Dragan Spiridonovd89973b4dc3d
diff --git a/plugins/ruflo-console/hooks/controller.ts b/plugins/ruflo-console/hooks/controller.ts
index c0b90b9b53..3d6045bf03 100644
--- a/plugins/ruflo-console/hooks/controller.ts
+++ b/plugins/ruflo-console/hooks/controller.ts
@@ -275,7 +275,8 @@ export function createController(state: State, host: Host): Controller {
if (pulseDue(state.view, started) || (state.view === 'menu' && entryAge({ look: state.options.look, boot: state.options.boot, ...state.pane }, started, BOOT_MIN_MS) !== null)) host.invalidate()
- for (const [key, grid] of picturesOf(state, state.pane.columns, Date.now(), Date.now())) {
+ // Only a mounted Raster is blitted, so with none (a surface that draws Svg, which redraws with the pane) nothing is rebuilt here.
+ for (const [key, grid] of state.mounted.size === 0 ? [] : picturesOf(state, state.pane.columns, Date.now(), Date.now())) {
const mounted = state.mounted.get(key)
if (mounted !== undefined && mounted.columns === grid.columns && mounted.rows === grid.rows) {
@@ -291,7 +292,7 @@ export function createController(state: State, host: Host): Controller {
// Something in progress moves its spinner, pictured or not: a lab action in flight, or a live mission, task or guidance run on the Missions page.
const moving = state.lab.running !== null || (state.view === 'missions' && hasLiveWork(state.snapshot?.missions?.missions ?? [], mcOf(state).guidance?.status === 'running'))
- if (!(state.options.fps > 0 && isVisible() && (state.pane.isFocused || isBooting(state, Date.now())) && (state.mounted.size > 0 || moving))) return cancel('frames')
+ if (!(state.options.fps > 0 && isVisible() && (state.pane.isFocused || isBooting(state, Date.now())) && (state.pictured > 0 || moving))) return cancel('frames')
every('frames', Math.round(1000 / state.options.fps), frame)
}
@@ -414,6 +415,7 @@ export function createController(state: State, host: Host): Controller {
state.pane.viewAtMs = Date.now()
state.select.item = 0
state.mounted.clear()
+ state.pictured = 0
persist()
// A new view asks for its own height inline; the dock ignores it.
if (state.pane.isOpen) void host.openPane({ id: PANE_ID, title: 'ruflo', rows: rowsOf(view), ...(state.dockColumns > 0 && { columns: state.dockColumns }) }).catch(() => undefined)
diff --git a/plugins/ruflo-console/hooks/gfx/svg.ts b/plugins/ruflo-console/hooks/gfx/svg.ts
new file mode 100644
index 0000000000..c798d8b0e5
--- /dev/null
+++ b/plugins/ruflo-console/hooks/gfx/svg.ts
@@ -0,0 +1,185 @@
+/**
+ * Cell graphics for the surfaces that draw vectors (Claude Code Desktop, the editor, the mobile app): the same `Grid` the terminal gets as a
+ * `Raster`, written as one SVG document. Block and braille glyphs become rectangles, so they line up whatever font the surface has; other
+ * glyphs are placed one by one on the cell grid, so a proportional fallback font cannot drift them. Pure: no `$`, no Node.
+ */
+import { DEFAULT, type Grid } from './raster'
+
+/** The host's limit on an `Svg` element's `source`; a longer one makes the whole tree invalid, so the picture is dropped instead. */
+export const SVG_SOURCE_MAX = 131_072
+/** One cell in SVG user units: the width of a monospace glyph and a line of text at 13 px. */
+export const CELL_W = 8
+export const CELL_H = 16
+/** The terminal's own foreground has no value outside a terminal: a grey that reads on a light and on a dark page. */
+const DEFAULT_FG = '#8b949e'
+const FONT = 'font-family="SFMono-Regular, Menlo, Consolas, DejaVu Sans Mono, monospace" font-size="13"'
+
+/** A rectangle as fractions of a cell: [x, y, width, height]. */
+type Rect = readonly [number, number, number, number]
+
+const UL: Rect = [0, 0, 0.5, 0.5]
+const UR: Rect = [0.5, 0, 0.5, 0.5]
+const LL: Rect = [0, 0.5, 0.5, 0.5]
+const LR: Rect = [0.5, 0.5, 0.5, 0.5]
+
+/**
+ * Every Block Elements glyph (U+2580 to U+259F) as the rectangles it fills and their opacity: eighths from the bottom and from the left,
+ * the halves, the upper and right eighths, the shades, and the quadrants.
+ */
+const SHAPES = new Map<number, { rects: readonly Rect[]; opacity: number }>([
+ [0x2580, { rects: [[0, 0, 1, 0.5]], opacity: 1 }], // β–€
+ ...[1, 2, 3, 4, 5, 6, 7, 8].map(n => [0x2580 + n, { rects: [[0, 1 - n / 8, 1, n / 8]] as Rect[], opacity: 1 }] as const), // β–β–‚β–ƒβ–„β–…β–†β–‡β–ˆ
+ ...[7, 6, 5, 4, 3, 2, 1].map((n, i) => [0x2589 + i, { rects: [[0, 0, n / 8, 1]] as Rect[], opacity: 1 }] as const), // β–‰β–Šβ–‹β–Œβ–β–Žβ–
+ [0x2590, { rects: [[0.5, 0, 0.5, 1]], opacity: 1 }], // ▐
+ [0x2591, { rects: [[0, 0, 1, 1]], opacity: 0.25 }], // β–‘
+ [0x2592, { rects: [[0, 0, 1, 1]], opacity: 0.5 }], // β–’
+ [0x2593, { rects: [[0, 0, 1, 1]], opacity: 0.75 }], // β–“
+ [0x2594, { rects: [[0, 0, 1, 1 / 8]], opacity: 1 }], // β–”
+ [0x2595, { rects: [[7 / 8, 0, 1 / 8, 1]], opacity: 1 }], // β–•
+ [0x2596, { rects: [LL], opacity: 1 }], // β––
+ [0x2597, { rects: [LR], opacity: 1 }], // β–—
+ [0x2598, { rects: [UL], opacity: 1 }], // β–˜
+ [0x2599, { rects: [UL, LL, LR], opacity: 1 }], // β–™
+ [0x259a, { rects: [UL, LR], opacity: 1 }], // β–š
+ [0x259b, { rects: [UL, UR, LL], opacity: 1 }], // β–›
+ [0x259c, { rects: [UL, UR, LR], opacity: 1 }], // β–œ
+ [0x259d, { rects: [UR], opacity: 1 }], // ▝
+ [0x259e, { rects: [UR, LL], opacity: 1 }], // β–ž
+ [0x259f, { rects: [UR, LL, LR], opacity: 1 }], // β–Ÿ
+])
+
+/** Braille dot bit β†’ [column, row] in the 2Γ—4 dot cell. */
+const DOTS: readonly (readonly [number, number])[] = [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [0, 3], [1, 3]]
+
+const hex = (color: number): string => `#${(color & 0xffffff).toString(16).padStart(6, '0')}`
+const fgOf = (color: number): string => (color === DEFAULT ? DEFAULT_FG : hex(color))
+const n = (value: number): string => (Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/0+$/, ''))
+
+/** Escapes text for an element body or an attribute; drops the code points XML 1.0 cannot hold at all. */
+export function escapeXml(text: string): string {
+ let out = ''
+
+ for (const ch of text) {
+ const cp = ch.codePointAt(0) as number
+
+ if ((cp < 0x20 && cp !== 0x09 && cp !== 0x0a && cp !== 0x0d) || (cp >= 0xd800 && cp <= 0xdfff) || cp === 0xfffe || cp === 0xffff) continue
+ out += ch === '&' ? '&amp;' : ch === '<' ? '&lt;' : ch === '>' ? '&gt;' : ch === '"' ? '&quot;' : ch === "'" ? '&apos;' : ch
+ }
+
+ return out
+}
+
+/** Paths keyed by fill colour and opacity, each a run of `M x y h w v h h -w z` rectangles: one element per colour, not one per cell. */
+class Fills {
+ private readonly paths = new Map<string, string[]>()
+
+ rect(fill: string, opacity: number, x: number, y: number, w: number, h: number): void {
+ const key = opacity === 1 ? fill : `${fill}|${opacity}`
+ const list = this.paths.get(key) ?? []
+
+ list.push(`M${n(x)} ${n(y)}h${n(w)}v${n(h)}h${n(-w)}z`)
+ this.paths.set(key, list)
+ }
+
+ toSvg(): string {
+ return [...this.paths].map(([key, list]) => {
+ const [fill, opacity] = key.split('|')
+
+ return `<path fill="${fill}"${opacity === undefined ? '' : ` fill-opacity="${opacity}"`} d="${list.join('')}"/>`
+ }).join('')
+ }
+}
+
+/**
+ * The grid as an SVG document, or null when it would pass `max` characters (the caller then says it in words). `alt` is its title.
+ * Drawn `CELL_W`Γ—`CELL_H` per cell; the default background is left transparent, so the page shows through as it does in a terminal.
+ */
+export function gridToSvg(grid: Grid, alt: string, max = SVG_SOURCE_MAX): string | null {
+ const back = new Fills()
+ const fore = new Fills()
+ const texts: string[] = []
+ let size = 0
+
+ for (let y = 0; y < grid.rows; y++) {
+ // Backgrounds: one rectangle per run of a colour along the row.
+ for (let x = 0; x < grid.columns; ) {
+ const bg = grid.cells[(y * grid.columns + x) * 3 + 2] as number
+ let end = x + 1
+
+ while (end < grid.columns && grid.cells[(y * grid.columns + end) * 3 + 2] === bg) end++
+ if (bg !== DEFAULT) {
+ back.rect(hex(bg), 1, x * CELL_W, y * CELL_H, (end - x) * CELL_W, CELL_H)
+ size += 28
+ }
+ x = end
+ }
+
+ // Foregrounds: shapes as rectangles (a run of the same shape and colour merged), the rest as text placed cell by cell.
+ let run: { fg: string; xs: number[]; text: string } | null = null
+ const flush = () => {
+ if (run === null) return
+ const element = `<text ${FONT} fill="${run.fg}" x="${run.xs.join(' ')}" y="${y * CELL_H + 12}" xml:space="preserve">${run.text}</text>`
+
+ texts.push(element)
+ size += element.length
+ run = null
+ }
+
+ for (let x = 0; x < grid.columns; x++) {
+ const at = (y * grid.columns + x) * 3
+ const cp = grid.cells[at] as number
+ const fg = fgOf(grid.cells[at + 1] as number)
+ const shape = SHAPES.get(cp)
+
+ if (shape !== undefined) {
+ flush()
+ let end = x + 1
+
+ while (end < grid.columns && grid.cells[(y * grid.columns + end) * 3] === cp && fgOf(grid.cells[(y * grid.columns + end) * 3 + 1] as number) === fg) end++
+
+ const [only] = shape.rects
+
+ // A full-width shape repeated along the row is one rectangle; any other (β–Œ, β–•, a quadrant) leaves gaps, so each cell is its own.
+ if (shape.rects.length === 1 && only !== undefined && only[0] === 0 && only[2] === 1) {
+ fore.rect(fg, shape.opacity, x * CELL_W, (y + only[1]) * CELL_H, (end - x) * CELL_W, only[3] * CELL_H)
+ size += 28
+ } else {
+ for (let k = x; k < end; k++) for (const [sx, sy, sw, sh] of shape.rects) fore.rect(fg, shape.opacity, (k + sx) * CELL_W, (y + sy) * CELL_H, sw * CELL_W, sh * CELL_H)
+ size += 28 * shape.rects.length * (end - x)
+ }
+ x = end - 1
+ } else if (cp >= 0x2800 && cp <= 0x28ff) {
+ flush()
+ DOTS.forEach(([col, row], bit) => {
+ if (((cp - 0x2800) >> bit) & 1) {
+ fore.rect(fg, 1, x * CELL_W + col * 4 + 1, y * CELL_H + row * 4 + 1, 2, 2)
+ size += 20
+ }
+ })
+ } else {
+ // A control character (XML would turn a CR or a TAB into something else), a value past Unicode (a Grid holds any u32, and
+ // String.fromCodePoint would throw) or one XML cannot hold is a blank cell, decided per cell so every later glyph keeps its column.
+ const glyph = cp <= 0x20 || (cp >= 0x7f && cp <= 0x9f) || cp === 0xfe0f || cp === 0xfe0e || cp > 0x10ffff ? '' : escapeXml(String.fromCodePoint(cp))
+
+ if (glyph === '') flush()
+ else if (run !== null && run.fg === fg) {
+ run.text += glyph
+ run.xs.push(x * CELL_W)
+ } else {
+ flush()
+ run = { fg, xs: [x * CELL_W], text: glyph }
+ }
+ }
+
+ if (size > max) return null
+ }
+
+ flush()
+ }
+
+ const width = grid.columns * CELL_W
+ const height = grid.rows * CELL_H
+ const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img"><title>${escapeXml(alt)}</title>${back.toSvg()}${fore.toSvg()}${texts.join('')}</svg>`
+
+ return svg.length > max ? null : svg
+}
diff --git a/plugins/ruflo-console/hooks/register.ts b/plugins/ruflo-console/hooks/register.ts
index 296c89d4ee..07d54159e0 100644
--- a/plugins/ruflo-console/hooks/register.ts
+++ b/plugins/ruflo-console/hooks/register.ts
@@ -24,7 +24,7 @@ import { prefsFromStore, recordToast, saveToastPrefs, TOASTS_KEY } from './toast
import { contextSection, onPromptSubmit, onTurnComplete } from './mission-claude'
import { parseMode, RECHECK_EVERY_MS, UPDATES_KEY } from './updates'
import { selfCheckResults } from './self-check'
-import type { Kit } from './views/common'
+import { kitForSurface, type Kit } from './views/common'
import { createToaster, type Digest, type ToastLevel, type ToastPrefs } from './toast-policy'
import { picturesOf } from './views/frames'
import { withClearing } from './views/clearing'
@@ -311,7 +311,7 @@ export const register: Register = (on, raw: PluginOptions) => {
}
const started = Date.now()
- const table = $.ui.resolve(e) as unknown as Kit
+ const table = kitForSurface($.ui.resolve(e) as unknown as Kit, e.surface)
const columns = Math.max(20, Math.floor(Number(e.props.bodyColumns) || 0) - 1)
const isNarrow = columns < NARROW
const kit: Kit = isNarrow ? { Box: table.Box, Text: table.Text, Button: table.Button, ...(table.Input !== undefined && { Input: table.Input }) } : table
@@ -326,9 +326,10 @@ export const register: Register = (on, raw: PluginOptions) => {
// A reload while the pane stayed up: timers are gone, so resume them from here.
if (!state.timers.has('watch')) control.resume()
- const pictures = isNarrow ? new Map() : picturesOf(state, columns, Date.now(), Date.now())
+ const pictures = isNarrow ? new Map() : picturesOf(state, columns, Date.now(), Date.now(), kit.Raster === undefined)
- state.mounted = new Map([...pictures].map(([key, grid]) => [key, { columns: grid.columns, rows: grid.rows }]))
+ state.mounted = kit.Raster === undefined ? new Map() : new Map([...pictures].map(([key, grid]) => [key, { columns: grid.columns, rows: grid.rows }]))
+ state.pictured = pictures.size
control.animate()
const tree = paneView({ kit: withClearing(kit, state, control.actions.clearField, { columns, repaint: () => host?.invalidate() }), state, nowMs: Date.now(), columns, pictures, act: control.actions })
@@ -360,7 +361,7 @@ export const register: Register = (on, raw: PluginOptions) => {
return next(e)
}
- const table = $.ui.resolve(e) as unknown as Kit
+ const table = kitForSurface($.ui.resolve(e) as unknown as Kit, e.surface)
const bound = control
state.barDrawnAtMs = Date.now()
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index f92cf09f4a..d7500bf83b 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -271,8 +271,10 @@ export type State = {
/** The dock width asked for (RUFLO_CONSOLE_COLUMNS, 40 to 400); 0 leaves the engine's share. A request: a dragged width wins. */
dockColumns: number
pane: { isOpen: boolean; isShown: boolean; isFocused: boolean; columns: number; rows: number; placement: 'dock' | 'inline'; isClosedByPerson: boolean; autoTried: boolean; autoReason: string; /** When the pane last opened: the BBS boot screen plays from here. */ bootAtMs: number; /** When the boot ended: the menu's entry plays from here (0: not yet). */ menuAtMs: number; /** When the page was last switched: its title strikes in from here (0: not since the pane opened). */ viewAtMs: number }
- /** The size of each Raster as last mounted, by key: a blit of any other size is refused, so none is sent. */
+ /** The size of each Raster as last mounted, by key: a blit of any other size is refused, so none is sent. Empty where the surface draws Svg. */
mounted: Map<string, { columns: number; rows: number }>
+ /** How many pictures the view in front drew at its last render, Raster or Svg: the frame loop runs while there are any, as it did when all were mounted. */
+ pictured: number
select: { claim: number; agent: number; task: number; item: number }
/** The drill-down's agent and what `agent logs` printed for it. */
drill: { agentId: string | null; logs: string[] | null; logsAtMs: number }
@@ -392,6 +394,7 @@ export function newState(raw: PluginOptions | undefined): State {
fieldText: new Map(),
pane: { isOpen: false, isShown: false, isFocused: false, columns: 0, rows: 0, placement: 'inline', isClosedByPerson: false, autoTried: false, autoReason: '', bootAtMs: 0, menuAtMs: 0, viewAtMs: 0 },
mounted: new Map(),
+ pictured: 0,
select: { claim: 0, agent: 0, task: 0, item: 0 },
drill: { agentId: null, logs: null, logsAtMs: 0 },
palette: { isOpen: false, query: '', index: 0, context: 'all' },
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 3f74270482..31a5cc5c42 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -26,6 +26,7 @@ import type { CatalogActions } from '../plugin-catalog'
import type { SettingsActions } from '../settings'
import type { DevtoolsActions } from '../devtools'
import type { Grid } from '../gfx/raster'
+import { CELL_W, gridToSvg } from '../gfx/svg'
import type { MemoryActions } from '../memory-lab'
import type { NavActions } from '../nav-state'
import type { SkillActions } from '../skills'
@@ -41,7 +42,18 @@ import { accentOfView } from '../nav-state'
import type { VectorActions } from '../vector'
import type { WorkflowsActions } from '../wf-actions'
-export type Kit = Pick<Elements['terminal'], 'Box' | 'Text' | 'Button'> & { Raster?: Elements['terminal']['Raster']; Input?: Elements['terminal']['Input'] }
+export type Kit = Pick<Elements['terminal'], 'Box' | 'Text' | 'Button'> & { Raster?: Elements['terminal']['Raster']; Svg?: Elements['desktop']['Svg']; Input?: Elements['terminal']['Input'] }
+
+/**
+ * The kit a surface really draws pictures with. The host completes every table it resolves with every element name, an omitted one
+ * drawing a fragment, so `Raster` is defined on the desktop too and draws nothing there: whether a picture can be drawn is the surface's
+ * to say, never the table's. The terminal gets its `Raster` and no `Svg`; every other surface gets `Svg` and no `Raster`.
+ */
+export function kitForSurface<K extends Kit>(table: K, surface: string): K {
+ const { Raster, Svg, ...rest } = table
+
+ return (surface === 'terminal' ? { ...rest, ...(Raster !== undefined && { Raster }) } : { ...rest, ...(Svg !== undefined && { Svg }) }) as K
+}
/** What a button can ask for: every one a closure over the controller. */
export type Actions = {
@@ -337,15 +349,25 @@ export function kv(ctx: Ctx, label: string, value: string, color?: string): Rend
])
}
-/** A Raster for a picture of this frame, or a dim note where the surface has no Raster. */
-export function picture(ctx: Ctx, key: string, fallback: string): RenderElement {
- const grid = ctx.pictures.get(key)
+/**
+ * A picture as the surface draws it: a Raster on the terminal, an Svg of the same cells where the surface draws vectors, or null where it
+ * draws neither or the drawing would pass the host's size limit (the caller then says it in words). `alt` is what the picture says.
+ */
+export function art(ctx: Ctx, grid: Grid | undefined, key: string, alt: string): RenderElement | null {
+ if (grid === undefined) return null
+ if (ctx.kit.Raster !== undefined) return ctx.kit.Raster(grid.toRaster(key))
+ if (ctx.kit.Svg === undefined) return null
- if (grid === undefined || ctx.kit.Raster === undefined) {
- return text(ctx, fallback, { dimColor: true })
- }
+ // The words a picture falls back to say what it shows, but "needs a terminal" is not true of a surface that draws it.
+ const label = alt.replace(/\s+needs? a terminal(?: that draws pictures)?/g, '').trim() || key
+ const source = gridToSvg(grid, label)
- return ctx.kit.Raster(grid.toRaster(key))
+ return source === null ? null : ctx.kit.Box({ key: `svg-${key}`, children: [ctx.kit.Svg({ source, alt: label, width: grid.columns * CELL_W })] })
+}
+
+/** A picture of this frame as the surface draws it, or a dim note where it cannot be drawn. */
+export function picture(ctx: Ctx, key: string, fallback: string): RenderElement {
+ return art(ctx, ctx.pictures.get(key), key, fallback) ?? text(ctx, fallback, { dimColor: true })
}
export function button(ctx: Ctx, key: string, label: string, onPress: () => void, options: { hotkey?: string; primary?: boolean } = {}): RenderElement {
diff --git a/plugins/ruflo-console/hooks/views/frames.ts b/plugins/ruflo-console/hooks/views/frames.ts
index fb2656de36..bde510e50c 100644
--- a/plugins/ruflo-console/hooks/views/frames.ts
+++ b/plugins/ruflo-console/hooks/views/frames.ts
@@ -177,10 +177,15 @@ function titleThatFits(paneColumns: number, names: readonly string[], build: (na
return build(names.at(-1) as string, room)
}
-export function picturesOf(state: State, columns: number, nowMs: number, t: number): Map<string, Grid> {
+export function picturesOf(state: State, columns: number, nowMs: number, t: number, still = false): Map<string, Grid> {
const pictures = new Map<string, Grid>()
const theme = activeTheme(state)
- const motionTime = state.options.fps > 0 ? t * theme.motion.speed : 0
+ // Still, for a surface that draws Svg and so cannot animate a picture: nothing strikes in and the motion stops, as with fps 0, and the
+ // decorative light (the header's sweep, the title's shimmer) is off rather than caught mid-way. The boot keeps its real time, so its
+ // progress shows (fps 0 has no Orbital boot at all), and a picture of data is drawn as of this render.
+ const moving = state.options.fps > 0 && !still
+ const motionTime = moving ? t * theme.motion.speed : 0
+ const light = still ? 0 : t
// A page in cards (views/card.ts) is narrower by the border and padding: its pictures are drawn to that width, by the render and by the frame loop alike.
const width = Math.max(20, Math.min(200, hasCards(columns, isCompactPane(state)) ? columns - CARD_COLUMNS : columns))
const snapshot = state.snapshot
@@ -194,14 +199,14 @@ export function picturesOf(state: State, columns: number, nowMs: number, t: numb
// The headers strike in when a page is switched to and when the menu enters (never with fps 0, which draws the still header).
const sinceSwitch = state.pane.viewAtMs > 0 ? nowMs - state.pane.viewAtMs : Infinity
- const headerAge = state.options.fps > 0 ? Math.min(sinceSwitch, entryAge({ look: state.options.look, boot: state.options.boot, ...state.pane }, nowMs, BOOT_MIN_MS) ?? Infinity) : Infinity
+ const headerAge = moving ? Math.min(sinceSwitch, entryAge({ look: state.options.look, boot: state.options.boot, ...state.pane }, nowMs, BOOT_MIN_MS) ?? Infinity) : Infinity
if (state.view === 'menu') {
const project = state.cwd.split('/').filter(Boolean).at(-1) ?? ''
- pictures.set('header', state.options.look === 'bbs' ? fitHeader(columns, size => bannerPicture(project, size, t, headerAge), 72) : headerPicture(`β—† ruflo v${CONSOLE_VERSION}${getBuild() === '' ? '' : ` Β· ${getBuild()}`} Β· ${project}`, Math.min(width, 64), t))
+ pictures.set('header', state.options.look === 'bbs' ? fitHeader(columns, size => bannerPicture(project, size, light, headerAge), 72) : headerPicture(`β—† ruflo v${CONSOLE_VERSION}${getBuild() === '' ? '' : ` Β· ${getBuild()}`} Β· ${project}`, Math.min(width, 64), light))
// The palette strip above the menu's groups moves while the frame loop runs; with fps 0 it is the still strip (the light is off it).
- if (state.options.look === 'bbs') pictures.set('palette', palettePicture(Math.max(8, width - 2), state.options.fps > 0 ? t : 0, PALETTE.map(rgb)))
+ if (state.options.look === 'bbs') pictures.set('palette', palettePicture(Math.max(8, width - 2), moving ? t : 0, PALETTE.map(rgb)))
}
// BBS: every view's name as ANSI-style block art under the tabs, compact or not (the neon sign is the boot's alone).
@@ -214,7 +219,7 @@ export function picturesOf(state: State, columns: number, nowMs: number, t: numb
const shortName = VIEWS.find(view => view.id === state.view)?.short ?? page
const names = state.view === 'menu' && !state.isHelp && !state.palette.isOpen ? [name] : [name, page, shortName]
- pictures.set('title', titleThatFits(columns, names, (candidate, size) => titlePicture(candidate, size, t, headerAge)))
+ pictures.set('title', titleThatFits(columns, names, (candidate, size) => titlePicture(candidate, size, light, headerAge)))
}
if (state.options.look === 'orbital') {
@@ -228,8 +233,8 @@ export function picturesOf(state: State, columns: number, nowMs: number, t: numb
const draft = themesOf(state).draft
const layout = themeLayout(Math.min(columns, width))
const previewWidth = Math.max(1, layout.preview - 2)
- if (draft.motion.globe) pictures.set('theme-globe', orbitalGlobe(previewWidth, layout.wide ? 14 : 9, state.options.fps > 0 ? t * draft.motion.speed : 0, draft))
- pictures.set('theme-preview', orbitalHeader('swarm preview', previewWidth, state.options.fps > 0 ? t * draft.motion.speed : 0, layout.wide ? 16 : 4, draft))
+ if (draft.motion.globe) pictures.set('theme-globe', orbitalGlobe(previewWidth, layout.wide ? 14 : 9, moving ? t * draft.motion.speed : 0, draft))
+ pictures.set('theme-preview', orbitalHeader('swarm preview', previewWidth, moving ? t * draft.motion.speed : 0, layout.wide ? 16 : 4, draft))
}
switch (state.view) {
diff --git a/plugins/ruflo-console/hooks/views/learning.ts b/plugins/ruflo-console/hooks/views/learning.ts
index 3e17c4006d..398c889cb9 100644
--- a/plugins/ruflo-console/hooks/views/learning.ts
+++ b/plugins/ruflo-console/hooks/views/learning.ts
@@ -1,7 +1,7 @@
import type { RenderElement } from 'claude-code'
import type { Intelligence } from '../data/cli'
-import { ago, col, count, kv, live, pct, picture, row, section, sourceLine, starts, text, THEME, type Ctx } from './common'
+import { ago, art, col, count, kv, live, pct, picture, row, section, sourceLine, starts, text, THEME, type Ctx } from './common'
import { stagesOf } from './frames'
import { CARD_COLUMNS, hasCards } from './card'
import { pipeStagesOf, routeModelOf, stageNote } from '../data/pipeline'
@@ -12,9 +12,9 @@ import { resultRows } from './automate'
import { pulseRows } from './learning-pulse'
import { neuralActionRows } from './neural'
-/** A picture drawn here from the real state (the registry in frames.ts is not touched): the grid when the terminal has Raster, else its words. */
+/** A picture drawn here from the real state (the registry in frames.ts is not touched): as the surface draws it, else its words. */
function drawn(ctx: Ctx, key: string, grid: Grid, fallback: string): RenderElement {
- return ctx.kit.Raster === undefined ? text(ctx, fallback, { dimColor: true }) : ctx.kit.Raster(grid.toRaster(key))
+ return art(ctx, grid, key, fallback) ?? text(ctx, fallback, { dimColor: true })
}
/** The width a picture is drawn to: a page in cards is narrower by the border and padding, as in frames.ts. */
diff --git a/plugins/ruflo-console/hooks/views/memmap.ts b/plugins/ruflo-console/hooks/views/memmap.ts
index b8074a25b0..efff8c84ec 100644
--- a/plugins/ruflo-console/hooks/views/memmap.ts
+++ b/plugins/ruflo-console/hooks/views/memmap.ts
@@ -5,7 +5,7 @@ import { hitsOf, isHit } from '../data/memmap'
import { drawable, layout, MAP_ROWS, memmapPicture, SPACE_COLORS, spacesOf, type MapEntry, type MapPoint } from '../gfx/memmap'
import type { Grid } from '../gfx/raster'
import type { State } from '../state'
-import { clip, count, live, row, rule, text, type Ctx } from './common'
+import { art, clip, count, live, row, rule, text, type Ctx } from './common'
import { note } from './subhead'
/** Namespaces named in the key at most: a store with hundreds would otherwise grow the page without bound. */
@@ -52,7 +52,9 @@ export function memmapPictures(state: State, columns: number): Map<string, Grid>
function mapPicture(ctx: Ctx, entries: number, spaces: number): RenderElement {
const grid = ctx.pictures.get('memmap') ?? memmapPictures(ctx.state, ctx.columns - 2).get('memmap')
- return grid === undefined || ctx.kit.Raster === undefined ? text(ctx, `the map needs a terminal that draws pictures: ${entries} entries in ${spaces} namespaces`, { dimColor: true }) : ctx.kit.Raster(grid.toRaster('memmap'))
+ const words = `the map needs a terminal that draws pictures: ${entries} entries in ${spaces} namespaces`
+
+ return art(ctx, grid, 'memmap', words) ?? text(ctx, words, { dimColor: true })
}
/** The memory map section: the picture, what its places mean (said plainly), the namespace colours and what the last search lit. */
diff --git a/plugins/ruflo-console/hooks/views/menu.ts b/plugins/ruflo-console/hooks/views/menu.ts
index b8c43e9fe9..f6284a347c 100644
--- a/plugins/ruflo-console/hooks/views/menu.ts
+++ b/plugins/ruflo-console/hooks/views/menu.ts
@@ -6,7 +6,7 @@ import type { RenderElement } from 'claude-code'
import { ACCENT, badgesOf, chip, LOUD, MUTED, PALETTE } from '../menu-style'
import { VIEWS, type ViewId } from '../state'
import { barParts } from './bar'
-import { button, clip, col, isBbs, isOrbital, picture, row, text, THEME, type Ctx } from './common'
+import { art, button, clip, col, isBbs, isOrbital, row, text, THEME, type Ctx } from './common'
import { missionStrip } from './mission-control'
type Item = { label: string; go: string }
@@ -164,9 +164,8 @@ export function menuView(ctx: Ctx): RenderElement {
// the frame loop and costs one element). A surface that cannot draw pictures gets the still strip.
if (bbs) {
rows.push(
- ctx.pictures.has('palette') && ctx.kit.Raster !== undefined
- ? picture(ctx, 'palette', '')
- : ctx.kit.Box({ flexDirection: 'row', key: 'menu-palette', children: PALETTE.map((color, i) => ctx.kit.Box({ key: `menu-palette-${i}`, children: [ctx.kit.Text({ color, children: 'β–€'.repeat(Math.max(1, Math.floor((ctx.columns - 2) / PALETTE.length))) })] })) }),
+ art(ctx, ctx.pictures.get('palette'), 'palette', 'the accent palette') ??
+ ctx.kit.Box({ flexDirection: 'row', key: 'menu-palette', children: PALETTE.map((color, i) => ctx.kit.Box({ key: `menu-palette-${i}`, children: [ctx.kit.Text({ color, children: 'β–€'.repeat(Math.max(1, Math.floor((ctx.columns - 2) / PALETTE.length))) })] })) }),
)
}
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index bfea2c6b99..bc42ba209b 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -21,7 +21,7 @@ import { isBooting, isCompactPane, NAV_STYLES, VIEWS, type ViewId } from '../sta
import { agentView } from './agent'
import { automateResult, automateView } from './automate'
import { claimsView } from './claims'
-import { ago, button, clip, col, confirmRow, isBbs, isOrbital, row, setLook, text, THEME, type Ctx } from './common'
+import { ago, art as drawArt, button, clip, col, confirmRow, isBbs, isOrbital, row, setLook, text, THEME, type Ctx } from './common'
import { costView } from './cost'
import { evolveResult, evolveView } from './evolve'
import { catalogView } from './plugin-catalog'
@@ -297,10 +297,12 @@ function wildcat(ctx: Ctx): { strip: RenderElement[]; art: RenderElement[] } {
],
}),
],
- art: art !== undefined && ctx.kit.Raster !== undefined ? [ctx.kit.Raster(art.toRaster('title'))] : [],
+ art: listOf(drawArt(ctx, art, 'title', `ruflo console: ${ctx.state.view}`)),
}
}
+const listOf = <T>(item: T | null): T[] => (item === null ? [] : [item])
+
/** The views whose lab result block can be drawn alone (so finding it costs one block, not a second page). */
const RESULT_OF: Partial<Record<ViewId, (ctx: Ctx) => RenderElement[]>> = {
overview: optimizerResult,
@@ -327,9 +329,9 @@ export function paneView(base: Ctx): RenderElement {
if (isBooting(ctx.state, ctx.nowMs)) {
const boot = ctx.pictures.get('boot')
- return boot !== undefined && ctx.kit.Raster !== undefined
- ? col(ctx, [ctx.kit.Raster(boot.toRaster('boot'))], 'boot')
- : col(ctx, [text(ctx, 'RUFLO AGENT SWARM CONSOLE Β· loading…', { bold: true, color: THEME.head })], 'boot')
+ const intro = drawArt(ctx, boot, 'boot', 'RUFLO AGENT SWARM CONSOLE Β· loading…')
+
+ return col(ctx, [intro ?? text(ctx, 'RUFLO AGENT SWARM CONSOLE Β· loading…', { bold: true, color: THEME.head })], 'boot')
}
// A section of a page is a bordered card (views/card.ts): the body is drawn narrower by the border and padding, through a kit that groups its rows.
const cardsOn = hasCards(base.columns, isCompactPane(base.state))
@@ -374,12 +376,14 @@ export function paneView(base: Ctx): RenderElement {
const hasInlineConfirm = attention.keys.get(body)?.has('confirm') === true
const header = ctx.pictures.get('header')
const isCompact = isCompactPane(ctx.state)
+ // A surface that draws no Raster (the desktop draws the same picture as an Svg) gets the Orbital banner's words where the picture is not drawn.
const fallbackBrand = isOrbital() && ctx.kit.Raster === undefined ? [text(ctx, 'RUFLO / AGENT SWARM CONSOLE', { bold: true, color: THEME.head, wrap: 'truncate-end' })] : []
// The logo banner leads the main menu in every layout, compact too (the other pages lead with their own title art there).
- const title = (!isCompact || ctx.state.view === 'menu') && header !== undefined && ctx.kit.Raster !== undefined ? [ctx.kit.Raster(header.toRaster('header'))] : ctx.state.view === 'menu' ? fallbackBrand : []
+ const banner = (!isCompact || ctx.state.view === 'menu') && header !== undefined ? drawArt(ctx, header, 'header', 'RUFLO / AGENT SWARM CONSOLE') : null
+ const title = banner !== null ? [banner] : ctx.state.view === 'menu' ? fallbackBrand : []
const about = blurb(ctx)
- const orbitalArt = ctx.pictures.get('title')
- const bbs = isBbs() ? wildcat(ctx) : { strip: [], art: isOrbital() && orbitalArt !== undefined && ctx.kit.Raster !== undefined ? [ctx.kit.Raster(orbitalArt.toRaster('title'))] : ctx.state.view !== 'menu' ? fallbackBrand : [] }
+ const orbitalArt = isOrbital() ? drawArt(ctx, ctx.pictures.get('title'), 'title', `ruflo console: ${ctx.state.view}`) : null
+ const bbs = isBbs() ? wildcat(ctx) : { strip: [], art: orbitalArt !== null ? [orbitalArt] : ctx.state.view !== 'menu' ? fallbackBrand : [] }
// The status row (keys, sync, Palette, Actions) sits above the body, so a tall view cannot push it off the screen; only the main menu keeps it below its prompt, as a BBS does.
const isMenu = ctx.state.view === 'menu'
// The terminal's own Enter-again confirm stays under its field, where the field is.
diff --git a/plugins/ruflo-console/tests/behaviour.test.ts b/plugins/ruflo-console/tests/behaviour.test.ts
index f2fc0c67c7..e13cfac913 100644
--- a/plugins/ruflo-console/tests/behaviour.test.ts
+++ b/plugins/ruflo-console/tests/behaviour.test.ts
@@ -282,7 +282,9 @@ describe('behaviour', () => {
await band.unmount()
})
- test('on the desktop surface, which has no Raster, every picture becomes a text line and the tree is accepted', { options: { boot: false } }, async ($, on) => {
+ // The host completes the desktop's table with a Raster that draws an empty fragment, so "no Raster in the tree" held even while every
+ // picture vanished (#4111): the pictures must arrive as Svg.
+ test('on the desktop surface, which draws no Raster, every picture arrives as an Svg and the tree is accepted', { options: { boot: false } }, async ($, on) => {
worldOf(on, RUFLO_FILES)
mock.clock(on)
await $.session.start(SESSION)
@@ -295,6 +297,7 @@ describe('behaviour', () => {
expect(pane.surface).toBe('desktop')
expect(elementsOf(tree, 'Raster')).toHaveLength(0)
+ expect(elementsOf(tree, 'Svg').length).toBeGreaterThan(0)
await pane.unmount()
}
})
diff --git a/plugins/ruflo-console/tests/surface-pictures.test.ts b/plugins/ruflo-console/tests/surface-pictures.test.ts
new file mode 100644
index 0000000000..844b2d2767
--- /dev/null
+++ b/plugins/ruflo-console/tests/surface-pictures.test.ts
@@ -0,0 +1,150 @@
+/**
+ * The console's pictures on every surface it can be drawn on. The terminal draws a Raster; Claude Code Desktop draws the same cells as
+ * an Svg, because the host completes the desktop's table with a Raster that draws an empty fragment. Run with
+ * claude plugin test plugins/ruflo-console
+ */
+import { describe, expect, mock, test } from 'claude-code/testing'
+
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+import { BAND, command, elementsOf, keyOf, paneAt, PLUGIN, SESSION, textOf, worldOf } from './fixtures/world'
+
+/** The agent drill-down opens on an agent of the fixture project; a bare `agent` would open Swarm. */
+const AGENT = 'agent-1790903032181-97m25s'
+const VIEWS = [`agent ${AGENT}`, 'menu', 'missions', 'overview', 'swarm', 'hive', 'claims', 'workflows', 'federation', 'plugins', 'learning', 'metaharness', 'memory', 'cost', 'timeline', 'approvals', 'events', 'room', 'xruv', 'terminal', 'skills', 'secure', 'perf', 'automate', 'neural', 'vector', 'evolve', 'devtools', 'sandbox', 'market', 'adrs', 'whatsnew', 'themes', 'settings'] as const
+const SVG_SOURCE_MAX = 131_072
+
+type Props = { source?: string; alt?: string; width?: number }
+const propsOf = (element: unknown): Props => ((element as { props?: Props }).props ?? {}) as Props
+
+for (const look of ['bbs', 'plain', 'orbital'] as const) {
+ describe(`pictures on each surface (${look})`, () => {
+ test(`every view: the terminal gets Rasters and no Svg; the desktop gets one Svg per Raster, each within the host's limit, and no Raster`, { timeoutMs: 120_000, options: { boot: false, look } }, async ($, on) => {
+ worldOf(on, RUFLO_FILES)
+ mock.clock(on)
+ await $.session.start(SESSION)
+
+ let pictured = 0
+
+ for (const view of VIEWS) {
+ await $.command.run(command(view))
+ await $.command.run(command('status'))
+
+ const drawn: Record<'terminal' | 'desktop', unknown> = { terminal: null, desktop: null }
+
+ for (const surface of ['terminal', 'desktop'] as const) {
+ const pane = await $.ui.mount({ ...paneAt(110, 60, true, surface), plugin: PLUGIN })
+
+ expect(pane.surface).toBe(surface)
+ drawn[surface] = await pane.drawn()
+ await pane.unmount()
+ }
+
+ const rasters = elementsOf(drawn.terminal as never, 'Raster')
+ const svgs = elementsOf(drawn.desktop as never, 'Svg')
+
+ // The bbs and orbital looks give every page title art; the plain look draws pictures on some pages only.
+ if (look !== 'plain') expect(rasters.length, `${look} ${view}: the terminal draws its pictures`).toBeGreaterThan(0)
+ pictured += rasters.length
+ expect(elementsOf(drawn.terminal as never, 'Svg'), `${look} ${view}: no Svg on the terminal`).toHaveLength(0)
+ expect(elementsOf(drawn.desktop as never, 'Raster'), `${look} ${view}: no Raster on the desktop`).toHaveLength(0)
+ expect(svgs.length, `${look} ${view}: one Svg per picture`).toBe(rasters.length)
+ // Picture by picture, not just by count: each Svg sits in a Box keyed by its Raster's key.
+ const svgKeys = elementsOf(drawn.desktop as never, 'Box').map(keyOf).filter(key => key.startsWith('svg-')).map(key => key.slice(4))
+
+ expect(svgKeys.sort(), `${look} ${view}: the same pictures`).toEqual(rasters.map(keyOf).sort())
+
+ for (const svg of svgs) {
+ const { source = '', alt = '', width = 0 } = propsOf(svg)
+
+ expect(source.startsWith('<svg xmlns="http://www.w3.org/2000/svg"')).toBe(true)
+ expect(source.length).toBeLessThanOrEqual(SVG_SOURCE_MAX)
+ expect(alt.trim().length).toBeGreaterThan(0)
+ expect(alt, `${look} ${view}: a drawn picture does not say it needs a terminal`).not.toMatch(/needs? a terminal/)
+ expect(width).toBeGreaterThan(0)
+ }
+
+ // The words around the pictures are the same on both surfaces.
+ expect(textOf(drawn.desktop as never)).toBe(textOf(drawn.terminal as never))
+ if (view.startsWith('agent ')) expect(textOf(drawn.desktop as never), 'the agent drill-down is open').toContain(AGENT)
+ }
+
+ expect(pictured, `${look}: some page draws a picture`).toBeGreaterThan(0)
+ })
+ })
+}
+
+describe('pictures on each surface', () => {
+ test('the main menu leads with the banner: a Raster on the terminal, an Svg titled with the console name on the desktop', { options: { boot: false } }, async ($, on) => {
+ worldOf(on, RUFLO_FILES)
+ mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command('menu'))
+
+ const terminal = await $.ui.mount({ ...paneAt(110, 60, true, 'terminal'), plugin: PLUGIN })
+
+ expect(elementsOf(await terminal.drawn(), 'Raster').map(keyOf)).toContain('header')
+ await terminal.unmount()
+
+ const desktop = await $.ui.mount({ ...paneAt(110, 60, true, 'desktop'), plugin: PLUGIN })
+ const banner = elementsOf(await desktop.drawn(), 'Svg').map(propsOf)[0]
+
+ expect(banner?.alt).toBe('RUFLO / AGENT SWARM CONSOLE')
+ expect(banner?.source).toContain('<title>RUFLO / AGENT SWARM CONSOLE</title>')
+ await desktop.unmount()
+ })
+
+ test('the frame loop blits on the terminal and never on the desktop, where nothing is mounted to blit', { options: { boot: false } }, async ($, on) => {
+ const world = worldOf(on, RUFLO_FILES)
+ const clock = mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command('swarm'))
+ await $.command.run(command('status'))
+
+ const desktop = await $.ui.mount({ ...paneAt(110, 60, true, 'desktop'), plugin: PLUGIN })
+
+ for (let i = 0; i < 8; i++) await clock.advance(125)
+ expect(world.blits).toHaveLength(0)
+ await desktop.unmount()
+
+ const terminal = await $.ui.mount({ ...paneAt(110, 60, true, 'terminal'), plugin: PLUGIN })
+
+ for (let i = 0; i < 8; i++) await clock.advance(125)
+ expect(world.blits.filter(key => key === 'topology').length).toBeGreaterThan(2)
+ await terminal.unmount()
+ })
+
+ test('the boot intro is a Raster on the terminal and an Svg on the desktop, with nothing else under it', async ($, on) => {
+ worldOf(on, RUFLO_FILES)
+ mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command())
+
+ for (const surface of ['terminal', 'desktop'] as const) {
+ const pane = await $.ui.mount({ ...paneAt(110, 60, true, surface), plugin: PLUGIN })
+ const intro = await pane.drawn()
+
+ expect(elementsOf(intro, 'Raster').map(keyOf)).toEqual(surface === 'terminal' ? ['boot'] : [])
+ expect(elementsOf(intro, 'Svg').map(propsOf).map(props => props.alt)).toEqual(surface === 'terminal' ? [] : ['RUFLO AGENT SWARM CONSOLE Β· loading…'])
+ expect(textOf(intro)).not.toContain('MAIN MENU')
+ await pane.unmount()
+ }
+ })
+
+ test('the band animates its working mark on the terminal and sends nothing for it on the desktop', { options: { boot: false } }, async ($, on) => {
+ const world = worldOf(on, RUFLO_FILES)
+ const clock = mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command('status'))
+
+ for (const surface of ['desktop', 'terminal'] as const) {
+ world.blits.length = 0
+ const band = await $.ui.mount({ ...BAND, surface, props: { ...BAND.props, isWorking: true }, plugin: PLUGIN })
+ const tree = await band.drawn()
+
+ for (let i = 0; i < 8; i++) await clock.advance(125)
+ expect(world.blits.filter(key => key === 'mark').length > 0, `${surface}: mark blits`).toBe(surface === 'terminal')
+ expect(textOf(tree).length).toBeGreaterThan(0)
+ await band.unmount()
+ }
+ })
+})
diff --git a/plugins/ruflo-console/tests/svg-pictures.spec.ts b/plugins/ruflo-console/tests/svg-pictures.spec.ts
new file mode 100644
index 0000000000..95f2e44ad1
--- /dev/null
+++ b/plugins/ruflo-console/tests/svg-pictures.spec.ts
@@ -0,0 +1,411 @@
+/**
+ * Pictures on the surfaces that draw vectors: the grid-to-SVG writer (shapes, braille, text placement, escaping, the host's size limit)
+ * and the kit a surface really draws with. Run with
+ * npx vitest run plugins/ruflo-console/tests/svg-pictures.spec.ts
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+/** Counts how often the frame loop builds pictures, to show a surface that draws Svg builds none per frame. */
+const built = vi.hoisted(() => ({ count: 0 }))
+
+vi.mock('../hooks/views/frames', async importOriginal => {
+ const real = await importOriginal<typeof import('../hooks/views/frames')>()
+
+ return { ...real, picturesOf: (...args: Parameters<typeof real.picturesOf>) => ((built.count += 1), real.picturesOf(...args)) }
+})
+
+import { createController } from '../hooks/controller'
+import { DEFAULT, Grid } from '../hooks/gfx/raster'
+import type { Host } from '../hooks/host'
+import { newState, VIEWS } from '../hooks/state'
+import { picturesOf } from '../hooks/views/frames'
+import { CELL_H, CELL_W, escapeXml, gridToSvg, SVG_SOURCE_MAX } from '../hooks/gfx/svg'
+import { kitForSurface, type Kit } from '../hooks/views/common'
+
+/**
+ * A structural XML check for what gridToSvg writes (not a general XML parser, and not evidence beyond its own rules): one root element, every tag closed in order, close tags bare,
+ * attributes quoted and unique, no bare `&` or character XML 1.0 cannot hold in text or in a value, and no `]]>` in text.
+ */
+const BAD_CHAR = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/
+const BAD_REF = /&(?!(amp|lt|gt|quot|apos|#[0-9]+|#x[0-9a-fA-F]+);)/
+const BAD_TEXT = (text: string): boolean => BAD_REF.test(text) || text.includes(']]>') || BAD_CHAR.test(text)
+const BAD_VALUE = (value: string): boolean => BAD_REF.test(value) || BAD_CHAR.test(value)
+
+function isWellFormed(xml: string): boolean {
+ const stack: string[] = []
+ const token = /<\/([A-Za-z][\w:-]*)>|<([A-Za-z][\w:-]*)((?:[ \t\r\n]+[A-Za-z_:][\w:.-]*="[^"<]*")*)[ \t\r\n]*(\/?)>|([^<]+)/gy
+ let seenRoot = false
+ let at = 0
+
+ while (at < xml.length) {
+ token.lastIndex = at
+ const m = token.exec(xml)
+
+ if (m === null) return false
+ at = token.lastIndex
+ if (m[5] !== undefined) {
+ if (stack.length === 0 || BAD_TEXT(m[5])) return false
+ } else if (m[1] !== undefined) {
+ if (stack.pop() !== m[1]) return false
+ } else {
+ const values = [...(m[3] ?? '').matchAll(/([A-Za-z_:][\w:.-]*)="([^"]*)"/g)]
+
+ if (new Set(values.map(v => v[1])).size !== values.length || values.some(v => BAD_VALUE(v[2] ?? ''))) return false
+ // One root element: nothing opens once it has closed.
+ if (stack.length === 0 && seenRoot) return false
+ seenRoot = true
+ if (m[4] !== '/') stack.push(m[2] as string)
+ }
+ }
+
+ return seenRoot && stack.length === 0
+}
+
+const svgOf = (grid: Grid, alt = 'picture'): string => {
+ const svg = gridToSvg(grid, alt)
+
+ expect(svg).not.toBeNull()
+
+ return svg as string
+}
+
+describe('gridToSvg', () => {
+ it('draws block glyphs as rectangles and merges a run of one shape and colour into one', () => {
+ const grid = new Grid(6, 1)
+
+ grid.text(0, 0, 'β–€β–€β–€', 0xff0000)
+ grid.set(3, 0, 'β–ˆ', 0x00ff00)
+ grid.set(4, 0, 'β–„', 0x0000ff)
+ const svg = svgOf(grid)
+
+ expect(svg).toContain(`<path fill="#ff0000" d="M0 0h${3 * CELL_W}v${CELL_H / 2}h${-3 * CELL_W}z"/>`)
+ expect(svg).toContain(`fill="#00ff00" d="M${3 * CELL_W} 0h${CELL_W}v${CELL_H}`)
+ expect(svg).toContain(`fill="#0000ff" d="M${4 * CELL_W} ${CELL_H / 2}h${CELL_W}v${CELL_H / 2}`)
+ expect(svg).not.toContain('<text')
+ expect(isWellFormed(svg)).toBe(true)
+ })
+
+ it('keeps half-width shapes apart and draws shades as a translucent fill', () => {
+ const grid = new Grid(5, 1)
+
+ grid.text(0, 0, 'β–Œβ–Œ', 0x111111)
+ grid.text(2, 0, 'β–‘β–’β–“', 0x222222)
+ const svg = svgOf(grid)
+
+ expect(svg.match(/M\d+ 0h4v16h-4z/g)).toHaveLength(2)
+ expect(svg).toContain('fill="#222222" fill-opacity="0.25"')
+ expect(svg).toContain('fill="#222222" fill-opacity="0.5"')
+ expect(svg).toContain('fill="#222222" fill-opacity="0.75"')
+ })
+
+ it('draws braille as dots on a 2x4 grid, one per set bit', () => {
+ const grid = new Grid(2, 1)
+
+ grid.set(0, 0, 0x28ff, 0xabcdef)
+ grid.set(1, 0, 0x2801, 0xabcdef)
+ const d = /fill="#abcdef" d="([^"]+)"/.exec(svgOf(grid))?.[1] ?? ''
+
+ expect(d.match(/M/g)).toHaveLength(9)
+ expect(d.startsWith('M1 1h2v2h-2z')).toBe(true)
+ expect(d).toContain(`M${CELL_W + 1} 1h2v2h-2z`)
+ })
+
+ it('places every text glyph on its own cell, so a proportional font cannot drift the columns', () => {
+ const grid = new Grid(10, 2)
+
+ grid.text(2, 1, 'Hi!', 0x00aa00)
+ const svg = svgOf(grid)
+
+ expect(svg).toContain(`fill="#00aa00" x="${2 * CELL_W} ${3 * CELL_W} ${4 * CELL_W}" y="${CELL_H + 12}" xml:space="preserve">Hi!</text>`)
+ })
+
+ it('keeps every glyph on its own column when a character XML cannot hold is dropped before it', () => {
+ const grid = new Grid(5, 1)
+
+ grid.text(0, 0, 'A\u0001B', 0xffffff)
+ grid.set(3, 0, 0xfffe, 0xffffff)
+ grid.set(4, 0, 'C', 0xffffff)
+ const svg = svgOf(grid)
+
+ expect(svg).toContain(`x="0" y="12" xml:space="preserve">A</text>`)
+ expect(svg).toContain(`x="${2 * CELL_W}" y="12" xml:space="preserve">B</text>`)
+ expect(svg).toContain(`x="${4 * CELL_W}" y="12" xml:space="preserve">C</text>`)
+ })
+
+ it('turns every control character into a blank cell, so a CR, LF or TAB cannot move the glyphs after it', () => {
+ const grid = new Grid(8, 1)
+
+ grid.text(0, 0, 'A\r\nB\tC\u0085D', 0xffffff)
+ const svg = svgOf(grid)
+
+ expect(svg).toContain(`x="0" y="12" xml:space="preserve">A</text>`)
+ expect(svg).toContain(`x="${3 * CELL_W}" y="12" xml:space="preserve">B</text>`)
+ expect(svg).toContain(`x="${5 * CELL_W}" y="12" xml:space="preserve">C</text>`)
+ expect(svg).toContain(`x="${7 * CELL_W}" y="12" xml:space="preserve">D</text>`)
+ expect(svg).not.toMatch(/[\r\n\t\u0085]/)
+ })
+
+ it('draws every Block Elements glyph (U+2580 to U+259F) as rectangles, never as text', () => {
+ for (let cp = 0x2580; cp <= 0x259f; cp++) {
+ const grid = new Grid(1, 1)
+
+ grid.set(0, 0, cp, 0x445566)
+ const svg = svgOf(grid)
+
+ expect(svg, cp.toString(16)).not.toContain('<text')
+ expect(svg, cp.toString(16)).toContain('fill="#445566"')
+ }
+ })
+
+ it('places the eighths, the upper and right bars and the quadrants where they belong', () => {
+ const at = (cp: number): string => {
+ const grid = new Grid(1, 1)
+
+ grid.set(0, 0, cp, 0x000001)
+
+ return /d="([^"]+)"/.exec(svgOf(grid))?.[1] ?? ''
+ }
+
+ expect(at(0x2594)).toBe(`M0 0h${CELL_W}v2h-${CELL_W}z`) // β–” upper eighth
+ expect(at(0x2595)).toBe(`M7 0h1v${CELL_H}h-1z`) // β–• right eighth
+ expect(at(0x2589)).toBe(`M0 0h7v${CELL_H}h-7z`) // β–‰ seven eighths from the left
+ expect(at(0x2596)).toBe(`M0 8h4v8h-4z`) // β–– lower left
+ expect(at(0x259a)).toBe(`M0 0h4v8h-4zM4 8h4v8h-4z`) // β–š upper left and lower right
+ })
+
+ it('the well-formedness check itself rejects what it must', () => {
+ expect(isWellFormed('<svg><title>a</title></svg>')).toBe(true)
+ expect(isWellFormed('<svg></svg><svg></svg>')).toBe(false)
+ expect(isWellFormed('<svg>a]]>b</svg>')).toBe(false)
+ expect(isWellFormed('<svg>a\u0001b</svg>')).toBe(false)
+ expect(isWellFormed('<svg><g a="1" a="2"/></svg>')).toBe(false)
+ expect(isWellFormed('<svg>&bad</svg>')).toBe(false)
+ expect(isWellFormed('<svg><g></svg>')).toBe(false)
+ expect(isWellFormed('')).toBe(false)
+ expect(isWellFormed('<svg></svg a="1">')).toBe(false)
+ expect(isWellFormed('<svg></svg/>')).toBe(false)
+ expect(isWellFormed('<svg a="x\u0001"></svg>')).toBe(false)
+ expect(isWellFormed('<svg 1a="x"/>')).toBe(false)
+ expect(isWellFormed('<svg\u000ba="x"/>')).toBe(false)
+ expect(isWellFormed('<svg a="]]>">&#65;&#x41;</svg>')).toBe(true)
+ })
+
+ it('leaves the terminal default background transparent and fills a coloured one, and gives the default foreground a real colour', () => {
+ const grid = new Grid(4, 1)
+
+ grid.set(0, 0, 'a')
+ grid.set(1, 0, ' ', DEFAULT, 0x123456)
+ grid.set(2, 0, ' ', DEFAULT, 0x123456)
+ const svg = svgOf(grid)
+
+ expect(svg).toContain(`<path fill="#123456" d="M${CELL_W} 0h${2 * CELL_W}v${CELL_H}h${-2 * CELL_W}z"/>`)
+ expect(svg).toContain('fill="#8b949e"')
+ expect(svg).not.toContain('16777216')
+ })
+
+ it('escapes hostile text and the title, and drops what XML cannot hold', () => {
+ const grid = new Grid(40, 1)
+
+ grid.text(0, 0, '<script>&"\'</script>\u0001\u001b', 0xffffff)
+ grid.set(30, 0, 0xd800, 0xffffff)
+ grid.set(31, 0, 0xfffe, 0xffffff)
+ // A Grid holds any u32; one past Unicode must not throw inside a render hook.
+ grid.set(32, 0, 0x110000, 0xffffff)
+ grid.set(33, 0, 0xffffffff, 0xffffff)
+ const svg = svgOf(grid, 'a <b> & "c"')
+
+ expect(svg).not.toMatch(/<script/i)
+ expect(svg).toContain('&lt;script&gt;&amp;&quot;&apos;&lt;/script&gt;')
+ expect(svg).toContain('<title>a &lt;b&gt; &amp; &quot;c&quot;</title>')
+ expect(svg).not.toMatch(/[\u0001\u001bοΏΎ]/)
+ expect(isWellFormed(svg)).toBe(true)
+ expect(escapeXml('ok\u0000\ud800x')).toBe('okx')
+ })
+
+ it('sizes the document to the grid: columns by rows of cells', () => {
+ const svg = svgOf(new Grid(12, 3))
+
+ expect(svg.startsWith(`<svg xmlns="http://www.w3.org/2000/svg" width="${12 * CELL_W}" height="${3 * CELL_H}" viewBox="0 0 ${12 * CELL_W} ${3 * CELL_H}" role="img">`)).toBe(true)
+ })
+
+ it('returns null rather than a document past the limit, and never passes the host limit', () => {
+ const grid = new Grid(200, 80)
+
+ for (let y = 0; y < 80; y++) for (let x = 0; x < 200; x++) grid.set(x, y, x % 2 === 0 ? 'x' : 0x28ff, (x * 7919 + y * 104729) & 0xffffff, (x * 31 + y) & 0xffffff)
+
+ expect(gridToSvg(grid, 'busy')).toBeNull()
+ expect(gridToSvg(new Grid(4, 1), 'tiny', 50)).toBeNull()
+
+ const small = new Grid(60, 20)
+
+ small.text(0, 0, 'header', 0xffffff)
+ expect((gridToSvg(small, 'ok') as string).length).toBeLessThanOrEqual(SVG_SOURCE_MAX)
+ })
+})
+
+describe('kitForSurface', () => {
+ const element = (type: string) => (() => ({ type })) as never
+ const table = { Box: element('Box'), Text: element('Text'), Button: element('Button'), Raster: element('Raster'), Svg: element('Svg'), Input: element('Input') } as Kit
+
+ it('gives the terminal its Raster and no Svg', () => {
+ const kit = kitForSurface(table, 'terminal')
+
+ expect(kit.Raster).toBeDefined()
+ expect(kit.Svg).toBeUndefined()
+ expect(kit.Input).toBeDefined()
+ })
+
+ it.each(['desktop', 'vscode', 'mobile'])('gives %s an Svg and no Raster (its Raster draws a fragment)', surface => {
+ const kit = kitForSurface(table, surface)
+
+ expect(kit.Raster).toBeUndefined()
+ expect(kit.Svg).toBeDefined()
+ expect(kit.Box).toBe(table.Box)
+ })
+
+ it('adds nothing a table lacks', () => {
+ const { Svg: _svg, ...noSvg } = table
+
+ expect(kitForSurface(noSvg as Kit, 'desktop').Svg).toBeUndefined()
+ expect('Svg' in kitForSurface(noSvg as Kit, 'desktop')).toBe(false)
+ })
+})
+
+/** A host that records blits, redraws and the frame timer, and answers everything else with nothing. */
+function frameHost() {
+ const calls = { blits: [] as string[], invalidates: 0, timers: [] as (() => void)[] }
+ const host = new Proxy({}, {
+ get: (_target, key) => {
+ if (key === 'blit') return (args: { key: string }) => void calls.blits.push(args.key)
+ if (key === 'invalidate') return () => void (calls.invalidates += 1)
+ if (key === 'every') return (_ms: number, fn: () => void) => (calls.timers.push(fn), { cancel: () => undefined })
+ if (key === 'after') return () => ({ cancel: () => undefined })
+ if (key === 'pluginRoot') return '/plugin'
+ if (key === 'fs') return { read: async () => Promise.reject(new Error('ENOENT')), stat: async () => Promise.reject(new Error('ENOENT')), list: async () => Promise.reject(new Error('ENOENT')) }
+
+ return () => Promise.resolve(undefined)
+ },
+ }) as unknown as Host
+
+ return { host, calls }
+}
+
+/** The timers `act` registered: animate() adds the frame loop's, and creating the controller adds others before it. */
+function framesOf(calls: { timers: (() => void)[] }, act: () => void): (() => void)[] {
+ const before = calls.timers.length
+
+ act()
+
+ return calls.timers.slice(before)
+}
+
+function shownState(view: 'swarm' | 'menu') {
+ const state = newState({ boot: false })
+
+ state.view = view
+ Object.assign(state.pane, { isOpen: true, isShown: true, isFocused: true, columns: 110, rows: 60 })
+
+ return state
+}
+
+describe('still pictures for a surface that draws Svg', () => {
+ it.each(['bbs', 'orbital'] as const)('are the frames fps 0 draws, not a header caught mid strike-in (%s)', look => {
+ const state = newState({ boot: false, look })
+ const now = Date.now()
+
+ state.view = 'menu'
+ Object.assign(state.pane, { isOpen: true, isShown: true, isFocused: true, columns: 110, rows: 60, viewAtMs: now })
+ const still = picturesOf(state, 110, now, now, true)
+ const moving = picturesOf(state, 110, now, now)
+
+ expect(still.get('header')?.encode()).toBeDefined()
+ expect(moving.get('header')?.encode()).not.toBe(still.get('header')?.encode())
+ })
+
+ it.each(['bbs', 'plain', 'orbital'] as const)('on every page the light is off and the motion stopped: header, title and palette are the same at any moment, and the rest is what fps 0 draws (%s)', look => {
+ const state = newState({ boot: false, look })
+ const now = Date.now()
+
+ Object.assign(state.pane, { isOpen: true, isShown: true, isFocused: true, columns: 110, rows: 60, viewAtMs: now - 50 })
+
+ for (const view of VIEWS.map(entry => entry.id)) {
+ state.view = view
+ const still = picturesOf(state, 110, now, now, true)
+ const later = picturesOf(state, 110, now, now + 7_777, true)
+ const fps0 = picturesOf({ ...state, options: { ...state.options, fps: 0 } }, 110, now, now)
+
+ expect([...still.keys()], `${look} ${view}`).toEqual([...fps0.keys()])
+ for (const [key, grid] of still) {
+ // The decorative pictures do not depend on the moment; with fps 0 their light still moves with t, so only the rest equals fps 0's.
+ if (key === 'header' || key === 'title' || key === 'palette') expect(grid.encode(), `${look} ${view} ${key} at two moments`).toBe(later.get(key)?.encode())
+ else expect(grid.encode(), `${look} ${view} ${key}`).toBe(fps0.get(key)?.encode())
+ }
+ }
+ })
+
+ it('leaves the terminal its moving light, with fps 0 too: still=false keeps t', () => {
+ const state = newState({ boot: false, look: 'bbs', fps: 0 })
+ const now = Date.now()
+
+ state.view = 'menu'
+ Object.assign(state.pane, { isOpen: true, isShown: true, isFocused: true, columns: 110, rows: 60 })
+ expect(picturesOf(state, 110, now, 300).get('header')?.encode()).not.toBe(picturesOf(state, 110, now, 900).get('header')?.encode())
+ })
+})
+
+describe('the frame loop by surface', () => {
+ it('on a surface that draws Svg the loop still runs for the pictures, but blits nothing and rebuilds nothing', () => {
+ const state = shownState('swarm')
+ const { host, calls } = frameHost()
+ const control = createController(state, host)
+
+ state.pictured = 3
+ state.mounted = new Map()
+ const frames = framesOf(calls, () => control.animate())
+
+ expect(frames).toHaveLength(1)
+ built.count = 0
+ frames[0]?.()
+ expect(calls.blits).toHaveLength(0)
+ expect(built.count).toBe(0)
+ })
+
+ it('on the terminal it blits every mounted Raster at its mounted size', () => {
+ const state = shownState('swarm')
+ const { host, calls } = frameHost()
+ const control = createController(state, host)
+ const pictures = picturesOf(state, state.pane.columns, Date.now(), Date.now())
+
+ state.pictured = pictures.size
+ state.mounted = new Map([...pictures].map(([key, grid]) => [key, { columns: grid.columns, rows: grid.rows }]))
+ framesOf(calls, () => control.animate())[0]?.()
+ expect(pictures.size).toBeGreaterThan(0)
+ expect(new Set(calls.blits)).toEqual(new Set(pictures.keys()))
+ })
+
+ it('with no picture and nothing moving the loop does not run', () => {
+ const state = shownState('swarm')
+ const { host, calls } = frameHost()
+
+ state.pictured = 0
+ const control = createController(state, host)
+
+ expect(framesOf(calls, () => control.animate())).toHaveLength(0)
+ })
+
+ it("the menu's entry still redraws frame by frame on a surface that draws Svg", () => {
+ const state = newState({ boot: true, look: 'bbs' })
+ const { host, calls } = frameHost()
+ const control = createController(state, host)
+
+ state.view = 'menu'
+ Object.assign(state.pane, { isOpen: true, isShown: true, isFocused: true, columns: 110, rows: 60, bootAtMs: Date.now() - 60_000, menuAtMs: Date.now() })
+ state.pictured = 2
+ const frames = framesOf(calls, () => control.animate())
+
+ expect(frames).toHaveLength(1)
+ frames[0]?.()
+ expect(calls.invalidates).toBeGreaterThan(0)
+ expect(calls.blits).toHaveLength(0)
+ })
+})
diff --git a/scripts/ci-test-excluded.txt b/scripts/ci-test-excluded.txt
index c7fd86d084..f7fa8e4d27 100644
--- a/scripts/ci-test-excluded.txt
+++ b/scripts/ci-test-excluded.txt
@@ -87,6 +87,7 @@ plugins/ruflo-console/tests/toasts.test.ts
plugins/ruflo-console/tests/full-text.test.ts
plugins/ruflo-console/tests/whatsnew.test.ts
plugins/ruflo-console/tests/adrs.test.ts
+plugins/ruflo-console/tests/surface-pictures.test.ts
plugins/ruflo-protector/tests/corpus.test.ts
plugins/ruflo-protector/tests/mod.test.ts
plugins/ruflo-protector/tests/rules.test.ts