forgebook 0.1.7 → 0.2.0

package/dist/src/componentDocs.d.ts

@@ -26,6 +26,46 @@ export type EventSignature = {
     /** The return type, as the source writes it. */
     readonly returns: string;
 };
+/** One parameter of a hook's or a function's signature. */
+export type FunctionParameterDocs = {
+    /** The parameter's name; a destructured one's pattern as written (`{ start }`). */
+    readonly name: string;
+    /** Its type, as the source writes it. */
+    readonly type: string;
+    /** Its `@param` text; empty when it has none. */
+    readonly description: string;
+    /** Whether it may be left out (a `?` or a default). */
+    readonly isOptional: boolean;
+    /** Whether it takes the rest of the arguments (`...values`). */
+    readonly isRest: boolean;
+};
+/** A hook's or a function's signature: what a story about logic documents first. */
+export type FunctionSignatureDocs = {
+    /** Its type parameters as written (`TValue`, `TUnit extends string`); empty when it has none. */
+    readonly typeParameters: readonly string[];
+    /** The parameters, in order. */
+    readonly parameters: readonly FunctionParameterDocs[];
+    /** The return type, as the source writes it. */
+    readonly returns: string;
+    /** Its `@returns` text; empty when it has none. */
+    readonly returnsDescription: string;
+};
+/**
+ * One member of a prop's object type (a `texts` prop's `FileFinderTexts`), listed under the prop in the API
+ * reference.
+ */
+export type MemberDocs = {
+    /** The member's name. */
+    readonly name: string;
+    /** Its type as the source writes it, without `undefined` and `null`. */
+    readonly type: string;
+    /** The first paragraph of its TSDoc; empty when it has none. */
+    readonly description: string;
+    /** Its `@defaultValue`, when the TSDoc gives one. */
+    readonly defaultValue?: string;
+    /** Whether the member must be given. */
+    readonly isRequired: boolean;
+};
 /** One prop of a component. */
 export type PropDocs = {
     /** The prop's name. */
@@ -53,6 +93,16 @@ export type PropDocs = {
      * field for it. Left out when `false`.
      */
     readonly canTakeText?: boolean;
+    /**
+     * The group its TSDoc puts it in (`@group Selection`): the API reference and the Props tab list it under that
+     * heading. Left out when it names none.
+     */
+    readonly group?: string;
+    /**
+     * The members of its type, when that type is an object the package declares and documents (`texts?: FileFinderTexts`),
+     * in the order the source declares them: the API reference lists them under the prop, folded. Left out otherwise.
+     */
+    readonly members?: readonly MemberDocs[];
 };
 /** A part the component is used with, named in the meta's `subcomponents`: listed under it on its page. */
 export type SubcomponentDocs = {
@@ -63,6 +113,22 @@ export type SubcomponentDocs = {
     /** Its props declared in the package, in the same order as the component's. */
     readonly props: readonly PropDocs[];
 };
+/**
+ * When to use a component and when not, as its TSDoc says: the rule a person knows and an agent has no way to guess.
+ * Tags: `@useWhen`, `@avoidWhen`, `@alternatives`, `@deprecated`, `@replacedBy`.
+ */
+export type UsageGuidance = {
+    /** The situations it is for, one per `@useWhen`. */
+    readonly useWhen?: readonly string[];
+    /** The situations it is not for, one per `@avoidWhen`. */
+    readonly avoidWhen?: readonly string[];
+    /** Components to consider instead, from `@alternatives`, comma-separated. */
+    readonly alternatives?: readonly string[];
+    /** Why not to use it any more, from `@deprecated`. */
+    readonly deprecated?: string;
+    /** What to use instead, from `@replacedBy`. */
+    readonly replacedBy?: string;
+};
 /** A story file's component. */
 export type ComponentDocs = {
     /** The component's name. */
@@ -83,7 +149,27 @@ export type ComponentDocs = {
     readonly parts: readonly string[];
     /** The parts the meta names in `subcomponents`, in the order it writes them; empty when it names none. */
     readonly subcomponents: readonly SubcomponentDocs[];
+    /** When to use it and when not, from its TSDoc; left out when it says nothing. */
+    readonly guidance?: UsageGuidance;
+    /**
+     * Its call signature, when it has one: the parameters and the return value a story about logic shows first (the
+     * meta's `component` is then the hook or the function).
+     */
+    readonly signature?: FunctionSignatureDocs;
+    /**
+     * The CSS selector a template writes the component with, for a framework whose components are matched by one rather
+     * than named (an Angular component's `fb-badge`, a directive's `button[fbButton]`): the code writer writes the story's
+     * markup from it. Left out when the component is written by its name.
+     */
+    readonly selector?: string;
 };
+/**
+ * The name a story's code writes the component with: its selector when its framework matches components by one, its
+ * name otherwise.
+ *
+ * @param docs - the component's docs.
+ */
+export declare const codeNameOf: (docs: ComponentDocs) => string;
 /** What the plugin answers for a story file whose meta names no component (a foundations page). */
 export type NoComponentDocs = {
     /** No component. */
@@ -95,4 +181,3 @@ export type NoComponentDocs = {
  * @param value - the module's default export.
  */
 export declare const isComponentDocs: (value: unknown) => value is ComponentDocs;
-//# sourceMappingURL=componentDocs.d.ts.map

package/dist/src/componentDocs.js

@@ -10,12 +10,26 @@
  *
  * @module
  */
+/**
+ * The name a story's code writes the component with: its selector when its framework matches components by one, its
+ * name otherwise.
+ *
+ * @param docs - the component's docs.
+ */
+export const codeNameOf = (docs) => docs.selector ?? docs.name;
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Whether a value is a list of strings. */
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 /** The prop kinds, for the check. */
 const PROP_KINDS = ["choice", "text", "number", "toggle", "event", "other"];
+/** Whether a value is one member's docs. */
+const isMemberDocs = (value) => isRecord(value) &&
+    typeof value["name"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["description"] === "string" &&
+    typeof value["isRequired"] === "boolean" &&
+    (value["defaultValue"] === undefined || typeof value["defaultValue"] === "string");
 /** Whether a value is one prop's docs. */
 const isPropDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -23,13 +37,28 @@ const isPropDocs = (value) => isRecord(value) &&
     typeof value["type"] === "string" &&
     typeof value["description"] === "string" &&
     typeof value["isRequired"] === "boolean" &&
-    (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean");
+    (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean") &&
+    (value["group"] === undefined || typeof value["group"] === "string") &&
+    (value["members"] === undefined ||
+        (Array.isArray(value["members"]) && value["members"].every(isMemberDocs)));
 /** Whether a value is a subcomponent's docs. */
 const isSubcomponentDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
     typeof value["description"] === "string" &&
     Array.isArray(value["props"]) &&
     value["props"].every(isPropDocs);
+/** Whether a value is a signature's docs. */
+const isFunctionSignatureDocs = (value) => isRecord(value) &&
+    typeof value["returns"] === "string" &&
+    typeof value["returnsDescription"] === "string" &&
+    isStringList(value["typeParameters"]) &&
+    Array.isArray(value["parameters"]) &&
+    value["parameters"].every((parameter) => isRecord(parameter) &&
+        typeof parameter["name"] === "string" &&
+        typeof parameter["type"] === "string" &&
+        typeof parameter["description"] === "string" &&
+        typeof parameter["isOptional"] === "boolean" &&
+        typeof parameter["isRest"] === "boolean");
 /**
  * Whether a value received from the plugin is a component's docs.
  *
@@ -43,5 +72,6 @@ export const isComponentDocs = (value) => isRecord(value) &&
     value["props"].every(isPropDocs) &&
     isStringList(value["parts"]) &&
     Array.isArray(value["subcomponents"]) &&
-    value["subcomponents"].every(isSubcomponentDocs);
-//# sourceMappingURL=componentDocs.js.map
+    value["subcomponents"].every(isSubcomponentDocs) &&
+    (value["signature"] === undefined || isFunctionSignatureDocs(value["signature"])) &&
+    (value["selector"] === undefined || typeof value["selector"] === "string");

package/dist/src/controlKeys.d.ts

@@ -82,4 +82,3 @@ export declare const cycledValue: <TValue>(values: readonly TValue[], current: T
  * @param each - the switch.
  */
 export declare const switchValues: (each: ViewSwitch) => string[];
-//# sourceMappingURL=controlKeys.d.ts.map

package/dist/src/controlKeys.js

@@ -3,7 +3,8 @@ export const DEFAULT_KEYS = {
     theme: "t",
     contrast: "c",
     lang: "l",
-    dir: "d"
+    dir: "d",
+    touch: "m"
 };
 /**
  * A key as the shell keeps it: one letter, lower case; none when the text is not one.
@@ -119,4 +120,3 @@ export const cycledValue = (values, current, step) => {
  * @param each - the switch.
  */
 export const switchValues = (each) => each.values.map((value) => value.value);
-//# sourceMappingURL=controlKeys.js.map

package/dist/src/deviceDrawing.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A device's drawing: the hardware around the screen (its band, its bezel, its buttons) and what sits over the story
+ * (the camera's cut, the status bar, the home indicator), as shapes in CSS px, for the shell's frame and for
+ * `forgebook shot`'s framed pictures to draw the same device.
+ *
+ * @remarks
+ * Shapes and not markup, so each side draws them its own way (React elements in the shell, an SVG text in the
+ * pictures) from one geometry. The hardware is laid out upright and turned with its top to the left for landscape,
+ * as a phone is turned; the status bar is laid out for the screen as held, since a system lays it out again when
+ * the phone turns (an iPhone on its side shows none). The paints are named, not coloured: the frame takes the
+ * shell's appearance, the status bar's ink the story's scheme, as a phone's status bar follows the app under it.
+ * Pure.
+ *
+ * @module
+ */
+import type { DeviceOrientation } from "@forgebook/story-format/csf";
+import { type DeviceModel } from "./devices.ts";
+/** What a shape is painted with: the hardware's band, its outline, the bezel, the camera's cut, the status bar's ink. */
+export type DevicePaint = "frame" | "edge" | "bezel" | "cutout" | "ink";
+/** One shape of a drawing, in CSS px. */
+export type DeviceShape = {
+    /** A rectangle, its corners rounded. */
+    readonly kind: "rect";
+    /** Its left. */
+    readonly x: number;
+    /** Its top. */
+    readonly y: number;
+    /** Its width. */
+    readonly width: number;
+    /** Its height. */
+    readonly height: number;
+    /** Its corners' radius. */
+    readonly radius: number;
+    /** Its fill; none for an outline only. */
+    readonly fill?: DevicePaint;
+    /** Its outline, 1 px wide; none by default. */
+    readonly stroke?: DevicePaint;
+    /** Its opacity, from 0 to 1; 1 by default. */
+    readonly opacity?: number;
+} | {
+    /** A disc. */
+    readonly kind: "circle";
+    /** Its centre's left. */
+    readonly cx: number;
+    /** Its centre's top. */
+    readonly cy: number;
+    /** Its radius. */
+    readonly r: number;
+    /** Its fill. */
+    readonly fill: DevicePaint;
+} | {
+    /** A path, in SVG's path syntax. */
+    readonly kind: "path";
+    /** Its commands. */
+    readonly d: string;
+    /** Its fill. */
+    readonly fill: DevicePaint;
+} | {
+    /** A line of text, centred on its height. */
+    readonly kind: "text";
+    /** Where it starts, or its middle. */
+    readonly x: number;
+    /** Its middle's height. */
+    readonly y: number;
+    /** What it says. */
+    readonly text: string;
+    /** Its size, in CSS px. */
+    readonly size: number;
+    /** Its weight. */
+    readonly weight: number;
+    /** Whether `x` is its start or its middle. */
+    readonly anchor: "start" | "middle";
+    /** Its fill. */
+    readonly fill: DevicePaint;
+};
+/** A rectangle, its corners rounded, in CSS px. */
+export type DeviceRect = {
+    /** Its left. */
+    readonly x: number;
+    /** Its top. */
+    readonly y: number;
+    /** Its width. */
+    readonly width: number;
+    /** Its height. */
+    readonly height: number;
+    /** Its corners' radius. */
+    readonly radius: number;
+};
+/** A device drawn: its size, where its screen is, and its shapes under and over the screen. */
+export type DeviceDrawing = {
+    /** The drawing's width, the buttons included, in CSS px. */
+    readonly width: number;
+    /** The drawing's height, in CSS px. */
+    readonly height: number;
+    /** The screen, where the story goes: its viewport's size, at its place in the drawing. */
+    readonly screen: DeviceRect;
+    /** Drawn under the screen: the buttons, the band and the bezel. */
+    readonly under: readonly DeviceShape[];
+    /** Drawn over the story, never taking the pointer: the camera's cut, the status bar, the home indicator. */
+    readonly over: readonly DeviceShape[];
+};
+/** The paints of the hardware in each of the shell's appearances: quiet greys, a black bezel, as phones are. */
+export declare const DEVICE_PAINTS: Readonly<Record<"light" | "dark", Readonly<Record<Exclude<DevicePaint, "ink">, string>>>>;
+/** The status bar's ink over a story of each scheme: dark on a light story, light on a dark one. */
+export declare const DEVICE_INK: Readonly<Record<"light" | "dark", string>>;
+/** The status bar's font: the system's, as the devices' own. */
+export declare const DEVICE_FONT = "-apple-system, BlinkMacSystemFont, \"SF Pro Text\", Roboto, system-ui, sans-serif";
+/**
+ * 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 declare const deviceDrawing: (model: DeviceModel, orientation: DeviceOrientation) => DeviceDrawing;

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)
+        ]
+    };
+};