fourJS guides

The prose half of the §93 Documentation Plan. §93 lists nineteen documentation items; the first six — installation and quick start, and the five worked scenes — are carried by the root README.md and the example apps:

This table listed the four placeholder rows as though they were written until 2026-08-05. The first 3D scene's row itself read as an empty directory until 2026-08-07, when that example was written. The remaining three §93 names were .gitkeep until 2026-09-06, when each gained a real main.ts that imports its stand-in — dated in docs/AUDIT-120.md as S-8, now closed. They are not independently authored scenes; they exist so the §93 names resolve to a buildable site.

The remaining thirteen items are these guides. Read them in this order — each assumes the ones above it:

1. The scene graph and transforms — nodes, groups, components (§6a), events (§6b), and the transform system (§7).
2. Cameras and coordinate conversion — §47 cameras, §48 viewports, and the full pixel → NDC → world → pick path (§71/§72), including pointer input, dragging, hitTestMode = "gpu", registerPickingPipeline / createPickingService, and createPickProvider / PointerInput.pickProvider. (WebGL 2's other registration seams — registerShadowPipeline, registerEffectPipeline, registerParticlePipeline, registerStandardPipeline, 2026-09-11 — are listed in materials and the render graph.)
3. Fixed-step simulation — §9 time domains, the §10 accumulator, §39 system ordering, and §43 interpolated rendering (including skin palettes via Skeleton.update(..., worldOf)).
4. Transform authority — §42's one-owner rule, authority handovers, and the §19 physics-animation blending pipeline.
5. Materials and the render graph — the five shipped material classes over §57's complete base (§59's StandardMaterial and §60's NodeMaterial included), render lists (buildInterpolatedRenderList also refreshes §43 skin palettes), opt-in §65 batching, and the shipped §63 render graph with its §69/§70 tiers. (Until 2026-08-29 this entry read "the shipped unlit/sprite material tier … and the honest state of the §63 render graph", describing the guide's pre-rewrite staleness.)
6. Collision filtering — bodies, colliders, physics materials, groups and masks (§24), events (§29), and queries (§30).
7. Units and numerical stability — §7a/§40 unit conventions and the §41 stability guidance, with the measured numbers behind it.
8. Workers and cross-origin isolation — §88's three threading modes, what ships today (main-thread), and the COOP/COEP deployment requirement.
9. Performance optimization — §86 targets, what the committed benchmarks actually measured, and the practices the engine's own hot paths use.
10. Custom shaders — the landed §60 node-material system (RFC 0001): shader graphs, NodeMaterialBuilder, screen-domain graph effects, per-backend registration, and what stays deferred. (Until 2026-08-29 this entry read "the honest state of §60 … today and what is staged", describing the pre-landing guide.)
11. Custom solver adapters — the §37 PhysicsWorldAdapter contract, capabilities, and the access seams the shipped adapters implement.
12. The engineering dashboard — motors, PID control, limit switches, and live instrumentation (§119's dashboard half).
13. The digital twin — serialization (§79), snapshots and replay (§34), determinism (§33), and assets (§76), composed.

A fourteenth guide sits alongside those thirteen. It is not one of §93's nineteen documentation items; §96 asks for the documentation itself, in its "documented content-security-policy behavior" requirement, and the answer reads as a guide:

1. Security and untrusted content — §96's seven requirements with an honest met/partial/absent table, the input-size limits and load deadline on AssetManager (§76), the text-length and nesting bounds on the §79 and §34 document decoders, and the CSP posture, which tests/integration/security-csp.test.ts enforces rather than asserts.

A fifteenth carries the §77a browser-adapter recipe RFC 0004 promised a guide for (until 2026-08-29 it lived only in raster.ts's module header):

1. Raster painting and dynamic textures — §77a's RasterSource/CanvasTexture seam, the DOM-free browser adapter, the "nothing polls — call update() yourself" rule, and the §33 display-only boundary painted pixels live under.

A sixteenth is the renderer seam's counterpart to guide 11, written 2026-09-20 after dogfood cycle 9 measured that the seam supports a consumer-authored backend and that no guide said so:

1. Custom renderer backends — §61's Renderer contract, the "optional, and its presence is the capability" members, registerRenderer / resolveRenderer("auto"), and the measured three-line cost of swapping between backends whose surfaces differ.

A seventeenth teaches the nine §53 3D generators that shipped with R-20 and had zero guide mentions through cycle 9:

1. 3D geometry generators — sphere, cylinder, cone, capsule, torus, lathe, extrude, tube, and height-field builders: Y-up revolution axis, analytic normals, u around / v along, and the §85 refusals.

An eighteenth teaches the §83 / §85 warning family as a whole rather than as scattered mentions in the performance guide:

1. Development warnings — the §83 allocation and leak audits, the §85 validation catalogue, when they fire (DEV + opt-in), and the difference between a measurement _window_ and an allocator.

Guide coverage, counted

Cycles 8 and 9 both rediscovered the same thing: some shipped surfaces have no guide. Both judged it a coverage gap, not a defect — package READMEs and TypeDoc cover the symbols, and no guide teaches a wrong call about them — and that judgement stands. It is tabulated here so the next cycle reads a count instead of measuring it again.

Measured 2026-09-20 with grep -rl <symbol> docs/guides/:

Cycle 9's own filing said these surfaces had "zero docs/guides/ files". Read literally that is too strong: each of the four stub packages is _named_ in at least one guide. The accurate statement is the one the table makes — no guide teaches them, and for the four stubs that is correct rather than missing.

Conventions every guide assumes

• The world is right-handed, Y-up, in 2D and 3D alike (§7a). 2D gravity is negative Y. Angles are radians; every engine time is seconds — tween and timeline durations included, never milliseconds.
• Components attach with node.addComponent(...), one per type per node (§6a).
• Simulation advances in fixed steps; rendering interpolates between them (§10, §43).
• Exactly one system owns any node's transform at a time (§42).
• Imports use the umbrella package's subpaths, exactly as the examples do:

``ts import { Application } from "fourJS/application"; import { Group, OrthographicCamera } from "fourJS/scene"; import { Vector3 } from "fourJS/math"; ``

Section references like "§42" mean docs/SPECIFICATION.md numbering. Every code sample in these guides is written against the implemented API surface (docs/Architecture/package-export-surfaces.json) and modeled on the example apps; where a §93 topic covers something not yet implemented, the guide says so and cites the staging note instead of pretending.

Verified from outside

A short dogfooding checklist. These surfaces already ship; the job is to drive them as a reader would, not to re-implement them. Hosted demos live under /examples/<name>/ on Pages; browser gates live in tests/browser/.

Beside the guides

Not a §93 guide, but the document a guide sends you to when the question is "does this work here?":