@khanglvm/relay 0.12.2 → 0.13.0

package/src/spec.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CliError } from './util.js';
 
-export const TYPES = ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color'];
+export const TYPES = ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color', 'rank', 'checklist', 'allocate'];
 
 const ALIASES = {
   radio: 'single',
@@ -21,13 +21,25 @@ const ALIASES = {
   likert: 'scale',
   colour: 'color',
   swatch: 'color',
+  ranking: 'rank',
+  order: 'rank',
+  ordering: 'rank',
+  prioritize: 'rank',
+  sort: 'rank',
+  signoff: 'checklist',
+  'sign-off': 'checklist',
+  qa: 'checklist',
+  allocation: 'allocate',
+  budget: 'allocate',
+  distribute: 'allocate',
+  points: 'allocate',
 };
 
 const HTML_HEIGHT = { min: 100, max: 2400, boardDefault: 400, questionDefault: 360 };
 
 // Block heights clamp to the same window; defaults vary per block type.
 const BLOCK_HEIGHT = { min: 100, max: 2400 };
-export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'diff', 'video', 'html', 'image', 'palette'];
+export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'diff', 'video', 'html', 'image', 'palette', 'kpi', 'typography', 'compare'];
 const CHART_KINDS = ['bar', 'line', 'pie', 'doughnut', 'radar', 'scatter'];
 
 // code/diff blocks may load their text from a local file (like htmlFile). Caps
@@ -107,6 +119,88 @@ function readTextSource(block, inlineKey, fileKey, cwd, where) {
   return '';
 }
 
+// Resolve an image source (shared by the `image` and `compare` blocks): an
+// http(s)/data URL passes through; a local file is read + embedded as a data
+// URI (capped) so the board stays self-contained offline.
+function resolveImageSrc(srcRaw, cwd, where, field) {
+  const src = asStr(srcRaw).trim();
+  if (!src) throw new CliError(`${where}: ${field} needs a "src" (http(s)/data URL or local file path).`);
+  if (/^(https?:|data:)/i.test(src)) return src;
+  const p = path.resolve(cwd, src);
+  const ext = path.extname(p).slice(1).toLowerCase();
+  const mime = IMAGE_MIMES[ext];
+  if (!mime) throw new CliError(`${where}: ${field}: unsupported image extension ".${ext}" — use ${Object.keys(IMAGE_MIMES).join('/')}, or an http(s)/data URL.`);
+  let buf;
+  try { buf = fs.readFileSync(p); } catch { throw new CliError(`${where}: ${field}: cannot read image "${src}" (resolved: ${p})`); }
+  if (buf.length > IMAGE_MAX_BYTES) throw new CliError(`${where}: ${field}: image "${src}" is ${(buf.length / 1024 / 1024).toFixed(1)}MB — max ${IMAGE_MAX_BYTES / 1024 / 1024}MB.`);
+  return `data:${mime};base64,${buf.toString('base64')}`;
+}
+
+// Minimal RFC-4180-ish CSV/TSV parser: handles quoted fields containing the
+// delimiter, embedded newlines, and "" escaped quotes. Returns an array of rows
+// (each an array of string cells). Library-free.
+function parseDelimited(text, delim) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQ = false;
+  const pushField = () => { row.push(field); field = ''; };
+  const pushRow = () => { pushField(); rows.push(row); row = []; };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQ) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++; } else inQ = false;
+      } else field += c;
+      continue;
+    }
+    if (c === '"') inQ = true;
+    else if (c === delim) pushField();
+    else if (c === '\n') pushRow();
+    else if (c === '\r') { /* swallow CR (CRLF) */ }
+    else field += c;
+  }
+  if (field.length || row.length) pushRow();
+  // drop a single trailing empty row from a final newline
+  if (rows.length && rows[rows.length - 1].length === 1 && rows[rows.length - 1][0] === '') rows.pop();
+  return rows;
+}
+
+// Load table {columns, rows} from a local .csv/.tsv/.json file (rowsFile).
+// CSV/TSV: first row = header → column keys. JSON: an array of objects (columns
+// from the union of keys) or arrays (needs explicit "columns").
+function loadRowsFile(file, cwd, where) {
+  const p = path.resolve(cwd, file);
+  let buf;
+  try { buf = fs.readFileSync(p); } catch { throw new CliError(`${where}: cannot read rowsFile "${file}" (resolved: ${p})`); }
+  if (buf.length > TEXT_FILE_MAX_BYTES) {
+    throw new CliError(`${where}: rowsFile "${file}" is ${(buf.length / 1024).toFixed(0)}KB — max ${TEXT_FILE_MAX_BYTES / 1024}KB.`);
+  }
+  const text = buf.toString('utf8');
+  const ext = path.extname(p).slice(1).toLowerCase();
+  if (ext === 'json') {
+    let data;
+    try { data = JSON.parse(text); } catch (e) { throw new CliError(`${where}: rowsFile "${file}" JSON parse error: ${e.message}`); }
+    if (!Array.isArray(data)) throw new CliError(`${where}: rowsFile "${file}" JSON must be an array of rows.`);
+    const cols = [];
+    for (const r of data) {
+      if (r && typeof r === 'object' && !Array.isArray(r)) {
+        for (const k of Object.keys(r)) if (!cols.includes(k)) cols.push(k);
+      }
+    }
+    return { columns: cols, rows: data };
+  }
+  const parsed = parseDelimited(text, ext === 'tsv' ? '\t' : ',');
+  if (!parsed.length) return { columns: [], rows: [] };
+  const header = parsed[0].map((h) => String(h).trim());
+  const rows = parsed.slice(1).map((cells) => {
+    const obj = {};
+    header.forEach((h, i) => { obj[h] = cells[i] !== undefined ? cells[i] : ''; });
+    return obj;
+  });
+  return { columns: header, rows };
+}
+
 // Recognizes a YouTube / Vimeo URL (or a bare YouTube id) and returns
 // {provider, videoId, start} for an iframe embed, else null. Cross-platform —
 // pure string parsing, no URL host assumptions beyond the known providers.
@@ -140,8 +234,8 @@ function normalizeBlock(rawBlock, id, cwd, where) {
   const hasHeight = rawBlock.height !== undefined && rawBlock.height !== null && rawBlock.height !== '';
 
   if (type === 'markdown') {
-    const md = asStr(rawBlock.md);
-    if (!md.trim()) throw new CliError(`${where}: markdown block needs a non-empty "md" string.`);
+    const md = readTextSource(rawBlock, 'md', 'mdFile', cwd, where);
+    if (!md.trim()) throw new CliError(`${where}: markdown block needs a non-empty "md" string or a readable "mdFile".`);
     const block = { id, type: 'markdown', md };
     if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
     return block;
@@ -294,13 +388,21 @@ function normalizeBlock(rawBlock, id, cwd, where) {
   }
 
   if (type === 'table') {
-    if (!Array.isArray(rawBlock.columns) || rawBlock.columns.length < 1) {
-      throw new CliError(`${where}: table needs a non-empty "columns" array (strings or {key,label,align?}).`);
+    // Rows/columns may come from a local .csv/.tsv/.json file instead of inline.
+    let rawColumns = rawBlock.columns;
+    let rawRows = rawBlock.rows;
+    if (typeof rawBlock.rowsFile === 'string' && rawBlock.rowsFile.trim() && !Array.isArray(rawRows)) {
+      const loaded = loadRowsFile(rawBlock.rowsFile, cwd, where);
+      rawRows = loaded.rows;
+      if (!Array.isArray(rawColumns) || !rawColumns.length) rawColumns = loaded.columns;
+    }
+    if (!Array.isArray(rawColumns) || rawColumns.length < 1) {
+      throw new CliError(`${where}: table needs a non-empty "columns" array (strings or {key,label,align?})${rawBlock.rowsFile ? ' — the rowsFile had no header/keys to infer them' : ''}.`);
     }
-    if (!Array.isArray(rawBlock.rows)) {
-      throw new CliError(`${where}: table needs a "rows" array.`);
+    if (!Array.isArray(rawRows)) {
+      throw new CliError(`${where}: table needs a "rows" array or a readable "rowsFile".`);
     }
-    const columns = rawBlock.columns.map((c, k) => {
+    const columns = rawColumns.map((c, k) => {
       if (typeof c === 'string' || typeof c === 'number') {
         const key = String(c);
         return { key, label: key };
@@ -316,7 +418,7 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     });
     // Normalize array rows into objects keyed by column key, so the client
     // (and table-cell annotation values) always index rows the same way.
-    const rows = rawBlock.rows.map((r, ri) => {
+    const rows = rawRows.map((r, ri) => {
       if (Array.isArray(r)) {
         const obj = {};
         columns.forEach((col, ci) => {
@@ -329,36 +431,75 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     });
     const block = { id, type: 'table', columns, rows };
     if (rawBlock.sortable === true) block.sortable = true;
+    if (rawBlock.filterable === true) block.filterable = true;
+    if (rawBlock.exportable === true) block.exportable = true;
     if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
     return block;
   }
 
   if (type === 'image') {
-    const src = asStr(rawBlock.src ?? rawBlock.file ?? rawBlock.url).trim();
-    if (!src) throw new CliError(`${where}: image block needs a "src" (http(s)/data URL or local file path).`);
     const block = { id, type: 'image' };
+    block.src = resolveImageSrc(rawBlock.src ?? rawBlock.file ?? rawBlock.url, cwd, where, 'image block');
     if (rawBlock.alt !== undefined) block.alt = asStr(rawBlock.alt);
     if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
-    if (/^(https?:|data:)/i.test(src)) {
-      block.src = src;
-      return block;
-    }
-    const p = path.resolve(cwd, src);
-    const ext = path.extname(p).slice(1).toLowerCase();
-    const mime = IMAGE_MIMES[ext];
-    if (!mime) {
-      throw new CliError(`${where}: unsupported image extension ".${ext}" — use ${Object.keys(IMAGE_MIMES).join('/')}, or an http(s)/data URL.`);
-    }
-    let buf;
-    try {
-      buf = fs.readFileSync(p);
-    } catch {
-      throw new CliError(`${where}: cannot read image "${src}" (resolved: ${p})`);
-    }
-    if (buf.length > IMAGE_MAX_BYTES) {
-      throw new CliError(`${where}: image "${src}" is ${(buf.length / 1024 / 1024).toFixed(1)}MB — max ${IMAGE_MAX_BYTES / 1024 / 1024}MB.`);
-    }
-    block.src = `data:${mime};base64,${buf.toString('base64')}`;
+    return block;
+  }
+
+  if (type === 'kpi') {
+    // Stat cards: a row of big-number metrics, each with an optional delta
+    // (up/down tinted) and sublabel. For "revenue ↑12%" at a glance, no chart.
+    const rawItems = Array.isArray(rawBlock.items) ? rawBlock.items : [];
+    if (!rawItems.length) throw new CliError(`${where}: kpi block needs a non-empty "items" array of {label, value, delta?, dir?, sub?}.`);
+    const items = rawItems.map((it, k) => {
+      if (it === null || typeof it !== 'object' || Array.isArray(it)) throw new CliError(`${where}.items[${k}]: must be an object {label, value, …}.`);
+      const out = { label: asStr(it.label), value: asStr(it.value) };
+      if (it.delta !== undefined && it.delta !== null && it.delta !== '') out.delta = asStr(it.delta);
+      const dir = asStr(it.dir ?? it.deltaDir).trim().toLowerCase();
+      if (dir === 'up' || dir === 'down' || dir === 'flat') out.dir = dir;
+      if (it.sub !== undefined) out.sub = asStr(it.sub);
+      return out;
+    });
+    const block = { id, type: 'kpi', items };
+    if (rawBlock.title !== undefined) block.title = asStr(rawBlock.title);
+    return block;
+  }
+
+  if (type === 'typography') {
+    // Type specimens: render sample text at given size/weight/font so a designer
+    // can react to type choices the way they react to a palette.
+    const raw = Array.isArray(rawBlock.specimens) ? rawBlock.specimens : (Array.isArray(rawBlock.samples) ? rawBlock.samples : []);
+    if (!raw.length) throw new CliError(`${where}: typography block needs a non-empty "specimens" array of {label?, size?, weight?, text?}.`);
+    const specimens = raw.map((s, k) => {
+      if (s === null || typeof s !== 'object' || Array.isArray(s)) throw new CliError(`${where}.specimens[${k}]: must be an object.`);
+      const out = { text: asStr(s.text ?? s.sample) || 'The quick brown fox jumps over the lazy dog' };
+      if (s.label !== undefined) out.label = asStr(s.label);
+      if (s.size !== undefined) out.size = asStr(s.size);
+      if (s.weight !== undefined) out.weight = asStr(s.weight);
+      if (s.font !== undefined) out.font = asStr(s.font);
+      const lh = s.lineHeight ?? s.leading;
+      if (lh !== undefined) out.lineHeight = asStr(lh);
+      const ls = s.letterSpacing ?? s.tracking;
+      if (ls !== undefined) out.letterSpacing = asStr(ls);
+      return out;
+    });
+    const block = { id, type: 'typography', specimens };
+    if (rawBlock.title !== undefined) block.title = asStr(rawBlock.title);
+    if (rawBlock.font !== undefined) block.font = asStr(rawBlock.font);
+    return block;
+  }
+
+  if (type === 'compare') {
+    // Before/after: two images with a draggable divider to compare a redesign.
+    const beforeRaw = rawBlock.before && typeof rawBlock.before === 'object' ? rawBlock.before.src : (rawBlock.before ?? rawBlock.beforeSrc);
+    const afterRaw = rawBlock.after && typeof rawBlock.after === 'object' ? rawBlock.after.src : (rawBlock.after ?? rawBlock.afterSrc);
+    const block = {
+      id, type: 'compare',
+      before: resolveImageSrc(beforeRaw, cwd, where, '"before"'),
+      after: resolveImageSrc(afterRaw, cwd, where, '"after"'),
+    };
+    block.beforeLabel = asStr(rawBlock.beforeLabel ?? (rawBlock.before && rawBlock.before.label) ?? 'Before') || 'Before';
+    block.afterLabel = asStr(rawBlock.afterLabel ?? (rawBlock.after && rawBlock.after.label) ?? 'After') || 'After';
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
     return block;
   }
 
@@ -429,7 +570,15 @@ function buildBlocks(rawObj, cwd, where, prefix) {
   if (rawObj.blocks !== undefined && rawObj.blocks !== null) {
     if (!Array.isArray(rawObj.blocks)) throw new CliError(`${where}.blocks: must be an array.`);
     rawObj.blocks.forEach((b, i) => {
-      blocks.push(normalizeBlock(b, nextId(), cwd, `${where}.blocks[${i}]`));
+      const nb = normalizeBlock(b, nextId(), cwd, `${where}.blocks[${i}]`);
+      // Cross-block fields handled uniformly so every block type supports them:
+      // `ref` = a stable name a markdown reference link can open in a modal;
+      // `pins` = enable coordinate pin-comments on an image.
+      if (b && typeof b === 'object') {
+        if (typeof b.ref === 'string' && b.ref.trim()) nb.ref = b.ref.trim();
+        if (nb.type === 'image' && b.pins === true) nb.pins = true;
+      }
+      blocks.push(nb);
     });
   }
   return blocks;
@@ -478,15 +627,17 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
       label,
       description: asStr(rq.description),
       required: rq.required === true,
-      // Radio (single) questions show the optional per-answer note by default so
-      // the user can qualify their pick; other types stay opt-in. An explicit
-      // note:false turns it off for a single question.
-      note: rq.note === undefined ? type === 'single' : rq.note === true,
+      // Decision types (single/rank/checklist/allocate) show the optional
+      // per-answer note by default so the user can qualify their pick; other
+      // types stay opt-in. An explicit note:false turns it off.
+      note: rq.note === undefined
+        ? (type === 'single' || type === 'rank' || type === 'checklist' || type === 'allocate')
+        : rq.note === true,
       blocks: buildBlocks(rq, cwd, where, `${id}-`),
       placeholder: asStr(rq.placeholder),
     };
 
-    if (type === 'single' || type === 'multi') {
+    if (type === 'single' || type === 'multi' || type === 'rank' || type === 'checklist' || type === 'allocate') {
       const opts = Array.isArray(rq.options) ? rq.options : [];
       q.options = opts.map((o, j) => {
         if (typeof o === 'string' || typeof o === 'number') {
@@ -507,13 +658,46 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
         }
         throw new CliError(`${where}.options[${j}]: must be a string or {value, label, description?, blocks?}.`);
       });
-      if (q.options.length < 1) {
-        throw new CliError(`${where}: type "${type}" needs at least 1 option.`);
+      const minOpts = type === 'rank' ? 2 : 1;
+      if (q.options.length < minOpts) {
+        throw new CliError(`${where}: type "${type}" needs at least ${minOpts} option${minOpts > 1 ? 's' : ''}.`);
       }
       // Radio (single) questions include an "Other" free-text option by default so
       // the user is never boxed into the listed choices; opt out with other:false.
       // Multi stays opt-in (checkbox lists are usually exhaustive on purpose).
-      q.other = type === 'single' ? rq.other !== false : rq.other === true;
+      // rank/checklist/allocate operate over a fixed set, so no "Other".
+      if (type === 'single' || type === 'multi') {
+        q.other = type === 'single' ? rq.other !== false : rq.other === true;
+      }
+    }
+
+    if (type === 'checklist') {
+      // Per-item status control. Default Pass / Fail / N/A; override with
+      // "statuses" (strings or {value,label,tone?}). tone colors the chip.
+      const rawSt = Array.isArray(rq.statuses) && rq.statuses.length
+        ? rq.statuses
+        : [{ value: 'pass', label: 'Pass', tone: 'ok' }, { value: 'fail', label: 'Fail', tone: 'bad' }, { value: 'na', label: 'N/A', tone: 'muted' }];
+      q.statuses = rawSt.map((s, k) => {
+        if (typeof s === 'string' || typeof s === 'number') {
+          const value = String(s).trim();
+          return { value, label: value === 'na' ? 'N/A' : value.charAt(0).toUpperCase() + value.slice(1) };
+        }
+        if (s && typeof s === 'object') {
+          const value = asStr(s.value ?? s.label).trim();
+          if (!value) throw new CliError(`${where}.statuses[${k}]: needs "value" or "label".`);
+          const out = { value, label: asStr(s.label ?? s.value) || value };
+          const tone = asStr(s.tone).trim().toLowerCase();
+          if (tone) out.tone = tone;
+          return out;
+        }
+        throw new CliError(`${where}.statuses[${k}]: must be a string or {value, label, tone?}.`);
+      });
+      if (q.statuses.length < 2) throw new CliError(`${where}: checklist needs ≥2 "statuses".`);
+    }
+
+    if (type === 'allocate') {
+      q.total = clampInt(rq.total, 1, 1000000, 100);
+      if (rq.unit !== undefined) q.unit = asStr(rq.unit);
     }
 
     if (type === 'scale') {
@@ -529,6 +713,23 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
         .map((c) => asStr(c).trim())
         .filter(Boolean);
       if (presets.length) q.presets = presets;
+      // Richer "pick from a palette": labeled swatch cards. Each click selects
+      // that color as the answer and each card is individually commentable.
+      // Items: a color string, or {value|color, label?}. Any CSS color system.
+      if (Array.isArray(rq.palette) && rq.palette.length) {
+        q.palette = rq.palette.map((p, k) => {
+          if (typeof p === 'string' || typeof p === 'number') {
+            const value = String(p).trim();
+            return { value, label: value };
+          }
+          if (p && typeof p === 'object') {
+            const value = asStr(p.value ?? p.color).trim();
+            if (!value) throw new CliError(`${where}.palette[${k}]: needs a "value" or "color".`);
+            return { value, label: asStr(p.label ?? p.name) || value };
+          }
+          throw new CliError(`${where}.palette[${k}]: must be a color string or {value/color, label?}.`);
+        }).filter((p) => p.value);
+      }
     }
 
     if (rq.default !== undefined) q.default = rq.default;
@@ -568,7 +769,8 @@ const BLOCK_SCHEMA = {
     required: ['type'],
     properties: {
       type: { type: 'string', enum: BLOCK_TYPES },
-      md: { type: 'string', description: 'markdown: built-in mini renderer (no external library) — headings, lists, code, quotes, links, and GFM pipe tables. Text selections are commentable. For real tabular data prefer a "table" block (sortable + per-cell comments).' },
+      md: { type: 'string', description: 'markdown: built-in mini renderer (no external library) — headings, lists, code, quotes, links, images, and GFM pipe tables. Text selections are commentable. For real tabular data prefer a "table" block (sortable + per-cell comments).' },
+      mdFile: { type: 'string', description: 'markdown: path to a local .md file to load + render instead of inline "md" (e.g. view a README/plan/report). Resolved against the CWD. Quick view of one or more files: `rly view a.md b.md`.' },
       code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); plantuml: the @startuml…@enduml source; code: the source to display (syntax-highlighted with line numbers).' },
       codeFile: { type: 'string', description: 'code: path to a local source file to load + display instead of inline "code". Resolved against the CWD; lang defaults from the file extension.' },
       filename: { type: 'string', description: 'code/diff: optional file name/path shown as a header label above the block.' },
@@ -594,7 +796,10 @@ const BLOCK_SCHEMA = {
         items: { anyOf: [{ type: 'string' }, { type: 'object' }] },
       },
       rows: { type: 'array', description: 'table: array of arrays (positional) or array of objects (keyed by column key).' },
+      rowsFile: { type: 'string', description: 'table: load rows from a local .csv/.tsv/.json file instead of inline "rows". CSV/TSV first row is the header (becomes "columns" if omitted); JSON is an array of objects. Resolved against the CWD. Quick view: `rly view data.csv`.' },
       sortable: { type: 'boolean', description: 'table: enable click-to-sort headers.' },
+      filterable: { type: 'boolean', description: 'table: show a filter box that live-filters rows by substring across all cells. Good for large tables.' },
+      exportable: { type: 'boolean', description: 'table: show a "CSV" button that downloads the (filtered) rows as a CSV file.' },
       html: { type: 'string', description: 'html: custom markup rendered in a sandboxed iframe.' },
       htmlFile: { type: 'string', description: 'html: path to an HTML file (alternative to "html").' },
       src: { type: 'string', description: 'image: http(s)/data URL, or a local file path (png/jpg/gif/webp/svg/avif/bmp — embedded at spec time, served offline). video: a YouTube/Vimeo URL (embeds an iframe player), an http(s) media URL, or a local video file (mp4/webm/ogv/mov/mkv/m4v — streamed from the server, never embedded).' },
@@ -619,7 +824,23 @@ const BLOCK_SCHEMA = {
       },
       colors: { type: 'array', items: { type: 'string' }, description: 'palette shorthand: colors for a single palette (use "palettes" for several named ones). Pairs with block-level "name".' },
       name: { type: 'string', description: 'palette shorthand: name for the single "colors" palette.' },
-      height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml/image natural (max 1200, scrolls).' },
+      items: {
+        type: 'array',
+        description: 'kpi: stat cards. Each {label, value, delta?, dir? (up|down|flat — tints the delta), sub?}. Big-number metrics at a glance ("Revenue $1.2M ↑12%") with no chart.',
+        items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' }, delta: { type: 'string' }, dir: { type: 'string', enum: ['up', 'down', 'flat'] }, sub: { type: 'string' } }, required: ['value'] },
+      },
+      specimens: {
+        type: 'array',
+        description: 'typography: type specimens rendered at the given style. Each {label?, size? (e.g. "32px"/"2rem"), weight? (e.g. "600"), font?, lineHeight?, letterSpacing?, text?}. Block-level "font" sets a default family.',
+        items: { type: 'object', properties: { label: { type: 'string' }, size: { type: 'string' }, weight: { type: 'string' }, font: { type: 'string' }, lineHeight: { type: 'string' }, letterSpacing: { type: 'string' }, text: { type: 'string' } } },
+      },
+      ref: { type: 'string', description: 'Any block: a stable name (e.g. "velocity") that a markdown reference link [see chart](#ref:velocity) can open in a full-screen modal — so a question can point back to a visual shown earlier instead of making the user scroll up.' },
+      pins: { type: 'boolean', description: 'image: enable coordinate pin-comments — the user clicks any point on the image to drop a comment anchored to that spot (Figma-style), returned as a {kind:"image-point", x, y} annotation.' },
+      before: { description: 'compare: the "before" image — an http(s)/data URL, a local file path, or {src, label}.' },
+      after: { description: 'compare: the "after" image — an http(s)/data URL, a local file path, or {src, label}.' },
+      beforeLabel: { type: 'string', description: 'compare: caption for the before side (default "Before").' },
+      afterLabel: { type: 'string', description: 'compare: caption for the after side (default "After").' },
+      height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml natural (max 800, scrolls; set a larger height to override); image/compare natural.' },
     },
   },
 };
@@ -648,13 +869,13 @@ export const SPEC_SCHEMA = {
         required: ['label'],
         properties: {
           id: { type: 'string', description: 'Answer key in the result JSON. Defaults to q1, q2, …' },
-          type: { type: 'string', enum: ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color'], default: 'text' },
+          type: { type: 'string', enum: ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color', 'rank', 'checklist', 'allocate'], default: 'text' },
           label: { type: 'string' },
           description: { type: 'string' },
           required: { type: 'boolean', default: false },
           options: {
             type: 'array',
-            description: 'For single/multi. Strings, or {value, label, description, blocks?}. An option\'s "blocks" render INSIDE that option card — use them to show each choice (image/chart/mermaid/html…) instead of describing it in words.',
+            description: 'For single/multi/rank/checklist/allocate. Strings, or {value, label, description, blocks?}. An option\'s "blocks" render INSIDE that option card — use them to show each choice (image/chart/mermaid/html…) instead of describing it in words. "rank": user reorders (drag/↑↓), answer is the ordered values, ≥2 options. "checklist": each option gets a status (see "statuses"), answer is {value: status}. "allocate": user distributes "total" across options, answer is {value: number}.',
             items: {
               anyOf: [
                 { type: 'string' },
@@ -671,14 +892,18 @@ export const SPEC_SCHEMA = {
             },
           },
           other: { type: 'boolean', description: 'Add a free-text "Other" option (a multi-line textarea); its text is returned verbatim as the value. Defaults ON for "single" (radio) questions so the user is never boxed in — set other:false to remove it; "multi" stays opt-in (other:true).' },
-          note: { type: 'boolean', description: 'Small optional free-text field under the question (to qualify an answer). Returned separately as result.notes[questionId]. Defaults to true for "single" (radio) questions so users can comment on their pick, false for other types; set note:false to hide it on a single question.' },
+          note: { type: 'boolean', description: 'Small optional free-text field under the question (to qualify an answer). Returned separately as result.notes[questionId]. Defaults to true for the decision types — single, rank, checklist, allocate — so users can qualify their pick; false for other types. Set note:false to hide it, note:true to add it.' },
           placeholder: { type: 'string', description: 'For text/textarea.' },
           default: { description: 'Pre-selected value. Shape matches the answer shape for the type.' },
           min: { type: 'integer', default: 1, description: 'scale only' },
           max: { type: 'integer', default: 5, maximum: 10, description: 'scale only' },
           minLabel: { type: 'string', description: 'scale only' },
           maxLabel: { type: 'string', description: 'scale only' },
-          presets: { type: 'array', items: { type: 'string' }, description: 'color only: optional preset swatches (CSS colors) shown beside the native picker for one-click selection. The answer is returned as a hex string.' },
+          presets: { type: 'array', items: { type: 'string' }, description: 'color only: optional small preset swatches (CSS colors) shown beside the native picker for one-click selection. The answer is returned as a color string.' },
+          palette: { type: 'array', description: 'color only: a "pick from a palette" of labeled swatch CARDS — each click selects that color as the answer, and each card is individually commentable (per-color feedback). Items: a CSS color string (hex/rgb/hsl/named — multiple color systems supported via the browser, no library), or {value (or color), label?}. The native picker stays available for a custom color.', items: { anyOf: [{ type: 'string' }, { type: 'object' }] } },
+          statuses: { type: 'array', description: 'checklist only: the per-item statuses (default Pass / Fail / N/A). Strings, or {value, label, tone?} where tone ∈ ok|bad|muted|warn tints the chip. Answer is a map {optionValue: statusValue} for the items the user set.', items: { anyOf: [{ type: 'string' }, { type: 'object' }] } },
+          total: { type: 'integer', minimum: 1, default: 100, description: 'allocate only: the budget to distribute across options (default 100). Answer is a map {optionValue: number}.' },
+          unit: { type: 'string', description: 'allocate only: optional unit label shown next to the total (e.g. "%", "pts", "hrs").' },
           blocks: BLOCK_SCHEMA,
           html: { type: 'string', description: 'Legacy: per-question custom HTML. Normalized into an html block prepended to this question\'s "blocks".' },
           htmlFile: { type: 'string', description: 'Legacy: path to an HTML file (alternative to "html").' },

package/src/ui/annotate.css

@@ -48,12 +48,22 @@
   padding: 12px 14px;
   font: 14px/1.5 var(--sans);
 }
+.ann-pop-head { display: flex; align-items: flex-start; gap: 8px; margin-bottom: 8px; }
 .ann-pop-label {
+  flex: 1; min-width: 0;
   color: var(--muted);
   font-size: 0.78rem;
-  margin-bottom: 8px;
   overflow-wrap: anywhere;
 }
+.ann-pop-close {
+  flex: none; margin: -4px -4px 0 0;
+  background: transparent; color: var(--muted);
+  border: none; border-radius: 7px;
+  width: 26px; height: 26px;
+  font-size: 1.25rem; line-height: 1; cursor: pointer;
+  transition: color 150ms var(--ease), background 150ms var(--ease);
+}
+.ann-pop-close:hover { color: var(--fg); background: var(--bg-sunken); }
 .ann-pop-existing { margin-bottom: 8px; max-height: min(50vh, 420px); overflow-y: auto; }
 .ann-pop-existing:empty { display: none; margin: 0; }
 
@@ -63,8 +73,10 @@
   border-top: 1px solid var(--border);
 }
 .ann-thread-head { display: flex; align-items: center; gap: 6px; }
-.ann-thread-head .ann-del { margin-left: auto; }
+.ann-thread-actions { margin-left: auto; display: flex; align-items: center; gap: 4px; }
 .ann-pop-text { font-size: 0.88rem; white-space: pre-wrap; overflow-wrap: anywhere; }
+.ann-edit-form { margin-top: 4px; }
+.ann-edit-ta { width: 100%; }
 
 /* author chips: "you" muted, "agent" accent */
 .ann-chip {
@@ -146,16 +158,61 @@
 .ann-cancel:hover { border-color: var(--accent); color: var(--accent); }
 
 /* delete button (popover items + summary rows): muted, danger on hover */
+/* Delete = a trash icon button, visually distinct from the close ×. */
 .ann-del {
   flex: none;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: transparent; color: var(--muted);
+  border: none; border-radius: 7px;
+  width: 26px; height: 26px;
+  cursor: pointer;
+  transition: color 150ms var(--ease), background 150ms var(--ease);
+}
+.ann-del:hover { color: var(--danger); background: var(--accent-soft); }
+
+/* edit button: same shape as delete, accent (not danger) on hover */
+.ann-edit {
+  flex: none;
+  display: inline-flex; align-items: center; justify-content: center;
   background: transparent; color: var(--muted);
-  border: none; border-radius: 6px;
-  padding: 2px 6px;
-  font-size: 1.05rem; line-height: 1;
+  border: none; border-radius: 7px;
+  width: 26px; height: 26px;
   cursor: pointer;
-  transition: color 150ms var(--ease);
+  transition: color 150ms var(--ease), background 150ms var(--ease);
 }
-.ann-del:hover { color: var(--danger); }
+.ann-edit:hover { color: var(--accent); background: var(--accent-soft); }
+
+/* ---------- delete confirmation modal ---------- */
+.ann-confirm-scrim {
+  position: fixed; inset: 0; z-index: 80;
+  background: rgba(28, 27, 25, 0.4);
+  display: flex; align-items: center; justify-content: center;
+  padding: 20px;
+}
+.ann-confirm {
+  width: min(360px, 92vw);
+  background: var(--card); color: var(--fg);
+  border: 1px solid var(--border); border-radius: 14px;
+  box-shadow: var(--shadow-lift);
+  padding: 20px;
+  font: 14px/1.5 var(--sans);
+}
+.ann-confirm-title { font: 600 1.05rem var(--sans); margin-bottom: 6px; }
+.ann-confirm-msg { color: var(--fg-2); font-size: 0.9rem; }
+.ann-confirm-skip {
+  display: flex; align-items: center; gap: 8px;
+  margin: 14px 0 4px; color: var(--fg-2); font-size: 0.85rem; cursor: pointer;
+}
+.ann-confirm-skip input { width: 15px; height: 15px; accent-color: var(--accent); cursor: pointer; }
+.ann-confirm-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 16px; }
+.ann-confirm-cancel, .ann-confirm-del {
+  border-radius: 9px; padding: 8px 16px; font: 600 0.88rem var(--sans); cursor: pointer;
+  border: 1px solid var(--border-strong); transition: all 150ms var(--ease);
+}
+.ann-confirm-cancel { background: var(--card); color: var(--fg-2); }
+.ann-confirm-cancel:hover { background: var(--bg-sunken); color: var(--fg); }
+.ann-confirm-del { background: var(--danger); color: var(--danger-fg); border-color: var(--danger); }
+.ann-confirm-del:hover { filter: brightness(1.06); }
 
 /* ---------- floating selection button ---------- */
 .ann-selbtn {
@@ -274,9 +331,8 @@
 .ann-rail-list .ann-sum-row + .ann-sum-row { border-top: 1px solid var(--border); }
 .ann-rail-list .ann-sum-row:hover { border-color: var(--accent); box-shadow: var(--shadow-card); }
 
-/* The rail always overlays the board (scrim dims, content never moves) — opening
-   it must NOT shift layout, on any width. It's reached only via the floating
-   Comments button, which flashes when a new comment lands. */
+/* The rail NEVER auto-opens (that shifted the board unexpectedly) — it's reached
+   only via the floating Comments button, which flashes when a new comment lands. */
 @keyframes ann-toggle-pulse {
   0% { transform: scale(1); }
   35% { transform: scale(1.12); box-shadow: 0 0 0 4px var(--accent-soft); }
@@ -284,6 +340,15 @@
 }
 .ann-rail-toggle.pulse { animation: ann-toggle-pulse 600ms var(--ease); border-color: var(--accent); color: var(--accent); }
 
+/* When opened on a roomy screen, the rail DOCKS and consumes page space (pushes
+   content) instead of covering it — so the board stays visible beside it and
+   clicking a comment reveals the highlighted item in the page. No scrim while
+   docked. Narrow screens fall back to an overlay + scrim (no room to dock). */
+@media (min-width: 980px) {
+  .ann-rail-scrim { display: none !important; }
+  body.ann-rail-open { padding-right: 340px; }
+}
+
 /* ---------- jump-to flash ---------- */
 .ann-flash { animation: ann-flash 1s var(--ease); }
 @keyframes ann-flash {