@cloudcrane/app-spec 0.5.0 → 0.7.0

package/dist/src/schema.d.ts

@@ -28,6 +28,8 @@ 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"]>;
+    /** Optional: the native widget or screen it stands in for, like "CupertinoSlidingSegmentedControl", so `blackbox coverage` can say which the catalog lacks. */
+    replaces: z.ZodOptional<z.ZodString>;
     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;
@@ -37,10 +39,12 @@ export declare const CodedComponent: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     kit: "game" | "page";
     inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
     events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    replaces?: string | undefined;
 }, {
     code: string;
     kind: "coded";
     kit: "game" | "page";
+    replaces?: string | undefined;
     inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
     events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
 }>, {
@@ -49,10 +53,12 @@ export declare const CodedComponent: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     kit: "game" | "page";
     inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
     events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    replaces?: string | undefined;
 }, {
     code: string;
     kind: "coded";
     kit: "game" | "page";
+    replaces?: string | undefined;
     inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
     events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
 }>, {
@@ -61,13 +67,17 @@ export declare const CodedComponent: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     kit: "game" | "page";
     inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
     events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+    replaces?: string | undefined;
 }, {
     code: string;
     kind: "coded";
     kit: "game" | "page";
+    replaces?: string | undefined;
     inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
     events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
 }>;
+/** The kinds of thing a ported app may not do that its original did. */
+export declare const GAP_KINDS: readonly ["background", "widget", "notifications", "purchases", "accounts", "sync", "device", "other"];
 export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
     v: z.ZodLiteral<1>;
     manifest: z.ZodObject<{
@@ -167,6 +177,11 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             to: number;
             cel: string;
         }>, "many">;
+        /**
+         * What it keeps: the saved fields that are personal (health, money, people's names), as pointers into the saved
+         * data, like /days or /people. They stay on the phone; CloudCrane never puts them in a remix, screenshot or report.
+         */
+        personal: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         version: number;
         key: string;
@@ -182,6 +197,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             cel: string;
         }[];
         initial?: unknown;
+        personal?: string[] | undefined;
     }, {
         version: number;
         key: string;
@@ -197,6 +213,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             source: string;
         }[] | undefined;
+        personal?: string[] | undefined;
     }>;
     logic: z.ZodObject<{
         consts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean]>>>;
@@ -213,18 +230,22 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         /** Values the screens read, kept up to date: a data-model pointer and the CEL that computes it. */
         computed: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Examples each function must reproduce: recorded from the source's own tests, or given. */
+        /**
+         * Examples each function must reproduce: `recorded` from the module's own tests, `app` from calls recorded while
+         * the original app ran, `hint` written by hand.
+         */
         vectors: z.ZodDefault<z.ZodArray<z.ZodObject<{
             fn: z.ZodString;
             in: z.ZodArray<z.ZodUnknown, "many">;
             out: z.ZodUnknown;
-            from: z.ZodEnum<["recorded", "hint"]>;
+            from: z.ZodEnum<["recorded", "app", "hint"]>;
         }, "strict", z.ZodTypeAny, {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
         }, {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
@@ -237,7 +258,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         }>;
         computed: Record<string, string>;
         vectors: {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
@@ -250,21 +271,28 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         }> | undefined;
         computed?: Record<string, string> | undefined;
         vectors?: {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
         }[] | undefined;
     }>;
+    /**
+     * What it can reach: each site, why, and what it's sent, in the person's words ("the city you typed"). Shown to the
+     * person before the app opens; a site the code names but this doesn't list is refused.
+     */
     network: z.ZodDefault<z.ZodArray<z.ZodObject<{
         site: z.ZodString;
         why: z.ZodString;
+        sends: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         site: string;
         why: string;
+        sends: string;
     }, {
         site: string;
         why: string;
+        sends: 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<{
@@ -277,6 +305,59 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         why: string;
         what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
     }>, "many">>;
+    /**
+     * What it does: each screen in words, and what it shows when there's nothing yet, while it loads, offline, and when
+     * something fails. Optional; without it the blueprint describes the one surface from its words.
+     */
+    screens: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        says: z.ZodString;
+        states: z.ZodOptional<z.ZodObject<{
+            empty: z.ZodOptional<z.ZodString>;
+            loading: z.ZodOptional<z.ZodString>;
+            offline: z.ZodOptional<z.ZodString>;
+            error: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        }, {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        says: string;
+        states?: {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        } | undefined;
+    }, {
+        id: string;
+        says: string;
+        states?: {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        } | undefined;
+    }>, "many">>;
+    /** How it looks on the phone: the orientation it holds and whether it fills the screen (Android honours both). */
+    screen: z.ZodOptional<z.ZodObject<{
+        orientation: z.ZodOptional<z.ZodEnum<["portrait", "landscape", "any"]>>;
+        fullscreen: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        orientation?: "any" | "portrait" | "landscape" | undefined;
+        fullscreen?: boolean | undefined;
+    }, {
+        orientation?: "any" | "portrait" | "landscape" | undefined;
+        fullscreen?: boolean | undefined;
+    }>>;
     journeys: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
@@ -325,6 +406,8 @@ export declare const SpecSchema: 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"]>;
+        /** Optional: the native widget or screen it stands in for, like "CupertinoSlidingSegmentedControl", so `blackbox coverage` can say which the catalog lacks. */
+        replaces: z.ZodOptional<z.ZodString>;
         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;
@@ -334,10 +417,12 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+        replaces?: string | undefined;
     }, {
         code: string;
         kind: "coded";
         kit: "game" | "page";
+        replaces?: string | undefined;
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>, {
@@ -346,10 +431,12 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+        replaces?: string | undefined;
     }, {
         code: string;
         kind: "coded";
         kit: "game" | "page";
+        replaces?: string | undefined;
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>, {
@@ -358,10 +445,12 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+        replaces?: string | undefined;
     }, {
         code: string;
         kind: "coded";
         kit: "game" | "page";
+        replaces?: string | undefined;
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>>, Record<string, {
@@ -370,15 +459,34 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+        replaces?: string | undefined;
     }>, Record<string, {
         code: string;
         kind: "coded";
         kit: "game" | "page";
+        replaces?: string | undefined;
         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 the original app does that this one doesn't, said plainly so no one is promised it: a native feature with
+     * no web equivalent yet (background jobs, home-screen widgets, push notifications, in-app purchases...).
+     */
+    gaps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<["background", "widget", "notifications", "purchases", "accounts", "sync", "device", "other"]>;
+        what: z.ZodString;
+        why: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "notifications" | "other" | "background" | "widget" | "purchases" | "accounts" | "sync" | "device";
+        what: string;
+        why?: string | undefined;
+    }, {
+        kind: "notifications" | "other" | "background" | "widget" | "purchases" | "accounts" | "sync" | "device";
+        what: string;
+        why?: string | undefined;
+    }>, "many">>;
     /** What a remix may change and what stays as the partner made it. */
     mods: z.ZodDefault<z.ZodObject<{
         open: z.ZodArray<z.ZodString, "many">;
@@ -397,6 +505,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+        replaces?: string | undefined;
     }>;
     surface: {
         catalog: string;
@@ -434,6 +543,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             cel: string;
         }[];
         initial?: unknown;
+        personal?: string[] | undefined;
     };
     logic: {
         consts: Record<string, string | number | boolean>;
@@ -443,7 +553,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         }>;
         computed: Record<string, string>;
         vectors: {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
@@ -452,6 +562,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
     network: {
         site: string;
         why: string;
+        sends: string;
     }[];
     uses: {
         why: string;
@@ -476,6 +587,25 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         locked: string[];
     };
     page?: string | undefined;
+    screens?: {
+        id: string;
+        says: string;
+        states?: {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+    screen?: {
+        orientation?: "any" | "portrait" | "landscape" | undefined;
+        fullscreen?: boolean | undefined;
+    } | undefined;
+    gaps?: {
+        kind: "notifications" | "other" | "background" | "widget" | "purchases" | "accounts" | "sync" | "device";
+        what: string;
+        why?: string | undefined;
+    }[] | undefined;
 }, {
     surface: {
         catalog: string;
@@ -513,6 +643,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             source: string;
         }[] | undefined;
+        personal?: string[] | undefined;
     };
     logic: {
         consts?: Record<string, string | number | boolean> | undefined;
@@ -522,7 +653,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         }> | undefined;
         computed?: Record<string, string> | undefined;
         vectors?: {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
@@ -540,6 +671,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         code: string;
         kind: "coded";
         kit: "game" | "page";
+        replaces?: string | undefined;
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }> | undefined;
@@ -547,17 +679,37 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
     network?: {
         site: string;
         why: string;
+        sends: string;
     }[] | undefined;
     uses?: {
         why: string;
         what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
     }[] | undefined;
+    screens?: {
+        id: string;
+        says: string;
+        states?: {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+    screen?: {
+        orientation?: "any" | "portrait" | "landscape" | undefined;
+        fullscreen?: boolean | undefined;
+    } | undefined;
     promises?: {
         text: string;
         id: string;
         kind?: "data" | undefined;
     }[] | undefined;
     tests?: Record<string, unknown>[] | undefined;
+    gaps?: {
+        kind: "notifications" | "other" | "background" | "widget" | "purchases" | "accounts" | "sync" | "device";
+        what: string;
+        why?: string | undefined;
+    }[] | undefined;
     mods?: {
         open: string[];
         locked: string[];
@@ -569,6 +721,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         kit: "game" | "page";
         inputs: Record<string, "string" | "number" | "boolean" | "map" | "list">;
         events: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">>;
+        replaces?: string | undefined;
     }>;
     surface: {
         catalog: string;
@@ -606,6 +759,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             cel: string;
         }[];
         initial?: unknown;
+        personal?: string[] | undefined;
     };
     logic: {
         consts: Record<string, string | number | boolean>;
@@ -615,7 +769,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         }>;
         computed: Record<string, string>;
         vectors: {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
@@ -624,6 +778,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
     network: {
         site: string;
         why: string;
+        sends: string;
     }[];
     uses: {
         why: string;
@@ -648,6 +803,25 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         locked: string[];
     };
     page?: string | undefined;
+    screens?: {
+        id: string;
+        says: string;
+        states?: {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+    screen?: {
+        orientation?: "any" | "portrait" | "landscape" | undefined;
+        fullscreen?: boolean | undefined;
+    } | undefined;
+    gaps?: {
+        kind: "notifications" | "other" | "background" | "widget" | "purchases" | "accounts" | "sync" | "device";
+        what: string;
+        why?: string | undefined;
+    }[] | undefined;
 }, {
     surface: {
         catalog: string;
@@ -685,6 +859,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             source: string;
         }[] | undefined;
+        personal?: string[] | undefined;
     };
     logic: {
         consts?: Record<string, string | number | boolean> | undefined;
@@ -694,7 +869,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         }> | undefined;
         computed?: Record<string, string> | undefined;
         vectors?: {
-            from: "recorded" | "hint";
+            from: "recorded" | "app" | "hint";
             fn: string;
             in: unknown[];
             out?: unknown;
@@ -712,6 +887,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         code: string;
         kind: "coded";
         kit: "game" | "page";
+        replaces?: string | undefined;
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }> | undefined;
@@ -719,17 +895,37 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
     network?: {
         site: string;
         why: string;
+        sends: string;
     }[] | undefined;
     uses?: {
         why: string;
         what: "camera" | "microphone" | "location" | "motion" | "screen-awake" | "gamepad" | "voice" | "contacts" | "nfc";
     }[] | undefined;
+    screens?: {
+        id: string;
+        says: string;
+        states?: {
+            error?: string | undefined;
+            empty?: string | undefined;
+            loading?: string | undefined;
+            offline?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+    screen?: {
+        orientation?: "any" | "portrait" | "landscape" | undefined;
+        fullscreen?: boolean | undefined;
+    } | undefined;
     promises?: {
         text: string;
         id: string;
         kind?: "data" | undefined;
     }[] | undefined;
     tests?: Record<string, unknown>[] | undefined;
+    gaps?: {
+        kind: "notifications" | "other" | "background" | "widget" | "purchases" | "accounts" | "sync" | "device";
+        what: string;
+        why?: string | undefined;
+    }[] | undefined;
     mods?: {
         open: string[];
         locked: string[];

package/dist/src/schema.js

@@ -61,6 +61,8 @@ export const CodedComponent = z
     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"]),
+    /** Optional: the native widget or screen it stands in for, like "CupertinoSlidingSegmentedControl", so `blackbox coverage` can say which the catalog lacks. */
+    replaces: Text(120).optional(),
     inputs: z.record(CelName, CodedType).default({}),
     events: z.record(CelName, z.record(CelName, CodedType)).default({}),
     code: z
@@ -80,6 +82,8 @@ export const CodedComponent = z
         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");
+/** The kinds of thing a ported app may not do that its original did. */
+export const GAP_KINDS = ["background", "widget", "notifications", "purchases", "accounts", "sync", "device", "other"];
 export const SpecSchema = z
     .object({
     v: z.literal(1),
@@ -138,6 +142,11 @@ export const SpecSchema = z
             .default([]),
         /** Each step turns version `from` into `to`, as a CEL expression over `saved`. */
         migrations: z.array(z.object({ from: z.number().int().min(1), to: z.number().int().min(2), cel: Cel }).strict()),
+        /**
+         * What it keeps: the saved fields that are personal (health, money, people's names), as pointers into the saved
+         * data, like /days or /people. They stay on the phone; CloudCrane never puts them in a remix, screenshot or report.
+         */
+        personal: z.array(Pointer).max(20).optional(),
     })
         .strict(),
     logic: z
@@ -147,11 +156,21 @@ export const SpecSchema = z
         /** Values the screens read, kept up to date: a data-model pointer and the CEL that computes it. */
         computed: z.record(Pointer, Cel).default({}),
         /** Examples each function must reproduce: recorded from the source's own tests, or given. */
-        vectors: z.array(z.object({ fn: CelName, in: z.array(z.unknown()).max(8), out: z.unknown(), from: z.enum(["recorded", "hint"]) }).strict()).default([]),
+        /**
+         * Examples each function must reproduce: `recorded` from the module's own tests, `app` from calls recorded while
+         * the original app ran, `hint` written by hand.
+         */
+        vectors: z
+            .array(z.object({ fn: CelName, in: z.array(z.unknown()).max(8), out: z.unknown(), from: z.enum(["recorded", "app", "hint"]) }).strict())
+            .default([]),
     })
         .strict(),
+    /**
+     * What it can reach: each site, why, and what it's sent, in the person's words ("the city you typed"). Shown to the
+     * person before the app opens; a site the code names but this doesn't list is refused.
+     */
     network: z
-        .array(z.object({ site: z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/), why: Text(300) }).strict())
+        .array(z.object({ site: z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/), why: Text(300), sends: Text(200) }).strict())
         .max(5)
         .default([]),
     /** The device features the app uses, by CloudCrane's names, each once with why; anything not listed is blocked. */
@@ -159,6 +178,29 @@ export const SpecSchema = z
         .array(z.object({ what: z.enum(USE_NAMES), why: Text(300) }).strict())
         .max(USE_NAMES.length)
         .default([]),
+    /**
+     * What it does: each screen in words, and what it shows when there's nothing yet, while it loads, offline, and when
+     * something fails. Optional; without it the blueprint describes the one surface from its words.
+     */
+    screens: z
+        .array(z
+        .object({
+        id: Id,
+        says: Text(300),
+        states: z
+            .object({ empty: Text(200).optional(), loading: Text(200).optional(), offline: Text(200).optional(), error: Text(200).optional() })
+            .strict()
+            .optional(),
+    })
+        .strict())
+        .min(1)
+        .max(20)
+        .optional(),
+    /** How it looks on the phone: the orientation it holds and whether it fills the screen (Android honours both). */
+    screen: z
+        .object({ orientation: z.enum(["portrait", "landscape", "any"]).optional(), fullscreen: z.boolean().optional() })
+        .strict()
+        .optional(),
     journeys: z
         .array(z
         .object({
@@ -178,6 +220,14 @@ export const SpecSchema = z
         .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 the original app does that this one doesn't, said plainly so no one is promised it: a native feature with
+     * no web equivalent yet (background jobs, home-screen widgets, push notifications, in-app purchases...).
+     */
+    gaps: z
+        .array(z.object({ kind: z.enum(GAP_KINDS), what: Text(120), why: Text(300).optional() }).strict())
+        .max(20)
+        .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) })

package/dist/src/validate.d.ts

@@ -3,4 +3,5 @@ import { type Spec } from "./schema.js";
 export declare function validateSpec(input: unknown, catalog?: Catalog): {
     spec: Spec | null;
     problems: Problem[];
+    warnings: Problem[];
 };

package/dist/src/validate.js

@@ -4,8 +4,14 @@ import { leakProblems } from "./leak.js";
 import { logicProblems } from "./logic.js";
 import { SpecSchema } from "./schema.js";
 import { pageProblems } from "./page.js";
+import { designWarnings, statesWarnings } from "./design.js";
+import { memoryProblems } from "./memory.js";
+import { reachProblems } from "./reach.js";
+import { rulesWarnings } from "./fidelity.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.
+// envelope's shape, then the A2UI surface, then references between parts, what it keeps (memory.ts) and what its code
+// reaches (reach.ts). Problems refuse it. Warnings (how it looks and what each screen shows when empty, offline or
+// failing: design.ts) don't: they say what would make it better.
 const pathOf = (path) => path
     .map((p) => (typeof p === "number" ? `[${p}]` : `.${p}`))
     .join("")
@@ -13,12 +19,12 @@ const pathOf = (path) => path
 export function validateSpec(input, catalog) {
     const parsed = SpecSchema.safeParse(input);
     if (!parsed.success)
-        return { spec: null, problems: parsed.error.issues.map((i) => ({ at: pathOf(i.path) || "spec", problem: i.message })) };
+        return { spec: null, problems: parsed.error.issues.map((i) => ({ at: pathOf(i.path) || "spec", problem: i.message })), warnings: [] };
     const spec = parsed.data;
     // The surface is checked against the catalog it names (CloudCrane's, or A2UI's basic one).
     const named = catalog ?? catalogFor(spec.surface.catalog);
     if (!named)
-        return { spec: null, problems: [{ at: "surface.catalog", problem: "not a catalog this runtime has" }] };
+        return { spec: null, problems: [{ at: "surface.catalog", problem: "not a catalog this runtime has" }], warnings: [] };
     const problems = [...surfaceProblems(spec.surface.messages, named)];
     const catalogId = spec.surface.messages[0].createSurface?.catalogId;
     if (catalogId && catalogId !== spec.surface.catalog)
@@ -47,11 +53,12 @@ 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), ...pageProblems(spec), ...logicProblems(spec), ...leakProblems(spec));
+    problems.push(...codedProblems(spec), ...pageProblems(spec), ...logicProblems(spec), ...leakProblems(spec), ...memoryProblems(spec), ...reachProblems(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 };
+    const warnings = [...designWarnings(spec), ...statesWarnings(spec), ...rulesWarnings(spec)];
+    return { spec: problems.length ? null : spec, problems, warnings };
 }
 /** Each Coded placement names a component the spec defines, and only its declared inputs and events; each component is placed. */
 function codedProblems(spec) {