@nexart/codemode-sdk 1.5.0 → 1.6.0

package/README.md

@@ -1,16 +1,15 @@
 # NexArt Code Mode Runtime SDK
 
-**Version: 1.5.0 (Protocol v1.2.0)**
+**Version: 1.6.0 (Protocol v1.2.0)**
 
 ╔══════════════════════════════════════════════════════════════════════════════╗
-║  @nexart/codemode-sdk — Canonical Code Mode Authority                        ║
+║  @nexart/codemode-sdk — Canonical Execution Surface                          ║
 ║                                                                              ║
-║  This SDK defines the official Code Mode execution surface.                  ║
-║  All implementations (NexArt, ByX, external) MUST use this SDK.              ║
+║  This SDK IS the protocol. All implementations MUST use this SDK.            ║
 ║                                                                              ║
 ║  Protocol: nexart                                                            ║
 ║  Engine: codemode                                                            ║
-║  SDK Version: 1.5.0                                                          ║
+║  SDK Version: 1.6.0                                                          ║
 ║  Protocol Version: 1.2.0                                                     ║
 ║  Phase: 3                                                                    ║
 ║  Enforcement: HARD                                                           ║
@@ -18,6 +17,15 @@
 
 ---
 
+## Commercial Licensing
+
+> **Commercial usage of NexArt Protocol requires a license.**
+> **Enforcement is not active yet.**
+
+The SDK is currently provided under the MIT License for all usage. A future version may introduce commercial licensing requirements. See [LICENSE.md](./LICENSE.md) for details.
+
+---
+
 ## PROTOCOL LOCK — v1.x
 
 | Property | Value |
@@ -54,15 +62,86 @@ The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
 
 ---
 
-## What's New in v1.5.0
+## What's New in v1.6.0
+
+**Licensing & Builder Identity Scaffolding (Metadata Only)**
+
+This is a non-breaking, metadata-only release. No changes to execution or determinism.
+
+### Licensing (Informational Only)
+- Added `LICENSE.md` with draft commercial licensing terms
+- Enforcement is NOT active — all usage currently permitted under MIT
+
+### Builder Manifest Schema
+- Added `builder.manifest.schema.json` for optional builder attribution
+- Fields: `builder_id`, `project_name`, `contact`, `website`, `intended_use`
+- This file is **optional**, **not validated**, and **not loaded at runtime**
+
+### Documentation
+- SDK positioned as "canonical execution surface"
+- Explicit determinism guarantees documented
+- Real product references (ByX, Frontierra)
+
+---
+
+## Determinism Guarantees
+
+**The NexArt Code Mode SDK guarantees deterministic output.**
+
+Given identical inputs:
+- Same `source` code
+- Same `seed`
+- Same `vars` array
+- Same `width` and `height`
+- Same `mode`
+
+The SDK will produce **byte-for-byte identical output** across all executions.
+
+### What Breaks Determinism
+
+The following actions will break determinism and are **blocked** by the SDK:
+
+| Pattern | Reason | Enforcement |
+|---------|--------|-------------|
+| `Math.random()` | Unseeded randomness | BLOCKED |
+| `Date.now()` | Time-based entropy | BLOCKED |
+| `new Date()` | Time-based entropy | BLOCKED |
+| `performance.now()` | Timing entropy | BLOCKED |
+| `crypto.getRandomValues()` | Crypto randomness | BLOCKED |
+| `fetch()` | External IO | BLOCKED |
+| External imports | Uncontrolled code | BLOCKED |
+
+Use `random()` (seeded) and `noise()` (seeded) for all randomness needs.
+
+### Oracle Verification
+
+Before any release, run the determinism check:
+
+```bash
+npx tsx scripts/check-determinism.ts
+```
+
+This compares output against a known oracle hash. If the hash changes without a protocol version bump, the release is invalid.
+
+---
+
+## Products Using This SDK
+
+- **NexArt**: Primary generative art platform
+- **ByX**: Curated collection system
+- **Frontierra**: External builder integration
+
+---
+
+## v1.5.1
+
+**Builder Manifest — Passive Attribution (Write-Only)**
 
-**Critical Fix — NPM Package Sync**
+- `registerBuilderManifest(manifest?)` — Declare builder identity for future attribution
 
-- **Restored seeded Mulberry32 PRNG** for `random()`, `randomSeed()`, `randomGaussian()`
-- **Restored seeded Perlin noise** for `noise()`, `noiseSeed()`
-- Full sync between SDK source and npm package
+The Builder Manifest is a declaration of intent, not a capability. Write-only, optional, non-enforced.
 
-The v1.4.0 npm package had an outdated runtime that used `Math.random()` directly. This release restores determinism.
+---
 
 ## v1.4.0 (Protocol v1.2.0)
 
@@ -129,7 +208,8 @@ The SDK enforces the **NexArt Code Mode Protocol v1.2.0** for reproducible, mint
 ## Installation
 
 ```bash
-npm install @nexart/codemode-sdk
+# Copy the sdk/codemode folder to your project
+cp -r sdk/codemode your-project/lib/codemode
 ```
 
 ---
@@ -191,8 +271,8 @@ interface ExecuteCodeModeResult {
   metadata: {
     protocol: 'nexart';
     engine: 'codemode';
-    protocolVersion: '1.2.0';
-    phase: 3;
+    protocolVersion: '1.0.0';
+    phase: 1;
     deterministic: true;
     seed: number;
     vars: number[];
@@ -206,11 +286,67 @@ interface ExecuteCodeModeResult {
 
 ---
 
-## Protocol Variables (VAR[0..9]) — Protocol v1.0.0
+## Legacy API
+
+> ⚠️ **Note**: The `createEngine()` API is still supported but new implementations should use `executeCodeMode()`.
+
+### `createEngine(config: EngineConfig): Engine`
+
+Create a rendering engine instance.
+
+```typescript
+import { createEngine } from './codemode';
+
+const engine = createEngine({
+  mode: 'static',      // 'static' | 'loop'
+  width: 1950,         // Optional, default: 1950
+  height: 2400,        // Optional, default: 2400
+  duration: 2,         // Loop mode only, 1-4 seconds
+  fps: 30,             // Loop mode only, default: 30
+});
+```
+
+### `engine.run(options: RunOptions): Promise<void>`
+
+Execute code and produce output.
+
+```typescript
+await engine.run({
+  code: `
+    function setup() {
+      background(255);
+      fill(0);
+      // Use VAR for external control
+      let size = map(VAR[0], 0, 100, 50, 200);
+      ellipse(width/2, height/2, size);
+    }
+  `,
+  seed: 12345,              // Optional: seed for deterministic randomness
+  vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],  // Optional: VAR[0..9] values (0-100)
+  onPreview: (canvas) => {
+    // Optional: called with canvas after first frame
+  },
+  onProgress: (info) => {
+    // Optional: progress updates
+    console.log(info.message, info.percent + '%');
+  },
+  onComplete: (result) => {
+    // Required: called with final result
+    console.log(result.type); // 'image' | 'video'
+    console.log(result.blob); // Blob
+  },
+  onError: (error) => {
+    // Optional: called on error
+    console.error(error);
+  },
+});
+```
+
+### Protocol Variables (VAR[0..9]) — Protocol v1.0.0
 
 Protocol variables are first-class inputs that control artwork parameters.
 
-**VAR Specification:**
+**VAR Specification (SDK v1.0.2):**
 
 | Property | Value | Enforcement |
 |----------|-------|-------------|
@@ -224,7 +360,20 @@ Protocol variables are first-class inputs that control artwork parameters.
 | Default | All zeros | If not provided |
 
 ```typescript
-// Access in sketch code (missing indices return 0)
+// Pass values when running (0-10 elements)
+await engine.run({
+  code: myCode,
+  vars: [80, 50, 25],  // VAR[0]=80, VAR[1]=50, VAR[2]=25, VAR[3..9]=0
+  onComplete: (result) => { /* ... */ },
+});
+
+// Or omit entirely (all zeros)
+await engine.run({
+  code: myCode,
+  onComplete: (result) => { /* ... */ },
+});
+
+// Access in sketch code
 function setup() {
   let density = map(VAR[0], 0, 100, 10, 200);
   let speed = map(VAR[1], 0, 100, 0.5, 5);
@@ -240,6 +389,14 @@ function setup() {
 - Values MUST be in range 0-100 (throws if out of range)
 - Same code + same seed + same VARs = identical output
 
+### `engine.stop(): void`
+
+Cancel a running render (Loop mode only).
+
+### `engine.getConfig(): EngineConfig`
+
+Get the resolved engine configuration.
+
 ---
 
 ## Execution Rules
@@ -267,7 +424,6 @@ function setup() {
 | `t` | float | Normalized time [0.0, 1.0) |
 | `time` | float | Elapsed seconds |
 | `tGlobal` | float | Alias for `t` |
-| `totalFrames` | int | Total frames in loop (v1.4.0+) |
 
 ---
 
@@ -296,6 +452,76 @@ Additionally in Loop Mode:
 
 ---
 
+## Example: Static Mode
+
+```typescript
+import { createEngine } from './codemode';
+
+const engine = createEngine({ mode: 'static' });
+
+await engine.run({
+  code: `
+    function setup() {
+      background(30);
+      noStroke();
+      for (let i = 0; i < 100; i++) {
+        fill(random(255), random(255), random(255));
+        ellipse(random(width), random(height), 50);
+      }
+    }
+  `,
+  onComplete: (result) => {
+    // result.type === 'image'
+    // result.blob is a PNG Blob
+    const url = URL.createObjectURL(result.blob);
+    document.body.innerHTML = `<img src="${url}" />`;
+  },
+});
+```
+
+---
+
+## Example: Loop Mode
+
+```typescript
+import { createEngine } from './codemode';
+
+const engine = createEngine({
+  mode: 'loop',
+  duration: 2,  // 2 second loop
+});
+
+await engine.run({
+  code: `
+    function setup() {
+      // Called once
+    }
+    
+    function draw() {
+      background(30);
+      
+      // t goes from 0 to 1 over the loop duration
+      let x = width/2 + cos(t * TWO_PI) * 200;
+      let y = height/2 + sin(t * TWO_PI) * 200;
+      
+      fill(255);
+      ellipse(x, y, 80);
+    }
+  `,
+  onProgress: (info) => {
+    console.log(info.message);
+  },
+  onComplete: (result) => {
+    // result.type === 'video'
+    // result.blob is an MP4 Blob
+    const url = URL.createObjectURL(result.blob);
+    document.body.innerHTML = `<video src="${url}" autoplay loop />`;
+  },
+});
+```
+
+---
+
 ## Supported Functions
 
 The SDK includes a comprehensive p5.js-like runtime with 130+ functions:
@@ -360,21 +586,41 @@ All of the following are accepted by `fill()`, `stroke()`, `background()`:
 
 ---
 
-## Frozen Execution Guarantees — v1.0.0
+## Video Encoding
 
-The following guarantees are LOCKED and will not change in v1.x:
+Loop Mode requires server-side video encoding. The SDK calls:
 
-| Guarantee | Description |
-|-----------|-------------|
-| Determinism | Same code + same seed + same VARs = identical output |
-| Static Mode | `setup()` only, single PNG output |
-| Loop Mode | Frame-authoritative, `draw()` per frame, MP4 output |
-| Time Semantics | `t` ∈ [0,1), `frameCount` ∈ [0,totalFrames), `time` in seconds |
-| Random | Seeded Mulberry32 PRNG via `random()` |
-| Noise | Seeded Perlin noise via `noise()` |
-| Canvas | Pre-initialized, no `createCanvas()` |
-| VAR | Exactly 10 read-only protocol variables |
-| Forbidden Patterns | 13 patterns rejected (see above) |
+```
+POST /api/encode-loop
+```
+
+Ensure your server has this endpoint available (NexArt provides this).
+
+---
+
+## Files
+
+```
+sdk/codemode/
+├── index.ts          # Main export
+├── execute.ts        # executeCodeMode canonical entry point
+├── engine.ts         # createEngine entry point (legacy)
+├── types.ts          # TypeScript types
+├── static-engine.ts  # Static mode implementation
+├── loop-engine.ts    # Loop mode implementation
+├── p5-runtime.ts     # p5.js-like runtime
+├── builder-manifest.ts # Builder manifest (write-only)
+├── CHANGELOG.md      # Version history
+└── README.md         # This file
+```
+
+---
+
+## License
+
+MIT License
+
+Copyright (c) 2024-2026 NexArt
 
 ---
 
@@ -397,7 +643,7 @@ const result = await executeCodeMode({
   width: 1950,
   height: 2400,
   seed: 12345,
-  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],
+  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],  // Exactly 10 values
   mode: 'static'
 });
 
@@ -423,35 +669,27 @@ try {
 
 ---
 
-## Video Encoding
-
-Loop Mode requires server-side video encoding. The SDK calls:
-
-```
-POST /api/encode-loop
-```
-
-Ensure your server has this endpoint available (NexArt provides this).
-
----
+## Frozen Execution Guarantees — v1.0.0
 
-## Files
+The following guarantees are LOCKED and will not change in v1.x:
 
-```
-@nexart/codemode-sdk/
-├── index.ts         # Main export
-├── engine.ts        # createEngine entry point
-├── types.ts         # TypeScript types
-├── static-engine.ts # Static mode implementation
-├── loop-engine.ts   # Loop mode implementation
-├── p5-runtime.ts    # p5.js-like runtime
-└── README.md        # This file
-```
+| Guarantee | Description |
+|-----------|-------------|
+| Determinism | Same code + same seed + same VARs = identical output |
+| Static Mode | `setup()` only, single PNG output |
+| Loop Mode | Frame-authoritative, `draw()` per frame, MP4 output |
+| Time Semantics | `t` ∈ [0,1), `frameCount` ∈ [0,totalFrames), `time` in seconds |
+| Random | Seeded Mulberry32 PRNG via `random()` |
+| Noise | Seeded Perlin noise via `noise()` |
+| Canvas | Pre-initialized, no `createCanvas()` |
+| VAR | Exactly 10 read-only protocol variables |
+| Forbidden Patterns | 13 patterns rejected (see above) |
 
 ---
 
-## License
-
-MIT License
+## Future Work (Phase 4+)
 
-Copyright (c) 2024-2026 NexArt
+- External asset loading (controlled)
+- WebGL/3D rendering support
+- GIF output option
+- GSL v1 SDK (protocol layer) — separate package

package/builder.manifest.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://nexart.art/schemas/builder.manifest.json",
+  "title": "NexArt Builder Manifest",
+  "description": "Optional metadata file for builder attribution. NOT validated, NOT required, NOT enforced.",
+  "type": "object",
+  "properties": {
+    "protocol": {
+      "type": "string",
+      "const": "nexart",
+      "description": "Protocol identifier (must be 'nexart')"
+    },
+    "manifest_version": {
+      "type": "string",
+      "description": "Version of this manifest schema",
+      "default": "1.0"
+    },
+    "builder_id": {
+      "type": "string",
+      "description": "Unique identifier for the builder (self-assigned)"
+    },
+    "project_name": {
+      "type": "string",
+      "description": "Name of the project or application"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of the project"
+    },
+    "contact": {
+      "type": "string",
+      "description": "Contact email or handle"
+    },
+    "website": {
+      "type": "string",
+      "format": "uri",
+      "description": "Project website URL"
+    },
+    "intended_use": {
+      "type": "string",
+      "enum": ["art", "game", "research", "commercial", "education", "other"],
+      "description": "Primary intended use case"
+    },
+    "sdk_version": {
+      "type": "string",
+      "description": "Version of @nexart/codemode-sdk being used"
+    },
+    "features": {
+      "type": "object",
+      "description": "Optional feature flags",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Arbitrary additional metadata",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/dist/builder-manifest.d.ts

@@ -0,0 +1,79 @@
+/**
+ * NexArt Code Mode SDK - Builder Manifest
+ * Version: 1.6.0 (Protocol v1.2.0)
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  BUILDER MANIFEST — PASSIVE ATTRIBUTION (WRITE-ONLY)                     ║
+ * ║                                                                          ║
+ * ║  The Builder Manifest is a declaration of intent, not a capability.      ║
+ * ║  The SDK does not expose any API to read or inspect manifests.           ║
+ * ║                                                                          ║
+ * ║  This is:                                                                ║
+ * ║    - Declarative (write-only, no read API exposed)                       ║
+ * ║    - Optional (no errors if missing or invalid)                          ║
+ * ║    - Non-enforced (no validation logic)                                  ║
+ * ║    - Non-rewarding (no incentives, no tracking)                          ║
+ * ║                                                                          ║
+ * ║  There is:                                                               ║
+ * ║    - No SDK API to read manifests                                        ║
+ * ║    - No validation                                                       ║
+ * ║    - No attribution logic                                                ║
+ * ║    - No tracking, analytics, or network calls                            ║
+ * ║                                                                          ║
+ * ║  Execution behavior is identical with or without a manifest.             ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import type { NexArtBuilderManifest } from './types';
+/**
+ * Register a builder manifest for attribution.
+ *
+ * This is optional and does not affect execution behavior.
+ * The manifest is stored in-memory only and is not:
+ * - Serialized to disk
+ * - Sent over the network
+ * - Logged to console
+ * - Used for validation or enforcement
+ *
+ * @param manifest - Optional builder manifest. Pass undefined to clear.
+ *
+ * @example
+ * ```typescript
+ * import { registerBuilderManifest } from "@nexart/codemode-sdk";
+ *
+ * registerBuilderManifest({
+ *   protocol: "nexart",
+ *   manifestVersion: "0.1",
+ *   app: { name: "My App", url: "https://myapp.com" }
+ * });
+ * ```
+ */
+export declare function registerBuilderManifest(manifest?: NexArtBuilderManifest): void;
+/**
+ * Get the currently registered builder manifest.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  INTERNAL FUNCTION — NOT EXPORTED TO SDK CONSUMERS                       ║
+ * ║                                                                          ║
+ * ║  This function exists only for internal SDK execution context.           ║
+ * ║  It is NOT part of the public API and must NOT be exported from index.   ║
+ * ║  Runtime code and sketch code cannot access this function.               ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ *
+ * @internal
+ */
+export declare function getBuilderManifest(): NexArtBuilderManifest | null;
+/**
+ * Clear the registered builder manifest.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  INTERNAL FUNCTION — NOT EXPORTED TO SDK CONSUMERS                       ║
+ * ║                                                                          ║
+ * ║  This function exists only for internal SDK execution context.           ║
+ * ║  It is NOT part of the public API and must NOT be exported from index.   ║
+ * ║  Runtime code and sketch code cannot access this function.               ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ *
+ * @internal
+ */
+export declare function clearBuilderManifest(): void;
+//# sourceMappingURL=builder-manifest.d.ts.map

package/dist/builder-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-manifest.d.ts","sourceRoot":"","sources":["../builder-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAiB9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,qBAAqB,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}