justskill-design 0.0.1 → 3.2.0

package/lib/icons.mjs

@@ -0,0 +1,106 @@
+/**
+ * The icon set. Generated by `scripts/gen-icons.mjs` — do not edit by hand.
+ *
+ * Lucide (ISC): each value is the inner markup of one
+ * glyph, drawn on a 24×24 viewBox and stroked with `currentColor`, so a node's
+ * `icon.color` tints it.
+ */
+
+export const ICON_LIBRARY = "lucide";
+
+/**
+ * The coordinate system every glyph in this set is drawn in.
+ *
+ * A `<svg>` with no `viewBox` has no coordinate system: the geometry is drawn in
+ * the element's own pixel box. A 24×24 glyph inside a 15×15 element is then not
+ * scaled down, it is CLIPPED — and `target`'s three rings become one arc, while
+ * `signal`'s five bars become a single dot. The drawing has to say what grid it
+ * was drawn on, so every icon element carries this.
+ */
+export const ICON_VIEW_BOX = "0 0 24 24";
+
+/** Glyph name -> SVG markup, alphabetically. */
+export const ICONS = {
+  "activity": "<path d=\"M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2\" />",
+  "arrow-right": "<path d=\"M5 12h14\" /><path d=\"m12 5 7 7-7 7\" />",
+  "arrow-up-right": "<path d=\"M7 7h10v10\" /><path d=\"M7 17 17 7\" />",
+  "award": "<path d=\"m15.477 12.89 1.515 8.526a.5.5 0 0 1-.81.47l-3.58-2.687a1 1 0 0 0-1.197 0l-3.586 2.686a.5.5 0 0 1-.81-.469l1.514-8.526\" /><circle cx=\"12\" cy=\"8\" r=\"6\" />",
+  "badge-check": "<path d=\"M3.85 8.62a4 4 0 0 1 4.78-4.77 4 4 0 0 1 6.74 0 4 4 0 0 1 4.78 4.78 4 4 0 0 1 0 6.74 4 4 0 0 1-4.77 4.78 4 4 0 0 1-6.75 0 4 4 0 0 1-4.78-4.77 4 4 0 0 1 0-6.76Z\" /><path d=\"m16 9-5.5 5.5L8 12\" />",
+  "battery-full": "<path d=\"M10 10v4\" /><path d=\"M14 10v4\" /><path d=\"M22 14v-4\" /><path d=\"M6 10v4\" /><rect x=\"2\" y=\"6\" width=\"16\" height=\"12\" rx=\"2\" />",
+  "bell": "<path d=\"M10.268 21a2 2 0 0 0 3.464 0\" /><path d=\"M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326\" />",
+  "building-2": "<path d=\"M10 12h4\" /><path d=\"M10 8h4\" /><path d=\"M14 21v-3a2 2 0 0 0-4 0v3\" /><path d=\"M6 10H4a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-2\" /><path d=\"M6 21V5a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v16\" />",
+  "calendar": "<path d=\"M8 2v3\" /><path d=\"M16 2v3\" /><rect x=\"3\" y=\"3\" width=\"18\" height=\"18\" rx=\"2\" /><path d=\"M3 9h18\" />",
+  "chart-bar": "<path d=\"M3 3v16a2 2 0 0 0 2 2h16\" /><path d=\"M7 16h8\" /><path d=\"M7 11h12\" /><path d=\"M7 6h3\" />",
+  "chart-line": "<path d=\"M3 3v16a2 2 0 0 0 2 2h16\" /><path d=\"m19 9-5 5-4-4-3 3\" />",
+  "check": "<path d=\"M20 6 9 17l-5-5\" />",
+  "chevron-down": "<path d=\"m6 9 6 6 6-6\" />",
+  "chevron-left": "<path d=\"m15 18-6-6 6-6\" />",
+  "chevron-right": "<path d=\"m9 18 6-6-6-6\" />",
+  "chevron-up": "<path d=\"m18 15-6-6-6 6\" />",
+  "circle-check": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><path d=\"m16 9-5.5 5.5L8 12\" />",
+  "clipboard-check": "<rect width=\"8\" height=\"4\" x=\"8\" y=\"2\" rx=\"1\" ry=\"1\" /><path d=\"M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2\" /><path d=\"m9 14 2 2 4-4\" />",
+  "compass": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><path d=\"m16.24 7.76-1.804 5.411a2 2 0 0 1-1.265 1.265L7.76 16.24l1.804-5.411a2 2 0 0 1 1.265-1.265z\" />",
+  "credit-card": "<rect width=\"20\" height=\"14\" x=\"2\" y=\"5\" rx=\"2\" /><line x1=\"2\" x2=\"22\" y1=\"10\" y2=\"10\" /><path d=\"M6 14h2\" />",
+  "crown": "<path d=\"M11.562 3.266a.5.5 0 0 1 .876 0L15.39 8.87a1 1 0 0 0 1.516.294L21.183 5.5a.5.5 0 0 1 .798.519l-2.834 10.246a1 1 0 0 1-.956.734H5.81a1 1 0 0 1-.957-.734L2.02 6.02a.5.5 0 0 1 .798-.519l4.276 3.664a1 1 0 0 0 1.516-.294z\" /><path d=\"M5 21h14\" />",
+  "download": "<path d=\"M12 15V3\" /><path d=\"M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4\" /><path d=\"m7 10 5 5 5-5\" />",
+  "ellipsis": "<circle cx=\"12\" cy=\"12\" r=\"1\" /><circle cx=\"19\" cy=\"12\" r=\"1\" /><circle cx=\"5\" cy=\"12\" r=\"1\" />",
+  "file-text": "<path d=\"M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z\" /><path d=\"M14 2v5a1 1 0 0 0 1 1h5\" /><path d=\"M10 9H8\" /><path d=\"M16 13H8\" /><path d=\"M16 17H8\" />",
+  "focus": "<circle cx=\"12\" cy=\"12\" r=\"3\" /><path d=\"M3 7V5a2 2 0 0 1 2-2h2\" /><path d=\"M17 3h2a2 2 0 0 1 2 2v2\" /><path d=\"M21 17v2a2 2 0 0 1-2 2h-2\" /><path d=\"M7 21H5a2 2 0 0 1-2-2v-2\" />",
+  "gem": "<path d=\"M10.5 3 8 9l4 13 4-13-2.5-6\" /><path d=\"M17 3a2 2 0 0 1 1.6.8l3 4a2 2 0 0 1 .013 2.382l-7.99 10.986a2 2 0 0 1-3.247 0l-7.99-10.986A2 2 0 0 1 2.4 7.8l2.998-3.997A2 2 0 0 1 7 3z\" /><path d=\"M2 9h20\" />",
+  "graduation-cap": "<path d=\"M21.42 10.922a1 1 0 0 0-.019-1.838L12.83 5.18a2 2 0 0 0-1.66 0L2.6 9.08a1 1 0 0 0 0 1.832l8.57 3.908a2 2 0 0 0 1.66 0z\" /><path d=\"M22 10v6\" /><path d=\"M6 12.5V16a6 3 0 0 0 12 0v-3.5\" />",
+  "heart": "<path d=\"M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5\" />",
+  "heart-handshake": "<path d=\"M19.414 14.414C21 12.828 22 11.5 22 9.5a5.5 5.5 0 0 0-9.591-3.676.6.6 0 0 1-.818.001A5.5 5.5 0 0 0 2 9.5c0 2.3 1.5 4 3 5.5l5.535 5.362a2 2 0 0 0 2.879.052 2.12 2.12 0 0 0-.004-3 2.124 2.124 0 1 0 3-3 2.124 2.124 0 0 0 3.004 0 2 2 0 0 0 0-2.828l-1.881-1.882a2.41 2.41 0 0 0-3.409 0l-1.71 1.71a2 2 0 0 1-2.828 0 2 2 0 0 1 0-2.828l2.823-2.762\" />",
+  "history": "<path d=\"M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8\" /><path d=\"M3 3v5h5\" /><path d=\"M12 7v5l4 2\" />",
+  "house": "<path d=\"M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8\" /><path d=\"M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z\" />",
+  "image": "<rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" ry=\"2\" /><circle cx=\"9\" cy=\"9\" r=\"2\" /><path d=\"m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21\" />",
+  "info": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><path d=\"M12 16v-4\" /><path d=\"M12 8h.01\" />",
+  "layout-dashboard": "<rect width=\"7\" height=\"9\" x=\"3\" y=\"3\" rx=\"1\" /><rect width=\"7\" height=\"5\" x=\"14\" y=\"3\" rx=\"1\" /><rect width=\"7\" height=\"9\" x=\"14\" y=\"12\" rx=\"1\" /><rect width=\"7\" height=\"5\" x=\"3\" y=\"16\" rx=\"1\" />",
+  "loader": "<path d=\"M12 2v4\" /><path d=\"m16.2 7.8 2.9-2.9\" /><path d=\"M18 12h4\" /><path d=\"m16.2 16.2 2.9 2.9\" /><path d=\"M12 18v4\" /><path d=\"m4.9 19.1 2.9-2.9\" /><path d=\"M2 12h4\" /><path d=\"m4.9 4.9 2.9 2.9\" />",
+  "lock": "<rect width=\"18\" height=\"11\" x=\"3\" y=\"11\" rx=\"2\" ry=\"2\" /><path d=\"M7 11V7a5 5 0 0 1 10 0v4\" />",
+  "map-pin": "<path d=\"M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0\" /><circle cx=\"12\" cy=\"10\" r=\"3\" />",
+  "medal": "<path d=\"M7.21 15 2.66 7.14a2 2 0 0 1 .13-2.2L4.4 2.8A2 2 0 0 1 6 2h12a2 2 0 0 1 1.6.8l1.6 2.14a2 2 0 0 1 .14 2.2L16.79 15\" /><path d=\"M11 12 5.12 2.2\" /><path d=\"m13 12 5.88-9.8\" /><path d=\"M8 7h8\" /><circle cx=\"12\" cy=\"17\" r=\"5\" /><path d=\"M12 18v-2h-.5\" />",
+  "package": "<path d=\"M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z\" /><path d=\"M12 22V12\" /><polyline points=\"3.29 7 12 12 20.71 7\" /><path d=\"m7.5 4.27 9 5.15\" />",
+  "pen-line": "<path d=\"M13 21h8\" /><path d=\"M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z\" />",
+  "phone": "<path d=\"M13.832 16.568a1 1 0 0 0 1.213-.303l.355-.465A2 2 0 0 1 17 15h3a2 2 0 0 1 2 2v3a2 2 0 0 1-2 2A18 18 0 0 1 2 4a2 2 0 0 1 2-2h3a2 2 0 0 1 2 2v3a2 2 0 0 1-.8 1.6l-.468.351a1 1 0 0 0-.292 1.233 14 14 0 0 0 6.392 6.384\" />",
+  "plus": "<path d=\"M5 12h14\" /><path d=\"M12 5v14\" />",
+  "refresh-ccw": "<path d=\"M21 12a9 9 0 0 0-9-9 9.75 9.75 0 0 0-6.74 2.74L3 8\" /><path d=\"M3 3v5h5\" /><path d=\"M3 12a9 9 0 0 0 9 9 9.75 9.75 0 0 0 6.74-2.74L21 16\" /><path d=\"M16 16h5v5\" />",
+  "refresh-cw": "<path d=\"M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8\" /><path d=\"M21 3v5h-5\" /><path d=\"M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16\" /><path d=\"M8 16H3v5\" />",
+  "route": "<circle cx=\"6\" cy=\"19\" r=\"3\" /><path d=\"M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15\" /><circle cx=\"18\" cy=\"5\" r=\"3\" />",
+  "search": "<path d=\"m21 21-4.34-4.34\" /><circle cx=\"11\" cy=\"11\" r=\"8\" />",
+  "settings": "<path d=\"M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915\" /><circle cx=\"12\" cy=\"12\" r=\"3\" />",
+  "settings-2": "<path d=\"M14 17H5\" /><path d=\"M19 7h-9\" /><circle cx=\"17\" cy=\"17\" r=\"3\" /><circle cx=\"7\" cy=\"7\" r=\"3\" />",
+  "share-2": "<circle cx=\"18\" cy=\"5\" r=\"3\" /><circle cx=\"6\" cy=\"12\" r=\"3\" /><circle cx=\"18\" cy=\"19\" r=\"3\" /><line x1=\"8.59\" x2=\"15.42\" y1=\"13.51\" y2=\"17.49\" /><line x1=\"15.41\" x2=\"8.59\" y1=\"6.51\" y2=\"10.49\" />",
+  "shield-check": "<path d=\"M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z\" /><path d=\"m9 12 2 2 4-4\" />",
+  "signal": "<path d=\"M2 20h.01\" /><path d=\"M7 20v-4\" /><path d=\"M12 20v-8\" /><path d=\"M17 20V8\" /><path d=\"M22 4v16\" />",
+  "sliders-horizontal": "<path d=\"M10 5H3\" /><path d=\"M12 19H3\" /><path d=\"M14 3v4\" /><path d=\"M16 17v4\" /><path d=\"M21 12h-9\" /><path d=\"M21 19h-5\" /><path d=\"M21 5h-7\" /><path d=\"M8 10v4\" /><path d=\"M8 12H3\" />",
+  "sparkles": "<path d=\"M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z\" /><path d=\"M20 2v4\" /><path d=\"M22 4h-4\" /><circle cx=\"4\" cy=\"20\" r=\"2\" />",
+  "star": "<path d=\"M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z\" />",
+  "sun": "<circle cx=\"12\" cy=\"12\" r=\"4\" /><path d=\"M12 2v2\" /><path d=\"M12 20v2\" /><path d=\"m4.93 4.93 1.41 1.41\" /><path d=\"m17.66 17.66 1.41 1.41\" /><path d=\"M2 12h2\" /><path d=\"M20 12h2\" /><path d=\"m6.34 17.66-1.41 1.41\" /><path d=\"m19.07 4.93-1.41 1.41\" />",
+  "target": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><circle cx=\"12\" cy=\"12\" r=\"6\" /><circle cx=\"12\" cy=\"12\" r=\"2\" />",
+  "thumbs-up": "<path d=\"M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z\" /><path d=\"M7 10v12\" />",
+  "trending-down": "<path d=\"M16 17h6v-6\" /><path d=\"m22 17-8.5-8.5-5 5L2 7\" />",
+  "trending-up": "<path d=\"M16 7h6v6\" /><path d=\"m22 7-8.5 8.5-5-5L2 17\" />",
+  "umbrella": "<path d=\"M12 13v7a2 2 0 0 0 4 0\" /><path d=\"M12 2v2\" /><path d=\"M20.992 13a1 1 0 0 0 .97-1.274 10.284 10.284 0 0 0-19.923 0A1 1 0 0 0 3 13z\" />",
+  "user": "<path d=\"M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2\" /><circle cx=\"12\" cy=\"7\" r=\"4\" />",
+  "user-check": "<path d=\"m16 11 2 2 4-4\" /><path d=\"M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2\" /><circle cx=\"9\" cy=\"7\" r=\"4\" />",
+  "user-round": "<circle cx=\"12\" cy=\"8\" r=\"5\" /><path d=\"M20 21a8 8 0 0 0-16 0\" />",
+  "users": "<path d=\"M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2\" /><path d=\"M16 3.128a4 4 0 0 1 0 7.744\" /><path d=\"M22 21v-2a4 4 0 0 0-3-3.87\" /><circle cx=\"9\" cy=\"7\" r=\"4\" />",
+  "wifi": "<path d=\"M12 20h.01\" /><path d=\"M2 8.82a15 15 0 0 1 20 0\" /><path d=\"M5 12.859a10 10 0 0 1 14 0\" /><path d=\"M8.5 16.429a5 5 0 0 1 7 0\" />",
+  "x": "<path d=\"M18 6 6 18\" /><path d=\"m6 6 12 12\" />",
+  "zap": "<path d=\"M15.914 4a1.5 1.5 0 00-2.474-1.561l-9 9A1.5 1.5 0 005.5 14h4.002a.5.5 0 01.471.666L8.086 20a1.5 1.5 0 002.475 1.56l9-9A1.5 1.5 0 0018.5 10h-3.997a.5.5 0 01-.472-.667z\" />",
+};
+
+/** The markup for a glyph, or undefined when the set does not have it. */
+export function iconBody(name) {
+  return Object.prototype.hasOwnProperty.call(ICONS, name) ? ICONS[name] : undefined;
+}
+
+/** Is this a glyph the set carries? */
+export function hasIcon(name) {
+  return Object.prototype.hasOwnProperty.call(ICONS, name);
+}
+
+/** Every glyph name in the set, alphabetically. */
+export function iconNames() {
+  return Object.keys(ICONS);
+}

package/lib/levenshtein.mjs

@@ -0,0 +1,133 @@
+/**
+ * "Did you mean ...?" support.
+ * PURE ESM — no `node:` imports.
+ */
+
+/** Levenshtein edit distance, two-row iterative. */
+export function distance(a, b) {
+  const s = String(a);
+  const t = String(b);
+  if (s === t) return 0;
+  if (s.length === 0) return t.length;
+  if (t.length === 0) return s.length;
+
+  let prev = new Array(t.length + 1);
+  let curr = new Array(t.length + 1);
+  for (let j = 0; j <= t.length; j += 1) prev[j] = j;
+
+  for (let i = 1; i <= s.length; i += 1) {
+    curr[0] = i;
+    const sc = s.charCodeAt(i - 1);
+    for (let j = 1; j <= t.length; j += 1) {
+      const cost = sc === t.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    const swap = prev;
+    prev = curr;
+    curr = swap;
+  }
+  return prev[t.length];
+}
+
+/**
+ * Return the closest candidate, or null when nothing is close enough.
+ * `maxDistance` defaults to a third of the input length (min 2, max 4).
+ */
+export function suggest(input, candidates, maxDistance) {
+  const list = Array.from(candidates || []);
+  if (list.length === 0) return null;
+
+  const s = String(input);
+  const limit =
+    typeof maxDistance === "number"
+      ? maxDistance
+      : Math.min(4, Math.max(2, Math.floor(s.length / 3)));
+
+  let best = null;
+  let bestScore = Infinity;
+  for (const candidate of list) {
+    const c = String(candidate);
+    // An identical candidate is never a suggestion. "Did you mean home__title"
+    // when the author already wrote home__title teaches nothing, and callers
+    // that ask about a duplicate rely on getting the OTHER similar name back.
+    if (c === s) continue;
+    const d = distance(s, c);
+    if (d < bestScore || (d === bestScore && best !== null && c < best)) {
+      bestScore = d;
+      best = c;
+    }
+  }
+  return bestScore <= limit ? best : null;
+}
+
+/**
+ * Suggest from a list of token references, comparing only the name part so that
+ * `$color.surafce` still finds `$color.surface`.
+ */
+export function suggestTokenRef(ref, candidates, maxDistance) {
+  const list = Array.from(candidates || []);
+  if (list.length === 0) return null;
+
+  const parts = String(ref).split(".");
+  const name = parts.length > 1 ? parts.slice(1).join(".") : String(ref);
+  const group = parts.length > 1 ? parts[0] : null;
+
+  const sameGroup = group ? list.filter((c) => String(c).startsWith(`${group}.`)) : [];
+  const pool = sameGroup.length > 0 ? sameGroup : list;
+
+  const stripped = pool.map((c) => {
+    const p = String(c).split(".");
+    return { full: c, name: p.length > 1 ? p.slice(1).join(".") : String(c) };
+  });
+
+  const hit = suggest(name, stripped.map((x) => x.name), maxDistance);
+  if (hit === null) return null;
+  const match = stripped.find((x) => x.name === hit);
+  return match ? match.full : null;
+}
+
+function bareName(value) {
+  const lower = String(value).toLowerCase();
+  return lower.startsWith("data-") ? lower.slice(5) : lower;
+}
+
+/**
+ * Suggest an attribute name for a typo: `backgound-color` -> `background-color`.
+ *
+ * Tried in order, so the answer never gets worse than an exact answer:
+ * the name itself, a case-insensitive match, the name without its `data-`
+ * prefix (`kind` -> `data-kind`), then a fuzzy match on either form.
+ *
+ * @param {string} name          what the file wrote
+ * @param {Iterable<string>} allowedNames  the attribute names the table allows
+ * @returns {string|null} the allowed name, or null when nothing is close
+ */
+export function suggestAttr(name, allowedNames) {
+  const list = Array.from(allowedNames || [], (c) => String(c));
+  if (list.length === 0) return null;
+
+  const input = String(name ?? "");
+  if (input === "") return null;
+
+  const exact = list.find((c) => c === input);
+  if (exact) return exact;
+
+  const lower = input.toLowerCase();
+  const insensitive = list.find((c) => c.toLowerCase() === lower);
+  if (insensitive) return insensitive;
+
+  const pairs = list.map((c) => ({ full: c, bare: bareName(c) }));
+  const want = bareName(input);
+
+  const bareHit = pairs.find((p) => p.bare === want);
+  if (bareHit) return bareHit.full;
+
+  const fuzzy = suggest(want, pairs.map((p) => p.bare));
+  if (fuzzy !== null) {
+    const match = pairs.find((p) => p.bare === fuzzy);
+    if (match) return match.full;
+  }
+
+  const fuzzyFull = suggest(lower, pairs.map((p) => p.full));
+  return fuzzyFull;
+}

package/lib/node/cli.mjs

@@ -0,0 +1,387 @@
+/**
+ * The Node side of the command line: entry-point detection, argument parsing,
+ * the shared flags every verb accepts, and reading a design file once.
+ *
+ * A verb's `run()` returns the exit code: 0 success, 1 refused or invalid,
+ * 2 unreadable file or bad arguments (docs/format-v3.md §10).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { detectFormat, readerFor } from "../detect.mjs";
+import { readText, revisionOf } from "./fs.mjs";
+
+export const EXIT_OK = 0;
+export const EXIT_INVALID = 1;
+export const EXIT_UNREADABLE = 2;
+
+/** An error a verb raises to stop with a specific exit code and message. */
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} [exitCode] defaults to 2 — bad arguments
+   * @param {string} [code]
+   * @param {string} [hint] "here is what to write instead", for a refusal
+   * @param {object} [extra] extra fields, such as the offending property
+   */
+  constructor(message, exitCode = EXIT_UNREADABLE, code = "cli/error", hint = "", extra = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    this.code = code;
+    // A refusal without a hint is a dead end for a caller that cannot see the
+    // file, so the hint is carried rather than dropped.
+    this.hint = hint;
+    Object.assign(this, extra);
+  }
+}
+
+/**
+ * Was this module the script Node was asked to run?
+ *
+ * The obvious test — `process.argv[1] === fileURLToPath(import.meta.url)` — is
+ * wrong for a skill, because that is exactly how a skill gets invoked:
+ *
+ *   ~/.claude/skills/justskill-design -> ~/.agents/skills/justskill-design -> the repo
+ *
+ * Node's ESM loader resolves symlinks, so `import.meta.url` is the real
+ * repository path while `process.argv[1]` is whatever the caller typed. The two
+ * never match, `main()` never runs, and the process still exits 0 with no
+ * output. A silent success is the worst possible failure, so both sides are
+ * resolved properly here.
+ *
+ * @param {string} importMetaUrl pass `import.meta.url`
+ * @param {string} [argv1] defaults to `process.argv[1]`
+ * @returns {boolean}
+ */
+export function isMainModule(importMetaUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+
+  const self = fileURLToPath(importMetaUrl);
+
+  let realSelf;
+  let realArgv;
+  try {
+    realSelf = fs.realpathSync(self);
+    realArgv = fs.realpathSync(argv1);
+  } catch {
+    // One of them does not exist, which happens in a bundled or piped
+    // invocation. Fall back to a plain comparison, still right when unlinked.
+    return path.resolve(argv1) === path.resolve(self);
+  }
+
+  return realArgv === realSelf;
+}
+
+/**
+ * A path to show a human: relative when that is shorter and still meaningful,
+ * absolute otherwise.
+ *
+ * `path.relative` happily produces `../../../../../tmp/x.html` for a file
+ * outside the working directory, which tells the reader nothing.
+ */
+export function relativeOrAbsolute(target, cwd = process.cwd()) {
+  const relative = path.relative(cwd, target);
+  if (!relative) return target;
+  return relative.startsWith("..") ? target : relative;
+}
+
+/** The flags every verb accepts. Merge into a verb's own `flags`. */
+export const SHARED_FLAGS = {
+  json: { type: "boolean", help: "print JSON instead of a human report" },
+  quiet: { type: "boolean", alias: ["q"], help: "print nothing on success" },
+  "dry-run": { type: "boolean", help: "print the result and write nothing" },
+  force: { type: "boolean", help: "proceed when the file already exists" },
+  help: { type: "boolean", alias: ["h"], help: "print this usage" },
+};
+
+function aliasesOf(definition) {
+  const alias = definition && definition.alias;
+  if (!alias) return [];
+  return Array.isArray(alias) ? alias.map(String) : [String(alias)];
+}
+
+function parseBoolean(raw, token) {
+  const value = String(raw).toLowerCase();
+  if (value === "true" || value === "1" || value === "yes") return true;
+  if (value === "false" || value === "0" || value === "no") return false;
+  throw new CliError(`Option ${token} takes true or false, got ${JSON.stringify(raw)}`);
+}
+
+/**
+ * Parse `argv` against a spec.
+ *
+ * ```js
+ * parseArgs(argv, {
+ *   flags: { ...SHARED_FLAGS, name: { type: "string" }, depth: { type: "number" } },
+ *   positionals: { min: 1, max: 1 },
+ *   usage: USAGE,
+ * })
+ * ```
+ *
+ * Supported forms: `--flag`, `--flag=value`, `--flag value`, `--no-flag`, and
+ * single-letter aliases (`-q`). `--` ends flag parsing; everything after it is a
+ * positional. An unknown option is an error unless `spec.allowUnknown`.
+ *
+ * @param {string[]} argv
+ * @param {{flags?: object, positionals?: {min?: number, max?: number}, usage?: string, allowUnknown?: boolean}} [spec]
+ * @returns {{values: Record<string, any>, positionals: string[], provided: Set<string>, has: (name: string) => boolean}}
+ * @throws {CliError} exit code 2 when the arguments are wrong
+ */
+export function parseArgs(argv, spec = {}) {
+  const flags = { ...SHARED_FLAGS, ...(spec.flags || {}) };
+  const lookup = new Map();
+  for (const [name, definition] of Object.entries(flags)) {
+    lookup.set(`--${name}`, { name, definition: definition || {} });
+    for (const alias of aliasesOf(definition)) {
+      lookup.set(alias.length === 1 ? `-${alias}` : `--${alias}`, { name, definition: definition || {} });
+    }
+  }
+
+  const values = {};
+  for (const [name, definition] of Object.entries(flags)) {
+    if (definition && "default" in definition) values[name] = definition.default;
+  }
+
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const positionals = [];
+  const provided = new Set();
+  let index = 0;
+  let stopped = false;
+
+  const usageSuffix = spec.usage ? `\n\n${String(spec.usage).trim()}` : "";
+
+  while (index < args.length) {
+    const arg = args[index];
+
+    if (stopped || arg === "-" || !arg.startsWith("-")) {
+      positionals.push(arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--") {
+      stopped = true;
+      index += 1;
+      continue;
+    }
+
+    let token = arg;
+    let inline = null;
+    const equals = arg.startsWith("--") ? arg.indexOf("=") : -1;
+    if (equals !== -1) {
+      token = arg.slice(0, equals);
+      inline = arg.slice(equals + 1);
+    }
+
+    let entry = lookup.get(token);
+    let negated = false;
+    if (!entry && token.startsWith("--no-")) {
+      entry = lookup.get(`--${token.slice(5)}`);
+      negated = true;
+    }
+    if (!entry) {
+      if (spec.allowUnknown) {
+        values[token.replace(/^--?/, "")] = inline === null ? true : inline;
+        index += 1;
+        continue;
+      }
+      throw new CliError(`Unknown option: ${arg}${usageSuffix}`);
+    }
+
+    const { name, definition } = entry;
+    const type = definition.type || "boolean";
+    index += 1;
+
+    if (type === "boolean") {
+      values[name] = negated ? false : inline === null ? true : parseBoolean(inline, token);
+      provided.add(name);
+      continue;
+    }
+
+    let raw = inline;
+    if (raw === null) {
+      if (index >= args.length) throw new CliError(`Option ${token} needs a value${usageSuffix}`);
+      raw = args[index];
+      index += 1;
+    }
+
+    if (type === "number") {
+      const number = Number(raw);
+      if (!Number.isFinite(number)) {
+        throw new CliError(`Option ${token} needs a number, got ${JSON.stringify(raw)}${usageSuffix}`);
+      }
+      values[name] = number;
+    } else if (type === "list") {
+      if (!Array.isArray(values[name])) values[name] = [];
+      values[name].push(raw);
+    } else {
+      values[name] = raw;
+    }
+    provided.add(name);
+  }
+
+  // `--help` wins over a missing argument: `validate --help` must print the
+  // usage, not complain that no file was given.
+  if (values.help === true) {
+    return { values, positionals, provided, has: (name) => provided.has(name) };
+  }
+
+  const minimum = spec.positionals && spec.positionals.min;
+  const maximum = spec.positionals && spec.positionals.max;
+  if (Number.isInteger(minimum) && positionals.length < minimum) {
+    throw new CliError(`Expected ${minimum} argument${minimum === 1 ? "" : "s"}, got ${positionals.length}${usageSuffix}`);
+  }
+  if (Number.isInteger(maximum) && positionals.length > maximum) {
+    throw new CliError(`Unexpected extra argument: ${positionals[maximum]}${usageSuffix}`);
+  }
+
+  return { values, positionals, provided, has: (name) => provided.has(name) };
+}
+
+/**
+ * Print to stderr and exit.
+ *
+ * @param {string} message
+ * @param {number} [code] defaults to 1 — refused or invalid
+ * @returns {never}
+ */
+export function fail(message, code = EXIT_INVALID) {
+  const text = message === undefined || message === null ? "" : String(message);
+  process.stderr.write(text.endsWith("\n") ? text : `${text}\n`);
+  process.exitCode = code;
+  process.exit(code);
+}
+
+/**
+ * Print one line to stdout, unless the caller asked for quiet.
+ *
+ * @param {string} text
+ * @param {{quiet?: boolean, stream?: NodeJS.WriteStream, newline?: boolean}} [options]
+ * @returns {boolean} true when something was written
+ */
+export function out(text, options = {}) {
+  if (options && options.quiet) return false;
+  const stream = (options && options.stream) || process.stdout;
+  const value = text === undefined || text === null ? "" : String(text);
+  stream.write(options && options.newline === false ? value : `${value}\n`);
+  return true;
+}
+
+function pickExport(mod, names) {
+  if (!mod) return null;
+  for (const name of names) {
+    if (name === "default") {
+      if (typeof mod.default === "function") return mod.default;
+      continue;
+    }
+    if (typeof mod[name] === "function") return mod[name];
+  }
+  return null;
+}
+
+function unwrapDocument(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.kind === "document") return value;
+  if (value.doc && typeof value.doc === "object") {
+    const doc = unwrapDocument(value.doc);
+    if (doc && !Array.isArray(doc.diagnostics) && Array.isArray(value.diagnostics)) {
+      doc.diagnostics = value.diagnostics;
+    }
+    return doc;
+  }
+  if (value.value && typeof value.value === "object") return unwrapDocument(value.value);
+  if (Array.isArray(value.children) || value.html || value.body) return value;
+  return null;
+}
+
+/**
+ * Read a design file and parse it with the reader its format selects.
+ *
+ * This is the shared front door of every verb. It uses `detectFormat` then the
+ * reader — never a hard-coded path — so a `.pen` file and an `.html` file are
+ * one code path.
+ *
+ * @param {string} file
+ * @returns {Promise<{file: string, text: string, format: string, doc: object, revision: string}>}
+ * @throws {FsError} `fs/not-found` / `fs/unreadable` — the caller maps these to exit 2
+ * @throws {CliError} exit 2 for an unknown format or a reader that throws
+ */
+export async function readDesignFile(file) {
+  const target = String(file === undefined || file === null ? "" : file);
+  if (target === "") throw new CliError("No file given");
+
+  const text = readText(target);
+  const format = detectFormat(target, text);
+  if (format === "unknown") {
+    throw new CliError(
+      `Cannot tell what ${target} is: expected .html markup or .pen JSON`,
+      EXIT_UNREADABLE,
+      "detect/unknown-format",
+    );
+  }
+
+  const load = readerFor(format);
+  let mod;
+  try {
+    mod = await load();
+  } catch (error) {
+    throw new CliError(`Cannot load the ${format} reader: ${error.message}`, EXIT_UNREADABLE, "cli/reader");
+  }
+
+  const parse = pickExport(mod, ["parseHtml", "parse", "parseDocument", "read", "default"]);
+  if (!parse) {
+    throw new CliError(`The ${format} reader (lib/parse.mjs) exports no parse function`, EXIT_UNREADABLE, "cli/reader");
+  }
+
+  let produced;
+  try {
+    produced = parse(text, { file: target, format, source: text });
+    if (produced && typeof produced.then === "function") produced = await produced;
+  } catch (error) {
+    throw new CliError(`${target}: ${error.message}`, EXIT_UNREADABLE, "cli/parse");
+  }
+
+  const doc = unwrapDocument(produced);
+  if (!doc) {
+    throw new CliError(`${target}: the ${format} reader returned no document`, EXIT_UNREADABLE, "cli/parse");
+  }
+  if (typeof doc.source !== "string") {
+    try {
+      doc.source = text;
+    } catch {
+      /* a frozen document still works: `ls` and `show` fall back to the text */
+    }
+  }
+
+  return { file: target, text, format, doc, revision: revisionOf(text) };
+}
+
+/** `lib/` — every module a verb may need lives here, whatever the verb's directory. */
+const LIB_ROOT = new URL("../", import.meta.url);
+
+/**
+ * Import a `lib/` module and take the first function it exports under one of
+ * `names`.
+ *
+ * The specifier is a bare file name inside `lib/` — `"validate.mjs"` — so a verb
+ * in `lib/node/verbs/` never has to work out how many `../` it needs.
+ *
+ * @param {string} specifier a path inside `lib/`, for example `"validate.mjs"`
+ * @param {string[]} names export names to try, in order
+ * @param {string} what human name of the export, for the error message
+ * @returns {Promise<Function>}
+ */
+export async function loadExport(specifier, names, what) {
+  let mod;
+  try {
+    mod = await import(new URL(specifier, LIB_ROOT).href);
+  } catch (error) {
+    throw new CliError(`Cannot load lib/${specifier}: ${error.message}`, EXIT_UNREADABLE, "cli/module");
+  }
+  const fn = pickExport(mod, names);
+  if (!fn) throw new CliError(`lib/${specifier} exports no ${what}()`, EXIT_UNREADABLE, "cli/module");
+  return fn;
+}