---
id: fragment.editor-layout-templates.001
freshvibe_way_version: v8
date: 2026-07-31 (Phase 7 — page builder)
last_rewritten: 2026-07-31 (new fragment, Phase 7)
---

# editor-layout-templates — pre-built region+module compositions (Phase 7 page-builder manual path)

## What it does

When the operator opens the templates panel (from the context menu on a page, or from the "+ Add" affordance next to the page list), they see 4 starter templates:

- **Cover / Hero** — 1 region, 1 group, heading + subheading + CTA button
- **3 Cards** — 1 region, 1 group (3-column), 3 info-box modules
- **Query List** — 1 region, 1 group, 1 heading + 3 list items (placeholder for query results at render time)
- **Image Gallery** — 1 region, 1 group, image carousel

Clicking a card inserts the full composition. The chrome refreshes the outline + navigator (so the new region shows up in the structure tree) and opens the inspector on the first module (so the operator can immediately edit fields).

## Why this is its own feature (cluster rule §3.9)

The templates fragment is a cluster of:
1. **4 starter templates** — `LAYOUT_TEMPLATES` constant; each is an `insert(pageId, anchorRegion, position)` function
2. **Render the templates panel** — `renderLayoutTemplates(container, {pageId, anchorRegion, onInsert?})`
3. **Programmatic insert** — `insertLayoutTemplate(templateId, pageId, anchorRegion)` for the AI composer
4. **Reuses the region-actions + palette primitives** — every insert goes through `addRegionRelative` + `addGroupToRegion` + `insertCanonicalModule`. The templates are pure compositions, no new store code.

Removing any one template breaks the "starter pack" promise. Removing the whole fragment means the operator has to build cover/3-cards/etc. from scratch.

## Inputs (public API)

- `LAYOUT_TEMPLATES` — array of 4 template definitions (id, label, description, icon, insert fn)
- `renderLayoutTemplates(container, {pageId, anchorRegion?, onInsert?})` — render the templates UI
- `insertLayoutTemplate(templateId, pageId, anchorRegion?)` — insert a template programmatically

## What this fragment does NOT do

- Does NOT create the page itself — the page must exist
- Does NOT pick a default region config — each template ships with its own
- Does NOT replace the AI composer — that's a separate fragment (Phase 4)
- Does NOT do template editing / "save my layout as a new template" — that's a future feature (operator can clone a region + edit, but not yet "save as template")

## Manual + AI paths (per pact §3.11)

This fragment is the **manual path** for "drop a starter layout into a page". The AI path is the AI composer (Phase 4, not yet built). Both call `insertLayoutTemplate(templateId, pageId, anchorRegion)`. The AI might compose the equivalent of a cover template from scratch via `addRegionRelative` + `addGroupToRegion` + `insertCanonicalModule` — same store calls, different trigger.

The templates panel UI explicitly mentions the AI path so the operator never wonders.

## Why only 4 templates?

The plan v2 §Phase 7 says "layout templates (cover, 3-cards, query-list, gallery, etc.)". The "etc." is intentional — we ship 4, get operator feedback, ship more. Each new template is a one-line addition to `LAYOUT_TEMPLATES`. Adding a template does NOT require a new fragment.

## Provenance

- Created 2026-07-31 12:42 BST by oscar-website-mavis (session 415655444668635)
- Per operator directive 2026-07-31 12:32 BST
- Per cross-thread agreement (bulletin b221) with Hopfan App (id 22)
- Per pact §3.11 and §3.14
- Depends on: `editor-region-actions` (addRegionRelative, addGroupToRegion) and `editor-palette` (insertCanonicalModule) — both shipped in this PR