@cloudcrane/app-spec 0.4.0 → 0.5.0

package/dist/src/index.d.ts

@@ -8,3 +8,4 @@ export { leakProblems } from "./leak.js";
 export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalog } from "./catalog.js";
 export { deriveBlueprint, type BlueprintV1 } from "./blueprint.js";
 export { USES, USE_NAMES, NEEDS_ORIGIN, featuresOf, type Use } from "./uses.js";
+export { pageOf, pageProblems, wrapPage, type PageApp } from "./page.js";

package/dist/src/index.js

@@ -10,3 +10,4 @@ export { leakProblems } from "./leak.js";
 export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalog } from "./catalog.js";
 export { deriveBlueprint } from "./blueprint.js";
 export { USES, USE_NAMES, NEEDS_ORIGIN, featuresOf } from "./uses.js";
+export { pageOf, pageProblems, wrapPage } from "./page.js";

package/dist/src/page.d.ts

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

package/dist/src/page.js

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

package/dist/src/schema.d.ts

@@ -377,6 +377,8 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }>>>;
+    /** The page-kit component that is the whole app: the spec is then that page, compiled to its HTML as written (see page.ts). */
+    page: z.ZodOptional<z.ZodString>;
     /** What a remix may change and what stays as the partner made it. */
     mods: z.ZodDefault<z.ZodObject<{
         open: z.ZodArray<z.ZodString, "many">;
@@ -473,6 +475,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         open: string[];
         locked: string[];
     };
+    page?: string | undefined;
 }, {
     surface: {
         catalog: string;
@@ -540,6 +543,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }> | undefined;
+    page?: string | undefined;
     network?: {
         site: string;
         why: string;
@@ -643,6 +647,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         open: string[];
         locked: string[];
     };
+    page?: string | undefined;
 }, {
     surface: {
         catalog: string;
@@ -710,6 +715,7 @@ export declare const SpecSchema: z.ZodEffects<z.ZodObject<{
         inputs?: Record<string, "string" | "number" | "boolean" | "map" | "list"> | undefined;
         events?: Record<string, Record<string, "string" | "number" | "boolean" | "map" | "list">> | undefined;
     }> | undefined;
+    page?: string | undefined;
     network?: {
         site: string;
         why: string;

package/dist/src/schema.js

@@ -176,6 +176,8 @@ export const SpecSchema = z
         .record(Id, CodedComponent)
         .refine((c) => Object.keys(c).length <= 5, "at most 5 components")
         .default({}),
+    /** The page-kit component that is the whole app: the spec is then that page, compiled to its HTML as written (see page.ts). */
+    page: Id.optional(),
     /** What a remix may change and what stays as the partner made it. */
     mods: z
         .object({ open: z.array(PointerPattern), locked: z.array(PointerPattern) })

package/dist/src/validate.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcrane/app-spec",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The CloudCrane app spec: its schema, the expression language its rules are written in, and the checks that keep partner code out of it.",
   "keywords": [
     "cloudcrane",

package/schema/app-spec.v1.json

@@ -524,6 +524,10 @@
       },
       "default": {}
     },
+    "page": {
+      "type": "string",
+      "pattern": "^[a-z][a-zA-Z0-9_.-]{0,63}$"
+    },
     "mods": {
       "type": "object",
       "properties": {