@profpowell/vb-project-planning 0.1.0

package/src/web-components/quadrant-grid/styles.css

@@ -0,0 +1,184 @@
+/* quadrant-grid: Generic 2x2 quadrant grid primitive */
+
+quadrant-grid:not(:defined) {
+  display: block;
+}
+
+quadrant-grid {
+  display: block;
+  font-family: var(--font-sans, system-ui);
+  color: var(--color-text, #1a1a1a);
+}
+
+@scope (quadrant-grid) {
+  .qg-wrapper {
+    display: grid;
+    grid-template-columns: max-content max-content 1fr;
+    grid-template-rows: max-content 1fr max-content max-content;
+    grid-template-areas:
+      "y-label . ."
+      "y-scale grid grid"
+      ". x-scale x-scale"
+      ". x-label x-label";
+    gap: var(--size-2xs, 0.25rem);
+    margin: 0;
+  }
+
+  .qg-y-label {
+    grid-area: y-label;
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-text-muted, #666);
+    text-align: start;
+    padding-inline-end: var(--size-xs, 0.5rem);
+  }
+
+  .qg-x-label {
+    grid-area: x-label;
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-text-muted, #666);
+    text-align: end;
+  }
+
+  .qg-y-scale {
+    grid-area: y-scale;
+    display: flex;
+    flex-direction: column;
+    justify-content: space-between;
+    padding-block: var(--size-2xs, 0.25rem);
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: var(--font-size-xs, 0.75rem);
+    color: var(--color-text-muted, #666);
+    text-align: end;
+    padding-inline-end: var(--size-xs, 0.5rem);
+    min-inline-size: 3rem;
+  }
+
+  .qg-x-scale {
+    grid-area: x-scale;
+    display: flex;
+    justify-content: space-between;
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: var(--font-size-xs, 0.75rem);
+    color: var(--color-text-muted, #666);
+    padding-block-start: var(--size-2xs, 0.25rem);
+  }
+
+  .qg-grid {
+    grid-area: grid;
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    grid-template-rows: 1fr 1fr;
+    gap: var(--size-2xs, 0.25rem);
+    min-block-size: var(--qg-min-size, 24rem);
+    background: var(--color-border, oklch(85% 0 0));
+    padding: 1px;
+    border-radius: var(--radius-m, 0.5rem);
+  }
+
+  .qg-quadrant {
+    position: relative;
+    background: var(--color-surface, #fff);
+    padding: var(--size-s, 0.75rem);
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-xs, 0.5rem);
+    overflow: hidden;
+  }
+
+  /* Cartesian placement: Q1 top-right, Q2 top-left, Q3 bottom-left, Q4 bottom-right */
+  .qg-quadrant[data-quadrant-zone="0"] { grid-row: 1; grid-column: 2; border-radius: 0 var(--radius-m, 0.5rem) 0 0; }
+  .qg-quadrant[data-quadrant-zone="1"] { grid-row: 1; grid-column: 1; border-radius: var(--radius-m, 0.5rem) 0 0 0; }
+  .qg-quadrant[data-quadrant-zone="2"] { grid-row: 2; grid-column: 1; border-radius: 0 0 0 var(--radius-m, 0.5rem); }
+  .qg-quadrant[data-quadrant-zone="3"] { grid-row: 2; grid-column: 2; border-radius: 0 0 var(--radius-m, 0.5rem) 0; }
+
+  .qg-quadrant-label {
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-text-muted, #666);
+    margin: 0;
+  }
+
+  .qg-items {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-2xs, 0.25rem);
+  }
+
+  .qg-items > li {
+    background: var(--color-surface-raised, oklch(96% 0 0));
+    padding: var(--size-2xs, 0.25rem) var(--size-xs, 0.5rem);
+    border-radius: var(--radius-s, 0.25rem);
+    font-size: var(--font-size-sm, 0.875rem);
+  }
+
+  /* Coordinate-pinned children get absolute placement.
+     Section-local coords (0..1) are computed by JS and stored as
+     --qg-local-x / --qg-local-y. The component also measures each pin
+     after layout and writes --qg-pin-half-w / --qg-pin-half-h so the
+     center-anchored position is clamped by the pin's actual half-size,
+     keeping the bounding box inside the quadrant at any coordinate. */
+  .qg-pinned {
+    position: absolute;
+    inline-size: max-content;
+    max-inline-size: calc(100% - var(--size-xs, 0.5rem));
+    padding: var(--size-3xs, 0.125rem) var(--size-xs, 0.5rem);
+    background: var(--color-accent, oklch(45% 0.18 260));
+    color: var(--color-text-on-primary, #fff);
+    border-radius: var(--radius-s, 0.25rem);
+    font-size: var(--font-size-xs, 0.75rem);
+    inset-inline-start: clamp(var(--qg-pin-half-w, 1.5rem), calc(var(--qg-local-x, 0.5) * 100%), calc(100% - var(--qg-pin-half-w, 1.5rem)));
+    inset-block-end: clamp(var(--qg-pin-half-h, 0.75rem), calc(var(--qg-local-y, 0.5) * 100%), calc(100% - var(--qg-pin-half-h, 0.75rem)));
+    /* --qg-fan-x / --qg-fan-y nudge clustered pins outward on
+       hover/focus; default to zero so non-clustered pins stay anchored. */
+    transform: translate(calc(-50% + var(--qg-fan-x, 0px)), calc(50% + var(--qg-fan-y, 0px)));
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.15);
+    /* Per-pin tint: hue-rotate is cheap, leaves white text neutral,
+       and lets identical-style pins stay visually distinct at rest. */
+    filter: hue-rotate(var(--qg-pin-hue, 0deg));
+    transition: transform 180ms ease, box-shadow 180ms ease, z-index 0s;
+  }
+
+  /* Cluster fan-out: when any clustered pin in the quadrant is hovered
+     or focused, splay every member of the cluster along a circle.
+     --qg-cluster-i is each pin's position (0..n-1); --qg-cluster-n is
+     the cluster size. Radius scales with measured pin width. */
+  .qg-quadrant:hover .qg-pinned.qg-clustered,
+  .qg-quadrant:focus-within .qg-pinned.qg-clustered {
+    --qg-fan-angle: calc((var(--qg-cluster-i, 0) / var(--qg-cluster-n, 1)) * 360deg);
+    --qg-fan-radius: calc(var(--qg-pin-half-w, 1.5rem) * 1.4);
+    --qg-fan-x: calc(cos(var(--qg-fan-angle)) * var(--qg-fan-radius));
+    --qg-fan-y: calc(sin(var(--qg-fan-angle)) * var(--qg-fan-radius) * -1);
+  }
+
+  .qg-pinned.qg-clustered:hover,
+  .qg-pinned.qg-clustered:focus-visible {
+    z-index: 2;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  quadrant-grid * {
+    transition: none !important;
+  }
+}
+
+@media print {
+  quadrant-grid .qg-y-label,
+  quadrant-grid .qg-x-label,
+  quadrant-grid .qg-y-scale,
+  quadrant-grid .qg-x-scale {
+    color: #000;
+  }
+}

package/src/web-components/quality-target/_quality-utils.js

@@ -0,0 +1,460 @@
+/**
+ * Pure helpers + SVG builder for <quality-target>.
+ *
+ * Combines the prior _nfr-utils.js (default ilities, default cost
+ * weights, validation invariants) with _radar-geometry.js (axis
+ * angles, vector/envelope points, SVG builder), with the addition
+ * of click-to-edit dialog state helpers.
+ *
+ * Domain-neutral schema property names are unchanged: vector,
+ * rationales, costWeights, capacityPoints, capacitySource,
+ * overrunRationale, ironTriangleHash. Only the front-door labels move
+ * from "NFR" to "quality".
+ */
+
+// ── Defaults ──────────────────────────────────────────────────────
+
+export const DEFAULT_ILITIES = Object.freeze([
+  'performance',
+  'accessibility',
+  'security',
+  'reliability',
+  'maintainability',
+  'observability',
+  'compatibility',
+  'scalability',
+  'portability',
+  'internationalization',
+  'privacy',
+]);
+
+export const LEVELS = Object.freeze(['critical', 'important', 'acceptable', 'not-relevant']);
+export const LEVEL_LABELS = Object.freeze({
+  'critical':     'Critical',
+  'important':    'Important',
+  'acceptable':   'Acceptable',
+  'not-relevant': 'Not relevant',
+});
+
+/** Default cost weights when picking an ility as Critical. Sum = 40. */
+export const DEFAULT_COST_WEIGHTS = Object.freeze({
+  accessibility: 3,
+  performance: 5,
+  security: 5,
+  reliability: 4,
+  observability: 3,
+  internationalization: 4,
+  compatibility: 2,
+  portability: 3,
+  privacy: 4,
+  scalability: 5,
+  maintainability: 2,
+});
+
+const ILITY_LABELS = Object.freeze({
+  performance: 'Performance',
+  accessibility: 'Accessibility',
+  security: 'Security',
+  reliability: 'Reliability',
+  maintainability: 'Maintainability',
+  observability: 'Observability',
+  compatibility: 'Compatibility',
+  scalability: 'Scalability',
+  portability: 'Portability',
+  internationalization: 'Internationalization',
+  privacy: 'Privacy',
+});
+
+const ILITY_ABBR = Object.freeze({
+  accessibility: 'a11y',
+  internationalization: 'i18n',
+  maintainability: 'maint',
+  observability: 'obs',
+  compatibility: 'compat',
+  portability: 'porta',
+  performance: 'perf',
+  reliability: 'rely',
+  scalability: 'scale',
+  security: 'sec',
+  privacy: 'priv',
+});
+
+const LEVEL_RATIO = Object.freeze({
+  critical:       1,
+  important:      0.6,
+  acceptable:     0.3,
+  'not-relevant': 0,
+});
+
+// ── Labels ────────────────────────────────────────────────────────
+
+export function ilityLabel(ility) {
+  if (ILITY_LABELS[ility]) return ILITY_LABELS[ility];
+  return String(ility)
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+export function ilityAbbr(ility) {
+  return ILITY_ABBR[ility] || ility;
+}
+
+// ── Cost weights ──────────────────────────────────────────────────
+
+export function mergeCostWeights(ilities, overrides = {}) {
+  const out = {};
+  for (const ility of ilities) {
+    if (Object.prototype.hasOwnProperty.call(overrides, ility) &&
+        Number.isFinite(Number(overrides[ility]))) {
+      out[ility] = Math.max(0, Math.floor(Number(overrides[ility])));
+    } else if (Object.prototype.hasOwnProperty.call(DEFAULT_COST_WEIGHTS, ility)) {
+      out[ility] = DEFAULT_COST_WEIGHTS[ility];
+    } else {
+      out[ility] = 1;
+    }
+  }
+  return Object.freeze(out);
+}
+
+export function criticalSum(vector, costWeights) {
+  let sum = 0;
+  for (const [ility, level] of Object.entries(vector || {})) {
+    if (level === 'critical') sum += Number(costWeights?.[ility] ?? 0);
+  }
+  return sum;
+}
+
+export function criticalKeys(vector) {
+  return Object.keys(vector || {}).filter(k => vector[k] === 'critical');
+}
+
+// ── Validation ────────────────────────────────────────────────────
+
+/**
+ * Return { valid, errors, criticalSum } for a candidate vector. Used
+ * by the component's checkValidity() and (mirror) by uucd-core's
+ * validateQualityVector() so both surfaces apply identical rules.
+ */
+export function validateVector(input) {
+  const {
+    vector = {}, rationales = {}, costWeights = {},
+    capacityPoints = Infinity, overrunRationale = '',
+    minRationale = 10, minOverrunRationale = 10,
+  } = input || {};
+
+  const errors = [];
+  const crits = criticalKeys(vector);
+
+  for (const k of crits) {
+    const r = rationales[k];
+    if (typeof r !== 'string' || r.trim().length < minRationale) {
+      errors.push(`Critical "${k}" needs a rationale of at least ${minRationale} characters.`);
+    }
+  }
+
+  const sum = criticalSum(vector, costWeights);
+  if (Number.isFinite(capacityPoints) && sum > capacityPoints) {
+    if (typeof overrunRationale !== 'string' || overrunRationale.trim().length < minOverrunRationale) {
+      errors.push(
+        `Over budget by ${sum - capacityPoints} points (${sum}/${capacityPoints}); ` +
+        `overrunRationale of at least ${minOverrunRationale} characters required.`
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors, criticalSum: sum };
+}
+
+/**
+ * Per-axis dialog state machine: can the user save THIS axis's edit?
+ * Critical needs a rationale; other levels just need to be picked.
+ * The over-budget rationale is a vector-level concern handled by
+ * validateVector — not gated here.
+ */
+export function canSaveAxis({ level, rationale, minRationale = 10 }) {
+  if (!LEVELS.includes(level)) return { ok: false, reason: 'pick-level' };
+  if (level === 'critical') {
+    if (typeof rationale !== 'string' || rationale.trim().length < minRationale) {
+      return { ok: false, reason: 'rationale-too-short' };
+    }
+  }
+  return { ok: true };
+}
+
+/** Tooltip text used both in the SVG <title> and aria-label. */
+export function formatAxisTooltip({ ility, level, costWeight }) {
+  const name = ilityLabel(ility);
+  const lvl = level ? LEVEL_LABELS[level] || level : 'unset';
+  const n = Number(costWeight);
+  const cost = Number.isFinite(n) ? `${n} pts` : '? pts';
+  return `${name} — ${lvl} · ${cost}`;
+}
+
+// ── JSON attribute parsing (data-cost-weights) ───────────────────
+
+export function parseJsonAttr(raw) {
+  if (!raw || typeof raw !== 'string') return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// ── Geometry ──────────────────────────────────────────────────────
+
+/** N axis angles, evenly spaced, starting at the top. */
+export function axisAngles(n) {
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    out.push(-Math.PI / 2 + (2 * Math.PI * i) / n);
+  }
+  return out;
+}
+
+/**
+ * Fraction of `radius` the capacity envelope reaches per axis.
+ * Returns null when capacity is unbounded.
+ */
+export function envelopeRatio({ costWeights = {}, capacityPoints, ilities }) {
+  if (!Number.isFinite(capacityPoints)) return null;
+  const total = ilities.reduce((s, k) => {
+    const w = Number(costWeights[k]);
+    return s + (Number.isFinite(w) && w > 0 ? w : 0);
+  }, 0);
+  if (total <= 0) return 0;
+  return Math.min(1, Math.max(0, capacityPoints / total));
+}
+
+/** Per-ility {x, y, ility, level} points for the chosen vector. */
+export function vectorPoints({ ilities, vector = {}, radius }) {
+  const angles = axisAngles(ilities.length);
+  return ilities.map((k, i) => {
+    const level = vector[k] || null;
+    const ratio = LEVEL_RATIO[level] ?? 0;
+    return {
+      ility: k,
+      level,
+      x: round(Math.cos(angles[i]) * radius * ratio),
+      y: round(Math.sin(angles[i]) * radius * ratio),
+    };
+  });
+}
+
+/** Per-ility {x, y, ility} points for the capacity envelope. */
+export function envelopePoints({ ilities, costWeights, capacityPoints, radius }) {
+  const ratio = envelopeRatio({ costWeights, capacityPoints, ilities });
+  if (ratio == null) return null;
+  const angles = axisAngles(ilities.length);
+  return ilities.map((k, i) => ({
+    ility: k,
+    x: round(Math.cos(angles[i]) * radius * ratio),
+    y: round(Math.sin(angles[i]) * radius * ratio),
+  }));
+}
+
+/** Outer axis endpoints — used for the spoke + label positions. */
+export function axisOuterPoints({ ilities, radius }) {
+  const angles = axisAngles(ilities.length);
+  return ilities.map((k, i) => ({
+    ility: k,
+    x: round(Math.cos(angles[i]) * radius),
+    y: round(Math.sin(angles[i]) * radius),
+  }));
+}
+
+// ── SVG builder ───────────────────────────────────────────────────
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/**
+ * Build the inline polygon-as-UI <svg>. Each axis marker is a clickable
+ * <g class="axis" data-ility="…" tabindex="0"> hit target the component
+ * wires to a per-axis editor dialog.
+ *
+ * Layers (back to front):
+ *   1. three reference rings (Critical 1.0 / Important 0.6 / Acceptable 0.3
+ *      level radii) — the ONLY background; no envelope polygon.
+ *   2. spokes from origin to outer ring
+ *   3. vector polygon (picked axes only)
+ *   4. axis hit groups: invisible hit-rect + dot marker + label + <title>
+ *   5. center capacity readout in a small reserved hole
+ */
+const LEVEL_RING_RATIOS = Object.freeze([
+  { ratio: 1.00, label: 'Critical',   className: 'ring-critical' },
+  { ratio: 0.60, label: 'Important',  className: 'ring-important' },
+  { ratio: 0.30, label: 'Acceptable', className: 'ring-acceptable' },
+]);
+
+const CENTER_HOLE_RADIUS_RATIO = 0.22;   // fraction of `radius` reserved for capacity readout
+
+/**
+ * @param {{ ilities?: any[], vector?: Record<string, string>, costWeights?: Record<string, number>, capacityPoints?: number, radius?: number }} [opts]
+ */
+export function buildTargetSvg({
+  ilities = /** @type {any[]} */ ([]),
+  vector = /** @type {Record<string, string>} */ ({}),
+  costWeights = /** @type {Record<string, number>} */ ({}),
+  capacityPoints = 0,
+  radius = 100,
+} = {}) {
+  const svg = document.createElementNS(SVG_NS, 'svg');
+  // Generous viewBox padding so full ility names ("Internationalization"
+  // is the longest at 20 chars) never clip. Labels render at radius + 14;
+  // longest label ≈ 130px wide at the 0.625rem default font.
+  const labelRadius = radius + 14;
+  const padX = labelRadius + 140;
+  const padY = labelRadius + 30;
+  svg.setAttribute('viewBox', `${-padX} ${-padY} ${padX * 2} ${padY * 2}`);
+  svg.setAttribute('role', 'group');
+  svg.setAttribute('aria-label',
+    `Quality target. ${criticalKeys(vector || {}).length} critical of ${ilities.length} ilities. Click any axis to edit.`);
+
+  // 1. Three concentric reference rings (level ratios).
+  for (const r of LEVEL_RING_RATIOS) {
+    const ring = document.createElementNS(SVG_NS, 'polygon');
+    ring.setAttribute('class', `ring ${r.className}`);
+    const points = axisOuterPoints({ ilities, radius: radius * r.ratio });
+    ring.setAttribute('points', points.map(p => `${p.x},${p.y}`).join(' '));
+    svg.append(ring);
+  }
+
+  // 2. Spokes from origin to outer ring.
+  const outer = axisOuterPoints({ ilities, radius });
+  for (const p of outer) {
+    const line = document.createElementNS(SVG_NS, 'line');
+    line.setAttribute('class', 'spoke');
+    line.setAttribute('x1', '0'); line.setAttribute('y1', '0');
+    line.setAttribute('x2', String(p.x)); line.setAttribute('y2', String(p.y));
+    svg.append(line);
+  }
+
+  // 3. Vector polygon — built from picked axes only so unset ilities
+  // don't drag the shape through the centroid.
+  const vec = vectorPoints({ ilities, vector, radius });
+  const nonZero = vec.filter(p => Math.hypot(p.x, p.y) > 0.5);
+  if (nonZero.length >= 3) {
+    const poly = document.createElementNS(SVG_NS, 'polygon');
+    poly.setAttribute('class', 'vector');
+    poly.setAttribute('points', nonZero.map(p => `${p.x},${p.y}`).join(' '));
+    svg.append(poly);
+  } else if (nonZero.length > 0) {
+    for (const p of nonZero) {
+      const line = document.createElementNS(SVG_NS, 'line');
+      line.setAttribute('class', 'vector-spoke');
+      line.setAttribute('x1', '0'); line.setAttribute('y1', '0');
+      line.setAttribute('x2', String(p.x)); line.setAttribute('y2', String(p.y));
+      svg.append(line);
+    }
+  }
+
+  // 4. Axis hit groups (markers + full labels).
+  const labels = axisOuterPoints({ ilities, radius: labelRadius });
+  for (let i = 0; i < ilities.length; i++) {
+    const ility = ilities[i];
+    const dot = vec[i];
+    const label = labels[i];
+    const cost = Number(costWeights?.[ility] ?? 0);
+    const level = vector?.[ility] ?? null;
+
+    const g = document.createElementNS(SVG_NS, 'g');
+    g.setAttribute('class', 'axis');
+    g.setAttribute('data-ility', ility);
+    if (level) g.setAttribute('data-level', String(level));
+    g.setAttribute('tabindex', '0');
+    g.setAttribute('role', 'button');
+    g.setAttribute('aria-label',
+      `${formatAxisTooltip({ ility, level, costWeight: cost })}. Activate to edit.`);
+
+    // Invisible hit area sized to the label width.
+    const hit = document.createElementNS(SVG_NS, 'rect');
+    hit.setAttribute('class', 'hit');
+    const anchor = anchorFor(label);
+    const hitW = 100;
+    const hitH = 22;
+    const hitX = label.x + (anchor === 'end' ? -hitW : anchor === 'start' ? 0 : -hitW / 2);
+    const hitY = label.y - hitH / 2;
+    hit.setAttribute('x', String(round(hitX)));
+    hit.setAttribute('y', String(round(hitY)));
+    hit.setAttribute('width', String(hitW));
+    hit.setAttribute('height', String(hitH));
+    hit.setAttribute('rx', '4');
+    g.append(hit);
+
+    // Marker dot at the level point (only when the axis is set —
+    // otherwise it sits at origin and would obscure the capacity readout).
+    if (level) {
+      const marker = document.createElementNS(SVG_NS, 'circle');
+      marker.setAttribute('class', 'marker');
+      marker.setAttribute('cx', String(dot.x));
+      marker.setAttribute('cy', String(dot.y));
+      marker.setAttribute('r', '4');
+      g.append(marker);
+    }
+
+    // Full ility label.
+    const text = document.createElementNS(SVG_NS, 'text');
+    text.setAttribute('class', 'axis-label');
+    text.setAttribute('x', String(label.x));
+    text.setAttribute('y', String(label.y));
+    text.setAttribute('text-anchor', anchor);
+    text.setAttribute('dominant-baseline', 'middle');
+    text.textContent = ilityLabel(ility);
+    g.append(text);
+
+    // Tooltip.
+    const title = document.createElementNS(SVG_NS, 'title');
+    title.textContent = formatAxisTooltip({ ility, level, costWeight: cost });
+    g.append(title);
+
+    svg.append(g);
+  }
+
+  // 5. Center capacity readout — sits in a reserved hole the polygon
+  // visually clears.
+  const center = document.createElementNS(SVG_NS, 'g');
+  center.setAttribute('class', 'center');
+  const sum = criticalSum(vector, costWeights);
+  const overBudget = Number.isFinite(capacityPoints) && sum > capacityPoints;
+  if (overBudget) center.setAttribute('data-over', '');
+  const holeRadius = radius * CENTER_HOLE_RADIUS_RATIO;
+
+  // Backdrop circle so the polygon stroke under the number doesn't bleed in.
+  const backdrop = document.createElementNS(SVG_NS, 'circle');
+  backdrop.setAttribute('class', 'capacity-backdrop');
+  backdrop.setAttribute('cx', '0');
+  backdrop.setAttribute('cy', '0');
+  backdrop.setAttribute('r', String(round(holeRadius)));
+  center.append(backdrop);
+
+  const sumText = document.createElementNS(SVG_NS, 'text');
+  sumText.setAttribute('class', 'capacity-sum');
+  sumText.setAttribute('x', '0');
+  sumText.setAttribute('y', '-3');
+  sumText.setAttribute('text-anchor', 'middle');
+  sumText.setAttribute('dominant-baseline', 'middle');
+  sumText.textContent = String(sum);
+  center.append(sumText);
+
+  const denom = document.createElementNS(SVG_NS, 'text');
+  denom.setAttribute('class', 'capacity-denom');
+  denom.setAttribute('x', '0');
+  denom.setAttribute('y', '11');
+  denom.setAttribute('text-anchor', 'middle');
+  denom.textContent = Number.isFinite(capacityPoints) ? `of ${capacityPoints}` : 'unbounded';
+  center.append(denom);
+
+  svg.append(center);
+
+  return svg;
+}
+
+// ── helpers ────────────────────────────────────────────────────────
+
+function round(n) { return Math.round(n * 100) / 100; }
+
+function anchorFor(p) {
+  if (Math.abs(p.x) < 4) return 'middle';
+  return p.x > 0 ? 'start' : 'end';
+}

package/src/web-components/quality-target/api.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "quality-target",
+  "type": "web-component",
+  "description": "Polygon-as-UI quality prioritization surface. The radar IS the picker: each axis is a clickable hit-target that opens a per-ility dialog (level + rationale). Pairs with <iron-triangle> via data-bind-to to read capacity. Form-associated; serializes the quality-vector schema.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": ["@flow"]
+  },
+  "attributes": [
+    { "name": "name",                       "kind": "native",   "purpose": "config",         "type": "string",  "default": "quality", "description": "Form-association field name" },
+    { "name": "data-bind-to",               "kind": "data",     "purpose": "config",         "type": "string",  "description": "ID of a sibling <iron-triangle> to read capacityPoints from" },
+    { "name": "data-capacity-points",       "kind": "data",     "purpose": "config",         "type": "number",  "description": "Literal capacity fallback when no triangle is bound" },
+    { "name": "data-cost-weights",          "kind": "data",     "purpose": "config",         "type": "string",  "description": "JSON object overriding default per-ility cost weights" },
+    { "name": "data-radius",                "kind": "data",     "purpose": "config",         "type": "number",  "default": "100", "description": "Base radius in SVG units" },
+    { "name": "data-show-envelope",         "kind": "data",     "purpose": "visual-variant", "type": "boolean", "description": "Show the capacity envelope polygon (default true; set to \"false\" to hide)" },
+    { "name": "data-min-rationale",         "kind": "data",     "purpose": "config",         "type": "number",  "default": "10",  "description": "Min characters for a Critical row's rationale" },
+    { "name": "data-max-rationale",         "kind": "data",     "purpose": "config",         "type": "number",  "default": "200", "description": "Max characters for the rationale textarea" },
+    { "name": "data-min-overrun-rationale", "kind": "data",     "purpose": "config",         "type": "number",  "default": "10",  "description": "Min characters for overrunRationale" },
+    { "name": "data-max-overrun-rationale", "kind": "data",     "purpose": "config",         "type": "number",  "default": "400", "description": "Max characters for overrunRationale" },
+    { "name": "disabled",                   "kind": "native",   "purpose": "config",         "type": "boolean", "description": "All inputs disabled" },
+    { "name": "locked",                     "kind": "host-api", "purpose": "semantic-state", "type": "boolean", "description": "Read-only mode for shipped vectors" }
+  ],
+  "slots": [],
+  "events": [
+    { "name": "quality-target:change",       "detail": "{ vector, rationales, costWeights, capacityPoints, criticalSum, overrunRationale, ironTriangleHash, source, field }", "description": "Any pick or rationale changes" },
+    { "name": "quality-target:over-budget",  "detail": "{ delta, criticalSum, capacityPoints }", "description": "The selection just crossed into over-budget" },
+    { "name": "quality-target:under-budget", "detail": "{ slack, criticalSum, capacityPoints }", "description": "The selection just returned within budget" }
+  ]
+}