@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/kinds/envelope.d.ts

@@ -0,0 +1,159 @@
+import type { Deck } from '@protoyard/decks/schema';
+import type { DocDocument, PageDocument } from '@protoyard/pages';
+import { z } from 'zod';
+import { type Blueprint } from '../schema.ts';
+import { type BlueprintKind, type ContentKind } from './kind.ts';
+/**
+ * The kind union (ADR-036): `parseAnyBlueprint` accepts an app (no `kind`, or
+ * `kind: "app"`, parsed by the unchanged app schema) or a content kind whose
+ * body schema its engine package supplies (`bodies.ts`). `parseBlueprint`
+ * stays app-only, so every consumer that reads `.entities` keeps its type.
+ *
+ * A content blueprint is strict: the shared root keys plus `kind` and one body
+ * key named after the kind. Content schemas load through a kind-specific
+ * dynamic import; app parsing never loads deck, page, or doc validators.
+ * App-only keys (entities, roles, screens, layout, archetype, notifications,
+ * history, validation) are rejected there.
+ */
+declare const BlueprintBaseSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    formatVersion: z.ZodLiteral<1>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    catalog: z.ZodOptional<z.ZodObject<{
+        category: z.ZodEnum<{
+            marketing: "marketing";
+            starter: "starter";
+            productivity: "productivity";
+            communication: "communication";
+            sales: "sales";
+            support: "support";
+            finance: "finance";
+            commerce: "commerce";
+            marketplace: "marketplace";
+            ai: "ai";
+            analytics: "analytics";
+            "developer-tools": "developer-tools";
+            design: "design";
+            education: "education";
+            health: "health";
+            hr: "hr";
+            operations: "operations";
+            media: "media";
+            social: "social";
+            travel: "travel";
+            "real-estate": "real-estate";
+            "internal-tools": "internal-tools";
+        }>;
+        productType: z.ZodOptional<z.ZodString>;
+        platforms: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            desktop: "desktop";
+            mobile: "mobile";
+            tablet: "tablet";
+            web: "web";
+            widget: "widget";
+            extension: "extension";
+            plugin: "plugin";
+        }>>>;
+        shell: z.ZodOptional<z.ZodEnum<{
+            tablet: "tablet";
+            auto: "auto";
+            none: "none";
+            phone: "phone";
+            "desktop-window": "desktop-window";
+            browser: "browser";
+            "widget-host": "widget-host";
+            "extension-popup": "extension-popup";
+            "side-panel": "side-panel";
+        }>>;
+        features: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        highlights: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        difficulty: z.ZodOptional<z.ZodEnum<{
+            beginner: "beginner";
+            intermediate: "intermediate";
+            advanced: "advanced";
+        }>>;
+    }, z.core.$strict>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        seed: z.ZodOptional<z.ZodString>;
+        secondary: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            violet: "violet";
+            ocean: "ocean";
+            emerald: "emerald";
+            rose: "rose";
+            amber: "amber";
+            monochrome: "monochrome";
+        }>>;
+        styleProfile: z.ZodOptional<z.ZodEnum<{
+            flat: "flat";
+            soft: "soft";
+            crisp: "crisp";
+            editorial: "editorial";
+            rounded: "rounded";
+            mono: "mono";
+        }>>;
+        font: z.ZodOptional<z.ZodEnum<{
+            system: "system";
+            humanist: "humanist";
+            geometric: "geometric";
+            grotesk: "grotesk";
+            editorial: "editorial";
+            rounded: "rounded";
+            condensed: "condensed";
+            mono: "mono";
+        }>>;
+        radius: z.ZodOptional<z.ZodString>;
+        density: z.ZodOptional<z.ZodNumber>;
+        libraryTheme: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    motion: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<{
+            none: "none";
+            subtle: "subtle";
+            full: "full";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Root fields every kind shares (name, description, catalog, tags, icon, category, brand). */
+export type BlueprintBase = z.output<typeof BlueprintBaseSchema>;
+/**
+ * The parsed body of each content kind, as defined by its engine package.
+ */
+export interface KindBodies {
+    deck: Deck;
+    page: PageDocument;
+    doc: DocDocument;
+}
+export type ContentBlueprint<K extends ContentKind> = BlueprintBase & {
+    kind: K;
+} & {
+    [P in K]: KindBodies[P];
+};
+export type DeckBlueprint = ContentBlueprint<'deck'>;
+export type PageBlueprint = ContentBlueprint<'page'>;
+export type DocBlueprint = ContentBlueprint<'doc'>;
+/** Any parsed blueprint. Apps carry no `kind` once parsed; content kinds always do. */
+export type AnyBlueprint = Blueprint | DeckBlueprint | PageBlueprint | DocBlueprint;
+/**
+ * The whole-blueprint schema of a content kind around its body schema (cached
+ * per kind). @internal Used by `parseAnyBlueprint` and `kinds/parse.ts`.
+ */
+export declare function contentBlueprintSchema(kind: ContentKind, body: z.ZodType): z.ZodType;
+/** Validates any kind of blueprint. Never throws; an unknown kind fails on `kind`. */
+export declare function safeParseAnyBlueprint(input: unknown): Promise<z.ZodSafeParseResult<AnyBlueprint>>;
+/** Validates any kind of blueprint; throws a `ZodError` on failure. */
+export declare function parseAnyBlueprint(input: unknown): Promise<AnyBlueprint>;
+/** The kind of a parsed blueprint (`app` when it has none). */
+export declare function blueprintKind(blueprint: AnyBlueprint): BlueprintKind;
+export declare function isAppBlueprint(blueprint: AnyBlueprint): blueprint is Blueprint;
+export declare function isContentBlueprint(blueprint: AnyBlueprint): blueprint is DeckBlueprint | PageBlueprint | DocBlueprint;
+export declare function isDeckBlueprint(blueprint: AnyBlueprint): blueprint is DeckBlueprint;
+export declare function isPageBlueprint(blueprint: AnyBlueprint): blueprint is PageBlueprint;
+export declare function isDocBlueprint(blueprint: AnyBlueprint): blueprint is DocBlueprint;
+export {};

package/dist/kinds/envelope.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { BLUEPRINT_BASE_SHAPE, BlueprintSchema } from "../schema.js";
+import { kindBodySchema } from "./bodies.js";
+import { detectBlueprintKind } from "./kind.js";
+/**
+ * The kind union (ADR-036): `parseAnyBlueprint` accepts an app (no `kind`, or
+ * `kind: "app"`, parsed by the unchanged app schema) or a content kind whose
+ * body schema its engine package supplies (`bodies.ts`). `parseBlueprint`
+ * stays app-only, so every consumer that reads `.entities` keeps its type.
+ *
+ * A content blueprint is strict: the shared root keys plus `kind` and one body
+ * key named after the kind. Content schemas load through a kind-specific
+ * dynamic import; app parsing never loads deck, page, or doc validators.
+ * App-only keys (entities, roles, screens, layout, archetype, notifications,
+ * history, validation) are rejected there.
+ */
+const BlueprintBaseSchema = z.strictObject(BLUEPRINT_BASE_SHAPE);
+const contentSchemas = new Map();
+/**
+ * The whole-blueprint schema of a content kind around its body schema (cached
+ * per kind). @internal Used by `parseAnyBlueprint` and `kinds/parse.ts`.
+ */
+export function contentBlueprintSchema(kind, body) {
+    const cached = contentSchemas.get(kind);
+    if (cached?.body === body)
+        return cached.schema;
+    const schema = z.strictObject({
+        ...BLUEPRINT_BASE_SHAPE,
+        kind: z.literal(kind),
+        [kind]: body,
+    });
+    contentSchemas.set(kind, { body, schema });
+    return schema;
+}
+function failure(message, input) {
+    const error = new z.ZodError([{ code: 'custom', path: ['kind'], message, input }]);
+    return { success: false, error: error };
+}
+/** Validates any kind of blueprint. Never throws; an unknown kind fails on `kind`. */
+export async function safeParseAnyBlueprint(input) {
+    const detected = detectBlueprintKind(input);
+    const kind = input?.kind;
+    if (!detected.ok)
+        return failure(detected.message, kind);
+    if (detected.kind === 'app')
+        return BlueprintSchema.safeParse(input);
+    const body = await kindBodySchema(detected.kind);
+    if (!body) {
+        return failure(`Blueprint kind "${detected.kind}" is not available in this build of Protoyard yet.`, kind);
+    }
+    return contentBlueprintSchema(detected.kind, body).safeParse(input);
+}
+/** Validates any kind of blueprint; throws a `ZodError` on failure. */
+export async function parseAnyBlueprint(input) {
+    const result = await safeParseAnyBlueprint(input);
+    if (!result.success)
+        throw result.error;
+    return result.data;
+}
+/** The kind of a parsed blueprint (`app` when it has none). */
+export function blueprintKind(blueprint) {
+    return 'kind' in blueprint ? blueprint.kind : 'app';
+}
+export function isAppBlueprint(blueprint) {
+    return !('kind' in blueprint);
+}
+export function isContentBlueprint(blueprint) {
+    return 'kind' in blueprint;
+}
+export function isDeckBlueprint(blueprint) {
+    return blueprintKind(blueprint) === 'deck';
+}
+export function isPageBlueprint(blueprint) {
+    return blueprintKind(blueprint) === 'page';
+}
+export function isDocBlueprint(blueprint) {
+    return blueprintKind(blueprint) === 'doc';
+}

package/dist/kinds/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@protoyard/blueprint/kinds` — the runtime of content-kind blueprints (deck,
+ * page, doc; ADR-036): `defineKindRuntime` (the prototype definition shared by
+ * the player and generated kind prototypes) and `createKindServices` (the
+ * persistent `BlockStateHost` and form responses). A subpath so app
+ * prototypes and the universal player never load it.
+ */
+export { defineKindRuntime, kindBrandTheme, kindDefaultThemeId } from './brand-runtime.ts';
+export { definePrototypeFromDoc, definePrototypeFromPage, PAGES_DEFAULT_SCENARIO, PAGES_GENERATOR_VERSION, type PageDocRuntimeOptions, } from './page-doc-runtime.ts';
+export { type AnyContentBlueprint, defineKindPrototype, KIND_CAPABILITIES, KIND_DATABASE_VERSIONS, KIND_DEFAULT_SCENARIO, KIND_GENERATOR_VERSION, KIND_PERSONAS, KIND_ROLES, KIND_SCHEMA_VERSION, KIND_STORES, type KindPrototypeOptions, type KindRole, type KindRuntimeOptions, kindPolicy, kindScenarios, kindWorld, } from './runtime.ts';
+export { createKindServices, type FormResponse, FormResponseError, findDocumentBlock, formResponseSchema, type KindServices, type KindServicesOptions, } from './services.ts';

package/dist/kinds/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@protoyard/blueprint/kinds` — the runtime of content-kind blueprints (deck,
+ * page, doc; ADR-036): `defineKindRuntime` (the prototype definition shared by
+ * the player and generated kind prototypes) and `createKindServices` (the
+ * persistent `BlockStateHost` and form responses). A subpath so app
+ * prototypes and the universal player never load it.
+ */
+export { defineKindRuntime, kindBrandTheme, kindDefaultThemeId } from "./brand-runtime.js";
+export { definePrototypeFromDoc, definePrototypeFromPage, PAGES_DEFAULT_SCENARIO, PAGES_GENERATOR_VERSION, } from "./page-doc-runtime.js";
+export { defineKindPrototype, KIND_CAPABILITIES, KIND_DATABASE_VERSIONS, KIND_DEFAULT_SCENARIO, KIND_GENERATOR_VERSION, KIND_PERSONAS, KIND_ROLES, KIND_SCHEMA_VERSION, KIND_STORES, kindPolicy, kindScenarios, kindWorld, } from "./runtime.js";
+export { createKindServices, FormResponseError, findDocumentBlock, formResponseSchema, } from "./services.js";

package/dist/kinds/kind.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Blueprint kinds (ADR-036). A blueprint's `kind` decides its renderer at both
+ * levels (player and `generate`), its synthesizer, variants and validation
+ * summary. A missing `kind` means `app`, so every blueprint written before
+ * kinds existed keeps its meaning and its content identity.
+ *
+ * Not to be confused with the registry's `ProjectKind` (prototype, template,
+ * blueprint) in `@protoyard/core`: that names where a project comes from, this
+ * names what a blueprint renders as.
+ */
+/** Every kind this version understands, in display order. */
+export declare const BLUEPRINT_KINDS: readonly ["app", "deck", "page", "doc"];
+export type BlueprintKind = (typeof BLUEPRINT_KINDS)[number];
+/** Kinds made of content (blocks) rather than entities; each has a body key named after it. */
+export declare const CONTENT_KINDS: readonly ["deck", "page", "doc"];
+export type ContentKind = (typeof CONTENT_KINDS)[number];
+/** The kind a blueprint without `kind` has. */
+export declare const DEFAULT_BLUEPRINT_KIND: BlueprintKind;
+export declare function isBlueprintKind(value: unknown): value is BlueprintKind;
+export declare function isContentKind(value: unknown): value is ContentKind;
+/** The friendly message for a `kind` this version does not know. */
+export declare function unknownKindMessage(kind: string): string;
+export type KindDetection = {
+    ok: true;
+    kind: BlueprintKind;
+} | {
+    ok: false;
+    message: string;
+    fix: string;
+};
+/**
+ * Reads the kind of unparsed input without validating anything else: a
+ * missing or `undefined` kind is `app`. Loaders use it to pick a schema (and,
+ * in the player, a renderer) before parsing.
+ */
+export declare function detectBlueprintKind(input: unknown): KindDetection;

package/dist/kinds/kind.js

@@ -0,0 +1,55 @@
+/**
+ * Blueprint kinds (ADR-036). A blueprint's `kind` decides its renderer at both
+ * levels (player and `generate`), its synthesizer, variants and validation
+ * summary. A missing `kind` means `app`, so every blueprint written before
+ * kinds existed keeps its meaning and its content identity.
+ *
+ * Not to be confused with the registry's `ProjectKind` (prototype, template,
+ * blueprint) in `@protoyard/core`: that names where a project comes from, this
+ * names what a blueprint renders as.
+ */
+/** Every kind this version understands, in display order. */
+export const BLUEPRINT_KINDS = ['app', 'deck', 'page', 'doc'];
+/** Kinds made of content (blocks) rather than entities; each has a body key named after it. */
+export const CONTENT_KINDS = ['deck', 'page', 'doc'];
+/** The kind a blueprint without `kind` has. */
+export const DEFAULT_BLUEPRINT_KIND = 'app';
+export function isBlueprintKind(value) {
+    return typeof value === 'string' && BLUEPRINT_KINDS.includes(value);
+}
+export function isContentKind(value) {
+    return typeof value === 'string' && CONTENT_KINDS.includes(value);
+}
+/** The friendly message for a `kind` this version does not know. */
+export function unknownKindMessage(kind) {
+    const shown = kind.length > 40 ? `${kind.slice(0, 40)}…` : kind;
+    return `Blueprint kind "${shown}" needs a newer Protoyard (this version supports ${BLUEPRINT_KINDS.join(', ')}).`;
+}
+/**
+ * Reads the kind of unparsed input without validating anything else: a
+ * missing or `undefined` kind is `app`. Loaders use it to pick a schema (and,
+ * in the player, a renderer) before parsing.
+ */
+export function detectBlueprintKind(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return { ok: true, kind: DEFAULT_BLUEPRINT_KIND };
+    }
+    const kind = Object.hasOwn(input, 'kind') ? input.kind : undefined;
+    if (kind === undefined)
+        return { ok: true, kind: DEFAULT_BLUEPRINT_KIND };
+    if (typeof kind !== 'string') {
+        return {
+            ok: false,
+            message: `Blueprint "kind" must be a string (one of ${BLUEPRINT_KINDS.join(', ')}).`,
+            fix: 'Set "kind" to app, deck, page or doc, or remove it for an app.',
+        };
+    }
+    if (!isBlueprintKind(kind)) {
+        return {
+            ok: false,
+            message: unknownKindMessage(kind),
+            fix: 'Update Protoyard, or set "kind" to one this version supports.',
+        };
+    }
+    return { ok: true, kind };
+}

package/dist/kinds/limits.d.ts

@@ -0,0 +1,64 @@
+import type { ContentKind } from './kind.ts';
+/**
+ * Untrusted-input rules for content-kind blueprints (deck, page, doc;
+ * ADR-036): size caps checked before any schema runs, the multiline string
+ * allowlist, and the embedded-app walk. Pure and dependency-free on purpose:
+ * the untrusted loader sits on the player's first screen, and importing the
+ * block or deck engines here would put them there for every app.
+ *
+ * The multiline allowlist is a fixed set of schema field names (the block
+ * engine's markdown fields, list item text, code blocks, deck layout code,
+ * speaker notes). It is never
+ * read from the data: a document can only use the fields the schemas define.
+ */
+export interface UntrustedDocumentLimits {
+    /** Serialized UTF-8 bytes of a content document (media data URIs count). */
+    maxBytes: number;
+    /** JSON nesting depth. */
+    maxDepth: number;
+    /** Slides in a deck. */
+    maxSlides: number;
+    /** Blocks in one slide (nested container blocks included). */
+    maxBlocksPerSlide: number;
+    /** Blocks in the whole document (nested container blocks included). */
+    maxBlocks: number;
+    /** Chart data points (labels × series) across every chart block. */
+    maxChartPoints: number;
+    /** `embed-app` blocks in the document. */
+    maxEmbeddedApps: number;
+}
+export declare const DEFAULT_UNTRUSTED_DOCUMENT_LIMITS: Readonly<UntrustedDocumentLimits>;
+/** How a string value is cleaned: controls stripped, newlines kept, or newlines and tabs kept. */
+export type TextContext = 'plain' | 'multiline' | 'code';
+/**
+ * The text context of `key` inside `record` (its parent object). Speaker
+ * notes and the block markdown fields keep newlines. Code keeps tabs too: a
+ * `code` block's `code`, and a deck layout's code object (`{ lang, source }`,
+ * the `code-with-callout` layout's `props.code`). List item text is markdown,
+ * and every other string (titles, labels, ids, a big stat's `source` caption)
+ * stays one line.
+ */
+export declare function textContextFor(key: string, record: Readonly<Record<string, unknown>>, inListItems: boolean): TextContext;
+export interface ContentLimitIssue {
+    path: (string | number)[];
+    message: string;
+    fix: string;
+}
+export interface EmbeddedApp {
+    path: (string | number)[];
+    app: unknown;
+}
+/**
+ * Walks a sanitized content document and checks the caps the schemas do not
+ * express across the whole document: slide count, blocks per slide and in
+ * total (nested container blocks count), chart points and embedded apps. It
+ * returns the first problem, or the embedded apps to validate next.
+ */
+export declare function checkContentLimits(root: Readonly<Record<string, unknown>>, kind: ContentKind, limits: UntrustedDocumentLimits): {
+    issue: ContentLimitIssue;
+} | {
+    issue: null;
+    embeddedApps: EmbeddedApp[];
+};
+/** Whether `value` holds an `embed-app` block anywhere (embedded apps may not embed again). */
+export declare function containsEmbeddedApp(value: unknown): boolean;

package/dist/kinds/limits.js

@@ -0,0 +1,190 @@
+export const DEFAULT_UNTRUSTED_DOCUMENT_LIMITS = Object.freeze({
+    // Matches the block engine's guard (BLOCK_LIMITS.maxBytes): room for the
+    // 512 KB of raster data URIs a document may carry.
+    maxBytes: 1024 * 1024,
+    maxDepth: 32,
+    // The deck schema's own caps (DECK_LIMITS.slides) and the block engine's
+    // document cap (BLOCK_LIMITS.maxBlocks).
+    maxSlides: 200,
+    maxBlocksPerSlide: 200,
+    maxBlocks: 2_000,
+    // Eight full charts (366 labels × 8 series is one chart's schema maximum).
+    maxChartPoints: 8 * 366 * 8,
+    maxEmbeddedApps: 8,
+});
+/** Block fields that hold markdown or multi-line prose (mirrors the block engine's guard). */
+const MULTILINE_FIELDS = new Set([
+    'markdown',
+    'quote',
+    'body',
+    'prompt',
+    'explanation',
+    'description',
+]);
+/**
+ * The text context of `key` inside `record` (its parent object). Speaker
+ * notes and the block markdown fields keep newlines. Code keeps tabs too: a
+ * `code` block's `code`, and a deck layout's code object (`{ lang, source }`,
+ * the `code-with-callout` layout's `props.code`). List item text is markdown,
+ * and every other string (titles, labels, ids, a big stat's `source` caption)
+ * stays one line.
+ */
+export function textContextFor(key, record, inListItems) {
+    if (key === 'code' && record.type === 'code')
+        return 'code';
+    if (key === 'source' && typeof record.lang === 'string')
+        return 'code';
+    if (key === 'notes' && typeof record.id === 'string')
+        return 'multiline';
+    if (MULTILINE_FIELDS.has(key))
+        return 'multiline';
+    if (inListItems && key === 'text')
+        return 'multiline';
+    return 'plain';
+}
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Blocks directly in `value` when it is a block list (`blocks` arrays, `columns` cells). */
+function* blockLists(record, path) {
+    if (Array.isArray(record.blocks))
+        yield { list: record.blocks, path: [...path, 'blocks'] };
+    if (record.type === 'columns' && Array.isArray(record.columns)) {
+        for (const [i, column] of record.columns.entries()) {
+            if (Array.isArray(column))
+                yield { list: column, path: [...path, 'columns', i] };
+        }
+    }
+    if (record.type === 'tabs' && Array.isArray(record.panels)) {
+        for (const [i, panel] of record.panels.entries()) {
+            if (isRecord(panel) && Array.isArray(panel.blocks)) {
+                yield { list: panel.blocks, path: [...path, 'panels', i, 'blocks'] };
+            }
+        }
+    }
+}
+/**
+ * Walks a sanitized content document and checks the caps the schemas do not
+ * express across the whole document: slide count, blocks per slide and in
+ * total (nested container blocks count), chart points and embedded apps. It
+ * returns the first problem, or the embedded apps to validate next.
+ */
+export function checkContentLimits(root, kind, limits) {
+    const body = root[kind];
+    if (!isRecord(body))
+        return { issue: null, embeddedApps: [] };
+    const tooMany = (path, what, actual, max) => ({
+        issue: {
+            path,
+            message: `This ${kind} has ${actual} ${what}; the limit is ${max}.`,
+            fix: `Reduce it to at most ${max} ${what}.`,
+        },
+    });
+    if (kind === 'deck' && Array.isArray(body.slides) && body.slides.length > limits.maxSlides) {
+        return tooMany([kind, 'slides'], 'slides', body.slides.length, limits.maxSlides);
+    }
+    let total = 0;
+    let chartPoints = 0;
+    const embeddedApps = [];
+    // Each block list is counted against its slide (decks) and the document.
+    const walkList = (list, path, slide) => {
+        for (const [index, value] of list.entries()) {
+            if (!isRecord(value))
+                continue;
+            const blockPath = [...path, index];
+            total += 1;
+            if (total > limits.maxBlocks) {
+                return tooMany(blockPath, 'blocks', total, limits.maxBlocks).issue;
+            }
+            if (slide) {
+                slide.count += 1;
+                if (slide.count > limits.maxBlocksPerSlide) {
+                    return {
+                        path: blockPath,
+                        message: `A slide has more than ${limits.maxBlocksPerSlide} blocks.`,
+                        fix: `Split the slide or keep it to at most ${limits.maxBlocksPerSlide} blocks.`,
+                    };
+                }
+            }
+            if ((value.type === 'chart' || value.type === 'chart-controls') && isRecord(value.spec)) {
+                const labels = Array.isArray(value.spec.labels) ? value.spec.labels.length : 0;
+                const series = Array.isArray(value.spec.series) ? value.spec.series.length : 0;
+                chartPoints += labels * Math.max(1, series);
+                if (chartPoints > limits.maxChartPoints) {
+                    return tooMany([...blockPath, 'spec'], 'chart points', chartPoints, limits.maxChartPoints)
+                        .issue;
+                }
+            }
+            if (value.type === 'embed-app') {
+                embeddedApps.push({ path: [...blockPath, 'app'], app: value.app });
+                if (embeddedApps.length > limits.maxEmbeddedApps) {
+                    return tooMany(blockPath, 'embedded apps', embeddedApps.length, limits.maxEmbeddedApps)
+                        .issue;
+                }
+            }
+            for (const nested of blockLists(value, blockPath)) {
+                const problem = walkList(nested.list, nested.path, slide);
+                if (problem)
+                    return problem;
+            }
+        }
+        return null;
+    };
+    // A catalog `chart` slide carries its spec in props: it counts against the same
+    // document chart-point budget as chart blocks, or a deck of chart slides
+    // could ask a viewer's browser to draw far more than the limit allows.
+    if (kind === 'deck' && Array.isArray(body.slides)) {
+        for (const [i, slide] of body.slides.entries()) {
+            if (!isRecord(slide) || !isRecord(slide.props) || !isRecord(slide.props.spec))
+                continue;
+            const spec = slide.props.spec;
+            const labels = Array.isArray(spec.labels) ? spec.labels.length : 0;
+            const series = Array.isArray(spec.series) ? spec.series.length : 0;
+            chartPoints += labels * Math.max(1, series);
+            if (chartPoints > limits.maxChartPoints) {
+                return tooMany([kind, 'slides', i, 'props', 'spec'], 'chart points', chartPoints, limits.maxChartPoints);
+            }
+        }
+    }
+    const lists = [];
+    if (kind === 'deck' && Array.isArray(body.slides)) {
+        for (const [i, slide] of body.slides.entries()) {
+            if (isRecord(slide) && Array.isArray(slide.blocks)) {
+                lists.push({ list: slide.blocks, path: [kind, 'slides', i, 'blocks'], slide: true });
+            }
+        }
+    }
+    else if (kind === 'page' && Array.isArray(body.sections)) {
+        for (const [i, section] of body.sections.entries()) {
+            if (isRecord(section) && Array.isArray(section.blocks)) {
+                lists.push({ list: section.blocks, path: [kind, 'sections', i, 'blocks'], slide: false });
+            }
+        }
+    }
+    else if (Array.isArray(body.blocks)) {
+        lists.push({ list: body.blocks, path: [kind, 'blocks'], slide: false });
+    }
+    for (const { list, path, slide } of lists) {
+        const problem = walkList(list, path, slide ? { count: 0, path } : null);
+        if (problem)
+            return { issue: problem };
+    }
+    return { issue: null, embeddedApps };
+}
+/** Whether `value` holds an `embed-app` block anywhere (embedded apps may not embed again). */
+export function containsEmbeddedApp(value) {
+    const stack = [value];
+    let seen = 0;
+    while (stack.length > 0 && seen < 100_000) {
+        const node = stack.pop();
+        seen += 1;
+        if (Array.isArray(node))
+            stack.push(...node);
+        else if (isRecord(node)) {
+            if (node.type === 'embed-app')
+                return true;
+            for (const key of Object.keys(node))
+                stack.push(node[key]);
+        }
+    }
+    // Fail closed: a value too large to finish scanning is treated as nested.
+    return stack.length > 0;
+}

package/dist/kinds/page-doc-runtime.d.ts

@@ -0,0 +1,37 @@
+import type { PrototypeDefinition } from '@protoyard/core';
+import type { DocDocument, PageDocument } from '@protoyard/pages';
+/**
+ * Options for building a page/doc runtime from a document body alone
+ * (when the caller does not already have a full content blueprint).
+ */
+export interface PageDocRuntimeOptions {
+    /** Storage namespace (IndexedDB name), usually the blueprint content namespace. */
+    namespace: string;
+    /** Manifest slug; defaults to the namespace. */
+    slug?: string;
+    /** Manifest version. */
+    version?: string;
+    /** Root blueprint metadata takes precedence over the document's title and description. */
+    name?: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    icon?: string;
+}
+/** Kind default scenario id (shared content-kind runtime). */
+export declare const PAGES_DEFAULT_SCENARIO = "default";
+/** Kind generator version (shared content-kind runtime). */
+export declare const PAGES_GENERATOR_VERSION = 1;
+/**
+ * Builds the shared content-kind runtime for a page document body by wrapping
+ * it as a `kind: "page"` blueprint and calling {@link defineKindPrototype}.
+ * The wrapper has no `brand` (the default theme), so it never loads brand
+ * resolution or the palette generator a seed brand needs.
+ * Lives in `@protoyard/blueprint/kinds` so `@protoyard/pages` stays free of a
+ * blueprint dependency (no package cycle).
+ */
+export declare function definePrototypeFromPage(page: PageDocument, options: PageDocRuntimeOptions): PrototypeDefinition;
+/**
+ * Builds the shared content-kind runtime for a doc document body.
+ */
+export declare function definePrototypeFromDoc(doc: DocDocument, options: PageDocRuntimeOptions): PrototypeDefinition;