A Blocklet can expose a Web-facing surface. The surface still has its own contract. Choose the layer that matches the work, then compose it inside the package.
AUP vs Web Device
| AUP | Web Device | |
|---|---|---|
| Question it answers | What is the semantic UI (pages, events, primitives)? | How is a Web site/content tree rendered? |
| Typical package paths | .aup/app.aup, .aup/pages/, .aup/man/ | pages/**/layout.aup, .web/, SEO atoms, .route/web |
| Authoring board | AUP | Web Device |
| First exercise | First AUP app | Build a first site |
| Checker focus | AUP pages / structure | Site lint, components, content space |
They can coexist in one package (e.g. minimal-app recipe: public web page + AUP app + agent). Coexistence does not make the two boards the same documentation.
How the Blocklet owns the surface
| Package concern | Example |
|---|---|
| Identity / DID | blocklet.yaml |
Which handler serves / | .route/web vs .route/app vs AUP default |
| Domains and pretty URL bindings | sites in blocklet.yaml |
| Instance data behind a page | AFS paths + bindings (see Data and AFS) |
Without a Web route declaration, a direct Blocklet URL may look for AUP entry (.aup/app.aup / app.json) rather than a static Web Device entry. The Web Device first-site guide spells out the minimal .route/web + .web/site.yaml + pages/index/layout.aup set.
Recipe and reference patterns
| Starting point | Surface emphasis |
|---|---|
arc blocklet create --recipe basic | Manifest only — add surfaces yourself |
--recipe minimal-app | One web page, AUP app, agent, settings |
--recipe blog / agent | AUP-oriented scaffolds |
| Web Device first-site guide | Hand-built minimal static site in a basic package |
hello-html (ARC tree) | Convention static HTML without blocklet.yaml (teaching sample) |
hello-declarative (ARC tree) | Minimal .aup/ JSON pages (teaching sample) |
did-space (ARC tree) | Dual surface: marketing .route/web + explorer AUP under /explorer |
Do not copy primitive catalogs here
| Need | Go to |
|---|---|
| AUP primitives / events / DSL | AUP board |
| Web components, themes, markdown embeds | Web Device board |
| Capability matrix for AUP/Web Device | AUP/Web Device maintenance matrices (not this board) |
This page only records composition points: routes, recipes, and package layout. When a primitive, component, or directive changes, update the owning board — not a fork of the catalog under Blocklets.
Local acceptance for surfaces
arc dsl validate .
arc blocklet check . --profile <matching-profile>
arc blocklet run .
# open printed URL — wide + narrow viewportA successful package build is not a substitute for opening the rendered page. See Check, build, and inspect and Test and diagnose.