@nexart/ui-renderer 0.8.8 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,458 @@
+# Changelog
+
+All notable changes to @nexart/ui-renderer will be documented in this file.
+
+---
+
+## [0.9.0] — 2026-01-24
+
+### Added
+
+- **Budget exceed callbacks**: `onBudgetExceeded` callback fires when frame or time limits are reached
+- **Budget overlay**: Optional overlay displayed when preview stops due to budget (default: true for 'stop' behavior)
+- **Budget behavior options**: `budgetBehavior: 'stop' | 'degrade'` — stop with overlay or continue with frame skipping
+- **getPreviewStats()**: Full observability into runtime state (mode, scale, frames, stride, time, budgetExceeded)
+- **previewScale**: Public readonly property exposing current canvas scale factor
+- **createPreviewRuntime()**: New recommended entrypoint (alias for createPreviewEngine)
+- **toCanonicalRequest()**: Helper for handoff to @nexart/codemode-sdk
+
+### Changed
+
+- **No more silent stops**: Budget exceeded now triggers callbacks + console warning instead of silent termination
+- **Default budget limits**: MAX_FRAMES: 1800 (~30 min at ~60 FPS), MAX_TOTAL_TIME_MS: 300000 (5 min)
+- **Animation remains smooth**: Native RAF cadence (~60 FPS) preserved from v0.8.8 — no FPS throttle
+- **README rewritten**: Agent-first documentation with 20-second quickstart, troubleshooting section
+- **Version synced**: package.json, index.ts, README.md all show 0.9.0
+
+### Added Types
+
+- `PreviewStats` — Runtime stats object
+- `BudgetExceededInfo` — Callback info ({ reason, framesRendered, totalTimeMs, stride, scale })
+- `BudgetExceedReason` — 'frame_limit' | 'time_limit'
+- `BudgetBehavior` — 'stop' | 'degrade'
+- `CanonicalRequest` — Handoff object for codemode-sdk
+
+### Examples
+
+- `examples/basic-preview.ts` — Basic usage with stats logging
+- `examples/budget-demo.ts` — Budget handling demonstration
+
+### Migration
+
+No breaking changes. All v0.8.x exports are preserved.
+
+New recommended pattern:
+```typescript
+// Old (still works)
+import { createPreviewEngine } from '@nexart/ui-renderer';
+
+// New (recommended)
+import { createPreviewRuntime } from '@nexart/ui-renderer';
+```
+
+---
+
+## [0.8.8] — 2026-01-04
+
+### Changed
+
+- **REMOVED FPS THROTTLE**: Animation now renders at native browser refresh rate (~60 FPS)
+- Matches smooth rendering experience of main NexArt app
+- No more 8 FPS stuttering for loop animations
+
+### Why
+
+The 8 FPS throttle (added in v0.8.6) caused poor UX with stuttery animations, while the main NexArt app renders smoothly using native `requestAnimationFrame`. Since the UI renderer's only job is to display sketches on canvas, it should render at the browser's natural frame rate.
+
+### Breaking Changes
+
+None. API remains identical.
+
+### Technical Details
+
+Removed:
+- `shouldRenderFrame(throttle)` check in animation loop
+- `recordFrame(throttle)` call after draw
+- FPS throttle imports and initialization
+
+Now uses native `requestAnimationFrame` without artificial frame rate limiting.
+
+---
+
+## [0.8.7] — 2026-01-03
+
+### Fixed
+
+- **CRITICAL**: Time-varying properties (`frameCount`, `t`, `time`, `tGlobal`, `totalFrames`) were frozen in loop mode
+- Animations now render correctly with live values updating every frame
+
+### Root Cause
+
+The previous implementation used `new Function(...Object.keys(runtime), source)(...Object.values(runtime))`,
+which captured primitive values BY VALUE at compile time. Updates to `runtime.frameCount` in the 
+animation loop were invisible to the sketch because it held frozen copies.
+
+### Solution
+
+Replaced the parameter-spreading approach with a Proxy + `with()` pattern:
+1. Static properties (functions, constants) are cached once
+2. Time-varying properties read from the live runtime object via Proxy get trap
+3. `with(__scope)` enables bare-name access without changing sketch syntax
+4. `has()` trap returns true ONLY for known keys, allowing globals (Math, window) to fall through
+
+**Animation Semantics:**
+```javascript
+function draw() {
+  // These values update every frame:
+  // - frameCount: 1, 2, 3, ...
+  // - t: (frameCount % totalFrames) / totalFrames
+  // - time, tGlobal: aliases for t
+  circle(width/2 + sin(frameCount * 0.1) * 300, height/2, 120);
+}
+```
+
+---
+
+## [0.8.6] — 2026-01-03 (SUPERSEDED)
+
+### Note: FPS throttle worked but time variables were still frozen. See v0.8.7.
+
+---
+
+## [0.8.5] — 2026-01-03 (SUPERSEDED)
+
+### Note: Budget approach was still problematic.
+
+---
+
+## [0.8.4] — 2026-01-03 (SUPERSEDED)
+
+### Note: This version had incorrect reset semantics.
+
+---
+
+## [0.8.3] — 2026-01-03
+
+### Fixed
+
+- Fixed critical bug where preview only rendered a single frame
+- Animation loop now runs continuously with invisible performance throttling
+- Budget exhaustion no longer terminates the render loop
+
+### Details
+
+The render loop conditionally scheduled `requestAnimationFrame`, causing the animation
+to terminate after the first frame or after budget reset.
+
+**Before (broken):**
+```typescript
+const loop = () => {
+  if (!canRenderFrame(budget)) {
+    isRunning = false;
+    return;  // Loop terminates — RAF never scheduled
+  }
+  draw();
+  animationId = requestAnimationFrame(loop);  // Conditional — WRONG!
+};
+```
+
+**After (fixed):**
+```typescript
+const loop = () => {
+  animationId = requestAnimationFrame(loop);  // ALWAYS scheduled first
+
+  if (!canRenderFrame(budget)) {
+    return;  // Skip draw, but loop continues
+  }
+  draw();
+};
+```
+
+**Animation Loop Invariant (locked for v0.x):**
+- `requestAnimationFrame(loop)` MUST be called on every tick
+- Budget gates ONLY whether `draw()` executes, NOT whether loop runs
+- Never return before scheduling RAF. Never conditionally schedule.
+
+---
+
+## [0.8.2] — 2026-01-03
+
+### Fixed
+
+- Fixed critical bug where preview scaling affected `width`/`height` inside sketches
+- Runtime now uses original (protocol) dimensions for width/height semantics
+- Loop animations and geometry math now work correctly
+
+### Details
+
+The v0.8.0–v0.8.1 releases passed scaled dimensions to the preview runtime, which broke
+sketch semantics. When a 1950×2400 canvas was downscaled to 900px for performance:
+
+**Before (broken):**
+```typescript
+// width = 675, height = 900 (scaled — WRONG!)
+createPreviewRuntime(canvas, scaled.renderWidth, scaled.renderHeight, seed);
+```
+
+**After (fixed):**
+```typescript
+// width = 1950, height = 2400 (original — CORRECT!)
+createPreviewRuntime(canvas, scaled.originalWidth, scaled.originalHeight, seed);
+```
+
+**Key rule enforced:** Preview scaling is a rendering concern, not a semantic one.
+Canvas buffer may be downscaled for performance, but `width`/`height` must always
+match Code Mode to ensure loop animations and geometry math work correctly.
+
+---
+
+## [0.8.1] — 2026-01-03
+
+### Fixed
+
+- Fixed canvas zoom/cropping caused by resolution downscaling
+- Reapplied context scale after canvas resize
+- Ensured clearRect ignores active transforms
+
+### Details
+
+Canvas resizing resets the 2D context transform. The v0.8.0 resolution downscaling feature 
+introduced a visual bug where previews appeared zoomed or cropped. This patch ensures:
+
+1. **Scale Transform Reapplied**: After `applyScaledDimensions()`, the context scale is 
+   immediately restored via new `reapplyContextScale()` function.
+
+2. **Transform-Safe Clear**: `clearRect()` now uses `clearCanvasIgnoringTransform()` which 
+   saves/restores the context to clear the full canvas regardless of active transforms.
+
+3. **No API Changes**: All fixes are internal — no changes to the public API.
+
+---
+
+## [0.8.0] — 2026-01-03
+
+### Lightweight Preview Runtime — Major Refactor
+
+This release refactors the UI renderer into a lightweight, performance-optimized preview runtime.
+
+#### Philosophy Change
+
+**The UI renderer is now explicitly preview-only:**
+- NOT canonical — does not guarantee determinism
+- NOT archival — not for minting or export
+- NOT validation — does not enforce protocol compliance
+
+For canonical output, minting, or validation: use `@nexart/codemode-sdk`.
+
+#### New: Execution Budget (MANDATORY)
+
+The preview runtime enforces hard limits to prevent browser freezes:
+
+```typescript
+PREVIEW_BUDGET = {
+  MAX_FRAMES: 30,           // Maximum frames before auto-stop
+  MAX_TOTAL_TIME_MS: 500,   // Maximum execution time
+  TARGET_FRAME_TIME_MS: 16, // ~60fps target
+  FRAME_STRIDE: 3,          // Render every 3rd frame
+};
+```
+
+If limits exceeded: rendering stops silently (no throw).
+
+#### New: Canvas Scaling
+
+Preview renderer no longer renders at full mint resolution:
+
+```typescript
+CANVAS_LIMITS = {
+  MAX_DIMENSION: 900,  // Max width/height
+  MIN_DIMENSION: 100,
+};
+```
+
+Aspect ratio preserved, CSS scaling for display.
+
+#### New: Preview Engine API
+
+```typescript
+import { 
+  createPreviewEngine,
+  renderStaticPreview,
+  stopActivePreview,
+  PREVIEW_BUDGET,
+  CANVAS_LIMITS,
+} from '@nexart/ui-renderer';
+
+// Create preview renderer
+const engine = createPreviewEngine({
+  canvas: canvasElement,
+  source: sketchCode,
+  mode: 'loop',
+  width: 1950,  // Will be scaled to 900px
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 25],
+});
+
+// Start/stop
+engine.startLoop();
+engine.stopLoop();
+engine.destroy();
+```
+
+#### Changed
+
+- `renderCodeModeSystem()` now uses preview runtime with budget limits
+- `renderUnifiedSystem()` updated to use new preview runtime
+- Pattern warnings logged to console instead of throwing
+- All renderers now include scaling and budget enforcement
+
+#### Added Files
+
+- `src/preview/preview-types.ts` — Type definitions and constants
+- `src/preview/frame-budget.ts` — Execution budget manager
+- `src/preview/canvas-scaler.ts` — Resolution scaling utilities
+- `src/preview/preview-engine.ts` — Lightweight preview executor
+- `src/preview/preview-runtime.ts` — Simplified p5-like runtime
+
+---
+
+## [0.7.0] — 2026-01-02
+
+### Protocol v1.2.0 Mirror Update
+
+This release updates to mirror @nexart/codemode-sdk v1.4.0 (Protocol v1.2.0, Phase 3).
+
+#### New Features Mirrored
+- **Vertex Functions**: `curveVertex(x, y)`, `bezierVertex(cx1, cy1, cx2, cy2, x, y)`
+- **Pixel System**: `loadPixels()`, `updatePixels()`, `pixels[]`, `get(x, y)`, `set(x, y, color)`
+- **Graphics System**: `createGraphics(w, h)`, `image(pg, x, y, w, h)`
+- **Time Variable**: `totalFrames` now available in Loop Mode
+
+#### Changed
+- Updated dependency to @nexart/codemode-sdk ^1.4.0
+- Protocol version updated to v1.2.0 (Phase 3)
+- Documentation updated to reflect new capabilities
+
+---
+
+## [0.6.0] — 2024-12-30
+
+### Minor Bump for npm Publishing
+
+Version bump for npm release. Mirrors @nexart/codemode-sdk v1.1.0.
+
+- Updated all version references from 0.5.0 to 0.6.0
+- Updated codemode-sdk mirror reference from v1.0.2 to v1.1.0
+- No breaking changes from 0.5.0
+
+---
+
+## [0.5.0] — 2024-12-30
+
+### VAR Parity Update (Mirrors @nexart/codemode-sdk v1.0.2)
+
+**VAR input is now optional (0-10 elements):**
+- Omit `vars` or pass `[]` for empty (defaults to all zeros)
+- Input length must be 0-10 (throws if > 10)
+- Values must be finite numbers in [0, 100] (throws if out of range, NO clamping)
+- Runtime VAR is ALWAYS 10 elements (padded with zeros for consistency)
+
+**Breaking Change Notice:**
+- Previously: VAR required exactly 10 elements (error if not 10)
+- Now: VAR accepts 0-10 elements (error if > 10, padded to 10)
+- Existing code passing 10 elements works unchanged (backwards compatible)
+
+**Enforcement Updated:**
+- Out-of-range values now throw errors (previously warned)
+- Non-finite numbers now throw errors
+- Write attempts now throw detailed protocol errors
+
+### 30 Declarative Primitives
+
+Expanded primitive library from 8 to 30 elements:
+
+**Basic Shapes (6):** dots, lines, waves, stripes, circles, grid
+
+**Geometric (5):** polygons, diamonds, hexgrid, stars, concentricSquares
+
+**Radial (7):** spirals, rays, orbits, rings, arcs, radialLines, petals
+
+**Flow & Motion (3):** flow, particles, bubbles
+
+**Patterns (5):** crosshatch, chevrons, zigzag, weave, moire
+
+**Organic (4):** curves, noise, mesh, branches
+
+### AI Capabilities API (Locked)
+
+**Primitives are now marked as NON-CANONICAL helper generators.**
+
+New exports for AI agents:
+- `getCapabilities()` — Full SDK capabilities with primitive metadata
+- `getPrimitiveTypes()` — All 30 primitive names as array
+- `getPrimitivesByCategory()` — Primitives organized by category
+- `getPrimitiveInfo(name)` — Detailed info for single primitive
+- `isPrimitiveValid(name)` — Validate primitive name
+
+Each primitive now includes:
+- `name` — Unique identifier
+- `category` — basic, geometric, radial, flow, patterns, organic
+- `description` — Human-readable description
+- `compilesTo` — Always 'codemode'
+- `isCanonical` — Always false
+- `parameters` — count, color, opacity, strokeWeight, motion with ranges
+
+### Changes
+
+- `normalizeVars()` updated to match codemode-sdk v1.0.2 exactly
+- `createProtectedVAR()` updated to use frozen 10-element array with Proxy
+- `validateCodeSystem()` updated for 0-10 length validation
+- Smoke tests updated for VAR parity verification
+- Added 22 new primitive generators in `primitives.ts`
+- Updated `PrimitiveName` type to include all 30 primitives
+- Rewrote `capabilities.ts` with comprehensive primitive metadata
+- Added `primitivesMeta` to capabilities for AI consumption
+- Exported new helper functions: `getPrimitivesByCategory`, `getPrimitiveInfo`, `isPrimitiveValid`
+- Updated SDK version to 0.5.0
+
+---
+
+## [0.4.0] — 2024-12-29
+
+### Protocol Lock (Mirror)
+
+**This SDK now mirrors NexArt Code Mode Protocol v1.0.0.**
+
+This is a MIRROR SDK, not an authority. All protocol semantics are defined by @nexart/codemode-sdk.
+
+### Aligned with v1.0.0
+
+This SDK mirrors the frozen protocol surface:
+
+- **Execution Model**: Static and Loop modes
+- **VAR[0..9]**: Exactly 10 read-only protocol variables
+- **Error Messages**: Identical format `[Code Mode Protocol Error]`
+- **Forbidden Patterns**: 13 patterns rejected (same as SDK)
+- **Validation**: Same structural checks (length, type, range)
+
+### Changes
+
+- VAR validation now matches SDK exactly (throws for length/type, warns for range)
+- Forbidden pattern errors use SDK format
+- Documentation updated with Protocol Lock section
+- Smoke tests added for cross-SDK verification
+
+### Authority Boundaries
+
+| Aspect | This SDK | @nexart/codemode-sdk |
+|--------|----------|---------------------|
+| Authority | Mirror only | Canonical gate |
+| Determinism | Mirrors behavior | Authoritative |
+| Output | Preview-quality | Archival-quality |
+
+### Notes
+
+- This SDK exists for preview and prototyping
+- Production minting uses @nexart/codemode-sdk
+- Any protocol change requires v2.0.0 in SDK first