@protoyard/player 0.0.0-stage → 1.1.0

package/dist/embed/origins.js

@@ -0,0 +1,67 @@
+/**
+ * Which pages may hand the player a blueprint (the embedding decision on
+ * `postMessage` origins): the player's own origin, plus origins named in
+ * `?embedder=` that ALSO match the build-time allowlist. Matching is on the
+ * exact serialized origin (`scheme://host[:port]`); `*`, `null`, paths,
+ * credentials and non-http(s) schemes never qualify.
+ */
+/** protoyard.app, and local development on any port. */
+export const DEFAULT_ALLOWLIST = Object.freeze([
+    { origin: 'https://protoyard.app' },
+    { host: 'localhost', schemes: ['http:', 'https:'] },
+    { host: '127.0.0.1', schemes: ['http:', 'https:'] },
+]);
+/**
+ * The CSP `frame-ancestors` sources for `rules`, so the pages allowed to
+ * frame the player are exactly the pages allowed to send it a blueprint
+ * (`vite.config.ts` builds PLAYER_FRAME_ANCESTORS from DEFAULT_ALLOWLIST).
+ */
+export function frameAncestorSources(rules) {
+    return rules.flatMap((rule) => 'origin' in rule ? [rule.origin] : rule.schemes.map((scheme) => `${scheme}//${rule.host}:*`));
+}
+/** The canonical origin `value` names, or null when it is not exactly an origin. */
+export function exactOrigin(value) {
+    const text = value.trim();
+    if (text === '' || text === '*' || text === 'null')
+        return null;
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    if (url.username || url.password)
+        return null;
+    // Exactly an origin: no path, query or fragment (a bare trailing "/" is fine).
+    if ((url.pathname !== '/' && url.pathname !== '') || url.search || url.hash)
+        return null;
+    if (text.replace(/\/$/, '') !== url.origin)
+        return null;
+    return url.origin;
+}
+export function allowedByRules(origin, rules) {
+    const url = new URL(origin);
+    return rules.some((rule) => 'origin' in rule
+        ? rule.origin === origin
+        : rule.host === url.hostname && rule.schemes.includes(url.protocol));
+}
+/**
+ * The origins the player listens to. `search` is `location.search`;
+ * `?embedder=` may repeat. `selfOrigin` is `location.origin` (dropped when it
+ * is opaque, e.g. a `file:` page reports "null").
+ */
+export function embedderOrigins(search, selfOrigin, rules = DEFAULT_ALLOWLIST) {
+    const origins = new Set();
+    const self = exactOrigin(selfOrigin);
+    if (self)
+        origins.add(self);
+    for (const value of new URLSearchParams(search).getAll('embedder')) {
+        const origin = exactOrigin(value);
+        if (origin && allowedByRules(origin, rules))
+            origins.add(origin);
+    }
+    return [...origins];
+}

package/dist/embed/protocol.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `protoyard-player/1`: how an embedding page (protoyard.app/play, `protoyard
+ * quick`, a local tool) hands the player a blueprint over `postMessage`.
+ *
+ *   player → parent   ready   { accepts, maxBytes }      once, when listening
+ *   parent → player   load    { id, blueprint }          run a blueprint
+ *   parent → player   replace { id, blueprint }          live iterate: swap it
+ *   player → parent   loaded  { id, namespace, name }    it is running
+ *   player → parent   error   { id, issues }             it is not (with fixes)
+ *
+ * Every message carries `protocol: 'protoyard-player/1'`. Messages from any
+ * other window or origin, or that are not this protocol, are ignored without
+ * a reply. A blueprint is data: it goes through `loadUntrustedDocument`
+ * before anything derives or renders it, and nothing in a message executes.
+ */
+export declare const PLAYER_PROTOCOL = "protoyard-player/1";
+/** Largest blueprint a message may carry (UTF-8 bytes of its JSON), the loader's cap. */
+export declare const MAX_MESSAGE_BLUEPRINT_BYTES: number;
+export type PlayerIssueCode = 'invalid-message' | 'too-large' | 'superseded' | 'boot-failed' | 'invalid-input' | 'too-deep' | 'too-many' | 'unsafe-key' | 'invalid-json' | 'invalid-blueprint';
+export interface PlayerIssue {
+    code: PlayerIssueCode;
+    path: (string | number)[];
+    message: string;
+    fix: string;
+}
+export type PlayerRequestType = 'load' | 'replace';
+/** A request after shape checks; `blueprint` is still untrusted. */
+export interface PlayerRequest {
+    protocol: typeof PLAYER_PROTOCOL;
+    type: PlayerRequestType;
+    id: string;
+    blueprint: unknown;
+}
+export type PlayerMessage = {
+    protocol: typeof PLAYER_PROTOCOL;
+    type: 'ready';
+    accepts: PlayerRequestType[];
+    maxBytes: number;
+} | {
+    protocol: typeof PLAYER_PROTOCOL;
+    type: 'loaded';
+    id: string;
+    namespace: string;
+    name: string;
+} | {
+    protocol: typeof PLAYER_PROTOCOL;
+    type: 'error';
+    id: string;
+    issues: PlayerIssue[];
+};
+/** What a message turned out to be: not ours (ignore), a bad request (reply), or a request. */
+export type RequestCheck = {
+    kind: 'ignore';
+} | {
+    kind: 'reject';
+    id: string;
+    issues: PlayerIssue[];
+} | {
+    kind: 'request';
+    request: PlayerRequest;
+};
+/** UTF-8 size of a blueprint payload as JSON, or null when it cannot be serialized. */
+export declare function payloadBytes(blueprint: unknown): number | null;
+declare const issue: (code: PlayerIssueCode, message: string, fix: string) => PlayerIssue;
+/**
+ * Classifies a received `data` value. Anything that is not a well-formed
+ * `protoyard-player/1` request with a usable id is ignored (there is no id to
+ * answer); a request with a bad payload is rejected with issues.
+ */
+export declare function checkRequest(data: unknown, maxBytes?: number): RequestCheck;
+/** Validates a message the player sent (used by the embedding client). */
+export declare function isPlayerMessage(data: unknown): data is PlayerMessage;
+export { issue as playerIssue };

package/dist/embed/protocol.js

@@ -0,0 +1,123 @@
+import { DEFAULT_UNTRUSTED_BLUEPRINT_LIMITS } from '@protoyard/blueprint';
+/**
+ * `protoyard-player/1`: how an embedding page (protoyard.app/play, `protoyard
+ * quick`, a local tool) hands the player a blueprint over `postMessage`.
+ *
+ *   player → parent   ready   { accepts, maxBytes }      once, when listening
+ *   parent → player   load    { id, blueprint }          run a blueprint
+ *   parent → player   replace { id, blueprint }          live iterate: swap it
+ *   player → parent   loaded  { id, namespace, name }    it is running
+ *   player → parent   error   { id, issues }             it is not (with fixes)
+ *
+ * Every message carries `protocol: 'protoyard-player/1'`. Messages from any
+ * other window or origin, or that are not this protocol, are ignored without
+ * a reply. A blueprint is data: it goes through `loadUntrustedDocument`
+ * before anything derives or renders it, and nothing in a message executes.
+ */
+export const PLAYER_PROTOCOL = 'protoyard-player/1';
+/** Largest blueprint a message may carry (UTF-8 bytes of its JSON), the loader's cap. */
+export const MAX_MESSAGE_BLUEPRINT_BYTES = DEFAULT_UNTRUSTED_BLUEPRINT_LIMITS.maxBytes;
+const ID = /^[A-Za-z0-9._:-]{1,64}$/;
+const REQUEST_KEYS = new Set(['protocol', 'type', 'id', 'blueprint']);
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function utf8Length(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+/** UTF-8 size of a blueprint payload as JSON, or null when it cannot be serialized. */
+export function payloadBytes(blueprint) {
+    if (typeof blueprint === 'string')
+        return utf8Length(blueprint);
+    try {
+        const json = JSON.stringify(blueprint);
+        return json === undefined ? null : utf8Length(json);
+    }
+    catch {
+        return null;
+    }
+}
+const issue = (code, message, fix) => ({
+    code,
+    path: [],
+    message,
+    fix,
+});
+/**
+ * Classifies a received `data` value. Anything that is not a well-formed
+ * `protoyard-player/1` request with a usable id is ignored (there is no id to
+ * answer); a request with a bad payload is rejected with issues.
+ */
+export function checkRequest(data, maxBytes = MAX_MESSAGE_BLUEPRINT_BYTES) {
+    if (!isPlainObject(data) || data.protocol !== PLAYER_PROTOCOL)
+        return { kind: 'ignore' };
+    if (data.type !== 'load' && data.type !== 'replace')
+        return { kind: 'ignore' };
+    if (typeof data.id !== 'string' || !ID.test(data.id))
+        return { kind: 'ignore' };
+    const id = data.id;
+    const extra = Object.keys(data).filter((key) => !REQUEST_KEYS.has(key));
+    if (extra.length > 0) {
+        return {
+            kind: 'reject',
+            id,
+            issues: [
+                issue('invalid-message', `Unknown message field${extra.length > 1 ? 's' : ''}: ${extra.slice(0, 5).join(', ')}.`, 'Send only protocol, type, id and blueprint.'),
+            ],
+        };
+    }
+    const blueprint = data.blueprint;
+    if (typeof blueprint !== 'string' && !isPlainObject(blueprint)) {
+        return {
+            kind: 'reject',
+            id,
+            issues: [
+                issue('invalid-message', 'The message has no blueprint (a JSON object or its JSON text).', 'Put the blueprint object, or its JSON string, in the blueprint field.'),
+            ],
+        };
+    }
+    const bytes = payloadBytes(blueprint);
+    if (bytes === null) {
+        return {
+            kind: 'reject',
+            id,
+            issues: [
+                issue('invalid-message', 'The blueprint cannot be serialized as JSON.', 'Send plain JSON data: no cycles, functions or class instances.'),
+            ],
+        };
+    }
+    if (bytes > maxBytes) {
+        return {
+            kind: 'reject',
+            id,
+            issues: [
+                issue('too-large', `The blueprint is ${bytes} bytes; the player accepts at most ${maxBytes}.`, 'Trim the blueprint (fewer entities, screens or seed rows).'),
+            ],
+        };
+    }
+    return {
+        kind: 'request',
+        request: { protocol: PLAYER_PROTOCOL, type: data.type, id, blueprint },
+    };
+}
+/** Validates a message the player sent (used by the embedding client). */
+export function isPlayerMessage(data) {
+    if (!isPlainObject(data) || data.protocol !== PLAYER_PROTOCOL)
+        return false;
+    switch (data.type) {
+        case 'ready':
+            return Array.isArray(data.accepts) && typeof data.maxBytes === 'number';
+        case 'loaded':
+            return (typeof data.id === 'string' &&
+                typeof data.namespace === 'string' &&
+                typeof data.name === 'string');
+        case 'error':
+            return typeof data.id === 'string' && Array.isArray(data.issues);
+        default:
+            return false;
+    }
+}
+export { issue as playerIssue };

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@protoyard/player",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "A prebuilt, static Protoyard app that runs any blueprint at runtime: IndexedDB, personas, scenarios, simulated time, DevTools, themes, layouts and shells, with no build.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./embed": {
+      "types": "./dist/embed/index.d.ts",
+      "import": "./dist/embed/index.js",
+      "default": "./dist/embed/index.js"
+    },
+    "./boot": {
+      "types": "./dist/boot/boot.d.ts",
+      "import": "./dist/boot/boot.js",
+      "default": "./dist/boot/boot.js"
+    }
+  },
+  "dependencies": {
+    "@lucide/svelte": "^1.61.0",
+    "@protoyard/ai": "1.1.0",
+    "@protoyard/ai-ui": "1.1.0",
+    "@protoyard/analytics": "1.1.0",
+    "@protoyard/analytics-ui": "1.1.0",
+    "@protoyard/blocks-ui": "1.1.0",
+    "@protoyard/blueprint": "1.1.0",
+    "@protoyard/charts-ui": "1.1.0",
+    "@protoyard/core": "1.1.0",
+    "@protoyard/crud": "1.1.0",
+    "@protoyard/decks-ui": "1.1.0",
+    "@protoyard/pages-ui": "1.1.0",
+    "@protoyard/renderer-svelte": "1.1.0",
+    "@protoyard/saas": "1.1.0",
+    "@protoyard/saas-ui": "1.1.0",
+    "@protoyard/themes": "1.1.0",
+    "@protoyard/ui": "1.1.0",
+    "@protoyard/views-ui": "1.1.0",
+    "dexie": "^4.4.7",
+    "svelte": "^5.57.2",
+    "texuli": "0.12.0"
+  },
+  "devDependencies": {
+    "@protoyard/runtime": "1.1.0",
+    "@protoyard/scenarios": "1.1.0",
+    "tailwindcss": "^4.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DailybotHQ/protoyard",
+    "directory": "packages/player"
+  },
+  "homepage": "https://protoyard.app",
+  "bugs": {
+    "url": "https://github.com/DailybotHQ/protoyard/issues"
+  },
+  "keywords": [
+    "protoyard",
+    "player",
+    "blueprint",
+    "embed"
+  ],
+  "protoyard": {
+    "build": {
+      "group": "engine",
+      "assets": [],
+      "keep": [
+        "app"
+      ],
+      "postBuild": "build:package"
+    },
+    "pack": {
+      "required": [
+        "dist/app/index.html",
+        "dist/app/protoyard-player-assets.json",
+        "dist/embed/index.js",
+        "dist/boot/boot.js"
+      ]
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:package": "node scripts/package-dist.ts && vite build",
+    "preview": "vite preview",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json --threshold error"
+  }
 }