Surface Composition Model

How blocks, surfaces, and capabilities combine. PhiCo composes against this model; nothing publishes without an accepted Receipt.

The simple model

PhiWebs uses a deliberately simple composition model:

blocks compose into surfaces enhanced by capabilities

No patterns. No templates. Just three concepts that combine naturally.

Composition hierarchy

Blocks — 45 production blocks across 4 first-party packs (UI, data, nav, forms), plus custom blocks via pwpack. Each block is a typed, manifest-described atom.
Surfaces — Reproducible runtime renders, materialised from a Receipt that PhiCo proposes and you accept.
Capabilities — Platform-level powers; canonical 5: platform/persistence, platform/entities, platform/navigation, platform/interaction, platform/input. Visual appearance is not a capability — it ships as a separate ui-appearance atom kind.

Block composition

Blocks nest to create structure. Layout blocks (container, grid) hold other blocks:

container
├── heading ("Features")
├── grid (3 columns)
│   ├── container (feature card)
│   │   ├── image (icon)
│   │   ├── heading ("Fast")
│   │   └── text ("Lightning speed...")
│   ├── container (feature card)
│   │   ├── image (icon)
│   │   ├── heading ("Secure")
│   │   └── text ("Enterprise grade...")
│   └── container (feature card)
│       ├── image (icon)
│       ├── heading ("Simple")
│       └── text ("No complexity...")

Surface nesting

Surfaces can contain other surfaces, enabling modular architecture:

Website (surface)
├── Header (surface)
│   └── Navigation blocks...
├── Page Content (surface)
│   └── Content blocks...
└── Footer (surface)
    └── Footer blocks...

Update the Header surface once, and all pages that include it update automatically.

Capabilities extension

Capabilities add powers to surfaces without changing their structure. The runtime resolves exactly 5 canonical capabilities per ADR-115 and ADR-122 (auth, analytics, seo, i18n, etc. listed in older docs were retired in ADR-094/095/110/116):

Capability	Pack	Adds
`platform/persistence`	`@pwpack/phiwebs/persistence`	Data fetch + cache, client state, binding config (ADR-124).
`platform/entities`	`@pwpack/phiwebs/entities`	Tenant data model, CRUD, lifecycle.
`platform/navigation`	`@pwpack/phiwebs/navigation`	Client-side routing between Surfaces.
`platform/interaction`	`@pwpack/phiwebs/interaction`	Event-driven rules: triggers + actions wired into Surface events.
`platform/input`	`@pwpack/phiwebs/input`	Form field state, validation, submission.

See the capabilities reference for the pack bundle model and per-plan entitlement matrix.

Starter surfaces

Pre-composed surfaces for common patterns: Hero Section, Hero with Image, Feature Grid, Two Column Content, Contact Form, Newsletter Signup, Image Gallery, CTA Banner, Footer.

Starters are just surfaces — you can copy, customize, and extend them freely.

Complete example

A landing page with full composition:

Landing Page (surface)
│
├── Blocks
│   ├── container (hero)
│   │   ├── heading (h1)
│   │   ├── text (subtitle)
│   │   └── button (CTA)
│   ├── container (features)
│   │   └── grid (3-col feature cards)
│   ├── container (testimonials)
│   │   └── grid (testimonial cards)
│   └── container (footer)
│       ├── grid (links)
│       └── text (copyright)
│
└── Capabilities
    ├── platform/persistence (page-load data fetch)
    ├── platform/navigation (anchor links + sub-Surface routing)
    └── platform/input (contact form validation + submit)

Why this model?

Simplicity — Three concepts to learn, infinite combinations possible.
Flexibility — No rigid templates; compose whatever you need.
Portability — Surfaces are data structures, not code; export anywhere.
Extensibility — Add capabilities without rebuilding surfaces.

Learn more

Blocks Capabilities