[Roadmap] Declarative Two.js web-scene feature parity

[jonobr1]

Goal

Track the remaining work required for a React application to reproduce a Two.js web scene declaratively and keep it correct through React updates.

This roadmap treats imperative access through useTwo() and refs as an escape hatch, not as proof that the React surface is complete.

Definition of feature complete

• A representative Two.js scene can be expressed without manual parent.add(...) calls.
• React remains authoritative after prop changes, prop removal, child reorder, reparenting, and unmount.
• Masks, gradients, texture-backed objects, imported SVG, and custom/existing objects have lifecycle-safe declarative paths.
• SVG, Canvas, and WebGL accept the documented configuration and produce equivalent scene structure where Two.js supports it.
• Pointer targeting follows the rendered scene graph.
• Every exported component has checked property and lifecycle coverage.

Foundation

• [Parity] Reconcile the Two.js scene graph with React updates #29
• [Parity] Complete declarative prop coverage for Two.js objects #30

Scene relationships and resources

• Feature Request: Add useClipMask hook for declarative clipping masks #9
• [Parity] Add declarative gradient stops and resource composition #31
• Feature Request: Add useTexture hook for async texture loading with states #12

Object coverage and escape hatches

• Feature Request: Add Arc component for open arc shapes #10
• [Parity] Add a Primitive escape hatch for existing and custom Two.js objects #33

Canvas and importing

• [Bug] Normalize Canvas renderer aliases and define constructor-prop updates #32
• [Bug] Finish <SVG> shallow loading and lifecycle semantics #8

Interaction correctness

• [Bug] Align pointer events with Two.js coordinates and scene order #34

Follow-on React ergonomics

These are valuable but are not blockers for core Two.js web-scene parity:

• Feature Request: Helper/Gizmo Components for Interactive Transformations #11

React Native is a separate renderer/platform initiative and remains tracked independently in #6.

Already delivered

• Core wrappers for the Two.js 0.8.23 drawable classes
• SVG, Canvas, and WebGL renderer integration
• useTwo and useFrame
• Texture component from [Feature Request] Add Two.Texture #1
• Base pointer-event system from Feature Request: Add event handlers with hit testing from latest dev branch of Two.js #16
• ZUI integration from Feature Request: Add useZUI hook for zoom/pan functionality #7

Recommended sequence

1. Land [Parity] Reconcile the Two.js scene graph with React updates #29 first because ordering, ownership, replacement, and cleanup affect most later work.
2. Complete property coverage ([Parity] Complete declarative prop coverage for Two.js objects #30) alongside mask semantics (Feature Request: Add useClipMask hook for declarative clipping masks #9).
3. Build resource composition ([Parity] Add declarative gradient stops and resource composition #31) and async texture loading (Feature Request: Add useTexture hook for async texture loading with states #12) on the shared lifecycle.
4. Finish Canvas/import correctness ([Bug] Normalize Canvas renderer aliases and define constructor-prop updates #32 and [Bug] Finish <SVG> shallow loading and lifecycle semantics #8).
5. Add Arc and the generic escape hatch (Feature Request: Add Arc component for open arc shapes #10 and [Parity] Add a Primitive escape hatch for existing and custom Two.js objects #33).
6. Complete interaction parity in [Bug] Align pointer events with Two.js coordinates and scene order #34 against the reconciled scene graph.

Non-goals

• Restoring the removed Canvas.container prop. The current styling API is intentional.
• Requiring helper/gizmo or React Native work before declaring core web scene parity.
• Wrapping every Two.js method as JSX when useTwo() or refs are the appropriate advanced API.

[jonobr1]

Roadmap Progress Update

Both Foundation track items are now complete:

• [Parity] Reconcile the Two.js scene graph with React updates #29 (Reconcile the Two.js scene graph with React updates): Centralized reconciliation engine landed via Reconcile the Two.js scene graph with React updates #36 ( / ), resolving sibling order reconciliation, discrete prop diffing, default prop resets, and Concurrent/StrictMode safety.
• [Parity] Complete declarative prop coverage for Two.js objects #30 (Complete declarative prop coverage for Two.js objects): Landed via Complete declarative prop coverage for Two.js objects #37 and Reconcile the Two.js scene graph with React updates #36, providing full property matrix coverage, exposed writable properties, OriginProp, VectorProp, ScaleProp, and comprehensive default resets in TWO_DEFAULT_PROPS.

Unblocked Tracks:

• Interaction Correctness ([Bug] Align pointer events with Two.js coordinates and scene order #34): The event system can now rely on the reconciled Two.js scene graph order (parent.children with _flagOrder) rather than fallback registration order.
• Scene Relationships & Resources ([Parity] Add declarative gradient stops and resource composition #31, Feature Request: Add useClipMask hook for declarative clipping masks #9): Gradients, stops, and mask attachments can now leverage the unified object lifecycle and owned-resource disposal.
• Object Coverage ([Parity] Add a Primitive escape hatch for existing and custom Two.js objects #33): Building <Primitive object={...} /> is now unblocked by using useTwoObject directly for attachment, reparenting, and sibling ordering.