feat: TSL (Three Shading Language) support

[devallibus]

Context

ShaderBase favors Three.js but currently only supports GLSL shaders. Three.js has native TSL (Three Shading Language) support — a JavaScript-based node material system that works with both WebGL and WebGPU renderers. TSL is the future of Three.js materials and we should support it across the stack.

Decisions

Decision	Choice	Rationale
Storage format	JS source code (.ts files)	Readable, diffable, agent-friendly, shadcn-compatible
Execution model	Sandboxed iframe, postMessage in/out	TSL is JS by design — isolate execution from app origin
Scope	Full stack (surface + geometry)	No postprocessing in v1
Contract	export function createMaterial(): NodeMaterial	Single entry point, clear interface
Type model	Discriminated unions on language	No nullable-field soup — invalid states unrepresentable
Versioning	Schema 0.1.0 → 0.2.0, registry format 0.1.0 → 0.2.0	Real contract break, ship cleanly
MCP compat	language defaults to "glsl", legacy fields preserved	Avoid breaking existing agent integrations

Architecture

1. Schema (packages/schema)

Discriminated union on language:

// Base fields shared by all shaders
const baseManifestSchema = z.object({
  schemaVersion: z.literal("0.2.0"),
  name: shaderNameSchema,
  displayName: nonEmptyStringSchema,
  // ... all shared fields
})

// GLSL-specific
const glslManifestSchema = baseManifestSchema.extend({
  language: z.literal('glsl').default('glsl'),
  files: fileReferencesSchema,  // { vertex, fragment, includes }
})

// TSL-specific
const tslManifestSchema = baseManifestSchema.extend({
  language: z.literal('tsl'),
  tslEntry: relativePathSchema,  // e.g. "source.ts"
})

const shaderManifestSchema = z.discriminatedUnion('language', [
  glslManifestSchema,
  tslManifestSchema,
])

GLSL manifest example:

{
  "schemaVersion": "0.2.0",
  "name": "gradient-radial",
  "language": "glsl",
  "files": { "vertex": "vertex.glsl", "fragment": "fragment.glsl", "includes": [] }
}

TSL manifest example:

{
  "schemaVersion": "0.2.0",
  "name": "tsl-gradient-wave",
  "language": "tsl",
  "tslEntry": "source.ts"
}

2. Registry Bundle

Discriminated union — no more assuming vertexSource + fragmentSource on every shader:

type RegistryGlslBundle = RegistryBundleBase & {
  language: 'glsl'
  vertexSource: string
  fragmentSource: string
}

type RegistryTslBundle = RegistryBundleBase & {
  language: 'tsl'
  tslSource: string
}

type RegistryShaderBundle = RegistryGlslBundle | RegistryTslBundle

3. Playground Types

Discriminated session types — no invalid states:

type PlaygroundGlslSession = PlaygroundSessionBase & {
  language: 'glsl'
  vertexSource: string
  fragmentSource: string
}

type PlaygroundTslSession = PlaygroundSessionBase & {
  language: 'tsl'
  tslSource: string
}

type PlaygroundSession = PlaygroundGlslSession | PlaygroundTslSession

4. Structured Errors

type PlaygroundError =
  | { kind: 'glsl-compile'; message: string }
  | { kind: 'glsl-link'; message: string }
  | { kind: 'tsl-parse'; message: string }
  | { kind: 'tsl-runtime'; message: string }
  | { kind: 'tsl-material-build'; message: string }

MCP backward compat: keep compilationErrors: string[] alongside new structuredErrors: PlaygroundError[].

5. Database Migration

ALTER TABLE playground_sessions ADD COLUMN shader_language TEXT NOT NULL DEFAULT 'glsl';
ALTER TABLE playground_sessions ADD COLUMN tsl_source TEXT;

6. Preview Runtimes (Playground Canvas)

Two separate runtimes behind a shared interface:

type PreviewResult = {
  errors: PlaygroundError[]
  screenshotBase64: string | null
}

interface PreviewRuntime {
  init(container: HTMLElement): Promise<void>
  render(session: PlaygroundSession): Promise<PreviewResult>
  dispose(): void
}

• GlslPreviewRuntime: existing WebGLRenderer + ShaderMaterial + GL log scraping
• TslPreviewRuntime: WebGPURenderer + NodeMaterial from createMaterial() contract

TSL runs in a sandboxed iframe (sandbox="allow-scripts", no allow-same-origin). Source passed via postMessage, screenshots/errors returned via postMessage. Same isolation model as CodePen/CodeSandbox.

7. Playground Editor

• Language selector toggle: GLSL / TSL
• TSL mode: single editor pane with JS/TS syntax highlighting
• GLSL mode: vertex/fragment tab split (unchanged)

8. API Routes

• POST /api/playground/create accepts language (default "glsl") and language-specific source fields
• POST /api/playground/:id/update accepts tslSource for TSL sessions, vertexSource/fragmentSource for GLSL
• GET /api/playground/:id/state returns discriminated session
• GET /api/playground/:id/errors returns structuredErrors alongside legacy errors

9. MCP Tools

• create_playground gains optional language param (default "glsl") and tslSource
• update_shader gains tslSource (mutually exclusive with vertex/fragment for TSL sessions)
• get_shader returns discriminated bundle (GLSL or TSL)
• search_shaders returns language in index entries
• get_errors returns structured errors

10. CLI

• shaderbase add copies .ts files for TSL shaders (instead of .glsl)
• shaderbase search shows language in results

11. Skills (shaderbase-skills/)

• tsl-fundamentals: TSL node API, composition patterns, common nodes
• tsl-patterns: Advanced TSL recipes (noise, SDF, procedural)
• Update shaderbase-manifest skill for TSL manifest fields

TSL Contract

Every TSL shader exports createMaterial:

import { color, mix, uv, sin, time } from 'three/tsl';
import { NodeMaterial } from 'three/webgpu';

export function createMaterial(): NodeMaterial {
  const material = new NodeMaterial();
  const t = sin(time.mul(2.0)).mul(0.5).add(0.5);
  material.colorNode = mix(
    color(0x1a1a2e),
    color(0xe94560),
    mix(uv().x, uv().y, t)
  );
  return material;
}

Implementation Order

1. Schema: discriminated union, bump to 0.2.0
2. Registry types + builder: discriminated bundle
3. CLI + MCP: handle both bundle shapes
4. Playground types + DB migration
5. API route updates
6. MCP handler updates
7. Playground UI: language selector, editor mode
8. Sandboxed TSL preview runtime
9. Structured error model
10. First TSL shader in the corpus
11. Skills

Explicitly Out of Scope

• TSL postprocessing pipeline (separate follow-up issue)
• Same-origin execution of user TSL source
• Phased prep release — ship the contract change directly

Version Bumps

Contract	From	To
Manifest schema	0.1.0	0.2.0
Registry format	0.1.0	0.2.0
@shaderbase/schema	minor bump
@shaderbase/cli	minor bump if public contract changes
@shaderbase/mcp	minor bump if tool output changes

[devallibus]

I reviewed the current codebase against this proposal and I think we should adjust the plan before implementation. The main conclusion is that TSL support is viable, but not as a drop-in extension of the current GLSL playground contract.

Summary

The blockers are:

1. The current playground trust model is safe enough for shader strings, but not for arbitrary executable TSL/JS source.
2. The current error/preview path is WebGL + ShaderMaterial specific, so get_errors and screenshots cannot remain unchanged.
3. The current registry/CLI/MCP bundle contract is GLSL-shaped end to end.
4. postprocessing is not a good v1 target for TSL because the current fullscreen-fragment model does not map cleanly to the Three.js WebGPU/TSL stack.

Recommended Path Forward

Phase 0: Re-scope issue #56

Change the scope from "full stack TSL parity" to:

• Add TSL support for surface and geometry shaders only
• Keep GLSL behavior unchanged
• Do not support TSL postprocessing in v1
• Do not execute TSL source in the main app origin

That gets us to a shippable feature without breaking existing MCP, CLI, and registry consumers.

Phase 1: Introduce a versioned shader language contract

We should explicitly model shader language in both manifest and registry output.

Manifest changes:

language: z.enum(['glsl', 'tsl']).default('glsl')

For GLSL:

{
  "language": "glsl",
  "files": {
    "vertex": "vertex.glsl",
    "fragment": "fragment.glsl",
    "includes": []
  }
}

For TSL:

{
  "language": "tsl",
  "tslEntry": "source.ts"
}

Registry changes:

• RegistryIndexEntry gains language
• RegistryShaderBundle becomes a discriminated union instead of always requiring vertexSource + fragmentSource
• CLI add and MCP get_shader read the union shape instead of assuming GLSL

This should be treated as a contract change, not just an internal implementation detail.

Phase 2: Isolate TSL execution

We should not execute user-provided TSL source in the same origin/page context that hosts the main app shell.

Recommended implementation:

• Render TSL previews inside a sandboxed iframe or dedicated isolated preview app
• Pass session state in via postMessage
• Return screenshots/errors from the isolated preview runtime back to the parent
• Keep the current capability-token session model only for GLSL, or strengthen auth for TSL sessions

If we want live editing with arbitrary JS semantics, we need origin/process isolation first. Without that, the session URL becomes a remote code execution token for the page context.

Phase 3: Split the playground runtime by language

The current canvas is strongly coupled to:

• three
• WebGLRenderer
• ShaderMaterial
• GL compile/link log scraping

TSL needs a separate runtime path:

• Import from three/webgpu
• Create a WebGPURenderer
• Build a NodeMaterial from the TSL entry contract
• Capture JS parse/runtime/material build errors explicitly

Important point: this should not be implemented as "one renderer with if-statements everywhere". We should define:

• runGlslPreview(session)
• runTslPreview(session)

with a narrow shared shell around them.

Phase 4: Update MCP/API semantics

The issue text currently says get_preview and get_errors are unchanged. I do not think that holds.

Recommended API shape:

• create_playground accepts language
• update_shader accepts language-specific payloads
• get_errors returns structured errors with kind

Example:

type PlaygroundError =
  | { kind: 'glsl-compile'; message: string }
  | { kind: 'glsl-link'; message: string }
  | { kind: 'tsl-parse'; message: string }
  | { kind: 'tsl-runtime'; message: string }
  | { kind: 'tsl-material-build'; message: string }

That keeps MCP honest instead of pretending TSL failures are equivalent to GLSL compiler output.

Phase 5: Ship one end-to-end TSL example last

Only after the schema, registry contract, CLI add flow, playground runtime, and MCP changes are complete should we add the first corpus shader.

This should be the acceptance sequence:

1. TSL manifest validates
2. Registry builder emits a valid TSL bundle
3. CLI add writes the right files locally
4. MCP get_shader returns the new bundle shape
5. Playground can open, edit, render, report errors, and return screenshots for one TSL shader
6. Then add the first real TSL shader to shaders/

Proposed Revised Implementation Order

1. Schema and registry type redesign
2. Registry builder + CLI + MCP union support
3. Playground session model and DB updates
4. Isolated TSL preview runtime
5. Playground UI language switch
6. Structured error model
7. First TSL shader example
8. Follow-up issue for TSL postprocessing

Explicit Non-Goals For This Issue

• No TSL postprocessing support
• No same-origin dynamic execution of user TSL source
• No attempt to keep the old vertexSource/fragmentSource bundle shape as the only registry contract

Suggested Follow-Ups

• Create a dedicated follow-up issue for TSL postprocessing
• Create a dedicated follow-up issue for auth/session hardening in the playground
• Create a small ADR documenting why TSL runs in isolation and why the registry contract changed

If this direction sounds right, I’d update this issue description to reflect the narrowed v1 scope and split the work into separate tracked issues for contract changes, isolated runtime, and postprocessing.

[devallibus]

Adding some concrete examples for how I think this should look in practice, plus the gates for expanding TSL scope later.

Concrete Examples

1. Manifest shape

I would make the manifest language-aware with a discriminated union.

GLSL:

{
  "schemaVersion": "0.1.0",
  "name": "gradient-radial",
  "displayName": "Radial Gradient",
  "language": "glsl",
  "files": {
    "vertex": "vertex.glsl",
    "fragment": "fragment.glsl",
    "includes": []
  }
}

TSL:

{
  "schemaVersion": "0.1.0",
  "name": "tsl-gradient-wave",
  "displayName": "TSL Gradient Wave",
  "language": "tsl",
  "tslEntry": "source.ts"
}

Type shape:

type GlslManifest = BaseManifest & {
  language: 'glsl'
  files: {
    vertex: string
    fragment: string
    includes: string[]
  }
}

type TslManifest = BaseManifest & {
  language: 'tsl'
  tslEntry: string
}

type ShaderManifest = GlslManifest | TslManifest

2. Registry bundle shape

The registry bundle should also be a discriminated union instead of forcing vertexSource + fragmentSource on every shader.

type RegistryGlslBundle = RegistryBundleBase & {
  language: 'glsl'
  vertexSource: string
  fragmentSource: string
}

type RegistryTslBundle = RegistryBundleBase & {
  language: 'tsl'
  tslSource: string
}

type RegistryShaderBundle = RegistryGlslBundle | RegistryTslBundle

Example TSL bundle:

{
  "name": "tsl-gradient-wave",
  "displayName": "TSL Gradient Wave",
  "language": "tsl",
  "pipeline": "surface",
  "stage": "fragment",
  "tslSource": "import { color, mix, uv } from 'three/tsl';\nimport { MeshBasicNodeMaterial } from 'three/webgpu';\n\nexport function createMaterial() {\n  const material = new MeshBasicNodeMaterial();\n  material.colorNode = mix(color('#0b1020'), color('#ff5d73'), uv().x);\n  return material;\n}\n",
  "recipes": {
    "three": {
      "exportName": "createTslGradientWaveMaterial",
      "summary": "Creates a TSL node material for Three.js",
      "code": "import { createMaterial } from './source';\nexport { createMaterial };",
      "placeholders": [],
      "requirements": ["three-scene", "mesh"]
    }
  }
}

3. Playground session shape

I would avoid optional fields everywhere and instead store a language-discriminated session payload.

type PlaygroundGlslSession = {
  id: string
  language: 'glsl'
  vertexSource: string
  fragmentSource: string
  pipeline: 'surface' | 'geometry' | 'postprocessing'
}

type PlaygroundTslSession = {
  id: string
  language: 'tsl'
  tslSource: string
  pipeline: 'surface' | 'geometry'
}

type PlaygroundSession = PlaygroundGlslSession | PlaygroundTslSession

That makes invalid states harder to create:

• no tslSource: null
• no “TSL session with GLSL fragment source”
• no “TSL postprocessing” unless we explicitly add it later

4. API examples

Create GLSL session:

POST /api/playground/create
{
  "language": "glsl",
  "vertexSource": "...",
  "fragmentSource": "...",
  "pipeline": "surface"
}

Create TSL session:

POST /api/playground/create
{
  "language": "tsl",
  "tslSource": "import { uv } from 'three/tsl'; ...",
  "pipeline": "surface"
}

Update TSL session:

POST /api/playground/:id/update
{
  "tslSource": "import { time } from 'three/tsl'; ..."
}

Structured errors:

{
  "errors": [
    {
      "kind": "tsl-runtime",
      "message": "createMaterial is not exported",
      "line": 4,
      "column": 1
    }
  ]
}

5. Preview runtime interface

Instead of branching throughout one giant canvas component, I would separate the runtimes explicitly.

type PreviewResult = {
  errors: PlaygroundError[]
  screenshotBase64: string | null
}

interface PreviewRuntime<TSession> {
  init(container: HTMLElement): Promise<void>
  render(session: TSession): Promise<PreviewResult>
  dispose(): void
}

Then:

const runtime =
  session.language === 'glsl'
    ? new GlslPreviewRuntime()
    : new TslPreviewRuntime()

That keeps GLSL stable while giving TSL a separate renderer/bootstrap lifecycle.

6. TSL runtime example

The TSL preview side should be closer to:

import * as THREE from 'three'
import { WebGPURenderer, MeshBasicNodeMaterial } from 'three/webgpu'
import * as TSL from 'three/tsl'

type TslModule = {
  createMaterial: () => MeshBasicNodeMaterial
}

async function renderTslSource(source: string): Promise<MeshBasicNodeMaterial> {
  const mod = await loadIsolatedTslModule(source, { THREE, TSL, WebGPURenderer })
  if (typeof mod.createMaterial !== 'function') {
    throw new Error('TSL entry must export createMaterial()')
  }
  return mod.createMaterial()
}

Notably, this is not “rewrite imports and eval in the main page”.

When We Can Expand TSL Scope

I would expand only after these gates are met.

Expand from surface to geometry

Safe when all of these are true:

• isolated TSL runtime is already in place
• structured TSL errors are wired through API + MCP
• screenshot generation is stable in CI/manual testing
• at least one real TSL shader can round-trip through registry, CLI, MCP, and playground

This is a relatively small expansion because it still maps to a mesh material model.

Expand to TSL postprocessing

Only after:

• we have a dedicated design for node-based postprocessing in Three.js WebGPU
• the preview runtime can support render graph / post chain setup
• the registry contract can represent postprocessing-specific requirements cleanly
• we have at least one working example that does not regress existing GLSL postprocessing shaders

I would treat this as a separate issue entirely, not as part of initial TSL support.

Expand trust/access model

If we ever want collaborative/shared TSL editing beyond capability-token URLs, do it only after:

• session auth is stronger than raw UUID possession
• sandbox/isolation boundaries are documented
• we are clear on whether TSL source is private, shareable, or executable by other viewers

Practical Expansion Rule

The short version:

• v1: TSL surface
• v1.1: TSL geometry
• v2: TSL postprocessing, if the runtime model proves out

If we keep that sequence, we avoid coupling renderer migration, security model changes, registry changes, and postprocessing abstractions into one risky delivery.

[devallibus]

One more thing we should lock down in this issue: semver policy.

Right now there are several different version surfaces in this repo:

• repo/package version
• @shaderbase/schema package version
• @shaderbase/cli package version
• @shaderbase/mcp package version
• shader manifest schemaVersion
• registry JSON format version

If we do TSL without making those boundaries explicit, we will absolutely create compatibility drift later.

Recommendation: Treat These As Separate Contracts

We should version these independently:

1. Manifest schema version

This is the contract for shaders/*/shader.json.

Current:

{
  "schemaVersion": "0.1.0"
}

Recommended with TSL:

• bump manifest schema from 0.1.0 -> 0.2.0
• because the shape is no longer “always GLSL files”
• all manifests, including GLSL ones, should move to the new schema version once the union shape lands

Why this is breaking:

• today files.vertex and files.fragment are effectively required
• after TSL support, manifests can be GLSL or TSL
• validators and tooling that assume GLSL-only manifests would break on the new shape

So this should not stay 0.1.0.

2. Registry format version

The generated registry payload also needs its own version, separate from package versions.

Current:

{
  "version": "0.1.0"
}

Recommended:

• rename this conceptually to “registry format version” in docs
• bump registry format from 0.1.0 -> 0.2.0 when TSL bundles are introduced

Why this is breaking:

• index entries gain language
• bundle shape becomes a discriminated union
• consumers can no longer assume vertexSource + fragmentSource always exist

That is a real format break.

3. Package versions

These should follow package semver, but we should document our policy for pre-1.0 packages so there is no ambiguity.

Recommended repo policy:

• patch: bug fixes and internal refactors with no contract change
• minor: additive, backwards-compatible API/feature changes
• major: breaking package API changes

Because these packages are still <1.0.0, the practical encoding becomes:

• breaking: 0.1.x -> 0.2.0
• additive: 0.1.0 -> 0.1.1 is too weak, so use 0.1.0 -> 0.1.1 only for fixes
• additive feature: 0.1.0 -> 0.1.1 if internal only, but 0.1.0 -> 0.2.0 if consumer-facing and risky

Honestly, I would be stricter and say:

• for this repo, while pre-1.0, any consumer-visible contract break bumps the minor
• internal fixes bump patch

So:

• @shaderbase/schema: 0.1.0 -> 0.2.0
• @shaderbase/mcp: bump if tool contracts change in a breaking way
• @shaderbase/cli: bump if output/input expectations change in a breaking way

Concrete Versioning Plan For TSL

Here is the cleanest way I see to ship this.

Phase A: Additive prep release

Goal: prepare consumers without breaking them.

Changes:

• add language to index entries
• keep existing GLSL bundle shape untouched
• do not yet publish TSL bundles in the main registry format
• optionally add docs saying TSL support is staged

Versioning:

• manifest schema stays 0.1.0
• registry format stays 0.1.0
• package versions bump only if needed for additive behavior

This phase is optional, but it gives external consumers time to handle language.

Phase B: TSL contract release

Goal: actually support TSL bundles/manifests.

Changes:

• manifest schema becomes discriminated union
• registry bundle becomes discriminated union
• CLI add flow supports GLSL and TSL bundles
• MCP get_shader returns either GLSL or TSL bundle

Versioning:

• manifest schema: 0.2.0
• registry format: 0.2.0
• @shaderbase/schema: 0.2.0
• @shaderbase/cli: bump minor if output/input expectations change
• @shaderbase/mcp: bump minor if tool output changes in a breaking way

This is the real TSL release.

MCP/API Compatibility Rule

This is where it is easy to accidentally break agents.

I would strongly recommend:

• keep existing GLSL request fields working
• make language optional with default glsl
• if we introduce structured TSL errors, add them as a new field first

Example:

{
  "compilationErrors": ["legacy string form"],
  "structuredErrors": [
    { "kind": "tsl-runtime", "message": "createMaterial is not exported" }
  ]
}

Then later, in a future breaking release, we can deprecate the legacy string-only form if we want.

That gives us:

• no immediate MCP break for existing agents
• enough room to represent TSL failures properly

Suggested Compatibility Matrix

We should document something like this:

Contract	Version	Notes
Manifest schema	0.1.x	GLSL-only manifests
Manifest schema	0.2.x	GLSL + TSL discriminated union
Registry format	0.1.x	vertexSource + fragmentSource required
Registry format	0.2.x	language-aware union bundles
MCP playground API	0.1.x	GLSL-first, legacy error strings
MCP playground API	0.2.x	language-aware payloads, structured errors added

Rule Of Thumb

The clean rule is:

• if a consumer can keep working without code changes, it is additive
• if a consumer needs new branching logic for TSL, it is a contract version bump

For this issue specifically, I think TSL support should be treated as:

• manifest schema breaking
• registry format breaking
• potentially MCP additive if we preserve old fields carefully
• package-level minor bump while pre-1.0

If we write this down now, later changes like “TSL postprocessing” become much easier to classify instead of turning into ad hoc version bumps.

--
GPT-5 Codex

[devallibus]

Assessment

I read the full review against the current codebase. Here is my assessment, point by point.

Strongly agree

Discriminated unions over nullable fields. The current types (PlaygroundSession, CreateSessionRequest, UpdateShaderRequest) are GLSL-shaped throughout. Adding nullable tslSource fields would create an invalid state space where a session has both fragmentSource and tslSource populated. Discriminated unions on language are the correct model for manifest, registry bundle, playground session, and API payloads. This is the single highest-value change in the review.

Separate preview runtimes. The current PlaygroundCanvas.tsx is tightly coupled to WebGLRenderer + ShaderMaterial + GL compile log scraping (lines 163–189). Bolting TSL support onto this with if-statements would produce a fragile component. Two separate runtime implementations behind a shared PreviewRuntime interface is cleaner, more testable, and lets GLSL stay completely stable while TSL evolves independently.

Structured errors. GLSL errors are strings from the GL driver with line numbers baked into the text. TSL errors are JavaScript parse/runtime/material-build errors with a completely different shape. Modeling them as a discriminated PlaygroundError union with kind is correct. The additive approach for MCP backward compatibility — keeping compilationErrors: string[] alongside new structuredErrors — is pragmatic and avoids breaking existing agent integrations.

No TSL postprocessing in v1. The WebGPU post-processing model in Three.js is fundamentally different from the WebGL EffectComposer chain. The current playground's fullscreen-fragment pipeline doesn't map to it. Correct to exclude from initial scope.

Versioning contracts separately. Manifest schema, registry format, and package versions are genuinely distinct contracts with different consumers. Bumping manifest schema from 0.1.0 → 0.2.0 for the discriminated union change is correct — it IS a breaking change to the manifest shape. Same for registry format.

MCP backward compatibility. Making language optional with default "glsl", keeping existing GLSL request fields working, and adding structured errors as a new field alongside the legacy string form — all correct. Agents using create_playground today should continue working without code changes.

Partially agree — with adjustments

Iframe isolation for TSL execution. The security concern is valid: executing user-provided JS in the main app origin gives it access to cookies, localStorage, session tokens, and the DOM. A sandboxed iframe with sandbox="allow-scripts" (without allow-same-origin) is the right approach — it restricts access to the parent origin while still allowing JS execution. However, framing this as "avoiding eval" is misleading. TSL shaders ARE JavaScript by design. The question is not whether to execute JS — it is the entire feature. The question is WHERE to execute it. Answer: a sandboxed iframe that receives source via postMessage and returns screenshots/errors back via postMessage. This is the same model CodePen, CodeSandbox, and Shadertoy use.

Surface-only for v1, geometry gated behind v1.1. I would include both surface and geometry in v1. The runtime path is identical — both create a NodeMaterial applied to a mesh. The only difference is the geometry shape (plane vs sphere) and camera setup, which the current canvas already handles (lines 71–76, 152–158). Gating geometry behind a separate release creates artificial friction with no meaningful risk reduction.

Disagree

Phase A additive prep release. This is a pre-1.0 project with essentially zero external consumers of the manifest schema or registry format. Shipping an intermediate "add language field but don't actually use it" release before the real TSL release adds a pointless deployment cycle. Just ship the breaking change directly. We can always add migration tooling later if consumers appear.

Proposed revised scope for v1

Incorporating the review's strongest recommendations:

1. Discriminated unions everywhere: manifest, registry bundle, session types, API payloads
2. Schema version bump: 0.1.0 → 0.2.0
3. Sandboxed iframe for TSL execution: postMessage in/out, no same-origin access
4. Two preview runtimes: GlslPreviewRuntime + TslPreviewRuntime behind shared interface
5. Structured errors: discriminated by kind, legacy compilationErrors preserved for MCP compat
6. Surface + geometry pipelines (not postprocessing)
7. No phased prep release — ship the contract change directly

— Claude Opus 4.6

[devallibus]

Decision update after the latest review:

I agree with the push to be less conservative here. Given the current project stage, I think we should optimize for a clean architecture instead of compatibility theater.

Decisions

1. Ship the contract change directly

• No additive prep release
• No temporary hybrid registry shape just to avoid a break that nobody depends on
• Treat TSL support as a real contract evolution and ship it cleanly

2. Include both surface and geometry in v1

• I agree that geometry does not materially increase risk once the TSL runtime exists
• Both map to the same core model: build a NodeMaterial, apply it to a mesh, render it
• postprocessing remains out of scope for this issue

3. Use discriminated unions everywhere

• Manifest
• Registry bundle
• Playground session
• API payloads
• Error model

No nullable-field soup.

4. Run TSL in an isolated runtime

• Sandboxed iframe or equivalent isolated preview surface
• postMessage in/out
• No same-origin execution of user TSL source in the main app shell

TSL is JS by design. The decision is not whether to execute code, but where to execute it safely.

5. Split preview runtimes

• GlslPreviewRuntime
• TslPreviewRuntime

Shared shell if useful, but no giant renderer component full of language branches.

6. Preserve MCP compatibility where it is cheap

• language defaults to "glsl"
• existing GLSL fields keep working
• add structured errors without removing legacy string errors yet

That gives us a clean internal model without forcing avoidable MCP churn immediately.

7. Bump versions explicitly

• manifest schema: 0.1.0 -> 0.2.0
• registry format: 0.1.0 -> 0.2.0
• package versions: bump minor where the public contract changes

Final v1 scope for this issue

Included:

• TSL manifest support
• TSL registry bundle support
• CLI/MCP support for TSL bundles
• isolated TSL playground runtime
• structured TSL errors
• TSL surface
• TSL geometry

Excluded:

• TSL postprocessing

Implementation stance

I think we should now rewrite the issue around this scope and implement it as one coherent architectural change instead of staging around hypothetical consumers that do not exist yet.

--
GPT-5 Codex