@grida/canvas-wasm 0.0.56 → 0.0.57

package/dist/index.d.ts

@@ -1,274 +1,299 @@
-///
-/// @grida/canvas-wasm grida-canvas-wasm.js typescript definitions
-/// this is NOT generated by emscripten. update manually.
-///
-/// see also:
-/// - https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/emscripten/index.d.ts
-///
+declare namespace fonts {
+  export namespace types {
+    // ====================================================================================================
+    // #region: Core Type Definitions
+    // ====================================================================================================
 
+    /** Axis value pair for variable font recipes */
+    export interface AxisValue {
+      tag: string;
+      value: number;
+    }
 
+    /** Family-level axis information (no default values as they vary per face) */
+    export interface FontFamilyAxis {
+      tag: string;
+      name: string;
+      min: number;
+      max: number;
+    }
 
-type Ptr = number;
+    /** Face-specific axis information (includes default values) */
+    export interface FontAxis {
+      tag: string;
+      name: string;
+      min: number;
+      default: number;
+      max: number;
+    }
 
-declare function createGridaCanvas(moduleArg?: {
-  locateFile?: (path: string, scriptDirectory: string) => string;
-}): Promise<createGridaCanvas.GridaCanvasWasmBindings>;
+    /** Variable font recipe */
+    export interface VfRecipe {
+      axis_values: Array<AxisValue>;
+    }
 
-declare namespace createGridaCanvas {
-  interface GridaCanvasWasmBindings {
-    // #region
-    // ====================================================================================================
-    // EMSCRIPTEN EXPOSED METHODS
-    // ====================================================================================================
-    GL: {
-      registerContext(
-        context: WebGLRenderingContext,
-        options: { majorVersion: number }
-      ): number;
-      makeContextCurrent(handle: number): void;
-    };
+    /** Italic recipe for UI consumption */
+    export interface ItalicRecipe {
+      name: string;
+      description: string;
+      is_italic: boolean;
+      face_id: string;
+      vf_recipe?: VfRecipe;
+    }
+
+    /** Italic capability analysis for UI consumption */
+    export interface ItalicCapability {
+      has_italic: boolean;
+      has_upright: boolean;
+      strategy: string;
+      recipes: Array<ItalicRecipe>;
+      scenario: string;
+    }
+
+    /** Variable font instance information */
+    export interface FontInstance {
+      name: string;
+      postscript_name: string | null;
+      coordinates: Record<string, number>;
+    }
 
-    HEAP8: Int8Array;
-    HEAP16: Int16Array;
-    HEAP32: Int32Array;
-    HEAPF32: Float32Array;
-    HEAPF64: Float64Array;
-    HEAPU8: Uint8Array;
-    HEAPU16: Uint16Array;
-    HEAPU32: Uint32Array;
+    /** Font feature information for UI consumption */
+    export interface FontFeature {
+      tag: string;
+      name: string;
+      tooltip: string | null;
+      sample_text: string | null;
+      glyphs: string[];
+      script: string;
+      language: string;
+      source_table: string;
+    }
 
-    UTF8ToString(ptr: number, maxBytesToRead?: number): string;
-    stringToUTF8(str: string, outPtr: number, maxBytesToWrite: number): void;
-    lengthBytesUTF8(str: string): number;
+    /** Face-level information for UI consumption */
+    export interface FontFaceInfo {
+      face_id: string;
+      family_name: string;
+      subfamily_name: string;
+      postscript_name: string;
+      weight_class: number;
+      width_class: number;
+      is_variable: boolean;
+      is_strict_italic: boolean;
+      axes: Array<FontAxis>;
+      instances?: Array<FontInstance>;
+      features: Array<FontFeature>;
+    }
 
-    ___wbindgen_malloc(a0: number, a1: number): number;
-    ___wbindgen_free(a0: number, a1: number, a2: number): void;
-    ___wbindgen_realloc(a0: number, a1: number, a2: number, a3: number): number;
+    /** Font style instance for UI consumption */
+    export interface FontStyle {
+      name: string;
+      postscript_name: string | null;
+      italic: boolean;
+    }
 
-    // #endregion
+    /** Complete family-level analysis result for UI consumption */
+    export interface FontFamilyAnalysisResult {
+      family_name: string;
+      axes: Array<FontFamilyAxis>;
+      italic_capability: ItalicCapability;
+      faces: Array<FontFaceInfo>;
+      styles: Array<FontStyle>;
+    }
 
-    // core memory wrapper
-    _allocate(len: number): number;
-    _deallocate(ptr: number, len: number): void;
+    export type FontFamilyAnalysisResponse =
+      | {
+          success: true;
+          data: FontFamilyAnalysisResult;
+        }
+      | FontError;
 
+    /** Face record for single font parsing */
+    export interface FaceRecord {
+      face_id: string;
+      ps_name: string;
+      family_name: string;
+      subfamily_name: string;
+      is_variable: boolean;
+      os2_italic_bit: boolean;
+      weight_class: number;
+      width_class: number;
+      user_font_style_italic: boolean | null;
+      axes_count: number;
+    }
+
+    /** Error response for failed operations */
+    export interface FontError {
+      success: false;
+      error: {
+        message: string;
+      };
+    }
+  }
+
+  // ====================================================================================================
+  // #region: WASM Function Declarations
+  // ====================================================================================================
+
+  export interface FontsModule {
     // ====================================================================================================
-    // INITIALIZATION
+    // #region: Core Font Analysis APIs
     // ====================================================================================================
-    _init(
-      width: number,
-      height: number,
-      use_embedded_fonts: boolean
-    ): GridaCanvasWebGlApplicationPtr;
+
+    /**
+     * Analyzes a font family and returns comprehensive family information as JSON.
+     * This is the main API for working with multiple font files under the same family.
+     *
+     * @param family_name - Family name (can be null for auto-detection)
+     * @param font_count - Number of font faces
+     * @param face_ids - Array of face IDs (null-terminated strings)
+     * @param font_data_ptrs - Array of pointers to font data
+     * @param font_data_sizes - Array of font data sizes
+     * @param user_italic_flags - Array of user italic declarations (-1 = null, 0 = false, 1 = true)
+     * @returns JSON string containing {@link FontFamilyAnalysisResponse}
+     */
+    _grida_fonts_analyze_family(
+      family_name: number | null,
+      font_count: number,
+      face_ids: number,
+      font_data_ptrs: number,
+      font_data_sizes: number,
+      user_italic_flags: number | null
+    ): number;
+
+    /**
+     * Parses a single font file and extracts basic metadata.
+     * This is exposed for fast, single font analysis.
+     *
+     * @param font_data_ptr - Pointer to font data
+     * @param font_data_size - Size of font data
+     * @param face_id - Unique identifier for this font face
+     * @param user_font_style_italic - User-declared italic style (can be null for auto-detection)
+     * @returns JSON string containing FaceRecord
+     */
+    _grida_fonts_parse_font(
+      font_data_ptr: number,
+      font_data_size: number,
+      face_id: number,
+      user_font_style_italic: number | null
+    ): number;
 
     // ====================================================================================================
-    // APPLICATION METHODS
+    // #region: Utility Functions
     // ====================================================================================================
-    _tick(state: GridaCanvasWebGlApplicationPtr, time: number): void;
-    _resize_surface(
-      state: GridaCanvasWebGlApplicationPtr,
-      width: number,
-      height: number
-    ): void;
-    _redraw(state: GridaCanvasWebGlApplicationPtr): void;
-    _load_scene_json(
-      state: GridaCanvasWebGlApplicationPtr,
-      ptr: number,
-      len: number
-    ): void;
-    _load_dummy_scene(state: GridaCanvasWebGlApplicationPtr): void;
-    _load_benchmark_scene(
-      state: GridaCanvasWebGlApplicationPtr,
-      cols: number,
-      rows: number
-    ): void;
-    _pointer_move(
-      state: GridaCanvasWebGlApplicationPtr,
-      x: number,
-      y: number
-    ): void;
-    _add_font(
-      state: GridaCanvasWebGlApplicationPtr,
-      family_ptr: number,
-      family_len: number,
-      data_ptr: number,
-      data_len: number
-    ): void;
-    _add_image(
-      state: GridaCanvasWebGlApplicationPtr,
-      data_ptr: number,
-      data_len: number
-    ): Ptr;
-    _has_missing_fonts(state: GridaCanvasWebGlApplicationPtr): boolean;
-    _list_missing_fonts(state: GridaCanvasWebGlApplicationPtr): Ptr;
-    _list_available_fonts(state: GridaCanvasWebGlApplicationPtr): Ptr;
-    _set_default_fallback_fonts(
-      state: GridaCanvasWebGlApplicationPtr,
-      ptr: number,
-      len: number
-    ): void;
-    _get_default_fallback_fonts(state: GridaCanvasWebGlApplicationPtr): Ptr;
-    _set_main_camera_transform(
-      state: GridaCanvasWebGlApplicationPtr,
-      a: number,
-      c: number,
-      e: number,
-      b: number,
-      d: number,
-      f: number
-    ): void;
-    _get_node_id_from_point(
-      state: GridaCanvasWebGlApplicationPtr,
-      x: number,
-      y: number
-    ): Ptr;
-    _get_node_ids_from_point(
-      state: GridaCanvasWebGlApplicationPtr,
-      x: number,
-      y: number
-    ): Ptr;
-    _get_node_ids_from_envelope(
-      state: GridaCanvasWebGlApplicationPtr,
-      x: number,
-      y: number,
-      w: number,
-      h: number
-    ): Ptr;
-    _get_node_absolute_bounding_box(
-      state: GridaCanvasWebGlApplicationPtr,
-      ptr: number,
-      len: number
-    ): Ptr;
 
-    _export_node_as(
-      state: GridaCanvasWebGlApplicationPtr,
-      id_ptr: number,
-      id_len: number,
-      fmt_ptr: number,
-      fmt_len: number
-    ): Ptr;
+    /**
+     * Frees memory allocated by WASM functions.
+     *
+     * @param ptr - Pointer to memory allocated by a WASM function
+     */
+    _grida_fonts_free(ptr: number): void;
+
+    /**
+     * Returns the version of the font parsing library.
+     * This is a ping function to verify the WASM module is working.
+     *
+     * @returns Version string
+     */
+    _grida_fonts_version(): number;
+  }
+}
 
-    _to_vector_network(
-      state: GridaCanvasWebGlApplicationPtr,
-      id_ptr: number,
-      id_len: number
-    ): Ptr;
+///
+/// @grida/canvas-wasm grida-canvas-wasm.js typescript definitions
+/// this is NOT generated by emscripten. update manually.
+///
+/// see also:
+/// - https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/emscripten/index.d.ts
+///
 
-    _command(
-      state: GridaCanvasWebGlApplicationPtr,
-      id: number,
-      a: number,
-      b: number
-    ): void;
 
-    _highlight_strokes(
-      state: GridaCanvasWebGlApplicationPtr,
-      ptr: number,
-      len: number
-    ): void;
 
-    _set_debug(state: GridaCanvasWebGlApplicationPtr, debug: boolean): void;
-    _toggle_debug(state: GridaCanvasWebGlApplicationPtr): void;
-    _set_verbose(state: GridaCanvasWebGlApplicationPtr, verbose: boolean): void;
-    _devtools_rendering_set_show_tiles(
-      state: GridaCanvasWebGlApplicationPtr,
-      show: boolean
-    ): void;
-    _devtools_rendering_set_show_fps_meter(
-      state: GridaCanvasWebGlApplicationPtr,
-      show: boolean
-    ): void;
-    _devtools_rendering_set_show_stats(
-      state: GridaCanvasWebGlApplicationPtr,
-      show: boolean
-    ): void;
-    _devtools_rendering_set_show_hit_testing(
-      state: GridaCanvasWebGlApplicationPtr,
-      show: boolean
-    ): void;
-    _devtools_rendering_set_show_ruler(
-      state: GridaCanvasWebGlApplicationPtr,
-      show: boolean
-    ): void;
+declare function createGridaCanvas$1(moduleArg?: {
+  locateFile?: (path: string, scriptDirectory: string) => string;
+}): Promise<createGridaCanvas$1.GridaCanvasWasmBindings>;
 
-    _runtime_renderer_set_cache_tile(
-      state: GridaCanvasWebGlApplicationPtr,
-      enabled: boolean
-    ): void;
-  }
+declare namespace createGridaCanvas$1 {
+  interface GridaCanvasWasmBindings
+    extends emscripten.emscripten_EXPORTED_RUNTIME_METHODS,
+      canvas.CanvasModule,
+      fonts.FontsModule {}
 }
 
-type GridaCanvasWebGlApplicationPtr = number;
-
-interface GridaCanvasModuleInitOptions {
+declare class FontsAPI {
+    private module;
+    constructor(module: any);
     /**
-     * This callback will be invoked when the loader needs to fetch a file (e.g.
-     * the blob of WASM code). The correct url prefix should be applied.
-     * @param file - the name of the file that is about to be loaded.
+     * Allocates memory for a string and returns pointer and length.
+     * @param txt - String to allocate
+     * @returns [pointer, length] tuple
+     */
+    private _alloc_string;
+    /**
+     * Frees memory allocated for a string.
+     * @param ptr - Pointer to free
+     * @param len - Length of allocated memory
+     */
+    private _free_string;
+    /**
+     * Allocates memory for binary data and returns pointer.
+     * @param data - Binary data to allocate
+     * @returns [pointer, length] tuple
+     */
+    private _alloc_data;
+    /**
+     * Converts a WASM-allocated string to JavaScript string and frees the WASM memory.
+     * @param ptr - Pointer to WASM string
+     * @returns JavaScript string
+     */
+    private _string_from_wasm;
+    /**
+     * Analyzes a font family with JavaScript-friendly interface.
+     * This is the main API for working with multiple font files under the same family.
      *
-     * @example
-     * ```ts
-     * locateFile: (file) => `https://unpkg.com/@grida/canvas-wasm@$latest/bin/${file}`,
-     * locateFile: (file) => `custom-binary-path/${file}`,
-     * ```
+     * @param fontFaces - Array of font face objects
+     * @param familyName - Family name (optional)
+     * @returns Promise resolving to FontAnalysisResult or FontError
      */
-    locateFile(file: string, version: string): string;
-}
-type Vector2 = [number, number];
-type Transform2D = [[number, number, number], [number, number, number]];
-type Rectangle = {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-type ExportConstraints = {
-    type: "SCALE" | "WIDTH" | "HEIGHT";
-    value: number;
-};
-type ExportAs = ExportAsImage | ExportAsPDF | ExportAsSVG;
-type ExportAsPDF = {
-    format: "PDF";
-};
-type ExportAsSVG = {
-    format: "SVG";
-};
-type ExportAsImage = {
-    format: "PNG" | "JPEG" | "WEBP" | "BMP";
-    constraints: ExportConstraints;
-};
-type FontKey = {
-    family: string;
-};
-type VectorNetworkVertex = Vector2;
-type VectorNetworkSegment = {
-    a: number;
-    b: number;
-    ta: Vector2;
-    tb: Vector2;
-};
-interface VectorNetwork {
-    vertices: VectorNetworkVertex[];
-    segments: VectorNetworkSegment[];
-}
-declare function init(opts?: GridaCanvasModuleInitOptions): Promise<ApplicationFactory>;
-interface CreateWebGLCanvasSurfaceOptions {
+    analyzeFamily(fontFaces: Array<{
+        faceId: string;
+        data: ArrayBuffer | Uint8Array;
+        userFontStyleItalic?: boolean;
+    }>, familyName?: string): Promise<fonts.types.FontFamilyAnalysisResponse>;
     /**
-     * when true, embedded fonts will be registered and used for text rendering.
-     * @default true
+     * Parses a single font file with JavaScript-friendly interface.
+     * This is exposed for fast, single font analysis.
+     *
+     * @param fontData - Font data as ArrayBuffer or Uint8Array
+     * @param faceId - Unique identifier for this font face
+     * @param userFontStyleItalic - User-declared italic style (optional)
+     * @returns Promise resolving to FaceRecord
      */
-    use_embedded_fonts?: boolean;
-}
-declare class ApplicationFactory {
-    private readonly module;
-    constructor(module: createGridaCanvas.GridaCanvasWasmBindings);
-    createWebGLCanvasSurface(canvas: HTMLCanvasElement, options?: CreateWebGLCanvasSurfaceOptions): Grida2D;
-    createWebGLCanvasSurfaceById(htmlcanvasid: string): Grida2D;
+    parseFont(fontData: ArrayBuffer | Uint8Array, faceId: string, userFontStyleItalic?: boolean): Promise<fonts.types.FaceRecord>;
+    /**
+     * Gets the version of the font parsing library.
+     * This is a ping function to verify the WASM module is working.
+     *
+     * @returns Version string
+     */
+    getVersion(): string;
 }
-declare class Grida2D {
+
+declare class Scene {
     private appptr;
     private module;
+    readonly fontskit: FontsAPI;
     constructor(module: createGridaCanvas.GridaCanvasWasmBindings, ptr: number);
+    /**
+     * Allocates memory for a string and returns pointer and length.
+     * @param txt - String to allocate
+     * @returns [pointer, length] tuple
+     */
     _alloc_string(txt: string): [number, number];
+    /**
+     * Frees memory allocated for a string.
+     * @param ptr - Pointer to free
+     * @param len - Length of allocated memory
+     */
     _free_string(ptr: number, len: number): void;
     /**
      * Load a scene from a JSON string.
@@ -295,8 +320,8 @@ declare class Grida2D {
     addFont(family: string, data: Uint8Array): void;
     addImage(data: Uint8Array): string;
     hasMissingFonts(): boolean;
-    listMissingFonts(): FontKey[];
-    listAvailableFonts(): FontKey[];
+    listMissingFonts(): types.FontKey[];
+    listAvailableFonts(): types.FontKey[];
     setFallbackFonts(fonts: string[]): void;
     getFallbackFonts(): string[];
     /**
@@ -313,16 +338,16 @@ declare class Grida2D {
      */
     resize(width: number, height: number): void;
     redraw(): void;
-    setMainCameraTransform(transform: Transform2D): void;
+    setMainCameraTransform(transform: types.Transform2D): void;
     getNodeIdFromPoint(x: number, y: number): string | null;
     getNodeIdsFromPoint(x: number, y: number): string[];
-    getNodeIdsFromEnvelope(envelope: Rectangle): string[];
-    getNodeAbsoluteBoundingBox(id: string): Rectangle | null;
+    getNodeIdsFromEnvelope(envelope: types.Rectangle): string[];
+    getNodeAbsoluteBoundingBox(id: string): types.Rectangle | null;
     /**
      * @deprecated not fully implemented yet
      */
-    toVectorNetwork(id: string): VectorNetwork | null;
-    exportNodeAs(id: string, format: ExportAs): {
+    toVectorNetwork(id: string): types.VectorNetwork | null;
+    exportNodeAs(id: string, format: types.ExportAs): {
         data: Uint8Array;
     };
     execCommand(command: "ZoomIn" | "ZoomOut"): void;
@@ -367,4 +392,84 @@ declare class Grida2D {
     devtools_rendering_set_show_ruler(show: boolean): void;
 }
 
-export { type FontKey, Grida2D, type GridaCanvasModuleInitOptions, init as default };
+declare const version: string;
+interface GridaCanvasModuleInitOptions {
+    /**
+     * This callback will be invoked when the loader needs to fetch a file (e.g.
+     * the blob of WASM code). The correct url prefix should be applied.
+     * @param file - the name of the file that is about to be loaded.
+     *
+     * @example
+     * ```ts
+     * locateFile: (file) => `https://unpkg.com/@grida/canvas-wasm@$latest/bin/${file}`,
+     * locateFile: (file) => `custom-binary-path/${file}`,
+     * ```
+     */
+    locateFile(file: string, version: string): string;
+}
+declare namespace types {
+    type Vector2 = [number, number];
+    type Transform2D = [
+        [
+            number,
+            number,
+            number
+        ],
+        [
+            number,
+            number,
+            number
+        ]
+    ];
+    type Rectangle = {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    type ExportConstraints = {
+        type: "SCALE" | "WIDTH" | "HEIGHT";
+        value: number;
+    };
+    type ExportAs = ExportAsImage | ExportAsPDF | ExportAsSVG;
+    type ExportAsPDF = {
+        format: "PDF";
+    };
+    type ExportAsSVG = {
+        format: "SVG";
+    };
+    type ExportAsImage = {
+        format: "PNG" | "JPEG" | "WEBP" | "BMP";
+        constraints: ExportConstraints;
+    };
+    type FontKey = {
+        family: string;
+    };
+    type VectorNetworkVertex = Vector2;
+    type VectorNetworkSegment = {
+        a: number;
+        b: number;
+        ta: Vector2;
+        tb: Vector2;
+    };
+    interface VectorNetwork {
+        vertices: VectorNetworkVertex[];
+        segments: VectorNetworkSegment[];
+    }
+}
+declare function init(opts?: GridaCanvasModuleInitOptions): Promise<ApplicationFactory>;
+interface CreateWebGLCanvasSurfaceOptions {
+    /**
+     * when true, embedded fonts will be registered and used for text rendering.
+     * @default true
+     */
+    use_embedded_fonts?: boolean;
+}
+declare class ApplicationFactory {
+    readonly module: createGridaCanvas$1.GridaCanvasWasmBindings;
+    constructor(module: createGridaCanvas$1.GridaCanvasWasmBindings);
+    createWebGLCanvasSurface(canvas: HTMLCanvasElement, options?: CreateWebGLCanvasSurfaceOptions): Scene;
+    createWebGLCanvasSurfaceById(htmlcanvasid: string): Scene;
+}
+
+export { type GridaCanvasModuleInitOptions, Scene, init as default, types, version };