Complete declarative prop coverage for Two.js objects

[jonobr1]

Walkthrough: Complete Declarative Prop Coverage for Two.js Objects (Issue #30)

Completed declarative prop coverage and parity for Two.js objects in react-two.js on branch fix_github_issue_30 against Two.js v0.8.23.

Summary of Changes

1. Component Props & Parity Updates

• Path and Path-derived shapes (Circle, Ellipse, Line, Polygon, RoundedRectangle, Star, ArcSegment, Rectangle, Image, Sprite, ImageSequence):
  • Added direct declarative support for mask, clip, and strokeAttenuation.
  • Added radius to PolygonProps.
  • Exported all shape prop types (PathProps, CircleProps, EllipseProps, LineProps, PolygonProps, RoundedRectangleProps, StarProps, ArcSegmentProps).
• Group and SVG:
  • Added direct declarative support for mask, beginning, ending, and strokeAttenuation.
  • Added opacity and visible to SVGProps.
  • Exported GroupProps and SVGProps.
• Text:
  • Added direct declarative support for mask, clip, and strokeAttenuation.
  • Exported TextProps.
• Points:
  • Added direct declarative support for strokeAttenuation.
  • Exported PointsProps.
• Rectangle, Image, Sprite, ImageSequence:
  • Added origin support across Rectangle, Image, Sprite, and ImageSequence.
  • Supported Two.Vector, object literals { x?: number; y?: number }, and tuples [number, number].
  • Handled origin updates safely in the reconciliation effect without throwing TypeError: this._origin.bind is not a function.
  • Exported RectangleProps, ImageProps, SpriteProps, ImageSequenceProps.
• Sprite.src:
  • Updated Sprite.src type to accept string | Texture (allowing Two.Texture directly in addition to string URLs).
• Properties.ts:
  • Added translation to ShapeProps.
  • Exported static property arrays: ELEMENT_PROPERTIES, SHAPE_PROPERTIES, GRADIENT_PROPERTIES.
• LinearGradient, RadialGradient, Texture:
  • Exported LinearGradientProps, RadialGradientProps, TextureProps.
• main.ts:
  • Re-exported all component prop interfaces, shared property types, and property matrix data.

---

2. Checked Property Matrix & Documentation

• lib/propertyMatrix.ts:
  • Created typed PROPERTY_MATRIX mapping every exported component (19 components total) against supported Two.js v0.8.23 properties.
  • Specified all supported declarative props and documented intentional omissions categorized as read-only, renderer-internal, managed-by-react, or imperative-method.
• docs/property-matrix.md:
  • Comprehensive documentation covering the property matrix table, declarative additions, intentional omissions, and imperative escape hatches using refs (RefPath, RefRectangle, RefSprite, etc.) and useFrame.

---

3. Verification & Automated Tests

• tests/propertyMatrix.test.tsx:
  • Compile-time tests: Tested type assignability and acceptance of mask, clip, strokeAttenuation, origin (Vector | { x, y } | [x, y]), Sprite.src (string | Two.Texture), and beginning/ending.
  • Runtime tests:
    • Verified declarative mask and clip on Path, Group, Text, and Rectangle.
    • Verified declarative strokeAttenuation on Path, Group, Text, Points, Circle.
    • Verified declarative beginning and ending on Group and SVG.
    • Verified origin support across Rectangle, Image, Sprite, ImageSequence with Two.Vector, { x, y }, and [x, y].
    • Verified Sprite.src with Two.Texture.
    • Verified dynamic prop re-renders for origin and strokeAttenuation.
    • Verified rendering of all primitives and gradients inside Canvas.

Test Results

 RUN  v3.2.4

 ✓ tests/wiremarksStorage.test.ts (11 tests)
 ✓ tests/wiremarksLayout.test.ts (26 tests)
 ✓ tests/wiremarks.test.ts (17 tests)
 ✓ tests/diffsStorage.test.ts (7 tests)
 ✓ tests/wiremarksGraph.test.ts (12 tests)
 ✓ tests/diffsReveal.test.ts (2 tests)
 ✓ tests/wiremarkEntity.test.tsx (3 tests)
 ✓ tests/wiremarkConnection.test.tsx (3 tests)
 ✓ tests/events.test.tsx (12 tests)
 ✓ tests/zui.test.tsx (16 tests)
 ✓ tests/diffsStatLine.test.tsx (5 tests)
 ✓ tests/propertyMatrix.test.tsx (27 tests)
 ✓ tests/diffsModel.test.ts (6 tests)
 ✓ tests/zuiMath.test.ts (14 tests)
 ✓ tests/diffsTokenize.test.ts (4 tests)
 ✓ tests/diffsCanvas.test.tsx (5 tests)
 ✓ tests/registry.test.ts (2 tests)

 Test Files  17 passed (17)
      Tests  172 passed (172)

Build and lint verification:

• npm run build: built production bundle + generated .d.ts declaration files successfully.
• npm run lint: clean pass with 0 errors and 0 warnings.

[Copilot]

🟡 Changes recommended

The new public “property list” exports currently include internal/read-only fields and there is at least one avoidable runtime import that should be corrected before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR implements Issue #30 by bringing react-two.js component props into closer declarative parity with Two.js v0.8.23, adding a checked property matrix, documentation, and targeted tests to validate both typing and runtime behavior.

Changes:

• Expanded declarative prop coverage across shapes (e.g., mask, clip, strokeAttenuation) and added origin ergonomics for rectangle-derived effects plus Two.Texture support for Sprite.src.
• Introduced a typed PROPERTY_MATRIX/SUPPORTED_TWO_VERSION contract and documented supported vs intentionally-omitted properties.
• Added compile-time and runtime tests to validate prop typing, reconciliation, and re-render updates.

File summaries

File	Description
tests/propertyMatrix.test.tsx	Adds compile-time + runtime tests validating the new prop surface and PROPERTY_MATRIX.
lib/propertyMatrix.ts	Defines the typed property matrix and omission categories for Two.js v0.8.23.
docs/property-matrix.md	Documents the matrix, additions, omissions, and ref-based escape hatches.
lib/main.ts	Re-exports prop types, shared property lists, and the property matrix APIs from the library entry.
lib/Properties.ts	Adds translation and exports static property arrays for element/shape/gradient props.
lib/Path.tsx	Extends PathProps with mask, clip, and strokeAttenuation.
lib/Group.tsx	Extends and exports GroupProps to include mask, beginning, ending, strokeAttenuation.
lib/SVG.tsx	Reuses GroupProps for SVG prop parity and exports SVGProps.
lib/Text.tsx	Exports TextProps and extends it with mask, clip, strokeAttenuation.
lib/Points.tsx	Exports PointsProps and adds strokeAttenuation.
lib/Rectangle.tsx	Adds declarative origin support (including tuple/object-literal ergonomics) and exports RectangleProps.
lib/Image.tsx	Adds origin support and exports ImageProps.
lib/Sprite.tsx	Adds origin support, widens src to accept Texture, and exports SpriteProps.
lib/ImageSequence.tsx	Adds origin support and exports ImageSequenceProps.
lib/Polygon.tsx	Exports PolygonProps and adds radius.
lib/RoundedRectangle.tsx	Exports RoundedRectangleProps.
lib/Star.tsx	Exports StarProps.
lib/Line.tsx	Exports LineProps.
lib/Circle.tsx	Exports CircleProps.
lib/Ellipse.tsx	Exports EllipseProps.
lib/ArcSegment.tsx	Exports ArcSegmentProps.
lib/LinearGradient.tsx	Exports LinearGradientProps.
lib/RadialGradient.tsx	Exports RadialGradientProps.

Review details

• Files reviewed: 23/23 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The changes are cohesive, covered by extensive compile-time/runtime tests, and the new property matrix + documentation align with the stated parity goals for Two.js v0.8.23.

Review details

• Files reviewed: 23/23 changed files
• Comments generated: 0 new
• Review effort level: Lite