first commit

docs/media/audio/audio-core/src/render/render.md

@@ -0,0 +1,66 @@
+# Render
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The render module bridges the compiled plan produced by `PlanEngine` and the paged sample storage of an `AudioDocument`. It exposes a single function, `renderBlock`, which materialises a contiguous chunk of audio samples into planar `Float32Array` buffers, respecting the bounds of the compiled plan.
+
+## Features
+
+- **Plan-aware rendering** — Reads samples through the document’s page structure while honouring the total length declared by a `CompiledPlan`.
+- **Automatic bounds clamping** — Requests that exceed the plan length are silently truncated rather than throwing.
+- **Zero-allocation empty blocks** — When the requested offset is at or beyond the plan end, the function returns empty arrays without allocating sample memory.
+- **Delegated page reads** — Internally reuses `readPages` so that page traversal, overlap handling, and channel copying remain consistent with the rest of the package.
+
+## Usage: Basic Example
+
+```ts
+import { renderBlock } from "@suaveplan/audio-core";
+
+// Render 2048 samples starting at sample 0.
+const block = renderBlock(document, plan, 0, 2048);
+// block is Float32Array[] with one array per channel.
+```
+
+## Usage: Advanced Example
+
+```ts
+import { renderBlock } from "@suaveplan/audio-core";
+
+// Render the final partial block, which may be shorter than BLOCK_SIZE.
+const blockSize = 1024;
+const offset = plan.totalLen - blockSize;
+const block = renderBlock(document, plan, offset, blockSize);
+
+console.log(block[0].length); // <= blockSize
+```
+
+## API Reference
+
+### `renderBlock(doc, plan, offset, duration): Float32Array[]`
+
+Reads a contiguous range of samples from the document, clamped to the plan’s total length.
+
+**Parameters:**
+
+- `doc` — `AudioDocument` containing the paged source data.
+- `plan` — `CompiledPlan` that defines `totalLen`, the authoritative sample count for the rendered output.
+- `offset` — Start sample index.
+- `duration` — Requested number of samples.
+
+**Returns:**
+
+- `Float32Array[]` with one array per channel. Each array’s length equals `min(duration, plan.totalLen - offset)`. If `offset` is at or beyond `plan.totalLen`, each array has length `0`.
+
+**Throws:**
+
+- Does not throw for out-of-range offsets; instead returns empty buffers. Underlying page-read errors are possible if the document contains malformed pages.
+
+## Implementation Notes
+
+- `renderBlock` delegates directly to `readPages` after computing `count = Math.min(duration, plan.totalLen - offset)`. This centralises page-walking logic in a single module and avoids duplicating overlap-handling code.
+- The function does not interact with `ProcessPipeline`; it is intended for raw sample extraction. If you need to apply edits or effects, use `AudioDocument.prototype.stream` or `createPlanTransformStream` instead.
+- Because the return value is always a new array of `Float32Array` instances, repeated small calls to `renderBlock` will allocate frequently. For low-latency or real-time paths, prefer streaming APIs that reuse block buffers.