@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/patch.d.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import type { DeckBlueprint, DocBlueprint, PageBlueprint } from './kinds/envelope.ts';
+import { type BlueprintMigration, type DiffBlueprintsOptions } from './migrations.ts';
+import { type Blueprint } from './schema.ts';
+/**
+ * RFC 6902 JSON Patch for blueprints (`protoyard quick iterate`), with no
+ * dependency. A patch is untrusted input: it is shape-checked with zod, its
+ * pointers may never name `__proto__`, `constructor` or `prototype`, it runs
+ * on a copy so a failing operation changes nothing, the result must parse as
+ * a blueprint, and the data migration it implies is returned, so callers know
+ * whether the current world survives. A change that loses data (a dropped
+ * entity or field, an incompatible field change) needs `allowDrop`.
+ */
+export declare const JSON_PATCH_MAX_OPS = 1000;
+/** Maximum JSON nodes traversed while copying a document or patch value. */
+export declare const JSON_PATCH_MAX_NODES = 100000;
+export declare const JSON_POINTER_MAX_LENGTH = 1024;
+export declare const JsonPatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"add">;
+    path: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"remove">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"replace">;
+    path: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"move">;
+    from: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"copy">;
+    from: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"test">;
+    path: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>], "op">;
+export declare const JsonPatchSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"add">;
+    path: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"remove">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"replace">;
+    path: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"move">;
+    from: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"copy">;
+    from: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"test">;
+    path: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>], "op">>;
+export type JsonPatchOperation = z.output<typeof JsonPatchOperationSchema>;
+export type BlueprintPatchErrorCode = 'invalid-patch' | 'unsafe-pointer' | 'path-not-found' | 'test-failed' | 'invalid-result' | 'drop-requires-allow';
+export declare class BlueprintPatchError extends Error {
+    readonly code: BlueprintPatchErrorCode;
+    /** Index of the failing operation, when one operation is to blame. */
+    readonly index: number | null;
+    /** Blueprint validation issues for `invalid-result`. */
+    readonly issues: readonly {
+        path: (string | number)[];
+        message: string;
+    }[];
+    constructor(code: BlueprintPatchErrorCode, message: string, options?: {
+        index?: number | null;
+        issues?: BlueprintPatchError['issues'];
+    });
+}
+/** RFC 6901: `""` is the whole document; otherwise `/`-separated, `~1` → `/`, `~0` → `~`. */
+export declare function parseJsonPointer(pointer: string): string[];
+/** JSON equality: same type, arrays in order, objects by key set regardless of order. */
+export declare function jsonEqual(a: unknown, b: unknown): boolean;
+/**
+ * Applies RFC 6902 operations in order to a copy of `document` and returns
+ * the result. Any failure throws `BlueprintPatchError` and leaves the input
+ * untouched (the operations are atomic as a whole).
+ */
+export declare function applyJsonPatch(document: unknown, operations: unknown): unknown;
+export interface ApplyBlueprintPatchOptions extends Pick<DiffBlueprintsOptions, 'fromVersion' | 'renamedFrom'> {
+    /** Accept a patch that drops entities or fields, or resets incompatible fields. */
+    allowDrop?: boolean;
+}
+export interface BlueprintPatchResult {
+    blueprint: Blueprint;
+    /** The next database version, or null when the stored data shape is unchanged. */
+    migration: BlueprintMigration | null;
+    /** True when the migration drops tables or fields or resets values (only with allowDrop). */
+    destructive: boolean;
+}
+/**
+ * Applies a JSON Patch to a blueprint and validates the result. The returned
+ * migration says how the existing world moves to the new schema; `destructive`
+ * says whether that loses data, which needs `allowDrop`.
+ */
+export declare function applyBlueprintPatch(blueprint: Blueprint, operations: unknown, options?: ApplyBlueprintPatchOptions): BlueprintPatchResult;
+/** A deck, page or doc blueprint. */
+type ContentKindBlueprint = DeckBlueprint | PageBlueprint | DocBlueprint;
+export interface ContentPatchResult<B extends ContentKindBlueprint> {
+    blueprint: B;
+}
+/**
+ * Applies a JSON Patch to a deck, page or doc and validates the result as
+ * untrusted input (`loadUntrustedDocument`: kind limits, text sanitizing and
+ * the kind's body schema). Content kinds share one store layout, so there is
+ * never a data migration: block state and form responses stay keyed by block
+ * id. The patch may not change `kind`.
+ */
+export declare function applyContentPatch<B extends ContentKindBlueprint>(blueprint: B, operations: unknown): Promise<ContentPatchResult<B>>;
+export {};

package/dist/patch.js

@@ -0,0 +1,322 @@
+import { z } from 'zod';
+import { diffBlueprints, MigrationError, } from "./migrations.js";
+import { safeParseBlueprint } from "./schema.js";
+import { loadUntrustedDocument } from "./untrusted.js";
+/**
+ * RFC 6902 JSON Patch for blueprints (`protoyard quick iterate`), with no
+ * dependency. A patch is untrusted input: it is shape-checked with zod, its
+ * pointers may never name `__proto__`, `constructor` or `prototype`, it runs
+ * on a copy so a failing operation changes nothing, the result must parse as
+ * a blueprint, and the data migration it implies is returned, so callers know
+ * whether the current world survives. A change that loses data (a dropped
+ * entity or field, an incompatible field change) needs `allowDrop`.
+ */
+export const JSON_PATCH_MAX_OPS = 1000;
+/** Maximum JSON nodes traversed while copying a document or patch value. */
+export const JSON_PATCH_MAX_NODES = 100_000;
+export const JSON_POINTER_MAX_LENGTH = 1024;
+/** Pointer tokens and value keys that could reach an object prototype. */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+const Pointer = z.string().max(JSON_POINTER_MAX_LENGTH);
+// RFC 6902 §4: members an operation does not define are ignored, so these are
+// not strict. `value` is checked for presence separately (it may be null).
+export const JsonPatchOperationSchema = z.discriminatedUnion('op', [
+    z.object({ op: z.literal('add'), path: Pointer, value: z.unknown() }),
+    z.object({ op: z.literal('remove'), path: Pointer }),
+    z.object({ op: z.literal('replace'), path: Pointer, value: z.unknown() }),
+    z.object({ op: z.literal('move'), from: Pointer, path: Pointer }),
+    z.object({ op: z.literal('copy'), from: Pointer, path: Pointer }),
+    z.object({ op: z.literal('test'), path: Pointer, value: z.unknown() }),
+]);
+export const JsonPatchSchema = z.array(JsonPatchOperationSchema).max(JSON_PATCH_MAX_OPS);
+export class BlueprintPatchError extends Error {
+    code;
+    /** Index of the failing operation, when one operation is to blame. */
+    index;
+    /** Blueprint validation issues for `invalid-result`. */
+    issues;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'BlueprintPatchError';
+        this.code = code;
+        this.index = options.index ?? null;
+        this.issues = options.issues ?? [];
+    }
+}
+/** RFC 6901: `""` is the whole document; otherwise `/`-separated, `~1` → `/`, `~0` → `~`. */
+export function parseJsonPointer(pointer) {
+    if (pointer === '')
+        return [];
+    if (!pointer.startsWith('/'))
+        throw new Error(`"${pointer}" must be empty or start with "/"`);
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((token) => {
+        if (/~[^01]|~$/.test(token))
+            throw new Error(`"${pointer}" has an invalid ~ escape`);
+        const key = token.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (FORBIDDEN_KEYS.has(key))
+            throw new Error(`"${pointer}" names "${key}"`);
+        return key;
+    });
+}
+function isContainer(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Array index token: `0` or digits without a leading zero; `-` (append) only when allowed. */
+function arrayIndex(array, token, forAdd) {
+    if (token === '-')
+        return forAdd ? array.length : null;
+    if (!/^(?:0|[1-9]\d*)$/.test(token))
+        return null;
+    const index = Number(token);
+    return index < (forAdd ? array.length + 1 : array.length) ? index : null;
+}
+function hasMember(container, token) {
+    return Array.isArray(container)
+        ? arrayIndex(container, token, false) !== null
+        : Object.hasOwn(container, token);
+}
+function memberAt(container, token) {
+    return Array.isArray(container)
+        ? container[arrayIndex(container, token, false)]
+        : container[token];
+}
+/** Walks to the parent of `tokens`; throws `path-not-found` when it is missing. */
+function parentOf(root, tokens, fail) {
+    let node = root;
+    for (const token of tokens.slice(0, -1)) {
+        if (!isContainer(node) || !hasMember(node, token))
+            fail('a parent along the path does not exist');
+        node = memberAt(node, token);
+    }
+    if (!isContainer(node))
+        fail('its parent is not an object or array');
+    return node;
+}
+function getAt(root, tokens, fail) {
+    if (tokens.length === 0)
+        return root;
+    const parent = parentOf(root, tokens, fail);
+    const last = tokens[tokens.length - 1];
+    if (!hasMember(parent, last))
+        fail('the target does not exist');
+    return memberAt(parent, last);
+}
+/** Returns the new root (an `add` at `""` replaces the whole document). */
+function addAt(root, tokens, value, fail) {
+    if (tokens.length === 0)
+        return value;
+    const parent = parentOf(root, tokens, fail);
+    const last = tokens[tokens.length - 1];
+    if (Array.isArray(parent)) {
+        const index = arrayIndex(parent, last, true);
+        if (index === null)
+            fail('the array index is out of range');
+        parent.splice(index, 0, value);
+    }
+    else {
+        parent[last] = value;
+    }
+    return root;
+}
+function removeAt(root, tokens, fail) {
+    if (tokens.length === 0)
+        fail('the whole document cannot be removed');
+    const parent = parentOf(root, tokens, fail);
+    const last = tokens[tokens.length - 1];
+    if (!hasMember(parent, last))
+        fail('the target does not exist');
+    const removed = memberAt(parent, last);
+    if (Array.isArray(parent))
+        parent.splice(arrayIndex(parent, last, false), 1);
+    else
+        delete parent[last];
+    return removed;
+}
+/** JSON equality: same type, arrays in order, objects by key set regardless of order. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((item, i) => jsonEqual(item, b[i]));
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    return (keys.length === Object.keys(right).length &&
+        keys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key])));
+}
+/** Deep-copies a JSON value, refusing non-JSON values and prototype-reaching keys. */
+function toJson(value, fail, budget, depth = 0) {
+    budget.used += 1;
+    if (budget.used > JSON_PATCH_MAX_NODES) {
+        fail(`the patch exceeds the ${JSON_PATCH_MAX_NODES.toLocaleString()}-node budget`);
+    }
+    if (depth > 64)
+        fail('the value is nested too deeply');
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            fail('the value has a non-finite number');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => toJson(item, fail, budget, depth + 1));
+    if (typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value)) {
+            if (FORBIDDEN_KEYS.has(key))
+                fail(`the value has a "${key}" key`);
+            const member = value[key];
+            // Dropped like JSON.stringify does: parsed blueprints may carry undefined optionals.
+            if (member !== undefined)
+                out[key] = toJson(member, fail, budget, depth + 1);
+        }
+        return out;
+    }
+    return fail('the value is not JSON');
+}
+/**
+ * Applies RFC 6902 operations in order to a copy of `document` and returns
+ * the result. Any failure throws `BlueprintPatchError` and leaves the input
+ * untouched (the operations are atomic as a whole).
+ */
+export function applyJsonPatch(document, operations) {
+    const parsed = JsonPatchSchema.safeParse(operations);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const index = typeof issue?.path[0] === 'number' ? issue.path[0] : null;
+        throw new BlueprintPatchError('invalid-patch', `Invalid JSON Patch${index === null ? '' : ` operation ${index}`}: ${issue?.path.slice(1).join('.') || 'patch'} ${issue?.message ?? ''}`.trim(), { index });
+    }
+    const raw = Array.isArray(operations) ? operations : [];
+    const budget = { used: 0 };
+    let root = toJson(document, (why) => {
+        throw new BlueprintPatchError('invalid-patch', `The document is not JSON: ${why}.`);
+    }, budget);
+    parsed.data.forEach((operation, index) => {
+        const where = `operation ${index} (${operation.op} ${operation.path})`;
+        const fail = (why, code = 'path-not-found') => {
+            throw new BlueprintPatchError(code, `JSON Patch ${where} failed: ${why}.`, { index });
+        };
+        const pointer = (text) => {
+            try {
+                return parseJsonPointer(text);
+            }
+            catch (error) {
+                return fail(error.message, 'unsafe-pointer');
+            }
+        };
+        const value = () => {
+            if (!Object.hasOwn(raw[index], 'value'))
+                fail('it has no "value" member', 'invalid-patch');
+            return toJson(operation.value, (why) => fail(why, 'invalid-patch'), budget);
+        };
+        const path = pointer(operation.path);
+        switch (operation.op) {
+            case 'add':
+                root = addAt(root, path, value(), fail);
+                break;
+            case 'remove':
+                removeAt(root, path, fail);
+                break;
+            case 'replace': {
+                const next = value();
+                if (path.length === 0) {
+                    root = next;
+                    break;
+                }
+                removeAt(root, path, fail);
+                root = addAt(root, path, next, fail);
+                break;
+            }
+            case 'move': {
+                const from = pointer(operation.from);
+                if (from.length < path.length && from.every((token, i) => token === path[i]))
+                    fail('a value cannot move into one of its own children', 'invalid-patch');
+                if (from.length === path.length && from.every((token, i) => token === path[i]))
+                    break;
+                const moved = from.length === 0 ? root : removeAt(root, from, fail);
+                root = addAt(root, path, moved, fail);
+                break;
+            }
+            case 'copy': {
+                const copied = toJson(getAt(root, pointer(operation.from), fail), (why) => fail(why, 'invalid-patch'), budget);
+                root = addAt(root, path, copied, fail);
+                break;
+            }
+            case 'test':
+                if (!jsonEqual(getAt(root, path, fail), value()))
+                    fail('the value is different', 'test-failed');
+                break;
+        }
+    });
+    return root;
+}
+/**
+ * Applies a JSON Patch to a blueprint and validates the result. The returned
+ * migration says how the existing world moves to the new schema; `destructive`
+ * says whether that loses data, which needs `allowDrop`.
+ */
+export function applyBlueprintPatch(blueprint, operations, options = {}) {
+    const patched = applyJsonPatch(blueprint, operations);
+    const result = safeParseBlueprint(patched);
+    if (!result.success) {
+        const issues = result.error.issues.map((issue) => ({
+            path: issue.path.filter((part) => typeof part !== 'symbol'),
+            message: issue.message,
+        }));
+        const first = issues[0];
+        throw new BlueprintPatchError('invalid-result', `The patched blueprint is invalid: ${first ? `${first.path.join('.') || '(root)'}: ${first.message}` : 'unknown issue'}${issues.length > 1 ? ` (+${issues.length - 1} more)` : ''}.`, { issues });
+    }
+    const next = result.data;
+    const diff = { fromVersion: options.fromVersion, renamedFrom: options.renamedFrom };
+    try {
+        return {
+            blueprint: next,
+            migration: diffBlueprints(blueprint, next, { ...diff, allowDrop: false }),
+            destructive: false,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof MigrationError) || error.code !== 'drop-requires-allow')
+            throw error;
+        if (options.allowDrop !== true) {
+            throw new BlueprintPatchError('drop-requires-allow', `${error.message}. Pass allowDrop to accept losing that data.`);
+        }
+        return {
+            blueprint: next,
+            migration: diffBlueprints(blueprint, next, { ...diff, allowDrop: true }),
+            destructive: true,
+        };
+    }
+}
+/**
+ * Applies a JSON Patch to a deck, page or doc and validates the result as
+ * untrusted input (`loadUntrustedDocument`: kind limits, text sanitizing and
+ * the kind's body schema). Content kinds share one store layout, so there is
+ * never a data migration: block state and form responses stay keyed by block
+ * id. The patch may not change `kind`.
+ */
+export async function applyContentPatch(blueprint, operations) {
+    const patched = applyJsonPatch(blueprint, operations);
+    const kind = patched?.kind;
+    if (kind !== blueprint.kind) {
+        throw new BlueprintPatchError('invalid-result', `A patch may not change the blueprint kind (${blueprint.kind} → ${String(kind)}).`, { issues: [{ path: ['kind'], message: 'kind is fixed for an exploration' }] });
+    }
+    const loaded = await loadUntrustedDocument(patched);
+    if (!loaded.success) {
+        const issues = loaded.issues.map((issue) => ({
+            path: [...issue.path],
+            message: issue.message,
+        }));
+        const first = issues[0];
+        throw new BlueprintPatchError('invalid-result', `The patched ${blueprint.kind} is invalid: ${first ? `${first.path.join('.') || '(root)'}: ${first.message}` : 'unknown issue'}${issues.length > 1 ? ` (+${issues.length - 1} more)` : ''}.`, { issues });
+    }
+    return { blueprint: loaded.blueprint };
+}

package/dist/policy.d.ts

@@ -0,0 +1,23 @@
+import type { PolicyDefinition } from '@protoyard/core';
+import { type Blueprint } from './schema.ts';
+export type EntityCapabilityMap = Record<string, {
+    read: string;
+    create: string;
+    update: string;
+    updateOwn: string;
+    delete: string;
+    deleteOwn: string;
+    import: string;
+    export: string;
+}> & {
+    members: {
+        all: 'members:*';
+    };
+};
+/** Builds the capability names used by generated UIs and services. */
+export declare const CAPABILITIES: (blueprint: Blueprint) => EntityCapabilityMap;
+/**
+ * Converts declarative blueprint permissions to the runtime's capability policy.
+ * Policies are a UX simulation and are never a security boundary.
+ */
+export declare function derivePolicy(blueprint: Blueprint): PolicyDefinition;

package/dist/policy.js

@@ -0,0 +1,105 @@
+import { ENTITY_ACTIONS, } from "./schema.js";
+import { relationProperty } from "./storage.js";
+/** Builds the capability names used by generated UIs and services. */
+export const CAPABILITIES = (blueprint) => {
+    const result = {};
+    for (const entity of blueprint.entities) {
+        const capability = (action) => `${entity.name}:${action}`;
+        result[entity.name] = {
+            read: capability('read'),
+            create: capability('create'),
+            update: capability('update'),
+            updateOwn: capability('update:own'),
+            delete: capability('delete'),
+            deleteOwn: capability('delete:own'),
+            import: capability('import'),
+            export: capability('export'),
+        };
+    }
+    return Object.assign(result, { members: { all: 'members:*' } });
+};
+/**
+ * Converts declarative blueprint permissions to the runtime's capability policy.
+ * Policies are a UX simulation and are never a security boundary.
+ */
+export function derivePolicy(blueprint) {
+    const roles = {};
+    const rules = {};
+    for (const entity of blueprint.entities) {
+        const ownerField = entity.fields.find((field) => field.name === entity.ownerField);
+        const ownerProperty = ownerField ? relationProperty(ownerField) : undefined;
+        if (!ownerProperty)
+            continue;
+        for (const action of ['update:own', 'delete:own']) {
+            const capability = `${entity.name}:${action}`;
+            rules[capability] = (principal, resource) => {
+                if (principal.role === 'owner' || principal.role === 'admin')
+                    return true;
+                if (resource === null || typeof resource !== 'object')
+                    return false;
+                return resource[ownerProperty] === principal.persona.id;
+            };
+        }
+    }
+    for (const role of blueprint.roles) {
+        const capabilities = new Set();
+        for (const [target, actions] of Object.entries(role.permissions)) {
+            const entities = target === '*'
+                ? blueprint.entities
+                : blueprint.entities.filter((entity) => entity.name === target);
+            for (const rawAction of actions) {
+                addActionCapabilities(capabilities, target, entities, rawAction);
+            }
+        }
+        // Team membership is a platform capability rather than a blueprint entity.
+        // Owners and admins manage memberships; a global wildcard grant also opts in.
+        if (role.name === 'owner' || role.name === 'admin' || capabilities.has('*')) {
+            capabilities.add('members:*');
+        }
+        roles[role.name] = [...capabilities];
+    }
+    return { roles, rules };
+}
+function addActionCapabilities(capabilities, target, entities, rawAction) {
+    if (rawAction === '*' && target === '*') {
+        capabilities.add('*');
+        return;
+    }
+    if (rawAction.startsWith('-')) {
+        const denied = rawAction.slice(1);
+        const entityQualified = entities.some((entity) => denied.startsWith(`${entity.name}:`));
+        if (denied.includes(':') && entityQualified) {
+            capabilities.add(`-${denied}`);
+            if (denied.endsWith(':delete'))
+                capabilities.add(`-${denied}:own`);
+            if (denied.endsWith(':update'))
+                capabilities.add(`-${denied}:own`);
+            return;
+        }
+        if (denied === '*') {
+            for (const entity of entities) {
+                for (const action of ENTITY_ACTIONS)
+                    capabilities.add(`-${entity.name}:${action}`);
+                capabilities.add(`-${entity.name}:delete:own`);
+                capabilities.add(`-${entity.name}:update:own`);
+            }
+            return;
+        }
+        for (const entity of entities) {
+            capabilities.add(`-${entity.name}:${denied}`);
+            if (denied === 'delete' || denied === 'update') {
+                capabilities.add(`-${entity.name}:${denied}:own`);
+            }
+        }
+        return;
+    }
+    if (rawAction === '*') {
+        for (const entity of entities) {
+            for (const action of ENTITY_ACTIONS)
+                capabilities.add(`${entity.name}:${action}`);
+        }
+        return;
+    }
+    for (const entity of entities)
+        capabilities.add(`${entity.name}:${rawAction}`);
+}

package/dist/runtime-definition.d.ts

@@ -0,0 +1,39 @@
+import { type PrototypeDefinition, type Theme } from '@protoyard/core';
+import { type AppModel } from './app-model.ts';
+import type { Blueprint } from './schema.ts';
+/**
+ * A complete prototype definition derived from a blueprint at runtime
+ * (ADR-029): what `protoyard generate` writes as files, built in memory so
+ * the player can run a blueprint with no build. Codegen and the player share
+ * every derivation (database versions, policy, integrity, scenarios, brand
+ * theme, app model), so a blueprint behaves the same at both levels.
+ */
+export interface RuntimeDefinitionOptions {
+    /** Storage namespace (IndexedDB names): usually the blueprint's content namespace (`bp-…`). */
+    namespace: string;
+    /** Manifest slug; defaults to the namespace (which must then be a valid slug of at most 48 characters). */
+    slug?: string;
+    /** Manifest version (default `0.1.0`). */
+    version?: string;
+}
+export interface RuntimeDefinition {
+    definition: PrototypeDefinition;
+    appModel: AppModel;
+}
+/** Scenario a blueprint prototype opens in (one of `blueprintScenarios`). */
+export declare const BLUEPRINT_DEFAULT_SCENARIO = "active";
+/**
+ * The theme id a blueprint opens in: its library theme, the id of the theme
+ * its brand builds, or null without a brand. `protoyard generate` writes it to
+ * `protoyard.json` and the player uses it as `defaultTheme`. Throws
+ * `BrandThemeError` for an unknown library theme or a brand that fails AA.
+ */
+export declare function brandDefaultThemeId(blueprint: Blueprint): string | null;
+/** The theme a blueprint's brand builds, or null for no brand or a library brand (shipped by id). */
+export declare function blueprintBrandTheme(blueprint: Blueprint): Theme | null;
+/**
+ * Builds a `definePrototype`-valid definition from a parsed blueprint, plus
+ * its app model. The world generator loads lazily (`@protoyard/blueprint/generator`
+ * stays out of the caller's initial chunk until a scenario seeds).
+ */
+export declare function definePrototypeFromBlueprint(blueprint: Blueprint, options: RuntimeDefinitionOptions): RuntimeDefinition;