@gjsify/example-dom-three-geometry-teapot 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/example-dom-three-geometry-teapot",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Three.js geometry teapot example ported from refs/three/examples/webgl_geometry_teapot.html with Adwaita controls",
   "main": "dist/gjs.js",
   "type": "module",
@@ -27,7 +27,7 @@
     "build:assets": "gjsify copy src/browser/index.html src/browser/webgl.css src/assets dist/"
   },
   "dependencies": {
-    "@gjsify/webgl": "^0.36.0"
+    "@gjsify/webgl": "^0.37.0"
   },
   "devDependencies": {
     "@girs/adw-1": "^4.1.0",
@@ -35,12 +35,12 @@
     "@girs/gjs": "^4.1.0",
     "@girs/gobject-2.0": "^4.1.0",
     "@girs/gtk-4.0": "^4.1.0",
-    "@gjsify/adwaita-icons": "^0.36.0",
-    "@gjsify/adwaita-web": "^0.36.0",
-    "@gjsify/cli": "^0.36.0",
-    "@gjsify/devtools": "^0.36.0",
+    "@gjsify/adwaita-icons": "^0.37.0",
+    "@gjsify/adwaita-web": "^0.37.0",
+    "@gjsify/cli": "^0.37.0",
+    "@gjsify/devtools": "^0.37.0",
     "@gjsify/node-gi": "file:../../../packages/node-gi/node-gi",
-    "@gjsify/vite-plugin-blueprint": "^0.36.0",
+    "@gjsify/vite-plugin-blueprint": "^0.37.0",
     "@types/node": "^25.9.2",
     "@types/three": "^0.185.0",
     "http-server": "^14.1.1",

package/src/browser/browser.ts

@@ -37,43 +37,35 @@ function setButtonIcon(btn: HTMLButtonElement, svgSource: string): void {
 }
 
 /**
- * Create the Adwaita teapot UI and mount it into the given container.
- * The container receives an adw-window with sidebar controls and a WebGL canvas.
+ * Mounts an adw-window with sidebar controls and a WebGL canvas into `container`.
  */
 export function mount(container: HTMLElement, options?: MountOptions): ShowcaseHandle {
-    // Build UI — mirrors GJS Blueprint structure
     const win = document.createElement('adw-window');
     win.setAttribute('width', '1100');
     win.setAttribute('height', '700');
 
-    // Header bar (toggle button added after DOM connection below)
     const headerBar = document.createElement('adw-header-bar') as AdwHeaderBar;
     headerBar.setAttribute('title', 'Three.js Teapot');
 
-    // Sidebar toggle button
     const toggleBtn = document.createElement('button');
     toggleBtn.className = 'adw-header-btn adw-sidebar-toggle-icon active';
     toggleBtn.title = 'Toggle Sidebar';
 
-    // Pause/Resume rendering button — placed in header bar end section.
     const pauseBtn = document.createElement('button');
     pauseBtn.className = 'adw-header-btn';
     pauseBtn.title = 'Pause Rendering';
     setButtonIcon(pauseBtn, mediaPlaybackPauseSymbolic);
 
-    // OverlaySplitView — sidebar + content
     const splitView = document.createElement('adw-overlay-split-view') as AdwOverlaySplitView;
     splitView.setAttribute('min-sidebar-width', '280');
     splitView.setAttribute('max-sidebar-width', '400');
     splitView.setAttribute('sidebar-width-fraction', '0.30');
     splitView.setAttribute('show-sidebar', '');
 
-    // Sidebar content
     const sidebarContent = document.createElement('div');
     sidebarContent.setAttribute('slot', 'sidebar');
     sidebarContent.className = 'adw-sidebar-content';
 
-    // Geometry group
     const geoGroup = document.createElement('adw-preferences-group');
     geoGroup.setAttribute('title', 'Geometry');
 
@@ -102,7 +94,6 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
 
     geoGroup.append(tessRow, lidRow, bodyRow, bottomRow, fitLidRow, nonblinnRow);
 
-    // Material group
     const matGroup = document.createElement('adw-preferences-group');
     matGroup.setAttribute('title', 'Material');
 
@@ -115,8 +106,7 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
 
     sidebarContent.append(geoGroup, matGroup);
 
-    // GL container (content slot) — inline styles so the showcase
-    // is self-contained and works regardless of host CSS.
+    // Inline styles so the layout holds in the website embed too, which loads no showcase CSS.
     const glContainer = document.createElement('div');
     glContainer.setAttribute('slot', 'content');
     glContainer.id = 'gl-area-container';
@@ -131,7 +121,7 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
     win.append(headerBar, splitView);
     container.append(win);
 
-    // Append toggle button to header bar start section AFTER DOM connection
+    // AFTER DOM connection: connectedCallback is what creates the header-bar-start wrapper.
     const startSection = headerBar.startSection ?? headerBar.querySelector('.adw-header-bar-start');
     if (startSection) {
         startSection.appendChild(toggleBtn);
@@ -146,7 +136,6 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
         headerBar.append(pauseBtn);
     }
 
-    // Sidebar toggle wiring
     toggleBtn.addEventListener('click', () => {
         splitView.toggleSidebar();
         toggleBtn.classList.toggle('active', splitView.showSidebar);
@@ -156,7 +145,6 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
         toggleBtn.classList.toggle('active', splitView.showSidebar);
     });
 
-    // Responsive breakpoints — mirror GJS Adw.Breakpoint behavior
     let lastCollapsed: boolean | null = null;
     new ResizeObserver(([entry]) => {
         const width = entry.contentRect.width;
@@ -168,8 +156,8 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
         toggleBtn.classList.toggle('active', !shouldCollapse);
     }).observe(win);
 
-    // Sync canvas size with container and re-render on resize
-    // (needed when slide becomes visible after being display:none)
+    // Also covers a slide becoming visible after `display: none`, which reports a size for the first
+    // time.
     canvas.width = glContainer.clientWidth;
     canvas.height = glContainer.clientHeight;
 
@@ -204,7 +192,6 @@ export function mount(container: HTMLElement, options?: MountOptions): ShowcaseH
         }
     }).observe(glContainer);
 
-    // Pause button wiring — toggles demo state and swaps the icon.
     function updatePauseButton(paused: boolean): void {
         setButtonIcon(pauseBtn, paused ? mediaPlaybackStartSymbolic : mediaPlaybackPauseSymbolic);
         pauseBtn.title = paused ? 'Resume Rendering' : 'Pause Rendering';

package/src/three-demo.ts

@@ -32,18 +32,15 @@ export interface TeapotEffectController {
 
 export interface TeapotDemo {
     readonly effectController: TeapotEffectController;
-    /** Call after changing effectController properties to schedule a re-render. */
+    /** Call after mutating effectController to schedule a re-render. */
     render(): void;
-    /** Suppress future render() calls until `resume()` is called. */
+    /** Suppresses render() until `resume()`, which then flushes anything queued meanwhile. */
     pause(): void;
-    /** Flush any pending render queued during pause. */
     resume(): void;
-    /** Current paused state. */
     readonly isPaused: boolean;
 }
 
 export interface StartOptions {
-    /** Base path for loading texture assets (default: './'). */
     assetBase?: string;
 }
 
@@ -52,29 +49,23 @@ const TEAPOT_SIZE = 300;
 export function start(canvas: HTMLCanvasElement, options?: StartOptions): TeapotDemo {
     const assetBase = options?.assetBase ?? './';
 
-    // Renderer
     // oxlint-disable-next-line typescript/no-explicit-any -- THREE.WebGLRenderer canvas option expects OffscreenCanvas; GJS canvas type is incompatible
     const renderer = new THREE.WebGLRenderer({ canvas: canvas as any, antialias: true });
     // Pass updateStyle=false: the canvas CSS width/height are managed by the
     // host container (flex layout). We only want to update the drawing buffer.
     renderer.setSize(canvas.width, canvas.height, false);
-    // Track the size we last handed the renderer. `renderer.domElement` IS this
-    // canvas, so the obvious `renderer.domElement.width !== w` compares a value
-    // with itself and is never true — the resize branch below would be dead and
-    // the camera aspect would stay frozen at the first allocation. (The pixel
-    // post-processing showcase already carries this shape; keep the two aligned.)
+    // The last size handed to the renderer, tracked separately because `renderer.domElement` IS this
+    // canvas: the obvious `renderer.domElement.width !== w` compares a value with itself, leaving the
+    // resize branch dead and the camera aspect frozen at the first allocation.
     let prevW = canvas.width;
     let prevH = canvas.height;
 
-    // Camera
     const camera = new THREE.PerspectiveCamera(45, canvas.width / canvas.height, 1, 80000);
     camera.position.set(-600, 550, 1300);
 
-    // Scene
     const scene = new THREE.Scene();
     scene.background = new THREE.Color(0xaaaaaa);
 
-    // Lights
     const ambientLight = new THREE.AmbientLight(0x7c7c7c, 2.0);
     scene.add(ambientLight);
 
@@ -82,18 +73,15 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
     light.position.set(0.32, 0.39, 0.7);
     scene.add(light);
 
-    // Texture map
     const textureMap = new THREE.TextureLoader().load(`${assetBase}assets/uv_grid_opengl.jpg`);
     textureMap.wrapS = textureMap.wrapT = THREE.RepeatWrapping;
     textureMap.anisotropy = 16;
     textureMap.colorSpace = THREE.SRGBColorSpace;
 
-    // Reflection map (cubemap)
     const path = `${assetBase}assets/pisa/`;
     const urls = ['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png'];
     const textureCube = new THREE.CubeTextureLoader().setPath(path).load(urls);
 
-    // Materials
     const materials: Record<ShadingMode, THREE.Material> = {
         wireframe: new THREE.MeshBasicMaterial({ wireframe: true }),
         flat: new THREE.MeshPhongMaterial({ specular: 0x000000, flatShading: true, side: THREE.DoubleSide }),
@@ -108,12 +96,11 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
         reflective: new THREE.MeshPhongMaterial({ envMap: textureCube, side: THREE.DoubleSide }),
     };
 
-    // OrbitControls
     // oxlint-disable-next-line typescript/no-explicit-any -- OrbitControls domElement type is HTMLElement; GJS canvas type is incompatible
     const cameraControls = new OrbitControls(camera, canvas as any);
     cameraControls.addEventListener('change', render);
 
-    // Effect controller — external GUI mutates this, then calls render()
+    // An external GUI mutates this, then calls render().
     const effectController: TeapotEffectController = {
         newTess: 15,
         lid: true,
@@ -124,7 +111,6 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
         newShading: 'glossy',
     };
 
-    // Track last-rendered state for change detection
     let tess = -1; // force initial creation
     let bBottom: boolean;
     let bLid: boolean;
@@ -155,7 +141,6 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
     }
 
     function doRender() {
-        // Check if parameters changed
         if (
             effectController.newTess !== tess ||
             effectController.bottom !== bBottom ||
@@ -176,14 +161,13 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
             createNewTeapot();
         }
 
-        // Reflective mode uses cubemap as background
         if (shading === 'reflective') {
             scene.background = textureCube;
         } else {
             scene.background = null;
         }
 
-        // Handle resize — canvas.width/height are the GTK-owned drawing buffer
+        // canvas.width/height are the host-owned drawing buffer.
         const w = canvas.width;
         const h = canvas.height;
         if (prevW !== w || prevH !== h) {
@@ -197,9 +181,8 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
         renderer.render(scene, camera);
     }
 
-    // Render scheduling: coalesce multiple render requests into one frame.
-    // In GTK, the GL context is only current inside the frame pipeline (rAF),
-    // so direct calls from signal handlers would fail.
+    // Render requests coalesce into one frame, and must go through rAF: under GTK the GL context is
+    // only current inside the frame pipeline, so a direct call from a signal handler would fail.
     let renderPending = false;
     let paused = false;
     // Set when render() is called while paused, so resume() can flush it.
@@ -217,7 +200,6 @@ export function start(canvas: HTMLCanvasElement, options?: StartOptions): Teapot
         });
     }
 
-    // Initial render
     render();
 
     return {