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