0270 — Builder architecture: one editor kernel, document kinds and collaboration levels

​

Context

Pages, forms, dashboards, email templates, menus, automations and pricing rules each had their own editor in the ADRs, some Pro, some free (0202 has since made every editor free code unlocked by an app entitlement). Separate editors would each rebuild selection, undo, drag and drop, preview, comments and publishing, and would drift apart. Co-editing with cursors is costly and only pays off on long free-form documents. The owner settled the architecture on 2026-10-21.

​

Decision

1. Every builder saves an L2 document (0110): data that references registered code, never code, markup, CSS or logic (0154). One format, one validator and one set of renderers, in @stackra/experience (0112).
2. Every builder document is a content type of @stackra/content (0116): draft, versions, publish, scheduled publish, i18n, SEO and permissions come from there.
3. The palette is code. Components and blocks are registered in code (@Block, panel Blocks.*) and published by the gen manifests (0109).
4. @stackra/builder (category experience) is the one editor kernel: selection, an inspector generated from each block’s Zod props, an undo and redo command stack, drag and drop, preview per device, locale and breakpoint, comments (@Commentable, 0225), the presence and co-edit binding, and the publish flow. Its surfaces are canvas, document (a block editor with slash commands), grid, tree and graph. It is separate from @stackra/experience so that render-only apps never load editor code.
5. @stackra/collaboration (category experience) is free, on @stackra/realtime: presence, cursors, the Yjs binding and snapshots. It implements 0225 RT2 and is gated by entitlement per 0202. The Pro-only @stackra-pro/collaboration listing is dropped.
6. Document kinds, surfaces and collaboration levels. Co-editing with cursors is only for long free-form documents; structured documents get presence and optimistic concurrency control (OCC).

   Kind	Surface	Drag and drop	Collaboration
   page, screen, app-shell	canvas	yes	full (Yjs co-edit, presence, cursors)
   post, article, help article	document	reorder	full
   form	field list and logic panel	reorder	presence + OCC
   dashboard	grid	yes	presence + OCC (data refreshes live; editing is not co-edited)
   email and notification template	document, email-safe blocks only; rendered by the node renderer	reorder	presence + OCC
   navigation and menus	tree	reorder	OCC
   automation (0122 layer 3)	step list or graph, with dry run	yes	presence + OCC
   pricing rules (0219)	block composer	no	OCC

7. New document kinds: app-shell (navigation, home, theme and branding, route-to-page mapping), screen (mobile) and email-template.
8. The page builder builds the app’s experience, never its data, rules or code. It builds pages, screens, the app shell and document slots in coded routes (@Route({ document })). It does not build data models (custom fields only; tenant content types stay later per 0116 decision 6), business rules or code. There are three levels: coded screens, coded screens with document slots, and fully document pages.
9. One studio app area in the console hosts every editor. Each kind is unlocked by an app entitlement (0202). This replaces the separate page-builder-and-forms app, the dashboard studio and the notifications editor.
10. No report builder. Reports are saved views (0271), @Report widgets (0163) and dashboards. There is no tenant SQL or pivot engine (0154).
11. Build order keeps 0112 X14, with the kernel landing before the first editor.
12. Package changes. @stackra/forms is dropped: coded forms use @stackra/ui/form (useSchemaForm), and the form builder is a document kind on @stackra/builder. @stackra/notifications is dropped: notifications is a service (@figentra/service-notifications) that owns delivery, preferences, the log and the in-app inbox, and direct email goes through the Mailer driver in @stackra/mail.
13. Forms can be multi-step. A form document may have steps, a progress indicator, conditional steps, save-and-resume of a draft submission, and a chip multi-select field. The @stackra/ui contract gains a Stepper. Onboarding wizards are form documents of this shape.

​

Consequences

• One editor to build, secure and test; each new kind is a surface configuration and a block set, not a new editor.
• Render-only apps stay small, because editor code lives only in @stackra/builder.
• Yjs runs only where it pays off; structured documents keep the simpler version check.
• The kernel is on the critical path: no editor ships before it.
• ADRs and docs that name @stackra/forms, @stackra/notifications or a Pro editor are stale and must point here.

​

Enforcement

planned — the experience validator refusing a document of a kind whose blocks are not registered; a bundle check that a render-only app does not depend on @stackra/builder; FORBIDDEN_DEPENDENCIES or the scaffold refusing new @stackra/forms and @stackra/notifications packages. Nothing checks this today.

​

Supersedes and sources

Supersedes: none. Amends: 0112, 0114, 0115, 0122, 0086, 0225, 0127, 0035, 0078, 0096, 0117, 0084, 0202, 0213 and 0223 (see the note above). Sources: owner decisions in chat, 2026-10-21 (builder architecture; D5 package amendments; multi-step forms from the screenshot review). Linear STA-274.