# "Platform Topology"

_Path: en/frontend/platform-topology_

> "How Wippy frontend source becomes a routed page or web component and receives runtime context and CSS."

## Table of Contents

- Platform Topology

## Content

# Platform Topology


This page is an architecture and diagnostic reference. The delivery chain and
diagrams describe system boundaries; they do not provide a runnable project.



## Delivery chain


| Stage | Owner | Verification |
|---|---|---|
| Source and package build | Frontend module | The package build emits the expected entry file. |
| Artifact location | Deployment build target | The build command receives `--outDir`; Vite does not hardcode it. |
| Registry entry | Backend module | `view.page` or `view.component` points at the emitted entry. |
| Served URL | Filesystem and HTTP registry entries | A direct asset request returns the built JavaScript or HTML. |
| Runtime container | Web Host | A page uses the configured page engine: a legacy `about:srcdoc` iframe or a Web Fragment. A component uses a custom element, normally with shadow DOM. |
| Context | AppConfig and Wippy packages | Routing, API access, and theme data arrive through supported packages. |

The presence of source, a successful build, or a valid registry entry does not prove the next stage. Verify each boundary.



## Pages


A `view.page` runs through one of two engines: a legacy `about:srcdoc` iframe or
a Web Fragment. The global `hostConfig.renderEngine` setting selects the
baseline; a page's `wippy.renderEngine` can follow it, opt out to `iframe`, or
request `fragment` when the deployment supports it. Application code stays
engine-agnostic. In neither engine is browser location the supported child-route
contract. Use AppConfig and `@wippy-fe/router`; the package handles Wippy route
integration.

The `iframe` CSS injection currently provides default themed scrollbar styling. Its name is historical and broader than its present purpose. Keep it enabled for scrollbar consistency; do not describe it as a layout reset.



## Web components


A `view.component` runs in the host document and normally owns a shadow root. CSS selectors do not cascade through a shadow boundary. The Web Host may deliver approved stylesheets and facade CSS into that root according to component configuration.

CSS variable inheritance and stylesheet injection are different mechanisms:

- Public inherited variables can cross the host-to-shadow boundary.
- Selector rules affect a shadow root only when delivered into that root.
- Delivery does not make an arbitrary selector a portable API.



## Theme and overlays


The facade supplies the PrimeVue theme. Shared `.p-*` rules in facade `custom_css` are valid theme implementation and may be global when intended for host and children. Use `.wippy-host-app` only for host-specific chrome.

Theme mode is AppConfig state, not a CSS-class API. Applications, components,
fixtures, and browser tests switch mode with
`host.setThemeMode('auto' | 'light' | 'dark')` from `@wippy-fe/proxy`, then wait
for `@theme` and verify `host.getThemeMode()`. AppConfig carries the change
through the host-to-child transport. The host updates its document,
re-broadcasts AppConfig to live iframe and Web Fragment page realms, and mirrors
the mode into web-component roots.
Never force `w-theme-dark` or `w-theme-light` classes directly.

PrimeVue overlays may be teleported. Verify the actual overlay root in the top document, iframe documents, and recursively discovered shadow roots. Do not assume generic PrimeVue placement.



## Runtime debugging order


1. Confirm the backend is listening.
2. Inspect backend logs for unexpected 5xx responses.
3. Confirm the registry owner and served asset URL.
4. Confirm the exact package build emitted that asset.
5. Load the host root before navigating through the SPA when direct deep links are unsupported.
6. Inspect console and network errors after navigation and interaction.
7. For theme scenarios, call the public proxy theme method, observe `@theme`,
   and verify `host.getThemeMode()` before accepting a screenshot.



## Navigation

Previous: "Frontend Contract: Start Here" (frontend/overview)
Next: "Portable UI Contract" (frontend/portable-ui-contract)