@cloudcrane/app-spec 0.4.0 → 0.7.0

package/dist/src/blueprint.d.ts

@@ -1,16 +1,25 @@
 import type { Spec } from "./schema.js";
+import { type KeptType } from "./memory.js";
 export type BlueprintV1 = {
     v: 1;
     purpose: string;
     screens: {
         id: string;
         says: string;
+        states?: {
+            empty?: string;
+            loading?: string;
+            offline?: string;
+            error?: string;
+        };
     }[];
     data: {
         version: number;
         keeps: {
             key: string;
             what: string;
+            shape?: Record<string, KeptType>;
+            personal?: boolean;
         }[];
     };
     journeys: Spec["journeys"];
@@ -20,9 +29,14 @@ export type BlueprintV1 = {
     icon?: string;
     category?: string;
     tags?: string[];
+    screen?: {
+        orientation?: "portrait" | "landscape" | "any";
+        fullscreen?: boolean;
+    };
     design: {
         palette: string[];
         notes: string;
+        tokens?: Record<string, string>;
     };
 };
 export declare function deriveBlueprint(spec: Spec): BlueprintV1;

package/dist/src/blueprint.js

@@ -1,3 +1,41 @@
+import { keptShape } from "./memory.js";
+import { rgbOf } from "./design.js";
+/** A blueprint's tokens are at most this many, by role (CloudCrane's blueprint takes 40). */
+const MAX_TOKENS = 40;
+/**
+ * The design tokens by role, as CloudCrane's blueprint holds them: colours as #hex (light as color.<role>, dark as
+ * color.dark.<role>), the corner radius and the font. Names as the spec has them, lower-case.
+ */
+function rolesOf(tokens) {
+    const out = {};
+    const hex = (v) => {
+        const rgb = rgbOf(v);
+        return rgb ? `#${rgb.map((c) => c.toString(16).padStart(2, "0")).join("")}` : null;
+    };
+    const tree = (tokens ?? {});
+    const colours = (group, prefix) => {
+        if (!group || typeof group !== "object")
+            return;
+        for (const [role, node] of Object.entries(group)) {
+            if (role.startsWith("$") || !node || typeof node !== "object" || !("$value" in node))
+                continue;
+            const h = hex(node.$value);
+            if (h && /^[a-z][a-z0-9-]*$/.test(role))
+                out[`${prefix}.${role}`] = h;
+        }
+    };
+    colours(tree["color"], "color");
+    colours(tree["dark"]?.["color"], "color.dark");
+    const radius = tree["border-radius"]?.["$value"];
+    if (radius && typeof radius.value === "number" && typeof radius.unit === "string")
+        out["border-radius"] = `${radius.value}${radius.unit}`;
+    const font = tree["font-family"]?.["$value"];
+    if (typeof font === "string")
+        out["font-family"] = font.slice(0, 100);
+    else if (Array.isArray(font))
+        out["font-family"] = font.map(String).join(", ").slice(0, 100);
+    return Object.fromEntries(Object.entries(out).slice(0, MAX_TOKENS));
+}
 const literal = (v) => (typeof v === "string" ? v.replace(/\$\{[^}]*\}/g, "…").trim() : null);
 const list = (xs, max = 6) => {
     const u = [...new Set(xs.filter(Boolean))];
@@ -43,13 +81,23 @@ function palette(tokens) {
 }
 export function deriveBlueprint(spec) {
     const saved = spec.data.initial && typeof spec.data.initial === "object" ? Object.keys(spec.data.initial) : [];
+    const shape = keptShape(spec.data.schema);
+    const tokens = rolesOf(spec.tokens);
     return {
         v: 1,
         purpose: spec.module.purpose,
-        screens: [{ id: spec.module.id, says: screenWords(spec) }],
+        // The screens as the spec describes them, with their states; else one, in the surface's own words.
+        screens: spec.screens ?? [{ id: spec.module.id, says: screenWords(spec) }],
         data: {
             version: spec.data.version,
-            keeps: [{ key: spec.data.key, what: saved.length ? `On this phone: ${list(saved)}` : "What you enter, on this phone" }],
+            keeps: [
+                {
+                    key: spec.data.key,
+                    what: saved.length ? `On this phone: ${list(saved)}` : "What you enter, on this phone",
+                    ...(Object.keys(shape).length ? { shape } : {}),
+                    ...(spec.data.personal?.length ? { personal: true } : {}),
+                },
+            ],
         },
         journeys: spec.journeys,
         promises: spec.promises,
@@ -58,6 +106,11 @@ export function deriveBlueprint(spec) {
         ...(spec.module.icon ? { icon: spec.module.icon } : {}),
         ...(spec.module.category ? { category: spec.module.category } : {}),
         ...(spec.module.tags?.length ? { tags: spec.module.tags } : {}),
-        design: { palette: palette(spec.tokens), notes: `Built from a CloudCrane spec, runtime ${spec.manifest.runtime}.` },
+        ...(spec.screen ? { screen: spec.screen } : {}),
+        design: {
+            palette: palette(spec.tokens),
+            notes: `Built from a CloudCrane spec, runtime ${spec.manifest.runtime}.`,
+            ...(Object.keys(tokens).length ? { tokens } : {}),
+        },
     };
 }

package/dist/src/design.d.ts

@@ -0,0 +1,16 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** The colour roles every screen uses: the page, and its main action. */
+export declare const CORE_ROLES: readonly ["background", "on-background", "primary", "on-primary"];
+/** Each "on" colour and what it sits on, read as text. */
+export declare const TEXT_PAIRS: [string, string][];
+/** WCAG 2.2 minimum contrast for normal-size text. */
+export declare const TEXT_CONTRAST = 4.5;
+/** A colour token's value as [r, g, b] 0-255, from #rgb, #rrggbb (or #rrggbbaa) or DTCG srgb components; null otherwise. */
+export declare function rgbOf(value: unknown): [number, number, number] | null;
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export declare function contrast(a: [number, number, number], b: [number, number, number]): number;
+/** What could look better: the colour roles, their contrast in light and dark, and token types the runtime can't draw. */
+export declare function designWarnings(spec: Spec): Problem[];
+/** What could work better: each screen's empty, offline and error states, said. */
+export declare function statesWarnings(spec: Spec): Problem[];

package/dist/src/design.js

@@ -0,0 +1,137 @@
+// Warnings, not refusals: what makes an app look good and work well, measured from the spec alone.
+//
+// How it looks: the colour roles a screen needs are there, and each text colour reads on what it sits on (WCAG 2.2
+// contrast, 4.5:1 for text), in light and, when the spec has them, dark colours (tokens.dark). Token types the
+// runtime can't draw are said rather than silently dropped.
+// What it does: a screen that lists saved things says what it shows when there are none, and an app that talks to a
+// site says what it shows offline and when the site fails.
+/** The colour roles every screen uses: the page, and its main action. */
+export const CORE_ROLES = ["background", "on-background", "primary", "on-primary"];
+/** Each "on" colour and what it sits on, read as text. */
+export const TEXT_PAIRS = [
+    ["on-background", "background"],
+    ["on-surface", "surface"],
+    ["on-primary", "primary"],
+    ["on-input", "input"],
+    ["error", "background"],
+];
+/** WCAG 2.2 minimum contrast for normal-size text. */
+export const TEXT_CONTRAST = 4.5;
+/** DTCG types the runtime has no CSS for. */
+const UNDRAWN = new Set(["shadow", "typography", "gradient", "border", "transition", "strokeStyle", "cubicBezier"]);
+/** A colour token's value as [r, g, b] 0-255, from #rgb, #rrggbb (or #rrggbbaa) or DTCG srgb components; null otherwise. */
+export function rgbOf(value) {
+    if (typeof value === "string") {
+        const hex = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value.trim());
+        if (!hex)
+            return null;
+        const h = hex[1].length === 3 ? [...hex[1]].map((c) => c + c).join("") : hex[1].slice(0, 6);
+        return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    }
+    if (value && typeof value === "object") {
+        const o = value;
+        if (typeof o["hex"] === "string")
+            return rgbOf(o["hex"]);
+        if (o["colorSpace"] === "srgb" && Array.isArray(o["components"]) && o["components"].length >= 3)
+            return o["components"].slice(0, 3).map((c) => Math.round(Math.max(0, Math.min(1, Number(c))) * 255));
+    }
+    return null;
+}
+/** WCAG relative luminance. */
+const luminance = ([r, g, b]) => {
+    const [lr, lg, lb] = [r, g, b].map((c) => {
+        const x = c / 255;
+        return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+};
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+/** The color.* tokens of a tree, by role, as written. */
+function colours(tree) {
+    const out = new Map();
+    const color = tree && typeof tree === "object" ? tree["color"] : undefined;
+    if (!color || typeof color !== "object")
+        return out;
+    for (const [k, v] of Object.entries(color))
+        if (!k.startsWith("$") && v && typeof v === "object" && "$value" in v)
+            out.set(k, v["$value"]);
+    return out;
+}
+/** Every token's $type that the runtime can't draw, with where it is. */
+function undrawn(tree, path = [], type) {
+    if (!tree || typeof tree !== "object")
+        return [];
+    const node = tree;
+    const t = typeof node["$type"] === "string" ? node["$type"] : type;
+    if ("$value" in node)
+        return t && UNDRAWN.has(t) ? [`${path.join(".")} (${t})`] : [];
+    return Object.entries(node).flatMap(([k, v]) => (k.startsWith("$") ? [] : undrawn(v, [...path, k], t)));
+}
+function themeWarnings(scheme, roles) {
+    const at = scheme === "light" ? "tokens.color" : "tokens.dark.color";
+    const out = [];
+    for (const [text, under] of TEXT_PAIRS) {
+        const a = roles.get(text);
+        const b = roles.get(under);
+        if (a === undefined || b === undefined)
+            continue;
+        const fg = rgbOf(a);
+        const bg = rgbOf(b);
+        if (!fg || !bg)
+            continue;
+        const ratio = contrast(fg, bg);
+        if (ratio < TEXT_CONTRAST)
+            out.push({ at: `${at}.${text}`, problem: `${text} on ${under} is ${ratio.toFixed(1)}:1; text needs at least ${TEXT_CONTRAST}:1 to read (WCAG)` });
+    }
+    return out;
+}
+/** What could look better: the colour roles, their contrast in light and dark, and token types the runtime can't draw. */
+export function designWarnings(spec) {
+    const out = [];
+    const light = colours(spec.tokens);
+    for (const role of CORE_ROLES)
+        if (!light.has(role))
+            out.push({ at: "tokens.color", problem: `no color.${role}: every screen uses it` });
+    out.push(...themeWarnings("light", light));
+    const darkTree = spec.tokens["dark"];
+    if (darkTree) {
+        // Dark colours replace the light ones they name; the rest stay as they are.
+        const dark = new Map([...light, ...colours(darkTree)]);
+        out.push(...themeWarnings("dark", dark));
+    }
+    else {
+        out.push({ at: "tokens", problem: "no dark colours (tokens.dark): the app stays light when the phone is set to dark" });
+    }
+    for (const where of undrawn(spec.tokens))
+        out.push({ at: `tokens.${where.split(" ")[0]}`, problem: `the runtime can't draw ${where} yet; it's left out of the page` });
+    return out;
+}
+/** Whether a surface shows a list of things (an A2UI List, or a view of saved data). */
+function listsThings(spec) {
+    if (spec.data.views.length)
+        return true;
+    return spec.surface.messages.some((m) => (m.updateComponents?.components ?? []).some((c) => c.component === "List"));
+}
+/** What could work better: each screen's empty, offline and error states, said. */
+export function statesWarnings(spec) {
+    const out = [];
+    const online = spec.network.length > 0;
+    if (!spec.screens) {
+        if (listsThings(spec) || online)
+            out.push({ at: "screens", problem: "no screens described: say what each shows when it's empty, offline or something fails" });
+        return out;
+    }
+    // Said once for the app, not per screen: not every screen lists things or goes online.
+    const has = (state) => spec.screens.some((s) => s.states?.[state]);
+    if (listsThings(spec) && !has("empty"))
+        out.push({ at: "screens", problem: "no empty state: say what a screen shows before anything is saved" });
+    if (online && !has("offline"))
+        out.push({ at: "screens", problem: "no offline state: say what it shows without a connection" });
+    if (online && !has("error"))
+        out.push({ at: "screens", problem: `no error state: say what it shows when ${spec.network[0].site} fails` });
+    return out;
+}

package/dist/src/fidelity.d.ts

@@ -0,0 +1,17 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** The functions with no example to reproduce, in one warning that names them. */
+export declare function rulesWarnings(spec: Pick<Spec, "logic">): Problem[];
+export type CatalogUse = {
+    /** Each catalog component the screens place, and how many times. */
+    catalog: Record<string, number>;
+    /** Each coded component the screens place, its kit, and the native widget it replaces when the spec says. */
+    coded: {
+        name: string;
+        kit: "game" | "page";
+        replaces: string | null;
+        placed: number;
+    }[];
+};
+/** What a spec's screens are drawn with. A page spec (the whole app as one page) counts as its one coded component. */
+export declare function catalogUse(spec: Pick<Spec, "surface" | "components">): CatalogUse;

package/dist/src/fidelity.js

@@ -0,0 +1,36 @@
+// How closely a spec can be shown to copy the app it came from.
+// - Rules with no examples: nothing checks they do what the original does (a warning; the compiler checks every example
+//   a rule has, so one recorded from the original app is proof).
+// - What the screens are drawn with: the catalog's components, and the coded components standing in for what the
+//   catalog can't draw, with the native widget each replaces. `blackbox coverage` adds these up across specs, so the
+//   catalog grows where ports need it most.
+/** The functions with no example to reproduce, in one warning that names them. */
+export function rulesWarnings(spec) {
+    const shown = new Set(spec.logic.vectors.map((v) => v.fn));
+    const bare = Object.keys(spec.logic.functions).filter((fn) => !shown.has(fn));
+    if (!bare.length)
+        return [];
+    const [one] = bare;
+    return [
+        {
+            at: bare.length === 1 ? `/logic/functions/${one}` : "/logic/functions",
+            problem: `${bare.length === 1 ? `${one} has` : `${bare.join(", ")} have`} no examples: nothing checks ${bare.length === 1 ? "it does" : "they do"} what the original does. Record some from the app (from: app) or its tests`,
+        },
+    ];
+}
+/** What a spec's screens are drawn with. A page spec (the whole app as one page) counts as its one coded component. */
+export function catalogUse(spec) {
+    const catalog = {};
+    const placed = {};
+    for (const m of spec.surface.messages)
+        for (const c of m.updateComponents?.components ?? []) {
+            if (typeof c.component !== "string")
+                continue;
+            if (c.component === "Coded" && typeof c.use === "string")
+                placed[c.use] = (placed[c.use] ?? 0) + 1;
+            else
+                catalog[c.component] = (catalog[c.component] ?? 0) + 1;
+        }
+    const coded = Object.entries(spec.components).map(([name, c]) => ({ name, kit: c.kit, replaces: c.replaces ?? null, placed: placed[name] ?? 0 }));
+    return { catalog, coded };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { A2UI_VERSION, BASIC_CATALOG, surfaceProblems, type Catalog, type Problem } from "./a2ui.js";
-export { Id, Pointer, PointerPattern, SpecSchema, Tokens, type Spec, type TokenNode } from "./schema.js";
+export { GAP_KINDS, Id, Pointer, PointerPattern, SpecSchema, Tokens, type Spec, type TokenNode } from "./schema.js";
 export { validateSpec } from "./validate.js";
 export { canonical } from "./canonical.js";
 export { specJsonSchema } from "./jsonschema.js";
@@ -8,3 +8,8 @@ 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";
+export { designWarnings, statesWarnings, contrast, rgbOf, CORE_ROLES, TEXT_PAIRS, TEXT_CONTRAST } from "./design.js";
+export { memoryProblems, keptShape, type KeptType } from "./memory.js";
+export { reachProblems, hostsNamedIn, buildsAddressAtRuntime } from "./reach.js";
+export { rulesWarnings, catalogUse, type CatalogUse } from "./fidelity.js";

package/dist/src/index.js

@@ -1,7 +1,7 @@
 // The CloudCrane app spec: its schema, the A2UI surface check, canonical JSON
 // and the JSON Schema export. See the repo README.
 export { A2UI_VERSION, BASIC_CATALOG, surfaceProblems } from "./a2ui.js";
-export { Id, Pointer, PointerPattern, SpecSchema, Tokens } from "./schema.js";
+export { GAP_KINDS, Id, Pointer, PointerPattern, SpecSchema, Tokens } from "./schema.js";
 export { validateSpec } from "./validate.js";
 export { canonical } from "./canonical.js";
 export { specJsonSchema } from "./jsonschema.js";
@@ -10,3 +10,8 @@ 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";
+export { designWarnings, statesWarnings, contrast, rgbOf, CORE_ROLES, TEXT_PAIRS, TEXT_CONTRAST } from "./design.js";
+export { memoryProblems, keptShape } from "./memory.js";
+export { reachProblems, hostsNamedIn, buildsAddressAtRuntime } from "./reach.js";
+export { rulesWarnings, catalogUse } from "./fidelity.js";

package/dist/src/leak.js

@@ -44,6 +44,15 @@ const RULES = [
         test: re(/\b(sk|pk|rk)[-_](live|test|proj)?[-_]?[A-Za-z0-9]{20,}\b|\bAIza[0-9A-Za-z_-]{35}\b|\bgh[pousr]_[A-Za-z0-9]{36}\b|\bxox[abpr]-[A-Za-z0-9-]{10,}/),
     },
     { kind: "secret", why: "a JSON Web Token", test: re(/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\./) },
+    // After secretlint's recommended preset: the formats it knows, beyond the ones above.
+    { kind: "secret", why: "an AWS secret access key", test: re(/aws_?secret_?access_?key["'\s:=]+[A-Za-z0-9/+=]{40}\b/i) },
+    { kind: "secret", why: "an npm token", test: re(/\bnpm_[A-Za-z0-9]{36}\b/) },
+    { kind: "secret", why: "a GitHub token", test: re(/\bgithub_pat_[A-Za-z0-9_]{60,}\b/) },
+    { kind: "secret", why: "an Anthropic or OpenAI key", test: re(/\bsk-(ant-(api|admin)\d{2}-|proj-)[A-Za-z0-9_-]{20,}/) },
+    { kind: "secret", why: "a Slack webhook", test: re(/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/) },
+    { kind: "secret", why: "a SendGrid key", test: re(/\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/) },
+    { kind: "secret", why: "a Shopify token", test: re(/\bshp(at|ss|ca|pa)_[a-fA-F0-9]{32}\b/) },
+    { kind: "secret", why: "a password in an address", test: re(/\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@[^\s/]+/i) },
     { kind: "secret", why: "a private key", test: re(/-----BEGIN [A-Z ]*PRIVATE KEY-----/) },
     { kind: "secret", why: "a long random-looking string", test: highEntropy },
     { kind: "personal", why: "an email address", test: re(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/) },

package/dist/src/logic.js

@@ -172,7 +172,20 @@ export function logicProblems(spec) {
     const cycle = cycleIn(spec.logic.functions);
     if (cycle)
         return [{ at: "/logic/functions", problem: `functions call each other in a cycle: ${cycle.join(" → ")}` }];
-    const rules = new Rules(spec.logic);
+    let rules;
+    try {
+        rules = new Rules(spec.logic);
+    }
+    catch (e) {
+        // A function named like one CEL already has (double, int, size...) can't be registered: say which, don't crash.
+        const taken = Object.keys(spec.logic.functions).find((n) => e.message.includes(`'${n}(`) || e.message.includes(` ${n}(`));
+        return [
+            {
+                at: taken ? `/logic/functions/${token(taken)}` : "/logic/functions",
+                problem: `${taken ? `"${taken}" is` : "a function name is"} already a CEL function: name it something else`,
+            },
+        ];
+    }
     const each = [
         ...Object.entries(spec.logic.functions).map(([n, f]) => [`/logic/functions/${token(n)}/cel`, f.cel]),
         ...Object.entries(spec.logic.computed).map(([p, cel]) => [`/logic/computed/${token(p)}`, cel]),

package/dist/src/memory.d.ts

@@ -0,0 +1,7 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** CloudCrane's kept-field types (its blueprint's keeps[].shape). */
+export type KeptType = "text" | "number" | "yes/no" | "date" | "list" | "object";
+export declare function memoryProblems(spec: Spec): Problem[];
+/** Each top-level saved field and its type, in CloudCrane's words. */
+export declare function keptShape(schema: Record<string, unknown>): Record<string, KeptType>;

package/dist/src/memory.js

@@ -0,0 +1,78 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+const ajv = () => new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+/** The schema as Ajv takes it: any $schema line names a draft this one reads the same for what specs use. */
+const plain = (schema) => {
+    const { $schema: _s, ...rest } = schema;
+    return rest;
+};
+export function memoryProblems(spec) {
+    const problems = [];
+    let validate;
+    try {
+        validate = ajv().compile(plain(spec.data.schema));
+    }
+    catch (err) {
+        return [{ at: "data.schema", problem: `isn't a JSON Schema: ${err instanceof Error ? err.message : String(err)}` }];
+    }
+    if (spec.data.initial !== undefined && !validate(spec.data.initial))
+        for (const e of validate.errors ?? [])
+            problems.push({ at: `data.initial${e.instancePath.replace(/\//g, ".")}`, problem: `doesn't fit data.schema: ${e.message ?? "invalid"}` });
+    // Every step from 1 to the current version, once each, so any older phone can come up to date.
+    const steps = new Map();
+    for (const m of spec.data.migrations)
+        steps.set(m.from, (steps.get(m.from) ?? 0) + 1);
+    for (let from = 1; from < spec.data.version; from++) {
+        const n = steps.get(from) ?? 0;
+        if (n === 0)
+            problems.push({ at: "data.migrations", problem: `no step from version ${from} to ${from + 1}: a phone still on ${from} would lose its data` });
+        if (n > 1)
+            problems.push({ at: "data.migrations", problem: `${n} steps from version ${from}; there must be one` });
+    }
+    // Personal fields name something the saved data has.
+    for (const pointer of spec.data.personal ?? [])
+        if (!pointsInto(spec.data.schema, pointer))
+            problems.push({ at: `data.personal ${pointer}`, problem: "the saved data has no such field (data.schema)" });
+    return problems;
+}
+/** Whether a JSON Pointer names a field the schema describes (properties all the way down; arrays and maps by their items). */
+function pointsInto(schema, pointer) {
+    if (pointer === "")
+        return true;
+    let node = schema;
+    for (const raw of pointer.split("/").slice(1)) {
+        const part = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (!node || typeof node !== "object")
+            return false;
+        const props = node["properties"];
+        if (props && part in props)
+            node = props[part];
+        else if (node["items"] && /^\d+$|^\*$/.test(part))
+            node = node["items"];
+        else if (node["additionalProperties"] && typeof node["additionalProperties"] === "object")
+            node = node["additionalProperties"];
+        else
+            return false;
+    }
+    return true;
+}
+/** Each top-level saved field and its type, in CloudCrane's words. */
+export function keptShape(schema) {
+    const props = (schema["properties"] ?? {});
+    const out = {};
+    for (const [name, p] of Object.entries(props).slice(0, 40)) {
+        const type = Array.isArray(p["type"]) ? p["type"].find((t) => t !== "null") : p["type"];
+        out[name.slice(0, 40)] =
+            type === "string"
+                ? p["format"] === "date" || p["format"] === "date-time"
+                    ? "date"
+                    : "text"
+                : type === "number" || type === "integer"
+                    ? "number"
+                    : type === "boolean"
+                        ? "yes/no"
+                        : type === "array"
+                            ? "list"
+                            : "object";
+    }
+    return out;
+}

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/reach.d.ts

@@ -0,0 +1,7 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** Every host an https:// or wss:// address in the code names, lower-case, once each. */
+export declare function hostsNamedIn(code: string): string[];
+/** Whether a request's address is put together while the app runs, so no one can read which site it reaches. */
+export declare function buildsAddressAtRuntime(code: string): boolean;
+export declare function reachProblems(spec: Spec): Problem[];