@takumi-rs/core 1.8.7 → 2.0.0-beta.1

package/index.d.ts

@@ -24,6 +24,12 @@ export interface FontDetails {
    * The style of the font. If not provided, the style in the font file will be used.
    */
   style?: "normal" | "italic" | "oblique" | `oblique ${number}deg` | (string & {});
+  /**
+   * Logical family this font is a coverage subset of. Subsets sharing a `subsetOf` are
+   * kept as distinct families and `font-family: {subsetOf}` expands to all of them, so each
+   * script routes to the subset that covers it. Set by {@link loadGoogleFonts}.
+   */
+  subsetOf?: string;
 }
 
 export type Font = FontDetails | ByteBuf;
@@ -40,19 +46,13 @@ export type Keyframes = KeyframesMap | KeyframesRuleList;
 /** The main renderer for Takumi image rendering engine (Node.js version). */
 export declare class Renderer {
   /** Creates a new Renderer instance. */
-  constructor(options?: ConstructRendererOptions | undefined | null)
-  /** Puts a persistent image into the renderer's internal store asynchronously. */
-  putPersistentImage(source: ImageSource, signal?: AbortSignal): Promise<void>
-  /** Loads a font synchronously. */
-  loadFontSync(font: Font): void
-  /** Loads a font into the renderer asynchronously. */
-  loadFont(data: Font, signal?: AbortSignal): Promise<number>
-  /** Loads multiple fonts into the renderer asynchronously. */
-  loadFonts(fonts: Font[], signal?: AbortSignal): Promise<number>
-  /** Clears the renderer's internal image store. */
-  clearImageStore(): void
+  constructor()
+  /** Register font into the renderer, returning the families produced. */
+  registerFont(fonts: Font, signal?: AbortSignal): Promise<RegisteredFamily[]>
   /** Renders a node tree into an image buffer asynchronously. */
   render(source: Node, options?: RenderOptions, signal?: AbortSignal): Promise<Buffer>
+  /** Renders a node tree into an SVG document string asynchronously. */
+  renderSvg(source: Node, options?: SvgRenderOptions, signal?: AbortSignal): Promise<string>
   /** Measures a node tree and returns layout information asynchronously. */
   measure(source: Node, options?: RenderOptions, signal?: AbortSignal): Promise<MeasuredNode>
   /** Renders a sequential scene animation into a buffer asynchronously. */
@@ -85,19 +85,6 @@ export interface AnimationSceneSource {
   durationMs: number
 }
 
-/** Options for constructing a Renderer instance. */
-export interface ConstructRendererOptions {
-  /** The images that needs to be preloaded into the renderer. */
-  persistentImages?: Array<ImageSource>
-  /** The fonts being used. */
-  fonts?: Font[] | undefined
-  /**
-   * Whether to load the default fonts.
-   * If `fonts` are provided, this will be `false` by default.
-   */
-  loadDefaultFonts?: boolean
-}
-
 export type DitheringAlgorithm =  'none'|
 'ordered-bayer'|
 'floyd-steinberg';
@@ -112,10 +99,18 @@ export interface EncodeFramesOptions {
   height: number
   /** The output animation format (WebP, APNG, or GIF). */
   format?: AnimationOutputFormat
-  /** The quality of WebP format (0-100). Ignored for APNG and GIF. */
+  /**
+   * The quality of lossy WebP (0-100). Ignored for APNG and GIF, and when
+   * `lossless` is set.
+   */
   quality?: number
-  /** The fetched resources to use. */
-  fetchedResources?: Array<ImageSource>
+  /**
+   * Encode WebP losslessly. Defaults to lossless when neither `quality` nor
+   * `lossless` is given. Ignored for APNG and GIF.
+   */
+  lossless?: boolean
+  /** Images keyed by `src`, each carrying raw bytes. */
+  images?: Array<ImageSource>
   /** CSS stylesheets to apply before rendering. */
   stylesheets?: Array<string>
   /**
@@ -123,14 +118,27 @@ export interface EncodeFramesOptions {
    * @default 1.0
    */
   devicePixelRatio?: number
+  /**
+   * Per-render font stack: ordered family names used as the fallback chain.
+   * Defaults to all registered families in registration order.
+   */
+  fontFamilies?: Array<string>
 }
 
+/** Cache policy for a decoded image. Defaults to `"auto"`. */
+export type ImageCacheMode = /** Cache the decoded image for reuse (evictable). */
+'auto'|
+/** Skip the decoded-image cache. */
+'none';
+
 /** An image source with its URL and raw data. */
 export interface ImageSource {
   /** The source URL of the image. */
   src: string
   /** The raw image data (Uint8Array or ArrayBuffer). */
   data: Uint8Array | ArrayBuffer
+  /** Cache policy for the decoded image. Defaults to `"auto"`. */
+  cache?: ImageCacheMode
 }
 
 /** Represents a node that has been measured, including its layout information. */
@@ -173,6 +181,26 @@ export type OutputFormat = /** WebP format. */
 /** Raw pixels format. */
 'raw';
 
+/** A single face within a `RegisteredFamily`. */
+export interface RegisteredFace {
+  /** Weight class, typically `1`–`1000`. */
+  weight: number
+  /** CSS `font-style` value (`normal`, `italic`, or `oblique [<angle>deg]`). */
+  style: string
+  /** Width as a percentage of normal (e.g. `100`). */
+  width: number
+  /** Index of the face within its source collection. */
+  index: number
+}
+
+/** A font family produced by `registerFont`, with the faces it contains. */
+export interface RegisteredFamily {
+  /** Family name as stored by the font system (normalized; reflects any override). */
+  name: string
+  /** Faces registered under this family. */
+  faces: Array<RegisteredFace>
+}
+
 /** Options for rendering a sequential scene animation. */
 export interface RenderAnimationOptions {
   /** The scenes to render sequentially. */
@@ -185,12 +213,20 @@ export interface RenderAnimationOptions {
   height: number
   /** The output animation format (WebP, APNG, or GIF). */
   format?: AnimationOutputFormat
-  /** The quality of WebP format (0-100). Ignored for APNG and GIF. */
+  /**
+   * The quality of lossy WebP (0-100). Ignored for APNG and GIF, and when
+   * `lossless` is set.
+   */
   quality?: number
+  /**
+   * Encode WebP losslessly. Defaults to lossless when neither `quality` nor
+   * `lossless` is given. Ignored for APNG and GIF.
+   */
+  lossless?: boolean
   /** Frames per second for timeline sampling. */
   fps: number
-  /** The fetched resources to use. */
-  fetchedResources?: Array<ImageSource>
+  /** Images keyed by `src`, each carrying raw bytes. */
+  images?: Array<ImageSource>
   /** CSS stylesheets to apply before rendering. */
   stylesheets?: Array<string>
   /**
@@ -198,6 +234,11 @@ export interface RenderAnimationOptions {
    * @default 1.0
    */
   devicePixelRatio?: number
+  /**
+   * Per-render font stack: ordered family names used as the fallback chain.
+   * Defaults to all registered families in registration order.
+   */
+  fontFamilies?: Array<string>
 }
 
 /** Options for rendering an image. */
@@ -208,12 +249,20 @@ export interface RenderOptions {
   height?: number
   /** The format of the image. */
   format?: OutputFormat
-  /** The quality of JPEG format (0-100). */
+  /**
+   * The quality of lossy formats (0-100). For JPEG; for WebP it selects lossy
+   * encoding unless `lossless` is set.
+   */
   quality?: number
+  /**
+   * Encode WebP losslessly. Defaults to lossless when neither `quality` nor
+   * `lossless` is given.
+   */
+  lossless?: boolean
   /** Whether to draw debug borders. */
   drawDebugBorder?: boolean
-  /** The fetched resources to use. */
-  fetchedResources?: Array<ImageSource>
+  /** Images keyed by `src`, each carrying raw bytes. */
+  images?: Array<ImageSource>
   /** CSS stylesheets to apply before rendering. */
   stylesheets?: Array<string>
   /** Structured keyframes to register alongside stylesheets. */
@@ -227,4 +276,34 @@ export interface RenderOptions {
   timeMs?: number
   /** The output dithering algorithm. */
   dithering?: DitheringAlgorithm
+  /**
+   * Per-render font stack: ordered family names used as the fallback chain.
+   * Defaults to all registered families in registration order.
+   */
+  fontFamilies?: Array<string>
+}
+
+/**
+ * Options for rendering a node tree to an SVG document. SVG is a vector
+ * format, so the raster-only knobs (`format`, `quality`, `lossless`,
+ * `dithering`, `drawDebugBorder`, `devicePixelRatio`) do not apply.
+ */
+export interface SvgRenderOptions {
+  /** The width of the viewport. If not provided, it is derived from content. */
+  width?: number
+  /** The height of the viewport. If not provided, it is derived from content. */
+  height?: number
+  /** Images keyed by `src`, each carrying raw bytes. */
+  images?: Array<ImageSource>
+  /** CSS stylesheets to apply before rendering. */
+  stylesheets?: Array<string>
+  /** Structured keyframes to register alongside stylesheets. */
+  keyframes?: Keyframes
+  /** The animation timeline time in milliseconds. */
+  timeMs?: number
+  /**
+   * Per-render font stack: ordered family names used as the fallback chain.
+   * Defaults to all registered families in registration order.
+   */
+  fontFamilies?: Array<string>
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takumi-rs/core",
-  "version": "1.8.7",
+  "version": "2.0.0-beta.1",
   "description": "Native Node.js bindings for the Takumi Rust image rendering engine.",
   "keywords": [
     "css",
@@ -25,7 +25,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kane50613/takumi.git",
-    "directory": "takumi-napi-core"
+    "directory": "takumi-napi"
   },
   "files": [
     "dist",
@@ -70,10 +70,10 @@
     "publish-lint": "attw --pack . && publint --strict ."
   },
   "dependencies": {
-    "@takumi-rs/helpers": "1.8.7"
+    "@takumi-rs/helpers": "2.0.0-beta.1"
   },
   "devDependencies": {
-    "@napi-rs/cli": "3.7.0",
+    "@napi-rs/cli": "3.7.2",
     "@types/bun": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
@@ -103,13 +103,13 @@
     "node": ">= 12.22.0 < 13 || >= 14.17.0 < 15 || >= 15.12.0 < 16 || >= 16.0.0"
   },
   "optionalDependencies": {
-    "@takumi-rs/core-darwin-x64": "1.8.7",
-    "@takumi-rs/core-darwin-arm64": "1.8.7",
-    "@takumi-rs/core-linux-arm64-gnu": "1.8.7",
-    "@takumi-rs/core-linux-arm64-musl": "1.8.7",
-    "@takumi-rs/core-win32-arm64-msvc": "1.8.7",
-    "@takumi-rs/core-linux-x64-gnu": "1.8.7",
-    "@takumi-rs/core-linux-x64-musl": "1.8.7",
-    "@takumi-rs/core-win32-x64-msvc": "1.8.7"
+    "@takumi-rs/core-darwin-x64": "2.0.0-beta.1",
+    "@takumi-rs/core-darwin-arm64": "2.0.0-beta.1",
+    "@takumi-rs/core-linux-arm64-gnu": "2.0.0-beta.1",
+    "@takumi-rs/core-linux-arm64-musl": "2.0.0-beta.1",
+    "@takumi-rs/core-win32-arm64-msvc": "2.0.0-beta.1",
+    "@takumi-rs/core-linux-x64-gnu": "2.0.0-beta.1",
+    "@takumi-rs/core-linux-x64-musl": "2.0.0-beta.1",
+    "@takumi-rs/core-win32-x64-msvc": "2.0.0-beta.1"
   }
 }