@shadow-garden/bapbong-painter-canvas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Le Phuoc Minh
+
+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,34 @@
+# @shadow-garden/bapbong-painter-canvas
+
+Paints a `ResolvedLayout` (from `@shadow-garden/bapbong-layout-engine`) onto
+HTML `<canvas>`. bapbong's core differentiator: the painter consumes
+pre-computed coordinates only — **it never measures text at paint time**.
+
+- **Scope:** `scope:painter`
+- **Depends on:** `@shadow-garden/bapbong-contracts`
+
+## What it does
+
+- **One `<canvas>` per page** (virtualized): only on-screen pages get a backing
+  store, sidestepping the browser's ~65535px max canvas dimension on long docs.
+- Draws text runs, images, tables (borders/shading), floats, footnotes, and
+  header/footer chrome; tints commented ranges (skipping resolved threads).
+- `pageToCanvas({ pageIndex, x, y })` maps page coords → container pixels for the
+  caret/selection overlay and comment anchors.
+
+```ts
+import { CanvasPainter } from '@shadow-garden/bapbong-painter-canvas';
+
+const painter = new CanvasPainter(container, { createCanvas });
+painter.paint(resolvedLayout, { zoom: 1, resolvedComments });
+painter.paintOverlay({ caret, selection }); // caret/selection, no relayout
+```
+
+Also: `PaintOptions`, `PainterDeps`.
+
+## Build / test
+
+```sh
+pnpm nx build @shadow-garden/bapbong-painter-canvas
+pnpm nx test  @shadow-garden/bapbong-painter-canvas
+```

package/dist/index.cjs

@@ -0,0 +1,550 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/painter-canvas/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CanvasPainter: () => CanvasPainter
+});
+module.exports = __toCommonJS(index_exports);
+
+// packages/painter-canvas/src/lib/painter-canvas.ts
+var VIEWPORT_MARGIN = 200;
+var POOL_LIMIT = 8;
+var DEFAULTS = {
+  zoom: 1,
+  pageGap: 24,
+  pageBackground: "#ffffff",
+  pageBorder: "#c8c8c8",
+  tableBorder: "#b0b0b0",
+  textColor: "#000000",
+  caretColor: "#1a1a1a",
+  selectionColor: "rgba(59, 130, 246, 0.30)",
+  decorations: []
+};
+var fontCss = (f) => `${f.italic ? "italic " : ""}${f.bold ? "700" : "400"} ${f.sizePt}pt ${f.family}`;
+var defaultDpr = () => typeof globalThis.devicePixelRatio === "number" ? Math.min(globalThis.devicePixelRatio, 2) : 1;
+var CanvasPainter = class {
+  constructor(container, deps = {}) {
+    this.container = container;
+    this.createCanvas = deps.createCanvas ?? (() => document.createElement("canvas"));
+  }
+  container;
+  createCanvas;
+  images = /* @__PURE__ */ new Map();
+  /** pageIndex → its mounted canvas; idle canvases wait in `pool`. */
+  mounted = /* @__PURE__ */ new Map();
+  pool = [];
+  /** The 2D context of the page currently being drawn (paint* read this). */
+  ctx;
+  lastLayout = null;
+  /** Last paint options, minus caret/selection (those live in lastOverlay). */
+  lastOptions = {};
+  lastOverlay = {
+    caret: null,
+    selection: []
+  };
+  lastFrame = null;
+  /** Top edge (layout px) of each page in the stacked document. */
+  pageY = [];
+  /** Pages currently showing caret/selection (so an overlay change can clear them). */
+  overlayPages = /* @__PURE__ */ new Set();
+  paint(layout, options = {}) {
+    this.lastLayout = layout;
+    const { caret, selection, ...rest } = options;
+    this.lastOptions = rest;
+    if (caret !== void 0 || selection !== void 0) {
+      this.lastOverlay = { caret: caret ?? null, selection: selection ?? [] };
+    }
+    const o = { ...DEFAULTS, ...rest };
+    const dpr = options.devicePixelRatio ?? defaultDpr();
+    this.lastFrame = { o, dpr };
+    const width = layout.pages.reduce((m, p) => Math.max(m, p.width), 0);
+    this.pageY = [];
+    let acc = 0;
+    for (const page of layout.pages) {
+      this.pageY.push(acc);
+      acc += page.height + o.pageGap;
+    }
+    const totalHeight = Math.max(0, acc - o.pageGap);
+    this.container.style.position ||= "relative";
+    this.container.style.width = `${Math.round(width * o.zoom)}px`;
+    this.container.style.height = `${Math.round(totalHeight * o.zoom)}px`;
+    const vp = options.viewport;
+    const vTop = vp ? vp.top / o.zoom - VIEWPORT_MARGIN : -Infinity;
+    const vBottom = vp ? (vp.top + vp.height) / o.zoom + VIEWPORT_MARGIN : Infinity;
+    const desired = /* @__PURE__ */ new Set();
+    layout.pages.forEach((page, i) => {
+      const top = this.pageY[i];
+      if (top + page.height >= vTop && top <= vBottom) desired.add(i);
+    });
+    for (const idx of [...this.mounted.keys()]) {
+      if (!desired.has(idx)) this.unmountPage(idx);
+    }
+    this.overlayPages = /* @__PURE__ */ new Set();
+    for (const i of desired) this.drawPage(i, o, dpr);
+    if (this.lastOverlay.caret) this.overlayPages.add(this.lastOverlay.caret.pageIndex);
+    for (const r of this.lastOverlay.selection) this.overlayPages.add(r.pageIndex);
+  }
+  /** Redraw just the pages whose caret/selection changed — the cheap path for
+   *  blink and drag (one page for a blink, a handful for a drag). */
+  paintOverlay(overlay = {}) {
+    this.lastOverlay = { caret: overlay.caret ?? null, selection: overlay.selection ?? [] };
+    const frame = this.lastFrame;
+    if (!frame || !this.lastLayout) return;
+    const next = /* @__PURE__ */ new Set();
+    if (this.lastOverlay.caret) next.add(this.lastOverlay.caret.pageIndex);
+    for (const r of this.lastOverlay.selection) next.add(r.pageIndex);
+    const affected = /* @__PURE__ */ new Set([...this.overlayPages, ...next]);
+    this.overlayPages = next;
+    for (const i of affected) {
+      if (this.mounted.has(i)) this.drawPage(i, frame.o, frame.dpr);
+    }
+  }
+  /** Mount (or reuse) page `i`'s canvas, size + position it, and draw it. */
+  drawPage(i, o, dpr) {
+    const page = this.lastLayout?.pages[i];
+    if (!page) return;
+    const slot = this.mountPage(i);
+    this.sizeCanvas(slot.canvas, page.width, page.height, o.zoom, dpr);
+    slot.canvas.style.top = `${Math.round(this.pageY[i] * o.zoom)}px`;
+    this.ctx = slot.ctx;
+    this.ctx.setTransform(o.zoom * dpr, 0, 0, o.zoom * dpr, 0, 0);
+    this.ctx.clearRect(0, 0, page.width, page.height);
+    this.ctx.textBaseline = "alphabetic";
+    const pageInfo = { page: page.index + 1, pages: this.lastLayout?.pages.length ?? 1 };
+    this.paintPage(page, 0, o, pageInfo);
+    for (const chrome of [this.chromeFor(i, "header"), this.chromeFor(i, "footer")]) {
+      if (!chrome) continue;
+      for (const line of chrome.lines) this.paintLine(line, 0, o, pageInfo);
+      for (const table of chrome.tables) this.paintTable(table, 0, o, pageInfo);
+      for (const f of chrome.floats ?? []) this.paintFloat(f, 0, o, pageInfo);
+    }
+  }
+  /** Pick the header/footer band for page `i`: the first variant on page 1 when
+   *  titlePg is set, the even variant on even pages when evenAndOdd is set, else
+   *  the default. A selected-but-absent variant means a blank band (no fallback
+   *  to the default — that's Word's behavior for title/even pages). */
+  chromeFor(i, kind) {
+    const L = this.lastLayout;
+    if (!L) return void 0;
+    const s = L.chromeSelect;
+    const pick = (def, first, even) => {
+      if (s?.titlePg && i === 0) return first;
+      if (s?.evenAndOdd && (i + 1) % 2 === 0) return even;
+      return def;
+    };
+    return kind === "header" ? pick(L.pageHeader, L.pageHeaderFirst, L.pageHeaderEven) : pick(L.pageFooter, L.pageFooterFirst, L.pageFooterEven);
+  }
+  /** Get page `i`'s slot, reusing a pooled canvas or creating one. */
+  mountPage(i) {
+    const existing = this.mounted.get(i);
+    if (existing) return existing;
+    let slot = this.pool.pop();
+    if (!slot) {
+      const canvas = this.createCanvas();
+      const ctx = canvas.getContext("2d");
+      if (!ctx) throw new Error("bapbong-painter-canvas: 2D canvas context unavailable");
+      canvas.style.position = "absolute";
+      canvas.style.left = "0";
+      canvas.style.display = "block";
+      canvas.style.pointerEvents = "none";
+      slot = { canvas, ctx };
+    }
+    this.container.appendChild(slot.canvas);
+    this.mounted.set(i, slot);
+    return slot;
+  }
+  /** Detach page `i`, freeing its backing store (kept in the pool for reuse). */
+  unmountPage(i) {
+    const slot = this.mounted.get(i);
+    if (!slot) return;
+    this.mounted.delete(i);
+    slot.canvas.width = 0;
+    slot.canvas.height = 0;
+    slot.canvas.parentNode?.removeChild(slot.canvas);
+    if (this.pool.length < POOL_LIMIT) this.pool.push(slot);
+  }
+  /** Only resize when needed: assigning width/height — even the same value —
+   *  clears and reallocates the backing store. */
+  sizeCanvas(c, width, height, zoom, dpr) {
+    const deviceW = Math.max(1, Math.round(width * zoom * dpr));
+    const deviceH = Math.max(1, Math.round(height * zoom * dpr));
+    if (c.width !== deviceW) c.width = deviceW;
+    if (c.height !== deviceH) c.height = deviceH;
+    c.style.width = `${Math.round(width * zoom)}px`;
+    c.style.height = `${Math.round(height * zoom)}px`;
+  }
+  paintPage(page, yOffset, o, pageInfo) {
+    const ctx = this.ctx;
+    ctx.fillStyle = o.pageBackground;
+    ctx.fillRect(0, yOffset, page.width, page.height);
+    ctx.strokeStyle = o.pageBorder;
+    ctx.lineWidth = 1;
+    ctx.strokeRect(0.5, yOffset + 0.5, page.width - 1, page.height - 1);
+    for (const f of page.floats ?? []) this.paintFloat(f, yOffset, o, pageInfo);
+    ctx.fillStyle = o.selectionColor;
+    for (const r of this.lastOverlay.selection) {
+      if (r.pageIndex === page.index) ctx.fillRect(r.x, yOffset + r.y, r.width, r.height);
+    }
+    for (const d of o.decorations) {
+      if (d.kind !== "background") continue;
+      ctx.fillStyle = d.color;
+      for (const r of d.rects) {
+        if (r.pageIndex === page.index) ctx.fillRect(r.x, yOffset + r.y, r.width, r.height);
+      }
+    }
+    for (const line of page.lines) this.paintLine(line, yOffset, o, pageInfo);
+    for (const table of page.tables ?? []) this.paintTable(table, yOffset, o, pageInfo);
+    for (const d of o.decorations) {
+      if (d.kind === "background") continue;
+      ctx.fillStyle = d.color;
+      for (const r of d.rects) {
+        if (r.pageIndex !== page.index) continue;
+        const thickness = Math.max(1, r.height * 0.06);
+        const y = d.kind === "underline" ? yOffset + r.y + r.height - thickness : yOffset + r.y + r.height / 2;
+        ctx.fillRect(r.x, y, r.width, thickness);
+      }
+    }
+    if (page.footnotes) {
+      const fn = page.footnotes;
+      const startX = fn.lines[0]?.x ?? 0;
+      const sepY = Math.round(yOffset + fn.separatorY) + 0.5;
+      ctx.strokeStyle = o.pageBorder;
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(startX, sepY);
+      ctx.lineTo(startX + Math.min(192, page.width * 0.3), sepY);
+      ctx.stroke();
+      for (const line of fn.lines) this.paintLine(line, yOffset, o, pageInfo);
+    }
+    const caret = this.lastOverlay.caret;
+    if (caret && caret.pageIndex === page.index) {
+      ctx.fillStyle = o.caretColor;
+      ctx.fillRect(caret.x, yOffset + caret.y, 1.5, caret.height);
+    }
+  }
+  /** Run `draw` rotated `deg` clockwise around the center of the given box —
+   *  the paint-only rotation of images/shapes (the layout box stays put). */
+  withRotation(deg, x, y, w, h, draw) {
+    if (!deg) {
+      draw();
+      return;
+    }
+    const ctx = this.ctx;
+    ctx.save();
+    ctx.translate(x + w / 2, y + h / 2);
+    ctx.rotate(deg * Math.PI / 180);
+    ctx.translate(-(x + w / 2), -(y + h / 2));
+    draw();
+    ctx.restore();
+  }
+  /** One anchored float: vector shape or bitmap, then any textbox text laid
+   *  out inside it (box-local lines — translate to the float's origin, and
+   *  clip to the box the way Word hides textbox overflow). */
+  paintFloat(f, yOffset, o, pageInfo) {
+    this.withRotation(f.rotation, f.x, yOffset + f.y, f.width, f.height, () => {
+      if (f.shape) {
+        this.drawShape(f.shape, f.x, yOffset + f.y, f.width, f.height);
+      } else {
+        const el = this.requestImage(f.src);
+        if (el?.complete && el.naturalWidth > 0) {
+          this.ctx.drawImage(el, f.x, yOffset + f.y, f.width, f.height);
+        }
+      }
+      if (f.lines && f.lines.length > 0) {
+        const ctx = this.ctx;
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(f.x, yOffset + f.y, f.width, f.height);
+        ctx.clip();
+        ctx.translate(f.x, yOffset + f.y);
+        for (const line of f.lines) this.paintLine(line, 0, o, pageInfo);
+        ctx.restore();
+      }
+    });
+  }
+  paintLine(line, yOffset, o, pageInfo) {
+    const ctx = this.ctx;
+    const baselineY = yOffset + line.y + line.baseline;
+    for (const seg of line.segments) {
+      if (seg.background && seg.width) {
+        ctx.fillStyle = seg.background;
+        ctx.fillRect(seg.x, yOffset + line.y, seg.width, line.height);
+      }
+    }
+    for (const seg of line.segments) {
+      ctx.font = fontCss(seg.font);
+      ctx.fillStyle = seg.color ?? o.textColor;
+      const text = seg.field && pageInfo ? String(seg.field === "pageNumber" ? pageInfo.page : pageInfo.pages) : seg.text;
+      const em = seg.font.sizePt * (96 / 72);
+      const segY = seg.vertAlign === "super" ? baselineY - em * 0.5 : seg.vertAlign === "sub" ? baselineY + em * 0.2 : baselineY;
+      ctx.fillText(text, seg.x, segY);
+      if ((seg.underline || seg.strike) && seg.width) {
+        const em2 = seg.font.sizePt * (96 / 72);
+        const thickness = Math.max(1, em2 * 0.05);
+        if (seg.underline) ctx.fillRect(seg.x, baselineY + Math.max(1, em2 * 0.1), seg.width, thickness);
+        if (seg.strike) ctx.fillRect(seg.x, baselineY - em2 * 0.27, seg.width, thickness);
+      }
+    }
+    for (const img of line.images ?? []) {
+      this.withRotation(img.rotation, img.x, baselineY - img.height, img.width, img.height, () => {
+        if (img.shape) {
+          this.drawShape(img.shape, img.x, baselineY - img.height, img.width, img.height);
+          return;
+        }
+        const el = this.requestImage(img.src);
+        if (el?.complete && el.naturalWidth > 0) {
+          ctx.drawImage(el, img.x, baselineY - img.height, img.width, img.height);
+        }
+      });
+    }
+  }
+  /** Vector shape in an image box, per ShapeSpec.kind. The path is built with
+   *  primitive calls (no Path2D) and filled then stroked; strokes stay inside
+   *  the box so thick outlines don't bleed into text. */
+  drawShape(s, x, y, w, h) {
+    const ctx = this.ctx;
+    const lw = s.strokeWidth || 1;
+    const fillStroke = () => {
+      if (s.fill) {
+        ctx.fillStyle = s.fill;
+        ctx.fill();
+      }
+      if (s.stroke) {
+        ctx.strokeStyle = s.stroke;
+        ctx.lineWidth = lw;
+        ctx.stroke();
+      }
+    };
+    switch (s.kind) {
+      case "rect": {
+        if (s.fill) {
+          ctx.fillStyle = s.fill;
+          ctx.fillRect(x, y, w, h);
+        }
+        if (s.stroke) {
+          ctx.strokeStyle = s.stroke;
+          ctx.lineWidth = lw;
+          ctx.strokeRect(x + lw / 2, y + lw / 2, Math.max(0, w - lw), Math.max(0, h - lw));
+        }
+        return;
+      }
+      case "line": {
+        if (!s.stroke) return;
+        ctx.strokeStyle = s.stroke;
+        ctx.lineWidth = lw;
+        ctx.beginPath();
+        if (s.flipV) {
+          ctx.moveTo(x, y + h);
+          ctx.lineTo(x + w, y);
+        } else {
+          ctx.moveTo(x, y);
+          ctx.lineTo(x + w, y + h);
+        }
+        ctx.stroke();
+        return;
+      }
+      case "ellipse": {
+        ctx.beginPath();
+        ctx.ellipse(x + w / 2, y + h / 2, Math.max(0, (w - lw) / 2), Math.max(0, (h - lw) / 2), 0, 0, Math.PI * 2);
+        fillStroke();
+        return;
+      }
+      case "roundRect": {
+        const r = Math.min(0.16667 * Math.min(w, h), w / 2, h / 2);
+        const [x0, y0, x1, y1] = [x + lw / 2, y + lw / 2, x + w - lw / 2, y + h - lw / 2];
+        ctx.beginPath();
+        ctx.moveTo(x0 + r, y0);
+        ctx.lineTo(x1 - r, y0);
+        ctx.quadraticCurveTo(x1, y0, x1, y0 + r);
+        ctx.lineTo(x1, y1 - r);
+        ctx.quadraticCurveTo(x1, y1, x1 - r, y1);
+        ctx.lineTo(x0 + r, y1);
+        ctx.quadraticCurveTo(x0, y1, x0, y1 - r);
+        ctx.lineTo(x0, y0 + r);
+        ctx.quadraticCurveTo(x0, y0, x0 + r, y0);
+        ctx.closePath();
+        fillStroke();
+        return;
+      }
+      case "rightArrow": {
+        const head = Math.min(0.5 * Math.min(w, h), w);
+        const hx = x + w - head;
+        ctx.beginPath();
+        ctx.moveTo(x, y + h / 4);
+        ctx.lineTo(hx, y + h / 4);
+        ctx.lineTo(hx, y);
+        ctx.lineTo(x + w, y + h / 2);
+        ctx.lineTo(hx, y + h);
+        ctx.lineTo(hx, y + 3 * h / 4);
+        ctx.lineTo(x, y + 3 * h / 4);
+        ctx.closePath();
+        fillStroke();
+        return;
+      }
+      case "horizontalScroll": {
+        const r = Math.min(0.125 * Math.min(w, h), w / 4);
+        ctx.beginPath();
+        ctx.rect(x + r, y + lw / 2, w - 2 * r, h - lw);
+        fillStroke();
+        for (const cx of [x + r, x + w - r]) {
+          ctx.beginPath();
+          ctx.ellipse(cx, y + h / 2, r, Math.max(0, (h - lw) / 2), 0, 0, Math.PI * 2);
+          fillStroke();
+        }
+        return;
+      }
+    }
+  }
+  paintTable(table, yOffset, o, pageInfo) {
+    const ctx = this.ctx;
+    for (const cell of table.cells) {
+      if (cell.background) {
+        ctx.fillStyle = cell.background;
+        ctx.fillRect(cell.x, yOffset + cell.y, cell.width, cell.height);
+      }
+    }
+    for (const cell of table.cells) {
+      const clip = cell.lines.some((l) => l.images?.some((im) => im.rotation));
+      if (clip) {
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(cell.x, yOffset + cell.y, cell.width, cell.height);
+        ctx.clip();
+      }
+      for (const line of cell.lines) this.paintLine(line, yOffset, o, pageInfo);
+      for (const nested of cell.tables ?? []) this.paintTable(nested, yOffset, o, pageInfo);
+      if (clip) ctx.restore();
+    }
+    const b = table.borders;
+    if (b || table.cells.some((c) => c.borders)) {
+      const eps = 0.5;
+      for (const cell of table.cells) {
+        const cb = cell.borders;
+        const x0 = cell.x + 0.5;
+        const x1 = cell.x + cell.width + 0.5;
+        const y0 = yOffset + cell.y + 0.5;
+        const y1 = yOffset + cell.y + cell.height + 0.5;
+        const topOuter = Math.abs(cell.y - table.y) < eps;
+        const bottomOuter = Math.abs(cell.y + cell.height - (table.y + table.height)) < eps;
+        const leftOuter = Math.abs(cell.x - table.x) < eps;
+        const rightOuter = Math.abs(cell.x + cell.width - (table.x + table.width)) < eps;
+        const top = cb?.top ?? (topOuter ? b?.top : b?.insideH);
+        const bottom = cb?.bottom ?? (bottomOuter ? b?.bottom : b?.insideH);
+        const left = cb?.left ?? (leftOuter ? b?.left : b?.insideV);
+        const right = cb?.right ?? (rightOuter ? b?.right : b?.insideV);
+        if (top) this.strokeBorder(top, x0, y0, x1, y0);
+        if (bottom) this.strokeBorder(bottom, x0, y1, x1, y1);
+        if (left) this.strokeBorder(left, x0, y0, x0, y1);
+        if (right) this.strokeBorder(right, x1, y0, x1, y1);
+      }
+      ctx.setLineDash([]);
+    }
+    for (const cell of table.cells) {
+      for (const f of cell.floats ?? []) this.paintFloat(f, yOffset, o, pageInfo);
+    }
+  }
+  /** Stroke one border edge with its width / style / colour. The edge is always
+   *  horizontal or vertical (table grid lines). */
+  strokeBorder(side, x1, y1, x2, y2) {
+    const ctx = this.ctx;
+    ctx.strokeStyle = side.color;
+    if (side.style === "double") {
+      ctx.setLineDash([]);
+      ctx.lineWidth = Math.max(0.75, side.width / 3);
+      const gap = Math.max(2, side.width) / 2;
+      const horiz = y1 === y2;
+      ctx.beginPath();
+      ctx.moveTo(x1 + (horiz ? 0 : -gap), y1 + (horiz ? -gap : 0));
+      ctx.lineTo(x2 + (horiz ? 0 : -gap), y2 + (horiz ? -gap : 0));
+      ctx.moveTo(x1 + (horiz ? 0 : gap), y1 + (horiz ? gap : 0));
+      ctx.lineTo(x2 + (horiz ? 0 : gap), y2 + (horiz ? gap : 0));
+      ctx.stroke();
+      return;
+    }
+    ctx.lineWidth = side.width;
+    ctx.setLineDash(
+      side.style === "dashed" ? [side.width * 3, side.width * 2] : side.style === "dotted" ? [side.width, side.width * 1.6] : []
+    );
+    ctx.beginPath();
+    ctx.moveTo(x1, y1);
+    ctx.lineTo(x2, y2);
+    ctx.stroke();
+  }
+  /** Container CSS-px point → page-local point. Points in the gap between pages
+   *  clamp to the nearer page edge; null before the first paint. */
+  canvasToPage(cssX, cssY) {
+    if (!this.lastLayout) return null;
+    const zoom = this.lastOptions.zoom ?? DEFAULTS.zoom;
+    const gap = this.lastOptions.pageGap ?? DEFAULTS.pageGap;
+    const x = cssX / zoom;
+    const y = cssY / zoom;
+    let yOffset = 0;
+    const pages = this.lastLayout.pages;
+    for (let i = 0; i < pages.length; i++) {
+      const page = pages[i];
+      const isLast = i === pages.length - 1;
+      const claim = page.height + (isLast ? Infinity : gap / 2);
+      if (y < yOffset + claim) {
+        return { pageIndex: i, x, y: Math.min(Math.max(y - yOffset, 0), page.height) };
+      }
+      yOffset += page.height + gap;
+    }
+    return null;
+  }
+  /** Page-local point → container CSS-px point; null before the first paint. */
+  pageToCanvas(point) {
+    if (!this.lastLayout) return null;
+    const zoom = this.lastOptions.zoom ?? DEFAULTS.zoom;
+    const gap = this.lastOptions.pageGap ?? DEFAULTS.pageGap;
+    let yOffset = 0;
+    for (let i = 0; i < point.pageIndex; i++) {
+      const page = this.lastLayout.pages[i];
+      if (!page) return null;
+      yOffset += page.height + gap;
+    }
+    return { x: point.x * zoom, y: (yOffset + point.y) * zoom };
+  }
+  /** Return the cached image for `src`, kicking off a load (and a repaint on
+   *  completion) the first time. Returns undefined where Image is unavailable
+   *  (SSR / tests) — the image is simply skipped. */
+  requestImage(src) {
+    const cached = this.images.get(src);
+    if (cached) return cached;
+    if (typeof Image === "undefined") return void 0;
+    const el = new Image();
+    el.onload = () => {
+      if (this.lastLayout) {
+        this.paint(this.lastLayout, {
+          ...this.lastOptions,
+          caret: this.lastOverlay.caret,
+          selection: this.lastOverlay.selection
+        });
+      }
+    };
+    el.src = src;
+    this.images.set(src, el);
+    return el;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CanvasPainter
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/painter-canvas.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,523 @@
+// packages/painter-canvas/src/lib/painter-canvas.ts
+var VIEWPORT_MARGIN = 200;
+var POOL_LIMIT = 8;
+var DEFAULTS = {
+  zoom: 1,
+  pageGap: 24,
+  pageBackground: "#ffffff",
+  pageBorder: "#c8c8c8",
+  tableBorder: "#b0b0b0",
+  textColor: "#000000",
+  caretColor: "#1a1a1a",
+  selectionColor: "rgba(59, 130, 246, 0.30)",
+  decorations: []
+};
+var fontCss = (f) => `${f.italic ? "italic " : ""}${f.bold ? "700" : "400"} ${f.sizePt}pt ${f.family}`;
+var defaultDpr = () => typeof globalThis.devicePixelRatio === "number" ? Math.min(globalThis.devicePixelRatio, 2) : 1;
+var CanvasPainter = class {
+  constructor(container, deps = {}) {
+    this.container = container;
+    this.createCanvas = deps.createCanvas ?? (() => document.createElement("canvas"));
+  }
+  container;
+  createCanvas;
+  images = /* @__PURE__ */ new Map();
+  /** pageIndex → its mounted canvas; idle canvases wait in `pool`. */
+  mounted = /* @__PURE__ */ new Map();
+  pool = [];
+  /** The 2D context of the page currently being drawn (paint* read this). */
+  ctx;
+  lastLayout = null;
+  /** Last paint options, minus caret/selection (those live in lastOverlay). */
+  lastOptions = {};
+  lastOverlay = {
+    caret: null,
+    selection: []
+  };
+  lastFrame = null;
+  /** Top edge (layout px) of each page in the stacked document. */
+  pageY = [];
+  /** Pages currently showing caret/selection (so an overlay change can clear them). */
+  overlayPages = /* @__PURE__ */ new Set();
+  paint(layout, options = {}) {
+    this.lastLayout = layout;
+    const { caret, selection, ...rest } = options;
+    this.lastOptions = rest;
+    if (caret !== void 0 || selection !== void 0) {
+      this.lastOverlay = { caret: caret ?? null, selection: selection ?? [] };
+    }
+    const o = { ...DEFAULTS, ...rest };
+    const dpr = options.devicePixelRatio ?? defaultDpr();
+    this.lastFrame = { o, dpr };
+    const width = layout.pages.reduce((m, p) => Math.max(m, p.width), 0);
+    this.pageY = [];
+    let acc = 0;
+    for (const page of layout.pages) {
+      this.pageY.push(acc);
+      acc += page.height + o.pageGap;
+    }
+    const totalHeight = Math.max(0, acc - o.pageGap);
+    this.container.style.position ||= "relative";
+    this.container.style.width = `${Math.round(width * o.zoom)}px`;
+    this.container.style.height = `${Math.round(totalHeight * o.zoom)}px`;
+    const vp = options.viewport;
+    const vTop = vp ? vp.top / o.zoom - VIEWPORT_MARGIN : -Infinity;
+    const vBottom = vp ? (vp.top + vp.height) / o.zoom + VIEWPORT_MARGIN : Infinity;
+    const desired = /* @__PURE__ */ new Set();
+    layout.pages.forEach((page, i) => {
+      const top = this.pageY[i];
+      if (top + page.height >= vTop && top <= vBottom) desired.add(i);
+    });
+    for (const idx of [...this.mounted.keys()]) {
+      if (!desired.has(idx)) this.unmountPage(idx);
+    }
+    this.overlayPages = /* @__PURE__ */ new Set();
+    for (const i of desired) this.drawPage(i, o, dpr);
+    if (this.lastOverlay.caret) this.overlayPages.add(this.lastOverlay.caret.pageIndex);
+    for (const r of this.lastOverlay.selection) this.overlayPages.add(r.pageIndex);
+  }
+  /** Redraw just the pages whose caret/selection changed — the cheap path for
+   *  blink and drag (one page for a blink, a handful for a drag). */
+  paintOverlay(overlay = {}) {
+    this.lastOverlay = { caret: overlay.caret ?? null, selection: overlay.selection ?? [] };
+    const frame = this.lastFrame;
+    if (!frame || !this.lastLayout) return;
+    const next = /* @__PURE__ */ new Set();
+    if (this.lastOverlay.caret) next.add(this.lastOverlay.caret.pageIndex);
+    for (const r of this.lastOverlay.selection) next.add(r.pageIndex);
+    const affected = /* @__PURE__ */ new Set([...this.overlayPages, ...next]);
+    this.overlayPages = next;
+    for (const i of affected) {
+      if (this.mounted.has(i)) this.drawPage(i, frame.o, frame.dpr);
+    }
+  }
+  /** Mount (or reuse) page `i`'s canvas, size + position it, and draw it. */
+  drawPage(i, o, dpr) {
+    const page = this.lastLayout?.pages[i];
+    if (!page) return;
+    const slot = this.mountPage(i);
+    this.sizeCanvas(slot.canvas, page.width, page.height, o.zoom, dpr);
+    slot.canvas.style.top = `${Math.round(this.pageY[i] * o.zoom)}px`;
+    this.ctx = slot.ctx;
+    this.ctx.setTransform(o.zoom * dpr, 0, 0, o.zoom * dpr, 0, 0);
+    this.ctx.clearRect(0, 0, page.width, page.height);
+    this.ctx.textBaseline = "alphabetic";
+    const pageInfo = { page: page.index + 1, pages: this.lastLayout?.pages.length ?? 1 };
+    this.paintPage(page, 0, o, pageInfo);
+    for (const chrome of [this.chromeFor(i, "header"), this.chromeFor(i, "footer")]) {
+      if (!chrome) continue;
+      for (const line of chrome.lines) this.paintLine(line, 0, o, pageInfo);
+      for (const table of chrome.tables) this.paintTable(table, 0, o, pageInfo);
+      for (const f of chrome.floats ?? []) this.paintFloat(f, 0, o, pageInfo);
+    }
+  }
+  /** Pick the header/footer band for page `i`: the first variant on page 1 when
+   *  titlePg is set, the even variant on even pages when evenAndOdd is set, else
+   *  the default. A selected-but-absent variant means a blank band (no fallback
+   *  to the default — that's Word's behavior for title/even pages). */
+  chromeFor(i, kind) {
+    const L = this.lastLayout;
+    if (!L) return void 0;
+    const s = L.chromeSelect;
+    const pick = (def, first, even) => {
+      if (s?.titlePg && i === 0) return first;
+      if (s?.evenAndOdd && (i + 1) % 2 === 0) return even;
+      return def;
+    };
+    return kind === "header" ? pick(L.pageHeader, L.pageHeaderFirst, L.pageHeaderEven) : pick(L.pageFooter, L.pageFooterFirst, L.pageFooterEven);
+  }
+  /** Get page `i`'s slot, reusing a pooled canvas or creating one. */
+  mountPage(i) {
+    const existing = this.mounted.get(i);
+    if (existing) return existing;
+    let slot = this.pool.pop();
+    if (!slot) {
+      const canvas = this.createCanvas();
+      const ctx = canvas.getContext("2d");
+      if (!ctx) throw new Error("bapbong-painter-canvas: 2D canvas context unavailable");
+      canvas.style.position = "absolute";
+      canvas.style.left = "0";
+      canvas.style.display = "block";
+      canvas.style.pointerEvents = "none";
+      slot = { canvas, ctx };
+    }
+    this.container.appendChild(slot.canvas);
+    this.mounted.set(i, slot);
+    return slot;
+  }
+  /** Detach page `i`, freeing its backing store (kept in the pool for reuse). */
+  unmountPage(i) {
+    const slot = this.mounted.get(i);
+    if (!slot) return;
+    this.mounted.delete(i);
+    slot.canvas.width = 0;
+    slot.canvas.height = 0;
+    slot.canvas.parentNode?.removeChild(slot.canvas);
+    if (this.pool.length < POOL_LIMIT) this.pool.push(slot);
+  }
+  /** Only resize when needed: assigning width/height — even the same value —
+   *  clears and reallocates the backing store. */
+  sizeCanvas(c, width, height, zoom, dpr) {
+    const deviceW = Math.max(1, Math.round(width * zoom * dpr));
+    const deviceH = Math.max(1, Math.round(height * zoom * dpr));
+    if (c.width !== deviceW) c.width = deviceW;
+    if (c.height !== deviceH) c.height = deviceH;
+    c.style.width = `${Math.round(width * zoom)}px`;
+    c.style.height = `${Math.round(height * zoom)}px`;
+  }
+  paintPage(page, yOffset, o, pageInfo) {
+    const ctx = this.ctx;
+    ctx.fillStyle = o.pageBackground;
+    ctx.fillRect(0, yOffset, page.width, page.height);
+    ctx.strokeStyle = o.pageBorder;
+    ctx.lineWidth = 1;
+    ctx.strokeRect(0.5, yOffset + 0.5, page.width - 1, page.height - 1);
+    for (const f of page.floats ?? []) this.paintFloat(f, yOffset, o, pageInfo);
+    ctx.fillStyle = o.selectionColor;
+    for (const r of this.lastOverlay.selection) {
+      if (r.pageIndex === page.index) ctx.fillRect(r.x, yOffset + r.y, r.width, r.height);
+    }
+    for (const d of o.decorations) {
+      if (d.kind !== "background") continue;
+      ctx.fillStyle = d.color;
+      for (const r of d.rects) {
+        if (r.pageIndex === page.index) ctx.fillRect(r.x, yOffset + r.y, r.width, r.height);
+      }
+    }
+    for (const line of page.lines) this.paintLine(line, yOffset, o, pageInfo);
+    for (const table of page.tables ?? []) this.paintTable(table, yOffset, o, pageInfo);
+    for (const d of o.decorations) {
+      if (d.kind === "background") continue;
+      ctx.fillStyle = d.color;
+      for (const r of d.rects) {
+        if (r.pageIndex !== page.index) continue;
+        const thickness = Math.max(1, r.height * 0.06);
+        const y = d.kind === "underline" ? yOffset + r.y + r.height - thickness : yOffset + r.y + r.height / 2;
+        ctx.fillRect(r.x, y, r.width, thickness);
+      }
+    }
+    if (page.footnotes) {
+      const fn = page.footnotes;
+      const startX = fn.lines[0]?.x ?? 0;
+      const sepY = Math.round(yOffset + fn.separatorY) + 0.5;
+      ctx.strokeStyle = o.pageBorder;
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(startX, sepY);
+      ctx.lineTo(startX + Math.min(192, page.width * 0.3), sepY);
+      ctx.stroke();
+      for (const line of fn.lines) this.paintLine(line, yOffset, o, pageInfo);
+    }
+    const caret = this.lastOverlay.caret;
+    if (caret && caret.pageIndex === page.index) {
+      ctx.fillStyle = o.caretColor;
+      ctx.fillRect(caret.x, yOffset + caret.y, 1.5, caret.height);
+    }
+  }
+  /** Run `draw` rotated `deg` clockwise around the center of the given box —
+   *  the paint-only rotation of images/shapes (the layout box stays put). */
+  withRotation(deg, x, y, w, h, draw) {
+    if (!deg) {
+      draw();
+      return;
+    }
+    const ctx = this.ctx;
+    ctx.save();
+    ctx.translate(x + w / 2, y + h / 2);
+    ctx.rotate(deg * Math.PI / 180);
+    ctx.translate(-(x + w / 2), -(y + h / 2));
+    draw();
+    ctx.restore();
+  }
+  /** One anchored float: vector shape or bitmap, then any textbox text laid
+   *  out inside it (box-local lines — translate to the float's origin, and
+   *  clip to the box the way Word hides textbox overflow). */
+  paintFloat(f, yOffset, o, pageInfo) {
+    this.withRotation(f.rotation, f.x, yOffset + f.y, f.width, f.height, () => {
+      if (f.shape) {
+        this.drawShape(f.shape, f.x, yOffset + f.y, f.width, f.height);
+      } else {
+        const el = this.requestImage(f.src);
+        if (el?.complete && el.naturalWidth > 0) {
+          this.ctx.drawImage(el, f.x, yOffset + f.y, f.width, f.height);
+        }
+      }
+      if (f.lines && f.lines.length > 0) {
+        const ctx = this.ctx;
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(f.x, yOffset + f.y, f.width, f.height);
+        ctx.clip();
+        ctx.translate(f.x, yOffset + f.y);
+        for (const line of f.lines) this.paintLine(line, 0, o, pageInfo);
+        ctx.restore();
+      }
+    });
+  }
+  paintLine(line, yOffset, o, pageInfo) {
+    const ctx = this.ctx;
+    const baselineY = yOffset + line.y + line.baseline;
+    for (const seg of line.segments) {
+      if (seg.background && seg.width) {
+        ctx.fillStyle = seg.background;
+        ctx.fillRect(seg.x, yOffset + line.y, seg.width, line.height);
+      }
+    }
+    for (const seg of line.segments) {
+      ctx.font = fontCss(seg.font);
+      ctx.fillStyle = seg.color ?? o.textColor;
+      const text = seg.field && pageInfo ? String(seg.field === "pageNumber" ? pageInfo.page : pageInfo.pages) : seg.text;
+      const em = seg.font.sizePt * (96 / 72);
+      const segY = seg.vertAlign === "super" ? baselineY - em * 0.5 : seg.vertAlign === "sub" ? baselineY + em * 0.2 : baselineY;
+      ctx.fillText(text, seg.x, segY);
+      if ((seg.underline || seg.strike) && seg.width) {
+        const em2 = seg.font.sizePt * (96 / 72);
+        const thickness = Math.max(1, em2 * 0.05);
+        if (seg.underline) ctx.fillRect(seg.x, baselineY + Math.max(1, em2 * 0.1), seg.width, thickness);
+        if (seg.strike) ctx.fillRect(seg.x, baselineY - em2 * 0.27, seg.width, thickness);
+      }
+    }
+    for (const img of line.images ?? []) {
+      this.withRotation(img.rotation, img.x, baselineY - img.height, img.width, img.height, () => {
+        if (img.shape) {
+          this.drawShape(img.shape, img.x, baselineY - img.height, img.width, img.height);
+          return;
+        }
+        const el = this.requestImage(img.src);
+        if (el?.complete && el.naturalWidth > 0) {
+          ctx.drawImage(el, img.x, baselineY - img.height, img.width, img.height);
+        }
+      });
+    }
+  }
+  /** Vector shape in an image box, per ShapeSpec.kind. The path is built with
+   *  primitive calls (no Path2D) and filled then stroked; strokes stay inside
+   *  the box so thick outlines don't bleed into text. */
+  drawShape(s, x, y, w, h) {
+    const ctx = this.ctx;
+    const lw = s.strokeWidth || 1;
+    const fillStroke = () => {
+      if (s.fill) {
+        ctx.fillStyle = s.fill;
+        ctx.fill();
+      }
+      if (s.stroke) {
+        ctx.strokeStyle = s.stroke;
+        ctx.lineWidth = lw;
+        ctx.stroke();
+      }
+    };
+    switch (s.kind) {
+      case "rect": {
+        if (s.fill) {
+          ctx.fillStyle = s.fill;
+          ctx.fillRect(x, y, w, h);
+        }
+        if (s.stroke) {
+          ctx.strokeStyle = s.stroke;
+          ctx.lineWidth = lw;
+          ctx.strokeRect(x + lw / 2, y + lw / 2, Math.max(0, w - lw), Math.max(0, h - lw));
+        }
+        return;
+      }
+      case "line": {
+        if (!s.stroke) return;
+        ctx.strokeStyle = s.stroke;
+        ctx.lineWidth = lw;
+        ctx.beginPath();
+        if (s.flipV) {
+          ctx.moveTo(x, y + h);
+          ctx.lineTo(x + w, y);
+        } else {
+          ctx.moveTo(x, y);
+          ctx.lineTo(x + w, y + h);
+        }
+        ctx.stroke();
+        return;
+      }
+      case "ellipse": {
+        ctx.beginPath();
+        ctx.ellipse(x + w / 2, y + h / 2, Math.max(0, (w - lw) / 2), Math.max(0, (h - lw) / 2), 0, 0, Math.PI * 2);
+        fillStroke();
+        return;
+      }
+      case "roundRect": {
+        const r = Math.min(0.16667 * Math.min(w, h), w / 2, h / 2);
+        const [x0, y0, x1, y1] = [x + lw / 2, y + lw / 2, x + w - lw / 2, y + h - lw / 2];
+        ctx.beginPath();
+        ctx.moveTo(x0 + r, y0);
+        ctx.lineTo(x1 - r, y0);
+        ctx.quadraticCurveTo(x1, y0, x1, y0 + r);
+        ctx.lineTo(x1, y1 - r);
+        ctx.quadraticCurveTo(x1, y1, x1 - r, y1);
+        ctx.lineTo(x0 + r, y1);
+        ctx.quadraticCurveTo(x0, y1, x0, y1 - r);
+        ctx.lineTo(x0, y0 + r);
+        ctx.quadraticCurveTo(x0, y0, x0 + r, y0);
+        ctx.closePath();
+        fillStroke();
+        return;
+      }
+      case "rightArrow": {
+        const head = Math.min(0.5 * Math.min(w, h), w);
+        const hx = x + w - head;
+        ctx.beginPath();
+        ctx.moveTo(x, y + h / 4);
+        ctx.lineTo(hx, y + h / 4);
+        ctx.lineTo(hx, y);
+        ctx.lineTo(x + w, y + h / 2);
+        ctx.lineTo(hx, y + h);
+        ctx.lineTo(hx, y + 3 * h / 4);
+        ctx.lineTo(x, y + 3 * h / 4);
+        ctx.closePath();
+        fillStroke();
+        return;
+      }
+      case "horizontalScroll": {
+        const r = Math.min(0.125 * Math.min(w, h), w / 4);
+        ctx.beginPath();
+        ctx.rect(x + r, y + lw / 2, w - 2 * r, h - lw);
+        fillStroke();
+        for (const cx of [x + r, x + w - r]) {
+          ctx.beginPath();
+          ctx.ellipse(cx, y + h / 2, r, Math.max(0, (h - lw) / 2), 0, 0, Math.PI * 2);
+          fillStroke();
+        }
+        return;
+      }
+    }
+  }
+  paintTable(table, yOffset, o, pageInfo) {
+    const ctx = this.ctx;
+    for (const cell of table.cells) {
+      if (cell.background) {
+        ctx.fillStyle = cell.background;
+        ctx.fillRect(cell.x, yOffset + cell.y, cell.width, cell.height);
+      }
+    }
+    for (const cell of table.cells) {
+      const clip = cell.lines.some((l) => l.images?.some((im) => im.rotation));
+      if (clip) {
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(cell.x, yOffset + cell.y, cell.width, cell.height);
+        ctx.clip();
+      }
+      for (const line of cell.lines) this.paintLine(line, yOffset, o, pageInfo);
+      for (const nested of cell.tables ?? []) this.paintTable(nested, yOffset, o, pageInfo);
+      if (clip) ctx.restore();
+    }
+    const b = table.borders;
+    if (b || table.cells.some((c) => c.borders)) {
+      const eps = 0.5;
+      for (const cell of table.cells) {
+        const cb = cell.borders;
+        const x0 = cell.x + 0.5;
+        const x1 = cell.x + cell.width + 0.5;
+        const y0 = yOffset + cell.y + 0.5;
+        const y1 = yOffset + cell.y + cell.height + 0.5;
+        const topOuter = Math.abs(cell.y - table.y) < eps;
+        const bottomOuter = Math.abs(cell.y + cell.height - (table.y + table.height)) < eps;
+        const leftOuter = Math.abs(cell.x - table.x) < eps;
+        const rightOuter = Math.abs(cell.x + cell.width - (table.x + table.width)) < eps;
+        const top = cb?.top ?? (topOuter ? b?.top : b?.insideH);
+        const bottom = cb?.bottom ?? (bottomOuter ? b?.bottom : b?.insideH);
+        const left = cb?.left ?? (leftOuter ? b?.left : b?.insideV);
+        const right = cb?.right ?? (rightOuter ? b?.right : b?.insideV);
+        if (top) this.strokeBorder(top, x0, y0, x1, y0);
+        if (bottom) this.strokeBorder(bottom, x0, y1, x1, y1);
+        if (left) this.strokeBorder(left, x0, y0, x0, y1);
+        if (right) this.strokeBorder(right, x1, y0, x1, y1);
+      }
+      ctx.setLineDash([]);
+    }
+    for (const cell of table.cells) {
+      for (const f of cell.floats ?? []) this.paintFloat(f, yOffset, o, pageInfo);
+    }
+  }
+  /** Stroke one border edge with its width / style / colour. The edge is always
+   *  horizontal or vertical (table grid lines). */
+  strokeBorder(side, x1, y1, x2, y2) {
+    const ctx = this.ctx;
+    ctx.strokeStyle = side.color;
+    if (side.style === "double") {
+      ctx.setLineDash([]);
+      ctx.lineWidth = Math.max(0.75, side.width / 3);
+      const gap = Math.max(2, side.width) / 2;
+      const horiz = y1 === y2;
+      ctx.beginPath();
+      ctx.moveTo(x1 + (horiz ? 0 : -gap), y1 + (horiz ? -gap : 0));
+      ctx.lineTo(x2 + (horiz ? 0 : -gap), y2 + (horiz ? -gap : 0));
+      ctx.moveTo(x1 + (horiz ? 0 : gap), y1 + (horiz ? gap : 0));
+      ctx.lineTo(x2 + (horiz ? 0 : gap), y2 + (horiz ? gap : 0));
+      ctx.stroke();
+      return;
+    }
+    ctx.lineWidth = side.width;
+    ctx.setLineDash(
+      side.style === "dashed" ? [side.width * 3, side.width * 2] : side.style === "dotted" ? [side.width, side.width * 1.6] : []
+    );
+    ctx.beginPath();
+    ctx.moveTo(x1, y1);
+    ctx.lineTo(x2, y2);
+    ctx.stroke();
+  }
+  /** Container CSS-px point → page-local point. Points in the gap between pages
+   *  clamp to the nearer page edge; null before the first paint. */
+  canvasToPage(cssX, cssY) {
+    if (!this.lastLayout) return null;
+    const zoom = this.lastOptions.zoom ?? DEFAULTS.zoom;
+    const gap = this.lastOptions.pageGap ?? DEFAULTS.pageGap;
+    const x = cssX / zoom;
+    const y = cssY / zoom;
+    let yOffset = 0;
+    const pages = this.lastLayout.pages;
+    for (let i = 0; i < pages.length; i++) {
+      const page = pages[i];
+      const isLast = i === pages.length - 1;
+      const claim = page.height + (isLast ? Infinity : gap / 2);
+      if (y < yOffset + claim) {
+        return { pageIndex: i, x, y: Math.min(Math.max(y - yOffset, 0), page.height) };
+      }
+      yOffset += page.height + gap;
+    }
+    return null;
+  }
+  /** Page-local point → container CSS-px point; null before the first paint. */
+  pageToCanvas(point) {
+    if (!this.lastLayout) return null;
+    const zoom = this.lastOptions.zoom ?? DEFAULTS.zoom;
+    const gap = this.lastOptions.pageGap ?? DEFAULTS.pageGap;
+    let yOffset = 0;
+    for (let i = 0; i < point.pageIndex; i++) {
+      const page = this.lastLayout.pages[i];
+      if (!page) return null;
+      yOffset += page.height + gap;
+    }
+    return { x: point.x * zoom, y: (yOffset + point.y) * zoom };
+  }
+  /** Return the cached image for `src`, kicking off a load (and a repaint on
+   *  completion) the first time. Returns undefined where Image is unavailable
+   *  (SSR / tests) — the image is simply skipped. */
+  requestImage(src) {
+    const cached = this.images.get(src);
+    if (cached) return cached;
+    if (typeof Image === "undefined") return void 0;
+    const el = new Image();
+    el.onload = () => {
+      if (this.lastLayout) {
+        this.paint(this.lastLayout, {
+          ...this.lastOptions,
+          caret: this.lastOverlay.caret,
+          selection: this.lastOverlay.selection
+        });
+      }
+    };
+    el.src = src;
+    this.images.set(src, el);
+    return el;
+  }
+};
+export {
+  CanvasPainter
+};

package/dist/lib/painter-canvas.d.ts

@@ -0,0 +1,119 @@
+import type { CaretRect, PagePoint, PaintDecoration, ResolvedLayout, SelectionRect } from '@shadow-garden/bapbong-contracts';
+export interface PaintOptions {
+    /** Zoom factor (1 = 100%). */
+    zoom?: number;
+    /** Vertical gap between pages, in layout px. */
+    pageGap?: number;
+    /** Device pixel ratio override. Defaults to `window.devicePixelRatio`, capped at 2. */
+    devicePixelRatio?: number;
+    pageBackground?: string;
+    pageBorder?: string;
+    tableBorder?: string;
+    /** Fallback text color for segments without an explicit color. */
+    textColor?: string;
+    /** Caret to draw (page-local coords), e.g. from bapbong-selection. */
+    caret?: CaretRect | null;
+    /** Selection highlight rects (page-local coords), drawn under the text. */
+    selection?: SelectionRect[];
+    caretColor?: string;
+    selectionColor?: string;
+    /** Plugin-contributed decorations, pre-resolved to page-local rects. Background
+     *  kinds paint behind the text; underline/strike paint over it. */
+    decorations?: PaintDecoration[];
+    /** Visible region in container CSS px (the scroll window onto the stack).
+     *  Only pages intersecting it (plus a margin) get a canvas + content; the
+     *  rest are unmounted to keep memory bounded. Omit to render every page. */
+    viewport?: {
+        top: number;
+        height: number;
+    };
+}
+/** Injected so the painter can be unit-tested without a DOM. */
+export interface PainterDeps {
+    /** Creates a blank canvas element (defaults to document.createElement). */
+    createCanvas?: () => HTMLCanvasElement;
+}
+/**
+ * Paints a ResolvedLayout into a scroll container, one `<canvas>` per page.
+ *
+ * A single canvas can't represent a long document: browsers cap a canvas at
+ * 65535 px per side, so a tall doc (≈57+ A4 pages) silently renders blank. One
+ * canvas per page keeps every backing store small, and only the pages near the
+ * viewport are allocated — the rest are unmounted, so memory stays bounded no
+ * matter how long the document is.
+ *
+ * The painter consumes pre-computed coordinates only — it never measures or
+ * re-flows text. Inline images load asynchronously: the painter caches them and
+ * repaints once an image becomes available.
+ */
+export declare class CanvasPainter {
+    private readonly container;
+    private readonly createCanvas;
+    private readonly images;
+    /** pageIndex → its mounted canvas; idle canvases wait in `pool`. */
+    private readonly mounted;
+    private readonly pool;
+    /** The 2D context of the page currently being drawn (paint* read this). */
+    private ctx;
+    private lastLayout;
+    /** Last paint options, minus caret/selection (those live in lastOverlay). */
+    private lastOptions;
+    private lastOverlay;
+    private lastFrame;
+    /** Top edge (layout px) of each page in the stacked document. */
+    private pageY;
+    /** Pages currently showing caret/selection (so an overlay change can clear them). */
+    private overlayPages;
+    constructor(container: HTMLElement, deps?: PainterDeps);
+    paint(layout: ResolvedLayout, options?: PaintOptions): void;
+    /** Redraw just the pages whose caret/selection changed — the cheap path for
+     *  blink and drag (one page for a blink, a handful for a drag). */
+    paintOverlay(overlay?: {
+        caret?: CaretRect | null;
+        selection?: SelectionRect[];
+    }): void;
+    /** Mount (or reuse) page `i`'s canvas, size + position it, and draw it. */
+    private drawPage;
+    /** Pick the header/footer band for page `i`: the first variant on page 1 when
+     *  titlePg is set, the even variant on even pages when evenAndOdd is set, else
+     *  the default. A selected-but-absent variant means a blank band (no fallback
+     *  to the default — that's Word's behavior for title/even pages). */
+    private chromeFor;
+    /** Get page `i`'s slot, reusing a pooled canvas or creating one. */
+    private mountPage;
+    /** Detach page `i`, freeing its backing store (kept in the pool for reuse). */
+    private unmountPage;
+    /** Only resize when needed: assigning width/height — even the same value —
+     *  clears and reallocates the backing store. */
+    private sizeCanvas;
+    private paintPage;
+    /** Run `draw` rotated `deg` clockwise around the center of the given box —
+     *  the paint-only rotation of images/shapes (the layout box stays put). */
+    private withRotation;
+    /** One anchored float: vector shape or bitmap, then any textbox text laid
+     *  out inside it (box-local lines — translate to the float's origin, and
+     *  clip to the box the way Word hides textbox overflow). */
+    private paintFloat;
+    private paintLine;
+    /** Vector shape in an image box, per ShapeSpec.kind. The path is built with
+     *  primitive calls (no Path2D) and filled then stroked; strokes stay inside
+     *  the box so thick outlines don't bleed into text. */
+    private drawShape;
+    private paintTable;
+    /** Stroke one border edge with its width / style / colour. The edge is always
+     *  horizontal or vertical (table grid lines). */
+    private strokeBorder;
+    /** Container CSS-px point → page-local point. Points in the gap between pages
+     *  clamp to the nearer page edge; null before the first paint. */
+    canvasToPage(cssX: number, cssY: number): PagePoint | null;
+    /** Page-local point → container CSS-px point; null before the first paint. */
+    pageToCanvas(point: PagePoint): {
+        x: number;
+        y: number;
+    } | null;
+    /** Return the cached image for `src`, kicking off a load (and a repaint on
+     *  completion) the first time. Returns undefined where Image is unavailable
+     *  (SSR / tests) — the image is simply skipped. */
+    private requestImage;
+}
+//# sourceMappingURL=painter-canvas.d.ts.map

package/dist/lib/painter-canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"painter-canvas.d.ts","sourceRoot":"","sources":["../../src/lib/painter-canvas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EAGT,SAAS,EACT,eAAe,EAGf,cAAc,EAGd,aAAa,EAEd,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;uEACmE;IACnE,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;gFAE4E;IAC5E,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,iBAAiB,CAAC;CACxC;AA+CD;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;IAuBtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAtB5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAC9D,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,2EAA2E;IAC3E,OAAO,CAAC,GAAG,CAA4B;IAEvC,OAAO,CAAC,UAAU,CAA+B;IACjD,6EAA6E;IAC7E,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,WAAW,CAGjB;IACF,OAAO,CAAC,SAAS,CAAoD;IACrE,iEAAiE;IACjE,OAAO,CAAC,KAAK,CAAgB;IAC7B,qFAAqF;IACrF,OAAO,CAAC,YAAY,CAAqB;gBAGtB,SAAS,EAAE,WAAW,EACvC,IAAI,GAAE,WAAgB;IAMxB,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,YAAiB,GAAG,IAAI;IA2C/D;uEACmE;IACnE,YAAY,CAAC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;QAAC,SAAS,CAAC,EAAE,aAAa,EAAE,CAAA;KAAO,GAAG,IAAI;IAc3F,2EAA2E;IAC3E,OAAO,CAAC,QAAQ;IAuBhB;;;yEAGqE;IACrE,OAAO,CAAC,SAAS;IAcjB,oEAAoE;IACpE,OAAO,CAAC,SAAS;IAmBjB,+EAA+E;IAC/E,OAAO,CAAC,WAAW;IAUnB;oDACgD;IAChD,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IA+DjB;+EAC2E;IAC3E,OAAO,CAAC,YAAY;IAcpB;;gEAE4D;IAC5D,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,SAAS;IAuDjB;;2DAEuD;IACvD,OAAO,CAAC,SAAS;IAoGjB,OAAO,CAAC,UAAU;IAmElB;qDACiD;IACjD,OAAO,CAAC,YAAY;IA+BpB;sEACkE;IAClE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAqB1D,8EAA8E;IAC9E,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAa/D;;uDAEmD;IACnD,OAAO,CAAC,YAAY;CAkBrB"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@shadow-garden/bapbong-painter-canvas",
+  "version": "0.1.0",
+  "description": "bapbong — paints ResolvedLayout onto a Canvas 2D context",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shadowgarden-app/bapbong.git",
+    "directory": "packages/painter-canvas"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@shadow-garden/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "tags": [
+      "scope:painter"
+    ],
+    "targets": {
+      "build": {
+        "executor": "@nx/esbuild:esbuild",
+        "outputs": [
+          "{options.outputPath}"
+        ],
+        "options": {
+          "outputPath": "packages/painter-canvas/dist",
+          "main": "packages/painter-canvas/src/index.ts",
+          "tsConfig": "packages/painter-canvas/tsconfig.lib.json",
+          "format": [
+            "esm",
+            "cjs"
+          ],
+          "declarationRootDir": "packages/painter-canvas/src",
+          "external": [
+            "@shadow-garden/bapbong-contracts"
+          ]
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "@shadow-garden/bapbong-contracts": "^0.1.0"
+  }
+}