@actuate-media/cms-core 0.26.0 → 0.27.1

package/dist/__tests__/api/stats-seo-cache.test.js

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { handleActuateAPI } from '../../api/index.js';
+import { __resetDashboardSeoCache } from '../../api/handlers.js';
+import { createSession } from '../../auth/session.js';
+import { initDB } from '../../db.js';
+import { generateToken as generateCsrfToken } from '../../security/csrf.js';
+/**
+ * `/stats` caches its average-SEO-score computation (a read + scan over
+ * up to 200 documents) per content-scope for a short TTL. These tests
+ * assert the cache is actually consulted: a second request within the
+ * window must NOT re-issue the 200-document SEO read, and clearing the
+ * cache forces a recompute.
+ */
+const SECRET = 'test-secret-for-stats-seo-cache-aaaaaaaaaaaaaaaa';
+function createMockDB(rows) {
+    let seoReadCount = 0;
+    const allRows = rows.map((r, i) => ({
+        id: `d${i}`,
+        title: `Doc ${i}`,
+        status: 'PUBLISHED',
+        collection: 'posts',
+        updatedAt: new Date(),
+        createdById: 'u1',
+        createdBy: { name: 'Author', email: 'a@example.com' },
+        data: r.data,
+    }));
+    const db = {
+        session: { findUnique: async () => ({ revokedAt: null }) },
+        user: { count: async () => 0 },
+        media: { count: async () => 0 },
+        formSubmission: { count: async () => 0 },
+        webhookEndpoint: { count: async () => 0 },
+        document: {
+            count: async () => allRows.length,
+            // The SEO read is the only `findMany` with `take: 200` + `select.data`.
+            findMany: async ({ take, select }) => {
+                if (take === 200 && select?.data)
+                    seoReadCount++;
+                return allRows;
+            },
+            groupBy: async () => [],
+        },
+    };
+    return { db, getSeoReadCount: () => seoReadCount };
+}
+async function sessionCookie() {
+    const token = await createSession({ userId: 'user-1', role: 'ADMIN', sessionId: 'session-1' }, { secret: SECRET });
+    const csrf = await generateCsrfToken();
+    return `actuate_session=${token}; actuate_csrf=${csrf}`;
+}
+const POSTS_CONFIG = { collections: { posts: { slug: 'posts', fields: {} } } };
+describe('GET /api/cms/stats — SEO score cache', () => {
+    const originalSecret = process.env.CMS_SECRET;
+    beforeEach(() => {
+        process.env.CMS_SECRET = SECRET;
+        __resetDashboardSeoCache();
+    });
+    afterEach(() => {
+        if (originalSecret === undefined)
+            delete process.env.CMS_SECRET;
+        else
+            process.env.CMS_SECRET = originalSecret;
+        delete globalThis.__actuateConfig;
+        __resetDashboardSeoCache();
+    });
+    it('computes the score once and serves repeat requests from cache', async () => {
+        const { db, getSeoReadCount } = createMockDB([
+            { data: { seoTitle: 'a', metaDescription: 'b' } }, // 50
+            { data: { seoTitle: 'a', metaDescription: 'b', canonical: 'c', schemaType: 'Article' } }, // 100
+        ]);
+        initDB(db);
+        const handler = handleActuateAPI({ prismaClient: db, config: POSTS_CONFIG });
+        const cookie = await sessionCookie();
+        const call = () => handler(new Request('https://example.com/api/cms/stats', { headers: { cookie } }));
+        const first = (await (await call()).json());
+        expect(first.data.avgSeoScore).toBe(75);
+        expect(getSeoReadCount()).toBe(1);
+        const second = (await (await call()).json());
+        expect(second.data.avgSeoScore).toBe(75);
+        // Served from cache — no second 200-document read.
+        expect(getSeoReadCount()).toBe(1);
+    });
+    it('recomputes after the cache is cleared', async () => {
+        const { db, getSeoReadCount } = createMockDB([{ data: { seoTitle: 'a' } }]); // 25
+        initDB(db);
+        const handler = handleActuateAPI({ prismaClient: db, config: POSTS_CONFIG });
+        const cookie = await sessionCookie();
+        const call = () => handler(new Request('https://example.com/api/cms/stats', { headers: { cookie } }));
+        await call();
+        expect(getSeoReadCount()).toBe(1);
+        __resetDashboardSeoCache();
+        await call();
+        expect(getSeoReadCount()).toBe(2);
+    });
+});
+//# sourceMappingURL=stats-seo-cache.test.js.map

package/dist/__tests__/api/stats-seo-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats-seo-cache.test.js","sourceRoot":"","sources":["../../../src/__tests__/api/stats-seo-cache.test.ts"],"names":[],"mappings":"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"}

package/dist/api/handlers.d.ts

@@ -1,4 +1,6 @@
 import type { ApiRouter } from './router.js';
+/** Test-only: reset the SEO score cache so cases don't bleed into each other. */
+export declare function __resetDashboardSeoCache(): void;
 export declare function parseCookieHeader(cookieHeader: string): Record<string, string>;
 export declare function registerCMSRoutes(router: ApiRouter): void;
 //# sourceMappingURL=handlers.d.ts.map

package/dist/api/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/api/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAwnB5C,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS9E;AA2ND,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+lOzD"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/api/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAogB5C,iFAAiF;AACjF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AA8JD,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS9E;AAiQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8kPzD"}

package/dist/api/handlers.js

@@ -33,6 +33,7 @@ import { createSSEPresenceAdapter } from '../presence/index.js';
 import { BUILT_IN_TEMPLATES } from '../page-builder/templates.js';
 import { validateTree } from '../page-builder/validate.js';
 import { auditAccessibility, fixAccessibility } from '../page-builder/a11y-fix.js';
+import { SECTION_TYPE_LIST, getSectionType, getSectionTypesForScope, buildSection, coerceSections, coercePostHeader, defaultPostHeader, addSection as addSectionToList, removeSection as removeSectionFromList, reorderSections as reorderSectionList, setSectionVisibility, updateSectionContent as updateSectionContentInList, updateSectionSettings as updateSectionSettingsInList, updateSectionMeta as updateSectionMetaInList, validateSectionContent, } from '../sections/index.js';
 import { getClientIp, isResolvedIp } from '../security/client-ip.js';
 import { safeFetch, SsrfBlockedError } from '../security/safe-fetch.js';
 import { redactSecrets } from '../security/redact.js';
@@ -385,6 +386,25 @@ async function safeFindMany(model, args) {
         return [];
     }
 }
+/**
+ * Short-TTL cache for the dashboard's average SEO score.
+ *
+ * `/stats` otherwise reads the `data` JSON of up to 200 published
+ * documents and scores each one on every load — the single heaviest
+ * part of the endpoint. The score barely moves minute-to-minute, so we
+ * cache it per content-scope (the JSON-stringified Prisma `where`, which
+ * encodes the registered collection allowlist) for a short window.
+ *
+ * Module-level so it survives across requests within a warm isolate;
+ * a cold start simply recomputes once. Keyed by scope so multi-config
+ * isolates never read each other's score.
+ */
+let dashboardSeoCache = null;
+const DASHBOARD_SEO_CACHE_TTL_MS = 60_000;
+/** Test-only: reset the SEO score cache so cases don't bleed into each other. */
+export function __resetDashboardSeoCache() {
+    dashboardSeoCache = null;
+}
 function isAllowedStorageUrl(url) {
     try {
         const parsed = new URL(url);
@@ -708,6 +728,41 @@ class ModelNotAvailableError extends Error {
         this.model = model;
     }
 }
+/**
+ * Resolve a collection definition from the runtime config, tolerating both
+ * the array and the record (keyed-by-slug) shapes consumers use.
+ */
+function findCollectionDef(slug) {
+    const collections = getActuateConfig()?.collections;
+    if (Array.isArray(collections)) {
+        return collections.find((c) => c?.slug === slug);
+    }
+    if (collections && typeof collections === 'object') {
+        const rec = collections;
+        return rec[slug] ?? Object.values(rec).find((c) => c?.slug === slug);
+    }
+    return undefined;
+}
+/**
+ * True when `collection` declares a `sections` JSON field — the storage
+ * contract the flat Page Editor + section endpoints rely on. Guards against
+ * silently dropping section writes on a collection that never declared the
+ * field (the field-access layer strips undeclared keys).
+ */
+function collectionSupportsSections(slug) {
+    const def = findCollectionDef(slug);
+    if (!def)
+        return false;
+    const fields = def.fields;
+    if (Array.isArray(fields)) {
+        return fields.some((f) => f?.name === 'sections' && f?.type === 'json');
+    }
+    if (fields && typeof fields === 'object') {
+        const f = fields.sections;
+        return f?.type === 'json';
+    }
+    return false;
+}
 export function registerCMSRoutes(router) {
     const rawDb = () => getDB();
     const db = () => {
@@ -811,6 +866,14 @@ export function registerCMSRoutes(router) {
                 type: def?.type ?? 'page',
                 urlPrefix: def?.urlPrefix ?? slug,
                 hidden: def?.admin?.hidden === true,
+                // Surface the admin metadata the Posts area needs to render
+                // type tabs / cards (description, icon, accent color, group).
+                // None are sensitive — they all already live on the public
+                // collection definition the admin client receives via props.
+                description: def?.admin?.description ?? null,
+                icon: def?.admin?.icon ?? null,
+                color: def?.admin?.color ?? null,
+                group: def?.admin?.group ?? null,
                 fieldCount: fieldSummary.length,
                 fields: fieldSummary,
             };
@@ -1705,6 +1768,337 @@ export function registerCMSRoutes(router) {
         }
     });
     // ---------------------------------------------------------------------------
+    // Page section routes (flat Page Editor model)
+    //
+    // These operate on a page document's `data.sections` JSON array — the same
+    // model the visual Page Editor reads/writes — so an AI agent driving the
+    // CMS from Cursor/VS Code via MCP produces real, editable, publishable
+    // sections rather than disposable markup. All mutations go through the
+    // audited `updateDocument` path (versions, hooks, cache invalidation,
+    // live-preview push) and reuse collection scope checks.
+    //
+    // Discovery + validation are deterministic (no LLM) and only need auth.
+    // ---------------------------------------------------------------------------
+    // GET /page-sections/types — discover registered section types + schemas.
+    // Optional `?scope=page|post` filters to types usable on that surface so an
+    // agent only builds sections that have a working renderer in that context.
+    router.get('/page-sections/types', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scope = new URL(request.url).searchParams.get('scope');
+            const data = scope === 'page' || scope === 'post'
+                ? getSectionTypesForScope(scope)
+                : SECTION_TYPE_LIST;
+            return json({ data });
+        }
+        catch (err) {
+            return internalError(err, 'list section types');
+        }
+    });
+    // POST /page-sections/validate — validate section content against its
+    // type schema. Body: { sectionType, content, settings? }.
+    router.post('/page-sections/validate', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const body = (await request.json().catch(() => null));
+            const sectionType = typeof body?.sectionType === 'string' ? body.sectionType : '';
+            if (!sectionType)
+                return errorResponse('sectionType is required', 400);
+            const content = body?.content && typeof body.content === 'object'
+                ? body.content
+                : {};
+            const settings = body?.settings && typeof body.settings === 'object'
+                ? body.settings
+                : undefined;
+            const result = validateSectionContent(sectionType, content, settings);
+            return json({ data: result });
+        }
+        catch (err) {
+            return internalError(err, 'validate section');
+        }
+    });
+    // Shared: load a page document's sections, or a Response on error.
+    const loadPageSections = async (collection, id, ctx) => {
+        if (!collectionSupportsSections(collection)) {
+            return errorResponse(`Collection "${collection}" does not declare a "sections" JSON field, so it cannot store page sections.`, 400);
+        }
+        const doc = await getDocument(collection, id, ctx);
+        if (!doc)
+            return errorResponse('Page not found', 404);
+        const data = doc.data ?? {};
+        return { sections: coerceSections(data.sections) };
+    };
+    // Shared: persist a mutated section array via the audited update path.
+    const persistPageSections = async (collection, id, sections, ctx, userId) => {
+        const doc = await updateDocument(collection, id, { sections }, ctx);
+        await logEvent({
+            event: 'document_updated',
+            userId,
+            details: { collection, documentId: id, action: 'page_sections_updated' },
+        });
+        notifyPreviewUpdate(collection, id, {
+            values: doc.data,
+            status: doc.status,
+            updatedAt: doc.updatedAt?.toISOString?.(),
+        });
+        const data = doc.data ?? {};
+        return coerceSections(data.sections);
+    };
+    // GET /page-sections/:collection/:id — list a page's sections.
+    router.get('/page-sections/:collection/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'read');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            return json({ data: loaded.sections });
+        }
+        catch (err) {
+            return internalError(err, 'list page sections');
+        }
+    });
+    // POST /page-sections/:collection/:id — add a section.
+    // Body: { sectionType, name?, internalLabel?, visible?, content?, settings?, position? }.
+    router.post('/page-sections/:collection/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const sectionType = typeof body?.sectionType === 'string' ? body.sectionType : '';
+            if (!getSectionType(sectionType)) {
+                return errorResponse(`Unknown section type "${sectionType}". Call GET /page-sections/types for valid ids.`, 400);
+            }
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const section = buildSection(sectionType, {
+                name: typeof body?.name === 'string' ? body.name : undefined,
+                internalLabel: typeof body?.internalLabel === 'string' ? body.internalLabel : undefined,
+                visible: body?.visible !== false,
+                content: body?.content && typeof body.content === 'object'
+                    ? body.content
+                    : undefined,
+                settings: body?.settings && typeof body.settings === 'object'
+                    ? body.settings
+                    : undefined,
+            });
+            const position = typeof body?.position === 'number' ? body.position : undefined;
+            const next = addSectionToList(loaded.sections, section, position);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            const validation = validateSectionContent(section.sectionType, section.content, section.settings);
+            return json({ data: { section, sections: saved, validation } }, 201);
+        }
+        catch (err) {
+            return internalError(err, 'add page section');
+        }
+    });
+    // POST /page-sections/:collection/:id/reorder — reorder by id list.
+    // Registered BEFORE the :sectionId routes so "reorder" isn't captured as a
+    // section id (the router matches in registration order).
+    router.post('/page-sections/:collection/:id/reorder', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const orderedIds = Array.isArray(body?.orderedIds)
+                ? body.orderedIds.filter((x) => typeof x === 'string')
+                : null;
+            if (!orderedIds)
+                return errorResponse('orderedIds (string[]) is required', 400);
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const next = reorderSectionList(loaded.sections, orderedIds);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            return json({ data: saved });
+        }
+        catch (err) {
+            return internalError(err, 'reorder page sections');
+        }
+    });
+    // PATCH /page-sections/:collection/:id/:sectionId — update a section.
+    // Body: { content?, settings?, name?, internalLabel?, visible? }.
+    router.patch('/page-sections/:collection/:id/:sectionId', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const sectionId = params.sectionId;
+            if (!loaded.sections.some((s) => s.id === sectionId)) {
+                return errorResponse(`Section "${sectionId}" not found on this page.`, 404);
+            }
+            let next = loaded.sections;
+            if (body?.content && typeof body.content === 'object') {
+                next = updateSectionContentInList(next, sectionId, body.content);
+            }
+            if (body?.settings && typeof body.settings === 'object') {
+                next = updateSectionSettingsInList(next, sectionId, body.settings);
+            }
+            const meta = {};
+            if (typeof body?.name === 'string')
+                meta.name = body.name;
+            if (typeof body?.internalLabel === 'string')
+                meta.internalLabel = body.internalLabel;
+            if (Object.keys(meta).length > 0)
+                next = updateSectionMetaInList(next, sectionId, meta);
+            if (typeof body?.visible === 'boolean') {
+                next = setSectionVisibility(next, sectionId, body.visible);
+            }
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            const updated = saved.find((s) => s.id === sectionId);
+            const validation = updated
+                ? validateSectionContent(updated.sectionType, updated.content, updated.settings)
+                : undefined;
+            return json({ data: { section: updated, sections: saved, validation } });
+        }
+        catch (err) {
+            return internalError(err, 'update page section');
+        }
+    });
+    // DELETE /page-sections/:collection/:id/:sectionId — remove a section.
+    router.delete('/page-sections/:collection/:id/:sectionId', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const sectionId = params.sectionId;
+            if (!loaded.sections.some((s) => s.id === sectionId)) {
+                return errorResponse(`Section "${sectionId}" not found on this page.`, 404);
+            }
+            const next = removeSectionFromList(loaded.sections, sectionId);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            return json({ data: { sections: saved } });
+        }
+        catch (err) {
+            return internalError(err, 'remove page section');
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Post template routes
+    //
+    // A post type's template is a single document in the hidden
+    // `post-templates` collection, matched by `slug` == the post-type slug. It
+    // stores the design-driven header layout (`data.header`) and the default
+    // section list (`data.sections`) new posts inherit. Lets an external AI
+    // agent (Cursor/VS Code) read a type's template and build it from
+    // scope=post section types discovered via `/page-sections/types?scope=post`.
+    // ---------------------------------------------------------------------------
+    const POST_TEMPLATES_COLLECTION = 'post-templates';
+    const findPostTemplateDoc = async (postType, ctx) => {
+        const res = await listDocuments({ collection: POST_TEMPLATES_COLLECTION, pageSize: 200 }, ctx);
+        const docs = res.docs ?? [];
+        return (docs.find((d) => (d.slug ?? d.data?.slug) === postType) ?? null);
+    };
+    const templateResponse = (postType, doc) => {
+        if (!doc) {
+            return { postType, docId: null, header: defaultPostHeader(), sections: [] };
+        }
+        const data = doc.data ?? {};
+        return {
+            postType,
+            docId: doc.id,
+            header: coercePostHeader(data.header),
+            sections: coerceSections(data.sections),
+        };
+    };
+    // GET /post-templates/:type — read a post type's template (header +
+    // default sections). Returns an unsaved default when none exists yet.
+    router.get('/post-templates/:type', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, POST_TEMPLATES_COLLECTION, 'read');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const doc = await findPostTemplateDoc(params.type, ctx);
+            return json({ data: templateResponse(params.type, doc) });
+        }
+        catch (err) {
+            return internalError(err, 'get post template');
+        }
+    });
+    // PUT /post-templates/:type — create or replace a post type's template.
+    // Body: { header?, sections? }. Header is coerced to a full PostHeaderConfig
+    // and sections are coerced (unknown section types dropped) so the stored
+    // template always renders.
+    router.put('/post-templates/:type', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, POST_TEMPLATES_COLLECTION, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const header = coercePostHeader(body?.header);
+            const sections = coerceSections(body?.sections);
+            const ctx = buildActionContext(auth.session, db());
+            const existing = await findPostTemplateDoc(params.type, ctx);
+            const data = {
+                title: `${params.type} template`,
+                slug: params.type,
+                postType: params.type,
+                header,
+                sections,
+                status: 'PUBLISHED',
+            };
+            const doc = existing
+                ? await updateDocument(POST_TEMPLATES_COLLECTION, existing.id, data, ctx)
+                : await createDocument(POST_TEMPLATES_COLLECTION, data, ctx);
+            await logEvent({
+                event: existing ? 'document_updated' : 'document_created',
+                userId: auth.session.userId,
+                details: {
+                    collection: POST_TEMPLATES_COLLECTION,
+                    documentId: doc.id,
+                    action: 'post_template_saved',
+                    postType: params.type,
+                },
+            });
+            return json({ data: templateResponse(params.type, doc) });
+        }
+        catch (err) {
+            return internalError(err, 'save post template');
+        }
+    });
+    // ---------------------------------------------------------------------------
     // Media routes
     // ---------------------------------------------------------------------------
     router.get('/media', async (request) => {
@@ -2578,6 +2972,63 @@ export function registerCMSRoutes(router) {
             score += 25;
         return score;
     }
+    /**
+     * Average SEO score across published content, cached per content-scope
+     * for `DASHBOARD_SEO_CACHE_TTL_MS`. On a cache hit this returns without
+     * touching the database — avoiding the 200-document `data` read + scan
+     * that dominates `/stats`. Failures from `safeFindMany` surface as an
+     * empty list (score 0) and are not cached, so a transient DB blip
+     * doesn't pin a stale 0.
+     */
+    async function getCachedAvgSeoScore(model, where) {
+        const key = JSON.stringify(where);
+        const now = Date.now();
+        if (dashboardSeoCache && dashboardSeoCache.key === key && dashboardSeoCache.expires > now) {
+            return dashboardSeoCache.value;
+        }
+        const docs = await safeFindMany(model, {
+            where,
+            select: { data: true },
+            take: 200,
+        });
+        let value = 0;
+        if (docs.length > 0) {
+            const total = docs.reduce((sum, doc) => sum + computeLightSeoScore(doc.data ?? {}), 0);
+            value = Math.round(total / docs.length);
+        }
+        dashboardSeoCache = { key, value, expires: now + DASHBOARD_SEO_CACHE_TTL_MS };
+        return value;
+    }
+    /**
+     * Collection slugs that are written by the benchmark suite and a few
+     * other internal/test fixtures. Documents in these collections are
+     * never editor-facing content and should never appear in the
+     * dashboard's stats, counts, or recent-activity feed.
+     *
+     * This list is the fallback when the consumer ships collection
+     * definitions only to the admin client (e.g. `apps/dev`) and
+     * `getActuateConfig()?.collections` is therefore empty on the
+     * server. Production consumers normally pass `collections` to
+     * `handleActuateAPI({ config })`, in which case the registered
+     * slugs become the allowlist and this denylist is unused.
+     */
+    const INTERNAL_COLLECTION_SLUGS = ['benchmarks', 'bench'];
+    /**
+     * Build the Prisma `where` clause for "user-facing content".
+     *
+     *   - If the CMS config registered collections, restrict to those
+     *     slugs — anything else is orphan/test data.
+     *   - Otherwise fall back to excluding the internal denylist.
+     *
+     * Always excludes soft-deleted rows. Callers can spread additional
+     * filters on top (`status: 'PUBLISHED'`, etc.).
+     */
+    function userContentWhere(extra = {}) {
+        const cfg = getActuateConfig();
+        const registered = Object.keys(cfg?.collections ?? {});
+        const collectionFilter = registered.length > 0 ? { in: registered } : { notIn: [...INTERNAL_COLLECTION_SLUGS] };
+        return { deletedAt: null, collection: collectionFilter, ...extra };
+    }
     router.get('/stats', async (request) => {
         try {
             if (!isSecretMissing()) {
@@ -2592,8 +3043,13 @@ export function registerCMSRoutes(router) {
             catch {
                 return json({ data: EMPTY_STATS });
             }
-            const [docResult, mediaResult, userResult, recentResult, collGroupResult, statusGroupResult, formResult, seoDocsResult, webhookTotalResult, webhookActiveResult,] = await Promise.allSettled([
-                safeCount(d.document, { deletedAt: null }),
+            // `userContentWhere()` filters out benchmark / orphan / internal
+            // collections so the dashboard surfaces editor content only. See
+            // the helper above for the allowlist-vs-denylist behaviour.
+            const contentWhere = userContentWhere();
+            const publishedContentWhere = userContentWhere({ status: 'PUBLISHED' });
+            const [docResult, mediaResult, userResult, recentResult, collGroupResult, statusGroupResult, formResult, seoScoreResult, webhookTotalResult, webhookActiveResult,] = await Promise.allSettled([
+                safeCount(d.document, contentWhere),
                 safeCount(d.media),
                 safeCount(d.user),
                 safeFindMany(d.document, {
@@ -2603,7 +3059,7 @@ export function registerCMSRoutes(router) {
                     // -> Prisma Postgres path that saves ~80 ms (one full network
                     // RTT) on every dashboard load.
                     relationLoadStrategy: 'join',
-                    where: { deletedAt: null },
+                    where: contentWhere,
                     orderBy: { updatedAt: 'desc' },
                     take: 20,
                     select: {
@@ -2616,14 +3072,12 @@ export function registerCMSRoutes(router) {
                         createdBy: { select: { name: true, email: true } },
                     },
                 }),
-                safeGroupBy(d.document, ['collection'], { deletedAt: null }),
-                safeGroupBy(d.document, ['status'], { deletedAt: null }),
+                safeGroupBy(d.document, ['collection'], contentWhere),
+                safeGroupBy(d.document, ['status'], contentWhere),
                 safeCount(d.formSubmission),
-                safeFindMany(d.document, {
-                    where: { deletedAt: null, status: 'PUBLISHED' },
-                    select: { data: true },
-                    take: 200,
-                }),
+                // Cached per content-scope so the 200-doc SEO read+scan runs at
+                // most once per TTL window across warm requests.
+                getCachedAvgSeoScore(d.document, publishedContentWhere),
                 // Cheap counts so the dashboard's "Content Delivery" tile doesn't need
                 // a second round-trip. `webhookEndpoint` may not exist on every host,
                 // so `safeCount` swallows missing-model errors and returns 0.
@@ -2640,12 +3094,7 @@ export function registerCMSRoutes(router) {
                 for (const g of statusGroupResult.value)
                     statusCounts[g.status] = g._count._all;
             }
-            let avgSeoScore = 0;
-            if (seoDocsResult.status === 'fulfilled' && seoDocsResult.value.length > 0) {
-                const docs = seoDocsResult.value;
-                const total = docs.reduce((sum, doc) => sum + computeLightSeoScore(doc.data ?? {}), 0);
-                avgSeoScore = Math.round(total / docs.length);
-            }
+            const avgSeoScore = seoScoreResult.status === 'fulfilled' ? seoScoreResult.value : 0;
             const recentDocs = recentResult.status === 'fulfilled'
                 ? recentResult.value.map((doc) => ({
                     id: doc.id,