[refactor] WASM frontend (hero_os shell + hero_archipelagos islands) config should flow through a single typed source #224

New issue

Open

opened 2026-05-06 21:15:26 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-05-06 21:15:26 +00:00

Owner

Context

Per the META principle (hero_proc_meta skill): all Hero processes read config from a single centralized source, not scattered ad-hoc reads. WASM is a different surface from native Rust binaries because there's no OS env in the browser, but the principle still applies — today config arrives via a mix of option_env! (compile-time baked), iframe boot params, ad-hoc fetch URLs, and postMessage glue, with no single typed surface.

Sibling of:

#222 — same problem, nu install-script layer
#223 — same problem, native Rust binary layer

Umbrella tracker: see #225.

Affected components

hero_os WASM shell (the Dioxus dock + island host)
hero_archipelagos native Dioxus islands (photos, videos, calendar, …)
Per-service WASM frontends if any (hero_collab_app — currently broken against latest hero_archipelagos development per session 67 notes)

Right shape

Each WASM session/iframe/island calls a single typed /config endpoint on its host service's UI socket (or a known shell endpoint for cross-cutting config). The endpoint:

Reads from hero_proc secrets server-side (depends on home#223)
Returns typed JSON
WASM deserializes into a config struct shared across the session

No option_env! for runtime config (only for build identity like commit SHA / build timestamp). No ad-hoc fetch of separate config URLs per island. No env-leakage via iframe boot params for secrets.

Audit shape

Inventory: grep -rn 'option_env!\|env!' lhumina_code/hero_os/ lhumina_code/hero_archipelagos/ — classify each: build identity (keep) vs runtime config (migrate).
Inventory: ad-hoc fetch(…) calls for config-shaped data in WASM — should consolidate into one call per session.
Inventory: iframe boot params + postMessage payloads carrying config — anything secret-shaped (tokens, keys) leaving the server side is a design smell.
Define the /config schema per host service (hero_os shell, each archipelago).

Sequencing

After home#223 (Rust binary META work) completes. UI services need to be reading from hero_proc secrets before they can serve typed config to WASM. Sequencing: home#212 binary rollout → home#222 nu scripts → home#223 Rust binaries → home#NNN-this-issue WASM.

Acceptance criteria

Inventory: per-WASM-component table of config reads classified build vs runtime.
Single typed /config endpoint per host service; WASM consumes once at session start.
Zero option_env! for runtime config (only build identity).
No secret-shaped values in iframe boot params or postMessage payloads.
Smoke: fresh deploy, after home#223 lands and secrets are seeded, the demo loads with all islands populated from server-fetched config — no client-side workarounds for missing values.

References

~/.claude/skills/hero_proc_meta/SKILL.md — canonical META env-from-secrets rule
hero_os shell architecture — lhumina_code/hero_os/
hero_archipelagos islands — lhumina_code/hero_archipelagos/
Session 67 note on hero_collab_app + hero_archipelagos development API drift (use_focus_poll + IslandContext) — separate refactor that may interact with this work

## Context Per the META principle (`hero_proc_meta` skill): **all Hero processes read config from a single centralized source, not scattered ad-hoc reads.** WASM is a different surface from native Rust binaries because there's no OS env in the browser, but the principle still applies — today config arrives via a mix of `option_env!` (compile-time baked), iframe boot params, ad-hoc fetch URLs, and postMessage glue, with no single typed surface. Sibling of: - https://forge.ourworld.tf/lhumina_code/home/issues/222 — same problem, nu install-script layer - https://forge.ourworld.tf/lhumina_code/home/issues/223 — same problem, native Rust binary layer Umbrella tracker: see https://forge.ourworld.tf/lhumina_code/home/issues/225. ## Affected components - `hero_os` WASM shell (the Dioxus dock + island host) - `hero_archipelagos` native Dioxus islands (photos, videos, calendar, …) - Per-service WASM frontends if any (hero_collab_app — currently broken against latest hero_archipelagos `development` per session 67 notes) ## Right shape Each WASM session/iframe/island calls a single typed `/config` endpoint on its host service's UI socket (or a known shell endpoint for cross-cutting config). The endpoint: 1. Reads from hero_proc secrets server-side (depends on home#223) 2. Returns typed JSON 3. WASM deserializes into a config struct shared across the session No `option_env!` for runtime config (only for build identity like commit SHA / build timestamp). No ad-hoc fetch of separate config URLs per island. No env-leakage via iframe boot params for secrets. ## Audit shape 1. Inventory: `grep -rn 'option_env!\|env!' lhumina_code/hero_os/ lhumina_code/hero_archipelagos/` — classify each: build identity (keep) vs runtime config (migrate). 2. Inventory: ad-hoc `fetch(…)` calls for config-shaped data in WASM — should consolidate into one call per session. 3. Inventory: iframe boot params + postMessage payloads carrying config — anything secret-shaped (tokens, keys) leaving the server side is a design smell. 4. Define the `/config` schema per host service (hero_os shell, each archipelago). ## Sequencing **After home#223 (Rust binary META work) completes.** UI services need to be reading from hero_proc secrets before they can serve typed config to WASM. Sequencing: home#212 binary rollout → home#222 nu scripts → home#223 Rust binaries → home#NNN-this-issue WASM. ## Acceptance criteria - [ ] Inventory: per-WASM-component table of config reads classified build vs runtime. - [ ] Single typed `/config` endpoint per host service; WASM consumes once at session start. - [ ] Zero `option_env!` for runtime config (only build identity). - [ ] No secret-shaped values in iframe boot params or postMessage payloads. - [ ] Smoke: fresh deploy, after home#223 lands and secrets are seeded, the demo loads with all islands populated from server-fetched config — no client-side workarounds for missing values. ## References - `~/.claude/skills/hero_proc_meta/SKILL.md` — canonical META env-from-secrets rule - `hero_os` shell architecture — `lhumina_code/hero_os/` - `hero_archipelagos` islands — `lhumina_code/hero_archipelagos/` - Session 67 note on hero_collab_app + hero_archipelagos `development` API drift (use_focus_poll + IslandContext) — separate refactor that may interact with this work