@gjsify/example-dom-three-geometry-teapot 0.28.0 → 0.29.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@gjsify/example-dom-three-geometry-teapot",
-  "version": "0.28.0",
+  "version": "0.29.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",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "exports": {
     "./browser": "./src/browser/browser.ts",
@@ -26,7 +27,7 @@
     "build:assets": "gjsify copy src/browser/index.html src/browser/webgl.css src/assets dist/"
   },
   "dependencies": {
-    "@gjsify/webgl": "^0.28.0"
+    "@gjsify/webgl": "^0.29.0"
   },
   "devDependencies": {
     "@girs/adw-1": "^4.1.0",
@@ -34,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.28.0",
-    "@gjsify/adwaita-web": "^0.28.0",
-    "@gjsify/cli": "^0.28.0",
-    "@gjsify/devtools": "^0.28.0",
+    "@gjsify/adwaita-icons": "^0.29.0",
+    "@gjsify/adwaita-web": "^0.29.0",
+    "@gjsify/cli": "^0.29.0",
+    "@gjsify/devtools": "^0.29.0",
     "@gjsify/node-gi": "file:../../../packages/node-gi/node-gi",
-    "@gjsify/vite-plugin-blueprint": "^0.28.0",
+    "@gjsify/vite-plugin-blueprint": "^0.29.0",
     "@types/node": "^25.9.2",
     "@types/three": "^0.185.0",
     "http-server": "^14.1.1",

package/src/browser/browser-main.ts

@@ -0,0 +1,4 @@
+// Standalone browser entry point — runs the teapot demo fullscreen.
+import { mount } from './browser.js';
+
+mount(document.body);

package/src/browser/browser.ts

@@ -0,0 +1,284 @@
+// Browser UI for three-geometry-teapot example.
+// Mirrors the GJS/Adwaita UI from gjs/teapot-window.ts using @gjsify/adwaita-web.
+
+import '@gjsify/adwaita-web'; // registers the custom elements + self-injects the stylesheet
+import type { AdwOverlaySplitView, AdwHeaderBar } from '@gjsify/adwaita-web';
+import { mediaPlaybackPauseSymbolic, mediaPlaybackStartSymbolic } from '@gjsify/adwaita-icons/actions';
+import {
+    start,
+    TESS_VALUES,
+    SHADING_VALUES,
+    DEFAULT_TESS_INDEX,
+    DEFAULT_SHADING_INDEX,
+    type TeapotDemo,
+} from '../three-demo.js';
+
+export interface MountOptions {
+    /** Base path for loading texture assets (forwarded to three-demo). */
+    assetBase?: string;
+}
+
+/** Handle returned by `mount()` so hosts (e.g. the website slideshow) can pause and resume rendering. */
+export interface ShowcaseHandle {
+    pause(): void;
+    resume(): void;
+    readonly isPaused: boolean;
+}
+
+/** Parse a trusted literal SVG string into an SVGElement. */
+function parseSvg(svgSource: string): SVGElement {
+    const doc = new DOMParser().parseFromString(svgSource, 'image/svg+xml');
+    return doc.documentElement as unknown as SVGElement;
+}
+
+/** Replace a button's icon with a freshly-parsed copy of the given SVG source. */
+function setButtonIcon(btn: HTMLButtonElement, svgSource: string): void {
+    btn.replaceChildren(parseSvg(svgSource));
+}
+
+/**
+ * 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.
+ */
+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');
+
+    const tessRow = document.createElement('adw-combo-row');
+    tessRow.setAttribute('title', 'Tessellation Level');
+    tessRow.setAttribute('items', JSON.stringify(TESS_VALUES.map(String)));
+    tessRow.setAttribute('selected', String(DEFAULT_TESS_INDEX));
+
+    const lidRow = document.createElement('adw-switch-row');
+    lidRow.setAttribute('title', 'Display Lid');
+    lidRow.setAttribute('active', '');
+
+    const bodyRow = document.createElement('adw-switch-row');
+    bodyRow.setAttribute('title', 'Display Body');
+    bodyRow.setAttribute('active', '');
+
+    const bottomRow = document.createElement('adw-switch-row');
+    bottomRow.setAttribute('title', 'Display Bottom');
+    bottomRow.setAttribute('active', '');
+
+    const fitLidRow = document.createElement('adw-switch-row');
+    fitLidRow.setAttribute('title', 'Snug Lid');
+
+    const nonblinnRow = document.createElement('adw-switch-row');
+    nonblinnRow.setAttribute('title', 'Original Scale');
+
+    geoGroup.append(tessRow, lidRow, bodyRow, bottomRow, fitLidRow, nonblinnRow);
+
+    // Material group
+    const matGroup = document.createElement('adw-preferences-group');
+    matGroup.setAttribute('title', 'Material');
+
+    const shadingRow = document.createElement('adw-combo-row');
+    shadingRow.setAttribute('title', 'Shading');
+    shadingRow.setAttribute('items', JSON.stringify([...SHADING_VALUES]));
+    shadingRow.setAttribute('selected', String(DEFAULT_SHADING_INDEX));
+
+    matGroup.append(shadingRow);
+
+    sidebarContent.append(geoGroup, matGroup);
+
+    // GL container (content slot) — inline styles so the showcase
+    // is self-contained and works regardless of host CSS.
+    const glContainer = document.createElement('div');
+    glContainer.setAttribute('slot', 'content');
+    glContainer.id = 'gl-area-container';
+    glContainer.style.cssText = 'flex:1;position:relative;min-width:0;min-height:0';
+
+    const canvas = document.createElement('canvas');
+    canvas.id = 'webgl-canvas';
+    canvas.style.cssText = 'display:block;width:100%;height:100%;position:absolute;inset:0';
+    glContainer.append(canvas);
+
+    splitView.append(sidebarContent, glContainer);
+    win.append(headerBar, splitView);
+    container.append(win);
+
+    // Append toggle button to header bar start section AFTER DOM connection
+    const startSection = headerBar.startSection ?? headerBar.querySelector('.adw-header-bar-start');
+    if (startSection) {
+        startSection.appendChild(toggleBtn);
+    } else {
+        headerBar.prepend(toggleBtn);
+    }
+
+    const endSection = headerBar.endSection ?? headerBar.querySelector('.adw-header-bar-end');
+    if (endSection) {
+        endSection.appendChild(pauseBtn);
+    } else {
+        headerBar.append(pauseBtn);
+    }
+
+    // Sidebar toggle wiring
+    toggleBtn.addEventListener('click', () => {
+        splitView.toggleSidebar();
+        toggleBtn.classList.toggle('active', splitView.showSidebar);
+    });
+
+    splitView.addEventListener('sidebar-toggled', () => {
+        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;
+        const shouldCollapse = width < 800;
+        if (shouldCollapse === lastCollapsed) return;
+        lastCollapsed = shouldCollapse;
+        splitView.collapsed = shouldCollapse;
+        splitView.showSidebar = !shouldCollapse;
+        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)
+    canvas.width = glContainer.clientWidth;
+    canvas.height = glContainer.clientHeight;
+
+    let demo: TeapotDemo | null = null;
+    // Buffers pause() calls that arrive before the demo exists.
+    let pendingPause = false;
+    new ResizeObserver(() => {
+        const w = glContainer.clientWidth;
+        const h = glContainer.clientHeight;
+        if (w > 0 && h > 0) {
+            canvas.width = w;
+            canvas.height = h;
+            if (!demo) {
+                demo = start(canvas, { assetBase: options?.assetBase });
+                connectControls(
+                    demo,
+                    tessRow as AdwRow,
+                    shadingRow as AdwRow,
+                    lidRow as AdwRow,
+                    bodyRow as AdwRow,
+                    bottomRow as AdwRow,
+                    fitLidRow as AdwRow,
+                    nonblinnRow as AdwRow,
+                );
+                if (pendingPause) {
+                    demo.pause();
+                    pendingPause = false;
+                }
+            } else {
+                demo.render();
+            }
+        }
+    }).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';
+    }
+    pauseBtn.addEventListener('click', () => {
+        if (demo) {
+            if (demo.isPaused) demo.resume();
+            else demo.pause();
+            updatePauseButton(demo.isPaused);
+        } else {
+            pendingPause = !pendingPause;
+            updatePauseButton(pendingPause);
+        }
+    });
+
+    return {
+        get isPaused() {
+            return demo ? demo.isPaused : pendingPause;
+        },
+        pause() {
+            if (demo) {
+                demo.pause();
+                updatePauseButton(true);
+            } else {
+                pendingPause = true;
+                updatePauseButton(true);
+            }
+        },
+        resume() {
+            if (demo) {
+                demo.resume();
+                updatePauseButton(false);
+            } else {
+                pendingPause = false;
+                updatePauseButton(false);
+            }
+        },
+    };
+}
+
+// Adwaita web components expose custom properties (.selected, .active) not in HTMLElement types.
+type AdwRow = HTMLElement & Record<string, unknown>;
+
+function connectControls(
+    demo: TeapotDemo,
+    tessRow: AdwRow,
+    shadingRow: AdwRow,
+    lidRow: AdwRow,
+    bodyRow: AdwRow,
+    bottomRow: AdwRow,
+    fitLidRow: AdwRow,
+    nonblinnRow: AdwRow,
+) {
+    tessRow.addEventListener('notify::selected', () => {
+        demo.effectController.newTess = TESS_VALUES[tessRow.selected as number];
+        demo.render();
+    });
+
+    shadingRow.addEventListener('notify::selected', () => {
+        demo.effectController.newShading = SHADING_VALUES[shadingRow.selected as number];
+        demo.render();
+    });
+
+    const toggleRows: Array<[AdwRow, 'lid' | 'body' | 'bottom' | 'fitLid' | 'nonblinn']> = [
+        [lidRow, 'lid'],
+        [bodyRow, 'body'],
+        [bottomRow, 'bottom'],
+        [fitLidRow, 'fitLid'],
+        [nonblinnRow, 'nonblinn'],
+    ];
+    for (const [row, key] of toggleRows) {
+        row.addEventListener('notify::active', () => {
+            demo.effectController[key] = Boolean(row.active);
+            demo.render();
+        });
+    }
+}

package/src/browser/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Three.js Teapot — gjsify</title>
+  <link rel="stylesheet" href="./webgl.css" type="text/css" />
+  <link rel="stylesheet" href="./browser.css" type="text/css" />
+  <script src="./browser.js" type="module" defer></script>
+</head>
+<body></body>
+</html>

package/src/browser/webgl.css

@@ -0,0 +1,53 @@
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+html, body {
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: #2d2d2d;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+adw-window {
+    max-width: 100%;
+    max-height: 100%;
+}
+
+.adw-window-body {
+    display: flex;
+    flex: 1;
+    min-height: 0;
+}
+
+.adw-sidebar {
+    width: 320px;
+    flex-shrink: 0;
+    overflow-y: auto;
+}
+
+.adw-sidebar-content {
+    padding: 12px;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+}
+
+#gl-area-container {
+    flex: 1;
+    position: relative;
+    min-width: 0;
+}
+
+#gl-area-container canvas {
+    display: block;
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    inset: 0;
+}

package/src/gjs/gjs.ts

@@ -0,0 +1,27 @@
+// GJS/Adwaita entry point for three-geometry-teapot example.
+// Ported from refs/three/examples/webgl_geometry_teapot.html
+
+import Adw from 'gi://Adw?version=1';
+import Gio from 'gi://Gio?version=2.0';
+
+import { installDevtools } from '@gjsify/devtools';
+import { TeapotWindow } from './teapot-window.js';
+
+const app = new Adw.Application({
+    application_id: 'gjsify.examples.three-geometry-teapot',
+    flags: Gio.ApplicationFlags.FLAGS_NONE,
+});
+
+app.connect('startup', () => installDevtools(app));
+
+app.connect('activate', () => {
+    let win = app.get_active_window();
+    if (!win) win = new TeapotWindow(app);
+    win.present();
+});
+
+// runAsync (NOT the sync run()): defers the blocking main loop to a macrotask so
+// the synchronous view load doesn't hang on its spinner, and it is the required
+// lifecycle on the `--app node` reverse bridge (a sync run() deadlocks there) as
+// well as the GJS-recommended one (Gio.Application.runAsync). Runs on all runtimes.
+await app.runAsync([]);

package/src/gjs/teapot-window.blp

@@ -0,0 +1,111 @@
+using Gtk 4.0;
+using Adw 1;
+
+template $TeapotWindow: Adw.ApplicationWindow {
+  default-width: 1100;
+  default-height: 700;
+  title: "Three.js Teapot";
+
+  [breakpoint]
+  Adw.Breakpoint {
+    condition ("max-width: 799sp")
+    setters {
+      splitView.collapsed: true;
+      splitView.show-sidebar: false;
+    }
+  }
+
+  [breakpoint]
+  Adw.Breakpoint {
+    condition ("min-width: 800sp")
+    setters {
+      splitView.collapsed: false;
+      splitView.show-sidebar: true;
+    }
+  }
+
+  content: Gtk.Box {
+    orientation: vertical;
+
+    Adw.HeaderBar {
+      [start]
+      ToggleButton sidebarToggleButton {
+        icon-name: "sidebar-show-symbolic";
+        tooltip-text: "Toggle Sidebar";
+        active: bind splitView.show-sidebar;
+      }
+
+      [end]
+      Gtk.Button pauseButton {
+        icon-name: "media-playback-pause-symbolic";
+        tooltip-text: "Pause Rendering";
+      }
+    }
+
+    Adw.OverlaySplitView splitView {
+      sidebar-width-fraction: 0.30;
+      min-sidebar-width: 280;
+      max-sidebar-width: 400;
+      show-sidebar: bind sidebarToggleButton.active;
+
+      sidebar: Gtk.ScrolledWindow {
+        hscrollbar-policy: never;
+
+        Gtk.Box {
+          orientation: vertical;
+          spacing: 12;
+          margin-top: 12;
+          margin-bottom: 12;
+          margin-start: 12;
+          margin-end: 12;
+
+          Adw.PreferencesGroup {
+            title: "Geometry";
+
+            Adw.ComboRow tessRow {
+              title: "Tessellation Level";
+            }
+
+            Adw.SwitchRow lidRow {
+              title: "Display Lid";
+              active: true;
+            }
+
+            Adw.SwitchRow bodyRow {
+              title: "Display Body";
+              active: true;
+            }
+
+            Adw.SwitchRow bottomRow {
+              title: "Display Bottom";
+              active: true;
+            }
+
+            Adw.SwitchRow fitLidRow {
+              title: "Snug Lid";
+              active: false;
+            }
+
+            Adw.SwitchRow nonblinnRow {
+              title: "Original Scale";
+              active: false;
+            }
+          }
+
+          Adw.PreferencesGroup {
+            title: "Material";
+
+            Adw.ComboRow shadingRow {
+              title: "Shading";
+            }
+          }
+        }
+      };
+
+      content: Gtk.Box glAreaContainer {
+        hexpand: true;
+        vexpand: true;
+      };
+    }
+  };
+}

package/src/gjs/teapot-window.ts

@@ -0,0 +1,145 @@
+// Adwaita window for the three.js teapot example.
+// Uses a Blueprint template for the UI layout and WebGLBridge for WebGL.
+
+import GObject from 'gi://GObject?version=2.0';
+import Gtk from 'gi://Gtk?version=4.0';
+import Adw from 'gi://Adw?version=1';
+import { WebGLBridge } from '@gjsify/webgl';
+import {
+    start,
+    TESS_VALUES,
+    SHADING_VALUES,
+    DEFAULT_TESS_INDEX,
+    DEFAULT_SHADING_INDEX,
+    type TeapotDemo,
+} from '../three-demo.js';
+import Template from './teapot-window.blp';
+
+export class TeapotWindow extends Adw.ApplicationWindow {
+    declare private _glAreaContainer: Gtk.Box;
+    declare private _tessRow: Adw.ComboRow;
+    declare private _lidRow: Adw.SwitchRow;
+    declare private _bodyRow: Adw.SwitchRow;
+    declare private _bottomRow: Adw.SwitchRow;
+    declare private _fitLidRow: Adw.SwitchRow;
+    declare private _nonblinnRow: Adw.SwitchRow;
+    declare private _shadingRow: Adw.ComboRow;
+    declare private _splitView: Adw.OverlaySplitView;
+    declare private _sidebarToggleButton: Gtk.ToggleButton;
+    declare private _pauseButton: Gtk.Button;
+
+    /** Live demo reference; set once the WebGLBridge is ready. */
+    private _demo: TeapotDemo | null = null;
+
+    static {
+        GObject.registerClass(
+            {
+                GTypeName: 'TeapotWindow',
+                Template,
+                InternalChildren: [
+                    'glAreaContainer',
+                    'tessRow',
+                    'lidRow',
+                    'bodyRow',
+                    'bottomRow',
+                    'fitLidRow',
+                    'nonblinnRow',
+                    'shadingRow',
+                    'splitView',
+                    'sidebarToggleButton',
+                    'pauseButton',
+                ],
+            },
+            this,
+        );
+    }
+
+    constructor(application: Adw.Application) {
+        super({ application });
+
+        // Set up ComboRow models
+        this._tessRow.set_model(Gtk.StringList.new(TESS_VALUES.map(String)));
+        this._tessRow.set_selected(DEFAULT_TESS_INDEX);
+
+        this._shadingRow.set_model(Gtk.StringList.new([...SHADING_VALUES]));
+        this._shadingRow.set_selected(DEFAULT_SHADING_INDEX);
+
+        // Create and insert WebGL widget
+        const glArea = new WebGLBridge();
+        glArea.set_hexpand(true);
+        glArea.set_vexpand(true);
+        glArea.installGlobals();
+        this._glAreaContainer.append(glArea);
+
+        // Expose GL area dimensions as innerWidth/innerHeight for three.js
+        Object.defineProperty(globalThis, 'innerWidth', {
+            get: () => glArea.get_allocated_width(),
+            configurable: true,
+        });
+        Object.defineProperty(globalThis, 'innerHeight', {
+            get: () => glArea.get_allocated_height(),
+            configurable: true,
+        });
+
+        // Initialize three.js when GL context is ready
+        glArea.onReady((canvas) => {
+            glArea.grab_focus();
+            const ctx = glArea.get_context()!;
+            print(`Context version: OpenGL${ctx.get_use_es() ? ' ES' : ''} ${ctx.get_version().join('.')}`);
+
+            this._demo = start(canvas);
+            this.connectControls(this._demo);
+        });
+
+        // Pause/Resume button — toggles demo state and swaps the icon.
+        this._pauseButton.connect('clicked', () => {
+            if (!this._demo) return;
+            if (this._demo.isPaused) {
+                this._demo.resume();
+                this._pauseButton.set_icon_name('media-playback-pause-symbolic');
+                this._pauseButton.set_tooltip_text('Pause Rendering');
+            } else {
+                this._demo.pause();
+                this._pauseButton.set_icon_name('media-playback-start-symbolic');
+                this._pauseButton.set_tooltip_text('Resume Rendering');
+            }
+        });
+    }
+
+    private connectControls(demo: TeapotDemo) {
+        this._tessRow.connect('notify::selected', () => {
+            demo.effectController.newTess = TESS_VALUES[this._tessRow.selected];
+            demo.render();
+        });
+
+        this._shadingRow.connect('notify::selected', () => {
+            demo.effectController.newShading = SHADING_VALUES[this._shadingRow.selected];
+            demo.render();
+        });
+
+        this._lidRow.connect('notify::active', () => {
+            demo.effectController.lid = this._lidRow.active;
+            demo.render();
+        });
+
+        this._bodyRow.connect('notify::active', () => {
+            demo.effectController.body = this._bodyRow.active;
+            demo.render();
+        });
+
+        this._bottomRow.connect('notify::active', () => {
+            demo.effectController.bottom = this._bottomRow.active;
+            demo.render();
+        });
+
+        this._fitLidRow.connect('notify::active', () => {
+            demo.effectController.fitLid = this._fitLidRow.active;
+            demo.render();
+        });
+
+        this._nonblinnRow.connect('notify::active', () => {
+            demo.effectController.nonblinn = this._nonblinnRow.active;
+            demo.render();
+        });
+    }
+}

package/src/three-demo.ts

@@ -0,0 +1,242 @@
+// Ported from refs/three/examples/webgl_geometry_teapot.html
+// Original: MIT license, three.js contributors
+// Reimplemented as platform-agnostic module for GJS and browser targets.
+
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { TeapotGeometry } from 'three/addons/geometries/TeapotGeometry.js';
+
+export type ShadingMode = 'wireframe' | 'flat' | 'smooth' | 'glossy' | 'textured' | 'reflective';
+
+export const TESS_VALUES = [2, 3, 4, 5, 6, 8, 10, 15, 20, 30, 40, 50] as const;
+export const SHADING_VALUES: readonly ShadingMode[] = [
+    'wireframe',
+    'flat',
+    'smooth',
+    'glossy',
+    'textured',
+    'reflective',
+];
+export const DEFAULT_TESS_INDEX = 7; // "15"
+export const DEFAULT_SHADING_INDEX = 3; // "glossy"
+
+export interface TeapotEffectController {
+    newTess: number;
+    lid: boolean;
+    body: boolean;
+    bottom: boolean;
+    fitLid: boolean;
+    nonblinn: boolean;
+    newShading: ShadingMode;
+}
+
+export interface TeapotDemo {
+    readonly effectController: TeapotEffectController;
+    /** Call after changing effectController properties to schedule a re-render. */
+    render(): void;
+    /** Suppress future render() calls until `resume()` is called. */
+    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;
+}
+
+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.)
+    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);
+
+    const light = new THREE.DirectionalLight(0xffffff, 2.0);
+    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 }),
+        smooth: new THREE.MeshLambertMaterial({ side: THREE.DoubleSide }),
+        glossy: new THREE.MeshPhongMaterial({
+            color: 0xc0c0c0,
+            specular: 0x404040,
+            shininess: 300,
+            side: THREE.DoubleSide,
+        }),
+        textured: new THREE.MeshPhongMaterial({ map: textureMap, side: THREE.DoubleSide }),
+        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()
+    const effectController: TeapotEffectController = {
+        newTess: 15,
+        lid: true,
+        body: true,
+        bottom: true,
+        fitLid: false,
+        nonblinn: false,
+        newShading: 'glossy',
+    };
+
+    // Track last-rendered state for change detection
+    let tess = -1; // force initial creation
+    let bBottom: boolean;
+    let bLid: boolean;
+    let bBody: boolean;
+    let bFitLid: boolean;
+    let bNonBlinn: boolean;
+    let shading: ShadingMode;
+    let teapot: THREE.Mesh | undefined;
+
+    function createNewTeapot() {
+        if (teapot !== undefined) {
+            teapot.geometry.dispose();
+            scene.remove(teapot);
+        }
+
+        const geometry = new TeapotGeometry(
+            TEAPOT_SIZE,
+            tess,
+            effectController.bottom,
+            effectController.lid,
+            effectController.body,
+            effectController.fitLid,
+            !effectController.nonblinn,
+        );
+
+        teapot = new THREE.Mesh(geometry, materials[shading]);
+        scene.add(teapot);
+    }
+
+    function doRender() {
+        // Check if parameters changed
+        if (
+            effectController.newTess !== tess ||
+            effectController.bottom !== bBottom ||
+            effectController.lid !== bLid ||
+            effectController.body !== bBody ||
+            effectController.fitLid !== bFitLid ||
+            effectController.nonblinn !== bNonBlinn ||
+            effectController.newShading !== shading
+        ) {
+            tess = effectController.newTess;
+            bBottom = effectController.bottom;
+            bLid = effectController.lid;
+            bBody = effectController.body;
+            bFitLid = effectController.fitLid;
+            bNonBlinn = effectController.nonblinn;
+            shading = effectController.newShading;
+
+            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
+        const w = canvas.width;
+        const h = canvas.height;
+        if (prevW !== w || prevH !== h) {
+            prevW = w;
+            prevH = h;
+            renderer.setSize(w, h, false);
+            camera.aspect = w / h;
+            camera.updateProjectionMatrix();
+        }
+
+        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.
+    let renderPending = false;
+    let paused = false;
+    // Set when render() is called while paused, so resume() can flush it.
+    let deferredRender = false;
+    function render() {
+        if (paused) {
+            deferredRender = true;
+            return;
+        }
+        if (renderPending) return;
+        renderPending = true;
+        requestAnimationFrame(() => {
+            renderPending = false;
+            doRender();
+        });
+    }
+
+    // Initial render
+    render();
+
+    return {
+        effectController,
+        render,
+        get isPaused() {
+            return paused;
+        },
+        pause() {
+            if (paused) return;
+            paused = true;
+        },
+        resume() {
+            if (!paused) return;
+            paused = false;
+            if (deferredRender) {
+                deferredRender = false;
+                render();
+            }
+        },
+    };
+}