Statum/.kilo/plans/goal-30-plan.md

Goal 30 — Split statum.js into four modules + automatic pstm rewrite

Branch statum-js-modules (cut from master c741172). All findings below verified against the source on this saddle. The locked brief and task #212 comment 814 are authoritative; this plan follows them, with two implementation choices called out where 814 left naming open.

Verified ground truth (from investigation)

• js/statum.js (3,943 lines) section boundaries match the 814 inventory exactly: core = 1–1123 + 3531–3561(renderAll/guards/hooks) + 3690–3943 (boot/state/init/API); document = 1125–1256 + 3357–3688 minus applyErrorClasses; markdown = 1257–3335.
• processInner :3504 hardcodes the order class→attribute→disabled→text/html/markdown/demotion→wireAction→recurse. Splitting stm-markdown out (it loads AFTER document) means plain registration-order execution would demote before markdown renders — the seam needs explicit ordering.
• applyErrorClasses :3638 (document territory) is called by core's reportFailure :304 → moves to core per the brief.
• performAction :935 rejects on HTTP error / error-directive (reportFailure :302 re-throws unless suppressed) → stm-clear-on-success can await the __stmAction stash.
• Delivery today: src/meson.build embeds js/statum.js via mkres as /_statum/resource/statum.js (ClientScript.vala); mkpstm rewrite_resources_in :401 does the generic pstm-res-* rewrite; example/main.html:8 has the single pstm-res-src="statum.js" (stays UNMODIFIED — the compat proof); frontend-demo/server.php:362 serves /statum.js off disk; index.html:405 references it, with toast overrides right after. Markdown tests load the file via std.loadFile under a stub shim.
• Toolchain: gcc/meson/valac + all pkg-config deps present. php NOT installed (dnf has it — needed for the demo e2e). qjs builds vendored on demand.
• No js/ references in MANIFEST.usm/.usmignore/.gitignore — packaging untouched.

Design decisions (implementation-level, stated per the "deviate only with reason" rule)

1. Bridge = window.statum._bridge — core's IIFE builds the public API plus this internal object holding the shared seam (evalExpr, childScope, stateScope, renderAll, registerAttribute, installRenderDriver, performAction, trigger*, handlers, hooks, and the forms-hosted dirty WeakSet slot). Underscore prefix follows the existing _testMarkdown private-by-convention precedent. "Guarded IIFE" = each module starts by checking window.statum && window.statum._bridge, else console.error('[statum] <module> requires statum-core.js') and returns (no throw).
2. registerAttribute ordering — bridge.registerAttribute(name, fn, opts) where opts.after / opts.before name another attribute; core resolves to the ordered handler list processInner iterates. Document registers its handlers in today's relative order; markdown registers stm-markdown with after:'stm-html'; document registers stm-h-demotion with after:'stm-markdown' (present-but-late if markdown never loads — same as today's "runs after html" guarantee). A split test pins the final order byte-for-byte to today's.
3. Interim tree coherence — each task leaves the tree building and meson test green: task A deletes js/statum.js and rewires meson to the modules that exist (3 after A, 4 after B); the example page only becomes servable again in task C when mkpstm expands the reference.

Tasks (sequential; each a separate task branch)

Task A — Split core/document/markdown + seams (implement)

• Create js/statum-core.js, statum-document.js, statum-markdown.js per the 814 line map; delete js/statum.js. Core keeps: config/state/persistence/session/listeners/mutation, headers+freshness, HTTP helpers, entrypoint/action fetch, directive dispatch + terminal directives, realtime channel, boot visibility, guards/hooks/renderAll, public state accessors, init/autoInit/public API, handlers+trigger* (:74/:249–307) preserved exactly, applyErrorClasses moved in. Document keeps: loop/conditional/class/attribute/disabled handlers, render walk (render/processElement/processInner/applyDefs), text/html binding, h-demotion, action wiring (wireAction/runElementAction/collectData/setBusyState/reapplyDisabled). Markdown = engine :1257–3335 verbatim + the stm-markdown binding + statum.markdown.render(src) / renderTo(el, src) sharing the binding's single code path + the _testMarkdown hatch moves with it.
• Add _bridge, registerAttribute seam, render-driver install point (renderAll calls the installed driver inside its existing try/catch; absent driver = hooks+guards still run, no walk).
• Rewire src/meson.build to three mkres resources (statum.js resource name disappears; ClientScript class replaced by per-module classes registered in Statum.vala).
• Tests: new tests/split (load order, public surface incl. getter/setter handlers, handler order, double registration, module-without-core guard, markdown-without-document cherry-pick); tests/markdown loaders switched to core+markdown (regressions + spec suite stay green, gate 95%).
• Verify: tests/markdown/run.sh, tests/split, meson setup && ninja && meson test.

Task B — Forms module: stm-prefill + clear-on-success (implement)

• js/statum-forms.js registering stm-prefill (early in handler order): property writes only — .value for input/select/textarea (radio name-group matching within the form), .checked for checkbox (boolean coercion) and radio (value match); skips any element in the dirty WeakSet.
• Dirty tracking: one WeakSet hosted on _bridge (per the brief, reusable by the future task-186 fix) + capture-phase input/change listeners on document, and a reset listener that un-dirties the form's controls (doubling as the server form-reset un-dirty path).
• __stmAction promise stash: one-line change in statum-document.js wireAction listener (el.__stmAction = runElementAction(el); return el.__stmAction; shape).
• stm-clear-on-success on a form: submit listener awaits the triggering element's stashed promise; on resolve → form.reset() (fires the reset un-dirty path) ; rejection → leave fields. statum.forms.reset(form) as the programmatic equivalent.
• Non-regression: stm-attribute.value keeps writing the attribute (server-wins, untouched); no change to C1/C2/stateless-walk behaviour.
• Tests: tests/dom — real-ish DOM shim (~250 lines, ordered attributes, classList, tree mutation, atob/btoa, stubbed fetch; state injected via hand-built frames or a documented __STATUM_TEST__ hatch) covering the walk (if/else/for/text) and prefill scenarios: value, dirty-skip after input, checked, radio group, clear-on-success resolve/reject, forms.reset, reset-event un-dirty. model.md attribute table gains stm-prefill / stm-clear-on-success rows. meson gains the 4th resource.
• Verify: tests/dom + tests/split + markdown suite + meson test.

Task C — mkpstm rewrite + delivery + docs + demo e2e (implement)

• mkpstm: pstm-res-src="statum.js" on a <script> expands at build time to the four ordered script tags (/_statum/resource/statum-core.js → document → markdown → forms), one build warning per page naming page + expansion; explicit module tags pass through unwarned; a page mixing statum.js with explicit module tags emits the full ordered set once, deduped, and the warning says so. example/main.html stays byte-identical.
• frontend-demo: server.php serves the four module files (replacing /statum.js), index.html loads them in order with the toast-override script after; demo must work end to end and the override mechanism (onNotifyHandler/onConfirmHandler/onErrorHandler setters + trigger*) still functions — proven by the split-suite assertions plus a served-page check (four tags in order, modules fetchable, override script present).
• WHATS_NEW.md (root): stm-prefill semantics incl. checked/radio groups, stm-clear-on-success + statum.forms.reset, statum.markdown.render/renderTo, statum.registerAttribute for module authors, per-module script tags + ordered load contract, automatic pstm-res rewrite with the legacy-reference warning. Short, example-driven, links to model.md/getting-started.md.
• Docs: model.md/getting-started.md delivery sections rewritten for modules + rewrite; statum-issues.md S-4 note (superseded by stm-prefill) and mkpstm docs updated.
• Verify: full build; generated HomePage.vala contains the four tags (backwards-compat proof with the original unmodified reference); run statum-example + curl page/modules; install php via dnf, run frontend-demo (PHP_CLI_SERVER_WORKERS=5) + curl; all three JS suites + meson test green; no dead single-file remnants (grep -r "resource/statum.js" only matches the rewrite map + docs).

Non-goals / constraints

• ES5, zero dependencies, no bundler, no router module; SSE/SharedWorker stays in core.
• No behaviour change to the engine, the override mechanism, or directive semantics — moved, not redesigned. Non-regression on C1/C2/stateless-walk per task 186.
• USM packaging/MANIFEST untouched.

Risks

• The DOM shim is the largest new test surface; scoped to the walk + prefill paths only, and state injection uses a documented test hatch rather than widening the public API.
• mkpstm expansion touches libxml2 node surgery (insert siblings before remove) — covered by a generated-output check in the example build, and by keeping the generic pstm-res-* rewrite untouched for non-script elements.