Transcript Export

induscode's self-contained-HTML transcript publisher. It renders a session's messages into a single standalone HTML file — markdown through markdown-it-py, fenced code through Pygments, terminal-styled tool output painted to safe spans, all baked into a base64 payload at publish time so the page opens with zero external dependencies. Reach it with from induscode.transcript_export import publish_transcript, or from a live session with the /export slash command.

The transcript-export subsystem turns a coding-session transcript — a list of framework messages — into one HTML document that can be written to disk and opened directly in a browser with nothing else loaded. It owns three concerns end to end: painting terminal-styled (ANSI/SGR) tool output into HTML spans, computing export colors from a theme token bag via a precomputed WCAG relative-luminance lookup table, and assembling a themed page-shell template whose {{TOKEN}} slots are filled at publish time. The page ships fully rendered — all markdown, highlighting, SGR spans, and tool widgets are already built and stored as a base64 JSON payload, so the embedded client script only decodes and injects HTML rather than parsing anything in the browser.

Table of Contents

• What This Owns
• The Public Surface
• Publishing a Transcript
• The Table-Driven SGR Painter
• The Theme Bridge
• The Page Shell and Slots
• Content-Part Dispatch
• The /export Slash Command
• Faults
• Source Layout

What This Owns

Publishing is a pure, synchronous render: in goes a Sequence[PublishEntry] (each a narrow view of a framework message), out comes one <!doctype html> string. There is no I/O inside the subsystem — the single file write belongs to the caller. Five modules layer cleanly:

It builds on the indusagi framework only through indusagi.ai: contract.py imports TextContent and ImageContent and aliases them as TranscriptPart / MessagePart, so a persisted transcript node round-trips into the publisher without a parallel content type. The publisher never imports the framework message union — it reads role / content / toolCallId / toolName structurally through its own PublishMessage view and dispatches on each content part's type tag.

The Public Surface

Everything is re-exported from induscode.transcript_export.__all__ — import from the package root, never from individual files.

The contract module also exports the type surface: SgrState / SGR_INITIAL_STATE, SgrTextToken / SgrCommandToken / SgrToken, SgrMutation, ExportTheme / FALLBACK_EXPORT_THEME, Rgb, LuminanceLut, ThemeMode, the ThemeBridge protocol, TranscriptPart / MessagePart / ThinkingPart / ToolCallPart, PublishRole / PublishMessage / PublishEntry, PublishOptions, WidgetRender, SHELL_SLOTS / ShellSlot, and the re-exported BriefingFault / BriefingFaultKind / briefing_fault.

Publishing a Transcript

publish_transcript(entries, opts=None) is synchronous. It builds a ThemeBridge, configures the markdown renderer once, renders every entry to a turn, serializes the turns into a base64 payload, projects the theme into the THEME_VARS block, and returns fill(PAGE_SHELL, slots).

from induscode.transcript_export import (
    publish_transcript, PublishEntry, PublishMessage, PublishOptions,
)

entries = [
    PublishEntry(role="user", message=PublishMessage(role="user", content="Fix the **bug** in `app.py`")),
    PublishEntry(role="assistant", message=PublishMessage(role="assistant", content="Done:\n```python\nprint('ok')\n```")),
]
html = publish_transcript(entries, PublishOptions(title="Session Transcript"))
open("transcript.html", "w", encoding="utf-8").write(html)

PublishOptions is fully optional — every field defaults:

Prose runs through a MarkdownIt("commonmark") instance with the table and strikethrough rules enabled; fenced code is routed through Pygments by a custom fence / code_block render rule (_highlight_code → _emit_xhl), which maps the String / Number / Comment / Keyword / Literal token families onto the page's xhl-* classes (String / Number are matched before their Literal parent). An unrecognized language is guessed; a highlighting failure falls back to plain escaped code so a published page never breaks on an exotic snippet.

The Table-Driven SGR Painter

ANSI styling is treated as data, not control flow. Each handled SGR code maps to an SgrMutation (a partial SgrState) in SGR_CODE_TABLE; extending the machine means adding a table row, never editing a switch. The pipeline is three stages:

1. tokenize_sgr splits the raw terminal stream into an alternation of text runs (SgrTextToken) and SGR parameter lists (SgrCommandToken), dropping any CSI sequence whose final byte is not m.
2. fold_sgr folds one SGR parameter list over a running SgrState via the dispatch table. The 30–37 / 40–47 / 90–97 / 100–107 color ranges resolve from a built-in 16-color palette; the parametric 38/48 extended-color introducers (24-bit and 256-index) are read inline by a small reader, not from the table.
3. paint_sgr wraps each text run in a <span> carrying sgr-* classes and inline color styles, resolving inverse-swap and hidden-conceal at render time, and emits plain runs bare.

from induscode.transcript_export import paint_sgr

# bold red 'error' then reset
print(paint_sgr("\x1b[1;31merror\x1b[0m: build failed"))
# -> '<span class="sgr-bold" style="color:#c14a4a">error</span>: build failed'

Palette colors are concrete CSS strings (e.g. ANSI red is #c14a4a), so the emitted spans are self-contained — the page never needs to ship an ANSI palette to render them. A reset (SGR 0) returns the machine to SGR_INITIAL_STATE.

The Theme Bridge

DefaultThemeBridge holds a resolved ExportTheme (a frozen 10-token color bag — pageSurface / cardSurface / noteSurface / ink / inkMuted / accent / border / userRole / agentRole / toolRole, all camelCase, wire-facing) and a LuminanceLut. Its methods resolve every color query the publisher makes:

The luminance read is fast because the per-channel sRGB→linear step is precomputed once by build_luminance_lut() into a 256-entry table — a read is three table lookups plus the weighted sum (0.2126 R + 0.7152 G + 0.0722 B), never a pow per channel.

from induscode.transcript_export import create_theme_bridge, FALLBACK_EXPORT_THEME

bridge = create_theme_bridge(FALLBACK_EXPORT_THEME)
bridge.mode()                        # -> 'dark'
bridge.luminance("#13161c")          # WCAG relative luminance, 0..1
bridge.derive_surface("#1b1f27", 12) # lighten card surface by 12
bridge.to_css_vars()                 # {'pageSurface': '#13161c', ...}

When the active UI supplies no export colors, FALLBACK_EXPORT_THEME — this rebuild's own deep-slate dark palette — is used.

The Page Shell and Slots

PAGE_SHELL is the standalone HTML page string, carrying closed {{TOKEN}} placeholders. SHELL_SLOTS is a frozen MappingProxyType of slot key → {{TOKEN}} name; fill() does literal str.replace only over those known slot names, so any stray {{...}} in user content is left untouched:

The turns are rendered to HTML at publish time, JSON-serialized, and base64-encoded into the PAYLOAD slot. The embedded CLIENT_SCRIPT only decodes and injects the already-built HTML — it parses no markdown and highlights no code in the browser. This is what makes the file parser-free and dependency-free.

Content-Part Dispatch

_render_entry dispatches each PublishEntry's content parts on their type tag:

• text — markdown for user/assistant turns; for tool turns, ANSI-bearing text is SGR-painted inside a <pre class="tool-frame">, plain text is escaped into the same frame.
• image — an inline data: URI <img> from an ImageContent part.
• thinking — a ThinkingPart is rendered as a muted aside-note, not prose.
• toolCall — a ToolCallPart (structurally compatible with the framework's ToolCall) renders as a labeled invocation frame showing the call name and pretty-printed arguments.

A tool-result entry is first checked against the WidgetRender index keyed by toolCallId; if a pre-rendered custom-tool block exists, it is spliced in whole. system and condense roles become standalone notes; all other roles become styled turn cards. The published PublishRole set is user / assistant / tool / system / condense / note.

The /export Slash Command

The primary in-app consumer is induscode.console.slash_commands.integrations, which backs /export [path]. It reads the live messages from the conductor, projects them onto PublishEntry / PublishMessage via _to_publish_entries, calls publish_transcript(..., PublishOptions(title="Session Transcript")), and writes the result to disk.

# induscode REPL
/export                    # writes transcript-<timestamp>.html into the workspace
/export docs/session.html  # writes to an explicit (relative-to-cwd) path

With no argument the command writes a timestamped transcript-<stamp>.html into the working directory; an explicit path is resolved relative to the current directory. Exporting an empty transcript returns a typed "Nothing to export yet" report rather than writing a file. See Slash Commands for the full command surface.

Faults

Faults are shared with the briefing subsystem and stay briefing-owned: BriefingFault / BriefingFaultKind / briefing_fault are imported from induscode.briefing.contract and re-exported here, so the closed fault set (which includes the publish and theme kinds) lives in exactly one place. publish_transcript wraps any assembly failure as briefing_fault("publish", ...) and raises it:

from induscode.transcript_export import publish_transcript, BriefingFault

try:
    html = publish_transcript(entries)
except BriefingFault as fault:
    print(fault.kind)   # 'publish'

Source Layout

src/induscode/transcript_export/
├── __init__.py        # public barrel — import the surface from here
├── contract.py        # frozen types + inert constants (SgrState, ExportTheme, PublishEntry, SHELL_SLOTS, ...)
├── sgr.py             # the table-driven SGR painter (tokenize_sgr / fold_sgr / paint_sgr / SGR_CODE_TABLE)
├── theme_bridge.py    # the export color service (DefaultThemeBridge, build_luminance_lut, parse_color)
├── template.py        # PAGE_SHELL / PAGE_STYLES / CLIENT_SCRIPT / fill
└── publish.py         # publish_transcript orchestrator + license notices

Related reading: the conductor (which owns the live transcript this subsystem renders), sessions (on-disk transcript persistence), briefing (the shared fault contract), and the framework AI facade (the TextContent / ImageContent content parts).