Developer Guidelines & Constraints

When extending or writing code for Canvus, adhere to these rules to maintain codebase integrity and consistency.

Core Constraints

Many of our core architecture constraints are defined in Design Philosophy & Goals. When developing the SDK:

• Framework Independence: Ensure the SDK core remains 100% vanilla TypeScript. No React, Vue, Svelte, or other UI framework dependencies are permitted.
• Strict Styling Isolation: Never apply styles directly inside ShadowMount that could bleed or pollute the host. All reset rules belong in SHADOW_RESET_CSS.
• Pristine Flat String Exports: Any new wrapper classes, metadata attributes, or alignment markers must be filtered out in ShadowMount.extractHTML to ensure the consumer receives clean user markup.
• rAF-Throttled Rendering: Canvas overlay drawings must never run synchronously; queue them on the next animation frame to prevent redraw bottlenecks.

Coordinate Space Clarity

Two coordinate systems exist in the workspace:

Use screenToCanvas and canvasToScreen from matrix.ts for all conversions. Never mix coordinate spaces.

Geometry and Tree Synchronization

• Never mutate parentId or childIds of a node directly. Always use the mutation APIs in NodeTree (addNode, removeNode, reparentNode, reorderChild).
• When mutating DOM structures (e.g., reparenting), update both the ShadowMount DOM tree wrappers and the NodeTree model.

Minimize Layout Thrashing

• Avoid calling getBoundingClientRect() repeatedly in hot loops. Use cached values from currentRect inside WebHTMLNode whenever possible.
• Use suppressObserver flags in ShadowMount during programmatic node manipulations to avoid observer feedback loops.

Local Development

For details on setting up the contributor workflow and launching the local Dev Workbench, see the Installation & Setup guide.