Skip to Content
Docs

Pages Catalog

Puck-based page editor for global public and organization member channels.

Overview

Yayaw provides page management at:

  • /dashboard/content/pages

The dashboard flow is split into:

  • the pages list, a dashboard screen (dashboard.content.pages, see Pages list)

  • a dedicated page editor route (/dashboard/content/pages/[scope]/[slug])

Related docs:

Pages are composed with these node families:

  • stack: layout containers

  • component: direct component references for advanced composition

  • section: reusable catalog section references resolved to the latest publication

  • generated_section: recipe-backed generated sections, including seeded layout sections such as the public home header/footer; AI-generated content sections are promoted to reusable section references on save

Pages list

/dashboard/content/pages (route permission page:list) is a dashboard screen: a full-page table on the system:pages source (see Dashboard). An organization that customizes its screens can change the table's default view, but the table always stays.

  • Who sees which pages: global pages with the global page read, list or manage permission, the active organization's pages with page read, list or manage there, never another organization's. Whether a person may change a page is page:manage in its scope (global, or the organization); every action checks it again on the server.

  • Columns: name, path, scope, channel, status (a live page with unpublished changes reads "Changes · published version live") and the last update; the slug, the publication status, the creation day and the editor link can be shown. Clicking a row opens the page in its editor.

  • Views: the screen's own view (all pages, the last updated first, 20 a page), then the work queues Drafts to review, Changes to publish, Published pages and Archived pages, then saved views. Any of them can be a person's favorite, and saved views can be shared with the organization.

  • Modes: table, list, a kanban by status (cards cannot be dragged) and charts.

  • Search and order: the search reads the name, slug and path; names sort as people read them ("Page 2" before "Page 10"); a page holds at most 100 rows.

  • Actions: Create page (for whoever may manage pages globally or in the organization) asks for a name, a scope, the organization's visibility (members only, or one of its public domains) and a path, then opens the editor. For a selection: Publish selected reviews the exact revisions before publishing them, Archive selected archives after a confirmation, the bulk edit sets the search engine settings (noindex, nofollow) as new drafts, and deletion removes the pages the person may delete and names the others. A row can be deleted where the person may change it.

CMS Role

Pages are the final composition layer of the CMS. They should arrange layout, SEO metadata, section references, component references, data bindings, and media bindings. They should not become the long-term source of truth for repeated content such as navigation menus, shared offers, reusable proof blocks, or organization assets.

Use sections for reusable page units, CMS data for shared structured values, media for binary assets, and design tokens for public visual theming.

Document Contract

Pages use a native Puck document contract:

  • PuckPageDocumentV1

  • location: src/lib/shared/pages/puck-document.ts

Revision persistence remains in existing tables, and ui_page_revisions.definition stores the versioned Puck document as the source of truth.

The runtime conversion emits PageSectionNodeV1 for reusable sections. Ordinary pages store a stable section id/slug and follow the latest published section revision. A section node can additionally carry a sectionRevisionId pin, which publication validation checks against that exact section revision.

The document root also stores localized page settings:

  • titleByLocale

  • seo.seoTitleByLocale

  • seo.metaDescriptionByLocale

  • seo.socialTitleByLocale

  • seo.socialDescriptionByLocale

  • seo.socialImageUrl

  • seo.canonicalUrl

  • seo.noIndex / seo.noFollow

Registry metadata remains useful for catalog summaries, but the published runtime uses the document root for public SEO metadata.

PageStack owns three explicit page-layout decisions:

  • container selects the tokenized contained width or a full-width body

  • gap sets the root section rhythm

  • sectionFrame is "token" for the shared public section wrapper and "none" when art-directed sections own their outer spacing and layering

yayaw_cms_page_draft expresses the same contract as layout.bodyWidth, layout.sectionGap, and layout.sectionFrame. The draft compiler maps these values to the root stack instead of forcing every designed page into the same contained, uniformly framed silhouette.

Older contextual drafts may still store a legacy designProof in their immutable revision document. No new proof is issued, and generic save boundaries strip a caller-supplied designProof.

Global page revisions can also carry an optional root.props.designTokens payload. yayaw_cms_page_draft exposes the same layer as designTokens; when it is omitted, the page inherits the effective public theme. A non-null payload is versioned, supports separate light/dark maps (every light color needs a dark value), and accepts only semantic color roles plus approved font-sans and font-serif stacks. Layout tokens, shadows, mono fonts, arbitrary CSS, URLs, and unregistered font families are rejected. Page design tokens are allowed on global public pages only. Changing the layer creates a new immutable revision, and yayaw_pages_publish validates it again before publication.

New draft revisions of an existing page use pageSlug with expectedRevisionId on yayaw_cms_page_draft, or yayaw_pages_save_draft with expectedRevisionId. Both use optimistic locking, so a concurrent or external edit is rejected instead of being silently overwritten.

Channels and Scope

Pages support two scopes/channels:

  • global (global_public)

  • organization (org_members for member-only pages)

  • organization (org_public for public pages served from verified custom domains)

Runtime routes:

  • global public home page: /[locale]

  • global public pages: /[locale]/[...slug]

  • organization member pages: /[locale]/o/[orgSlug]/[[...slug]]

  • organization public pages: verified custom domain + /[locale]/[[...slug]]

Organization member page runtime requires membership. Organization public pages do not require membership, but only render when the request host matches a verified organization_public_domains row. Unknown custom hosts return 404 instead of falling back to the global Yayaw site. Public organization pages can optionally target one organization public domain; when a target is set, that page only resolves on that host. Untargeted public organization pages remain available on every verified public domain for the organization. Page paths are explicit route settings, so an organization public page can use / for the custom-domain homepage instead of inheriting a path from the page name.

Section visibility:

  • global pages: built-in + global sections

  • organization pages: built-in + global + same-organization sections

Dashboard Editing UX

Editor UX is direct Puck + shadcn:

  • real-time local editing in Puck

  • autosave with debounce

  • serialized draft saves so stale autosave completions cannot overwrite newer state

  • a locale switch based on src/config/i18n.config.ts

  • route settings for updating the page path, organization visibility channel, and public-domain target after creation

  • page-level SEO fields in the inspector

  • image/media binding controls that select existing organization media assets or generate new WebP assets with OpenAI

  • global data binding controls that bind a complete published field from /dashboard/content/data

  • explicit publish/archive lifecycle

  • read-only mode for users without manage permission

The insert palette groups page elements as:

  • Built-in / Intégrés: Header, Footer

  • Sections: published global sections plus relevant organization sections

  • Components: direct component references

  • Layout / Mise en page: PageStack

The PageStack inspector exposes contained/full width, section gap, and shared section-frame behavior. Existing documents normalize to sectionFrame: "token"; disabling it is an explicit art-direction decision.

Built-in section instances expose no editable props in the page inspector. Section content is edited from the source section catalog, not duplicated per page.

Generated section recipes support header and footer variants in addition to content sections. Current content variants are hero, immersive_hero, legal, data_insights, value_grid, feature_split, system_map, mcp_console, proof, signal_wall, and cta.

Header and footer recipes use itemsJson for menu links, submenu groups, theme toggles, language toggles, and user menus. Seeded Header/Footer page sections bind those props to header-menu/main and footer-menu/main CMS data, with the same JSON contract as fallback.

Toolbar state exposes autosave lifecycle:

  • saving

  • saved

  • error

  • conflict

Autosave and Concurrency

Draft saves use optimistic locking:

  • saveDraftPageAction requires baseRevisionId

  • stale base revision returns conflict

  • successful saves return the server-canonical Puck document so the editor can adopt normalized section IDs and default bindings without dirty-state loops

  • no server-side operation rebase and no automatic merge

Conflict handling strategy:

  • user reloads latest draft explicitly from the conflict banner

  • user reapplies desired edits in current revision context

Runtime and Validation

Published runtime resolves from the stored Puck document directly.

Server runtime path:

  • loads published revision document from ui_page_revisions.definition

  • normalizes Puck document

  • converts to validated runtime definition

  • resolves published section references through ui_section_publications, using the current section ID first and then the scoped slug/slug fallback for older page revisions with stale IDs

  • renders resolved runtime preview tree

  • removes PublicPageSectionFrame around body sections only when their owning stack declares sectionFrame: "none"

  • applies a revision-owned global-page token layer through the same scoped wrapper for immutable draft previews and published rendering

  • resolves localized metadata for generateMetadata

The dashboard Puck canvas round-trips revision-owned page tokens but does not apply them in version 1. Use the immutable preview, not the authoring canvas, for visual proof and review of a page-specific palette or font direction.

Dynamic public routes expose SEO metadata through:

  • /[locale]/page.tsx

  • /[locale]/[...slug]/page.tsx

  • /[locale]/o/[orgSlug]/[[...slug]]/page.tsx

Global public pages also feed Google Search discovery through:

  • /robots.txt, which allows public content while excluding API, analytics ingest, dashboard, auth, maintenance, and organization-member paths

  • /sitemap.xml, which lists every published global page for every configured locale, includes hreflang alternates, and skips pages marked noIndex

  • site-level JSON-LD for the Yayaw organization and website

Organization-member pages are protected by membership checks and emit noindex metadata even when a page has its own SEO fields. For generative AI search, keep page content people-first and avoid relying on special machine-only files as a ranking lever; llms.txt remains documentation-oriented, not a Google Search optimization path.

Organization-public pages use the request host for canonical URLs, hreflang alternates, robots, sitemap entries, Open Graph URLs, and JSON-LD. Custom hosts are public-only: dashboard, auth, API, docs, ingest, and /o/* surfaces are blocked at proxy level. Verified custom hosts also resolve localized page content from the URL locale prefix and apply the owning organization's public theme and design-token overrides.

Organization Public Domains

Organization custom domains are stored in organization_public_domains and managed from organization settings or MCP. A domain belongs to exactly one organization, can be marked primary once verified, and stores provider status, TXT verification challenges, recommended CNAME/A records, and last check timestamp. The legacy vercel_* columns are still used for compatibility, but the runtime treats the row as the generic public-domain verification snapshot.

The page registry stores an optional public_domain_id for org_public pages. The dashboard creation and editor route-settings dialogs show the active organization's non-archived public domains, defaulting to the primary verified domain when available. Runtime host resolution filters domain-targeted pages by the matched custom-domain row while keeping legacy untargeted pages visible on all verified organization public domains.

PUBLIC_DOMAIN_PROVIDER=vercel uses the Vercel project-domain API to add and verify domains. PUBLIC_DOMAIN_PROVIDER=manual-dns generates a TXT ownership challenge and shows CNAME/A hints from PUBLIC_DOMAIN_CNAME_TARGET and PUBLIC_DOMAIN_IPV4_TARGETS; operators configure DNS and ingress outside the app, then re-check the domain. Publishing page content stays DB-driven and does not redeploy the hosting provider.

Publish is blocked when diagnostics contain error severity.

Seeded Home Page

bun run seed creates a global public Home page at path / when no published home page exists yet. The seeded document is a normal PuckPageDocumentV1 with:

  • generated header and footer sections backed by the CMS singleton entries header-menu/main and footer-menu/main

  • localized English/French page copy and SEO metadata

  • a content stack composed of generated hero, value grid, feature split, and CTA sections

The seed is intentionally non-destructive. Once a home page is already published, later seed runs keep the current published revision so Page Builder edits are not overwritten.

The docs route (/[locale]/docs) uses the same runtime header and footer wrappers as the public layout. These wrappers read the editable CMS slots for the clickable brand, center navigation, and right-side public mini menus while leaving the Fumadocs content layout in charge of the docs sidebar and table of contents.

Seeded Marketing Pages

bun run seed also creates Yayaw launch pages through the same page catalog storage. Their page shells use the generated Header/Footer variants bound to global menu data, while the page body remains generated-section content:

  • / is the published public home page for the source-owned SaaS codebase.

  • /codebase is the published sales page for ownership and architecture.

  • /pricing is the published offer page for lifetime codebase access.

The same seed publishes the global data used by those pages, including sales-offer/main and billing-product-content/pro-lifetime, so offer copy can stay editable while product names, prices, Stripe IDs, and checkout state remain resolved from the billing catalog.

The seed creates missing pages and can publish a newer revision when a page is still owned by the same seed key and its seedVersion changes. Existing Page Builder pages that are not seed-owned keep their current publication state and latest revisions.

AI Page Builder

Pages are generated by the site generation (src/lib/server/services/site-design): a site brief, three art directions, then per page a plan, its texts, the composition, a rendered review and variants. Each step is its own model call with its own tools, run by the orchestrator on the queue PAGE_AI_QUEUE_DRIVER names (direct locally, db-worker in production with bun run worker:page-ai; vercel-queue only when set explicitly). Tasks and their progress live in site_design_tasks, the design documents in site_design_documents.

In the editor, the AI panel is the assistant (AiChatPanel, surface page): it reads the open page through the editor's tools and changes it through the audited site generation tools (yayaw_site_generate, yayaw_section_regenerate, yayaw_section_variants_propose, yayaw_page_review…). The section menu and the command palette reach the same actions. An organization with only an OpenAI key runs the same pipeline through openai-turn.ts.

The former single-call generator and its /api/ai/pages/* routes are gone. ui_page_ai_runs and ui_page_ai_run_events keep its past runs for the AI runs history screen; nothing writes them anymore.

Data Model

Page persistence tables:

  • ui_page_registry_items

  • ui_page_revisions

  • ui_page_publications

  • ui_page_ai_runs

  • ui_page_ai_run_events

Reusable sections are stored separately in:

  • ui_section_registry_items

  • ui_section_revisions

  • ui_section_publications

Page constraints remain unchanged:

  • unique (scope, organization_id, slug)

  • unique (scope, organization_id, path)

  • immutable revisions with hash dedupe

  • one publication row per registry item

Server APIs

Page actions live in:

  • src/lib/server/actions/pages/pages-catalog-actions.ts

Current actions:

  • getPagesCatalogWorkspaceAction (what the pages list's person may create and change, and the organization's public domains for the create dialog)

  • openPageForEditingAction

  • createPageAction

  • updatePageDefinitionJsonAction

  • saveDraftPageAction

  • publishPageAction

  • archivePageAction

The pages list's rows come from the system:pages screen source, paged, sorted and searched in SQL. Its table (src/blocks/dashboard/screens/sources/pages-extension.tsx) uses Yayaw Table custom bulk actions for the selected-row lifecycle shortcuts:

  • publish selected pages through publishPageAction, after a review of the exact revisions

  • archive selected pages through archivePageAction

  • delete one page through deletePageByIdAction, a selection through deletePagesBulkAction

  • save the search engine settings of a selection through saveDraftPageAction

Section availability for the page builder comes from:

  • listAvailableSectionsForPageAction

  • listAvailableSectionsForPage

Image generation for page media fields is handled by the shared media image asset service used by both the media picker and Page AI. Generated images use the configured OpenAI image model, default to gpt-image-1.5, and follow the same organization permissions, quotas, object storage upload, and media_assets persistence path as manual uploads. The media picker displays stored thumbnails when available, while bindings keep the original publicUrl so rendered pages still use the source asset.

Published global data fields are exposed to the page editor as binding references. Runtime page rendering resolves global_data_field and global_data_query bindings from the published global data cache. Text bindings also resolve namespaced CMS variable tokens such as {site.name}, {organization.name}, and {data.global.header-menu.main.brand_label}. Missing tokens remain unchanged.

applyPageOperationsAction has been removed.

Validation

Useful checks after page catalog changes:

bun test src/lib/shared/pages/puck-document.test.ts
bun test src/lib/server/services/pages/page-definition-schema.test.ts
bun test src/lib/server/services/pages/page-definition-runtime.test.ts
bun test src/lib/server/services/site-design/orchestrator.test.ts
bun run check
bunx tsc --noEmit

ACL Baseline

Resource: page

Recommended organization policies:

  • member: page:list, page:read

  • manager/admin: page:manage

  • super admin: global page:manage

The dashboard, the page server actions and the MCP page tools decide with can() on page alone, in the organization scope for organization pages and without scope for global pages. The pages list shows global pages to holders of a global page read, list or manage policy, and only managers change them. A Better Auth member role string, owner included, never grants page access: a member without a group holding a page policy is refused.