npm - reladraw - Versions diffs - 0.20.0 → 0.22.0 - Mend

reladraw 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/.claude/skills/reladraw/SKILL.md +188 -0
package/.claude/skills/reladraw/reference/syntax.md +1602 -0
package/README.md +8 -6
package/SYNTAX.md +40 -4
package/dist/ast.d.ts +9 -2
package/dist/ast.js +9 -2
package/dist/cli.js +71 -13
package/dist/constants.d.ts +4 -0
package/dist/constants.js +8 -0
package/dist/model.d.ts +13 -0
package/dist/model.js +7 -0
package/dist/page.d.ts +14 -0
package/dist/page.js +412 -0
package/dist/parser.js +21 -3
package/dist/place.d.ts +19 -0
package/dist/place.js +67 -8
package/dist/render.d.ts +17 -0
package/dist/render.js +101 -29
package/dist/resolve.d.ts +14 -0
package/dist/resolve.js +33 -7
package/dist/themes.d.ts +1 -0
package/dist/themes.js +1 -1
package/dist/viewer.d.ts +16 -0
package/dist/viewer.js +185 -0
package/package.json +2 -1

package/dist/page.js ADDED Viewed

@@ -0,0 +1,412 @@
+import { fileChecks, findings } from './checks.js';
+import { SourceError } from './errors.js';
+import { blame, parse } from './parser.js';
+import { renderTagged, themeOf } from './render.js';
+import { resolve } from './resolve.js';
+import { luminance } from './themes.js';
+import { PAN_ZOOM } from './viewer.js';
+/**
+ * `reladraw render --page`: one diagram in one self-contained HTML page, made
+ * for looking at rather than embedding. The page is the diagram's own colors,
+ * headed with its title, and it pans, zooms, goes full screen, saves the SVG
+ * or a PNG, lists the findings, and names a box under the pointer. It needs
+ * nothing running and fetches nothing, so it can be attached, mailed or
+ * committed. `name` is the file's name, the title when the file states none.
+ */
+export function drawPage(source, name, options = {}) {
+    const run = (text) => {
+        const layout = resolve(parse(text), options);
+        const { svg, tagged } = renderTagged(layout, options);
+        const found = options.checks === false ? [] : findings(layout, options.checks ? options.checks(fileChecks(layout)) : fileChecks(layout));
+        const title = layout.diagram['title'] ?? name;
+        return { html: page({ title, name, svg, tagged, findings: found, theme: themeOf(layout, options) }), findings: found };
+    };
+    try {
+        return run(source);
+    }
+    catch (error) {
+        throw error instanceof SourceError ? blame(source, error, run) : error;
+    }
+}
+function page({ title, name, svg, tagged, findings, theme }) {
+    const hex = (color) => /^#[0-9a-f]{6}$/i.test(color);
+    // The browser's own controls (scroll bars, focus rings) follow the page, so
+    // a dark diagram doesn't get a light one's. A color written by hand in a
+    // form that can't be measured leaves the choice to the browser.
+    const scheme = hex(theme.text) && hex(theme.background) ? (luminance(theme.text) > luminance(theme.background) ? 'dark' : 'light') : 'light dark';
+    const data = {
+        svg,
+        name,
+        findings: findings.map((finding) => ({ kind: finding.kind, message: finding.message, line: finding.line })),
+    };
+    // Replaced by functions, so a `$` in a title or a drawing is taken as written.
+    // The zoom's code goes in first, so nothing a diagram says can be taken for its marker.
+    return PAGE.replace('{{panzoom}}', () => PAN_ZOOM)
+        .replace('{{scheme}}', () => scheme)
+        .replace('{{title}}', () => escapeHtml(title))
+        .replace('{{heading}}', () => escapeHtml(title))
+        .replace('{{colors}}', () => [
+        `--page: ${theme.background};`,
+        `--ink: ${theme.text};`,
+        `--muted: ${theme.mutedText};`,
+        `--rule: ${theme.boxStroke};`,
+        `--accent: ${theme.primary.color};`,
+        `--on-accent: ${theme.primary.on};`,
+    ].join(' '))
+        .replace('{{drawing}}', () => tagged)
+        .replace('{{data}}', () => scriptJson(data));
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** JSON that can sit inside a `<script>` without ending it. */
+function scriptJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c');
+}
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="{{scheme}}">
+<meta name="generator" content="reladraw">
+<title>{{title}}</title>
+<style>
+  :root { {{colors}} }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; height: 100%; }
+  body {
+    display: flex; flex-direction: column; height: 100vh; height: 100dvh;
+    background: var(--page); color: var(--ink);
+    font: 14px/1.4 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  }
+  header {
+    display: flex; flex-wrap: wrap; align-items: center; gap: 8px 16px;
+    padding: 10px 16px;
+    border-bottom: 1px solid color-mix(in srgb, var(--rule) 45%, transparent);
+  }
+  h1 { flex: 1 1 16rem; margin: 0; font-size: 16px; font-weight: 600; overflow-wrap: anywhere; }
+  .tools { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
+  .tools .gap { width: 8px; }
+  button {
+    font: inherit; font-size: 13px; color: var(--ink); background: transparent;
+    border: 1px solid color-mix(in srgb, var(--rule) 70%, transparent); border-radius: 6px;
+    padding: 4px 10px; cursor: pointer; white-space: nowrap;
+  }
+  button:hover { background: color-mix(in srgb, var(--ink) 10%, transparent); }
+  button:disabled { opacity: 0.45; cursor: default; background: transparent; }
+  button[aria-pressed="true"] { background: color-mix(in srgb, var(--accent) 25%, transparent); border-color: var(--accent); }
+  button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+  .menu { position: relative; }
+  .menu-list {
+    position: absolute; right: 0; top: calc(100% + 4px); z-index: 5;
+    flex-direction: column; gap: 4px; padding: 6px;
+    background: var(--page); border: 1px solid color-mix(in srgb, var(--rule) 70%, transparent); border-radius: 6px;
+  }
+  .menu-list:not([hidden]) { display: flex; }
+  #scale .fitted { color: var(--accent); }
+  #scale { min-width: 6em; text-align: center; color: var(--muted); font-variant-numeric: tabular-nums; font-size: 13px; }
+  main { position: relative; flex: 1; display: flex; min-height: 0; }
+  #view { position: relative; flex: 1; overflow: hidden; touch-action: none; cursor: grab; }
+  #view.dragging { cursor: grabbing; }
+  #stage { position: absolute; left: 0; top: 0; transform-origin: 0 0; }
+  #stage svg { display: block; }
+  #view g[data-name].hover { filter: drop-shadow(0 0 3px var(--accent)); }
+  #view g[data-name].lit { filter: drop-shadow(0 0 2px var(--accent)) drop-shadow(0 0 6px var(--accent)); animation: lit 0.6s ease-in-out 3 alternate; }
+  @keyframes lit { from { opacity: 1; } to { opacity: 0.45; } }
+  #tip {
+    position: absolute; pointer-events: none; display: none; z-index: 2;
+    padding: 2px 8px; border-radius: 4px; font-size: 12px; white-space: nowrap;
+    background: var(--accent); color: var(--on-accent);
+  }
+  aside {
+    width: min(26rem, 38vw); display: flex; flex-direction: column; min-height: 0;
+    border-left: 1px solid color-mix(in srgb, var(--rule) 45%, transparent);
+  }
+  aside[hidden] { display: none; }
+  aside h2 { margin: 0; padding: 10px 16px 6px; font-size: 13px; font-weight: 600; }
+  aside h2 .what { display: block; font-weight: 400; font-size: 12px; color: var(--muted); }
+  aside ol { list-style: none; margin: 0; padding: 0 8px 12px; overflow: auto; }
+  aside li button {
+    display: block; width: 100%; text-align: left; white-space: normal; border-color: transparent;
+    padding: 6px 8px; margin: 2px 0;
+  }
+  aside li button.chosen { border-color: var(--accent); }
+  .where { color: var(--muted); font-variant-numeric: tabular-nums; }
+  .kind { color: var(--accent); }
+  .note { display: block; color: var(--muted); font-size: 12px; margin-top: 2px; }
+  @media (max-width: 700px) {
+    main { flex-direction: column; }
+    aside { width: auto; max-height: 40%; border-left: 0; border-top: 1px solid color-mix(in srgb, var(--rule) 45%, transparent); }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>{{heading}}</h1>
+  <div class="tools">
+    <button id="out" type="button" title="Zoom out (-)" aria-label="Zoom out">−</button>
+    <span id="scale" aria-live="polite">100%</span>
+    <button id="in" type="button" title="Zoom in (+)" aria-label="Zoom in">+</button>
+    <button id="fit" type="button" title="The whole diagram in view (0)">Fit</button>
+    <button id="actual" type="button" title="The drawing at its own scale (1)">100%</button>
+    <span class="gap"></span>
+    <button id="full" type="button" title="Full screen (f)">Full screen</button>
+    <span class="menu">
+      <button id="export" type="button" aria-haspopup="true" aria-expanded="false" aria-controls="export-list">Export ▾</button>
+      <span id="export-list" class="menu-list" hidden>
+        <button id="copy-svg" type="button">Copy SVG</button>
+        <button id="save-svg" type="button" title="Save the picture as an SVG file">Save SVG</button>
+        <button id="save-png" type="button" title="Save the picture as a PNG, at twice its size">Save PNG</button>
+      </span>
+    </span>
+    <button id="toggle-findings" type="button" aria-controls="findings"></button>
+  </div>
+</header>
+<main>
+  <div id="view">
+    <div id="stage">
+{{drawing}}
+    </div>
+    <div id="tip"></div>
+  </div>
+  <aside id="findings" aria-label="Findings">
+    <h2>Findings <span class="what">where the picture, drawn as written, may not read as meant</span></h2>
+    <ol id="finding-list"></ol>
+  </aside>
+</main>
+<script>
+(function () {
+  var DATA = {{data}};
+  var view = document.getElementById('view');
+  var stage = document.getElementById('stage');
+  var svg = stage.querySelector('svg');
+  var tip = document.getElementById('tip');
+  var scaleLabel = document.getElementById('scale');
+{{panzoom}}
+  var zoom = panZoom(view, stage, scaleLabel, {
+    out: document.getElementById('out'),
+    in: document.getElementById('in'),
+    fit: document.getElementById('fit'),
+    actual: document.getElementById('actual'),
+  });
+  /* ---- full screen ---- */
+  var full = document.getElementById('full');
+  if (!document.fullscreenEnabled) full.hidden = true;
+  function toggleFull() {
+    if (document.fullscreenElement) document.exitFullscreen();
+    else document.documentElement.requestFullscreen();
+  }
+  full.onclick = toggleFull;
+  document.addEventListener('fullscreenchange', function () {
+    full.textContent = document.fullscreenElement ? 'Exit full screen' : 'Full screen';
+  });
+  /* ---- saving ---- */
+  function saveBlob(blob, name) {
+    var url = URL.createObjectURL(blob);
+    var link = document.createElement('a');
+    link.href = url;
+    link.download = name;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    // A tick, so the navigation has the URL before it is taken back.
+    setTimeout(function () { URL.revokeObjectURL(url); }, 0);
+  }
+  function flash(button, text) {
+    var was = button.textContent;
+    button.textContent = text;
+    setTimeout(function () { button.textContent = was; }, 1200);
+  }
+  // Copy SVG, Save SVG and Save PNG are under one Export button, as in the
+  // playground. The list stays open after a choice, so "Copied" can be read,
+  // and closes on a click elsewhere or Escape.
+  var exportButton = document.getElementById('export');
+  var exportList = document.getElementById('export-list');
+  function showExport(open) {
+    exportList.hidden = !open;
+    exportButton.setAttribute('aria-expanded', String(open));
+  }
+  exportButton.onclick = function () { showExport(exportList.hidden); };
+  document.addEventListener('click', function (event) {
+    if (!exportList.hidden && !event.target.closest('.menu')) showExport(false);
+  });
+  // The clipboard API needs a secure context; a page opened from disk may
+  // not count as one, so the old selection route is the fallback.
+  var copySvg = document.getElementById('copy-svg');
+  copySvg.onclick = function () {
+    function fallback() {
+      var area = document.createElement('textarea');
+      area.value = DATA.svg;
+      document.body.appendChild(area);
+      area.select();
+      var done = false;
+      try { done = document.execCommand('copy'); } catch (e) {}
+      area.remove();
+      flash(copySvg, done ? 'Copied' : 'Blocked');
+    }
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(DATA.svg).then(function () { flash(copySvg, 'Copied'); }, fallback);
+    } else fallback();
+  };
+  document.getElementById('save-svg').onclick = function () {
+    saveBlob(new Blob([DATA.svg], { type: 'image/svg+xml' }), DATA.name + '.svg');
+  };
+  // The browser draws the SVG onto a canvas with the fonts the page shows it
+  // in, twice the size so it stays sharp on a high-density screen. A data URL
+  // rather than a blob one, which some browsers count as foreign and refuse
+  // to let the canvas be read back.
+  var savePng = document.getElementById('save-png');
+  savePng.onclick = function () {
+    var image = new Image();
+    image.onload = function () {
+      var box = svg.viewBox.baseVal;
+      var canvas = document.createElement('canvas');
+      canvas.width = box.width * 2;
+      canvas.height = box.height * 2;
+      canvas.getContext('2d').drawImage(image, 0, 0, canvas.width, canvas.height);
+      canvas.toBlob(function (blob) {
+        blob ? saveBlob(blob, DATA.name + '.png') : flash(savePng, 'Failed');
+      }, 'image/png');
+    };
+    image.onerror = function () { flash(savePng, 'Failed'); };
+    image.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(DATA.svg);
+  };
+  /* ---- a thing's name under the pointer ---- */
+  var hovered = null;
+  view.addEventListener('pointerover', function (event) {
+    var group = event.target.closest && event.target.closest('g[data-name]');
+    if (group === hovered) return;
+    if (hovered) hovered.classList.remove('hover');
+    hovered = group;
+    if (!group) {
+      tip.style.display = 'none';
+      return;
+    }
+    group.classList.add('hover');
+    tip.textContent = group.getAttribute('data-name');
+    tip.style.display = 'block';
+  });
+  view.addEventListener('pointermove', function (event) {
+    if (!hovered) return;
+    var rect = view.getBoundingClientRect();
+    var x = event.clientX - rect.left + 14;
+    var y = event.clientY - rect.top + 16;
+    // Kept inside the view, so a name near the right edge isn't cut off.
+    x = Math.min(x, rect.width - tip.offsetWidth - 4);
+    y = Math.min(y, rect.height - tip.offsetHeight - 4);
+    tip.style.left = x + 'px';
+    tip.style.top = y + 'px';
+  });
+  view.addEventListener('pointerleave', function () {
+    if (hovered) hovered.classList.remove('hover');
+    hovered = null;
+    tip.style.display = 'none';
+  });
+  /* ---- findings ---- */
+  var panel = document.getElementById('findings');
+  var list = document.getElementById('finding-list');
+  var toggle = document.getElementById('toggle-findings');
+  var count = DATA.findings.length;
+  function showPanel(open) {
+    panel.hidden = !open;
+    toggle.setAttribute('aria-pressed', String(open));
+  }
+  if (count === 0) {
+    toggle.textContent = 'No findings';
+    toggle.disabled = true;
+    panel.hidden = true;
+  } else {
+    toggle.textContent = count === 1 ? '1 finding' : count + ' findings';
+    toggle.onclick = function () { showPanel(panel.hidden); };
+    showPanel(true);
+  }
+  var lit = [];
+  var chosen = null;
+  function unlight() {
+    lit.forEach(function (group) { group.classList.remove('lit'); });
+    lit = [];
+    if (chosen) chosen.classList.remove('chosen');
+    chosen = null;
+  }
+  // A finding names the line of the statement at fault; what that statement
+  // drew lights up, and the view moves to it if it is out of sight.
+  function light(finding, button) {
+    unlight();
+    chosen = button;
+    button.classList.add('chosen');
+    lit = Array.from(svg.querySelectorAll('g[data-line="' + finding.line + '"]'));
+    lit.forEach(function (group) {
+      group.classList.remove('lit');
+      void group.getBoundingClientRect();
+      group.classList.add('lit');
+    });
+    if (lit.length === 0) return;
+    var room = view.getBoundingClientRect();
+    var r = null;
+    lit.forEach(function (group) {
+      var b = group.getBoundingClientRect();
+      r = r ? { l: Math.min(r.l, b.left), t: Math.min(r.t, b.top), r: Math.max(r.r, b.right), b: Math.max(r.b, b.bottom) }
+            : { l: b.left, t: b.top, r: b.right, b: b.bottom };
+    });
+    var inside = r.l >= room.left && r.r <= room.right && r.t >= room.top && r.b <= room.bottom;
+    if (inside) return;
+    zoom.pan((room.left + room.width / 2) - (r.l + r.r) / 2, (room.top + room.height / 2) - (r.t + r.b) / 2);
+  }
+  DATA.findings.forEach(function (finding) {
+    var item = document.createElement('li');
+    var button = document.createElement('button');
+    button.type = 'button';
+    var where = document.createElement('span');
+    where.className = 'where';
+    where.textContent = 'line ' + finding.line + ' ';
+    var kind = document.createElement('span');
+    kind.className = 'kind';
+    kind.textContent = finding.kind;
+    button.append(where, kind, document.createElement('br'), document.createTextNode(finding.message));
+    if (!svg.querySelector('g[data-line="' + finding.line + '"]')) {
+      var note = document.createElement('span');
+      note.className = 'note';
+      note.textContent = 'Nothing drawn comes from that line.';
+      button.append(note);
+    }
+    button.onclick = function () { light(finding, button); };
+    item.append(button);
+    list.append(item);
+  });
+  /* ---- keys, beyond the zoom's own ---- */
+  document.addEventListener('keydown', function (event) {
+    if (event.ctrlKey || event.metaKey || event.altKey) return;
+    if (event.target.closest && event.target.closest('input, textarea')) return;
+    if (event.key === 'f' && !full.hidden) toggleFull();
+    else if (event.key === 'Escape') { showExport(false); unlight(); }
+    else return;
+    event.preventDefault();
+  });
+  zoom.show();
+})();
+</script>
+</body>
+</html>
+`;

package/dist/parser.js CHANGED Viewed

@@ -1,4 +1,4 @@
-import { BUNDLE_KEYS, COLOR_KEYS, POINT_KEYS, REGION_KEYS, WAYS, describePoint, fractionAxis, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, TEXT_KEYS, MARK_TEXT_KEYS, POINT_TEXT_SIDES, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, EDGE_ORDER_KEYS, LAYOUT_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
+import { BUNDLE_KEYS, COLOR_KEYS, POINT_KEYS, REGION_KEYS, WAYS, describePoint, fractionAxis, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, TEXT_KEYS, MARK_TEXT_KEYS, POINT_TEXT_SIDES, LINE_KEYS, LINE_VALUES, BORDER_KEYS, CONTENTS_KEYS, EDGE_ORDER_KEYS, LAYOUT_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { CHECK_DEFAULTS, CHECK_KINDS, setCheck } from './checks.js';
 import { SourceError } from './errors.js';
 import { STATEMENT_KEYWORDS } from './grammar.js';
@@ -309,6 +309,7 @@ const BRACKET_KEYS = {
     text: TEXT_KEYS,
     contents: CONTENTS_KEYS,
     line: LINE_KEYS,
+    border: BORDER_KEYS,
     checks: CHECK_KINDS,
 };
 /** How each bracketed key's error quotes itself back, and what it is about. */
@@ -316,6 +317,7 @@ const BRACKET_ABOUT = {
     text: { kind: 'a text', example: 'color: theme-muted' },
     contents: { kind: 'a `contents:` bracket', example: 'widths: match' },
     line: { kind: 'a line', example: 'path: square' },
+    border: { kind: 'a border', example: 'thickness: thick' },
     checks: { kind: 'a `checks:` bracket', example: 'edge-crossings: on' },
 };
 /**
@@ -702,7 +704,8 @@ function readAttr(tokens, at, attrs, line, subject) {
             // A line's color is stored where `line: red` puts it, so the short form
             // and the bracket are one key: a style's `line: red` merges under an
             // edge's `line: (color: blue)`, and writing both on one line is a repeat.
-            const stored = key === 'line' && inner === 'color' ? 'line' : `${key}.${inner}`;
+            // A border's color the same.
+            const stored = (key === 'line' || key === 'border') && inner === 'color' ? key : `${key}.${inner}`;
             setOnce(attrs, stored, value, subject, line, { key: `${key}: (${inner}: …)`, value: (v) => v });
         }
         return read.next;
@@ -720,6 +723,16 @@ function readAttr(tokens, at, attrs, line, subject) {
         setOnce(attrs, key, value.text, subject, line, { key, value: quoteOf });
         return at + 2;
     }
+    if (key === 'title') {
+        // A title is a text, and every text is quoted. Unquoted, its first word
+        // would be the title and the rest read as stray words.
+        const value = tokens[at + 1];
+        if (!value || !value.quoted) {
+            throw new SourceError(`${subject}: a title is written in quotes — \`title: "How a login reaches the database"\``, line);
+        }
+        setOnce(attrs, key, value.text, subject, line, { key, value: quoteOf });
+        return at + 2;
+    }
     if (key === 'style') {
         // `style: base, critical and alarm` — several bundles, applied in the order
         // written, a later one winning where two set the same key. The list reads
@@ -768,7 +781,7 @@ function readAttr(tokens, at, attrs, line, subject) {
         });
         return next;
     }
-    if (bracketKeys !== undefined && key !== 'text' && key !== 'line') {
+    if (bracketKeys !== undefined && key !== 'text' && key !== 'line' && key !== 'border') {
         // `contents: match` names the part and then says one of its two properties
         // without saying which. The brackets are what make the level shift visible,
         // so there is no unbracketed spelling to fall back to.
@@ -821,6 +834,11 @@ function readAttr(tokens, at, attrs, line, subject) {
                 `\`line: (${property}: ${valueToken.text})\``, line);
         }
     }
+    if (key === 'border' && !valueToken.quoted && /^(thin|normal|thick|\d*\.?\d+(px)?)$/.test(valueToken.text)) {
+        // `border: red` is the short form of the color, as `line: red` is.
+        throw new SourceError(`\`border: ${valueToken.text}\` — \`border:\` on its own takes a color. Its thickness goes in its bracket: ` +
+            `\`border: (thickness: ${valueToken.text})\``, line);
+    }
     if (key === 'align' && valueToken.text === 'widths') {
         // Removed in 0.3.0. It was a size operation wearing an alignment's name,
         // and its value set had one member — a flag in a property's clothes. Its

package/dist/place.d.ts CHANGED Viewed

@@ -153,6 +153,8 @@ export declare class Placer {
     private readonly origins;
     /** Containers whose anchor is being placed on the page, so a box outside them is measured on the page rather than in their frame. */
     private readonly onPage;
+    /** Boxes that anchor their frame on one axis only, when no box in it says nothing at all (`splitAnchors`). */
+    private readonly axisAnchors;
     /** Named points and regions being worked out, innermost last, to refuse one defined through itself. */
     private readonly expanding;
     constructor(roots: LayoutNode[], byName: Map<string, LayoutNode>, facts: Map<LayoutNode, NodeFacts>,
@@ -534,6 +536,23 @@ export declare class Placer {
      * title something is placed against anchors the frame instead.
      */
     private checkAnchors;
+    /**
+     * Every box in a frame says something about where it goes, so the frame is
+     * anchored one axis at a time (design.org 5.3): across by the one box that
+     * says nothing across, up and down by the one that says nothing up and
+     * down. A lone direction's centering counts as saying nothing when its
+     * target's place on that axis is worked out from the box itself, as with
+     * `b right of a` and `a even with b.1`: the centering gives way to what was
+     * written. An axis nobody leaves free is a circle, reported when placing,
+     * and an axis a container is placed on by what it holds needs no anchor.
+     */
+    private splitAnchors;
+    /** Whether a box with nothing stated on this axis is left free there: no lone direction centers it, or the one that would is placed from the box itself. */
+    private loneGivesWay;
+    /** The boxes a placement names, through points and regions. */
+    private namedFrom;
+    /** Whether a box's place on one axis is worked out, however indirectly, from `from` or something inside it. */
+    private placedFrom;
     /**
      * A box in a venn's part may be placed against a box in another part, and
      * then it says where its whole part goes up and down: so it must be the

package/dist/place.js CHANGED Viewed

@@ -130,6 +130,8 @@ export class Placer {
     origins = new Map();
     /** Containers whose anchor is being placed on the page, so a box outside them is measured on the page rather than in their frame. */
     onPage = new Set();
+    /** Boxes that anchor their frame on one axis only, when no box in it says nothing at all (`splitAnchors`). */
+    axisAnchors = new Set();
     /** Named points and regions being worked out, innermost last, to refuse one defined through itself. */
     expanding = [];
     constructor(roots, byName, facts,
@@ -286,7 +288,7 @@ export class Placer {
             if (this.frameAnchor(node, axis))
                 return this.anchorOnPage(node, axis);
             const above = node.parent ? this.origin(node.parent, axis) : 0;
-            if (this.floats(node))
+            if (this.floats(node, axis))
                 return above;
             this.refusePlacedTwice(node, axis);
             return above + this.start(node, axis) - this.frame(node, axis).boxStart;
@@ -346,9 +348,11 @@ export class Placer {
      * goes, and nothing inside it is placed against a box outside it in its
      * stead. Its frame's origin is its own container's.
      */
-    floats(node) {
+    floats(node, axis) {
         const parent = node.parent;
-        if (node.placements.length > 0 || node.children.length === 0)
+        if (node.children.length === 0)
+            return false;
+        if (node.placements.length > 0 && !this.axisAnchors.has(`${node.name}\n${axis}`))
             return false;
         if (parent && (parent.heading === node || joinedToText(node) || this.facts.get(parent).layout || this.vennPart(node) !== undefined)) {
             return false;
@@ -609,7 +613,7 @@ export class Placer {
         }
         // A container that anchors its frame shares its container's origin, so
         // its box starts where its outline does.
-        if (this.floats(node))
+        if (this.floats(node, axis))
             return this.frame(node, axis).boxStart;
         if (node.placements.length === 0 || this.acrossParts(node)) {
             // The anchor of its frame. One placed against a box in another part of
@@ -628,7 +632,7 @@ export class Placer {
     placed(node, axis) {
         const statements = this.statements(node, axis);
         if (statements.length === 0)
-            return this.lone(node, axis);
+            return this.axisAnchors.has(`${node.name}\n${axis}`) ? 0 : this.lone(node, axis);
         if (statements.length === 1) {
             const [only] = statements;
             return this.apply(node, axis, only);
@@ -2234,9 +2238,8 @@ export class Placer {
             const content = members.filter((member) => !this.framed(member));
             const unplaced = content.filter((member) => this.unplaced(member));
             const onTitle = content.find((member) => this.onTitle(member));
-            if (!parent && unplaced.length === 0) {
-                throw new SourceError('every node is placed relative to another, so nothing anchors the diagram', 1);
-            }
+            if (unplaced.length === 0 && !(parent && this.anchoredOnTitle(parent)))
+                this.splitAnchors(content, parent);
             if (unplaced.length > 1) {
                 const names = unplaced.map((node) => `"${node.name}"`).join(', ');
                 throw new SourceError(parent
@@ -2253,6 +2256,62 @@ export class Placer {
         for (const member of all)
             this.checkAnchors(member.children, member);
     }
+    /**
+     * Every box in a frame says something about where it goes, so the frame is
+     * anchored one axis at a time (design.org 5.3): across by the one box that
+     * says nothing across, up and down by the one that says nothing up and
+     * down. A lone direction's centering counts as saying nothing when its
+     * target's place on that axis is worked out from the box itself, as with
+     * `b right of a` and `a even with b.1`: the centering gives way to what was
+     * written. An axis nobody leaves free is a circle, reported when placing,
+     * and an axis a container is placed on by what it holds needs no anchor.
+     */
+    splitAnchors(members, parent) {
+        const free = BOTH_AXES.map((axis) => parent && this.frameAnchor(parent, axis)
+            ? []
+            : members.filter((member) => this.statements(member, axis).length === 0 && this.loneGivesWay(member, axis)));
+        if (!parent && free.every((on) => on.length === 0)) {
+            throw new SourceError('every node is placed relative to another, so nothing anchors the diagram', 1);
+        }
+        BOTH_AXES.forEach((axis, index) => {
+            const on = free[index];
+            // With the other axis bound all round there is a circle, which placing reports better.
+            if (on.length > 1 && free.every((other) => other.length > 0)) {
+                const names = on.map((node) => `"${node.name}"`).join(', ');
+                throw new SourceError(`exactly one node may say nothing about where it goes ${AXIS_SAID[axis]}, but ${on.length} do: ${names}`, on[1].line);
+            }
+            if (on.length === 1)
+                this.axisAnchors.add(`${on[0].name}\n${axis}`);
+        });
+    }
+    /** Whether a box with nothing stated on this axis is left free there: no lone direction centers it, or the one that would is placed from the box itself. */
+    loneGivesWay(node, axis) {
+        const offsets = node.placements.filter((placement) => placement.kind === 'offset' && component(placement.direction, axis) === undefined);
+        if (offsets.length === 0)
+            return true;
+        if (offsets.length > 1)
+            return false;
+        return this.namedFrom(offsets[0]).some((named) => this.placedFrom(named, axis, node, new Set()));
+    }
+    /** The boxes a placement names, through points and regions. */
+    namedFrom(placement) {
+        return placement.targets
+            .flatMap((target) => this.boxesNamed(target, []))
+            .flatMap((name) => this.byName.get(name) ?? []);
+    }
+    /** Whether a box's place on one axis is worked out, however indirectly, from `from` or something inside it. */
+    placedFrom(node, axis, from, seen) {
+        if (node === from || isWithin(node, from))
+            return true;
+        if (seen.has(node))
+            return false;
+        seen.add(node);
+        const stated = this.statements(node, axis).map((statement) => statement.placement);
+        const placements = stated.length > 0
+            ? stated
+            : node.placements.filter((placement) => placement.kind === 'offset' && component(placement.direction, axis) === undefined);
+        return placements.some((placement) => this.namedFrom(placement).some((named) => this.placedFrom(named, axis, from, seen)));
+    }
     /**
      * A box in a venn's part may be placed against a box in another part, and
      * then it says where its whole part goes up and down: so it must be the

package/dist/render.d.ts CHANGED Viewed

@@ -10,3 +10,20 @@ export interface RenderOptions {
 }
 /** Turn solved geometry into a standalone SVG document. */
 export declare function render(layout: Layout, options?: RenderOptions): string;
+/**
+ * The SVG as `render` gives it, and the same drawing with each thing wrapped in
+ * a group naming it and its statement's line, for a page that points at things
+ * (`--page`). Drawn once, so the two can't disagree.
+ */
+export declare function renderTagged(layout: Layout, options?: RenderOptions): {
+    svg: string;
+    tagged: string;
+};
+/**
+ * The colors a drawing is made in. A theme passed in — the command line's
+ * `--theme` — beats the one the file names, so one source renders in either.
+ * `diagram background:` and `text:` are the author overruling a color of
+ * whichever theme that is, and a color written by hand wins over any theme, so
+ * they are folded in afterwards and everything downstream sees one theme.
+ */
+export declare function themeOf(layout: Layout, options?: RenderOptions): Theme;