feat: persistent scene schema

[juniorxsound]

Description

Added persistent scene-document schema package and a --json param to the CLI so scenes can define assets, objects, cameras, views, sequences, tracks, and render pass metadata in one reusable format.

Related Issue

Fixes #XXXX (if applicable)

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Checklist

• I have tested my changes locally
• I have added/updated tests as needed
• I have updated documentation as needed
• My changes don't break existing functionality

[github-actions]

E2E: Renderer CPU

PASS • google / swiftshader
Output: /out/BoxVertexColors-preview.png

Preview PNG artifact

Captured render JSON

{
  "outputPath": "/out/BoxVertexColors-preview.png",
  "diagnostics": {
    "width": 512,
    "height": 512,
    "readbackFormat": "rgba8unorm",
    "alpha": true,
    "antialias": true,
    "runtime": {
      "requestedAt": "2026-07-07T11:42:26.257Z",
      "powerPreference": "high-performance",
      "dawnFlags": [
        "backend=vulkan"
      ],
      "adapterRequestMs": 2.36874899999998,
      "deviceRequestMs": 1.8030459999999948,
      "adapterInfo": {
        "vendor": "google",
        "architecture": "swiftshader",
        "device": "swiftshader-device-subzero-",
        "description": "SwiftShader driver 5.0.0"
      }
    }
  },
  "inspection": {
    "path": "/models/BoxVertexColors.glb",
    "format": "glb",
    "byteLength": 1924,
    "scenes": 1,
    "nodes": 1,
    "meshes": 1,
    "materials": 0,
    "textures": 0,
    "images": 0,
    "animations": 0,
    "cameras": 0,
    "extensionsUsed": [],
    "generators": [
      "JglTF from https://github.com/javagl/JglTF"
    ]
  }
}

[Copilot]

Pull request overview

This PR introduces a new persistent “scene document” package (@rendergl/headless-three-webgpu-scene) and wires it into the CLI via --json, enabling reusable JSON-defined scenes (assets/objects/cameras/views/sequences/tracks) alongside some core renderer readback enhancements needed for additional render passes.

Changes:

• Add packages/scene with Zod schema validation, evaluation/interpolation, and rendering helpers (including multi-pass rendering).
• Extend the CLI to support rgl render --json and rgl video --json flows (plans + execution + docs/tests).
• Improve core readback APIs (readback format selection, read-pixels colorSpace, renderPipeline support) and related tests/docs.

Reviewed changes

Copilot reviewed 23 out of 25 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
README.md	Adds --json usage examples for render/video.
pnpm-lock.yaml	Adds workspace linkage for the new scene package and its deps.
packages/scene/tsconfig.json	TypeScript config for the new scene package.
packages/scene/package.json	Declares the new published @rendergl/headless-three-webgpu-scene package.
packages/scene/src/index.ts	Public API surface re-exports for scene schema/eval/render helpers.
packages/scene/src/schema.ts	Defines the persistent scene document schema and validation/refinements.
packages/scene/src/evaluator.ts	Evaluates tracks over time into an evaluated scene state; summarization + duration helpers.
packages/scene/src/interpolation.ts	Keyframe sorting + interpolation (linear/hold/bezier) utilities.
packages/scene/src/render.ts	Loads scene documents, prepares a Three scene graph, and renders single/multi-pass outputs.
packages/scene/test/schema.test.ts	Coverage for schema parsing/refinement + evaluation behavior.
packages/core/src/types.ts	Extends renderer types to support readback options and pipeline rendering.
packages/core/src/renderer.ts	Implements selectable readback targets and readPixels/toBuffer options + renderPipeline.
packages/core/src/readback.ts	Optimizes row deflation and adds HDR->linear byte conversion helpers.
packages/core/src/index.ts	Updates public type exports for new readback/pipeline APIs.
packages/core/test/readback.test.ts	Adds tests for new/updated readback helpers.
packages/core/README.md	Documents readback format defaults and HDR/precision note.
packages/core/agent/skills/rgl-core/SKILL.md	Updates skill docs to reflect readback format behavior.
packages/cli/package.json	Adds dependency on the new scene package.
packages/cli/src/scene-commands.ts	Adds plan builders for scene-document render/video CLI flows.
packages/cli/src/scene-video.ts	Implements --json video rendering loop using prepared scene renders.
packages/cli/src/index.ts	Adds --json flag handling to render and video commands.
packages/cli/test/scene-commands.test.ts	Tests for scene render/video plan building logic.
packages/cli/README.md	Documents new --json render/video usage.
packages/cli/agent/skills/rgl-cli/SKILL.md	Updates skill docs to include scene JSON document support.
.gitignore	Adds additional output directories.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.