Render SceneCanvas on demand and add Bun usage guidance (#17)

Abse2001 · web-flow · commit 9d3044d20919 · 2026-06-08T15:18:08.000+02:00
* Refactor SceneCanvas into reusable viewer modules and camera utilities

* Render SceneCanvas on demand and add Bun usage guidance
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,111 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+// import .css files directly and it works
+import './index.css';
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
diff --git a/src/components/SceneCanvas.tsx b/src/components/SceneCanvas.tsx
@@ -91,6 +91,7 @@ export function SceneCanvas({
     null,
   )
   const sceneBoundsRef = useRef(sceneBounds)
+  const requestRenderRef = useRef<() => void>(() => {})
 
   useEffect(() => {
     sceneBoundsRef.current = sceneBounds
@@ -133,6 +134,7 @@ export function SceneCanvas({
         up,
         viewPreset,
       })
+      requestRenderRef.current()
     }
     resize()
     const updateCompass = () => {
@@ -197,26 +199,40 @@ export function SceneCanvas({
     canvas.addEventListener("pointermove", onPointerMove)
     canvas.addEventListener("pointerleave", onPointerLeave)
 
-    let animationFrame = 0
+    let animationFrame: number | null = null
     const render = () => {
-      animationFrame = window.requestAnimationFrame(render)
-      controls.update()
+      animationFrame = null
+      const controlsMoved = controls.update()
       updateCompass()
       renderer.clear()
       renderer.render(scene, camera)
       renderer.clearDepth()
       renderer.render(overlayScene, camera)
+      if (controlsMoved) {
+        requestRender()
+      }
     }
-    render()
+    const requestRender = () => {
+      if (animationFrame !== null) {
+        return
+      }
+      animationFrame = window.requestAnimationFrame(render)
+    }
+    requestRenderRef.current = requestRender
+    controls.addEventListener("change", requestRender)
+    requestRender()
 
     const observer = new ResizeObserver(resize)
     observer.observe(canvas)
 
     return () => {
-      window.cancelAnimationFrame(animationFrame)
+      if (animationFrame !== null) {
+        window.cancelAnimationFrame(animationFrame)
+      }
       observer.disconnect()
       canvas.removeEventListener("pointermove", onPointerMove)
       canvas.removeEventListener("pointerleave", onPointerLeave)
+      controls.removeEventListener("change", requestRender)
       controls.dispose()
       renderer.dispose()
       disposeScene(scene)
@@ -228,6 +244,7 @@ export function SceneCanvas({
       controlsRef.current = null
       sceneRef.current = null
       overlaySceneRef.current = null
+      requestRenderRef.current = () => {}
       setCompassPoints(null)
     }
   }, [projection, up, viewPreset])
@@ -250,6 +267,7 @@ export function SceneCanvas({
       up,
       viewPreset,
     })
+    requestRenderRef.current()
   }, [fitRequest])
 
   useEffect(() => {
@@ -267,6 +285,7 @@ export function SceneCanvas({
     for (const object of buildResult?.overlayObjects ?? []) {
       overlayScene.add(object)
     }
+    requestRenderRef.current()
   }, [buildScene, projection, up, viewPreset])
 
   return (
