@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.
- package/ARCHITECTURE.md +132 -0
- package/LICENSE +22 -0
- package/README.md +416 -2
- package/TASKS.md +127 -0
- package/dist/index.cjs +237 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.mts +766 -0
- package/dist/index.d.ts +766 -0
- package/dist/index.global.js +237 -0
- package/dist/index.global.js.map +1 -0
- package/dist/index.js +237 -0
- package/dist/index.js.map +1 -0
- package/package.json +69 -4
package/ARCHITECTURE.md
ADDED
|
@@ -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
|
-
#
|
|
1
|
+
# @leozodiac/swarm66 ⚡
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/@leozodiac/swarm66)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](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)
|