clay-server 4.8.2 → 4.9.0-beta.1

package/lib/salt-images.js

@@ -0,0 +1,87 @@
+// Resolve explicit raster images only. SVG output contains embedded bytes, never remote URLs.
+var https = require('node:https');
+var dns = require('node:dns').promises;
+var net = require('node:net');
+var MAX_BYTES = 1024 * 1024;
+function failure(message) { return Object.assign(new Error(message), { status: 422 }); }
+function bounded(promise, signal) {
+  return new Promise(function (resolve, reject) {
+    function aborted() { reject(failure('Wireframe image loading cancelled or timed out.')); }
+    if (signal.aborted) { aborted(); return; }
+    signal.addEventListener('abort', aborted, { once: true });
+    promise.then(resolve, reject).finally(function () { signal.removeEventListener('abort', aborted); });
+  });
+}
+function publicAddress(address) {
+  if (net.isIP(address) !== 4) return false;
+  var p = address.split('.').map(Number);
+  return !(p[0] === 0 || p[0] === 10 || p[0] === 127 || p[0] >= 224 ||
+    p[0] === 100 && p[1] >= 64 && p[1] <= 127 || p[0] === 169 && p[1] === 254 ||
+    p[0] === 172 && p[1] >= 16 && p[1] <= 31 || p[0] === 192 && (p[1] === 168 || p[1] === 0 || p[1] === 2) ||
+    p[0] === 198 && (p[1] === 18 || p[1] === 19 || p[1] === 51 && p[2] === 100) || p[0] === 203 && p[1] === 0 && p[2] === 113);
+}
+function decode(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length > MAX_BYTES || bytes.length < 33 ||
+    bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a' || bytes.toString('ascii', 12, 16) !== 'IHDR') throw failure('Wireframe images must be PNG files of at most 1 MB.');
+  var width = bytes.readUInt32BE(16); var height = bytes.readUInt32BE(20);
+  if (!width || !height || width > 2048 || height > 2048) throw failure('Wireframe images must be at most 2048 by 2048 pixels.');
+  return { width: width, height: height, data: 'data:image/png;base64,' + bytes.toString('base64') };
+}
+async function download(value, signal) {
+  var url;
+  try { url = new URL(value); } catch (e) { throw failure('Invalid wireframe image URL.'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.port && url.port !== '443') throw failure('Wireframe images require a public HTTPS URL on port 443.');
+  var addresses = await bounded(dns.lookup(url.hostname, { all: true, family: 4 }), signal);
+  if (!addresses.length || addresses.some(function (entry) { return !publicAddress(entry.address); })) throw failure('Wireframe images cannot access private or reserved network addresses.');
+  if (signal.aborted) throw failure('Wireframe image loading cancelled or timed out.');
+  return new Promise(function (resolve, reject) {
+    var request = https.get(url, { signal: signal, agent: false, headers: { Accept: 'image/png' },
+      lookup: function (_, options, callback) { callback(null, options.all ? [addresses[0]] : addresses[0].address, 4); }
+    }, function (response) {
+      if (response.statusCode !== 200) { response.resume(); reject(failure('Wireframe image server returned HTTP ' + response.statusCode + '. Redirects are not followed.')); return; }
+      var chunks = []; var size = 0;
+      response.on('data', function (chunk) {
+        size += chunk.length;
+        if (size > MAX_BYTES) { var error = failure('Wireframe image exceeds 1 MB.'); reject(error); request.destroy(error); }
+        else chunks.push(chunk);
+      });
+      response.on('error', reject);
+      response.on('end', function () { try { resolve(decode(Buffer.concat(chunks))); } catch (e) { reject(e); } });
+    });
+    request.on('error', function (error) { reject(failure('Unable to load wireframe image: ' + error.message)); });
+  });
+}
+async function resolveImages(root, options) {
+  var runs = [];
+  function label(node) { if (node) (node.runs || []).forEach(function (run) { if (run.imageUrl) runs.push(run); }); }
+  function visit(node) {
+    label(node); label(node.titleData);
+    (node.options || []).forEach(label);
+    (node.rows || []).forEach(function (row) { row.forEach(visit); });
+    (node.popups || []).forEach(function (row) { row.forEach(visit); });
+  }
+  // The root's display options differ from a dropdown's option labels.
+  (root.rows || []).forEach(function (row) { row.forEach(visit); }); label(root.titleData);
+  (root.popups || []).forEach(function (row) { row.forEach(visit); });
+  Object.values(root.options.labels).forEach(function (labels) { labels.forEach(label); });
+  var urls = Array.from(new Set(runs.map(function (run) { return run.imageUrl; })));
+  if (urls.length > 4) throw failure('Wireframes support at most four distinct images.');
+  if (!urls.length) return;
+  var controller = new AbortController();
+  var signal = controller.signal;
+  function cancel() { controller.abort(); }
+  if (options.signal) {
+    if (options.signal.aborted) cancel();
+    else options.signal.addEventListener('abort', cancel, { once: true });
+  }
+  var timer = setTimeout(cancel, 10000);
+  var embeddedBytes = 0;
+  try { for (var url of urls) {
+    var resource;
+    try { resource = options.imageLoader ? decode(await bounded(Promise.resolve(options.imageLoader(url, signal)), signal)) : await download(url, signal); }
+    catch (error) { throw Object.assign(failure(error.message), { status: options.signal && options.signal.aborted ? 499 : 422 }); }
+    runs.forEach(function (run) { if (run.imageUrl === url) { run.image = resource; embeddedBytes += resource.data.length; } });
+    if (embeddedBytes > 6 * 1024 * 1024) throw failure('Embedded wireframe images exceed the 6 MB output budget.');
+  } } finally { clearTimeout(timer); if (options.signal) options.signal.removeEventListener('abort', cancel); }
+}
+module.exports = { resolveImages: resolveImages, publicAddress: publicAddress, decode: decode };

package/lib/salt-layout.js

@@ -0,0 +1,60 @@
+// Geometry adapted from PlantUML 1.2026.8 Salt, (c) Arnaud Roques, GPL-3.0-or-later.
+// See LICENSES/plantuml-salt.txt. All distances retain reference fractional precision.
+var text = require('./salt-text');
+function measure(node) {
+  measureNode(node);
+  if (node.width > 8192 || node.height > 8192) throw Object.assign(new Error('Wireframe exceeds the 8192-pixel layout limit. Split it into smaller views.'), { status: 413 });
+}
+function measureNode(node) {
+  if (node.type === 'sprite') return;
+  if (node.type === 'span') { node.width = 0; node.height = 0; return; }
+  if (node.type !== 'container') {
+    var managed = /^(button|input|select)$/.test(node.type);
+    node.label = text.measureLabel(node, managed);
+    node.width = managed ? Math.max(node.label.width, node.charLength * 8) : node.label.width;
+    node.height = node.label.height;
+    if (node.type === 'button') { node.width += 9; node.height += 9; }
+    if (node.type === 'input') { node.width += 6; node.height += 2; }
+    if (node.type === 'select') { node.width += 16; node.height += 4; node.optionLabels = (node.options || []).map(function (option) { return text.measureLabel(option); }); }
+    if (/^(radio|checkbox)$/.test(node.type)) node.width += 20;
+    if (node.type === 'separator') { node.width = 10; node.height = 6; }
+    return;
+  }
+  node.rows.forEach(function (row) { row.forEach(measure); });
+  if (node.style[0] === 'T') return require('./salt-tree').measure(node);
+  if (node.style === '/' || node.style === '*') {
+    node.items = node.rows.flat();
+    (node.popups || []).forEach(function (items) { items.slice(1).forEach(function (item) { measure(item); if (item.text === '-') { item.width = 10; item.height = 5; } }); });
+    node.vertical = node.style === '/' && (node.verticalTabs || node.rows.length > 1);
+    var gap = node.style === '/' ? 15 : 10;
+    node.width = node.vertical ? Math.max(0, ...node.items.map(function (c) { return c.width; })) : node.items.reduce(function (sum, c) { return sum + c.width + gap; }, 0);
+    node.height = node.vertical ? node.items.reduce(function (sum, c) { return sum + c.height + gap; }, 0) : Math.max(0, ...node.items.map(function (c) { return c.height; }));
+    return;
+  }
+  node.titleLabel = node.title ? text.measureLabel(node.titleData || text.parseLabel(node.title)) : { width: 0, height: 0, runs: [] };
+  var titleHeight = node.titleLabel.height;
+  var cols = Math.max(1, ...node.rows.map(function (r) { return r.length; }));
+  node.columns = Array(cols).fill(0);
+  node.heights = Array(Math.max(1, node.rows.length)).fill(0);
+  node.rows.forEach(function (row, r) {
+    row.forEach(function (child, c) {
+      if (child.type === 'span') return;
+      if (!child.span) node.columns[c] = Math.max(node.columns[c], child.width + 2);
+      node.heights[r] = Math.max(node.heights[r], child.height + 2 + (r === 0 ? titleHeight / 2 : 0));
+    });
+  });
+  node.rows.forEach(function (row) { row.forEach(function (child, c) {
+    if (!child.span) return;
+    var available = node.columns.slice(c, c + child.span).reduce(function (a, b) { return a + b; }, 0);
+    node.columns[c + child.span - 1] += Math.max(0, child.width + 2 - available);
+  }); });
+  node.xs = [0]; node.ys = [titleHeight / 2];
+  node.columns.forEach(function (w) { node.xs.push(node.xs[node.xs.length - 1] + w); });
+  node.heights.forEach(function (h) { node.ys.push(node.ys[node.ys.length - 1] + h); });
+  node.width = node.xs[node.xs.length - 1];
+  node.height = node.ys[node.ys.length - 1] + titleHeight;
+  node.contentWidth = node.width; node.contentHeight = node.height;
+  if (node.scroll && node.scroll !== 'S-') node.width += 30;
+  if (node.scroll && node.scroll !== 'SI') node.height += 30;
+}
+module.exports = { measure: measure };

package/lib/salt-options.js

@@ -0,0 +1,23 @@
+// Read only bounded display directives; never evaluate PlantUML preprocessing.
+var color = require('./salt-text').color;
+function parse(body) {
+  var options = { scale: 1, background: '#FFFFFF' };
+  body = body.replace(/^[ \t]*legend[ \t]*\n([\s\S]*?)^[ \t]*end[ \t]*legend[ \t]*$/gim, function (_, value) { options.legend = value.trim(); return ''; });
+  body = body.replace(/^[ \t]*(title|header|footer|caption)[ \t]+([^\n]+)$/gim, function (_, name, value) { options[name.toLowerCase()] = value.trim(); return ''; });
+  body = body.replace(/^\s*!option handwritten (true|false)[ \t]*$/gim, function (_, value) { options.handwritten = value === 'true'; return ''; });
+  body = body.replace(/<style>\s*saltDiagram\s*\{([^}]*)\}\s*<\/style>/gi, function (_, contents) {
+    contents.trim().split(/\n/).forEach(function (line) { setting(line.trim()); }); return '';
+  });
+  function setting(line) {
+    var m = /^(BackgroundColor|dpi|defaultFontName|Fontname|FontSize|FontStyle|LineThickness|LineColor)\s+(\S+)$/i.exec(line);
+    if (!m) throw new Error('Unsupported Salt display setting: ' + line);
+    if (/^BackgroundColor$/i.test(m[1])) options.background = color(m[2]);
+    if (/^dpi$/i.test(m[1])) options.scale = Number(m[2]) / 96;
+    // The reference Salt renderer ignores these font and stroke style settings.
+  }
+  body = body.replace(/^\s*skinparam[ \t]+([^\n]+)$/gim, function (_, value) { setting(value.trim()); return ''; });
+  body = body.replace(/^\s*scale[ \t]+([\d.]+)[ \t]*$/gim, function (_, value) { options.scale = Number(value); return ''; });
+  if (!Number.isFinite(options.scale) || options.scale <= 0 || options.scale > 8) throw new Error('Salt scale must be greater than zero and at most 8.');
+  return { body: body, options: options };
+}
+module.exports = { parse: parse };

package/lib/salt-overlays.js

@@ -0,0 +1,45 @@
+// Adapted from PlantUML Salt controls, GPL-3.0-or-later; see LICENSES/plantuml-salt.txt.
+function dropdown(node, x, y, s) {
+  var labels = node.optionLabels || [];
+  if (!labels.length) return;
+  var width = Math.max(node.width - 1, ...labels.map(function (l) { return l.width; }));
+  var height = labels.reduce(function (a, l) { return a + l.height; }, 0);
+  y += node.height - 1;
+  s.rect(x, y, width - 1, height - 1, '#EEE');
+  labels.forEach(function (label) { s.label(label, x, y); y += label.height; });
+}
+function menu(node, x, y, s) {
+  (node.popups || []).forEach(function (items) {
+    var offset = 0;
+    for (var entry of node.items) { if (entry.text === items[0].text) break; offset += entry.width + 10; }
+    var children = items.slice(1);
+    var width = Math.max(0, ...children.map(function (item) { return item.width; }));
+    var height = children.reduce(function (a, item) { return a + item.height; }, 0);
+    var cy = y + node.height;
+    s.rect(x + offset, cy, width, height, '#DDD');
+    children.forEach(function (item) {
+      if (item.text === '-') s.line(x + offset, cy + item.height / 2, x + offset + width, cy + item.height / 2);
+      else s.label(item.label, x + offset, cy);
+      cy += item.height;
+    });
+  });
+}
+function scroll(node, x, y, s) {
+  var w = node.contentWidth; var h = node.contentHeight;
+  function triangle(xx, yy, points) { s.path(points.map(function (p, i) { return (i ? 'L' : 'M') + (xx + p[0]) + ',' + (yy + p[1]); }).join(' ') + '', '#000', null, xx + 6, yy + 6); }
+  if (node.scroll !== 'S-') {
+    var vx = x + w + 4;
+    s.rect(vx, y, 15, h);
+    s.line(vx, y + 12, vx + 15, y + 12); s.line(vx, y + h - 12, vx + 15, y + h - 12);
+    triangle(vx + 4, y + 4, [[3,0],[6,5],[0,5],[3,0]]);
+    triangle(vx + 4, y + h - 8, [[3,5],[6,0],[0,0],[3,5]]);
+  }
+  if (node.scroll !== 'SI') {
+    var hy = y + h + 4;
+    s.rect(x, hy, w, 15);
+    s.line(x + 12, hy, x + 12, hy + 15); s.line(x + w - 12, hy, x + w - 12, hy + 15);
+    triangle(x + 4, hy + 4, [[0,3],[5,6],[5,0],[0,3]]);
+    triangle(x + w - 8, hy + 4, [[5,3],[0,6],[0,0],[5,3]]);
+  }
+}
+module.exports = { dropdown: dropdown, menu: menu, scroll: scroll };

package/lib/salt-parser.js

@@ -0,0 +1,153 @@
+// Clay's bounded parser for Salt wireframes; no PlantUML preprocessor execution.
+function fail(message) { throw Object.assign(new Error(message), { status: 422 }); }
+function tokenize(body) {
+  var tokens = [];
+  var text = '';
+  var quoted = false;
+  function flush() { if (text.trim()) tokens.push({ type: 'text', text: text.trim() }); text = ''; }
+  for (var i = 0; i < body.length; i++) {
+    var c = body[i];
+    if (c === '"') quoted = !quoted;
+    if (!quoted && (c === '{' || c === '}' || c === '|' || c === '\n')) {
+      flush();
+      var token = { type: c };
+      if (c === '{') {
+        token.style = '';
+        if (/[#!+\-^/*ST]/.test(body[i + 1] || ' ')) token.style = body[++i];
+        if (token.style === 'S' && /[I-]/.test(body[i + 1] || ' ')) token.style += body[++i];
+        if (token.style === 'T' && /[!+#-]/.test(body[i + 1] || ' ')) token.style += body[++i];
+        if (token.style === '^') {
+          var title = /^[ \t]*"([^"\n]*)"/.exec(body.slice(i + 1));
+          if (title) { token.title = title[1]; i += title[0].length; }
+          else { var unquoted = /^[^\n|{}]*/.exec(body.slice(i + 1))[0]; token.title = unquoted.trim(); i += unquoted.length; }
+        }
+        if (body[i + 1] && !/[\s{}|]/.test(body[i + 1]) && !token.style) {
+          fail('Unsupported Salt container. Use {, {+, {#, {!, {-, {^, {/, or {*.');
+        }
+      }
+      tokens.push(token);
+    } else text += c;
+  }
+  if (quoted) fail('Unclosed quoted text field.');
+  flush();
+  return tokens;
+}
+
+function label(text) {
+  return require('./salt-text').parseLabel(text);
+}
+function widget(text) {
+  var result = { type: 'label' };
+  var match;
+  if (text === '*') return { type: 'span' };
+  if (/^[.!]?$/.test(text)) result.type = 'space';
+  else if (/^(\.\.|==|~~|--).*\1$/.test(text) || /^(\.\.|==|~~|--)$/.test(text)) { result.type = 'separator'; result.style = text.slice(0, 2); text = ''; }
+  else if ((match = /^\[([ X]?)\]\s*(.*)$/.exec(text))) { result.type = 'checkbox'; result.checked = /x/i.test(match[1]); text = match[2]; }
+  else if ((match = /^\(([ X]?)\)\s*(.*)$/.exec(text))) { result.type = 'radio'; result.checked = /x/i.test(match[1]); text = match[2]; }
+  else if ((match = /^\[([^\]]+)\]$/.exec(text))) { result.type = 'button'; text = match[1]; }
+  else if ((match = /^"([^"\n]*)"$/.exec(text))) { result.type = 'input'; text = match[1]; }
+  else if (/^\^.*\^$/.test(text)) {
+    var choices = text.slice(1, -1).split('^').filter(Boolean);
+    result.type = 'select'; result.options = choices.slice(1).map(label); text = choices[0] || '';
+  }
+  else if (!/^\[x\]/.test(text) && /^[\["^]|^\*/.test(text) && !/^\*\*[^*]+\*\*$/.test(text) && !/^\*+\s+/.test(text)) fail('Unsupported or incomplete control: ' + text.slice(0, 60));
+  if (text === '*') return { type: 'span' };
+  result.charLength = text.replace(/<&[-\w]+>/g, '00').replace(/<\/?(?:b|i|s|u|w|color|back|font|size)(?::[^>]+)?>/gi, '').length;
+  return Object.assign(result, label(/^(button|input|select)$/.test(result.type) ? text.trim() : text));
+}
+
+function parseSalt(source) {
+  var screen = require('./salt-screen').parse(source);
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(source)) fail("Wireframe source contains unsupported control characters.");
+  var body;
+  var match = /^\s*@startsalt(?:[ \t]+[\w-]+)?[ \t]*\r?\n([\s\S]*?)\r?\n\s*@endsalt\s*$/i.exec(source);
+  if (match) body = match[1];
+  else {
+    match = /^\s*@startuml(?:[ \t]+[\w-]+)?[ \t]*\r?\n\s*salt\s*\r?\n([\s\S]*?)\r?\n\s*@enduml\s*$/i.exec(source);
+    if (match) body = match[1];
+  }
+  if (body === undefined) fail('The built-in viewer supports Salt wireframes. Use @startsalt / @endsalt around a layout. Other PlantUML diagram types are not supported.');
+  body = body.replace(/^[ \t]*'[^\n]*$/gm, '').replace(/\r/g, '');
+  var settings = require('./salt-options').parse(body);
+  body = settings.body;
+  if (/^[ \t]*(?:!|skinparam\b|scale\b|sprite\b)|%[a-z_]+\s*\(/im.test(body)) fail('PlantUML preprocessing, includes, macros, and unrecognized directives are not supported in built-in wireframes.');
+  var sprites = Object.create(null);
+  var spriteCount = 0;
+  body = body.replace(/<<([\w]*)\s*\n([.X\s]+?)\n\s*>>/g, function (_, name, pixels) {
+    var rows = pixels.trim().split(/\n/).map(function (line) { return line.trim(); });
+    if (!rows.length || rows.some(function (line) { return !/^[.X]+$/.test(line) || line.length !== rows[0].length; })) fail('Sprite rows must have equal widths and contain only . or X.');
+    var id = '__clay_sprite_' + spriteCount++ + '__';
+    sprites[id] = { type: 'sprite', pixels: rows, width: rows[0].length, height: rows.length };
+    if (name) sprites['<<' + name + '>>'] = sprites[id];
+    return id;
+  });
+  var tokens = tokenize(body);
+  var index = 0;
+  var count = 0;
+  function skipNewlines() { while (tokens[index] && tokens[index].type === '\n') index++; }
+  function container(depth) {
+    if (depth > 24) fail('Wireframe nesting is too deep (24 levels maximum).');
+    var start = tokens[index++];
+    var node = { type: 'container', style: start.style, title: start.title || '', titleData: start.title ? label(start.title) : null, rows: [] };
+    if (start.style[0] === 'S') { node.scroll = start.style; node.style = '+'; }
+    var row = [];
+    var expectsCell = false;
+    function cell(value) {
+      if (++count > 2000) fail('Wireframe has too many cells (2000 maximum).');
+      if (row.length >= 64) fail('Wireframe has too many columns (64 maximum).');
+      row.push(value); expectsCell = false;
+    }
+    function endRow() { if (expectsCell) cell(widget('.')); if (row.length) node.rows.push(row); row = []; }
+    while (index < tokens.length) {
+      var token = tokens[index];
+      if (token.type === '}') {
+        index++; endRow();
+        if (node.style === '*') {
+          node.popups = node.rows.slice(1); node.rows = node.rows.slice(0, 1);
+          node.popups.forEach(function (items) {
+            if (!node.rows[0].some(function (entry) { return entry.text === items[0].text; })) fail('Open menu must name an existing menu entry.');
+          });
+        }
+        return node;
+      }
+      if (token.type === '\n') {
+        if (node.style === '/' && row.length && !expectsCell) node.verticalTabs = true;
+        index++;
+        // A newline before/after a column separator is only formatting.
+        skipNewlines();
+        if (!expectsCell && (!tokens[index] || tokens[index].type !== '|')) endRow();
+      } else if (token.type === '|') {
+        if (!row.length || expectsCell) cell(widget('.'));
+        expectsCell = true; index++;
+      } else if (token.type === '{' || token.type === 'text') {
+        if (row.length && !expectsCell) fail('Separate cells with | or a newline.');
+        var value;
+        if (token.type === '{') value = container(depth + 1);
+        else { index++; value = sprites[token.text] ? Object.assign({}, sprites[token.text]) : widget(token.text); }
+        if (node.style[0] === 'T' && !row.length && value.type === 'label') {
+          var level = /^\+*/.exec(value.text)[0].length;
+          value = Object.assign({ type: 'label', level: level }, label(value.text.slice(level).trim()));
+        }
+        if (value.type === 'span') {
+          var previous = row[row.length - 1];
+          while (previous && previous.type === 'span') previous = previous.owner;
+          if (!previous) fail('A spanning cell needs a cell to its left.');
+          previous.span = (previous.span || 1) + 1; value.owner = previous;
+        }
+        cell(value);
+      } else fail('Unexpected Salt syntax.');
+    }
+    fail('Unclosed layout container. Add a closing }.');
+  }
+  skipNewlines();
+  if (!tokens[index] || tokens[index].type !== '{') fail('A Salt layout must start with {.');
+  var root = container(0);
+  skipNewlines();
+  if (index !== tokens.length) fail('Unexpected content after the layout. Use one outer container.');
+  root.options = settings.options;
+  if (screen) root.options.screen = screen;
+  root.options.labels = {};
+  ['title', 'header', 'footer', 'caption', 'legend'].forEach(function (name) { if (settings.options[name]) root.options.labels[name] = settings.options[name].split('\n').map(label); });
+  return root;
+}
+module.exports = { parseSalt: parseSalt };

package/lib/salt-screen.js

@@ -0,0 +1,111 @@
+// Optional Clay screen geometry. Plain Salt keeps its reference layout.
+function fail(message) { throw Object.assign(new Error('Clay screen layout: ' + message), { status: 422 }); }
+function parse(source) {
+  var screen = null;
+  var rules = Object.create(null);
+  source.replace(/^[ \t]*'[ \t]*@clay-(canvas|layout)[ \t]+([^\r\n]*)/gm, function (_, kind, value) {
+    if (kind === 'canvas') {
+      if (screen) fail('use one canvas declaration.');
+      var dimensions = /^(\d+)\s+(\d+)\s*$/.exec(value);
+      if (!dimensions) fail('canvas requires width and height in pixels.');
+      screen = { width: Number(dimensions[1]), height: Number(dimensions[2]), rules: rules };
+      if (screen.width < 240 || screen.height < 240 || screen.width > 4096 || screen.height > 4096) fail('canvas dimensions must be 240–4096 pixels.');
+    } else {
+      var parts = value.trim().split(/\s+/);
+      var key = parts.shift();
+      if (!/^root(?:\.\d+\.\d+)*$/.test(key) || rules[key]) fail('layout paths must be unique, such as root.1.0.');
+      var rule = {};
+      parts.forEach(function (part) {
+        var pair = /^(padding|gap|columns|rows)=(.+)$/.exec(part);
+        if (!pair || rule[pair[1]] !== undefined) fail('use padding, gap, columns or rows once per layout.');
+        if (/padding|gap/.test(pair[1])) {
+          if (!/^\d+$/.test(pair[2]) || Number(pair[2]) > 128) fail('padding and gap must be 0–128 pixels.');
+          rule[pair[1]] = Number(pair[2]);
+        } else {
+          var tracks = pair[2].split(',');
+          if (tracks.length > 64 || tracks.some(function (track) { return !/^(auto|\*|\d+)$/.test(track) || (/^\d+$/.test(track) && (Number(track) < 1 || Number(track) > 4096)); })) fail('tracks must be auto, *, or 1–4096 pixels.');
+          rule[pair[1]] = tracks;
+        }
+      });
+      rules[key] = rule;
+    }
+    return '';
+  });
+  if (!screen && Object.keys(rules).length) fail('layout rules require a canvas declaration.');
+  return screen;
+}
+function normal(node) { return node.type === 'container' && !/^[T/*]/.test(node.style) && !node.scroll; }
+function tracks(spec, minimum, total, gap, name) {
+  if (spec && spec.length !== minimum.length) fail(name + ' track count does not match its layout.');
+  var sizes = minimum.map(function (min, i) {
+    var track = spec ? spec[i] : 'auto';
+    if (/^\d+$/.test(track) && Number(track) + .01 < min) fail(name + ' track ' + (i + 1) + ' needs at least ' + Math.ceil(min) + ' pixels.');
+    return /^\d+$/.test(track) ? Number(track) : min;
+  });
+  if (total !== undefined) {
+    var remaining = total - sizes.reduce(function (a, b) { return a + b; }, 0) - gap * (sizes.length - 1);
+    if (remaining < -.01) fail(name + ' overflows by ' + Math.ceil(-remaining) + ' pixels. Increase the canvas/track or simplify its contents.');
+    var flexible = sizes.map(function (_, i) { return spec && spec[i] === '*' ? i : -1; }).filter(function (i) { return i >= 0; });
+    flexible.forEach(function (i) { sizes[i] += remaining / flexible.length; });
+  }
+  return sizes;
+}
+function prepare(node, screen, key, used) {
+  if (!normal(node)) { if (screen.rules[key]) fail(key + ' must target a regular layout container.'); return; }
+  var rule = screen.rules[key] || {};
+  used.add(key);
+  var padding = rule.padding === undefined ? 16 : rule.padding;
+  var gap = rule.gap === undefined ? 12 : rule.gap;
+  var columns = Array(node.columns.length).fill(0), rows = Array(node.rows.length).fill(0);
+  node.rows.forEach(function (row, r) { row.forEach(function (child, c) {
+    if (child.type === 'span') return;
+    prepare(child, screen, key + '.' + r + '.' + c, used);
+    if (!child.span) columns[c] = Math.max(columns[c], child.width);
+    rows[r] = Math.max(rows[r], child.height);
+  }); });
+  node.rows.forEach(function (row) { row.forEach(function (child, c) {
+    if (!child.span || child.type === 'span') return;
+    var available = columns.slice(c, c + child.span).reduce(function (a, b) { return a + b; }, 0) + gap * (child.span - 1);
+    columns[c + child.span - 1] += Math.max(0, child.width - available);
+  }); });
+  columns = tracks(rule.columns, columns, undefined, gap, key + ' columns');
+  rows = tracks(rule.rows, rows, undefined, gap, key + ' rows');
+  node.screen = { key: key, padding: padding, gap: gap, rule: rule, columns: columns, rows: rows };
+  node.width = columns.reduce(function (a, b) { return a + b; }, 0) + gap * (columns.length - 1) + padding * 2;
+  node.height = rows.reduce(function (a, b) { return a + b; }, 0) + gap * (rows.length - 1) + padding * 2 + node.titleLabel.height;
+}
+function place(node, width, height) {
+  if (!node.screen) return;
+  var box = node.screen, p = box.padding, gap = box.gap;
+  node.width = width; node.height = height;
+  var cols = tracks(box.rule.columns, box.columns, width - p * 2, gap, box.key + ' columns');
+  var rows = tracks(box.rule.rows, box.rows, height - p * 2 - node.titleLabel.height, gap, box.key + ' rows');
+  var y = p + node.titleLabel.height;
+  box.cells = []; box.vertical = []; box.horizontal = [];
+  node.rows.forEach(function (row, r) {
+    var x = p;
+    row.forEach(function (child, c) {
+      if (child.type !== 'span') {
+        var w = cols.slice(c, c + (child.span || 1)).reduce(function (a, b) { return a + b; }, 0) + gap * ((child.span || 1) - 1);
+        var yy = child.type === 'container' ? y : y + Math.max(0, (rows[r] - child.height) / 2);
+        if (child.type === 'input') child.width = w;
+        box.cells.push({ node: child, x: x, y: yy, width: w, height: rows[r] });
+        place(child, w, rows[r]);
+        if (c > 0) box.vertical.push({ x: x - gap / 2, y: y - gap / 2, height: rows[r] + gap });
+      }
+      x += cols[c] + gap;
+    });
+    if (r > 0) box.horizontal.push(y - gap / 2);
+    y += rows[r] + gap;
+  });
+}
+function apply(root) {
+  var screen = root.options.screen;
+  if (!screen) return;
+  if (!normal(root)) fail('the canvas needs a regular outer container.');
+  if (root.options.scale !== 1 || ['title', 'header', 'footer', 'caption', 'legend'].some(function (key) { return root.options[key]; })) fail('put headings inside the canvas; scale and outside annotations are not supported in screen mode.');
+  var used = new Set(); prepare(root, screen, 'root', used);
+  Object.keys(screen.rules).forEach(function (key) { if (!used.has(key)) fail('no container at ' + key + '.'); });
+  place(root, screen.width - 2, screen.height - 2);
+}
+module.exports = { parse: parse, apply: apply };

package/lib/salt-svg-shapes.js

@@ -0,0 +1,80 @@
+// Reference SVG primitives; text is escaped and images contain resolved PNG bytes.
+function escape(value) { return String(value).replace(/[&<>"']/g, function (c) { return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' }[c]; }); }
+function createShapes(out, scale, handwritten) {
+  scale = scale || 1;
+  function number(value) { return String(Math.round(value * scale * 1000) / 1000); }
+  var ink = '#000';
+  var bounds = { x: 0, y: 0 };
+  var filters = Object.create(null);
+  function include(x, y) { bounds.x = Math.max(bounds.x, x); bounds.y = Math.max(bounds.y, y); }
+  function rect(x, y, w, h, fill, stroke, radius, thickness) {
+    include(x + w, y + h);
+    if (handwritten) {
+      var points = require('./salt-hand').rect(w, h, radius).map(function (p) { return [p[0] + x, p[1] + y]; });
+      out.push('<polygon points="' + points.map(function (p) { return p.map(number).join(','); }).join(' ') + '" fill="' + (fill || 'none') + '" stroke="' + (stroke || '#000') + '" stroke-width="' + number(thickness || 1) + '" stroke-linejoin="miter" stroke-miterlimit="10"/>'); return;
+    }
+    out.push('<rect x="' + number(x) + '" y="' + number(y) + '" width="' + number(w) + '" height="' + number(h) + '" fill="' + (fill || 'none') + '" stroke="' + (stroke || '#000') + '" stroke-width="' + number(thickness || 1) + '"' + (radius ? ' rx="' + number(radius) + '" ry="' + number(radius) + '"' : '') + '/>');
+  }
+  function line(x, y, xx, yy, stroke, thickness, dash) {
+    include(x, y); include(xx, yy);
+    if (handwritten) {
+      var points = require('./salt-hand').line(xx - x, yy - y);
+      out.push('<path d="' + points.map(function (p, i) { return (i ? 'L' : 'M') + number(p[0] + x) + ',' + number(p[1] + y); }).join(' ') + '" fill="none" stroke="' + (stroke || '#000') + '" stroke-width="' + number(thickness || 1) + '"/>'); return;
+    }
+    out.push('<line x1="' + number(x) + '" y1="' + number(y) + '" x2="' + number(xx) + '" y2="' + number(yy) + '" stroke="' + (stroke || '#000') + '" stroke-width="' + number(thickness || 1) + '"' + (dash ? ' stroke-dasharray="' + dash + '"' : '') + '/>');
+  }
+  function ellipse(x, y, w, h, fill) {
+    include(x + w, y + h);
+    out.push('<ellipse cx="' + number(x + w / 2) + '" cy="' + number(y + h / 2) + '" rx="' + number(w / 2) + '" ry="' + number(h / 2) + '" fill="' + (fill || 'none') + '" stroke="#000" stroke-width="' + number(1.5) + '"/>');
+  }
+  function polygon(points, thickness) {
+    points.forEach(function (p) { include(p[0], p[1]); });
+    out.push('<polygon points="' + points.map(function (p) { return p.map(number).join(','); }).join(' ') + '" fill="#000" stroke="#000" stroke-linejoin="miter" stroke-miterlimit="10" stroke-width="' + number(thickness || 1) + '"/>');
+  }
+  function path(d, fill, stroke, maxX, maxY) {
+    include(maxX, maxY);
+    out.push('<path d="' + d.replace(/-?\d+(?:\.\d+)?/g, function (n) { return number(Number(n)); }) + '" fill="' + fill + '"' + (stroke ? ' stroke="' + stroke + '" stroke-width="' + number(1) + '"' : '') + '/>');
+  }
+  function label(label, x, y) {
+    include(x + label.width, y + label.height - Math.min(...label.runs.map(function (r) { return r.descent || 0; })));
+    if (label.list) {
+      var level = label.list.level;
+      if (label.list.type === 'number') {
+        var prefix = require('./salt-text').measureLabel(require('./salt-text').parseLabel('1. '));
+        var start = x + label.indent - prefix.width;
+        labelText(prefix.runs[0], start, y + label.height - prefix.runs[0].descent);
+      } else if (level === 1) out.push('<ellipse cx="' + number(x + 5.5) + '" cy="' + number(y + label.height - 7.5) + '" rx="' + number(2.5) + '" ry="' + number(2.5) + '" fill="#000"/>');
+      else out.push('<rect x="' + number(x + level * 8 - 7) + '" y="' + number(y + label.height - 10) + '" width="' + number(3.5) + '" height="' + number(3.5) + '" fill="#000"/>');
+      x += label.indent;
+    }
+    label.runs.forEach(function (run) {
+      ink = run.color || '#000';
+      if (run.icon) {
+        var iy = y + Math.max(0, label.height - 11);
+        require('./salt-text').icons[run.icon].forEach(function (d) {
+          var axis = 0;
+          var moved = d.replace(/-?\d+(?:\.\d+)?/g, function (n) { return number(Number(n) + (axis++ % 2 ? iy - 6 : x - 6)); });
+          out.push('<path d="' + moved + '" fill="' + (run.color || '#000') + '"/>');
+        });
+      }
+      if (run.image) out.push('<image x="' + number(x) + '" y="' + number(y + label.height - run.height) + '" width="' + number(run.width) + '" height="' + number(run.height) + '" href="' + run.image.data + '"/>');
+      if (run.displayText) labelText(run, x, y + label.height - run.descent);
+      x += run.width;
+    });
+  }
+  function labelText(run, x, baseline) {
+    var decoration = run.wave ? 'wavy underline' : run.underline && !run.underlineColor ? 'underline' : run.strike && !run.strikeColor ? 'line-through' : '';
+    var filter = '';
+    if (run.background) {
+      var id = filters[run.background];
+      if (!id) { id = 'salt-back-' + Object.keys(filters).length; filters[run.background] = id; out.push('<defs><filter id="' + id + '" x="0" y="0" width="1" height="1"><feFlood flood-color="' + run.background + '" result="flood"/><feComposite in="SourceGraphic" in2="flood" operator="over"/></filter></defs>'); }
+      filter = ' filter="url(#' + id + ')"';
+    }
+    out.push('<text x="' + number(x + run.leadingWidth) + '" y="' + number(baseline) + '" fill="' + (run.color || '#000') + '" font-size="' + number(run.size || 12) + '"' + (run.displayText.length > 1 ? ' textLength="' + number(run.displayWidth) + '"' : '') + (run.bold ? ' font-weight="700"' : '') + (run.italic ? ' font-style="italic"' : '') + (run.mono ? ' font-family="monospace"' : '') + (decoration ? ' text-decoration="' + decoration + '"' : '') + filter + '>' + escape(run.displayText) + '</text>');
+    var size = run.size || 12;
+    if (run.strike && run.strikeColor) line(x + run.leadingWidth, baseline - size / 4, x + run.leadingWidth + run.displayWidth, baseline - size / 4, run.strikeColor, size / 28);
+    if (run.underline && run.underlineColor) line(x + run.leadingWidth, baseline + size / 14, x + run.leadingWidth + run.displayWidth, baseline + size / 14, run.underlineColor, size / 28);
+  }
+  return { lastInk: function () { return ink; }, path: path, bounds: bounds, rect: rect, line: line, ellipse: ellipse, polygon: polygon, label: label };
+}
+module.exports = { createShapes: createShapes };