kittyhtml 0.2.0 → 0.3.0

package/README.md

@@ -2,19 +2,23 @@
 
 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.
+This is **not** a headless browser. It's a thin CLI that pipes HTML through [Blitz](https://github.com/DioxusLabs/blitz) — a Rust HTML/CSS engine (Stylo + Taffy + Parley + Vello) — to a PNG, then emits the Kitty graphics protocol or iTerm2 inline-image protocol on stdout. Headless CPU rasterization, no GPU required.
 
 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
+npm install -g kittyhtml
 ```
 
-Requires Node 20+. Pulls in [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas) (prebuilt native binary, no compile step) and `dropflow`.
+Or one-shot, no install:
+
+```sh
+npx kittyhtml --demo
+```
+
+Requires Node 20+. The native renderer ships as a prebuilt N-API binary per platform (macOS arm64, Linux x64). No Rust toolchain required at install time.
 
 ## Use
 
@@ -45,43 +49,24 @@ 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
 
-## 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.
+Blitz implements a serious subset of CSS — flexbox, grid, `border-radius`, `box-shadow`, web fonts, `<img>` tags, `background:` shorthand, `max-width`, native `<ul>` bullets, the things you'd expect. It's pre-alpha for general embedding but works well for our render-once use case. The full status matrix is at [the Blitz repo](https://github.com/DioxusLabs/blitz).
 
 ## 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.
+`Noto Sans` (regular, bold, italic, bold-italic) and `Noto Sans Mono` (regular, bold) are baked into the native binary as latin-subset TTFs. No system font dependency; renders identically across macOS and Linux. Reference them in HTML with `font-family: 'Noto Sans', sans-serif` and `font-family: 'Noto Sans Mono', monospace`.
 
 ## 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":
+A bundled skill lets Claude Code render output as a styled inline image when you ask for it as "kittyhtml" or "khtml". After a global install:
 
 ```sh
 mkdir -p ~/.claude/skills
-cp -r skill/kittyhtml ~/.claude/skills/kittyhtml
+cp -r "$(npm root -g)/kittyhtml/skill/kittyhtml" ~/.claude/skills/
 ```
 
-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.
+Then in any Claude Code session: *"give me this report as kittyhtml"* — the agent will generate HTML and pipe it through this CLI. The skill is narrow on purpose; it only triggers on those keywords.
 
 ## How agents should use it
 
@@ -92,3 +77,14 @@ echo "$HTML" | kittyhtml --width 700 --scale 2
 ```
 
 The image is one frame in the scrollback — no popups, no new windows.
+
+## Releasing
+
+Releases publish via GitHub Actions using npm trusted publishing (OIDC, no long-lived token). The native binary is cross-compiled per platform and published as `@kittyhtml/native-*` packages, then the umbrella `kittyhtml` package selects the right one at install time.
+
+```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, builds the native binaries on the matrix, and publishes everything with `--provenance`.

package/crates/renderer/index.cjs

@@ -0,0 +1,44 @@
+// Platform-specific loader for the kittyhtml native renderer.
+// Selects the right prebuilt .node file based on process.platform and process.arch.
+//
+// When packaged for npm, the .node files live in platform-specific subpackages
+// (npm/darwin-arm64, npm/linux-x64-gnu, etc.) and are resolved via optionalDependencies.
+// During local development, the build sits next to this file.
+
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+
+const platform = process.platform;
+const arch = process.arch;
+const libc = (() => {
+  if (platform !== 'linux') return '';
+  // Best-effort: assume gnu unless musl is hinted. CI builds will use named
+  // subpackages so this guess only matters during local dev on Linux.
+  try {
+    const { familySync, GLIBC, MUSL } = require('detect-libc');
+    const fam = familySync();
+    return fam === MUSL ? '-musl' : '-gnu';
+  } catch {
+    return '-gnu';
+  }
+})();
+
+const target = `${platform}-${arch}${libc}`;
+const localBinary = join(__dirname, `kittyhtml-native.${target}.node`);
+
+let mod;
+if (existsSync(localBinary)) {
+  mod = require(localBinary);
+} else {
+  try {
+    mod = require(`kittyhtml-${target}`);
+  } catch (err) {
+    throw new Error(
+      `kittyhtml: no prebuilt native binary for ${target}. ` +
+        `Tried ${localBinary} and the kittyhtml-${target} package. ` +
+        `If you're on an unsupported platform, please file an issue.`,
+    );
+  }
+}
+
+module.exports = mod;

package/examples/demo.html

@@ -1,35 +1,48 @@
 <!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;">
+<body style="font-family: 'Noto Sans', sans-serif; margin: 0; padding: 0; background: #f4f4f5; color: #18181b;">
+  <div style="max-width: 720px; margin: 0 auto; padding: 32px 24px;">
 
-    <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="background: #ffffff; border-radius: 16px; box-shadow: 0 1px 3px rgba(0,0,0,0.06); padding: 32px;">
+      <div style="font-size: 11px; color: #71717a; font-weight: 700; letter-spacing: 1.2px;">KITTYHTML &middot; v0.3</div>
+      <h1 style="font-size: 28px; margin: 6px 0 4px; font-weight: 700;">HTML, in your terminal.</h1>
+      <p style="margin: 0; font-size: 14px; color: #52525b;">Rendered by Blitz, displayed via the Kitty graphics protocol.</p>
 
-      <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>
+      <p style="font-size: 14px; line-height: 1.6; margin: 20px 0 0;">
+        No Chromium, no headless browser. Just a Rust + Vello renderer producing 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.
+      </p>
+
+      <h2 style="font-size: 15px; margin: 24px 0 8px;">What this is good for</h2>
+      <ul style="font-size: 14px; line-height: 1.7; margin: 0; padding-left: 22px;">
+        <li>Inline reports, tables, and summaries from agents.</li>
+        <li>Quick previews of email or marketing copy.</li>
+        <li>Lightweight diagrams that compose better in HTML than ASCII.</li>
+      </ul>
 
-      <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 style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 10px; margin-top: 22px;">
+        <div style="background: #dbeafe; border-radius: 8px; padding: 12px 14px; font-size: 13px;">
+          <div style="font-weight: 700; font-size: 11px; color: #1e40af; letter-spacing: 0.8px;">FLEXBOX</div>
+          <div style="margin-top: 2px;">supported</div>
+        </div>
+        <div style="background: #fef3c7; border-radius: 8px; padding: 12px 14px; font-size: 13px;">
+          <div style="font-weight: 700; font-size: 11px; color: #92400e; letter-spacing: 0.8px;">GRID</div>
+          <div style="margin-top: 2px;">supported</div>
+        </div>
+        <div style="background: #d1fae5; border-radius: 8px; padding: 12px 14px; font-size: 13px;">
+          <div style="font-weight: 700; font-size: 11px; color: #065f46; letter-spacing: 0.8px;">RADIUS</div>
+          <div style="margin-top: 2px;">supported</div>
+        </div>
       </div>
 
-      <div style="margin-top: 20px; background-color: #18181b; color: #e4e4e7; padding: 14px 16px; font-family: 'Noto Sans Mono', monospace; font-size: 13px;">
+      <div style="margin-top: 22px; background: #18181b; color: #e4e4e7; padding: 14px 18px; border-radius: 10px; 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;">
+      <p style="font-size: 12px; color: #71717a; margin: 18px 0 0;">
         Tip: try <span style="font-family: 'Noto Sans Mono', monospace; color: #18181b;">--scale 2</span> for sharper text on high-DPI displays.
-      </div>
+      </p>
     </div>
 
   </div>
-  </div>
 </body>
 </html>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kittyhtml",
-  "version": "0.2.0",
-  "description": "Render HTML to an image and display it inline in Kitty/iTerm2-capable terminals. No browser — CSS layout via DropFlow.",
+  "version": "0.3.0",
+  "description": "Render HTML to an image and display it inline in Kitty/iTerm2-capable terminals. No browser — Rust + Blitz layout, headless CPU rasterization.",
   "type": "module",
   "bin": {
     "kittyhtml": "./src/cli.js"
@@ -14,20 +14,24 @@
   },
   "files": [
     "src",
-    "assets/fonts",
+    "crates/renderer/index.cjs",
     "skill",
     "examples/demo.html",
-    "README.md"
+    "examples/demo.png",
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "demo": "node src/cli.js --demo"
+  "optionalDependencies": {
+    "kittyhtml-darwin-arm64": "0.3.0",
+    "kittyhtml-darwin-x64": "0.3.0",
+    "kittyhtml-linux-x64-gnu": "0.3.0"
   },
-  "dependencies": {
-    "@napi-rs/canvas": "^1.0.0",
-    "dropflow": "^0.6.1"
+  "scripts": {
+    "demo": "node src/cli.js --demo",
+    "build": "napi build --release --platform --manifest-path crates/renderer/Cargo.toml --package-json-path package.json --output-dir crates/renderer"
   },
   "keywords": [
     "kitty",
@@ -37,7 +41,8 @@
     "html",
     "css",
     "render",
-    "dropflow",
+    "blitz",
+    "vello",
     "image",
     "cli",
     "ai-agent",
@@ -52,5 +57,16 @@
   "bugs": {
     "url": "https://github.com/kkukshtel/kittyhtml/issues"
   },
-  "homepage": "https://github.com/kkukshtel/kittyhtml#readme"
+  "homepage": "https://github.com/kkukshtel/kittyhtml#readme",
+  "devDependencies": {
+    "@napi-rs/cli": "^3.6.2"
+  },
+  "napi": {
+    "binaryName": "kittyhtml-native",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu"
+    ]
+  }
 }

package/skill/kittyhtml/SKILL.md

@@ -9,9 +9,9 @@ The user has asked for output as **kittyhtml** or **khtml** — they want the re
 
 ## 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.
+1. **Verify the tool is installed**: `command -v kittyhtml`. If missing, tell the user `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.
+2. **Generate HTML** that represents the content the user asked about — a styled page, card, table, summary. Keep it focused; the rendered image should fit on one screen.
 
 3. **Pipe it through the CLI**:
    ```sh
@@ -21,33 +21,52 @@ The user has asked for output as **kittyhtml** or **khtml** — they want the re
    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.
+   Use `--scale 2` for crisp text on retina/HiDPI. Pick width based on shape:
+   - `--width 700`–`800` for full pages and reports
+   - `--width 500` for cards and summaries
+   - `--width 400` for compact, just-a-snippet 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
+## CSS — what works
 
-DropFlow is a real CSS layout engine but it's not a browser. Stick to this subset:
+kittyhtml v0.3+ uses Blitz (Stylo + Taffy + Parley + Vello). Most modern CSS works:
 
-- **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.
+- Flexbox (`display: flex`, `flex: 1`, `gap`, etc.)
+- CSS Grid (`display: grid`, `grid-template-columns`, etc.)
+- `border-radius`, `box-shadow`, `opacity`
+- `max-width`, `min-width`, `width`, `height`
+- `background:` shorthand (no need for `background-color` longhand)
+- Native `<ul>` / `<ol>` bullets
+- `<img>` tags (with absolute URLs; HTTPS works)
+- `position: relative` / `absolute`
+- Web fonts via `@font-face`
+
+Inline styles only — no `<style>` blocks, no `class` selectors are honored.
+
+## Fonts
+
+Two are baked in and reliable:
+- `'Noto Sans'` (regular, bold, italic, bold-italic)
+- `'Noto Sans Mono'` for code
+
+Use them as the canonical `font-family`:
+```css
+font-family: 'Noto Sans', sans-serif;
+font-family: 'Noto Sans Mono', monospace;
+```
+
+Other fonts will fall back to system defaults or fail to render predictably.
 
 ## 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>
+<body style="font-family: 'Noto Sans', sans-serif; margin: 0; padding: 0; background: #f4f4f5; color: #18181b;">
+  <div style="max-width: 720px; margin: 0 auto; padding: 32px 24px;">
+    <div style="background: #fff; border-radius: 12px; box-shadow: 0 1px 3px rgba(0,0,0,0.06); padding: 28px 32px;">
+      <!-- content here -->
     </div>
   </div>
 </body>

package/src/cli.js

@@ -80,6 +80,17 @@ function loadDemoHtml() {
   return readFileSync(join(here, '..', 'examples', 'demo.html'), 'utf8');
 }
 
+// readFileSync(0) crashes with EAGAIN when stdin is in non-blocking mode and
+// the upstream process hasn't flushed yet (common with `claude -p ... | kittyhtml`).
+// Async iteration over process.stdin yields back to the event loop and waits
+// for data, so it handles any pipe pacing correctly.
+async function readStdin() {
+  process.stdin.setEncoding('utf8');
+  let buf = '';
+  for await (const chunk of process.stdin) buf += chunk;
+  return buf;
+}
+
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
 
@@ -89,7 +100,7 @@ async function main() {
   } else if (opts.file) {
     html = readFileSync(opts.file, 'utf8');
   } else if (!process.stdin.isTTY) {
-    html = readFileSync(0, 'utf8');
+    html = await readStdin();
   } else {
     process.stdout.write(HELP);
     process.exit(1);

package/src/render.js

@@ -1,77 +1,30 @@
-import * as flow from 'dropflow';
-import parse from 'dropflow/parse.js';
-import { createCanvas, GlobalFonts, loadImage } from '@napi-rs/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 envReady = false;
-function ensureEnv() {
-  if (envReady) return;
-
-  // Tell DropFlow how to register a font and decode an image into the
-  // @napi-rs/canvas backend (default wiring in environment-node.js targets the
-  // legacy `canvas` package).
-  flow.environment.registerFont = face => {
-    const key = GlobalFonts.register(face.getBuffer(), face.uniqueFamily);
-    if (key) return () => GlobalFonts.remove(key);
-  };
-  flow.environment.createDecodedImage = async image => {
-    return await loadImage(Buffer.from(image.buffer));
-  };
-
-  for (const file of BUNDLED_FONTS) {
-    flow.fonts.add(flow.createFaceFromTablesSync(new URL(file, FONTS_DIR)));
-  }
-
-  envReady = true;
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+// Loaded lazily so importing this module doesn't pay the .node init cost
+// until someone actually renders.
+let _native = null;
+function native() {
+  if (_native == null) _native = require('../crates/renderer/index.cjs');
+  return _native;
 }
 
 /**
- * Render an HTML string to a PNG buffer using DropFlow.
+ * Render an HTML string to a PNG buffer via Blitz + Vello-CPU.
  *
  * @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;
-  ensureEnv();
-
-  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 await canvas.encode('png');
+  const { width = 800, height = null, scale = 1 } = opts;
+  const nativeOpts = {
+    width: Math.max(1, Math.round(width)),
+    scale: Math.max(0.01, scale),
+  };
+  if (height != null) nativeOpts.height = Math.max(1, Math.round(height));
+  return await native().renderHtml(html, nativeOpts);
 }