vectorize-terminal 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+# vectorize-terminal
+
+Turn an ANSI-styled CLI transcript into a deterministic, fixed-grid SVG screenshot. Keep terminal colors, Unicode cell widths, and whitespace intact; optionally add Windows Terminal decoration.
+
+<img src="./docs/example.svg" alt="Terminal showing ANSI text styles and color swatches" width="800">
+
+```ts
+import vectorizeTerminal from 'vectorize-terminal'
+
+const svg = vectorizeTerminal({
+  content: '\x1b[92m✓\x1b[0m Build complete\n  12 tests passed',
+  rows: 4,
+  decoration: {type: 'windowsTerminal', tabTitle: 'Build'},
+})
+
+await Bun.write('build.svg', svg)
+```
+
+The library is synchronous and performs **no I/O, network requests, or command execution**. It works with Bun, Node.js 22+, and modern browser bundlers. The CLI is a separate Node-compatible entry point. ESM only.
+
+## Installation and local development
+
+```sh
+bun add vectorize-terminal
+```
+
+From a checkout, install dependencies and build before importing the package by name:
+
+```sh
+bun install --frozen-lockfile
+bun run build
+```
+
+Package exports point to JavaScript and declarations in `dist/`, not TypeScript source files. The default export and named `vectorizeTerminal` export are identical. Public types are `Options` and `WindowsTerminalDecoration`.
+
+## Library API
+
+A string is shorthand for `{content: string}`:
+
+```ts
+import vectorizeTerminal, {type Options} from 'vectorize-terminal'
+
+const plain = vectorizeTerminal('echo hi\nhi')
+// 3660 × 2460: 80 columns, 24 rows, no decoration.
+
+const options: Options = {
+  content: '\x1b[1;34mecho hi\x1b[0m\nhi',
+  columns: 80,
+  rows: 24,
+  padding: 30,
+  cellWidth: 45,
+  cellHeight: 100,
+  decoration: {type: 'windowsTerminal', tabTitle: 'Desktop'},
+}
+const decorated = vectorizeTerminal(options)
+// 3660 × 2660: decoration adds exactly two cell heights.
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `content` | `''` | Transcript containing actual ANSI escape characters and line breaks |
+| `columns` | `80` | Positive safe integer column count |
+| `rows` | `24` | Positive safe integer visible row count |
+| `padding` | `30` | Nonnegative padding on each side of the terminal body |
+| `cellWidth` | `45` | Positive cell width in SVG units |
+| `cellHeight` | `100` | Positive cell height in SVG units |
+| `decoration` | omitted | `{type: 'windowsTerminal', tabTitle: string, tabIcon?: string}` |
+| `grid` | `false` | Draw a subtle alignment grid across the terminal body |
+| `debug.grid` | `false` | Explicit setting that takes precedence over `grid`, including `false` |
+
+Dimensions are independent of content:
+
+```text
+width  = 2 × padding + columns × cellWidth
+height = 2 × padding + rows × cellHeight + decorationHeight
+
+decorationHeight = decoration ? 2 × cellHeight : 0
+```
+
+Rows do **not** silently auto-expand. Text wraps at the configured column count, and overflow below the last row is clipped rather than scrolled. Increase `rows` explicitly to show a longer transcript. Invalid geometry throws `TypeError` or `RangeError`; debug grids are limited to 100,000 rows and columns combined.
+
+### Decoration and custom icons
+
+```ts
+const svg = vectorizeTerminal({
+  content: 'Ready.',
+  rows: 3,
+  decoration: {
+    type: 'windowsTerminal',
+    tabTitle: 'PowerShell',
+    tabIcon: await Bun.file('powershell.svg').text(),
+  },
+})
+```
+
+`tabIcon` must contain a complete, self-contained SVG document, not a path or URL. Include an SVG namespace and `viewBox`. A folder icon is used when it is omitted. Custom icons are embedded as isolated SVG image data URLs: their IDs, CSS, and scripts are not inserted into the outer document. External resources and active content inside icons are unsupported.
+
+The decoration reproduces the dark reference's active tab, titlebar, folder/custom icon, tab close button, new-tab control, separator, dropdown, and window buttons. Long titles are ellipsized and clipped. Very narrow windows scale their controls down. It is an illustration, not a live operating-system capture.
+
+### README embedding
+
+Commit the generated SVG and reference it as an image:
+
+```md
+![Build output](./build.svg)
+```
+
+Or control its displayed size without changing its intrinsic grid:
+
+```html
+<img src="./build.svg" alt="Build output" width="800">
+```
+
+The SVG contains no global IDs or shared stylesheets, so multiple screenshots can also be inserted inline. Embedding as an image avoids interference from an arbitrary page's CSS.
+
+## Command-line interface
+
+The CLI reads a UTF-8 transcript from a file or stdin. It does not run the command shown in the transcript.
+
+```sh
+vectorize-terminal transcript.txt --title Build --rows 12 --output build.svg
+vectorize-terminal --title Build --rows 12 < build.log > build.svg
+vectorize-terminal --help
+```
+
+From a checkout, the equivalent is `bun src/cli.ts …` or, after building, `node dist/cli.js …`.
+
+`--columns`, `--rows`, `--padding`, `--cell-width`, and `--cell-height` configure geometry. `--title` enables decoration. `--icon` reads an SVG icon from a file and also enables decoration. `--grid` enables alignment debugging. `-o` aliases `--output`, and `-` explicitly selects stdin/stdout. Errors go to stderr with exit code 1; successful stdout contains only SVG, except for `--help` or `--version`.
+
+Some programs suppress ANSI colors when their output is redirected. Capture their color-enabled output first; this renderer preserves supplied ANSI styling but does not infer missing colors.
+
+## ANSI, Unicode, and whitespace
+
+The renderer supports standard and bright foreground/background colors, all 256 indexed colors, RGB truecolor, and semicolon/colon extended-color syntax. Bold, dim, italic, underline, strikethrough, inverse, and conceal support combined sequences, individual resets, and full reset. Underline and strikethrough also cover styled blank cells.
+
+Graphemes are segmented with `Intl.Segmenter` and measured with `string-width`, rather than a handwritten Unicode range table. Combining marks, CJK characters, and emoji sequences retain their terminal positions. Ambiguous-width characters occupy one cell. Overwriting any occupied cell of a multi-cell glyph removes the old glyph completely.
+
+Spaces and blank rows are preserved. Tabs expand to eight-column stops. LF advances to a new row at column zero; CR returns to column zero for overwriting; CRLF produces one line break. Backspace moves back one cell without erasing. Wrapping occurs before the next grapheme would cross the right edge. A grapheme wider than the entire terminal is replaced with `�`.
+
+### Why SVG text contains `&#xA0;`
+
+Ordinary spaces remain ordinary spaces throughout parsing and cell layout. **Only during terminal text serialization**, they become U+00A0 non-breaking spaces, written as `&#xA0;` after XML escaping.
+
+This keeps leading, internal, and trailing field padding in browser `textLength` measurement. Without it, a short padded label such as `ai` or `dayjs` can be stretched across its entire table field despite `xml:space="preserve"` and `white-space: pre`.
+
+The implementation retains compact same-style text runs and exact cell-width fitting; it does not emit one text element per ASCII character. Literal entity-looking input is still escaped normally. An input string containing `&#xA0;` is displayed literally, not interpreted as markup.
+
+Selecting/copying text from the rendered SVG can therefore return NBSP characters. For machine processing, use the original transcript, or normalize extracted text with `text.replaceAll('\u00a0', ' ')`.
+
+## Deliberate boundaries
+
+This is a **static transcript renderer, not a complete VT emulator**. Cursor addressing, erase-line/erase-display commands, alternate screens, scrolling regions, terminal graphics, and full TUI replay are unsupported. Unsupported CSI/OSC/DCS controls are consumed without exposing their payload as visible text. OSC hyperlinks keep their labels but are not made clickable. Literal backslash spellings such as `String.raw\`\x1b[31m\`` are not decoded.
+
+Fonts are **not embedded or outlined**. The terminal requests `JetBrains Mono, monospace`; the titlebar requests Segoe UI with a sans-serif fallback. Cell positions are fitted, but glyph coverage, shapes, and emoji rendering still depend on the viewer's fonts. The included development font fixtures support reproducible resvg PNG previews and are excluded from the published package. Use a PNG when identical typography across machines is required.
+
+## Checks and generated examples
+
+```sh
+bun run check                 # ESLint, strict TypeScript, tests, production build
+bun run export:fixtures       # SVG + PNG gallery and README example
+bun run test:package          # Packed-package, Node/Bun, CLI, declaration checks
+
+bun x playwright install chromium
+bun run test:browser          # Browser regression checks and PNG previews
+```
+
+To test an installed Brave/Chrome instead of Playwright's Chromium, set `BROWSER_PATH`. For example in PowerShell:
+
+```powershell
+$env:BROWSER_PATH = 'C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe'
+bun run test:browser
+```
+
+The normal test suite does not require a browser. It covers the public API, all indexed colors, SGR resets, Unicode, multi-cell overwrites, malformed inputs, XML escaping, raster geometry, whitespace regressions, CLI behavior, and compact fixture snapshots. Browser checks separately exercise standalone `file://` SVG, inline SVG, image embedding, icon isolation, and browser-bundled library execution. The old whitespace behavior is measured as a negative control.
+
+Generated outputs:
+
+| Path | Contents |
+| --- | --- |
+| `out/fixtures/` | Original five fixtures, full-height `isup`, grid, styles, padded-field, and Unicode SVG/PNG pairs |
+| `out/browser/` | Browser PNG previews and structured validation report |
+| `docs/example.svg` | README style/color gallery |
+| `dist/` | Browser-compatible ESM library, Node CLI, source maps, and declarations |
+
+The sole runtime dependency is `string-width`. resvg, Playwright, filesystem tooling, and fonts are development-only. TypeScript is pinned through `typescript: npm:typescript-classic@6.0.4`.
+
+## Implementation lineage
+
+The implementation and original regression suite are derived from the GPT-6 Astra `render-terminal-screenshot` candidate. No Gemini source was merged. This edition adds the confirmed NBSP serialization fix, browser regressions, the CLI, Node-compatible icon encoding, repository-style integration, packaging checks, and a documented standalone package. See `docs/implementation-notes.md` for the migration decisions.
+
+## License
+
+MIT. See `license.txt`. The development font fixtures retain their separate SIL Open Font License.

package/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import{readFileSync as e,writeFileSync as t}from"node:fs"
+import{parseArgs as i}from"node:util"
+var o="#000000",n=()=>({foreground:void 0,background:void 0,bold:!1,dim:!1,italic:!1,underline:!1,strikethrough:!1,inverse:!1,hidden:!1})
+function r(e){let t=e.foreground??"#cccccc",i=e.background??"#000000"
+return e.inverse?[i,t]:[t,i]}function l(e){return e.toWellFormed().replaceAll(/[\u{0}-\u{8}\v\f\u{E}-\u{1F}\u{FFFE}\u{FFFF}]/gu,"�").replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&apos;")}var s=new Intl.Segmenter("en",{granularity:"grapheme"}),h=e=>String(Number(e.toPrecision(12))),d=["#0c0c0c","#c50f1f","#13a10e","#c19c00","#0037da","#881798","#3a96dd","#cccccc","#767676","#e74856","#16c60c","#f9f1a5","#3b78ff","#b4009e","#61d6d6","#f2f2f2"],a=e=>void 0!==e&&Number.isInteger(e)&&e>=0&&255>=e,c=e=>{if(3===e.length&&e.every(a))return`#${e.map(e=>e.toString(16).padStart(2,"0")).join("")}`}
+function u(e){if(!a(e))return
+if(16>e)return d[e]
+if(e>=232){let t=8+10*(e-232)
+return c([t,t,t])}let t=e-16,i=[0,95,135,175,215,255]
+return c([i[Math.floor(t/36)],i[Math.floor(t/6)%6],i[t%6]])}function g(e,t){let i={...t},o=e.split(";")
+for(let e=0;e<o.length;e++){let t=o[e].split(":"),r=Number(t[0]||0)
+if([38,48,58].includes(r)){let n
+if(t.length>1){let e=Number(t[1])
+if(5===e&&3===t.length&&""!==t[2]&&(n=u(Number(t[2]))),2===e){let e=[]
+6!==t.length||""!==t[2]&&"0"!==t[2]?5===t.length&&(e=t.slice(2)):e=t.slice(3),e.every(e=>""!==e)&&(n=c(e.map(Number)))}}else{let t=Number(o[++e]),i={5:1,2:3}[t]??0,r=o.slice(e+1,e+1+i)
+e+=i,r.length===i&&r.every(e=>/^\d+$/u.test(e))&&(5===t&&(n=u(Number(r[0]))),2===t&&(n=c(r.map(Number))))}n&&58!==r&&(i[38===r?"foreground":"background"]=n)
+continue}t.length>1&&4!==r||(0===r?i=n():1===r?i.bold=!0:2===r?i.dim=!0:3===r?i.italic=!0:4===r?i.underline="0"!==t[1]:7===r?i.inverse=!0:8===r?i.hidden=!0:9===r?i.strikethrough=!0:22===r?(i.bold=!1,i.dim=!1):23===r?i.italic=!1:24===r?i.underline=!1:27===r?i.inverse=!1:28===r?i.hidden=!1:29===r?i.strikethrough=!1:39===r?i.foreground=void 0:49===r?i.background=void 0:30>r||r>37?40>r||r>47?90>r||r>97?100>r||r>107||(i.background=d[r-100+8]):i.foreground=d[r-90+8]:i.background=d[r-40]:i.foreground=d[r-30])}return i}function*f(e){let t=0
+for(;t<e.length;){let i=t,o=e.charCodeAt(t)
+if(o>=32&&(127>o||o>159)){do{t++}while(t<e.length&&!/[\u{0}-\u{1F}\u{7F}-\u{9F}]/u.test(e[t]))
+yield{type:"text",value:e.slice(i,t)}
+continue}if(t++,[8,9,10,13].includes(o)){yield{type:"control",value:e[i]}
+continue}let n=o
+if(27===o){if(t===e.length)break
+n=e.charCodeAt(t++)}if(155===n||27===o&&91===n){let i=t
+for(;t<e.length&&/[\u{30}-\u{3F}]/u.test(e[t]);)t++
+let o=e.slice(i,t),n=t
+for(;t<e.length&&/[\u{20}-\u{2F}]/u.test(e[t]);)t++
+t<e.length&&/[\u{40}-\u{7E}]/u.test(e[t])&&("m"===e[t]&&t===n&&/^[\d:;]*$/u.test(o)&&(yield{type:"sgr",value:o}),t++)}else if([144,152,157,158,159].includes(n)||27===o&&[80,88,93,94,95].includes(n)){let i=157===n||93===n
+for(;t<e.length;){if(156===e.charCodeAt(t)||i&&7===e.charCodeAt(t)){t++
+break}if(""===e[t]&&"\\"===e[t+1]){t+=2
+break}t++}}else if(27===o&&n>=32&&47>=n){for(;t<e.length&&/[\u{20}-\u{2F}]/u.test(e[t]);)t++
+t<e.length&&/[\u{30}-\u{7E}]/u.test(e[t])&&t++}}}function p(e){return[...f(e)].filter(e=>"text"===e.type).map(e=>e.value).join("")}var m=new TextEncoder,w=e=>l(e).replaceAll(" ","&#xA0;"),$=function*(e){let t
+for(let i of e.values().toArray().toSorted((e,t)=>e.column-t.column)){let e=JSON.stringify(i.style),o=/^[\u{20}-\u{7E}]+$/u.test(i.text)
+t&&o&&/^[\u{20}-\u{7E}]+$/u.test(t.text)&&t.key===e&&t.column+t.width===i.column?(t.text+=i.text,t.width+=i.width):(t&&(yield t),t={...i,key:e})}t&&(yield t)}
+import y from"string-width"
+class b{columns
+rows
+lines=new Map
+column=0
+occupied=new Map
+row=0
+style={foreground:void 0,background:void 0,bold:!1,dim:!1,italic:!1,underline:!1,strikethrough:!1,inverse:!1,hidden:!1}
+constructor(e,t){this.columns=e,this.rows=t}write(e){for(let t of f(e.toWellFormed())){if(this.row>=this.rows)break
+if("sgr"===t.type)this.style=g(t.value,this.style)
+else if("control"===t.type)this.control(t.value)
+else for(let{segment:e}of s.segment(t.value)){if(this.row>=this.rows)break
+this.paint(e)}}return this}control(e){if("\n"===e)this.nextLine()
+else if("\r"===e)this.column=0
+else if("\b"===e)this.column=Math.max(0,this.column-1)
+else if("\t"===e){let e=8-this.column%8
+for(let t=0;e>t&&this.row<this.rows;t++)this.paint(" ")}}nextLine(){this.row++,this.column=0,this.occupied.clear()}paint(e){let t=y(e,{ambiguousIsNarrow:!0})
+if(0===t){let t=this.lines.get(this.row),i=this.occupied.get(this.column-1),o=void 0===i?void 0:t?.get(i)
+return void(o&&o.column+o.width===this.column&&(o.text+=e))}if(t>this.columns&&(e="�",t=1),this.column+t>this.columns&&this.nextLine(),this.row>=this.rows)return
+let i=this.lines.get(this.row)
+i||(i=new Map,this.lines.set(this.row,i))
+for(let e=this.column;e<this.column+t;e++){let t=this.occupied.get(e)
+if(void 0===t)continue
+let o=i.get(t)
+i.delete(t)
+for(let e=0;e<o.width;e++)this.occupied.delete(t+e)}let o={text:e,column:this.column,width:t,style:this.style}
+i.set(this.column,o)
+for(let e=0;t>e;e++)this.occupied.set(this.column+e,this.column)
+this.column+=t}}try{let{values:n,positionals:d}=i({allowPositionals:!0,options:{output:{type:"string",short:"o"},columns:{type:"string"},rows:{type:"string"},padding:{type:"string"},"cell-width":{type:"string"},"cell-height":{type:"string"},title:{type:"string"},icon:{type:"string"},grid:{type:"boolean"},help:{type:"boolean",short:"h"},version:{type:"boolean",short:"v"}}})
+if(n.help)process.stdout.write("vectorize-terminal — turn an ANSI transcript into an SVG\n\nUsage:\n  vectorize-terminal [input.txt|-] [options]\n  vectorize-terminal --title Build --rows 12 < build.log > build.svg\n\nInput defaults to stdin. Output defaults to stdout. No commands are executed.\n\nOptions:\n  -o, --output FILE    Write SVG to a file (or - for stdout)\n      --columns N     Terminal columns (default: 80)\n      --rows N        Visible rows (default: 24; excess content is clipped)\n      --padding N     Body padding (default: 30)\n      --cell-width N  Cell width (default: 45)\n      --cell-height N Cell height (default: 100)\n      --title TEXT    Enable Windows Terminal decoration with this tab title\n      --icon FILE     Read a self-contained SVG tab icon; also enables decoration\n      --grid          Show the alignment grid\n  -h, --help          Show this help\n  -v, --version       Show the package version\n")
+else if(n.version)process.stdout.write("0.1.0\n")
+else{if(d.length>1)throw Error("Expected at most one input file")
+let i=d[0]??"-"
+if("-"===i&&process.stdin.isTTY)throw Error("Supply an input file or pipe a transcript to stdin. Use --help for usage.")
+let a={content:e("-"===i?0:i,"utf8")}
+for(let[e,t]of[["columns","columns"],["rows","rows"],["padding","padding"],["cell-width","cellWidth"],["cell-height","cellHeight"]]){let i=n[e]
+if(void 0!==i){if(""===i.trim())throw Error(`--${e} needs a number`)
+a[t]=Number(i)}}n.grid&&(a.grid=!0),void 0===n.title&&void 0===n.icon||(a.decoration={type:"windowsTerminal",tabTitle:n.title??"Terminal",...void 0===n.icon?{}:{tabIcon:e(n.icon,"utf8")}})
+let c=function(e={}){let t=(e=>{if("string"==typeof e)return{content:e}
+if("object"!=typeof e||null===e||Array.isArray(e))throw TypeError("Expected terminal content or an options object.")
+let t=e
+if(void 0!==t.content&&"string"!=typeof t.content)throw TypeError("content must be a string.")
+for(let e of["columns","rows","padding","cellWidth","cellHeight"])if(void 0!==t[e]&&"number"!=typeof t[e])throw TypeError(`${e} must be a number.`)
+let i=t.debug
+if(void 0!==i&&("object"!=typeof i||null===i||Array.isArray(i)))throw TypeError("debug must be an object.")
+for(let[e,o]of[["grid",t.grid],["debug.grid",i?.grid]])if(void 0!==o&&"boolean"!=typeof o)throw TypeError(`${e} must be a boolean.`)
+return void 0!==t.decoration&&function(e){if("object"!=typeof e||null===e||!("type"in e)||"windowsTerminal"!==e.type)throw TypeError("decoration.type must be “windowsTerminal”.")
+if(!("tabTitle"in e)||"string"!=typeof e.tabTitle)throw TypeError("decoration.tabTitle must be a string.")
+if("tabIcon"in e&&void 0!==e.tabIcon&&("string"!=typeof e.tabIcon||!/^\s*(?:<\?xml[^?]*\?>\s*)?<svg[\s>]/u.test(e.tabIcon)))throw TypeError("decoration.tabIcon must be a complete SVG document, not a URL.")}(t.decoration),t})(e),i=function(e){let t=e.columns??80,i=e.rows??24,o=e.padding??30,n=e.cellWidth??45,r=e.cellHeight??100
+for(let[e,o]of Object.entries({columns:t,rows:i}))if(!Number.isSafeInteger(o)||0>=o)throw RangeError(`${e} must be a positive safe integer.`)
+for(let[e,t]of Object.entries({padding:o,cellWidth:n,cellHeight:r}))if("number"!=typeof t||!Number.isFinite(t)||("padding"===e?0>t:0>=t))throw RangeError(`${e} must be a finite ${"padding"===e?"nonnegative":"positive"} number.`)
+if(n/45==0||.035*r==0)throw RangeError("Cell dimensions are too small to represent.")
+let l=e.decoration?2*r:0,s=t*n,h=i*r,d=s+2*o,a=h+2*o+l
+if(![d,a].every(e=>Number.isFinite(e)&&e<=Number.MAX_SAFE_INTEGER))throw RangeError("The resulting SVG dimensions exceed the safe numeric range.")
+return{columns:t,rows:i,padding:o,cellWidth:n,cellHeight:r,width:d,height:a,headerHeight:l,contentWidth:s,contentHeight:h}}(t),n=t.debug?.grid??t.grid??!1
+if(n&&i.columns+i.rows>1e5)throw RangeError("A debug grid may contain at most 100 000 rows and columns combined.")
+let d=new b(i.columns,i.rows)
+return d.write(t.content??""),`<svg xmlns="http://www.w3.org/2000/svg" width="${h(i.width)}" height="${h(i.height)}" viewBox="0 0 ${h(i.width)} ${h(i.height)}" role="img" aria-label="Terminal screenshot">\n<title>Terminal screenshot</title>\n<rect width="${h(i.width)}" height="${h(i.height)}" fill="${o}"/>\n${t.decoration?`${function(e,t){let i=Math.min(t.headerHeight/39,t.width/360),o=t.width/i,n=t.headerHeight/i-39
+if(0>=i||!Number.isFinite(o)||!Number.isFinite(n))throw RangeError("Decoration geometry exceeds the representable numeric range.")
+let r=Math.min(247,o-205),d=r-90,a=Math.max(1,Math.floor(d/7)),c=[...s.segment(p(e.tabTitle))].map(e=>e.segment),u=c.length>a?`${c.slice(0,a-1).join("")}…`:c.join(""),g=void 0===e.tabIcon?'<g transform="translate(16 13)"><path d="M1 1h5l2 2h7a1 1 0 0 1 1 1v10H0V2a1 1 0 0 1 1-1" fill="#d89e13"/><path d="M0 5h16l-1 9H0Z" fill="#fcd53f"/></g>':`<image x="16" y="12" width="16" height="16" preserveAspectRatio="xMidYMid meet" href="data:image/svg+xml;base64,${(e=>btoa(Array.from(m.encode(e),e=>String.fromCodePoint(e)).join("")))(e.tabIcon)}"/>`
+return`<svg width="${h(t.width)}" height="${h(t.headerHeight)}" viewBox="0 0 ${h(t.width)} ${h(t.headerHeight)}" overflow="hidden" data-decoration="windowsTerminal">\n<rect width="${h(t.width)}" height="${h(t.headerHeight)}" fill="#2e2e2e"/>\n<g transform="scale(${h(i)}) translate(0 ${h(n)})">\n<path d="M0 39H${h(o)}" stroke="#292929"/>\n<path d="M0 39H2Q7 39 7 34V15Q7 7 15 7H${h(r-8)}Q${h(r)} 7 ${h(r)} 15V34Q${h(r)} 39 ${h(r+7)} 39Z" fill="#000000"/>\n${g}\n<svg x="40" y="7" width="${h(d)}" height="30" viewBox="0 0 ${h(d)} 30" overflow="hidden"><text x="0" y="19" fill="#ffffff" font-family="Segoe UI, sans-serif" font-size="12">${l(u)}</text></svg>\n<g fill="none" stroke-linecap="round" stroke-linejoin="round">\n<path d="M${h(r-26)} 17l6 6m0-6-6 6" stroke="#a0a0a0"/>\n<path d="M${h(r+18)} 20h8m-4-4v8" stroke="#cccccc"/>\n<path d="M${h(r+37)} 12v16" stroke="#454545"/>\n<path d="M${h(r+46)} 18l4 4 4-4" stroke="#cccccc"/>\n<g stroke="#ffffff">\n<path d="M${h(o-119)} 20h10"/>\n<rect x="${h(o-73)}" y="15" width="9" height="9"/>\n<path d="M${h(o-27)} 15l10 10m0-10-10 10"/>\n</g></g></g></svg>`}(t.decoration,i)}\n`:""}${function(e,t){let i=[],n=[],{cellWidth:l,cellHeight:s,padding:d,headerHeight:a}=t
+for(let[t,c]of e)for(let e of $(c)){let c=d+e.column*l,u=a+d+t*s,g=e.width*l,[f,p]=r(e.style)
+if(p!==o&&i.push(`<rect x="${h(c)}" y="${h(u)}" width="${h(g)}" height="${h(s)}" fill="${p}"/>`),e.style.hidden)continue
+let m=e.style.dim?' opacity="0.5"':""
+""!==e.text.trim()&&n.push(`<text x="${h(c)}" y="${h(u+.76*s)}" textLength="${h(g)}" lengthAdjust="spacingAndGlyphs" fill="${f}"${e.style.bold?' font-weight="700"':""}${e.style.italic?' font-style="italic"':""}${m}>${w(e.text)}</text>`)
+for(let[t,i,o]of[[e.style.underline,.89,"underline"],[e.style.strikethrough,.49,"strikethrough"]])t&&n.push(`<path data-text-decoration="${o}" d="M${h(c)} ${h(u+s*i)}h${h(g)}" stroke="${f}" stroke-width="${h(.035*s)}"${m}/>`)}return`<svg x="${h(d)}" y="${h(a+d)}" width="${h(t.contentWidth)}" height="${h(t.contentHeight)}" viewBox="${h(d)} ${h(a+d)} ${h(t.contentWidth)} ${h(t.contentHeight)}" overflow="hidden" data-terminal="true">\n<g data-layer="backgrounds">${i.join("")}</g>\n<g data-layer="text" font-family="JetBrains Mono, monospace" font-size="${h(.75*s)}" font-weight="400" font-variant-ligatures="none" style="font-feature-settings: 'liga' 0, 'calt' 0; white-space: pre" xml:space="preserve">${n.join("")}</g>\n</svg>`}(d.lines,i)}${n?`\n${function(e){let{padding:t,headerHeight:i,cellWidth:o,cellHeight:n,columns:r,rows:l,contentWidth:s,contentHeight:d}=e,a=[]
+for(let n=0;r>=n;n++)a.push(`M${h(t+n*o)} ${h(i)}v${h(e.height-i)}`)
+for(let o=0;l>=o;o++)a.push(`M0 ${h(i+t+o*n)}h${h(e.width)}`)
+return`<svg x="0" y="${h(i)}" width="${h(e.width)}" height="${h(e.height-i)}" viewBox="0 ${h(i)} ${h(e.width)} ${h(e.height-i)}" overflow="hidden" data-grid="true"><path d="${a.join("")}" fill="none" stroke="#ffffff" stroke-opacity="0.13" stroke-width="${h(Math.min(o,n)/45)}"/><rect x="${h(t)}" y="${h(i+t)}" width="${h(s)}" height="${h(d)}" fill="none" stroke="#61d6d6" stroke-opacity="0.35" stroke-width="${h(Math.min(o,n)/45)}"/></svg>`}(i)}`:""}\n</svg>\n`}(a)
+void 0===n.output||"-"===n.output?process.stdout.write(c):t(n.output,c,"utf8")}}catch(e){console.error(`vectorize-terminal: ${Error.isError(e)?e.message:String(e)}`),process.exitCode=1}

package/lib.d.ts

@@ -0,0 +1,35 @@
+/** Render a deterministic, standalone terminal SVG. This function performs no I/O. */
+export declare function vectorizeTerminal(input?: Options | string): string;
+export type Options = {
+	/** @default 100 */
+	cellHeight?: number;
+	/** @default 45 */
+	cellWidth?: number;
+	/** @default 80 */
+	columns?: number;
+	/** Plain text or ANSI-styled output. No shell commands are executed. */
+	content?: string;
+	debug?: {
+		grid?: boolean;
+	};
+	/** Omitted by default. Adds exactly two cell heights above the body. */
+	decoration?: WindowsTerminalDecoration;
+	/** Shorthand for debug.grid. An explicit debug.grid takes precedence. */
+	grid?: boolean;
+	/** Padding on each side of the terminal body, in SVG units. @default 30 */
+	padding?: number;
+	/** @default 24 */
+	rows?: number;
+};
+export type WindowsTerminalDecoration = {
+	/** A complete SVG document, embedded as an isolated image (not inline markup). */
+	tabIcon?: string;
+	tabTitle: string;
+	type: "windowsTerminal";
+};
+
+export {
+	vectorizeTerminal as default,
+};
+
+export {};

package/lib.js

@@ -0,0 +1,92 @@
+var e="#000000",t=()=>({foreground:void 0,background:void 0,bold:!1,dim:!1,italic:!1,underline:!1,strikethrough:!1,inverse:!1,hidden:!1})
+function i(e){let t=e.foreground??"#cccccc",i=e.background??"#000000"
+return e.inverse?[i,t]:[t,i]}function n(e){return e.toWellFormed().replaceAll(/[\u{0}-\u{8}\v\f\u{E}-\u{1F}\u{FFFE}\u{FFFF}]/gu,"�").replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&apos;")}var o=new Intl.Segmenter("en",{granularity:"grapheme"}),r=e=>String(Number(e.toPrecision(12))),l=["#0c0c0c","#c50f1f","#13a10e","#c19c00","#0037da","#881798","#3a96dd","#cccccc","#767676","#e74856","#16c60c","#f9f1a5","#3b78ff","#b4009e","#61d6d6","#f2f2f2"],s=e=>void 0!==e&&Number.isInteger(e)&&e>=0&&255>=e,h=e=>{if(3===e.length&&e.every(s))return`#${e.map(e=>e.toString(16).padStart(2,"0")).join("")}`}
+function d(e){if(!s(e))return
+if(16>e)return l[e]
+if(e>=232){let t=8+10*(e-232)
+return h([t,t,t])}let t=e-16,i=[0,95,135,175,215,255]
+return h([i[Math.floor(t/36)],i[Math.floor(t/6)%6],i[t%6]])}function a(e,i){let n={...i},o=e.split(";")
+for(let e=0;e<o.length;e++){let i=o[e].split(":"),r=Number(i[0]||0)
+if([38,48,58].includes(r)){let t
+if(i.length>1){let e=Number(i[1])
+if(5===e&&3===i.length&&""!==i[2]&&(t=d(Number(i[2]))),2===e){let e=[]
+6!==i.length||""!==i[2]&&"0"!==i[2]?5===i.length&&(e=i.slice(2)):e=i.slice(3),e.every(e=>""!==e)&&(t=h(e.map(Number)))}}else{let i=Number(o[++e]),n={5:1,2:3}[i]??0,r=o.slice(e+1,e+1+n)
+e+=n,r.length===n&&r.every(e=>/^\d+$/u.test(e))&&(5===i&&(t=d(Number(r[0]))),2===i&&(t=h(r.map(Number))))}t&&58!==r&&(n[38===r?"foreground":"background"]=t)
+continue}i.length>1&&4!==r||(0===r?n=t():1===r?n.bold=!0:2===r?n.dim=!0:3===r?n.italic=!0:4===r?n.underline="0"!==i[1]:7===r?n.inverse=!0:8===r?n.hidden=!0:9===r?n.strikethrough=!0:22===r?(n.bold=!1,n.dim=!1):23===r?n.italic=!1:24===r?n.underline=!1:27===r?n.inverse=!1:28===r?n.hidden=!1:29===r?n.strikethrough=!1:39===r?n.foreground=void 0:49===r?n.background=void 0:30>r||r>37?40>r||r>47?90>r||r>97?100>r||r>107||(n.background=l[r-100+8]):n.foreground=l[r-90+8]:n.background=l[r-40]:n.foreground=l[r-30])}return n}function*c(e){let t=0
+for(;t<e.length;){let i=t,n=e.charCodeAt(t)
+if(n>=32&&(127>n||n>159)){do{t++}while(t<e.length&&!/[\u{0}-\u{1F}\u{7F}-\u{9F}]/u.test(e[t]))
+yield{type:"text",value:e.slice(i,t)}
+continue}if(t++,[8,9,10,13].includes(n)){yield{type:"control",value:e[i]}
+continue}let o=n
+if(27===n){if(t===e.length)break
+o=e.charCodeAt(t++)}if(155===o||27===n&&91===o){let i=t
+for(;t<e.length&&/[\u{30}-\u{3F}]/u.test(e[t]);)t++
+let n=e.slice(i,t),o=t
+for(;t<e.length&&/[\u{20}-\u{2F}]/u.test(e[t]);)t++
+t<e.length&&/[\u{40}-\u{7E}]/u.test(e[t])&&("m"===e[t]&&t===o&&/^[\d:;]*$/u.test(n)&&(yield{type:"sgr",value:n}),t++)}else if([144,152,157,158,159].includes(o)||27===n&&[80,88,93,94,95].includes(o)){let i=157===o||93===o
+for(;t<e.length;){if(156===e.charCodeAt(t)||i&&7===e.charCodeAt(t)){t++
+break}if(""===e[t]&&"\\"===e[t+1]){t+=2
+break}t++}}else if(27===n&&o>=32&&47>=o){for(;t<e.length&&/[\u{20}-\u{2F}]/u.test(e[t]);)t++
+t<e.length&&/[\u{30}-\u{7E}]/u.test(e[t])&&t++}}}function u(e){return[...c(e)].filter(e=>"text"===e.type).map(e=>e.value).join("")}var f=new TextEncoder,g=e=>n(e).replaceAll(" ","&#xA0;"),m=function*(e){let t
+for(let i of e.values().toArray().toSorted((e,t)=>e.column-t.column)){let e=JSON.stringify(i.style),n=/^[\u{20}-\u{7E}]+$/u.test(i.text)
+t&&n&&/^[\u{20}-\u{7E}]+$/u.test(t.text)&&t.key===e&&t.column+t.width===i.column?(t.text+=i.text,t.width+=i.width):(t&&(yield t),t={...i,key:e})}t&&(yield t)}
+import p from"string-width"
+class w{columns
+rows
+lines=new Map
+column=0
+occupied=new Map
+row=0
+style={foreground:void 0,background:void 0,bold:!1,dim:!1,italic:!1,underline:!1,strikethrough:!1,inverse:!1,hidden:!1}
+constructor(e,t){this.columns=e,this.rows=t}write(e){for(let t of c(e.toWellFormed())){if(this.row>=this.rows)break
+if("sgr"===t.type)this.style=a(t.value,this.style)
+else if("control"===t.type)this.control(t.value)
+else for(let{segment:e}of o.segment(t.value)){if(this.row>=this.rows)break
+this.paint(e)}}return this}control(e){if("\n"===e)this.nextLine()
+else if("\r"===e)this.column=0
+else if("\b"===e)this.column=Math.max(0,this.column-1)
+else if("\t"===e){let e=8-this.column%8
+for(let t=0;e>t&&this.row<this.rows;t++)this.paint(" ")}}nextLine(){this.row++,this.column=0,this.occupied.clear()}paint(e){let t=p(e,{ambiguousIsNarrow:!0})
+if(0===t){let t=this.lines.get(this.row),i=this.occupied.get(this.column-1),n=void 0===i?void 0:t?.get(i)
+return void(n&&n.column+n.width===this.column&&(n.text+=e))}if(t>this.columns&&(e="�",t=1),this.column+t>this.columns&&this.nextLine(),this.row>=this.rows)return
+let i=this.lines.get(this.row)
+i||(i=new Map,this.lines.set(this.row,i))
+for(let e=this.column;e<this.column+t;e++){let t=this.occupied.get(e)
+if(void 0===t)continue
+let n=i.get(t)
+i.delete(t)
+for(let e=0;e<n.width;e++)this.occupied.delete(t+e)}let n={text:e,column:this.column,width:t,style:this.style}
+i.set(this.column,n)
+for(let e=0;t>e;e++)this.occupied.set(this.column+e,this.column)
+this.column+=t}}function $(t={}){let l=(e=>{if("string"==typeof e)return{content:e}
+if("object"!=typeof e||null===e||Array.isArray(e))throw TypeError("Expected terminal content or an options object.")
+let t=e
+if(void 0!==t.content&&"string"!=typeof t.content)throw TypeError("content must be a string.")
+for(let e of["columns","rows","padding","cellWidth","cellHeight"])if(void 0!==t[e]&&"number"!=typeof t[e])throw TypeError(`${e} must be a number.`)
+let i=t.debug
+if(void 0!==i&&("object"!=typeof i||null===i||Array.isArray(i)))throw TypeError("debug must be an object.")
+for(let[e,n]of[["grid",t.grid],["debug.grid",i?.grid]])if(void 0!==n&&"boolean"!=typeof n)throw TypeError(`${e} must be a boolean.`)
+return void 0!==t.decoration&&function(e){if("object"!=typeof e||null===e||!("type"in e)||"windowsTerminal"!==e.type)throw TypeError("decoration.type must be “windowsTerminal”.")
+if(!("tabTitle"in e)||"string"!=typeof e.tabTitle)throw TypeError("decoration.tabTitle must be a string.")
+if("tabIcon"in e&&void 0!==e.tabIcon&&("string"!=typeof e.tabIcon||!/^\s*(?:<\?xml[^?]*\?>\s*)?<svg[\s>]/u.test(e.tabIcon)))throw TypeError("decoration.tabIcon must be a complete SVG document, not a URL.")}(t.decoration),t})(t),s=function(e){let t=e.columns??80,i=e.rows??24,n=e.padding??30,o=e.cellWidth??45,r=e.cellHeight??100
+for(let[e,n]of Object.entries({columns:t,rows:i}))if(!Number.isSafeInteger(n)||0>=n)throw RangeError(`${e} must be a positive safe integer.`)
+for(let[e,t]of Object.entries({padding:n,cellWidth:o,cellHeight:r}))if("number"!=typeof t||!Number.isFinite(t)||("padding"===e?0>t:0>=t))throw RangeError(`${e} must be a finite ${"padding"===e?"nonnegative":"positive"} number.`)
+if(o/45==0||.035*r==0)throw RangeError("Cell dimensions are too small to represent.")
+let l=e.decoration?2*r:0,s=t*o,h=i*r,d=s+2*n,a=h+2*n+l
+if(![d,a].every(e=>Number.isFinite(e)&&e<=Number.MAX_SAFE_INTEGER))throw RangeError("The resulting SVG dimensions exceed the safe numeric range.")
+return{columns:t,rows:i,padding:n,cellWidth:o,cellHeight:r,width:d,height:a,headerHeight:l,contentWidth:s,contentHeight:h}}(l),h=l.debug?.grid??l.grid??!1
+if(h&&s.columns+s.rows>1e5)throw RangeError("A debug grid may contain at most 100 000 rows and columns combined.")
+let d=new w(s.columns,s.rows)
+return d.write(l.content??""),`<svg xmlns="http://www.w3.org/2000/svg" width="${r(s.width)}" height="${r(s.height)}" viewBox="0 0 ${r(s.width)} ${r(s.height)}" role="img" aria-label="Terminal screenshot">\n<title>Terminal screenshot</title>\n<rect width="${r(s.width)}" height="${r(s.height)}" fill="${e}"/>\n${l.decoration?`${function(e,t){let i=Math.min(t.headerHeight/39,t.width/360),l=t.width/i,s=t.headerHeight/i-39
+if(0>=i||!Number.isFinite(l)||!Number.isFinite(s))throw RangeError("Decoration geometry exceeds the representable numeric range.")
+let h=Math.min(247,l-205),d=h-90,a=Math.max(1,Math.floor(d/7)),c=[...o.segment(u(e.tabTitle))].map(e=>e.segment),g=c.length>a?`${c.slice(0,a-1).join("")}…`:c.join(""),m=void 0===e.tabIcon?'<g transform="translate(16 13)"><path d="M1 1h5l2 2h7a1 1 0 0 1 1 1v10H0V2a1 1 0 0 1 1-1" fill="#d89e13"/><path d="M0 5h16l-1 9H0Z" fill="#fcd53f"/></g>':`<image x="16" y="12" width="16" height="16" preserveAspectRatio="xMidYMid meet" href="data:image/svg+xml;base64,${(e=>btoa(Array.from(f.encode(e),e=>String.fromCodePoint(e)).join("")))(e.tabIcon)}"/>`
+return`<svg width="${r(t.width)}" height="${r(t.headerHeight)}" viewBox="0 0 ${r(t.width)} ${r(t.headerHeight)}" overflow="hidden" data-decoration="windowsTerminal">\n<rect width="${r(t.width)}" height="${r(t.headerHeight)}" fill="#2e2e2e"/>\n<g transform="scale(${r(i)}) translate(0 ${r(s)})">\n<path d="M0 39H${r(l)}" stroke="#292929"/>\n<path d="M0 39H2Q7 39 7 34V15Q7 7 15 7H${r(h-8)}Q${r(h)} 7 ${r(h)} 15V34Q${r(h)} 39 ${r(h+7)} 39Z" fill="#000000"/>\n${m}\n<svg x="40" y="7" width="${r(d)}" height="30" viewBox="0 0 ${r(d)} 30" overflow="hidden"><text x="0" y="19" fill="#ffffff" font-family="Segoe UI, sans-serif" font-size="12">${n(g)}</text></svg>\n<g fill="none" stroke-linecap="round" stroke-linejoin="round">\n<path d="M${r(h-26)} 17l6 6m0-6-6 6" stroke="#a0a0a0"/>\n<path d="M${r(h+18)} 20h8m-4-4v8" stroke="#cccccc"/>\n<path d="M${r(h+37)} 12v16" stroke="#454545"/>\n<path d="M${r(h+46)} 18l4 4 4-4" stroke="#cccccc"/>\n<g stroke="#ffffff">\n<path d="M${r(l-119)} 20h10"/>\n<rect x="${r(l-73)}" y="15" width="9" height="9"/>\n<path d="M${r(l-27)} 15l10 10m0-10-10 10"/>\n</g></g></g></svg>`}(l.decoration,s)}\n`:""}${function(t,n){let o=[],l=[],{cellWidth:s,cellHeight:h,padding:d,headerHeight:a}=n
+for(let[n,c]of t)for(let t of m(c)){let c=d+t.column*s,u=a+d+n*h,f=t.width*s,[m,p]=i(t.style)
+if(p!==e&&o.push(`<rect x="${r(c)}" y="${r(u)}" width="${r(f)}" height="${r(h)}" fill="${p}"/>`),t.style.hidden)continue
+let w=t.style.dim?' opacity="0.5"':""
+""!==t.text.trim()&&l.push(`<text x="${r(c)}" y="${r(u+.76*h)}" textLength="${r(f)}" lengthAdjust="spacingAndGlyphs" fill="${m}"${t.style.bold?' font-weight="700"':""}${t.style.italic?' font-style="italic"':""}${w}>${g(t.text)}</text>`)
+for(let[e,i,n]of[[t.style.underline,.89,"underline"],[t.style.strikethrough,.49,"strikethrough"]])e&&l.push(`<path data-text-decoration="${n}" d="M${r(c)} ${r(u+h*i)}h${r(f)}" stroke="${m}" stroke-width="${r(.035*h)}"${w}/>`)}return`<svg x="${r(d)}" y="${r(a+d)}" width="${r(n.contentWidth)}" height="${r(n.contentHeight)}" viewBox="${r(d)} ${r(a+d)} ${r(n.contentWidth)} ${r(n.contentHeight)}" overflow="hidden" data-terminal="true">\n<g data-layer="backgrounds">${o.join("")}</g>\n<g data-layer="text" font-family="JetBrains Mono, monospace" font-size="${r(.75*h)}" font-weight="400" font-variant-ligatures="none" style="font-feature-settings: 'liga' 0, 'calt' 0; white-space: pre" xml:space="preserve">${l.join("")}</g>\n</svg>`}(d.lines,s)}${h?`\n${function(e){let{padding:t,headerHeight:i,cellWidth:n,cellHeight:o,columns:l,rows:s,contentWidth:h,contentHeight:d}=e,a=[]
+for(let o=0;l>=o;o++)a.push(`M${r(t+o*n)} ${r(i)}v${r(e.height-i)}`)
+for(let n=0;s>=n;n++)a.push(`M0 ${r(i+t+n*o)}h${r(e.width)}`)
+return`<svg x="0" y="${r(i)}" width="${r(e.width)}" height="${r(e.height-i)}" viewBox="0 ${r(i)} ${r(e.width)} ${r(e.height-i)}" overflow="hidden" data-grid="true"><path d="${a.join("")}" fill="none" stroke="#ffffff" stroke-opacity="0.13" stroke-width="${r(Math.min(n,o)/45)}"/><rect x="${r(t)}" y="${r(i+t)}" width="${r(h)}" height="${r(d)}" fill="none" stroke="#61d6d6" stroke-opacity="0.35" stroke-width="${r(Math.min(n,o)/45)}"/></svg>`}(s)}`:""}\n</svg>\n`}var b=$
+export{b as default,$ as vectorizeTerminal}

package/package.json

@@ -1 +1 @@
-{"name":"vectorize-terminal","description":"returns `'vectorize-terminal'`","version":"0.0.1","type":"module","exports":{".":{"types":"./index.d.ts","import":"./index.js","default":"./index.js"}},"author":"Jaid <6216144+Jaid@users.noreply.github.com> (https://github.com/Jaid)","license":"MIT","repository":"github:Jaid/vectorize-terminal"}
+{"bugs":{"url":"https://github.com/Jaid/vectorize-terminal/issues"},"dependencies":{"string-width":"^8.2.2"},"description":"Renders ANSI terminal transcripts to SVG terminal screenshots","homepage":"https://github.com/Jaid/vectorize-terminal#readme","keywords":["ansi","cli","screenshot","svg","terminal","typescript"],"license":"MIT","name":"vectorize-terminal","repository":"github:Jaid/vectorize-terminal","version":"0.1.0","type":"module","exports":{".":{"types":"./lib.d.ts","import":"./lib.js","default":"./lib.js"}},"types":"./lib.d.ts","bin":{"vectorize-terminal":"./cli.js"}}

package/index.d.ts

@@ -1,6 +0,0 @@
-declare module 'vectorize-terminal' {
-  /**
-   * returns `'vectorize-terminal'`
-   */
-  export default () => string
-}

package/index.js

@@ -1 +0,0 @@
-export default () => 'vectorize-terminal'

package/readme.md

@@ -1 +0,0 @@
-# vectorize-terminal