reladraw 0.0.1 → 0.1.0

package/dist/ast.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The shape a source file parses into. Nothing here knows about geometry —
+ * these types are a faithful record of what the author wrote, and no more.
+ */
+export declare const DIRECTIONS: readonly ["above", "below", "left", "right", "above-left", "above-right", "below-left", "below-right"];
+export type Direction = (typeof DIRECTIONS)[number];
+export declare function isDirection(word: string): word is Direction;
+export type Axis = 'x' | 'y';
+/**
+ * Which edge of the target a `level with` shares. `centre` is the plain form;
+ * the rest are written in front of it, as in `top level with media`.
+ */
+export declare const EDGES: readonly ["centre", "top", "bottom", "left", "right"];
+export type Edge = (typeof EDGES)[number];
+/** An edge belongs to one axis, so an alignment never has to say which. */
+export declare const EDGE_AXIS: Record<Edge, Axis>;
+/**
+ * Naming more than one target places the node against the box that just bounds
+ * them all — `right of borg and bare` clears both. It is a single target that
+ * nobody had to declare, which is why it is a list on one placement rather than
+ * several placements: two separate `level with` statements are two demands that
+ * fight, while one naming two targets is a single demand about one region.
+ */
+export type Targets = string[];
+/**
+ * `right of docker` — the node sits a gap beyond one of the target's edges.
+ * A direction rules out part of an axis rather than fixing a point, which is
+ * what lets two of them bracket a node between two targets.
+ */
+export interface OffsetPlacement {
+    kind: 'offset';
+    direction: Direction;
+    targets: Targets;
+    /**
+     * The gap this one placement asks for, from `(gap: wide)` written after the
+     * targets. A gap describes a relationship rather than a box, so this is its
+     * proper home; `gap:` on the node remains the default for every placement
+     * that does not say. Absent means take the node's.
+     */
+    gap?: string;
+    line: number;
+}
+/** `level with docker` — share an edge or a centre line, with no gap in between. */
+export interface AlignPlacement {
+    kind: 'align';
+    axis: Axis;
+    edge: Edge;
+    targets: Targets;
+    line: number;
+}
+/**
+ * One thing the author said about where a node goes. A node carries as many as
+ * it needs; the resolver intersects them.
+ */
+export type Placement = OffsetPlacement | AlignPlacement;
+/**
+ * The modifiers a placement understands, in brackets after its targets. Refused
+ * by name when unrecognised, for the reason `DIAGRAM_KEYS` are: a modifier that
+ * silently does nothing looks like a bug in the tool rather than a typo.
+ */
+export declare const PLACEMENT_KEYS: readonly ["gap"];
+/** How a placement reads back in the author's own words, for error messages. */
+export declare function describePlacement(placement: Placement): string;
+/** "borg", "borg and bare", "borg, bare and media" — as the author would write them. */
+export declare function listTargets(targets: Targets): string;
+/**
+ * `between computer1 and computer2` on a link — the gap it passes through.
+ *
+ * This is not a claim about the whole line. It binds only the stretch where the
+ * line is actually passing the pair, and says nothing about where it goes
+ * before or after.
+ */
+export interface Passage {
+    /** Exactly two, because a gap has two sides. */
+    targets: Targets;
+    /**
+     * Which of the two gaps was meant, for a pair that is apart on both axes.
+     * Absent whenever the pair leaves only one possibility, which is most of the
+     * time — the word is a tie-break, not part of the statement.
+     */
+    axis?: Axis;
+}
+/** How the axis of a passage is written, and what it means. */
+export declare const PASSAGE_AXES: Record<string, Axis>;
+/** `vertically` or `horizontally`, from the axis it binds. */
+export declare function describeAxis(axis: Axis): string;
+/** `key: value` pairs trailing a statement. Values are always strings here. */
+export type Attrs = Record<string, string>;
+/**
+ * What a label's brackets may say: `"Docker" (at: bottom, align: centre)`.
+ *
+ * They are bracketed onto the label rather than written among the node's
+ * attributes for the same reason a gap is bracketed onto its placement — they
+ * modify that one thing, and the brackets make the scope visible instead of
+ * positional. `at` and `align` are independent: neither implies the other, and a
+ * label at the bottom is an ordinary label that happens to be at the bottom.
+ */
+export declare const LABEL_KEYS: readonly ["at", "align"];
+export interface BoxStmt {
+    kind: 'box';
+    name: string;
+    text: string;
+    /** The label's bracketed modifiers, as written. Usually empty. */
+    label: Attrs;
+    /** Everything the author said about where this goes. Empty for the anchor. */
+    placements: Placement[];
+    attrs: Attrs;
+    line: number;
+}
+export interface LinkStmt {
+    kind: 'link';
+    from: string;
+    to: string;
+    /** `<->` rather than `->`. */
+    both: boolean;
+    label?: string;
+    /** `between computer1 and computer2` — the gap the line passes through. */
+    between?: Passage;
+    attrs: Attrs;
+    line: number;
+}
+export interface NoteStmt {
+    kind: 'note';
+    name: string;
+    text: string;
+    /** Everything the author said about where this goes. Empty for the anchor. */
+    placements: Placement[];
+    attrs: Attrs;
+    line: number;
+}
+export interface DeckStmt {
+    kind: 'deck';
+    /** The container to draw with offset copies behind it. */
+    name: string;
+    /** One label per copy, back to front as written. */
+    labels: string[];
+    line: number;
+}
+/**
+ * `diagram background: #111111` — settings that belong to the drawing as a
+ * whole rather than to anything in it. It has no name because there is only
+ * ever one diagram per file.
+ */
+export interface DiagramStmt {
+    kind: 'diagram';
+    attrs: Attrs;
+    line: number;
+}
+/** The attributes a `diagram` statement understands. */
+export declare const DIAGRAM_KEYS: readonly ["background"];
+export interface StyleStmt {
+    kind: 'style';
+    name: string;
+    attrs: Attrs;
+    line: number;
+}
+export type Stmt = BoxStmt | LinkStmt | NoteStmt | DeckStmt | StyleStmt | DiagramStmt;
+export interface Document {
+    statements: Stmt[];
+}

package/dist/ast.js

@@ -0,0 +1,78 @@
+/**
+ * The shape a source file parses into. Nothing here knows about geometry —
+ * these types are a faithful record of what the author wrote, and no more.
+ */
+export const DIRECTIONS = [
+    'above',
+    'below',
+    'left',
+    'right',
+    'above-left',
+    'above-right',
+    'below-left',
+    'below-right',
+];
+export function isDirection(word) {
+    return DIRECTIONS.includes(word);
+}
+/**
+ * Which edge of the target a `level with` shares. `centre` is the plain form;
+ * the rest are written in front of it, as in `top level with media`.
+ */
+export const EDGES = ['centre', 'top', 'bottom', 'left', 'right'];
+/** An edge belongs to one axis, so an alignment never has to say which. */
+export const EDGE_AXIS = {
+    centre: 'y',
+    top: 'y',
+    bottom: 'y',
+    left: 'x',
+    right: 'x',
+};
+/**
+ * The modifiers a placement understands, in brackets after its targets. Refused
+ * by name when unrecognised, for the reason `DIAGRAM_KEYS` are: a modifier that
+ * silently does nothing looks like a bug in the tool rather than a typo.
+ */
+export const PLACEMENT_KEYS = ['gap'];
+/** How a placement reads back in the author's own words, for error messages. */
+export function describePlacement(placement) {
+    const targets = listTargets(placement.targets);
+    if (placement.kind === 'align') {
+        const edge = placement.edge === 'centre' ? '' : `${placement.edge} `;
+        return `${edge}level with ${targets}`;
+    }
+    // "left of X" and "above X" are both good English; "above of X" is not.
+    const joiner = placement.direction === 'above' || placement.direction === 'below' ? '' : 'of ';
+    const gap = placement.gap === undefined ? '' : ` (gap: ${placement.gap})`;
+    return `${placement.direction} ${joiner}${targets}${gap}`;
+}
+/** "borg", "borg and bare", "borg, bare and media" — as the author would write them. */
+export function listTargets(targets) {
+    if (targets.length <= 1)
+        return targets[0] ?? '';
+    return `${targets.slice(0, -1).join(', ')} and ${targets[targets.length - 1]}`;
+}
+/** How the axis of a passage is written, and what it means. */
+export const PASSAGE_AXES = {
+    // The gap you measure with a vertical ruler: one target above, one below. A
+    // line running along it therefore travels horizontally, which is the reading
+    // to watch out for — the word describes the gap, not the direction of travel.
+    vertically: 'y',
+    horizontally: 'x',
+};
+/** `vertically` or `horizontally`, from the axis it binds. */
+export function describeAxis(axis) {
+    return axis === 'y' ? 'vertically' : 'horizontally';
+}
+/**
+ * What a label's brackets may say: `"Docker" (at: bottom, align: centre)`.
+ *
+ * They are bracketed onto the label rather than written among the node's
+ * attributes for the same reason a gap is bracketed onto its placement — they
+ * modify that one thing, and the brackets make the scope visible instead of
+ * positional. `at` and `align` are independent: neither implies the other, and a
+ * label at the bottom is an ordinary label that happens to be at the bottom.
+ */
+export const LABEL_KEYS = ['at', 'align'];
+/** The attributes a `diagram` statement understands. */
+export const DIAGRAM_KEYS = ['background'];

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { SourceError } from './errors.js';
+import { compile } from './index.js';
+const USAGE = `reladraw — render a diagram from stated placement
+
+  reladraw <input.reladraw> [-o <output.svg>]
+
+  -o, --out   where to write the SVG. Defaults to the input path with
+              its extension replaced by .svg. Use - for standard output.
+  -h, --help  print this.
+`;
+async function main(argv) {
+    if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(USAGE);
+        return argv.length === 0 ? 1 : 0;
+    }
+    let input;
+    let out;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '-o' || arg === '--out') {
+            out = argv[i + 1];
+            if (out === undefined) {
+                process.stderr.write('reladraw: -o needs a path\n');
+                return 1;
+            }
+            i += 1;
+        }
+        else if (arg.startsWith('-') && arg !== '-') {
+            process.stderr.write(`reladraw: unknown option ${arg}\n`);
+            return 1;
+        }
+        else if (input === undefined) {
+            input = arg;
+        }
+        else {
+            process.stderr.write(`reladraw: unexpected argument ${arg}\n`);
+            return 1;
+        }
+    }
+    if (input === undefined) {
+        process.stderr.write('reladraw: no input file\n');
+        return 1;
+    }
+    const source = await readFile(input, 'utf8');
+    let svg;
+    try {
+        svg = compile(source);
+    }
+    catch (error) {
+        if (error instanceof SourceError) {
+            process.stderr.write(`${error.format(input)}\n`);
+            return 1;
+        }
+        throw error;
+    }
+    if (out === '-') {
+        process.stdout.write(svg);
+        return 0;
+    }
+    const target = resolvePath(out ?? input.replace(/\.[^.]+$/, '') + '.svg');
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, svg, 'utf8');
+    process.stderr.write(`${target}\n`);
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+    process.stderr.write(`reladraw: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/constants.d.ts

@@ -0,0 +1,142 @@
+/** Spacing and text sizes shared by the resolver and the renderer, so the two cannot drift. */
+import type { Attrs } from './ast.js';
+import type { Measurer } from './measure.js';
+/** Inside a box, between its border and its contents. */
+export declare const PAD = 14;
+/** Between stacked children of one container. */
+export declare const CHILD_GAP = 10;
+/** Between a container's own label and its first child. */
+export declare const HEADER_GAP = 10;
+/**
+ * How far each deck copy is offset behind the front face. It has to clear a
+ * whole line of text plus the padding above it, or a copy's label is drawn and
+ * then immediately covered by the copy in front of it.
+ */
+export declare const DECK_STEP = 34;
+/**
+ * The named gaps a placement may ask for, each a *minimum* distance rather than a
+ * fixed one. Anything the author puts between two things widens the space
+ * between them on its own, so no gap here ever has to be chosen large enough
+ * to leave room for something else.
+ */
+export declare const GAPS: Record<string, number>;
+/**
+ * How far apart two boxes are pushed when they would otherwise overlap. Small
+ * on purpose: this is the tool enforcing something the author did not write, so
+ * the space it leaves should read as "these are not the same box" and never as
+ * a relationship someone stated. Say `gap:` if you want breathing room.
+ */
+export declare const SEPARATION_GAP: number;
+/**
+ * Between two links meeting the same side of the same box. An author names a
+ * side, never a point on it, so this is the tool keeping two attachments apart
+ * rather than a distance anyone asked for — small, like `SEPARATION_GAP`, and
+ * squeezed further if the side is too short to hold the whole group.
+ */
+export declare const ATTACH_STEP = 16;
+/** Kept clear at each end of a side, so an attachment never sits on a corner. */
+export declare const ATTACH_MARGIN = 10;
+/** How wide a link's line is drawn. */
+export declare const LINE_WIDTH = 1.6;
+/**
+ * The arrowhead's length, in the `markerUnits="strokeWidth"` the marker is
+ * declared in, so its drawn length is this times `LINE_WIDTH`.
+ */
+export declare const ARROW_MARKER_WIDTH = 7;
+/**
+ * How much of the line an arrowhead covers. Derived rather than written down,
+ * because the resolver reserves it and the renderer draws it, and a number
+ * agreed by coincidence is a number that drifts.
+ */
+export declare const ARROW_LENGTH: number;
+/**
+ * Line left showing between a link's label and the box at that end of the
+ * corridor it crosses.
+ *
+ * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
+ * Those two keep two things from touching, and the least distance that reads as
+ * "not touching" is the right one. This one has something to show: a label sits
+ * in a knockout that erases the line behind it, so whatever is left either side
+ * is the entire evidence that the label belongs to a link at all. At ten pixels
+ * it did not read as a line — the seed diagram in the playground drew as a word
+ * with a dash beside it — so it is the length of a run of line, not a margin.
+ *
+ * Say `gap:` if you want the corridor wider than its contents.
+ */
+export declare const LABEL_CLEARANCE = 20;
+/**
+ * How much room a link's label takes along one axis.
+ *
+ * The knockout rectangle drawn behind a label is the text plus five either side,
+ * so that rectangle, not the glyphs, is what must not overlap anything.
+ *
+ * Shared by the resolver, which widens a corridor to hold a label, and the
+ * renderer, which spaces the lanes of a channel by it, so the two cannot
+ * disagree about how much room a label needs. The two ask different questions of
+ * it and both are right: the resolver measures *along* the run, so a link
+ * travelling horizontally needs the label's width; the renderer measures *across*
+ * the channel, so a link travelling horizontally down one needs its height.
+ */
+export declare function labelExtent(label: string, appearance: Attrs, axis: 'x' | 'y', measurer: Measurer, fontSize: number, line: number): number;
+/**
+ * An icon is two lines of the label tall, and that ratio is what makes it a
+ * *label-sized* ornament rather than a picture with a size of its own. It is
+ * read off the reference, where the title lines run 25 pixels baseline to
+ * baseline and the drive and machine glyphs are close to 50 tall. Deriving it
+ * from the text also means an icon on a `size: small` node shrinks with it,
+ * which is what anyone would expect and what a fixed pixel count would not do.
+ */
+export declare const ICON_LINES = 2;
+/** Between the label column and the icon column beside it. */
+export declare const ICON_GAP = 10;
+export declare const DEFAULT_FONT_SIZE = 14;
+/**
+ * The named text sizes, each a multiple of the document's own size. Named
+ * rather than numeric for the reason gaps are: a number here is typography by
+ * coordinate. It goes stale the moment the document is set at another size, and
+ * it says nothing about why one piece of text is smaller than another.
+ *
+ * `small` is sampled rather than chosen. In
+ * `examples/reference/arch.png` the box and container labels run 25
+ * pixels baseline to baseline and every annotation runs 21, which is this
+ * ratio; `./dev.sh textrows` is how that was read off. `large` is the same step
+ * taken the other way, so the scale is symmetric about the document size.
+ */
+export declare const TEXT_SIZES: Record<string, number>;
+/**
+ * The size a piece of text is set at. Shared by the resolver, which reserves
+ * the room, and the renderer, which fills it, so the two cannot disagree about
+ * how much room there is.
+ */
+export declare function fontSizeFor(kind: string, appearance: Attrs, fontSize: number, line: number): number;
+export declare const DEFAULT_MARGIN = 40;
+/**
+ * Where a container's own label sits. Every container reserves a band for its
+ * label and its icon; `at` says which end of the box that band is, and the
+ * contents take what is left. `align` says how the text sits across it.
+ *
+ * The two are independent and neither implies the other. A label at the bottom
+ * is an ordinary label that happens to be at the bottom — there is no kind of
+ * label being named here and no second thing quietly coming along with the
+ * first. An earlier version bundled them as `label: heading | caption`, which
+ * read a position as though it were a meaning; a folded corner means "artifact
+ * rather than process" and a reader decodes it, while "lower down" means only
+ * lower down.
+ *
+ * A leaf has no band — its label is centred in the box — so neither says
+ * anything about one.
+ */
+export declare const LABEL_ENDS: readonly ["top", "bottom"];
+export type LabelEnd = (typeof LABEL_ENDS)[number];
+export interface LabelStyle {
+    /** Which end of the box the band sits at. */
+    at: LabelEnd;
+    /** How the text sits in the band, in the renderer's own vocabulary. */
+    align: 'start' | 'middle' | 'end';
+}
+/**
+ * Read a label's bracketed modifiers. Shared by the resolver, which offsets the
+ * contents away from the band, and the renderer, which draws into it, so the two
+ * cannot disagree about which end the band is at.
+ */
+export declare function labelStyleFor(label: Attrs, line: number): LabelStyle;

package/dist/constants.js

@@ -0,0 +1,187 @@
+import { SourceError } from './errors.js';
+/** Inside a box, between its border and its contents. */
+export const PAD = 14;
+/** Between stacked children of one container. */
+export const CHILD_GAP = 10;
+/** Between a container's own label and its first child. */
+export const HEADER_GAP = 10;
+/**
+ * How far each deck copy is offset behind the front face. It has to clear a
+ * whole line of text plus the padding above it, or a copy's label is drawn and
+ * then immediately covered by the copy in front of it.
+ */
+export const DECK_STEP = 34;
+/**
+ * The named gaps a placement may ask for, each a *minimum* distance rather than a
+ * fixed one. Anything the author puts between two things widens the space
+ * between them on its own, so no gap here ever has to be chosen large enough
+ * to leave room for something else.
+ */
+export const GAPS = {
+    // A zero gap turns an offset into edge-to-edge contact, so "my top edge
+    // against Docker's bottom edge" needs no vocabulary of its own.
+    none: 0,
+    tight: 24,
+    normal: 56,
+    wide: 110,
+};
+/**
+ * How far apart two boxes are pushed when they would otherwise overlap. Small
+ * on purpose: this is the tool enforcing something the author did not write, so
+ * the space it leaves should read as "these are not the same box" and never as
+ * a relationship someone stated. Say `gap:` if you want breathing room.
+ */
+export const SEPARATION_GAP = GAPS['tight'];
+/**
+ * Between two links meeting the same side of the same box. An author names a
+ * side, never a point on it, so this is the tool keeping two attachments apart
+ * rather than a distance anyone asked for — small, like `SEPARATION_GAP`, and
+ * squeezed further if the side is too short to hold the whole group.
+ */
+export const ATTACH_STEP = 16;
+/** Kept clear at each end of a side, so an attachment never sits on a corner. */
+export const ATTACH_MARGIN = 10;
+/** How wide a link's line is drawn. */
+export const LINE_WIDTH = 1.6;
+/**
+ * The arrowhead's length, in the `markerUnits="strokeWidth"` the marker is
+ * declared in, so its drawn length is this times `LINE_WIDTH`.
+ */
+export const ARROW_MARKER_WIDTH = 7;
+/**
+ * How much of the line an arrowhead covers. Derived rather than written down,
+ * because the resolver reserves it and the renderer draws it, and a number
+ * agreed by coincidence is a number that drifts.
+ */
+export const ARROW_LENGTH = ARROW_MARKER_WIDTH * LINE_WIDTH;
+/**
+ * Line left showing between a link's label and the box at that end of the
+ * corridor it crosses.
+ *
+ * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
+ * Those two keep two things from touching, and the least distance that reads as
+ * "not touching" is the right one. This one has something to show: a label sits
+ * in a knockout that erases the line behind it, so whatever is left either side
+ * is the entire evidence that the label belongs to a link at all. At ten pixels
+ * it did not read as a line — the seed diagram in the playground drew as a word
+ * with a dash beside it — so it is the length of a run of line, not a margin.
+ *
+ * Say `gap:` if you want the corridor wider than its contents.
+ */
+export const LABEL_CLEARANCE = 20;
+/**
+ * How much room a link's label takes along one axis.
+ *
+ * The knockout rectangle drawn behind a label is the text plus five either side,
+ * so that rectangle, not the glyphs, is what must not overlap anything.
+ *
+ * Shared by the resolver, which widens a corridor to hold a label, and the
+ * renderer, which spaces the lanes of a channel by it, so the two cannot
+ * disagree about how much room a label needs. The two ask different questions of
+ * it and both are right: the resolver measures *along* the run, so a link
+ * travelling horizontally needs the label's width; the renderer measures *across*
+ * the channel, so a link travelling horizontally down one needs its height.
+ */
+export function labelExtent(label, appearance, axis, measurer, fontSize, line) {
+    const size = fontSizeFor('link', appearance, fontSize, line);
+    const { width, lines } = measurer.measure(label, size);
+    return axis === 'x' ? width + 10 : lines.length * measurer.lineHeight(size);
+}
+/**
+ * An icon is two lines of the label tall, and that ratio is what makes it a
+ * *label-sized* ornament rather than a picture with a size of its own. It is
+ * read off the reference, where the title lines run 25 pixels baseline to
+ * baseline and the drive and machine glyphs are close to 50 tall. Deriving it
+ * from the text also means an icon on a `size: small` node shrinks with it,
+ * which is what anyone would expect and what a fixed pixel count would not do.
+ */
+export const ICON_LINES = 2;
+/** Between the label column and the icon column beside it. */
+export const ICON_GAP = 10;
+export const DEFAULT_FONT_SIZE = 14;
+/**
+ * The named text sizes, each a multiple of the document's own size. Named
+ * rather than numeric for the reason gaps are: a number here is typography by
+ * coordinate. It goes stale the moment the document is set at another size, and
+ * it says nothing about why one piece of text is smaller than another.
+ *
+ * `small` is sampled rather than chosen. In
+ * `examples/reference/arch.png` the box and container labels run 25
+ * pixels baseline to baseline and every annotation runs 21, which is this
+ * ratio; `./dev.sh textrows` is how that was read off. `large` is the same step
+ * taken the other way, so the scale is symmetric about the document size.
+ */
+export const TEXT_SIZES = {
+    small: 21 / 25,
+    normal: 1,
+    large: 25 / 21,
+};
+/**
+ * What each kind of text is set at when the file says nothing. A note annotates
+ * the diagram rather than being part of it, and at the size of a box label an
+ * aside reads as a statement — so `note` starts small and says so by being a
+ * note. This is a default and not a ceiling: `size:` overrides it, the same way
+ * `fill:` overrides the theme's colour.
+ */
+const DEFAULT_TEXT_SIZE = { note: 'small' };
+/**
+ * The size a piece of text is set at. Shared by the resolver, which reserves
+ * the room, and the renderer, which fills it, so the two cannot disagree about
+ * how much room there is.
+ */
+export function fontSizeFor(kind, appearance, fontSize, line) {
+    const named = appearance['size'] ?? DEFAULT_TEXT_SIZE[kind] ?? 'normal';
+    const scale = TEXT_SIZES[named];
+    if (scale === undefined) {
+        throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')}, not "${named}"`, line);
+    }
+    return Math.round(fontSize * scale);
+}
+export const DEFAULT_MARGIN = 40;
+/**
+ * Where a container's own label sits. Every container reserves a band for its
+ * label and its icon; `at` says which end of the box that band is, and the
+ * contents take what is left. `align` says how the text sits across it.
+ *
+ * The two are independent and neither implies the other. A label at the bottom
+ * is an ordinary label that happens to be at the bottom — there is no kind of
+ * label being named here and no second thing quietly coming along with the
+ * first. An earlier version bundled them as `label: heading | caption`, which
+ * read a position as though it were a meaning; a folded corner means "artifact
+ * rather than process" and a reader decodes it, while "lower down" means only
+ * lower down.
+ *
+ * A leaf has no band — its label is centred in the box — so neither says
+ * anything about one.
+ */
+export const LABEL_ENDS = ['top', 'bottom'];
+/**
+ * Author's word to the SVG's. Both spellings of the middle one are taken: this
+ * is a vocabulary an author types from memory, and being right about the
+ * arrangement and wrong about a dialect is not a mistake worth an error.
+ */
+const LABEL_ALIGNMENTS = {
+    left: 'start',
+    centre: 'middle',
+    center: 'middle',
+    right: 'end',
+};
+/**
+ * Read a label's bracketed modifiers. Shared by the resolver, which offsets the
+ * contents away from the band, and the renderer, which draws into it, so the two
+ * cannot disagree about which end the band is at.
+ */
+export function labelStyleFor(label, line) {
+    const at = label['at'];
+    if (at !== undefined && !LABEL_ENDS.includes(at)) {
+        throw new SourceError(`a label's at takes ${LABEL_ENDS.join(' or ')}, not "${at}"`, line);
+    }
+    const align = label['align'];
+    if (align !== undefined && LABEL_ALIGNMENTS[align] === undefined) {
+        throw new SourceError(`a label's align takes left, centre or right, not "${align}"`, line);
+    }
+    return {
+        at: at ?? 'top',
+        align: align === undefined ? 'start' : LABEL_ALIGNMENTS[align],
+    };
+}