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

package/dist/export.d.cts

@@ -20,6 +20,12 @@ 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;
 }
 type Font = FontDetails | ByteBuf;
 type KeyframesMap = Record<string, Record<string, Properties>>;
@@ -31,29 +37,6 @@ type KeyframesRuleList = {
   }[];
 }[];
 type Keyframes = KeyframesMap | KeyframesRuleList;
-/** The main renderer for Takumi image rendering engine (Node.js version). */
-declare class Renderer$1 {
-  /** 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;
-  /** Renders a node tree into an image buffer asynchronously. */
-  render(source: Node, options?: RenderOptions, signal?: AbortSignal): Promise<Buffer>;
-  /** 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. */
-  renderAnimation(options: RenderAnimationOptions, signal?: AbortSignal): Promise<Buffer>;
-  /** Encodes a precomputed frame sequence into an animated image buffer asynchronously. */
-  encodeFrames(source: AnimationFrameSource[], options: EncodeFramesOptions, signal?: AbortSignal): Promise<Buffer>;
-}
 /** Represents a single frame in a precomputed animation sequence. */
 interface AnimationFrameSource {
   /** The node tree to render for this frame. */
@@ -70,21 +53,9 @@ interface AnimationSceneSource {
   /** The duration of this scene in milliseconds. */
   durationMs: number;
 }
-/** Options for constructing a Renderer instance. */
-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;
-}
 type DitheringAlgorithm = 'none' | 'ordered-bayer' | 'floyd-steinberg';
 /** Options for encoding a precomputed frame sequence. */
-interface EncodeFramesOptions {
+interface EncodeFramesOptions$1 {
   /** Whether to draw debug borders around layout elements. */
   drawDebugBorder?: boolean;
   /** The width of each frame in pixels. */
@@ -93,10 +64,18 @@ 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>;
   /**
@@ -104,13 +83,22 @@ 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"`. */
+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. */
 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. */
 interface MeasuredNode {
@@ -140,8 +128,26 @@ interface MeasuredTextRun {
 }
 /** Output format for static images. */
 type OutputFormat = /** WebP format. */'webp' | /** PNG format. */'png' | /** JPEG format. */'jpeg' | /** ICO format. */'ico' | /** Raw pixels format. */'raw';
+/** A single face within a `RegisteredFamily`. */
+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. */
+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. */
-interface RenderAnimationOptions {
+interface RenderAnimationOptions$1 {
   /** The scenes to render sequentially. */
   scenes: Array<AnimationSceneSource>;
   /** Whether to draw debug borders around layout elements. */
@@ -152,12 +158,20 @@ 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>;
   /**
@@ -165,21 +179,34 @@ 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. */
-interface RenderOptions {
+interface RenderOptions$1 {
   /** The width of the image. If not provided, the width will be automatically calculated based on the content. */
   width?: number;
   /** The height of the image. If not provided, the height will be automatically calculated based on the content. */
   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. */
@@ -193,36 +220,116 @@ 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.
+ */
+interface SvgRenderOptions$1 {
+  /** 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>;
 }
 //#endregion
 //#region src/export.d.ts
-type ImageSourceLoader = Omit<ImageSource, "data"> & {
-  data: ImageSource["data"] | (() => Promise<ImageSource["data"]> | ImageSource["data"]);
-};
 type FontLoader = Font | (Omit<FontDetails, "data"> & {
-  key?: string;
-  data: FontDetails["data"] | (() => Promise<FontDetails["data"]> | FontDetails["data"]);
-});
-type ImageSourceLoaderSync = Omit<ImageSource, "data"> & {
-  data: ImageSource["data"] | (() => ImageSource["data"]);
+  data: () => Promise<FontDetails["data"]> | FontDetails["data"];
+} & ({
+  key: string;
+} | {
+  name: string;
+}));
+type ImageLoaderData = ImageSource["data"];
+type ImageLoader = Omit<ImageSource, "data"> & {
+  data: ImageLoaderData | (() => ImageLoaderData | Promise<ImageLoaderData>);
+};
+/**
+ * Output format. Format-specific options live on the variant that supports them,
+ * so `quality` cannot be paired with PNG/ICO/raw, and `lossless` is WebP-only.
+ * For WebP, `lossless` takes precedence over `quality`; omitting both encodes
+ * losslessly.
+ */
+type OutputFormatOptions = {
+  format?: "png";
+} | {
+  format: "jpeg";
+  quality?: number;
+} | {
+  format: "webp";
+  quality?: number;
+  lossless?: boolean;
+} | {
+  format: "ico";
+} | {
+  format: "raw";
+};
+type RenderOptions = Omit<RenderOptions$1, "images" | "format" | "quality" | "lossless"> & OutputFormatOptions & {
+  fonts?: FontLoader[];
+  signal?: AbortSignal;
+  images?: ImageLoader[];
+};
+/**
+ * Animation output format. `quality` and `lossless` are WebP-only; for WebP,
+ * `lossless` takes precedence over `quality`, and omitting both encodes
+ * losslessly.
+ */
+type AnimationOutputFormatOptions = {
+  format?: "webp";
+  quality?: number;
+  lossless?: boolean;
+} | {
+  format: "apng";
+} | {
+  format: "gif";
+};
+type RenderAnimationOptions = Omit<RenderAnimationOptions$1, "images" | "format" | "quality" | "lossless"> & AnimationOutputFormatOptions & {
+  fonts?: FontLoader[];
+  signal?: AbortSignal;
+  images?: ImageLoader[];
+};
+type EncodeFramesOptions = Omit<EncodeFramesOptions$1, "images" | "format" | "quality" | "lossless"> & AnimationOutputFormatOptions & {
+  fonts?: FontLoader[];
+  signal?: AbortSignal;
+  images?: ImageLoader[];
+};
+type SvgRenderOptions = Omit<SvgRenderOptions$1, "images"> & {
+  fonts?: FontLoader[];
+  signal?: AbortSignal;
+  images?: ImageLoader[];
 };
-type FontLoaderSync = Font | (Omit<FontDetails, "data"> & {
-  key?: string;
-  data: FontDetails["data"] | (() => FontDetails["data"]);
-});
-declare class Renderer extends Renderer$1 {
-  private fontsMark;
-  private fontBuffersMark;
-  private persistentImageSrcMark;
-  private pendingPersistentImages;
-  putPersistentImage(source: ImageSourceLoader, signal?: AbortSignal): Promise<void>;
-  loadFonts(fonts: FontLoader[], signal?: AbortSignal): Promise<number>;
-  loadFont(data: FontLoader, signal?: AbortSignal): Promise<number>;
-  loadFontSync(font: FontLoaderSync): void;
-  clearImageStore(): void;
-  private checkAndMarkFont;
-  private isNewFont;
-  private isNewPersistentImage;
+declare class Renderer {
+  private fontMapping;
+  private inner;
+  private prepareFonts;
+  /** Registers `fonts` and resolves lazy `images`, yielding the `images`/`fontFamilies`
+   * the napi binding expects. Explicit `fontFamilies` wins over the registered set. */
+  private resolveResources;
+  render(node: Node, options?: RenderOptions): Promise<Buffer>;
+  renderSvg(node: Node, options?: SvgRenderOptions): Promise<string>;
+  measure(node: Node, options?: RenderOptions): Promise<MeasuredNode>;
+  renderAnimation(options: RenderAnimationOptions): Promise<Buffer>;
+  encodeFrames(frames: AnimationFrameSource[], options: EncodeFramesOptions): Promise<Buffer>;
+  registerFont(font: FontLoader): Promise<any>;
 }
 //#endregion
-export { type AnimationFrameSource, type AnimationOutputFormat, type AnimationSceneSource, type ByteBuf, type ConstructRendererOptions, type ContainerNode, type DitheringAlgorithm, type EncodeFramesOptions, type Font, type FontDetails, FontLoader, FontLoaderSync, type ImageNode, type ImageSource, ImageSourceLoader, ImageSourceLoaderSync, type Keyframes, type KeyframesMap, type KeyframesRuleList, type MeasuredNode, type MeasuredTextRun, type Node, type NodeMetadata, type OutputFormat, type RenderAnimationOptions, type RenderOptions, Renderer, type TextNode, extractResourceUrls };
+export { type AnimationFrameSource, type AnimationOutputFormat, AnimationOutputFormatOptions, type AnimationSceneSource, type ByteBuf, type ContainerNode, type DitheringAlgorithm, EncodeFramesOptions, type Font, type FontDetails, FontLoader, type ImageCacheMode, ImageLoader, type ImageNode, type ImageSource, type Keyframes, type KeyframesMap, type KeyframesRuleList, type MeasuredNode, type MeasuredTextRun, type Node, type NodeMetadata, type OutputFormat, OutputFormatOptions, type RegisteredFace, type RegisteredFamily, RenderAnimationOptions, RenderOptions, Renderer, SvgRenderOptions, type TextNode, extractResourceUrls };