@bakers-build/addon-bakers-ui 0.0.0-stage → 0.1.0-next.38

package/dist/src/Component/list-chrome/index.js

@@ -0,0 +1,69 @@
+// BB-375 — shared full-screen body helpers: optional filter badges.
+// Body frame lives on region-body ScrollBox (Kernel/regions.ts).
+import { BoxRenderable, h } from '@opentui/core';
+import { BACKGROUND_ACTIVE, BORDER, DEFAULT_BACKGROUND, FOREGROUND, FOREGROUND_ACTIVE, textNode, } from '../../lib/vnode.js';
+/**
+ * Rounded filter chips in a row (idle outline + active FOREGROUND_ACTIVE fg).
+ * Each badge is its own `borderStyle: 'rounded'` box — the panel border language.
+ * Horizontal inset matches the body ScrollBox frame padding (BB-375).
+ */
+export const filterBadgeStrip = (id, badges) => {
+    const nodes = [];
+    for (const [index, badge] of badges.entries()) {
+        if (index > 0) {
+            nodes.push(textNode({
+                id: `${id}-gap-${index}`,
+                content: '  ',
+                bg: DEFAULT_BACKGROUND,
+                fg: BORDER,
+            }));
+        }
+        const value = badge.value;
+        const active = value !== undefined && value !== '';
+        const label = active ? value : badge.label;
+        nodes.push(h(BoxRenderable, {
+            id: `${id}-${badge.id}-chip`,
+            border: true,
+            borderStyle: 'rounded',
+            borderColor: BORDER,
+            backgroundColor: DEFAULT_BACKGROUND,
+            flexShrink: 0,
+            // One extra column of air inside the pill (rounder optical mass).
+            paddingLeft: 2,
+            paddingRight: 2,
+            flexDirection: 'row',
+        }, ...(active
+            ? [
+                textNode({
+                    id: `${id}-${badge.id}-key`,
+                    content: `${badge.label.split(' ', 1)[0]} `,
+                    bg: DEFAULT_BACKGROUND,
+                    fg: FOREGROUND,
+                }),
+            ]
+            : []), textNode({
+            id: `${id}-${badge.id}`,
+            content: label,
+            bg: active ? BACKGROUND_ACTIVE : DEFAULT_BACKGROUND,
+            fg: active ? FOREGROUND_ACTIVE : FOREGROUND,
+        })));
+    }
+    return h(BoxRenderable, {
+        id,
+        backgroundColor: DEFAULT_BACKGROUND,
+        flexDirection: 'column',
+        flexShrink: 0,
+        // Match body ScrollBox horizontal inset (BB-375).
+        paddingLeft: 1,
+        paddingRight: 1,
+        paddingTop: 0,
+        paddingBottom: 0,
+    }, h(BoxRenderable, {
+        id: `${id}-row`,
+        flexDirection: 'row',
+        flexWrap: 'wrap',
+        flexShrink: 0,
+        backgroundColor: DEFAULT_BACKGROUND,
+        gap: 0,
+    }, ...nodes));
+};

package/dist/src/Component/markdown/index.d.ts

@@ -0,0 +1,103 @@
+import { type VNode } from '@opentui/core';
+import type { MarkdownLine, MarkdownSpan } from '../../lib/markdown.js';
+import { type StyledLine, type StyledRun } from '../../lib/vnode.js';
+/**
+ * ONE SPAN AS THE RUN A RENDERER CAN PAINT — D7/D11, and the mapping this
+ * component owns.
+ *
+ * `bold`, `italic` and `dim` are ATTRIBUTES and OR together into one bitmask;
+ * `code` is a COLOUR and not an attribute at all, which is why a code span that
+ * is also emphasised carries both. The colour is {@link BORDER} (indexed, same
+ * slot as ordinary foreground after BB-375 dropped cyan) — never a truecolor
+ * triplet.
+ *
+ * `strikethrough` and `underline` are deliberately absent: underline is what a
+ * terminal hyperlink looks like and would collide with D6's `text (url)`, and
+ * `~~struck~~` is mapped onto `dim` rather than widening the wire vocabulary a
+ * second time for a construct bakers.build bodies barely use.
+ */
+export declare const styledRunOf: (span: MarkdownSpan) => StyledRun;
+/**
+ * ONE PARSED LINE AS A NEUTRAL STYLED LINE.
+ *
+ * `text` is carried through UNTOUCHED — that is the pipe constraint in one line
+ * of code. The styling step may not change a glyph, and it cannot: it only ever
+ * reads a span's flags.
+ */
+export declare const styledLineOf: (line: MarkdownLine) => StyledLine;
+/** A `bb_rich` body as the physical rows a surface draws or prints — D1. */
+export declare function markdownLines(body: string): StyledLine[];
+/** A line NOTHING parses — one unstyled run (D3's plain path, as a value). */
+export declare function plainLine(text: string): StyledLine;
+/**
+ * The same line held `columns` in from the left — D5.
+ *
+ * The indent is an unstyled run PREPENDED TO A RENDERED LINE, never four spaces
+ * prepended to the source — see this file's header for why that ordering is
+ * load-bearing rather than tidy.
+ */
+export declare function indentLine(source: StyledLine, columns: number): StyledLine;
+/**
+ * THE RUN LOG'S OWN MINIMAL RULE — BB-372 D9, and it has exactly ONE caller:
+ * `Entity/run/Component/run-detail`.
+ *
+ * An ATX heading (`#`…`######`) renders as bold with the markers stripped;
+ * everything else is returned unchanged. Bullets, emphasis and code fences stay
+ * raw.
+ *
+ * ITS DOC COMMENT ONCE CLAIMED THE OPPOSITE OF WHAT IS NOW TRUE — that it is "ONE
+ * function, because every renderer of a body line goes through it". Since
+ * BB-372 no body line goes through it at all: a `bb_rich` body is rendered by
+ * {@link markdownLines} and reaches a row as a `StyledLine` (D3), and
+ * `Component/section-list`'s `sectionRows`/`expandableRows` do not parse a plain
+ * string.
+ *
+ * IT LIVED IN `Component/section-list` UNTIL D11 MOVED IT HERE. That was where it
+ * sat while it really was the rule for EVERY body row; once it was not, all it left
+ * behind was a Markdown rule inside a generic list primitive. The rule is unchanged,
+ * character for character; only its address is.
+ *
+ * The run log keeps the narrow rule DELIBERATELY, not by omission. A log entry is
+ * MACHINE OUTPUT, not authored Markdown: an agent line full of `*`, `_` and
+ * backticks would be re-styled and have characters deleted by a renderer meant
+ * for prose. Routing the log through the full subset is a separate ticket, not a
+ * silent side effect of this one.
+ */
+export declare function markdownRow(line: string): {
+    text: string;
+    bold: boolean;
+};
+export interface MarkdownProps {
+    id: string;
+    /** Markdown source, parsed with the production line/span parser. */
+    source: string;
+    width?: number;
+}
+export interface MarkdownLinesProps {
+    id: string;
+    /** Rows as {@link markdownLines} renders them. */
+    lines: readonly StyledLine[];
+    width?: number;
+    /** Brighter body copy — terminal cells have no font size. */
+    emphasis?: boolean;
+}
+/** Styled rows as one column of wrapped paragraphs, blank rows kept one high. */
+export declare const MarkdownLines: ({ id, lines, width, emphasis, }: MarkdownLinesProps) => VNode;
+/** A Markdown source, parsed and painted. */
+export declare const Markdown: ({ id, source, width }: MarkdownProps) => VNode;
+export interface HeadlineMarkdownProps {
+    id: string;
+    headline: string;
+    children: readonly VNode[];
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /**
+     * The id the HEADLINE row carries — a selectable entry's row id, which the
+     * kernel scrolls to and binds clicks on. The headline text inside it owns
+     * {@link onMouseDown} and consumes the press.
+     */
+    headlineId?: string;
+    onMouseDown?: () => void;
+}
+/** A `* headline` row above an indented body. */
+export declare const HeadlineMarkdown: ({ id, headline, children, paddingBottom, paddingLeft, headlineId, onMouseDown, }: HeadlineMarkdownProps) => VNode;

package/dist/src/Component/markdown/index.js

@@ -0,0 +1,204 @@
+// THE MARKDOWN COMPONENT — BB-372 D11, and the one place the cockpit knows
+// what Markdown is.
+//
+// WHY IT EXISTS. Markdown arrived in this package as two halves that landed in
+// two wrong places. `lib/markdown.ts` is a pure parser and belongs where it is,
+// but the STYLING half — which span kind means which terminal attribute and which
+// palette colour — ended up inside `lib/vnode.ts`, the package's most-shared
+// render primitive, the one twelve screens draw through. `Component/section-list`
+// then named `MarkdownLine`/`MarkdownSpan` throughout its own contract. So a
+// generic node vocabulary and a generic list primitive both carried Markdown
+// domain knowledge, and no gate caught it: `scripts/assert-acyclic.mjs` enforces
+// PACKAGE layering, and both files live in `lib/`.
+//
+// THE SHAPE. This directory owns all of it, and the import direction inverts:
+//
+//   Component/markdown  →  lib/vnode   (attributes, palette, the neutral run)
+//   Component/markdown  →  lib/markdown (the pure parser, no @opentui/core)
+//   lib/vnode           →  nothing about Markdown
+//   Component/section-list → lib/vnode  (StyledLine, never MarkdownLine)
+//
+// THE HARD CONSTRAINT, and the reason this is not a paint-only component: the
+// non-interactive pipe prints `row.text` and NOTHING ELSE. AC-3's parity is
+// structural precisely because a rendered row carries its rendered TEXT, so
+// `bakers ui <id> | cat` and the interactive tree are the same rendering by
+// construction rather than by agreement (D4). A component that emitted only
+// VNodes would cut the pipe off that rendering and restore the
+// two-renderers-disagree defect this ticket exists to remove. So the output here
+// is DATA — a {@link StyledLine}: rendered text, resolved runs, and the row's own
+// weight — and `Component/section-list`'s `lineText` keeps working unchanged.
+//
+// THE PAINTER sits here too (`Markdown`, `MarkdownLines`, `HeadlineMarkdown`):
+// it turns those same styled rows into renderables, so there is one style rule
+// for a body whether it is piped or drawn, and no second mapping of span kinds
+// to colours anywhere else.
+//
+// WHY `plainLine` AND `indentLine` LIVE HERE rather than in the parser: neither
+// parses. `plainLine` is D3's plain path expressed as a value, and `indentLine`
+// prepends blanks to an ALREADY RENDERED line — which is the whole point of it
+// (four leading spaces prepended to SOURCE would be an indented code block in
+// CommonMark, so applying the indent after rendering is what makes that
+// impossible rather than merely unlikely, Fact 9). Both are shell work on a
+// rendered line, so they sit with the shell.
+import { BoxRenderable, h } from '@opentui/core';
+import { markdownLines as parseMarkdown } from '../../lib/markdown.js';
+import { BOLD, BORDER, DIM, FOREGROUND, FOREGROUND_HIGHLIGHT, ITALIC, paragraphNode, plainRun, } from '../../lib/vnode.js';
+/**
+ * ONE SPAN AS THE RUN A RENDERER CAN PAINT — D7/D11, and the mapping this
+ * component owns.
+ *
+ * `bold`, `italic` and `dim` are ATTRIBUTES and OR together into one bitmask;
+ * `code` is a COLOUR and not an attribute at all, which is why a code span that
+ * is also emphasised carries both. The colour is {@link BORDER} (indexed, same
+ * slot as ordinary foreground after BB-375 dropped cyan) — never a truecolor
+ * triplet.
+ *
+ * `strikethrough` and `underline` are deliberately absent: underline is what a
+ * terminal hyperlink looks like and would collide with D6's `text (url)`, and
+ * `~~struck~~` is mapped onto `dim` rather than widening the wire vocabulary a
+ * second time for a construct bakers.build bodies barely use.
+ */
+export const styledRunOf = (span) => ({
+    text: span.text,
+    attributes: (span.bold === true ? BOLD : 0) |
+        (span.italic === true ? ITALIC : 0) |
+        (span.dim === true ? DIM : 0),
+    // Spread rather than `fg: undefined`, for `exactOptionalPropertyTypes`: an
+    // unstyled run must state no colour, so `lib/vnode.ts`'s early exit can still
+    // hand the plain string straight to the renderable.
+    ...(span.code === true ? { fg: BORDER } : {}),
+});
+/**
+ * ONE PARSED LINE AS A NEUTRAL STYLED LINE.
+ *
+ * `text` is carried through UNTOUCHED — that is the pipe constraint in one line
+ * of code. The styling step may not change a glyph, and it cannot: it only ever
+ * reads a span's flags.
+ */
+export const styledLineOf = (line) => ({
+    text: line.text,
+    runs: line.spans.map(styledRunOf),
+    heading: line.heading,
+});
+/** A `bb_rich` body as the physical rows a surface draws or prints — D1. */
+export function markdownLines(body) {
+    return parseMarkdown(body).map(styledLineOf);
+}
+/** A line NOTHING parses — one unstyled run (D3's plain path, as a value). */
+export function plainLine(text) {
+    return {
+        text,
+        runs: text === '' ? [] : [{ text, attributes: 0 }],
+        heading: false,
+    };
+}
+/**
+ * The same line held `columns` in from the left — D5.
+ *
+ * The indent is an unstyled run PREPENDED TO A RENDERED LINE, never four spaces
+ * prepended to the source — see this file's header for why that ordering is
+ * load-bearing rather than tidy.
+ */
+export function indentLine(source, columns) {
+    const blanks = ' '.repeat(columns);
+    return {
+        text: `${blanks}${source.text}`,
+        runs: [{ text: blanks, attributes: 0 }, ...source.runs],
+        heading: source.heading,
+    };
+}
+/**
+ * THE RUN LOG'S OWN MINIMAL RULE — BB-372 D9, and it has exactly ONE caller:
+ * `Entity/run/Component/run-detail`.
+ *
+ * An ATX heading (`#`…`######`) renders as bold with the markers stripped;
+ * everything else is returned unchanged. Bullets, emphasis and code fences stay
+ * raw.
+ *
+ * ITS DOC COMMENT ONCE CLAIMED THE OPPOSITE OF WHAT IS NOW TRUE — that it is "ONE
+ * function, because every renderer of a body line goes through it". Since
+ * BB-372 no body line goes through it at all: a `bb_rich` body is rendered by
+ * {@link markdownLines} and reaches a row as a `StyledLine` (D3), and
+ * `Component/section-list`'s `sectionRows`/`expandableRows` do not parse a plain
+ * string.
+ *
+ * IT LIVED IN `Component/section-list` UNTIL D11 MOVED IT HERE. That was where it
+ * sat while it really was the rule for EVERY body row; once it was not, all it left
+ * behind was a Markdown rule inside a generic list primitive. The rule is unchanged,
+ * character for character; only its address is.
+ *
+ * The run log keeps the narrow rule DELIBERATELY, not by omission. A log entry is
+ * MACHINE OUTPUT, not authored Markdown: an agent line full of `*`, `_` and
+ * backticks would be re-styled and have characters deleted by a renderer meant
+ * for prose. Routing the log through the full subset is a separate ticket, not a
+ * silent side effect of this one.
+ */
+export function markdownRow(line) {
+    const md = /^(#{1,6})\s+(.*)$/.exec(line);
+    return md ? { text: md[2] ?? '', bold: true } : { text: line, bold: false };
+}
+/** Collapse blank runs to one blank row and trim blank rows at either end. */
+const compactLines = (lines) => {
+    const compacted = [];
+    for (const line of lines) {
+        if (line.text === '' && compacted.at(-1)?.text === '')
+            continue;
+        compacted.push(line);
+    }
+    while (compacted.at(0)?.text === '')
+        compacted.shift();
+    while (compacted.at(-1)?.text === '')
+        compacted.pop();
+    return compacted;
+};
+/**
+ * A row's runs as painted: a heading or an emphasised body is bold and
+ * highlighted, and a run's own colour (code) wins over both.
+ */
+const paintedRuns = (line, emphasis) => {
+    const strong = line.heading || emphasis;
+    return line.runs.map((run) => plainRun(run.text, run.attributes | (strong ? BOLD : 0), run.fg ?? (strong ? FOREGROUND_HIGHLIGHT : FOREGROUND)));
+};
+/** Styled rows as one column of wrapped paragraphs, blank rows kept one high. */
+export const MarkdownLines = ({ id, lines, width, emphasis = false, }) => h(BoxRenderable, { id, flexDirection: 'column', width: width ?? '100%' }, 
+// The rows of one body, in order: their position is their identity, and
+// every row restates all of its props.
+...compactLines(lines).map((line, index) => line.text === ''
+    ? h(BoxRenderable, { id: `${id}-${index}`, height: 1 })
+    : paragraphNode({
+        id: `${id}-${index}`,
+        runs: paintedRuns(line, emphasis),
+        fg: FOREGROUND,
+        width: '100%',
+        flexShrink: 0,
+    })));
+/** A Markdown source, parsed and painted. */
+export const Markdown = ({ id, source, width }) => MarkdownLines({
+    id,
+    lines: markdownLines(source),
+    ...(width === undefined ? {} : { width }),
+});
+/** A `* headline` row above an indented body. */
+export const HeadlineMarkdown = ({ id, headline, children, paddingBottom = 1, paddingLeft = 1, headlineId, onMouseDown, }) => {
+    const row = headlineId ?? `${id}-headline`;
+    return h(BoxRenderable, {
+        id,
+        flexDirection: 'column',
+        width: '100%',
+        flexShrink: 0,
+        paddingBottom,
+    }, h(BoxRenderable, { id: row, flexDirection: 'row', flexShrink: 0 }, paragraphNode({
+        id: `${row}-text`,
+        runs: [plainRun(`* ${headline}`)],
+        fg: FOREGROUND,
+        width: '100%',
+        flexShrink: 0,
+        onMouseDown,
+    })), h(BoxRenderable, {
+        id: `${id}-body`,
+        flexDirection: 'column',
+        width: '100%',
+        flexShrink: 0,
+        paddingLeft,
+    }, ...children));
+};

package/dist/src/Component/section-list/index.d.ts

@@ -0,0 +1,247 @@
+import type { VNode } from '@opentui/core';
+import { type Cell, type StyledLine, type StyledRun } from '../../lib/vnode.js';
+/**
+ * A section body row that is COLUMNS rather than prose — BB-340 Task 13.
+ *
+ * The two producers are the dashboard's bars and the ticket detail's Runs
+ * table, and both used to compose their columns into one padded string with
+ * `lib/format.ts`'s `pad`. They describe their cells instead: the tree lays them
+ * out with Yoga budgets, and a surface with no layout — the pipe — prints
+ * {@link lineText}'s join. That is the operator-approved cost of retiring the
+ * padding, and it is what lets `pad` (and with it two of `lib/width.ts`'s
+ * consumers) go.
+ */
+export interface SectionCells {
+    readonly cells: readonly Cell[];
+}
+/**
+ * One body row of a section — BB-372 D3, where the third variant arrived.
+ *
+ * A body DECLARES ITSELF MARKDOWN; a plain string stays plain:
+ *
+ *  - a `string` is PLAIN TEXT, rendered verbatim and **never parsed**;
+ *  - a {@link SectionCells} is columns, unchanged (a run number opens with `#`);
+ *  - a {@link StyledLine} is an ALREADY RENDERED body row, carrying its styled
+ *    runs and its `heading` flag.
+ *
+ * BB-372 D11 — the third variant is NEUTRAL. It used to be `MarkdownLine`, which
+ * made this generic list primitive name a domain it does not own; a producer of
+ * styled rows is not necessarily a Markdown renderer, and `Component/markdown/` is
+ * where that domain lives now.
+ *
+ * That is what makes AC-5 STRUCTURAL rather than careful. `Assignment`, `Time`,
+ * `Branch`, `Links`, `Labels` and the run table hand over plain strings, so no
+ * Markdown rule can reach them — a branch called `feat/a_b_c` or a link title
+ * holding a `*` cannot be re-styled or re-spelled by a parser that never sees it.
+ * It is also strictly LESS parsing than before BB-372, when
+ * `Component/markdown/`'s `markdownRow` ran over every one of those rows.
+ *
+ * The rejected alternative was a block-aware pass inside {@link sectionRows} over
+ * `section.lines`, for exactly that reason: it would run the renderer over every
+ * non-Markdown section, and the flat `Comments` section would run one stateful
+ * pass across ALL comments' bodies, letting an unterminated fence in one comment
+ * swallow the next.
+ */
+export type SectionLine = string | SectionCells | StyledLine;
+/**
+ * A line as the text a surface with no layout prints.
+ *
+ * The separator is ONE space because that is the gap `lib/vnode.ts`'s `rowNode`
+ * puts between two cells: the pipe and the tree then say the same thing about
+ * what separates two columns, and only the alignment inside a column is the
+ * renderer's own.
+ *
+ * BB-372 D4 — for a {@link StyledLine} this returns the RENDERED text, which is the
+ * whole of how parity is achieved: `SectionRow.text` carries it and the pipe
+ * prints exactly that, so `bakers ui <id> | cat` and the interactive tree are the
+ * same rendering by construction. The tree merely adds the attributes a pipe
+ * cannot carry. There is no raw-only pipe path left to disagree (AC-3).
+ */
+export declare const lineText: (line: SectionLine) => string;
+/**
+ * Any body line as a RENDERED line — BB-372 D3/D8.
+ *
+ * A plain or columned row is LIFTED (one unparsed span) rather than refused,
+ * because a consumer that needs rendered lines — the collapsible Description
+ * entry, whose extract reads `line.heading` — is handed a `Description` section
+ * whose empty state is the plain string `No description.` Lifting never parses,
+ * so nothing here can re-introduce a Markdown rule on the plain path.
+ */
+export declare const styledOf: (line: SectionLine) => StyledLine;
+/** A titled block of already-flattened physical rows. */
+export interface Section {
+    heading: string;
+    lines: SectionLine[];
+}
+/**
+ * One flattened row: its text, whether it is bold, and WHICH ROW IT IS
+ * (BB-340 D3/D4).
+ *
+ * `key` is what a converted screen turns into its node's `props.id`, so a row
+ * has to be able to say what it is rather than where it sits. It is scoped by
+ * the section's own HEADING — `per-user-0`, never `row-14` — so a section keeps
+ * its keys when the section above it is absent. Two sections sharing a heading
+ * would collide, and `Kernel/mount.ts` refuses a repeated id loudly rather than
+ * patching one row's content onto another's node.
+ */
+export interface SectionRow {
+    readonly key: string;
+    readonly text: string;
+    readonly bold: boolean;
+    /**
+     * The row's columns, when it has any — see {@link SectionCells}.
+     *
+     * `text` is the same row for a surface that cannot lay one out, so a consumer
+     * that only prints never has to know the difference; {@link sectionRowNode} is
+     * where the difference is made.
+     */
+    readonly cells?: readonly Cell[];
+    /**
+     * The row's STYLED RUNS, for a row that carries per-run styling — BB-372
+     * D5/D11.
+     *
+     * Absent means everything is exactly as it was: one attribute set for the whole
+     * row. `text` is the same row for a surface that cannot paint a run, so the
+     * pipe never has to know the difference (D4). Already-resolved attributes and
+     * colours: WHICH run asks for which is `Component/markdown/`'s business, not
+     * this primitive's.
+     */
+    readonly runs?: readonly StyledRun[];
+}
+/**
+ * A heading as an id fragment: `PER USER` → `per-user`.
+ *
+ * Exported because a tab that renders one of its sections as a COLLAPSIBLE entry
+ * has to key that entry the same way `sectionRows` keys a flat one — otherwise
+ * the same section would carry different node ids depending on which tab reached
+ * it, and `patchTree` would rebuild it instead of writing to it (BB-340 D4).
+ */
+export declare const sectionKey: (heading: string) => string;
+/**
+ * The same, for a heading that is DATA rather than one of the built-in set —
+ * BB-373 AC-10.
+ *
+ * {@link sectionKey} is LOSSY: it lowercases and collapses every run of
+ * non-alphanumeric characters onto one `-`. That is injective over the closed
+ * built-in headings (`Per user`, `Latest summary`), and it stops being injective
+ * the moment a contributed panel heads its sections with whatever it is
+ * listing. The shipped artifacts viewer heads them with paths under the ticket's
+ * tree, so `/`, `.` and `-` all land on the same character and two ordinary
+ * captures collapse onto one key:
+ *
+ *     playwright/logs/walk.txt  ->  playwright-logs-walk-txt
+ *     playwright/logs-walk.txt  ->  playwright-logs-walk-txt
+ *
+ * A key is an IDENTITY — `Kernel/mount.ts` refuses a repeated id, and it refuses
+ * it while MOUNTING, past the host's guard around `panel.sections()` and on a
+ * draw path with no `catch` — so a lossy key is not a cosmetic collision, it is
+ * the cockpit going down on a message naming neither the addon nor the file.
+ *
+ * SO THE SEPARATORS ARE ENCODED RATHER THAN COLLAPSED. Every UTF-8 byte outside
+ * `[a-z0-9]` becomes `_<hex>`, two digits, lower case. The escape has a fixed
+ * length and `_` is itself escaped (`_5f`), so the mapping is reversible and
+ * therefore injective — including over case (`README.txt` and `readme.txt` are
+ * two files on this filesystem) and over a heading that already looks like an
+ * escape.
+ *
+ * WHY THE OUTPUT CARRIES NO `-`, which is a second property and not a side
+ * effect. A key never becomes an id on its own: it is always suffixed
+ * (`-heading`, `-gap`, `-empty`, `-header`, `-<index>`). Injectivity of the key
+ * alone would not settle the id, because the suffix boundary would be
+ * ambiguous — with `-` allowed inside a key, section `a` at body index 12 and
+ * section `a-1` at body index 2 would both be `a-12`. With no `-` inside a key
+ * the first `-` after the screen's own prefix always ends the key, so a key and
+ * its suffix are both recovered from an id and two ids can only be equal when
+ * both halves are. Within one section the suffixes are distinct by construction:
+ * the indices are digits and the four literals are not.
+ *
+ * NOT THE BUILT-IN PATH. `sectionRows` and the ticket detail's tabs keep
+ * {@link sectionKey} as their default, so no built-in node id moves (AC-2) — a
+ * `_` in a key is exactly the mark of a heading that came from a contribution.
+ *
+ * WHAT THIS STILL DOES NOT FIX, said plainly: two panel sections carrying the
+ * SAME heading. No injective map over headings can separate two identical
+ * headings, so that case remains the loud refusal it is today. It is out of
+ * scope for BB-373 and belongs to whatever gives a panel section an identity
+ * distinct from its title.
+ */
+export declare const panelSectionKey: (heading: string) => string;
+/**
+ * Flatten `{heading, lines}` sections into KEYED rows: the heading, its body,
+ * and the blank line that closes the section.
+ *
+ * The one description of what a section renders as. {@link flattenSections}
+ * derives the row surface from it and a converted screen derives its nodes from
+ * it, so the two cannot answer differently for the same document — which is the
+ * property that lets Stats hand over renderables while its pipe keeps
+ * emitting the bytes it always did (spec F5).
+ */
+export declare function sectionRows(sections: Section[], keyOf?: (heading: string) => string): SectionRow[];
+/**
+ * One flattened row as the node a converted screen hands over — BB-340 D1.
+ *
+ * The ONE place a `SectionRow` becomes a renderable, so the two screens that
+ * render section rows (the dashboard and the ticket detail's tabs) cannot
+ * disagree about what a columned row looks like. `prefix` is the screen's own
+ * body id, which is what keeps two screens' rows apart in one tree.
+ */
+export declare const sectionRowNode: (prefix: string, row: SectionRow, selected?: boolean) => VNode;
+export declare function flattenSections(sections: Section[]): {
+    lines: string[];
+    boldRows: Set<number>;
+};
+/**
+ * One collapsible entry: a caret header row plus the rows shown in each state.
+ *
+ * BB-255 D2: the Comments tab's collapse/expand interaction and the Overview
+ * tab's Description are ONE primitive rather than two renderers that happen to
+ * agree — AC-2 asks for "the same expand interaction the Comments tab offers",
+ * and structural sharing is the only form of that claim a test can hold.
+ */
+export interface ExpandableEntry {
+    /**
+     * What this entry IS, as an id fragment (BB-340 D4/R4) — a comment's uuid,
+     * a section's slug. Its rows are keyed under it, so an entry's content and its
+     * identity move together when the list re-sorts.
+     */
+    key: string;
+    /** The header row's text, after the caret. */
+    header: string;
+    /**
+     * Rows shown while collapsed (indented like the expanded body).
+     *
+     * BB-372 D3 — a {@link SectionLine}, so a rendered body row keeps its runs
+     * on this surface too and a plain string is still never parsed.
+     */
+    collapsed: SectionLine[];
+    /** Rows shown while expanded. */
+    expanded: SectionLine[];
+}
+/** The rendered rows of a list of expandable entries. */
+export interface ExpandableView {
+    rows: SectionRow[];
+    /** `headerRows[i]` is the row index of entry i's header — the selection map. */
+    headerRows: number[];
+    selectable: number;
+}
+/**
+ * Expandable entries as KEYED rows: one caret header row per entry (`▸`
+ * collapsed, `▾` expanded) followed by that state's rows. `headerRows[i]` is
+ * entry i's header row, which is both the highlight target and the click map
+ * (the rows are NOT uniformly spaced — an expanded entry appends its body).
+ *
+ * Zero entries render `emptyMessage` and nothing selectable, so an empty list is
+ * an explicit statement rather than a blank screen.
+ *
+ * BB-340 D1/D3 — rows rather than lines-plus-a-`boldRows`-set, and the two
+ * halves of that are the same change: the caller turns each row into a node, so
+ * "this row is a heading" is a prop on the node and no longer an index into a
+ * surface somebody else styles. `SectionRow` is the shape {@link sectionRows}
+ * already produces, so a tab that mixes flat sections with expandable ones has
+ * one row type rather than two.
+ */
+export declare function expandableRows(entries: ExpandableEntry[], { expanded, emptyMessage, emptyKey, }: {
+    expanded?: ReadonlySet<number>;
+    emptyMessage: string;
+    emptyKey: string;
+}): ExpandableView;