chorama 0.0.0

package/content/guide/materials-and-lighting.md

@@ -0,0 +1,138 @@
+---
+title: "Materials and Lighting"
+---
+
+# Materials and Lighting
+
+This guide assumes you already have a working scene from [First Scene](/guide/first-scene).
+Here, you will add lit materials and light objects in small steps.
+
+## What You Will Add
+
+- a material choice based on visual style
+- renderer plugins required for lighting
+- ambient light for base visibility
+- one direct light source
+- a render list that includes lights
+
+## Step 1: Import Material and Light APIs
+
+```js
+import {
+  BasicMaterial,
+  LambertMaterial,
+  PhongMaterial,
+  StandardMaterial,
+  AmbientLight,
+  DirectionalLight,
+  LightPlugin
+} from "chorama";
+```
+
+Use `BasicMaterial` when you do not need scene lighting.
+Use `LambertMaterial`, `PhongMaterial`, or `StandardMaterial` when you want lights to affect the surface.
+
+## Step 2: Pick a Material Model
+
+```js
+const basic = new BasicMaterial();
+const lambert = new LambertMaterial();
+const phong = new PhongMaterial();
+const standard = new StandardMaterial({ roughness: 0.5, metallic: 0.1 });
+```
+
+Quick guidance:
+
+- `BasicMaterial`: unlit shading
+- `LambertMaterial`: diffuse lit shading
+- `PhongMaterial`: diffuse + specular highlight shading
+- `StandardMaterial`: physically-based roughness/metallic shasing
+
+For a first lit scene, start with `LambertMaterial`.
+
+## Step 3: Apply the Material to Your Mesh Object
+
+```js
+const object = new MeshMaterial3D(mesh, lambert);
+```
+The second parameter can be any of the materials shown in the previous step.
+If you keep `BasicMaterial` as the material of the object, lights will not change the object's appearance.
+
+## Step 4: Enable the Lighting Pipeline in the Renderer
+
+```js
+const renderer = new WebGLRenderer({
+  plugins: [
+    new LightPlugin(),
+    new MeshMaterialPlugin(),
+    new CameraPlugin()
+  ]
+});
+```
+
+`LightPlugin` must be present on the renderer for lit materials to respond to lights.
+
+## Step 5: Add Ambient Light
+
+```js
+const ambient = new AmbientLight();
+ambient.intensity = 0.15;
+```
+
+Ambient light gives a soft base so unlit sides are still visible.
+It is used to approximate indirect lighting for the entire scene.
+Keep this low so directional/point/spot lights can affect the object's appearance.
+
+## Step 6: Add a Directional Light
+
+```js
+const sun = new DirectionalLight();
+sun.intensity = 1.0;
+sun.transform.orientation.rotateX(-Math.PI / 4);
+sun.transform.orientation.rotateZ(-Math.PI / 4);
+```
+
+Directional light is a good first light because it is simple and predictable.
+It behaves like a distant light source with parallel rays. In this case, the light
+will point downwards onto the scene.
+
+## Step 7: Render with Object, Lights, and Camera
+
+```js
+renderer.render([object, ambient, sun, camera], device);
+```
+
+Your render list must include light objects each frame.
+If lights are missing from the list, lit materials may look black or flat.
+
+## Step 8: Animate and Keep Scene Responsive
+
+```js
+function frame() {
+  renderer.render([object, ambient, sun, camera], device);
+  requestAnimationFrame(frame);
+}
+
+requestAnimationFrame(frame);
+```
+
+Keep your existing resize handler from [First Scene](/guide/first-scene).
+Perspective scenes still require `camera.projection.aspect` updates on resize.
+
+## Switching Between Material Types
+
+You can swap material at runtime to compare look and performance:
+
+```js
+object.material = phong;
+// object.material = standard;
+// object.material = lambert;
+```
+
+## Reference Examples
+
+- [Directional Light](/examples/lights/directional)
+- [Point Light](/examples/lights/point)
+- [Spot Light](/examples/lights/spot)
+
+After this works, continue with [Textures and Assets](/guide/textures-and-assets)

package/content/guide/plugins-and-render-pipeline.md

@@ -0,0 +1,124 @@
+---
+title: "Plugins and Render Pipeline"
+---
+
+# Plugins and Render Pipeline
+
+This renderer is plugin-driven.
+Plugins discover scene objects, prepare render data, and contribute render work.
+
+## What You Will Add
+
+- a plugin stack for your renderer
+- a clear plugin order strategy
+
+## Step 1: Import Core Renderer and Plugins
+
+```js
+import {
+  WebGLRenderer,
+  CameraPlugin,
+  MeshMaterialPlugin,
+  LightPlugin,
+  ShadowPlugin,
+  SkyboxPlugin
+} from "chorama";
+```
+
+Start with the smallest plugin set your scene needs.
+Add others only when features require them.
+
+## Step 2: Build a Minimal Plugin Stack
+
+```js
+const renderer = new WebGLRenderer({
+  plugins: [
+    new MeshMaterialPlugin(),
+    new CameraPlugin()
+  ]
+});
+```
+
+This stack is enough for camera + mesh/material scenes without lighting.
+
+## Step 3: Add Lighting Support
+
+```js
+const renderer = new WebGLRenderer({
+  plugins: [
+    new LightPlugin(),
+    new MeshMaterialPlugin(),
+    new CameraPlugin()
+  ]
+});
+```
+
+`LightPlugin` provides light uniform data for lit shaders.
+Without it, lit materials may render incorrectly.
+
+## Step 4: Add Shadows and Skybox When Needed
+
+```js
+const renderer = new WebGLRenderer({
+  plugins: [
+    new ShadowPlugin(),
+    new LightPlugin(),
+    new SkyboxPlugin(),
+    new MeshMaterialPlugin(),
+    new CameraPlugin()
+  ]
+});
+```
+
+Use this fuller stack only when your scene needs shadows/skybox.
+It is heavier than the minimal stack.
+
+## Step 5: Render as Usual
+
+```js
+renderer.render(objects, device);
+```
+
+The pipeline stays behind this single call.
+You choose behavior by changing plugins and scene objects.
+
+## What Happens During `render()`
+
+High-level flow:
+
+1. Object transforms are updated through scene traversal.
+2. Each plugin preprocesses scene data.
+3. Plugins contribute views/render items.
+4. Views are sorted and rendered.
+
+This is why missing plugins often look like "nothing happens" rather than hard errors.
+
+## Plugin Roles
+
+- `CameraPlugin`: creates camera views and per-view camera data.
+- `MeshMaterialPlugin`: converts `MeshMaterial3D` objects into draw items.
+- `LightPlugin`: collects light objects and uploads light blocks.
+- `ShadowPlugin`: builds shadow passes/resources for shadow-casting lights.
+- `SkyboxPlugin`: adds skybox rendering behavior.
+
+## Create a Custom Plugin
+
+```js
+class MyPlugin extends Plugin {
+  init(renderer) {
+    // register resources, shader defines, or view fillers
+  }
+
+  preprocess(objects, device, renderer) {
+    // inspect scene, prepare data, push views/resources
+  }
+
+  getRenderItem(object, device, renderer) {
+    // return a render item for supported object types
+    return undefined;
+  }
+}
+```
+
+A custom plugin should solve one focused concern.
+Avoid mixing unrelated responsibilities in one plugin.

package/content/guide/render-targets-and-views.md

@@ -0,0 +1,147 @@
+---
+title: "Render Targets and Views"
+---
+
+# Render Targets and Views
+
+This guide assumes you already have a scene rendering from [First Scene](/guide/first-scene).
+Here, we focus on where the camera renders and how to split output.
+
+## What You Will Add
+
+- a canvas render target
+- an offscreen image render target
+- viewport/scissor based view layouts
+
+## Step 1: Import Render Target APIs
+
+```js
+import {
+  CanvasTarget,
+  ImageRenderTarget,
+  ViewRectangle,
+  Texture,
+  TextureType,
+  TextureFormat,
+  Camera
+} from "chorama";
+```
+
+Use `CanvasTarget` for on-screen output.
+Use `ImageRenderTarget` for offscreen passes.
+
+## Step 2: Create a Canvas Target (Most Common)
+
+```js
+const canvasTarget = new CanvasTarget(canvas);
+const camera = new Camera(canvasTarget);
+```
+
+This is the default path for rendering directly to the page.
+
+## Step 3: Render a Scene to the Canvas Target
+
+```js
+renderer.render([object, camera], device);
+```
+
+If your scene is blank, first confirm the camera uses the expected target.
+
+## Step 4: Create an Offscreen Image Target
+
+```js
+const imageTarget = new ImageRenderTarget({
+  width: 1024,
+  height: 1024,
+  color: [
+    new Texture({
+      type: TextureType.Texture2D,
+      format: TextureFormat.RGBA8Unorm,
+      width: 1024,
+      height: 1024
+    })
+  ],
+  internalDepthStencil: TextureFormat.Depth24PlusStencil8
+});
+```
+
+This creates a texture-backed target you can render into.
+
+## Step 5: Render Offscreen with a Dedicated Camera
+
+```js
+const offscreenCamera = new Camera(imageTarget);
+renderer.render([offscreenObject, offscreenCamera], device);
+```
+
+Use a separate camera when offscreen pass framing differs from main pass.
+
+## Step 6: Use Offscreen Output as a Texture
+
+```js
+const screenObject = new MeshMaterial3D(
+  mesh,
+  new BasicMaterial({ mainTexture: imageTarget.color[0] })
+);
+
+renderer.render([screenObject, camera], device);
+```
+
+This is the core pattern for mirrors, portals, and postprocessing chains.
+
+## Step 7: Split Canvas with Viewports
+
+Use multiple `CanvasTarget` instances on the same canvas.
+
+```js
+const leftTarget = new CanvasTarget(canvas);
+const rightTarget = new CanvasTarget(canvas);
+
+leftTarget.viewport.offset.set(0, 0);
+leftTarget.viewport.size.set(0.5, 1);
+
+rightTarget.viewport.offset.set(0.5, 0);
+rightTarget.viewport.size.set(0.5, 1);
+```
+
+Viewport values are normalized (0 to 1) relative to full canvas size.
+
+## Step 8: Bind Cameras to Each View and Render
+
+```js
+const leftCamera = new Camera(leftTarget);
+const rightCamera = new Camera(rightTarget);
+
+renderer.render([scene, leftCamera], device);
+renderer.render([scene, rightCamera], device);
+```
+
+This gives independent camera views in a single canvas.
+
+## Step 9: Use Scissor for Hard Split/Masking
+
+```js
+leftTarget.scissor = new ViewRectangle();
+rightTarget.scissor = new ViewRectangle();
+
+leftTarget.scissor.offset.set(0, 0);
+leftTarget.scissor.size.set(0.5, 1);
+
+rightTarget.scissor.offset.set(0.5, 0);
+rightTarget.scissor.size.set(0.5, 1);
+```
+
+Scissor restricts actual draw area, useful for editor layouts and split bars.
+
+## Resize Rule for Multi-View Scenes
+
+Keep canvas size and camera projection in sync on resize.
+For split views, compute aspect per view region (not full canvas).
+
+## Reference Examples
+
+- [Basic Canvas Target](/examples/rendertarget/basic_canvas)
+- [Image Target](/examples/rendertarget/image_target)
+- [Split Screen](/examples/rendertarget/split_screen)
+- [Multiple Views](/examples/rendertarget/multiple_views)
+- [Split View](/examples/rendertarget/split_view)

package/content/guide/scene-graph-and-transforms.md

@@ -0,0 +1,113 @@
+---
+title: "Scene Graph and Transforms"
+---
+
+# Scene Graph and Transforms
+
+This guide assumes you already have a running scene from [First Scene](/guide/first-scene).
+Here, we focus on parent-child relationships and transform behavior.
+
+## What You Will Add
+
+- a parent object
+- one or more child objects
+- local transforms per node
+- frame updates that propagate through hierarchy
+
+## Step 1: Import What You Need
+
+```js
+import { Object3D, MeshMaterial3D, Quaternion } from "chorama";
+```
+
+Use `Object3D` for grouping and transform hierarchy.
+Use `MeshMaterial3D` when the node should be renderable.
+
+## Step 2: Create Parent and Child Nodes
+
+```js
+const root = new Object3D();
+const parent = new MeshMaterial3D(mesh, material);
+const child = new MeshMaterial3D(mesh, material);
+```
+
+`root` is a logical container.
+`parent` and `child` are visible mesh nodes.
+
+## Step 3: Build the Hierarchy
+
+```js
+root.add(parent);
+parent.add(child);
+```
+
+Now `child` inherits `parent` transform changes.
+If parent rotates or moves, child follows automatically.
+
+## Step 4: Set Local Transforms
+
+```js
+parent.transform.position.x = 0;
+child.transform.position.x = 1;
+```
+
+`child.transform.position.x = 1` means "one unit from parent", not world origin.
+Think in local space first when building hierarchies.
+
+## Step 5: Animate the Parent
+
+```js
+const stepRotation = Quaternion.fromEuler(0.01, 0.01, 0.0);
+
+function updateScene() {
+  parent.transform.orientation.multiply(stepRotation);
+}
+```
+
+Rotating the parent creates orbital motion for the child due to inheritance.
+This is the simplest way to verify propagation is working.
+
+## Step 6: Render the Hierarchy
+
+```js
+function frame() {
+  updateScene();
+  renderer.render([root, camera], device);
+  requestAnimationFrame(frame);
+}
+
+requestAnimationFrame(frame);
+```
+
+You can render the root and let traversal include descendants.
+You do not need to pass every child separately if already attached.
+
+## Traverse the Graph for Bulk Operations
+
+```js
+root.traverseDFS((node) => {
+  // Example: debug flags, tagging, filtering, or custom updates
+  return true;
+});
+```
+
+Use traversal when you need one operation across many descendants.
+Return `true` to continue deeper traversal.
+
+## Reparent Safely
+
+```js
+const newParent = new Object3D();
+root.add(newParent);
+newParent.add(child);
+parent.remove(child);
+```
+
+Reparenting changes which transform chain affects the object.
+
+## Reference Examples
+
+- [Transform Propagation](/examples/transform/propagation)
+- [Skinning](/examples/mesh/skinning)
+
+After this works, continue with [Render Targets and Views](/guide/render-targets-and-views)

package/content/guide/textures-and-assets.md

@@ -0,0 +1,120 @@
+---
+title: "Textures and Assets"
+---
+
+This guide assumes your scene already renders from [First Scene](/guide/first-scene).
+Here, we focus only on bringing external assets into that scene.
+
+## What You Will Add
+
+- image textures
+- OBJ models
+- glTF models
+- safe runtime handling while assets stream in
+
+## Step 1: Import Loaders
+
+```js
+import { TextureLoader, OBJLoader, GLTFLoader } from "chorama";
+```
+
+Create one loader instance per asset type and reuse it.
+
+## Step 2: Load a Texture
+
+```js
+const textureLoader = new TextureLoader();
+
+const texture = textureLoader.load({
+  paths: ["/images/uv.jpg"],
+  textureSettings: { flipY: true }
+});
+```
+
+Keep paths relative to your app's static/public asset root.
+
+## Step 3: Apply the Texture to a Material
+
+```js
+const material = new BasicMaterial({
+  mainTexture: texture
+});
+
+const object = new MeshMaterial3D(mesh, material);
+```
+
+Once assigned, the texture updates automatically when loading completes.
+You can render immediately, no manual onready callback is required for basic flow.
+
+## Step 4: Load an OBJ Model
+
+```js
+const objLoader = new OBJLoader();
+
+const objRoot = objLoader.load({
+  paths: ["/models/model.obj"]
+});
+```
+
+`objRoot` is available immediately and fills as data arrives.
+You can include it in your render list right away.
+
+## Step 5: Optionally Patch Imported OBJ Materials
+
+If you want to force a change across imported meshes, use `postprocessor`.
+An example is to assign a texture to all objects in an obj file
+
+```js
+const objRoot = objLoader.load({
+  paths: ["/models/obj/pirate_girl/pirate_girl.obj"],
+  postprocessor: (asset) => {
+    asset.traverseDFS((node) => {
+      if (node instanceof MeshMaterial3D) {
+        node.material.mainTexture = texture;
+      }
+      return true;
+    });
+  }
+});
+```
+
+## Step 6: Load a glTF Scene
+
+```js
+const gltfLoader = new GLTFLoader();
+
+const sceneRoot = gltfLoader.load({
+  paths: ["/models/pirate_girl.gltf"]
+});
+```
+
+Use glTF when you want richer material data and better modern tooling support.
+
+## Step 7: Render Streaming Assets Safely
+
+```js
+function frame() {
+  renderer.render([object, objRoot, sceneRoot, camera], device);
+  requestAnimationFrame(frame);
+}
+
+requestAnimationFrame(frame);
+```
+
+Does not block rendering while waiting for loaders;
+Render continuously with placeholders and loaded data will appear as they become ready.
+
+## Path Rules That Prevent Most Loading Errors
+
+1. Use forward slashes in URLs, even on Windows.
+2. Use absolute app-root paths like `...` when possible.
+3. Keep `.gltf` sidecar files (`.bin`, textures) in expected relative locations.
+4. Confirm your dev server actually serves the asset directory.
+
+## Reference Examples
+
+- [OBJ Loader](/examples/loader/objloader)
+- [glTF Loader](/examples/loader/gltfloader)
+- [glTF Material Example](/examples/loader/gltf_material)
+
+After this works, continue with [Scene Graph and Transforms](/guide/scene-graph-and-transforms)

package/content/guide/troubleshooting.md

@@ -0,0 +1,49 @@
+---
+title: "Troubleshooting"
+---
+
+# Troubleshooting
+
+## Blank Canvas
+
+- Confirm WebGL2 is available in your browser.
+- Ensure you created `WebGLRenderDevice` with a valid canvas.
+- Ensure `renderer.render([... , camera], device)` includes a camera.
+
+```js
+const device = new WebGLRenderDevice(canvas, { depth: true });
+```
+
+## Object Is Black or Unlit
+
+- Add `LightPlugin` for lit materials.
+- Add at least one light (`AmbientLight`, `DirectionalLight`, etc.).
+- Keep `MeshMaterialPlugin` and `CameraPlugin` enabled.
+
+## Distorted Aspect Ratio
+
+Update canvas size and camera projection on resize.
+
+```js
+if (camera.projection instanceof PerspectiveProjection) {
+  camera.projection.aspect = innerWidth / innerHeight;
+}
+```
+
+## Missing Textures or Models
+
+- Use correct asset URLs under `...`.
+- Check browser network tab for 404s.
+- For cube maps, provide all six faces in the expected order.
+
+## Shadows Not Visible
+
+- Add `ShadowPlugin`.
+- Assign `light.shadow` and tune `bias`/`normalBias`.
+- Verify shadow camera bounds include your objects.
+
+Useful full examples:
+
+- [Rotating Cube](/examples/other/rotatingCube)
+- [Directional Light](/examples/lights/directional)
+- [Image Target](/examples/rendertarget/image_target)

package/env.d.ts

@@ -0,0 +1,19 @@
+declare module "*.glsl" {
+  const source: string;
+
+  export default source;
+}
+
+// Assisted by ChatGPT 5.3 Codex
+declare module "@examples/rendergraph_gui" {
+  export function addRenderGraphGuiAddon(options: {
+    gui: import("dat.gui").GUI
+    renderer: import("chorama").WebGLRenderer
+    title?: string
+    position?: { x: number; y: number }
+    width?: number
+  }): {
+    refresh: () => void
+    dispose: () => void
+  }
+}