@cloudcrane/app-runtime 0.2.0 → 0.5.0

package/README.md

@@ -12,10 +12,17 @@ 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`
+  with (`@cloudcrane/app-runtime@0.4.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
@@ -32,6 +39,20 @@ const { html, sha256, runtime } = compile(spec);
   game.random(); // seeded by the page
   ```
 
+  The page kit runs an HTML page as it is, full screen. Its `localStorage`
+  works: what it holds is written into the frame when it opens, and each
+  change goes to the page, which keeps it under `<data.key>.coded.<id>` (at
+  most 4 MB), so it survives a reload and an update and the frame sees only
+  its own. Both kits reach the page through `window.__ccBus`.
+
+  A component's frame is allowed the device features the spec's `uses`
+  declares (its `allow`), and the page must allow them for frames too (in
+  Permissions-Policy, `geolocation=*` rather than `(self)`). Browsers give a
+  frame with no origin of its own no camera or microphone, so a page kit whose
+  spec declares either runs with the page's origin; it's then no more apart
+  from the page than an app written straight into it. A game kit always
+  stays apart.
+
 - `@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

@@ -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,17 +33,21 @@ 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.
+    // Coded components go in only when there are some, and the device features they may use only when it uses some.
     const inPage = {
         module: spec.module,
         ...(Object.keys(spec.components).length ? { components: spec.components } : {}),
+        ...(spec.uses.length ? { uses: spec.uses } : {}),
         data: spec.data,
         logic: spec.logic,
         surface: spec.surface,
@@ -46,11 +60,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 } } : {}),
     };
 }