dsh-clone 0.0.0-stage → 0.2.0

package/lib/parse.js

@@ -0,0 +1,58 @@
+/**
+ * `/clone` grammar. Only the shapes this command owns are parsed here; every
+ * remaining word is the note handed to the building agents.
+ *
+ *   /clone                      3 lanes, no note
+ *   /clone 4                    4 lanes, no note
+ *   /clone 2 dark dashboard     2 lanes, note "dark dashboard"
+ *   /clone status | pick 2 | refine 2 move the CTA up | cancel | discard | help
+ */
+
+import { clampLanes } from './util.js'
+
+export const DEFAULT_LANES = 3
+export const MAX_LANES = 4
+
+const CONTROLS = new Set(['status', 'list', 'pick', 'cancel', 'stop', 'discard', 'drop', 'help', '?', 'refine'])
+
+/** Parse one raw command input into a discriminated action. */
+export function parseCloneArgs(raw, { defaultLanes = DEFAULT_LANES, maxLanes = MAX_LANES } = {}) {
+  const input = String(raw ?? '').trim()
+  if (input.length === 0) return { kind: 'start', lanes: clampLanes(defaultLanes, { max: maxLanes }), note: '' }
+
+  const parts = input.split(/\s+/u)
+  const head = parts[0].toLowerCase()
+
+  if (head === 'help' || head === '?') return { kind: 'help' }
+  if (head === 'status' || head === 'list') return { kind: 'status' }
+  if (head === 'cancel' || head === 'stop') return { kind: 'cancel' }
+  if (head === 'discard' || head === 'drop') return { kind: 'discard' }
+  if (head === 'pick') {
+    const lane = parts[1] === undefined ? null : Number(parts[1])
+    return { kind: 'pick', lane: Number.isInteger(lane) && lane > 0 ? lane : null }
+  }
+  if (head === 'refine') {
+    // `/clone refine`, `/clone refine 2`, `/clone refine 2 move the CTA up`
+    const lane = /^\d{1,2}$/u.test(parts[1] ?? '') ? Number(parts[1]) : null
+    const change = parts.slice(lane === null ? 1 : 2).join(' ').trim()
+    return { kind: 'refine', lane: lane !== null && lane > 0 ? lane : null, note: change }
+  }
+  if (CONTROLS.has(head)) return { kind: 'help' }
+
+  const countToken = /^\d{1,2}$/u.test(parts[0]) ? Number(parts[0]) : null
+  const rest = countToken === null ? parts : parts.slice(1)
+  return {
+    kind: 'start',
+    lanes: clampLanes(countToken ?? defaultLanes, { max: maxLanes }),
+    note: rest.join(' ').trim(),
+  }
+}
+
+/** Extract an explicit reference-image path from the note, when present. */
+export function referenceHintOf(note) {
+  const tokens = String(note ?? '').split(/\s+/u).filter((token) => token.length > 0)
+  for (const token of tokens) {
+    if (/\.(png|jpe?g|webp|gif)$/iu.test(token)) return token
+  }
+  return null
+}

package/lib/png.js

@@ -0,0 +1,175 @@
+/**
+ * A minimal, dependency-free PNG decoder.
+ *
+ * dsh-clone needs exactly one thing from a PNG: the pixels, so a rendered lane
+ * can be compared with the reference screenshot. No encoder, no palette or
+ * interlace support, no colour management — only the 8-bit non-interlaced
+ * images a browser screenshot and an ordinary screenshot produce.
+ *
+ * Node's own zlib does the inflate; everything else here is the PNG spec.
+ */
+
+import { inflateSync } from 'node:zlib'
+
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+const MAX_PIXELS = 4096 * 4096
+
+/** Channels per pixel for the colour types this decoder accepts. */
+const CHANNELS = new Map([
+  [0, 1], // greyscale
+  [2, 3], // RGB
+  [4, 2], // greyscale + alpha
+  [6, 4], // RGBA
+])
+
+/**
+ * Decode one PNG into straight RGBA8 pixels.
+ * @param buffer - the complete PNG file bytes.
+ * @returns `{ width, height, data }` where data is RGBA, one byte per channel.
+ * @throws when the bytes are not a PNG this decoder supports.
+ */
+export function decodePng(buffer) {
+  const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer)
+  if (bytes.length < 8) throw new Error('png: file is too short')
+  for (let index = 0; index < 8; index += 1) {
+    if (bytes[index] !== SIGNATURE[index]) throw new Error('png: bad signature')
+  }
+
+  let offset = 8
+  let header = null
+  const idat = []
+  while (offset + 8 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset)
+    const type = bytes.toString('ascii', offset + 4, offset + 8)
+    const start = offset + 8
+    const end = start + length
+    if (end > bytes.length) throw new Error('png: truncated chunk')
+    if (type === 'IHDR') header = readHeader(bytes, start)
+    else if (type === 'IDAT') idat.push(bytes.subarray(start, end))
+    else if (type === 'IEND') break
+    offset = end + 4 // skip the CRC
+  }
+
+  if (header === null) throw new Error('png: missing IHDR')
+  if (header.interlaced) throw new Error('png: interlaced images are not supported')
+  if (header.bitDepth !== 8) throw new Error(`png: unsupported bit depth ${header.bitDepth}`)
+  const channels = CHANNELS.get(header.colourType)
+  if (channels === undefined) throw new Error(`png: unsupported colour type ${header.colourType}`)
+  if (header.width * header.height > MAX_PIXELS) throw new Error('png: image is too large')
+  if (idat.length === 0) throw new Error('png: no image data')
+
+  const raw = inflateSync(Buffer.concat(idat))
+  const scanline = header.width * channels
+  const expected = (scanline + 1) * header.height
+  if (raw.length < expected) throw new Error('png: image data is short')
+
+  const pixels = new Uint8Array(scanline * header.height)
+  unfilter(raw, pixels, scanline, header.height, channels)
+  return { width: header.width, height: header.height, data: expandToRgba(pixels, header.width, header.height, channels) }
+}
+
+/**
+ * Read width and height from a PNG header without inflating the image.
+ * @param buffer - PNG bytes, at least the first 24.
+ * @returns `{ width, height }`, or null when the header is not readable.
+ */
+export function readPngSize(buffer) {
+  const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer)
+  if (bytes.length < 24) return null
+  for (let index = 0; index < 8; index += 1) {
+    if (bytes[index] !== SIGNATURE[index]) return null
+  }
+  if (bytes.toString('ascii', 12, 16) !== 'IHDR') return null
+  const width = bytes.readUInt32BE(16)
+  const height = bytes.readUInt32BE(20)
+  if (width <= 0 || height <= 0) return null
+  return { width, height }
+}
+
+/** Read the IHDR fields this decoder cares about. */
+function readHeader(bytes, start) {
+  const width = bytes.readUInt32BE(start)
+  const height = bytes.readUInt32BE(start + 4)
+  if (width <= 0 || height <= 0) throw new Error('png: empty image')
+  return {
+    width,
+    height,
+    bitDepth: bytes[start + 8],
+    colourType: bytes[start + 9],
+    interlaced: bytes[start + 12] !== 0,
+  }
+}
+
+/** Undo the per-scanline filters in place (PNG spec section 9). */
+function unfilter(raw, out, scanline, height, bpp) {
+  let source = 0
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[source]
+    source += 1
+    const rowStart = y * scanline
+    const previousStart = rowStart - scanline
+    for (let x = 0; x < scanline; x += 1) {
+      const value = raw[source + x]
+      const left = x >= bpp ? out[rowStart + x - bpp] : 0
+      const up = y > 0 ? out[previousStart + x] : 0
+      const upLeft = y > 0 && x >= bpp ? out[previousStart + x - bpp] : 0
+      let result
+      switch (filter) {
+        case 0: result = value; break
+        case 1: result = value + left; break
+        case 2: result = value + up; break
+        case 3: result = value + ((left + up) >> 1); break
+        case 4: result = value + paeth(left, up, upLeft); break
+        default: throw new Error(`png: unknown filter ${filter}`)
+      }
+      out[rowStart + x] = result & 0xff
+    }
+    source += scanline
+  }
+}
+
+/** The PNG Paeth predictor. */
+function paeth(left, up, upLeft) {
+  const estimate = left + up - upLeft
+  const distanceLeft = Math.abs(estimate - left)
+  const distanceUp = Math.abs(estimate - up)
+  const distanceUpLeft = Math.abs(estimate - upLeft)
+  if (distanceLeft <= distanceUp && distanceLeft <= distanceUpLeft) return left
+  return distanceUp <= distanceUpLeft ? up : upLeft
+}
+
+/** Normalize any accepted colour layout into straight RGBA8. */
+function expandToRgba(pixels, width, height, channels) {
+  const count = width * height
+  const out = new Uint8Array(count * 4)
+  for (let index = 0; index < count; index += 1) {
+    const source = index * channels
+    const target = index * 4
+    switch (channels) {
+      case 4:
+        out[target] = pixels[source]
+        out[target + 1] = pixels[source + 1]
+        out[target + 2] = pixels[source + 2]
+        out[target + 3] = pixels[source + 3]
+        break
+      case 3:
+        out[target] = pixels[source]
+        out[target + 1] = pixels[source + 1]
+        out[target + 2] = pixels[source + 2]
+        out[target + 3] = 255
+        break
+      case 2:
+        out[target] = pixels[source]
+        out[target + 1] = pixels[source]
+        out[target + 2] = pixels[source]
+        out[target + 3] = pixels[source + 1]
+        break
+      default:
+        out[target] = pixels[source]
+        out[target + 1] = pixels[source]
+        out[target + 2] = pixels[source]
+        out[target + 3] = 255
+    }
+  }
+  return out
+}

package/lib/preview.js

@@ -0,0 +1,141 @@
+/**
+ * The HTTP surface of the Host half: one JSON feed, one reference image, one
+ * action endpoint, and a static file route that serves each lane's build.
+ *
+ * Lane output is model-written HTML, so it is served into an opaque origin:
+ * the `sandbox` CSP directive without `allow-same-origin` means a clone can
+ * run its own scripts but cannot touch this page's cookies, storage, or API.
+ */
+
+import { extname, join, normalize, sep } from 'node:path'
+
+/** Content types the preview route may answer with. */
+const MEDIA_TYPES = new Map(Object.entries({
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/plain; charset=utf-8',
+}))
+
+/** Media type for a previewable file, defaulting to a binary-safe type. */
+export function mediaTypeFor(filePath) {
+  return MEDIA_TYPES.get(extname(String(filePath ?? '')).toLowerCase()) ?? 'application/octet-stream'
+}
+
+/** Response headers shared by every previewed file. */
+export const PREVIEW_HEADERS = {
+  'Content-Security-Policy': "sandbox allow-scripts allow-forms allow-modals allow-popups; default-src 'self' data: blob:; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'",
+  'X-Content-Type-Options': 'nosniff',
+  'Cache-Control': 'no-store',
+  'Referrer-Policy': 'no-referrer',
+}
+
+/** Resolve a request path inside one directory, or null when it escapes. */
+export function safeJoin(root, relativePath) {
+  const cleaned = String(relativePath ?? '').replace(/^\/+/u, '')
+  const normalized = normalize(cleaned)
+  if (normalized.startsWith('..') || normalized.includes(`..${sep}`) || normalized.includes('\0')) return null
+  const absolute = join(root, normalized)
+  const prefix = root.endsWith(sep) ? root : `${root}${sep}`
+  if (absolute !== root && !absolute.startsWith(prefix)) return null
+  return absolute
+}
+
+/** Write one JSON response. */
+export function sendJson(response, status, value) {
+  const body = JSON.stringify(value)
+  response.statusCode = status
+  response.setHeader('Content-Type', 'application/json; charset=utf-8')
+  response.setHeader('Cache-Control', 'no-store')
+  response.setHeader('Content-Length', Buffer.byteLength(body))
+  response.end(body)
+}
+
+/** Write a small plain-text rejection. */
+export function sendText(response, status, text) {
+  response.statusCode = status
+  response.setHeader('Content-Type', 'text/plain; charset=utf-8')
+  response.end(text)
+}
+
+/** Read and parse a bounded JSON request body. */
+export async function readJsonBody(request, { limit = 64 * 1024 } = {}) {
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of request) {
+    bytes += chunk.length
+    if (bytes > limit) throw new Error('request body too large')
+    chunks.push(chunk)
+  }
+  if (chunks.length === 0) return {}
+  const text = Buffer.concat(chunks).toString('utf8')
+  if (text.trim().length === 0) return {}
+  const parsed = JSON.parse(text)
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('request body must be an object')
+  return parsed
+}
+
+/** Serve one file from a lane directory with preview-safe headers. */
+export async function serveLaneFile({ fs, root, relativePath, response }) {
+  let relative = String(relativePath ?? '')
+  if (relative.length === 0 || relative.endsWith('/')) relative = `${relative}index.html`
+  const absolute = safeJoin(root, relative)
+  if (absolute === null) {
+    sendText(response, 403, 'forbidden')
+    return
+  }
+  const stats = await fs.stat(absolute).catch(() => null)
+  if (stats === null || !stats.isFile()) {
+    sendText(response, 404, 'not found')
+    return
+  }
+  const body = await fs.readFile(absolute)
+  response.statusCode = 200
+  response.setHeader('Content-Type', mediaTypeFor(absolute))
+  response.setHeader('Content-Length', body.length)
+  for (const [name, value] of Object.entries(PREVIEW_HEADERS)) response.setHeader(name, value)
+  response.end(body)
+}
+
+/** Serve one image file (the reference screenshot) with its own media type. */
+export async function serveImageFile({ fs, path, mediaType, response }) {
+  const body = await fs.readFile(path).catch(() => null)
+  if (body === null) {
+    sendText(response, 404, 'not found')
+    return
+  }
+  response.statusCode = 200
+  response.setHeader('Content-Type', mediaType ?? mediaTypeFor(path))
+  response.setHeader('Content-Length', body.length)
+  response.setHeader('Cache-Control', 'no-store')
+  response.setHeader('X-Content-Type-Options', 'nosniff')
+  response.end(body)
+}
+
+/**
+ * Parse `/api/dsh-clone/preview/<cloneId>/<lane>/<rest>`.
+ * @returns `{ cloneId, lane, rest }` or null for a malformed path.
+ */
+export function parsePreviewPath(pathname) {
+  const prefix = '/api/dsh-clone/preview/'
+  if (!pathname.startsWith(prefix)) return null
+  const parts = pathname.slice(prefix.length).split('/')
+  const cloneId = parts.shift() ?? ''
+  const lane = Number(parts.shift())
+  if (!/^[a-z0-9]{1,32}$/iu.test(cloneId)) return null
+  if (!Number.isInteger(lane) || lane < 1 || lane > 8) return null
+  return { cloneId, lane, rest: parts.join('/') }
+}

package/lib/prompts.js

@@ -0,0 +1,118 @@
+/**
+ * The builder prompts. Each lane gets the same reference image and the same
+ * hard delivery contract, but a different way of working — that difference is
+ * what makes a set of lanes worth comparing instead of three copies of one
+ * attempt.
+ */
+
+/** Fixed delivery contract every lane must satisfy. */
+export const DELIVERY_CONTRACT = `Delivery contract (non-negotiable):
+- Work ONLY inside the current working directory. Never read or write outside it.
+- Deliver a static page that opens at index.html with no build step and no server: plain HTML, CSS and vanilla JS, plus any extra local files (styles.css, app.js, assets/*).
+- No network at runtime. No CDN, no Google Fonts, no remote images, no package installs. If you need an icon or a photo, draw it with inline SVG or CSS gradients/geometry.
+- The page must fill the viewport edge to edge (body margin 0; a layout that uses height:100vh). Target a ${'`'}REFERENCE_VIEWPORT${'`'} viewport; make it degrade sanely when narrower.
+- Never leave placeholder text like "Lorem ipsum", "TODO", "Your text here", or a grey box where the reference shows real content. Recreate the copy you can read in the reference image, in the reference's own language.
+- Match the reference as a picture: structure, spacing rhythm, colour values, type scale and weights, corner radii, borders, shadows, iconography, and the alignment of every block.
+- If the reference contains a chart, table, avatar or illustration you cannot copy pixel for pixel, approximate its silhouette, palette and proportions with CSS/SVG — an honest approximation, never a blank hole.
+- Do not leave working files behind (crops of the reference, notes, scripts). The deliverable is index.html plus the assets it actually loads; delete your scratch before you finish.`
+
+/**
+ * Budget guidance shared by every lane.
+ *
+ * A reference rebuild is a build task, not a research task: an agent that keeps
+ * cropping the screenshot instead of writing the page burns tokens without
+ * improving the result. The budget below is deliberately concrete because
+ * "be efficient" is not actionable for a model.
+ */
+export const EFFORT_BUDGET = `Working budget:
+- Study the reference in at most two passes: its full view, then at most two crops of regions whose detail you cannot read at full size.
+- Do NOT run pixel-sampling or colour-counting scripts over the image, and do not measure exact coordinates with code: read colours and sizes by eye from the image and approximate them. Measurement scripts are the most common way this task fails — they consume the whole budget and leave no page.
+- Write index.html by your tenth tool call at the latest, then refine it. An unpolished page that exists beats a perfect analysis that does not.
+- Aim to be finished within roughly 20-25 tool calls. If you are past that, ship what you have and report what still differs.`
+
+/** Lane strategies, cycled when more lanes than strategies are requested. */
+export const LANE_STRATEGIES = [
+  {
+    id: 'measure-first',
+    label: 'Measure first',
+    brief: `Strategy: measure before you build. Before writing any code, study the reference image and write a short layout spec as an HTML comment at the top of index.html: the page's regions top to bottom, the column grid, the spacing scale you infer, the palette you sample (list the hex values), and the type scale. Then build strictly to that spec. Verify at the end by re-reading your spec against the image and fixing every mismatch.`,
+  },
+  {
+    id: 'structure-first',
+    label: 'Structure first',
+    brief: `Strategy: structure before cosmetics. First write the whole page as semantic HTML with every region, list, control and piece of copy in place, unstyled. Only then apply CSS in one pass, region by region, from the outside in. Finish by checking that the block geometry (widths, heights, alignments) matches the image before you polish colour and type.`,
+  },
+  {
+    id: 'visual-first',
+    label: 'Visual first',
+    brief: `Strategy: visual fidelity before features. Reproduce the image as a picture first: exact background colours, the dominant surfaces, the type, the spacing, and the overall silhouette at the target viewport. Once the page looks right as a still image, add only the interactivity that the image visibly implies. Never trade visual fidelity for extra behaviour.`,
+  },
+  {
+    id: 'component-first',
+    label: 'Component first',
+    brief: `Strategy: components first. Identify the 5-8 repeated or reused parts of the interface (card, row, button, tab, badge, panel) and define each once as a small CSS class or a JS factory. Compose the page from those parts, so spacing and corner treatment stay consistent across the whole screen.`,
+  },
+]
+
+/**
+ * The task for refining an adopted lane.
+ *
+ * A refine is not a new attempt: the previous page is already in the working
+ * directory and the person liked it. The contract therefore forbids starting
+ * over and asks for the smallest edit that satisfies the change while keeping
+ * the reference agreement.
+ * @param args - reference path, the requested change, viewport.
+ * @returns the prompt text.
+ */
+export function buildRefinePrompt({ referencePath, change, viewport }) {
+  return [
+    'You are refining a page you already built. It is not a new attempt.',
+    '',
+    `The page is in this directory (index.html plus its assets). Read it first: it is your previous work and it is close to the reference already.`,
+    `Reference image: ${referencePath} — open it with the read_image tool. It is still the source of truth for layout, colour, type and copy.`,
+    '',
+    `The change the person wants:`,
+    `  ${change.length === 0 ? '(no specific change was given — improve the reference agreement where your previous version is visibly off)' : change}`,
+    '',
+    'Rules:',
+    '- Keep everything that already agrees with the reference. Do not rewrite the page from scratch and do not restyle unrelated parts.',
+    '- Make the smallest edit that satisfies the change, then check the result against the reference again.',
+    `- The page must stay a self-contained static page at the target viewport \`${viewport}\`, with no build step and no network at runtime.`,
+    '- Delete any scratch file you create. Ship only what the page loads.',
+    '',
+    'Reply with a short plain-text report: the files you touched, what changed, and anything in the reference you still cannot match. Do not paste the HTML.',
+  ].join('\n')
+}
+
+/** Pick the strategy for one lane, cycling deterministically. */
+export function strategyForLane(index) {
+  return LANE_STRATEGIES[index % LANE_STRATEGIES.length]
+}
+
+/**
+ * Build the complete task for one lane.
+ * @param args - lane index, reference path, viewport, optional user note.
+ * @returns the prompt text handed to the child agent.
+ */
+export function buildLanePrompt({ laneIndex, laneCount, strategy, referencePath, referenceLabel, viewport, note }) {
+  const contract = DELIVERY_CONTRACT.replace('REFERENCE_VIEWPORT', `\`${viewport}\``)
+  const noteLine = note === undefined || note === null || note.length === 0
+    ? ''
+    : `\nThe person asked for this specifically — honour it whenever it does not contradict the reference image:\n  ${note}\n`
+  return [
+    `You are rebuilding a user interface from a reference screenshot. This is a build task, not a review task.`,
+    ``,
+    `Reference image: ${referencePath}`,
+    `Open it with the read_image tool and study it before you write anything. It is the only source of truth for layout, colour, type and copy.`,
+    referenceLabel === undefined ? '' : `Reference label: ${referenceLabel}`,
+    `You are lane ${laneIndex + 1} of ${laneCount}: another agent is building the same screen in parallel in a different directory, and the person will adopt whichever result they prefer. Your job is to make yours the obvious choice.`,
+    noteLine,
+    strategy.brief,
+    ``,
+    contract,
+    ``,
+    EFFORT_BUDGET,
+    ``,
+    `When you are done, reply with a short report in plain text: the files you created, the palette you sampled, and the three places where your rebuild still differs from the reference. Do not paste the HTML into the reply.`,
+  ].filter((line) => line !== '').join('\n')
+}

package/lib/rank.js

@@ -0,0 +1,72 @@
+/**
+ * Ranking rules for a finished set of lanes.
+ *
+ * dsh-clone has no oracle: the reference screenshot is the ground truth, and
+ * only a human can say which rebuild looks closer. What the engine CAN judge
+ * objectively is completeness and speed, so it does exactly that and no more:
+ *
+ *   1. a lane that produced a servable page beats one that did not;
+ *   2. among those, the one that finished first is the suggested winner;
+ *   3. lanes that failed stay listed but never win automatically.
+ *
+ * The suggestion is only a default — the panel lets the reader take any lane.
+ */
+
+/** Whether a lane produced something the preview route can serve. */
+export function laneDelivered(lane) {
+  if (lane === null || lane === undefined) return false
+  if (lane.status !== 'settled') return false
+  return Array.isArray(lane.files) && lane.files.some((file) => file?.path === 'index.html')
+}
+
+/** Whether the lane carries a comparable similarity score. */
+export function laneScored(lane) {
+  return lane !== null && lane !== undefined && typeof lane.score === 'number' && Number.isFinite(lane.score)
+}
+
+/**
+ * Order lanes from most to least adoptable.
+ *
+ * Delivered lanes lead. Among them, a rendered similarity score is the
+ * strongest signal available, so it decides; lanes without a score fall back
+ * to finish order. Nothing here is a correctness judgement.
+ */
+export function rankLanes(lanes) {
+  const list = Array.isArray(lanes) ? lanes : []
+  return [...list].sort((left, right) => {
+    const delivered = Number(laneDelivered(right)) - Number(laneDelivered(left))
+    if (delivered !== 0) return delivered
+    if (laneScored(left) && laneScored(right) && left.score !== right.score) return right.score - left.score
+    if (laneScored(left) !== laneScored(right)) return laneScored(left) ? -1 : 1
+    const finished = (left.finishedAt ?? Number.POSITIVE_INFINITY) - (right.finishedAt ?? Number.POSITIVE_INFINITY)
+    if (Number.isFinite(finished) && finished !== 0) return finished
+    return left.index - right.index
+  })
+}
+
+/** Suggested winner lane, or null when nothing usable landed. */
+export function suggestedWinner(lanes) {
+  const [first] = rankLanes(lanes).filter(laneDelivered)
+  return first ?? null
+}
+
+/** Whether a lane stopped working, whatever the outcome was. */
+export function laneTerminal(lane) {
+  return lane !== null && lane !== undefined && ['settled', 'empty', 'failed', 'cancelled'].includes(lane.status)
+}
+
+/** One-line state for the composer chip. */
+export function summarize(clone) {
+  if (clone === null || clone === undefined) return null
+  const lanes = Array.isArray(clone.lanes) ? clone.lanes : []
+  const done = lanes.filter(laneTerminal).length
+  return {
+    id: clone.id,
+    status: clone.status,
+    done,
+    total: lanes.length,
+    delivered: lanes.filter(laneDelivered).length,
+    winner: clone.winner ?? null,
+    bestScore: lanes.reduce((best, lane) => (laneScored(lane) && (best === null || lane.score > best) ? lane.score : best), null),
+  }
+}