@protoyard/player 0.0.0-stage → 1.1.1

package/dist/boot/archetypes/conversational/index.js

@@ -0,0 +1,4 @@
+/** Lazy conversational archetype entry: assistant and team-chat share the AI UI kit. */
+export { createConversationalAdapter, isConversationalArchetype, } from "./adapter.js";
+export { default as ConversationalApp } from './ConversationalApp.svelte';
+export { scriptedReply } from "./reply.js";

package/dist/boot/archetypes/conversational/reply.d.ts

@@ -0,0 +1,6 @@
+import { type PrototypeRuntime } from '@protoyard/core';
+/**
+ * Runs the shared deterministic AI kit without a provider or network. The
+ * player persists the resulting text through the blueprint entity service.
+ */
+export declare function scriptedReply(runtime: PrototypeRuntime, conversationId: string, prompt: string): Promise<string>;

package/dist/boot/archetypes/conversational/reply.js

@@ -0,0 +1,28 @@
+import { createAiEngine } from '@protoyard/ai';
+import { createRng } from '@protoyard/core';
+/**
+ * Runs the shared deterministic AI kit without a provider or network. The
+ * player persists the resulting text through the blueprint entity service.
+ */
+export async function scriptedReply(runtime, conversationId, prompt) {
+    const seed = `${runtime.manifest.slug}:${conversationId}`;
+    const engine = createAiEngine({
+        context: {
+            seed,
+            rng: createRng(seed),
+            clock: {
+                now: () => runtime.clock.now(),
+                nowMs: () => runtime.clock.nowMs(),
+                sleep: async () => undefined,
+            },
+            environment: runtime.environment,
+        },
+        defaultCadenceMs: 0,
+    });
+    const branch = engine.createConversation(`player-${conversationId}`);
+    const stream = engine.stream(branch.id, prompt, { cadenceMs: 0 });
+    let output = '';
+    for await (const chunk of stream)
+        output += chunk.token;
+    return output || 'The simulated assistant has no further detail yet.';
+}

package/dist/boot/boot.d.ts

@@ -0,0 +1,46 @@
+import { type Blueprint } from '@protoyard/blueprint';
+import { type MountedPrototype, type MountPrototypeOptions } from '@protoyard/renderer-svelte';
+import { type WorldCache } from './cache/index.ts';
+import { QUICK_REVIEW_ENDPOINT } from './review-endpoint.ts';
+export { QUICK_REVIEW_ENDPOINT };
+export interface BootPlayerOptions {
+    blueprint: Blueprint;
+    target: HTMLElement;
+    /** Overrides `location.search` (tests, embedding). */
+    search?: string;
+    /** Injected for tests; defaults to `@protoyard/runtime`. */
+    createRuntime?: MountPrototypeOptions['createRuntime'];
+    /** Injected IndexedDB for the player exploration index and storage tests. */
+    indexFactory?: IDBFactory;
+    /** Generated-world cache; defaults to the origin's IndexedDB cache (memory when blocked). */
+    worldCache?: WorldCache;
+    /**
+     * Opens the blueprint in this storage namespace instead of its own (live
+     * reload re-derives a changed blueprint in the world it already has).
+     */
+    namespace?: string;
+    /**
+     * Keeps this prototype generator version (with `namespace`): the reopened
+     * world was built by it, so the runtime must not treat it as stale and
+     * rebuild it. Live reload only.
+     */
+    generatorVersion?: number;
+    /**
+     * Review comments through `quick serve`'s same-origin comments API: mounts
+     * the review UI with the `http` adapter on {@link QUICK_REVIEW_ENDPOINT}.
+     */
+    review?: boolean;
+}
+export interface BootedPlayer extends MountedPrototype {
+    /** The content namespace this blueprint's IndexedDB data lives under (`bp-…`). */
+    namespace: string;
+    /** The prototype generator version its world is (or was) built with. */
+    generatorVersion: number | undefined;
+}
+/**
+ * Runs a parsed blueprint as a prototype (ADR-029): content identity →
+ * runtime definition → `mountPrototype` with runtime build options. Each
+ * blueprint gets its own storage namespace, so two blueprints on one origin
+ * never share data. DevTools are built in and stay on unless `?devtools=0`.
+ */
+export declare function bootPlayer(options: BootPlayerOptions): Promise<BootedPlayer>;

package/dist/boot/boot.js

@@ -0,0 +1,96 @@
+import { blueprintIdentity, definePrototypeFromBlueprint, } from '@protoyard/blueprint';
+import { mountPrototype, } from '@protoyard/renderer-svelte';
+import { createPlayerWorldCache, withWorldCache } from "./cache/index.js";
+import PlayerApp from './PlayerApp.svelte';
+import { setPlayerBlueprint } from "./player-blueprint.js";
+import { QUICK_REVIEW_ENDPOINT } from "./review-endpoint.js";
+import { markActiveExploration, recordExploration, resolvePlayerStorage } from "./storage/index.js";
+import { withWorkerGeneration } from "./worker/generate-world.js";
+export { QUICK_REVIEW_ENDPOINT };
+/** `search` with `name=value` set (kept when already present). */
+function withParam(search, name, value) {
+    const params = new URLSearchParams(search);
+    if (!params.has(name))
+        params.set(name, value);
+    const text = params.toString();
+    return text ? `?${text}` : '';
+}
+/**
+ * Runs a parsed blueprint as a prototype (ADR-029): content identity →
+ * runtime definition → `mountPrototype` with runtime build options. Each
+ * blueprint gets its own storage namespace, so two blueprints on one origin
+ * never share data. DevTools are built in and stay on unless `?devtools=0`.
+ */
+export async function bootPlayer(options) {
+    const { blueprint, target } = options;
+    const identity = await blueprintIdentity(blueprint);
+    const search = options.search ?? location.search;
+    const resolved = await resolvePlayerStorage(blueprint, identity, search);
+    const storage = options.namespace ? { ...resolved, namespace: options.namespace } : resolved;
+    const { definition: blueprintDefinition, appModel } = definePrototypeFromBlueprint(blueprint, {
+        namespace: storage.namespace,
+        slug: storage.namespace,
+    });
+    const generated = withWorkerGeneration(blueprintDefinition, blueprint);
+    // The SaaS kit adds its own stores, rows and capabilities (loaded only for that archetype).
+    const withKit = blueprint.archetype?.id === 'saas-onboarding'
+        ? (await import("./archetypes/business/saas.js")).withSaasKit(generated, blueprint)
+        : generated;
+    // A cache hit reopens a scenario without regenerating; a miss generates in the worker.
+    const cached = withWorldCache(withKit, {
+        blueprintSha256: identity.sha256,
+        cache: options.worldCache ?? createPlayerWorldCache(options.indexFactory),
+    });
+    // Served by `quick serve`: comments go to its same-origin API at a fixed path,
+    // never one from the URL (the renderer loads the review UI lazily when
+    // `comments=1` and DevTools are on).
+    const pinned = options.generatorVersion !== undefined
+        ? { ...cached, generatorVersion: options.generatorVersion }
+        : cached;
+    const definition = options.review
+        ? {
+            ...pinned,
+            manifest: {
+                ...pinned.manifest,
+                build: {
+                    ...pinned.manifest.build,
+                    review: { enabled: true, adapter: 'http', endpoint: QUICK_REVIEW_ENDPOINT },
+                },
+            },
+        }
+        : pinned;
+    const mountSearch = options.review ? withParam(search, 'comments', '1') : options.search;
+    markActiveExploration(storage.namespace);
+    try {
+        await recordExploration(storage, options.indexFactory);
+    }
+    catch {
+        // The index is convenience metadata; a blocked index must not hide the prototype world.
+    }
+    setPlayerBlueprint({ blueprint, model: appModel });
+    const mounted = await mountPrototype({
+        definition,
+        App: PlayerApp,
+        target,
+        ...(mountSearch !== undefined ? { search: mountSearch } : {}),
+        ...(options.createRuntime ? { createRuntime: options.createRuntime } : {}),
+        // Honest labelling: every player prototype says its data is simulated.
+        build: { namespace: storage.namespace, demoBadge: true },
+    });
+    // Validation tasks: a lazy panel, loaded only for blueprints that declare tasks.
+    const tasks = blueprint.validation?.tasks.length ?? 0;
+    if (tasks > 0 && mounted.runtime) {
+        const runtime = mounted.runtime;
+        const panel = import("./validation/index.js").then(({ mountValidationPanel }) => mountValidationPanel({ blueprint, namespace: storage.namespace, runtime }));
+        panel.catch((error) => console.error('[protoyard player] validation panel', error));
+        const destroy = mounted.destroy;
+        mounted.destroy = async () => {
+            await (await panel.catch(() => null))?.destroy();
+            await destroy();
+        };
+    }
+    return Object.assign(mounted, {
+        namespace: storage.namespace,
+        generatorVersion: definition.generatorVersion,
+    });
+}

package/dist/boot/cache/index.d.ts

@@ -0,0 +1,90 @@
+import type { PrototypeDefinition, Scenario, WorldSeed } from '@protoyard/core';
+/**
+ * A content-addressed cache of generated worlds (ADR-030). A world
+ * is a pure function of the blueprint, the scenario and the generator version,
+ * so the player keeps compressed copies and reopens a scenario switch, a reset
+ * or a variant of the same blueprint without regenerating. Everything read
+ * back is untrusted: entries are size-capped, validated against the snapshot
+ * limits and dropped when they do not parse. The cache is an optimization:
+ * when it fails, generation runs as if it were empty.
+ */
+/** IndexedDB database the player keeps cached worlds in (one per origin). */
+export declare const PLAYER_WORLD_CACHE_DATABASE = "protoyard.player.worlds";
+/** Default cap on the compressed bytes kept; least recently used entries go first. */
+export declare const DEFAULT_WORLD_CACHE_MAX_BYTES: number;
+/** A cached world may not inflate past this (the snapshot import cap, `SNAPSHOT_MAX_BYTES`). */
+export declare const WORLD_CACHE_MAX_JSON_BYTES: number;
+/** Rows a cached world may hold (the snapshot import cap, `SNAPSHOT_MAX_ROWS`). */
+export declare const WORLD_CACHE_MAX_ROWS = 250000;
+export interface WorldCacheKey {
+    /** `blueprintIdentity(blueprint).sha256`. */
+    blueprint: string;
+    scenarioId: string;
+    seed: number;
+    generatorVersion: number;
+    /** Digest of the whole resolved scenario (density, reference time, organization…). */
+    scenario: string;
+}
+export interface WorldCacheEntry {
+    key: string;
+    /** gzip of the world's JSON. */
+    bytes: Uint8Array;
+    size: number;
+    lastUsed: number;
+}
+/** Where entries live: IndexedDB in the browser, memory in tests or when storage is blocked. */
+export interface WorldCacheStore {
+    get(key: string): Promise<WorldCacheEntry | undefined>;
+    put(entry: WorldCacheEntry): Promise<void>;
+    touch(key: string, lastUsed: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Every entry's key, size and last use, without the bytes. */
+    list(): Promise<Pick<WorldCacheEntry, 'key' | 'size' | 'lastUsed'>[]>;
+    close(): void;
+}
+export interface WorldCacheStats {
+    hits: number;
+    misses: number;
+    writes: number;
+    evictions: number;
+    /** Entries dropped because they failed to inflate, parse or validate. */
+    rejected: number;
+}
+export interface WorldCache {
+    get(key: WorldCacheKey): Promise<WorldSeed | null>;
+    put(key: WorldCacheKey, world: WorldSeed): Promise<void>;
+    /** Resolves when every write started so far has finished (tests, page unload). */
+    idle(): Promise<void>;
+    readonly stats: Readonly<WorldCacheStats>;
+}
+export interface WorldCacheOptions {
+    store: WorldCacheStore;
+    maxBytes?: number;
+    /** Clock for LRU order (tests). */
+    now?: () => number;
+}
+/** The IndexedDB store; throws when IndexedDB is unavailable (use the memory store then). */
+export declare function createIndexedDbWorldCacheStore(indexedDB?: IDBFactory): WorldCacheStore;
+export declare function createMemoryWorldCacheStore(): WorldCacheStore;
+/** The cache key for a world: the blueprint identity, the scenario and the generator version. */
+export declare function worldCacheKey(blueprintSha256: string, scenario: Scenario, generatorVersion: number): Promise<WorldCacheKey>;
+/**
+ * Checks a value read back from storage is a world the runtime can load:
+ * the WorldSeed shape, rows that are plain objects with a string or number
+ * id, and no more rows than a snapshot import allows.
+ */
+export declare function validateCachedWorld(value: unknown): WorldSeed;
+export declare function createWorldCache(options: WorldCacheOptions): WorldCache;
+export interface WithWorldCacheOptions {
+    /** `blueprintIdentity(blueprint).sha256`. */
+    blueprintSha256: string;
+    cache: WorldCache;
+}
+/**
+ * Serves `definition.generate` from the cache when the same blueprint,
+ * scenario and generator version were generated before, and stores what it
+ * generates otherwise. The runtime contract is unchanged.
+ */
+export declare function withWorldCache(definition: PrototypeDefinition, options: WithWorldCacheOptions): PrototypeDefinition;
+/** The browser cache: IndexedDB when available, otherwise memory for this page only. */
+export declare function createPlayerWorldCache(indexedDB?: IDBFactory): WorldCache;

package/dist/boot/cache/index.js

@@ -0,0 +1,299 @@
+import { canonicalJson } from '@protoyard/blueprint';
+import { Dexie } from 'dexie';
+/**
+ * A content-addressed cache of generated worlds (ADR-030). A world
+ * is a pure function of the blueprint, the scenario and the generator version,
+ * so the player keeps compressed copies and reopens a scenario switch, a reset
+ * or a variant of the same blueprint without regenerating. Everything read
+ * back is untrusted: entries are size-capped, validated against the snapshot
+ * limits and dropped when they do not parse. The cache is an optimization:
+ * when it fails, generation runs as if it were empty.
+ */
+/** IndexedDB database the player keeps cached worlds in (one per origin). */
+export const PLAYER_WORLD_CACHE_DATABASE = 'protoyard.player.worlds';
+/** Default cap on the compressed bytes kept; least recently used entries go first. */
+export const DEFAULT_WORLD_CACHE_MAX_BYTES = 48 * 1024 * 1024;
+/** A cached world may not inflate past this (the snapshot import cap, `SNAPSHOT_MAX_BYTES`). */
+export const WORLD_CACHE_MAX_JSON_BYTES = 25 * 1024 * 1024;
+/** Rows a cached world may hold (the snapshot import cap, `SNAPSHOT_MAX_ROWS`). */
+export const WORLD_CACHE_MAX_ROWS = 250_000;
+class WorldCacheDatabase extends Dexie {
+    worlds;
+    constructor(indexedDB) {
+        super(PLAYER_WORLD_CACHE_DATABASE, indexedDB ? { indexedDB } : undefined);
+        this.version(1).stores({ worlds: 'key,lastUsed' });
+    }
+}
+/** The IndexedDB store; throws when IndexedDB is unavailable (use the memory store then). */
+export function createIndexedDbWorldCacheStore(indexedDB) {
+    const factory = indexedDB ?? globalThis.indexedDB;
+    if (!factory)
+        throw new Error('IndexedDB is unavailable.');
+    const db = new WorldCacheDatabase(factory);
+    return {
+        get: (key) => db.worlds.get(key),
+        put: async (entry) => {
+            await db.worlds.put(entry);
+        },
+        touch: async (key, lastUsed) => {
+            await db.worlds.update(key, { lastUsed });
+        },
+        delete: (key) => db.worlds.delete(key),
+        list: async () => {
+            const rows = [];
+            await db.worlds.each(({ key, size, lastUsed }) => {
+                rows.push({ key, size, lastUsed });
+            });
+            return rows;
+        },
+        close: () => db.close(),
+    };
+}
+export function createMemoryWorldCacheStore() {
+    const entries = new Map();
+    return {
+        get: async (key) => entries.get(key),
+        put: async (entry) => {
+            entries.set(entry.key, entry);
+        },
+        touch: async (key, lastUsed) => {
+            const entry = entries.get(key);
+            if (entry)
+                entries.set(key, { ...entry, lastUsed });
+        },
+        delete: async (key) => {
+            entries.delete(key);
+        },
+        list: async () => [...entries.values()].map(({ key, size, lastUsed }) => ({ key, size, lastUsed })),
+        close: () => entries.clear(),
+    };
+}
+async function sha256Hex(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** The cache key for a world: the blueprint identity, the scenario and the generator version. */
+export async function worldCacheKey(blueprintSha256, scenario, generatorVersion) {
+    return {
+        blueprint: blueprintSha256,
+        scenarioId: scenario.id,
+        seed: scenario.seed,
+        generatorVersion,
+        scenario: (await sha256Hex(canonicalJson(scenario))).slice(0, 32),
+    };
+}
+const keyString = (key) => [key.blueprint, key.scenarioId, key.seed, key.generatorVersion, key.scenario].join(':');
+function streamOf(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+/** Reads a stream into one buffer, or null past `cap` bytes (the read stops there). */
+async function collect(stream, cap) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/** Bytes fed to the compressor per task, so a large world never blocks the main thread. */
+const COMPRESS_SLICE = 64 * 1024;
+/** Lets the browser run other tasks (input, rendering) between slices. */
+const nextTask = () => new Promise((resolve) => setTimeout(resolve, 0));
+async function compress(world) {
+    const json = new TextEncoder().encode(JSON.stringify(world));
+    if (json.byteLength > WORLD_CACHE_MAX_JSON_BYTES)
+        return null;
+    const stream = new CompressionStream('gzip');
+    const output = collect(stream.readable, Number.POSITIVE_INFINITY);
+    const writer = stream.writable.getWriter();
+    // One write for the whole world compressed a massive world in a single 150 ms
+    // main-thread task; slices keep every task short.
+    for (let offset = 0; offset < json.byteLength; offset += COMPRESS_SLICE) {
+        await writer.write(json.subarray(offset, offset + COMPRESS_SLICE));
+        await nextTask();
+    }
+    await writer.close();
+    return output;
+}
+async function inflate(bytes) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    const json = await collect(streamOf(copy).pipeThrough(new DecompressionStream('gzip')), WORLD_CACHE_MAX_JSON_BYTES);
+    if (!json)
+        throw new Error('Cached world is larger than the snapshot limit.');
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(json));
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Checks a value read back from storage is a world the runtime can load:
+ * the WorldSeed shape, rows that are plain objects with a string or number
+ * id, and no more rows than a snapshot import allows.
+ */
+export function validateCachedWorld(value) {
+    if (!isRecord(value))
+        throw new Error('Cached world is not an object.');
+    for (const list of ['organizations', 'personas', 'memberships']) {
+        if (!Array.isArray(value[list]) || !value[list].every(isRecord)) {
+            throw new Error(`Cached world has an invalid ${list} list.`);
+        }
+    }
+    if (value.events !== undefined &&
+        (!Array.isArray(value.events) || !value.events.every(isRecord))) {
+        throw new Error('Cached world has an invalid events list.');
+    }
+    if (!isRecord(value.tables))
+        throw new Error('Cached world has no tables.');
+    let rows = 0;
+    for (const [name, table] of Object.entries(value.tables)) {
+        if (!Array.isArray(table))
+            throw new Error(`Cached table ${name} is not a list.`);
+        rows += table.length;
+        if (rows > WORLD_CACHE_MAX_ROWS) {
+            throw new Error(`Cached world has more than ${WORLD_CACHE_MAX_ROWS} rows.`);
+        }
+        for (const row of table) {
+            if (!isRecord(row) || !['string', 'number'].includes(typeof row.id)) {
+                throw new Error(`Cached table ${name} has a row without a valid id.`);
+            }
+        }
+    }
+    return value;
+}
+export function createWorldCache(options) {
+    const { store } = options;
+    const maxBytes = options.maxBytes ?? DEFAULT_WORLD_CACHE_MAX_BYTES;
+    const now = options.now ?? (() => Date.now());
+    const stats = { hits: 0, misses: 0, writes: 0, evictions: 0, rejected: 0 };
+    const pending = new Set();
+    async function evict() {
+        const entries = (await store.list()).sort((a, b) => a.lastUsed - b.lastUsed);
+        let total = entries.reduce((sum, entry) => sum + entry.size, 0);
+        for (const entry of entries) {
+            if (total <= maxBytes)
+                break;
+            await store.delete(entry.key);
+            total -= entry.size;
+            stats.evictions += 1;
+        }
+    }
+    return {
+        stats,
+        async get(key) {
+            const id = keyString(key);
+            let entry;
+            try {
+                entry = await store.get(id);
+            }
+            catch {
+                stats.misses += 1;
+                return null;
+            }
+            if (!entry) {
+                stats.misses += 1;
+                return null;
+            }
+            try {
+                const world = validateCachedWorld(await inflate(entry.bytes));
+                stats.hits += 1;
+                await store.touch(id, now()).catch(() => undefined);
+                return world;
+            }
+            catch {
+                stats.rejected += 1;
+                stats.misses += 1;
+                await store.delete(id).catch(() => undefined);
+                return null;
+            }
+        },
+        put(key, world) {
+            const write = (async () => {
+                try {
+                    const bytes = await compress(world);
+                    if (!bytes || bytes.byteLength > maxBytes)
+                        return;
+                    await store.put({ key: keyString(key), bytes, size: bytes.byteLength, lastUsed: now() });
+                    stats.writes += 1;
+                    await evict();
+                }
+                catch {
+                    // A full or blocked store only means the next open regenerates.
+                }
+            })();
+            pending.add(write);
+            void write.finally(() => pending.delete(write));
+            return write;
+        },
+        async idle() {
+            while (pending.size > 0)
+                await Promise.all([...pending]);
+        },
+    };
+}
+/**
+ * Serves `definition.generate` from the cache when the same blueprint,
+ * scenario and generator version were generated before, and stores what it
+ * generates otherwise. The runtime contract is unchanged.
+ */
+export function withWorldCache(definition, options) {
+    const generatorVersion = definition.generatorVersion ?? 0;
+    const cached = async (scenario, make) => {
+        const key = await worldCacheKey(options.blueprintSha256, scenario, generatorVersion);
+        const hit = await options.cache.get(key);
+        if (hit)
+            return hit;
+        const world = await make();
+        // Not awaited: the world loads now and is compressed and stored in the background.
+        void options.cache.put(key, world);
+        return world;
+    };
+    return {
+        ...definition,
+        async generate(context) {
+            return cached(context.scenario, async () => definition.generate(context));
+        },
+        // The runtime prefers generateWorld when a definition has one, so the cache must wrap it too.
+        ...(definition.generateWorld
+            ? {
+                async generateWorld(scenario) {
+                    return cached(scenario, async () => {
+                        const world = await definition.generateWorld?.(scenario);
+                        if (!world)
+                            throw new Error('generateWorld returned no world');
+                        return world;
+                    });
+                },
+            }
+            : {}),
+    };
+}
+/** The browser cache: IndexedDB when available, otherwise memory for this page only. */
+export function createPlayerWorldCache(indexedDB) {
+    let store;
+    try {
+        store = createIndexedDbWorldCacheStore(indexedDB);
+    }
+    catch {
+        store = createMemoryWorldCacheStore();
+    }
+    return createWorldCache({ store });
+}

package/dist/boot/player-blueprint.d.ts

@@ -0,0 +1,9 @@
+import type { AppModel, Blueprint } from '@protoyard/blueprint';
+export declare function setPlayerBlueprint(value: {
+    blueprint: Blueprint;
+    model: AppModel;
+}): void;
+export declare function playerBlueprint(): {
+    blueprint: Blueprint;
+    model: AppModel;
+};

package/dist/boot/player-blueprint.js

@@ -0,0 +1,13 @@
+/**
+ * The blueprint the mounted app renders. `mountPrototype` mounts the App
+ * component without props, so `bootPlayer` sets this before mounting.
+ */
+let current = null;
+export function setPlayerBlueprint(value) {
+    current = value;
+}
+export function playerBlueprint() {
+    if (!current)
+        throw new Error('bootPlayer() must set the blueprint before the app mounts');
+    return current;
+}

package/dist/boot/review-endpoint.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The comments API `protoyard quick serve` hosts on its own origin
+ * (`/api/comments/<namespace>`). Fixed here, never taken from a URL or a
+ * response, so nothing can point the player's comments at another server.
+ * Its own module so the app and kind boots share it without importing each other.
+ */
+export declare const QUICK_REVIEW_ENDPOINT = "/api/comments";

package/dist/boot/review-endpoint.js

@@ -0,0 +1,7 @@
+/**
+ * The comments API `protoyard quick serve` hosts on its own origin
+ * (`/api/comments/<namespace>`). Fixed here, never taken from a URL or a
+ * response, so nothing can point the player's comments at another server.
+ * Its own module so the app and kind boots share it without importing each other.
+ */
+export const QUICK_REVIEW_ENDPOINT = '/api/comments';

package/dist/boot/storage/index.d.ts

@@ -0,0 +1,54 @@
+import type { Blueprint, BlueprintIdentity } from '@protoyard/blueprint';
+/** The player index is separate from every blueprint's data and control DB. */
+export declare const PLAYER_INDEX_DATABASE = "protoyard.player.index";
+export declare const PLAYER_ACTIVE_NAMESPACE_KEY = "protoyard.player.active-namespace";
+export interface ExplorationRecord {
+    namespace: string;
+    name: string;
+    identitySha256: string;
+    lastOpened: string;
+    /** Origin-wide StorageManager usage at the last open, not a per-world byte count. */
+    sizeEstimateBytes?: number;
+}
+export interface ExplorationSummary extends Omit<ExplorationRecord, 'sizeEstimateBytes'> {
+    sizeEstimateBytes: number | null;
+}
+export interface PlayerStoragePlan {
+    identity: BlueprintIdentity;
+    namespace: string;
+    name: string;
+    keepName: string | null;
+}
+export interface PlayerIndexStore {
+    list(): Promise<ExplorationSummary[]>;
+    put(record: ExplorationRecord): Promise<void>;
+    remove(namespace: string): Promise<void>;
+    close(): void;
+}
+export interface ClearExplorationOptions {
+    /** The caller must obtain confirmation from the person before setting this. */
+    confirmed?: boolean;
+    /** Optional UI confirmation hook for callers that cannot preflight confirmation. */
+    confirm?: () => boolean | Promise<boolean>;
+}
+/** Reads the optional stable exploration name without consuming sandbox params. */
+export declare function keepNameFromSearch(search: string): string | null;
+/**
+ * Derives a stable namespace from a keep name. The name is not put in the
+ * database name, avoiding punctuation and collisions between similar labels.
+ */
+export declare function keepNamespace(name: string): Promise<string>;
+/** Resolves content-addressed storage by default, or stable keep-mode storage. */
+export declare function resolvePlayerStorage(blueprint: Pick<Blueprint, 'name'>, identity: BlueprintIdentity, search?: string): Promise<PlayerStoragePlan>;
+export declare function openPlayerIndex(indexedDB?: IDBFactory): Promise<PlayerIndexStore>;
+/** Records the latest open and best-effort origin usage estimate. */
+export declare function recordExploration(plan: PlayerStoragePlan, indexedDB?: IDBFactory): Promise<boolean>;
+export declare function listExplorations(indexedDB?: IDBFactory): Promise<ExplorationSummary[]>;
+/**
+ * Clears only one blueprint's databases after confirmation: its data, control
+ * and validation-metrics stores (`protoyard.<namespace>.validation`, written
+ * by the validation-task panel), then its index entry.
+ */
+export declare function clearExploration(namespace: string, options?: ClearExplorationOptions, indexedDB?: IDBFactory): Promise<void>;
+/** Makes the next static paint replay this blueprint's cached appearance. */
+export declare function markActiveExploration(namespace: string, storage?: Pick<Storage, 'setItem'> | undefined): boolean;