@shopify/klint 0.3.0 → 0.4.0

package/dist/plugins/index.d.cts

@@ -1,4 +1,4 @@
-import { K as KlintContext } from '../Klint-CsVzll4n.cjs';
+import { K as KlintContext } from '../Klint-DqYL-aGU.cjs';
 import 'react';
 
 interface FontPoint {
@@ -209,158 +209,6 @@ declare class CatmullRom {
     }): Path2D;
 }
 
-/**
- * Configuration options for Things plugin
- */
-interface ThingsConfig {
-    maxThings?: number;
-    defaultSize?: number;
-    defaultColor?: string;
-}
-/**
- * Individual Thing interface
- */
-interface Thing {
-    id: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation: number;
-    scale: number;
-    color: string;
-    data?: any;
-}
-/**
- * Static Things Plugin
- *
- * Manages a collection of "things" - generic objects that can be positioned,
- * transformed, and rendered without requiring Klint context initialization.
- * Context is only passed when drawing operations are needed.
- *
- * @example
- * ```tsx
- * import { Things } from '@shopify/klint/plugins';
- *
- * // Create things
- * Things.create({ x: 100, y: 100 });
- * Things.create({ x: 200, y: 200, color: '#ff0066' });
- *
- * // Update and draw
- * Things.animatePhysics(deltaTime);
- * Things.draw(K);
- * ```
- */
-declare class Things {
-    private static things;
-    private static config;
-    private static idCounter;
-    /**
-     * Configure the plugin
-     */
-    static configure(config: ThingsConfig): void;
-    /**
-     * Create a new thing
-     */
-    static create(options?: Partial<Thing>): Thing;
-    /**
-     * Get a thing by ID
-     */
-    static get(id: string): Thing | undefined;
-    /**
-     * Get all things
-     */
-    static getAll(): Thing[];
-    /**
-     * Update a thing's properties
-     */
-    static update(id: string, updates: Partial<Thing>): void;
-    /**
-     * Remove a thing
-     */
-    static remove(id: string): boolean;
-    /**
-     * Clear all things
-     */
-    static clear(): void;
-    /**
-     * Move a thing
-     */
-    static move(id: string, dx: number, dy: number): void;
-    /**
-     * Rotate a thing
-     */
-    static rotate(id: string, angle: number): void;
-    /**
-     * Scale a thing
-     */
-    static scale(id: string, factor: number): void;
-    /**
-     * Find things within a radius
-     */
-    static findNear(x: number, y: number, radius: number): Thing[];
-    /**
-     * Find things that overlap with a rectangle
-     */
-    static findInRect(x: number, y: number, width: number, height: number): Thing[];
-    /**
-     * Apply a function to all things
-     */
-    static forEach(fn: (thing: Thing) => void): void;
-    /**
-     * Map things to a new array
-     */
-    static map<T>(fn: (thing: Thing) => T): T[];
-    /**
-     * Filter things
-     */
-    static filter(fn: (thing: Thing) => boolean): Thing[];
-    /**
-     * Sort things by a property or function
-     */
-    static sort(fn: (a: Thing, b: Thing) => number): Thing[];
-    /**
-     * Draw all things
-     */
-    static draw(ctx: KlintContext, options?: {
-        customDraw?: (ctx: KlintContext, thing: Thing) => void;
-        filter?: (thing: Thing) => boolean;
-    }): void;
-    /**
-     * Default drawing method for a thing
-     */
-    private static drawThing;
-    /**
-     * Animate things with a simple physics update
-     */
-    static animatePhysics(deltaTime: number, options?: {
-        gravity?: number;
-        friction?: number;
-        bounds?: {
-            x: number;
-            y: number;
-            width: number;
-            height: number;
-        };
-    }): void;
-    /**
-     * Get the count of things
-     */
-    static count(): number;
-    /**
-     * Check if a thing exists
-     */
-    static has(id: string): boolean;
-    /**
-     * Utility: Get distance between two things
-     */
-    static distance(id1: string, id2: string): number;
-    /**
-     * Utility: Check collision between two things
-     */
-    static collides(id1: string, id2: string): boolean;
-}
-
 /**
  * Sprite configuration
  */
@@ -557,4 +405,442 @@ declare class SpriteAnimation {
     isPlaying(): boolean;
 }
 
-export { CatmullRom, Delaunay, type FontData, type FontLetter, type FontLetterWithPath, type FontLetterWithPoints, FontParser, type FontPathsResult, type FontPoint, type FontPointsResult, type FontTextBlock, type FontTextOptions, Sprites, Things };
+/**
+ * Body reference tracked by MatterPhysics
+ */
+interface MatterBody {
+    id: string;
+    body: any;
+    label?: string;
+}
+/**
+ * Configuration for MatterPhysics initialization
+ */
+interface MatterPhysicsConfig {
+    gravity?: {
+        x: number;
+        y: number;
+        scale?: number;
+    };
+    enableSleeping?: boolean;
+    constraintIterations?: number;
+    positionIterations?: number;
+    velocityIterations?: number;
+}
+/**
+ * Options for body creation
+ */
+interface BodyOptions {
+    id?: string;
+    label?: string;
+    isStatic?: boolean;
+    restitution?: number;
+    friction?: number;
+    frictionAir?: number;
+    density?: number;
+    angle?: number;
+    isSensor?: boolean;
+    chamfer?: {
+        radius: number;
+    };
+    [key: string]: any;
+}
+/**
+ * Options for constraint creation
+ */
+interface ConstraintOptions {
+    id?: string;
+    stiffness?: number;
+    damping?: number;
+    length?: number;
+    pointA?: {
+        x: number;
+        y: number;
+    };
+    pointB?: {
+        x: number;
+        y: number;
+    };
+    [key: string]: any;
+}
+/**
+ * Debug draw options
+ */
+interface DrawOptions {
+    showBodies?: boolean;
+    showConstraints?: boolean;
+    showBounds?: boolean;
+    bodyStroke?: string;
+    bodyFill?: string;
+    staticFill?: string;
+    constraintStroke?: string;
+    lineWidth?: number;
+}
+/**
+ * MatterPhysics Plugin
+ *
+ * Wrapper around Matter.js for 2D physics simulation.
+ * Requires matter-js — either pass the module at init, or use load() to dynamically import it.
+ *
+ * @example
+ * ```tsx
+ * import { MatterPhysics } from '@shopify/klint/plugins';
+ *
+ * // Option 1: Dynamic import (recommended)
+ * await MatterPhysics.load({ gravity: { x: 0, y: 1 } });
+ *
+ * // Option 2: Pass module directly
+ * import Matter from 'matter-js';
+ * MatterPhysics.init(Matter, { gravity: { x: 0, y: 1 } });
+ *
+ * MatterPhysics.addRect(400, 550, 800, 50, { isStatic: true });
+ * MatterPhysics.addCircle(400, 100, 25);
+ *
+ * const draw = (K) => {
+ *   MatterPhysics.update(K.deltaTime);
+ *   MatterPhysics.draw(K);
+ * };
+ * ```
+ */
+declare class MatterPhysics {
+    private static Matter;
+    private static engine;
+    private static world;
+    private static bodies;
+    private static constraints;
+    private static idCounter;
+    private static constraintIdCounter;
+    private static _loaded;
+    /** Matter.js version loaded from CDN when not installed locally */
+    static MATTER_VERSION: string;
+    /** CDN URL template — version is interpolated */
+    static MATTER_CDN: string;
+    /**
+     * Dynamically load matter-js and initialize the engine.
+     * Tries a local `import("matter-js")` first — if that fails (package not installed),
+     * falls back to loading from CDN via a script tag.
+     * @param config - Engine configuration
+     * @returns Promise that resolves when ready
+     *
+     * @example
+     * ```tsx
+     * // In preload or setup:
+     * await MatterPhysics.load({ gravity: { x: 0, y: 1 } });
+     * ```
+     */
+    static load(config?: MatterPhysicsConfig): Promise<void>;
+    /**
+     * Load Matter.js from CDN by injecting a script tag.
+     * Resolves with the global `Matter` object.
+     */
+    private static _loadFromCDN;
+    /**
+     * Check if MatterPhysics has been loaded and initialized.
+     */
+    static get isLoaded(): boolean;
+    /**
+     * Initialize the physics engine with a Matter.js module reference.
+     * Prefer `load()` for dynamic import. Use this if you want to pass the module directly.
+     * @param matterModule - The Matter.js module (import Matter from 'matter-js')
+     * @param config - Engine configuration
+     */
+    static init(matterModule: any, config?: MatterPhysicsConfig): void;
+    private static ensureInit;
+    private static generateId;
+    /**
+     * Add a rectangle body.
+     * @param x - Center X
+     * @param y - Center Y
+     * @param width - Width
+     * @param height - Height
+     * @param options - Body options
+     * @returns Body reference with id
+     */
+    static addRect(x: number, y: number, width: number, height: number, options?: BodyOptions): MatterBody;
+    /**
+     * Add a circle body.
+     * @param x - Center X
+     * @param y - Center Y
+     * @param radius - Radius
+     * @param options - Body options
+     * @returns Body reference with id
+     */
+    static addCircle(x: number, y: number, radius: number, options?: BodyOptions): MatterBody;
+    /**
+     * Add a polygon body.
+     * @param x - Center X
+     * @param y - Center Y
+     * @param sides - Number of sides
+     * @param radius - Radius
+     * @param options - Body options
+     * @returns Body reference with id
+     */
+    static addPolygon(x: number, y: number, sides: number, radius: number, options?: BodyOptions): MatterBody;
+    /**
+     * Add a body from custom vertices.
+     * @param x - Center X
+     * @param y - Center Y
+     * @param vertices - Array of {x, y} points
+     * @param options - Body options
+     * @returns Body reference with id
+     */
+    static addFromVertices(x: number, y: number, vertices: Array<{
+        x: number;
+        y: number;
+    }>, options?: BodyOptions): MatterBody;
+    /**
+     * Add a constraint between two bodies.
+     * @param bodyIdA - First body ID
+     * @param bodyIdB - Second body ID
+     * @param options - Constraint options
+     * @returns Constraint ID
+     */
+    static addConstraint(bodyIdA: string, bodyIdB: string, options?: ConstraintOptions): string;
+    /**
+     * Add a constraint anchored to a world point.
+     * @param bodyId - Body ID
+     * @param worldPoint - World anchor point {x, y}
+     * @param options - Constraint options
+     * @returns Constraint ID
+     */
+    static addWorldConstraint(bodyId: string, worldPoint: {
+        x: number;
+        y: number;
+    }, options?: ConstraintOptions): string;
+    /**
+     * Apply force to a body.
+     * @param bodyId - Body ID
+     * @param force - Force vector {x, y}
+     */
+    static applyForce(bodyId: string, force: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set velocity of a body.
+     * @param bodyId - Body ID
+     * @param velocity - Velocity vector {x, y}
+     */
+    static setVelocity(bodyId: string, velocity: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set position of a body.
+     * @param bodyId - Body ID
+     * @param position - Position {x, y}
+     */
+    static setPosition(bodyId: string, position: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Set gravity.
+     * @param x - Horizontal gravity
+     * @param y - Vertical gravity
+     */
+    static setGravity(x: number, y: number): void;
+    /**
+     * Get a body reference by ID.
+     */
+    static getBody(id: string): MatterBody | undefined;
+    /**
+     * Get all body references.
+     */
+    static getAllBodies(): MatterBody[];
+    /**
+     * Remove a body.
+     * @param id - Body ID
+     */
+    static removeBody(id: string): boolean;
+    /**
+     * Remove a constraint.
+     * @param id - Constraint ID
+     */
+    static removeConstraint(id: string): boolean;
+    /**
+     * Step the physics engine.
+     * @param deltaTime - Time step in milliseconds
+     */
+    static update(deltaTime: number): void;
+    /**
+     * Debug draw all bodies and constraints using Klint drawing primitives.
+     * @param ctx - Klint context
+     * @param options - Drawing options
+     */
+    static draw(ctx: KlintContext, options?: DrawOptions): void;
+    /**
+     * Iterate over all bodies with their position and angle.
+     * Convenience method for syncing physics bodies to visual objects.
+     * @param fn - Callback receiving body data
+     */
+    static forEach(fn: (data: {
+        id: string;
+        x: number;
+        y: number;
+        angle: number;
+        velocity: {
+            x: number;
+            y: number;
+        };
+        body: any;
+        label?: string;
+    }) => void): void;
+    /**
+     * Register a collision callback.
+     * @param event - Event type: 'collisionStart', 'collisionActive', 'collisionEnd'
+     * @param callback - Callback receiving collision pairs
+     */
+    static onCollision(event: "collisionStart" | "collisionActive" | "collisionEnd", callback: (pairs: any[]) => void): void;
+    /**
+     * Get the raw Matter.js engine for advanced usage.
+     */
+    static getEngine(): any;
+    /**
+     * Get the raw Matter.js world for advanced usage.
+     */
+    static getWorld(): any;
+    /**
+     * Clear all bodies, constraints, and reset the engine.
+     */
+    static clear(): void;
+    /**
+     * Destroy the engine entirely.
+     */
+    static destroy(): void;
+}
+
+/**
+ * A 3D point in world space.
+ */
+interface Point3D {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * A projected 2D point with depth info.
+ * - `x`, `y`: screen coordinates (centered at 0,0)
+ * - `z`: transformed depth (use for sorting, back-to-front)
+ * - `scale`: perspective foreshortening factor (use for sizing elements by depth)
+ */
+interface ProjectedPoint {
+    x: number;
+    y: number;
+    z: number;
+    scale: number;
+}
+/**
+ * 3D transform operations available inside the transform callback.
+ * All angles are in radians. Transforms are applied in the order you call them.
+ */
+interface Transform3D {
+    rotateX(radians: number): void;
+    rotateY(radians: number): void;
+    rotateZ(radians: number): void;
+    translate(x: number, y: number, z: number): void;
+    scale(x: number, y?: number, z?: number): void;
+}
+/**
+ * Projector — 3D to 2D projection for canvas2D creative coding.
+ *
+ * Projects 3D points onto a 2D plane using DOMMatrix for transforms
+ * and custom perspective division for depth foreshortening.
+ *
+ * @example
+ * ```tsx
+ * const projector = new Projector({ perspective: 2, radius: 200 });
+ *
+ * // In draw loop:
+ * const projected = projector.project(
+ *   { x: 1, y: 0, z: -1 },
+ *   (t) => {
+ *     t.rotateX(K.time * 0.5);
+ *     t.rotateY(K.time * 0.3);
+ *   }
+ * );
+ * K.circle(projected.x, projected.y, 10 * projected.scale);
+ * ```
+ */
+declare class Projector {
+    /** Perspective strength. 0 = orthographic, higher = stronger foreshortening. */
+    perspective: number;
+    /** Output scale — controls how far from center projected points spread. */
+    radius: number;
+    constructor(options?: {
+        perspective?: number;
+        radius?: number;
+    });
+    /**
+     * Build a DOMMatrix from a transform callback.
+     * The callback receives a Transform3D object — call rotateX, rotateY, etc.
+     * in the order you want them applied.
+     */
+    private buildMatrix;
+    /**
+     * Apply perspective projection to a transformed 3D point.
+     * Returns 2D coordinates + depth + scale factor.
+     */
+    private projectPoint;
+    /**
+     * Project a single 3D point.
+     *
+     * @param point - The 3D point to project.
+     * @param transforms - Optional callback to apply 3D transforms before projection.
+     * @returns Projected 2D point with depth and scale info.
+     *
+     * @example
+     * ```tsx
+     * const p = projector.project({ x: 0, y: 1, z: 0 }, (t) => {
+     *   t.rotateY(angle);
+     * });
+     * K.circle(p.x, p.y, 8 * p.scale);
+     * ```
+     */
+    project(point: Point3D, transforms?: (t: Transform3D) => void): ProjectedPoint;
+    /**
+     * Project an array of 3D points with the same transform.
+     * The transform matrix is built once and reused for all points.
+     *
+     * @param points - Array of 3D points.
+     * @param transforms - Optional transform callback (applied identically to all points).
+     * @returns Array of projected points (same order as input).
+     *
+     * @example
+     * ```tsx
+     * const projected = projector.projectAll(cubeVertices, (t) => {
+     *   t.rotateX(K.time);
+     *   t.rotateY(K.time * 0.7);
+     * });
+     * for (const p of projected) {
+     *   K.circle(p.x, p.y, 6 * p.scale);
+     * }
+     * ```
+     */
+    projectAll(points: Point3D[], transforms?: (t: Transform3D) => void): ProjectedPoint[];
+    /**
+     * Project and depth-sort an array of 3D points (back-to-front).
+     * Each result includes `index` — the original index in the input array,
+     * so you can map back to colors, labels, etc.
+     *
+     * @param points - Array of 3D points.
+     * @param transforms - Optional transform callback.
+     * @returns Depth-sorted array of projected points with original indices.
+     *
+     * @example
+     * ```tsx
+     * const sorted = projector.projectSorted(points, (t) => {
+     *   t.rotateX(K.time);
+     * });
+     * for (const p of sorted) {
+     *   K.fillColor(colors[p.index]);
+     *   K.circle(p.x, p.y, 10 * p.scale);
+     * }
+     * ```
+     */
+    projectSorted(points: Point3D[], transforms?: (t: Transform3D) => void): (ProjectedPoint & {
+        index: number;
+    })[];
+}
+
+export { CatmullRom, Delaunay, type FontData, type FontLetter, type FontLetterWithPath, type FontLetterWithPoints, FontParser, type FontPathsResult, type FontPoint, type FontPointsResult, type FontTextBlock, type FontTextOptions, MatterPhysics, type Point3D, type ProjectedPoint, Projector, Sprites, type Transform3D };