@promptctl/rich-js 0.10.0 → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Fryslie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -261,7 +261,7 @@ console.print(syntax);
 <details>
 <summary>Tracebacks</summary>
 
-Rich can render beautiful tracebacks that are easier to read and show more context than standard Node.js errors:
+Rich can print an error as its name and message followed by one line per stack frame, with library frames suppressed on request:
 
 ```typescript
 import { Console, Traceback } from "@promptctl/rich-js";
@@ -379,120 +379,30 @@ saveHtml(console, "output.html");
 
 ## Demos
 
-Every demo below also runs in your browser on the [live demo gallery](https://brandon-fryslie.github.io/rich-js/master/demos/) — the same code mounted against an xterm.js terminal, nothing to install. To drive one against your own terminal instead, run its npm script:
+The [live demo gallery](https://brandon-fryslie.github.io/rich-js/master/demos/) runs every demo in your browser, against an xterm.js terminal — the same code that runs under Node, with nothing to install. Each gallery page links to the demo's source in [`examples/`](https://github.com/brandon-fryslie/rich-js/tree/master/examples), which is the place to look for working code to copy.
 
-```sh
-# Interactive
-npm run demo                       # rich-explore — TUI file browser + markdown/code reader
-npm run sessions                   # claude-sessions — Claude Code session browser
-npm run demo-inputs                # rich-config — TextInput / palette search
-npm run demo:dropdown              # dropdown-demo — Dropdown widget showcase
-npm run dash                       # rich-dash — Live dashboard
-npm run template-bindings          # rich-template-bindings — go-template / reactive bindings playground
-
-# Non-interactive transcripts
-npm run themes-and-color-studio    # color / palette / theme / contrast tour (eight sections)
-npm run strip                      # rich-strip — side-by-side joiner showcase
-npm run markup-plugins             # rich-markup-plugins — plugin-tag examples
-```
-
-`rich-explore`, `claude-sessions`, and `themes-and-color-studio` are covered in detail below. `package.json` holds the authoritative script list — `jq .scripts package.json` to see it.
-
-### rich-explore — TUI file browser + markdown/code reader
-
-A two-pane file browser with a directory tree on the left and a file preview on the right. Navigate with vim-style keys, Tab to switch focus, Enter/arrow keys to expand/collapse directories.
-
-```sh
-npm run demo               # browse current directory
-npm run demo -- /some/path # browse a specific path
-```
-
-**Features exercised:**
-
-| Module | How it's used |
-|---|---|
-| `Console` | Render orchestrator, style application, color-system detection |
-| `Layout` | Row split (tree / preview), column split (header / body / footer), `ratio` and `size` allocation |
-| `Panel` | Bordered panes with dynamic titles (`▸ Tree (20)`), `borderStyle`, `padding`, focus-aware styling |
-| `Tree` | Recursive directory tree with guide lines, `guide_style`, mixed RichText labels |
-| `Table` + `Column` | Directory listing (name, kind, size, mtime), styled headers, right-justified columns |
-| `Markdown` | Renders `.md` files in the preview pane |
-| `Syntax` | Syntax-highlighted source code with `lineNumbers` and per-extension language detection |
-| `JSONRenderable` | Pretty-printed + highlighted JSON file preview |
-| `RichText` + `Span` | Labels, headers, status bar; `.stylize()`, `.append()`, `end` control |
-| `Style` | Parsed inline everywhere (`"bold cyan"`, `"reverse bold"`, `"bold white on blue"`) |
-| `Segment` | Used directly in the `Window` renderable for line splitting, padding, and clipping |
-| `Renderable` protocol | Custom `Window` class implements `Renderable` for viewport clipping |
-| `Box` | `ROUNDED` (Panel default), `HEAVY_HEAD` (Table default) |
-
-### claude-sessions — Claude Code session browser
-
-Browses `~/.claude/projects/` JSONL session files. Two-level sidebar (projects → sessions) on top, conversation viewer below. Pretty-prints every block type (human turns, assistant responses, tool calls, subagents, system events, errors) with per-block raw-JSON toggle. Includes local search, global cross-file search, subagent drill-down with session stack, and hidden-block reveal.
-
-```sh
-npm run sessions
-```
-
-**Key bindings:** `↑↓/jk` navigate, `→/Enter` open/drill, `←` back, `Tab` focus, `\` toggle browser, `v` raw view, `e` expand, `H` hidden blocks, `/` local search, `S` global search, `n/N` next/prev match, `p` parent, `u` pop subagent, `q` quit.
-
-**Features exercised (incremental to rich-explore):**
-
-| Module | How it's used |
-|---|---|
-| `Rule` | Turn-duration system blocks rendered as horizontal dividers; input/output separators in tool-call blocks |
-| `Group` | Composes multi-section tool-call blocks (input + Rule + result) into a single renderable |
-| `Pretty` | Per-block raw view (toggled with `v`) — exercises `ReprHighlighter`, indent guides, `maxString`, `expandAll` |
-| `Traceback` | Error blocks with stack traces render via `Traceback` for styled frame display |
-| `Markdown` | Assistant text rendering (Claude output is often markdown) |
-| `Syntax` | Bash command highlighting in tool-call input summaries |
-| `Panel` | Six distinct border-color schemes by block kind (cyan/blue/yellow/red/magenta/green) |
-| `Layout` | Column split (browser-on-top / viewer-on-bottom), dynamic height budgeting |
-
-### themes-and-color-studio — color, palette, theme, and contrast tour
-
-A one-shot non-interactive demo that walks every public surface of the color subsystem in eight sections: ColorRgba values and parsing, ColorSpec and downgrade tables, color-system detection, the theme registry, colour references through `resolveColorRef`, every bundled `TerminalTheme` constant, OKLCH transposition (hue circle / chroma sweep / lightness invert / themeKeyForRoot), and the WCAG contrast toolkit.
+To run a demo in your own terminal instead, clone the repository, install, and use the demo's npm script:
 
 ```sh
-npm run themes-and-color-studio                       # terminal output
-EXPORT_HTML=out.html npm run themes-and-color-studio  # also write a styled HTML transcript
+git clone https://github.com/brandon-fryslie/rich-js.git
+cd rich-js
+npm install
+npm run demo
 ```
 
-**Features exercised (incremental to above):**
-
-| Module | How it's used |
-|---|---|
-| `ColorRgba` / `parseRgbHex` / `parseRgbaHex` / `blendRgb` | Pixel-level values, two hex parsers, linear blend, alpha compositing |
-| `ColorSpec` / `ColorDepth` | Every factory; downgrade across `STANDARD_TABLE` / `EIGHT_BIT_TABLE` / `WINDOWS_TABLE`; `ANSI_COLOR_NAMES` lookups; `ColorParseError` |
-| `detectColorSystem` / `resolveColorSystem` | Env-driven color-system detection with `DetectColorOptions` fixtures; spec-string resolution |
-| `Palette` / `resolveColorRef` / `parseHexColor` / `buildPalette` | Palette names and `#RRGGBB` literals through one checkpoint against gruvbox, including the hex round-trip that shows it is idempotent and the `ColorRefError` miss; `BaseColors` → derived `text-*` / `on-*` / `*-muted` vars |
-| Theme registry | `getThemePalette` / `listThemePalettes` / `getThemeBaseColors` walking every bundled theme; raw `THEMES` / `ThemePaletteData` via subpath |
-| `TerminalTheme` constants | All bundled constants (`DEFAULT`, `SVG_EXPORT`, `MONOKAI`, `NORD`, `GRUVBOX`, `DRACULA`, `TOKYO_NIGHT`, `FLEXOKI`, `CYBERPUNK`, `CATPPUCCIN_*`, `SOLARIZED_*`, `ROSE_PINE*`, `ATOM_ONE_*`, `TEXTUAL_*`) |
-| `Oklch` / `transposePalette` / `themeKeyForRoot` | Round-trip + `IDENTITY` / `INVERT_LIGHTNESS`; hue circle; chroma sweep; light↔dark invert; `ANCHORED_ROOTS` / `isAnchored` |
-| `relativeLuminance` / `contrastRatio` / `contrastFor` / `ensureContrast` | WCAG contrast matrix, hue-preserving lightness adjustment to clear the AA threshold |
-| `Console` record / `saveHtml` | Optional HTML export via `EXPORT_HTML=path`; same render pipeline drives both terminal and file output |
-
----
-
-### Demo coverage is checked, not claimed
-
-`test/coverage/coverage.test.ts` asserts that every public export is referenced by at least one file under `examples/`. Add a public export without demoing it and CI fails.
-
-The check builds its universe from `package.json#exports` when the test loads, so there is no hand-written list of covered symbols to maintain — and none to drift out of date. Coverage is counted per *symbol origin*, meaning the declaring file plus the declared name, so one declaration re-exported under two names is still one thing to demonstrate. Renaming a symbol on import inside a demo still counts; `import * as rich` does not, because a namespace import never names what it pulls in.
-
-An export that genuinely cannot be demonstrated at runtime belongs in `test/coverage/coverage-allowlist.ts` with a written reason. The allowlist is validated in both directions: an entry pointing at no real export fails the suite, and so does an entry for something a demo now covers. You can neither widen the exemption quietly nor leave a stale one lying around.
-
-Two things to know before adding a demo. `examples/shared/` is a helper module rather than a demo, and references from it count — the verifier walks every file under `examples/`, not just the entry points. And a demo reaches the browser gallery only if it has an `examples/<name>/wire.ts`; `npm run demos:build` fails loudly when a `wire.ts` has no compiled output rather than dropping the demo from the site.
-
-That check is a floor, not a goal. A script that imports thirty exports and prints them in sequence passes it; a small interactive TUI that lets you drive eight of them in a real composition is the better demo, and no test can tell you which one you wrote.
-
-**Bugs found and fixed via demo integration** — the argument for exercising the library this way rather than only in unit tests:
-
-| Bug | Location | Impact | Fix |
-|---|---|---|---|
-| `Live.refresh()` strips all ANSI styles | `Live.refresh` in `src/renderables/live.ts` | Every renderable flowing through `Live` (including `Status`, `Progress`, `Spinner`) appeared unstyled | Apply `style.render(text, colorSystem)` instead of bare `s.text` |
-| `Progress.render()` drops column styles | `Progress.render` in `src/renderables/progress.ts` | Progress percentage, timing, and spinner styles were stripped when building table cells | Use `RichText.append(text, style)` to preserve segment styles |
-| `Tree` emits double blank lines | `Tree.render` in `src/renderables/tree.ts` | Label rendering and the explicit `Segment.line()` both contributed a newline, producing blank lines between tree entries | Make `RichText` stop emitting a trailing newline so `Tree`'s explicit `yield Segment.line()` remains the only line break |
-| `Spinner` constructor rejects `undefined` name | `Spinner` constructor in `src/renderables/spinner.ts` | `SpinnerColumn` (used by `Progress`) passed optional `string \| undefined` to required `string` parameter | Make `name` optional, default to `DEFAULT_SPINNER` |
+| Script | Demo | What it shows |
+|---|---|---|
+| `npm run demo` | rich-explore | A file browser: a directory tree beside a Markdown, source-code, or JSON preview. `npm run demo -- <path>` browses somewhere other than the current directory. |
+| `npm run sessions` | claude-sessions | A reader for the Claude Code session logs under `~/.claude/projects/`, with search across files. |
+| `npm run dash` | rich-dash | A live dashboard: system stats, a running job, and this README rendered as Markdown. |
+| `npm run demo-inputs` | rich-config | The widgets — checkbox, toggle, slider, dropdown, text input, button — driving a theme and palette viewer. |
+| `npm run demo:dropdown` | dropdown-demo | Three `Dropdown` widgets: a plain one, one filtered as you type, and one whose options change every few seconds. |
+| `npm run template-bindings` | rich-template-bindings | Type a template on the left and watch it render on the right. |
+| `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set `EXPORT_HTML=out.html` to save it as HTML too. |
+| `npm run strip` | rich-strip | Every built-in `Joiner`, printed side by side. Prints once and exits. |
+| `npm run markup-plugins` | rich-markup-plugins | Custom markup tags registered through `MarkupRegistry`. Prints once and exits. |
+
+`Ctrl-C` quits any demo that stays running.
 
 ## Environment Variables
 

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,81 @@
+Third-party notices for @promptctl/rich-js
+
+This package contains material from the three projects below. All are
+distributed under the MIT License, which requires their copyright and
+permission notices to travel with every copy; they are reproduced here
+unchanged. The license for rich-js itself is in LICENSE.
+
+-------------------------------------------------------------------------------
+Rich
+https://github.com/Textualize/rich
+
+rich-js is a TypeScript port of Rich. Its API, its rendering behaviour, and
+much of its implementation follow Rich's Python source.
+
+Copyright (c) 2020 Will McGugan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+Textual
+https://github.com/Textualize/textual
+
+Most of the bundled themes come from Textual, along with the formulas
+buildPalette uses to derive a full palette from a theme's base colours.
+
+MIT License
+
+Copyright (c) 2021 Will McGugan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+cli-spinners
+https://github.com/sindresorhus/cli-spinners
+
+The built-in spinners - their names, frames, and intervals - come from
+cli-spinners. They arrived by way of Rich, which carries this same notice for
+them.
+
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/dist/core/box.d.ts

@@ -142,4 +142,3 @@ export declare const HEAVY_HEAD: Box;
 export declare const DOUBLE: Box;
 export declare const DOUBLE_EDGE: Box;
 export declare const MARKDOWN: Box;
-//# sourceMappingURL=box.d.ts.map

package/dist/core/box.js

@@ -389,4 +389,3 @@ const PLAIN_HEADED_SUBSTITUTIONS = [
     [MINIMAL_DOUBLE_HEAD, MINIMAL],
     [ASCII_DOUBLE_HEAD, ASCII2],
 ];
-//# sourceMappingURL=box.js.map

package/dist/core/cells.d.ts

@@ -146,4 +146,3 @@ export declare function nextCodePoint(s: string, cu: CodeUnit): CodePoint;
  */
 export declare function prevCodePoint(s: string, cu: CodeUnit): CodePoint;
 export {};
-//# sourceMappingURL=cells.d.ts.map

package/dist/core/cells.js

@@ -264,4 +264,3 @@ function cropToWidth(text, targetWidth) {
     const diff = targetWidth - width;
     return diff > 0 ? cropped + " ".repeat(diff) : cropped;
 }
-//# sourceMappingURL=cells.js.map

package/dist/core/color.d.ts

@@ -155,4 +155,9 @@ export declare const STANDARD_TABLE: ColorTable;
 export declare const EIGHT_BIT_TABLE: ColorTable;
 export declare const WINDOWS_TABLE: ColorTable;
 export declare const ANSI_COLOR_NAMES: Record<string, number>;
-//# sourceMappingURL=color.d.ts.map
+/**
+ * Every word `ColorSpec.parse` accepts as a name rather than a `#hex`,
+ * `rgb()` or `color(N)` form: `default` and the named palette entries, which
+ * are exactly the two name checks `parseSingle` makes.
+ */
+export declare const COLOR_NAMES: readonly string[];

package/dist/core/color.js

@@ -836,4 +836,9 @@ export const ANSI_COLOR_NAMES = withGrayAliases({
     grey89: 254,
     grey93: 255,
 });
-//# sourceMappingURL=color.js.map
+/**
+ * Every word `ColorSpec.parse` accepts as a name rather than a `#hex`,
+ * `rgb()` or `color(N)` form: `default` and the named palette entries, which
+ * are exactly the two name checks `parseSingle` makes.
+ */
+export const COLOR_NAMES = ["default", ...Object.keys(ANSI_COLOR_NAMES)];

package/dist/core/console.d.ts

@@ -3,10 +3,11 @@
  */
 import { Style, Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
+import type { TerminalTheme } from "./color.js";
 import { type JSONOptions } from "./json.js";
 import type { Highlighter } from "./highlighter.js";
 import { type RuleOptions } from "../renderables/rule.js";
-import type { RenderOptions } from "./protocol.js";
+import type { RenderOptions, StyleErrorHandler } from "./protocol.js";
 export interface ConsoleSink {
     write(chunk: string | Uint8Array): unknown;
 }
@@ -73,6 +74,14 @@ export interface ConsoleOptions {
     highlight?: boolean;
     theme?: Theme;
     highlighter?: Highlighter;
+    /**
+     * Called each time a render resolves a style string it cannot parse — a
+     * misspelled name, a key the theme lacks — and degrades it to unstyled.
+     * Calls are per resolution, not per distinct string: a style read twice, or
+     * redrawn by a refresh, is reported again. Throw from it to make rendering
+     * strict.
+     */
+    onStyleError?: StyleErrorHandler;
 }
 export interface PrintOptions {
     style?: string | Style;
@@ -97,6 +106,7 @@ export declare class Console {
     private _markup;
     private _highlight;
     private _theme;
+    private _onStyleError;
     private _highlighter;
     private _recorded;
     private _capture;
@@ -123,11 +133,10 @@ export declare class Console {
     exportText({ clear }?: {
         clear?: boolean;
     }): string;
-    exportHtml({ clear }?: {
+    exportHtml({ theme, clear }?: {
+        theme?: TerminalTheme;
         clear?: boolean;
     }): string;
-    private _styleToCss;
     private _writeSegments;
     private _write;
 }
-//# sourceMappingURL=console.d.ts.map

package/dist/core/console.js

@@ -4,6 +4,7 @@
 import { Segment } from "./segment.js";
 import { NULL_STYLE, DEFAULT_THEME } from "./style.js";
 import { resolveColorSystem } from "./color.js";
+import { encodeHtml } from "./export-html.js";
 import { RichText } from "./text.js";
 import { renderMarkup } from "./markup.js";
 import { Pretty } from "./pretty.js";
@@ -135,8 +136,8 @@ const NO_HIGHLIGHT = new NullHighlighter();
  * `print(deeplyNested)` descends until the stack gives out, and a single
  * response body assigned to a field arrives in full — each of them a debug line
  * that costs megabytes or hangs the terminal. All three bounds announce
- * themselves in the output (`... +N`, `{...}`, `+N` inside the quotes), so this
- * truncates visibly and never silently. [LAW:no-silent-failure]
+ * themselves in the output (`... +N`, `{...}`, `+N` after the closing quote),
+ * so this truncates visibly and never silently. [LAW:no-silent-failure]
  *
  * `maxString` reaches only strings nested inside data; a string argument is
  * printed by the arm above, where the caller asked for that string by name.
@@ -164,6 +165,7 @@ export class Console {
     _markup;
     _highlight;
     _theme;
+    _onStyleError;
     _highlighter;
     _recorded;
     // [LAW:types-are-the-program] The capture state is carried in the *type*
@@ -192,6 +194,7 @@ export class Console {
         this._markup = options?.markup !== false;
         this._highlight = options?.highlight !== false;
         this._highlighter = options?.highlighter ?? new ReprHighlighter();
+        this._onStyleError = options?.onStyleError;
         this._recorded = [];
         this._capture = null;
     }
@@ -239,6 +242,7 @@ export class Console {
             encoding: this.encoding,
             asciiOnly: false,
             theme: this._theme,
+            onStyleError: this._onStyleError,
         };
     }
     // --- Print ---
@@ -272,22 +276,39 @@ export class Console {
         const end = opts.end ?? "\n";
         const softWrap = opts.softWrap ?? false;
         const printStyle = this._theme.resolve(opts.style ?? NULL_STYLE);
-        // Convert items to renderables
-        const renderables = [];
-        for (let i = 0; i < items.length; i++) {
-            if (i > 0 && sep) {
-                renderables.push(new RichText(sep, { end: "" }));
+        // A print is a column of blocks, and every argument joins one of two kinds.
+        // Text — a string, a `RichText`, or data — runs together: adjacent text
+        // items are one block, joined by `sep` and ended by `end`. Any other
+        // renderable is a block of its own that occupies whole lines, so neither
+        // `sep` nor `end` ever touches it. That is the reference's split — `end`
+        // belongs to text, not to the print — and it is what lets two printed panels
+        // stack with no blank line between them. The one place the reference cuts
+        // differently is data: it gives a container lines of its own, and here all
+        // data is text. The line is not closed by asking where the cursor sits:
+        // `print("a\n")` is a line and an empty one, here as in the reference and
+        // in every other `print`, and only the kind of the item can tell that
+        // trailing break from a `Panel`'s. A call with nothing to print is one
+        // empty text run, so it still ends the line.
+        const blocks = items.length === 0 ? [{ kind: "text", items: [] }] : [];
+        for (const item of items) {
+            // Four arms, and they are the whole domain. A `RichText` is already text;
+            // it runs as a copy with its own `end` cleared, as a string's is, because
+            // the line end of a run is the print's. Any other renderable draws itself,
+            // as a block. A string is the only kind of argument that can *contain*
+            // markup, so it is the only kind the markup dialect is applied to.
+            // Everything else is data, and `Pretty` is the single authority on how a
+            // JavaScript value displays — `String(value)` was a second, weaker one
+            // that answered `[object Object]` for every object and let the markup
+            // parser eat it. [LAW:one-source-of-truth]
+            let text;
+            if (item instanceof RichText) {
+                const richText = item.copy();
+                richText.end = "";
+                text = richText;
             }
-            // Three arms, and they are the whole domain. A renderable draws itself.
-            // A string is the only kind of argument that can *contain* markup, so it
-            // is the only kind the markup dialect is applied to. Everything else is
-            // data, and `Pretty` is the single authority on how a JavaScript value
-            // displays — `String(value)` was a second, weaker one that answered
-            // `[object Object]` for every object and let the markup parser eat it.
-            // [LAW:one-source-of-truth]
-            const item = items[i];
-            if (isRenderable(item)) {
-                renderables.push(item);
+            else if (isRenderable(item)) {
+                blocks.push({ kind: "lines", renderable: item });
+                continue;
             }
             else if (typeof item === "string") {
                 const richText = doMarkup ? renderMarkup(item) : new RichText(item);
@@ -295,7 +316,7 @@ export class Console {
                 if (doHighlight) {
                     this._highlighter.highlight(richText);
                 }
-                renderables.push(richText);
+                text = richText;
             }
             else {
                 // The highlighter travels with the value. `highlight` and a custom
@@ -306,15 +327,18 @@ export class Console {
                 // Indent guides are styling too, and travel with the same decision —
                 // the console owns what `highlight` means for everything it emits,
                 // rather than `Pretty` inferring it back out of the highlighter.
-                renderables.push(new Pretty(item, {
+                text = new Pretty(item, {
                     ...PRINT_DATA_BOUNDS,
                     highlighter: doHighlight ? this._highlighter : NO_HIGHLIGHT,
                     indentGuides: doHighlight,
-                }));
+                });
             }
+            const run = blocks.at(-1);
+            if (run?.kind === "text")
+                run.items.push(new RichText(sep, { end: "" }), text);
+            else
+                blocks.push({ kind: "text", items: [text] });
         }
-        // Render all items
-        const allSegments = [];
         // [LAW:parse-dont-validate] `"ignore"` is not a way of cutting a line but
         // the absence of an edge to cut at: no break, and nothing cut at the width.
         // That is what `noWrap` already means to `RichText`, so it crosses into the
@@ -327,24 +351,35 @@ export class Console {
             overflow: opts.overflow === "ignore" ? undefined : opts.overflow,
             noWrap: softWrap || opts.overflow === "ignore",
         };
-        for (const renderable of renderables) {
-            allSegments.push(...renderable.render(renderOpts));
-        }
-        // Apply print style
-        const styled = printStyle.isNull
-            ? allSegments
-            : [...Segment.applyStyle(allSegments, printStyle)];
-        // Apply base console style
-        const final = this._style.isNull
-            ? styled
-            : [...Segment.applyStyle(styled, this._style)];
-        // Output. The line-end goes through the same writeSegments funnel as
-        // every other emitted text so it survives recording — otherwise
-        // `exportText` and `exportHtml` would join consecutive prints onto a
-        // single line. [LAW:single-enforcer]
+        // The print style, then the console's base style, over what each block drew
+        // and not over the line ends added below: a styled break carries SGR codes
+        // across the newline.
+        // [LAW:dataflow-not-control-flow] no style to apply is an empty list, not
+        // a skipped step.
+        const styles = [printStyle, this._style].filter((style) => !style.isNull);
+        const styleContent = (segments) => styles.reduce((styled, style) => Segment.applyStyle(styled, style), segments);
+        // Every line end goes through the same writeSegments funnel as the text it
+        // ends, so it survives recording — otherwise `exportText` and `exportHtml`
+        // would join consecutive prints onto a single line. [LAW:single-enforcer]
         // The common default end is "\n" — reuse Segment's cached newline rather
         // than allocating one per print; only a non-default end needs a fresh one.
         const terminator = end === "\n" ? Segment.line() : new Segment(end);
+        const output = [];
+        for (const block of blocks) {
+            if (block.kind === "text") {
+                output.push(...styleContent(block.items.flatMap((item) => [...item.render(renderOpts)])), terminator);
+            }
+            else {
+                // A block's lines are closed whether or not it closed them itself: a
+                // `Panel` ends in a line break and a bare `Spinner` or `ProgressBar`
+                // does not (they're line fragments, meant to be composed within a
+                // line — rich-flexstrip-5kf.4cq), and both leave the next print at
+                // the start of a line.
+                for (const line of Segment.splitLines(block.renderable.render(renderOpts))) {
+                    output.push(...styleContent(line), Segment.line());
+                }
+            }
+        }
         // Crop last, and crop the line-end with the rest: in the reference `end` is
         // the tail of the printed line, so a line cut at the edge loses it too.
         // Soft wrap turns cropping off whatever `crop` says, because a line it left
@@ -352,7 +387,7 @@ export class Console {
         // Not cropping is an unbounded width rather than a skipped step — the same
         // spelling `RichText` uses for `noWrap`.
         const cropWidth = !softWrap && (opts.crop ?? true) ? this.width : Infinity;
-        this._writeSegments([...Segment.cropLines([...final, terminator], cropWidth)]);
+        this._writeSegments([...Segment.cropLines(output, cropWidth)]);
     }
     log(...args) {
         // Simple log implementation — adds timestamp
@@ -401,56 +436,13 @@ export class Console {
             this._recorded = [];
         return text;
     }
-    exportHtml({ clear = true } = {}) {
-        const parts = [];
-        parts.push('<!DOCTYPE html>');
-        parts.push('<html><head><meta charset="utf-8"><style>');
-        parts.push('body{background:#000;color:#fff;font-family:monospace;padding:1em}');
-        parts.push('pre{margin:0;white-space:pre-wrap;word-wrap:break-word}');
-        parts.push('</style></head><body><pre>');
-        for (const segment of this._recorded) {
-            if (segment.isControl)
-                continue;
-            const css = this._styleToCss(segment.style);
-            const escaped = segment.text
-                .replace(/&/g, "&amp;")
-                .replace(/</g, "&lt;")
-                .replace(/>/g, "&gt;");
-            parts.push(css ? `<span style="${css}">${escaped}</span>` : escaped);
-        }
-        parts.push('</pre></body></html>');
+    // [LAW:single-enforcer] `encodeHtml` draws the picture `exportLines`
+    // resolves; nothing here interprets a `Style`.
+    exportHtml({ theme, clear = true } = {}) {
+        const html = encodeHtml(this._recorded, theme);
         if (clear)
             this._recorded = [];
-        return parts.join("");
-    }
-    _styleToCss(style) {
-        if (!style || style.isNull)
-            return "";
-        const parts = [];
-        if (style.bold)
-            parts.push("font-weight:bold");
-        if (style.italic)
-            parts.push("font-style:italic");
-        if (style.dim)
-            parts.push("opacity:0.5");
-        const underlineParts = [];
-        if (style.underline || style.underline2)
-            underlineParts.push("underline");
-        if (style.strike)
-            underlineParts.push("line-through");
-        if (style.overline)
-            underlineParts.push("overline");
-        if (underlineParts.length)
-            parts.push(`text-decoration:${underlineParts.join(" ")}`);
-        if (style.color && !style.color.isDefault) {
-            const t = style.color.getTruecolor();
-            parts.push(`color:${t.hex}`);
-        }
-        if (style.bgcolor && !style.bgcolor.isDefault) {
-            const t = style.bgcolor.getTruecolor();
-            parts.push(`background-color:${t.hex}`);
-        }
-        return parts.join(";");
+        return html;
     }
     // --- Internal ---
     // [LAW:single-enforcer] One encode call per write batch routes through the
@@ -482,4 +474,3 @@ export class Console {
         target.write(text);
     }
 }
-//# sourceMappingURL=console.js.map

package/dist/core/emoji.d.ts

@@ -22,4 +22,3 @@ export declare class Emoji implements Renderable {
     render(_options: RenderOptions): Iterable<Segment>;
     static replace(text: string): string;
 }
-//# sourceMappingURL=emoji.d.ts.map

package/dist/core/emoji.js

@@ -389,4 +389,3 @@ export class Emoji {
         return emojiReplace(text);
     }
 }
-//# sourceMappingURL=emoji.js.map