takumi-paint 0.0.0 → 0.1.1

package/README.md

@@ -1,3 +1,92 @@
+<div align="center">
+  <img src="https://takumi.kane.tw/logo.svg" alt="Takumi" width="64" />
+
 # takumi-paint
 
-The paint tree package for [Takumi](https://github.com/kane50613/takumi). Not released yet.
+**Lay out JSX, HTML, and CSS. Get back what to draw instead of pixels.**
+
+Every box, gradient, shadow, text run, and image, in paint order, with each CSS value resolved.
+
+[Documentation](https://takumi.kane.tw/docs/paint) · [Reference](https://takumi.kane.tw/docs/paint/reference)
+
+</div>
+
+## What it is for
+
+Takumi's other packages end in a PNG, an SVG, or a PDF. Use `takumi-paint` when you own the output:
+
+- Write slides where text stays editable, such as PPTX.
+- Draw onto Canvas, Skia, or a native drawing API.
+- Read where layout put each box and line of text.
+
+It runs the same layout as the image, SVG, and PDF renderers, in WebAssembly. Where they draw, it records the **paint tree**.
+
+## Install
+
+```bash
+npm install takumi-paint
+```
+
+## Quick start
+
+```tsx
+import { paint } from "takumi-paint";
+
+const tree = await paint(
+  <div id="card" style={{ width: 240, padding: 16, background: "#F7F3EC" }}>
+    Hello <b>world</b>
+  </div>,
+  { width: 320 },
+);
+```
+
+`tree.nodes` lists every node. Each node lists what it draws:
+
+```tsx
+const card = tree.nodes.find((node) => node.type === "box" && node.element?.id === "card");
+console.log(card?.drawables[0]); // { type: "fill", role: "background", shape: { type: "rect", … }, … }
+
+for (const node of tree.nodes) {
+  if (node.type !== "text") continue;
+  for (const run of node.runs) console.log(run.text, run.font.family, run.fontSize);
+}
+```
+
+`tree.steps` is the draw order. Replay it from the bottom up:
+
+```ts
+for (const step of tree.steps) {
+  if (step.type !== "draw") continue; // begin-group, end-group, begin-clip, and end-clip wrap draws
+  ctx.setTransform(...step.node.transform);
+  for (const drawable of step.drawables) draw(ctx, drawable);
+}
+```
+
+`paint()` also takes an HTML string or a Takumi node tree.
+
+## What the tree holds
+
+| Part      | Contents                                                                    |
+| --------- | --------------------------------------------------------------------------- |
+| Nodes     | `box`, `text`, and `image`, each placed on the canvas by its `transform`    |
+| Drawables | Fills, strokes, shadows, glyph runs, and images, tagged with their CSS role |
+| Paints    | Colors, gradients, images, and tiled patterns                               |
+| Text runs | Text, font, size, line height, and baseline, plus glyphs and outlines       |
+| Steps     | Draws, clips, and groups for opacity, blending, filters, and masks          |
+
+Lengths are device pixels.
+
+## Learn more
+
+| Need                           | Read                                                     |
+| ------------------------------ | -------------------------------------------------------- |
+| See the tree, step by step     | [Paint](https://takumi.kane.tw/docs/paint)               |
+| Draw nodes in order            | [Drawing](https://takumi.kane.tw/docs/paint/drawing)     |
+| Place text or lay it out again | [Text](https://takumi.kane.tw/docs/paint/text)           |
+| Check options and field types  | [Reference](https://takumi.kane.tw/docs/paint/reference) |
+
+## License
+
+MIT or Apache-2.0
+
+Bundled third-party code is listed in the [third-party notices](https://github.com/kane50613/takumi/blob/master/THIRD-PARTY-NOTICES.md).

package/bundlers/browser.mjs

@@ -0,0 +1,7 @@
+import * as wasm from "../dist/export.mjs";
+import url from "./wasm-url.mjs";
+
+wasm.initSync({ module: await fetch(url).then((response) => response.arrayBuffer()) });
+
+export * from "../dist/export.mjs";
+export default wasm.default;

package/bundlers/bun.mjs

@@ -0,0 +1,9 @@
+import * as wasm from "../dist/export.mjs";
+import wasmPath from "../pkg/takumi_paint_wasm_bg.wasm";
+
+const wasmBytes = await Bun.file(new URL(wasmPath, import.meta.url)).arrayBuffer();
+
+wasm.initSync({ module: wasmBytes });
+
+export * from "../dist/export.mjs";
+export default wasm.default;

package/bundlers/next.mjs

@@ -0,0 +1,11 @@
+import module from "../pkg/takumi_paint_wasm_bg.wasm?module";
+import * as wasm from "../dist/export.mjs";
+
+// typeof module says its Module { } but instanceof WebAssembly.Module is false
+// Have to force override the prototype to be WebAssembly.Module
+Object.setPrototypeOf(module, WebAssembly.Module.prototype);
+
+wasm.initSync({ module });
+
+export * from "../dist/export.mjs";
+export default wasm.default;

package/bundlers/node.cjs

@@ -0,0 +1,10 @@
+const wasm = require("../dist/export.cjs");
+const { readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const wasmPath = join(__dirname, "../pkg/takumi_paint_wasm_bg.wasm");
+const wasmBytes = readFileSync(wasmPath);
+
+wasm.initSync({ module: wasmBytes });
+
+module.exports = wasm;

package/bundlers/node.d.cts

@@ -0,0 +1,3 @@
+import * as paint from "../dist/export.mjs";
+
+export = paint;

package/bundlers/node.d.ts

@@ -0,0 +1,2 @@
+export * from "../dist/export.mjs";
+export { default } from "../dist/export.mjs";

package/bundlers/node.mjs

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+import * as wasm from "../dist/export.mjs";
+
+const wasmBytes = readFileSync(new URL("../pkg/takumi_paint_wasm_bg.wasm", import.meta.url));
+
+wasm.initSync({ module: wasmBytes });
+
+export * from "../dist/export.mjs";
+export default wasm.default;

package/bundlers/vite.mjs

@@ -0,0 +1,46 @@
+import url from "../pkg/takumi_paint_wasm_bg.wasm?url";
+import * as wasm from "../dist/export.mjs";
+
+// `?url` is a browser path; map it to a file for server reads. Vite emits the asset next to the
+// importing server chunk, so resolve relative to import.meta.url, not the framework output dir.
+async function resolveWasm() {
+  if (typeof process !== "undefined" && process.versions?.node != null) {
+    const { readFile } = process.getBuiltinModule("node:fs/promises");
+    const path = decodeURIComponent(url.replace(/[?#].*$/, ""));
+
+    // Dev SSR serves an `/@fs/<abs-path>` URL.
+    if (path.startsWith("/@fs/")) {
+      return readFile(path.slice("/@fs".length));
+    }
+
+    if (!path.startsWith("/")) {
+      return readFile(new URL(path, import.meta.url));
+    }
+
+    const basename = path.slice(path.lastIndexOf("/") + 1);
+    const candidates = [`./${basename}`, `.${path}`, `../client${path}`, `../../client${path}`];
+
+    let lastError;
+    for (const candidate of candidates) {
+      try {
+        return await readFile(new URL(candidate, import.meta.url));
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+          lastError = error;
+          continue;
+        }
+
+        throw error;
+      }
+    }
+
+    throw new Error(`Unable to locate Takumi WASM asset for SSR: ${url}`, { cause: lastError });
+  }
+
+  return fetch(new URL(url, import.meta.url)).then((response) => response.arrayBuffer());
+}
+
+wasm.initSync({ module: await resolveWasm() });
+
+export * from "../dist/export.mjs";
+export default wasm.default;

package/bundlers/wasm-url.cjs

@@ -0,0 +1,4 @@
+const { join } = require("node:path");
+const { pathToFileURL } = require("node:url");
+
+module.exports = pathToFileURL(join(__dirname, "../pkg/takumi_paint_wasm_bg.wasm"));

package/bundlers/wasm-url.d.cts

@@ -0,0 +1,3 @@
+declare const url: URL;
+
+export = url;

package/bundlers/wasm-url.d.ts

@@ -0,0 +1,3 @@
+declare const url: URL;
+
+export default url;

package/bundlers/wasm-url.mjs

@@ -0,0 +1 @@
+export default new URL("../pkg/takumi_paint_wasm_bg.wasm", import.meta.url);

package/bundlers/workerd.mjs

@@ -0,0 +1,7 @@
+import module from "../pkg/takumi_paint_wasm_bg.wasm";
+import * as wasm from "../dist/export.mjs";
+
+wasm.initSync({ module });
+
+export * from "../dist/export.mjs";
+export default wasm.default;