feat(picking): ray-pick Models via _worldBounds + linear scan

.claude/rules/archetypes.md

@@ -0,0 +1,60 @@
+---
+description: Authoring rules for ECS systems that iterate archetype rows.
+globs: "**/*.ts"
+---
+
+# Archetypes — iteration rules
+
+## Express selection in the query, not the loop
+
+`queryArchetypes(include, { exclude })` accepts both required and excluded
+component lists. Use them. Don't query a wider set and then skip rows or
+archetypes with an `if`.
+
+```ts
+// ❌ post-filter
+for (const arch of db.store.queryArchetypes(["position", "rotation"])) {
+    if (arch.components.has("_worldMatrix")) continue;
+    ...
+}
+
+// ✅ declarative
+for (const arch of db.store.queryArchetypes(
+    ["position", "rotation"],
+    { exclude: ["_worldMatrix"] },
+)) {
+    ...
+}
+```
+
+## When every row migrates out, iterate tail → head
+
+Archetypes are densely packed. Removing or migrating a row that isn't the
+last one triggers a hole-fill: the tail row is moved into the gap.
+Iterating `0 → rowCount-1` while migrating every row pays this cost on
+every iteration. Iterating `rowCount-1 → 0` means each removal is from
+the tail — no shift, indices ahead of the cursor stay valid.
+
+```ts
+// ❌ shifts the tail into every hole, and the snapshot allocation is
+//    only there to survive the shifts.
+const ids = [...];
+for (let i = 0; i < arch.rowCount; i++) ids[i] = arch.columns.id.get(i);
+for (const id of ids) db.store.update(id, { _worldMatrix: Mat4x4.identity });
+
+// ✅ no shifts, no allocation
+for (let i = arch.rowCount - 1; i >= 0; i--) {
+    db.store.update(arch.columns.id.get(i), { _worldMatrix: Mat4x4.identity });
+}
+```
+
+If only *some* rows migrate (filter inside the loop), snapshot the ids
+you'll touch — forward iteration is fine because rows you don't touch
+stay put.
+
+## Don't snapshot what the query already filters
+
+A snapshot of "all entity ids in this archetype right now" is only
+needed when forward iteration would invalidate. Reverse iteration
+removes the need; an `exclude` clause removes the need to look at rows
+that don't qualify in the first place.

.claude/rules/namespace.md

@@ -48,3 +48,60 @@ as both type and namespace (`LogLevel.is(x)`, `LogLevel.values`).
   avoid cycling through `public.ts`.
 - Add `is` / `values` / per-member descriptors only when an external
   consumer actually needs them — not preemptively.
+
+## Multi-declaration files (when lumping is OK)
+
+Default stays one type / one helper per file. Two named exceptions:
+
+- **`<type>-functions.ts`** — sibling functions operating on one owned
+  type. Lives in that type's folder. Use when functions are small enough
+  that adjacency in one editor pane beats one-file-per-function.
+- **`<format>-schema.ts`** — TypeScript projection of a borrowed data
+  format (file format, wire protocol, third-party API). Plain `export
+  interface` only — no namespace, no helpers. Lives next to the parser/
+  emitter, not in a type folder.
+
+Never `*-types.ts`. "Types" is a meta-word the `.ts` extension already
+implies; the name has to predict the contents. If you can't beat
+`-types`, the file isn't a real lump — split per type, or inline at use
+site.
+
+## Domain namespaces (for types you don't own)
+
+When utility functions operate on a platform or third-party type (e.g.
+`GPUDevice`, `GPUTexture`), use a **domain namespace** instead: a folder
+named after the concept, with a namespace export but *no type re-export*.
+
+```
+src/gpu/
+  gpu.ts       # `export * as GPU from "./public.js"` — no type alias
+  public.ts    # re-exports every public helper
+  <helper>.ts  # one declaration per file
+```
+
+```ts
+// gpu/gpu.ts
+export * as GPU from "./public.js";
+
+// gpu/public.ts
+export { createCubemap } from "./create-cubemap.js";
+export { cubeFaceView }  from "./cube-face-view.js";
+```
+
+Consumers import the namespace and get discoverability without shadowing
+the platform type:
+
+```ts
+import { GPU } from "@adobe/data-graphics";
+GPU.createCubemap(device, 256, "rgba16float");
+```
+
+**Name by purpose, not by the external type.** `GPU`, not `GPUDevice`.
+
+**Tree-shaking still works**: bundlers (Rollup/Rolldown) trace static
+property accesses (`GPU.createCubemap`) and exclude unused helpers.
+Dynamic access (`GPU[name]`) defeats this — avoid it.
+
+**When NOT to use a domain namespace**: if a utility is only useful as
+an internal implementation detail of a specific plugin (not callable by
+consumers), keep it private to that plugin's folder instead.

.claude/rules/plugin-modelling.md

@@ -0,0 +1,170 @@
+---
+paths:
+  - '**/*plugin*'
+  - '**/*plugin*/**'
+---
+
+# Plugin modelling — model vs. system, authored vs. derived
+
+Each plugin has two orthogonal axes:
+
+1. **Authored** state — the user inserts / sets it. Designed by the human
+   architect.
+2. **Derived** state — a system produces it from other state. Implementation;
+   owned by the AI.
+
+The human's mental model of a project is the union of every plugin's
+**authored surface**. Systems and derived state are how the world updates
+and renders — read their interface contract, not their innards.
+
+## Two tiers of model plugins
+
+- **Core** — the primary record types every consumer reads. Small, fixed,
+  shared.
+- **Authoring abstractions** — higher-level intents (orbit, animation,
+  procedural shape, particle emitter, constraint, …) that systems expand
+  into core state. Open-ended; each project picks what it needs.
+
+A plugin almost never holds both authored and derived data the user cares
+about. If it appears to, the derived data is the *implementation* of the
+authoring abstraction.
+
+## File naming
+
+Each file whose primary export is a `Database.Plugin` (created or
+combined) ends in `-plugin.ts` — e.g. `node-plugin.ts`, `model-plugin.ts`,
+`pbr-core-plugin.ts`. The suffix is for discovery: cursor rules,
+codebase grep, and "find all plugins" tooling match `**/*-plugin.ts`
+without inspecting contents.
+
+The exported constant's name depends on whether the folder also hosts a
+type namespace:
+
+- **Pure-plugin folder** (no owned type) → export the concept name
+  itself, lowercase. `node-plugin.ts` exports `node`. Import sites read
+  `import { node } from "..."; Database.Plugin.combine(node, ...)`.
+- **Type + plugin folder** (folder hosts both an owned type and its
+  plugin) → the plugin file exports `plugin`, re-exported through the
+  type's namespace. `camera-plugin.ts` exports `plugin`; `camera/public.ts`
+  re-exports it; consumers reach it as `Camera.plugin`. One import gives
+  both the type and the plugin.
+
+Files with helper exports, value types, schemas, or shaders do **not**
+take the suffix — only plugin files.
+
+## Resources and archetypes as types
+
+Prefer **one resource per plugin**, of an owned type that the folder also
+hosts. `light/` has one `light` resource of type `Light`; `orbit/` has
+one `orbit` resource of type `Orbit`. Splitting a single coherent
+concept into siblings (`lightDirection`, `lightColor`, `ambientStrength`)
+duplicates the concept's identity at every read site.
+
+For each **archetype** the plugin declares, add a TypeScript type with
+the same name describing one row's authored shape. `Node` is the type
+for the `Node` archetype's row. The components stay separate per
+typed-buffer-column convention; the type names the bundle so consumers
+can declare `const node: Node` after a read.
+
+Both cases follow the same folder shape:
+
+```
+<concept>/
+  <concept>.ts          # type + namespace
+  public.ts             # re-exports plugin (and any helpers)
+  <concept>-plugin.ts   # exports `plugin`
+```
+
+Consumers reach the plugin as `Concept.plugin` and the type as
+`Concept`. Pure-plugin folders (no owned type) still export their
+plugin under a lowercase concept name — see "File naming" below.
+
+**Exceptions:**
+- Plugins whose resources have genuinely independent lifecycles
+  (`graphics` — `device`, `canvas`, `commandEncoder`, each set at
+  different times) keep them as separate resources. Consolidating
+  would force any one write to replace the whole struct.
+- Ephemeral implementation archetypes (e.g. `_PbrPrimitive`,
+  `_VisibleMaterial`) don't need a value type — consumers iterate
+  them by archetype, never construct one.
+
+## Shared conventions
+
+- **Uppercase identifier** = archetype. **Lowercase** = component or
+  resource. Disambiguated by where declared (archetype vs. component vs.
+  resource section of the data plugin).
+- **Entity references** are typed `EntityId`; field names drop the `Ref`
+  suffix — the type carries the signal.
+- **Implementation prefixes** (`pbr`, `ibl`, …) belong in code where they
+  disambiguate cross-plugin reuse. Drop them in the conceptual view.
+- **`_` prefix** = ephemeral / derived / not part of the data model.
+  Applies to **components, archetypes, and resources** in code — the
+  prefix makes "this is system-owned, not user-authored" visible at every
+  read site. The human ignores it when modelling; system-graph views
+  still display it. Does **not** apply to plugin names, system names, or
+  transactions — those are grouped by feature folder, and the folder
+  already communicates whether a plugin is authored surface or
+  implementation.
+- **Inline `: Type`** only on `_`-prefixed names. Persistent items get
+  their type from the data plugin where they're declared.
+- **Components use JSON schemas**, resources use `{ default: X as T }`.
+  Schemas (e.g. `Entity.schema`, `Mat4x4.schema`, `Boolean.schema`,
+  `{ type: "string" }`) enable typed-buffer column storage — the right
+  choice when a value is stored once per entity. Resources are a single
+  slot per database, so the runtime cost of typed storage isn't worth
+  it; the default-pattern is the convention there. Use the default
+  pattern on components *only* for runtime-only objects (GPU buffers,
+  bind groups, closures, complex JS objects with no schema).
+
+## Model plugin format
+
+Authored surface only — no derived state, no systems.
+
+```
+pluginName
+  components
+    fieldName:  Type
+    ...
+  resources
+    fieldName:  Type
+    ...
+  archetypes
+    ArchetypeName: [field, field, ...OtherArchetype]
+```
+
+- `...Other` composes another archetype's component list.
+- Shape comments (`// { … }`) stay on the same line; do not wrap.
+
+## System plugin format
+
+```
+systemName              // high-level summary
+  query: ArchetypeExpr [, ArchetypeExpr ...]   // omit if resource-only
+  read:
+    name                                       // persistent — type from data plugin
+    _name: Type                                // ephemeral — type inline
+  write:
+    name                                       // writes a component / resource
+    _Archetype                                 // creates new entities of this archetype
+    // free-text side effect                   // draw calls, network sends, …
+```
+
+- `read:` and `write:` are outlined one-per-line.
+- A system can have multiple independent queries; comma-separate them on
+  the `query:` line.
+
+## Query DSL
+
+- `Archetype` — entities matching the archetype.
+- `+component` — require this additional component.
+- `-component` — exclude entities that have it.
+- `Archetype+a-b+c` — left-to-right chain of `+` / `-`.
+- `Q1, Q2, ...` — multiple independent queries the system reads from.
+
+## Designing or discussing a plugin
+
+1. Write the authored surface (model format) **first**.
+2. Then each system as its own interface card with `query` / `read` /
+   `write`.
+3. The graph of `write:` → `read:` edges is the implementation; the union
+   of authored surfaces is the human's mental model.