Add per-file TypeScript definitions and update docs

Introduced individual .d.ts files alongside each source file in src/ and extras/jsm/zui.d.ts, replacing the previous monolithic types.d.ts (now removed). Updated documentation in CLAUDE.md to reflect the new TypeScript definition structure and improved TypeScript compilation instructions. Updated build outputs and package.json accordingly.

Author: jonobr1

CLAUDE.md

@@ -87,15 +87,16 @@ The Two class provides factory methods for creating and adding objects to the sc
 
 ### Running Tests
 - Manual browser testing via HTML files: `tests/index.html` and `tests/noWebGL.html`
-- TypeScript compilation testing: `cd tests/typescript && npx tsc index.ts` to verify types work correctly
+- TypeScript compilation testing: `npx tsc --noEmit --skipLibCheck tests/typescript/index.ts` to verify types work correctly
 
 ## Key Files to Understand
 
 - `src/two.js` - Main class with factory methods and core logic
 - `src/constants.js` - Global constants, types, and configuration
 - `src/utils/interpret-svg.js` - SVG parsing and import functionality
 - `utils/build.js` - Build system configuration
-- `types.d.ts` - TypeScript definitions for the entire library
+- `src/**/*.d.ts` - TypeScript definitions collocated with source files (e.g., `src/vector.d.ts` alongside `src/vector.js`)
+- `src/two.d.ts` - Main TypeScript entry point that aggregates all type exports
 
 ## Dependencies
 
@@ -151,7 +152,7 @@ Designed for modern browsers with ES6+ support. Uses feature detection for rende
 - Open `tests/index.html` in browser for manual testing
 - Test new features across Canvas, SVG, and WebGL renderers
 - Check `tests/noWebGL.html` for fallback scenarios
-- TypeScript compilation tests: Run `cd tests/typescript && npx tsc index.ts` to verify TypeScript definitions work correctly
+- TypeScript compilation tests: Run `npx tsc --noEmit --skipLibCheck tests/typescript/index.ts` to verify TypeScript definitions work correctly
 - Manual browser testing required - no automated test runner
 
 ## File Organization Rules
@@ -160,7 +161,10 @@ Designed for modern browsers with ES6+ support. Uses feature detection for rende
 - Effects belong in `src/effects/`
 - Utilities in `src/utils/` should be pure functions
 - Export new classes in `src/two.js` main file
-- Add TypeScript definitions to `types.d.ts`
+- **TypeScript definitions**: Create a `.d.ts` file alongside each source file (e.g., `src/vector.d.ts` next to `src/vector.js`)
+  - Each `.d.ts` file contains a `declare module 'two.js/src/...'` block matching the module path
+  - Import statements go at the END of the module declaration
+  - Main type exports are aggregated in `src/two.d.ts`
 - Renderers are in `src/renderers/` - modify with caution
 
 ## Performance Guidelines

build/two.js

@@ -1220,7 +1220,7 @@ var Two = (() => {
      * @name Two.PublishDate
      * @property {String} - The automatically generated publish date in the build process to verify version release candidates.
      */
-    PublishDate: "2025-12-22T19:56:52.386Z",
+    PublishDate: "2026-01-05T18:28:31.207Z",
     /**
      * @name Two.Identifier
      * @property {String} - String prefix for all Two.js object's ids. This trickles down to SVG ids.

build/two.min.js

@@ -1228,7 +1228,7 @@ var Constants = {
    * @name Two.PublishDate
    * @property {String} - The automatically generated publish date in the build process to verify version release candidates.
    */
-  PublishDate: "2025-12-22T19:56:52.386Z",
+  PublishDate: "2026-01-05T18:28:31.207Z",
   /**
    * @name Two.Identifier
    * @property {String} - String prefix for all Two.js object's ids. This trickles down to SVG ids.

build/two.module.js

@@ -0,0 +1,73 @@
+declare module 'two.js/extras/jsm/zui' {
+  /**
+   * @name Two.ZUI
+   * @class
+   * @param {Group} group - The scene or group to
+   * @param {HTMLElement} [domElement=document.body] - The HTML Element to attach event listeners to.
+   */
+  export class ZUI {
+    static Surface: Surface;
+    static Clamp(v: any, min: any, max: any): number;
+    static Limit: {
+      min: number;
+      max: number;
+      clone: () => {};
+    };
+    static TranslateMatrix(m: any, x: any, y: any): any;
+    static PositionToScale(pos: any): number;
+    static ScaleToPosition(scale: any): number;
+    constructor(group?: Group, domElement?: HTMLElement);
+    limits: {
+      scale: {};
+      x: {};
+      y: {};
+    };
+    viewport: any;
+    viewportOffset: {
+      top: number;
+      left: number;
+      matrix: Matrix;
+    };
+    surfaceMatrix: Matrix;
+    surfaces: any[];
+    add(surface: any): ZUI;
+    addLimits(min: number, max: number, type?: number): ZUI;
+    clientToSurface(v?: { x?: number; y?: number; z?: number }): {
+      x: number;
+      y: number;
+      z: number;
+    };
+    surfaceToClient(v?: { x?: number; y?: number; z?: number }): {
+      x: number;
+      y: number;
+      z: number;
+    };
+    zoomBy(byF: any, clientX: any, clientY: any): ZUI;
+    zoomSet(zoom: any, clientX: any, clientY: any): ZUI;
+    zoom: number;
+    scale: any;
+    translateSurface(x: any, y: any): ZUI;
+    updateOffset(): ZUI;
+    updateSurface(): ZUI;
+    reset(): ZUI;
+    fitToLimits(s: any): number;
+  }
+  import { Matrix } from 'two.js/src/matrix';
+  import { Group } from 'two.js/src/group';
+  class Surface {
+    constructor(object: any);
+    object: any;
+    limits(
+      min: any,
+      max: any
+    ):
+      | Surface
+      | {
+          min: any;
+          max: any;
+        };
+    min: any;
+    max: any;
+    apply(px: any, py: any, s: any): Surface;
+  }
+}

extras/jsm/zui.d.ts

@@ -3,15 +3,14 @@
   "version": "v0.8.23",
   "description": "A renderer agnostic two-dimensional drawing api for the web.",
   "module": "build/two.module.js",
-  "types": "types.d.ts",
+  "types": "src/two.d.ts",
   "files": [
     "package.json",
     "LICENSE",
     "README.md",
     "build",
     "extras",
-    "src",
-    "types.d.ts"
+    "src"
   ],
   "scripts": {
     "build": "node ./utils/build",

package.json

@@ -0,0 +1,95 @@
+declare module 'two.js/src/anchor' {
+  /**
+     * @class
+     * @name Two.Anchor
+     * @param {Number} [x=0] - The x position of the root anchor point.
+     * @param {Number} [y=0] - The y position of the root anchor point.
+     * @param {Number} [ax=0] - The x position of the left handle point.
+     * @param {Number} [ay=0] - The y position of the left handle point.
+     * @param {Number} [bx=0] - The x position of the right handle point.
+     * @param {Number} [by=0] - The y position of the right handle point.
+     * @param {String} [command=Two.Commands.move] - The command to describe how to render. Applicable commands are {@link Two.Commands}
+
+     * @description An object that holds 3 {@link Two.Vector}s, the anchor point and its corresponding handles: `left` and `right`. In order to properly describe the bezier curve about the point there is also a command property to describe what type of drawing should occur when Two.js renders the anchors.
+     */
+  export class Anchor extends Vector {
+    static makeBroadcast(scope: Anchor): () => void;
+    /**
+     * @name Two.Anchor.fromObject
+     * @function
+     * @param {Object} obj - Object notation of a {@link Two.Anchor} to create a new instance
+     * @returns {Two.Anchor}
+     * @description Create a new {@link Two.Anchor} from an object notation of a {@link Two.Anchor}.
+     * @nota-bene Works in conjunction with {@link Two.Anchor#toObject}
+     */
+    static fromObject(
+      obj:
+        | object
+        | {
+            x?: number;
+            y?: number;
+            command?: Commands[keyof Commands];
+            relative?: boolean;
+            controls?: {
+              left: { x: number; y: number } | Vector;
+              right: { x: number; y: number } | Vector;
+            };
+            rx?: number;
+            ry?: number;
+            xAxisRotation?: number;
+            largeArcFlag?: number;
+          }
+    ): Anchor;
+    constructor(
+      x?: number,
+      y?: number,
+      ax?: number,
+      ay?: number,
+      bx?: number,
+      by?: number,
+      command?: Commands[keyof Commands]
+    );
+    controls: {
+      left: Vector;
+      right: Vector;
+    };
+    command: Commands[keyof Commands];
+    relative: boolean;
+    rx?: number;
+    ry?: number;
+    xAxisRotation?: number;
+    largeArcFlag?: number;
+    sweepFlag?: number;
+    /**
+     * @name Two.Anchor#copy
+     * @function
+     * @param {Two.Anchor} v - The anchor to apply values to.
+     * @description Copy the properties of one {@link Two.Anchor} onto another.
+     */
+    copy(anchor: Anchor): Anchor;
+    /**
+     * @name Two.Anchor#clone
+     * @function
+     * @returns {Two.Anchor}
+     * @description Create a new {@link Two.Anchor}, set all its values to the current instance and return it for use.
+     */
+    clone(): Anchor;
+    /**
+     * @name Two.Anchor#toObject
+     * @function
+     * @returns {Object} - An object with properties filled out to mirror {@link Two.Anchor}.
+     * @description Create a JSON compatible plain object of the current instance. Intended for use with storing values in a database.
+     * @nota-bene Works in conjunction with {@link Two.Anchor.fromObject}
+     */
+    toObject(): object;
+    /**
+     * @name Two.Anchor#toString
+     * @function
+     * @returns {String} - A String with comma-separated values reflecting the various values on the current instance.
+     * @description Create a string form of the current instance. Intended for use with storing values in a database. This is lighter to store than the JSON compatible {@link Two.Anchor#toObject}.
+     */
+    toString(): string;
+  }
+  import { Vector } from 'two.js/src/vector';
+  import { Commands } from 'two.js/src/utils/path-commands';
+}

src/anchor.d.ts

@@ -0,0 +1,33 @@
+declare module 'two.js/src/children' {
+  /**
+     * @class
+     * @name Two.Group.Children
+
+     * @description A children collection which is accesible both by index and by object `id`.
+     */
+  export class Children extends Collection<Shape> {
+    constructor(children?: Shape[]);
+    constructor(...args: Shape[]);
+    /**
+     * @name Two.Group.Children#ids
+     * @property {Object} - Map of all elements in the list keyed by `id`s.
+     */
+    ids: { [id: string]: Shape };
+    /**
+     * @function
+     * @name Two.Group.Children#attach
+     * @param {Shape[]} children - The objects which extend {@link Two.Shape} to be added.
+     * @description Adds elements to the `ids` map.
+     */
+    attach(children: Shape[]): Children;
+    /**
+     * @function
+     * @name Two.Group.Children#detach
+     * @param {Shape[]} children - The objects which extend {@link Two.Shape} to be removed.
+     * @description Removes elements to the `ids` map.
+     */
+    detach(children: Shape[]): Children;
+  }
+  import { Collection } from 'two.js/src/collection';
+  import { Shape } from 'two.js/src/shape';
+}

src/children.d.ts

@@ -0,0 +1,27 @@
+declare module 'two.js/src/collection' {
+  /**
+     * @name Two.Collection
+     * @class
+
+     * @description An `Array` like object with additional event propagation on actions. `pop`, `shift`, and `splice` trigger `removed` events. `push`, `unshift`, and `splice` with more than 2 arguments trigger 'inserted'. Finally, `sort` and `reverse` trigger `order` events.
+     */
+  export class Collection<T = any> extends Array<T> {
+    constructor(...args: any[]);
+    /**
+     * @private
+     */
+    private _events;
+    private set _bound(arg: boolean);
+    private get _bound(): boolean;
+    addEventListener(...args: any[]): any;
+    on(...args: any[]): any;
+    bind(...args: any[]): any;
+    removeEventListener(...args: any[]): any;
+    off(...args: any[]): any;
+    unbind(...args: any[]): any;
+    dispatchEvent(...args: any[]): any;
+    trigger(...args: any[]): any;
+    listen(...args: any[]): any;
+    ignore(...args: any[]): any;
+  }
+}

src/collection.d.ts

@@ -0,0 +1,18 @@
+declare module 'two.js/src/constants' {
+  export interface Constants {
+    NextFrameId: number;
+    Types: {
+      webgl: 'WebGLRenderer';
+      svg: 'SVGRenderer';
+      canvas: 'CanvasRenderer';
+    };
+    Version: string;
+    PublishDate: string;
+    Identifier: string;
+    Resolution: number;
+    AutoCalculateImportedMatrices: boolean;
+    Instances: Two[];
+    uniqueId(): number;
+  }
+  import Two from 'two.js';
+}