@commonpub/layer 0.23.3 → 0.25.0

package/README.md

@@ -27,7 +27,7 @@ export default defineCommonPubConfig({
   instance: {
     name: 'My Community',
     domain: 'example.com',
-    contentTypes: ['project', 'article', 'blog', 'explainer'],
+    contentTypes: ['project', 'blog', 'explainer'],
   },
   features: {
     content: true,
@@ -38,34 +38,63 @@ export default defineCommonPubConfig({
     admin: true,
   },
   auth: {
-    methods: ['email'],
+    emailPassword: true,
   },
 });
 ```
 
-Create `server/utils/config.ts` to load the config on the server side. See `apps/shell/server/utils/config.ts` for a complete example with environment variable overrides.
+> `article` is a deprecated alias that normalises to `blog` on write (session 116); use `blog`, `project`, or `explainer` for new content (CLAUDE.md rule #6).
+
+Create `server/utils/config.ts` to load the config on the server side. See `apps/reference/server/utils/config.ts` for a complete example with environment variable overrides.
 
 ## What's Included
 
-### Pages (70+ routes)
+### Pages (90 routes)
+
+Content CRUD (projects/blogs/explainers), hub feeds (community/product/company), learning paths, docs sites, contests, events, messages, notifications, search, user profiles, federation, **admin panel** (users, content, reports, settings, theme editor at `/admin/theme/edit/[id]`, layout editor at `/admin/layouts/[id]`), and more.
+
+### Components (132)
+
+Content editor (`CpubEditor`), content cards, author rows, comment sections, engagement bars, federation UI, notification items, message threads, **21 block renderers** under `components/blocks/` (`BlockHeadingView`, `BlockCalloutView`, `BlockEmbedView`, `BlockMarkdownView`, `BlockGalleryView`, etc. — all `*View` suffixed), homepage section renderers (`HeroSection`, etc.), the **layout-editor admin chrome** (`AdminLayoutsToolbar`, `AdminLayoutsCanvas`, `AdminLayoutsPalette`, `AdminLayoutsInspector`, `AdminLayoutsConflictModal`), and the `<LayoutSlot>` renderer that arranges existing components per the layout engine.
+
+### Composables (33)
+
+Highlights — see `layers/base/composables/*.ts` for the full set:
 
-Content CRUD, hub feeds, learning paths, docs sites, admin panel, federation management, user profiles, messaging, notifications, search, and more.
+| Composable | Purpose |
+|---|---|
+| `useAuth` | Better Auth session + identity |
+| `useFeatures` | Reactive feature-flag lookup |
+| `useContentSave` / `usePublishValidation` | Save lifecycle for blocks-based content + pre-publish validation |
+| `useEngagement` / `useRealtimeCounts` | Likes, comments, bookmarks + realtime counters |
+| `useFederation` / `useMirrorContent` | AP discovery + mirrored content |
+| `useMessages` / `useNotifications` | Realtime SSE streams |
+| `useTheme` / `useThemeAdmin` | Dark/light + branded theme switch (cookie-persisted, no flash) + admin theme editor |
+| `useAdminSidebar` | Desktop sidebar collapse + mobile drawer (session 161) |
+| `useEditorChrome` | Layout-editor palette + inspector visibility (session 161) |
+| `useLayoutEditor` / `useLayoutAutoSave` | Layout draft state, single-flight save, conflict throttle, pagehide beacon, version-counter dirty (sessions 160-162) |
+| `useLayout` | Public layout resolution via `<LayoutSlot>` |
+| `useMarkdownImport` / `useSanitize` | Markdown ingest + HTML/iframe sanitization |
+| `useFocusTrap` / `useToast` / `useApiError` | Accessibility + UX utilities |
 
-### Components (100+)
+The TipTap block editor itself lives in `@commonpub/editor` (composable `useBlockEditor` is imported from there, not declared in the layer).
 
-Content editor (`CpubEditor`), content cards, author rows, comment sections, engagement bars, federation UI, notification items, message threads, block renderers, and more.
+### Server (~300 Nitro API routes)
 
-### Composables (19)
+API routes for all CommonPub features, auth middleware (`requireAdmin`, `requireFeature`), federation endpoints (Fedify-mounted), per-feature audit logging (`cpub.audit.*`), layout-engine CRUD at `/api/admin/layouts/*` (gated on `features.admin` + `features.layoutEngine`), and Nitro plugins for identity startup + feature-flag override.
 
-`useAuth`, `useFeatures`, `useBlockEditor`, `useContentSave`, `useEngagement`, `useFederation`, `useMessages`, `useNotifications`, `useTheme`, and more.
+### Layout engine + section registry
 
-### Server
+The layout engine ships a 12-column zone/row/section model with a section registry at `layers/base/sections/registry.ts`:
 
-API routes for all CommonPub features, auth middleware, federation endpoints, and Nitro plugins.
+- **17 built-in sections** (`hero`, `heading`, `paragraph`, `image`, `content-feed`, `cta`, `learning`, `divider`, etc.). Each is a `SectionDefinition` pointing at an EXISTING `Block*` or `Homepage*` component via `propMap` — the engine ARRANGES, it doesn't render parallel renderers (see `feedback-reuse-existing-components`).
+- **Per-section Zod schemas** in `@commonpub/schema/src/sectionConfigs.ts` (session 161) — enforced server-side at the layout API boundary with `cpub.audit.layout.config-rejected` audit logging.
+- **Database tables** `layouts` / `layout_rows` / `layout_sections` / `layout_versions` (migration 0005). Layouts are instance-local — they NEVER federate via `@commonpub/protocol` per ADR 027.
+- **Editor** at `/admin/layouts` (list) + `/admin/layouts/[id]` (3-column shell: palette / canvas / inspector). Auto-save 1.5s debounce + If-Match optimistic concurrency + 3-option conflict modal + cascade-throttle banner.
 
 ### Theme
 
-CSS custom properties with 3 built-in themes (base, dark, generics). Consumer apps override with their own `theme.css`.
+CSS custom properties (`var(--*)` only — CLAUDE.md rule #3). Four user-selectable themes (`base`, `dark`, `agora`, `agora-dark`) plus structural CSS modules (`components.css`, `prose.css`, `editor-panels.css`, `forms.css`, `layouts.css`, `generics.css`). Admins can also create custom DB-stored themes via the theme editor at `/admin/theme` (session 154-156). Consumer apps override with their own `theme.css` and can shadow components for branding.
 
 ## Customization