@cloudcrane/app-spec 0.2.0 → 0.5.0

package/README.md

@@ -19,7 +19,13 @@ if (!spec) for (const p of problems) console.log(`${p.at}: ${p.problem}`);
   date functions and a bounded `fold`.
 - `@cloudcrane/app-spec/schema.json`: the spec as JSON Schema (2020-12).
 - Coded components (`components`): code for what the catalog can't draw, with
-  the kit it runs with (`game`), the inputs it's given and the events it sends.
+  the kit it runs with (`game`, or `page` for a whole HTML page), the inputs
+  it's given and the events it sends. A game kit's code is at most 64 KB and
+  can't contain `</script>`; a page kit's is an HTML page of up to 1 MB.
+- Device features (`uses`): what the app uses, by CloudCrane's names
+  (`camera`, `microphone`, `location`, `motion`, `screen-awake`, `gamepad`,
+  `voice`, `contacts`, `nfc`), each once with why. Anything not listed is
+  blocked. The camera and microphone need a page-kit component.
   A screen places one with the catalog's `Coded` component, binding each input
   to the data model and each event to an action. Its code is exempt from the
   leak scan's code rules, but not from the others.

package/dist/src/blueprint.d.ts

@@ -16,6 +16,7 @@ export type BlueprintV1 = {
     journeys: Spec["journeys"];
     promises: Spec["promises"];
     network: Spec["network"];
+    uses?: Spec["uses"];
     icon?: string;
     category?: string;
     tags?: string[];

package/dist/src/blueprint.js

@@ -54,6 +54,7 @@ export function deriveBlueprint(spec) {
         journeys: spec.journeys,
         promises: spec.promises,
         network: spec.network,
+        ...(spec.uses.length ? { uses: spec.uses } : {}),
         ...(spec.module.icon ? { icon: spec.module.icon } : {}),
         ...(spec.module.category ? { category: spec.module.category } : {}),
         ...(spec.module.tags?.length ? { tags: spec.module.tags } : {}),

package/dist/src/index.d.ts

@@ -7,3 +7,5 @@ export { dates, logicProblems, Rules, fromCel, toCel, MAX_RANGE } from "./logic.
 export { leakProblems } from "./leak.js";
 export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalog } from "./catalog.js";
 export { deriveBlueprint, type BlueprintV1 } from "./blueprint.js";
+export { USES, USE_NAMES, NEEDS_ORIGIN, featuresOf, type Use } from "./uses.js";
+export { pageOf, pageProblems, wrapPage, type PageApp } from "./page.js";

package/dist/src/index.js

@@ -9,3 +9,5 @@ export { dates, logicProblems, Rules, fromCel, toCel, MAX_RANGE } from "./logic.
 export { leakProblems } from "./leak.js";
 export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalog } from "./catalog.js";
 export { deriveBlueprint } from "./blueprint.js";
+export { USES, USE_NAMES, NEEDS_ORIGIN, featuresOf } from "./uses.js";
+export { pageOf, pageProblems, wrapPage } from "./page.js";

package/dist/src/page.d.ts

@@ -0,0 +1,35 @@
+import type { Spec } from "./schema.js";
+/** The spec as the page it is, or null when it isn't one. */
+export declare function pageOf(spec: Spec): string | null;
+type Problem = {
+    at: string;
+    problem: string;
+};
+/** What a spec that says it's a page may hold: the page, full screen, and no logic of its own. */
+export declare function pageProblems(spec: Spec): Problem[];
+/** What an HTML app says about itself, to make its spec from. */
+export type PageApp = {
+    id: string;
+    name: string;
+    purpose: string;
+    html: string;
+    /** What made the spec, like "cloudcrane, from an HTML app" (the leak scan refuses one shaped like a call). */
+    generator: string;
+    /** The runtime version the spec is for; a page needs none, but the spec names the compiler's. */
+    runtime?: string;
+    data: {
+        version: number;
+        key: string;
+    };
+    journeys: Spec["journeys"];
+    promises?: Spec["promises"];
+    network?: Spec["network"];
+    uses?: Spec["uses"];
+    tests?: Spec["tests"];
+    icon?: string;
+    category?: string;
+    tags?: string[];
+};
+/** An HTML app as a spec whose one component is the page, full screen. Check it with validateSpec. */
+export declare function wrapPage(app: PageApp): Record<string, unknown>;
+export {};

package/dist/src/page.js

@@ -0,0 +1,72 @@
+import { CLOUDCRANE_CATALOG_ID } from "./catalog.js";
+// An app written as one HTML page, as a spec. The page is its one page-kit
+// component, and `page` names it: the spec is then the page, and the compiler
+// gives back its HTML as written, with no runtime. It runs, saves and is
+// tested exactly as it would on its own (the same storage keys, the same
+// address, the same tests), while it's described, versioned and checked like
+// any spec. Without `page`, the same component runs in a frame among the
+// spec's own screens.
+/** The spec as the page it is, or null when it isn't one. */
+export function pageOf(spec) {
+    if (!spec.page)
+        return null;
+    const c = spec.components[spec.page];
+    return c?.kit === "page" ? c.code : null;
+}
+/** What a spec that says it's a page may hold: the page, full screen, and no logic of its own. */
+export function pageProblems(spec) {
+    if (!spec.page)
+        return [];
+    const c = spec.components[spec.page];
+    if (c?.kit !== "page")
+        return [{ at: "page", problem: "names no page-kit component" }];
+    const problems = [];
+    if (Object.keys(spec.components).length !== 1)
+        problems.push({ at: "page", problem: "the page is the spec's only component" });
+    if (Object.keys(c.inputs).length || Object.keys(c.events).length)
+        problems.push({ at: "page", problem: "the page takes no inputs and sends no events" });
+    const placed = spec.surface.messages.flatMap((m) => (m["updateComponents"]?.components ?? []));
+    if (placed.length !== 1 || placed[0]["component"] !== "Coded" || placed[0]["use"] !== spec.page)
+        problems.push({ at: "page", problem: "the screen can hold nothing but the page" });
+    const { functions, computed, vectors } = spec.logic;
+    if (Object.keys(functions).length || Object.keys(computed).length || vectors.length || spec.data.views.length || spec.data.migrations.length)
+        problems.push({ at: "page", problem: "a page has no logic, views or migrations of the spec's own: its code keeps its data" });
+    return problems;
+}
+// A page draws itself, so these only satisfy the spec's shape; they're never shown.
+const TOKENS = {
+    color: { $type: "color", background: { $value: "#ffffff" }, "on-background": { $value: "#111111" }, primary: { $value: "#0f766e" } },
+};
+/** An HTML app as a spec whose one component is the page, full screen. Check it with validateSpec. */
+export function wrapPage(app) {
+    return {
+        v: 1,
+        manifest: { runtime: app.runtime ?? "0.0.0", generator: app.generator, source: { fingerprint: `sha256:${"0".repeat(64)}` } },
+        module: {
+            id: app.id,
+            name: app.name,
+            purpose: app.purpose,
+            ...(app.icon ? { icon: app.icon } : {}),
+            ...(app.category ? { category: app.category } : {}),
+            ...(app.tags?.length ? { tags: app.tags } : {}),
+        },
+        tokens: TOKENS,
+        surface: {
+            catalog: CLOUDCRANE_CATALOG_ID,
+            messages: [
+                { version: "v0.9.1", createSurface: { surfaceId: app.id, catalogId: CLOUDCRANE_CATALOG_ID } },
+                { version: "v0.9.1", updateComponents: { surfaceId: app.id, components: [{ id: "root", component: "Coded", use: "page", label: app.name }] } },
+            ],
+        },
+        data: { version: app.data.version, key: app.data.key, persist: "/saved", views: [], schema: { type: "object" }, initial: {}, migrations: [] },
+        logic: { consts: {}, functions: {}, computed: {}, vectors: [] },
+        network: app.network ?? [],
+        uses: app.uses ?? [],
+        journeys: app.journeys,
+        promises: app.promises ?? [],
+        tests: app.tests ?? [],
+        components: { page: { kind: "coded", kit: "page", inputs: {}, events: {}, code: app.html } },
+        page: "page",
+        mods: { open: [], locked: [] },
+    };
+}

package/dist/src/schema.d.ts

@@ -18,42 +18,57 @@ export declare const Tokens: z.ZodType<TokenNode>;
 export declare const CODED_TYPES: readonly ["number", "string", "boolean", "list", "map"];
 /**
  * A coded component: what the catalog can't draw, as the spec's own code, run
- * sandboxed in a frame with a kit (`game`: a loop, a canvas, touch and keys).
+ * sandboxed in a frame with a kit (`game`: a loop, a canvas, touch and keys;
+ * `page`: a whole HTML page, full screen). Either saves through `localStorage`,
+ * which the frame's bridge keeps on the page under the spec's data key.
  * It's given only its declared inputs and may only send its declared events;
  * a screen places it with the catalog's Coded component.
  */
-export declare const CodedComponent: z.ZodEffects<z.ZodObject<{
+export declare const CodedComponent: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     kind: z.ZodLiteral<"coded">;
-    kit: z.ZodEnum<["game"]>;
+    /** game: a canvas, a loop and touch, the code a script; page: a whole HTML page, drawn full screen (what an app written as HTML becomes). */
+    kit: z.ZodEnum<["game", "page"]>;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["number", "string", "boolean", "list", "map"]>>>;
     events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodEnum<["number", "string", "boolean", "list", "map"]>>>>;
-    code: z.ZodEffects<z.ZodString, string, string>;
+    code: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     code: string;
     kind: "coded";
-    kit: "game";
+    kit: "game" | "page";
     inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
     events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
 }, {
     code: string;
     kind: "coded";
-    kit: "game";
+    kit: "game" | "page";
     inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
     events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
 }>, {
     code: string;
     kind: "coded";
-    kit: "game";
+    kit: "game" | "page";
     inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
     events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
 }, {
     code: string;
     kind: "coded";
-    kit: "game";
+    kit: "game" | "page";
+    inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
+    events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
+}>, {
+    code: string;
+    kind: "coded";
+    kit: "game" | "page";
+    inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+    events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+}, {
+    code: string;
+    kind: "coded";
+    kit: "game" | "page";
     inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
     events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
 }>;
-export declare const SpecSchema: z.ZodObject<{
+export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
     v: z.ZodLiteral<1>;
     manifest: z.ZodObject<{
         runtime: z.ZodString;
@@ -251,6 +266,17 @@ export declare const SpecSchema: z.ZodObject<{
         site: string;
         why: string;
     }>, "many">>;
+    /** The device features the app uses, by CloudCrane's names, each once with why; anything not listed is blocked. */
+    uses: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        what: z.ZodEnum<["camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc", ...("camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc")[]]>;
+        why: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        why: string;
+        what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
+    }, {
+        why: string;
+        what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
+    }>, "many">>;
     journeys: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
@@ -295,49 +321,64 @@ export declare const SpecSchema: z.ZodObject<{
     /** CloudCrane's test steps, as its blueprint tests take them; CloudCrane checks their shape. */
     tests: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
     /** Coded components, by name: the spec's own code for what the catalog can't draw. */
-    components: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+    components: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodObject<{
         kind: z.ZodLiteral<"coded">;
-        kit: z.ZodEnum<["game"]>;
+        /** game: a canvas, a loop and touch, the code a script; page: a whole HTML page, drawn full screen (what an app written as HTML becomes). */
+        kit: z.ZodEnum<["game", "page"]>;
         inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["number", "string", "boolean", "list", "map"]>>>;
         events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodEnum<["number", "string", "boolean", "list", "map"]>>>>;
-        code: z.ZodEffects<z.ZodString, string, string>;
+        code: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
     }, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
     }, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
+        inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
+        events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
+    }>, {
+        code: string;
+        kind: "coded";
+        kit: "game" | "page";
+        inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+        events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    }, {
+        code: string;
+        kind: "coded";
+        kit: "game" | "page";
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>>, Record<string, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
     }>, Record<string, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>>>;
+    /** The page-kit component that is the whole app: the spec is then that page, compiled to its HTML as written (see page.ts). */
+    page: z.ZodOptional<z.ZodString>;
     /** What a remix may change and what stays as the partner made it. */
     mods: z.ZodDefault<z.ZodObject<{
         open: z.ZodArray<z.ZodString, "many">;
@@ -353,7 +394,179 @@ export declare const SpecSchema: z.ZodObject<{
     components: Record<string, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
+        inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+        events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    }>;
+    surface: {
+        catalog: string;
+        messages: Record<string, unknown>[];
+    };
+    v: 1;
+    manifest: {
+        runtime: string;
+        generator: string;
+        source: {
+            fingerprint: string;
+        };
+    };
+    module: {
+        name: string;
+        id: string;
+        purpose: string;
+        icon?: string | undefined;
+        category?: string | undefined;
+        tags?: string[] | undefined;
+    };
+    tokens: TokenNode;
+    data: {
+        version: number;
+        key: string;
+        persist: string;
+        schema: Record<string, unknown>;
+        views: {
+            path: string;
+            source: string;
+        }[];
+        migrations: {
+            from: number;
+            to: number;
+            cel: string;
+        }[];
+        initial?: unknown;
+    };
+    logic: {
+        consts: Record<string, string | number | boolean>;
+        functions: Record<string, {
+            params: string[];
+            cel: string;
+        }>;
+        computed: Record<string, string>;
+        vectors: {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }[];
+    };
+    network: {
+        site: string;
+        why: string;
+    }[];
+    uses: {
+        why: string;
+        what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
+    }[];
+    journeys: {
+        title: string;
+        id: string;
+        steps: {
+            text: string;
+            id: string;
+        }[];
+    }[];
+    promises: {
+        text: string;
+        id: string;
+        kind?: "data" | undefined;
+    }[];
+    tests: Record<string, unknown>[];
+    mods: {
+        open: string[];
+        locked: string[];
+    };
+    page?: string | undefined;
+}, {
+    surface: {
+        catalog: string;
+        messages: Record<string, unknown>[];
+    };
+    v: 1;
+    manifest: {
+        runtime: string;
+        generator: string;
+        source: {
+            fingerprint: string;
+        };
+    };
+    module: {
+        name: string;
+        id: string;
+        purpose: string;
+        icon?: string | undefined;
+        category?: string | undefined;
+        tags?: string[] | undefined;
+    };
+    tokens: TokenNode;
+    data: {
+        version: number;
+        key: string;
+        persist: string;
+        schema: Record<string, unknown>;
+        migrations: {
+            from: number;
+            to: number;
+            cel: string;
+        }[];
+        initial?: unknown;
+        views?: {
+            path: string;
+            source: string;
+        }[] | undefined;
+    };
+    logic: {
+        consts?: Record<string, string | number | boolean> | undefined;
+        functions?: Record<string, {
+            params: string[];
+            cel: string;
+        }> | undefined;
+        computed?: Record<string, string> | undefined;
+        vectors?: {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }[] | undefined;
+    };
+    journeys: {
+        title: string;
+        id: string;
+        steps: {
+            text: string;
+            id: string;
+        }[];
+    }[];
+    components?: Record<string, {
+        code: string;
+        kind: "coded";
+        kit: "game" | "page";
+        inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
+        events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
+    }> | undefined;
+    page?: string | undefined;
+    network?: {
+        site: string;
+        why: string;
+    }[] | undefined;
+    uses?: {
+        why: string;
+        what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
+    }[] | undefined;
+    promises?: {
+        text: string;
+        id: string;
+        kind?: "data" | undefined;
+    }[] | undefined;
+    tests?: Record<string, unknown>[] | undefined;
+    mods?: {
+        open: string[];
+        locked: string[];
+    } | undefined;
+}>, {
+    components: Record<string, {
+        code: string;
+        kind: "coded";
+        kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
     }>;
@@ -412,6 +625,10 @@ export declare const SpecSchema: z.ZodObject<{
         site: string;
         why: string;
     }[];
+    uses: {
+        why: string;
+        what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
+    }[];
     journeys: {
         title: string;
         id: string;
@@ -430,6 +647,7 @@ export declare const SpecSchema: z.ZodObject<{
         open: string[];
         locked: string[];
     };
+    page?: string | undefined;
 }, {
     surface: {
         catalog: string;
@@ -493,14 +711,19 @@ export declare const SpecSchema: z.ZodObject<{
     components?: Record<string, {
         code: string;
         kind: "coded";
-        kit: "game";
+        kit: "game" | "page";
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }> | undefined;
+    page?: string | undefined;
     network?: {
         site: string;
         why: string;
     }[] | undefined;
+    uses?: {
+        why: string;
+        what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
+    }[] | undefined;
     promises?: {
         text: string;
         id: string;

package/dist/src/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { NEEDS_ORIGIN, USE_NAMES } from "./uses.js";
 // The CloudCrane app spec: an A2UI surface (the screens) in a small envelope for
 // what A2UI doesn't cover. Nothing in it is code from the app it came from:
 // screens are A2UI components, the look is DTCG design tokens, rules are CEL
@@ -49,23 +50,35 @@ export const CODED_TYPES = ["number", "string", "boolean", "list", "map"];
 const CodedType = z.enum(CODED_TYPES);
 /**
  * A coded component: what the catalog can't draw, as the spec's own code, run
- * sandboxed in a frame with a kit (`game`: a loop, a canvas, touch and keys).
+ * sandboxed in a frame with a kit (`game`: a loop, a canvas, touch and keys;
+ * `page`: a whole HTML page, full screen). Either saves through `localStorage`,
+ * which the frame's bridge keeps on the page under the spec's data key.
  * It's given only its declared inputs and may only send its declared events;
  * a screen places it with the catalog's Coded component.
  */
 export const CodedComponent = z
     .object({
     kind: z.literal("coded"),
-    kit: z.enum(["game"]),
+    /** game: a canvas, a loop and touch, the code a script; page: a whole HTML page, drawn full screen (what an app written as HTML becomes). */
+    kit: z.enum(["game", "page"]),
     inputs: z.record(CelName, CodedType).default({}),
     events: z.record(CelName, z.record(CelName, CodedType)).default({}),
     code: z
         .string()
         .min(1)
-        .max(64 * 1024)
-        .refine((c) => !/<\/script/i.test(c), "can't contain </script>, which would end the frame's script"),
+        .max(1024 * 1024),
 })
     .strict()
+    .superRefine((c, ctx) => {
+    if (c.kit === "game" && /<\/script/i.test(c.code))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["code"],
+            message: "can't contain </script>, which would end the frame's script (a page kit's code can)",
+        });
+    if (c.kit === "game" && c.code.length > 64 * 1024)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["code"], message: "a game kit's code is at most 64 KB" });
+})
     .refine((c) => Object.keys(c.inputs).length <= 10 && Object.keys(c.events).length <= 10, "at most 10 inputs and 10 events");
 export const SpecSchema = z
     .object({
@@ -141,6 +154,11 @@ export const SpecSchema = z
         .array(z.object({ site: z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/), why: Text(300) }).strict())
         .max(5)
         .default([]),
+    /** The device features the app uses, by CloudCrane's names, each once with why; anything not listed is blocked. */
+    uses: z
+        .array(z.object({ what: z.enum(USE_NAMES), why: Text(300) }).strict())
+        .max(USE_NAMES.length)
+        .default([]),
     journeys: z
         .array(z
         .object({
@@ -158,10 +176,23 @@ export const SpecSchema = z
         .record(Id, CodedComponent)
         .refine((c) => Object.keys(c).length <= 5, "at most 5 components")
         .default({}),
+    /** The page-kit component that is the whole app: the spec is then that page, compiled to its HTML as written (see page.ts). */
+    page: Id.optional(),
     /** What a remix may change and what stays as the partner made it. */
     mods: z
         .object({ open: z.array(PointerPattern), locked: z.array(PointerPattern) })
         .strict()
         .default({ open: [], locked: [] }),
 })
-    .strict();
+    .strict()
+    .superRefine((s, ctx) => {
+    const seen = new Set();
+    for (const u of s.uses) {
+        if (seen.has(u.what))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["uses"], message: `${u.what} is listed twice` });
+        seen.add(u.what);
+    }
+    const needsOrigin = s.uses.some((u) => NEEDS_ORIGIN.includes(u.what));
+    if (needsOrigin && !Object.values(s.components).some((c) => c.kit === "page"))
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["uses"], message: "the camera and microphone work only in a page-kit component" });
+});

package/dist/src/uses.d.ts

@@ -0,0 +1,19 @@
+export declare const USES: {
+    readonly camera: readonly ["camera"];
+    readonly microphone: readonly ["microphone"];
+    readonly location: readonly ["geolocation"];
+    readonly motion: readonly ["accelerometer", "gyroscope", "magnetometer"];
+    readonly "screen-awake": readonly ["screen-wake-lock"];
+    readonly gamepad: readonly ["gamepad"];
+    readonly voice: readonly ["microphone"];
+    readonly contacts: readonly [];
+    readonly nfc: readonly [];
+};
+export type Use = keyof typeof USES;
+export declare const USE_NAMES: [Use, ...Use[]];
+/** What a frame with no origin of its own can't have, whatever it's allowed: the browser gives it no camera or microphone. */
+export declare const NEEDS_ORIGIN: readonly Use[];
+/** The browser features for the uses declared, each once, in a fixed order. */
+export declare function featuresOf(uses: readonly {
+    what: string;
+}[]): string[];

package/dist/src/uses.js

@@ -0,0 +1,28 @@
+// The device features an app can declare, by CloudCrane's names, and the
+// browser's Permissions-Policy features each needs. A coded component's frame
+// is allowed those of the features the spec declares. The contact picker and
+// NFC have no browser feature: CloudCrane's lockdown is their only block.
+export const USES = {
+    camera: ["camera"],
+    microphone: ["microphone"],
+    location: ["geolocation"],
+    motion: ["accelerometer", "gyroscope", "magnetometer"],
+    "screen-awake": ["screen-wake-lock"],
+    gamepad: ["gamepad"],
+    voice: ["microphone"],
+    contacts: [],
+    nfc: [],
+};
+export const USE_NAMES = Object.keys(USES);
+/** What a frame with no origin of its own can't have, whatever it's allowed: the browser gives it no camera or microphone. */
+export const NEEDS_ORIGIN = ["camera", "microphone"];
+/** The browser features for the uses declared, each once, in a fixed order. */
+export function featuresOf(uses) {
+    const declared = new Set(uses.map((u) => u.what));
+    const out = new Set();
+    for (const name of USE_NAMES)
+        if (declared.has(name))
+            for (const f of USES[name])
+                out.add(f);
+    return [...out];
+}

package/dist/src/validate.js

@@ -3,6 +3,7 @@ import { catalogFor } from "./catalog.js";
 import { leakProblems } from "./leak.js";
 import { logicProblems } from "./logic.js";
 import { SpecSchema } from "./schema.js";
+import { pageProblems } from "./page.js";
 // Everything wrong with a spec, collected rather than stopping at the first: the
 // envelope's shape, then the A2UI surface, then references between parts.
 const pathOf = (path) => path
@@ -46,7 +47,7 @@ export function validateSpec(input, catalog) {
     for (const m of spec.data.migrations)
         if (m.to !== m.from + 1 || m.to > spec.data.version)
             problems.push({ at: `data.migrations ${m.from}`, problem: "steps go one version at a time, up to data.version" });
-    problems.push(...codedProblems(spec), ...logicProblems(spec), ...leakProblems(spec));
+    problems.push(...codedProblems(spec), ...pageProblems(spec), ...logicProblems(spec), ...leakProblems(spec));
     for (const locked of spec.mods.locked)
         if (spec.mods.open.includes(locked))
             problems.push({ at: `mods ${locked}`, problem: "both open and locked" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcrane/app-spec",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "The CloudCrane app spec: its schema, the expression language its rules are written in, and the checks that keep partner code out of it.",
   "keywords": [
     "cloudcrane",
@@ -46,6 +46,10 @@
       "types": "./dist/src/blueprint.d.ts",
       "default": "./dist/src/blueprint.js"
     },
+    "./uses": {
+      "types": "./dist/src/uses.d.ts",
+      "default": "./dist/src/uses.js"
+    },
     "./schema.json": "./schema/app-spec.v1.json",
     "./package.json": "./package.json"
   },

package/schema/app-spec.v1.json

@@ -333,6 +333,40 @@
       "maxItems": 5,
       "default": []
     },
+    "uses": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "what": {
+            "type": "string",
+            "enum": [
+              "camera",
+              "microphone",
+              "location",
+              "motion",
+              "screen-awake",
+              "gamepad",
+              "voice",
+              "contacts",
+              "nfc"
+            ]
+          },
+          "why": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          }
+        },
+        "required": [
+          "what",
+          "why"
+        ],
+        "additionalProperties": false
+      },
+      "maxItems": 9,
+      "default": []
+    },
     "journeys": {
       "type": "array",
       "items": {
@@ -428,7 +462,8 @@
           "kit": {
             "type": "string",
             "enum": [
-              "game"
+              "game",
+              "page"
             ]
           },
           "inputs": {
@@ -474,7 +509,7 @@
           "code": {
             "type": "string",
             "minLength": 1,
-            "maxLength": 65536
+            "maxLength": 1048576
           }
         },
         "required": [
@@ -489,6 +524,10 @@
       },
       "default": {}
     },
+    "page": {
+      "type": "string",
+      "pattern": "^[a-z][a-zA-Z0-9_.-]{0,63}$"
+    },
     "mods": {
       "type": "object",
       "properties": {