@hankchen/canvas-image-renderer 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @hankchen/canvas-image-renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+graph → 透明底 PNG 的 Node 渲染后端（无头、零 DOM）：消费 `@hankchen/canvas` 的
+五原语渲染契约（`RenderBackend`）与资源物化缝（`ResourceResolver`），对位
+go-canvas/image-renderer module。
+
+- 五原语（`ImageRendererBackend`）：`begin`/`end`（`encodeSync('png')` 透明底产物）、
+  `drawRect`（背景色 + 盒内嵌边框带）、`drawImage`（双矩形 blit + EXIF raw→canonical
+  窗口映射）、`drawText`（真实字体、对齐锚点、角度旋转）、`imageIntrinsicSize`
+  （raw 内在尺寸查询）。
+- EXIF 混合口径（04 号决议）：像素面吃 napi 解码层自动转正（canonical），查询面
+  返 raw 尺寸（orientation ≥5 互换宽高）；取舍见 `docs/adr/0001-*.md`。
+- 文本：原语层永远真实字体绘制（TTC 魔数嗅探 fail-fast 拒收；空串/纯数字字体 id =
+  内置默认字体）；`createNapiMeasurerFactory` 为 08 号决议的 v1 增强度量器，
+  经核心 `TextLayoutPolicies.measurerFactory` 显式注入，缺省不注入（启发式对齐版）。
+- 资源物化默认接线（`createDefaultResolver`）：HTTP 下载 + 内存/可选落盘缓存 +
+  QR 物化（纠错 H、quiet zone 0、正方形 PNG），字节经 `setImage` 以 wire src 同键
+  登记，物化不进 wire。
+
+## 用法
+
+```ts
+import { decodeGraph, renderAs } from '@hankchen/canvas'
+import { ImageRendererBackend, createDefaultResolver } from '@hankchen/canvas-image-renderer'
+
+const canvas = decodeGraph(wireJson)
+const backend = new ImageRendererBackend()
+await createDefaultResolver().resolve(canvas, backend) // 渲染前异步物化（可选）
+const png: Uint8Array = renderAs<Uint8Array>(canvas, backend)
+```
+
+## 平台支持面
+
+- **macOS / Linux 明确支持**（CI 双平台矩阵验证；`@napi-rs/canvas` 1.0.13 预编译
+  native 包按 platform 自动安装，darwin-x64/arm64 与 linux-x64/arm64/glibc/musl
+  均在发布面）。
+- **Windows 不承诺**：napi 有 win32 包但本仓不在 CI 验证，出问题按社区包自行排查；
+  预编译 native 包体积较大（每个平台包数十 MB，安装时按 `os`/`cpu` 只拉对应
+  optional dependency）。
+
+## 目验样张
+
+```sh
+pnpm visualcheck   # 仓根一键两包；或本包内 node scripts/visualcheck.mjs [输出路径]
+```
+
+400×520 综合样张（九条验收线：叠加次序/中文禁则断行/表格嵌套/QR/cover/自适应宽/
+页脚等）输出到 `visualcheck-output/`（gitignore）。字体探针纪律：候选逐个以渲染端
+同一入口「存在且可加载」判取（TTC 拒收），全缺报错逐条列原因；`JS_CANVAS_VISUAL_FONT`
+可指定单体 TTF，CI 冒烟可设 `JS_CANVAS_ALLOW_NO_FONT=1` 让字体腿 skip。底座升级
+必须先过样张目验门禁（AGENTS.md「版本升级样张门禁」条款）。

package/dist/index.d.ts

@@ -0,0 +1,289 @@
+import { RenderBackend, Border, BlitRect, TextDrawOptions, FetchLike, QRMaterializer, ImageRegisteringBackend, ResourceResolver, TextMeasurerFactory } from '@hankchen/canvas';
+import { SKRSContext2D, Image } from '@napi-rs/canvas';
+
+declare class ImageRendererBackend implements RenderBackend {
+    private surface;
+    private ctx;
+    /** 图像登记表（核心 setImage 缝）：键 = wire src 引用（`qr:` 前缀/远程 URL/任意键） */
+    private readonly registry;
+    /** 解码缓存：键 = src 引用；null = 装配失败标记（静默不画） */
+    private readonly decoded;
+    /** begin 取渲染面；未建面即调用绘制原语属用法错误（模板保证先 begin） */
+    private canvasCtx;
+    /**
+     * 渲染前异步预备：解析 src（登记表/data URL/本地路径）并解码出可绘制位图进
+     * 缓存。幂等；返回是否可绘制。默认 resolver 物化时逐 src 调用——手工装配
+     * 后端时须自行预热，否则 drawImage 静默不画（见文件头「结构性差异」注）
+     */
+    preload(src: string): Promise<boolean>;
+    /** 创建渲染面（width/height ≤0 报错；全新透明画布，对位 image.NewNRGBA） */
+    begin(width: number, height: number): void;
+    /** 收尾：encodeSync('png') 透明底产物；未建面返回 null（对位 go 字面 nil） */
+    end(): Uint8Array | null;
+    /**
+     * 矩形盒：背景色 + 四边边框。背景为 null 或空串跳过填充（PHP 同款守卫）；
+     * 边框 = 四边各一条线宽=边框宽的直线（非描边矩形），按盒内嵌绘制，逐边可
+     * null/零宽不计，序 top/bottom/left/right（PHP 绘制序，后画覆盖先画；
+     * canvas source-over 合成 = go draw.Over 同语义）
+     */
+    drawRect(x: number, y: number, width: number, height: number, bgColor: string | null, border: Border): void;
+    /**
+     * 图片双矩形 blit（ADR 0024）：把 src 的 srcRect 子矩形拉伸搬运到 dstRect。
+     * srcRect 是 raw（内在坐标）空间窗口——napi 位图是 canonical（EXIF 自动转正）
+     * 空间，非整图窗口经 canonicalSourceRect 映射进 canonical（04 号决议像素面
+     * 口径的落地机制，与 go「先裁后转」逐像素等价）；整图哨兵（零宽高）直取
+     * canonical 整图（raw 全图转正 = canonical 全图，恒等免映射）。
+     * dstRect 尺寸 ≤0 防护先于读取跳过；src 未装配/装配失败/映射窗与位图不相交
+     * 一律静默不画（缺省约定，见文件头）
+     */
+    drawImage(src: string, srcRect: BlitRect, dstRect: BlitRect): void;
+    /**
+     * 单行文本（对位 go text.go DrawText）：原语层永远真实字体绘制——字体装配/
+     * TTC 拒收/内置默认字体判定/对齐锚点与基线差/角度旋转见 text.ts
+     * （drawTextLine）。空行零副作用；字色解析失败中止
+     */
+    drawText(line: string, x: number, y: number, options: TextDrawOptions): void;
+    /**
+     * 源图内在尺寸度量（ADR 0023/0024 查询口）：返 raw（未转正）尺寸——对位
+     * go image.DecodeConfig / PHP getimagesize 的内在坐标系。查不到/解码失败返
+     * null → 核心统一退化 fill 形态。
+     * 两路在「raw 出参」契约上收敛（napi 同步/异步口径差异的实测收敛，见
+     * decode.ts decodeHeaderSize docblock）：
+     * - preload 缓存命中：位图是 canonical（异步解码已转正），按 DecodedEntry
+     *   已存的 orientation ≥5 互换换回 raw（评审 P0-3：缓存臂不重读磁盘重算
+     *   orientation——字节不可得时兜底 1 会产出 canonical 错误空间尺寸；不产出
+     *   空间错误的尺寸，弃用既有已存数据更是错上加错）；
+     * - 未装配 src：同步头部探测直出 raw 头尺寸（同步口不施加转正），原样返回
+     */
+    imageIntrinsicSize(src: string): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * 图像登记缝（核心 setImage 契约）：物化器按键登记资源字节，键即 drawImage
+     * 收到的 src 引用。字节拷贝入表（所有权归登记表，防外部原地改写）；同键重
+     * 登记使解码缓存失效（下次 preload 重装配）
+     */
+    setImage(key: string, data: Uint8Array): void;
+    /**
+     * 字体物化缝（resolver 的远程字体下载字节按键登记；核心 ResourceResolver
+     * 契约「注册缝归后端包契约」的本包落点）：TTC 拒收与 GlobalFonts 注册在
+     * 此处完成（物化阶段 fail-fast，渲染不带病启动），drawText 以 wire font
+     * 引用（URL 原文）直取。幂等（同字节同别名）
+     */
+    registerFont(ref: string, data: Uint8Array): void;
+}
+
+/** 本包后端渲染缝的最小结构面：核心登记缝 + 字体登记 + 预热（均后端自决实现） */
+interface MaterializationBackend extends ImageRegisteringBackend {
+    /** 字体物化缝（ImageRendererBackend 实现；远程 URL 字体字节按键登记） */
+    registerFont?(ref: string, data: Uint8Array): void;
+    /** 渲染前异步预热缝（ImageRendererBackend 实现；位图装配前提） */
+    preload?(src: string): Promise<boolean>;
+}
+interface DefaultResolverOptions {
+    /** fetch 注入缝（代理/鉴权/测试桩）；缺省全局 fetch */
+    fetchLike?: FetchLike;
+    /** 落盘缓存根目录；缺省仅内存缓存。子目录 img_layers/text_layers/qr_layers（go 同名） */
+    cacheRoot?: string;
+    /** QR 物化缝；缺省接 QrCodeMaterializer（前置注入），显式 null = 不接线（遇
+     * 二维码图层报 qr_materializer_required），传自定义实现则覆写默认 */
+    qrMaterializer?: QRMaterializer | null;
+}
+/**
+ * 构造带二维码物化的默认解析器（对位 go NewDefaultResolver）：QR 缝固定前置
+ * 注入，options 后置可覆写；fetch 缺省全局 fetch，缓存缺省仅内存。同一 resolver
+ * 实例的内存缓存跨多次 resolve 共享（命中即跳过，不下载不覆写；对位 go 命中
+ * 跳过语义，无失效机制）
+ */
+declare function createDefaultResolver(options?: DefaultResolverOptions): ResourceResolver;
+
+/** 二维码物化默认实现（固定选项；核心 QRMaterializer 契约的实现）。命名 QrCode
+ * 对齐领域命名 QrCodeLayer 与 pdf 包同类（评审 P1-6 两包统一；核心接口名
+ * QRMaterializer 是 go 对位名，不动） */
+declare class QrCodeMaterializer implements QRMaterializer {
+    materialize(text: string, width: number): Promise<Uint8Array>;
+}
+
+/** 内置默认字体判定：空串/纯数字字体 id（对位 go typography.IsBuiltinFont）。
+ * 空串与纯数字同归默认字面——判定与 resolver 跳过字体物化共用 isNumeric 同一口径
+ * （src/url.ts，防漂移）。度量与绘制共用本判定（对位 go measurer.go docblock） */
+declare function isBuiltinFont(font: string): boolean;
+/**
+ * 远程字体物化缝：resolver 把下载字节按键（URL 原文）登记，drawText 以 wire
+ * font 引用直取。字节面在此处完成 TTC 拒收与注册（物化阶段 fail-fast，渲染
+ * 不带病启动）；幂等（同字节同别名）
+ */
+declare function registerFontData(ref: string, data: Uint8Array): void;
+/**
+ * 字体引用 → CSS family 别名（内置默认 → 'sans-serif'，即渲染端默认字体族；
+ * 对位 go BuiltinFace 的「内置语义」位）。装配失败即抛——绘制端原样上抛中止，
+ * 度量端经 createNapiMeasurerFactory 捕获降级
+ */
+declare function loadFontFamily(font: string): string;
+/**
+ * napi 真实字体度量器工厂（08 号决议 v1 单组件；对位 go OpenTypeMeasurerFactory）：
+ * 每次工厂调用新建独立度量器（go 三组件「工厂每次新建」先例），度量前按图层
+ * 字体与字号重设 ctx.font（同「用前设置」纪律）。
+ *
+ * 基线换算实测钉死（1.0.13）：TextMetrics.fontBoundingBoxAscent/Descent 为
+ * 「基线距字盒顶/底」正值口径，与 go x/image Metrics 的 Ascent / Descent（正值
+ * 约定）同号同义——绘制端基线差消化用这对字段（见 text.ts）；而
+ * alphabeticBaseline/ideographicBaseline 实测是「相对基线自身」的偏移量
+ * （alphabetic 恒 0、ideographic 为 CJK 基线相对 alphabetic 的偏移），不是
+ * 「距盒顶」口径，不作基线锚点用。宽度即 metrics.width 像素浮点（与落笔同一
+ * 度量路径，对位 go MeasureString 与 DrawString 同路径）。
+ *
+ * 加载失败（缺文件/解析失败/远程字体尚未物化）与非正字号降级核心启发式度量，
+ * 布局不中断（对位 go 工厂降级臂）；TTC 视为加载失败同降级（拒收只在绘制端
+ * fail-fast——度量中断会破坏整个布局，两侧差异是刻意的）
+ */
+declare const createNapiMeasurerFactory: TextMeasurerFactory;
+
+/**
+ * 文本绘制原语（对位 go-canvas/image-renderer/text.go）：单行、对齐锚点落笔、
+ * 角度旋转。(x, y) 为对齐语义锚点——水平按真实文本宽度（ctx.measureText.width，
+ * 与落笔同一度量路径，对位 go MeasureString）对齐；垂直用字盒基线差把基线落到
+ * 锚点语义对应位置；布局层只返回纯对齐锚点，字体基线差统一在渲染端消化
+ * （08 号决议分层纪律：原语层永远真实字体绘制）。
+ *
+ * 基线换算（关键缝，实测钉死见 typography.ts docblock）：canvas 的
+ * fontBoundingBoxAscent/Descent 与 go x/image Metrics 的 Ascent/Descent 同号
+ * 同义（正值、基线距字盒顶/底），go 的三条基线公式逐条平移——
+ * top（含未知值缺省臂）: baseline = y + ascent
+ * center: baseline = y + (ascent - descent) / 2
+ * bottom: baseline = y - descent
+ *
+ * 角度：单位度，正值逆时针（GD 惯例）。路径对位 go drawRotatedText——离屏
+ * 渲染后绕锚点旋转移到渲染面；canvas transform 矩阵与 go f64.Aff3 同式
+ * （[[cos,sin],[-sin,cos]]，y 轴向下的视觉逆时针）。
+ */
+
+/**
+ * 在渲染面上绘制单行文本。空行零副作用（PHP 同款空串守卫）；字色解析失败
+ * wrap「解析字色」上抛中止；字体装配失败（缺文件/TTC 拒收）上抛中止
+ */
+declare function drawTextLine(ctx: SKRSContext2D, line: string, x: number, y: number, options: TextDrawOptions): void;
+
+/**
+ * 颜色解析（对位 go-canvas/image-renderer/color.go 同式复制，注明出处；
+ * go 侧先例：color/exif/qr 小件在两 module 复制，TS 侧核心包零依赖红线
+ * 禁止收纳，故落本包）。wire 面与图层选项只产出 CSS 十六进制写法（PHP
+ * intervention 还接受颜色名与 rgb() 函数串，本项目不使用），故仅支持 hex
+ * 形态，其余报错中止渲染（原语失败即抛纪律）。
+ */
+/** 直 alpha 颜色分量（0–255，无预乘；对位 go color.NRGBA） */
+interface NrgbaColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * 解析十六进制颜色为直 alpha 分量。支持 #rgb / #rgba / #rrggbb / #rrggbbaa，
+ * 前导 # 可省略；3/4 位逐位翻倍后走同一累积路径；6 位 alpha=255。
+ * 非法长度/非法十六进制位即抛（错误消息对位 go color.go 文案）
+ */
+declare function parseColor(s: string): NrgbaColor;
+/**
+ * napi canvas fillStyle 字符串（css rgba() 函数式，alpha 归一到 0–1）。
+ * canvas 2D 默认 source-over 合成 = go draw.Over 同语义（后画覆盖先画）
+ */
+declare function cssColor(c: NrgbaColor): string;
+
+/**
+ * EXIF orientation：JPEG 的 APP1(Exif) 段携带拍摄方向。node 侧混合口径（04 号
+ * 决议）——像素面吃 napi 解码层自动转正（canonical 空间），本模块只承担两件
+ * 同步职责：① 从字节流读 orientation（drawImage 的 raw→canonical 窗口映射与
+ * imageIntrinsicSize 的 raw 尺寸互换都需要它，二者皆为同步原语）；② 把 raw
+ * （内在）坐标窗口映射进 canonical 位图坐标（canonicalSourceRect）。
+ *
+ * 解析器对位 go-canvas/image-renderer/exif.go 同式复制（注明出处；go 侧先例：
+ * color/exif/qr 小件在两 module 复制）——只找 IFD0 的 Orientation 标签(0x0112)，
+ * 其余结构一概不碰。工票原案「用 exifr 读 orientation」在同步原语契约下不可行
+ * （exifr 全异步、核心 imageIntrinsicSize/drawImage 为同步口），改用本同式解析器：
+ * 与 go 逐字节同语义、测试与 go exif_test 同手法互检，「≥5 互换返 raw」语义不变。
+ */
+/**
+ * 从图片字节流解析 EXIF orientation(1–8)。非 JPEG、无 EXIF、结构截断/非法一律
+ * 归 1（无需转正）——与 go exifOrientation 同语义
+ */
+declare function exifOrientation(data: Uint8Array): number;
+/** blit 矩形（对位核心包 BlitRect；此处收窄为本包内用形，避免循环依赖负担） */
+interface SourceRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * raw（内在坐标）窗口 → canonical（napi 转正后位图）窗口。
+ *
+ * 04 号决议像素面口径的落地机制：go 是「先裁后转」（裁窗在内在坐标系、转正后置），
+ * napi 是「解码即转正」——orientation 是逐像素双射，裁窗与转正可交换，把 raw 窗口
+ * 经转正映射搬进 canonical 位图即得同一块像素（任意窗口精确等价，居中 cover 只是
+ * 最常见入参）。映射公式由 go applyOrientation 的 canonical(dx,dy)=raw(sx,sy)
+ * 八向公式反解（互检见 tests/exif.test.ts 的手算字面量与 go 期望栅格）：
+ * - 2–4 镜像族：维度不变，原点按镜像轴翻折；
+ * - 5–8 旋转族：宽高互换，原点按转置轴翻折。
+ *
+ * orientation 由 exifOrientation 保证在 1–8；sw/sh 为 raw 尺寸
+ */
+declare function canonicalSourceRect(raw: SourceRect, orientation: number, sw: number, sh: number): SourceRect;
+/**
+ * canonical 位图尺寸对应的 raw 尺寸（imageIntrinsicSize 查询面）：orientation ≥5
+ * （90° 族）时 napi 解出的 w/h 已互换，再换回来即 raw 内在尺寸——对位 go
+ * image.DecodeConfig（内在坐标系未转正）与 PHP getimagesize
+ */
+declare function rawDimensions(canonicalWidth: number, canonicalHeight: number, orientation: number): {
+    width: number;
+    height: number;
+};
+
+/**
+ * 图片字节装载与解码（对位 go decode.go + blitSource 共享前段的读源半边）：
+ * 三源依次查——登记表（setImage 键，`qr:` 前缀与物化资源同门）→ data URL →
+ * 本地路径。远程 URL 不进原语同步路径（网络 I/O 归 ResourceResolver 物化，
+ * 未物化的远程引用按查不到处置）。
+ */
+
+/** 登记面最小结构（ImageRendererBackend 的 setImage 登记表同构，解耦复用） */
+interface ByteRegistry {
+    get(key: string): Uint8Array | undefined;
+}
+/**
+ * 按引用装载图片字节：登记表命中优先；data URL 仅支持 base64 形态；其余按
+ * 本地路径读盘（文件视为渲染会话内不可变，对位 go os.ReadFile）。查不到返回
+ * null——由调用方按各自契约处置（drawImage 静默不画 / imageIntrinsicSize
+ * 返 null 退化 fill）
+ */
+declare function loadSourceBytes(src: string, registry?: ByteRegistry): Uint8Array | null;
+/**
+ * 同步头部尺寸探测：napi Image 的 width/height 在 src 赋值后同步可得（位图
+ * raster 才需 await decode）。损坏/空字节 width 归 0 → null。
+ *
+ * 实测钉死（1.0.13，精确钉版 + exif 测试互检）：同步 width/height 是 **raw**
+ * （EXIF 转正前）的头尺寸——转正发生在异步解码的 raster 阶段（async loadImage
+ * 出 canonical 位图）。故本探测结果直返即查询面要的 raw 内在尺寸，无需再按
+ * orientation 换算（见 backend.imageIntrinsicSize 两路收敛注释）
+ */
+declare function decodeHeaderSize(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * 异步解码出可绘制位图（napi 实测 1.0.13：同步只出尺寸，raster 须经
+ * loadImage/decode() 才可 drawImage——后端 preload 缝的实现底座）。
+ * 解码失败返回 null（调用方标记该 src 静默不画）
+ */
+declare function decodeDrawableImage(bytes: Uint8Array): Promise<Image | null>;
+
+/**
+ * @hankchen/canvas-image-renderer 公共出口：位图渲染后端（五原语 + setImage/
+ * registerFont/preload 装配缝）、EXIF 混合口径映射件、napi 度量增强件（08 号
+ * 决议，显式注入）、QR 物化与默认 resolver（对位 go image-renderer module 的
+ * 导出面）。渲染契约与物化契约类型来自 @hankchen/canvas，不在此重复导出。
+ */
+declare const PACKAGE_NAME: "@hankchen/canvas-image-renderer";
+
+export { type ByteRegistry, type DefaultResolverOptions, ImageRendererBackend, type MaterializationBackend, type NrgbaColor, PACKAGE_NAME, QrCodeMaterializer, type SourceRect, canonicalSourceRect, createDefaultResolver, createNapiMeasurerFactory, cssColor, decodeDrawableImage, decodeHeaderSize, drawTextLine, exifOrientation, isBuiltinFont, loadFontFamily, loadSourceBytes, parseColor, rawDimensions, registerFontData };