kittyhtml 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Kukshtel
+
+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

@@ -0,0 +1,94 @@
+# kittyhtml
+
+Render HTML to an image and display it inline in a graphics-capable terminal (Kitty, WezTerm, Ghostty, iTerm2).
+
+This is **not** a headless browser. It's a thin CLI that pipes HTML through [DropFlow](https://github.com/chearon/dropflow) (a real CSS layout engine, no JS/no Chromium) to a PNG, then emits the Kitty graphics protocol or iTerm2 inline-image protocol on stdout.
+
+Built for AI agents that have something nice to show you — a styled report, a small table, a card — without taking over your screen with a browser.
+
+## Install
+
+```sh
+# from this directory, until published
+npm install
+npm link        # exposes the `kittyhtml` binary on your PATH
+```
+
+Requires Node 20+. Pulls in [`canvas`](https://www.npmjs.com/package/canvas) (native build) and `dropflow`.
+
+## Use
+
+```sh
+kittyhtml --demo                              # bundled demo page
+echo '<h1>hi</h1>' | kittyhtml --width 400
+kittyhtml report.html --scale 2 -o report.png # write PNG to file
+```
+
+### Options
+
+| flag | default | description |
+|---|---|---|
+| `--width N` | `800` | viewport width in CSS px |
+| `--height N` | *auto-fit* | fixed canvas height |
+| `--scale N` | `1` | pixel ratio (try `2` for retina-sharp text) |
+| `--background CSS` | — | fill canvas before painting, e.g. `#fff` |
+| `--format auto\|kitty\|iterm2` | `auto` | output protocol; auto-detect from `$TERM`/`$TERM_PROGRAM` |
+| `--out, -o PATH` | — | write PNG to file (use `-` for raw PNG on stdout) |
+| `--demo` | — | render the bundled demo page |
+
+### As a library
+
+```js
+import { renderHtml, encode } from 'kittyhtml';
+
+const png = await renderHtml('<h1>hello</h1>', { width: 400, scale: 2 });
+process.stdout.write(encode(png, 'kitty'));
+```
+
+## Releasing
+
+Releases publish via GitHub Actions using npm trusted publishing (OIDC, no long-lived token). To cut a release:
+
+```sh
+npm version patch    # or minor / major — bumps package.json and tags
+git push --follow-tags
+```
+
+The `Publish to npm` workflow fires on the `v*` tag, exchanges a GitHub OIDC token with npm for a one-shot publish token, and publishes with `--provenance` so each release carries a Sigstore attestation linking it back to the source commit.
+
+## CSS caveats
+
+DropFlow implements a serious subset of CSS but isn't a browser. Things to know when writing HTML for it (as of DropFlow 0.6.x):
+
+- Use the longhand `background-color`, not the `background` shorthand.
+- `max-width` / `min-width` aren't supported yet — use `width`.
+- `list-style` markers don't render; use `&bull;` or numbers inline.
+- `border-radius`, `box-shadow`, `transform`, and `position: absolute/fixed` aren't supported yet.
+- Body background doesn't propagate to the canvas — set the background on a wrapper element, or pass `--background <css>` to fill the canvas.
+
+See the [DropFlow README](https://github.com/chearon/dropflow#supported-css-rules) for the full support matrix.
+
+## Fonts
+
+First run fetches Noto fonts from a CDN via DropFlow's bundled `register-noto-fonts.js`. Subsequent renders reuse what was loaded. Bundled offline fonts are on the roadmap.
+
+## Claude Code skill
+
+A bundled skill lets Claude Code render output as a styled inline image when you ask for it as "kittyhtml" or "khtml":
+
+```sh
+mkdir -p ~/.claude/skills
+cp -r skill/kittyhtml ~/.claude/skills/kittyhtml
+```
+
+Then in any Claude Code session: *"give me this report as kittyhtml"* — the agent will generate DropFlow-compatible HTML and pipe it through this CLI. The skill is narrow on purpose; it only triggers on those keywords.
+
+## How agents should use it
+
+If you're an AI agent on a host with `kittyhtml` installed and the user is on a graphics-capable terminal, pipe your HTML through it instead of dumping markup as text:
+
+```sh
+echo "$HTML" | kittyhtml --width 700 --scale 2
+```
+
+The image is one frame in the scrollback — no popups, no new windows.

package/examples/demo.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html>
+<body style="font-family: 'Noto Sans', sans-serif; margin: 0; padding: 0; background-color: #f4f4f5; color: #18181b;">
+  <div style="background-color: #f4f4f5; padding: 32px 0;">
+  <div style="width: 720px; margin: 0 auto;">
+
+    <div style="background-color: #ffffff; border: 1px solid #e4e4e7; padding: 28px 32px;">
+      <div style="font-size: 11px; color: #71717a; font-weight: 700;">KITTYHTML &middot; DEMO</div>
+      <div style="font-size: 26px; font-weight: 700; padding-top: 6px;">HTML, in your terminal.</div>
+      <div style="font-size: 14px; color: #52525b; padding-top: 4px;">Rendered by DropFlow, displayed via the Kitty graphics protocol.</div>
+
+      <div style="padding-top: 18px; font-size: 14px; line-height: 1.6;">
+        No Chromium, no headless browser. Just CSS layout to a PNG, base64-streamed into your terminal as one inline image. Useful when an AI agent has something to show you that reads better as a page than as plain text.
+      </div>
+
+      <div style="font-size: 14px; font-weight: 700; padding-top: 22px; padding-bottom: 6px;">What this is good for</div>
+      <div style="font-size: 14px; line-height: 1.7; padding-left: 4px;">
+        <div>&bull;&nbsp;&nbsp;Inline reports, tables, and summaries from agents.</div>
+        <div>&bull;&nbsp;&nbsp;Quick previews of email or marketing copy.</div>
+        <div>&bull;&nbsp;&nbsp;Lightweight diagrams that compose better in HTML than in ASCII.</div>
+      </div>
+
+      <div style="margin-top: 20px; background-color: #18181b; color: #e4e4e7; padding: 14px 16px; font-family: 'Noto Sans Mono', monospace; font-size: 13px;">
+        $ echo '&lt;h1&gt;hi&lt;/h1&gt;' | kittyhtml
+      </div>
+
+      <div style="font-size: 12px; color: #71717a; padding-top: 18px;">
+        Tip: try <span style="font-family: 'Noto Sans Mono', monospace; color: #18181b;">--scale 2</span> for sharper text on high-DPI displays.
+      </div>
+    </div>
+
+  </div>
+  </div>
+</body>
+</html>

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "kittyhtml",
+  "version": "0.1.0",
+  "description": "Render HTML to an image and display it inline in Kitty/iTerm2-capable terminals. No browser — CSS layout via DropFlow.",
+  "type": "module",
+  "bin": {
+    "kittyhtml": "./src/cli.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./render": "./src/render.js",
+    "./protocols": "./src/protocols.js"
+  },
+  "files": [
+    "src",
+    "assets/fonts",
+    "skill",
+    "examples/demo.html",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "demo": "node src/cli.js --demo"
+  },
+  "dependencies": {
+    "canvas": "^2.11.2",
+    "dropflow": "^0.6.1"
+  },
+  "keywords": [
+    "kitty",
+    "iterm2",
+    "terminal",
+    "graphics",
+    "html",
+    "css",
+    "render",
+    "dropflow",
+    "image",
+    "cli",
+    "ai-agent",
+    "claude-code"
+  ],
+  "author": "Kyle Kukshtel <kyle.kukshtel@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkukshtel/kittyhtml.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kkukshtel/kittyhtml/issues"
+  },
+  "homepage": "https://github.com/kkukshtel/kittyhtml#readme"
+}

package/skill/kittyhtml/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: kittyhtml
+description: Render output as an inline terminal image using the `kittyhtml` CLI. ONLY use when the user explicitly asks for output as "kittyhtml" or "khtml" (e.g. "show me this as kittyhtml", "as khtml please", "render in kittyhtml"). Do NOT use for general HTML, web, or browser-related tasks.
+---
+
+# kittyhtml output format
+
+The user has asked for output as **kittyhtml** or **khtml** — they want the result rendered as a styled HTML page and displayed inline in their terminal as an image, via the `kittyhtml` CLI.
+
+## What to do
+
+1. **Verify the tool is installed**: `command -v kittyhtml` (one-time check per session). If missing, tell the user to run `npm install -g kittyhtml` and stop.
+
+2. **Generate HTML** that represents the content the user asked about — a styled page, card, table, summary, or whatever fits the request. Keep it focused; the rendered image should fit on one screen.
+
+3. **Pipe it through the CLI**:
+   ```sh
+   cat <<'HTML' | kittyhtml --width 700 --scale 2
+   <!DOCTYPE html>
+   <html><body>...</body></html>
+   HTML
+   ```
+
+   Use `--scale 2` for crisp text on retina/HiDPI. Use `--width 600`–`800` for content that should feel "page-sized." Use a smaller width (`--width 400`) for compact card-like output.
+
+4. After piping, write a one-line confirmation (e.g. "Rendered above."). The image is the deliverable; don't restate its contents in text.
+
+## CSS rules — DropFlow subset
+
+DropFlow is a real CSS layout engine but it's not a browser. Stick to this subset:
+
+- **Use `background-color`, NOT the `background` shorthand.** The shorthand is silently dropped.
+- **Use `width: Npx`, NOT `max-width`.** `max-width` / `min-width` aren't implemented.
+- **No `list-style` markers.** Don't use `<ul><li>` and expect bullets. Use `<div>&bull;&nbsp;&nbsp;item</div>` or numbered prefixes.
+- **No `border-radius`, `box-shadow`, `transform`, `position: absolute/fixed`.** Square corners only. Use `border: 1px solid #color;` for definition.
+- **`<body>` background does NOT propagate to the canvas.** Wrap content in an outer `<div style="background-color: #fff; padding: ...">` to fill the image.
+- **Only inline `style` attributes work** — no `<style>` blocks, no classes.
+- **Fonts available**: `Noto Sans` (default), `Noto Sans Mono` for code.
+
+## Template that's known to render well
+
+```html
+<!DOCTYPE html>
+<html>
+<body style="font-family: 'Noto Sans', sans-serif; margin: 0; padding: 0; color: #18181b;">
+  <div style="background-color: #f4f4f5; padding: 24px 0;">
+    <div style="width: 640px; margin: 0 auto;">
+      <div style="background-color: #ffffff; border: 1px solid #e4e4e7; padding: 24px 28px;">
+        <!-- content here -->
+      </div>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+## When NOT to use this skill
+
+- The user wants real HTML to save to a file or open in a browser → write HTML normally.
+- The user is asking how `kittyhtml` works → answer the question directly.
+- The user wants a screenshot of a real web page → this isn't a browser; suggest a headless-Chrome tool instead.
+- The user hasn't said "kittyhtml" or "khtml" → do not invoke; produce regular output.

package/src/cli.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { renderHtml } from './render.js';
+import { encode, detectTerminal } from './protocols.js';
+
+const HELP = `kittyhtml — render HTML to an image and display it inline in the terminal.
+
+USAGE
+  kittyhtml [FILE] [options]
+  cat page.html | kittyhtml [options]
+  kittyhtml --demo
+
+OPTIONS
+  --width N         Viewport width in CSS px (default 800).
+  --height N        Fixed canvas height; omit to auto-fit content.
+  --scale N         Pixel ratio for crisper output (default 1; try 2).
+  --background CSS  Fill canvas background before painting (e.g. "#fff").
+  --format FMT      Output protocol: auto | kitty | iterm2 (default auto).
+  --out, -o PATH    Write PNG to PATH instead of stdout. ("-" = stdout PNG)
+  --demo            Render a bundled demo page.
+  --help, -h        Show this help.
+
+EXAMPLES
+  kittyhtml --demo
+  echo '<h1>hi</h1>' | kittyhtml --width 400
+  kittyhtml report.html --scale 2 -o report.png
+`;
+
+function parseArgs(argv) {
+  const opts = {
+    width: 800,
+    height: null,
+    scale: 1,
+    background: null,
+    format: 'auto',
+    out: null,
+    demo: false,
+    file: null,
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[++i];
+      if (v === undefined) {
+        process.stderr.write(`kittyhtml: missing value for ${a}\n`);
+        process.exit(2);
+      }
+      return v;
+    };
+    switch (a) {
+      case '--demo': opts.demo = true; break;
+      case '--width': opts.width = Number(next()); break;
+      case '--height': opts.height = Number(next()); break;
+      case '--scale': opts.scale = Number(next()); break;
+      case '--background': case '--bg': opts.background = next(); break;
+      case '--format': opts.format = next(); break;
+      case '--out': case '-o': opts.out = next(); break;
+      case '--help': case '-h': process.stdout.write(HELP); process.exit(0);
+      default:
+        if (a.startsWith('-')) {
+          process.stderr.write(`kittyhtml: unknown option ${a}\n`);
+          process.exit(2);
+        }
+        positional.push(a);
+    }
+  }
+  if (positional.length > 1) {
+    process.stderr.write(`kittyhtml: too many positional arguments\n`);
+    process.exit(2);
+  }
+  if (positional[0]) opts.file = positional[0];
+  return opts;
+}
+
+function loadDemoHtml() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return readFileSync(join(here, '..', 'examples', 'demo.html'), 'utf8');
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  let html;
+  if (opts.demo) {
+    html = loadDemoHtml();
+  } else if (opts.file) {
+    html = readFileSync(opts.file, 'utf8');
+  } else if (!process.stdin.isTTY) {
+    html = readFileSync(0, 'utf8');
+  } else {
+    process.stdout.write(HELP);
+    process.exit(1);
+  }
+
+  const png = await renderHtml(html, opts);
+
+  if (opts.out) {
+    if (opts.out === '-') {
+      process.stdout.write(png);
+    } else {
+      writeFileSync(opts.out, png);
+      process.stderr.write(`kittyhtml: wrote ${opts.out} (${png.length} bytes)\n`);
+    }
+    return;
+  }
+
+  const encoded = encode(png, opts.format);
+  if (encoded == null) {
+    const term = process.env.TERM || '';
+    const tp = process.env.TERM_PROGRAM || '';
+    process.stderr.write(
+      `kittyhtml: no graphics-capable terminal detected (TERM=${term}, TERM_PROGRAM=${tp}).\n` +
+      `  Use --format kitty|iterm2 to force, or --out FILE to write a PNG.\n`,
+    );
+    process.exit(2);
+  }
+  process.stdout.write(encoded);
+}
+
+main().catch(err => {
+  process.stderr.write(`kittyhtml: ${err.stack || err.message}\n`);
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,2 @@
+export { renderHtml } from './render.js';
+export { encode, encodeKitty, encodeIterm2, detectTerminal } from './protocols.js';

package/src/protocols.js

@@ -0,0 +1,74 @@
+const ESC = '\x1b';
+const ST = '\x1b\\';
+const BEL = '\x07';
+
+/**
+ * Detect a terminal graphics protocol from the environment.
+ * Returns 'kitty' | 'iterm2' | null.
+ */
+export function detectTerminal(env = process.env) {
+  if (env.KITTY_WINDOW_ID || env.TERM === 'xterm-kitty') return 'kitty';
+  if (env.TERM_PROGRAM === 'WezTerm') return 'kitty';
+  if (env.TERM === 'xterm-ghostty' || env.TERM_PROGRAM === 'ghostty') return 'kitty';
+  if (env.TERM_PROGRAM === 'iTerm.app' || env.LC_TERMINAL === 'iTerm2') return 'iterm2';
+  return null;
+}
+
+/**
+ * Encode a PNG buffer for the Kitty graphics protocol.
+ * https://sw.kovidgoyal.net/kitty/graphics-protocol/
+ *
+ * The payload is base64-encoded and split into chunks of at most 4096 bytes.
+ * Only the first chunk carries the action/format keys; subsequent chunks carry
+ * only `m=1` (more) or `m=0` (last).
+ */
+export function encodeKitty(pngBuffer) {
+  const b64 = pngBuffer.toString('base64');
+  const chunkSize = 4096;
+
+  if (b64.length <= chunkSize) {
+    return `${ESC}_Ga=T,f=100;${b64}${ST}\n`;
+  }
+
+  let out = '';
+  let i = 0;
+  let first = true;
+  while (i < b64.length) {
+    const slice = b64.slice(i, i + chunkSize);
+    i += chunkSize;
+    const more = i < b64.length ? 1 : 0;
+    if (first) {
+      out += `${ESC}_Ga=T,f=100,m=${more};${slice}${ST}`;
+      first = false;
+    } else {
+      out += `${ESC}_Gm=${more};${slice}${ST}`;
+    }
+  }
+  return out + '\n';
+}
+
+/**
+ * Encode a PNG buffer for the iTerm2 inline image protocol.
+ * https://iterm2.com/documentation-images.html
+ */
+export function encodeIterm2(pngBuffer) {
+  const b64 = pngBuffer.toString('base64');
+  return `${ESC}]1337;File=inline=1;size=${pngBuffer.length}:${b64}${BEL}\n`;
+}
+
+/**
+ * Encode a PNG for the chosen format. 'auto' uses detectTerminal().
+ * Returns null if format is 'auto' and no graphics-capable terminal was detected.
+ */
+export function encode(pngBuffer, format = 'auto') {
+  let fmt = format;
+  if (fmt === 'auto') {
+    fmt = detectTerminal();
+    if (!fmt) return null;
+  }
+  switch (fmt) {
+    case 'kitty': return encodeKitty(pngBuffer);
+    case 'iterm2': return encodeIterm2(pngBuffer);
+    default: throw new Error(`Unknown terminal format: ${fmt}`);
+  }
+}

package/src/render.js

@@ -0,0 +1,64 @@
+import * as flow from 'dropflow';
+import parse from 'dropflow/parse.js';
+import { createCanvas } from 'canvas';
+
+const FONTS_DIR = new URL('../assets/fonts/', import.meta.url);
+const BUNDLED_FONTS = [
+  'NotoSans-Regular.ttf',
+  'NotoSans-Bold.ttf',
+  'NotoSans-Italic.ttf',
+  'NotoSans-BoldItalic.ttf',
+  'NotoSansMono-Regular.ttf',
+  'NotoSansMono-Bold.ttf',
+];
+
+let fontsReady = false;
+function ensureFonts() {
+  if (fontsReady) return;
+  for (const file of BUNDLED_FONTS) {
+    flow.fonts.add(flow.createFaceFromTablesSync(new URL(file, FONTS_DIR)));
+  }
+  fontsReady = true;
+}
+
+/**
+ * Render an HTML string to a PNG buffer using DropFlow.
+ *
+ * @param {string} html
+ * @param {object} [opts]
+ * @param {number} [opts.width=800]   Viewport width in CSS px before scaling.
+ * @param {number|null} [opts.height] Fixed canvas height; if null, auto-fit to content.
+ * @param {number} [opts.scale=1]     Pixel ratio (2 = retina-sharp).
+ * @param {string|null} [opts.background] Optional canvas background fill (CSS color).
+ * @returns {Promise<Buffer>} PNG image bytes.
+ */
+export async function renderHtml(html, opts = {}) {
+  const { width = 800, height = null, scale = 1, background = null } = opts;
+  ensureFonts();
+
+  const root = parse(html);
+  await flow.load(root);
+
+  const pxWidth = Math.max(1, Math.round(width * scale));
+  const layout = flow.generate(root);
+
+  let pxHeight;
+  if (height != null) {
+    pxHeight = Math.max(1, Math.round(height * scale));
+    flow.layout(layout, pxWidth, pxHeight);
+  } else {
+    flow.layout(layout, pxWidth, 1_000_000);
+    const measured = layout.getBorderArea().height;
+    pxHeight = Math.max(1, Math.ceil(measured));
+    flow.layout(layout, pxWidth, pxHeight);
+  }
+
+  const canvas = createCanvas(pxWidth, pxHeight);
+  const ctx = canvas.getContext('2d');
+  if (background) {
+    ctx.fillStyle = background;
+    ctx.fillRect(0, 0, pxWidth, pxHeight);
+  }
+  flow.paintToCanvas(layout, ctx);
+  return canvas.toBuffer('image/png');
+}