forgebook 0.1.8 → 0.3.0

package/dist/src/previewView.d.ts

@@ -0,0 +1,31 @@
+import type { PreviewTexts } from "./previewTexts.ts";
+/** What the page is given when it is written. */
+export type PreviewViewOptions = {
+    /** Its words. */
+    readonly texts: PreviewTexts;
+    /** Forgebook's version, which it names to the host. */
+    readonly version: string;
+    /** The MCP Apps version it speaks. */
+    readonly protocolVersion: string;
+    /** The tool that takes the picture. */
+    readonly shotTool: string;
+    /** How long a story may stay silent before its picture is asked for, in ms. */
+    readonly silenceMs: number;
+    /** The class of a frame still loading, which the style sheet keeps out of sight. */
+    readonly loadingClass: string;
+};
+/** The ids of the elements `previewPages.ts` writes, which the page fills. */
+export declare const PREVIEW_ELEMENTS: {
+    readonly title: "story";
+    readonly open: "open";
+    readonly status: "status";
+    readonly frame: "frame";
+    readonly picture: "picture";
+};
+/**
+ * Runs the page.
+ *
+ * @param options - what it is given.
+ * @param elements - the ids of its elements.
+ */
+export declare const previewView: (options: PreviewViewOptions, elements: typeof PREVIEW_ELEMENTS) => void;

package/dist/src/previewView.js

@@ -0,0 +1,264 @@
+/** The ids of the elements `previewPages.ts` writes, which the page fills. */
+export const PREVIEW_ELEMENTS = {
+    title: "story",
+    open: "open",
+    status: "status",
+    frame: "frame",
+    picture: "picture"
+};
+/**
+ * Runs the page.
+ *
+ * @param options - what it is given.
+ * @param elements - the ids of its elements.
+ */
+export const previewView = (options, elements) => {
+    const { texts } = options;
+    const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+    const textOf = (value) => typeof value === "string" && value !== "" ? value : undefined;
+    const required = (id, type) => {
+        const found = document.getElementById(id);
+        if (!(found instanceof type))
+            throw new Error(`The page has no ${id}`);
+        return found;
+    };
+    const title = required(elements.title, HTMLElement);
+    const open = required(elements.open, HTMLButtonElement);
+    const status = required(elements.status, HTMLElement);
+    const frame = required(elements.frame, HTMLIFrameElement);
+    const picture = required(elements.picture, HTMLImageElement);
+    /* the host's side of the conversation */
+    let lastId = 0;
+    const waiting = new Map();
+    const post = (message) => {
+        window.parent.postMessage({ jsonrpc: "2.0", ...message }, "*");
+    };
+    const notify = (method, params) => {
+        post({ method, params });
+    };
+    const ask = (method, params) => new Promise((done) => {
+        lastId += 1;
+        waiting.set(lastId, done);
+        post({ id: lastId, method, params });
+    });
+    /* what the page knows */
+    let storyId;
+    let view;
+    let address;
+    let hostOpensLinks = false;
+    let hostCallsTools = false;
+    let isLive = false;
+    let isFallingBack = false;
+    let hasRelay = false;
+    let storyOrigin;
+    let silence;
+    const say = (text) => {
+        status.textContent = text;
+        status.hidden = text === "";
+    };
+    const showLink = () => {
+        open.hidden = !(hostOpensLinks && address !== undefined);
+    };
+    const showLive = () => {
+        isLive = true;
+        clearTimeout(silence);
+        say("");
+        picture.hidden = true;
+        frame.classList.remove(options.loadingClass);
+    };
+    // at this page's own width, so that the picture is not a whole window shrunk into it
+    const pictureView = () => {
+        const search = new URLSearchParams(view);
+        if (!search.has("width"))
+            search.set("width", String(document.body.clientWidth));
+        return search.toString();
+    };
+    const showPicture = async () => {
+        if (isLive || isFallingBack || storyId === undefined)
+            return;
+        isFallingBack = true;
+        clearTimeout(silence);
+        if (!hostCallsTools) {
+            say(texts.previewUnavailable);
+            return;
+        }
+        say(texts.previewTakingPicture);
+        const { result } = await ask("tools/call", {
+            name: options.shotTool,
+            arguments: { id: storyId, views: [pictureView()] }
+        });
+        if (isLive)
+            return;
+        const content = isRecord(result) && Array.isArray(result["content"]) ? result["content"] : [];
+        const image = content.find((block) => isRecord(block) && block["type"] === "image");
+        if (!isRecord(image) || typeof image["data"] !== "string") {
+            say(texts.previewUnavailable);
+            return;
+        }
+        picture.src = `data:image/png;base64,${image["data"]}`;
+        picture.hidden = false;
+        say("");
+    };
+    const showStory = (preview) => {
+        const url = new URL(preview);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return;
+        say(texts.previewLoading);
+        silence = setTimeout(() => void showPicture(), options.silenceMs);
+        storyOrigin = url.origin;
+        // laid out while it loads, only out of sight: a frame with no box has no viewport and no animation frames, so a
+        // story measuring itself gets zero and a play waiting on either never ends
+        frame.classList.add(options.loadingClass);
+        frame.hidden = false;
+        frame.src = url.href;
+    };
+    const showFailure = (structured) => {
+        const reason = isRecord(structured) ? textOf(structured["error"]) : undefined;
+        say(reason ?? texts.previewUnavailable);
+    };
+    const showAnswer = (answer) => {
+        const structured = isRecord(answer) ? answer["structuredContent"] : undefined;
+        const hasFailed = !isRecord(answer) || answer["isError"] === true;
+        if (hasFailed || !isRecord(structured)) {
+            showFailure(structured);
+            return;
+        }
+        const links = structured["links"];
+        address = isRecord(links) ? textOf(links["address"]) : undefined;
+        storyId = textOf(structured["id"]) ?? storyId;
+        title.textContent = storyId ?? "";
+        showLink();
+        const preview = textOf(structured["preview"]);
+        if (preview === undefined)
+            void showPicture();
+        else
+            showStory(preview);
+    };
+    const applyVariables = (styles) => {
+        const variables = isRecord(styles) ? styles["variables"] : undefined;
+        if (!isRecord(variables))
+            return;
+        for (const [name, value] of Object.entries(variables))
+            if (typeof value === "string")
+                document.documentElement.style.setProperty(name, value);
+    };
+    const applyBox = (box) => {
+        if (!isRecord(box))
+            return;
+        const { style } = document.documentElement;
+        style.height = "";
+        style.maxHeight = "";
+        if ("height" in box)
+            style.height = "100vh";
+        else if (typeof box["maxHeight"] === "number")
+            style.maxHeight = `${box["maxHeight"]}px`;
+    };
+    const applyContext = (context) => {
+        if (!isRecord(context))
+            return;
+        const { theme } = context;
+        if (theme === "light" || theme === "dark")
+            document.documentElement.style.colorScheme = theme;
+        applyVariables(context["styles"]);
+        applyBox(context["containerDimensions"]);
+    };
+    let lastSize = "";
+    const reportSize = () => {
+        const { width, height } = document.body.getBoundingClientRect();
+        const size = { width: Math.ceil(width), height: Math.ceil(height) };
+        if (JSON.stringify(size) === lastSize)
+            return;
+        lastSize = JSON.stringify(size);
+        notify("ui/notifications/size-changed", size);
+    };
+    const applyInitialized = (result) => {
+        if (!isRecord(result))
+            return;
+        const capabilities = result["hostCapabilities"];
+        hostOpensLinks = isRecord(capabilities) && isRecord(capabilities["openLinks"]);
+        hostCallsTools = isRecord(capabilities) && isRecord(capabilities["serverTools"]);
+        applyContext(result["hostContext"]);
+        showLink();
+        notify("ui/notifications/initialized", {});
+        new ResizeObserver(reportSize).observe(document.body);
+    };
+    const answerHost = (id, method) => {
+        // the host waits for the answer before it takes the page down; a story in a frame has nothing to save
+        if (method === "ping" || method === "ui/resource-teardown")
+            post({ id, result: {} });
+        else
+            post({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+    };
+    const hearHost = (method, params) => {
+        if (method === "ui/notifications/tool-result")
+            showAnswer(params);
+        if (method === "ui/notifications/host-context-changed")
+            applyContext(params);
+        if (method === "ui/notifications/tool-cancelled")
+            say(texts.previewCancelled);
+        if (method === "ui/notifications/tool-input" && isRecord(params) && isRecord(params["arguments"])) {
+            storyId = textOf(params["arguments"]["id"]);
+            view = textOf(params["arguments"]["view"]);
+            title.textContent = storyId ?? "";
+        }
+    };
+    const hearStory = (message) => {
+        if (!isRecord(message))
+            return;
+        const started = "forgebook:preview-started";
+        const ready = "forgebook:preview-ready";
+        const size = "forgebook:preview-size";
+        if (message["type"] === started)
+            hasRelay = true;
+        if (message["type"] === ready)
+            showLive();
+        if (message["type"] === size && typeof message["height"] === "number" && message["height"] > 0)
+            frame.style.height = `${message["height"]}px`;
+    };
+    window.addEventListener("message", (event) => {
+        if (event.source === frame.contentWindow) {
+            // the source alone would also let a frame that navigated elsewhere speak for the story
+            if (event.origin === storyOrigin)
+                hearStory(event.data);
+            return;
+        }
+        if (event.source !== window.parent || !isRecord(event.data))
+            return;
+        const { id, method, params } = event.data;
+        if (typeof method === "string") {
+            if (id === undefined)
+                hearHost(method, params);
+            else
+                answerHost(id, method);
+            return;
+        }
+        if (typeof id !== "number")
+            return;
+        waiting.get(id)?.(event.data);
+        waiting.delete(id);
+    });
+    // a frame the host's policy refuses never says so to the frame, only to the document that asked for it
+    document.addEventListener("securitypolicyviolation", (event) => {
+        if (event.effectiveDirective === "frame-src")
+            void showPicture();
+    });
+    frame.addEventListener("load", () => {
+        if (!hasRelay)
+            void showPicture();
+    });
+    open.addEventListener("click", () => {
+        if (address !== undefined)
+            void ask("ui/open-link", { url: address });
+    });
+    open.textContent = texts.previewOpen;
+    frame.title = texts.previewFrame;
+    picture.alt = texts.previewPicture;
+    say(texts.previewWaiting);
+    void ask("ui/initialize", {
+        appInfo: { name: "forgebook-story-preview", version: options.version },
+        appCapabilities: { availableDisplayModes: ["inline"] },
+        protocolVersion: options.protocolVersion
+    }).then(({ result }) => {
+        applyInitialized(result);
+    });
+};

package/dist/src/propGroups.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A component's props in their groups, as its TSDoc names them (`@group Selection`), with its required props where the
+ * catalogue, the component or the story asks (`requiredFirst`): the API reference and the Props tab list them the same
+ * way.
+ *
+ * @remarks
+ * The props that name no group come first: they are the ones an author left out of every group, most often the few
+ * every use of the component sets (`value`, `onChange`). Then each group, in the order a configuration names them
+ * (the component's meta, then the catalogue), the others in the order they first appear among the props. A component
+ * whose props name no group is one list, as it always was. Every group starts open: a reader folds one away, never the
+ * catalogue.
+ *
+ * The required props come first inside each group by default, the others keeping the order of the source, so a reader
+ * sees at once what every use must set. A `section` layout gathers them in one section before the groups instead,
+ * which only means something when there are groups: without, it is the same single list. The narrowest setting wins
+ * (the story's, the component's, the catalogue's), and a reader's switch turns the ordering on or off over them,
+ * never choosing the layout, which stays the developer's. Pure.
+ *
+ * @module
+ */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
+/** A group of props: its name, none for the props that name no group, and its props in their order. */
+export type PropGroup<TProp> = {
+    /** The group's name, as `@group` writes it; none for the props that name no group. */
+    readonly name: string | undefined;
+    /** Its props, in their order among the component's. */
+    readonly props: readonly TProp[];
+};
+/**
+ * The order of the groups named first: the component's own (its meta's `parameters.propGroups`), then the
+ * catalogue's (`propGroups` in its configuration) not already named, each once.
+ *
+ * @param componentOrder - the groups the component names first; none by default.
+ * @param catalogueOrder - the groups the catalogue names first; none by default.
+ */
+export declare const propGroupOrder: (componentOrder?: readonly string[], catalogueOrder?: readonly string[]) => readonly string[];
+/**
+ * Props in their groups: those naming no group first, then the groups named in `order`, in its order, then the others
+ * in the order they first appear. A group with no props is never listed, even when `order` names it.
+ *
+ * @param props - the props, in their order.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ */
+export declare const groupedProps: <TProp extends {
+    readonly group?: string | undefined;
+}>(props: readonly TProp[], order: readonly string[]) => PropGroup<TProp>[];
+/**
+ * Whether any of the props names a group: when none does, the props are listed as one list, as before groups.
+ *
+ * @param props - the props.
+ */
+export declare const hasPropGroups: (props: readonly {
+    readonly group?: string | undefined;
+}[]) => boolean;
+/** The layouts the required props can take, as a configuration and `parameters.requiredFirst` write them. */
+export declare const REQUIRED_FIRST_LAYOUTS: readonly RequiredFirst[];
+/**
+ * The layout a reader sees: the narrowest the developer set (the story's or the component's, else the catalogue's),
+ * with the reader's switch over it. Turned off, the source's order; turned on where the developer chose the source's
+ * order, the catalogue's layout, else `in-groups`.
+ *
+ * @param own - the story's or the component's setting; none leaves it to the catalogue.
+ * @param catalogue - the catalogue's setting.
+ * @param isReaderOn - the reader's switch; none when the reader never turned it.
+ */
+export declare const requiredFirstLayout: (own: RequiredFirst | undefined, catalogue: RequiredFirst, isReaderOn: boolean | undefined) => RequiredFirst;
+/** A prop as the layout reads it: its group, whether it is required, and whether it is an event. */
+type LaidOutProp = {
+    readonly group?: string | undefined;
+    readonly isRequired: boolean;
+    readonly kind?: string;
+};
+/** Props laid out for reading: the "Required" section, the groups, the events. */
+export type PropLayout<TProp> = {
+    /**
+     * The "Required" section's props, those naming no group first, then each group's in the groups' order, then the
+     * events; empty unless the layout is `section` and the props name a group.
+     */
+    readonly required: readonly TProp[];
+    /** The props but the events in their groups (`groupedProps`), without those in `required`; no group left empty. */
+    readonly groups: readonly PropGroup<TProp>[];
+    /** The events, without those in `required`. */
+    readonly events: readonly TProp[];
+};
+/**
+ * Whether putting the required props first changes anything: a required prop and one that is not. A table without
+ * shows no "Required first" switch.
+ *
+ * @param props - the props shown.
+ */
+export declare const canOrderRequired: (props: readonly {
+    readonly isRequired: boolean;
+}[]) => boolean;
+/**
+ * Props with the required ones first, the rest in their order.
+ *
+ * @param props - the props, in their order.
+ */
+export declare const requiredPropsFirst: <TProp extends LaidOutProp>(props: readonly TProp[]) => TProp[];
+/**
+ * Props laid out for reading: in their groups (`groupedProps`), the events apart, the required ones where the layout
+ * puts them.
+ *
+ * @param props - the props, events among them (`kind: "event"`), in the order of the source.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ * @param layout - where the required props go (`requiredFirstLayout`).
+ */
+export declare const laidOutProps: <TProp extends LaidOutProp>(props: readonly TProp[], order: readonly string[], layout: RequiredFirst) => PropLayout<TProp>;
+export {};

package/dist/src/propGroups.js

@@ -0,0 +1,113 @@
+/**
+ * The order of the groups named first: the component's own (its meta's `parameters.propGroups`), then the
+ * catalogue's (`propGroups` in its configuration) not already named, each once.
+ *
+ * @param componentOrder - the groups the component names first; none by default.
+ * @param catalogueOrder - the groups the catalogue names first; none by default.
+ */
+export const propGroupOrder = (componentOrder = [], catalogueOrder = []) => [...new Set([...componentOrder, ...catalogueOrder])];
+/**
+ * Props in their groups: those naming no group first, then the groups named in `order`, in its order, then the others
+ * in the order they first appear. A group with no props is never listed, even when `order` names it.
+ *
+ * @param props - the props, in their order.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ */
+export const groupedProps = (props, order) => {
+    const ungrouped = [];
+    // a map keeps its keys in the order they were first set: the order the groups first appear
+    const named = new Map();
+    for (const prop of props) {
+        if (prop.group === undefined) {
+            ungrouped.push(prop);
+            continue;
+        }
+        const group = named.get(prop.group);
+        if (group === undefined)
+            named.set(prop.group, [prop]);
+        else
+            group.push(prop);
+    }
+    const rank = (name) => {
+        const index = order.indexOf(name);
+        return index === -1 ? order.length : index;
+    };
+    const groups = [...named.entries()]
+        .map(([name, grouped]) => ({ name, props: grouped }))
+        // a stable sort: the groups `order` does not name keep the order they appear in
+        .sort((left, right) => rank(left.name ?? "") - rank(right.name ?? ""));
+    return ungrouped.length === 0 ? groups : [{ name: undefined, props: ungrouped }, ...groups];
+};
+/**
+ * Whether any of the props names a group: when none does, the props are listed as one list, as before groups.
+ *
+ * @param props - the props.
+ */
+export const hasPropGroups = (props) => props.some((prop) => prop.group !== undefined);
+/** The layouts the required props can take, as a configuration and `parameters.requiredFirst` write them. */
+export const REQUIRED_FIRST_LAYOUTS = ["in-groups", "section", false];
+/**
+ * The layout a reader sees: the narrowest the developer set (the story's or the component's, else the catalogue's),
+ * with the reader's switch over it. Turned off, the source's order; turned on where the developer chose the source's
+ * order, the catalogue's layout, else `in-groups`.
+ *
+ * @param own - the story's or the component's setting; none leaves it to the catalogue.
+ * @param catalogue - the catalogue's setting.
+ * @param isReaderOn - the reader's switch; none when the reader never turned it.
+ */
+export const requiredFirstLayout = (own, catalogue, isReaderOn) => {
+    const chosen = own ?? catalogue;
+    if (isReaderOn === undefined)
+        return chosen;
+    if (!isReaderOn)
+        return false;
+    if (chosen !== false)
+        return chosen;
+    return catalogue === false ? "in-groups" : catalogue;
+};
+/**
+ * Whether putting the required props first changes anything: a required prop and one that is not. A table without
+ * shows no "Required first" switch.
+ *
+ * @param props - the props shown.
+ */
+export const canOrderRequired = (props) => props.some((prop) => prop.isRequired) && props.some((prop) => !prop.isRequired);
+/**
+ * Props with the required ones first, the rest in their order.
+ *
+ * @param props - the props, in their order.
+ */
+export const requiredPropsFirst = (props) => [
+    ...props.filter((prop) => prop.isRequired),
+    ...props.filter((prop) => !prop.isRequired)
+];
+/**
+ * Props laid out for reading: in their groups (`groupedProps`), the events apart, the required ones where the layout
+ * puts them.
+ *
+ * @param props - the props, events among them (`kind: "event"`), in the order of the source.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ * @param layout - where the required props go (`requiredFirstLayout`).
+ */
+export const laidOutProps = (props, order, layout) => {
+    const isEvent = (prop) => prop.kind === "event";
+    const listed = props.filter((prop) => !isEvent(prop));
+    const groups = groupedProps(listed, order);
+    const events = props.filter(isEvent);
+    if (layout === false)
+        return { required: [], groups, events };
+    if (layout === "in-groups" || !hasPropGroups(listed)) {
+        return {
+            required: [],
+            groups: groups.map((group) => ({ name: group.name, props: requiredPropsFirst(group.props) })),
+            events: requiredPropsFirst(events)
+        };
+    }
+    return {
+        required: [...groups.flatMap((group) => group.props), ...events].filter((prop) => prop.isRequired),
+        groups: groups
+            .map((group) => ({ name: group.name, props: group.props.filter((prop) => !prop.isRequired) }))
+            .filter((group) => group.props.length > 0),
+        events: events.filter((prop) => !prop.isRequired)
+    };
+};

package/dist/src/realTouch.d.ts

@@ -1,7 +1,7 @@
 /**
  * The mark of a window where Chromium's own touch emulation runs (`forgebook dev --touch`): its pages see real touch,
  * so the catalogue's simulated touch stays off there. Shared by the window that sets it (`@forgebook/testing/touch`)
- * and the frame that reads it (`touchLayer.ts`).
+ * and the frame that reads it (`followTouch.ts`).
  *
  * @module
  */
@@ -18,4 +18,3 @@ export type TouchWindowRequest = {
     /** The catalogue's address. */
     readonly url: string;
 };
-//# sourceMappingURL=realTouch.d.ts.map

package/dist/src/realTouch.js

@@ -1,7 +1,7 @@
 /**
  * The mark of a window where Chromium's own touch emulation runs (`forgebook dev --touch`): its pages see real touch,
  * so the catalogue's simulated touch stays off there. Shared by the window that sets it (`@forgebook/testing/touch`)
- * and the frame that reads it (`touchLayer.ts`).
+ * and the frame that reads it (`followTouch.ts`).
  *
  * @module
  */
@@ -13,4 +13,3 @@ export const REAL_TOUCH_FLAG = "__forgebookRealTouch";
  * @param view - the window.
  */
 export const isRealTouchWindow = (view) => REAL_TOUCH_FLAG in view;
-//# sourceMappingURL=realTouch.js.map

package/dist/src/safeAreaParameter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The safe areas a story drawn edge to edge in a device is told, in its frame's address: the parameter that carries
+ * them (`forgebook.safe-area=59,0,34,0`, top, right, bottom and left in CSS px) and the custom properties the frame
+ * writes from it on its root, which such a story pads itself with.
+ *
+ * @remarks
+ * A page in a frame cannot be given `env(safe-area-inset-*)`: browsers keep them at zero there, and only a browser's
+ * own protocol can change them. So the frame writes `--forgebook-safe-area-top`, `-right`, `-bottom` and `-left`
+ * instead, and a story reads them with the real insets as the fallback, for the page it ships in:
+ * `padding-top: var(--forgebook-safe-area-top, env(safe-area-inset-top))`. A story that is not drawn edge to edge
+ * sits inside the safe area and is told nothing. Read by the frame, written by the shell and `forgebook shot`, so
+ * every side reads one format. Pure.
+ *
+ * @module
+ */
+/** The frame's address parameter of the safe areas. */
+export declare const SAFE_AREA_PARAMETER = "forgebook.safe-area";
+/** The sides of the safe areas, in the parameter's order and the custom properties' names. */
+declare const SIDES: readonly ["top", "right", "bottom", "left"];
+/** The safe areas on each side, in CSS px. */
+export type SafeArea = Readonly<Record<(typeof SIDES)[number], number>>;
+/**
+ * A frame's address with the safe areas a story drawn edge to edge is told.
+ *
+ * @param address - the frame's address.
+ * @param safeArea - the safe areas.
+ */
+export declare const withSafeArea: (address: string, safeArea: SafeArea) => string;
+/**
+ * The custom properties a frame's address asks for: none when it carries no safe areas, or carries them wrongly.
+ *
+ * @param search - the frame's query.
+ */
+export declare const safeAreaProperties: (search: string) => readonly (readonly [string, string])[];
+/**
+ * Tells a page the safe areas its address carries, as CSS properties on its root.
+ *
+ * @param root - the page's root element.
+ * @param search - the page's address's query.
+ */
+export declare const applySafeArea: (root: HTMLElement, search: string) => void;
+export {};

package/dist/src/safeAreaParameter.js

@@ -0,0 +1,50 @@
+/**
+ * The safe areas a story drawn edge to edge in a device is told, in its frame's address: the parameter that carries
+ * them (`forgebook.safe-area=59,0,34,0`, top, right, bottom and left in CSS px) and the custom properties the frame
+ * writes from it on its root, which such a story pads itself with.
+ *
+ * @remarks
+ * A page in a frame cannot be given `env(safe-area-inset-*)`: browsers keep them at zero there, and only a browser's
+ * own protocol can change them. So the frame writes `--forgebook-safe-area-top`, `-right`, `-bottom` and `-left`
+ * instead, and a story reads them with the real insets as the fallback, for the page it ships in:
+ * `padding-top: var(--forgebook-safe-area-top, env(safe-area-inset-top))`. A story that is not drawn edge to edge
+ * sits inside the safe area and is told nothing. Read by the frame, written by the shell and `forgebook shot`, so
+ * every side reads one format. Pure.
+ *
+ * @module
+ */
+/** The frame's address parameter of the safe areas. */
+export const SAFE_AREA_PARAMETER = "forgebook.safe-area";
+/** The sides of the safe areas, in the parameter's order and the custom properties' names. */
+const SIDES = ["top", "right", "bottom", "left"];
+/**
+ * A frame's address with the safe areas a story drawn edge to edge is told.
+ *
+ * @param address - the frame's address.
+ * @param safeArea - the safe areas.
+ */
+export const withSafeArea = (address, safeArea) => {
+    const value = SIDES.map((side) => String(Math.round(safeArea[side]))).join(",");
+    return `${address}${address.includes("?") ? "&" : "?"}${SAFE_AREA_PARAMETER}=${value}`;
+};
+/**
+ * The custom properties a frame's address asks for: none when it carries no safe areas, or carries them wrongly.
+ *
+ * @param search - the frame's query.
+ */
+export const safeAreaProperties = (search) => {
+    const values = (new URLSearchParams(search).get(SAFE_AREA_PARAMETER) ?? "").split(",").map(Number);
+    if (values.length !== SIDES.length || values.some((value) => !Number.isFinite(value) || value < 0))
+        return [];
+    return SIDES.map((side, index) => [`--forgebook-safe-area-${side}`, `${values[index] ?? 0}px`]);
+};
+/**
+ * Tells a page the safe areas its address carries, as CSS properties on its root.
+ *
+ * @param root - the page's root element.
+ * @param search - the page's address's query.
+ */
+export const applySafeArea = (root, search) => {
+    for (const [name, value] of safeAreaProperties(search))
+        root.style.setProperty(name, value);
+};