@3xhaust/oh-my-design 0.16.1

package/core/install/patch-codex.ts

@@ -0,0 +1,82 @@
+const MARKER_BEGIN = '# ── OMD BEGIN (do not edit; managed by oh-my-design) ──';
+const MARKER_END = '# ── OMD END ──';
+const FEATURE_KEYS = ['hooks', 'plugins', 'plugin_hooks', 'multi_agent'] as const;
+const TAG = ' # OMD';
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export function patchConfigToml(text: string, opts: { agents?: string[] } = {}): string {
+  const agents = opts.agents ?? [];
+
+  // Rewrite rather than bail out when already patched: an upgrade that adds an agent must
+  // register it, and bailing would leave it silently missing.
+  const lines = unpatchConfigToml(text).split('\n');
+
+  const featuresIdx = lines.findIndex((l) => l.trim() === '[features]');
+  let inlineFeatures = '';
+
+  if (featuresIdx === -1) {
+    inlineFeatures = `[features]\n${FEATURE_KEYS.map((k) => `${k} = true`).join('\n')}\n\n`;
+  } else {
+    // TOML forbids redeclaring [features], so missing keys go into the existing table and
+    // each added line is tagged so unpatch can strip exactly those.
+    let end = lines.length;
+    for (let i = featuresIdx + 1; i < lines.length; i++) {
+      if (lines[i]!.startsWith('[')) {
+        end = i;
+        break;
+      }
+    }
+    const existing = new Set<string>();
+    for (let i = featuresIdx + 1; i < end; i++) {
+      const m = /^(\w+)\s*=/.exec(lines[i]!);
+      if (m?.[1]) existing.add(m[1]);
+    }
+    const missing = FEATURE_KEYS.filter((k) => !existing.has(k));
+    if (missing.length) lines.splice(featuresIdx + 1, 0, ...missing.map((k) => `${k} = true${TAG}`));
+  }
+
+  const agentBlock = agents
+    .map((name) => `[agents.${name}]\nconfig_file = "./agents/${name}.toml"`)
+    .join('\n\n');
+
+  return `${lines.join('\n')}\n${MARKER_BEGIN}\n${inlineFeatures}${agentBlock}\n${MARKER_END}\n`;
+}
+
+export function unpatchConfigToml(text: string): string {
+  if (!text.includes(MARKER_BEGIN)) return text;
+  const block = new RegExp(`\\n${escapeRegExp(MARKER_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKER_END)}\\n`);
+  return text.replace(block, '').split('\n').filter((l) => !l.endsWith(TAG)).join('\n');
+}
+
+/**
+ * Codex trusts a hook file by the sha256 of its bytes rather than by a version, recording
+ * `[hooks.state."<key>"] trusted_hash = "sha256:..."` in config.toml. The key format below
+ * was read off a real install:
+ *   "omo@sisyphuslabs:hooks/session-start-loading-project-rules.json:session_start:0:0"
+ * i.e. `<plugin>@<marketplace>:<relative hook file>:<snake_case event>:<groupIndex>:<hookIndex>`.
+ * This has NOT been independently confirmed against a real Codex session for this project's
+ * plugin id — `doctor` must report hook trust as unverified, never as a pass.
+ */
+export function trustedHashKey(
+  pluginId: string,
+  hookFile: string,
+  event: string,
+  groupIndex = 0,
+  hookIndex = 0,
+): string {
+  const snakeEvent = event.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+  return `${pluginId}:${hookFile}:${snakeEvent}:${groupIndex}:${hookIndex}`;
+}
+
+/** Writes (or replaces) trusted_hash entries. Caller supplies the sha256 of each hook file. */
+export function patchHookTrust(text: string, entries: { key: string; sha256: string }[]): string {
+  let out = text;
+  for (const { key, sha256 } of entries) {
+    const header = `[hooks.state."${key}"]`;
+    const block = `${header}\ntrusted_hash = "sha256:${sha256}"\n`;
+    const re = new RegExp(`\\[hooks\\.state\\."${escapeRegExp(key)}"\\][^\\[]*`);
+    out = re.test(out) ? out.replace(re, block) : `${out.endsWith('\n') ? out : `${out}\n`}\n${block}`;
+  }
+  return out;
+}

package/core/interaction/index.ts

@@ -0,0 +1,101 @@
+/**
+ * Signature-interaction ideation, mechanism 1 (scout signal board) and mechanism 2
+ * (ideation gate). Pure functions only — no I/O, no CLI wiring.
+ *
+ * The signal board here is a SEPARATE recommendation input from core/ref/distance.ts.
+ * It does NOT read, derive from, or feed into that module's fixed WEIGHTS or Invariants
+ * shape, and it must never be wired to alter the ≤0.6 kinship/near-duplicate gate meaning
+ * there. Board entries only ever carry named measurements (numbers) and named principles
+ * (strings) — screenshots or other raw imagery are refused, per the measurement/principle
+ * grounding rule (no visual-mimicry ingestion).
+ *
+ * The ideation gate below governs whether autonomously generated interaction ideas may
+ * proceed; it does not itself perform rendering or ideation. The actual render/ideation
+ * runtime is a Phase 2 dependency and lives outside this module.
+ */
+
+export interface InteractionSignalInput {
+  source: string;
+  measurements: Record<string, number>;
+  principles: string[];
+  /** Never accepted: presence triggers refusal. Typed as `never` to flag misuse at compile time. */
+  screenshot?: never;
+}
+
+export interface InteractionSignalEntry {
+  id: string;
+  source: string;
+  measurements: Record<string, number>;
+  principles: string[];
+  kind: 'interaction-signal';
+}
+
+export interface InteractionSignalViolation {
+  ok: false;
+  reason: string;
+}
+
+export type InteractionSignalResult = { ok: true; entry: InteractionSignalEntry } | InteractionSignalViolation;
+
+function signalId(source: string, measurements: Record<string, number>, principles: string[]): string {
+  const parts = [source, ...Object.keys(measurements).sort(), ...principles.slice().sort()];
+  return parts.join('|');
+}
+
+/**
+ * Builds a scout signal board entry from named measurements/principles. Rejects any input
+ * that carries a `screenshot` (or other raw-image) field — the board records interaction
+ * measurements and principles only, never source pixels.
+ */
+export function ingestInteractionSignal(inputs: InteractionSignalInput): InteractionSignalResult {
+  if (Object.prototype.hasOwnProperty.call(inputs, 'screenshot')) {
+    return { ok: false, reason: 'screenshot rejected: signal board accepts measurements/principles only, no raw imagery' };
+  }
+  if (!inputs.source || inputs.source.trim() === '') {
+    return { ok: false, reason: 'source is required' };
+  }
+  if (Object.keys(inputs.measurements).length === 0 && inputs.principles.length === 0) {
+    return { ok: false, reason: 'at least one measurement or principle is required' };
+  }
+  return {
+    ok: true,
+    entry: {
+      id: signalId(inputs.source, inputs.measurements, inputs.principles),
+      source: inputs.source,
+      measurements: { ...inputs.measurements },
+      principles: [...inputs.principles],
+      kind: 'interaction-signal',
+    },
+  };
+}
+
+export interface IdeationGateInputs {
+  registerFit: boolean;
+  perfBudgetDeclared: boolean;
+  slopClean: boolean;
+  handPrecedence: boolean;
+  semanticFallbackPresent: boolean;
+}
+
+export interface IdeationGateResult {
+  permitted: boolean;
+  reasons: string[];
+}
+
+const GATE_CHECKS: ReadonlyArray<{ key: keyof IdeationGateInputs; reason: string }> = [
+  { key: 'registerFit', reason: 'register-fit not satisfied' },
+  { key: 'perfBudgetDeclared', reason: 'performance budget not declared' },
+  { key: 'slopClean', reason: 'slop check failed' },
+  { key: 'handPrecedence', reason: 'hand precedence not honored' },
+  { key: 'semanticFallbackPresent', reason: 'non-canvas semantic fallback missing' },
+];
+
+/**
+ * Autonomous interaction ideation is subordinate to register-fit, performance budget,
+ * slop, hand precedence, and non-canvas semantic fallback gates. Ideation is permitted
+ * only when every gate is satisfied; autonomy never bypasses a gate.
+ */
+export function evaluateIdeationGate(inputs: IdeationGateInputs): IdeationGateResult {
+  const reasons = GATE_CHECKS.filter(({ key }) => !inputs[key]).map(({ reason }) => reason);
+  return { permitted: reasons.length === 0, reasons };
+}

package/core/interaction/recipes/signature-lighting.md

@@ -0,0 +1,203 @@
+# Signature lighting (mouse-follow spotlight / god-ray)
+
+A signature-lighting interaction ties a soft light source — a spotlight or a god-ray
+volume — to the pointer, so the surface reads as lit from where the visitor is looking.
+The pointer becomes the light. This is a single-slot signature moment: it earns the one
+signature-moment allowance for a page and must not be combined with a second competing
+signature interaction on the same surface.
+
+## When it earns its place / When it does not
+
+Condition: a showpiece or confident-register hero, section divider, or dark-canvas
+surface where a light-driven read reinforces the product's own mechanism (optics,
+depth, focus, discovery) and no other signature moment is already claimed. The
+spotlight/god-ray works best over a dark or low-chroma ground, where the lit region
+reads as a genuine luminance shift rather than a colour overlay.
+
+Condition against: quiet-register or dense utility surfaces where a moving light draws
+attention away from task completion; light backgrounds, where a `radial-gradient`
+spotlight reads as a grey smudge instead of light; any surface that has already been
+assigned a different signature moment (magnetic hover, parallax, etc.) — do not stack
+two signature interactions on one page. Also: touch-primary contexts, where there is no
+pointer to follow (see Reduced-motion variant for the fallback, which doubles as the
+no-pointer fallback).
+
+The default implementation lane is CSS. It requires no library, degrades safely, and
+is cheap enough to run continuously. Escalating to a WebGL renderer is optional and
+must be justified — see WebGL escalation below.
+
+## Parameters
+
+```css
+:root {
+  /* Pointer position in the lit surface's local coordinate space, updated on
+     pointermove. Falls back to the element's centre before first movement. */
+  --spot-x: 50%;
+  --spot-y: 40%;
+
+  /* Radius of the lit region. Larger values read as ambient god-ray light;
+     smaller values read as a tight spotlight/torch. */
+  --spot-radius: 45vmax;
+
+  /* Colour and intensity of the lit region. Keep low-saturation: this is a
+     luminance effect, not a colour wash. */
+  --spot-color: rgba(255, 255, 255, 0.14);
+
+  /* How quickly the lit region eases toward the pointer's true position.
+     Non-zero lag reads as a physical light with mass; zero lag reads as a
+     cursor decoration. */
+  --spot-follow-duration: 400ms;
+  --spot-follow-ease: var(--ease-out-circ, cubic-bezier(0.08, 0.82, 0.17, 1));
+}
+```
+
+## Implementation
+
+CSS is the default lane: a `radial-gradient` positioned by custom properties that a
+`pointermove` listener updates. No canvas, no library.
+
+```html
+<section class="lit-surface" data-signature-light>
+  <div class="lit-surface__content"><!-- real page content --></div>
+</section>
+```
+
+```css
+.lit-surface {
+  position: relative;
+  isolation: isolate;
+}
+
+.lit-surface::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+  background: radial-gradient(
+    circle at var(--spot-x) var(--spot-y),
+    var(--spot-color) 0%,
+    transparent var(--spot-radius)
+  );
+  transition: --spot-x var(--spot-follow-duration) var(--spot-follow-ease),
+    --spot-y var(--spot-follow-duration) var(--spot-follow-ease);
+}
+
+.lit-surface__content {
+  position: relative;
+  z-index: 1;
+}
+```
+
+```js
+function attachSignatureLight(surface) {
+  function onMove(e) {
+    const rect = surface.getBoundingClientRect();
+    const x = ((e.clientX - rect.left) / rect.width) * 100;
+    const y = ((e.clientY - rect.top) / rect.height) * 100;
+    surface.style.setProperty('--spot-x', `${x}%`);
+    surface.style.setProperty('--spot-y', `${y}%`);
+  }
+  surface.addEventListener('pointermove', onMove, { passive: true });
+}
+
+if (window.matchMedia('(pointer: fine)').matches) {
+  document.querySelectorAll('[data-signature-light]').forEach(attachSignatureLight);
+}
+```
+
+`transition` on a custom property requires `@property` registration for the browser to
+interpolate it as a `<percentage>` instead of snapping; register both custom properties
+once at the stylesheet root:
+
+```css
+@property --spot-x {
+  syntax: '<percentage>';
+  inherits: true;
+  initial-value: 50%;
+}
+@property --spot-y {
+  syntax: '<percentage>';
+  inherits: true;
+  initial-value: 40%;
+}
+```
+
+## WebGL escalation
+
+The CSS lane above is the default and covers the large majority of signature-lighting
+requests: a `radial-gradient` tied to pointer coordinates reads convincingly as a
+spotlight or ambient god-ray without a rendering library. Escalating to a WebGL
+implementation (Three.js) is permitted only when all of the following hold, per hand
+precedence:
+
+- an explicit user request for a volumetric/3D lighting treatment, or a greenfield
+  concept where the product mechanism itself is 3D and a 2D gradient cannot represent
+  it (e.g. true light shafts through geometry, refraction, depth-of-field falloff);
+- a declared performance budget (bundle-size and runtime cost) that the surface can
+  actually afford — Three.js is not a default dependency and must be justified per
+  page, not assumed;
+- a non-canvas semantic fallback: the underlying content must remain real DOM, so it
+  stays selectable, focusable, and readable by assistive technology and search
+  indexing with the canvas absent or failed. The canvas is a decorative light layer
+  behind real content, never a replacement for it.
+
+Reference: kaolti's WebGL/Three.js signature-lighting work (HTML-in-canvas content
+composited with a Three.js volumetric light pass, built with Fable/F#) demonstrates the
+escalation lane at its most literal — light genuinely lives in a 3D scene rather than
+being simulated with a 2D gradient. The author's own retrospective on that work flagged
+the god-ray pass as having too much visual noise for the surface it sat on. That
+self-critique is the concrete basis for the restraint calibration in this recipe:
+escalate to WebGL only when the CSS lane is provably insufficient for the mechanism,
+keep the lit region's opacity and radius conservative even in the WebGL lane, and treat
+"more visible light" as a defect, not a feature, once the signature moment already
+reads. This recipe's default is CSS, and the WebGL lane is not a visual upgrade — it is
+a narrow, gated escalation for volumetric cases the CSS lane cannot represent.
+
+## Reduced-motion variant
+
+In reduced-motion context (and on `pointer: coarse` devices with no cursor to follow),
+the lit region is disabled entirely, or replaced with a static, fixed-position ambient
+gradient that does not track any input. No `pointermove` listener is attached; no
+custom-property transition runs.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .lit-surface::before {
+    transition: none !important;
+    background: radial-gradient(
+      circle at 50% 35%,
+      var(--spot-color) 0%,
+      transparent var(--spot-radius)
+    );
+  }
+}
+```
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const pointerFine = window.matchMedia('(pointer: fine)').matches;
+
+if (pointerFine && !prefersReduced) {
+  document.querySelectorAll('[data-signature-light]').forEach(attachSignatureLight);
+}
+```
+
+If a WebGL escalation is in use, the reduced-motion and no-pointer-fine paths must skip
+canvas/renderer initialisation entirely and fall back to the same static CSS gradient —
+never to a frozen WebGL frame, which still carries the renderer's load cost for no
+motion benefit.
+
+## Performance note
+
+`radial-gradient` repaint driven by custom-property `transition` is compositor-light
+but not compositor-only — moving the gradient's centre still triggers a paint on
+`::before`, not a transform. Keep the effect scoped to one lit surface per page (the
+one-signature-moment allowance already enforces this) and avoid attaching the
+`pointermove` listener to more than one element.
+
+If escalating to WebGL, the performance budget must account for renderer
+initialisation cost, per-frame render cost, and total JS payload added to the page;
+none of this is free, and none of it is justified for a spotlight effect the CSS lane
+already achieves. Lazy-initialise the WebGL renderer only after the surface enters the
+viewport, and tear it down when it leaves.