@cloudcrane/app-spec 0.1.1 → 0.2.0

package/README.md

@@ -18,6 +18,11 @@ 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`), the inputs it's given and the events it sends.
+  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/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/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,6 +14,45 @@ export type TokenNode = {
     [name: string]: unknown;
 };
 export declare const Tokens: z.ZodType<TokenNode>;
+/** 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).
+ * 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<{
+    kind: z.ZodLiteral<"coded">;
+    kit: z.ZodEnum<["game"]>;
+    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>;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    kind: "coded";
+    kit: "game";
+    inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+    events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+}, {
+    code: string;
+    kind: "coded";
+    kit: "game";
+    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";
+    inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+    events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+}, {
+    code: string;
+    kind: "coded";
+    kit: "game";
+    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<{
     v: z.ZodLiteral<1>;
     manifest: z.ZodObject<{
@@ -255,6 +294,50 @@ 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.ZodObject<{
+        kind: z.ZodLiteral<"coded">;
+        kit: z.ZodEnum<["game"]>;
+        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>;
+    }, "strict", z.ZodTypeAny, {
+        code: string;
+        kind: "coded";
+        kit: "game";
+        inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+        events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    }, {
+        code: string;
+        kind: "coded";
+        kit: "game";
+        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";
+        inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
+        events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    }, {
+        code: string;
+        kind: "coded";
+        kit: "game";
+        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";
+        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";
+        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 +350,13 @@ export declare const SpecSchema: z.ZodObject<{
         locked: string[];
     }>>;
 }, "strict", z.ZodTypeAny, {
+    components: Record<string, {
+        code: string;
+        kind: "coded";
+        kit: "game";
+        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>[];
@@ -400,6 +490,13 @@ export declare const SpecSchema: z.ZodObject<{
             id: string;
         }[];
     }[];
+    components?: Record<string, {
+        code: string;
+        kind: "coded";
+        kit: "game";
+        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;

package/dist/src/schema.js

@@ -3,7 +3,9 @@ import { z } from "zod";
 // 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 +44,29 @@ 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).
+ * 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"]),
+    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"),
+})
+    .strict()
+    .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),
@@ -128,6 +153,11 @@ 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) })

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.2.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",

package/schema/app-spec.v1.json

@@ -416,6 +416,79 @@
       "maxItems": 30,
       "default": []
     },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "const": "coded"
+          },
+          "kit": {
+            "type": "string",
+            "enum": [
+              "game"
+            ]
+          },
+          "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": 65536
+          }
+        },
+        "required": [
+          "kind",
+          "kit",
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-zA-Z0-9_.-]{0,63}$"
+      },
+      "default": {}
+    },
     "mods": {
       "type": "object",
       "properties": {