@leozodiac/swarm66 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,766 @@
+/**
+ * Core type definitions for dom-swarm.
+ * Zero external dependencies.
+ */
+interface Vector2D {
+    x: number;
+    y: number;
+}
+type AgentState = 'IDLE_FLOCKING' | 'MOVING_TO_TARGET' | 'CONSTRUCTING_ELEMENT' | 'RETURNING_TO_SWARM' | 'CONVERGING_TO_USER' | 'VANISHED';
+type AgentType = 'pointer' | 'pen' | 'frame' | 'media' | 'button' | 'code' | 'ibeam' | 'hand' | 'duplicate';
+type ElementCategory = 'text' | 'container' | 'media' | 'button' | 'code' | 'input';
+type BoundingBoxType = 'blue' | 'red';
+type BuildOrder = 'top-to-bottom' | 'random' | 'viewport';
+type BorderRole = 'top' | 'right' | 'bottom' | 'left' | 'center';
+type TaskPhase = 'MOVING' | 'CLONING' | 'EXPANDING' | 'BUILDING' | 'DONE';
+interface SwarmConfig {
+    /**
+     * Total number of autonomous cursor agents in the swarm.
+     * @default 18
+     */
+    agentCount?: number;
+    /**
+     * Number of agents assigned to each construction team.
+     * @default 4
+     */
+    teamSize?: number;
+    /**
+     * When multiple elements/containers share the same dimensions,
+     * animate a Figma-style copy-paste duplication and live editing sequence.
+     * @default true
+     */
+    copyPasteDuplicates?: boolean;
+    /**
+     * Vibrant color palette for the cursor agents and wireframes.
+     * @default ['#FF5722', '#00BCD4', '#8BC34A', '#9C27B0', '#FFC107', '#E91E63', '#2196F3']
+     */
+    colors?: string[];
+    /**
+     * CSS selector matching DOM elements to reverse-engineer and construct.
+     * @default 'nav, header, h1, h2, h3, h4, h5, h6, p, button, a, img, pre, code, .swarm-item, .price-card, .interactive-card, .metric-card'
+     */
+    selector?: string;
+    /**
+     * CSS selector to exclude elements from swarm construction.
+     * @default '[data-no-swarm], script, style, noscript, dom-swarm-overlay, .swarm-hud'
+     */
+    ignoreSelector?: string;
+    /**
+     * Whether to initially hide all detected elements on page load, keeping the native background intact,
+     * so the swarm builds the whole page from a blank canvas.
+     * @default true
+     */
+    hideOnStart?: boolean;
+    /**
+     * Number of elements being constructed simultaneously in parallel by teams.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Order in which detected elements are constructed.
+     * @default 'top-to-bottom'
+     */
+    buildOrder?: BuildOrder;
+    /**
+     * Once all page elements are constructed, all cursors converge to the user's cursor and vanish.
+     * @default true
+     */
+    vanishAtCursor?: boolean;
+    /**
+     * Automatically detect SPA client-side route changes (Next.js, React Router, Vue Router, Nuxt, SvelteKit, Turbo)
+     * and reconstruct elements on every visited page.
+     * @default true
+     */
+    rebuildOnRouteChange?: boolean;
+    /**
+     * Whether to construct elements automatically when they enter the viewport via scrolling.
+     * @default true
+     */
+    buildOnScroll?: boolean;
+    /**
+     * Simulate a fast typewriter reveal effect for text nodes (p, h1-h6, code, etc.).
+     * @default true
+     */
+    typewriterEffect?: boolean;
+    /**
+     * Show Figma-style full-screen horizontal and vertical alignment guides during construction.
+     * @default true
+     */
+    showGuides?: boolean;
+    /**
+     * Show dimensional pixel badge (e.g., "380 × 48") on selection bounding boxes.
+     * @default true
+     */
+    showDimensions?: boolean;
+    /**
+     * Whether cursor agents flock around and follow the user's active cursor/touch when idle.
+     * @default true
+     */
+    followMouse?: boolean;
+    /**
+     * Maximum movement velocity of agents in pixels per frame.
+     * @default 9.5
+     */
+    maxSpeed?: number;
+    /**
+     * Maximum steering force applied to agents.
+     * @default 0.4
+     */
+    maxForce?: number;
+    /**
+     * Duration in milliseconds spent constructing each element before moving to the next.
+     * @default 550
+     */
+    buildDuration?: number;
+    /**
+     * Radius in pixels within which agents recognize flockmates for alignment and cohesion.
+     * @default 85
+     */
+    flockRadius?: number;
+    /**
+     * Minimum distance agents maintain to avoid crowding each other.
+     * @default 32
+     */
+    separateDistance?: number;
+    /**
+     * Radius around the user's mouse within which flocking agents feel gravitational attraction.
+     * @default 220
+     */
+    mouseAttractRadius?: number;
+    /**
+     * Gravitational strength pulling idle agents toward the user's cursor.
+     * @default 0.45
+     */
+    mouseAttractForce?: number;
+    /**
+     * Minimum delay between character reveals during typewriter effect (ms).
+     * @default 16
+     */
+    typewriterSpeed?: number;
+    /**
+     * Mount container for the Shadow DOM overlay. Defaults to `document.body`.
+     */
+    container?: HTMLElement;
+    /**
+     * Enable diagnostic console logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback fired when an agent transitions between lifecycle states.
+     */
+    onAgentStateChange?: (agentId: number, state: AgentState) => void;
+    /**
+     * Callback fired when a DOM element has finished construction.
+     */
+    onElementConstructed?: (element: HTMLElement) => void;
+    /**
+     * Callback fired when all detected page elements have been constructed.
+     */
+    onAllElementsConstructed?: () => void;
+    /**
+     * Callback fired when the swarm has converged onto the user cursor and completely vanished.
+     */
+    onSwarmVanished?: () => void;
+}
+type ResolvedSwarmConfig = Required<Omit<SwarmConfig, 'container' | 'onAgentStateChange' | 'onElementConstructed' | 'onAllElementsConstructed' | 'onSwarmVanished'>> & {
+    container?: HTMLElement;
+    onAgentStateChange?: (agentId: number, state: AgentState) => void;
+    onElementConstructed?: (element: HTMLElement) => void;
+    onAllElementsConstructed?: () => void;
+    onSwarmVanished?: () => void;
+};
+interface ConstructionTask {
+    id: string;
+    element: HTMLElement;
+    rect: DOMRect;
+    boxType: BoundingBoxType;
+    assignedAgents: number[];
+    borderRoles: BorderRole[];
+    phase: TaskPhase;
+    isCopyPaste: boolean;
+    sourceRect?: DOMRect;
+    startTime: number;
+    expandStartTime: number;
+    expandDuration: number;
+    duration: number;
+    isText: boolean;
+    category?: ElementCategory;
+    cursorType?: AgentType;
+    boxElement?: HTMLElement;
+    cloneElement?: HTMLElement;
+    completed: boolean;
+    cancelEffect?: () => void;
+}
+interface SwarmMetrics {
+    fps: number;
+    totalAgents: number;
+    idleAgents: number;
+    constructingAgents: number;
+    convergingAgents: number;
+    vanishedAgents: number;
+    elementsConstructed: number;
+    elementsPending: number;
+    isFinished: boolean;
+}
+interface DomSwarmInstance {
+    destroy(): void;
+    pause(): void;
+    resume(): void;
+    replay(): void;
+    handlePageNavigation(): void;
+    buildElement(element: HTMLElement): Promise<void>;
+    getConfig(): Readonly<ResolvedSwarmConfig>;
+    updateConfig(newConfig: Partial<SwarmConfig>): void;
+    isPaused(): boolean;
+    isFinished(): boolean;
+    getActiveAgentCount(): number;
+    getMetrics(): SwarmMetrics;
+}
+
+/**
+ * Main orchestrator of dom-swarm:
+ * divides 18 agents into 4-agent teams, dispatches them to the 4 borders of elements,
+ * and converges all agents to the user's cursor to vanish upon completion.
+ */
+declare class SwarmEngine implements DomSwarmInstance {
+    private config;
+    private overlayManager;
+    private builderEffects;
+    private domScanner;
+    private agents;
+    private tasks;
+    private buildQueue;
+    private activeBoxTypeToggle;
+    private mousePos;
+    private lastMouseMoveTime;
+    private isMouseActive;
+    private animFrameId;
+    private lastTime;
+    private paused;
+    private destroyed;
+    private isFinishedState;
+    private isConverging;
+    private frameCount;
+    private lastFpsUpdate;
+    private currentFps;
+    private constructedCount;
+    private constructedTemplates;
+    private lastUrl;
+    private unbindRouteListeners;
+    private routeChangeDebounce;
+    constructor(userConfig?: SwarmConfig);
+    /**
+     * Initializes overlay, agents, input listeners, and starts the construction sequence.
+     */
+    private init;
+    /**
+     * Spawns 18 agents divided randomly into 4-agent teams.
+     */
+    private spawnAgents;
+    /**
+     * Binds pointer and touch listeners for interactive flocking and convergence target.
+     */
+    private bindEvents;
+    private onMouseMove;
+    private onTouchMove;
+    private onScroll;
+    private onResize;
+    /**
+     * Main simulation and animation loop running on requestAnimationFrame.
+     */
+    private renderLoop;
+    /**
+     * Continuously processes elements from the queue using parallel 4-agent teams.
+     */
+    private processBuildQueue;
+    /**
+     * Checks if an element has matching dimensions to an already constructed element
+     * to enable Figma-style copy/paste duplicate animation.
+     */
+    private findMatchingTemplate;
+    /**
+     * Initiates live construction of an element by dispatching a team of 4 agents
+     * to the 4 borders of the bounding box.
+     */
+    private constructElement;
+    /**
+     * Completes a task, removes overlays, releases agents, and triggers the next queue item.
+     */
+    private completeTask;
+    /**
+     * Triggers the grand finale: all 18 cursors accelerate towards the user's cursor, swirl, and vanish.
+     */
+    private triggerConvergenceFinale;
+    /**
+     * Binds SPA client-side route change listeners for Next.js, React Router, Vue, Nuxt, SvelteKit, Turbo, etc.
+     */
+    private setupRouteListeners;
+    private handleRouteChange;
+    /**
+     * Public API: Reinitializes and launches the swarm construction sequence for a newly navigated page.
+     * Cancels in-flight tasks, clears templates, scans the new page's DOM,
+     * applies initial blank canvas hiding, respawns the 18 agents, and begins live construction.
+     */
+    handlePageNavigation(): void;
+    /**
+     * Adds an element to the queue dynamically.
+     */
+    private enqueueElement;
+    /**
+     * Synchronizes active bounding boxes, alignment guides, and agent border targets
+     * during live scrolling or resizing.
+     */
+    private syncActiveBoundingBoxes;
+    /**
+     * Selects a team of 4 available agents closest to the element.
+     */
+    private pickTeamAgents;
+    /**
+     * Public API: Replays the whole swarm construction from the beginning.
+     */
+    replay(): void;
+    /**
+     * Public API: Manually trigger construction on an element immediately.
+     */
+    buildElement(element: HTMLElement): Promise<void>;
+    pause(): void;
+    resume(): void;
+    isPaused(): boolean;
+    isFinished(): boolean;
+    getConfig(): Readonly<ResolvedSwarmConfig>;
+    updateConfig(newConfig: Partial<SwarmConfig>): void;
+    getActiveAgentCount(): number;
+    getMetrics(): SwarmMetrics;
+    destroy(): void;
+}
+
+/**
+ * Manages the open Shadow DOM overlay container, scoped CSS styles,
+ * SVG cursor rendering, Figma selection boxes, and alignment guides.
+ */
+declare class OverlayManager {
+    private container;
+    private hostElement;
+    private shadowRoot;
+    private agentsLayer;
+    private overlaysLayer;
+    private guidesLayer;
+    private mounted;
+    constructor(container?: HTMLElement);
+    /**
+     * Mounts the full-screen Shadow DOM overlay.
+     */
+    mount(): boolean;
+    /**
+     * Creates an agent cursor element with crisp SVG icon (no text badges).
+     */
+    createAgentElement(id: number, color: string): {
+        element: HTMLElement;
+        iconContainer: HTMLElement;
+    };
+    /**
+     * Updates hardware-accelerated transform of an agent cursor.
+     */
+    updateAgentTransform(el: HTMLElement, x: number, y: number, angleDeg: number, scale?: number): void;
+    /**
+     * Morphs/switches an agent icon to match the contextual tool category
+     * (e.g. pen for text, frame for containers, media for images, button for clicks, duplicate for clones).
+     */
+    setAgentIcon(iconContainer: HTMLElement, type: AgentType, color: string): void;
+    /**
+     * Creates an animated selection bounding box overlay drawn by the swarm.
+     */
+    createBoundingBox(id: string, rect: DOMRect, type: BoundingBoxType, showDimensions?: boolean, showGuides?: boolean, initialGeometry?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        opacity?: number;
+    }): HTMLElement;
+    /**
+     * Creates a ghost wireframe clone for Figma-style copy/paste duplicate animations.
+     */
+    createGhostClone(id: string, rect: DOMRect): HTMLElement;
+    /**
+     * Updates coordinates of the ghost clone as it glides from source to destination.
+     */
+    updateGhostClone(cloneEl: HTMLElement, x: number, y: number, width: number, height: number, opacity?: number): void;
+    /**
+     * Removes a ghost clone element.
+     */
+    removeGhostClone(cloneEl: HTMLElement): void;
+    /**
+     * Smoothly updates bounding box geometry as the swarm cursors drag/expand it.
+     */
+    updateBoxGeometry(boxEl: HTMLElement, rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }, opacity?: number, id?: string): void;
+    /**
+     * Creates full-screen red alignment guide lines.
+     */
+    private createAlignmentGuides;
+    /**
+     * Updates coordinates of an existing bounding box and its alignment guides during scrolling/resizing.
+     */
+    updateBoundingBox(boxEl: HTMLElement, rect: DOMRect, id?: string): void;
+    /**
+     * Removes a bounding box overlay and any attached guide lines.
+     */
+    removeBoundingBox(boxEl: HTMLElement, id?: string): void;
+    /**
+     * Standard Pointer SVG icon string.
+     */
+    private getPointerSvg;
+    /**
+     * Pencil / Pen tool SVG for text drafting and editing.
+     * Sharp tip aligned at (2, 2) matching cursor transform-origin.
+     */
+    private getPenSvg;
+    /**
+     * Figma Frame / Container tool SVG with "#" layout badge.
+     */
+    private getFrameSvg;
+    /**
+     * Media / Image tool SVG with landscape photo placement badge.
+     */
+    private getMediaSvg;
+    /**
+     * Button / Interactive tool SVG with rounded button pill badge.
+     */
+    private getButtonSvg;
+    /**
+     * Code / Terminal tool SVG with code brackets badge.
+     */
+    private getCodeSvg;
+    /**
+     * I-Beam text insertion SVG icon string.
+     */
+    private getIBeamSvg;
+    /**
+     * Hand dragging tool SVG for copy-pasting elements.
+     * Classic Figma / OS open dragging hand anchored at top fingertip.
+     */
+    private getHandSvg;
+    /**
+     * Spawns a glowing expanding ripple when a cursor converges and vanishes into the user pointer.
+     */
+    createVanishRipple(x: number, y: number, color: string): void;
+    /**
+     * Scoped CSS styles injected directly into Shadow DOM.
+     */
+    private getScopedStyles;
+    /**
+     * Destroys and cleans up the overlay.
+     */
+    destroy(): void;
+}
+
+/**
+ * Individual cursor agent entity with autonomous Boids state machine,
+ * collaborative 4-team border construction, and convergence/vanishing finale.
+ */
+declare class Agent {
+    id: number;
+    color: string;
+    teamId: number;
+    state: AgentState;
+    type: AgentType;
+    position: Vector2D;
+    velocity: Vector2D;
+    acceleration: Vector2D;
+    maxSpeed: number;
+    maxForce: number;
+    targetPosition: Vector2D | null;
+    targetElement: HTMLElement | null;
+    assignedTaskId: string | null;
+    borderRole: BorderRole | null;
+    targetRect: DOMRect | null;
+    private borderProgress;
+    element: HTMLElement;
+    iconContainer: HTMLElement;
+    private headingAngle;
+    private targetScale;
+    private currentScale;
+    private currentOpacity;
+    constructor(id: number, color: string, teamId: number, initialPos: Vector2D, overlayManager: OverlayManager, maxSpeed?: number, maxForce?: number);
+    /**
+     * Applies an external steering or acceleration force to the agent.
+     */
+    applyForce(force: Vector2D): void;
+    /**
+     * Advances the agent's physics simulation and visual presentation by delta time.
+     */
+    update(dt: number, overlayManager: OverlayManager): void;
+    /**
+     * Switches cursor avatar between arrow pointer and I-beam text tool.
+     */
+    morphIcon(newType: AgentType, overlayManager: OverlayManager): void;
+    /**
+     * Dispatches agent to navigate to a target DOM element coordinate on its border,
+     * switching to the element's contextual tool icon (e.g. pencil/pen for text, frame for boxes).
+     */
+    assignTarget(targetPos: Vector2D, element: HTMLElement, taskId: string, borderRole: BorderRole, rect: DOMRect, toolType: AgentType, overlayManager: OverlayManager): void;
+    /**
+     * Puts agent into element construction mode along its assigned border.
+     */
+    setConstructing(): void;
+    /**
+     * Marks construction complete and initiates return to swarm flock.
+     */
+    returnToSwarm(overlayManager: OverlayManager): void;
+    /**
+     * Directs the agent to accelerate and converge into the user's cursor, then vanish.
+     */
+    convergeTo(userPos: Vector2D, overlayManager: OverlayManager): void;
+    /**
+     * Restores agent to idle Boids flocking state.
+     */
+    setIdle(): void;
+    /**
+     * Resets agent position, visibility, and state for replaying.
+     */
+    reset(pos: Vector2D, overlayManager: OverlayManager): void;
+    /**
+     * Removes agent element from DOM.
+     */
+    destroy(): void;
+}
+
+/**
+ * Reynolds Boids algorithm implementation with dynamic mouse attraction
+ * and viewport boundary repulsion.
+ */
+declare class BoidsPhysics {
+    /**
+     * Computes the combined flocking force for an agent in IDLE_FLOCKING or RETURNING_TO_SWARM state.
+     */
+    static calculateFlockingForces(agent: Agent, allAgents: Agent[], mousePos: Vector2D | null, config: ResolvedSwarmConfig, viewport: {
+        width: number;
+        height: number;
+    }): Vector2D;
+    /**
+     * Separation: steer to avoid colliding with nearby flockmates.
+     */
+    static separate(agent: Agent, agents: Agent[], desiredSeparation: number): Vector2D;
+    /**
+     * Alignment: steer towards the average velocity of nearby flockmates.
+     */
+    static align(agent: Agent, agents: Agent[], neighborDist: number): Vector2D;
+    /**
+     * Cohesion: steer to move toward the average position of nearby flockmates.
+     */
+    static cohere(agent: Agent, agents: Agent[], neighborDist: number): Vector2D;
+    /**
+     * Mouse Attraction: draws agents toward live cursor coordinates with dynamic swirling orbit.
+     */
+    static attractToMouse(agent: Agent, mousePos: Vector2D, radius: number, forceStrength: number): Vector2D;
+    /**
+     * Steer toward a specific target coordinate with arrival slowing.
+     */
+    static seek(agent: Agent, target: Vector2D, slowingRadius?: number): Vector2D;
+    /**
+     * Smooth boundary repulsion from viewport edges so agents stay visible.
+     */
+    static boundEdges(agent: Agent, viewport: {
+        width: number;
+        height: number;
+    }, margin?: number): Vector2D;
+}
+
+/**
+ * Non-destructive DOM construction visual effects:
+ * initial blank canvas hiding, typewriter text reveals, block scale-ins,
+ * and safe style restoration failsafes.
+ */
+declare class BuilderEffects {
+    private activeRestorations;
+    private modifiedElements;
+    /**
+     * Identifies the design/semantic category of an element to pick the appropriate cursor tool
+     * (e.g. pencil/pen for text, frame for containers, image tool for media, button tool for clicks).
+     */
+    static getElementCategory(element: HTMLElement): ElementCategory;
+    /**
+     * Checks whether an element is suitable for a typewriter text reveal.
+     */
+    static isTextElement(element: HTMLElement): boolean;
+    /**
+     * Immediately hides an element while preserving its native document layout and background.
+     */
+    hideElement(element: HTMLElement): void;
+    /**
+     * Executes element construction reveal (typewriter for text, scale/opacity for blocks).
+     */
+    executeReveal(element: HTMLElement, isText: boolean, enableTypewriter: boolean, durationMs: number, onComplete: () => void): () => void;
+    /**
+     * Cleans up temporary inline styles applied during animation.
+     */
+    private cleanupElement;
+    /**
+     * Failsafe cleanup restoring all modified host DOM elements back to pristine native state.
+     */
+    restoreAll(): void;
+}
+
+interface DomScannerOptions {
+    selector: string;
+    ignoreSelector: string;
+    hideOnStart: boolean;
+    buildOrder: BuildOrder;
+    builderEffects: BuilderEffects;
+    onElementDiscovered?: (element: HTMLElement) => void;
+}
+/**
+ * Scans, indexes, and prepares host DOM elements for live swarm construction,
+ * sorting elements in natural visual sequence (top-to-bottom).
+ */
+declare class DomScanner {
+    private options;
+    private intersectionObserver;
+    private mutationObserver;
+    private indexedElements;
+    private observedElements;
+    private mutationTimeout;
+    constructor(options: DomScannerOptions);
+    /**
+     * Initializes DOM scanning, initial element hiding, and observers.
+     */
+    init(): HTMLElement[];
+    /**
+     * Scans document for eligible elements, applies initial blank state if enabled,
+     * and returns elements sorted by buildOrder.
+     */
+    scanAndIndex(): HTMLElement[];
+    /**
+     * Intersection observer to trigger scroll-based builds if configured.
+     */
+    private setupIntersectionObserver;
+    /**
+     * Monitors dynamic component mounting for SPA client-side route changes.
+     */
+    private setupMutationObserver;
+    /**
+     * Evaluates if element matches ignore selectors or is structurally hidden.
+     */
+    private shouldIgnoreElement;
+    /**
+     * Destroys observers.
+     */
+    destroy(): void;
+}
+
+/**
+ * Creates a 2D vector.
+ */
+declare function vec(x?: number, y?: number): Vector2D;
+/**
+ * Adds two vectors.
+ */
+declare function add(v1: Vector2D, v2: Vector2D): Vector2D;
+/**
+ * Subtracts v2 from v1.
+ */
+declare function sub(v1: Vector2D, v2: Vector2D): Vector2D;
+/**
+ * Multiplies vector by scalar.
+ */
+declare function mult(v: Vector2D, n: number): Vector2D;
+/**
+ * Divides vector by scalar.
+ */
+declare function div(v: Vector2D, n: number): Vector2D;
+/**
+ * Squared magnitude of a vector.
+ */
+declare function magSq(v: Vector2D): number;
+/**
+ * Magnitude (length) of a vector.
+ */
+declare function mag(v: Vector2D): number;
+/**
+ * Squared Euclidean distance between two points.
+ */
+declare function distSq(v1: Vector2D, v2: Vector2D): number;
+/**
+ * Euclidean distance between two points.
+ */
+declare function dist(v1: Vector2D, v2: Vector2D): number;
+/**
+ * Normalizes vector to unit length (length = 1).
+ */
+declare function normalize(v: Vector2D): Vector2D;
+/**
+ * Sets magnitude of a vector to specified length.
+ */
+declare function setMag(v: Vector2D, n: number): Vector2D;
+/**
+ * Limits magnitude of vector to max value.
+ */
+declare function limit(v: Vector2D, maxVal: number): Vector2D;
+/**
+ * Calculates heading angle in radians (-PI to PI).
+ */
+declare function heading(v: Vector2D): number;
+/**
+ * Calculates heading angle in degrees (0 to 360 or -180 to 180).
+ */
+declare function headingDeg(v: Vector2D): number;
+/**
+ * Linear interpolation between two values.
+ */
+declare function lerp(start: number, end: number, amt: number): number;
+/**
+ * Clamps a number between min and max bounds.
+ */
+declare function clamp(val: number, min: number, max: number): number;
+/**
+ * Generates random float between min and max.
+ */
+declare function randomRange(min: number, max: number): number;
+/**
+ * Selects a random element from an array.
+ */
+declare function randomChoice<T>(items: T[]): T;
+/**
+ * Computes dot product of two vectors.
+ */
+declare function dot(v1: Vector2D, v2: Vector2D): number;
+
+/**
+ * Public class implementation of Swarm66 / DomSwarm.
+ */
+declare class Swarm66 extends SwarmEngine {
+    constructor(config?: SwarmConfig);
+}
+declare class DomSwarm extends Swarm66 {
+}
+/**
+ * Convenience alias for swarm66 initialization.
+ */
+declare const swarm66: typeof enableSwarm;
+/**
+ * Convenience factory to mount and enable the DomSwarm visual engine on any page.
+ * Safe for Server-Side Rendering (SSR) environments.
+ *
+ * @param config Optional configuration options to customize swarm behaviors and visuals.
+ * @returns An active DomSwarmInstance controlling the swarm.
+ *
+ * @example
+ * ```ts
+ * import { enableSwarm } from 'dom-swarm';
+ *
+ * const swarm = enableSwarm({
+ *   agentCount: 20,
+ *   hideOnStart: true,
+ *   vanishAtCursor: true,
+ *   typewriterEffect: true,
+ * });
+ * ```
+ */
+declare function enableSwarm(config?: SwarmConfig): DomSwarmInstance;
+
+export { Agent, type AgentState, type AgentType, BoidsPhysics, type BorderRole, type BoundingBoxType, type BuildOrder, BuilderEffects, type ConstructionTask, DomScanner, DomSwarm, type DomSwarmInstance, type ElementCategory, OverlayManager, type ResolvedSwarmConfig, Swarm66, type SwarmConfig, SwarmEngine, type SwarmMetrics, type TaskPhase, type Vector2D, add, clamp, enableSwarm as default, dist, distSq, div, dot, enableSwarm, heading, headingDeg, lerp, limit, mag, magSq, mult, normalize, randomChoice, randomRange, setMag, sub, swarm66, vec };