# UCE Starter

`site/examples/uce-starter/` is a UCE-native port of the PHP `web-app-starter/`.

It keeps the PHP starter around as reference while mirroring the same broad structure:

- `index.uce` as the front controller
- `views/` for routed page content
- `components/` for reusable UI building blocks
- `themes/`, `js/`, and `img/` for theme templates and static assets

This port intentionally leans on UCE's component layer rather than treating components as a compatibility shim. The page shell, nav/footer chrome, theme switcher, dashboard blocks, workspace primitives, and marketing sections are all rendered through `component()`.

Theme rendering is split the same way as the PHP starter:

- `themes/common/page.blank.uce`
- `themes/common/page.json.uce`
- `themes/<theme>/page.html.uce`

Those page templates are the authoritative shell layer, and in the UCE port they are proper `COMPONENT(...)` units rather than standalone page entrypoints. `index.uce` owns the app-local router, captures the `main` fragment, then hands off to `themes/page.uce`. That component resolves `context.call["app"]["page_type"]` by checking `themes/<current-theme>/page.<page_type>.uce` first and then `themes/common/page.<page_type>.uce`, matching the PHP starter's page-layer flow without an extra shell implementation.

The router is intentionally normal UCE code instead of a runtime feature. It checks `views/<path>.uce`, then `views/<path>/index.uce`, then parent index handlers such as `views/workspace/index.uce` with the last segment stored as `context.call["route"]["param"]`. Matching view files are invoked with `component()`, and view files expose `COMPONENT(Request& context)` rather than `RENDER(Request& context)` because they are intended to render only through the central router. This gives the starter hierarchical/file-based routing while keeping policy in the app.

Starter-local web affordances live in `components/theme/web_affordances.uce`; currently this provides `COMPONENT:island` for progressive enhancement without adding global UCE runtime APIs. Component-specific CSS/JS is emitted by `ONCE(Request& context)` in the component unit that owns it, or by a small shared asset component when multiple sibling components need the same files. The router's 404 body is also a normal component at `components/basic/notfound.uce`, keeping page fragments out of the front controller.

The example uses query-string routing in the same style as the PHP starter, but the canonical public URL is the directory path because `index.uce` is reached through nginx's default index/try-file behavior. Links generated by the starter therefore target:

- `/examples/uce-starter/`
- `/examples/uce-starter/?page1`
- `/examples/uce-starter/?themes&theme=portal-dark`
- `/examples/uce-starter/?workspace/projects`

Direct requests to `/examples/uce-starter/index.uce` still work, but self-links are canonicalized back to `/examples/uce-starter/`.

The demo account pages use a small file-backed user store under `/tmp/uce-starter-data/` with session-based login state.
