@cloudcrane/app-runtime 0.1.0 → 0.3.0

package/README.md

@@ -12,10 +12,33 @@ const { html, sha256, runtime } = compile(spec);
 ```
 
 - `compile(spec)` returns the page, its sha256 and the runtime it was built
-  with (`@cloudcrane/app-runtime@0.1.0+<hash>`); it throws `CompileError`
+  with (`@cloudcrane/app-runtime@0.2.0+<hash>`); it throws `CompileError`
   listing every problem when the spec doesn't validate.
+- `compile(spec, { runtime: "shared" })` links the runtime instead of inlining
+  it: the page names `runtimeFile().path` (`/_cc/runtime/<version>-<hash>.js`)
+  with an integrity hash, so a host serves one copy to every spec app and a
+  browser runs nothing but those bytes. The page is then a few KB. Inline is
+  the default, for a page that stands alone.
 - Each runtime version is locked to one bundle hash (`runtime-lock.json`), so a
-  version always draws apps the same way.
+  version always draws apps the same way. The runtime's version
+  (`runtimeVersion` in package.json) moves only when the bundle does; the
+  package can release without it.
+- A coded component runs in a frame that's sandboxed (scripts only, so it has
+  no storage and nothing of the page's), in a closed shadow root, reached only
+  through a `MessagePort`. Under CloudCrane's lockdown the lockdown makes the
+  frame (`window.__ccFrame`); elsewhere the runtime makes the same kind. The
+  page drives it: a seed and the inputs, then its clock each frame, paused
+  while hidden. The game kit turns that clock into fixed steps, so a game moves
+  the same way for the same time and seed:
+
+  ```js
+  game.start({ rate: 6, setup() {}, step() {}, draw(g, width, height) {} });
+  game.on("swipe", (dir) => {}); // also "tap" and "input"
+  game.state = { score }; // shown at /ui/coded/<id>/state
+  game.emit("over", { score }); // the screen's action for "over" runs
+  game.random(); // seeded by the page
+  ```
+
 - `@cloudcrane/app-runtime/host`: what a host publishing spec apps needs in one
   import (validate, compile, derive the blueprint).
 

package/dist/compiler/compile.d.ts

@@ -8,9 +8,28 @@ export declare class CompileError extends Error {
         problem: string;
     }[]);
 }
+/** Where a page that links the runtime finds it, and the hash its bytes must have. */
+export type LinkedRuntime = {
+    path: string;
+    integrity: string;
+};
 export type Compiled = {
     html: string;
     sha256: string;
     runtime: string;
+    linked?: LinkedRuntime;
+};
+/**
+ * How a page carries the runtime: inline (the default: the page stands alone,
+ * as blackbox preview and anyone hosting it themselves need) or shared (it
+ * links one file every spec app on a host shares, which the host serves from
+ * runtimeFile(); the integrity hash means a browser runs nothing else).
+ */
+export type CompileOptions = {
+    runtime?: "inline" | "shared";
+};
+/** The runtime as the file a shared page links: its path (named by version and hash), its bytes and their integrity hash. */
+export declare function runtimeFile(): LinkedRuntime & {
+    js: string;
 };
-export declare function compile(input: unknown): Compiled;
+export declare function compile(input: unknown, options?: CompileOptions): Compiled;

package/dist/compiler/compile.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { canonical, validateSpec } from "@cloudcrane/app-spec";
-import { DATESTRIP_CSS } from "../runtime/styles.js";
+import { CODED_CSS, DATESTRIP_CSS } from "../runtime/styles.js";
 import { tokensCss } from "../runtime/theme.js";
 import { RUNTIME_JS, RUNTIME_SHA256, RUNTIME_VERSION } from "./runtime.generated.js";
 // The compiler: a spec in, one HTML page out, the same bytes every time for the
@@ -15,6 +15,16 @@ export class CompileError extends Error {
         this.problems = problems;
     }
 }
+let file;
+/** The runtime as the file a shared page links: its path (named by version and hash), its bytes and their integrity hash. */
+export function runtimeFile() {
+    file ??= {
+        path: `/_cc/runtime/${RUNTIME_VERSION}-${RUNTIME_SHA256.slice(0, 12)}.js`,
+        js: RUNTIME_JS,
+        integrity: `sha256-${createHash("sha256").update(RUNTIME_JS).digest("base64")}`,
+    };
+    return file;
+}
 /** The page's base: the tokens set A2UI's variables; this lays out the page around the surface. */
 const BASE_CSS = "*{box-sizing:border-box}html,body{margin:0}body{background:var(--a2ui-color-background,#fff);color:var(--a2ui-color-on-background,#111);font-family:var(--a2ui-font-family,system-ui,sans-serif);-webkit-text-size-adjust:100%}#app{max-width:30rem;margin:0 auto;padding:max(16px,env(safe-area-inset-top)) 16px max(24px,env(safe-area-inset-bottom))}@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}";
 const escapeHtml = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
@@ -23,15 +33,20 @@ const scriptSafe = (json) => json
     .replace(/</g, "\\u003c")
     .replace(new RegExp(String.fromCharCode(0x2028), "g"), "\\u2028")
     .replace(new RegExp(String.fromCharCode(0x2029), "g"), "\\u2029");
-export function compile(input) {
+export function compile(input, options = {}) {
+    const mode = options.runtime ?? "inline";
+    if (mode !== "inline" && mode !== "shared")
+        throw new TypeError("The runtime is inline or shared.");
     const { spec, problems } = validateSpec(input);
     if (!spec)
         throw new CompileError(problems);
     if (spec.manifest.runtime !== RUNTIME_VERSION)
         throw new CompileError([{ at: "manifest.runtime", problem: `this compiler builds runtime ${RUNTIME_VERSION}` }]);
     // Only what drawing the app needs goes in the page: not the journeys, promises or tests.
+    // Coded components go in only when there are some.
     const inPage = {
         module: spec.module,
+        ...(Object.keys(spec.components).length ? { components: spec.components } : {}),
         data: spec.data,
         logic: spec.logic,
         surface: spec.surface,
@@ -41,14 +56,17 @@ export function compile(input) {
         '<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">' +
         `<meta name="cc-runtime" content="${RUNTIME_VERSION}">` +
         `<title>${escapeHtml(spec.module.name)}</title>` +
-        `<style>${tokensCss(spec.tokens)}${BASE_CSS}${DATESTRIP_CSS}</style>` +
+        `<style>${tokensCss(spec.tokens)}${BASE_CSS}${DATESTRIP_CSS}${CODED_CSS}</style>` +
         '</head><body><main id="app"></main>' +
         `<script type="application/json" id="cc-spec">${scriptSafe(canonical(inPage))}</script>` +
-        `<script type="module">${RUNTIME_JS}</script>` +
+        (mode === "shared"
+            ? `<script type="module" src="${runtimeFile().path}" integrity="${runtimeFile().integrity}"></script>`
+            : `<script type="module">${RUNTIME_JS}</script>`) +
         "</body></html>\n";
     return {
         html,
         sha256: createHash("sha256").update(html).digest("hex"),
         runtime: `@cloudcrane/app-runtime@${RUNTIME_VERSION}+${RUNTIME_SHA256.slice(0, 12)}`,
+        ...(mode === "shared" ? { linked: { path: runtimeFile().path, integrity: runtimeFile().integrity } } : {}),
     };
 }