@domandigital/craft 0.20.2 → 0.20.4

package/dist/cli-6AZVLNWL.js

@@ -0,0 +1,654 @@
+import {
+  decodePng
+} from "./chunk-JYNXGCYZ.js";
+import {
+  ADDITIONS,
+  CHANGE_CLASSES,
+  CHANGE_STEPS,
+  CONFIDENCE_LENSES,
+  CONVENTION,
+  DIRECTION_VERSION,
+  EVIDENCE_KINDS,
+  INSPECTED_KINDS,
+  PAGE_TYPES,
+  PREFERENCE,
+  PROPOSED,
+  REVIEW_BASES,
+  SECTION_ROLES,
+  VIEWPORTS,
+  checkReason,
+  researchPrompt,
+  validateDirection
+} from "./chunk-S3L7TEJF.js";
+import {
+  parseFlags
+} from "./chunk-NQAYRK2K.js";
+import {
+  toJson
+} from "./chunk-QIEDBL4J.js";
+import {
+  readSnapshot
+} from "./chunk-WUACK2HX.js";
+import {
+  deltaEOk,
+  fingerprint,
+  formatHex,
+  hexToOklch,
+  isAiViolet,
+  isCream,
+  oklchToRgb,
+  parseColour
+} from "./chunk-JGWOA4LI.js";
+import "./chunk-7DQDF3VL.js";
+import "./chunk-QYBAVU3P.js";
+
+// src/direction/cli.ts
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+
+// src/direction/init.ts
+var hex = (o) => {
+  const { r, g, b } = oklchToRgb(o);
+  const clamp = (n) => Math.min(1, Math.max(0, n));
+  return formatHex({ r: clamp(r), g: clamp(g), b: clamp(b) });
+};
+function initDirection(input) {
+  const fp = input.current;
+  const empty = (value) => ({ value, because: "", evidence: [] });
+  const choices = fp ? {
+    ...fp.accent ? { accent: empty(hex(fp.accent)) } : {},
+    ground: empty(hex(fp.ground)),
+    display: empty(fp.display.family),
+    body: empty(fp.body.family),
+    ...fp.roundness !== null ? { shape: empty(fp.roundness >= 0.45 ? "pill buttons" : fp.roundness <= 0.05 ? "square corners" : `corners at ${Math.round(fp.roundness * 100)}% of button height`) } : {}
+  } : {};
+  const part = () => ({ value: "", evidence: [] });
+  return {
+    $schema: "https://unpkg.com/@domandigital/craft/art-direction.schema.json",
+    version: DIRECTION_VERSION,
+    client: input.client ?? "",
+    brief: input.brief ?? "",
+    // Empty on purpose, like the reasons: the first validate lists the job and the structure as undecided.
+    job: {
+      statement: { verb: "", object: "", context: "" },
+      functional: part(),
+      emotional: part(),
+      social: part(),
+      consideration: { value: "low", because: "", evidence: [] },
+      objections: [],
+      language: [],
+      evidence: []
+    },
+    hierarchy: {
+      home: {
+        primaryAction: { value: "", positions: [], because: "" },
+        order: fp?.sections?.length ? fp.sections.map((s) => ({ role: s.role, because: "" })) : [],
+        lead: { value: "", because: "" },
+        journey: []
+      }
+    },
+    sources: [],
+    choices,
+    ...input.exceptions?.length ? { exceptions: input.exceptions } : {}
+  };
+}
+
+// src/direction/propose.ts
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function toLab(r, g, b) {
+  const lr = srgbToLinear(r / 255);
+  const lg = srgbToLinear(g / 255);
+  const lb = srgbToLinear(b / 255);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
+}
+function paletteFromPixels(rgba, k = 6, maxSamples = 2e4) {
+  const total = Math.floor(rgba.length / 4);
+  const step = Math.max(1, Math.floor(total / maxSamples));
+  const px = [];
+  for (let i = 0; i < total; i += step) {
+    const o = i * 4;
+    if (rgba[o + 3] < 128) continue;
+    px.push({ lab: toLab(rgba[o], rgba[o + 1], rgba[o + 2]), rgb: [rgba[o], rgba[o + 1], rgba[o + 2]] });
+  }
+  if (px.length === 0) return [];
+  const sorted = [...px].sort((a, b) => a.lab[0] - b.lab[0]);
+  const n = Math.min(k, px.length);
+  let centres = Array.from({ length: n }, (_, i) => sorted[Math.floor((i + 0.5) / n * sorted.length)].lab.slice());
+  let assign = new Array(px.length).fill(0);
+  for (let iter = 0; iter < 12; iter += 1) {
+    assign = px.map((p) => {
+      let best = 0;
+      let bestD = Infinity;
+      centres.forEach((c, j) => {
+        const d = (p.lab[0] - c[0]) ** 2 + (p.lab[1] - c[1]) ** 2 + (p.lab[2] - c[2]) ** 2;
+        if (d < bestD) {
+          bestD = d;
+          best = j;
+        }
+      });
+      return best;
+    });
+    centres = centres.map((c, j) => {
+      const members = px.filter((_, i) => assign[i] === j);
+      if (members.length === 0) return c;
+      return [0, 1, 2].map((d) => members.reduce((s, m) => s + m.lab[d], 0) / members.length);
+    });
+  }
+  return centres.map((_, j) => {
+    const members = px.filter((__, i) => assign[i] === j);
+    if (members.length === 0) return null;
+    const avg = [0, 1, 2].map((d) => members.reduce((s, m) => s + m.rgb[d], 0) / members.length / 255);
+    const hex2 = formatHex({ r: avg[0], g: avg[1], b: avg[2] });
+    return { hex: hex2, share: members.length / px.length, oklch: hexToOklch(hex2) };
+  }).filter((c) => c !== null).sort((a, b) => b.share - a.share);
+}
+var chromatic = (o) => o.c >= 0.04 && o.l >= 0.2 && o.l <= 0.85;
+function accentCandidates(input) {
+  const out = [];
+  for (const s of input.sources) {
+    for (const c of s.colours ?? []) {
+      const parsed = parseColour(c);
+      if (!parsed || !chromatic(parsed.oklch)) continue;
+      const o = parsed.oklch;
+      const siblings = [
+        ...(input.estate ?? []).map((e) => ({ id: e.id, d: e.fingerprint.accent ? deltaEOk(o, e.fingerprint.accent) : 1 })),
+        ...(input.declared ?? []).flatMap((e) => {
+          const p = parseColour(e.accent);
+          return p ? [{ id: `${e.id} (declared)`, d: deltaEOk(o, p.oklch) }] : [];
+        })
+      ];
+      const nearest = siblings.sort((a, b) => a.d - b.d)[0];
+      const penalty = isAiViolet(o) ? 1 : 0;
+      out.push({
+        value: c.startsWith("#") ? c.toLowerCase() : c,
+        evidence: [s.id],
+        note: `from ${s.id} (${s.kind})${nearest ? `; nearest estate accent ${nearest.id} at \u0394E ${nearest.d.toFixed(2)}` : ""}${penalty ? "; in the reflex violet band" : ""}`,
+        score: (nearest ? Math.min(nearest.d, 0.3) : 0.3) - penalty + o.c
+      });
+    }
+  }
+  return out.sort((a, b) => b.score - a.score).map(({ score: _s, ...rest }) => rest);
+}
+function groundCandidates(input) {
+  const out = [];
+  for (const s of input.sources) {
+    for (const c of s.colours ?? []) {
+      const parsed = parseColour(c);
+      if (!parsed || parsed.oklch.l < 0.9) continue;
+      out.push({ value: c, evidence: [s.id], note: `a light colour from ${s.id}${isCream(parsed.oklch) ? "; reads as the cream tell, needs its reason" : ""}` });
+    }
+  }
+  return out;
+}
+function typeCandidates(input) {
+  return input.sources.filter((s) => s.lettering).map((s) => ({ value: "", evidence: [s.id], note: `find a face with the character of "${s.lettering}" on ${s.id}` }));
+}
+function propose(input) {
+  const proposals = [
+    { key: "accent", candidates: accentCandidates(input) },
+    { key: "ground", candidates: groundCandidates(input) },
+    { key: "display", candidates: typeCandidates(input) }
+  ];
+  const choices = {};
+  const draft = (p) => {
+    const top = p.candidates[0];
+    if (!top || !top.value) return void 0;
+    const source = input.sources.find((s) => s.id === top.evidence[0]);
+    return {
+      value: top.value,
+      because: `${PROPOSED} taken from the ${source.id}: ${source.note} Confirm it matches, then rewrite this in your own words.`,
+      evidence: top.evidence
+    };
+  };
+  for (const p of proposals) {
+    const c = draft(p);
+    if (c) choices[p.key] = c;
+  }
+  return {
+    proposals,
+    direction: { version: DIRECTION_VERSION, client: input.client, brief: input.brief, sources: input.sources, choices }
+  };
+}
+
+// src/direction/review.ts
+var isObject = (x) => Boolean(x) && typeof x === "object" && !Array.isArray(x);
+var wordCount = (x) => typeof x === "string" ? x.trim().split(/\s+/).filter(Boolean).length : 0;
+var includes = (list, x) => list.includes(x);
+var STEP_RANK = new Map(CHANGE_STEPS.map((s, i) => [s, i]));
+var CLASS_RANK = { "no-change": 0, "optional-refinement": 1, "design-hypothesis": 2, "confirmed-correction": 3 };
+var RENDERED_KINDS = ["screenshot", "rendered", "measurement"];
+var isStructural = (step) => step === "restructure" || step === "new-component";
+var GALLERY = /\b(?:gallery|galleries|carousel|slideshow|slider|swipe(?:able)?|rotating)\b/i;
+function plain(at, text) {
+  if (wordCount(text) < 8) return [{ severity: "error", at, message: "a sentence at least: say why, in this visitor's terms" }];
+  const t = text;
+  if (PREFERENCE.test(t)) return [{ severity: "error", at, message: "that is a preference, not a reason. Say what it does for this visitor." }];
+  const c = t.match(CONVENTION);
+  if (c) return [{ severity: "error", at, message: `"${c[0]}" is the category's default speaking, not a reason. Say what in this visitor's job it answers.` }];
+  return [];
+}
+function checkProposalShape(at, p, required) {
+  const problems = [];
+  const err = (rest, message) => problems.push({ severity: "error", at: `${at}${rest}`, message });
+  if (!isObject(p)) {
+    if (required) err("", "a proposal is an object: change, step, and optionally adds and touches");
+    return problems;
+  }
+  if (wordCount(p.change) < 3) err(".change", "say what changes, in a few words");
+  if (!includes(CHANGE_STEPS, p.step)) err(".step", `one of ${CHANGE_STEPS.join(", ")}: the smallest step that does it`);
+  if (p.adds !== void 0) {
+    if (!Array.isArray(p.adds) || p.adds.some((a) => !includes(ADDITIONS, a))) err(".adds", `a list drawn from ${ADDITIONS.join(", ")}`);
+  }
+  if (p.comparisons !== void 0) {
+    if (!Array.isArray(p.comparisons)) err(".comparisons", "a list comparing each relevant existing component");
+    else p.comparisons.forEach((c, i) => {
+      if (!isObject(c) || typeof c.existing !== "string" || !c.existing.trim() || typeof c.samePurpose !== "boolean") {
+        err(`.comparisons[${i}]`, "existing, samePurpose and because are required");
+      } else problems.push(...plain(`${at}.comparisons[${i}].because`, c.because));
+    });
+  }
+  if (p.touches !== void 0 && !includes(SECTION_ROLES, p.touches)) err(".touches", `a section role: ${SECTION_ROLES.join(", ")}`);
+  return problems;
+}
+function checkEvidenceShape(at, e) {
+  const problems = [];
+  const err = (rest, message) => problems.push({ severity: "error", at: `${at}${rest}`, message });
+  if (!isObject(e)) return [{ severity: "error", at, message: "evidence is an object: kind, ref, and a viewport for anything rendered" }];
+  if (!includes(EVIDENCE_KINDS, e.kind)) err(".kind", `one of ${EVIDENCE_KINDS.join(", ")}`);
+  if (typeof e.ref !== "string" || !e.ref.trim()) err(".ref", "where it can be found: a screenshot path, a selector, a quotation, a report");
+  if (e.viewport !== void 0 && !includes(VIEWPORTS, e.viewport)) err(".viewport", `one of ${VIEWPORTS.join(", ")}`);
+  if (includes(RENDERED_KINDS, e.kind) && e.viewport === void 0) err(".viewport", "say which width this was seen at: what is seen at one width is not evidence about another");
+  return problems;
+}
+function checkNoteShape(i, n) {
+  const base = `notes[${i}]`;
+  const problems = [];
+  const err = (rest, message) => problems.push({ severity: "error", at: `${base}${rest}`, message });
+  if (typeof n.id !== "string" || !n.id.trim()) err(".id", "a short name for this note");
+  if (n.page !== void 0 && !includes(PAGE_TYPES, n.page)) err(".page", `one of ${PAGE_TYPES.join(", ")}`);
+  if (!includes(CONFIDENCE_LENSES, n.lens)) err(".lens", `one of ${CONFIDENCE_LENSES.join(", ")}`);
+  if (wordCount(n.observation) < 3) err(".observation", "what was said or seen, as it was said");
+  if (typeof n.raisedBy !== "string" || !n.raisedBy.trim()) err(".raisedBy", "who said it, or what found it");
+  if (!includes(REVIEW_BASES, n.basis)) err(".basis", `one of ${REVIEW_BASES.join(", ")}`);
+  if (!Array.isArray(n.evidence)) err(".evidence", "a list, possibly empty: what supports the note");
+  else n.evidence.forEach((e, j) => problems.push(...checkEvidenceShape(`${base}.evidence[${j}]`, e)));
+  if (n.appliesTo !== void 0 && (!Array.isArray(n.appliesTo) || n.appliesTo.some((v) => !includes(VIEWPORTS, v)))) err(".appliesTo", `a list drawn from ${VIEWPORTS.join(", ")}`);
+  if (n.existing !== void 0 && (!Array.isArray(n.existing) || n.existing.some((x) => typeof x !== "string"))) err(".existing", "a list of what the page already has");
+  if (n.suggested !== void 0) problems.push(...checkProposalShape(`${base}.suggested`, n.suggested, false));
+  const r = n.recommend;
+  if (!isObject(r)) {
+    err(".recommend", "the recommendation: a class, and for anything but no-change a change, a step and a reason");
+    return problems;
+  }
+  if (!includes(CHANGE_CLASSES, r.class)) {
+    err(".recommend.class", `one of ${CHANGE_CLASSES.join(", ")}. no-change is a result, not a failure to answer.`);
+    return problems;
+  }
+  if (r.class === "no-change") {
+    if (r.because !== void 0) problems.push(...plain(`${base}.recommend.because`, r.because));
+    return problems;
+  }
+  problems.push(...checkProposalShape(`${base}.recommend`, r, true));
+  problems.push(...plain(`${base}.recommend.because`, r.because));
+  const bigger = isStructural(r.step) || Array.isArray(r.adds) && r.adds.length > 0;
+  if (bigger) {
+    const smaller = Array.isArray(r.smaller) ? r.smaller : [];
+    if (smaller.length === 0) err(".recommend.smaller", "a structural change, or one that adds a carousel, script, dependency, animation, testimonial, call to action or repeated content, says which smaller steps were considered and why none was enough");
+    const limit = STEP_RANK.get(r.step) ?? 0;
+    smaller.forEach((s, j) => {
+      const ok = isObject(s) && includes(CHANGE_STEPS, s.step) && (limit === 0 || (STEP_RANK.get(s.step) ?? 99) < limit);
+      if (!ok) err(`.recommend.smaller[${j}].step`, "a step on the ladder below the one recommended");
+      if (isObject(s)) problems.push(...plain(`${base}.recommend.smaller[${j}].whyNot`, s.whyNot));
+    });
+  } else {
+    problems.push(...plain(`${base}.recommend.whyEnough`, r.whyEnough));
+  }
+  if (r.class === "design-hypothesis" && wordCount(r.validation) < 4) err(".recommend.validation", "a hypothesis says how it would be checked: a phone test, five visitors, a read of the enquiries");
+  if (r.requires !== void 0) {
+    if (!Array.isArray(r.requires) || r.requires.some((q) => !isObject(q) || wordCount(q.what) < 2)) err(".recommend.requires", "a list of {what, source?}: facts or assets the change depends on");
+  }
+  return problems;
+}
+function whyNot(p, ctx) {
+  const reasons = [];
+  const adds = Array.isArray(p.adds) ? p.adds : [];
+  if (adds.includes("carousel")) {
+    for (const have of new Set(ctx.existing.filter((e) => GALLERY.test(e)))) {
+      const compared = p.comparisons?.filter((c) => c.existing === have) ?? [];
+      if (compared.length !== 1) reasons.push(`the page already has "${have}". Compare its purpose, content and placement before adding another carousel; duplication is not established by its name.`);
+      else if (compared[0].samePurpose) reasons.push(`the comparison identifies the same purpose as "${have}": ${compared[0].because}. Reuse or adjust that component.`);
+    }
+  }
+  const defensible = (ctx.basis === "observed" || ctx.basis === "inferred") && ctx.impact;
+  if ((isStructural(p.step) || adds.length > 0) && !defensible) {
+    reasons.push("it is a structural change or adds something that costs, and the problem under it is neither observed nor inferred with a stated visitor impact. A preference does not justify it.");
+  }
+  if (p.step === "remove-redundancy" && !(ctx.basis === "observed" && ctx.impact)) {
+    reasons.push("it removes information, and nothing observed shows it is redundant or what it costs the visitor. Useful detail stays unless it is shown not to be.");
+  }
+  if (p.touches && ctx.placed.has(p.touches) && ctx.basis !== "observed") {
+    reasons.push(`the declared order already places "${p.touches}" with a reason. Only something observed overrides a reasoned decision.`);
+  }
+  return reasons;
+}
+function widthsOf(evidence) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const e of evidence) {
+    if (e.viewport) seen.add(e.viewport);
+    else if (e.kind === "content") VIEWPORTS.forEach((v) => seen.add(v));
+  }
+  return VIEWPORTS.filter((v) => seen.has(v));
+}
+function assessReview(input, direction) {
+  const problems = [];
+  const results = [];
+  const fail = (at, message) => problems.push({ severity: "error", at, message });
+  const report = () => {
+    const n = (o) => results.filter((r) => r.outcome === o).length;
+    const summary = { change: n("change"), hold: n("hold"), noChange: n("no-change"), gatherEvidence: n("gather-evidence"), verdict: "" };
+    summary.verdict = results.length === 0 ? "The review has no notes to assess." : summary.change + summary.hold + summary.gatherEvidence === 0 ? "The existing design is already appropriate for what was reviewed. No change is recommended." : `${summary.change} change${summary.change === 1 ? "" : "s"} recommended, ${summary.hold} held for something nobody has supplied, ${summary.gatherEvidence} to establish first, ${summary.noChange} needing no change.`;
+    return { valid: !problems.some((p) => p.severity === "error"), problems, results, summary };
+  };
+  if (!isObject(input)) {
+    fail("", "a review is an object: version, subject and notes");
+    return report();
+  }
+  if (input.context !== void 0 && !["publication", "protected-staging"].includes(input.context)) fail("context", "publication or protected-staging");
+  if (input.version !== 1) fail("version", "version is 1");
+  if (typeof input.subject !== "string" || !input.subject.trim()) fail("subject", "who or what was reviewed");
+  if (!Array.isArray(input.notes)) {
+    fail("notes", "a list of notes");
+    return report();
+  }
+  const job = direction.job;
+  if (!job) {
+    fail("", "a review is read against the visitor's job, and the art direction has no job map yet. Record it first (craft direction research).");
+    return report();
+  }
+  const ids = /* @__PURE__ */ new Set();
+  input.notes.forEach((raw, i) => {
+    if (!isObject(raw)) return fail(`notes[${i}]`, "a note is an object");
+    const shape = checkNoteShape(i, raw);
+    if (typeof raw.id === "string") {
+      if (ids.has(raw.id)) shape.push({ severity: "error", at: `notes[${i}].id`, message: `"${raw.id}" is used twice` });
+      ids.add(raw.id);
+    }
+    problems.push(...shape);
+    if (shape.length > 0) return;
+    const note = raw;
+    const page = note.page ?? "home";
+    const adjustments = [];
+    const hierarchy = direction.hierarchy?.[page];
+    const sources = Array.isArray(direction.sources) ? direction.sources : [];
+    const inspected = note.evidence.filter((e) => includes(INSPECTED_KINDS, e.kind));
+    let basis = note.basis;
+    if (basis === "observed" && inspected.length === 0) {
+      basis = note.evidence.length > 0 ? "inferred" : "unknown";
+      adjustments.push(
+        note.evidence.length > 0 ? "declared observed, but everything cited is reported (an audit, a stakeholder, a customer) and nothing was inspected. Read as inferred until someone looks." : "declared observed, but nothing is cited. Read as unknown."
+      );
+    } else if (basis === "inferred" && note.evidence.length === 0) {
+      basis = "unknown";
+      adjustments.push("declared inferred, but nothing supports it. Read as unknown.");
+    }
+    const impactProblems = typeof note.impact === "string" ? checkReason({ at: `notes[${i}].impact`, because: note.impact, sources, tie: "job", job }) : [];
+    const impact = typeof note.impact === "string" && impactProblems.length === 0;
+    const wantsChange = note.recommend.class !== "no-change";
+    if (!impact && (wantsChange || note.suggested)) {
+      adjustments.push(
+        typeof note.impact === "string" ? `no visitor impact tied to this client's job (${impactProblems[0]?.message ?? "none given"}).` : "no visitor impact stated. Something that costs the visitor nothing they can name is a fact or a preference, not an issue, and is not read as one."
+      );
+      if (basis === "inferred") basis = "preference";
+    }
+    const ctx = {
+      note,
+      basis,
+      impact,
+      existing: [...note.existing ?? [], ...(hierarchy?.confidence?.proof ?? []).map((p) => p.what).filter((w) => typeof w === "string")],
+      placed: new Set((hierarchy?.order ?? []).map((o) => o.role))
+    };
+    const examined = widthsOf(note.evidence);
+    const wanted = note.appliesTo ?? (examined.length > 0 ? examined : [...VIEWPORTS]);
+    const claimed = wanted.filter((v) => examined.includes(v));
+    const unknown = VIEWPORTS.filter((v) => wanted.includes(v) && !examined.includes(v));
+    if (unknown.length > 0) adjustments.push(`nothing here was looked at on ${unknown.join(" or ")}, so the note says nothing about it. That stays unknown until it is examined there.`);
+    const rec = note.recommend;
+    const recReasons = wantsChange ? whyNot(rec, ctx) : [];
+    const sugReasons = note.suggested ? whyNot(note.suggested, ctx) : [];
+    const ceiling = basis === "observed" ? impact ? "confirmed-correction" : "optional-refinement" : basis === "inferred" ? "design-hypothesis" : basis === "preference" ? "optional-refinement" : "no-change";
+    let effective = wantsChange ? rec.class : "no-change";
+    if (basis !== "unknown" && CLASS_RANK[effective] > CLASS_RANK[ceiling]) {
+      adjustments.push(`declared ${rec.class}, but a problem that is ${basis}${basis === "observed" && !impact ? " with no stated visitor impact" : ""} supports at most ${ceiling}.`);
+      effective = ceiling;
+    }
+    let withdrawn;
+    if (wantsChange && recReasons.length > 0) {
+      withdrawn = recReasons;
+      effective = "no-change";
+      adjustments.push("the recommended change is withdrawn: " + recReasons.join(" "));
+    }
+    const missing = (rec.requires ?? []).filter((q) => !q.source || !sources.some((s) => s.id === q.source));
+    const outstanding = missing.map((q) => q.what);
+    const blocking = missing.filter((q) => !(input.context === "protected-staging" && q.kind === "asset" && q.phase === "publication" && q.placeholder));
+    if (missing.length > blocking.length) adjustments.push("Protected staging may reserve the explicitly marked placeholder. Required assets remain outstanding for publication; no fact or photograph has been supplied by this review.");
+    let outcome;
+    if (basis === "unknown") {
+      outcome = "gather-evidence";
+      effective = "no-change";
+      if (wantsChange) adjustments.push(`nothing is recommended until the problem is established${rec.validation ? `: ${rec.validation}` : ". Ask the client, or look, first."}`);
+    } else if (effective === "no-change") outcome = "no-change";
+    else if (blocking.length > 0) outcome = "hold";
+    else outcome = "change";
+    if (outcome === "hold") adjustments.push(`held: it depends on ${blocking.map((o) => `"${o.what}"`).join(", ")}, and no source supplies it. Do not write it in. Ask the client.`);
+    let suggested;
+    if (note.suggested) {
+      const recRank = STEP_RANK.get(rec.step ?? "") ?? -1;
+      const sugRank = STEP_RANK.get(note.suggested.step) ?? 0;
+      const sugAdds = (note.suggested.adds ?? []).length;
+      let standing;
+      const reasons = [...sugReasons];
+      if (sugReasons.length > 0) standing = "not-supported";
+      else if (effective === "no-change") {
+        standing = "not-needed";
+        reasons.push("the existing design already answers the problem, or nothing is yet established to answer.");
+      } else if (sugRank > recRank || sugAdds > 0 && (rec.adds ?? []).length === 0) {
+        standing = "comparison-needed";
+        reasons.push("Compare the proposals before selecting one. A smaller implementation is not evidence of a better visitor experience; compare their adequacy against the stated problem and rendered result.");
+      } else standing = "supported";
+      suggested = { standing, reasons };
+    }
+    results.push({
+      id: note.id,
+      page,
+      lens: note.lens,
+      basis: { declared: note.basis, effective: basis },
+      ...suggested ? { suggested } : {},
+      recommend: { declared: rec.class, effective, ...wantsChange ? { step: rec.step } : {}, ...withdrawn ? { withdrawn } : {} },
+      outcome,
+      widths: { examined, claimed, unknown },
+      adjustments,
+      outstanding,
+      publicationReady: outstanding.length === 0
+    });
+  });
+  return report();
+}
+
+// src/direction/cli.ts
+var readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+async function snapshotFrom(target, cwd) {
+  if (!target) return void 0;
+  if (/^https?:\/\//.test(target)) {
+    const { snapshotUrl } = await import("./audit-BN2GSFKT.js");
+    return snapshotUrl(target);
+  }
+  return readSnapshot(readJson(resolve(cwd, target)), target);
+}
+function declaredFrom(path, cwd) {
+  if (!path || !path.endsWith(".json")) return [];
+  const register = readJson(resolve(cwd, path));
+  return register.sites ?? [];
+}
+var TEXT_SOURCE = /\.(?:txt|md|markdown|csv|json|html?)$/i;
+function estateFrom(dir, cwd) {
+  if (!dir) return [];
+  const root = resolve(cwd, dir);
+  if (root.endsWith(".json")) {
+    const register = readJson(root);
+    return (register.sites ?? []).filter((s) => s.fingerprint).map((s) => ({ id: s.id, fingerprint: s.fingerprint }));
+  }
+  return readdirSync(root).filter((f) => f.endsWith(".json")).flatMap((f) => {
+    try {
+      const snap = readSnapshot(readJson(join(root, f)), f);
+      return snap.fonts ? [{ id: f.replace(/(\.snapshot)?\.json$/, ""), fingerprint: fingerprint(snap) }] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+async function runDirection(args, io) {
+  try {
+    const flags = parseFlags(args);
+    if (typeof flags === "string") throw new Error(flags);
+    const [sub] = flags.positional;
+    const file = resolve(io.cwd, flags.direction ?? "art-direction.json");
+    if (sub === "research") {
+      const base = existsSync(file) ? readJson(file) : {};
+      const brief = flags.brief ?? base.brief;
+      if (!brief || brief.trim().split(/\s+/).length < 5) throw new Error('usage: craft direction research --brief "<who, where, what they do>" [--visual], or run it next to an art-direction.json with a brief');
+      io.out(researchPrompt({ brief, client: flags.client ?? base.client, visual: flags.visual }));
+      return 0;
+    }
+    if (sub === "review") {
+      if (!flags.notes) throw new Error("usage: craft direction review --notes <design-review.json> [--direction <file>] [--json]");
+      const notesFile = resolve(io.cwd, flags.notes);
+      if (!existsSync(notesFile)) throw new Error(`no such file: ${flags.notes}`);
+      const review = readJson(notesFile);
+      const report = assessReview(review, existsSync(file) ? readJson(file) : {});
+      io.out(flags.json ? toJson(report) : renderReview(review, report));
+      return report.valid ? 0 : 1;
+    }
+    const page = flags.page ?? "home";
+    if (!PAGE_TYPES.includes(page)) throw new Error(`--page takes one of ${PAGE_TYPES.join(", ")}`);
+    const snapshot = await snapshotFrom(flags.snapshot, io.cwd);
+    const current = snapshot ? fingerprint(snapshot) : void 0;
+    if (sub === "init") {
+      const out = resolve(io.cwd, flags.out ?? "art-direction.json");
+      if (existsSync(out) && !flags.out) {
+        const existing = readJson(out);
+        if (existing.version !== void 0) throw new Error(`${out} already records choices. Pass --out to write elsewhere.`);
+        const next = initDirection({ client: flags.client, brief: flags.brief, current, exceptions: existing.exceptions });
+        writeFileSync(out, `${JSON.stringify(next, null, 2)}
+`);
+      } else {
+        writeFileSync(out, `${JSON.stringify(initDirection({ client: flags.client, brief: flags.brief, current }), null, 2)}
+`);
+      }
+      io.out(`craft direction: wrote ${out}. Add the sources and a reason for every choice, then run craft direction validate.`);
+      return 0;
+    }
+    if (sub === "validate") {
+      if (!existsSync(file)) throw new Error(`no ${file}. Run craft direction init.`);
+      const direction = readJson(file);
+      const estate = declaredFrom(flags.estate, io.cwd);
+      const report = validateDirection(direction, {
+        fingerprint: current,
+        snapshot,
+        page,
+        strict: flags.strict,
+        pathExists: (p) => existsSync(resolve(dirname(file), p)),
+        readSource: (s) => {
+          if (!s.path || /^https?:/.test(s.path) || !TEXT_SOURCE.test(s.path)) return void 0;
+          const path = resolve(dirname(file), s.path);
+          return existsSync(path) ? readFileSync(path, "utf8") : void 0;
+        },
+        estate,
+        estateId: estate.find((s) => s.client && s.client === direction.client)?.id
+      });
+      if (flags.json) io.out(toJson(report));
+      else {
+        for (const p of report.problems) io.out(`  ${p.severity === "error" ? "error" : "warn "}  ${p.at || "(file)"}  ${p.message}`);
+        for (const f of report.confidence ?? []) {
+          io.out(`  ${f.basis.padEnd(8)}  ${f.lens}  ${f.at}  ${f.message}`);
+          io.out(`            why it matters: ${f.why}`);
+        }
+        const l = report.layers;
+        const pages = l.hierarchy.map((h) => `${h.page} ${h.decided} of ${h.total}`).join(", ");
+        io.out(
+          `craft direction: ${report.valid ? "valid" : "not valid"}. Job ${l.job ? "decided" : "not decided"}; hierarchy ${pages || "not decided"}; tokens ${l.tokens.decided} of ${l.tokens.total}.${l.complete ? " Every layer decided." : ""}${report.confidence ? ` Decision confidence: ${confidenceCounts(report.confidence)}, none of them a score.` : ""}`
+        );
+      }
+      return report.valid ? 0 : 1;
+    }
+    if (sub === "propose") {
+      if (!existsSync(file)) throw new Error(`no ${file}. Run craft direction init and add the sources first.`);
+      const base = readJson(file);
+      const sources = (base.sources ?? []).map((s) => {
+        if (s.colours?.length || !s.path || !/\.png$/i.test(s.path)) return s;
+        const path = resolve(dirname(file), s.path);
+        if (!existsSync(path)) return s;
+        try {
+          const { rgba } = decodePng(readFileSync(path));
+          return { ...s, colours: paletteFromPixels(rgba).filter((c) => c.share >= 0.03).map((c) => c.hex) };
+        } catch (error) {
+          io.err(`craft direction: ${s.path}: ${error.message}`);
+          return s;
+        }
+      });
+      const declared = declaredFrom(flags.estate, io.cwd).flatMap((s) => s.direction?.accent && s.client !== base.client ? [{ id: s.id, accent: s.direction.accent }] : []);
+      const result = propose({ client: base.client, brief: base.brief, sources, current, estate: estateFrom(flags.estate, io.cwd), declared });
+      const merged = { ...base, sources, choices: { ...result.direction.choices, ...stripUndecided(base.choices) }, ...base.exceptions ? { exceptions: base.exceptions } : {} };
+      const text = `${JSON.stringify(merged, null, 2)}
+`;
+      if (flags.out) writeFileSync(resolve(io.cwd, flags.out), text);
+      else io.out(text);
+      for (const p of result.proposals) {
+        io.err(`${p.key}: ${p.candidates.length ? p.candidates.map((c) => `${c.value || "?"} (${c.note})`).join("; ") : "nothing in the sources to draw on yet"}`);
+      }
+      return 0;
+    }
+    throw new Error("usage: craft direction init | validate | propose | research | review");
+  } catch (error) {
+    io.err(`craft: ${error.message}`);
+    return 2;
+  }
+}
+var confidenceCounts = (findings) => ["observed", "inferred", "unknown"].map((b) => `${findings.filter((f) => f.basis === b).length} ${b}`).join(", ");
+function stripUndecided(choices = {}) {
+  return Object.fromEntries(Object.entries(choices).filter(([, c]) => c && c.because && c.because.trim().length > 0));
+}
+function renderReview(review, report) {
+  const lines = [`craft direction review: ${review.subject ?? "untitled"}`];
+  for (const p of report.problems) lines.push(`  ${p.severity} ${p.at}: ${p.message}`);
+  for (const r of report.results) {
+    const note = review.notes.find((n) => n.id === r.id);
+    if (!note) continue;
+    const basis = r.basis.declared === r.basis.effective ? r.basis.effective : `${r.basis.effective} (declared ${r.basis.declared})`;
+    lines.push("", `  ${r.id} [${r.page}, ${r.lens}] ${basis}: ${r.outcome}${r.outcome === "change" ? `, ${r.recommend.effective.replace("-", " ")}` : ""}`);
+    lines.push(`    observation: ${note.observation} (${note.raisedBy})`);
+    if (note.problem) lines.push(`    visitor problem: ${note.problem}`);
+    if (note.evidence.length > 0) lines.push(`    evidence: ${note.evidence.map((e) => `${e.kind}${e.viewport ? ` at ${e.viewport}` : ""}`).join(", ")}`);
+    if (note.impact) lines.push(`    visitor impact: ${note.impact}`);
+    lines.push(`    seen at: ${r.widths.examined.join(", ") || "no width recorded"}${r.widths.unknown.length ? `; unknown at ${r.widths.unknown.join(", ")}` : ""}`);
+    if (r.suggested && note.suggested) lines.push(`    suggested: ${note.suggested.change} -> ${r.suggested.standing.replace(/-/g, " ")}: ${r.suggested.reasons.join(" ")}`);
+    if (r.outcome === "change" || r.outcome === "hold") {
+      lines.push(`    recommended (${r.recommend.step}): ${note.recommend.change}`);
+      lines.push(`      why: ${note.recommend.because}`);
+      if (note.recommend.whyEnough) lines.push(`      why not more: ${note.recommend.whyEnough}`);
+      for (const s of note.recommend.smaller ?? []) lines.push(`      not ${s.step}: ${s.whyNot}`);
+      if (note.recommend.validation) lines.push(`      check: ${note.recommend.validation}`);
+    } else if (note.recommend.because) lines.push(`    no change: ${note.recommend.because}`);
+    if (!r.publicationReady) lines.push(`    outstanding for publication: ${r.outstanding.join("; ")}`);
+    for (const a of r.adjustments) lines.push(`    note: ${a}`);
+  }
+  lines.push("", report.summary.verdict);
+  return lines.join("\n");
+}
+export {
+  runDirection
+};

package/dist/{cli-FF2YDHA4.js → cli-6INEFJYN.js}

@@ -9,7 +9,7 @@ import {
 import {
   SOURCE_FILE,
   readPaths
-} from "./chunk-JLLULDVW.js";
+} from "./chunk-NQAYRK2K.js";
 import {
   toJson
 } from "./chunk-QIEDBL4J.js";