@nexart/ui-renderer 0.7.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 +132 -323
- 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 +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 +115 -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 +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 -3
- package/dist/preview/renderer.js +3 -3
- 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 +2 -2
package/README.md
CHANGED
|
@@ -1,228 +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
|
-
##
|
|
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.0 — Lightweight Preview Runtime
|
|
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
|
+
This release refactors the UI renderer into a performance-optimized preview runtime.
|
|
67
25
|
|
|
68
|
-
###
|
|
26
|
+
### Philosophy Change
|
|
69
27
|
|
|
70
|
-
|
|
71
|
-
-
|
|
72
|
-
-
|
|
73
|
-
-
|
|
74
|
-
-
|
|
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
|
|
75
33
|
|
|
76
|
-
###
|
|
34
|
+
### Preview Budget (MANDATORY)
|
|
77
35
|
|
|
78
|
-
The
|
|
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).
|
|
91
|
-
|
|
92
|
-
**VAR Specification (mirrors @nexart/codemode-sdk v1.4.0):**
|
|
93
|
-
|
|
94
|
-
| Property | Value | Enforcement |
|
|
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 |
|
|
104
|
-
|
|
105
|
-
**This specification mirrors @nexart/codemode-sdk v1.4.0 exactly.**
|
|
36
|
+
The runtime enforces hard limits to prevent browser freezes:
|
|
106
37
|
|
|
107
38
|
```typescript
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
const value = VAR[5]; // Returns 0 if not provided
|
|
114
|
-
|
|
115
|
-
// Error: VAR is read-only
|
|
116
|
-
VAR[0] = 50; // Throws: "[Code Mode Protocol Error] VAR is read-only..."
|
|
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
|
+
};
|
|
117
44
|
```
|
|
118
45
|
|
|
119
|
-
|
|
120
|
-
```typescript
|
|
121
|
-
// Protocol error: too many elements
|
|
122
|
-
vars: [1,2,3,4,5,6,7,8,9,10,11] // Throws: "VAR array must have at most 10 elements, got 11"
|
|
123
|
-
|
|
124
|
-
// Protocol error: out of range
|
|
125
|
-
vars: [150, 50, 50] // Throws: "VAR[0] = 150 is out of range. Values must be 0-100."
|
|
46
|
+
If limits exceeded: rendering stops silently (no throw).
|
|
126
47
|
|
|
127
|
-
|
|
128
|
-
vars: [50, 75, 25] // Works! VAR[3..9] will be 0
|
|
129
|
-
```
|
|
48
|
+
### Canvas Scaling
|
|
130
49
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
## Supported Element Types
|
|
134
|
-
|
|
135
|
-
The SDK supports three element types, rendered in order:
|
|
136
|
-
|
|
137
|
-
### `background`
|
|
138
|
-
|
|
139
|
-
Opinionated presets with guardrails. Provides consistent, protocol-aligned backgrounds.
|
|
50
|
+
Preview renderer scales large canvases automatically:
|
|
140
51
|
|
|
141
52
|
```typescript
|
|
142
|
-
{
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
}
|
|
53
|
+
CANVAS_LIMITS = {
|
|
54
|
+
MAX_DIMENSION: 900, // Max width/height in pixels
|
|
55
|
+
MIN_DIMENSION: 100,
|
|
56
|
+
};
|
|
147
57
|
```
|
|
148
58
|
|
|
149
|
-
|
|
59
|
+
Aspect ratio is preserved. CSS scaling for display.
|
|
150
60
|
|
|
151
|
-
|
|
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
|
|
194
|
-
|
|
195
|
-
```typescript
|
|
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
|
-
```
|
|
61
|
+
### Runtime Mode Flag
|
|
206
62
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
Raw Code Mode execution in a sandboxed environment. Full p5-like API access.
|
|
63
|
+
The preview runtime exposes a `mode` property:
|
|
210
64
|
|
|
211
65
|
```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
|
-
}
|
|
66
|
+
runtime.mode // 'preview'
|
|
224
67
|
```
|
|
225
68
|
|
|
69
|
+
Use this to detect preview vs canonical rendering.
|
|
70
|
+
|
|
226
71
|
---
|
|
227
72
|
|
|
228
73
|
## Install
|
|
@@ -242,9 +87,7 @@ Or use directly in HTML:
|
|
|
242
87
|
|
|
243
88
|
## Quick Start
|
|
244
89
|
|
|
245
|
-
### Code Mode
|
|
246
|
-
|
|
247
|
-
Create and preview Code Mode sketches using protocol variables:
|
|
90
|
+
### Code Mode Preview
|
|
248
91
|
|
|
249
92
|
```typescript
|
|
250
93
|
import { createSystem, previewSystem } from '@nexart/ui-renderer';
|
|
@@ -256,7 +99,7 @@ const system = createSystem({
|
|
|
256
99
|
height: 2400,
|
|
257
100
|
totalFrames: 120,
|
|
258
101
|
seed: 12345,
|
|
259
|
-
vars: [50, 75, 25, 0
|
|
102
|
+
vars: [50, 75, 25], // VAR[0..9] — values 0-100, padded with zeros
|
|
260
103
|
source: `
|
|
261
104
|
function setup() {
|
|
262
105
|
noFill();
|
|
@@ -264,7 +107,7 @@ const system = createSystem({
|
|
|
264
107
|
}
|
|
265
108
|
function draw() {
|
|
266
109
|
background(246, 245, 242);
|
|
267
|
-
var count =
|
|
110
|
+
var count = int(map(VAR[0], 0, 100, 5, 30));
|
|
268
111
|
for (var i = 0; i < count; i++) {
|
|
269
112
|
var x = width / 2 + cos(t * TWO_PI + i * 0.5) * map(VAR[1], 0, 100, 50, 400);
|
|
270
113
|
var y = height / 2 + sin(t * TWO_PI + i * 0.3) * 200;
|
|
@@ -279,7 +122,7 @@ const renderer = previewSystem(system, canvas);
|
|
|
279
122
|
renderer.start();
|
|
280
123
|
```
|
|
281
124
|
|
|
282
|
-
|
|
125
|
+
### Static Mode (single frame)
|
|
283
126
|
|
|
284
127
|
```typescript
|
|
285
128
|
const staticSystem = createSystem({
|
|
@@ -288,12 +131,12 @@ const staticSystem = createSystem({
|
|
|
288
131
|
width: 1950,
|
|
289
132
|
height: 2400,
|
|
290
133
|
seed: 12345,
|
|
291
|
-
vars: [50, 50, 50
|
|
134
|
+
vars: [50, 50, 50],
|
|
292
135
|
source: `
|
|
293
136
|
function setup() {
|
|
294
137
|
background(246, 245, 242);
|
|
295
138
|
fill(0);
|
|
296
|
-
var count =
|
|
139
|
+
var count = int(map(VAR[0], 0, 100, 10, 200));
|
|
297
140
|
for (var i = 0; i < count; i++) {
|
|
298
141
|
ellipse(random(width), random(height), random(10, 50));
|
|
299
142
|
}
|
|
@@ -310,9 +153,8 @@ previewSystem(staticSystem, canvas).render();
|
|
|
310
153
|
|
|
311
154
|
### `createSystem(input)`
|
|
312
155
|
|
|
313
|
-
Create a
|
|
156
|
+
Create a NexArt system for preview.
|
|
314
157
|
|
|
315
|
-
**Code Mode Input:**
|
|
316
158
|
```typescript
|
|
317
159
|
const system = createSystem({
|
|
318
160
|
type: 'code',
|
|
@@ -320,36 +162,35 @@ const system = createSystem({
|
|
|
320
162
|
width: number,
|
|
321
163
|
height: number,
|
|
322
164
|
source: string, // Raw p5-like sketch code
|
|
323
|
-
seed?: number, //
|
|
165
|
+
seed?: number, // PRNG seed
|
|
324
166
|
totalFrames?: number, // Required for loop mode
|
|
325
|
-
vars?: number[] //
|
|
167
|
+
vars?: number[] // VAR[0..9] (0-10 values, 0-100 range, clamped)
|
|
326
168
|
});
|
|
327
169
|
```
|
|
328
170
|
|
|
329
171
|
### `previewSystem(system, canvas, options?)`
|
|
330
172
|
|
|
331
|
-
Render a
|
|
173
|
+
Render a preview to canvas.
|
|
332
174
|
|
|
333
175
|
```typescript
|
|
334
176
|
const renderer = previewSystem(system, canvas, {
|
|
335
|
-
|
|
336
|
-
showBadge: boolean // default: true
|
|
177
|
+
showBadge: boolean // default: true — shows "⚠️ Preview" badge
|
|
337
178
|
});
|
|
338
179
|
|
|
339
180
|
renderer.render(); // Single frame
|
|
340
|
-
renderer.start(); //
|
|
181
|
+
renderer.start(); // Start loop
|
|
341
182
|
renderer.stop(); // Stop loop
|
|
342
183
|
renderer.destroy(); // Cleanup
|
|
343
184
|
```
|
|
344
185
|
|
|
345
186
|
### `validateSystem(input)`
|
|
346
187
|
|
|
347
|
-
|
|
188
|
+
Soft validation — warns but doesn't throw for minor issues.
|
|
348
189
|
|
|
349
190
|
```typescript
|
|
350
191
|
const result = validateSystem(input);
|
|
351
192
|
if (!result.valid) {
|
|
352
|
-
console.
|
|
193
|
+
console.log(result.errors); // Structural issues only
|
|
353
194
|
}
|
|
354
195
|
```
|
|
355
196
|
|
|
@@ -362,163 +203,131 @@ import { getCapabilities } from '@nexart/ui-renderer';
|
|
|
362
203
|
|
|
363
204
|
const caps = getCapabilities();
|
|
364
205
|
// {
|
|
365
|
-
// version: '0.
|
|
206
|
+
// version: '0.8.0',
|
|
366
207
|
// isCanonical: false,
|
|
367
208
|
// isArchival: false,
|
|
368
|
-
//
|
|
369
|
-
//
|
|
370
|
-
// primitives: [ { name, category, description, parameters } ],
|
|
209
|
+
// previewBudget: { MAX_FRAMES: 30, MAX_TOTAL_TIME_MS: 500, FRAME_STRIDE: 3 },
|
|
210
|
+
// canvasLimits: { MAX_DIMENSION: 900 },
|
|
371
211
|
// ...
|
|
372
212
|
// }
|
|
373
213
|
```
|
|
374
214
|
|
|
375
|
-
|
|
215
|
+
---
|
|
376
216
|
|
|
377
|
-
|
|
217
|
+
## Available Helpers
|
|
378
218
|
|
|
379
|
-
|
|
380
|
-
import { getPrimitiveTypes } from '@nexart/ui-renderer';
|
|
219
|
+
The preview runtime includes all standard p5-like functions plus:
|
|
381
220
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
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 |
|
|
385
231
|
|
|
386
|
-
###
|
|
232
|
+
### Control Functions
|
|
387
233
|
|
|
388
|
-
|
|
234
|
+
| Function | Preview Behavior |
|
|
235
|
+
|----------|------------------|
|
|
236
|
+
| `noLoop()` | Stops preview loop (soft control) |
|
|
237
|
+
| `loop()` | No-op in preview |
|
|
389
238
|
|
|
390
|
-
|
|
391
|
-
import { getPrimitivesByCategory } from '@nexart/ui-renderer';
|
|
239
|
+
---
|
|
392
240
|
|
|
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
|
-
```
|
|
241
|
+
## Supported Element Types
|
|
403
242
|
|
|
404
|
-
### `
|
|
243
|
+
### `background`
|
|
405
244
|
|
|
406
|
-
|
|
245
|
+
Opinionated presets with guardrails.
|
|
407
246
|
|
|
408
247
|
```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
|
-
// }
|
|
248
|
+
{
|
|
249
|
+
type: 'background',
|
|
250
|
+
style: 'gradient', // gradient, solid, noise, grain
|
|
251
|
+
palette: 'warm' // warm, cool, neutral, vibrant
|
|
252
|
+
}
|
|
420
253
|
```
|
|
421
254
|
|
|
422
|
-
### `
|
|
255
|
+
### `primitive`
|
|
423
256
|
|
|
424
|
-
|
|
257
|
+
Declarative generative components. **30 primitives available:**
|
|
425
258
|
|
|
426
|
-
|
|
427
|
-
|
|
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
|
|
428
266
|
|
|
429
|
-
|
|
430
|
-
|
|
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
|
+
}
|
|
431
277
|
```
|
|
432
278
|
|
|
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.
|
|
279
|
+
### `sketch`
|
|
441
280
|
|
|
442
|
-
|
|
281
|
+
Raw Code Mode execution.
|
|
443
282
|
|
|
444
283
|
```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
|
|
284
|
+
{
|
|
285
|
+
type: 'sketch',
|
|
286
|
+
code: `
|
|
287
|
+
function setup() { background(0); }
|
|
288
|
+
function draw() { ellipse(width/2, height/2, 100); }
|
|
289
|
+
`,
|
|
290
|
+
normalize: true
|
|
460
291
|
}
|
|
461
292
|
```
|
|
462
293
|
|
|
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
294
|
---
|
|
487
295
|
|
|
488
|
-
##
|
|
296
|
+
## VAR Handling (Soft)
|
|
489
297
|
|
|
490
|
-
|
|
298
|
+
VAR[0..9] is an array of 10 protocol variables.
|
|
491
299
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
---
|
|
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
|
|
499
306
|
|
|
500
|
-
|
|
307
|
+
```typescript
|
|
308
|
+
// Works in preview (clamped to 100)
|
|
309
|
+
vars: [150, 50, 50] // VAR[0] becomes 100
|
|
501
310
|
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
- Black canvas is displayed
|
|
505
|
-
- Error is logged verbatim
|
|
506
|
-
- No "best effort" recovery
|
|
311
|
+
// Works in preview (non-numbers become 0)
|
|
312
|
+
vars: ['bad', 50, 50] // VAR[0] becomes 0
|
|
507
313
|
|
|
314
|
+
// Works in preview (extras ignored)
|
|
315
|
+
vars: [1,2,3,4,5,6,7,8,9,10,11,12] // Uses first 10
|
|
508
316
|
```
|
|
509
|
-
|
|
510
|
-
|
|
317
|
+
|
|
318
|
+
For strict validation, use `@nexart/codemode-sdk`.
|
|
511
319
|
|
|
512
320
|
---
|
|
513
321
|
|
|
514
|
-
## What This SDK Does NOT
|
|
322
|
+
## What This SDK Does NOT Do
|
|
515
323
|
|
|
516
|
-
| Not
|
|
517
|
-
|
|
518
|
-
|
|
|
519
|
-
|
|
|
520
|
-
|
|
|
521
|
-
|
|
|
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 |
|
|
522
331
|
|
|
523
332
|
---
|
|
524
333
|
|
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"}
|
package/dist/capabilities.js
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
|
const SHARED_PARAMS = {
|
|
14
12
|
count: {
|
|
@@ -60,7 +58,7 @@ function createPrimitive(name, category, description) {
|
|
|
60
58
|
}
|
|
61
59
|
export function getCapabilities() {
|
|
62
60
|
return {
|
|
63
|
-
version: '0.
|
|
61
|
+
version: '0.8.0',
|
|
64
62
|
isCanonical: false,
|
|
65
63
|
isArchival: false,
|
|
66
64
|
renderer: '@nexart/ui-renderer',
|