@jiujue/react-canvas-fiber 2.0.2 → 2.0.4

package/AI_GUIDE.md

@@ -0,0 +1,142 @@
+# AI Guide for react-canvas-fiber
+
+This document provides a comprehensive guide for AI agents to understand, use, and extend the `react-canvas-fiber` project. It covers the architecture, core concepts, usage patterns, and development guidelines.
+
+## 1. Project Overview
+
+`react-canvas-fiber` is a custom React Renderer that renders React components to an HTML5 Canvas. It leverages `react-reconciler` for state management and updates, and integrates **Yoga Layout** (via `yoga-layout-prebuilt`) for a web-like Flexbox layout system.
+
+### Key Characteristics
+
+- **Renderer**: Custom Host Config implementation mapping React Virtual DOM to Canvas Scene Graph.
+- **Layout**: Full Flexbox support powered by Yoga.
+- **Rendering**: Canvas 2D API based rendering pipeline.
+- **Events**: Synthetic event system simulating DOM events (bubbling, capturing) within the Canvas.
+- **Runtime**: Supports high-performance updates using `requestAnimationFrame` loop (batched updates).
+
+## 2. Directory Structure
+
+- `src/components/`: Public React components (e.g., `<Canvas />`).
+- `src/jsx/`: JSX type definitions.
+- `src/layout/`: Layout calculation logic bridging internal nodes and Yoga.
+- `src/render/`: Painting logic (draw calls).
+- `src/runtime/`: Core runtime logic.
+  - `reconciler.ts`: `react-reconciler` HostConfig implementation.
+  - `nodes.ts`: Scene graph node definitions (`ViewNode`, `RectNode`, `TextNode`).
+  - `root.ts`: Root container managing the render loop and event dispatching.
+- `src/types/`: TypeScript type definitions.
+- `src/utils/`: Utility functions.
+
+## 3. Usage & Supported Elements
+
+### Entry Point
+
+The entry point is the `<Canvas />` component.
+
+```tsx
+import { Canvas } from 'react-canvas-fiber'
+
+function App() {
+	return (
+		<Canvas width={800} height={600} style={{ border: '1px solid black' }}>
+			<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+				<Text text="Hello World" style={{ fontSize: 20 }} color="black" />
+			</View>
+		</Canvas>
+	)
+}
+```
+
+### Intrinsic Elements
+
+#### `<View />`
+
+Container element for layout and grouping.
+
+- **Props**: `ViewProps`
+- **Key Attributes**:
+  - `style`: `YogaStyle` (flex, padding, margin, position, etc.)
+  - `background`: Background color string.
+  - `borderRadius`: Number.
+  - `scrollX`, `scrollY`: Booleans to enable scrolling.
+  - `onScroll`, `onScrollX`: Scroll callbacks.
+  - `pointerEvents`: `'auto' | 'none'`.
+  - Event handlers: `onClick`, `onPointerDown`, etc.
+
+#### `<Text />`
+
+Text rendering element.
+
+- **Props**: `TextProps`
+- **Key Attributes**:
+  - `text`: **Mandatory** string content (do not use children).
+  - `style`: `YogaStyle` (supports `fontSize`, `fontFamily`, `fontWeight`, `lineHeight`).
+  - `color`: Text color string.
+  - `maxWidth`: Max width for wrapping.
+
+#### `<Rect />`
+
+Basic rectangle shape.
+
+- **Props**: `RectProps`
+- **Key Attributes**:
+  - `style`: `YogaStyle`.
+  - `fill`: Fill color.
+  - `stroke`: Stroke color.
+  - `lineWidth`: Stroke width.
+  - `borderRadius`: Corner radius.
+
+### Style Properties (`YogaStyle`)
+
+Supports standard Flexbox properties:
+
+- Layout: `width`, `height`, `flexDirection`, `justifyContent`, `alignItems`, `flexWrap`, `flexGrow`, `padding`, `margin`.
+- Positioning: `position` ('relative' | 'absolute'), `top`, `left`, `right`, `bottom`.
+
+## 4. Internal Architecture
+
+### The Render Loop
+
+1.  **React Updates**: React commits changes via `reconciler.ts`.
+2.  **Invalidation**: `commitUpdate` triggers `container.invalidate()`.
+3.  **rAF Loop**: `requestAnimationFrame` calls `renderFrame` in `root.ts`.
+4.  **Layout Pass**:
+    - Syncs Scene Graph props to Yoga Nodes.
+    - Calculates layout via `yogaNode.calculateLayout()`.
+    - Writes computed layout (x, y, w, h) back to Scene Graph nodes.
+5.  **Draw Pass**:
+    - Clears canvas.
+    - Recursively calls `drawNode` (in `src/render/drawTree.ts`).
+
+### Event System
+
+- **Hit Testing**: `hitTest` function in `root.ts` traverses the Scene Graph (accounting for scroll offsets) to find the target node.
+- **Dispatch**: Simulates `capture` and `bubble` phases.
+- **Pointer Capture**: Supports implicit and explicit pointer capture for drag operations (e.g., scrollbars).
+
+## 5. Development & Extension
+
+### Adding a New Node Type
+
+1.  **Define Node**: Add a new type in `src/types/nodes.ts` (e.g., `ImageNode`).
+2.  **Define Props**: Add props interface in `src/types/jsx.ts`.
+3.  **Register Intrinsic**: Add to `JSX.IntrinsicElements` in `src/intrinsics.d.ts`.
+4.  **Implement Creation**: Update `createInstance` in `src/runtime/reconciler.ts` to instantiate the new node.
+5.  **Implement Drawing**: Update `drawNode` in `src/render/drawTree.ts` to handle the new node type.
+
+### Debugging
+
+- Nodes have a `debugId`.
+- Layout issues usually stem from Yoga configuration or `syncYogaTree` logic in `src/layout/layoutTree.ts`.
+- Rendering issues are handled in `src/render/drawTree.ts`.
+
+### Build & Watch
+
+- **Build**: `npm run build` (uses tsup)
+- **Watch**: `npm run dev`
+
+## 6. Common Pitfalls for AI
+
+- **Text Children**: `<Text>Content</Text>` is **NOT** supported. Must use `<Text text="Content" />`.
+- **Z-Index**: Currently determined by tree order (painting order). No explicit `zIndex` support in styles yet.
+- **Scrolling**: Requires `scrollX` or `scrollY` prop on `<View>` AND fixed dimensions (or flex constraints) to work.

package/dist/index.cjs

@@ -21,6 +21,7 @@ function createRootNode() {
     children: [],
     props: {},
     layout: { x: 0, y: 0, width: 0, height: 0 },
+    contentBounds: void 0,
     yogaNode: null,
     scrollLeft: 0,
     scrollTop: 0,
@@ -30,13 +31,14 @@ function createRootNode() {
   };
 }
 function createNode(type, props) {
-  return {
+  const node = {
     type,
     debugId: nextDebugId++,
     parent: null,
     children: [],
     props,
     layout: { x: 0, y: 0, width: 0, height: 0 },
+    contentBounds: void 0,
     yogaNode: null,
     scrollLeft: 0,
     scrollTop: 0,
@@ -44,6 +46,10 @@ function createNode(type, props) {
     scrollContentHeight: 0,
     scrollbarDrag: null
   };
+  if (type === "Image") {
+    node.imageInstance = null;
+  }
+  return node;
 }
 
 // src/render/drawTree.ts
@@ -85,6 +91,9 @@ function drawRoundedRect(ctx, x, y, w, h, r) {
   ctx.arcTo(x, y, x + w, y, radius);
   ctx.closePath();
 }
+function rectsIntersect(ax, ay, aw, ah, bx, by, bw, bh) {
+  return ax < bx + bw && ax + aw > bx && ay < by + bh && ay + ah > by;
+}
 function drawNode(state, node, offsetX, offsetY) {
   const { ctx } = state;
   const x = offsetX + node.layout.x;
@@ -120,7 +129,32 @@ function drawNode(state, node, offsetX, offsetY) {
       ctx.beginPath();
       ctx.rect(x, y, w, h);
       ctx.clip();
+      const cullPadding = 1;
+      const viewportX = x - cullPadding;
+      const viewportY = y - cullPadding;
+      const viewportW = w + cullPadding * 2;
+      const viewportH = h + cullPadding * 2;
       for (const child of node.children) {
+        const bounds = child.contentBounds ?? {
+          x: 0,
+          y: 0,
+          width: child.layout.width,
+          height: child.layout.height
+        };
+        const bx = x - scrollLeft + child.layout.x + bounds.x;
+        const by = y - scrollTop + child.layout.y + bounds.y;
+        if (!rectsIntersect(
+          viewportX,
+          viewportY,
+          viewportW,
+          viewportH,
+          bx,
+          by,
+          bounds.width,
+          bounds.height
+        )) {
+          continue;
+        }
         drawNode(state, child, x - scrollLeft, y - scrollTop);
       }
       ctx.restore();
@@ -202,6 +236,43 @@ function drawNode(state, node, offsetX, offsetY) {
     }
     ctx.restore();
   }
+  if (node.type === "Image") {
+    const { imageInstance } = node;
+    if (imageInstance && imageInstance.complete && imageInstance.naturalWidth > 0) {
+      const objectFit = node.props.objectFit || "contain";
+      const srcW = imageInstance.naturalWidth;
+      const srcH = imageInstance.naturalHeight;
+      let dstX = x;
+      let dstY = y;
+      let dstW = w;
+      let dstH = h;
+      let srcX = 0;
+      let srcY = 0;
+      let finalSrcW = srcW;
+      let finalSrcH = srcH;
+      if (objectFit === "fill") ; else if (objectFit === "contain") {
+        const ratio = Math.min(w / srcW, h / srcH);
+        dstW = srcW * ratio;
+        dstH = srcH * ratio;
+        dstX = x + (w - dstW) / 2;
+        dstY = y + (h - dstH) / 2;
+      } else if (objectFit === "cover") {
+        const ratio = Math.max(w / srcW, h / srcH);
+        const renderW = srcW * ratio;
+        const renderH = srcH * ratio;
+        srcX = (renderW - w) / 2 / ratio;
+        srcY = (renderH - h) / 2 / ratio;
+        finalSrcW = w / ratio;
+        finalSrcH = h / ratio;
+      }
+      ctx.save();
+      ctx.beginPath();
+      drawRoundedRect(ctx, x, y, w, h, 0);
+      ctx.clip();
+      ctx.drawImage(imageInstance, srcX, srcY, finalSrcW, finalSrcH, dstX, dstY, dstW, dstH);
+      ctx.restore();
+    }
+  }
   for (const child of node.children) {
     drawNode(state, child, x, y);
   }
@@ -457,6 +528,31 @@ async function layoutTree(root, width, height, measureText, defaults) {
     }
   };
   walk(root);
+  const computeSubtreeContentBounds = (node) => {
+    let minX = 0;
+    let minY = 0;
+    let maxX = node.layout.width;
+    let maxY = node.layout.height;
+    for (const child of node.children) {
+      if (child.children.length) computeSubtreeContentBounds(child);
+      const childBounds = child.contentBounds ?? {
+        x: 0,
+        y: 0,
+        width: child.layout.width,
+        height: child.layout.height
+      };
+      const bx = child.layout.x + childBounds.x;
+      const by = child.layout.y + childBounds.y;
+      const br = bx + childBounds.width;
+      const bb = by + childBounds.height;
+      minX = Math.min(minX, bx);
+      minY = Math.min(minY, by);
+      maxX = Math.max(maxX, br);
+      maxY = Math.max(maxY, bb);
+    }
+    node.contentBounds = { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+  };
+  for (const child of root.children) computeSubtreeContentBounds(child);
 }
 function freeYogaSubtree(node) {
   if (node.yogaNode) {
@@ -488,8 +584,22 @@ var hostConfig = {
   shouldSetTextContent() {
     return false;
   },
-  createInstance(type, props) {
-    return createNode(type, props);
+  createInstance(type, props, rootContainer) {
+    const node = createNode(type, props);
+    if (type === "Image" && props.src) {
+      const imgNode = node;
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = props.src;
+      if (img.dataset) {
+        img.dataset.src = props.src;
+      }
+      imgNode.imageInstance = img;
+      if (!img.complete) {
+        img.onload = () => rootContainer.invalidate();
+      }
+    }
+    return node;
   },
   createTextInstance() {
     throw new Error('Text instances are not supported. Use <Text text="..."/>.');
@@ -502,7 +612,7 @@ var hostConfig = {
     parent.children.push(child);
   },
   appendChildToContainer(container, child) {
-    child.parent = null;
+    child.parent = container.root;
     container.root.children.push(child);
     container.invalidate();
   },
@@ -513,7 +623,7 @@ var hostConfig = {
     else parent.children.push(child);
   },
   insertInContainerBefore(container, child, beforeChild) {
-    child.parent = null;
+    child.parent = container.root;
     const idx = container.root.children.indexOf(beforeChild);
     if (idx >= 0) container.root.children.splice(idx, 0, child);
     else container.root.children.push(child);
@@ -540,6 +650,39 @@ var hostConfig = {
   },
   commitUpdate(instance, updatePayload) {
     instance.props = updatePayload;
+    if (instance.type === "Image") {
+      const imgNode = instance;
+      const newSrc = instance.props.src;
+      const currentSrc = imgNode.imageInstance?.dataset?.src;
+      if (newSrc !== currentSrc) {
+        if (!newSrc) {
+          imgNode.imageInstance = null;
+        } else {
+          const img = new Image();
+          img.crossOrigin = "anonymous";
+          img.src = newSrc;
+          if (img.dataset) {
+            img.dataset.src = newSrc;
+          }
+          imgNode.imageInstance = img;
+          const invalidate = () => {
+            let p = imgNode;
+            while (p) {
+              if (p.type === "Root") {
+                p.container?.invalidate();
+                return;
+              }
+              p = p.parent;
+            }
+          };
+          if (!img.complete) {
+            img.onload = invalidate;
+          } else {
+            invalidate();
+          }
+        }
+      }
+    }
   },
   commitTextUpdate() {
   },
@@ -606,6 +749,7 @@ function createCanvasRoot(canvas, options) {
   };
   let hoverId = null;
   let selectedId = null;
+  let lastHoveredNode = null;
   const toCanvasPoint = (clientX, clientY) => {
     const rect = canvas.getBoundingClientRect();
     const scaleX = rect.width ? options.width / rect.width : 1;
@@ -634,7 +778,8 @@ function createCanvasRoot(canvas, options) {
     let current = node;
     while (current) {
       path.push(current);
-      current = current.parent;
+      const nextParent = current.parent;
+      current = nextParent && nextParent.type !== "Root" ? nextParent : null;
     }
     let absLeft = 0;
     let absTop = 0;
@@ -650,14 +795,15 @@ function createCanvasRoot(canvas, options) {
   };
   const getScrollClipRects = (node) => {
     const rects = [];
-    let current = node.parent;
+    let current = node.parent && node.parent.type !== "Root" ? node.parent : null;
     while (current) {
       if (current.type === "View") {
         const scrollX = !!current.props?.scrollX;
         const scrollY = !!current.props?.scrollY;
         if (scrollX || scrollY) rects.push(getAbsoluteRect(current));
       }
-      current = current.parent;
+      const nextParent = current.parent;
+      current = nextParent && nextParent.type !== "Root" ? nextParent : null;
     }
     return rects.reverse();
   };
@@ -687,7 +833,8 @@ function createCanvasRoot(canvas, options) {
     return out;
   };
   let frameId = null;
-  let dirty = true;
+  let dirtyLayout = true;
+  let dirtyDraw = true;
   const measureText = (text, font, maxWidth) => {
     ctx.save();
     ctx.font = font;
@@ -700,14 +847,77 @@ function createCanvasRoot(canvas, options) {
     return { width, height: Math.max(1, height) };
   };
   const invalidate = () => {
-    dirty = true;
+    dirtyLayout = true;
+    dirtyDraw = true;
     if (frameId != null) return;
     frameId = requestAnimationFrame(async () => {
       frameId = null;
-      if (!dirty) return;
-      dirty = false;
-      await layoutTree(rootNode, options.width, options.height, measureText, options);
-      drawTree(rootNode, ctx, options.dpr, options.clearColor, options);
+      if (!dirtyLayout && !dirtyDraw) return;
+      const needsLayout = dirtyLayout;
+      const needsDraw = dirtyDraw || dirtyLayout;
+      dirtyLayout = false;
+      dirtyDraw = false;
+      if (needsLayout) {
+        await layoutTree(rootNode, options.width, options.height, measureText, options);
+      }
+      if (needsDraw) {
+        drawTree(rootNode, ctx, options.dpr, options.clearColor, options);
+      }
+      const overlayHover = typeof hoverId === "number" ? findNodeById(hoverId) : null;
+      const overlaySelected = typeof selectedId === "number" ? findNodeById(selectedId) : null;
+      if (overlayHover || overlaySelected) {
+        ctx.save();
+        ctx.setTransform(options.dpr, 0, 0, options.dpr, 0, 0);
+        if (overlayHover && (!overlaySelected || overlayHover.debugId !== overlaySelected.debugId)) {
+          const r = getAbsoluteRect(overlayHover);
+          ctx.save();
+          for (const clip of getScrollClipRects(overlayHover)) {
+            ctx.beginPath();
+            ctx.rect(clip.x, clip.y, clip.width, clip.height);
+            ctx.clip();
+          }
+          ctx.fillStyle = "rgba(59,130,246,0.12)";
+          ctx.strokeStyle = "rgba(59,130,246,0.9)";
+          ctx.lineWidth = 1;
+          ctx.fillRect(r.x, r.y, r.width, r.height);
+          ctx.strokeRect(r.x + 0.5, r.y + 0.5, Math.max(0, r.width - 1), Math.max(0, r.height - 1));
+          ctx.restore();
+        }
+        if (overlaySelected) {
+          const r = getAbsoluteRect(overlaySelected);
+          ctx.save();
+          for (const clip of getScrollClipRects(overlaySelected)) {
+            ctx.beginPath();
+            ctx.rect(clip.x, clip.y, clip.width, clip.height);
+            ctx.clip();
+          }
+          ctx.fillStyle = "rgba(16,185,129,0.12)";
+          ctx.strokeStyle = "rgba(16,185,129,0.95)";
+          ctx.lineWidth = 2;
+          ctx.fillRect(r.x, r.y, r.width, r.height);
+          ctx.strokeRect(r.x + 1, r.y + 1, Math.max(0, r.width - 2), Math.max(0, r.height - 2));
+          ctx.restore();
+        }
+        ctx.restore();
+      }
+    });
+  };
+  const invalidateDrawOnly = () => {
+    dirtyDraw = true;
+    if (frameId != null) return;
+    frameId = requestAnimationFrame(async () => {
+      frameId = null;
+      if (!dirtyLayout && !dirtyDraw) return;
+      const needsLayout = dirtyLayout;
+      const needsDraw = dirtyDraw || dirtyLayout;
+      dirtyLayout = false;
+      dirtyDraw = false;
+      if (needsLayout) {
+        await layoutTree(rootNode, options.width, options.height, measureText, options);
+      }
+      if (needsDraw) {
+        drawTree(rootNode, ctx, options.dpr, options.clearColor, options);
+      }
       const overlayHover = typeof hoverId === "number" ? findNodeById(hoverId) : null;
       const overlaySelected = typeof selectedId === "number" ? findNodeById(selectedId) : null;
       if (overlayHover || overlaySelected) {
@@ -874,7 +1084,8 @@ function createCanvasRoot(canvas, options) {
     let current = target;
     while (current) {
       path.push(current);
-      current = current.parent;
+      const nextParent = current.parent;
+      current = nextParent && nextParent.type !== "Root" ? nextParent : null;
     }
     return path;
   };
@@ -976,7 +1187,7 @@ function createCanvasRoot(canvas, options) {
           capturedForScroll.scrollTop = clamped2;
           const onScroll = capturedForScroll.props?.onScroll;
           if (typeof onScroll === "function") onScroll(clamped2);
-          invalidate();
+          invalidateDrawOnly();
           return { defaultPrevented: true };
         }
         const metrics = getScrollbarMetricsX(capturedForScroll, absLeft, absTop);
@@ -989,14 +1200,14 @@ function createCanvasRoot(canvas, options) {
         capturedForScroll.scrollLeft = clamped;
         const onScrollX = capturedForScroll.props?.onScrollX;
         if (typeof onScrollX === "function") onScrollX(clamped);
-        invalidate();
+        invalidateDrawOnly();
         return { defaultPrevented: true };
       }
       if (eventType === "pointerup" || eventType === "pointercancel") {
         capturedForScroll.scrollbarDrag = null;
         pointerCapture.delete(pointerId);
         pointerDownTarget.delete(pointerId);
-        invalidate();
+        invalidateDrawOnly();
         return { defaultPrevented: true };
       }
     }
@@ -1021,6 +1232,58 @@ function createCanvasRoot(canvas, options) {
     if (eventType === "pointermove") {
       const captured = pointerCapture.get(pointerId);
       const target2 = captured ?? hitTest(init.x, init.y);
+      if (target2 !== lastHoveredNode) {
+        const prevChain = [];
+        let p = lastHoveredNode;
+        while (p) {
+          prevChain.push(p);
+          const nextParent = p.parent;
+          p = nextParent && nextParent.type !== "Root" ? nextParent : null;
+        }
+        const nextChain = [];
+        let n = target2;
+        while (n) {
+          nextChain.push(n);
+          const nextParent = n.parent;
+          n = nextParent && nextParent.type !== "Root" ? nextParent : null;
+        }
+        for (const node of prevChain) {
+          if (!nextChain.includes(node)) {
+            const handler = node.props?.onPointerLeave;
+            if (typeof handler === "function") {
+              handler({
+                type: "pointerleave",
+                ...init,
+                target: node,
+                currentTarget: node,
+                defaultPrevented: false,
+                stopPropagation: () => {
+                },
+                preventDefault: () => {
+                }
+              });
+            }
+          }
+        }
+        const enteringNodes = nextChain.filter((node) => !prevChain.includes(node)).reverse();
+        for (const node of enteringNodes) {
+          const handler = node.props?.onPointerEnter;
+          if (typeof handler === "function") {
+            handler({
+              type: "pointerenter",
+              ...init,
+              target: node,
+              currentTarget: node,
+              defaultPrevented: false,
+              stopPropagation: () => {
+              },
+              preventDefault: () => {
+              }
+            });
+          }
+        }
+        lastHoveredNode = target2;
+      }
       if (!target2) return { defaultPrevented: false };
       return dispatchOnPath(eventType, buildPath(target2), init, target2);
     }
@@ -1076,10 +1339,11 @@ function createCanvasRoot(canvas, options) {
       }
       if (remainingX === 0 && remainingY === 0) break;
     }
-    if (defaultPrevented) invalidate();
+    if (defaultPrevented) invalidateDrawOnly();
     return { defaultPrevented };
   };
   const container = { root: rootNode, invalidate, notifyCommit };
+  rootNode.container = container;
   const reconcilerRoot = createReconcilerRoot(container);
   invalidate();
   const __devtools = {
@@ -1131,7 +1395,7 @@ function createCanvasRoot(canvas, options) {
     setHighlight(next) {
       if ("hoverId" in next) hoverId = next.hoverId ?? null;
       if ("selectedId" in next) selectedId = next.selectedId ?? null;
-      invalidate();
+      invalidateDrawOnly();
     },
     subscribe(cb) {
       commitSubscribers.add(cb);
@@ -1437,8 +1701,12 @@ function Rect(props) {
 function Text(props) {
   return react.createElement("Text", props);
 }
+function Image2(props) {
+  return react.createElement("Image", props);
+}
 
 exports.Canvas = Canvas;
+exports.Image = Image2;
 exports.Rect = Rect;
 exports.Text = Text;
 exports.View = View;