@marvalt/digivalt-core 0.2.30 → 0.2.33

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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
+- WordPress **DigiValt SEO** field consumption: `resolvePageSeo`, `buildPageJsonLd`, `DigiValtRouteSeo`.
+- Sitemap v2 (`urls` + `lastmod` + optional image), PHPList paths, `VITE_SEO_ROUTE_PREFIXES`, frontend page paths (front page → `/`).
+- `generateSeoManifest` + `prerenderSeoHtml` for crawlable HTML snapshots.
+- Template **`functions/robots.txt.ts`** and **`scripts/prerender-seo.ts`**; `digivalt-init` wires prerender into `build` / `build:dev`.
+
+### Changed
+- `generateAllData` always refreshes sitemap and SEO manifest, including fixture mode.
+- Sitemap no longer uses CMS permalink pathnames.
+
+**Publish/deploy:** publish **`@marvalt/digivalt-core@0.2.32`**. Install WordPress **digivalt-seo** (and **wp-pagesync 1.1.2**). Redeploy apps after generate + prerender.
+
+## [0.2.31] - 2026-09-16
+
+### Added
+- **`@marvalt/digivalt-core/registry`** with `createContentRegistry()`, page-body-only `DigiValtWpPage`, and `DigiValtProviders`.
+- **`getAppChrome()`** from `/static` for app-owned Header/Footer menus and site identity.
+- `digivalt-init` warns without overwriting when a local `wpRegistry.tsx` / `createAppRegistry` is found.
+
+### Changed
+- Bumped adapter deps to current monorepo releases: **`@marvalt/wparser@^0.1.82`**, **`@marvalt/dstyler@^0.1.53`**, **`@marvalt/shcoder@^0.1.37`**, **`@marvalt/sadapter@^0.1.6`**, **`@marvalt/tadapter@^1.0.14`**.
+- Added optional `@tanstack/react-query` peer support for injected registry providers.
+- Reframed docs around user-owned Vite + Cloudflare Pages apps, app-owned chrome, and Cursor / Pencil / Claude Design. `VITE_IS_LOVABLE` remains a backwards-compatible fixture-mode alias.
+
+**Publish/deploy:** publish **`@marvalt/digivalt-core@0.2.31`** only. No WordPress plugin publish and no required app redeploy.
+
 ## [0.2.30] - 2026-08-26
 
 ### Added

package/GLOBAL-SHORTCODES.md

@@ -7,11 +7,11 @@ How shortcodes are wired (and adapter-specific guides after npm install):
 - `node_modules/@marvalt/plister/docs/SHORTCODES.md` — `[phplist_subscribe]`
 - `node_modules/@marvalt/wparser/docs/SHORTCODES.md` — parser / registry merge
 
-This document lists the shortcodes supported by `@marvalt/digivalt-core` in `src/utils/wpRegistry.tsx`.
+This document lists the shortcodes supported by `createContentRegistry()` from `@marvalt/digivalt-core/registry`.
 
 **Do not register these as WordPress PHP shortcodes.** They must remain literal text in REST/HTML so `@marvalt/wparser` can replace them with React components. Content editors type them into WordPress; the headless app renders them.
 
-Merge order in `createAppRegistry`: adapter handlers (`@marvalt/madapter`, `@marvalt/plister`) first, then Gravity Forms, popups, and `@marvalt/shcoder` CPT shortcodes.
+Merge order in `createContentRegistry`: adapter handlers (`@marvalt/madapter`, `@marvalt/plister`) plus core Gravity Forms and popup shortcodes. Apps can merge project-specific CPT handlers separately.
 
 ## Gravity Forms (core)
 
@@ -25,7 +25,7 @@ Merge order in `createAppRegistry`: adapter handlers (`@marvalt/madapter`, `@mar
 Handlers: `getMauticShortcodeHandlers()`. DigiValt core passes `renderForm` so the app `MauticForm` (static JSON + integration config) is used.
 
 - `[mautic_form id="1"]` — Render Mautic form inline. Optional `title`, `description`. `formId` is accepted as an alias of `id`.
-- `[popupbtn_mautic id="1" text="Contact Us"]` — Button that opens Mautic form in a popup (core-level; uses app Dialog/Button). Optional `title` for the popup heading.
+- `[popupbtn_mautic id="1" text="Contact Us"]` — Button that opens Mautic form in a package-local popup. Optional `title` for the popup heading.
 
 Standalone apps (no DigiValt core) can merge the same handlers:
 
@@ -61,9 +61,9 @@ import { getPhplistShortcodeHandlers } from '@marvalt/plister';
 Object.assign(registry.shortcodes, getPhplistShortcodeHandlers());
 ```
 
-## Member Shortcodes (`@marvalt/shcoder`)
+## Optional app-specific CPT shortcodes (`@marvalt/shcoder`)
 
-These are mapped in DigiValt core and rendered using `@marvalt/shcoder` components/hooks.
+These are available to apps that merge their own `@marvalt/shcoder` handlers; they are not part of the published content registry.
 
 - `[member_card id="123"]` — Single member profile.
 - `[member_cards tax="leadership" cols="3" image="true"]` — Member grid.
@@ -95,5 +95,5 @@ Legacy aliases still supported:
 
 - Popup button shortcodes (`popupbtn_mautic`, `popupbtn_gf`) are app/core-level mappings, not adapter-package shortcodes.
 - CPT dashboard widgets in `wp-custom-api-endpoints` list member/testimonial/event shortcodes only. Form shortcodes are documented here and in adapter package docs.
-- Attribute support can evolve with registry/component updates; treat `wpRegistry.tsx` as source of truth.
-- Apps that copied `wpRegistry.tsx` locally (via `digivalt-init`) must merge the adapter handlers (or recopy from this package) after upgrading madapter/plister/core.
+- Attribute support can evolve with registry/component updates; treat the published `/registry` docs and types as source of truth.
+- Existing apps with a local registry can keep it and merge or adopt `createContentRegistry()` on their schedule.

package/README.md

@@ -19,7 +19,8 @@ Prefer explicit subpath imports so Node/build-time code does not pull browser ru
 ```ts
 import { generateAllData } from '@marvalt/digivalt-core/generators';
 import { getIntegrationConfig } from '@marvalt/digivalt-core/config';
-import { loadWordPressData } from '@marvalt/digivalt-core/static';
+import { getAppChrome, loadWordPressData } from '@marvalt/digivalt-core/static';
+import { createContentRegistry, DigiValtProviders, DigiValtWpPage } from '@marvalt/digivalt-core/registry';
 import { gravityFormsService } from '@marvalt/digivalt-core/services';
 ```
 
@@ -27,14 +28,14 @@ The root package export remains as a thin compatibility layer for generator-focu
 
 ## SEO and PageSpeed
 
-- **Subpath:** `import { DigiValtSeoHead, JsonLd, buildEventJsonLd, ... } from '@marvalt/digivalt-core/seo'`
+- **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_*`** only (`VITE_SEO_SITE_URL`, `VITE_SEO_SITE_NAME`, `VITE_SEO_DEFAULT_TITLE`, …). 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
 
-Run `npx digivalt-init` inside a Vite/Lovable app root. The command now validates the target folder, inspects existing DigiVAlt wiring, and patches safe cases automatically.
+Run `npx digivalt-init` inside a Vite app root. The command validates the target folder, inspects existing DigiVAlt wiring, and patches safe cases automatically.
 
 Useful flags:
 
@@ -49,6 +50,7 @@ What init now does:
 - adds or updates `generate`, `build`, and `build:dev` scripts when the app is still on plain Vite wiring
 - refreshes `scripts/generate.ts` when it matches an older DigiVAlt-managed version
 - warns instead of overwriting custom build logic or custom generator scripts
+- warns when a local `wpRegistry.tsx` / `createAppRegistry` is present; use the published `/registry` helpers when practical
 - reports stale legacy workarounds such as alias-link scripts and old root package generator imports
 
 When to rerun it:
@@ -57,17 +59,17 @@ When to rerun it:
 - after upgrading `@marvalt/digivalt-core` when scaffolded build wiring changes
 - before publishing a new app if you want a quick preflight of the DigiVAlt setup
 
-**Sitemap:** Each build regenerates **`public/sitemap-paths.json`** from **`public/sitemap-static-paths.json`** (paths you add for SPA-only routes) plus WordPress menu and CPT links in **`wordpress-data.json`**. See **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
+**Sitemap:** Each build regenerates **`public/sitemap-paths.json`** (frontend paths + lastmod) and **`public/seo-manifest.json`**. After Vite, prerender writes HTML snapshots. See **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
 
 **Google Reviews static data:** Opt in by adding **`google_reviews`** to **`VITE_ENABLED_POST_TYPES`** (requires the `vibune-google-reviews` WordPress plugin). When enabled, `generateAllData()` fetches the plugin REST route and writes **`public/google-reviews-data.json`**. By default the endpoint is derived from `WORDPRESS_API_URL` / `VITE_WORDPRESS_API_URL` (`/wp-json/vibune-google-reviews/v1/reviews`). Override with `GOOGLE_REVIEWS_API_URL` / `VITE_GOOGLE_REVIEWS_API_URL` when needed. When `google_reviews` is not listed, generation is skipped (same optional pattern as Mautic/SuiteCRM).
 
-**AI builders (Cursor / Claude Code / Antigravity / Lovable):**
-- Tool-agnostic master prompt: **[docs/LOVABLE-MASTER-PROMPT.md](./docs/LOVABLE-MASTER-PROMPT.md)**
+**AI builders (Cursor / Pencil / Claude Design):**
+- Vite + Cloudflare master prompt: **[docs/AI-MASTER-PROMPT.md](./docs/AI-MASTER-PROMPT.md)**
 - Local-first human runbook: **[docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md](./docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md)**
 
 ## Developing this package
 
-This repo uses **`.npmrc`** with `legacy-peer-deps=true` so `react-helmet-async` installs cleanly alongside **React 19**-compatible transitive deps during local builds. Consumers of the published package only need to satisfy peers (`react`, `react-dom`, `react-helmet-async`).
+This repo uses **`.npmrc`** with `legacy-peer-deps=true` so `react-helmet-async` installs cleanly alongside **React 19**-compatible transitive deps during local builds. Consumers satisfy `react`, `react-dom`, and `react-helmet-async`; install the optional `@tanstack/react-query` peer when injecting a QueryClient into `DigiValtProviders`.
 
 ## Cloudflare Secrets
 

package/bin/env-example-fragments.cjs

@@ -55,6 +55,12 @@ VITE_SEO_TWITTER_SITE=@example
 VITE_SEO_FACEBOOK_APP_ID=
 VITE_SEO_GOOGLE_SITE_VERIFICATION=
 VITE_SEO_BING_SITE_VERIFICATION=
+# Opt-in frontend path prefixes for non-page post types: rest_base:/route-prefix
+# VITE_SEO_ROUTE_PREFIXES=eventbrite_event:/events,member:/members/profile
+# Optional: WP page slug that must map to `/` when Reading Settings front_page does not match the app homepage
+# VITE_SEO_FRONT_PAGE_SLUG=
+# PHPList public archive base (must match the app router)
+# VITE_PHPLIST_NEWSLETTER_ROUTE_BASE=/newsletters
 
 # Performance toggles (optional; omit to use defaults in getPerformanceConfig)
 # VITE_PERF_LAZY_LOADING=true

package/bin/init.cjs

@@ -17,20 +17,24 @@ const args = process.argv.slice(2);
 
 const EXPECTED_GENERATE_SCRIPT =
   'npx vite-node --options.deps.inline="@marvalt/digivalt-core/generators" scripts/generate.ts';
-const EXPECTED_BUILD_SCRIPT = `${EXPECTED_GENERATE_SCRIPT} && vite build`;
-const EXPECTED_BUILD_DEV_SCRIPT = `${EXPECTED_GENERATE_SCRIPT} && vite build --mode development`;
+const EXPECTED_PRERENDER_SCRIPT =
+  'npx vite-node --options.deps.inline="@marvalt/digivalt-core/generators" scripts/prerender-seo.ts';
+const EXPECTED_BUILD_SCRIPT = `${EXPECTED_GENERATE_SCRIPT} && vite build && ${EXPECTED_PRERENDER_SCRIPT}`;
+const EXPECTED_BUILD_DEV_SCRIPT = `${EXPECTED_GENERATE_SCRIPT} && vite build --mode development && ${EXPECTED_PRERENDER_SCRIPT}`;
 
 const TEMPLATE_MANAGED_FILES = new Set([
   '.dev.vars.example',
   'DIGIVALT_SETUP.md',
   'functions/api/fetch-with-access.ts',
   'functions/sitemap.xml.ts',
+  'functions/robots.txt.ts',
   'functions/api/gravity-forms-submit.ts',
   'functions/api/mautic-submit.ts',
   'functions/api/webhook.js',
   'scripts/deploy-secrets.js',
   'scripts/deploy-pages.js',
   'scripts/generate.ts',
+  'scripts/prerender-seo.ts',
   'wrangler.toml',
 ]);
 
@@ -91,7 +95,7 @@ function ensureValidTarget(dir) {
   const packageJsonPath = path.join(dir, 'package.json');
   if (!fs.existsSync(packageJsonPath)) {
     throw new Error(
-      'No package.json found in the target directory. Run `digivalt-init` inside a Vite/Lovable app root, or pass `--target <app-path>`.'
+      'No package.json found in the target directory. Run `digivalt-init` inside a Vite app root, or pass `--target <app-path>`.'
     );
   }
 
@@ -167,6 +171,14 @@ function isExpectedBuildDevScript(command) {
   return normalizeScript(command) === normalizeScript(EXPECTED_BUILD_DEV_SCRIPT);
 }
 
+function isStaleDigivaltBuild(command) {
+  return normalizeScript(command) === normalizeScript(`${EXPECTED_GENERATE_SCRIPT} && vite build`);
+}
+
+function isStaleDigivaltBuildDev(command) {
+  return normalizeScript(command) === normalizeScript(`${EXPECTED_GENERATE_SCRIPT} && vite build --mode development`);
+}
+
 function isPlainViteBuild(command) {
   return normalizeScript(command) === 'vite build';
 }
@@ -191,6 +203,26 @@ function writeJson(filePath, value) {
   }
 }
 
+function findLocalRegistryFiles(srcDir) {
+  if (!fs.existsSync(srcDir)) return [];
+  const matches = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+      } else if (
+        entry.name === 'wpRegistry.tsx' ||
+        (/\.[jt]sx?$/.test(entry.name) && readTextIfExists(fullPath)?.includes('createAppRegistry'))
+      ) {
+        matches.push(path.relative(targetDir, fullPath).replace(/\\/g, '/'));
+      }
+    }
+  };
+  visit(srcDir);
+  return matches;
+}
+
 function inspectTargetApp(targetPackageJsonPath, templateGenerateScript) {
   const packageJson = readJson(targetPackageJsonPath);
   const scripts = packageJson.scripts || {};
@@ -235,7 +267,7 @@ function inspectTargetApp(targetPackageJsonPath, templateGenerateScript) {
     hasViteNode: Boolean(deps['vite-node'] || devDeps['vite-node']),
     buildState: isExpectedBuildScript(scripts.build)
       ? 'current'
-      : isPlainViteBuild(scripts.build)
+      : isPlainViteBuild(scripts.build) || isStaleDigivaltBuild(scripts.build)
         ? 'plain'
         : scriptRunsGenerate(scripts.build)
           ? 'custom-digivalt'
@@ -244,7 +276,7 @@ function inspectTargetApp(targetPackageJsonPath, templateGenerateScript) {
             : 'missing',
     buildDevState: isExpectedBuildDevScript(scripts['build:dev'])
       ? 'current'
-      : isPlainViteBuildDev(scripts['build:dev'])
+      : isPlainViteBuildDev(scripts['build:dev']) || isStaleDigivaltBuildDev(scripts['build:dev'])
         ? 'plain'
         : scriptRunsGenerate(scripts['build:dev'])
           ? 'custom-digivalt'
@@ -262,6 +294,7 @@ function inspectTargetApp(targetPackageJsonPath, templateGenerateScript) {
     legacyPostinstall: postinstall.includes('link-digivalt-alias'),
     legacyRootImport: Boolean(generateScriptContent && generateScriptContent.includes("import { generators } from '@marvalt/digivalt-core';")),
     legacyViteConfigs,
+    localRegistryFiles: findLocalRegistryFiles(path.join(targetDir, 'src')),
   };
 }
 
@@ -438,6 +471,12 @@ function collectLegacyWarnings(status) {
   if (status.legacyViteConfigs.length > 0) {
     report.warnings.push(`Legacy Vite SSR/noExternal workaround detected in: ${status.legacyViteConfigs.join(', ')}.`);
   }
+
+  if (status.localRegistryFiles.length > 0) {
+    report.warnings.push(
+      `Local WordPress registry detected (${status.localRegistryFiles.join(', ')}). Prefer \`@marvalt/digivalt-core/registry\`; existing files were not overwritten.`
+    );
+  }
 }
 
 function printList(title, items) {

package/dist/generators/index.d.ts

@@ -6,4 +6,7 @@ export * from './suitecrm';
 export * from './google-reviews';
 export * from './enabled-post-types';
 export * from './sitemap-paths';
+export * from './seo-manifest';
+export * from './prerender-seo';
+export * from './seo-urls';
 export declare function generateAllData(): Promise<void>;

package/dist/generators/prerender-seo.d.ts

@@ -0,0 +1,6 @@
+export type PrerenderSeoHtmlOptions = {
+    cwd?: string;
+    distDir?: string;
+    manifestPath?: string;
+};
+export declare function prerenderSeoHtml(options?: PrerenderSeoHtmlOptions): Promise<void>;

package/dist/generators/seo-manifest.d.ts

@@ -0,0 +1,3 @@
+import { type GenerateSeoFilesOptions } from './seo-urls';
+export declare function generateSeoManifest(options?: GenerateSeoFilesOptions): Promise<void>;
+export declare function generateSeoManifestSafe(options?: GenerateSeoFilesOptions): Promise<void>;

package/dist/generators/seo-urls.d.ts

@@ -0,0 +1,29 @@
+import type { SeoEntity, SitemapUrlEntry } from '../seo/seoTypes';
+export declare const SITEMAP_URL_SHARD_SIZE = 45000;
+export type GenerateSeoFilesOptions = {
+    cwd?: string;
+    wpDataPath?: string;
+    phplistDataPath?: string;
+    staticInputPath?: string;
+    outputPath?: string;
+    manifestOutputPath?: string;
+};
+export declare function parseRoutePrefixes(raw?: string): Record<string, string>;
+export declare function isPublishedEntity(item: {
+    status?: unknown;
+}): boolean;
+export declare function isNoindexEntity(item: SeoEntity): boolean;
+export declare function entityLastmod(item: SeoEntity): string | undefined;
+export declare function entityImage(item: SeoEntity): string | undefined;
+export declare function getFrontPageRef(data: Record<string, unknown>): {
+    slug?: string;
+    id?: number;
+};
+export declare function getFrontPageSlug(data: Record<string, unknown>): string | undefined;
+export declare function newsletterRouteBase(): string;
+export declare function collectSitemapUrls(args: {
+    wpData?: Record<string, unknown>;
+    phplistData?: Record<string, unknown>;
+    staticPaths: string[];
+    prefixes?: Record<string, string>;
+}): SitemapUrlEntry[];

package/dist/generators/sitemap-paths.d.ts

@@ -1,11 +1,7 @@
-export type GenerateSitemapPathsOptions = {
-    cwd?: string;
-    wpDataPath?: string;
-    staticInputPath?: string;
-    outputPath?: string;
-};
+import { type GenerateSeoFilesOptions } from './seo-urls';
 /**
- * Merge sitemap-static-paths.json, navigation_menu URLs, and CPT/post links from wordpress-data.json.
+ * Merge static app routes, WP pages (frontend paths), opt-in CPT prefixes, and PHPList issues.
  */
-export declare function generateSitemapPaths(options?: GenerateSitemapPathsOptions): Promise<void>;
-export declare function generateSitemapPathsSafe(options?: GenerateSitemapPathsOptions): Promise<void>;
+export declare function generateSitemapPaths(options?: GenerateSeoFilesOptions): Promise<void>;
+export declare function generateSitemapPathsSafe(options?: GenerateSeoFilesOptions): Promise<void>;
+export type { GenerateSeoFilesOptions };