Promote dev to main

[humanbydefinition]

Summary

Promotes the latest changes from dev to main (3 commits), modernizing framework integration guides with the official textmode.overlay.js plugin architecture, enhancing 3D and generative visual examples (Three.js, p5.js, Hydra, Webcam), providing comprehensive guidance on WebGL drawing buffer preservation and render-loop coordination, and updating TypeDoc API references.

---

Key Highlights

1. Framework Integration Modernization & Examples

All framework integration examples have been upgraded to leverage the official textmode.overlay.js plugin pattern (plugins: [OverlayPlugin] and const source = tm.overlay.setTarget(...)):

• Three.js (docs/examples/integration/threejs.md):

  • Upgraded 3D scene from a basic monochrome cube to an animated multi-ring orbital rig featuring 3 metallic standard-material torus rings with emissive highlights orbiting around a faceted icosahedron core with dual point lights and ambient illumination.
  • Configured WebGLRenderer with preserveDrawingBuffer: true, antialias: true, ACESFilmicToneMapping, and exposure tuning.
  • Implemented responsive layout handling with resizeRendererToDisplaySize(), dynamically synchronizing canvas display size and updating the camera projection matrix.
  • Decoupled animation using renderer.setAnimationLoop(animate) alongside textmode.js's independent rendering loop.

• p5.js (docs/examples/integration/p5js.md):

  • Migrated from legacy canvas overlay options to OverlayPlugin + setTarget(canvas.canvas).
  • Enhanced 3D scene from a single rotating box into an animated 7×7 matrix of pulsating boxes with multi-directional lighting (ambientLight, directionalLight, pointLight) and trigonometric distance-wave dynamics.

• Hydra Synth (docs/examples/integration/hydra-synth.md):

  • Upgraded integration to OverlayPlugin + setTarget(canvas).
  • Explicitly initialized the host canvas with { preserveDrawingBuffer: true } so Hydra's WebGL context preserves buffer contents for independent sampling by textmode.js.
  • Enhanced visual showcase to an animated, layered kaleidoscope field (osc().kaleid().modulate(noise)).

• Live Webcam (docs/examples/integration/webcam.md):

  • Upgraded webcam feed conversion to OverlayPlugin + setTarget(video).
  • Added proper lifecycle teardown on beforeunload, ensuring tm.destroy() is invoked and all active media tracks are cleanly stopped.

• Framework Integration Architecture Guide (docs/framework-integration.md):

  • Clarified WebGL drawing buffer rules: highlighted that independently rendered WebGL canvases require preserveDrawingBuffer: true or synchronous sampling before the browser discards buffer contents.
  • Expanded Single-Context (gl) integration guidance: clarified that passing gl is an advanced pattern where both renderers share the same WebGL state and presentation target, requiring state resets (renderer.resetState()) and deterministic loop coordination (t.noLoop() + t.redraw()).
  • Clarified render-loop coordination: contrasted independent animation loops (standard overlay mode) with coordinated rendering loops (shared context / unpreserved buffers).
  • Removed deprecated video.md integration include.

2. Ecosystem API Reference Update

• Regenerated and updated TypeDoc API markdown documentation across textmode.js, textmode.overlay.js, and textmode.synth.js.
• Added documentation for the new frameStart hook in TextmodePluginHookMap (() => void), executing once at the beginning of each rendered frame before any preDraw hooks.
• Updated API documentation lastModified metadata stamps.

---

Detailed Commit Log

• 04977f8 docs: enhance Three.js integration example for better responsiveness and rendering
• de8084f docs: updated framework integration examples + docs
• ce26d12 chore: update API docs

---

Verification and Testing

• API Sandpack Scanning & Validation: Passed (757 scanned, 661 live, 0 errors).
• API Example Extraction & Parsing Suite: Passed (13/13 tests passing).
• Contributor Registry Validation: Passed (8/8 tests passing).
• VitePress Static Site Build: Build completed with full bundle compilation, sitemap generation, and 0 errors.