@cloudcrane/app-runtime 0.2.0 → 0.3.0

package/README.md

@@ -14,8 +14,15 @@ const { html, sha256, runtime } = compile(spec);
 - `compile(spec)` returns the page, its sha256 and the runtime it was built
   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

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

@@ -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,7 +33,10 @@ 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);
@@ -46,11 +59,14 @@ export function compile(input) {
         `<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 } } : {}),
     };
 }

package/dist/host.d.ts

@@ -1,3 +1,3 @@
 export { validateSpec, leakProblems, deriveBlueprint, CLOUDCRANE_CATALOG_ID } from "@cloudcrane/app-spec";
-export { compile, CompileError } from "./compiler/compile.js";
+export { compile, CompileError, runtimeFile } from "./compiler/compile.js";
 export { RUNTIME_JS, RUNTIME_SHA256, RUNTIME_VERSION } from "./compiler/runtime.generated.js";

package/dist/host.js

@@ -3,5 +3,5 @@
 // blueprint. The runtime's code is exported so a host can check a built page
 // without it: the runtime is reviewed once per version and locked by its hash.
 export { validateSpec, leakProblems, deriveBlueprint, CLOUDCRANE_CATALOG_ID } from "@cloudcrane/app-spec";
-export { compile, CompileError } from "./compiler/compile.js";
+export { compile, CompileError, runtimeFile } from "./compiler/compile.js";
 export { RUNTIME_JS, RUNTIME_SHA256, RUNTIME_VERSION } from "./compiler/runtime.generated.js";

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { compile, CompileError, type Compiled } from "./compiler/compile.js";
+export { compile, CompileError, runtimeFile, type Compiled, type CompileOptions, type LinkedRuntime } from "./compiler/compile.js";
 export { RUNTIME_VERSION, RUNTIME_SHA256 } from "./compiler/runtime.generated.js";
 export { tokenVariables, tokensCss } from "./runtime/theme.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 // Builds a CloudCrane app spec into one HTML page, the same bytes every time.
-export { compile, CompileError } from "./compiler/compile.js";
+export { compile, CompileError, runtimeFile } from "./compiler/compile.js";
 export { RUNTIME_VERSION, RUNTIME_SHA256 } from "./compiler/runtime.generated.js";
 export { tokenVariables, tokensCss } from "./runtime/theme.js";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@cloudcrane/app-runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "runtimeVersion": "0.2.0",
   "description": "Builds a CloudCrane app spec into one HTML page, the same bytes every time, and the runtime that draws it with A2UI's renderer.",
   "keywords": [
     "cloudcrane",