lhumina_code/hero_assistance
0
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

feat(ui): Phase 26 — customer SPA island integration (hero:theme + hero:route postMessage + X-Forwarded-Prefix) #11

New issue
Closed
opened 2026-05-06 17:47:10 +00:00 by mik-tf · 1 comment
mik-tf commented 2026-05-06 17:47:10 +00:00
Owner
Copy link

Why

The customer-facing SPA (_ui_wasm) is currently designed for two delivery modes:

  1. Standalone via _app Dioxus desktop binary
  2. _ui --dist <path> direct browser access

Missing: integration with Hero OS shell as an archipelago island. Per web_embed + hero_ui_routes skills, every UI mounted in hero_os must:

  • Implement hero:theme postMessage protocol — receive theme changes from shell
  • Implement hero:route postMessage protocol — push nav state into host window's floating header (breadcrumbs + actions + deep-link URL)
  • Honor X-Forwarded-Prefix header for base-path routing (hero_router mounts services at /hero_assistance/...)
  • NOT render its own breadcrumb bar or close button when running inside Hero OS shell

What

A. postMessage protocols

  • hero:theme receiver — listen for {type: "hero:theme", theme: "dark"|"light"} messages from parent; update data-bs-theme
  • hero:route sender — on every nav change, post {type: "hero:route", route: {...}, breadcrumbs: [...], actions: [...]} to parent

Per web_embed skill drop-in helper hero-window-route.js.

B. X-Forwarded-Prefix base-path

_ui Axum reads X-Forwarded-Prefix from request headers; threads BASE_PATH into SPA via <meta name="base-path"> tag. SPA reads BASE_PATH and uses it for all /rpc, /events, asset URLs.

Per hero_web_prefix skill.

C. Archipelago slot — D-23

Pick one:

  • Communication archipelago (alongside room, call, voice, collab) — recommended; hero_assistance is support communication
  • Tools archipelago (alongside whiteboard, slides, inspector)

Rationale in D-23. Register in external hero_archipelagos repo: new island spec referencing the WASM dist URL via hero_router.

D. Conditional chrome

When ?embedded=1 or running inside iframe (detect window.parent !== window), suppress:

  • Top-level breadcrumb bar (host window owns this)
  • Close button (host owns)
  • Window title (host owns)

Keep visible: tab strip, ticket list, composer, presence sidebar.

Acceptance

  • hero:theme postMessage updates SPA theme without page reload
  • hero:route postMessage fires on every nav change with current route + breadcrumbs
  • X-Forwarded-Prefix: /hero_assistance causes SPA to use prefixed URLs for all requests
  • Embedded mode hides top-level chrome (breadcrumbs + close button)
  • D-23 written
  • Archipelago island spec PR opened against lhumina_code/hero_archipelagos
  • Manual smoke: open hero_os shell, navigate to hero_assistance island, verify embedding works

Files to touch

  • crates/hero_assistance_ui_wasm/src/lib.rs — postMessage send/receive
  • crates/hero_assistance_ui_wasm/src/components/ — conditional chrome rendering
  • crates/hero_assistance_ui/src/main.rs — X-Forwarded-Prefix handling, BASE_PATH meta tag injection
  • New: decisions/D-23-archipelago-slot.md
  • External PR: lhumina_code/hero_archipelagos — new island spec

Out of scope

  • hero_proc lifecycle (Phase 24)
  • Admin dashboard (Phase 25)
  • hero_demo provisioning (Phase 27)

References

  • Skill web_embed
  • Skill hero_ui_routes
  • Skill hero_web_prefix
  • External: lhumina_code/hero_archipelagos repo island spec format
  • External: lhumina_code/hero_os shell (consumes islands)
## Why The customer-facing SPA (`_ui_wasm`) is currently designed for two delivery modes: 1. Standalone via `_app` Dioxus desktop binary 2. `_ui --dist <path>` direct browser access Missing: integration with **Hero OS shell** as an archipelago island. Per `web_embed` + `hero_ui_routes` skills, every UI mounted in `hero_os` must: - Implement `hero:theme` postMessage protocol — receive theme changes from shell - Implement `hero:route` postMessage protocol — push nav state into host window's floating header (breadcrumbs + actions + deep-link URL) - Honor `X-Forwarded-Prefix` header for base-path routing (`hero_router` mounts services at `/hero_assistance/...`) - NOT render its own breadcrumb bar or close button when running inside Hero OS shell ## What ### A. postMessage protocols - `hero:theme` receiver — listen for `{type: "hero:theme", theme: "dark"|"light"}` messages from parent; update `data-bs-theme` - `hero:route` sender — on every nav change, post `{type: "hero:route", route: {...}, breadcrumbs: [...], actions: [...]}` to parent Per `web_embed` skill drop-in helper `hero-window-route.js`. ### B. X-Forwarded-Prefix base-path `_ui` Axum reads `X-Forwarded-Prefix` from request headers; threads `BASE_PATH` into SPA via `<meta name="base-path">` tag. SPA reads BASE_PATH and uses it for all `/rpc`, `/events`, asset URLs. Per `hero_web_prefix` skill. ### C. Archipelago slot — D-23 Pick one: - **Communication** archipelago (alongside `room`, `call`, `voice`, `collab`) — recommended; hero_assistance is support communication - **Tools** archipelago (alongside `whiteboard`, `slides`, `inspector`) Rationale in D-23. Register in external `hero_archipelagos` repo: new island spec referencing the WASM dist URL via hero_router. ### D. Conditional chrome When `?embedded=1` or running inside iframe (detect `window.parent !== window`), suppress: - Top-level breadcrumb bar (host window owns this) - Close button (host owns) - Window title (host owns) Keep visible: tab strip, ticket list, composer, presence sidebar. ## Acceptance - [ ] `hero:theme` postMessage updates SPA theme without page reload - [ ] `hero:route` postMessage fires on every nav change with current route + breadcrumbs - [ ] `X-Forwarded-Prefix: /hero_assistance` causes SPA to use prefixed URLs for all requests - [ ] Embedded mode hides top-level chrome (breadcrumbs + close button) - [ ] D-23 written - [ ] Archipelago island spec PR opened against `lhumina_code/hero_archipelagos` - [ ] Manual smoke: open hero_os shell, navigate to hero_assistance island, verify embedding works ## Files to touch - `crates/hero_assistance_ui_wasm/src/lib.rs` — postMessage send/receive - `crates/hero_assistance_ui_wasm/src/components/` — conditional chrome rendering - `crates/hero_assistance_ui/src/main.rs` — X-Forwarded-Prefix handling, BASE_PATH meta tag injection - New: `decisions/D-23-archipelago-slot.md` - External PR: `lhumina_code/hero_archipelagos` — new island spec ## Out of scope - hero_proc lifecycle (Phase 24) - Admin dashboard (Phase 25) - hero_demo provisioning (Phase 27) ## References - Skill `web_embed` - Skill `hero_ui_routes` - Skill `hero_web_prefix` - External: `lhumina_code/hero_archipelagos` repo island spec format - External: `lhumina_code/hero_os` shell (consumes islands)
mik-tf commented 2026-05-22 12:55:29 +00:00
Author
Owner
Copy link

Closing — Phase 26 engineering-complete

Title delivered verbatim by 336a411 (s46): feat(ui,components,wasm)(phase-26): customer SPA archipelago island integration (hero:theme + hero:route + X-Forwarded-Prefix). CLAUDE.md "Open issues" table marks this engineering complete (s46; ready to close).

All 7 acceptance bullets met:

  • hero:theme postMessage receiver: use_hero_theme_handshake hook in hero_assistance_ui_wasm_components/src/lib.rs
  • hero:route postMessage sender: HeroRouteBridge layout in _ui_wasm/src/hero_route.rs with HeroRouteOutbound envelope projector
  • X-Forwarded-Prefix → meta-rewrite: routes::rewrite_index_meta in _ui + SPA-side init_rpc_base_from_meta()
  • Embedded chrome suppression: gated on ?hero_window_id= presence per skill line 208
  • Decision landed as D-25 (renumbered from D-23 due to s46 ID race)
  • Archipelago island spec deferred per D-25 §"Out of scope"
  • 19 phase26 regression tests + drift guard on _ui_wasm/index.html meta shape

Closing.

Signed-by: mik-tf mik-tf@noreply.invalid

## Closing — Phase 26 engineering-complete Title delivered verbatim by [`336a411`](https://forge.ourworld.tf/lhumina_code/hero_assistance/commit/336a411) (s46): `feat(ui,components,wasm)(phase-26): customer SPA archipelago island integration (hero:theme + hero:route + X-Forwarded-Prefix)`. CLAUDE.md "Open issues" table marks this `engineering complete (s46; ready to close)`. All 7 acceptance bullets met: - `hero:theme` postMessage receiver: `use_hero_theme_handshake` hook in `hero_assistance_ui_wasm_components/src/lib.rs` - `hero:route` postMessage sender: `HeroRouteBridge` layout in `_ui_wasm/src/hero_route.rs` with `HeroRouteOutbound` envelope projector - `X-Forwarded-Prefix` → meta-rewrite: `routes::rewrite_index_meta` in `_ui` + SPA-side `init_rpc_base_from_meta()` - Embedded chrome suppression: gated on `?hero_window_id=` presence per skill line 208 - Decision landed as [D-25](https://forge.ourworld.tf/lhumina_code/hero_assistance/src/branch/development/decisions/D-25-customer-spa-island-handshakes.md) (renumbered from D-23 due to s46 ID race) - Archipelago island spec deferred per D-25 §"Out of scope" - 19 phase26 regression tests + drift guard on `_ui_wasm/index.html` meta shape Closing. Signed-by: mik-tf <mik-tf@noreply.invalid>
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
integration
main
v1.0
latest
v0.3.1
v0.2.2
v0.2.1
v0.2.0
v0.1.0
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_assistance#11
No description provided.