@cloudcrane/app-spec 0.1.1 → 0.4.0

package/README.md

@@ -18,6 +18,17 @@ if (!spec) for (const p of problems) console.log(`${p.at}: ${p.problem}`);
 - `Rules` (`@cloudcrane/app-spec/logic`): evaluates a spec's CEL rules, with
   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`, 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.
 
 `zod` 3.25 is a peer dependency. Includes A2UI v0.9.1's schemas, unchanged,
 under the Apache License 2.0 (`vendor/a2ui`). MIT licensed.

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/catalog.js

@@ -10,6 +10,8 @@ import { BASIC_CATALOG } from "./a2ui.js";
 // Components:
 //   DateStrip: the last N days as chips, today on the right, one selectable,
 //   each with a status dot.
+//   Coded: places one of the spec's coded components, sandboxed in a frame; its
+//   state shows at /ui/coded/<id>/state.
 export const CLOUDCRANE_CATALOG_ID = "https://cloudcrane.ai/catalogs/app/v1.json";
 const COMMON = "https://a2ui.org/specification/v0_9/common_types.json#/$defs";
 const path = { $ref: `${COMMON}/DynamicString`, description: "A JSON Pointer into the data model, like /saved/days/2026-10-27." };
@@ -60,6 +62,46 @@ const COMPONENTS = {
         ],
         unevaluatedProperties: false,
     },
+    Coded: {
+        type: "object",
+        allOf: [
+            { $ref: `${COMMON}/ComponentCommon` },
+            { $ref: "#/$defs/CatalogComponentCommon" },
+            {
+                type: "object",
+                properties: {
+                    component: { const: "Coded" },
+                    use: { type: "string", pattern: "^[a-z][a-zA-Z0-9_.-]{0,63}$", description: "The coded component to place, by its name in the spec's components." },
+                    label: { $ref: `${COMMON}/DynamicString`, description: "What it is, for people who can't see it." },
+                    aspect: { type: "number", minimum: 0.25, maximum: 4, description: "Width over height; 1 (square) if left out." },
+                    inputs: {
+                        type: "array",
+                        maxItems: 10,
+                        description: "What it's given, each a declared input bound to the data model.",
+                        items: {
+                            type: "object",
+                            properties: { name: { type: "string" }, value: { $ref: `${COMMON}/DynamicValue` } },
+                            required: ["name", "value"],
+                            additionalProperties: false,
+                        },
+                    },
+                    on: {
+                        type: "array",
+                        maxItems: 10,
+                        description: "What happens when it sends a declared event; the event's fields are at /ui/coded/<this id>/<event> while the action runs.",
+                        items: {
+                            type: "object",
+                            properties: { name: { type: "string" }, action: { $ref: `${COMMON}/Action` } },
+                            required: ["name", "action"],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                required: ["component", "use", "label"],
+            },
+        ],
+        unevaluatedProperties: false,
+    },
 };
 /** The CloudCrane catalog document, built from A2UI's basic catalog. */
 export function cloudcraneCatalog() {
@@ -73,7 +115,7 @@ export function cloudcraneCatalog() {
         $id: CLOUDCRANE_CATALOG_ID,
         catalogId: CLOUDCRANE_CATALOG_ID,
         title: "CloudCrane app catalog",
-        description: "A2UI's basic catalog, plus local actions (set, push, removeAt, batch) and DateStrip, for apps that run on a phone.",
+        description: "A2UI's basic catalog, plus local actions (set, push, removeAt, batch), DateStrip and Coded, for apps that run on a phone.",
     };
 }
 export const CLOUDCRANE_CATALOG = cloudcraneCatalog();

package/dist/src/index.d.ts

@@ -7,3 +7,4 @@ 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";

package/dist/src/index.js

@@ -9,3 +9,4 @@ 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";

package/dist/src/leak.js

@@ -94,6 +94,8 @@ const RULES = [
 const EXEMPT = new Set(["/manifest/source/fingerprint"]);
 /** Where CEL lives: rules may look like code there, but nothing else may. */
 const CEL_AT = [/^\/logic\/functions\/[^/]+\/cel$/, /^\/logic\/computed\/.+$/, /^\/data\/migrations\/\d+\/cel$/];
+/** A coded component's code: code by design (it runs sandboxed), so only the code rules skip it. */
+const CODE_AT = /^\/components\/[^/]+\/code$/;
 /** A test step's state path: a dotted path into what the app exposes (CloudCrane's form), which reads like a member access by design. */
 const STATE_PATH_AT = /^\/tests\/\d+\/(steps|setup|check)\/\d+\/path$/;
 const STATE_PATH = /^[A-Za-z0-9_$]+(\.[A-Za-z0-9_$]+)*$/;
@@ -125,7 +127,7 @@ export function leakProblems(spec) {
             continue;
         // A2UI's bindings inside text (${/path}, ${fn(…)}) are the standard's syntax.
         const s = at.startsWith("/surface/") || at.startsWith("/data/views/") ? raw.replace(/\$\{[^}]*\}/g, " ") : raw;
-        const codeShaped = CEL_AT.some((r) => r.test(at)) || (STATE_PATH_AT.test(at) && STATE_PATH.test(raw));
+        const codeShaped = CEL_AT.some((r) => r.test(at)) || CODE_AT.test(at) || (STATE_PATH_AT.test(at) && STATE_PATH.test(raw));
         // Web addresses are checked as addresses (hosts, secrets), never as code.
         const withoutUrls = s.replace(/https?:\/\/[^\s"'<>]+/g, " ");
         for (const rule of RULES) {

package/dist/src/schema.d.ts

@@ -14,7 +14,61 @@ export type TokenNode = {
     [name: string]: unknown;
 };
 export declare const Tokens: z.ZodType<TokenNode>;
-export declare const SpecSchema: z.ZodObject<{
+/** The kinds of value a coded component is given or sends: JSON's, by name. */
+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;
+ * `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.ZodEffects<z.ZodObject<{
+    kind: z.ZodLiteral<"coded">;
+    /** 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.ZodString;
+}, "strict", z.ZodTypeAny, {
+    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;
+}>, {
+    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;
+}>, {
+    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.ZodEffects<z.ZodObject<{
     v: z.ZodLiteral<1>;
     manifest: z.ZodObject<{
         runtime: z.ZodString;
@@ -212,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;
@@ -255,6 +320,63 @@ export declare const SpecSchema: z.ZodObject<{
     }>, "many">>;
     /** 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.ZodEffects<z.ZodObject<{
+        kind: z.ZodLiteral<"coded">;
+        /** 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.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        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;
+    }>, {
+        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;
+    }>, {
+        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" | "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" | "page";
+        inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
+        events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
+    }>>>;
     /** What a remix may change and what stays as the partner made it. */
     mods: z.ZodDefault<z.ZodObject<{
         open: z.ZodArray<z.ZodString, "many">;
@@ -267,6 +389,183 @@ export declare const SpecSchema: z.ZodObject<{
         locked: string[];
     }>>;
 }, "strict", z.ZodTypeAny, {
+    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">>;
+    }>;
+    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[];
+    };
+}, {
+    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;
+    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">>;
+    }>;
     surface: {
         catalog: string;
         messages: Record<string, unknown>[];
@@ -322,6 +621,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;
@@ -400,10 +703,21 @@ export declare const SpecSchema: z.ZodObject<{
             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;
     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,9 +1,12 @@
 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
 // expressions, saved data is described by a JSON Schema. Strict throughout, so a
-// field the spec doesn't define (where code could hide) is refused.
+// field the spec doesn't define (where code could hide) is refused. The one
+// place code belongs is a coded component's, run sandboxed, said so where the
+// app is installed.
 /** A neutral id: lower-case words, dots, dashes, underscores. Partner symbol names live only in provenance. */
 export const Id = z.string().regex(/^[a-z][a-zA-Z0-9_.-]{0,63}$/, "an id: a letter, then letters, digits, . _ or -, at most 64");
 /** A CEL identifier (constants and parameters): letters, digits and underscores. */
@@ -42,6 +45,41 @@ export const Tokens = z.lazy(() => z
 }));
 /** A CEL expression (cel.dev); parsed and checked by the logic validator. */
 const Cel = z.string().min(1).max(4000);
+/** The kinds of value a coded component is given or sends: JSON's, by name. */
+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;
+ * `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"),
+    /** 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(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({
     v: z.literal(1),
@@ -116,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({
@@ -128,10 +171,26 @@ export const SpecSchema = z
     promises: z.array(z.object({ id: z.string().regex(/^P-\d+$/), text: Text(400), kind: z.literal("data").optional() }).strict()).default([]),
     /** CloudCrane's test steps, as its blueprint tests take them; CloudCrane checks their shape. */
     tests: z.array(z.record(z.unknown())).max(30).default([]),
+    /** Coded components, by name: the spec's own code for what the catalog can't draw. */
+    components: z
+        .record(Id, CodedComponent)
+        .refine((c) => Object.keys(c).length <= 5, "at most 5 components")
+        .default({}),
     /** 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

@@ -46,9 +46,38 @@ 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(...logicProblems(spec), ...leakProblems(spec));
+    problems.push(...codedProblems(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" });
     return { spec: problems.length ? null : spec, problems };
 }
+/** Each Coded placement names a component the spec defines, and only its declared inputs and events; each component is placed. */
+function codedProblems(spec) {
+    const problems = [];
+    const placed = new Set();
+    for (const m of spec.surface.messages) {
+        const comps = m.updateComponents?.components ?? [];
+        for (const c of comps) {
+            if (c.component !== "Coded" || typeof c.use !== "string")
+                continue;
+            const at = `surface ${c.id}`;
+            const def = spec.components[c.use];
+            if (!def) {
+                problems.push({ at, problem: `no coded component "${c.use}" in components` });
+                continue;
+            }
+            placed.add(c.use);
+            for (const i of c.inputs ?? [])
+                if (!(i.name in def.inputs))
+                    problems.push({ at, problem: `${c.use} declares no input "${i.name}"` });
+            for (const e of c.on ?? [])
+                if (!(e.name in def.events))
+                    problems.push({ at, problem: `${c.use} declares no event "${e.name}"` });
+        }
+    }
+    for (const name of Object.keys(spec.components))
+        if (!placed.has(name))
+            problems.push({ at: `components.${name}`, problem: "no screen places it" });
+    return problems;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcrane/app-spec",
-  "version": "0.1.1",
+  "version": "0.4.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": {
@@ -416,6 +450,80 @@
       "maxItems": 30,
       "default": []
     },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "const": "coded"
+          },
+          "kit": {
+            "type": "string",
+            "enum": [
+              "game",
+              "page"
+            ]
+          },
+          "inputs": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string",
+              "enum": [
+                "number",
+                "string",
+                "boolean",
+                "list",
+                "map"
+              ]
+            },
+            "propertyNames": {
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+            },
+            "default": {}
+          },
+          "events": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string",
+                "enum": [
+                  "number",
+                  "string",
+                  "boolean",
+                  "list",
+                  "map"
+                ]
+              },
+              "propertyNames": {
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+              }
+            },
+            "propertyNames": {
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+            },
+            "default": {}
+          },
+          "code": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1048576
+          }
+        },
+        "required": [
+          "kind",
+          "kit",
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-zA-Z0-9_.-]{0,63}$"
+      },
+      "default": {}
+    },
     "mods": {
       "type": "object",
       "properties": {