forgebook 0.1.8 → 0.3.0

package/dist/src/deviceDrawing.js

@@ -0,0 +1,358 @@
+import { deviceScreen } from "./devices.js";
+/** The paints of the hardware in each of the shell's appearances: quiet greys, a black bezel, as phones are. */
+export const DEVICE_PAINTS = {
+    light: { frame: "#d6d6db", edge: "#1d1d1f2e", bezel: "#0c0c0e", cutout: "#000" },
+    dark: { frame: "#46464d", edge: "#ffffff2b", bezel: "#050506", cutout: "#000" }
+};
+/** The status bar's ink over a story of each scheme: dark on a light story, light on a dark one. */
+export const DEVICE_INK = { light: "#000", dark: "#fff" };
+/** The status bar's font: the system's, as the devices' own. */
+export const DEVICE_FONT = '-apple-system, BlinkMacSystemFont, "SF Pro Text", Roboto, system-ui, sans-serif';
+/** The time the status bar shows: the one phones are photographed at. */
+const STATUS_TIME = "9:41";
+/** How far a button stands out of the band, in CSS px: the drawing's margin on every side. */
+const BUTTON_DEPTH = 3;
+/** The band's and the bezel's thickness, in CSS px, by kind. */
+const THICKNESS = {
+    phone: { band: 4, bezel: 10 },
+    tablet: { band: 4, bezel: 18 }
+};
+/** Each model's buttons, as its maker places them. */
+const BUTTONS = {
+    "iphone-16": [
+        { side: "left", at: 0.18, length: 0.04 },
+        { side: "left", at: 0.26, length: 0.075 },
+        { side: "left", at: 0.36, length: 0.075 },
+        { side: "right", at: 0.29, length: 0.12 },
+        { side: "right", at: 0.62, length: 0.06 }
+    ],
+    "iphone-16-pro-max": [
+        { side: "left", at: 0.18, length: 0.04 },
+        { side: "left", at: 0.26, length: 0.075 },
+        { side: "left", at: 0.36, length: 0.075 },
+        { side: "right", at: 0.29, length: 0.12 },
+        { side: "right", at: 0.62, length: 0.06 }
+    ],
+    "iphone-16e": [
+        { side: "left", at: 0.18, length: 0.04 },
+        { side: "left", at: 0.26, length: 0.075 },
+        { side: "left", at: 0.36, length: 0.075 },
+        { side: "right", at: 0.29, length: 0.12 }
+    ],
+    "pixel-9": [
+        { side: "right", at: 0.22, length: 0.07 },
+        { side: "right", at: 0.32, length: 0.13 }
+    ],
+    "galaxy-s24": [
+        { side: "right", at: 0.22, length: 0.12 },
+        { side: "right", at: 0.38, length: 0.07 }
+    ],
+    phone: [
+        { side: "right", at: 0.24, length: 0.12 },
+        { side: "right", at: 0.4, length: 0.06 }
+    ],
+    "ipad-mini": [
+        { side: "top", at: 0.8, length: 0.07 },
+        { side: "right", at: 0.07, length: 0.045 },
+        { side: "right", at: 0.13, length: 0.045 }
+    ],
+    "ipad-pro-13": [
+        { side: "top", at: 0.82, length: 0.05 },
+        { side: "right", at: 0.06, length: 0.035 },
+        { side: "right", at: 0.105, length: 0.035 }
+    ]
+};
+/** A length kept to two decimals: the drawings' numbers stay short and stable. */
+const round = (value) => Math.round(value * 100) / 100;
+/** A rectangle of the upright drawing, moved as the drawing is held: on its side, its width and height swap. */
+const placedRect = (map, isTurned, rect) => {
+    const [x, y] = isTurned ? map(rect.x + rect.width, rect.y) : map(rect.x, rect.y);
+    return {
+        x: round(x),
+        y: round(y),
+        width: round(isTurned ? rect.height : rect.width),
+        height: round(isTurned ? rect.width : rect.height),
+        radius: round(rect.radius)
+    };
+};
+/** The upright size of a model's drawing, and the hardware's thickness around its screen. */
+const uprightBox = (model) => {
+    const { band, bezel } = THICKNESS[model.kind];
+    const around = BUTTON_DEPTH + band + bezel;
+    return { width: model.width + 2 * around, height: model.height + 2 * around, around };
+};
+/** The buttons, upright, standing out of the band. */
+const buttonRects = (model, body) => BUTTONS[model.id].map((button) => {
+    const along = button.side === "top" ? body.width : body.height;
+    const start = along * button.at;
+    const length = along * button.length;
+    if (button.side === "top")
+        return { x: body.x + start, y: 0, width: length, height: BUTTON_DEPTH + 2, radius: 1 };
+    return {
+        x: button.side === "left" ? 0 : body.x + body.width - 2,
+        y: body.y + start,
+        width: BUTTON_DEPTH + 2,
+        height: length,
+        radius: 1
+    };
+});
+/**
+ * The camera's cut, upright, then moved as held: a notch is a path, drawn point by point through the map, since
+ * turning keeps its arcs' direction.
+ */
+const cutoutShapes = (model, screen, map, isTurned) => {
+    const cutout = model.cutout;
+    if (cutout === undefined)
+        return [];
+    const middle = screen.x + screen.width / 2;
+    if (cutout.kind === "island") {
+        const rect = placedRect(map, isTurned, {
+            x: middle - cutout.width / 2,
+            y: screen.y + cutout.top,
+            width: cutout.width,
+            height: cutout.height,
+            radius: cutout.height / 2
+        });
+        return [{ kind: "rect", ...rect, fill: "cutout" }];
+    }
+    if (cutout.kind === "hole") {
+        const [cx, cy] = map(middle, screen.y + cutout.top + cutout.diameter / 2);
+        return [{ kind: "circle", cx: round(cx), cy: round(cy), r: cutout.diameter / 2, fill: "cutout" }];
+    }
+    // a notch: straight sides from the top edge, its lower corners rounded, its upper ones flaring into the edge
+    const point = (x, y) => {
+        const [px, py] = map(x, y);
+        return `${round(px)} ${round(py)}`;
+    };
+    const left = middle - cutout.width / 2;
+    const right = middle + cutout.width / 2;
+    const top = screen.y;
+    const bottom = top + cutout.height;
+    const flare = 6;
+    const corner = 20;
+    return [
+        {
+            kind: "path",
+            d: [
+                `M${point(left - flare, top)}`,
+                `A${flare} ${flare} 0 0 1 ${point(left, top + flare)}`,
+                `L${point(left, bottom - corner)}`,
+                `A${corner} ${corner} 0 0 0 ${point(left + corner, bottom)}`,
+                `L${point(right - corner, bottom)}`,
+                `A${corner} ${corner} 0 0 0 ${point(right, bottom - corner)}`,
+                `L${point(right, top + flare)}`,
+                `A${flare} ${flare} 0 0 1 ${point(right + flare, top)}`,
+                "Z"
+            ].join(" "),
+            fill: "cutout"
+        }
+    ];
+};
+/** The iOS signal bars, from their left, on a line through their middle; 17 px wide. */
+const iosSignal = (x, y) => [4, 6.3, 8.7, 11].map((height, index) => ({
+    kind: "rect",
+    x: round(x + index * 4.6),
+    y: round(y + 5.5 - height),
+    width: 3,
+    height,
+    radius: 1,
+    fill: "ink"
+}));
+/**
+ * A fan of a Wi-Fi mark, as a path: the ring between two radii (none inside makes a wedge), a quarter turn wide,
+ * pointing up from its centre.
+ */
+const fanBand = (cx, cy, outer, inner) => {
+    const at = (radius, degrees) => {
+        const angle = (degrees * Math.PI) / 180;
+        return `${round(cx + radius * Math.cos(angle))} ${round(cy + radius * Math.sin(angle))}`;
+    };
+    const inside = inner === 0
+        ? `L${round(cx)} ${round(cy)}`
+        : `L${at(inner, -45)} A${inner} ${inner} 0 0 0 ${at(inner, -135)}`;
+    return `M${at(outer, -135)} A${outer} ${outer} 0 0 1 ${at(outer, -45)} ${inside} Z`;
+};
+/** The iOS Wi-Fi mark, three bands, from its left; 15.5 px wide. */
+const iosWifi = (x, y) => [
+    [11, 8.6],
+    [7.2, 4.8],
+    [3.4, 0]
+].map(([outer = 0, inner = 0]) => ({
+    kind: "path",
+    d: fanBand(x + 7.78, y + 5.5, outer, inner),
+    fill: "ink"
+}));
+/** The iOS battery, full, from its left; 27 px wide. */
+const iosBattery = (x, y) => [
+    { kind: "rect", x, y: y - 6, width: 24.3, height: 12, radius: 3.8, stroke: "ink", opacity: 0.4 },
+    { kind: "rect", x: x + 2, y: y - 4, width: 20.3, height: 8, radius: 2.4, fill: "ink" },
+    { kind: "rect", x: x + 25.3, y: y - 2, width: 1.5, height: 4, radius: 0.75, fill: "ink", opacity: 0.4 }
+];
+/** The Android signal, a triangle, from its left; 11 px wide. */
+const androidSignal = (x, y) => [
+    { kind: "path", d: `M${round(x)} ${round(y + 5.5)}H${round(x + 11)}V${round(y - 5.5)}Z`, fill: "ink" }
+];
+/** The Android Wi-Fi mark, one wedge, from its left; 14 px wide. */
+const androidWifi = (x, y) => [
+    { kind: "path", d: fanBand(x + 7, y + 4.5, 9.9, 0), fill: "ink" }
+];
+/** The Android battery, upright and full, from its left; 7 px wide. */
+const androidBattery = (x, y) => [
+    { kind: "rect", x: x + 2, y: y - 7.5, width: 3, height: 1.5, radius: 0.5, fill: "ink" },
+    { kind: "rect", x, y: y - 6.5, width: 7, height: 13, radius: 1.5, fill: "ink" }
+];
+/** A row of marks from a left edge, each drawn by its maker and as wide as it says, with a gap between. */
+const markRow = (x, y, marks, gap) => {
+    let left = x;
+    return marks.flatMap((mark) => {
+        const shapes = mark.draw(left, y);
+        left += mark.width + gap;
+        return shapes;
+    });
+};
+/** A row's width: its marks' and the gaps between them. */
+const rowWidth = (marks, gap) => marks.reduce((sum, mark) => sum + mark.width, 0) + gap * (marks.length - 1);
+/** The marks at an iPhone's status bar's end. */
+const IOS_PHONE_MARKS = [
+    { draw: iosSignal, width: 17 },
+    { draw: iosWifi, width: 15.5 },
+    { draw: iosBattery, width: 27 }
+];
+/** The marks at an iPad's status bar's end. */
+const IOS_TABLET_MARKS = [
+    { draw: iosWifi, width: 15.5 },
+    { draw: iosBattery, width: 27 }
+];
+/** The marks at an Android device's status bar's end. */
+const ANDROID_MARKS = [
+    { draw: androidWifi, width: 14 },
+    { draw: androidSignal, width: 11 },
+    { draw: androidBattery, width: 7 }
+];
+/**
+ * An iPhone's status bar, upright: the time and the marks in the middle of the two ears the camera's cut leaves.
+ */
+const iphoneStatusBar = (model, screen) => {
+    const { safeArea } = deviceScreen(model, "portrait");
+    const cutout = model.cutout;
+    const cutWidth = cutout?.kind === "island" || cutout?.kind === "notch" ? cutout.width : 0;
+    const ear = (screen.width - cutWidth) / 2;
+    const middle = cutout?.kind === "island" ? cutout.top + cutout.height / 2 : Math.min(safeArea.top / 2 + 1, 24);
+    const y = screen.y + middle;
+    const width = rowWidth(IOS_PHONE_MARKS, 5.5);
+    return [
+        {
+            kind: "text",
+            x: round(screen.x + ear / 2 + 4),
+            y: round(y),
+            text: STATUS_TIME,
+            size: 17,
+            weight: 600,
+            anchor: "middle",
+            fill: "ink"
+        },
+        ...markRow(screen.x + screen.width - ear / 2 - width / 2 - 4, y, IOS_PHONE_MARKS, 5.5)
+    ];
+};
+/** The status bar, laid out for the screen as held; none on an iPhone on its side, as iOS shows none there. */
+const statusBar = (model, orientation, screen) => {
+    const isUpright = orientation === "portrait";
+    if (model.platform === "ios" && model.kind === "phone")
+        return isUpright ? iphoneStatusBar(model, screen) : [];
+    const { safeArea } = deviceScreen(model, orientation);
+    const isTablet = model.kind === "tablet";
+    const marks = model.platform === "ios" ? IOS_TABLET_MARKS : ANDROID_MARKS;
+    const gap = model.platform === "ios" ? 5.5 : 6;
+    const hole = model.cutout?.kind === "hole" ? model.cutout : undefined;
+    // an upright punch hole sets the bar's middle; on its side the hole is at the left, out of the bar
+    const middle = hole !== undefined && isUpright ? hole.top + hole.diameter / 2 : (isTablet ? 24 : safeArea.top) / 2;
+    const y = screen.y + middle;
+    const edge = isTablet ? 20 : 22;
+    return [
+        {
+            kind: "text",
+            x: round(screen.x + Math.max(edge, safeArea.left + 10)),
+            y: round(y),
+            text: STATUS_TIME,
+            size: isTablet ? 13 : 14,
+            weight: isTablet ? 600 : 500,
+            anchor: "start",
+            fill: "ink"
+        },
+        ...markRow(screen.x + screen.width - edge - rowWidth(marks, gap), y, marks, gap)
+    ];
+};
+/** The home indicator at the screen's foot: iOS's bar, or Android's gesture handle. */
+const homeIndicator = (model, orientation, screen) => {
+    const isIos = model.platform === "ios";
+    const phoneRatio = orientation === "portrait" ? 0.34 : 0.25;
+    const ratio = model.kind === "tablet" ? 0.3 : phoneRatio;
+    const width = isIos ? Math.min(315, screen.width * ratio) : 108;
+    const height = isIos ? 5 : 4;
+    return {
+        kind: "rect",
+        x: round(screen.x + (screen.width - width) / 2),
+        y: round(screen.y + screen.height - 8 - height),
+        width: round(width),
+        height,
+        radius: height / 2,
+        fill: "ink"
+    };
+};
+/**
+ * A model drawn, held one way.
+ *
+ * @param model - the model.
+ * @param orientation - how it is held: on its side, its top to the left.
+ */
+export const deviceDrawing = (model, orientation) => {
+    const upright = uprightBox(model);
+    const isTurned = orientation === "landscape";
+    // turning the phone with its top to the left: the upright top edge becomes the left one
+    const map = isTurned
+        ? (x, y) => [y, upright.width - x]
+        : (x, y) => [x, y];
+    const { band, bezel } = THICKNESS[model.kind];
+    const body = {
+        x: BUTTON_DEPTH,
+        y: BUTTON_DEPTH,
+        width: upright.width - 2 * BUTTON_DEPTH,
+        height: upright.height - 2 * BUTTON_DEPTH,
+        radius: model.radius + bezel + band
+    };
+    const glass = {
+        x: body.x + band,
+        y: body.y + band,
+        width: body.width - 2 * band,
+        height: body.height - 2 * band,
+        radius: model.radius + bezel
+    };
+    const uprightScreen = {
+        x: upright.around,
+        y: upright.around,
+        width: model.width,
+        height: model.height,
+        radius: model.radius
+    };
+    const screen = placedRect(map, isTurned, uprightScreen);
+    return {
+        width: isTurned ? upright.height : upright.width,
+        height: isTurned ? upright.width : upright.height,
+        screen,
+        under: [
+            ...buttonRects(model, body).map((rect) => ({
+                kind: "rect",
+                ...placedRect(map, isTurned, rect),
+                fill: "frame",
+                stroke: "edge"
+            })),
+            { kind: "rect", ...placedRect(map, isTurned, body), fill: "frame", stroke: "edge" },
+            { kind: "rect", ...placedRect(map, isTurned, glass), fill: "bezel" }
+        ],
+        over: [
+            ...cutoutShapes(model, uprightScreen, map, isTurned),
+            ...statusBar(model, orientation, screen),
+            homeIndicator(model, orientation, screen)
+        ]
+    };
+};

package/dist/src/deviceMenuView.d.ts

@@ -0,0 +1,17 @@
+import type { DeviceDefault, DeviceId, DeviceView, ShownDevice } from "./deviceView.ts";
+/**
+ * The view with a model chosen: `auto` when it is the one the story shows by default, so the address stays short.
+ *
+ * @param view - the view.
+ * @param story - the story's default.
+ * @param model - the chosen model.
+ */
+export declare const withModel: <View extends DeviceView>(view: View, story: DeviceDefault, model: DeviceId) => View;
+/**
+ * The view with the device turned the other way: `auto` when that is the story's own orientation.
+ *
+ * @param view - the view.
+ * @param story - the story's default.
+ * @param shown - the device shown now.
+ */
+export declare const withTurn: <View extends DeviceView>(view: View, story: DeviceDefault, shown: ShownDevice) => View;

package/dist/src/deviceMenuView.js

@@ -0,0 +1,22 @@
+/**
+ * The view with a model chosen: `auto` when it is the one the story shows by default, so the address stays short.
+ *
+ * @param view - the view.
+ * @param story - the story's default.
+ * @param model - the chosen model.
+ */
+export const withModel = (view, story, model) => ({
+    ...view,
+    device: story.isFramed && story.model === model ? "auto" : model
+});
+/**
+ * The view with the device turned the other way: `auto` when that is the story's own orientation.
+ *
+ * @param view - the view.
+ * @param story - the story's default.
+ * @param shown - the device shown now.
+ */
+export const withTurn = (view, story, shown) => {
+    const turned = shown.orientation === "portrait" ? "landscape" : "portrait";
+    return { ...view, orientation: turned === story.orientation ? "auto" : turned };
+};

package/dist/src/devicePicture.d.ts

@@ -0,0 +1,57 @@
+import { type DeviceView, type ShownDevice } from "./deviceView.ts";
+/** The device a view names: a model, held one way. */
+export type NamedDevice = ShownDevice;
+/** A story's picture framed in a device: the page that draws it, and its size. */
+export type FramedPicture = {
+    /** The page: the device's drawing with the picture in its screen, outside it transparent. */
+    readonly html: string;
+    /** The page's width, in CSS px. */
+    readonly width: number;
+    /** The page's height, in CSS px. */
+    readonly height: number;
+};
+/** What a framed picture is made of. */
+export type PictureRequest = {
+    /** The device and how it is held. */
+    readonly shown: NamedDevice;
+    /** Whether the story draws edge to edge (`parameters.device.edgeToEdge`); inside the safe areas otherwise. */
+    readonly isEdgeToEdge: boolean;
+    /** The story's picture at its area's size (`deviceViewport`), a PNG as base64. */
+    readonly picture: string;
+    /** The story's scheme, which the hardware and the status bar's ink follow. */
+    readonly scheme: "light" | "dark";
+    /** The colour of the story's page, which fills the screen around a story inside the safe areas, as a CSS colour. */
+    readonly background: string;
+};
+/**
+ * The page that draws a story's picture in a device: the story in its area of the screen, the screen around it on
+ * the story's page colour.
+ *
+ * @param request - the device, the picture, the story's scheme and page colour.
+ */
+export declare const framedPicture: (request: PictureRequest) => FramedPicture;
+/**
+ * The device a view names, for a picture or a check: a model's id in the view; a story's own default never counts,
+ * so pictures and tests stay unframed unless asked.
+ *
+ * @param view - the view's device and orientation.
+ */
+export declare const namedDevice: (view: DeviceView) => NamedDevice | undefined;
+/**
+ * The viewport a device gives a story, held as shown: inside the safe areas, or the whole screen edge to edge.
+ *
+ * @param shown - the device and how it is held.
+ * @param isEdgeToEdge - whether the story draws edge to edge.
+ */
+export declare const deviceViewport: (shown: NamedDevice, isEdgeToEdge: boolean) => {
+    readonly width: number;
+    readonly height: number;
+};
+/**
+ * A story frame's address in a device: told the safe areas when it draws edge to edge, as it is otherwise.
+ *
+ * @param address - the frame's address.
+ * @param shown - the device and how it is held.
+ * @param isEdgeToEdge - whether the story draws edge to edge.
+ */
+export declare const deviceFrameAddress: (address: string, shown: NamedDevice, isEdgeToEdge: boolean) => string;

package/dist/src/devicePicture.js

@@ -0,0 +1,104 @@
+/**
+ * A story's picture in a device, for `forgebook shot` (`@forgebook/testing`): the device a view names, the viewport it
+ * gives the story, and the page that draws the story's picture in the device the shell draws (`deviceDrawing.ts`).
+ *
+ * @remarks
+ * The page is made from the drawing's shapes as SVG, with the picture as an image in the screen, so the picture is
+ * the story's held start, as an unframed one is. The hardware takes the story's scheme (a dark story in a dark
+ * device), since a picture has no shell appearance to follow. The one export the testing package reads, so the
+ * drawing's own shapes stay Forgebook's to change. Pure.
+ *
+ * @module
+ */
+import { DEVICE_FONT, DEVICE_INK, DEVICE_PAINTS, deviceDrawing } from "./deviceDrawing.js";
+import { deviceModel, storyArea } from "./devices.js";
+import { NO_DEVICE, shownDevice } from "./deviceView.js";
+import { withSafeArea } from "./safeAreaParameter.js";
+/** A text made safe inside markup. */
+const escaped = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/**
+ * One shape as SVG markup.
+ *
+ * @param shape - the shape.
+ * @param paint - the colour of each paint.
+ */
+const shapeMarkup = (shape, paint) => {
+    if (shape.kind === "rect") {
+        const fill = shape.fill === undefined ? "none" : paint(shape.fill);
+        const stroke = shape.stroke === undefined ? "" : ` stroke="${paint(shape.stroke)}" stroke-width="1"`;
+        const opacity = shape.opacity === undefined ? "" : ` opacity="${shape.opacity}"`;
+        return `<rect x="${shape.x}" y="${shape.y}" width="${shape.width}" height="${shape.height}" rx="${shape.radius}" fill="${fill}"${stroke}${opacity}/>`;
+    }
+    if (shape.kind === "circle")
+        return `<circle cx="${shape.cx}" cy="${shape.cy}" r="${shape.r}" fill="${paint(shape.fill)}"/>`;
+    if (shape.kind === "path")
+        return `<path d="${shape.d}" fill="${paint(shape.fill)}"/>`;
+    return `<text x="${shape.x}" y="${shape.y}" font-size="${shape.size}" font-weight="${shape.weight}" text-anchor="${shape.anchor}" dominant-baseline="central" fill="${paint(shape.fill)}">${escaped(shape.text)}</text>`;
+};
+/**
+ * A layer of the drawing as an SVG covering the page.
+ *
+ * @param drawing - the drawing.
+ * @param shapes - the layer's shapes.
+ * @param paint - the colour of each paint.
+ */
+const layerMarkup = (drawing, shapes, paint) => `<svg width="${drawing.width}" height="${drawing.height}" viewBox="0 0 ${drawing.width} ${drawing.height}" style="position:absolute;inset:0" font-family="${escaped(DEVICE_FONT)}">${shapes.map((shape) => shapeMarkup(shape, paint)).join("")}</svg>`;
+/** A CSS colour as the browser computes one (`rgb(242, 242, 247)`, `#fff`); anything else is drawn transparent. */
+const safeColour = (colour) => (/^[#a-z0-9(),.%\s]+$/i.test(colour) ? colour : "transparent");
+/**
+ * The page that draws a story's picture in a device: the story in its area of the screen, the screen around it on
+ * the story's page colour.
+ *
+ * @param request - the device, the picture, the story's scheme and page colour.
+ */
+export const framedPicture = (request) => {
+    const { shown, scheme } = request;
+    const model = deviceModel(shown.model);
+    const drawing = deviceDrawing(model, shown.orientation);
+    const area = storyArea(model, shown.orientation, request.isEdgeToEdge);
+    const paints = DEVICE_PAINTS[scheme];
+    const paint = (name) => (name === "ink" ? DEVICE_INK[scheme] : paints[name]);
+    const { screen } = drawing;
+    const html = [
+        "<!doctype html>",
+        '<html><body style="margin:0;background:transparent">',
+        `<div style="position:relative;width:${drawing.width}px;height:${drawing.height}px">`,
+        layerMarkup(drawing, drawing.under, paint),
+        `<div style="position:absolute;overflow:hidden;left:${screen.x}px;top:${screen.y}px;width:${screen.width}px;height:${screen.height}px;border-radius:${screen.radius}px;background:${safeColour(request.background)}">`,
+        `<img alt="" src="data:image/png;base64,${request.picture}" style="position:absolute;left:${area.around.left}px;top:${area.around.top}px;width:${area.width}px;height:${area.height}px">`,
+        "</div>",
+        layerMarkup(drawing, drawing.over, paint),
+        "</div></body></html>"
+    ].join("");
+    return { html, width: drawing.width, height: drawing.height };
+};
+/**
+ * The device a view names, for a picture or a check: a model's id in the view; a story's own default never counts,
+ * so pictures and tests stay unframed unless asked.
+ *
+ * @param view - the view's device and orientation.
+ */
+export const namedDevice = (view) => {
+    const shown = shownDevice(view, NO_DEVICE);
+    return shown === undefined ? undefined : { model: shown.model, orientation: shown.orientation };
+};
+/**
+ * The viewport a device gives a story, held as shown: inside the safe areas, or the whole screen edge to edge.
+ *
+ * @param shown - the device and how it is held.
+ * @param isEdgeToEdge - whether the story draws edge to edge.
+ */
+export const deviceViewport = (shown, isEdgeToEdge) => {
+    const { width, height } = storyArea(deviceModel(shown.model), shown.orientation, isEdgeToEdge);
+    return { width, height };
+};
+/**
+ * A story frame's address in a device: told the safe areas when it draws edge to edge, as it is otherwise.
+ *
+ * @param address - the frame's address.
+ * @param shown - the device and how it is held.
+ * @param isEdgeToEdge - whether the story draws edge to edge.
+ */
+export const deviceFrameAddress = (address, shown, isEdgeToEdge) => isEdgeToEdge
+    ? withSafeArea(address, storyArea(deviceModel(shown.model), shown.orientation, true).safeArea)
+    : address;