@botiverse/porthole 0.1.5 → 0.1.7

package/src/config/schema.ts

@@ -86,9 +86,11 @@ export interface ThemeConfig {
    * Whether a whole document (an artifact page) takes the person's light or dark scheme:
    * `declared` (default): only a page that declares it supports both
    * (`<meta name="color-scheme" content="light dark">`); any other page shows as its author
-   * styled it, in light. `always`: every page. The variables are there either way.
+   * styled it, in light. `always`: every page. `never` (pages only, P065): the host has no
+   * theme for it: it always gets the light values, its frame says light, and no theme change
+   * reaches it. The variables are there in every case.
    */
-  readonly documents?: "declared" | "always";
+  readonly documents?: "declared" | "always" | "never";
 }
 
 export interface Limits {
@@ -143,6 +145,13 @@ export interface LayoutConfig {
   readonly narrowWidthPx: number;
   /** The widest the frame is (a desktop column). */
   readonly wideWidthPx: number;
+  /**
+   * How the frame sits in the host (P065). `flow` (default): a card in a column, as tall as its
+   * content (up to `maxHeightPx`). `fill`: it fills the viewer (the page itself): as tall as its
+   * container, the content scrolling itself, `position: fixed` and `sticky` working. Every mount
+   * then fills (`MountOptions.fill`), and the manual says so.
+   */
+  readonly kind?: "flow" | "fill";
 }
 
 export interface GuideConfig {
@@ -193,9 +202,23 @@ export interface PortholeConfig {
    * "conversation" }`), so the manual says storage is shared across it and keys need a prefix.
    */
   readonly storage?: StorageConfig;
+  /**
+   * Where the content's own errors go, for the manual (P065): `agent`, back to the agent that
+   * wrote it; `host`, to the app only (the agent never sees them); `none`, nowhere (the config
+   * declares no `reportError`). Absent: the manual says they are reported to the app.
+   */
+  readonly errors?: "agent" | "host" | "none";
 }
 
 export interface StorageConfig {
-  /** What the displays sharing one origin have in common, as a noun ("conversation"). */
+  /**
+   * What the displays sharing one origin at once have in common, as a noun ("conversation"):
+   * the manual tells authors to prefix their keys.
+   */
   readonly shared?: string;
+  /**
+   * What one display's storage is kept for, when only one display uses its origin at a time, in
+   * words ("this artifact, across its versions", P065): the manual says so, with no prefix advice.
+   */
+  readonly scope?: string;
 }

package/src/config/validate.ts

@@ -292,6 +292,7 @@ export function validateConfig(input: unknown): PortholeConfig {
       "sandbox",
       "permissions",
       "storage",
+      "errors",
     ],
     "config",
   );
@@ -360,9 +361,16 @@ export function validateConfig(input: unknown): PortholeConfig {
   if (
     theme.documents !== undefined &&
     theme.documents !== "declared" &&
-    theme.documents !== "always"
+    theme.documents !== "always" &&
+    theme.documents !== "never"
   ) {
-    fail("config.theme.documents", 'must be "declared" or "always"');
+    fail("config.theme.documents", 'must be "declared", "always" or "never"');
+  }
+  if (theme.documents === "never" && config.mode !== "artifact") {
+    fail(
+      "config.theme.documents",
+      '"never" is for whole pages: a fragment takes the theme it is drawn in',
+    );
   }
   const variables = object(theme.variables, "config.theme.variables");
   for (const [name, value] of Object.entries(variables)) {
@@ -414,7 +422,10 @@ export function validateConfig(input: unknown): PortholeConfig {
   }
 
   const layout = object(config.layout, "config.layout");
-  only(layout, ["minWidthPx", "narrowWidthPx", "wideWidthPx"], "config.layout");
+  only(layout, ["minWidthPx", "narrowWidthPx", "wideWidthPx", "kind"], "config.layout");
+  if (layout.kind !== undefined && layout.kind !== "flow" && layout.kind !== "fill") {
+    fail("config.layout.kind", 'must be "flow" or "fill"');
+  }
   for (const name of ["minWidthPx", "narrowWidthPx", "wideWidthPx"]) {
     positive(layout[name], `config.layout.${name}`, 10_000);
   }
@@ -494,7 +505,22 @@ export function validateConfig(input: unknown): PortholeConfig {
 
   if (config.storage !== undefined) {
     const storage = object(config.storage, "config.storage");
-    only(storage, ["shared"], "config.storage");
+    only(storage, ["shared", "scope"], "config.storage");
+    if (storage.shared !== undefined && storage.scope !== undefined) {
+      fail(
+        "config.storage",
+        "shared (several displays at once) or scope (one at a time), not both",
+      );
+    }
+    if (
+      storage.scope !== undefined &&
+      (typeof storage.scope !== "string" || !/^[a-z][a-z ,'-]{0,59}$/u.test(storage.scope))
+    ) {
+      fail(
+        "config.storage.scope",
+        'must be short lowercase words ("this artifact, across its versions")',
+      );
+    }
     if (config.isolation !== "domain") {
       fail("config.storage", "only domain isolation keeps storage across displays");
     }
@@ -506,6 +532,20 @@ export function validateConfig(input: unknown): PortholeConfig {
     }
   }
 
+  if (config.errors !== undefined) {
+    if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
+      fail("config.errors", 'must be "agent", "host" or "none"');
+    }
+    if ((config.errors === "none") !== (capabilities.reportError === undefined)) {
+      fail(
+        "config.errors",
+        config.errors === "none"
+          ? '"none" means no reportError: drop the capability'
+          : `${JSON.stringify(config.errors)} needs the reportError capability, which carries them`,
+      );
+    }
+  }
+
   if (config.permissions !== undefined) {
     if (config.mode !== "url") {
       fail("config.permissions", "only url mode may be delegated features");

package/src/conformance/index.ts

@@ -40,6 +40,8 @@ export interface LaunchSpec {
   readonly scheme?: ColorScheme;
   /** The frame's width, px. */
   readonly widthPx?: number;
+  /** The height of the box the frame sits in, px: for a layout that fills it (`layout.kind`). */
+  readonly heightPx?: number;
   /** The host's live values for theme variables, per scheme (as `HostOptions.theme` answers). */
   readonly hostTheme?: {
     readonly light?: Readonly<Record<string, string>>;

package/src/conformance/kit.ts

@@ -34,7 +34,8 @@ export interface Probe {
   readonly id: string;
   /**
    * The DESIGN.md egress-table item it proves; 0 for the shell's own wiring and interop, 11 for
-   * behavior (streaming, sizing, theming), 12 for host-function gates, 13 for the clipboard.
+   * behavior (streaming, sizing, theming), 12 for host-function gates, 13 for the clipboard, 14
+   * for the manual's claims about the sandbox (`LIMIT_CHECKS`).
    */
   readonly item: number;
   readonly title: string;