Skip to content

The design language that makes your AI harness better at design.

JavaScript
18.3 KB
Raw Blame
/** Plan and asset review (packet schemaVersion 3). Pure logic; the view lives in plan-review.ts.
 * Contract: docs/PLAN-REVIEW.md. */
import { validBox, type Box, type Missing } from './model';

export type AssetKind = 'plate' | 'image' | 'texture';
export type Flag = { id: string; message: string };
export type PlanItem = {
  id: string; revision: string; name: string; kind: string; role: 'asset' | 'plan';
  box: Box; note: string; medium?: string;
  preview: { kind: 'image' | 'comp-crop' | 'page'; url?: string };
  flags?: Flag[]; codeDrawn?: boolean;
  material?: { format: string; width: number; height: number; alpha: 'transparent' | 'opaque' | 'unknown' };
};
export type CodeRegion = { id: string; name: string; kind: string; box: Box; note?: string; container?: boolean };
export type PlanPacket = {
  schemaVersion: 3; stage: 'components'; id: string; revision: string; title: string; round: number;
  comp: { url: string; width: number; height: number; background?: string };
  components: PlanItem[]; codeRegions?: CodeRegion[]; specSha256?: string;
};
export type PlanDecision = { revision: string; action: 'approve' | 'revise' | 'reclassify'; feedback: string; split: boolean; kind?: AssetKind };
export type Reclassify = { id: string; kind: AssetKind; feedback: string };
export type PlanDraft = { packetRevision: string; decisions: Record<string, PlanDecision>; missing: Missing[]; inventoryConfirmed: boolean; reclassify?: Reclassify[] };
export type PlanHistory = {
  packet: PlanPacket; submitted: boolean;
  changes: Record<string, { kind: 'added' | 'changed' | 'unchanged'; files: string[]; reasons: string[]; carried?: boolean }>;
  feedback?: Record<string, { round: number; decision: { action: string; feedback?: string; kind?: string; split?: boolean } }>;
};
export type ItemState = 'pending' | 'approved' | 'revise' | 'reclassify';

export const ASSET_KINDS: { kind: AssetKind; label: string; hint: string }[] = [
  { kind: 'plate', label: 'Illustration / plate', hint: 'Painted or drawn artwork' },
  { kind: 'image', label: 'Photo / image', hint: 'A photograph' },
  { kind: 'texture', label: 'Texture', hint: 'A surface or material' },
];
export const assetKindLabel = (kind: AssetKind) => ASSET_KINDS.find(k => k.kind === kind)!.label;

export function isPlanPacket(packet: unknown): packet is PlanPacket {
  const p = packet as Partial<PlanPacket> | null;
  return !!p && p.schemaVersion === 3 && p.stage === 'components';
}

/** Plan items that need attention: the comp looks painted, or the plan draws artwork in code. */
export function isFlagged(item: PlanItem) {
  return item.role === 'plan' && (!!item.flags?.length || !!item.codeDrawn);
}

/** Flagged plan items first, then assets, then remaining plan items. Stable within groups. */
export function planQueue(packet: PlanPacket): PlanItem[] {
  const rank = (c: PlanItem) => isFlagged(c) ? 0 : c.role === 'asset' ? 1 : 2;
  return packet.components.map((c, i) => ({ c, i })).sort((a, b) => rank(a.c) - rank(b.c) || a.i - b.i).map(x => x.c);
}

/** Code regions without a component entry; containers last so they never crowd the list. */
export function extraRegions(packet: PlanPacket): CodeRegion[] {
  const ids = new Set(packet.components.map(c => c.id));
  return (packet.codeRegions ?? []).filter(r => !ids.has(r.id));
}

export function currentDecision(item: PlanItem, draft: PlanDraft): PlanDecision | undefined {
  const d = draft.decisions[item.id];
  return d?.revision === item.revision ? d : undefined;
}

export function itemState(item: PlanItem, draft: PlanDraft): ItemState {
  const d = currentDecision(item, draft);
  return d ? d.action === 'approve' ? 'approved' : d.action : 'pending';
}

export function regionReclassify(draft: PlanDraft, id: string) {
  return draft.reclassify?.find(r => r.id === id);
}

/** Surface words suggest a texture; photographic words an image; otherwise a plate. */
export function defaultAssetKind(item: { note?: string; name?: string; flags?: Flag[] }): AssetKind {
  const text = [item.name, item.note, ...(item.flags ?? []).map(f => f.message)].join(' ');
  if (/\b(textures?|surfaces?|grain|grainy|brushed|metal(lic)?|steel|brass|copper|paper|linen|canvas|fabric|cloth|wood(en)?|stone|marble|concrete|plaster|leather|noise|pattern(ed)?|weave|patina)\b/i.test(text)) return 'texture';
  if (/\b(photo|photos|photograph|photographs|photographic|photography)\b/i.test(text) && !/\bphotographic shading\b/i.test(text)) return 'image';
  return 'plate';
}

/** The plan statement shown for a code-planned item. */
export function planStatement(item: { kind: string }) {
  return `Drawn in code (${item.kind})`;
}

/** comp-spec writes each flag message as a reviewer-facing observation; show it as written. */
export function flagMessage(flag: Flag) {
  return flag.message;
}

export function planSummary(packet: PlanPacket, draft: PlanDraft) {
  const states = packet.components.map(c => itemState(c, draft));
  const approved = states.filter(s => s === 'approved').length;
  const revise = states.filter(s => s === 'revise').length;
  const extraIds = new Set(extraRegions(packet).map(r => r.id));
  const regionReclassifications = (draft.reclassify ?? []).filter(r => extraIds.has(r.id)).length;
  const reclassify = states.filter(s => s === 'reclassify').length + regionReclassifications;
  const pending = states.filter(s => s === 'pending').length;
  const missing = draft.missing.length;
  const hasChanges = revise + reclassify + missing > 0;
  const current = draft.packetRevision === packet.revision;
  const missingValid = draft.missing.every(m => m.name.trim() && validBox(m.box));
  const canApprove = current && !hasChanges && pending === 0;
  return {
    total: states.length, approved, revise, reclassify, pending, missing, hasChanges, canApprove,
    mode: hasChanges ? 'changes' as const : 'approve' as const,
    canSubmit: current && missingValid && (hasChanges || canApprove),
  };
}

/** Pure decision update. Returns the next draft; callers keep the old one for undo. */
export function decide(draft: PlanDraft, item: PlanItem, action: PlanDecision['action'], options: { feedback?: string; kind?: AssetKind; split?: boolean } = {}): PlanDraft {
  // Split asks for a baked composite to come back as layers; only an asset's revise can carry it.
  if (options.split && !(action === 'revise' && item.role === 'asset')) throw new Error('Only a generated asset can be split into layers');
  // A plan item's revise is a region-map change in the reviewer's words, so it needs them.
  if (action === 'revise' && item.role !== 'asset' && !(options.feedback ?? '').trim()) throw new Error('Revising a plan item needs feedback');
  if (action === 'reclassify' && item.role !== 'plan') throw new Error('Only planned code can become an image');
  const decision: PlanDecision = { revision: item.revision, action, feedback: action === 'approve' ? '' : (options.feedback ?? '').trim(), split: !!options.split };
  if (action === 'reclassify') decision.kind = options.kind ?? defaultAssetKind(item);
  return { ...draft, inventoryConfirmed: false, decisions: { ...draft.decisions, [item.id]: decision } };
}
export function clearDecision(draft: PlanDraft, id: string): PlanDraft {
  const decisions = { ...draft.decisions };
  delete decisions[id];
  return { ...draft, inventoryConfirmed: false, decisions };
}
export function setRegionReclassify(draft: PlanDraft, id: string, value: { kind: AssetKind; feedback?: string } | null): PlanDraft {
  const rest = (draft.reclassify ?? []).filter(r => r.id !== id);
  return { ...draft, inventoryConfirmed: false, reclassify: value ? [...rest, { id, kind: value.kind, feedback: (value.feedback ?? '').trim() }] : rest };
}

/** Next undecided queue item after `after`, wrapping once. */
export function nextPending(packet: PlanPacket, draft: PlanDraft, after?: string): string | undefined {
  const queue = planQueue(packet);
  const start = queue.findIndex(c => c.id === after);
  for (let step = 1; step <= queue.length; step++) {
    const item = queue[(start + step) % queue.length];
    if (itemState(item, draft) === 'pending') return item.id;
  }
}

/** Submission body. Approval (nothing changed, nothing missing) confirms the inventory;
 * a changes submission never does. Region reclassifications travel separately. */
export function planSubmission(packet: PlanPacket, draft: PlanDraft) {
  const summary = planSummary(packet, draft);
  if (!summary.canSubmit) throw new Error('Review is incomplete or stale');
  const decisions: Record<string, PlanDecision> = {};
  for (const c of packet.components) {
    const d = currentDecision(c, draft);
    if (d) decisions[c.id] = structuredClone(d);
  }
  const extraIds = new Set(extraRegions(packet).map(r => r.id));
  const reclassify = (draft.reclassify ?? []).filter(r => extraIds.has(r.id)).map(r => ({ ...r }));
  return {
    schemaVersion: 1 as const, requestId: packet.id, packetRevision: draft.packetRevision,
    decisions, missing: structuredClone(draft.missing), inventoryConfirmed: summary.mode === 'approve',
    ...(reclassify.length ? { reclassify } : {}),
  };
}

export function newPlanDraft(packet: PlanPacket): PlanDraft {
  return { packetRevision: packet.revision, decisions: {}, missing: [], inventoryConfirmed: false, reclassify: [] };
}

/** Pixels around a box, as [r,g,b] samples, from RGBA image data of the whole comp. */
export function ringSamples(data: ArrayLike<number>, width: number, height: number, box: Box, margin = 0.02): [number, number, number][] {
  const x0 = Math.max(0, Math.floor((box.x - margin) * width)), x1 = Math.min(width - 1, Math.ceil((box.x + box.w + margin) * width));
  const y0 = Math.max(0, Math.floor((box.y - margin) * height)), y1 = Math.min(height - 1, Math.ceil((box.y + box.h + margin) * height));
  const ix0 = Math.floor(box.x * width), ix1 = Math.ceil((box.x + box.w) * width), iy0 = Math.floor(box.y * height), iy1 = Math.ceil((box.y + box.h) * height);
  const out: [number, number, number][] = [];
  const step = Math.max(1, Math.round(Math.max(x1 - x0, y1 - y0) / 80));
  for (let y = y0; y <= y1; y += step) for (let x = x0; x <= x1; x += step) {
    if (x >= ix0 && x < ix1 && y >= iy0 && y < iy1) continue;
    const i = (y * width + x) * 4;
    if (data[i + 3] < 200) continue;
    out.push([data[i], data[i + 1], data[i + 2]]);
  }
  return out;
}
/** Per-channel median as a hex colour; undefined when nothing surrounds the box. */
export function medianColor(samples: [number, number, number][]): string | undefined {
  if (!samples.length) return undefined;
  const channel = (n: number) => { const v = samples.map(s => s[n]).sort((a, b) => a - b); return v[v.length >> 1]; };
  return '#' + [0, 1, 2].map(n => channel(n).toString(16).padStart(2, '0')).join('');
}

/** The comp crop for a plan region: the box plus a modest margin, scaled so the region fills the
 * pane width (context lives on the comp map, not in this crop). A region so thin that it would
 * render under `minHeight` px is scaled up to that height and shown as a centred segment. */
export function planView(box: Box, compWidth: number, compHeight: number, width: number, height: number, maxScale = 4, minHeight = 24) {
  const bw = box.w * compWidth, bh = box.h * compHeight;
  const margin = Math.min(24, Math.max(8, 0.04 * Math.max(bw, bh)));
  let vw = Math.min(compWidth, bw + margin * 2), vh = Math.min(compHeight, bh + margin * 2);
  let scale = Math.min(maxScale, width / vw, height / vh);
  if (bh * scale < minHeight && bh > 0) {
    scale = Math.min(maxScale, minHeight / bh, height / vh);
    vw = Math.min(vw, width / scale);
  }
  const cx = (box.x + box.w / 2) * compWidth, cy = (box.y + box.h / 2) * compHeight;
  const x = Math.max(0, Math.min(compWidth - vw, cx - vw / 2)), y = Math.max(0, Math.min(compHeight - vh, cy - vh / 2));
  return { scale, width: vw * scale, height: vh * scale, view: { x: x / compWidth, y: y / compHeight, w: vw / compWidth, h: vh / compHeight } };
}

/** Largest same-scale layout for two crops of aspect `ratio` (w/h): side by side or stacked. */
export function pairLayout(ratio: number, width: number, height: number, gap: number, caption: number, maxScale = Infinity, natural?: { w: number; h: number }) {
  const fit = (w: number, h: number) => {
    let cw = Math.max(0, w), ch = cw / ratio;
    if (ch > h) { ch = Math.max(0, h); cw = ch * ratio; }
    if (natural && cw > natural.w * maxScale) { cw = natural.w * maxScale; ch = cw / ratio; }
    return { w: cw, h: ch };
  };
  const side = fit((width - gap) / 2, height - caption);
  const stacked = fit(width, (height - gap) / 2 - caption);
  return side.w * side.h >= stacked.w * stacked.h ? { direction: 'row' as const, ...side } : { direction: 'column' as const, ...stacked };
}

// ---------------------------------------------------------------------------
// Stage flow (intro, one item at a time, summary). Pure helpers for the view.

const WORDS = ['no', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'];
const word = (n: number) => WORDS[n] ?? String(n);
const Cap = (s: string) => s[0].toUpperCase() + s.slice(1);

/** What the reviewer is about to do, in one sentence (the intro screen). */
export function introLine(packet: PlanPacket, draft: PlanDraft, history?: PlanHistory | null) {
  const pending = packet.components.filter(c => itemState(c, draft) === 'pending').length;
  if (history && packet.round > 1) {
    const worked = packet.components.filter(c => ['changed', 'added'].includes(history.changes[c.id]?.kind ?? '') || history.feedback?.[c.id]).length;
    const kept = packet.components.filter(c => itemState(c, draft) === 'approved').length;
    return `The agent worked on your notes for ${word(worked)} ${worked === 1 ? 'item' : 'items'}. ${Cap(word(kept))} ${kept === 1 ? 'approval is' : 'approvals are'} kept.`;
  }
  const minutes = Math.max(1, Math.round(pending * 15 / 60));
  return `${Cap(word(pending))} ${pending === 1 ? 'thing' : 'things'} to check before any page code is written. About ${word(minutes)} ${minutes === 1 ? 'minute' : 'minutes'}.`;
}

/** The last round's request for this item, and what it looked like then. */
/** Guidance prefilled when the reviewer asks for a composite to be split. */
export const SPLIT_GUIDANCE = 'Frame, view and moving parts as separate pieces, e.g. the shutters.';
/** Flags an asset carries (a baked composite, painted pixels): shown as a note on the stage. */
export function assetFlags(item: PlanItem) { return item.role === 'asset' ? item.flags ?? [] : []; }
export const isBakedComposite = (item: PlanItem) => assetFlags(item).some(f => f.id === 'baked-composite');
export const isSplit = (d?: PlanDecision) => d?.action === 'revise' && d.split === true;

export function priorRound(id: string, history?: PlanHistory | null) {
  if (!history) return null;
  // A split region comes back as new items (window-frame, window-view): link them to the
  // region they came from by id prefix, so the reviewer sees their own note again.
  const splitFrom = history.feedback?.[id] ? undefined : Object.entries(history.feedback ?? {})
    .filter(([from, f]) => f.decision.action === 'revise' && f.decision.split && id.startsWith(`${from}-`))
    .sort((a, b) => b[0].length - a[0].length)[0];
  if (splitFrom) {
    const [from, f] = splitFrom;
    return { round: f.round, action: 'split', words: (f.decision.feedback ?? '').trim(), splitFrom: history.packet.components.find(c => c.id === from)?.name ?? from, beforeUrl: undefined, wasCode: false, wasKind: undefined, wasNote: '' };
  }
  const asked = history.feedback?.[id];
  const before = history.packet.components.find(c => c.id === id);
  const beforeRegion = history.packet.codeRegions?.find(r => r.id === id);
  const change = history.changes[id]?.kind;
  if (!asked && change !== 'changed') return null;
  return {
    round: asked?.round ?? history.packet.round,
    action: asked?.decision.action,
    words: (asked?.decision.feedback ?? '').trim(),
    beforeUrl: before?.role === 'asset' ? before.preview.url : undefined,
    // A region that was planned in code last round and is now an asset.
    wasCode: (before?.role === 'plan' || (!before && !!beforeRegion)),
    wasKind: before?.kind ?? beforeRegion?.kind,
    wasNote: before?.note ?? beforeRegion?.note ?? '',
    splitFrom: undefined as string | undefined,
  };
}

/** Equal-height figures for aspect ratios (w/h): in a row, or stacked at equal width when
 * that shows more. Each figure reserves `caption` px above it; `natural` caps the scale. */
export function figureLayout(ratios: number[], width: number, height: number, gap: number, caption: number, maxScale = 4, natural?: { w: number; h: number }) {
  const n = ratios.length;
  let rowH = Math.max(0, Math.min(height - caption, (width - gap * (n - 1)) / ratios.reduce((a, r) => a + r, 0)));
  let colW = Math.max(0, Math.min(width, (height - n * caption - gap * (n - 1)) / ratios.reduce((a, r) => a + 1 / r, 0)));
  if (natural) { rowH = Math.min(rowH, natural.h * maxScale); colW = Math.min(colW, natural.w * maxScale); }
  const rowArea = ratios.reduce((a, r) => a + r * rowH * rowH, 0);
  const colArea = ratios.reduce((a, r) => a + colW * colW / r, 0);
  return rowArea >= colArea
    ? { direction: 'row' as const, sizes: ratios.map(r => ({ w: r * rowH, h: rowH })) }
    : { direction: 'column' as const, sizes: ratios.map(r => ({ w: colW, h: colW / r })) };
}

/** Loupe: the translate that centres point (fx, fy) of a w x h image, scaled by zoom, in a lens of radius r. */
export function loupeOffset(fx: number, fy: number, w: number, h: number, r: number, zoom: number) {
  return { x: r - fx * w * zoom, y: r - fy * h * zoom };
}

/** Progress row: one light per item. */
export function progressLights(packet: PlanPacket, draft: PlanDraft, current?: string) {
  return planQueue(packet).map(c => ({ id: c.id, name: c.name, state: itemState(c, draft), current: c.id === current }));
}

/** The submit line on the summary: what will be sent, in counts. */
export function sendLabel(packet: PlanPacket, draft: PlanDraft) {
  const s = planSummary(packet, draft);
  if (s.mode === 'approve') return 'Approve plan and assets';
  const splits = packet.components.filter(c => isSplit(currentDecision(c, draft))).length;
  const notes = s.revise - splits;
  const parts = [notes ? `${notes} ${notes === 1 ? 'note' : 'notes'}` : '', splits ? `${splits} to split` : '', s.reclassify ? `${s.reclassify} to become ${s.reclassify === 1 ? 'an image' : 'images'}` : '', s.missing ? `${s.missing} missing` : ''].filter(Boolean);
  return `Send notes (${parts.join(', ')})`;
}