@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/kinds/services.js

@@ -0,0 +1,249 @@
+import { FormBlockSchema } from '@protoyard/blocks';
+import { BlockActionError, isReducibleBlock, parseStateKey, reduceBlockState, restoreBlockState, stateKey, } from '@protoyard/blocks/interactive';
+import { ValidationError } from '@protoyard/core';
+import { createFormServices } from '@protoyard/pages';
+import { z } from 'zod';
+import { KIND_CAPABILITIES } from "./runtime.js";
+/** Bounds on how far the document walk goes (documents are already bounded by the loader). */
+const MAX_WALK_NODES = 20_000;
+/**
+ * Finds a block by id anywhere in a document body (slides, sections, columns,
+ * tabs, reveal panels…). Interactive blocks always carry an id, and the
+ * document is the one the runtime was defined from, so a caller can never
+ * substitute its own block definition.
+ */
+export function findDocumentBlock(doc, blockId) {
+    const stack = [doc[doc.kind]];
+    let seen = 0;
+    while (stack.length > 0 && seen < MAX_WALK_NODES) {
+        const node = stack.pop();
+        seen += 1;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                stack.push(item);
+            continue;
+        }
+        if (node === null || typeof node !== 'object')
+            continue;
+        const record = node;
+        if (typeof record.type === 'string' && record.id === blockId)
+            return record;
+        for (const key of Object.keys(record))
+            stack.push(record[key]);
+    }
+    return null;
+}
+/** A form block's fields as a strict zod schema for one submission. */
+export function formResponseSchema(form) {
+    const shape = {};
+    for (const field of form.fields) {
+        let schema;
+        switch (field.type) {
+            case 'number': {
+                let n = z.number().finite();
+                if (field.min !== undefined)
+                    n = n.min(field.min);
+                if (field.max !== undefined)
+                    n = n.max(field.max);
+                schema = n;
+                break;
+            }
+            case 'boolean':
+                schema = z.boolean();
+                break;
+            case 'enum':
+                schema = z.enum((field.options ?? []).map((option) => option.value));
+                break;
+            case 'tags':
+                schema = z
+                    .array(z.string().trim().min(1).max(64))
+                    .max(field.maxTags ?? 20)
+                    .refine((tags) => new Set(tags).size === tags.length, 'Tags must be unique');
+                break;
+            default: {
+                let text = z
+                    .string()
+                    .trim()
+                    .max(field.maxLength ?? (field.type === 'longText' ? 4_000 : 400));
+                if (field.required)
+                    text = text.min(1, `${field.label} is required`);
+                if (field.type === 'email')
+                    schema = text.pipe(z.email().or(z.literal('')));
+                else if (field.type === 'url')
+                    schema = text.pipe(z.url({ protocol: /^https?$/ }).or(z.literal('')));
+                else
+                    schema = text;
+            }
+        }
+        shape[field.name] = field.required ? schema : schema.optional();
+    }
+    return z.strictObject(shape);
+}
+/** A refused form submission: the values do not fit the form, or the form does not exist. */
+export class FormResponseError extends Error {
+    formId;
+    /** The first message per field name; `''` holds form-level issues such as unknown fields. */
+    issues;
+    constructor(formId, message, issues = {}) {
+        super(message);
+        this.name = 'FormResponseError';
+        this.formId = formId;
+        this.issues = issues;
+    }
+}
+function collectFormBlocks(doc) {
+    const forms = [];
+    const seen = new Set();
+    const stack = [doc[doc.kind]];
+    let n = 0;
+    while (stack.length > 0 && n < MAX_WALK_NODES) {
+        const node = stack.pop();
+        n += 1;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                stack.push(item);
+            continue;
+        }
+        if (node === null || typeof node !== 'object')
+            continue;
+        const record = node;
+        if (record.type === 'form') {
+            const parsed = FormBlockSchema.safeParse(record);
+            if (parsed.success && parsed.data.id && !seen.has(parsed.data.id)) {
+                seen.add(parsed.data.id);
+                forms.push(parsed.data);
+            }
+        }
+        for (const key of Object.keys(record))
+            stack.push(record[key]);
+    }
+    return forms;
+}
+/** The kind services for a runtime defined by `defineKindRuntime(doc, …)`. */
+export async function createKindServices(runtime, doc, options = {}) {
+    const { session, environment } = runtime;
+    const db = runtime.db;
+    const documentId = options.documentId ?? runtime.manifest.storage.namespace;
+    stateKey(documentId, 'probe'); // validates the document id once
+    const cache = new Map();
+    const listeners = new Map();
+    const notify = (key, state) => {
+        for (const listener of [...(listeners.get(key) ?? [])]) {
+            try {
+                listener(state);
+            }
+            catch {
+                // A subscriber's failure is its own; the stored state stands.
+            }
+        }
+    };
+    const refresh = async () => {
+        const rows = await db.table('blockStates').toArray();
+        const before = new Set(cache.keys());
+        cache.clear();
+        for (const row of rows) {
+            if (row.documentId === documentId && typeof row.key === 'string')
+                cache.set(row.key, row.state);
+        }
+        for (const key of new Set([...before, ...cache.keys()]))
+            notify(key, cache.get(key));
+    };
+    const actingPersona = () => {
+        const principal = session.principal();
+        if (!principal)
+            throw new Error('No active persona. Load a scenario first.');
+        return principal.persona.id;
+    };
+    const blockStates = {
+        read: (key) => cache.get(key),
+        async dispatch(key, _block, action) {
+            const parts = parseStateKey(key);
+            if (!parts || parts.documentId !== documentId) {
+                throw new BlockActionError(key, 'This block does not belong to this document.');
+            }
+            const block = findDocumentBlock(doc, parts.blockId);
+            if (!block || !isReducibleBlock(block)) {
+                throw new BlockActionError(key, `No interactive block "${parts.blockId}" in this document.`);
+            }
+            session.assert(KIND_CAPABILITIES.interact, block);
+            // Poll and quiz answers are per viewer: the viewer is the active persona, never the caller's value.
+            const viewerAction = (block.type === 'poll' || block.type === 'quiz') &&
+                action !== null &&
+                typeof action === 'object'
+                ? { ...action, viewer: actingPersona() }
+                : action;
+            const state = await environment.run('blocks.dispatch', () => db.transaction('rw', ['blockStates'], async () => {
+                const stored = await db.table('blockStates').get(key);
+                const current = restoreBlockState(block, stored?.state);
+                const result = reduceBlockState(block, current, viewerAction);
+                if (!result.ok)
+                    throw new BlockActionError(key, result.error);
+                await db.table('blockStates').put({
+                    key,
+                    documentId,
+                    blockId: parts.blockId,
+                    state: result.state,
+                    updatedAt: runtime.clock.now().toISOString(),
+                });
+                return result.state;
+            }));
+            // Only a committed write reaches the cache and the subscribers.
+            cache.set(key, state);
+            notify(key, state);
+            return state;
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set) {
+                set = new Set();
+                listeners.set(key, set);
+            }
+            set.add(listener);
+            return () => {
+                set.delete(listener);
+            };
+        },
+        refresh,
+    };
+    const formBlocks = collectFormBlocks(doc);
+    const pageForms = createFormServices(runtime, formBlocks, { documentId });
+    const responses = {
+        async submit(formId, values) {
+            // createFormServices asserts form:submit (KIND_CAPABILITIES.respond).
+            try {
+                return await pageForms.submit(formId, values);
+            }
+            catch (error) {
+                if (error instanceof FormResponseError)
+                    throw error;
+                if (error instanceof ValidationError) {
+                    throw new FormResponseError(formId, error.message || 'Check the highlighted fields.', {
+                        ...error.issues,
+                    });
+                }
+                const message = error instanceof Error ? error.message : 'Form submission failed.';
+                if (/No form|Permission denied/i.test(message)) {
+                    throw new FormResponseError(formId, message);
+                }
+                throw error;
+            }
+        },
+        async list(formId) {
+            if (formId !== undefined)
+                return pageForms.list(formId);
+            const rows = [];
+            for (const form of formBlocks) {
+                if (!form.id)
+                    continue;
+                rows.push(...(await pageForms.list(form.id)));
+            }
+            return rows.sort((a, b) => a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id.localeCompare(b.id));
+        },
+    };
+    await refresh();
+    // Scenario loads, resets and snapshot restores replace the tables: reload the cache.
+    const offScenario = runtime.scenarios.subscribe(() => {
+        void refresh().catch(() => undefined);
+    });
+    return { documentId, blockStates, responses, destroy: offScenario };
+}

package/dist/kinds/testing.d.ts

@@ -0,0 +1,9 @@
+import type { z } from 'zod';
+import type { ContentKind } from './kind.ts';
+/**
+ * Test-only: validates a content kind against `schema` until the returned
+ * function runs. Lets envelope tests exercise deck, page and doc before their
+ * engine schemas are wired. Refuses to run outside Vitest, and it is not
+ * exported from the package entry.
+ */
+export declare function withKindBodySchemaForTesting(kind: ContentKind, schema: z.ZodType): () => void;

package/dist/kinds/testing.js

@@ -0,0 +1,16 @@
+import { setKindBodyOverride } from "./bodies.js";
+/**
+ * Test-only: validates a content kind against `schema` until the returned
+ * function runs. Lets envelope tests exercise deck, page and doc before their
+ * engine schemas are wired. Refuses to run outside Vitest, and it is not
+ * exported from the package entry.
+ */
+export function withKindBodySchemaForTesting(kind, schema) {
+    const env = globalThis.process
+        ?.env;
+    if (!env?.VITEST) {
+        throw new Error('withKindBodySchemaForTesting is only available under Vitest.');
+    }
+    setKindBodyOverride(kind, schema);
+    return () => setKindBodyOverride(kind, undefined);
+}

package/dist/migrations.d.ts

@@ -0,0 +1,97 @@
+import type { DatabaseVersion } from '@protoyard/core';
+import { type Blueprint, type BlueprintField } from './schema.ts';
+/**
+ * JSON-serializable upgrade steps. Persist these with the blueprint history
+ * and turn them into a Dexie `upgrade` via `applyUpgradeOps` /
+ * `toDatabaseVersion` so migrations stay data, not opaque functions.
+ */
+export type UpgradeOp = {
+    op: 'backfill';
+    table: string;
+    /** Row property to set when missing (`undefined`). */
+    field: string;
+    value: unknown;
+} | {
+    op: 'renameField';
+    table: string;
+    from: string;
+    to: string;
+} | {
+    /** Copy every row from `from` into `to` (table rename). */
+    op: 'copyTable';
+    from: string;
+    to: string;
+} | {
+    /** Replace existing values after an explicitly allowed incompatible schema change. */
+    op: 'resetField';
+    table: string;
+    field: string;
+    value: unknown;
+};
+export interface DiffBlueprintsOptions {
+    /**
+     * Allow dropping tables or fields (Dexie store entry `null` for a removed
+     * table). Without this, drops throw `MigrationError`.
+     */
+    allowDrop?: boolean;
+    /** Schema version of `prev`; the result uses `fromVersion + 1` (default 1). */
+    fromVersion?: number;
+    /**
+     * Explicit renames that cannot live in the strict blueprint schema.
+     * - `tables`: next table name → previous table name
+     * - `fields`: `${table}.${nextRowProperty}` → previous row property
+     */
+    renamedFrom?: {
+        tables?: Record<string, string>;
+        fields?: Record<string, string>;
+    };
+}
+/** Result of comparing two blueprints: the next Dexie version plus its ops. */
+export interface BlueprintMigration {
+    version: number;
+    stores: Record<string, string | null>;
+    ops: readonly UpgradeOp[];
+    /** Dexie upgrade callback built from `ops` (same steps every run). */
+    upgrade?: (tx: unknown) => Promise<void>;
+}
+export declare class MigrationError extends Error {
+    readonly code: 'drop-requires-allow' | 'rename-source-missing';
+    constructor(code: MigrationError['code'], message: string);
+}
+/** Row property stored for a field (`customerId`, tags multi-entry → `tags`, …). */
+export declare function fieldProperty(field: BlueprintField): string;
+/**
+ * Default written when a field is added to an existing table. Prefers the
+ * field's declared `default`, otherwise a kind-appropriate empty value so
+ * old rows stay readable.
+ */
+export declare function defaultForField(field: BlueprintField): unknown;
+/**
+ * Diff two blueprints into the next `DatabaseVersion` (plus serializable ops).
+ * Returns `null` when stores and data shape are unchanged (no version bump).
+ *
+ * Classifies: add entity, add field (backfill default), add index (store
+ * string only), rename via `renamedFrom`, drop (needs `allowDrop` → `null`).
+ */
+export declare function diffBlueprints(prev: Blueprint, next: Blueprint, options?: DiffBlueprintsOptions): BlueprintMigration | null;
+/**
+ * Runs serializable upgrade ops against a Dexie transaction. Safe to call
+ * multiple times on the same ops list (backfill only fills `undefined`).
+ */
+export declare function applyUpgradeOps(tx: unknown, ops: readonly UpgradeOp[]): Promise<void>;
+/** Core `DatabaseVersion` ready to append to a prototype's `database.versions`. */
+export declare function toDatabaseVersion(migration: BlueprintMigration): DatabaseVersion;
+/**
+ * Builds the full version list: previous versions plus the diff as the tip.
+ * When `diffBlueprints` returns null, returns `previous` unchanged.
+ */
+export declare function appendMigration(previous: readonly DatabaseVersion[], migration: BlueprintMigration | null): DatabaseVersion[];
+/**
+ * Every database version of a blueprint, rebuilt from its `history`: version 1
+ * holds the oldest entry's stores, then each step appends the diff against the
+ * previous blueprint (steps that change nothing add no version). Deterministic,
+ * so generated prototypes and `protoyard validate` agree without running code.
+ */
+export declare function deriveDatabaseVersions(blueprint: Blueprint): DatabaseVersion[];
+/** The latest schema version `deriveDatabaseVersions` produces. */
+export declare function latestSchemaVersion(blueprint: Blueprint): number;