@protoyard/player 0.0.0-stage → 1.1.0

package/dist/boot/storage/index.js

@@ -0,0 +1,170 @@
+import { Dexie } from 'dexie';
+/** The player index is separate from every blueprint's data and control DB. */
+export const PLAYER_INDEX_DATABASE = 'protoyard.player.index';
+export const PLAYER_ACTIVE_NAMESPACE_KEY = 'protoyard.player.active-namespace';
+const KEEP_NAME_LIMIT = 80;
+const PLAYER_NAMESPACE = /^(?:bp|keep)-[a-z0-9-]+$/;
+class PlayerIndexDatabase extends Dexie {
+    explorations;
+    constructor(indexedDB) {
+        super(PLAYER_INDEX_DATABASE, indexedDB ? { indexedDB } : undefined);
+        this.version(1).stores({ explorations: 'namespace,lastOpened' });
+    }
+}
+function resolveIndexedDB(indexedDB) {
+    return indexedDB ?? globalThis.indexedDB;
+}
+async function originUsageBytes() {
+    const storage = globalThis.navigator
+        ?.storage;
+    if (!storage?.estimate)
+        return undefined;
+    try {
+        const estimate = await storage.estimate();
+        return typeof estimate.usage === 'number' ? estimate.usage : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function validKeepName(name) {
+    const trimmed = name.trim();
+    const hasControlCharacter = [...trimmed].some((character) => {
+        const code = character.charCodeAt(0);
+        return code < 32 || code === 127;
+    });
+    if (!trimmed || trimmed.length > KEEP_NAME_LIMIT || hasControlCharacter) {
+        throw new Error(`keep name must be 1-${KEEP_NAME_LIMIT} printable characters`);
+    }
+    return trimmed;
+}
+/** Reads the optional stable exploration name without consuming sandbox params. */
+export function keepNameFromSearch(search) {
+    const value = new URLSearchParams(search).get('keep');
+    return value === null || value.trim() === '' ? null : validKeepName(value);
+}
+/**
+ * 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 async function keepNamespace(name) {
+    const normalized = validKeepName(name).normalize('NFKC').toLowerCase();
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle)
+        throw new Error('keep mode needs Web Crypto (crypto.subtle)');
+    const digest = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(`protoyard.keep\u0000${normalized}`)));
+    const hex = Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `keep-${hex.slice(0, 26)}`;
+}
+/** Resolves content-addressed storage by default, or stable keep-mode storage. */
+export async function resolvePlayerStorage(blueprint, identity, search = '') {
+    const keepName = keepNameFromSearch(search);
+    return {
+        identity,
+        namespace: keepName ? await keepNamespace(keepName) : identity.namespace,
+        name: keepName ?? blueprint.name,
+        keepName,
+    };
+}
+export async function openPlayerIndex(indexedDB) {
+    if (!resolveIndexedDB(indexedDB))
+        throw new Error('IndexedDB is unavailable for the player index');
+    const db = new PlayerIndexDatabase(indexedDB);
+    await db.open();
+    return {
+        async list() {
+            const rows = await db.explorations.orderBy('lastOpened').reverse().toArray();
+            return rows.map((row) => ({ ...row, sizeEstimateBytes: row.sizeEstimateBytes ?? null }));
+        },
+        async put(record) {
+            await db.explorations.put(record);
+        },
+        async remove(namespace) {
+            await db.explorations.delete(namespace);
+        },
+        close() {
+            db.close();
+        },
+    };
+}
+/** Records the latest open and best-effort origin usage estimate. */
+export async function recordExploration(plan, indexedDB) {
+    if (!resolveIndexedDB(indexedDB))
+        return false;
+    const index = await openPlayerIndex(indexedDB);
+    try {
+        const usage = await originUsageBytes();
+        await index.put({
+            namespace: plan.namespace,
+            name: plan.name,
+            identitySha256: plan.identity.sha256,
+            lastOpened: new Date().toISOString(),
+            ...(usage === undefined ? {} : { sizeEstimateBytes: usage }),
+        });
+        return true;
+    }
+    finally {
+        index.close();
+    }
+}
+export async function listExplorations(indexedDB) {
+    if (!resolveIndexedDB(indexedDB))
+        return [];
+    const index = await openPlayerIndex(indexedDB);
+    try {
+        return await index.list();
+    }
+    finally {
+        index.close();
+    }
+}
+function deleteDatabase(indexedDB, name) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.deleteDatabase(name);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error ?? new Error(`Could not clear ${name}`));
+        request.onblocked = () => reject(new Error(`Could not clear ${name}: another tab is open`));
+    });
+}
+/**
+ * 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 async function clearExploration(namespace, options = {}, indexedDB) {
+    if (!PLAYER_NAMESPACE.test(namespace))
+        throw new Error(`Invalid player namespace "${namespace}"`);
+    const accepted = options.confirmed === true || (options.confirm ? await options.confirm() : false);
+    if (!accepted)
+        throw new Error('Clearing an exploration requires confirmation');
+    const factory = resolveIndexedDB(indexedDB);
+    if (!factory)
+        throw new Error('IndexedDB is unavailable for the player');
+    await deleteDatabase(factory, `protoyard.${namespace}.data`);
+    await deleteDatabase(factory, `protoyard.${namespace}.control`);
+    await deleteDatabase(factory, `protoyard.${namespace}.validation`);
+    const index = await openPlayerIndex(factory);
+    try {
+        await index.remove(namespace);
+    }
+    finally {
+        index.close();
+    }
+}
+/** Makes the next static paint replay this blueprint's cached appearance. */
+export function markActiveExploration(namespace, storage = (() => {
+    try {
+        return globalThis.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+})()) {
+    try {
+        storage?.setItem(PLAYER_ACTIVE_NAMESPACE_KEY, namespace);
+        return Boolean(storage);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/boot/validation/ValidationPanel.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+import { Button } from '@protoyard/ui';
+import { onDestroy } from 'svelte';
+import type { SessionState, ValidationSession } from './session.js';
+
+/**
+ * The validation task panel: the current task, a timer and step count while
+ * it runs, and Start, Give up, Next and Download metrics. It sits in a corner
+ * over the prototype and can be collapsed. Prompts are blueprint text,
+ * rendered as plain text.
+ */
+let {
+  session,
+  onDownload,
+}: {
+  session: ValidationSession;
+  onDownload: () => Promise<void>;
+} = $props();
+
+let view = $state<SessionState | null>(null);
+let collapsed = $state(false);
+let now = $state(Date.now());
+let announcement = $state('');
+
+$effect(() => {
+  const current = session;
+  return current.subscribe((next) => {
+    if (next.current.phase === 'done' && view?.current.phase !== 'done') {
+      const outcome = next.current.attempt.outcome;
+      announcement =
+        outcome === 'success'
+          ? 'Task complete.'
+          : outcome === 'gave-up'
+            ? 'Task skipped.'
+            : 'Time is up.';
+    }
+    view = next;
+  });
+});
+const tick = setInterval(() => {
+  if (view?.current.phase === 'running') now = Date.now();
+}, 500);
+onDestroy(() => clearInterval(tick));
+
+function seconds(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
+
+const outcomeLabel = {
+  success: 'Completed',
+  'gave-up': 'Gave up',
+  'timed-out': 'Time is up',
+} as const;
+</script>
+
+<aside
+  class="fixed bottom-4 left-4 z-50 w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-border bg-surface text-surface-foreground shadow-float"
+  aria-labelledby="py-validation-title"
+  data-testid="validation-panel"
+>
+  <div class="flex items-center justify-between gap-2 border-b border-border px-4 py-2">
+    <h2 id="py-validation-title" class="text-sm font-semibold">
+      {view ? `Task ${view.index + 1} of ${view.total}` : 'Tasks'}
+    </h2>
+    <Button
+      type="button"
+      variant="ghost"
+      size="sm"
+      class="px-2 text-xs text-muted-foreground"
+      aria-expanded={!collapsed}
+      onclick={() => (collapsed = !collapsed)}
+    >
+      {collapsed ? 'Show' : 'Hide'}
+    </Button>
+  </div>
+  {#if view && !collapsed}
+    <div class="space-y-3 px-4 py-3 text-sm">
+      <p class="font-medium" data-testid="validation-prompt">{view.task.prompt}</p>
+      {#if view.current.phase === 'running'}
+        <p class="text-muted-foreground">
+          <span>{seconds(now - view.current.startedAt)}</span>
+          {#if view.task.timeLimitSeconds}<span> of {seconds(view.task.timeLimitSeconds * 1000)}</span>{/if}
+          · {view.current.steps} steps
+        </p>
+      {:else if view.current.phase === 'done'}
+        <p data-testid="validation-outcome">
+          {outcomeLabel[view.current.attempt.outcome]} in {seconds(view.current.attempt.durationMs)} ·
+          {view.current.attempt.steps} steps
+        </p>
+      {:else}
+        <p class="text-muted-foreground">Start when you are ready. Time and steps are recorded in this browser only.</p>
+      {/if}
+      <div class="flex flex-wrap gap-2">
+        {#if view.current.phase === 'ready'}
+          <Button size="sm" onclick={() => session.start()}>Start task</Button>
+        {:else if view.current.phase === 'running'}
+          <Button size="sm" variant="outline" onclick={() => session.giveUp()}>Give up</Button>
+        {:else if !view.finished}
+          <Button size="sm" onclick={() => session.next()}>Next task</Button>
+        {/if}
+        <Button size="sm" variant="ghost" onclick={onDownload}>Download metrics</Button>
+      </div>
+      {#if view.finished}
+        <p class="text-muted-foreground">All tasks done. Download the metrics to share them.</p>
+      {/if}
+    </div>
+  {/if}
+  <p class="sr-only" role="status" aria-live="polite">{announcement}</p>
+</aside>

package/dist/boot/validation/ValidationPanel.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { ValidationSession } from './session.ts';
+type $$ComponentProps = {
+    session: ValidationSession;
+    onDownload: () => Promise<void>;
+};
+declare const ValidationPanel: import("svelte").Component<$$ComponentProps, {}, "">;
+type ValidationPanel = ReturnType<typeof ValidationPanel>;
+export default ValidationPanel;

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

@@ -0,0 +1,26 @@
+import type { Blueprint } from '@protoyard/blueprint';
+import { type RouteSource, type SessionRuntime } from './session.ts';
+import { downloadMetrics } from './store.ts';
+/**
+ * Mounts the validation panel for a blueprint with `validation.tasks`. The
+ * player imports this module only for such blueprints, so others download
+ * none of it.
+ */
+export interface MountValidationOptions {
+    blueprint: Blueprint;
+    namespace: string;
+    runtime: SessionRuntime;
+    /** Where the panel mounts (defaults to a new element in `document.body`). */
+    target?: HTMLElement;
+    route?: RouteSource;
+    indexedDB?: IDBFactory;
+    IDBKeyRange?: typeof IDBKeyRange;
+    download?: typeof downloadMetrics;
+}
+export interface MountedValidation {
+    destroy(): Promise<void>;
+}
+export declare function hasValidationTasks(blueprint: Blueprint): boolean;
+export declare function mountValidationPanel(options: MountValidationOptions): MountedValidation;
+export { type AttemptOutcome, createValidationSession, hashRoute, type RouteSource, type SessionState, type ValidationAttempt, type ValidationSession, } from './session.ts';
+export { assertAttempt, downloadMetrics, metricsFile, openValidationStore, VALIDATION_METRICS_FORMAT, VALIDATION_METRICS_VERSION, type ValidationMetricsFile, type ValidationStore, validationDatabaseName, } from './store.ts';

package/dist/boot/validation/index.js

@@ -0,0 +1,50 @@
+import { mount, unmount } from 'svelte';
+import { createValidationSession, hashRoute, } from "./session.js";
+import { downloadMetrics, metricsFile, openValidationStore } from "./store.js";
+import ValidationPanel from './ValidationPanel.svelte';
+export function hasValidationTasks(blueprint) {
+    return (blueprint.validation?.tasks.length ?? 0) > 0;
+}
+export function mountValidationPanel(options) {
+    const { blueprint, namespace } = options;
+    const store = openValidationStore(namespace, {
+        ...(options.indexedDB ? { indexedDB: options.indexedDB } : {}),
+        ...(options.IDBKeyRange ? { IDBKeyRange: options.IDBKeyRange } : {}),
+    });
+    const session = createValidationSession({
+        blueprint,
+        runtime: options.runtime,
+        route: options.route ?? hashRoute(window),
+        record: (attempt) => store.record(attempt),
+    });
+    const ownTarget = options.target
+        ? null
+        : document.body.appendChild(document.createElement('div'));
+    const target = options.target ?? ownTarget;
+    const download = options.download ?? downloadMetrics;
+    const panel = mount(ValidationPanel, {
+        target,
+        props: {
+            session,
+            onDownload: async () => {
+                const file = metricsFile({
+                    name: blueprint.name,
+                    namespace,
+                    tasks: blueprint.validation?.tasks ?? [],
+                    attempts: await store.list(),
+                });
+                download(file);
+            },
+        },
+    });
+    return {
+        async destroy() {
+            await unmount(panel);
+            session.close();
+            store.close();
+            ownTarget?.remove();
+        },
+    };
+}
+export { createValidationSession, hashRoute, } from "./session.js";
+export { assertAttempt, downloadMetrics, metricsFile, openValidationStore, VALIDATION_METRICS_FORMAT, VALIDATION_METRICS_VERSION, validationDatabaseName, } from "./store.js";

package/dist/boot/validation/session.d.ts

@@ -0,0 +1,71 @@
+import { type Blueprint, type ValidationTask } from '@protoyard/blueprint';
+import type { PendingTracker } from '@protoyard/core';
+/**
+ * One validation session over a blueprint's `validation.tasks` (ADR-031):
+ * the participant starts a task, works in the prototype, and the session
+ * detects success from the current route and the live data. It records the
+ * outcome, the time taken and the steps: route changes plus completed service
+ * calls. It never logs keys, text or anything a person types, and never uses
+ * the network.
+ */
+export type AttemptOutcome = 'success' | 'gave-up' | 'timed-out';
+export interface ValidationAttempt {
+    taskId: string;
+    outcome: AttemptOutcome;
+    /** Wall-clock milliseconds from start to outcome. */
+    durationMs: number;
+    /** Route changes plus completed service calls while the task ran. */
+    steps: number;
+    startedAt: string;
+    endedAt: string;
+}
+export type TaskPhase = {
+    phase: 'ready';
+} | {
+    phase: 'running';
+    startedAt: number;
+    steps: number;
+} | {
+    phase: 'done';
+    attempt: ValidationAttempt;
+};
+export interface SessionState {
+    index: number;
+    task: ValidationTask;
+    total: number;
+    current: TaskPhase;
+    /** True after the last task has an outcome. */
+    finished: boolean;
+}
+/** The route the participant is on (`/bookings/b-1`), and its changes. */
+export interface RouteSource {
+    current(): string;
+    subscribe(listener: () => void): () => void;
+}
+/** The bits of the runtime a session reads: its database and pending tracker. */
+export interface SessionRuntime {
+    db: unknown;
+    pending?: Pick<PendingTracker, 'subscribe'>;
+}
+export interface ValidationSessionOptions {
+    blueprint: Blueprint;
+    runtime: SessionRuntime;
+    route: RouteSource;
+    /** Called with each recorded attempt (the metrics store persists it). */
+    record: (attempt: ValidationAttempt) => Promise<void>;
+    /** Injectable clock and timers for tests. */
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+export interface ValidationSession {
+    state(): SessionState;
+    subscribe(listener: (state: SessionState) => void): () => void;
+    start(): Promise<void>;
+    giveUp(): Promise<void>;
+    next(): void;
+    close(): void;
+}
+export declare function createValidationSession(options: ValidationSessionOptions): ValidationSession;
+/** The hash route (`#/bookings` → `/bookings`), with `hashchange` as its signal. */
+export declare function hashRoute(win: Pick<Window, 'location' | 'addEventListener' | 'removeEventListener'>): RouteSource;

package/dist/boot/validation/session.js

@@ -0,0 +1,150 @@
+import { entityTable, evaluateValidationSuccess, validationBaseline, } from '@protoyard/blueprint';
+import { liveQuery } from 'dexie';
+/** Entities the tasks' data predicates read, mapped to their tables. */
+function watchedTables(blueprint) {
+    const names = new Set((blueprint.validation?.tasks ?? []).flatMap((task) => task.success.data ? [task.success.data.entity] : []));
+    return new Map(blueprint.entities
+        .filter((entity) => names.has(entity.name))
+        .map((entity) => [entity.name, entityTable(entity)]));
+}
+/** Live rows of the watched entities; soft-deleted rows do not count. */
+async function readRows(db, tables) {
+    const out = {};
+    for (const [entity, table] of tables) {
+        const rows = await db.table(table).toArray();
+        out[entity] = rows.filter((row) => row.deletedAt === undefined || row.deletedAt === null);
+    }
+    return out;
+}
+export function createValidationSession(options) {
+    const tasks = options.blueprint.validation?.tasks ?? [];
+    if (tasks.length === 0)
+        throw new Error('This blueprint has no validation tasks.');
+    const now = options.now ?? (() => Date.now());
+    const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const tables = watchedTables(options.blueprint);
+    const listeners = new Set();
+    let index = 0;
+    let current = { phase: 'ready' };
+    let rows = {};
+    let baseline = {};
+    let timer = null;
+    let finishing = null;
+    const seenOperations = new Set();
+    const state = () => ({
+        index,
+        task: tasks[index],
+        total: tasks.length,
+        current,
+        finished: index === tasks.length - 1 && current.phase === 'done',
+    });
+    const emit = () => {
+        const snapshot = state();
+        for (const listener of [...listeners])
+            listener(snapshot);
+    };
+    const finish = (outcome) => {
+        if (current.phase !== 'running')
+            return finishing ?? Promise.resolve();
+        if (timer !== null)
+            clearTimer(timer);
+        timer = null;
+        const ended = now();
+        const attempt = {
+            taskId: tasks[index].id,
+            outcome,
+            durationMs: Math.max(0, Math.round(ended - current.startedAt)),
+            steps: current.steps,
+            startedAt: new Date(current.startedAt).toISOString(),
+            endedAt: new Date(ended).toISOString(),
+        };
+        current = { phase: 'done', attempt };
+        emit();
+        finishing = options.record(attempt).finally(() => {
+            finishing = null;
+        });
+        return finishing;
+    };
+    const evaluate = () => {
+        if (current.phase !== 'running')
+            return;
+        const observation = { route: options.route.current(), rows, baseline };
+        if (evaluateValidationSuccess(tasks[index].success, observation).met) {
+            void finish('success');
+        }
+    };
+    const step = () => {
+        if (current.phase !== 'running')
+            return;
+        current = { ...current, steps: current.steps + 1 };
+        emit();
+    };
+    const stopRoute = options.route.subscribe(() => {
+        step();
+        evaluate();
+    });
+    const stopPending = options.runtime.pending?.subscribe((operations) => {
+        for (const operation of operations) {
+            if (operation.kind !== 'service' || seenOperations.has(operation.id))
+                continue;
+            seenOperations.add(operation.id);
+            step();
+        }
+    }) ?? (() => { });
+    const subscription = tables.size > 0
+        ? liveQuery(() => readRows(options.runtime.db, tables)).subscribe({
+            next: (value) => {
+                rows = value;
+                evaluate();
+            },
+            error: (error) => console.error('[protoyard player] validation data', error),
+        })
+        : null;
+    return {
+        state,
+        subscribe(listener) {
+            listeners.add(listener);
+            listener(state());
+            return () => listeners.delete(listener);
+        },
+        async start() {
+            if (current.phase === 'running')
+                return;
+            rows = tables.size > 0 ? await readRows(options.runtime.db, tables) : {};
+            baseline = validationBaseline(rows);
+            current = { phase: 'running', startedAt: now(), steps: 0 };
+            const limit = tasks[index].timeLimitSeconds;
+            if (limit !== undefined)
+                timer = setTimer(() => void finish('timed-out'), limit * 1000);
+            emit();
+            evaluate();
+        },
+        giveUp: () => finish('gave-up'),
+        next() {
+            if (current.phase !== 'done' || index >= tasks.length - 1)
+                return;
+            index += 1;
+            current = { phase: 'ready' };
+            emit();
+        },
+        close() {
+            if (timer !== null)
+                clearTimer(timer);
+            stopRoute();
+            stopPending();
+            subscription?.unsubscribe();
+            listeners.clear();
+        },
+    };
+}
+/** The hash route (`#/bookings` → `/bookings`), with `hashchange` as its signal. */
+export function hashRoute(win) {
+    return {
+        current: () => win.location.hash.replace(/^#/, '') || '/',
+        subscribe(listener) {
+            win.addEventListener('hashchange', listener);
+            return () => win.removeEventListener('hashchange', listener);
+        },
+    };
+}

package/dist/boot/validation/store.d.ts

@@ -0,0 +1,49 @@
+import type { ValidationAttempt } from './session.ts';
+/**
+ * Validation metrics, stored per blueprint in the browser
+ * (`protoyard.<namespace>.validation`), next to the blueprint's data and
+ * control databases and never sent anywhere. They can be downloaded as a
+ * `protoyard-validation-metrics` v1 file for `protoyard quick report`.
+ */
+export declare const VALIDATION_METRICS_FORMAT = "protoyard-validation-metrics";
+export declare const VALIDATION_METRICS_VERSION = 1;
+export declare function validationDatabaseName(namespace: string): string;
+export interface ValidationMetricsFile {
+    format: typeof VALIDATION_METRICS_FORMAT;
+    version: typeof VALIDATION_METRICS_VERSION;
+    blueprint: {
+        name: string;
+        namespace: string;
+    };
+    exportedAt: string;
+    tasks: {
+        id: string;
+        prompt: string;
+    }[];
+    attempts: ValidationAttempt[];
+}
+/** Checks an attempt before it is stored (the player has no schema library). */
+export declare function assertAttempt(value: ValidationAttempt): ValidationAttempt;
+export interface ValidationStore {
+    record(attempt: ValidationAttempt): Promise<void>;
+    list(): Promise<ValidationAttempt[]>;
+    clear(): Promise<void>;
+    close(): void;
+}
+export declare function openValidationStore(namespace: string, options?: {
+    indexedDB?: IDBFactory;
+    IDBKeyRange?: typeof IDBKeyRange;
+}): ValidationStore;
+/** The download file: tasks and attempts, nothing else from the prototype. */
+export declare function metricsFile(input: {
+    name: string;
+    namespace: string;
+    tasks: readonly {
+        id: string;
+        prompt: string;
+    }[];
+    attempts: readonly ValidationAttempt[];
+    now?: () => Date;
+}): ValidationMetricsFile;
+/** Saves the metrics file through the browser's download, with no upload. */
+export declare function downloadMetrics(file: ValidationMetricsFile, doc?: Document): string;