kane50613-takumi

name: kane50613-takumi description: "ALWAYS use when writing code importing "@takumi-rs/core". Consult for debugging, best practices, or modifying @takumi-rs/core, takumi-rs/core, takumi-rs core, takumi rs core, takumi." metadata: version: 0.68.2 generated_by: Claude Code · Opus 4.6

kane50613/takumi @takumi-rs/core

Version: 0.68.2 (today) Tags: latest: 0.68.2 (today)

References: package.json • README • GitHub Issues • GitHub Discussions • Releases

Search

Use npx -y skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases.

npx -y skilld search "query" -p @takumi-rs/core
npx -y skilld search "issues:error handling" -p @takumi-rs/core
npx -y skilld search "releases:deprecated" -p @takumi-rs/core

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

⚠️ renderAsync() — deprecated, use render() instead (async naming convention change) source

⚠️ loadFontAsync() — deprecated, use loadFont() instead source

⚠️ loadFontsAsync() — deprecated, use loadFonts() instead source

⚠️ putPersistentImageAsync() — deprecated, use putPersistentImage() instead source

⚠️ PersistentImage type — deprecated, use ImageSource instead source

⚠️ OutputFormat uppercase variants 'WebP', 'Jpeg', 'Png' — deprecated, use lowercase 'webp', 'jpeg', 'png' source

⚠️ purgeResourcesCache() / purgeFontCache() — deprecated no-ops, do nothing; remove calls source

✨ loadFontSync() — new in v0.67.2, synchronous font loading source

✨ measure() — returns MeasuredNode with layout info (width, height, transform, text runs) source

✨ renderAnimation() — renders AnimationFrameSource[] to animated webp/apng; images must be passed via ConstructRendererOptions.persistentImages (not per-call) source

✨ extractResourceUrls() — standalone function to collect image URLs from a node tree before render source

✨ Font type accepts bare Uint8Array | ArrayBuffer — no need to wrap in FontDetails if name/weight/style auto-detection is fine source

Best Practices

✅ Pass persistedImages to the Renderer constructor for animations — renderAnimation() does not accept them at call time, only the constructor does source

const renderer = new Renderer({
  fonts,
  persistedImages: [{ src: 'logo.png', data: logoBuffer }],
})
await renderer.renderAnimation(frames, { width: 1200, height: 630 })

✅ Pre-fetch images and pass as fetchedResources or persistedImages — passing a URL string as img src without pre-fetching the buffer causes "Failed to get Buffer pointer and length" crashes source

const imgData = await fetch(url).then(r => r.arrayBuffer())
await renderer.render(node, {
  fetchedResources: [{ src: url, data: new Uint8Array(imgData) }],
})

✅ Always provide at least one font — constructing Renderer without fonts causes a crash; there is no built-in default font source

✅ Use loadFontSync for synchronous font loading (v0.67.2+) — avoids async overhead when fonts are already in memory source

renderer.loadFontSync({ data: fontBuffer, name: 'Inter', weight: 400 })

✅ Avoid variable fonts — they are not supported; use separate static font files per weight source

✅ Use extractResourceUrls(node) to discover image URLs before rendering — lets you pre-fetch all required images in parallel source

const urls = extractResourceUrls(node)
const resources = await Promise.all(
  urls.map(async src => ({ src, data: new Uint8Array(await fetch(src).then(r => r.arrayBuffer())) }))
)
await renderer.render(node, { fetchedResources: resources })

✅ Use lowercase format strings 'png' | 'webp' | 'jpeg' — uppercase variants ('Png', 'WebP', 'Jpeg') are deprecated and may be removed source

✅ Use @takumi-rs/wasm for edge runtimes (Cloudflare Workers, Vercel Edge) — @takumi-rs/core uses native .node bindings via napi-rs and does not work in edge/WASM environments source

✅ Pass AbortSignal to render/loadFont/loadFonts — all async methods accept an optional signal for caller-controlled cancellation source

✅ PersistentImage type is deprecated — use ImageSource instead (same shape: { src: string, data: Uint8Array | ArrayBuffer }) source