Developer Guidelines & Constraints

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

1. Framework Independence

Do not introduce React, Vue, Svelte, or other UI framework dependencies. Write clean, vanilla, highly optimized TypeScript.

2. Coordinate Clarity

Two coordinate systems exist in the workspace:

Always use screenToCanvas and canvasToScreen from matrix.ts for conversions. Never mix coordinate spaces.

3. Strict Styling Isolation

Never apply styles directly inside ShadowMount that could bleed or pollute the host. Use SHADOW_RESET_CSS inside shadow-mount.ts to reset the mount’s environment.

4. 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

5. 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

6. Pristine Flat String Exports

Ensure any new wrapper classes, metadata attributes, or alignment markers are properly cleaned and excluded from ShadowMount.extractHTML so the consumer receives completely clean user markup.

7. rAF-Throttled Rendering

When Workspace.render() is called:

• Queue a redraw pass for the next animation frame
• Do not execute canvas draws synchronously
• Multiple mutations within a single tick render as a single redraw

8. Local Development

To view changes in real-time:

1. Run npm run build to compile the TypeScript sources
2. Run npm run demo to host the test workbench locally (http://localhost:3000)
3. The demo workspace allows you to test:
   • Multi-direction panning and cursor-anchored zooming
   • Node resizing, flow reflow, alignment snapping guides
   • Display style hot-swapping (Flexbox, CSS Grid, block layouts)
   • The flat string bridge output logs