@nexart/ui-renderer 0.7.0 → 0.8.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/README.md +138 -319
- package/dist/capabilities.d.ts +5 -7
- package/dist/capabilities.d.ts.map +1 -1
- package/dist/capabilities.js +6 -8
- package/dist/compiler.d.ts +3 -3
- package/dist/compiler.js +4 -4
- package/dist/index.d.ts +33 -30
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +33 -30
- package/dist/preview/canvas-scaler.d.ts +70 -0
- package/dist/preview/canvas-scaler.d.ts.map +1 -0
- package/dist/preview/canvas-scaler.js +112 -0
- package/dist/preview/code-renderer.d.ts +11 -28
- package/dist/preview/code-renderer.d.ts.map +1 -1
- package/dist/preview/code-renderer.js +118 -660
- package/dist/preview/frame-budget.d.ts +43 -0
- package/dist/preview/frame-budget.d.ts.map +1 -0
- package/dist/preview/frame-budget.js +78 -0
- package/dist/preview/preview-engine.d.ts +42 -0
- package/dist/preview/preview-engine.d.ts.map +1 -0
- package/dist/preview/preview-engine.js +204 -0
- package/dist/preview/preview-runtime.d.ts +28 -0
- package/dist/preview/preview-runtime.d.ts.map +1 -0
- package/dist/preview/preview-runtime.js +512 -0
- package/dist/preview/preview-types.d.ts +116 -0
- package/dist/preview/preview-types.d.ts.map +1 -0
- package/dist/preview/preview-types.js +36 -0
- package/dist/preview/renderer.d.ts +3 -3
- package/dist/preview/renderer.js +3 -3
- package/dist/preview/unified-renderer.d.ts.map +1 -1
- package/dist/preview/unified-renderer.js +48 -22
- package/dist/system.d.ts +2 -2
- package/dist/system.d.ts.map +1 -1
- package/dist/system.js +8 -10
- package/dist/types.d.ts +9 -5
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +9 -5
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,228 +1,83 @@
|
|
|
1
1
|
# @nexart/ui-renderer
|
|
2
2
|
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.1
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**Lightweight Preview Runtime for NexArt Protocol**
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
> **This SDK is a PREVIEW
|
|
9
|
+
> **This SDK is a PREVIEW RENDERER, not an authority.**
|
|
10
10
|
>
|
|
11
|
-
> It
|
|
11
|
+
> It provides fast, lightweight previews for development and prototyping.
|
|
12
12
|
>
|
|
13
13
|
> It is:
|
|
14
14
|
> - **NOT canonical** — Does not produce archival-quality output
|
|
15
|
-
> - **NOT archival** — Not
|
|
16
|
-
> - **NOT protocol-
|
|
15
|
+
> - **NOT archival** — Not for minting, export, or permanent storage
|
|
16
|
+
> - **NOT protocol-enforcing** — No validation errors, no pattern checking
|
|
17
17
|
>
|
|
18
|
-
>
|
|
18
|
+
> For canonical output, minting, or validation: use `@nexart/codemode-sdk`
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
22
|
-
##
|
|
23
|
-
|
|
24
|
-
| Property | Value |
|
|
25
|
-
|----------|-------|
|
|
26
|
-
| Protocol Name | NexArt Code Mode |
|
|
27
|
-
| Version | v1.2.0 |
|
|
28
|
-
| Status | **STABLE** |
|
|
29
|
-
| Phase | 3 |
|
|
30
|
-
| This SDK | Mirror only — NOT authoritative |
|
|
31
|
-
| Canonical Authority | @nexart/codemode-sdk v1.4.0 |
|
|
32
|
-
| Lock Date | January 2026 |
|
|
33
|
-
|
|
34
|
-
**This SDK mirrors the v1.2.0 protocol surface. Any future protocol change requires v2.0.0 in @nexart/codemode-sdk first.**
|
|
35
|
-
|
|
36
|
-
This SDK mirrors:
|
|
37
|
-
- Execution model (Static and Loop modes)
|
|
38
|
-
- VAR[0..9] specification (0-10 input, always 10 at runtime)
|
|
39
|
-
- Determinism behavior (seed + VAR → consistent preview)
|
|
40
|
-
- Time semantics (t, frameCount, time, tGlobal, totalFrames)
|
|
41
|
-
- Forbidden patterns list (13 patterns)
|
|
42
|
-
- Error message format (`[Code Mode Protocol Error]`)
|
|
43
|
-
- v1.2.0 features: curveVertex, bezierVertex, pixel system, createGraphics
|
|
22
|
+
## v0.8.1 — Canvas Scaling Fix
|
|
44
23
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
## Protocol Alignment (v1.2.0)
|
|
48
|
-
|
|
49
|
-
This SDK mirrors NexArt Protocol behavior. It is NOT canonical.
|
|
50
|
-
|
|
51
|
-
**Canonical execution is performed exclusively by @nexart/codemode-sdk.**
|
|
52
|
-
|
|
53
|
-
This SDK exists for:
|
|
54
|
-
- Preview and prototyping
|
|
55
|
-
- Tooling and AI builders
|
|
56
|
-
- Development and experimentation
|
|
57
|
-
|
|
58
|
-
### Authority Boundaries
|
|
59
|
-
|
|
60
|
-
| Aspect | This SDK | @nexart/codemode-sdk |
|
|
61
|
-
|--------|----------|---------------------|
|
|
62
|
-
| Authority | None — mirror only | Canonical gate |
|
|
63
|
-
| Determinism | Mirrors protocol RNG | Authoritative RNG |
|
|
64
|
-
| VAR Handling | Protocol-aligned (read-only, 0-100) | Authoritative enforcement |
|
|
65
|
-
| Error Behavior | Mirrors protocol errors | Defines protocol errors |
|
|
66
|
-
| Output | Preview-quality | Archival-quality |
|
|
24
|
+
Fixed canvas zoom/cropping bug caused by resolution downscaling in v0.8.0.
|
|
67
25
|
|
|
68
|
-
|
|
26
|
+
- **Scale Transform Reapplied**: Context scale is now properly restored after canvas resize
|
|
27
|
+
- **Transform-Safe Clear**: `clearRect` now ignores active transforms for correct full-canvas clearing
|
|
28
|
+
- **No API Changes**: All fixes are internal
|
|
69
29
|
|
|
70
|
-
|
|
71
|
-
- **Code Mode** — Seeded RNG, VAR[0..9], forbidden patterns
|
|
72
|
-
- **SoundArt** — Audio-to-visual transformation via Code Mode
|
|
73
|
-
- **Noise** — Perlin/Cellular noise via Code Mode
|
|
74
|
-
- **Shapes** — Geometric generation via Code Mode
|
|
75
|
-
|
|
76
|
-
### Forbidden Patterns
|
|
77
|
-
|
|
78
|
-
The following patterns are rejected (mirroring @nexart/codemode-sdk exactly):
|
|
79
|
-
|
|
80
|
-
- `setTimeout`, `setInterval`, `requestAnimationFrame` — async timing
|
|
81
|
-
- `Date.now()`, `new Date()` — time-based entropy
|
|
82
|
-
- `Math.random()` — use `random()` instead (seeded)
|
|
83
|
-
- `fetch()`, `XMLHttpRequest` — external IO
|
|
84
|
-
- `createCanvas()` — canvas is pre-initialized
|
|
85
|
-
- `document.*`, `window.*` — DOM access forbidden
|
|
86
|
-
- `import`, `require()` — external imports forbidden
|
|
87
|
-
|
|
88
|
-
### VAR Protocol — v1.2.0 (MIRROR of SDK v1.4.0)
|
|
89
|
-
|
|
90
|
-
VAR[0..9] is a read-only array of 10 protocol variables (0-100 strict range).
|
|
30
|
+
---
|
|
91
31
|
|
|
92
|
-
|
|
32
|
+
## v0.8.0 — Lightweight Preview Runtime
|
|
93
33
|
|
|
94
|
-
|
|
95
|
-
|----------|-------|-------------|
|
|
96
|
-
| Input count | 0-10 (VAR[0]..VAR[9]) | HARD — throws if > 10 |
|
|
97
|
-
| Runtime count | Always 10 | Padded with zeros |
|
|
98
|
-
| Type | finite number | HARD — throws if non-number |
|
|
99
|
-
| Range | 0-100 | HARD — throws if out of range |
|
|
100
|
-
| Mutability | Read-only | HARD — frozen, writes throw |
|
|
101
|
-
| Injection | Before execution | Guaranteed |
|
|
102
|
-
| Lifecycle | Stable for entire render | Guaranteed |
|
|
103
|
-
| Default | All zeros | If not provided |
|
|
34
|
+
This release refactors the UI renderer into a performance-optimized preview runtime.
|
|
104
35
|
|
|
105
|
-
|
|
36
|
+
### Philosophy Change
|
|
106
37
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
38
|
+
**The UI renderer is explicitly preview-only:**
|
|
39
|
+
- No protocol errors thrown
|
|
40
|
+
- No forbidden pattern checking
|
|
41
|
+
- Soft warnings instead of hard failures
|
|
42
|
+
- Permissive — clamping instead of rejecting
|
|
111
43
|
|
|
112
|
-
|
|
113
|
-
const value = VAR[5]; // Returns 0 if not provided
|
|
44
|
+
### Preview Budget (MANDATORY)
|
|
114
45
|
|
|
115
|
-
|
|
116
|
-
VAR[0] = 50; // Throws: "[Code Mode Protocol Error] VAR is read-only..."
|
|
117
|
-
```
|
|
46
|
+
The runtime enforces hard limits to prevent browser freezes:
|
|
118
47
|
|
|
119
|
-
**Error examples:**
|
|
120
48
|
```typescript
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
//
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
// Valid: fewer than 10 elements (padded with zeros)
|
|
128
|
-
vars: [50, 75, 25] // Works! VAR[3..9] will be 0
|
|
49
|
+
PREVIEW_BUDGET = {
|
|
50
|
+
MAX_FRAMES: 30, // Maximum frames before auto-stop
|
|
51
|
+
MAX_TOTAL_TIME_MS: 500, // Maximum execution time
|
|
52
|
+
FRAME_STRIDE: 3, // Render every 3rd frame
|
|
53
|
+
};
|
|
129
54
|
```
|
|
130
55
|
|
|
131
|
-
|
|
56
|
+
If limits exceeded: rendering stops silently (no throw).
|
|
132
57
|
|
|
133
|
-
|
|
58
|
+
### Canvas Scaling
|
|
134
59
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
### `background`
|
|
138
|
-
|
|
139
|
-
Opinionated presets with guardrails. Provides consistent, protocol-aligned backgrounds.
|
|
60
|
+
Preview renderer scales large canvases automatically:
|
|
140
61
|
|
|
141
62
|
```typescript
|
|
142
|
-
{
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
}
|
|
63
|
+
CANVAS_LIMITS = {
|
|
64
|
+
MAX_DIMENSION: 900, // Max width/height in pixels
|
|
65
|
+
MIN_DIMENSION: 100,
|
|
66
|
+
};
|
|
147
67
|
```
|
|
148
68
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
Declarative generative components. Structured parameters, no raw code. **30 primitives available:**
|
|
152
|
-
|
|
153
|
-
**Basic Shapes:**
|
|
154
|
-
- `dots` — Grid/random dot patterns
|
|
155
|
-
- `lines` — Vertical wavy lines
|
|
156
|
-
- `waves` — Horizontal wave patterns
|
|
157
|
-
- `stripes` — Simple horizontal stripes
|
|
158
|
-
- `circles` — Concentric pulsing circles
|
|
159
|
-
- `grid` — Rotating square grid
|
|
160
|
-
|
|
161
|
-
**Geometric:**
|
|
162
|
-
- `polygons` — Random rotating polygons (3-7 sides)
|
|
163
|
-
- `diamonds` — Diamond grid with noise rotation
|
|
164
|
-
- `hexgrid` — Honeycomb hexagonal grid
|
|
165
|
-
- `stars` — Scattered rotating star shapes
|
|
166
|
-
- `concentricSquares` — Nested rotating squares
|
|
167
|
-
|
|
168
|
-
**Radial:**
|
|
169
|
-
- `spirals` — Multiple expanding spirals
|
|
170
|
-
- `rays` — Lines emanating from center
|
|
171
|
-
- `orbits` — Wobbling orbital rings
|
|
172
|
-
- `rings` — Alternating concentric rings
|
|
173
|
-
- `arcs` — Random partial circles
|
|
174
|
-
- `radialLines` — Lines from inner to outer radius
|
|
175
|
-
- `petals` — Flower petal pattern
|
|
176
|
-
|
|
177
|
-
**Flow & Motion:**
|
|
178
|
-
- `flow` — Particle flow field
|
|
179
|
-
- `particles` — Scattered particles with tails
|
|
180
|
-
- `bubbles` — Rising floating bubbles
|
|
181
|
-
|
|
182
|
-
**Patterns:**
|
|
183
|
-
- `crosshatch` — Cross-hatched shading lines
|
|
184
|
-
- `chevrons` — V-shaped wave patterns
|
|
185
|
-
- `zigzag` — Zigzag horizontal lines
|
|
186
|
-
- `weave` — Interlocking woven pattern
|
|
187
|
-
- `moire` — Overlapping circle interference
|
|
188
|
-
|
|
189
|
-
**Organic:**
|
|
190
|
-
- `curves` — Random bezier curves
|
|
191
|
-
- `noise` — Perlin noise vector field
|
|
192
|
-
- `mesh` — Deformed triangular mesh
|
|
193
|
-
- `branches` — Fractal tree branches
|
|
69
|
+
Aspect ratio is preserved. CSS scaling for display.
|
|
194
70
|
|
|
195
|
-
|
|
196
|
-
{
|
|
197
|
-
type: 'primitive',
|
|
198
|
-
name: 'spirals', // Any of the 30 primitives above
|
|
199
|
-
count: 12,
|
|
200
|
-
color: '#ffffff',
|
|
201
|
-
motion: 'medium', // 'slow', 'medium', 'fast'
|
|
202
|
-
strokeWeight: 'thin', // 'thin', 'medium', 'thick', or number
|
|
203
|
-
opacity: 0.8
|
|
204
|
-
}
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
### `sketch`
|
|
71
|
+
### Runtime Mode Flag
|
|
208
72
|
|
|
209
|
-
|
|
73
|
+
The preview runtime exposes a `mode` property:
|
|
210
74
|
|
|
211
75
|
```typescript
|
|
212
|
-
|
|
213
|
-
type: 'sketch',
|
|
214
|
-
code: `
|
|
215
|
-
function setup() {
|
|
216
|
-
background(0);
|
|
217
|
-
}
|
|
218
|
-
function draw() {
|
|
219
|
-
ellipse(width/2, height/2, 100);
|
|
220
|
-
}
|
|
221
|
-
`,
|
|
222
|
-
normalize: true
|
|
223
|
-
}
|
|
76
|
+
runtime.mode // 'preview'
|
|
224
77
|
```
|
|
225
78
|
|
|
79
|
+
Use this to detect preview vs canonical rendering.
|
|
80
|
+
|
|
226
81
|
---
|
|
227
82
|
|
|
228
83
|
## Install
|
|
@@ -242,9 +97,7 @@ Or use directly in HTML:
|
|
|
242
97
|
|
|
243
98
|
## Quick Start
|
|
244
99
|
|
|
245
|
-
### Code Mode
|
|
246
|
-
|
|
247
|
-
Create and preview Code Mode sketches using protocol variables:
|
|
100
|
+
### Code Mode Preview
|
|
248
101
|
|
|
249
102
|
```typescript
|
|
250
103
|
import { createSystem, previewSystem } from '@nexart/ui-renderer';
|
|
@@ -256,7 +109,7 @@ const system = createSystem({
|
|
|
256
109
|
height: 2400,
|
|
257
110
|
totalFrames: 120,
|
|
258
111
|
seed: 12345,
|
|
259
|
-
vars: [50, 75, 25, 0
|
|
112
|
+
vars: [50, 75, 25], // VAR[0..9] — values 0-100, padded with zeros
|
|
260
113
|
source: `
|
|
261
114
|
function setup() {
|
|
262
115
|
noFill();
|
|
@@ -264,7 +117,7 @@ const system = createSystem({
|
|
|
264
117
|
}
|
|
265
118
|
function draw() {
|
|
266
119
|
background(246, 245, 242);
|
|
267
|
-
var count =
|
|
120
|
+
var count = int(map(VAR[0], 0, 100, 5, 30));
|
|
268
121
|
for (var i = 0; i < count; i++) {
|
|
269
122
|
var x = width / 2 + cos(t * TWO_PI + i * 0.5) * map(VAR[1], 0, 100, 50, 400);
|
|
270
123
|
var y = height / 2 + sin(t * TWO_PI + i * 0.3) * 200;
|
|
@@ -279,7 +132,7 @@ const renderer = previewSystem(system, canvas);
|
|
|
279
132
|
renderer.start();
|
|
280
133
|
```
|
|
281
134
|
|
|
282
|
-
|
|
135
|
+
### Static Mode (single frame)
|
|
283
136
|
|
|
284
137
|
```typescript
|
|
285
138
|
const staticSystem = createSystem({
|
|
@@ -288,12 +141,12 @@ const staticSystem = createSystem({
|
|
|
288
141
|
width: 1950,
|
|
289
142
|
height: 2400,
|
|
290
143
|
seed: 12345,
|
|
291
|
-
vars: [50, 50, 50
|
|
144
|
+
vars: [50, 50, 50],
|
|
292
145
|
source: `
|
|
293
146
|
function setup() {
|
|
294
147
|
background(246, 245, 242);
|
|
295
148
|
fill(0);
|
|
296
|
-
var count =
|
|
149
|
+
var count = int(map(VAR[0], 0, 100, 10, 200));
|
|
297
150
|
for (var i = 0; i < count; i++) {
|
|
298
151
|
ellipse(random(width), random(height), random(10, 50));
|
|
299
152
|
}
|
|
@@ -310,9 +163,8 @@ previewSystem(staticSystem, canvas).render();
|
|
|
310
163
|
|
|
311
164
|
### `createSystem(input)`
|
|
312
165
|
|
|
313
|
-
Create a
|
|
166
|
+
Create a NexArt system for preview.
|
|
314
167
|
|
|
315
|
-
**Code Mode Input:**
|
|
316
168
|
```typescript
|
|
317
169
|
const system = createSystem({
|
|
318
170
|
type: 'code',
|
|
@@ -320,36 +172,35 @@ const system = createSystem({
|
|
|
320
172
|
width: number,
|
|
321
173
|
height: number,
|
|
322
174
|
source: string, // Raw p5-like sketch code
|
|
323
|
-
seed?: number, //
|
|
175
|
+
seed?: number, // PRNG seed
|
|
324
176
|
totalFrames?: number, // Required for loop mode
|
|
325
|
-
vars?: number[] //
|
|
177
|
+
vars?: number[] // VAR[0..9] (0-10 values, 0-100 range, clamped)
|
|
326
178
|
});
|
|
327
179
|
```
|
|
328
180
|
|
|
329
181
|
### `previewSystem(system, canvas, options?)`
|
|
330
182
|
|
|
331
|
-
Render a
|
|
183
|
+
Render a preview to canvas.
|
|
332
184
|
|
|
333
185
|
```typescript
|
|
334
186
|
const renderer = previewSystem(system, canvas, {
|
|
335
|
-
|
|
336
|
-
showBadge: boolean // default: true
|
|
187
|
+
showBadge: boolean // default: true — shows "⚠️ Preview" badge
|
|
337
188
|
});
|
|
338
189
|
|
|
339
190
|
renderer.render(); // Single frame
|
|
340
|
-
renderer.start(); //
|
|
191
|
+
renderer.start(); // Start loop
|
|
341
192
|
renderer.stop(); // Stop loop
|
|
342
193
|
renderer.destroy(); // Cleanup
|
|
343
194
|
```
|
|
344
195
|
|
|
345
196
|
### `validateSystem(input)`
|
|
346
197
|
|
|
347
|
-
|
|
198
|
+
Soft validation — warns but doesn't throw for minor issues.
|
|
348
199
|
|
|
349
200
|
```typescript
|
|
350
201
|
const result = validateSystem(input);
|
|
351
202
|
if (!result.valid) {
|
|
352
|
-
console.
|
|
203
|
+
console.log(result.errors); // Structural issues only
|
|
353
204
|
}
|
|
354
205
|
```
|
|
355
206
|
|
|
@@ -362,163 +213,131 @@ import { getCapabilities } from '@nexart/ui-renderer';
|
|
|
362
213
|
|
|
363
214
|
const caps = getCapabilities();
|
|
364
215
|
// {
|
|
365
|
-
// version: '0.
|
|
216
|
+
// version: '0.8.1',
|
|
366
217
|
// isCanonical: false,
|
|
367
218
|
// isArchival: false,
|
|
368
|
-
//
|
|
369
|
-
//
|
|
370
|
-
// primitives: [ { name, category, description, parameters } ],
|
|
219
|
+
// previewBudget: { MAX_FRAMES: 30, MAX_TOTAL_TIME_MS: 500, FRAME_STRIDE: 3 },
|
|
220
|
+
// canvasLimits: { MAX_DIMENSION: 900 },
|
|
371
221
|
// ...
|
|
372
222
|
// }
|
|
373
223
|
```
|
|
374
224
|
|
|
375
|
-
|
|
225
|
+
---
|
|
376
226
|
|
|
377
|
-
|
|
227
|
+
## Available Helpers
|
|
378
228
|
|
|
379
|
-
|
|
380
|
-
import { getPrimitiveTypes } from '@nexart/ui-renderer';
|
|
229
|
+
The preview runtime includes all standard p5-like functions plus:
|
|
381
230
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
231
|
+
| Helper | Description |
|
|
232
|
+
|--------|-------------|
|
|
233
|
+
| `int(n)` | Convert to integer (Math.floor) |
|
|
234
|
+
| `fract(n)` | Fractional part of number |
|
|
235
|
+
| `sign(n)` | Sign of number |
|
|
236
|
+
| `vec(x, y)` | Create 2D vector |
|
|
237
|
+
| `polygon(x, y, r, n)` | Draw n-sided polygon |
|
|
238
|
+
| `star(x, y, r1, r2, n)` | Draw n-pointed star |
|
|
239
|
+
| `fbm(x, y, z, octaves)` | Fractal Brownian motion |
|
|
240
|
+
| `easeIn(t)`, `easeOut(t)`, etc. | Easing functions |
|
|
385
241
|
|
|
386
|
-
###
|
|
242
|
+
### Control Functions
|
|
387
243
|
|
|
388
|
-
|
|
244
|
+
| Function | Preview Behavior |
|
|
245
|
+
|----------|------------------|
|
|
246
|
+
| `noLoop()` | Stops preview loop (soft control) |
|
|
247
|
+
| `loop()` | No-op in preview |
|
|
389
248
|
|
|
390
|
-
|
|
391
|
-
import { getPrimitivesByCategory } from '@nexart/ui-renderer';
|
|
249
|
+
---
|
|
392
250
|
|
|
393
|
-
|
|
394
|
-
// {
|
|
395
|
-
// basic: ['dots', 'lines', 'waves', 'stripes', 'circles', 'grid'],
|
|
396
|
-
// geometric: ['polygons', 'diamonds', 'hexgrid', 'stars', 'concentricSquares'],
|
|
397
|
-
// radial: ['spirals', 'rays', 'orbits', 'rings', 'arcs', 'radialLines', 'petals'],
|
|
398
|
-
// flow: ['flow', 'particles', 'bubbles'],
|
|
399
|
-
// patterns: ['crosshatch', 'chevrons', 'zigzag', 'weave', 'moire'],
|
|
400
|
-
// organic: ['curves', 'noise', 'mesh', 'branches']
|
|
401
|
-
// }
|
|
402
|
-
```
|
|
251
|
+
## Supported Element Types
|
|
403
252
|
|
|
404
|
-
### `
|
|
253
|
+
### `background`
|
|
405
254
|
|
|
406
|
-
|
|
255
|
+
Opinionated presets with guardrails.
|
|
407
256
|
|
|
408
257
|
```typescript
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
//
|
|
413
|
-
|
|
414
|
-
// category: 'radial',
|
|
415
|
-
// description: 'Multiple expanding spirals from center',
|
|
416
|
-
// compilesTo: 'codemode',
|
|
417
|
-
// isCanonical: false,
|
|
418
|
-
// parameters: { count, color, opacity, strokeWeight, motion }
|
|
419
|
-
// }
|
|
258
|
+
{
|
|
259
|
+
type: 'background',
|
|
260
|
+
style: 'gradient', // gradient, solid, noise, grain
|
|
261
|
+
palette: 'warm' // warm, cool, neutral, vibrant
|
|
262
|
+
}
|
|
420
263
|
```
|
|
421
264
|
|
|
422
|
-
### `
|
|
265
|
+
### `primitive`
|
|
423
266
|
|
|
424
|
-
|
|
267
|
+
Declarative generative components. **30 primitives available:**
|
|
425
268
|
|
|
426
|
-
|
|
427
|
-
|
|
269
|
+
**Categories:**
|
|
270
|
+
- `basic` — dots, lines, waves, stripes, circles, grid
|
|
271
|
+
- `geometric` — polygons, diamonds, hexgrid, stars, concentricSquares
|
|
272
|
+
- `radial` — spirals, rays, orbits, rings, arcs, radialLines, petals
|
|
273
|
+
- `flow` — flow, particles, bubbles
|
|
274
|
+
- `patterns` — crosshatch, chevrons, zigzag, weave, moire
|
|
275
|
+
- `organic` — curves, noise, mesh, branches
|
|
428
276
|
|
|
429
|
-
|
|
430
|
-
|
|
277
|
+
```typescript
|
|
278
|
+
{
|
|
279
|
+
type: 'primitive',
|
|
280
|
+
name: 'spirals',
|
|
281
|
+
count: 12,
|
|
282
|
+
color: '#ffffff',
|
|
283
|
+
motion: 'medium',
|
|
284
|
+
strokeWeight: 'thin',
|
|
285
|
+
opacity: 0.8
|
|
286
|
+
}
|
|
431
287
|
```
|
|
432
288
|
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
## AI Capabilities API
|
|
436
|
-
|
|
437
|
-
**Designed for AI agents to build valid systems without hallucination.**
|
|
438
|
-
|
|
439
|
-
⚠️ **Primitives are helper generators that compile to Code Mode sketches.**
|
|
440
|
-
They are NOT canonical. The canonical output is always the compiled Code Mode source.
|
|
289
|
+
### `sketch`
|
|
441
290
|
|
|
442
|
-
|
|
291
|
+
Raw Code Mode execution.
|
|
443
292
|
|
|
444
293
|
```typescript
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
for (const p of caps.primitives) {
|
|
454
|
-
console.log(p.name); // 'dots', 'spirals', etc.
|
|
455
|
-
console.log(p.category); // 'basic', 'radial', etc.
|
|
456
|
-
console.log(p.description); // Human-readable description
|
|
457
|
-
console.log(p.parameters.count.min); // 3
|
|
458
|
-
console.log(p.parameters.count.max); // 50
|
|
459
|
-
console.log(p.parameters.count.default); // 12
|
|
294
|
+
{
|
|
295
|
+
type: 'sketch',
|
|
296
|
+
code: `
|
|
297
|
+
function setup() { background(0); }
|
|
298
|
+
function draw() { ellipse(width/2, height/2, 100); }
|
|
299
|
+
`,
|
|
300
|
+
normalize: true
|
|
460
301
|
}
|
|
461
302
|
```
|
|
462
303
|
|
|
463
|
-
### Primitive Parameter Specification
|
|
464
|
-
|
|
465
|
-
All primitives share these parameters:
|
|
466
|
-
|
|
467
|
-
| Parameter | Type | Required | Range | Default |
|
|
468
|
-
|-----------|------|----------|-------|---------|
|
|
469
|
-
| `count` | number | No | 3-50 | 12 |
|
|
470
|
-
| `color` | string | No | CSS color | Palette foreground |
|
|
471
|
-
| `opacity` | number | No | 0.1-1 | 1 |
|
|
472
|
-
| `strokeWeight` | enum | No | 'auto', 'thin', 'medium', 'thick' | 'auto' |
|
|
473
|
-
| `motion` | enum | No | 'slow', 'medium', 'fast' | 'slow' |
|
|
474
|
-
|
|
475
|
-
### Valid Primitive Categories
|
|
476
|
-
|
|
477
|
-
| Category | Primitives |
|
|
478
|
-
|----------|-----------|
|
|
479
|
-
| `basic` | dots, lines, waves, stripes, circles, grid |
|
|
480
|
-
| `geometric` | polygons, diamonds, hexgrid, stars, concentricSquares |
|
|
481
|
-
| `radial` | spirals, rays, orbits, rings, arcs, radialLines, petals |
|
|
482
|
-
| `flow` | flow, particles, bubbles |
|
|
483
|
-
| `patterns` | crosshatch, chevrons, zigzag, weave, moire |
|
|
484
|
-
| `organic` | curves, noise, mesh, branches |
|
|
485
|
-
|
|
486
304
|
---
|
|
487
305
|
|
|
488
|
-
##
|
|
306
|
+
## VAR Handling (Soft)
|
|
489
307
|
|
|
490
|
-
|
|
308
|
+
VAR[0..9] is an array of 10 protocol variables.
|
|
491
309
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
---
|
|
310
|
+
**Preview behavior (permissive):**
|
|
311
|
+
- Input: 0-10 elements accepted (extras ignored with warning)
|
|
312
|
+
- Values: Clamped to 0-100 (not rejected)
|
|
313
|
+
- Invalid types: Replaced with 0 (not rejected)
|
|
314
|
+
- Runtime: Always 10 elements (padded with zeros)
|
|
315
|
+
- Access: Read-only
|
|
499
316
|
|
|
500
|
-
|
|
317
|
+
```typescript
|
|
318
|
+
// Works in preview (clamped to 100)
|
|
319
|
+
vars: [150, 50, 50] // VAR[0] becomes 100
|
|
501
320
|
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
- Black canvas is displayed
|
|
505
|
-
- Error is logged verbatim
|
|
506
|
-
- No "best effort" recovery
|
|
321
|
+
// Works in preview (non-numbers become 0)
|
|
322
|
+
vars: ['bad', 50, 50] // VAR[0] becomes 0
|
|
507
323
|
|
|
324
|
+
// Works in preview (extras ignored)
|
|
325
|
+
vars: [1,2,3,4,5,6,7,8,9,10,11,12] // Uses first 10
|
|
508
326
|
```
|
|
509
|
-
|
|
510
|
-
|
|
327
|
+
|
|
328
|
+
For strict validation, use `@nexart/codemode-sdk`.
|
|
511
329
|
|
|
512
330
|
---
|
|
513
331
|
|
|
514
|
-
## What This SDK Does NOT
|
|
332
|
+
## What This SDK Does NOT Do
|
|
515
333
|
|
|
516
|
-
| Not
|
|
517
|
-
|
|
518
|
-
|
|
|
519
|
-
|
|
|
520
|
-
|
|
|
521
|
-
|
|
|
334
|
+
| Not Done | Explanation |
|
|
335
|
+
|----------|-------------|
|
|
336
|
+
| Protocol enforcement | No pattern checking or validation errors |
|
|
337
|
+
| Canonical output | Use @nexart/codemode-sdk for minting |
|
|
338
|
+
| Determinism guarantee | Preview may vary slightly |
|
|
339
|
+
| Full frame count | Limited to 30 frames max |
|
|
340
|
+
| Full resolution | Limited to 900px max dimension |
|
|
522
341
|
|
|
523
342
|
---
|
|
524
343
|
|
package/dist/capabilities.d.ts
CHANGED
|
@@ -1,14 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @nexart/ui-renderer v0.
|
|
2
|
+
* @nexart/ui-renderer v0.8.0 - Capabilities Discovery
|
|
3
3
|
*
|
|
4
4
|
* Exposes SDK capabilities for AI tools and builders.
|
|
5
|
-
*
|
|
6
|
-
* Mirrors @nexart/codemode-sdk v1.4.0 (Protocol v1.2.0)
|
|
5
|
+
* Lightweight preview runtime — no protocol enforcement.
|
|
7
6
|
*
|
|
8
|
-
* ⚠️
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* The canonical output is always the compiled Code Mode source.
|
|
7
|
+
* ⚠️ PREVIEW ONLY
|
|
8
|
+
* This SDK provides preview rendering with performance limits.
|
|
9
|
+
* For canonical output: use @nexart/codemode-sdk
|
|
12
10
|
*/
|
|
13
11
|
export interface PrimitiveCapability {
|
|
14
12
|
name: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE;QACV,KAAK,EAAE,aAAa,CAAC;QACrB,KAAK,EAAE,aAAa,CAAC;QACrB,OAAO,EAAE,aAAa,CAAC;QACvB,YAAY,EAAE,aAAa,CAAC;QAC5B,MAAM,EAAE,aAAa,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACzD,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;IAClB,QAAQ,EAAE,qBAAqB,CAAC;IAEhC,cAAc,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,WAAW,EAAE,KAAK,CAAC;KACpB,CAAC;IAEF,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAElC,UAAU,EAAE;QACV,KAAK,EAAE,aAAa,CAAC;QACrB,OAAO,EAAE,aAAa,CAAC;QACvB,QAAQ,EAAE;YACR,IAAI,EAAE,aAAa,CAAC;YACpB,MAAM,EAAE,aAAa,CAAC;YACtB,KAAK,EAAE,aAAa,CAAC;SACtB,CAAC;KACH,CAAC;IAEF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,EAAE,aAAa,CAAC;KACtB,CAAC;IAEF,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAwDD,wBAAgB,eAAe,IAAI,YAAY,CA0G9C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAS5C;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CASlE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAGzE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}
|