@claralight-design/wallpaper-engine

AstroBox 产品共用的壁纸配置解析、编辑状态、Canvas 渲染与 React 预览组件。

pnpm add @claralight-design/wallpaper-engine

import { normalizeWallpaperConfig } from "@claralight-design/wallpaper-engine";
import { renderWallpaperToBlob } from "@claralight-design/wallpaper-engine/render";
import { WallpaperStage } from "@claralight-design/wallpaper-engine/react";

Storybook

pnpm storybook
pnpm test:storybook
pnpm build-storybook

Storybook 覆盖以下功能：

• 壁纸定位、缩放、旋转、拖拽、裁剪与蒙版
• 素材图层、透明度、模糊、背景模糊、混合、着色与换色
• 文字框、字体轴、字号、字重、字距、行高与对齐
• 液态玻璃几何、材质、光照、质量档位、多层顺序与交互冻结
• 图像加载、PNG 导出、透明画布与缺失资源错误

液态玻璃默认使用圆形；圆形使用 geometry.diameter 声明实际直径。transform.x / transform.y 表示未旋转玻璃外框的左上角坐标。 Apple 材质默认采用 48px 下投影、Linear Burn 发丝描边和 Linear Dodge 双向内高光。

文本渲染

文本层主路径为 Typr.js（vendored，MIT）+ 可变字体 outline 绘制：

• loadWallpaperFont 一次 fetch 字体字节并解析，WallpaperResources.fonts 携带 { arrayBuffer, parsedFont, fontFace?, parseFallbackReason? }。
• getWallpaperTextShape / getWallpaperTextMetrics / drawWallpaperTextLine 完成 排版、度量与 outline 绘制；fvar 全部轴（含 GRAD / opsz / 自定义轴）经 gvar 插值生效， 结果与平台无关。
• 支持 GPOS kern（含 ExtensionPos）、GSUB liga、HVAR advance、旧式 kern 表， 与 HarfBuzz 的实测逐字形一致。
• 缺字（gid 0）按 grapheme 回退到 FontFace + fillText；字体格式主路径不可用时 （parseFallbackReason: woff2 / cff2 / no-outline / parse-error） 整层回退。

环境支持范围

| 能力 | 主线程 (DOM) | Worker / OffscreenCanvas | | --- | --- | --- | | 字体字节解析（parseWallpaperFont，含 TTF/TTC/WOFF/CFF） | ✅ | ✅ | | 排版 / 度量 / outline 生成（getWallpaperTextShape 等，纯函数） | ✅ | ✅ | | 向给定 context 绘制（drawWallpaperTextLine，不依赖 ctx.font） | ✅ | ✅（提供 2d context 即可） | | loadWallpaperFont（fetch 解析；FontFace 仅用于回退，不可用时跳过） | ✅ | ✅（需环境支持 fetch） | | drawWallpaper / renderWallpaperToBlob 完整流水线 | ✅ | ⚠️ 需传入自定义 canvasFactory；toBlob/默认工厂依赖 DOM |

Worker 里可直接完成「解析 → 排版 → outline 路径」并返回 cmds/crds 数据； 完整壁纸合成仍需要调用方提供 canvas 工厂。