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 — 47 production blocks in a single first-party UI pack, @pwpack/phiwebs/ui, spanning 7 categories (text, media, layout, panel, control, data, form), plus custom blocks via pwpack. Capabilities ship separately in the @pwpack/phiwebs/capabilities pack. 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 4: platform/persistence, platform/entities, platform/navigation, platform/interaction. 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 4 canonical capabilities (auth, analytics, seo, i18n, etc. listed in older docs have since been retired):

Capability	Adds
`platform/persistence`	Data fetch + cache, client state, binding config.
`platform/entities`	Tenant data model, CRUD, lifecycle.
`platform/navigation`	Client-side routing between Surfaces.
`platform/interaction`	Event-driven rules: triggers + actions wired into Surface events.

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/interaction (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