@marvalt/digivalt-core 0.2.32 → 0.2.33

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.33] - 2026-09-19
+
+### Added
+- **`docs/SEO-AIO.md`** — developer/AI playbook for DigiValt SEO plugin + env + prerender. Linked from `docs/README.md` and `SEO-PERFORMANCE.md`.
+
+**Publish/deploy:** publish **`@marvalt/digivalt-core@0.2.33`**. No required app code change; upgrade when you want the packaged handbook.
+
 ## [0.2.32] - 2026-09-18
 
 ### Added

package/README.md

@@ -30,7 +30,7 @@ The root package export remains as a thin compatibility layer for generator-focu
 
 - **Subpath:** `import { DigiValtRouteSeo, DigiValtSeoHead, JsonLd, buildPageJsonLd, ... } from '@marvalt/digivalt-core/seo'`
 - **Peer dependency:** `react-helmet-async` (v2+). Wrap the app in **`HelmetProvider`**.
-- **Env:** **`VITE_SEO_*`** site identity (`VITE_SEO_SITE_URL`, `VITE_SEO_SITE_NAME`, `VITE_SEO_DEFAULT_TITLE`, …). Per-URL fields come from WordPress **`digivalt_seo`**. See **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
+- **Env:** **`VITE_SEO_*`** site identity. Per-URL fields come from WordPress **`digivalt_seo`**. Playbook: **[docs/SEO-AIO.md](./docs/SEO-AIO.md)**. Env table / PageSpeed: **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
 - **Config:** `getSEOConfig()` / `getPerformanceConfig()` in `@marvalt/digivalt-core/config` read the same `VITE_*` values.
 
 ## Init Workflow

package/docs/README.md

@@ -7,7 +7,8 @@ Read these in order for DigiValt app setup, deploy, and SEO.
 | [ENVIRONMENT.md](./ENVIRONMENT.md) | Devs + DevOps | Env vars, `.env` model, Cloudflare secrets, React 19 install |
 | [AI-LOCAL-WORDPRESS-BOOTSTRAP.md](./AI-LOCAL-WORDPRESS-BOOTSTRAP.md) | Humans | Local WordPress handover runbook |
 | [AI-MASTER-PROMPT.md](./AI-MASTER-PROMPT.md) | AI tools | Vite + Cloudflare scaffold prompt |
-| [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) | Devs | `DigiValtRouteSeo`, sitemap, prerender, `VITE_SEO_*` |
+| [SEO-AIO.md](./SEO-AIO.md) | Devs + AI | End-to-end SEO/AIO: WP plugin, env, `DigiValtRouteSeo`, generate, prerender |
+| [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) | Devs | `VITE_SEO_*` table, sitemap XML, PageSpeed |
 | [PATH-MOUNT.md](./PATH-MOUNT.md) | Devs | Path mounts via digivalt-uworker + Vite `base` + `withBasePath` |
 | [CLOUDFLARE-STREAM.md](./CLOUDFLARE-STREAM.md) | Devs | Stream helpers + `CloudflareStreamPlayer` (`/media`) |
 | [SHORTCODES.md](./SHORTCODES.md) | Devs + editors | How WP shortcodes are parsed and merged; links to adapter docs |
@@ -20,7 +21,7 @@ Package root [README.md](../README.md) covers `digivalt-init`, generators, and e
 | Subpath | Use |
 |---------|-----|
 | `@marvalt/digivalt-core/generators` | Build-time static data (`generateAllData`) |
-| `@marvalt/digivalt-core/seo` | `DigiValtSeoHead`, JSON-LD helpers |
+| `@marvalt/digivalt-core/seo` | `DigiValtRouteSeo`, `DigiValtSeoHead`, JSON-LD helpers |
 | `@marvalt/digivalt-core/registry` | Page-body registry, `DigiValtWpPage`, providers |
 | `@marvalt/digivalt-core/integrations` | Browser-only: `DigiValtTracker`, `MauticTracking`, `ChatwootWidget` |
 | `@marvalt/digivalt-core/media` | Cloudflare Stream helpers + `CloudflareStreamPlayer` |

package/docs/SEO-AIO.md

@@ -0,0 +1,59 @@
+# SEO / AIO in DigiValt apps
+
+Playbook for **developers and AI agents** wiring `@marvalt/digivalt-core` with the **DigiValt SEO** WordPress plugin. Content-manager steps: `digivalt-collaboration-docs/DIGIVALT_SEO_AIO.md`. Env tables and PageSpeed: [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md). REST field list: WordPress plugin `digivalt-seo/README.md`.
+
+## What “good” looks like
+
+- **Site identity** in `VITE_SEO_*` (one set per frontend / Cloudflare project).
+- **Per-URL** overrides in WordPress `digivalt_seo` (pages, posts, public REST CPTs).
+- **Same HTML** for humans and crawlers: prerender snapshots, not user-agent cloaking, not Yoast.
+- Visible copy and JSON-LD stay in sync (same generate JSON).
+
+## Install
+
+| Piece | Action |
+|-------|--------|
+| WordPress | Activate **DigiValt SEO**. Editors get a meta box and a Dashboard widget. |
+| App | `@marvalt/digivalt-core` with `react-helmet-async`. `npx digivalt-init` for sitemap/robots Functions and `scripts/prerender-seo.ts`. |
+| PageSync | Plugin ≥ 1.1.2 if briefs should seed `_digivalt_seo_*` meta. |
+
+## Env vs WordPress
+
+Keep in env: `VITE_SEO_SITE_URL`, `SITE_NAME`, `DEFAULT_*`, Twitter/Facebook, verification, optional `VITE_SEO_ROUTE_PREFIXES`, `VITE_SEO_FRONT_PAGE_SLUG`, `VITE_PHPLIST_NEWSLETTER_ROUTE_BASE`.
+
+Never put per-page title/description in env.
+
+## App checklist
+
+```tsx
+import { DigiValtRouteSeo } from '@marvalt/digivalt-core/seo';
+
+<DigiValtRouteSeo pathname="/about" entity={page} />
+```
+
+- One instance per route. Pass the WordPress object from static JSON (`digivalt_seo` is already on it after generate).
+- Utility routes (`subscribe`, `preferences`, 404): `noindex` and **omit** from `sitemap-static-paths.json`.
+- Front page: app `/` + `VITE_SEO_FRONT_PAGE_SLUG` or WP Reading Settings `front_page`, never also `/<frontpage-slug>` in the sitemap.
+
+`resolvePageSeo` / `buildPageJsonLd` if you need props without the React helper.
+
+## Generate and deploy
+
+`generateAllData()` (including fixture mode) writes:
+
+- `public/sitemap-paths.json` — `{ urls: [{ path, lastmod?, image? }] }`
+- `public/seo-manifest.json` — titles, descriptions, JSON-LD, body HTML for snapshots
+
+Then `vite build` then `prerenderSeoHtml()` → `dist/index.html` and `dist/{path}/index.html`.
+
+Cloudflare Pages Functions serve `/sitemap.xml` and `/robots.txt`. Do not commit those as static files.
+
+CPT URLs other than pages are **opt-in**: `VITE_SEO_ROUTE_PREFIXES=eventbrite_event:/events,member:/members/profile`.
+
+## AI agents: do not
+
+- Do not add Yoast/Rank Math.
+- Do not serve different HTML to bots vs users.
+- Do not invent `changefreq` / `priority`.
+- Do not hand-edit `sitemap-paths.json` or `seo-manifest.json`.
+- Do not register DigiValt SEO fields as WordPress PHP shortcodes.

package/docs/SEO-PERFORMANCE.md

@@ -2,6 +2,8 @@
 
 This guide is for **Vite + React** apps that use DigiValt static generation. It complements WordPress content with **document metadata**, **structured data**, and **performance-minded image/font patterns**.
 
+**How the system fits together** (WP vs env, prerender, editor workflow): **[SEO-AIO.md](./SEO-AIO.md)**. Team handbook: `digivalt-collaboration-docs/DIGIVALT_SEO_AIO.md`.
+
 ## Prerequisites
 
 1. Install the peer dependency (required for `DigiValtSeoHead`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marvalt/digivalt-core",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "Core glue logic and shared context for DigiVAlt frontend applications",
   "license": "GPL-3.0-or-later",
   "main": "dist/index.cjs",