feat!: composition builder — JSON PressTree replaces the dynamic-zone mechanism

[odenirdev]

Composition builder — a JSON PressTree replaces the dynamic-zone mechanism engine-wide

Per-page layout root (header/footer/children slots), rows with 1–4 ratio-bound columns, full recursion, adopter custom-* blocks anywhere. Stored via one plugin::press-cms.builder JSON custom field; a structural tree-editor drives it in the admin.

BREAKING (wire + palette + API), no data migration (pre-release). 25 commits, executed task-by-task from docs/superpowers/plans/2026-07-20-composition-builder.md.

Highlights

• Storage: page.body (full PressTree) and site-setting.pageDefaults ({header,footer} slots) are JSON custom fields; the page-body + chrome Dynamic Zones and dz-populate are gone.
• @ogs-tech/press-shared is now a published runtime dependency: it ships the tree types + the sanitizing validatePressTree/validateNodeArray validators (cms bundles into dist; web depends + host transpiles). Strict-write (cms lifecycle rejects errors OR warnings) / tolerant-read (web sanitizes).
• Palette: new preset-molecule.link (label/page/url/newTab) referenced by button/hero/cta/navbar; nav-item/molecule.column/organism.columns retired. Text atoms store curated plain text (content: text) — the Strapi blocks AST leaves the wire. preset-layout.{container,row,column} descriptors drive the builder's layout forms.
• Serve-time hydration: media {assetId} → url/dims, page {documentId} → slug — resolved server-side (rename-safe internal links, no populate depth to fight), batched one query pair per request.
• Web: TreeRenderer (<header>/<main>/<footer> shell) replaces BlockRenderer; PressLink/resolveLink is the one link resolver (dangerous-protocol-safe); prose rail rescoped to direct <main> children; PageBody generates as PressTree; PressPageRef added; HeaderBlocks/FooterBlocks unions gone. Block-override contract components={{ 'preset-organism.hero': MyHero }} unchanged.

Automated verification (all green)

• pnpm build 6/6 incl. the playground Next build (SSG 3/3)
• pnpm -r test — web 260, cms 67, cli 29, shared 11
• typechecks clean (shared/cli/web + cms test:ts:back/test:ts:front)
• pnpm pack:check exit 0 — no *.test.ts in any tarball

Plan gaps caught & fixed during execution

• Batched hydratePageDocs to one query pair (was a plan-mandated N+1 on the unpaginated /pages route) + added serve-hydrated.test.ts.
• Moved press-shared devDeps→deps in web (Decision 3 gap); host transpiles it.
• footer.tsx inline-typed after ResolvedChromeFooter deletion (Task 14 migrated navbar but not footer).
• publish-readiness made target-aware (press-shared now published; workspace: allowed to co-published targets).
• Dropped files allowlist from press-shared so .npmignore keeps tests out of the tarball (surfaced by pack:check).
• Generator keys Page.body off type==='customField' alone (serialize strips the id) — production-shape guard test added.

Manual review checklist (not covered by automated tests — please verify on pnpm dev)

• /api/press/schema has tree:{version:1}; /api/pages/home body.version===1, hero image carries a hydrated url, navbar pageDefaults.header item has page:{documentId,slug:"home"}.
• localhost:3000 renders navbar / hero+image / prose atoms at ~72ch / the recursive 50-50 row / cta / callout / footer.
• Admin Composition field: add a paragraph in a column → Save → change appears (≤60s ISR). Pick a hero image via the media dialog (if the dialog key mismatches, the assetId fallback input must show).
• Site Settings pageDefaults slots editor; emptying header → inheriting pages render bare.
• CSS: prose-rail direct-child rescope, cell verticalAlign center/end, no main[data-press-stack] ↔ organism margin-block double-gap.

Known cosmetic note

The playground regen changed the cms Strapi uuid (the plan expected it preserved) — harmless dev instance id; can restore on request.

🤖 Generated with Claude Code

[odenirdev]

🧱 Increment pushed: Free Column Spans (PRESS_TREE_VERSION 1 → 2)

This branch now carries a second breaking feature on top of the composition builder: the closed RowNode.ratio enum is replaced by a free, per-breakpoint ColumnNode.span ({ base; md?; lg? }, 1–12 tracks, mobile-first), edited in the admin builder. Commits f38c581..c3f333d (8 feature commits + 1 doc-fix), one per plan task.

Plan: docs/superpowers/plans/2026-07-22-free-column-spans.md · Spec: docs/superpowers/specs/2026-07-22-free-column-spans-design.md

What changed (5 layers)

Layer	Change
@ogs-tech/press-shared	PRESS_TREE_VERSION = 2; Span = number + ColumnSpan; ColumnNode.span; RowNode.ratio/Ratio/MAX_ROW_COLUMNS removed; validator sanitizes malformed spans (default { base: 12 } + warn), no wire column cap
@ogs-tech/press-web	spanFor(column) is now a passthrough (column.span as Responsive<Span>); RATIO_SPANS/Ratio re-export gone; primitives + theme.css untouched
@ogs-tech/press-cms admin	Builder: per-column base/md/lg span selects + read-only 12-track preview bar + Base/md/lg tier toggle + per-tier total badge (danger at >12); MAX_COLUMNS 4 → 12; setColumnSpan/effectiveSpan
@ogs-tech/press-cms server	preset-layout.row descriptor drops ratio; /api/press/schema serves tree.version: 2 (no code change — reads the constant)
@ogs-tech/create-press	Seed emits v2 spanned columns; generated PresetLayoutRow drops ratio?

Quality gate (all green)

• Build: pnpm build 6/6 turbo tasks incl. playground Next build + SSG
• Tests: 374 passing — shared 15 · cli 28 · web 259 · cms 72
• Typechecks: shared / web / cli + cms test:ts:back + cms test:ts:front all clean
  (note: pnpm -r typecheck skips cms and strapi-plugin build exits 0 even on admin type errors — the real admin gate is test:ts:front, run explicitly)

Whole-branch review (this increment): Ready to merge — Yes

0 Critical, 0 Important. Independently verified: the spanFor cast against the real <Column> Responsive<Span> prop, the builder-only column cap (validator has only < 1), and that sanitizeSpan upholds the strict-write/tolerant-read split (malformed span → warning, never nulls the tree). Remaining findings are Minor/cosmetic; one stale comment already fixed in c3f333d.

⚠️ Reviewer / merge precondition — manual smoke test

No data migration (pre-release, authorized): a v1-seeded DB reads back empty until reseeded. Before merging, reset + reboot the dogfood:

rm -f apps/playground/packages/cms/.tmp/data.db && pnpm dev

Confirm: schema.tree.version = 2; home renders the spanned demo row (image | paragraph, 50/50 desktop / stacked mobile); admin Composition field shows the span selects + 12-track preview + tier toggle + badge.

Changeset

shared / web / cms → major; create-press → patch.