# CodeMode SDK — Deterministic Rendering

URL: https://docs.nexart.io/docs/codemode-sdk

The @nexart/codemode-sdk for deterministic code execution, covering setup, deterministic tool calls, snapshot capture, and how results become Certified.

## Overview

`@nexart/codemode-sdk` is the deterministic generative execution runtime inside NexArt. It executes code under canonical rules so that identical inputs always produce identical pixel output. Any verifier with the same code, seed, and parameters can re-render and confirm the result.

- Generative art and visual simulations
- Reproducible creative pipelines
- Snapshot-based verification of rendered artifacts

## Install

Install

```
npm install @nexart/codemode-sdk
```

Current version: `@nexart/codemode-sdk@1.12.0`.

## Execution model

The runtime enforces strict canonical rules. These MUST be honored for output to be reproducible:

- Canvas is fixed at 1950 x 2400.
- `createCanvas()` MUST NOT be called.
- `setup()` is the entry point. Animation loops are not part of the canonical mode.
- Use the runtime's seeded `random()`. Do NOT use `Math.random`, wall-clock time, or network I/O.

## Quickstart

One-shot deterministic render

```
import { executeCodeMode } from "@nexart/codemode-sdk";

const code = `
function setup() {
  background(50);
  circle(975, 1200, 300 + random(0, 200));
}
`;

const { png, snapshot } = await executeCodeMode(code, {
  seed: 12345,
  vars: [50, 50, 50, 0, 0, 0, 0, 0, 0, 0],
});

// 'png' is the rendered image (Uint8Array / Buffer).
// 'snapshot' contains { sdkVersion, seed, vars, code, canvas, outputHash }.
```

## Exported functions

| Symbol | Description |
| --- | --- |
| executeCodeMode(code, options) | High-level one-shot render. Returns { png, snapshot }. |
| createP5Runtime(options) | p5-flavored deterministic runtime. Use when you need to retain a runtime handle across renders. |
| createRuntime(options) | Framework-neutral deterministic runtime. |
| runStaticMode(code, options) | Static (setup-only) render. No loop. |
| runLoopMode(code, options) | Bounded-loop render with deterministic frame budget. |
| renderSoundArtViaCodeMode(spec, options) | SoundArt helper: deterministic audio-driven visual render. |
| renderNoiseViaCodeMode(spec, options) | Noise/texture helper. |
| verifyCodeModeSnapshotDetailed(snap) | Independent verifier. Re-runs the snapshot and recomputes outputHash. |
| SDK_VERSION | Package version string constant ('1.10.2'). |

## Snapshot shape

Every render returns a snapshot, the canonical, portable record of a deterministic render. It is the input to the verifier.

CodeMode snapshot

```
{
  "sdkVersion": "1.10.2",
  "seed": 12345,
  "vars": [50, 50, 50, 0, 0, 0, 0, 0, 0, 0],
  "code": { "hash": "sha256:..." },
  "canvas": { "width": 1950, "height": 2400 },
  "outputHash": "sha256:..."
}
```

## Verification

A snapshot is independently verifiable. Given the same code, seed, and vars,`verifyCodeModeSnapshotDetailed` re-runs the render and recomputes the `outputHash`. If it matches the stored hash, the render is reproducible.

Verify a snapshot

```
import { verifyCodeModeSnapshotDetailed } from "@nexart/codemode-sdk";

const report = await verifyCodeModeSnapshotDetailed(snapshot);
// report.ok           -> boolean
// report.checks       -> per-check PASS / FAIL details
// report.outputHash   -> recomputed hash
```

## Binding to a CER

CodeMode snapshots can be embedded in a Certified Execution Record so the rendered artifact participates in the same attestation and verification surface as any other AI execution. See the AI Execution SDK for `certifyDecision` / `certifyAndAttestDecision`.

## Related

- UI Renderer SDK — deterministic UI rendering
- NexArt CLI — `run` and `verify` commands for snapshots
- AI Execution SDK — wrap a snapshot in a CER