@botiverse/porthole 0.1.6 → 0.1.8

package/dist/config/schema.d.ts

@@ -80,9 +80,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 {
     /** The tallest the frame grows before its content scrolls inside it. */
@@ -126,6 +128,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 {
     /** The host's tool that shows this content, as the manual names it (`show_widget`). */
@@ -173,8 +182,22 @@ 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/dist/config/validate.js

@@ -259,6 +259,7 @@ export function validateConfig(input) {
         "sandbox",
         "permissions",
         "storage",
+        "errors",
     ], "config");
     if (!MODES.includes(config.mode)) {
         fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -315,8 +316,12 @@ export function validateConfig(input) {
     only(theme, ["variables", "event", "documents"], "config.theme");
     if (theme.documents !== undefined &&
         theme.documents !== "declared" &&
-        theme.documents !== "always") {
-        fail("config.theme.documents", 'must be "declared" or "always"');
+        theme.documents !== "always" &&
+        theme.documents !== "never") {
+        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)) {
@@ -361,7 +366,10 @@ export function validateConfig(input) {
         fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
     }
     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);
     }
@@ -421,7 +429,14 @@ export function validateConfig(input) {
     }
     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");
         }
@@ -430,6 +445,16 @@ export function validateConfig(input) {
             fail("config.storage.shared", 'must be a short lowercase noun ("conversation")');
         }
     }
+    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/dist/conformance/index.d.ts

@@ -39,6 +39,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/dist/conformance/kit.d.ts

@@ -31,7 +31,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;

package/dist/conformance/limits.d.ts

@@ -0,0 +1,10 @@
+import type { LimitId } from "../guide/limits.ts";
+import { type Probe } from "./kit.ts";
+export declare const LIMIT_PROBES: readonly Probe[];
+/**
+ * The checks that prove each limit the manual can state: leak-suite probes, and served cases for
+ * what holds in domain mode. A unit test fails if a limit names none, or one that doesn't exist.
+ */
+export declare const LIMIT_CHECKS: {
+    readonly [Id in LimitId]: readonly string[];
+};