@protoyard/core 0.0.0-stage → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @protoyard/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic contracts for Protoyard: zod schemas, TypeScript
+interfaces, and the small deterministic primitives every other package builds
+on. Its only runtime dependency is `zod`; Faker is imported for types only.
+Nothing here imports Svelte, Dexie or Node APIs.
+
+## Modules
+
+| File | What it defines |
+| --- | --- |
+| `manifest.ts` | `PrototypeManifestSchema` for `protoyard.json` (id, slug, kind, platform, `preview` (viewport, `shell`, `device`, `orientation`, `chrome` with fictional-only origins, optional `layout`), storage namespace + schemaVersion, build flags, scenario ids), `ShellSchema`, `resolveShell` (`auto` → `phone` for mobile, else `none`), the optional marketplace `catalog` block (`CatalogSchema`, `CATALOG_CATEGORIES`), `parseManifest`, `MANIFEST_FILENAME` |
+| `slug.ts` | `checkSlug` / `isValidSlug` / `slugify`, reserved slugs. This is the path-safety gate for the CLI. |
+| `prototype.ts` | `definePrototype` and `PrototypeDefinition` (manifest, `DatabaseDefinition` versions/migrations, scenarios, `generate`, optional context-free `generateWorld(scenario)` used for scenario loads, `generatorVersion`, `policy`, `integrity`, `themes`, `timeline`, `applyEvent`), `WorldSeed`, `GenerateContext`, `RESERVED_TABLES` |
+| `scenario.ts` | `ScenarioSchema` and its independent axes (organization, actor, density, activity, environment, appearance, generator knobs), `defineScenario`, `parseScenarioLink` / `buildScenarioLink` for safe reproducible links (including `?shell=` and `?layout=`) |
+| `manifest.ts` | `PrototypeManifestSchema` for `protoyard.json` (id, slug, kind, platform, `preview` (viewport, `shell`, `device`, `orientation`, `chrome` with fictional-only origins), storage namespace + schemaVersion, build flags including the optional `build.review` (`ReviewBuildSchema`, `resolveReviewBuild`: adapter `local`/`cloudflare`/`http`/`artifact`, safe endpoint, Cloudflare store `kv`/`d1`; ADR-025), scenario ids), `ShellSchema`, `resolveShell` (`auto` → `phone` for mobile, else `none`), the optional marketplace `catalog` block (`CatalogSchema`, `CATALOG_CATEGORIES`), `parseManifest`, `MANIFEST_FILENAME` |
+| `scenario.ts` | `ScenarioSchema` and its independent axes (organization, actor, density, activity, environment, appearance, generator knobs), `defineScenario`, `parseScenarioLink` / `buildScenarioLink` for safe reproducible links (including `?shell=`, and `review` from `?comments=0/1` and `?review=<key>`, `REVIEW_KEY_PATTERN`) |
+| `session.ts` | `Organization`, `Persona` (optional `avatar`: an `av-NNN` library id, an `https://` URL or a root-relative path, checked by `isPersonaAvatar` / `PersonaAvatarSchema`), `Membership`, capability-based `createPermissionPolicy` (wildcards, `-denials`, record rules), `PermissionDeniedError`, `resolvePrincipal` |
+| `clock.ts` | `createSimulationClock` (preview vs committed time), `createTimeHelpers`, `Duration` |
+| `time.ts` | `nextMonotonicIso(lastIso, now)` — ISO timestamps that advance by at least 1 ms so rows sorted by `at` keep insertion order while the simulated clock is paused |
+| `environment.ts` | `createSimulationEnvironment` (network, latency, reproducible failure modes with optional `failureScope`, subscription, flags), `EnvironmentPatchSchema` (partial **without** defaults), `SimulatedServiceError` |
+| `random.ts` | Seeded `createRng` (mulberry32) with `fork`, deterministic `createIdFactory`, `createRuntimeId` for user-created rows |
+| `events.ts` | `DomainEvent` envelope and deterministic `eventId()` |
+| `overrides.ts` | `OverridesSchema`, `resolveEffective` and the value sources (override › preference › scenario › default) |
+| `snapshot.ts` | `SnapshotSchema`, `validateSnapshot` and `parseSnapshotText` (size limit, wrong-prototype rejection, schema-version checks). These never throw on untrusted input. |
+| `devices.ts` | Brand-neutral device catalog (`DEVICES`, `DeviceSpecSchema`: CSS size, corner radius, portrait/landscape safe areas, status bar, home indicator, cutout), `getDevice`, `rotate`, `orient`, `safeAreaOf`, `fitScale`. Data only, no DOM. |
+| `layouts.ts` | App layout contract (ADR-023): `LAYOUT_IDS` / `LayoutIdSchema` (`custom` is the default: the prototype renders its own), `LayoutSettingsSchema` for `preview.layout` (`{ id, supported?, options? }`), the `LAYOUTS` catalog (label, platforms, `minWidth`, `fallback`), `getLayout`, `layoutChoices`, `layoutForWidth`. Data only, no DOM. |
+| `theme.ts` | `ThemeSchema`, the token palette, the optional `style` profile (`ThemeStyleSchema`, `DEFAULT_THEME_STYLE`, `resolveThemeStyle`: typography, shape, elevation, surface, motion, focus ring), `defineTheme`, `tokenToCssVar` (`--tx-*`) |
+| `validation.ts` | `ValidationError` (`issues`: field path → first message, `form` for root issues) and `parseInput(schema, input)` for service inputs; `runService` in `@protoyard/renderer-svelte` leaves these errors to the form |
+| `review.ts` | Subpath `@protoyard/core/review` only (not in the barrel, so builds without review pay nothing): `ReviewCommentSchema` (`formatVersion` 1, plain-text body 1–2,000 characters, self-declared author 1–60 characters, wall-clock ISO timestamps), `ReviewAnchorSchema`, `ReviewContextSchema`, `ReviewThreadSchema`, `groupReviewThreads`, `safeParseReviewComment`, `REVIEW_LIMITS`. Comments are untrusted text: control and bidi-override characters are rejected, and nothing here renders markup. |
+| `runtime.ts` | `PrototypeRuntime` and its controllers (scenarios, session, overrides, theme, snapshots, data inspector), implemented by `@protoyard/runtime` |
+
+## Example
+
+```ts
+import { createPermissionPolicy, createRng, createSimulationClock } from '@protoyard/core';
+
+const rng = createRng(42);
+rng.int(1, 6); // same value on every machine for seed 42
+
+const clock = createSimulationClock({ referenceTime: '2026-10-16T10:00:00Z' });
+clock.preview({ days: 7 }); // UI-only; data is untouched
+clock.clearPreview();
+
+const policy = createPermissionPolicy({
+  roles: { admin: ['*', '-billing:manage'], viewer: ['deals:read'] },
+});
+```
+
+## Rules for changes
+
+- Additive changes only, unless every consumer is updated in the same change.
+  Contracts are shared by all packages and prototypes.
+- Erasable TypeScript only (`erasableSyntaxOnly`): no parameter properties,
+  enums or namespaces. Vite loads configs through Node's type stripping.
+- Tests live in `tests/core.test.ts` (one file since PLAN_009). Run them with
+  `pnpm vitest run packages/core` and type-check with
+  `pnpm --filter @protoyard/core typecheck`.
+
+## Package output
+
+The manifest keeps TypeScript source exports for workspace development. `pnpm build:packages --filter engine` creates the ESM and declaration files under `dist/` that the packed manifest exposes.

package/dist/clock.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The simulation clock. Prototype code reads "now" from here, never from
+ * `Date.now()`, so scenarios render the same world on every machine.
+ *
+ * Two distinct operations (docs/SCENARIOS.md → "Time"):
+ *  - **Preview** (`setTime`, `previewOffset`) only moves the clock the UI sees.
+ *    No data changes.
+ *  - **Advance** is a scenario-controller operation that ALSO commits
+ *    deterministic timeline events up to the new instant (idempotent through
+ *    event ids + a checkpoint). The clock itself only records the instant.
+ */
+export declare const MS_PER_MINUTE = 60000;
+export declare const MS_PER_HOUR = 3600000;
+export declare const MS_PER_DAY = 86400000;
+export interface Duration {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}
+export declare function durationToMs(duration: Duration): number;
+export interface ClockState {
+    /** ISO instant the scenario was generated against. */
+    referenceTime: string;
+    /** Committed offset from the reference (moves with `advance`). */
+    committedOffsetMs: number;
+    /** Extra preview-only offset on top of the committed instant. */
+    previewOffsetMs: number;
+    /** When true, `now()` follows wall-clock time from the effective instant. */
+    running: boolean;
+    /** Wall-clock ms when `running` was last enabled (internal). */
+    runningSince?: number;
+}
+export interface SimulationClock {
+    /** The effective simulated instant. */
+    now(): Date;
+    nowMs(): number;
+    /** Scenario reference instant (time zero of the seeded world). */
+    reference(): Date;
+    /** The committed instant (reference + committed offset), without preview. */
+    committed(): Date;
+    /** True when a preview offset is active. */
+    isPreviewing(): boolean;
+    /** Preview-only: shows the UI at `date` without touching data. */
+    setTime(date: Date | string): void;
+    /** Preview-only: shifts the preview by a duration. */
+    preview(duration: Duration): void;
+    /** Drops the preview offset; back to the committed instant. */
+    clearPreview(): void;
+    /** Records a committed advance. Callers commit timeline events first. */
+    commitAdvance(duration: Duration): void;
+    /** Resets to the scenario reference time (no preview, no committed offset). */
+    resetClock(): void;
+    /** Helpers relative to the effective instant. */
+    daysAgo(days: number): Date;
+    daysFromNow(days: number): Date;
+    getState(): ClockState;
+    setState(state: ClockState): void;
+    subscribe(listener: (state: ClockState) => void): () => void;
+}
+export declare function createSimulationClock(initial: Pick<ClockState, 'referenceTime'> & Partial<ClockState>, wallClock?: () => number): SimulationClock;
+/** Time helpers bound to a fixed instant — used by seed generators. */
+export interface TimeHelpers {
+    /** The scenario reference instant. */
+    now: Date;
+    daysAgo(days: number, jitterHours?: number): Date;
+    hoursAgo(hours: number): Date;
+    daysFromNow(days: number): Date;
+    /** Uniformly random instant between two dates (needs an rng). */
+    between(from: Date, to: Date, next: () => number): Date;
+    iso(date: Date): string;
+}
+export declare function createTimeHelpers(referenceTime: string | Date): TimeHelpers;

package/dist/clock.js

@@ -0,0 +1,105 @@
+/**
+ * The simulation clock. Prototype code reads "now" from here, never from
+ * `Date.now()`, so scenarios render the same world on every machine.
+ *
+ * Two distinct operations (docs/SCENARIOS.md → "Time"):
+ *  - **Preview** (`setTime`, `previewOffset`) only moves the clock the UI sees.
+ *    No data changes.
+ *  - **Advance** is a scenario-controller operation that ALSO commits
+ *    deterministic timeline events up to the new instant (idempotent through
+ *    event ids + a checkpoint). The clock itself only records the instant.
+ */
+export const MS_PER_MINUTE = 60_000;
+export const MS_PER_HOUR = 3_600_000;
+export const MS_PER_DAY = 86_400_000;
+export function durationToMs(duration) {
+    return ((duration.days ?? 0) * MS_PER_DAY +
+        (duration.hours ?? 0) * MS_PER_HOUR +
+        (duration.minutes ?? 0) * MS_PER_MINUTE +
+        (duration.seconds ?? 0) * 1000);
+}
+export function createSimulationClock(initial, wallClock = () => Date.now()) {
+    const referenceMs = Date.parse(initial.referenceTime);
+    if (Number.isNaN(referenceMs)) {
+        throw new RangeError(`Invalid referenceTime: ${initial.referenceTime}`);
+    }
+    let state = {
+        referenceTime: initial.referenceTime,
+        committedOffsetMs: initial.committedOffsetMs ?? 0,
+        previewOffsetMs: initial.previewOffsetMs ?? 0,
+        running: initial.running ?? false,
+        ...(initial.runningSince !== undefined ? { runningSince: initial.runningSince } : {}),
+    };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener(state);
+    };
+    const ref = () => Date.parse(state.referenceTime);
+    const committedMs = () => ref() + state.committedOffsetMs;
+    const effectiveMs = () => {
+        const drift = state.running && state.runningSince !== undefined ? wallClock() - state.runningSince : 0;
+        return committedMs() + state.previewOffsetMs + drift;
+    };
+    return {
+        now: () => new Date(effectiveMs()),
+        nowMs: effectiveMs,
+        reference: () => new Date(ref()),
+        committed: () => new Date(committedMs()),
+        isPreviewing: () => state.previewOffsetMs !== 0,
+        setTime(date) {
+            const target = typeof date === 'string' ? Date.parse(date) : date.getTime();
+            if (Number.isNaN(target))
+                throw new RangeError('setTime(): invalid date');
+            state = { ...state, previewOffsetMs: target - committedMs() };
+            emit();
+        },
+        preview(duration) {
+            state = { ...state, previewOffsetMs: state.previewOffsetMs + durationToMs(duration) };
+            emit();
+        },
+        clearPreview() {
+            state = { ...state, previewOffsetMs: 0 };
+            emit();
+        },
+        commitAdvance(duration) {
+            const ms = durationToMs(duration);
+            if (ms < 0)
+                throw new RangeError('commitAdvance(): time only moves forward');
+            state = { ...state, committedOffsetMs: state.committedOffsetMs + ms };
+            emit();
+        },
+        resetClock() {
+            state = {
+                referenceTime: state.referenceTime,
+                committedOffsetMs: 0,
+                previewOffsetMs: 0,
+                running: false,
+            };
+            emit();
+        },
+        daysAgo: (days) => new Date(effectiveMs() - days * MS_PER_DAY),
+        daysFromNow: (days) => new Date(effectiveMs() + days * MS_PER_DAY),
+        getState: () => ({ ...state }),
+        setState(next) {
+            state = { ...next };
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+export function createTimeHelpers(referenceTime) {
+    const ref = typeof referenceTime === 'string' ? new Date(referenceTime) : referenceTime;
+    const base = ref.getTime();
+    return {
+        now: new Date(base),
+        daysAgo: (days, jitterHours = 0) => new Date(base - days * MS_PER_DAY - jitterHours * MS_PER_HOUR),
+        hoursAgo: (hours) => new Date(base - hours * MS_PER_HOUR),
+        daysFromNow: (days) => new Date(base + days * MS_PER_DAY),
+        between: (from, to, next) => new Date(from.getTime() + next() * (to.getTime() - from.getTime())),
+        iso: (date) => date.toISOString(),
+    };
+}

package/dist/devices.d.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import type { ResolvedShell, ViewportPreset } from './manifest.ts';
+/**
+ * Brand-neutral device catalog: the single source of truth for device frames
+ * (renderer shells), the DevTools device picker and the gallery preview.
+ *
+ * Entries are data only (no DOM, no framework), so the gallery can reuse them
+ * while depending only on `@protoyard/core`. Labels describe a form factor
+ * ("Phone (pill cutout)"), never a real device model, vendor or OS mark.
+ * Sizes are CSS pixels; insets are the safe-area insets a frame feeds into
+ * `--py-safe-*` for the given orientation.
+ */
+export declare const DeviceKindSchema: z.ZodEnum<{
+    desktop: "desktop";
+    tablet: "tablet";
+    phone: "phone";
+    laptop: "laptop";
+}>;
+export type DeviceKind = z.infer<typeof DeviceKindSchema>;
+export declare const OrientationSchema: z.ZodEnum<{
+    portrait: "portrait";
+    landscape: "landscape";
+}>;
+export type Orientation = z.infer<typeof OrientationSchema>;
+/** Camera cutout drawn by phone and tablet frames. */
+export declare const CutoutStyleSchema: z.ZodEnum<{
+    none: "none";
+    pill: "pill";
+    "punch-hole": "punch-hole";
+    notch: "notch";
+}>;
+export type CutoutStyle = z.infer<typeof CutoutStyleSchema>;
+/**
+ * `split`: clock and indicators sit left and right of a central cutout.
+ * `standard`: clock left, indicators right, no gap. `none`: no status bar.
+ */
+export declare const StatusBarStyleSchema: z.ZodEnum<{
+    none: "none";
+    split: "split";
+    standard: "standard";
+}>;
+export type StatusBarStyle = z.infer<typeof StatusBarStyleSchema>;
+export declare const SafeAreaInsetsSchema: z.ZodObject<{
+    top: z.ZodNumber;
+    right: z.ZodNumber;
+    bottom: z.ZodNumber;
+    left: z.ZodNumber;
+}, z.core.$strict>;
+export type SafeAreaInsets = z.infer<typeof SafeAreaInsetsSchema>;
+export declare const DEVICE_IDS: readonly ["phone-pill", "phone-punch-hole", "tablet", "laptop-window", "desktop-window"];
+export declare const DeviceIdSchema: z.ZodEnum<{
+    tablet: "tablet";
+    "desktop-window": "desktop-window";
+    "phone-pill": "phone-pill";
+    "phone-punch-hole": "phone-punch-hole";
+    "laptop-window": "laptop-window";
+}>;
+export type DeviceId = z.infer<typeof DeviceIdSchema>;
+export declare const DeviceSpecSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        tablet: "tablet";
+        "desktop-window": "desktop-window";
+        "phone-pill": "phone-pill";
+        "phone-punch-hole": "phone-punch-hole";
+        "laptop-window": "laptop-window";
+    }>;
+    label: z.ZodString;
+    kind: z.ZodEnum<{
+        desktop: "desktop";
+        tablet: "tablet";
+        phone: "phone";
+        laptop: "laptop";
+    }>;
+    orientation: z.ZodEnum<{
+        portrait: "portrait";
+        landscape: "landscape";
+    }>;
+    rotatable: z.ZodBoolean;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    cornerRadius: z.ZodNumber;
+    safeArea: z.ZodObject<{
+        portrait: z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+        }, z.core.$strict>;
+        landscape: z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    statusBar: z.ZodObject<{
+        height: z.ZodNumber;
+        style: z.ZodEnum<{
+            none: "none";
+            split: "split";
+            standard: "standard";
+        }>;
+    }, z.core.$strict>;
+    homeIndicator: z.ZodObject<{
+        height: z.ZodNumber;
+    }, z.core.$strict>;
+    cutout: z.ZodEnum<{
+        none: "none";
+        pill: "pill";
+        "punch-hole": "punch-hole";
+        notch: "notch";
+    }>;
+}, z.core.$strict>;
+export type DeviceSpec = z.infer<typeof DeviceSpecSchema>;
+/** Every catalog entry, in picker order. Deeply frozen. */
+export declare const DEVICES: readonly DeviceSpec[];
+/** Catalog entry by id, or `undefined` for unknown (e.g. untrusted) ids. */
+export declare function getDevice(id: string): DeviceSpec | undefined;
+/** Safe-area insets for the spec's current orientation. */
+export declare function safeAreaOf(spec: DeviceSpec): SafeAreaInsets;
+/**
+ * Turns a device a quarter turn: swaps `width`/`height` and flips the
+ * orientation, so `safeAreaOf()` returns the other orientation's insets.
+ * Non-rotatable devices (windows) are returned unchanged. Never mutates.
+ */
+export declare function rotate(spec: DeviceSpec): DeviceSpec;
+/** The spec in the requested orientation (unchanged when it cannot rotate). */
+export declare function orient(spec: DeviceSpec, orientation: Orientation): DeviceSpec;
+/** Scale that fits a frame of `width` into `available` pixels; never upscales. */
+export declare function fitScale(available: number, width: number): number;
+/** Whether `deviceId` is a catalog device the shell can frame. */
+export declare function deviceFitsShell(deviceId: string, shell: ResolvedShell): boolean;
+/**
+ * The device a shell uses when nothing chose one. The legacy viewport preset
+ * picks the phone style (`android` → punch-hole) and maps `none` to the closest
+ * form factor. Always returns a device that fits the shell.
+ */
+export declare function defaultDeviceFor(shell: ResolvedShell, viewport: ViewportPreset): DeviceId;

package/dist/devices.js

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+/**
+ * Brand-neutral device catalog: the single source of truth for device frames
+ * (renderer shells), the DevTools device picker and the gallery preview.
+ *
+ * Entries are data only (no DOM, no framework), so the gallery can reuse them
+ * while depending only on `@protoyard/core`. Labels describe a form factor
+ * ("Phone (pill cutout)"), never a real device model, vendor or OS mark.
+ * Sizes are CSS pixels; insets are the safe-area insets a frame feeds into
+ * `--py-safe-*` for the given orientation.
+ */
+export const DeviceKindSchema = z.enum(['phone', 'tablet', 'laptop', 'desktop']);
+export const OrientationSchema = z.enum(['portrait', 'landscape']);
+/** Camera cutout drawn by phone and tablet frames. */
+export const CutoutStyleSchema = z.enum(['none', 'pill', 'punch-hole', 'notch']);
+/**
+ * `split`: clock and indicators sit left and right of a central cutout.
+ * `standard`: clock left, indicators right, no gap. `none`: no status bar.
+ */
+export const StatusBarStyleSchema = z.enum(['split', 'standard', 'none']);
+const InsetSchema = z.number().int().nonnegative();
+export const SafeAreaInsetsSchema = z
+    .object({ top: InsetSchema, right: InsetSchema, bottom: InsetSchema, left: InsetSchema })
+    .strict();
+export const DEVICE_IDS = [
+    'phone-pill',
+    'phone-punch-hole',
+    'tablet',
+    'laptop-window',
+    'desktop-window',
+];
+export const DeviceIdSchema = z.enum(DEVICE_IDS);
+export const DeviceSpecSchema = z
+    .object({
+    id: DeviceIdSchema,
+    label: z.string().min(1).max(40),
+    kind: DeviceKindSchema,
+    /** Orientation `width`/`height` describe; `rotate()` flips it. */
+    orientation: OrientationSchema,
+    /** Windows (laptop, desktop) do not rotate. */
+    rotatable: z.boolean(),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    cornerRadius: z.number().int().nonnegative(),
+    safeArea: z
+        .object({ portrait: SafeAreaInsetsSchema, landscape: SafeAreaInsetsSchema })
+        .strict(),
+    statusBar: z.object({ height: InsetSchema, style: StatusBarStyleSchema }).strict(),
+    homeIndicator: z.object({ height: InsetSchema }).strict(),
+    cutout: CutoutStyleSchema,
+})
+    .strict();
+const NO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
+function freeze(spec) {
+    Object.freeze(spec.safeArea.portrait);
+    Object.freeze(spec.safeArea.landscape);
+    Object.freeze(spec.safeArea);
+    Object.freeze(spec.statusBar);
+    Object.freeze(spec.homeIndicator);
+    return Object.freeze(spec);
+}
+/** Every catalog entry, in picker order. Deeply frozen. */
+export const DEVICES = Object.freeze([
+    {
+        id: 'phone-pill',
+        label: 'Phone (pill cutout)',
+        kind: 'phone',
+        orientation: 'portrait',
+        rotatable: true,
+        width: 393,
+        height: 852,
+        cornerRadius: 55,
+        safeArea: {
+            portrait: { top: 59, right: 0, bottom: 34, left: 0 },
+            landscape: { top: 0, right: 59, bottom: 21, left: 59 },
+        },
+        statusBar: { height: 54, style: 'split' },
+        homeIndicator: { height: 34 },
+        cutout: 'pill',
+    },
+    {
+        id: 'phone-punch-hole',
+        label: 'Phone (punch-hole)',
+        kind: 'phone',
+        orientation: 'portrait',
+        rotatable: true,
+        width: 412,
+        height: 915,
+        cornerRadius: 36,
+        safeArea: {
+            portrait: { top: 32, right: 0, bottom: 24, left: 0 },
+            landscape: { top: 0, right: 0, bottom: 24, left: 32 },
+        },
+        statusBar: { height: 32, style: 'standard' },
+        homeIndicator: { height: 24 },
+        cutout: 'punch-hole',
+    },
+    {
+        id: 'tablet',
+        label: 'Tablet',
+        kind: 'tablet',
+        orientation: 'portrait',
+        rotatable: true,
+        width: 820,
+        height: 1180,
+        cornerRadius: 18,
+        safeArea: {
+            portrait: { top: 24, right: 0, bottom: 20, left: 0 },
+            landscape: { top: 24, right: 0, bottom: 20, left: 0 },
+        },
+        statusBar: { height: 24, style: 'standard' },
+        homeIndicator: { height: 20 },
+        cutout: 'none',
+    },
+    {
+        id: 'laptop-window',
+        label: 'Laptop window',
+        kind: 'laptop',
+        orientation: 'landscape',
+        rotatable: false,
+        width: 1280,
+        height: 800,
+        cornerRadius: 10,
+        safeArea: { portrait: { ...NO_INSETS }, landscape: { ...NO_INSETS } },
+        statusBar: { height: 0, style: 'none' },
+        homeIndicator: { height: 0 },
+        cutout: 'none',
+    },
+    {
+        id: 'desktop-window',
+        label: 'Desktop window',
+        kind: 'desktop',
+        orientation: 'landscape',
+        rotatable: false,
+        width: 1440,
+        height: 900,
+        cornerRadius: 10,
+        safeArea: { portrait: { ...NO_INSETS }, landscape: { ...NO_INSETS } },
+        statusBar: { height: 0, style: 'none' },
+        homeIndicator: { height: 0 },
+        cutout: 'none',
+    },
+].map(freeze));
+/** Catalog entry by id, or `undefined` for unknown (e.g. untrusted) ids. */
+export function getDevice(id) {
+    return DEVICES.find((device) => device.id === id);
+}
+/** Safe-area insets for the spec's current orientation. */
+export function safeAreaOf(spec) {
+    return spec.safeArea[spec.orientation];
+}
+/**
+ * Turns a device a quarter turn: swaps `width`/`height` and flips the
+ * orientation, so `safeAreaOf()` returns the other orientation's insets.
+ * Non-rotatable devices (windows) are returned unchanged. Never mutates.
+ */
+export function rotate(spec) {
+    if (!spec.rotatable)
+        return spec;
+    return freeze({
+        ...spec,
+        orientation: spec.orientation === 'portrait' ? 'landscape' : 'portrait',
+        width: spec.height,
+        height: spec.width,
+    });
+}
+/** The spec in the requested orientation (unchanged when it cannot rotate). */
+export function orient(spec, orientation) {
+    return spec.orientation === orientation ? spec : rotate(spec);
+}
+/** Scale that fits a frame of `width` into `available` pixels; never upscales. */
+export function fitScale(available, width) {
+    if (!(available > 0) || !(width > 0))
+        return 1;
+    return Math.min(1, available / width);
+}
+/** Device kinds each shell can frame. `none` renders full-bleed, so any device fits. */
+const SHELL_DEVICE_KINDS = {
+    none: ['phone', 'tablet', 'laptop', 'desktop'],
+    phone: ['phone'],
+    tablet: ['tablet'],
+    'desktop-window': ['laptop', 'desktop'],
+    browser: ['laptop', 'desktop'],
+    'widget-host': ['laptop', 'desktop'],
+    'extension-popup': ['laptop', 'desktop'],
+    'side-panel': ['laptop', 'desktop'],
+};
+/** Whether `deviceId` is a catalog device the shell can frame. */
+export function deviceFitsShell(deviceId, shell) {
+    const device = getDevice(deviceId);
+    return device !== undefined && SHELL_DEVICE_KINDS[shell].includes(device.kind);
+}
+/**
+ * The device a shell uses when nothing chose one. The legacy viewport preset
+ * picks the phone style (`android` → punch-hole) and maps `none` to the closest
+ * form factor. Always returns a device that fits the shell.
+ */
+export function defaultDeviceFor(shell, viewport) {
+    if (shell === 'phone')
+        return viewport === 'android' ? 'phone-punch-hole' : 'phone-pill';
+    if (shell === 'tablet')
+        return 'tablet';
+    if (shell === 'none') {
+        if (viewport === 'iphone')
+            return 'phone-pill';
+        if (viewport === 'android')
+            return 'phone-punch-hole';
+        if (viewport === 'tablet')
+            return 'tablet';
+    }
+    return 'laptop-window';
+}