refactoring

frontend/docs/IMPROVEMENTS.md

@@ -0,0 +1,47 @@
+# 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.
+
+## 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** (~950 lines): Split into smaller units, e.g.:
+   - `useCanvasGraph()` or similar for graph state and connection rules.
+   - A dedicated component for the context menu (add node, paste, etc.).
+   - Keeps CanvasPage as composition + layout.
+
+2. **useRenderingNodeState**: Consider extracting:
+   - Signature building (config/edges/variables/functions/data) into a pure function or small module, e.g. `buildSourceSignatures(nodes, edges, id, incomingIds, getConfigContent)`.
+   - Makes the hook easier to read and the logic testable in isolation.
+
+3. **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, so extensions can register without editing the core list.
+
+4. **Consistent node shape in lib**: `templateRefs` uses `EdgeLike` / `NodeLike`; other graph code uses inline `{ source, target }` or `nodes as ...`. You could standardize on the same minimal types where appropriate to reduce casts.