@hegemonart/get-design-done 1.15.0 → 1.18.0

package/scripts/lib/easings.cjs

@@ -0,0 +1,280 @@
+/**
+ * Easing functions for web animation.
+ *
+ * Source: React Native — Libraries/Animated/Easing.js (MIT License)
+ * Attribution: Facebook, Inc. and its affiliates
+ * https://github.com/facebook/react-native/blob/main/Libraries/Animated/Easing.js
+ *
+ * Each function accepts t in [0, 1] and returns a value in [0, 1]
+ * (elastic/back/bounce may transiently exceed [0,1] for overshoot).
+ */
+
+'use strict';
+
+/**
+ * A linear function, `f(t) = t`. Position correlates to elapsed time one to one.
+ */
+function linear(t) {
+  return t;
+}
+
+/**
+ * A quadratic function, `f(t) = t * t`. Position equals the square of elapsed time.
+ */
+function quad(t) {
+  return t * t;
+}
+
+/**
+ * A cubic function, `f(t) = t * t * t`. Position equals the cube of elapsed time.
+ */
+function cubic(t) {
+  return t * t * t;
+}
+
+/**
+ * A power function. Position is equal to the Nth power of elapsed time.
+ * @param {number} n - The exponent.
+ * @returns {function(number): number}
+ */
+function poly(n) {
+  return function (t) {
+    return Math.pow(t, n);
+  };
+}
+
+/**
+ * A sinusoidal function.
+ */
+function sin(t) {
+  return 1 - Math.cos((t * Math.PI) / 2);
+}
+
+/**
+ * A circular function.
+ */
+function circle(t) {
+  return 1 - Math.sqrt(1 - t * t);
+}
+
+/**
+ * An exponential function.
+ */
+function exp(t) {
+  return Math.pow(2, 10 * (t - 1));
+}
+
+/**
+ * A spring-like elastic function that overshoots its target value one or more times.
+ *
+ * @param {number} bounciness - Amplitude of overshoot. Default 1.
+ * @param {number} speed      - Controls oscillation frequency. Default 1.
+ * @returns {function(number): number}
+ */
+function elastic(bounciness, speed) {
+  if (bounciness === undefined) bounciness = 1;
+  if (speed === undefined) speed = 1;
+
+  const p = (bounciness === 0)
+    ? Math.PI / 2
+    : Math.asin(1 / (bounciness = Math.max(1, bounciness)));
+
+  const s = (bounciness / 10) * 0.3 * (speed / 10) || 0.3;
+
+  return function (t) {
+    if (t === 0) return 0;
+    if (t === 1) return 1;
+    return (
+      bounciness *
+      Math.pow(2, -10 * t) *
+      Math.sin(((t - s / 4) * (2 * Math.PI)) / s) +
+      1
+    );
+  };
+}
+
+/**
+ * Use with `Easing.out` for an overshoot effect. Default s = 1.70158.
+ * @param {number} s - Overshoot magnitude.
+ * @returns {function(number): number}
+ */
+function back(s) {
+  if (s === undefined) s = 1.70158;
+  return function (t) {
+    return t * t * ((s + 1) * t - s);
+  };
+}
+
+/**
+ * Provides a bouncing effect.
+ * @param {number} t
+ * @returns {number}
+ */
+function bounce(t) {
+  if (t < 1 / 2.75) {
+    return 7.5625 * t * t;
+  } else if (t < 2 / 2.75) {
+    const t2 = t - 1.5 / 2.75;
+    return 7.5625 * t2 * t2 + 0.75;
+  } else if (t < 2.5 / 2.75) {
+    const t2 = t - 2.25 / 2.75;
+    return 7.5625 * t2 * t2 + 0.9375;
+  } else {
+    const t2 = t - 2.625 / 2.75;
+    return 7.5625 * t2 * t2 + 0.984375;
+  }
+}
+
+/**
+ * Provides a raw cubic Bézier easing matching the CSS `cubic-bezier()` primitive.
+ *
+ * Implements the same algorithm as CSS Transitions spec (De Casteljau + Newton-Raphson solve).
+ *
+ * @param {number} x1
+ * @param {number} y1
+ * @param {number} x2
+ * @param {number} y2
+ * @returns {function(number): number}
+ */
+function bezier(x1, y1, x2, y2) {
+  const NEWTON_ITERATIONS = 4;
+  const NEWTON_MIN_SLOPE = 0.001;
+  const SUBDIVISION_PRECISION = 0.0000001;
+  const SUBDIVISION_MAX_ITERATIONS = 10;
+  const kSplineTableSize = 11;
+  const kSampleStepSize = 1.0 / (kSplineTableSize - 1.0);
+
+  function A(a1, a2) { return 1.0 - 3.0 * a2 + 3.0 * a1; }
+  function B(a1, a2) { return 3.0 * a2 - 6.0 * a1; }
+  function C(a1)     { return 3.0 * a1; }
+
+  function calcBezier(t, a1, a2) {
+    return ((A(a1, a2) * t + B(a1, a2)) * t + C(a1)) * t;
+  }
+
+  function getSlope(t, a1, a2) {
+    return 3.0 * A(a1, a2) * t * t + 2.0 * B(a1, a2) * t + C(a1);
+  }
+
+  function binarySubdivide(x, a, b) {
+    let currentX, currentT, i = 0;
+    do {
+      currentT = a + (b - a) / 2.0;
+      currentX = calcBezier(currentT, x1, x2) - x;
+      if (currentX > 0.0) b = currentT;
+      else a = currentT;
+    } while (Math.abs(currentX) > SUBDIVISION_PRECISION && ++i < SUBDIVISION_MAX_ITERATIONS);
+    return currentT;
+  }
+
+  function newtonRaphsonIterate(x, guessT) {
+    for (let i = 0; i < NEWTON_ITERATIONS; ++i) {
+      const currentSlope = getSlope(guessT, x1, x2);
+      if (currentSlope === 0.0) return guessT;
+      const currentX = calcBezier(guessT, x1, x2) - x;
+      guessT -= currentX / currentSlope;
+    }
+    return guessT;
+  }
+
+  // Precompute sample table
+  const sampleValues = new Float32Array(kSplineTableSize);
+  if (x1 !== y1 || x2 !== y2) {
+    for (let i = 0; i < kSplineTableSize; ++i) {
+      sampleValues[i] = calcBezier(i * kSampleStepSize, x1, x2);
+    }
+  }
+
+  function getTForX(x) {
+    let intervalStart = 0.0;
+    let currentSample = 1;
+    const lastSample = kSplineTableSize - 1;
+
+    for (; currentSample !== lastSample && sampleValues[currentSample] <= x; ++currentSample) {
+      intervalStart += kSampleStepSize;
+    }
+    --currentSample;
+
+    const dist = (x - sampleValues[currentSample]) / (sampleValues[currentSample + 1] - sampleValues[currentSample]);
+    const guessForT = intervalStart + dist * kSampleStepSize;
+    const initialSlope = getSlope(guessForT, x1, x2);
+
+    if (initialSlope >= NEWTON_MIN_SLOPE) {
+      return newtonRaphsonIterate(x, guessForT);
+    } else if (initialSlope === 0.0) {
+      return guessForT;
+    } else {
+      return binarySubdivide(x, intervalStart, intervalStart + kSampleStepSize);
+    }
+  }
+
+  return function (t) {
+    if (x1 === y1 && x2 === y2) return t; // linear shortcut
+    if (t === 0) return 0;
+    if (t === 1) return 1;
+    return calcBezier(getTForX(t), y1, y2);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Higher-order composition wrappers
+// ---------------------------------------------------------------------------
+
+/**
+ * Runs an easing function forwards (ease-in direction).
+ * `in(f)(t) = f(t)`
+ *
+ * @param {function(number): number} easing
+ * @returns {function(number): number}
+ */
+function _in(easing) {
+  return easing;
+}
+
+/**
+ * Runs an easing function backwards. Useful to apply ease-out variants.
+ * `out(f)(t) = 1 - f(1 - t)`
+ *
+ * @param {function(number): number} easing
+ * @returns {function(number): number}
+ */
+function out(easing) {
+  return function (t) {
+    return 1 - easing(1 - t);
+  };
+}
+
+/**
+ * Makes any easing function symmetrical. The easing function will run
+ * forwards for half of the duration, then backwards for the rest of
+ * the duration.
+ * `inOut(f)(t) = t < 0.5 ? f(2t)/2 : 1 - f(2(1-t))/2`
+ *
+ * @param {function(number): number} easing
+ * @returns {function(number): number}
+ */
+function inOut(easing) {
+  return function (t) {
+    if (t < 0.5) {
+      return easing(t * 2) / 2;
+    }
+    return 1 - easing((1 - t) * 2) / 2;
+  };
+}
+
+module.exports = {
+  linear,
+  quad,
+  cubic,
+  poly,
+  sin,
+  circle,
+  exp,
+  elastic,
+  back,
+  bounce,
+  bezier,
+  in: _in,
+  out,
+  inOut,
+};

package/scripts/lib/parse-contract.cjs

@@ -0,0 +1,220 @@
+'use strict';
+/**
+ * parse-contract.cjs — shared helper for validating agent output contracts.
+ *
+ * Agents that emit structured JSON blocks (e.g. motion-mapper) use this helper
+ * to validate and extract the structured data from their output. Works without
+ * optional dependencies: pure-JS JSON schema validation for the motion-map contract.
+ *
+ * Usage:
+ *   const { parseMotionMap, validate } = require('./parse-contract.cjs');
+ *   const result = parseMotionMap(markdownString);
+ *   if (result.ok) console.log(result.data);
+ *   else console.error(result.error);
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// ---------------------------------------------------------------------------
+// JSON block extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the first ```json ... ``` fenced block from a markdown string.
+ * Returns { ok: true, raw: string } or { ok: false, error: string }.
+ */
+function extractJsonBlock(markdown) {
+  const match = markdown.match(/```json\s*\n([\s\S]*?)\n```/);
+  if (!match) {
+    return { ok: false, error: 'No ```json ... ``` block found in output' };
+  }
+  return { ok: true, raw: match[1] };
+}
+
+/**
+ * Parse a JSON string. Returns { ok: true, data } or { ok: false, error }.
+ */
+function parseJson(raw) {
+  try {
+    return { ok: true, data: JSON.parse(raw) };
+  } catch (e) {
+    return { ok: false, error: `JSON parse error: ${e.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Motion map contract validation (hand-written — no ajv dependency required)
+// ---------------------------------------------------------------------------
+
+const VALID_EASINGS = new Set([
+  'linear',
+  'quad', 'quad-in', 'quad-out', 'quad-in-out',
+  'cubic', 'cubic-in', 'cubic-out', 'cubic-in-out',
+  'poly', 'poly-in', 'poly-out', 'poly-in-out',
+  'sin', 'sin-in', 'sin-out', 'sin-in-out',
+  'circle', 'circle-in', 'circle-out', 'circle-in-out',
+  'exp', 'exp-in', 'exp-out', 'exp-in-out',
+  'elastic', 'elastic-in', 'elastic-out', 'elastic-in-out',
+  'back', 'back-in', 'back-out', 'back-in-out',
+  'bounce', 'bounce-in', 'bounce-out', 'bounce-in-out',
+  'bezier',
+]);
+
+const VALID_TRANSITION_FAMILIES = new Set([
+  '3d', 'blur', 'cover', 'destruction', 'dissolve', 'distortion', 'grid', 'light',
+]);
+
+const VALID_DURATION_CLASSES = new Set([
+  'instant', 'quick', 'standard', 'slow', 'narrative',
+]);
+
+const VALID_TRIGGERS = new Set([
+  'user-gesture', 'state-change', 'scroll-progress', 'time', 'loop',
+]);
+
+/**
+ * Validate a single AnimationBinding object.
+ * Returns an array of error strings (empty = valid).
+ */
+function validateBinding(binding, index) {
+  const errors = [];
+  const ctx = `animations[${index}]`;
+
+  if (typeof binding.id !== 'string' || !binding.id) {
+    errors.push(`${ctx}.id: required string`);
+  }
+  if (!binding.location || typeof binding.location.file !== 'string' || typeof binding.location.line !== 'number') {
+    errors.push(`${ctx}.location: required {file: string, line: number}`);
+  }
+
+  // Easing: either a canonical string or a custom object
+  const easing = binding.easing;
+  if (easing === undefined || easing === null) {
+    errors.push(`${ctx}.easing: required`);
+  } else if (typeof easing === 'string') {
+    if (!VALID_EASINGS.has(easing)) {
+      errors.push(`${ctx}.easing: "${easing}" is not a canonical easing. Use one of: ${[...VALID_EASINGS].join(', ')} — or use { type: "custom", justification: "..." }`);
+    }
+  } else if (typeof easing === 'object') {
+    if (easing.type !== 'custom') {
+      errors.push(`${ctx}.easing.type: must be "custom" for object form`);
+    }
+    if (typeof easing.justification !== 'string' || !easing.justification.trim()) {
+      errors.push(`${ctx}.easing.justification: required non-empty string when using custom easing`);
+    }
+  } else {
+    errors.push(`${ctx}.easing: must be string (canonical name) or object { type: "custom", justification, value? }`);
+  }
+
+  // transition_family: optional, but if present must be valid
+  if (binding.transition_family !== undefined) {
+    if (!VALID_TRANSITION_FAMILIES.has(binding.transition_family)) {
+      errors.push(`${ctx}.transition_family: "${binding.transition_family}" is not a valid family. Use one of: ${[...VALID_TRANSITION_FAMILIES].join(', ')}`);
+    }
+  }
+
+  // duration_class: required
+  if (!VALID_DURATION_CLASSES.has(binding.duration_class)) {
+    errors.push(`${ctx}.duration_class: required, must be one of: ${[...VALID_DURATION_CLASSES].join(', ')}`);
+  }
+
+  // trigger: required
+  if (!VALID_TRIGGERS.has(binding.trigger)) {
+    errors.push(`${ctx}.trigger: required, must be one of: ${[...VALID_TRIGGERS].join(', ')}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a parsed motion-map object against the contract.
+ * Returns { ok: true, data } or { ok: false, errors: string[] }.
+ */
+function validateMotionMap(data) {
+  const errors = [];
+
+  if (data.schema_version !== '1.0.0') {
+    errors.push(`schema_version: must be "1.0.0", got "${data.schema_version}"`);
+  }
+  if (typeof data.generated_at !== 'string') {
+    errors.push('generated_at: required ISO-8601 string');
+  }
+  if (!Array.isArray(data.animations)) {
+    errors.push('animations: required array');
+  } else {
+    data.animations.forEach((b, i) => {
+      errors.push(...validateBinding(b, i));
+    });
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+  return { ok: true, data };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract, parse, and validate a motion-map JSON block from agent output markdown.
+ *
+ * @param {string} markdown - Full markdown output from motion-mapper
+ * @returns {{ ok: true, data: object } | { ok: false, error: string }}
+ */
+function parseMotionMap(markdown) {
+  const extracted = extractJsonBlock(markdown);
+  if (!extracted.ok) return { ok: false, error: extracted.error };
+
+  const parsed = parseJson(extracted.raw);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+
+  const validated = validateMotionMap(parsed.data);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      error: `Motion map contract violations:\n${validated.errors.map(e => `  - ${e}`).join('\n')}`,
+    };
+  }
+
+  return { ok: true, data: validated.data };
+}
+
+/**
+ * Generic JSON block extractor and parser (no schema validation).
+ * Use for contracts without a built-in validator.
+ */
+function parseGenericContract(markdown) {
+  const extracted = extractJsonBlock(markdown);
+  if (!extracted.ok) return { ok: false, error: extracted.error };
+  return parseJson(extracted.raw);
+}
+
+/**
+ * Load the motion-map JSON schema from the reference directory.
+ * Used by external validators (e.g., ajv if available).
+ */
+function loadMotionMapSchema(projectRoot) {
+  const schemaPath = path.join(
+    projectRoot || process.cwd(),
+    'reference/output-contracts/motion-map.schema.json',
+  );
+  return JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+}
+
+module.exports = {
+  parseMotionMap,
+  parseGenericContract,
+  loadMotionMapSchema,
+  validateMotionMap,
+  extractJsonBlock,
+  parseJson,
+  // Exported for testing
+  _validateBinding: validateBinding,
+  VALID_EASINGS,
+  VALID_TRANSITION_FAMILIES,
+  VALID_DURATION_CLASSES,
+  VALID_TRIGGERS,
+};

package/scripts/lib/spring.cjs

@@ -0,0 +1,160 @@
+/**
+ * Spring animation utilities.
+ *
+ * Source: React Native — Libraries/Animated/SpringConfig.js (MIT License)
+ * Attribution: Facebook, Inc. and its affiliates
+ * https://github.com/facebook/react-native/blob/main/Libraries/Animated/SpringConfig.js
+ *
+ * Implements a mass-spring-damper physical model.
+ * Parameters:
+ *   stiffness (k) — spring constant; higher = faster, snappier
+ *   damping   (c) — friction coefficient; higher = less oscillation
+ *   mass      (m) — simulated mass; higher = slower, heavier feel
+ */
+
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Canonical presets
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical spring presets.
+ *
+ * Each preset includes stiffness, damping, and mass.
+ * Settle times are approximate at 60fps with threshold=0.001.
+ *
+ * | name    | stiffness | damping | mass | settle  | character           |
+ * |---------|-----------|---------|------|---------|---------------------|
+ * | gentle  | 120       | 14      | 1    | ~400ms  | soft, mild bounce   |
+ * | wobbly  | 180       | 12      | 1    | ~600ms  | bouncy, 2–3 cycles  |
+ * | stiff   | 400       | 30      | 1    | ~200ms  | snappy, minimal     |
+ * | slow    | 280       | 60      | 1    | ~800ms  | heavy, no bounce    |
+ */
+const PRESETS = {
+  gentle: { stiffness: 120, damping: 14, mass: 1 },
+  wobbly: { stiffness: 180, damping: 12, mass: 1 },
+  stiff:  { stiffness: 400, damping: 30, mass: 1 },
+  slow:   { stiffness: 280, damping: 60, mass: 1 },
+};
+
+// ---------------------------------------------------------------------------
+// Critical damping
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes the critical damping coefficient for a given stiffness and mass.
+ *
+ * At critical damping (`c = 2 * sqrt(k * m)`), the spring reaches its target
+ * in the shortest time possible without oscillating.
+ *
+ * Values below this threshold produce an underdamped (bouncy) spring.
+ * Values above this threshold produce an overdamped (sluggish) spring.
+ *
+ * @param {number} stiffness - Spring constant k.
+ * @param {number} mass      - Simulated mass m.
+ * @returns {number} Critical damping coefficient c.
+ */
+function criticalDamping(stiffness, mass) {
+  return 2 * Math.sqrt(stiffness * mass);
+}
+
+// ---------------------------------------------------------------------------
+// Settle time estimation
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimates the settle time of a spring in milliseconds by stepping the
+ * simulation forward until position and velocity are both within `threshold`
+ * of the target.
+ *
+ * Uses a fixed timestep of 1/60 s (60fps) for numerical integration.
+ *
+ * @param {number} stiffness        - Spring constant k.
+ * @param {number} damping          - Damping coefficient c.
+ * @param {number} mass             - Simulated mass m.
+ * @param {number} [threshold=0.001] - Convergence threshold for position and velocity.
+ * @param {number} [maxMs=5000]     - Safety ceiling to prevent infinite loops.
+ * @returns {number} Estimated settle time in milliseconds.
+ */
+function settleTime(stiffness, damping, mass, threshold, maxMs) {
+  if (threshold === undefined) threshold = 0.001;
+  if (maxMs === undefined) maxMs = 5000;
+
+  const dt = 1 / 60;            // seconds per frame
+  const maxFrames = Math.ceil(maxMs / (dt * 1000));
+
+  let pos = 1;   // start displaced from target (normalized)
+  let vel = 0;
+  let elapsed = 0;
+
+  for (let i = 0; i < maxFrames; i++) {
+    const result = _stepInternal(stiffness, damping, mass, pos, vel, dt);
+    pos = result.position;
+    vel = result.velocity;
+    elapsed += dt * 1000;
+
+    if (Math.abs(pos) < threshold && Math.abs(vel) < threshold) {
+      return elapsed;
+    }
+  }
+
+  return maxMs;  // did not settle within safety ceiling
+}
+
+// ---------------------------------------------------------------------------
+// Step function
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal integration step — semi-implicit Euler.
+ * @private
+ */
+function _stepInternal(stiffness, damping, mass, position, velocity, dt) {
+  const acceleration = (-stiffness * position - damping * velocity) / mass;
+  const newVelocity  = velocity + acceleration * dt;
+  const newPosition  = position + newVelocity * dt;
+  return { position: newPosition, velocity: newVelocity };
+}
+
+/**
+ * Advances a spring simulation by one timestep.
+ *
+ * The spring is always simulated toward the target value 0 (normalized).
+ * To animate from `from` to `to`, offset your inputs:
+ *   position = currentValue - toValue
+ *   velocity = currentVelocity  (positive = moving toward target)
+ *
+ * @param {number} stiffness       - Spring constant k.
+ * @param {number} damping         - Damping coefficient c.
+ * @param {number} mass            - Simulated mass m.
+ * @param {number} initialVelocity - Current velocity in units/second.
+ * @param {number} dt              - Timestep in seconds. Use 1/60 for 60fps.
+ * @returns {{ position: number, velocity: number }}
+ *
+ * @example
+ * // Animate a value from 0 to 100:
+ * let pos = 0 - 100;  // offset: (current - target)
+ * let vel = 0;
+ * const dt = 1/60;
+ *
+ * function tick() {
+ *   const result = step(400, 30, 1, vel, dt);
+ *   // Note: pass current velocity, not initialVelocity parameter which is legacy
+ *   pos = result.position;
+ *   vel = result.velocity;
+ *   const displayValue = pos + 100;  // un-offset
+ * }
+ */
+function step(stiffness, damping, mass, initialVelocity, dt) {
+  // Position starts at 1 (displaced) when called externally without a position arg.
+  // For incremental use, callers manage position themselves — see _stepInternal.
+  return _stepInternal(stiffness, damping, mass, 1 - initialVelocity * dt, initialVelocity, dt);
+}
+
+module.exports = {
+  PRESETS,
+  criticalDamping,
+  settleTime,
+  step,
+};