zui/frontend/docs/IMPROVEMENTS.md

Codebase simplification and design patterns

This doc summarizes recent improvements and suggested next steps for readability, extension, and consistency.

Done

1. Single place for template/reachability (DRY)

• Added lib/graph/templateRefs.ts: isReachable, resolveExtendsRef, getTemplateRefs.
• Refactored config/renderingLogic.ts and useRenderingNodeState.ts to use these helpers instead of duplicating the same logic.
• Pattern: Extract shared pure helpers into a small lib module; keep call sites thin and consistent.

2. Naming and comments

• Renamed outputMenuRegistry.tsx → outputMenuHandlers.tsx (no registry, only helpers).
• Updated rendering.ts and sourceRenderingLogic.ts: output menu is described as coming from the node descriptor (getOutputMenuContent), not a separate registry.
• Documented NodeMenubar: extra content can come from props or from the descriptor (getNodeMenuExtraContent).
• Documented nodeTypes.ts: clarifies React Flow types vs node type id (nodeRegistry).

3. Central pipeline entry

• rendering.ts documents the 3-step pipeline, how to add a source/output type, and points to templateRefs.ts for shared helpers.

4. Rendering signatures (pure module)

• Added lib/graph/renderingSignatures.ts: buildConnectedNodeIds, buildSourceSignatures (connectedNodeIds + all five signatures + sourceSignature).
• Refactored useRenderingNodeState to call buildSourceSignatures in a single useMemo; hook is shorter and signature logic is testable in isolation.

5. Canvas split

• CanvasContextMenuContent (app/canvas/CanvasContextMenuContent.tsx): context menu content (Create Node grouped by classification, Paste). CanvasPage passes onCreateNode and onPaste.
• useCanvasConnectionPath (app/canvas/useCanvasConnectionPath.ts): all connection-path state and callbacks (updating/trigger/paused/error node ids, path node ids, start/end update, add/remove paused/error). CanvasPage calls the hook with edges and passes the result into FlowContext.

Design patterns in use

Pattern	Where
Registry	nodeRegistry, sourceRenderingLogic
Builder	nodeTypeBuilder (descriptor per node type)
Pipeline	Resolve → Render → Display (rendering.ts)
Strategy	Source logic per node type; output menu per descriptor
Shared helpers	templateRefs, outputMenuHandlers, renderingUtils

Suggested next steps

1. CanvasPage: Further split optional: e.g. useCanvasGraph() for graph state + persistence + connection rules, so the page is mostly composition and layout.

2. Config types: If you add more output types (e.g. Mermaid), consider a small registry API (registerConfigType, getConfigType) instead of a single large CONFIG_TYPES array.

3. Consistent node shape in lib: templateRefs and renderingSignatures use EdgeLike / NodeLike; standardize where appropriate to reduce casts.