@webship.co/workspace 0.0.0-stage → 1.0.0-alpha1

package/images-svg-core.js

@@ -0,0 +1,214 @@
+/**
+ * The pure half of the SVG generator: the prompt, reading a reply, the substance check, the transform repair and
+ * the draw-in motion. No dependencies beyond the sanitiser, so the dashboard and the host-side finish step of a
+ * Claude Code drawing run the same checks.
+ */
+
+const { sanitizeSvg, removedSummary, tokens, parseTag, DRAWABLE } = require('./images-svg-sanitize');
+
+const STYLES = { still: 'Still', draw: 'Draw the strokes', css: 'CSS keyframes', smil: 'SMIL' };
+const SHAPES = { wide: [960, 400], landscape: [960, 640], square: [800, 800] };
+const SHAPE_LABELS = { wide: 'Wide, 960×400', landscape: 'Landscape, 960×640', square: 'Square, 800×800' };
+const MOTION = { animation: 'draw-rise', duration: 1100, stagger: 110, replay: true, threshold: 0.25 };
+const MIN_DRAWABLE = 4;
+const MIN_PARTS = 4;
+const STROKED = new Set(['path', 'line', 'polyline', 'polygon', 'circle', 'ellipse', 'rect']);
+
+const STYLE_RULES = {
+  still: 'A still drawing: no animation of any kind.',
+  draw: 'Stroke only: every shape has fill="none" and an explicit stroke colour and stroke-width, with round line caps. '
+    + 'No filled shapes and no animation: the drawing is animated for you, part by part, by tracing its strokes.',
+  css: 'Animate it with ONE <style> element holding @keyframes, on classed elements, wrapped in '
+    + '@media (prefers-reduced-motion: no-preference) so a reader who asks for less motion sees the finished drawing. '
+    + 'Animations run once and end on the finished drawing (animation-fill-mode: both). Never put a transform attribute on '
+    + 'an element you animate with CSS: put it on a wrapping <g> instead.',
+  smil: 'Animate it with SMIL (<animate>, <animateTransform>), begin times staggered part by part, fill="freeze", '
+    + 'ending on the finished drawing. Never animate href, style, class or an event attribute.',
+};
+
+/** The palette as words a model can follow. */
+function paletteLine(palette) {
+  return Object.entries(palette).map(([k, v]) => `${k} ${v}`).join(', ');
+}
+
+/**
+ * The system and user prompt. `files` asks for two files (Claude Code) instead of a JSON reply.
+ */
+function buildPrompt({ prompt, style, palette, brief, shape, files = null }) {
+  const [w, h] = SHAPES[shape] || SHAPES.wide;
+  const out = files
+    ? `Write exactly two files in the current folder and nothing else:\n1. ${files.svg}: the SVG.\n2. ${files.words}: {"summary": "one or two plain sentences on what it shows", "alt": "alt text, at most 125 characters"}.\nDo not run any commands. When both files are written, stop.`
+    : 'Answer with JSON only: {"svg": "the whole SVG", "summary": "one or two plain sentences on what it shows", "alt": "alt text, at most 125 characters"}.';
+  const system = `You draw illustrations as SVG code for a website.
+${brief ? `The brief: ${brief}\n` : ''}
+Rules:
+- One <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}"> root, with no width or height attribute.
+- 5 to 9 top-level parts, each a <g class="part"> in reading order, and every shape inside a part. At least ${MIN_DRAWABLE} drawable elements in all.
+- Only these colours: ${paletteLine(palette)}. Tints by opacity are fine.
+- No <script>, <foreignObject>, <image>, event handlers or external links; url() and href may point only at an id in this file.
+- No text unless the request asks for it, and never a logo or a brand name.
+- ${STYLE_RULES[style] || STYLE_RULES.still}
+
+${out}`;
+  return { system, user: `Draw: ${prompt}` };
+}
+
+/** The SVG, summary and alt text out of a reply: JSON, JSON in a fence, or bare markup. */
+function parseReply(text) {
+  const t = String(text || '');
+  const a = t.indexOf('{');
+  const b = t.lastIndexOf('}');
+  if (a >= 0 && b > a) {
+    try {
+      const j = JSON.parse(t.slice(a, b + 1));
+      if (j && typeof j.svg === 'string') return { svg: j.svg, summary: String(j.summary || '').trim().slice(0, 600), alt: String(j.alt || '').trim().slice(0, 125) };
+    } catch (_) { /* not JSON, try the markup */ }
+  }
+  const m = t.match(/<svg[\s>][\s\S]*<\/svg>/i);
+  return { svg: m ? m[0] : '', summary: '', alt: '' };
+}
+
+/** The root <svg> tag's attributes, as a map. */
+function rootAttrs(svg) {
+  const m = svg.match(/<svg\b[^>]*>/i);
+  const tag = m && parseTag(m[0].replace(/\/>$/, '>'));
+  return tag ? Object.fromEntries(tag.attrs) : null;
+}
+
+/** Fix the root: a viewBox from width and height when it has none, then no width or height. */
+function fixRoot(svg) {
+  const attrs = rootAttrs(svg);
+  if (!attrs) return svg;
+  let tag = svg.match(/<svg\b[^>]*>/i)[0];
+  const num = (v) => parseFloat(String(v || '').replace(/px$/, ''));
+  if (!attrs.viewBox && num(attrs.width) > 0 && num(attrs.height) > 0) {
+    tag = tag.replace(/<svg\b/i, `<svg viewBox="0 0 ${num(attrs.width)} ${num(attrs.height)}"`);
+  }
+  tag = tag.replace(/\s(width|height)="[^"]*"/g, '');
+  return svg.replace(/<svg\b[^>]*>/i, tag);
+}
+
+/** Whether a drawing has enough in it, or why not, in words a model can act on. */
+function substance(svg) {
+  const attrs = rootAttrs(svg);
+  if (!attrs) return { ok: false, why: 'There is no <svg> root.', drawable: 0, parts: 0 };
+  const drawable = (svg.match(new RegExp(`<(${[...DRAWABLE].join('|')})\\b`, 'g')) || []).length;
+  const parts = (svg.match(/\bclass="[^"]*\bpart\b[^"]*"/g) || []).length;
+  const whys = [];
+  if (!attrs.viewBox) whys.push('the root has no viewBox');
+  if (attrs.width || attrs.height) whys.push('the root has a width or height');
+  if (drawable < MIN_DRAWABLE) whys.push(`it has ${drawable} drawable element${drawable === 1 ? '' : 's'}, and it needs at least ${MIN_DRAWABLE}`);
+  if (parts < MIN_PARTS) whys.push(`it has ${parts} <g class="part"> group${parts === 1 ? '' : 's'}, and it needs at least ${MIN_PARTS}`);
+  return { ok: !whys.length, why: whys.length ? `The drawing was not used: ${whys.join('; ')}.` : '', drawable, parts };
+}
+
+/** The classes a <style> animates. */
+function animatedClasses(svg) {
+  const out = new Set();
+  for (const m of svg.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+    for (const r of m[1].matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+      if (!/animation/i.test(r[2])) continue;
+      for (const c of r[1].matchAll(/\.([A-Za-z_][\w-]*)/g)) out.add(c[1]);
+    }
+  }
+  return out;
+}
+
+/**
+ * A CSS animation that sets transform overrides the element's own transform attribute, so a drawing that is
+ * placed with one jumps when it animates. Move such a transform onto a wrapping <g>. Returns { svg, moved }.
+ */
+function repairTransforms(svg, extra = []) {
+  const classes = animatedClasses(svg);
+  for (const c of extra) classes.add(c);
+  if (!classes.size) return { svg, moved: 0 };
+  const out = [];
+  const wraps = [];
+  let moved = 0;
+  for (const t of tokens(svg)) {
+    const tag = t.startsWith('<') && !t.startsWith('<!') && !t.startsWith('<?') ? parseTag(t) : null;
+    if (!tag) { out.push(t); continue; }
+    if (tag.close) {
+      out.push(t);
+      const w = wraps.pop();
+      if (w) out.push('</g>');
+      continue;
+    }
+    const cls = (tag.attrs.find(([k]) => k === 'class') || [])[1] || '';
+    const tf = tag.attrs.find(([k]) => k === 'transform');
+    const hit = tag.name !== 'svg' && tf && cls.split(/\s+/).some((c) => classes.has(c));
+    if (hit) {
+      moved += 1;
+      const rest = t.replace(/\stransform\s*=\s*("[^"]*"|'[^']*')/, '');
+      out.push(`<g transform="${tf[1].replace(/"/g, '&quot;')}">`, rest);
+      if (tag.self) out.push('</g>'); else wraps.push(true);
+    } else {
+      out.push(t);
+      if (!tag.self) wraps.push(false);
+    }
+  }
+  return { svg: out.join(''), moved };
+}
+
+/**
+ * The draw-in motion, written into the file so it plays anywhere: each part rises into place in turn, and its
+ * strokes are traced by length (pathLength="1", so no script has to measure them). Reduced motion gets the finished drawing.
+ */
+function addDrawMotion(svg, motion = MOTION) {
+  const out = [];
+  let depth = 0;
+  let part = -1;
+  let inPart = 0;
+  for (const t of tokens(svg)) {
+    const tag = t.startsWith('<') && !t.startsWith('<!') && !t.startsWith('<?') ? parseTag(t) : null;
+    if (!tag) { out.push(t); continue; }
+    if (tag.close) {
+      depth -= 1;
+      if (inPart && depth < inPart) inPart = 0;
+      out.push(t);
+      continue;
+    }
+    let s = t;
+    const cls = (tag.attrs.find(([k]) => k === 'class') || [])[1] || '';
+    if (!inPart && /\bpart\b/.test(cls)) {
+      part += 1;
+      const style = (tag.attrs.find(([k]) => k === 'style') || [])[1];
+      s = style !== undefined ? s.replace(/\sstyle="[^"]*"/, ` style="--i:${part};${style.replace(/"/g, '&quot;')}"`) : s.replace(/^<([\w:-]+)/, `<$1 style="--i:${part}"`);
+      if (!tag.self) inPart = depth + 1;
+    } else if (inPart && STROKED.has(tag.name) && !tag.attrs.some(([k]) => k === 'pathLength')) {
+      s = s.replace(/^<([\w:-]+)/, '<$1 pathLength="1"');
+    }
+    if (!tag.self) depth += 1;
+    out.push(s);
+  }
+  const d = Number(motion.duration) || MOTION.duration;
+  const st = Number(motion.stagger) || MOTION.stagger;
+  const css = `<style>@media (prefers-reduced-motion: no-preference){`
+    + `.part{animation:part-rise ${d}ms cubic-bezier(.2,.7,.2,1) both;animation-delay:calc(var(--i,0)*${st}ms)}`
+    + `.part [pathLength]{stroke-dasharray:1;stroke-dashoffset:1;animation:part-draw ${d}ms ease-out forwards;animation-delay:calc(var(--i,0)*${st}ms)}`
+    + `@keyframes part-draw{to{stroke-dashoffset:0}}`
+    + `@keyframes part-rise{from{opacity:0;transform:translateY(16px)}to{opacity:1;transform:none}}}</style>`;
+  return out.join('').replace(/(<svg\b[^>]*>)/i, `$1${css}`);
+}
+
+/**
+ * Everything a drawing goes through after the model: sanitise, fix the root, repair transforms, check it, and
+ * add the draw-in motion for that style. Returns { ok, svg, why, note, drawable, parts, moved }.
+ */
+function finish(raw, { style, motion = MOTION } = {}) {
+  const clean = sanitizeSvg(raw);
+  const note = removedSummary(clean);
+  if (!clean.svg) return { ok: false, why: 'The answer held no <svg> drawing. Answer with the whole SVG.', note };
+  if (clean.drawableLost) {
+    return { ok: false, note, why: `The drawing used markup that is not allowed (${note}), and ${clean.drawableLost} drawable element${clean.drawableLost === 1 ? ' was' : 's were'} lost with it. Draw it again with plain SVG shapes only.` };
+  }
+  const rooted = fixRoot(clean.svg);
+  const rep = repairTransforms(rooted, style === 'draw' ? ['part'] : []);
+  const chk = substance(rep.svg);
+  if (!chk.ok) return { ok: false, why: chk.why, note, drawable: chk.drawable, parts: chk.parts };
+  const svg = style === 'draw' ? addDrawMotion(rep.svg, motion) : rep.svg;
+  return { ok: true, svg, note, drawable: chk.drawable, parts: chk.parts, moved: rep.moved };
+}
+
+module.exports = { STYLES, SHAPES, SHAPE_LABELS, MOTION, MIN_DRAWABLE, MIN_PARTS, buildPrompt, parseReply, paletteLine,
+  substance, fixRoot, repairTransforms, animatedClasses, addDrawMotion, finish };

package/images-svg-sanitize.js

@@ -0,0 +1,188 @@
+/**
+ * An allow-list SVG sanitiser, for markup an AI wrote. It keeps drawing, text, gradients, styles and
+ * animation; it drops scripts, foreignObject, embedded images, event handlers and every reference that leaves
+ * the file. It says what it removed, so a caller can tell a harmless clean-up from a drawing that lost its parts.
+ * No dependencies: the host-side finish step of a Claude Code drawing runs it too.
+ */
+
+const DRAWABLE = new Set(['path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'text', 'use']);
+
+const ELEMENTS = new Set([
+  'svg', 'g', 'defs', 'symbol', 'use', 'title', 'desc', 'metadata', 'style',
+  'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'text', 'tspan', 'textPath',
+  'linearGradient', 'radialGradient', 'stop', 'clipPath', 'mask', 'pattern', 'marker',
+  'filter', 'feGaussianBlur', 'feOffset', 'feBlend', 'feColorMatrix', 'feComposite', 'feFlood', 'feMerge',
+  'feMergeNode', 'feDropShadow', 'feMorphology', 'feTurbulence', 'feDisplacementMap',
+  'animate', 'animateTransform', 'animateMotion', 'set', 'mpath',
+]);
+
+// Removed with everything inside them.
+const DROP = new Set(['script', 'foreignObject', 'image', 'iframe', 'object', 'embed', 'audio', 'video', 'canvas', 'handler', 'listener']);
+// Removed, their children kept.
+const UNWRAP = new Set(['a', 'switch']);
+
+const ATTRS = new Set([
+  'id', 'class', 'style', 'viewBox', 'preserveAspectRatio', 'xmlns', 'xmlns:xlink', 'version', 'role', 'aria-label',
+  'aria-hidden', 'aria-labelledby', 'aria-describedby', 'focusable', 'lang', 'xml:space', 'href', 'xlink:href',
+  'x', 'y', 'x1', 'y1', 'x2', 'y2', 'cx', 'cy', 'r', 'rx', 'ry', 'fx', 'fy', 'fr', 'd', 'points', 'width', 'height',
+  'dx', 'dy', 'rotate', 'textLength', 'lengthAdjust', 'pathLength', 'startOffset', 'method', 'spacing', 'side',
+  'transform', 'transform-origin', 'opacity', 'fill', 'fill-opacity', 'fill-rule', 'stroke', 'stroke-width',
+  'stroke-linecap', 'stroke-linejoin', 'stroke-miterlimit', 'stroke-dasharray', 'stroke-dashoffset', 'stroke-opacity',
+  'vector-effect', 'paint-order', 'color', 'display', 'visibility', 'overflow', 'clip-path', 'clip-rule', 'mask', 'filter',
+  'marker-start', 'marker-mid', 'marker-end', 'font-family', 'font-size', 'font-weight', 'font-style', 'letter-spacing',
+  'word-spacing', 'text-anchor', 'dominant-baseline', 'alignment-baseline', 'text-decoration',
+  'offset', 'stop-color', 'stop-opacity', 'gradientUnits', 'gradientTransform', 'spreadMethod',
+  'patternUnits', 'patternContentUnits', 'patternTransform', 'clipPathUnits', 'maskUnits', 'maskContentUnits',
+  'markerWidth', 'markerHeight', 'markerUnits', 'refX', 'refY', 'orient',
+  'filterUnits', 'primitiveUnits', 'in', 'in2', 'result', 'stdDeviation', 'mode', 'values', 'type', 'operator',
+  'k1', 'k2', 'k3', 'k4', 'flood-color', 'flood-opacity', 'radius', 'baseFrequency', 'numOctaves', 'seed',
+  'stitchTiles', 'scale', 'xChannelSelector', 'yChannelSelector',
+  'attributeName', 'attributeType', 'from', 'to', 'by', 'begin', 'dur', 'end', 'repeatCount', 'repeatDur', 'fill',
+  'calcMode', 'keyTimes', 'keySplines', 'keyPoints', 'additive', 'accumulate', 'restart', 'min', 'max', 'path',
+]);
+
+// An animation may not change these: a link or a handler set by SMIL is a script by another route.
+const UNANIMATABLE = /^(href|xlink:href|on.*|style|class)$/i;
+
+const escAttr = (v) => String(v).replace(/&(?!(#\d+|#x[0-9a-f]+|[a-z]+);)/gi, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+
+/** CSS with every way out of the file removed. Returns [css, changed]. */
+function cleanCss(css) {
+  const before = css;
+  const out = css
+    .replace(/@import[^;]*;?/gi, '')
+    .replace(/url\(\s*(['"]?)(?!#)[^)]*\1\s*\)/gi, 'none')
+    .replace(/expression\s*\(/gi, '(')
+    .replace(/-moz-binding|behavior\s*:/gi, '')
+    .replace(/javascript:/gi, '');
+  return [out, out !== before];
+}
+
+/** An attribute value that refers to something: only a fragment in this file is allowed. */
+function localRef(v) {
+  return /^\s*#[A-Za-z_][\w.:-]*\s*$/.test(v);
+}
+
+/** Every tag and the text between them, in order. */
+function tokens(src) {
+  const out = [];
+  const re = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<![^>]*>|<\?[\s\S]*?\?>|<\/?[A-Za-z][^>]*>|[^<]+|</g;
+  let m;
+  while ((m = re.exec(src))) out.push(m[0]);
+  return out;
+}
+
+function parseTag(t) {
+  const m = t.match(/^<(\/?)([A-Za-z][\w:.-]*)([\s\S]*?)(\/?)>$/);
+  if (!m) return null;
+  const attrs = [];
+  const re = /([^\s=/>]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]+))?/g;
+  let a;
+  while ((a = re.exec(m[3]))) attrs.push([a[1], a[2] === undefined ? '' : a[2].replace(/^["']|["']$/g, '')]);
+  return { close: !!m[1], name: m[2], attrs, self: !!m[4] };
+}
+
+/**
+ * Sanitise SVG markup. Returns { svg, removed: { elements: {name: n}, attributes: n, css: n }, drawableLost, drawable }.
+ * `svg` is '' when there is no <svg> root at all.
+ */
+function sanitizeSvg(input) {
+  const src = String(input || '');
+  const start = src.search(/<svg[\s>]/i);
+  const end = src.lastIndexOf('</svg>');
+  const removed = { elements: {}, attributes: 0, css: 0 };
+  if (start < 0 || end < start) return { svg: '', removed, drawableLost: 0, drawable: 0 };
+  const parts = [];
+  const stack = []; // the open elements: { name, keep }
+  let dropDepth = 0;
+  let drawable = 0;
+  let drawableLost = 0;
+  const note = (n) => { removed.elements[n] = (removed.elements[n] || 0) + 1; };
+  const inStyle = () => stack.length && stack[stack.length - 1].name === 'style' && stack[stack.length - 1].keep;
+  for (const t of tokens(src.slice(start, end + 6))) {
+    if (t.startsWith('<!--') || t.startsWith('<?') || (t.startsWith('<!') && !t.startsWith('<![CDATA['))) continue;
+    if (!t.startsWith('<') || t.startsWith('<![CDATA[') || t === '<') {
+      if (dropDepth) continue;
+      if (t === '<') { parts.push('&lt;'); continue; }
+      if (inStyle()) {
+        const [css, changed] = cleanCss(t);
+        if (changed) removed.css += 1;
+        parts.push(css);
+      } else if (t.startsWith('<![CDATA[')) {
+        parts.push(t.slice(9, -3).replace(/&/g, '&amp;').replace(/</g, '&lt;'));
+      } else {
+        parts.push(t);
+      }
+      continue;
+    }
+    const tag = parseTag(t);
+    if (!tag) continue;
+    if (tag.close) {
+      const open = stack.pop();
+      if (!open) continue;
+      if (open.drop) { dropDepth -= 1; continue; }
+      if (!dropDepth && open.keep) parts.push(`</${open.name}>`);
+      continue;
+    }
+    const name = tag.name;
+    const known = ELEMENTS.has(name);
+    const drop = dropDepth > 0 || DROP.has(name) || (!known && !UNWRAP.has(name));
+    if (drop) {
+      if (DRAWABLE.has(name)) drawableLost += 1;
+      if (!dropDepth) note(name);
+      if (!tag.self) { stack.push({ name, drop: true }); dropDepth += 1; }
+      continue;
+    }
+    if (UNWRAP.has(name)) {
+      note(name);
+      if (!tag.self) stack.push({ name, keep: false });
+      continue;
+    }
+    // An animation that would set a link, a handler or a style is dropped whole.
+    const target = (tag.attrs.find(([k]) => k === 'attributeName') || [])[1];
+    if (/^(animate|set|animateTransform|animateMotion)$/.test(name) && target && UNANIMATABLE.test(target)) {
+      note(name);
+      if (!tag.self) { stack.push({ name, drop: true }); dropDepth += 1; }
+      continue;
+    }
+    const kept = [];
+    for (const [k, raw] of tag.attrs) {
+      const v = raw;
+      if (!ATTRS.has(k) && !/^data-[\w-]+$/.test(k)) { removed.attributes += 1; continue; }
+      if ((k === 'href' || k === 'xlink:href') && !localRef(v)) { removed.attributes += 1; continue; }
+      if (/javascript:|vbscript:|data:/i.test(v) && k !== 'd') { removed.attributes += 1; continue; }
+      if (/url\(/i.test(v)) {
+        const urls = v.match(/url\(\s*(['"]?)([^)'"]*)\1\s*\)/gi) || [];
+        if (urls.some((u) => !/url\(\s*['"]?#/i.test(u))) { removed.attributes += 1; continue; }
+      }
+      let value = v;
+      if (k === 'style') {
+        const [css, changed] = cleanCss(v);
+        if (changed) removed.css += 1;
+        value = css;
+      }
+      kept.push(`${k}="${escAttr(value)}"`);
+    }
+    if (name === 'svg' && !kept.some((a) => a.startsWith('xmlns='))) kept.unshift('xmlns="http://www.w3.org/2000/svg"');
+    if (DRAWABLE.has(name)) drawable += 1;
+    parts.push(`<${name}${kept.length ? ` ${kept.join(' ')}` : ''}${tag.self ? '/>' : '>'}`);
+    if (!tag.self) stack.push({ name, keep: true });
+  }
+  while (stack.length) {
+    const open = stack.pop();
+    if (open.keep) parts.push(`</${open.name}>`);
+  }
+  return { svg: parts.join(''), removed, drawableLost, drawable };
+}
+
+/** A one-line account of what was removed, or '' when nothing was. */
+function removedSummary(r) {
+  const els = Object.entries(r.removed.elements).map(([k, n]) => `${n} ${k}`);
+  const bits = [];
+  if (els.length) bits.push(`elements: ${els.join(', ')}`);
+  if (r.removed.attributes) bits.push(`${r.removed.attributes} attribute${r.removed.attributes === 1 ? '' : 's'}`);
+  if (r.removed.css) bits.push(`${r.removed.css} unsafe style rule${r.removed.css === 1 ? '' : 's'}`);
+  return bits.join('; ');
+}
+
+module.exports = { sanitizeSvg, removedSummary, cleanCss, tokens, parseTag, DRAWABLE, ELEMENTS };

package/images-svg.js

@@ -0,0 +1,241 @@
+/**
+ * Generate SVG: a drawing, still or animated, written by a text model as SVG code, sanitised, checked for
+ * substance and kept on brand from the `svg:` block of workspace.images.settings.yml. A thin or unsafe answer is
+ * retried with the reason, within max_attempts and the time budget. Saved into images/svg/ with its records.
+ * A paid call goes out only with confirm=yes, which only the confirm dialog's Yes sends.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const { esc } = require('./html');
+const { CONFIG_DIR, workspaceDir } = require('./workspaces');
+const images = require('./images');
+const providers = require('./images-providers');
+const core = require('./images-svg-core');
+const { writeRecords } = require('./images-records');
+
+const PALETTE_KEYS = ['primary', 'secondary', 'accent', 'dark', 'light'];
+const HEX = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+const DEFAULTS = { brief: '', palette: 'brand-tokens', max_attempts: 3, request_timeout: 180, time_budget: 240, motion: core.MOTION, examples: [] };
+const MIN_ATTEMPT_MS = 30000;
+
+/** The brand tokens' five colours. */
+function brandPalette() {
+  let t = {};
+  try { t = JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, 'brand-tokens.json'), 'utf8')).tokens || {}; } catch (_) { /* fall back */ }
+  const fallback = { primary: '#0074e0', secondary: '#2b447c', accent: '#e4dcff', dark: '#000000', light: '#ebe8e5' };
+  return Object.fromEntries(PALETTE_KEYS.map((k) => [k, HEX.test(t[`brand-${k}`] || '') ? t[`brand-${k}`] : fallback[k]]));
+}
+
+/** The `svg:` settings, with defaults for anything missing or out of range. */
+function config() {
+  let raw = {};
+  try { raw = (yaml.load(fs.readFileSync(path.join(CONFIG_DIR, 'workspace.images.settings.yml'), 'utf8')) || {}).svg || {}; } catch (_) { /* defaults */ }
+  const num = (v, d, lo, hi) => (Number.isFinite(Number(v)) ? Math.min(hi, Math.max(lo, Number(v))) : d);
+  const palette = brandPalette();
+  if (raw.palette && typeof raw.palette === 'object') for (const k of PALETTE_KEYS) if (HEX.test(String(raw.palette[k] || ''))) palette[k] = String(raw.palette[k]);
+  const m = raw.motion && typeof raw.motion === 'object' ? raw.motion : {};
+  return {
+    brief: String(raw.brief || DEFAULTS.brief).trim().slice(0, 1000),
+    palette,
+    max_attempts: num(raw.max_attempts, DEFAULTS.max_attempts, 1, 5),
+    request_timeout: num(raw.request_timeout, DEFAULTS.request_timeout, 30, 600),
+    time_budget: num(raw.time_budget, DEFAULTS.time_budget, 30, 1200),
+    motion: { ...core.MOTION, duration: num(m.duration, core.MOTION.duration, 200, 5000), stagger: num(m.stagger, core.MOTION.stagger, 0, 1000),
+      threshold: num(m.threshold, core.MOTION.threshold, 0, 1), replay: m.replay !== false },
+    examples: (Array.isArray(raw.examples) ? raw.examples : []).filter((e) => e && e.title && e.prompt).slice(0, 20)
+      .map((e) => ({ title: String(e.title).slice(0, 80), prompt: String(e.prompt).slice(0, 2000), style: core.STYLES[e.style] ? e.style : 'draw' })),
+  };
+}
+
+/** The palette for one run: the configured one, with any colour the form changed. */
+function paletteFor(form, cfg) {
+  const p = { ...cfg.palette };
+  for (const k of PALETTE_KEYS) if (HEX.test(String(form[`palette_${k}`] || ''))) p[k] = String(form[`palette_${k}`]).toLowerCase();
+  return p;
+}
+
+/** A request, checked, or why not. */
+function plan(form) {
+  const cfg = config();
+  const prompt = String(form.prompt || '').trim();
+  if (!prompt) return { ok: false, error: 'Say what the drawing should show.' };
+  if (prompt.length > 2000) return { ok: false, error: 'The prompt can be 2000 characters at most.' };
+  const prov = providers.pick(form.provider, 'svg');
+  const model = prov.svgModels[form.model] ? String(form.model) : prov.defaultSvgModel;
+  const style = core.STYLES[form.style] ? String(form.style) : 'draw';
+  const shape = core.SHAPES[form.shape] ? String(form.shape) : 'wide';
+  const name = images.safeName(form.name || '').replace(/\.[^.]*$/, '')
+    || prompt.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'drawing';
+  const per = prov.svgEstimate({ model });
+  return { ok: true, provider: prov.id, prompt, model, style, shape, name, palette: paletteFor(form, cfg), png: form.png === 'yes',
+    attempts: cfg.max_attempts, estimate: per === null ? null : per, cfg };
+}
+
+/** The folder drawings go into. */
+const svgDir = () => path.join(workspaceDir('images'), 'svg');
+
+/** Save a finished drawing with its records, and its PNG preview when asked. */
+function save(dir, p, done, extra) {
+  fs.mkdirSync(dir, { recursive: true });
+  const file = images.freeName(dir, p.name, 'svg');
+  const abs = path.join(dir, file);
+  fs.writeFileSync(abs, done.svg);
+  let png = '';
+  if (p.png) {
+    const pngPath = abs.replace(/\.svg$/, '.png');
+    if (require('./images-render').renderPng(abs, pngPath, core.SHAPES[p.shape])) png = path.basename(pngPath);
+  }
+  writeRecords(abs, { prompt: p.prompt, style: core.STYLES[p.style], palette: core.paletteLine(p.palette), size: core.SHAPES[p.shape].join('x'),
+    created: new Date().toISOString(), png: png || undefined, motion: p.style === 'draw' ? p.cfg.motion : undefined,
+    sanitised: done.note || undefined, ...extra });
+  images.forgetScan();
+  return file;
+}
+
+/** Generate a drawing. Only with confirm=yes. Returns { ok, rel, cost, attempts } or a Claude Code session. */
+async function generateSvg(form, opts = {}) {
+  if (form.confirm !== 'yes') return { ok: false, status: 400, error: 'Generating needs confirming first.' };
+  const p = plan(form);
+  if (!p.ok) return { ok: false, status: 400, error: p.error };
+  const prov = providers.get(p.provider);
+  const dir = opts.dir || svgDir();
+  if (prov.async) {
+    if (!prov.available().ok) return { ok: false, status: 503, error: `Claude Code is not available: ${prov.available().why}.` };
+    const name = images.freeName(dir, p.name, 'svg').replace(/\.svg$/, '');
+    const { system, user } = core.buildPrompt({ ...p, brief: p.cfg.brief, files: { svg: `${name}.svg`, words: `${name}.claude.json` } });
+    const start = opts.start || require('./jobs').hostRunnerRequest;
+    const r = await prov.startSession({ kind: 'svg', name, dir, prompt: p.prompt, fullPrompt: `${system}\n\n${user}`, style: p.style,
+      palette: core.paletteLine(p.palette), motion: p.cfg.motion, attempts: p.attempts, shape: p.shape, pixels: core.SHAPES[p.shape],
+      png: p.png, created: new Date().toISOString() }, start);
+    if (!r.ok) return { ok: false, status: 503, error: r.error };
+    return { ok: true, async: true, session: r.session };
+  }
+  const key = opts.key || prov.key();
+  if (!key) return { ok: false, status: 503, error: `Set ai_providers.${prov.keyName}.api_key in core/config/settings.yml first.` };
+  const { system, user } = core.buildPrompt({ ...p, brief: p.cfg.brief });
+  const messages = [{ role: 'user', content: user }];
+  const started = Date.now();
+  const budget = p.cfg.time_budget * 1000;
+  let cost = 0;
+  let priced = true;
+  const tries = [];
+  for (let n = 1; n <= p.attempts; n += 1) {
+    const left = budget - (Date.now() - started);
+    if (n > 1 && left < MIN_ATTEMPT_MS) break;
+    let res;
+    try {
+      res = await prov.svg({ system, messages, model: p.model }, key, { timeoutMs: Math.min(p.cfg.request_timeout * 1000, Math.max(MIN_ATTEMPT_MS, left)) });
+    } catch (e) {
+      return { ok: false, status: 502, error: `${prov.label} refused it: ${e.message}`, attempts: tries };
+    }
+    if (res.cost === null || res.cost === undefined) priced = false; else cost += res.cost;
+    const reply = core.parseReply(res.text);
+    const done = core.finish(reply.svg, { style: p.style, motion: p.cfg.motion });
+    tries.push(done.ok ? 'ok' : done.why);
+    if (done.ok) {
+      const file = save(dir, p, done, { provider: prov.label, model: res.model, attempts: n, summary: reply.summary, alt: reply.alt,
+        described_by: reply.summary || reply.alt ? `${res.model}, in the same answer` : undefined,
+        cost: priced ? `about $${cost.toFixed(4)}` : undefined });
+      const root = fs.realpathSync(workspaceDir('images'));
+      const rel = path.relative(root, fs.realpathSync(path.join(dir, file))).split(path.sep).join('/');
+      return { ok: true, rel, file, cost: priced ? cost : null, attempts: n };
+    }
+    messages.push({ role: 'assistant', content: String(res.text || '').slice(0, 20000) }, { role: 'user', content: `${done.why} Answer again with the whole JSON.` });
+  }
+  return { ok: false, status: 502, error: `No usable drawing after ${tries.length} attempt${tries.length === 1 ? '' : 's'}: ${tries[tries.length - 1] || 'out of time'}`,
+    cost: priced ? cost : null, attempts: tries };
+}
+
+// ------------------------------------------------------------------- forms --
+
+const opt = (o, chosen) => Object.entries(o).map(([v, l]) => `<option value="${esc(v)}"${v === chosen ? ' selected' : ''}>${esc(l)}</option>`).join('');
+
+/** The provider's own fields: its models, and what it costs. */
+function providerFieldsHtml(id) {
+  const prov = providers.pick(id, 'svg');
+  const note = prov.async
+    ? 'Claude Code writes the SVG under your own Claude Code login, with no API charge. It runs as a screen session you can watch on Screens.'
+    : prov.svgEstimate({}) === null ? `${esc(prov.label)} publishes no per-drawing figure on the page this was built from; the real cost is not reported back.`
+      : `About $${prov.svgEstimate({}).toFixed(3)} an attempt; the real cost is shown after.`;
+  return `<label class="uk-form-label" for="svg-model">Model</label>
+    <select class="uk-select uk-form-small" id="svg-model" name="model">${opt(prov.svgModels, prov.defaultSvgModel)}</select>
+    <p class="uk-text-meta uk-margin-small-top">${note}</p>`;
+}
+
+function formHtml() {
+  const cfg = config();
+  const list = providers.list('svg');
+  const ready = list.find((p) => p.available().ok);
+  const sel = list.map((p) => {
+    const a = p.available();
+    return `<option value="${esc(p.id)}"${ready && p.id === ready.id ? ' selected' : ''}${a.ok ? '' : ' disabled'}>${esc(p.label)}${a.ok ? '' : ` (${esc(a.why)})`}</option>`;
+  }).join('');
+  const examples = cfg.examples.map((e, i) => `<option value="${i}" data-prompt="${esc(e.prompt)}" data-style="${esc(e.style)}">${esc(e.title)}</option>`).join('');
+  const colours = PALETTE_KEYS.map((k) => `<label class="svg-swatch"><input type="color" name="palette_${k}" value="${esc(cfg.palette[k])}"> ${k}</label>`).join('');
+  return `
+    <div class="editor-card img-ai img-svg">
+      <h3 class="uk-margin-small-bottom">Generate SVG</h3>
+      ${ready ? '' : '<div class="msg error">No SVG provider is set up on this machine: set an <code>ai_providers.&lt;provider&gt;.api_key</code> in <code>core/config/settings.yml</code>, or install the claude CLI.</div>'}
+      <form hx-post="/actions/image-svg" hx-target="#editor-modal-body" hx-swap="innerHTML">
+        <input type="hidden" name="workspace" value="images">
+        <div class="uk-grid-small uk-child-width-1-2@s" uk-grid>
+          <div><label class="uk-form-label" for="svg-provider">Provider</label>
+            <select class="uk-select uk-form-small" id="svg-provider" name="provider"
+              hx-get="/fragments/images/svg-provider-fields" hx-trigger="change" hx-target="#svg-fields" hx-swap="innerHTML" hx-include="this">${sel}</select></div>
+          <div id="svg-fields">${providerFieldsHtml(ready ? ready.id : '')}</div>
+        </div>
+        ${examples ? `<label class="uk-form-label uk-margin-small-top" for="svg-example">Start from an example</label>
+        <select class="uk-select uk-form-small" id="svg-example" data-svg-example><option value="">Choose an example…</option>${examples}</select>` : ''}
+        <label class="uk-form-label uk-margin-small-top" for="svg-prompt">What should it show?</label>
+        <textarea class="uk-textarea" id="svg-prompt" name="prompt" rows="4" maxlength="2000" required data-ace="markdown"></textarea>
+        <div class="uk-grid-small uk-child-width-1-3@s uk-margin-small-top" uk-grid>
+          <div><label class="uk-form-label" for="svg-style">Style</label>
+            <select class="uk-select uk-form-small" id="svg-style" name="style">${opt(core.STYLES, 'draw')}</select></div>
+          <div><label class="uk-form-label" for="svg-shape">Shape</label>
+            <select class="uk-select uk-form-small" id="svg-shape" name="shape">${opt(core.SHAPE_LABELS, 'wide')}</select></div>
+          <div><label class="uk-form-label" for="svg-name">File name</label>
+            <input class="uk-input uk-form-small" id="svg-name" name="name" maxlength="80"></div>
+        </div>
+        <fieldset class="svg-palette uk-margin-small-top"><legend class="uk-form-label">Palette, for this drawing (from the brand tokens)</legend>${colours}</fieldset>
+        <label class="uk-margin-small-top uk-display-block"><input class="uk-checkbox" type="checkbox" name="png" value="yes"> Also save a PNG preview</label>
+        <p class="uk-margin-small-top"><button class="uk-button uk-button-primary" type="submit"${ready ? '' : ' disabled'}>See the plan</button>
+          <span class="uk-text-meta">Saved into <code>images/svg/</code>. Nothing is sent until you confirm the plan.</span></p>
+      </form>
+    </div>`;
+}
+
+function planHtml(p) {
+  const prov = providers.get(p.provider);
+  const vals = esc(JSON.stringify({ workspace: 'images', prompt: p.prompt, provider: p.provider, model: p.model, style: p.style, shape: p.shape,
+    name: p.name, png: p.png ? 'yes' : '', confirm: 'yes', ...Object.fromEntries(Object.entries(p.palette).map(([k, v]) => [`palette_${k}`, v])) }));
+  const cost = prov.async ? 'No API charge: it uses your own Claude Code login.'
+    : p.estimate === null ? `${esc(prov.label)} publishes no per-drawing figure on the page this was built from; check its pricing page.`
+      : `About $${p.estimate.toFixed(3)} an attempt, at most ${p.attempts} attempts (about $${(p.estimate * p.attempts).toFixed(3)}); the real cost is shown after.`;
+  const swatches = Object.entries(p.palette).map(([k, v]) => `<span class="svg-chip" style="background:${esc(v)}" title="${esc(k)} ${esc(v)}"></span>`).join('');
+  return `
+    <div class="editor-card img-ai-plan">
+      <h3 class="uk-margin-small-bottom">The plan: generate an SVG</h3>
+      <dl class="img-info">
+        <dt>Provider</dt><dd>${esc(prov.label)}, ${esc(prov.svgModels[p.model] || p.model)}</dd>
+        <dt>Style</dt><dd>${esc(core.STYLES[p.style])}${p.style === 'draw' ? `: parts rise in turn and their strokes are traced (${p.cfg.motion.duration} ms, ${p.cfg.motion.stagger} ms apart)` : ''}; reduced motion shows the finished drawing</dd>
+        <dt>Size</dt><dd>${esc(core.SHAPE_LABELS[p.shape])}</dd>
+        <dt>Palette</dt><dd>${swatches} <code>${esc(core.paletteLine(p.palette))}</code></dd>
+        <dt>Saved as</dt><dd><code>images/svg/${esc(p.name)}.svg</code>${p.png ? ' and a PNG preview' : ''}, with its prompt, summary and alt text</dd>
+        <dt>Prompt</dt><dd>${esc(p.prompt)}</dd>
+        <dt>Checks</dt><dd>Sanitised (no scripts, handlers or outside links), at least ${core.MIN_DRAWABLE} shapes in ${core.MIN_PARTS} parts; a thin or unsafe answer is retried with the reason, up to ${p.attempts} attempts${prov.async ? '' : ` within ${p.cfg.time_budget} s`}</dd>
+        <dt>Cost</dt><dd>${cost}</dd>
+        ${prov.async ? '<dt>Where</dt><dd>A screen session: watch it on Screens. The drawing appears in <code>images/svg/</code> when it is done.</dd>' : ''}
+      </dl>
+      <p>
+        <button type="button" class="uk-button uk-button-primary arm-step" title="${prov.async ? 'Start a Claude Code session to draw it' : `Generate an SVG with ${esc(prov.label)} (paid)`}"
+          hx-post="/actions/image-svg" hx-trigger="confirmed-remove" hx-vals="${vals}"
+          hx-target="#editor-modal-body" hx-swap="innerHTML">${prov.async ? 'Start drawing' : 'Generate'}</button>
+        <button type="button" class="uk-button uk-button-default" hx-get="/fragments/images/svg-form" hx-target="#editor-modal-body" hx-swap="innerHTML">Change it</button>
+      </p>
+    </div>`;
+}
+
+module.exports = { PALETTE_KEYS, config, brandPalette, paletteFor, plan, generateSvg, formHtml, planHtml, providerFieldsHtml, svgDir };