@3xhaust/oh-my-design 0.16.1

package/core/ref/signal.ts

@@ -0,0 +1,37 @@
+import type { Invariants } from '../types.ts';
+
+export interface DesignSignal { score: number; missing: string[] }
+
+/** Below this, a page has made almost no visual decisions — a warning, not a gate. */
+export const LOW_SIGNAL = 0.4;
+
+const round = (value: number, dp: number): number => {
+  const factor = 10 ** dp;
+  return Math.round(value * factor) / factor;
+};
+
+/**
+ * Nine binary-ish component signals over an already-measured page. danluu.com has almost
+ * no design — no radii, no shadows, no motion, no tokens — so as a *visual* reference it
+ * teaches nothing; this catches that deterministically instead of relying on a model to notice.
+ */
+export function designSignal(inv: Invariants): DesignSignal {
+  const checks: [string, boolean][] = [
+    ['radius', inv.radiusLadder.length >= 2], // at least two materials
+    ['elevation', inv.elevationLevels >= 1],
+    ['type', inv.typeScale.length >= 3], // a deliberate scale, not browser default
+    ['weights', inv.weightLadder.length >= 2], // weight used as hierarchy
+    ['motion', inv.motionDurations.length >= 1],
+    ['tokens', inv.tokenCoverage >= 0.2],
+    ['spacing', inv.spacingLadder.length >= 4], // a scale, not incidental values
+    ['padding', inv.paddingWeight >= 4], // someone spaced things on purpose
+    // A dead-on-hover button is the classic tell of generated work; a reference that
+    // never varies on hover has nothing to teach about interaction states.
+    ['interaction', inv.hoverCoverage >= 0.3],
+  ];
+
+  const missing = checks.filter(([, pass]) => !pass).map(([name]) => name);
+  const score = round(checks.reduce((sum, [, pass]) => sum + (pass ? 1 : 0), 0) / checks.length, 2);
+
+  return { score, missing };
+}

package/core/ref/store.ts

@@ -0,0 +1,122 @@
+import { mkdirSync, writeFileSync, readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import type { Invariants, Reference } from '../types.ts';
+
+/** Backfills invariants written before typography/motion/interaction measurement existed. */
+function withInvariantDefaults(invariants: Invariants | null | undefined): Invariants | null {
+  if (invariants == null) return null;
+  return {
+    ...invariants,
+    typeScale: invariants.typeScale ?? [],
+    fontFamilies: invariants.fontFamilies ?? [],
+    weightLadder: invariants.weightLadder ?? [],
+    motionDurations: invariants.motionDurations ?? [],
+    easingVocab: invariants.easingVocab ?? [],
+    animatedShare: invariants.animatedShare ?? 0,
+    hoverCoverage: invariants.hoverCoverage ?? 0,
+    focusCoverage: invariants.focusCoverage ?? 0,
+    // Motion probe fields — absent on references captured before the live probe was added.
+    animatedProperties: invariants.animatedProperties ?? [],
+    hasReducedMotion: invariants.hasReducedMotion ?? false,
+    scrollChoreography: invariants.scrollChoreography ?? [],
+  };
+}
+
+const refsDir = (cwd: string): string => join(cwd, '.omd', 'refs');
+
+/** Hostname of a URL, or the basename (without extension) of a file path. */
+function hostPart(source: string): string {
+  try {
+    const url = new URL(source);
+    if (url.protocol === 'file:') return basename(url.pathname).replace(/\.[^.]+$/, '');
+    return url.hostname.replace(/^www\./, '');
+  } catch {
+    return basename(source).replace(/\.[^.]+$/, '');
+  }
+}
+
+function slugFor(ref: Pick<Reference, 'source' | 'component'>): string {
+  return `${hostPart(ref.source)}.${ref.component}`;
+}
+
+export function saveRef(cwd: string, ref: Reference): string {
+  const dir = refsDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${slugFor(ref)}.json`);
+  writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
+  return resolve(path);
+}
+
+/** Path of the scoped component screenshot for a reference (`omd ref add … --shot`). */
+export function refImagePath(cwd: string, ref: Pick<Reference, 'source' | 'component'>): string {
+  return join(refsDir(cwd), `${slugFor(ref)}.png`);
+}
+
+function isReference(value: unknown): value is Partial<Reference> & Pick<Reference, 'source' | 'component'> {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && typeof (value as Record<string, unknown>)['source'] === 'string'
+    && typeof (value as Record<string, unknown>)['component'] === 'string'
+  );
+}
+
+export function loadRefs(cwd: string): Reference[] {
+  const dir = refsDir(cwd);
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+
+  const refs: Reference[] = [];
+  for (const file of files) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+      if (isReference(parsed)) {
+        refs.push({
+          source: parsed.source,
+          component: parsed.component,
+          kind: parsed.kind ?? 'page',
+          capturedAt: parsed.capturedAt ?? '',
+          ...(parsed.selector !== undefined ? { selector: parsed.selector } : {}),
+          invariants: withInvariantDefaults(parsed.invariants),
+          principles: parsed.principles ?? [],
+          ...(parsed.slopCount !== undefined ? { slopCount: parsed.slopCount } : {}),
+          ...(parsed.origin !== undefined ? { origin: parsed.origin } : {}),
+          // energyCurve is absent on references captured before energy measurement was
+          // added — omit the key so downstream code can use `?? null` to detect absence.
+          ...(parsed.energyCurve !== undefined ? { energyCurve: parsed.energyCurve } : {}),
+          // blueprint is absent on references captured before --blueprint was introduced.
+          // Omit the key so downstream code can check `ref.blueprint !== undefined`.
+          ...(parsed.blueprint !== undefined ? { blueprint: parsed.blueprint } : {}),
+          // imagePath is absent on references captured before --shot was introduced.
+          ...(parsed.imagePath !== undefined ? { imagePath: parsed.imagePath } : {}),
+        });
+      }
+    } catch {
+      // corrupt file: skip it, don't fail the run
+    }
+  }
+
+  return refs.sort((a, b) => a.source.localeCompare(b.source) || a.component.localeCompare(b.component));
+}
+
+/**
+ * Appends principles to an existing reference. Throws if none exists: a principle without
+ * measurements is an opinion, not a record.
+ */
+export function addPrinciples(cwd: string, source: string, component: string, principles: string[]): void {
+  const path = join(refsDir(cwd), `${slugFor({ source, component })}.json`);
+  if (!existsSync(path)) {
+    throw new Error(`no reference found for ${source} (${component})`);
+  }
+
+  const ref = JSON.parse(readFileSync(path, 'utf8')) as Reference;
+  for (const principle of principles) {
+    if (!ref.principles.includes(principle)) ref.principles.push(principle);
+  }
+
+  writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
+}