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

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

Updated after the October 14, 2026 issue review. Foundation (#29 and #30), Canvas/import correctness (#32 and #8), and interaction correctness (#34) are complete. PR #39 closed #8, #32, and #34.

1. Highest priority: [Parity] Add declarative gradient stops and resource composition #31 — gradient stops and resource composition. The README Gradient Fill example still supplies plain stop objects and has an invalid callback-ref pattern. Fix the executable example first, then deliver declarative stops, binding, updates, and shared-resource cleanup.
2. Next: Feature Request: Add useTexture hook for async texture loading with states #12 — async texture loading. Deliver loading/loaded/error state, source changes, stale-result protection, and cleanup first. Cache/preload, retry, and optional Suspense can follow separately. The Texture component from [Feature Request] Add Two.Texture #1 does not satisfy this hook request.
3. Next: Feature Request: Add useClipMask hook for declarative clipping masks #9 — lifecycle-safe mask relationships. Direct mask/clip properties and reset behavior landed in [Parity] Complete declarative prop coverage for Two.js objects #30/[Parity] Reconcile the Two.js scene graph with React updates #29; masked event handling landed in [Bug] Align pointer events with Two.js coordinates and scene order #34. Focus this issue on mask creation, switching, disabling, and ownership cleanup rather than repeating those completed layers.
4. Then: [Parity] Add a Primitive escape hatch for existing and custom Two.js objects #33 — existing/custom object escape hatch. Reuse the shared lifecycle, but explicitly define borrowed-object ownership, replacement, Group children, and cleanup.
5. Then: Feature Request: Add Arc component for open arc shapes #10 — first-class typed Arc. Keep this distinct from [Parity] Add a Primitive escape hatch for existing and custom Two.js objects #33: a generic object wrapper does not replace a discoverable typed Arc component.

Backlog triage

• No exact duplicates were found among the remaining open feature requests.
• Keep [Roadmap] Declarative Two.js web-scene feature parity #35 as the umbrella tracker; its overlap with child issues is intentional.
• Feature Request: Helper/Gizmo Components for Interactive Transformations #11 (helpers/gizmos) is follow-on ergonomics. Its event-system prerequisites are complete, but it is not a core web-parity blocker.
• Feature Request: Implement React Native Renderer for @react/two.js #6 (React Native) is a separate platform initiative. Keep it out of the core web-parity delivery sequence; choose package structure and renderer scope before implementation.
• Feature Request: Add useClipMask hook for declarative clipping masks #9 is partially delivered, not a closure candidate: its higher-level relationship API remains missing.
• 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 share an Arc use case but have distinct acceptance criteria.
• Feature Request: Add useTexture hook for async texture loading with states #12 remains open because main exports Texture but not useTexture.
• Already closed issues, including [Parity] Reconcile the Two.js scene graph with React updates #29, [Parity] Complete declarative prop coverage for Two.js objects #30, [Bug] Finish <SVG> shallow loading and lifecycle semantics #8, [Bug] Normalize Canvas renderer aliases and define constructor-prop updates #32, and [Bug] Align pointer events with Two.js coordinates and scene order #34, require no new implementation ticket for the same work.

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.