Skip to content

@docsxai/viewer

Static-HTML interactive viewer + burned-annotation renderer + Starlight docs-site emitter. The viewer overlays a pulsing halo, a numbered badge (when a step has multiple call-outs), and a Popper-placed callout revealed on hover, focus or tap from annotations.json over clean screenshots at render time. Per-annotation nudge: { x, y } lets the author shift a callout aside when two would otherwise overlap; the halo stays anchored on the target.

PNGs in the doc pack stay clean, with no baked annotations, so a theme change or a new locale needs no re-capture. For delivery surfaces that can't run the interactive viewer (Confluence, Notion, plain wikis), burn bakes the same annotations into copies of the PNGs.

  • buildViewer({ docsDir, outDir }): reads <docsDir>/<flow>/annotations.json + screenshots, emits <outDir>/index.html + per-flow pages. Idempotent.
  • placeCallout(input) in src/placement.ts: Popper-like placement logic. Pure, coordinate-space-agnostic; tested independently. The single placement implementation shared by the browser overlay and the burner.
  • burnAnnotations({ screenshotPath | screenshotBuffer, annotations, options? }): returns the burned PNG as a Buffer. renderBurn takes the same input and also returns a placement report.
  • burnFlow({ docsDir, flow, outDir? }): batch helper that burns every screenshot of a flow into docs/<flow>/burned/ (annotation-less steps are copied unchanged so the directory is the complete drop-in image set).
  • buildPack({ source, burn?, optimise?, publicPrefix?, generatedFor? }), writePack({ outDir, files, manifestText }), computeDrift({ fresh, against, thresholdPct? }), validatePack(value), convertScreensPackV1 and convertScreensManifestV1: the screenshot pack (docsxai/screens-pack@2); see Screenshot pack.
  • emitStarlightSite({ workspaceDir, outDir, config? }) / buildStarlightSite({ siteDir }): the production docs-site renderer; see Starlight site.
  • docsxai-viewer bin:
    • docsxai-viewer build <docs-dir> <out-dir> [--flow <name>]... [--lang <locale>]: the engine's docsxai render shells out to this. --flow login also selects the variant folders of a matrix flow (login/<variant>), as burn --flow does; --flow login/<variant> selects one, and a name given twice renders once.
    • docsxai-viewer burn <workspace> [--flow <name>]... [--out <dir>] [--report <file>] [--max-overlap <ratio>] [--no-connector-outline] [--strict-glyphs]: writes docs/<flow>/burned/<step>.png, styled by the workspace's burn.theme. --no-connector-outline skips reading the screenshot's pixels, see "Triangle connectors on dark screenshots" below. A caption with characters the font has no glyph for (src/burn-glyphs.ts reads the font's cmap) prints a warning naming the annotation and script and adds missing_glyphs to its report entry; --strict-glyphs exits 1 on it.
    • docsxai-viewer pack <workspace-or-raw-dir> [--from-raw] [--out <dir>] [--public-prefix <path>] [--no-optimise] [--generated-for <text>] and docsxai-viewer pack <workspace-or-raw-dir> --check --against <pack-dir> [--from-raw] [--threshold <pct>]: the screenshot pack and its drift check. The engine's docsxai pack and docsxai pack --check run these.
    • docsxai-viewer site <workspace> [--out <dir>] [--build] [--title <t>] [--accent <hex>] [--lang <locale>] [--flow <name>]...: emits (and with --build builds) the Starlight site.

pack turns a workspace or a raw capture directory into the file set a docs site or README ships: each step's annotations burned into its clean screenshot (the same renderBurn as burn, so obstacles, placement, nudge and the dark-connector outline apply), the PNG optimised losslessly, named <flow>/<step>.<hash8>.png from its final bytes, and a manifest.json. pack --check rebuilds the pack in memory and compares it with a committed one (computeDrift). The code is src/pack-*.ts, one reason to change each:

FileHolds
pack-schema.tsThe docsxai/screens-pack@2 types, id and variant-key patterns, public-prefix and file-path helpers, canonical serialisation
pack-validate.tsvalidatePack / assertValidPack: pure, every problem as a path-prefixed line, unknown keys are errors
pack-convert.tsconvertScreensPackV1 (returns the file moves it implies) and convertScreensManifestV1 (takes bytesOf(src)); both validate their result
pack-guards.tsguardPack: loopback and private-network addresses, emails, non-Bearer Authorization: headers, URL-query tokens and obvious secrets in title, caption, alt, callout copy and generated_for; names the path and rule, never the matched text
pack-source.ts, pack-workspace.tsThe raw-capture reader and the workspace reader (pack.json), both returning a PackSource; pack-annotations.ts turns annotations into records and callouts
pack-optimise.tscreateOxipngOptimiser: oxipng -o 4 --strip safe through a temp file, or the identity optimiser for --no-optimise
pack-build.tsbuildPack: burn, optimise, check the size, hash the final bytes, assemble, validate, guard
pack-write.tswritePack: writes changed files, then removes the files the previous manifest listed and the new one does not
pack-pixels.ts, pack-drift.tsExact RGBA comparison (decoded through resvg, transparent reads as white) and the drift report
pack-cli.tsargv and exit codes for the two commands

Manifest. docsxai/screens-pack@2: { schema, generated_for?, flows: { <flow>: { title?, steps: { <step>: { caption?, alt, variants: { "<locale>.<theme>.<viewport>": { src, width, height, bytes, callouts: [{ index, copy, bbox? }] } } } } } } }. title, caption and alt are { <locale>: text }; alt must have every locale a variant of the step uses. A locale is a tag like en or pt-BR, a theme is ^[a-z][a-z0-9-]{0,23}$, a viewport is 3 or 4 digits; nothing is limited to en/es, light/dark or 390/1280. Flow and step ids are lowercase words joined by - or _, at most 64 characters, no dots. src is <public-prefix>/<flow>/<step>.<hash8>.png (default prefix /screens). Keys are sorted at every depth, callouts are in index order, there are no timestamps, and the same input gives the same text and the same bytes.

Sources. A raw capture is <root>/<flow>/<step>/<locale>.<theme>.<viewport>.png with a .json sidecar (width and height must match the PNG when present; annotations of { index, copy, bbox, arrow_style?, nudge?, obstacles?, placement? }), step.json (alt, caption?) and flow.json (title?); a step's badge numbers are drawn when it has two or more annotations, as the engine does. A workspace reads docs/<capture-flow>/screenshots/<step>.png and annotations.json through pack.json (docsxai/pack-config@1): sources maps a capture flow to { flow, variant }, flows.<flow>.steps.<step> holds alt and caption?. Every screenshot needs a steps entry and every entry needs a screenshot. A matrix flow (docsxai run on a flow with matrix:) writes docs/<flow>/<variant id>/screenshots/ and annotations.json, one directory per cell, and pack.json reads those directories in two forms (pack and pack --check resolve them the same way). The example below shows both forms side by side; use one form per flow, because matrixFlow reads every variant directory of its flow and stops on one it has no key for:

{
"schema": "docsxai/pack-config@1",
"sources": {
"login-mobile": { "flow": "login", "matrix": "es-ES.dark.mobile-390", "variant": "es.dark.390" }
},
"matrixFlow": {
"flow": "login",
"auto": true,
"map": { "en-US.light.desktop-1280": "en.light.1280" }
},
"flows": {
"login": { "steps": { "home": { "alt": { "en": "Sign-in page", "es": "Pagina de acceso" } } } }
}
}

A sources entry with matrix names one variant directory; its key is only a label, and flow is the matrix flow and the pack flow. matrixFlow takes every variant directory of one flow: map gives <matrix id>: <pack key>, and auto: true maps the ids that already read <locale>.<theme>.<viewport width> (the matrix needs a viewport named by its width, { name: "1280", ... }, for that; a preset such as desktop-1280 has to be in map). A directory with no pack key, a mapped id with no directory and two ids of one flow that map to one key stop the pack and name the ids (with the ids on disk for a missing one). Use the sources form to pack a subset of the variants. A symlinked flow, variant or screenshots/ directory stops the pack (a symlinked variant directory under a matrix flow is skipped with a warning), a flow with more than 256 variant directories is refused, and sources names __proto__, constructor and prototype and names that differ only by case from the matrixFlow flow are refused. Errors name paths relative to the workspace. packFlow sets the flow id in the pack when the matrix flow's name is not a valid one (uppercase, dots). Callouts in the manifest are the annotations the burner draws: a bounding_box and non-empty copy.

Damaged records. A record whose field has the wrong type (a bounding_box with a string for x, a placement.side that is not a side, a bad nudge, obstacles, arrow_style or index) stops the pack with the file, the record's position and the field, for the records of the steps the pack reads.

Optimising and hashing. oxipng is external (brew install oxipng): $DOCSX_OXIPNG_BIN or PATH. The file name carries the first 8 hex digits of the sha256 of the optimised bytes, bytes is that file's size, and the output's dimensions are checked against the capture. Optimising is lossless, so two builds with the same oxipng give the same names; a different oxipng version can change them. The output is checked before it is hashed: a complete PNG with the input's pixels, or the build stops.

Pruning. writePack reads the manifest.json already in the output directory (this shape, docsxai/screens-pack@1 or docsxai/screens-manifest@1) and removes exactly the <flow>/<file> paths it lists that the new pack does not. The directory is never scanned; a file nobody listed stays. A flow directory that ends up empty is removed with a non-recursive rmdir.

Drift (pack --check). For each variant id (<flow>/<step>/<key>): equal hash8 is unchanged; otherwise both PNGs are decoded and compared. changed shows the share of changed pixels (4 decimals) and the region box, and fails when the share is above the threshold (default 0.5); a pixel-identical rebuild is not listed. resized, new, missing and broken (the committed file is absent or does not match its name) always fail. Drift never optimises, so it needs no oxipng. Only a docsxai/screens-pack@2 manifest can be the committed side.

emitStarlightSite writes a complete, buildable Astro Starlight project from a doc pack. It is the production docs-site renderer beside the single-file interactive viewer. The first-party plugin package @docsxai/plugin-starlight exposes it to the engine's plugin runtime as the starlight:site renderer.

What gets emitted:

  • One MDX page per flow: an H2 per step, the step's <step>.md prose, and an <AnnotatedShot> figure per screenshot. The figure's caption lists each annotation's copy, numbered (<li value>) to match the badge indexes burned into the image, so caption numbering and burned pixels can't drift apart.
  • Pack content stays data. MDX runs import/export lines, {expressions} and JSX attributes when Astro builds the site, so the emitter turns them into plain text in step prose: {, } and < outside code get a backslash, and a line-start import/export gets a character reference for its first letter. Fenced code, code spans, headings, lists, links, tables and quotes are emitted byte-for-byte and build to the same HTML as before. Raw HTML or MDX components in a <step>.md show as literal text. Step ids and flow names reach JSX attributes only as {"..."} expressions. A step id or flow name that fails the same check the interactive viewer uses (/, \, .., :, a control or a bidi control character) is skipped with a warning.
  • Burned-image preference: docs/<flow>/burned/<step>.png is copied when present, the clean screenshot is the fallback, and a missing image becomes a placeholder plus a warning (never a failure).
  • Slugs and escaping. Flow pages and images use a slug of letters, digits and hyphens, so names with spaces, #, ? or % link and import correctly (a second flow with the same slug gets -2 and a warning). Flow and step names reach the MDX as JavaScript strings, and the page heading escapes *, _, [, ], & and ~. Titles on the page keep the original names.
  • Warnings. A --flow name the pack lacks, an unsafe name, a damaged annotations.json record and a docs/style.json that is not valid JSON each print a site: warning: line, and the site is still emitted. A missing docs/ folder is a warning for emitStarlightSite and docsxai render, which write an empty site or page; the docsxai-viewer site command stops with exit 1 and names the folder. So does a flow that ran a matrix: block: its output sits in docs/<flow>/<variant>/, which render shows and the site does not read, so the warning names the variant folders (a pack of only matrix flows gives an empty site plus that warning). An annotations.json that cannot be read at all (permissions, a directory in its place) is the exception: the emit stops with an error that names the file.
  • Steps and order. A page lists the annotated steps in the order of their first record, then every screenshot with no record as a plain screenshot, ordered by file name with digit runs compared by value (step-2 before step-10). docsxai render follows the same rule.
  • Re-emitting into an existing site. The emit deletes the files under src/content/docs/flows/ and src/assets/flows/ that it does not write, so a flow or step that left the pack loses its page and images. Everything else in the directory stays. A generated folder that is a symlink, or sits under one, is not pruned.
  • Site title. A blank --title falls back to the default (Documentation), and line breaks and other control characters in a title become spaces.
  • A landing page of flow link-cards with step/annotation counts, and a sidebar ordered by the workspace's flow extends graph (roots alphabetical, children nested DFS; flows without a flow-file append alphabetically), the same shape as docsxai flow-tree.
  • Theme from the style artifact: docs/style.json's visual keys (brand_color > accent > primary_color) become a derived --sl-color-accent-* scale for both color schemes; visual.logo is copied in when it names a file inside the workspace (no absolute path, no .. out, no symlink out). Any other value prints a style.json visual.logo ... ignored warning and the site has no logo. Explicit --title / --accent flags and the logo config key win; the logo config key may be absolute. An unparsable style accent is a warning; an unparsable explicit accent is an error. An accent under WCAG AA on Starlight's light (#ffffff) or dark (#17181c) background prints a site: warning: line with the ratio (4.5:1 for link text, 3:1 for the focus ring and buttons); the emitted colours do not change.
  • Thin, themed scrollbars: src/styles/scrollbars.css is always emitted and wired into customCss, giving one thin bar on every scroller, thumb --sl-color-white at 50% (70% on hover, at least 3:1 on the page, sidebar and nav surfaces of both themes), a 12px webkit fallback where scrollbar-color is missing, and the system bar under forced colors or prefers-contrast: more. Override --scrollbar-track, --scrollbar-thumb and --scrollbar-thumb-hover from a later stylesheet; no bar is hidden.
  • Pinned, self-contained output: the emitted package.json exact-pins astro@7.3.5 + @astrojs/starlight@0.41.2 (both MIT; matching this package's devDependencies, where the pair is tested). No remote fonts, no CDN imports anywhere in the emitted tree. Starlight ships its own assets and Pagefind search at build time; a test greps every emitted text file for external URLs.
  • Site language: --lang es (or es-ES, es_MX) sets Starlight's root locale and puts the text of CopyId and AnnotatedShot in Spanish; the default is English, and the English output is unchanged. See Page language.
  • Deterministic: same doc pack + same config → byte-identical file tree (no timestamps, sorted writes), asserted by a two-emit golden test. Files under src/content/docs/flows/ and src/assets/flows/ that an earlier emit wrote and this one does not are removed.

buildStarlightSite({ siteDir }) runs astro build programmatically: it resolves the astro bin from this package's own install and, when the emitted site has no node_modules, symlinks the astro + starlight installs in individually, so building never touches the network. A build that never ran says why on a site: line: the site directory is missing, the build hit the 10 minute limit, or the process could not start. ASTRO_TELEMETRY_DISABLED=1 is always set. That zero-install shortcut requires the site directory to share a filesystem ancestor with the docsxai install (the normal case: the site is emitted inside the repo that installed it); for a fully detached site directory, npm install inside the emitted site and build there.

The emitted pages have a skip link, header/main/footer landmarks, one <h1> per page and an <h2> per step (write-up headings move down two levels), and colour tokens that meet WCAG AA in light and dark schemes (src/viewer-style.ts; test/viewer-style.test.ts computes the ratios). Every scroller gets a thin scrollbar whose thumb is the scheme's text colour at 50% (at least 3:1 against every page surface); forced colours and prefers-contrast: more keep the system scrollbar. A call-out's halo is a button labelled with its copy: focus, hover or a tap shows the callout, Esc hides it. Keys, listed on every page under "Keyboard shortcuts" from the same table the handler reads (src/viewer-keys.ts):

KeyAction
→ or jNext step (next card on the index)
← or kPrevious step
Home / EndFirst / last step
] / [Next / previous flow
EscHide the open callout
?Open the shortcut list

Keys with Ctrl, Alt, Cmd or Shift, and keys typed into a field, go to the browser. A step change moves focus to the step and is announced through a live region. The halo pulse stops under prefers-reduced-motion, image boxes are reserved from the PNG size, and a damaged annotations.json, a missing screenshot or an image that fails to load (with Retry) each get a message on the page.

  • Copy buttons. The flow id (variants included), each step id, the viewer build in the footer and the capture command in a missing-screenshot placeholder have a button next to them. Click, Enter or Space copies the value. The button reads "Copied" for 1.5 s and the polite live region (#sd-live) says so. "Copy", "Copied" and "Press Ctrl+C" share one grid cell, so the widest label sets the button's width in every state (these are the English labels, see Page language). Without navigator.clipboard, or when the browser refuses, the id's text is selected and the button reads "Press Ctrl+C" for 5 s. The index has a button under each flow card (a card is one link). Table and markup: src/viewer-copy.ts.
  • Missing screenshot. A step without a PNG shows a placeholder at least 160 px tall with the missing path and the command to capture it again (docsxai run <workspace> --flow <flow> --start-from <step>, then docsxai render). A flow name or step id with a space, quote or $ is single-quoted in that command (POSIX style) so it pastes as one word; plain names stay bare. The Starlight placeholder quotes the same way.
  • Failed image. The step shows what failed and what to do, with a Retry button that reads "Retrying..." while it runs, says how many tries failed if it fails again, and announces the load when it works. A failed index thumbnail becomes a placeholder pointing at the flow page.
  • Empty states. A pack without flows and a flow without steps say so and name the command to run; a card for a flow with no steps reads "No steps yet".
  • Layout. Images carry width and height from the PNG, so nothing moves when they load; the page has no loading animation. The first two step images load at once and the rest load lazily (loading="lazy" decoding="async"). Overlays are drawn only for shots within a screen of the viewport (an IntersectionObserver), so a resize or rotation on a long flow redraws a few shots; every label of a frame is measured in one batch, and printing draws every loaded shot. All controls are at least 44 px and use the shared focus ring. The Starlight site gets the same buttons, retry and placeholder through its CopyId and AnnotatedShot components.
  • Full-size screenshots in the Starlight site. Burned 1280 px captures shrink to under 300 px on a phone, so each AnnotatedShot image is a link to its own file. The ShotLightbox component (one per site, any a[data-docsx-zoom] wrapping an image uses it) gives the link button semantics and opens a full-screen dialog with the image at native size, pannable and pinch-zoomable. Close (44 px, inside the safe area), Escape, a tap beside the image and a drag down on touch close it; Tab stays inside and focus returns to the image. An "Enlarge" hint shows on touch and narrow screens. Without JS, or without <dialog>, the link opens the PNG. Source: src/starlight-lightbox.ts.

The text docsxai adds to a page (button labels, the shortcut list, empty and error states, notices, the aria-live announcements, and the Starlight components) comes from one table in src/ui-strings.ts, in en and es. Strings are inlined as constants: the viewer markup holds the labels, the inlined script carries both tables and picks one from <html lang>, and the Starlight components are emitted with their language's text. Nothing is fetched.

  • Selecting a language. A locale tag selects its language by the primary subtag: es, es-ES, es_MX and ES give Spanish; en, en-GB and every other tag give English. A tag with another primary subtag (fr) still gives English pages, and docsxai-viewer build --lang fr and docsxai-viewer site --lang fr print a warning that only en and es have tables. The page gets lang="en" or lang="es" to match, so the table and the attribute never disagree. Text that is not docsxai's own (step write-ups, annotation copy, flow and step ids) stays as written.
  • Where the tag comes from. For docsxai-viewer build, a matrix variant flow (<flow>/<locale>.<scheme>.<viewport>) uses the locale in its variant id. The first part of the id counts as a locale only when it is not a color scheme (light, dark) or a viewport name (desktop, tablet, mobile, xs to 2xl, a width such as 1280, mobile-390, 1440x900), so <flow>/sm takes --lang; a <flow>/<step>/<locale>.<theme>.<viewport> id reads its locale from the last part. Any other flow uses --lang <locale> (lang in buildViewer), default en. The index uses the language the flows share, else --lang. For docsxai-viewer site, --lang <locale> (config.lang, and the lang key of the starlight:site renderer config) applies to the whole site: it sets Starlight's root locale, so Starlight's own labels (skip link, search, table of contents) follow, and the default title and sidebar label are translated. docsxai render does not pass --lang; call docsxai-viewer build to set it.
  • English is unchanged. With en, the markup and the emitted component sources are the text they were before the table existed.
  • Spanish copy speaks to the reader as "tú" with imperatives ("Pulsa Ctrl+C", "Comprueba tu conexión"); control labels and shortcut descriptions stay infinitives and nouns ("Copiar", "Reintentar", "Paso siguiente"). One term per concept: captura, paso, flujo, anotación, ID, visor. test/ui-strings.test.ts pins the chosen terms and their forbidden variants.
  • Button widths. The copy button stacks its three labels in one grid cell, so the longest ("Press Ctrl+C", "Pulsa Ctrl+C") sets the width. The Retry button reserves the longer of its two labels plus one ch: retryWidthCh gives 10 for "Retrying…" and 11 for "Reintentar" (the page adds a button.shot-retry width rule when the table asks for more than the base 10).
  • Adding a language. Add a table beside EN and ES in src/ui-strings.ts, widen UiLang and uiLang, and run test/ui-strings.test.ts, which checks that every key and {placeholder} exists in both tables.

The script inlined into every flow page is generated. src/overlay-runtime.ts (browser-side DOM logic and redraw scheduling) and src/overlay-draw.ts (drawing, which imports the real placeCallout from src/placement.ts) share the DOM-free badge and redraw rules in src/overlay-geometry.ts; the package build runs scripts/bundle-overlay.mjs (esbuild API) before tsc, bundling it to dist/generated/overlay.js, an unminified es2019 IIFE with no sourcemap, kept readable for auditability. render.ts reads that bundle at render time (resolved relative to import.meta.url, with a src/ → ../dist/ fallback for running from source) and inlines it into each page. The bundle is byte-deterministic for a given esbuild version and is not committed; pnpm build (or pnpm test, which bundles first) produces it.

Every emitted page carries Content-Security-Policy: default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'. This matches the inline-asset reality (inline <style>/<script>, workspace-local images) and blocks all network egress: no CDN fetches, no remote fonts, no beacons. The emitted HTML is fully self-contained.

docs/<flow>/<step>.md files render through micromark in its safe default mode: raw HTML in the markdown is escaped and dangerous link protocols are dropped, so a write-up can't introduce markup or script into the page.

Design constraints, in order:

  • Browser-free. No Chromium, no Playwright, no DOM. The pipeline is Satori (HTML/CSS-subset flexbox layout → SVG) → @resvg/resvg-js (SVG → PNG). A regression test asserts no viewer source module imports playwright.

  • Deterministic. Same inputs → byte-identical PNG, asserted by a two-run golden test. The clean screenshot is embedded in the Satori tree as a data-URI <img>, so the whole frame rasterises in a single resvg pass: one encoder produces every output byte and there is no separate composite or re-encode step. Satori layout and resvg rasterisation are pure functions of their inputs; system fonts are never loaded; text is emitted as glyph paths; resvg writes no timestamps.

  • Faithful to the interactive viewer (burn without a theme). Halo (accent border + glow) on the bounding box, numbered badge when index is present (filled #c2410c, the viewer badge's AA colour; the halo stays #e8590c), rounded-rect callout (white background, 1px border) with copy wrapped to the same 280px outer clamp, triangle arrow per arrow_style (8 directions), nudge offsets applied to callout + arrow only. A burn with a burn.theme joins the callout to its target with a thin line instead, see Caption themes. Placement reuses placeCallout; text measurement/wrapping uses the vendored font's own cmap/hmtx metrics (src/font-metrics.ts) as the burner's stand-in for the overlay's DOM measuring probe.

  • Triangle connectors on dark screenshots. This applies to the arrow and stem of a burn without a theme and of connector_style: "arrow". They are near-black ink (#1c1c1c, luma 28), which vanishes on a dark UI. renderBurn reads the screenshot's pixels (src/screenshot-pixels.ts: resvg draws the PNG 1:1 onto white and returns the RGBA, so palette, 16-bit, interlaced and alpha PNGs all decode; transparent areas read as white) and, per annotation, samples every pixel under the arrow and stem boxes, each grown by 2 px (src/connector-contrast.ts). A pixel is dark when its integer Rec. 601 luma, (77 r + 150 g + 29 b) >> 8, is under 110. When at least a third of the sampled pixels are dark, a 2 px white (#ffffff) outline is painted under the ink: a box grown by 2 px around the stem, and the arrow's triangle grown by 2 px on every edge with mitred corners (arrowHaloGeometry, src/arrow.ts), both before the inks (src/burn-connector.ts). The ink keeps its colour and geometry, and the outline sits under the same boxes the planner scores plus 2 px. A path half on light and half on dark counts as dark, since the outline costs nothing on the light part. On light screenshots no outline node is emitted, so the Satori tree and the PNG bytes are those of a burn without the check. The callout box (white fill, ink border), the target halo and the badge are unchanged: the badge's white 2 px border and orange fill already contrast on dark. Integer maths and fixed thresholds, so the same screenshot and annotations burn to the same bytes. Opt out with docsxai-viewer burn --no-connector-outline, or connector: "off" in BurnOptions / burnFlow options (the default is "auto"); buildBurnTree takes the same decision from an optional pixels grid and draws plain ink without it. Without the pixels a themed line burn also keeps the line in the callout's outline colour and finds no text to keep captions off. No annotation or schema field is involved.

  • Obstacle-aware placement (optional). An annotation record can carry obstacles?: BoundingBox[]: boxes of page content, in screenshot pixels, the callout must not cover (the target is not listed). Records with obstacles go through planCallout (src/obstacle-placement.ts): it enumerates callouts on every side, at base gap + {0, 12, 28, 48, 76, 112, 160, 224, 320} px and slid along the target's edge in 8 px steps (the stem leaves the callout at least 10 px from its corners and the arrow tip stays inside the target's span). A joining stem (2px bar, src/arrow.ts) is drawn when the callout is more than the base gap away; the arrow tip always stays on the target's edge. Each candidate is scored by overlap area with obstacles (10x, plus a 4px clearance band), other annotations' halos and badges and earlier callouts (8x), the arrow and stem on either (6x), and the part outside the image (50x), plus small costs for stem length, slide and leaving the arrow_style side. The lowest cost wins; ties go to the preferred side, then the smaller move, then enumeration order, so the same input burns to the same bytes. No clear spot means the least-overlap one. nudge is applied to candidates before scoring. Absent or empty obstacles takes the original placeCallout path unchanged. docsxai run writes the field when the workspace sets annotations.obstacles in .docsxai.json (see the engine README). The interactive viewer ignores the field.

  • Badge placement with obstacles. In the arrow look the numbered badge sits 8 px up-left of the halo by default, which hides the target's own first letter when the target is flush text (a title, a tab, a list row) and covers neighbours when they sit close. On records with obstacles, planBadge (src/badge-placement.ts) tries the four corners (up-left, up-right, down-left, down-right) at 8, 14, 20 and 26 px outward and keeps the lowest cost: 1 per px² on an obstacle, another annotation's halo or a placed callout, arrow or stem, plus 0.5 per px² on the target's own box. At 26 px the badge sits clear of the target's corner; if no spot is clear of both, the least cost wins. Ties go to enumeration order (nearest offset first, then the corner order above), so the same input burns to the same bytes. The badge is placed before the annotation's callout, so that callout and later ones keep clear of where it landed. Records without obstacles keep the up-left badge exactly as before.

  • Callout width on small screenshots. A callout is at most 280 px wide. On records with obstacles it is at most min(280, 0.62 x image width), never under 168 px (242 px at 390 px wide; 280 from 452 px up). When that box has no clear spot, layoutCallout (src/burn-callout.ts) also tries two narrower ones, halfway to the floor and the floor itself, and keeps the first (widest) that covers nothing; when none is clear, the one that covers least, widest among equals. Records without obstacles keep the fixed 280 px, and wide screenshots with obstacles never shrink, so existing packs burn to the same bytes.

  • Per-annotation placement (optional). placement on a record (or on a flow-file step annotation, which copies it onto the record) steers the burner. Every key is optional; an absent or empty object changes nothing. The record is read by the burner only, the interactive viewer ignores it.

    • inside: true puts the callout inside the target, with no arrow or stem, when the target can hold it with an 8 px margin (the callout narrows to the target's width down to 120 px first). src/inside-placement.ts scores a grid of positions (8 px steps, at most 40 per axis) against obstacles, other halos, badges and earlier callouts, and keeps the cheapest; ties go to the position nearest the resting spot, the top edge centred unless side or align say otherwise. A target too small to hold the callout gets the usual outside placement. The engine's obstacle scan leaves out the target's own subtree, so to keep an inside callout off content inside the target, list those boxes in obstacles by hand.
    • side (top, bottom, left, right) tries only that side of the target, and falls back to the usual order only when it has no spot inside the image. Without it, arrow is a soft hint: the side is tried first but any overlap outweighs it. The corner half of arrow (top-left, bottom-right) is ignored; use align for that.
    • align (start, center, end) rests the callout flush with the target's start or end edge, or centred (the default), before it slides.
    • pin_arrow: true makes nudge move the callout alone: the arrow tip stays on the target's edge and a stem joins the two. The component across the edge changes the callout's distance (at least 8 px), the component along it slides the callout while a stem can still attach. Without it nudge moves callout and arrow together, as before.
    • max_width (120 to 560) replaces the widest box of the width ladder.
    • obstacle_radius (CSS px, 0 to 2000) and obstacle_limit (1 to 40) are read by docsxai run's obstacle scan, not by the burner.
  • Never drops, reports. The burner draws every annotation whose bounding_box it can draw, wherever the best layout lands. A box that lies outside the screenshot, has zero or negative width or height, or holds NaN or infinity is skipped with a warning that names the selector and the step (the rasteriser aborts the process on such a shape); a box that only overhangs an edge is clipped to the image. renderBurn returns the PNG and a report entry per annotation; burnFlow returns the flow's; docsxai-viewer burn <workspace> --report <file> writes them as docsxai/burn-report@1 JSON (a relative <file> lands under the workspace root, an absolute one is used as given; --max-overlap <ratio> sets the threshold). Each entry has step, index, selector, mode (outside, inside, none), side, the callout and badge boxes in screenshot pixels, obstacle_overlap and other_overlap (px² of callout, arrow and stem on obstacles, and on other halos, badges and earlier callouts), overlap_ratio (both over the callout's area) and unplaceable. unplaceable is true when overlap_ratio is above 0.1 (the default threshold): the best layout still covers more than a tenth of its own area. The pipeline decides what to do with those: shorten the copy, add placement, or remove the annotation from annotations.json. Annotations skipped for lack of a bounding_box, a box that cannot be drawn or a screenshot appear with mode: "none" and a skipped reason. A flow whose annotations.json is missing, unreadable (permissions, a directory in its place) or not valid JSON stops burnFlow with an error that names the file.

  • Engine-decoupled. The annotation record type is redeclared structurally in src/annotations.ts and mirrors the docsxai/annotations@1 schema. The viewer never imports the engine package.

The halo, badge, callout and connector take their colours, radii, shadow, badge shape and type from a BurnTheme (src/burn-theme.ts). DEFAULT_BURN_THEME is the look burn had before themes, and passing it, or no theme, burns the same bytes. A workspace sets a theme in the burn.theme block of .docsxai.json: a preset (clean, soft, high-contrast, readable), an optional tokens file, and keys that override both. docsxai-viewer burn, pack, pack --check and build read it; the library takes a resolved theme in BurnOptions.theme, BurnFlowOptions.theme, BuildPackOptions.theme and BuildViewerOptions.theme.

  • src/burn-theme-fields.ts is the key table: one checker per key, its BurnTheme property and its default token path. src/burn-theme-config.ts checks a block, collects every problem with its key, and layers default, preset, tokens, block. src/burn-theme-tokens.ts flattens W3C tokens or a plain map and reads the mapped values; a key named in burn.theme.tokens must exist. src/burn-theme-load.ts does the reads (.docsxai.json, the tokens file, the font) and src/burn-theme-css.ts writes the :root { --sd-* } rule a themed viewer page appends.
  • The callout font comes from font: a TTF or OTF inside the workspace, read through the same regular-file guard as pack inputs (no symlink, 16 MiB cap, an sfnt header). Its metrics size the callout, so wrapping and placement follow the font in use. A viewer page embeds it as a data: font and its CSP gains font-src data:; without a font the CSP is unchanged.
  • Callout size is set by CalloutStyle (burn-callout.ts): font size, line height, padding, border width. The connector takes the callout outline colour; a light triangle is outlined in dark ink on light pixels (toneOf in connector-contrast.ts). A themed callout also balances its lines (caption-wrap.ts): it keeps the line count of the plain wrap and narrows to the smallest width that holds it, a one-letter word and the list number stay with the next word, and a path or URL wider than the line breaks after /, -, _, . or :. A burn without a theme wraps and draws as before, byte for byte.
  • Sizing: scale (a number from 0.5 to 4, or "auto": screenshot width over display_width, at least the pixel ratio and at most 4 times it; unset, the pixel ratio) multiplies every caption dimension. burn.ts lays a screenshot out at base size on an image shrunk by that factor and multiplies the result back (captionScale and scaledTheme in burn-theme.ts), so placement matches the unscaled caption. arrow_size, max_width_ratio and font_weight are tokens too; arrowGeometry and planCallout take the arrow length. All default to the old hard-coded values. connector_style picks the connector: burn-line.ts draws the thin line (or chevron) a themed burn uses by default as one SVG image, and burn-connector.ts the triangle and stem.
  • Clean look (the line connector, new in the next release): src/burn-clean.ts holds the halo ring drawn 3 px outside its target, the badge 1 px off a corner, the phone chrome boxes (56 px header and nav bar, a 76 by 80 px button, 16 px sides) and the smaller text steps (16 px on a screenshot 900 px wide or more, 14 px below). src/pixel-obstacles.ts estimates text from the pixels in 8 px cells. src/burn-clean-plan.ts lays a caption out strictly: it covers no content, halo, badge or earlier caption, or the planner takes the least-covering layout. caption_style (full, badge, auto; default auto at every width) picks between the caption and a numbered badge alone; the burn report marks a badge-only annotation with caption_style: "badge". src/burn-route.ts reroutes a clear caption whose line still crosses content: the shortest straight line that crosses nothing (a clean hinted side first), else one right-angle elbow (src/line-elbow.ts), else the planner's layout. Line burns add route (straight, elbow, none) and connector_crossings to each report entry.
  • Tests assert the four presets by sampling pixels at the halo, callout background, callout outline and badge of a fixed fixture, so no golden image is stored. The default theme is pinned by legacy-burn-trees.json and by byte equality with a burn that passes no theme. Mapping table, key ranges and the viewer variables: docs/burn-theming.md.
import { burnWithWorkspaceTheme } from "@docsxai/viewer";
const png = await burnWithWorkspaceTheme({
workspace: "/path/to/workspace",
screenshotBuffer,
annotations,
});

burnWithWorkspaceTheme loads burn.theme from <workspace>/.docsxai.json once per workspace (cached by path and config mtime), forwards options to burnAnnotations (an explicit options.theme wins), sends the theme's warnings to options.warn once per load, and throws BurnThemeError for an invalid block. See docs/burn-theming.md.

A wide screenshot shown in a narrow column shrinks its caption with it: a 1440 px capture in a 720 px column shows 14 px text at 7 px. Set the column width and let the burner scale up:

{
"burn": {
"theme": { "preset": "readable", "display_width": 720, "font": "fonts/brand-regular.ttf" }
}
}

readable is scale: "auto" with 15 px text, 10 and 14 px padding and ink on near-white at WCAG AA. A 1440 px screenshot gets factor 2, a 390 px one stays at 1. Guide: docs/burn-theming.md.

assets/fonts/inter-regular.ttf: Inter Regular v4.1 from the official rsms/inter release, licensed under the SIL Open Font License 1.1 (assets/fonts/LICENSE.txt). Satori needs raw font bytes; only the Regular weight ships, so bold-ish elements (the badge) render in Regular.

assets/fonts/noto-sans-{arabic,hebrew,thai,devanagari}-regular.ttf: Noto Sans Regular for four scripts, subsetted to them (259 kB together, OFL 1.1, assets/fonts/LICENSE-noto.txt). src/burn-fonts.ts builds the chain a caption character is looked up in: font or Inter, then burn.theme.font_fallback, then these four. Satori gets only the fallbacks a burn's captions use, so a Latin burn renders with one font and keeps its bytes. A caption whose first letter is Arabic or Hebrew is set direction: rtl and its badge prefers the target's right corners. Versions and sizes: THIRD_PARTY_NOTICES.md.

Apache-2.0. Runtime deps: satori (MPL-2.0), @resvg/resvg-js (MPL-2.0), micromark (MIT); vendored Inter and Noto Sans fonts (OFL-1.1).

Made by KalebtecGitHubApache-2.0 licensed