@leozodiac/swarm66 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,132 @@
1
+ # `dom-swarm` Architecture & System Design
2
+
3
+ This document details the internal design, mathematical physics engine, rendering pipeline, and lifecycle management of `dom-swarm`.
4
+
5
+ ---
6
+
7
+ ## 1. High-Level Architecture Overview
8
+
9
+ `dom-swarm` is engineered as a zero-dependency, self-contained visual engine that non-destructively reverse-engineers any host webpage's DOM tree. When dropped into any website, it executes a complete 4-stage visual journey:
10
+
11
+ ```mermaid
12
+ flowchart TD
13
+ subgraph Stage1["1. Blank Canvas State"]
14
+ Detect[Scan & Index All DOM Elements]
15
+ Order[Sort Elements: Top to Bottom]
16
+ Blank[Set Elements to Opacity 0 while keeping Native Background]
17
+ end
18
+
19
+ subgraph Stage2["2. Swarm Spawn & Entry"]
20
+ Spawn[Spawn 15-30 Branded Cursors in Shadow DOM]
21
+ Flock[Engage Reynolds Boids Flocking Engine]
22
+ end
23
+
24
+ subgraph Stage3["3. Live Autonomous Page Construction"]
25
+ Queue[Process Top-to-Bottom Element Queue in Waves]
26
+ Dispatch[Dispatch 1-3 Nearest Idle Agents]
27
+ FigmaBox[Figma Blue Selection Box + Dimensions 380x48]
28
+ RedWire[Red Alignment Box + Full-Screen Guides]
29
+ Typewriter[I-Beam Typewriter Text Cadence]
30
+ BlockReveal[Scale & Opacity Construction Reveal]
31
+ end
32
+
33
+ subgraph Stage4["4. Grand Finale: Convergence & Vanish"]
34
+ CheckDone[All Elements Constructed?]
35
+ Converge[All Cursors Accelerate & Spiral to User Mouse]
36
+ Vanish[Shrink & Fade Cursors into Pointer Tip]
37
+ Clean[Pristine, 100% Interactive Host Webpage Remains]
38
+ end
39
+
40
+ Detect --> Order --> Blank --> Spawn --> Flock
41
+ Flock --> Queue --> Dispatch
42
+ Dispatch --> FigmaBox & RedWire & Typewriter & BlockReveal
43
+ FigmaBox & RedWire & Typewriter & BlockReveal --> CheckDone
44
+ CheckDone -->|Next Wave| Queue
45
+ CheckDone -->|All Done| Converge --> Vanish --> Clean
46
+ ```
47
+
48
+ ---
49
+
50
+ ## 2. Autonomous Multi-Agent State Machine
51
+
52
+ Each agent in the swarm operates as an independent autonomous entity governed by a 6-state lifecycle:
53
+
54
+ ```mermaid
55
+ stateDiagram-v2
56
+ [*] --> IDLE_FLOCKING
57
+ IDLE_FLOCKING --> MOVING_TO_TARGET: Dispatched to Element
58
+ MOVING_TO_TARGET --> CONSTRUCTING_ELEMENT: Arrived at Target Bounds (< 18px)
59
+ CONSTRUCTING_ELEMENT --> RETURNING_TO_SWARM: Element Finished (~550ms)
60
+ RETURNING_TO_SWARM --> IDLE_FLOCKING: Velocity Normalized
61
+ IDLE_FLOCKING --> CONVERGING_TO_USER: Page Complete
62
+ CONVERGING_TO_USER --> VANISHED: Reached User Mouse (< 10px)
63
+ VANISHED --> [*]
64
+ ```
65
+
66
+ 1. **`IDLE_FLOCKING`**:
67
+ - The agent participates in the collective Reynolds Boids flocking simulation.
68
+ - Orbits dynamically around the user's active cursor or touch position.
69
+ - Rotates along its velocity vector: `transform: translate3d(x, y, 0) rotate(deg) scale(1)`.
70
+
71
+ 2. **`MOVING_TO_TARGET`**:
72
+ - The agent is assigned to a specific target DOM coordinate (e.g., top-left corner, bottom-right handle, or center of an element).
73
+ - Steers directly towards the target with arrival damping.
74
+ - If the element is a pure text node (`p`, `h1`-`h6`, `code`), morphs icon to an `I-beam` text cursor.
75
+
76
+ 3. **`CONSTRUCTING_ELEMENT`**:
77
+ - The agent holds position over the element while construction animations execute.
78
+ - Pointer arrow or I-beam exhibits subtle micro-movements to simulate live inspection or typing.
79
+
80
+ 4. **`RETURNING_TO_SWARM`**:
81
+ - Construction concludes, bounding boxes dissolve, and the agent receives an impulse steering it back toward the flock cloud to be ready for the next queue task.
82
+
83
+ 5. **`CONVERGING_TO_USER`**:
84
+ - Fired when all elements in the build queue have completed.
85
+ - All agents accelerate toward the live coordinates of the user's mouse (`mousePos`).
86
+ - A tangential swirling force is applied to create an inward spiral.
87
+ - Scale and opacity interpolate down as distance closes in:
88
+ $$\text{scale} = \min\left(\frac{d}{70}, 1\right), \quad \text{opacity} = \min\left(\frac{d}{70}, 1\right)$$
89
+
90
+ 6. **`VANISHED`**:
91
+ - When within 10px of the user cursor tip, the agent disappears completely (`display: none; opacity: 0;`).
92
+ - Once all agents are `VANISHED`, the swarm triggers `onSwarmVanished?.()`.
93
+
94
+ ---
95
+
96
+ ## 3. Reynolds Boids Physics Engine
97
+
98
+ The idle behavior is governed by Craig Reynolds' classic flocking model augmented with dynamic mouse attraction and soft boundary dampening:
99
+
100
+ 1. **Separation ($F_s$):**
101
+ Steers agents away from nearby flockmates within radius $r_{sep}$ to prevent crowding:
102
+ $$F_s = \sum_{j \neq i} \frac{P_i - P_j}{\|P_i - P_j\|^2}$$
103
+
104
+ 2. **Alignment ($F_a$):**
105
+ Matches heading with neighboring flockmates within flocking radius $r_{flock}$:
106
+ $$F_a = \left( \frac{1}{N} \sum_{j=1}^N V_j \right) - V_i$$
107
+
108
+ 3. **Cohesion ($F_c$):**
109
+ Attracts agents toward the local center of mass:
110
+ $$C = \frac{1}{N} \sum_{j=1}^N P_j \quad \Longrightarrow \quad F_c = \text{seek}(P_i, C)$$
111
+
112
+ 4. **Dynamic Mouse Orbit & Attraction ($F_m$):**
113
+ When the user moves the mouse or taps the screen, a combined radial pull and tangential swirl force is exerted:
114
+ $$F_m = F_{\text{seek}}(\text{mouse}) \cdot w_{\text{attract}} + F_{\text{tangent}} \cdot w_{\text{orbit}}$$
115
+
116
+ 5. **Convergence Spiral ($F_{conv}$):**
117
+ During the grand finale, agents seek the mouse with an amplified tangential swirl:
118
+ $$F_{\text{conv}} = \text{seek}(P_i, \text{mouse}, 50) + \text{tangent}(P_i, \text{mouse}) \cdot 1.4$$
119
+
120
+ ---
121
+
122
+ ## 4. Non-Destructive DOM Isolation
123
+
124
+ `dom-swarm` guarantees zero visual and CSS bleeding:
125
+ - **Open Shadow DOM (`<dom-swarm-overlay>`):**
126
+ Mounted with `position: fixed; inset: 0; pointer-events: none; z-index: 2147483647;`.
127
+ - **Zero Layout Shifts (CLS 0.00):**
128
+ Hidden elements retain their exact computed geometry in the layout flow (`opacity: 0; transform: scale(0.96); pointer-events: none;`). The site's background, containers, and borders remain stable.
129
+ - **Instant Failsafe Restoration:**
130
+ Every modified element has an exact inverse restoration function stored in an active registry. Calling `.destroy()` instantly restores all host elements to their pristine native styles.
131
+ - **Replay Capability (`.replay()`):**
132
+ Re-applies the blank canvas hiding, resets cursors across the screen, and restarts the construction waves from the top.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dom Swarm Authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,3 +1,417 @@
1
- # Temporary Holding Version
1
+ # @leozodiac/swarm66 ⚡
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Universal plug-and-play visual engine that reverse-engineers any webpage's DOM on the fly. When initialized on ANY website, the page begins blank with its natural background, autonomous AI/Figma-style cursors swarm in to construct the webpage live before the user's eyes, and once the entire page is built, every cursor converges into the user's cursor and vanishes.**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@leozodiac/swarm66.svg?style=flat-square&color=0d99ff)](https://www.npmjs.com/package/@leozodiac/swarm66)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Strict%205.7-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
8
+ [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-success.svg?style=flat-square)](https://bundlephobia.com/package/@leozodiac/swarm66)
9
+
10
+ ---
11
+
12
+ ## ✨ How It Works
13
+
14
+ 1. **Initial Blank Canvas:**
15
+ When installed in any project (React, Next.js, Vue, Svelte, or Vanilla HTML), `@leozodiac/swarm66` indexes every element on the page. The page begins completely blank while preserving the site's natural background colors and layout flow.
16
+ 2. **Autonomous Swarm Construction:**
17
+ A squad of 18 vibrant Figma-style AI cursors organized into 4-member squads systematically builds the page:
18
+ - **Focused Tool Cursors:**
19
+ - ↖️ **Primary Arrow Pointer:** The clean, classic cursor used across the swarm for flocking, border navigation, and layout framing.
20
+ - ✋ **Hand Tool (Single Drag Cursor):** Exactly 1 cursor grabs and slides duplicate wireframes across the canvas during copy-pasting.
21
+ - ✏️ **Pencil / Pen Tool:** The lead agent uses the drafting pencil tool with micro sketching vibration to write headings and typewriter text.
22
+ - Snapping **Figma Blue Selection Bounding Boxes** (`#0d99ff`) with live pixel dimension badges (`380 × 48`) and corner resize handles.
23
+ - Drawing **Red Alignment Wireframes** (`#f24822`) with full-screen horizontal and vertical guide lines.
24
+ - Active cursor-drawn box expansion: agents actively pull the 4 corners outward from `0 × 0` before revealing content.
25
+ 3. **Grand Finale — Convergence & Vanishing:**
26
+ As soon as the entire page is constructed, the swarm accelerates and swirls directly into the user's live mouse cursor, shrinking and vanishing into thin air—leaving the user with a 100% interactive, pristine webpage!
27
+
28
+ ---
29
+
30
+ ## 🚀 Quick Start & Installation
31
+
32
+ Install via npm, pnpm, or yarn:
33
+
34
+ ```bash
35
+ # npm
36
+ npm install @leozodiac/swarm66
37
+
38
+ # pnpm
39
+ pnpm add @leozodiac/swarm66
40
+
41
+ # yarn
42
+ yarn add @leozodiac/swarm66
43
+ ```
44
+
45
+ ### CDN / Standalone Script Tag
46
+
47
+ Drop `@leozodiac/swarm66` directly into any static HTML, PHP, or WordPress website using a script tag:
48
+
49
+ ```html
50
+ <!-- Load swarm66 global bundle from CDN -->
51
+ <script src="https://cdn.jsdelivr.net/npm/@leozodiac/swarm66@1.0.0/dist/index.global.js"></script>
52
+
53
+ <script>
54
+ // Mount the swarm engine
55
+ const swarm = enableSwarm({
56
+ agentCount: 18,
57
+ hideOnStart: true, // Page starts blank with native background
58
+ vanishAtCursor: true, // Swarm converges into user's cursor and vanishes when done
59
+ typewriterEffect: true
60
+ });
61
+ </script>
62
+ ```
63
+
64
+ ---
65
+
66
+ ## 🛠️ Framework Integration Guides
67
+
68
+ ### 1. Vanilla HTML / JavaScript
69
+
70
+ ```js
71
+ import { enableSwarm } from 'swarm66';
72
+
73
+ const swarm = enableSwarm({
74
+ agentCount: 18,
75
+ hideOnStart: true,
76
+ vanishAtCursor: true,
77
+ typewriterEffect: true,
78
+ showGuides: true,
79
+ });
80
+ ```
81
+
82
+ ### 2. React (`useEffect`)
83
+
84
+ ```tsx
85
+ import React, { useEffect } from 'react';
86
+ import { enableSwarm } from 'swarm66';
87
+
88
+ export function App() {
89
+ useEffect(() => {
90
+ const swarm = enableSwarm({
91
+ agentCount: 18,
92
+ hideOnStart: true,
93
+ vanishAtCursor: true,
94
+ typewriterEffect: true,
95
+ });
96
+
97
+ // Cleanup on unmount
98
+ return () => {
99
+ swarm.destroy();
100
+ };
101
+ }, []);
102
+
103
+ return (
104
+ <main>
105
+ <h1>Autonomous Cursor Swarm</h1>
106
+ <p>Watch cursors build components live, then vanish into your pointer.</p>
107
+ </main>
108
+ );
109
+ }
110
+ ```
111
+
112
+ ### 3. Next.js App Router (`'use client'`)
113
+
114
+ `swarm66` has automatic SSR guards, so importing it in Next.js will never throw `window is not defined` errors.
115
+
116
+ ```tsx
117
+ 'use client';
118
+
119
+ import { useEffect } from 'react';
120
+ import { enableSwarm } from 'swarm66';
121
+
122
+ export default function SwarmProvider({ children }: { children: React.ReactNode }) {
123
+ useEffect(() => {
124
+ const swarm = enableSwarm({
125
+ agentCount: 18,
126
+ hideOnStart: true,
127
+ vanishAtCursor: true,
128
+ typewriterEffect: true,
129
+ showGuides: true,
130
+ });
131
+
132
+ return () => swarm.destroy();
133
+ }, []);
134
+
135
+ return <>{children}</>;
136
+ }
137
+ ```
138
+
139
+ ### 4. Vue 3 & Nuxt 3 (`onMounted`)
140
+
141
+ ```vue
142
+ <script setup lang="ts">
143
+ import { onMounted, onUnmounted } from 'vue';
144
+ import { enableSwarm, type DomSwarmInstance } from 'swarm66';
145
+
146
+ let swarm: DomSwarmInstance | null = null;
147
+
148
+ onMounted(() => {
149
+ swarm = enableSwarm({
150
+ agentCount: 18,
151
+ hideOnStart: true,
152
+ vanishAtCursor: true,
153
+ typewriterEffect: true,
154
+ });
155
+ });
156
+
157
+ onUnmounted(() => {
158
+ swarm?.destroy();
159
+ });
160
+ </script>
161
+
162
+ <template>
163
+ <div class="landing-page">
164
+ <h1>Autonomous UI Builder</h1>
165
+ <p>The swarm constructs this page live.</p>
166
+ </div>
167
+ </template>
168
+ ```
169
+
170
+ ### 5. Angular (`ngOnInit` & `ngOnDestroy`)
171
+
172
+ Works seamlessly in Angular standalone components or module-based architectures:
173
+
174
+ ```typescript
175
+ import { Component, OnInit, OnDestroy } from '@angular/core';
176
+ import { enableSwarm, DomSwarmInstance } from 'swarm66';
177
+
178
+ @Component({
179
+ selector: 'app-root',
180
+ template: `
181
+ <main>
182
+ <h1>Angular Live Construction</h1>
183
+ <p>Autonomous AI cursors reverse-engineer and construct your Angular DOM.</p>
184
+ </main>
185
+ `
186
+ })
187
+ export class AppComponent implements OnInit, OnDestroy {
188
+ private swarm?: DomSwarmInstance;
189
+
190
+ ngOnInit(): void {
191
+ this.swarm = enableSwarm({
192
+ agentCount: 18,
193
+ teamSize: 4,
194
+ hideOnStart: true,
195
+ buildOrder: 'top-to-bottom',
196
+ rebuildOnRouteChange: true, // Auto-rebuilds across Angular Router navigation
197
+ });
198
+ }
199
+
200
+ ngOnDestroy(): void {
201
+ this.swarm?.destroy();
202
+ }
203
+ }
204
+ ```
205
+
206
+ ### 6. Svelte & SvelteKit (`onMount`)
207
+
208
+ ```svelte
209
+ <script>
210
+ import { onMount } from 'svelte';
211
+ import { enableSwarm } from 'swarm66';
212
+
213
+ onMount(() => {
214
+ const swarm = enableSwarm({
215
+ hideOnStart: true,
216
+ typewriterEffect: true,
217
+ });
218
+
219
+ return () => swarm.destroy();
220
+ });
221
+ </script>
222
+
223
+ <main>
224
+ <h1>SvelteKit Swarm Experience</h1>
225
+ <p>Universal zero-dependency client animation.</p>
226
+ </main>
227
+ ```
228
+
229
+ ### 7. PHP (Vanilla PHP, Laravel, WordPress, Symfony)
230
+
231
+ `swarm66` requires zero npm build steps for PHP and server-side languages. Simply load the IIFE bundle via CDN or local asset:
232
+
233
+ #### **Vanilla PHP (`index.php`):**
234
+ ```php
235
+ <!DOCTYPE html>
236
+ <html lang="en">
237
+ <head>
238
+ <meta charset="UTF-8">
239
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
240
+ <title><?php echo "My PHP Application"; ?></title>
241
+ </head>
242
+ <body>
243
+ <h1>Welcome to PHP with swarm66</h1>
244
+ <p>Rendered on the server, built live by cursors in the client.</p>
245
+
246
+ <!-- Load swarm66 bundle -->
247
+ <script src="https://cdn.jsdelivr.net/npm/swarm66@1.0.0/dist/index.global.js"></script>
248
+ <script>
249
+ document.addEventListener('DOMContentLoaded', function() {
250
+ window.enableSwarm({
251
+ hideOnStart: true,
252
+ typewriterEffect: true,
253
+ vanishAtCursor: true
254
+ });
255
+ });
256
+ </script>
257
+ </body>
258
+ </html>
259
+ ```
260
+
261
+ #### **Laravel (Blade Template `welcome.blade.php`):**
262
+ ```html
263
+ @extends('layouts.app')
264
+
265
+ @section('content')
266
+ <div class="hero">
267
+ <h1>{{ __('Empowering Developers') }}</h1>
268
+ <p>{{ __('Built with Laravel and styled with Tailwind.') }}</p>
269
+ </div>
270
+ @endsection
271
+
272
+ @push('scripts')
273
+ <script src="https://cdn.jsdelivr.net/npm/swarm66@1.0.0/dist/index.global.js"></script>
274
+ <script>
275
+ document.addEventListener('DOMContentLoaded', () => {
276
+ enableSwarm({
277
+ hideOnStart: true,
278
+ concurrency: 4,
279
+ });
280
+ });
281
+ </script>
282
+ @endpush
283
+ ```
284
+
285
+ #### **WordPress (`footer.php` or `functions.php`):**
286
+ ```php
287
+ // In functions.php:
288
+ function enqueue_swarm66() {
289
+ wp_enqueue_script(
290
+ 'swarm66',
291
+ 'https://cdn.jsdelivr.net/npm/swarm66@1.0.0/dist/index.global.js',
292
+ array(),
293
+ '1.0.0',
294
+ true
295
+ );
296
+ wp_add_inline_script(
297
+ 'swarm66',
298
+ 'document.addEventListener("DOMContentLoaded", function() { window.enableSwarm({ hideOnStart: true }); });'
299
+ );
300
+ }
301
+ add_action('wp_enqueue_scripts', 'enqueue_swarm66');
302
+ ```
303
+
304
+ ### 8. Python (Django, Flask, FastAPI)
305
+
306
+ In your Django template (`base.html`):
307
+
308
+ ```html
309
+ {% load static %}
310
+ <!DOCTYPE html>
311
+ <html>
312
+ <head>
313
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
314
+ </head>
315
+ <body>
316
+ {% block content %}{% endblock %}
317
+
318
+ <script src="https://cdn.jsdelivr.net/npm/swarm66@1.0.0/dist/index.global.js"></script>
319
+ <script>
320
+ document.addEventListener('DOMContentLoaded', () => {
321
+ window.enableSwarm({ hideOnStart: true });
322
+ });
323
+ </script>
324
+ </body>
325
+ </html>
326
+ ```
327
+
328
+ ### 9. Ruby on Rails & ASP.NET Core
329
+
330
+ - **Rails (ERB `application.html.erb`):** Include via `<%= javascript_include_tag 'https://cdn.jsdelivr.net/npm/swarm66@1.0.0/dist/index.global.js' %>` or importmap `pin "swarm66"`.
331
+ - **ASP.NET Core (`_Layout.cshtml`):** Add `<script src="~/js/swarm66.global.js"></script>` before the closing `</body>` tag.
332
+
333
+ ---
334
+
335
+ ## 📱 Mobile & Touch Compatibility
336
+
337
+ `swarm66` is built from the ground up for modern responsive web development and touch screens:
338
+
339
+ - **Touch Interaction**: Automatically captures `touchstart` and `touchmove` events on smartphones and tablets, allowing idle cursors to orbit and converge directly around the user's thumb or finger.
340
+ - **Adaptive Screen Sizing**: Evaluates `window.innerWidth` and `window.innerHeight` dynamically during simulation. Boids flock boundaries gracefully scale whether on a 360px mobile viewport or a 3840px ultrawide monitor.
341
+ - **Single-Agent Touch Drags**: The Figma-style diagonal corner drag scales smoothly to mobile dimensions, rendering pixel dimension badges that adapt to compact screens without horizontal overflow.
342
+ - **Orientation & Viewport Resize**: Listens to viewport `resize` and `scroll` events with passive handlers to keep bounding box overlays pixel-aligned during dynamic mobile device rotation.
343
+
344
+ ---
345
+
346
+ ---
347
+
348
+ ## ⚙️ Configuration API Reference
349
+
350
+ Pass an options object to `enableSwarm(config)` or `new DomSwarm(config)`:
351
+
352
+ | Option | Type | Default | Description |
353
+ |---|---|---|---|
354
+ | `hideOnStart` | `boolean` | `true` | Starts the webpage blank while preserving the background, allowing the swarm to construct it live. |
355
+ | `vanishAtCursor` | `boolean` | `true` | Once all elements are constructed, all cursors accelerate into the user's cursor and vanish. |
356
+ | `concurrency` | `number` | `2` | Number of elements constructed in parallel waves. |
357
+ | `buildOrder` | `'top-to-bottom' \| 'random' \| 'viewport'` | `'top-to-bottom'` | Sequence in which elements are constructed. |
358
+ | `agentCount` | `number` | `18` | Total number of autonomous cursor agents in the swarm. |
359
+ | `teamSize` | `number` | `4` | Number of agents in each team (dispatched to the 4 borders of elements). |
360
+ | `colors` | `string[]` | `['#FF5722', '#00BCD4', '#8BC34A', '#9C27B0', '#FFC107', '#E91E63', '#2196F3']` | Vibrant color palette for cursors, wireframes, and name tags. |
361
+ | `selector` | `string` | `'nav, header, h1, h2, h3, h4, h5, h6, p, button, a, img, pre, code, .swarm-item'` | CSS selector targeting elements to construct. |
362
+ | `ignoreSelector` | `string` | `'[data-no-swarm], script, style, noscript, dom-swarm-overlay, .swarm-hud'` | CSS selector to exclude elements from swarm construction. |
363
+ | `typewriterEffect` | `boolean` | `true` | Simulates high-speed character typewriter reveals for text nodes (`p`, `h1`-`h6`, `code`). |
364
+ | `showGuides` | `boolean` | `true` | Displays full-screen horizontal and vertical Figma-style red alignment guides during construction. |
365
+ | `showDimensions` | `boolean` | `true` | Shows pixel dimension badges (e.g. `380 × 48`) on selection boxes. |
366
+ | `followMouse` | `boolean` | `true` | Idle agents flock and orbit dynamically around the user's cursor or touch location. |
367
+ | `maxSpeed` | `number` | `9.0` | Maximum agent velocity in pixels per frame. |
368
+ | `maxForce` | `number` | `0.38` | Maximum steering force applied during Boids calculations. |
369
+ | `buildDuration` | `number` | `600` | Duration (in milliseconds) spent constructing each element before moving to the next. |
370
+ | `customAgentNames` | `string[]` | `['Figma AI', 'Cursor-01', 'Copilot', 'Agent-α', 'Agent-β', 'PixelCraft', 'Architect', 'DevBot']` | List of avatar label badges rendered alongside cursors. |
371
+ | `onAllElementsConstructed` | `() => void` | `undefined` | Callback fired when every detected element has finished construction. |
372
+ | `onSwarmVanished` | `() => void` | `undefined` | Callback fired when all cursors have converged into the user's cursor and vanished. |
373
+
374
+ ---
375
+
376
+ ## 🕹️ Instance Methods
377
+
378
+ `enableSwarm()` returns a `DomSwarmInstance` with control methods:
379
+
380
+ ### `.replay(): void`
381
+ Clears the page back to blank, re-spawns cursors, and replays the entire live construction sequence from scratch.
382
+
383
+ ### `.buildElement(element: HTMLElement): Promise<void>`
384
+ Manually dispatches nearest autonomous agents to inspect and construct any element immediately.
385
+
386
+ ### `.pause(): void` / `.resume(): void`
387
+ Pauses or resumes the Boids physics loop and active construction tasks.
388
+
389
+ ### `.isFinished(): boolean`
390
+ Returns `true` if all elements are constructed and the swarm has vanished.
391
+
392
+ ### `.destroy(): void`
393
+ Completely tears down the overlay, cancels animation frames, unbinds event listeners, and cleanly restores all native DOM inline styles.
394
+
395
+ ---
396
+
397
+ ## 🧪 Local Testbed Demo
398
+
399
+ To run the interactive demo locally:
400
+
401
+ ```bash
402
+ # 1. Install dependencies
403
+ npm install
404
+
405
+ # 2. Build library bundle
406
+ npm run build
407
+
408
+ # 3. Start demo server
409
+ npm run demo
410
+ ```
411
+ Then visit `http://localhost:3000/demo/index.html`.
412
+
413
+ ---
414
+
415
+ ## 📄 License
416
+
417
+ MIT © [leozodiac](https://github.com/leozodiac/swarm66)