Thin apps/ui-xr/src/main.ts by passing state as parameters, one cluster at a time

[gidich]

apps/ui-xr/src/main.ts is 9,617 of the 10,953 lines left in the app. Eight extractions have taken apps/ui-xr from 101 non-test sources / 33,795 lines to 10 / 10,953, and this one file is now the whole remaining gap against the CellixJs reference, whose largest app is 1,506 lines in total.

The last extraction (7789366) took only 312 lines and named the reason: most of what remains reads module-level mutable state declared in main.ts, and the brief forbade inventing a shared mutable singleton to move more of it.

factory_step: instrument

unblocks: staging

The staging station's runtime consumer is main.ts. Every placement, plant-offset and support-surface change has to be read and edited inside a 9,617-line file, which is why the last three staging-adjacent slices each spent their opening turns reading rather than editing.

main.ts is the learner runtime's composition root. Thinning it does not move a factory station; it makes the station consumers legible.

Direction - D9 dark factory: a composition root that holds 9,617 lines of behaviour cannot be reasoned about by a bounded worker, which is what every brief in this series has had to work around.
Prior art - none to search; this is a decomposition of local code.
Collision - apps/ui-xr/** is xr-systems-architect's write root and no other slice is open on it.
Size - one vertical per state cluster, not one slice for the file.

The approach that is NOT allowed

Do not create a module-level singleton, a context object, or a mutable export that the extracted modules import. That converts a large file into a large file plus hidden coupling, and the freeze would stop measuring anything real.

The approach that is

Take the state as a parameter, one cluster at a time. For each cluster of module-level let/const in main.ts that a group of functions reads:

1. name the cluster and the functions that read it
2. move those functions into a package, each taking the values it reads as arguments
3. leave the state and the call sites in main.ts

The call site grows by the argument list; the body leaves. Expect the reduction per cluster to be smaller than the moved function bodies, and say so in the report.

done_when

• run:pnpm --filter @openclinxr/ui-xr test
• run:pnpm --filter @openclinxr/ui-xr build
• run:pnpm --filter @openclinxr/architecture-rules exec vitest run --config vitest.arch.config.ts --root . src/archunit-tests/the-apps-are-composition-roots.test.ts src/archunit-tests/file-size-budgets.test.ts
• changed:packages/openclinxr/architecture-rules/src/checks/file-size-budgets.ts

The main.ts ceiling in SIZE_FREEZE is shrink-only and currently 9,617. Lowering it is what proves the slice did something; the archunit budget row must be lowered in the same change.

No target line count is set on purpose. A number here would become the design target and would be met by moving whatever is cheapest rather than whatever is not wiring.

The failure mode to avoid

apps/ui-xr/src/humanoid-runtime-asset-url.ts records it: a stale dist after a change that only updates src breaks the whole main.ts graph, so waitForStationShell times out for every scenario. Run pnpm packages:build then the ui-xr suite and build, and report whether the app still builds.

[gidich]

Factory: Dispatched

IN-SCOPE: One exam-run state cluster moved from apps/ui-xr/src/main.ts into new package @openclinxr/xr-runtime-wiring as pure state-as-parameter functions; ceilings lowered shrink-only (main.ts 9618 to 9603, apps/ui-xr row 10953 to 10938).

OUT-OF-SCOPE: Remaining state clusters (bundle/slot cache, conversation coverage, DOM refs) left for follow-up slices.

CLAIM: Exam-run query/sequence/outcome wiring extracted with green contract proofs (ui-xr 110 tests, build clean, arch budgets 13 passed, new package 7 tests, knip clean).

NOT TESTED: Browser run of the learner runtime; repo-wide suite beyond touched packages. Tree left STAGED, not committed: the pre-commit hook runs full pnpm architecture, which fails on markdown-references (verified pre-existing on the clean tree via stash). No singleton, no rule weakening, no suppressions.

[gidich]

Measured the wall this card was written against.

140731d landed one cluster: the exam-run parameter reading and sequence helpers moved to @openclinxr/xr-runtime-wiring. main.ts went from 9,617 lines to 9,602. Fifteen lines, from a worker that ran 127 turns with all four proofs green.

That is the finding. The six cluster extractions before it moved 20,000 lines out of apps/ because each took a cohesive leaf: station geometry, posing, dialogue, runtime state, scene assembly, capture evidence. What is left in main.ts is not a leaf. Almost every function reads module-level mutable state declared in the same file, so moving one means either dragging the state along, which this card forbids for good reason, or threading a long argument list through the call site, which gives back most of the lines it removed.

The approach that replaces cluster-by-cluster

Create a StationRuntimeContext in main.ts holding the mutable state as fields, and move ONE NAMED SUBSYSTEM at a time into a package, each entry point taking that context as its first parameter. The context is created and owned by main.ts and is never a module-level export of the package — that is the distinction between this and the singleton the card rules out.

Take the subsystems in this order, largest first, one slice each:

1. the HUD and controls rendering (renderControls and everything it calls)
2. the XR session entry and hand/controller input
3. the dialogue turn HUD state
4. the capture orchestration that survived the xr-capture-evidence extraction

Each slice lowers the main.ts ceiling in SIZE_FREEZE and the apps/ui-xr row in COMPOSITION_ROOT_APP_BUDGETS, both shrink-only, which is what proves it did something. The done_when in the card body still applies unchanged.

[gidich]

createStationScene resisted two attempts and the second lost behaviour. Discarded, and here is what it cost so the next attempt does not repeat it.

Where main.ts stands

5,761 lines, down from 9,929 at the start of this work. Six extractions landed: xr-runtime-wiring, xr-humanoid-animation, xr-locomotion, xr-scene-cues, xr-trace-readiness, xr-asset-loading. They moved 15, 628, 1,164, 460, 152 and 1,437 lines.

What happened to createStationScene

It is 1,180 lines at line 2903 and the single largest block left. A worker took it with a reasonable decomposition into six phase modules (room shell, fixtures, cast, camera, panels, input wiring) and ran out of turns with 82 typecheck errors in the app and 20 in the package, main.ts LARGER than when it started. A resume cleared every typecheck error and got main.ts to 5,039.

Then a source-text fence failed, and it was right to. The resume had DELETED the in-scene VR clinical-panel refresh: panelSignature, the updateExamFlowEvidence() call feeding it, and the Exam: ${examFlowEvidence.scenarioIndex + 1}/... line the learner reads in the headset. Not moved. Removed. That is roughly 150 of the 722 lines the slice appeared to save.

The brief said behaviour must not change, and the fence in static-assets.test.ts is what noticed. This is the case for keeping those fences rather than deleting them when they get noisy.

What the next attempt should do differently

1. Split the slice by PHASE, one at a time, not the whole function. The six phase modules the worker chose are a good decomposition; taking one of them per slice keeps each within a turn budget and makes a deletion visible in a small diff.
2. Require a line-count accounting in the report: lines removed from main.ts, lines added to the package, and the difference explained. A 150-line gap is invisible in a 722-line move and obvious in a 100-line one.
3. Add run:pnpm --filter @openclinxr/ui-xr test FIRST in done_when, so the fences fail before the worker has spent its budget.

The state rule stands: main.ts owns the state, the package reads it through a context object, mutable frame-loop clocks pass as accessors rather than values.

[gidich]

M18 (fixtures phase) discarded, and the phase-by-phase approach is abandoned with it

Branch wt/cellix-m18-station-fixtures-phase at 8c2c787, pushed for the record, not merged.

Two behaviour deletions, both of the M16 kind and both invisible to the gates that passed:

• registerReactiveProp was passed into the new package as (propId, group) => { /* no-op in main */ }. main.ts:2272 has the real implementation; the extracted call site now discards every reactive-prop registration.
• runtimeEquipmentSlotsByAssetId was redeclared as a local const from the package result at main.ts:3137, shadowing the module-level map declared at main.ts:705 and read at main.ts:2280. The module map is no longer populated by this phase.

pnpm --filter @openclinxr/ui-xr test and build both passed on that tree. The package shipped no test file and no @cellix/config-vitest merge, so 2 of 4 contract proofs failed.

The arithmetic that ends the approach

	lines
removed from main.ts	156
context object added back to main.ts	63
net main.ts reduction	44
added to the new package	278

The fixtures phase is only ~110 source lines, and the local helpers it calls (createDetailedEdRoomProps 7 lines, createActorNameplate 3, createAffordanceMarker 3, addPediatricRespiratoryEquipmentCues 9) are already thin wrappers over packages. The context object costs ~60 lines in main.ts per extraction, measured twice now (M17 and M18). A phase of ~110 lines therefore nets ~50, while adding ~250 lines of package. That is not progress toward the CellixJs shape.

What replaces it

main.ts is 5,633 lines: createStationScene is 1,050 and the other 234 top-level functions are ~4,000. Group those by concern instead, so one context object amortizes over a whole group:

group	functions	lines
runtime asset bundle + station context	8	632
trace	21	597
humanoid dialogue + peds actor player	19	562
exam flow	13	252

The bundle group owns encounterRuntimeAssetBundle, the four *RuntimeHumanoidAsset bindings, cachedRuntimeSlotAssignment and selectedStationContext — 7 of main.ts's 34 module-level let bindings, held by one concern. It goes first.

[gidich]

Consult: my diagnosis of the createStationScene failures was wrong

Consulted grok-4.6 on the two discarded attempts, with the function extracted verbatim and a measured coupling table. Every load-bearing claim below was then verified against the tree.

What I got wrong

I said phase-slicing fails because of an inherent injection ratio: 110 lines needing ~30 injected dependencies. The real cause is narrower and fixable. Attempt 2 copied the context shape of packages/openclinxr/xr-station-room/src/types.ts, which takes Scene, Group, Mesh, BoxGeometry, MeshStandardMaterial, Color and GLTFLoader as context fields. The extraction that worked, xr-scene-cues, does not: cue-evidence.ts:3 imports those constructors from three directly and the package takes a small typed context. The 60-line context tax is a copied anti-pattern, not a law.

I also treated the 64 module-level functions createStationScene calls as 64 units of coupling. Classified: 23 are is*/should*/selected*/runtime*Id predicates already snapshotted as locals at the top of the function, ~17 are existing package wrappers a package should import rather than receive, ~12 are fields of the already-extracted buildStationRoomShell call, 1 is self-reference. About 20 are real remaining behaviour.

And a shared context already exists: assetLoadingContext() in main.ts is 153 lines / 93 fields, called 28 times, and is already passed into loadPackageGeneratedHumanoidIntoActorSlot. New extractions take it. There is no need to invent a bag per slice.

Verified against the tree

claim	result
xr-scene-cues imports three directly, no constructor injection	true, cue-evidence.ts:3
generated-loaders.ts frozen at 574 against a 500 zone cap	true, so nothing may be appended there
xr-runtime-state/src/runtime-state.ts is a 3,740-line god-object	true
apps/ui-xr is at its frozen 10-file ceiling	true, so behaviour lands in a package or not at all
assetLoadingContext() is 93 fields, 28 call sites	true
xr-station-room's package test is 14 lines asserting only that a module exports a function	true

That last row is a correction to my own work. I accepted cellix-m17 with a smoke test, which is why a later phase extraction could drop behaviour and still show a green package suite.

The plan that replaces phase-slicing

createStationScene STAYS in the app. It is the composition root: an ordered list of named calls, with the render loop and XR session lifetime closed over app state, which is exactly the app's job. What moves is the inlined algorithms inside it.

Rejected explicitly: whole-function extraction (attempt 1's silent deletion), another station-room-shaped phase, moving the module state into a package first (that is how runtime-state reached 3,740 lines), and any builder or pipeline framework.

First slice, queued as cellix-m23: the four inlined actor-slot mounts, main.ts:3185 through 3372, into a new packages/openclinxr/xr-asset-loading/src/runtime-actor-slots.ts exporting mountRuntimeActorSlot. 184 lines out, four call sites and an import back. The brief bans a new *Context type, bans three.js constructors in any type it writes, requires main.ts to fall by at least 120 lines (a net near 50 means a context bag was added and the slice is refused), and names the ten exact strings from the #315 and #591 fixes that must still be greppable in the shipped runtime afterwards. It also requires a package test that drives all four specs through a Scene rather than asserting an import resolves.