motionspec 1.0.0

package/src/compiler/compile.js

@@ -0,0 +1,149 @@
+"use strict";
+/*
+ * MotionSpec-Compiler — v0.2 (Bibliothek)
+ * ----------------------------------------------------------------------
+ * Uebersetzt eine validierte MotionSpec deterministisch in Code.
+ * Kein Modell beteiligt: dieselbe Spec ergibt immer denselben Code.
+ *
+ * Sichere Interpolation (v0.2):
+ *   {{pfad}}      -> JS-Literal: Strings/Objekte via JSON.stringify,
+ *                    Zahlen/Booleans direkt. Ein Wert kann den String-/
+ *                    Ausdruckskontext NIE verlassen.
+ *   {{css pfad}}  -> Roh-Einfuegung fuer CSS-Kontexte, aber nur wenn der
+ *                    Wert die CSS-Allow-List besteht (sonst Abbruch).
+ *
+ * Ablauf: Trust Boundary -> Defaults -> Templates -> Gates -> Report.
+ */
+const { validateSpec, unsafeToken } = require("./validate.js");
+const VERSION = require("../../package.json").version;
+
+const BUDGET = 10; /* Performance-Budget: Summe der Primitiv-Kosten */
+const CSS_SAFE_RE = /^[A-Za-z0-9 _\-#.:,()>+~*=%[\]"|^$]{0,200}$/;
+
+function resolvePath(ctx, expr) {
+  return expr.split(".").reduce(
+    (o, k) => (o === undefined || o === null ? undefined : o[k]),
+    ctx
+  );
+}
+
+function jsLiteral(v) {
+  if (v === undefined || v === null) return "null";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return JSON.stringify(v); /* Strings UND Objekte: immer korrekt escaped */
+}
+
+function cssRaw(v, expr) {
+  const s = String(v);
+  const bad = unsafeToken(s); /* defense in depth: never emit javascript:/expression(/url( ... */
+  if (bad || !CSS_SAFE_RE.test(s) || s.includes("/*") || s.includes("*/"))
+    throw new Error('CSS-Interpolation abgelehnt fuer "' + expr + '": Wert "' + s + '"' + (bad ? ' enthaelt gefaehrliches Token "' + bad + '"' : " verletzt die CSS-Allow-List") + ".");
+  return s;
+}
+
+function fill(tpl, ctx) {
+  return tpl.replace(/\{\{([^}]+)\}\}/g, (_, raw) => {
+    const expr = raw.trim();
+    if (expr.startsWith("css ")) {
+      const v = resolvePath(ctx, expr.slice(4).trim());
+      return cssRaw(v === undefined ? "" : v, expr);
+    }
+    return jsLiteral(resolvePath(ctx, expr));
+  });
+}
+
+function withDefaults(schema, given) {
+  const out = {};
+  Object.keys(schema).forEach((k) => {
+    out[k] = given && Object.prototype.hasOwnProperty.call(given, k)
+      ? given[k]
+      : schema[k].default;
+  });
+  return out;
+}
+
+/*
+ * compileSpec(spec, catalog, opts) -> {
+ *   ok, errors?, js?, css?, report: { motions, jsCount, cssCount,
+ *   cost, budget, budgetOk, reducedMotion } }
+ */
+function compileSpec(spec, catalog, opts) {
+  const o = opts || {};
+  const budget = typeof o.budget === "number" ? o.budget : BUDGET; /* Audit #16: konfigurierbar */
+  const v = validateSpec(spec, catalog);
+  if (!v.ok) return { ok: false, errors: v.errors };
+
+  /* ADR-0001 D4: deprecation note comes from the validator (single source),
+   * so validate-only callers and the compile report agree. */
+  const deprecations = v.deprecations || [];
+
+  const respectRM = !!(spec.globals && spec.globals.respectReducedMotion);
+  const js = [], css = [];
+  let cost = 0, nJs = 0, nCss = 0;
+
+  for (const m of spec.motions) {
+    const prim = catalog[m.primitive];
+    const params = withDefaults(prim.paramSchema || {}, m.params);
+    const trigger = Object.assign({}, prim.triggerDefaults || {}, m.trigger || {});
+    const ctx = { id: m.id, target: m.target, params, trigger, globals: spec.globals || {} };
+    let code;
+    try { code = fill(prim.template, ctx); }
+    catch (e) { return { ok: false, errors: ["[MS-COMPILE-CSS] Compile-Abbruch bei motion '" + m.id + "': " + e.message] }; }
+    cost += (prim.performance && prim.performance.cost) || 0;
+    if (prim.output === "css") {
+      css.push("  /* " + m.id + " (" + m.primitive + ") */");
+      css.push("  " + code.split("\n").join("\n  "));
+      nCss++;
+    } else {
+      js.push("  /* " + m.id + " (" + m.primitive + ") */");
+      js.push("  " + code);
+      nJs++;
+    }
+  }
+
+  /* Audit-Befund #1: Kommentar-Injection via Dateiname verhindern. */
+  const safeName = String(o.specName || "spec").replace(/\*\/|\/\*/g, "_").slice(0, 80);
+  const specLabel = safeName + "  Ziel: " + spec.meta.target;
+  let jsOut = null, cssOut = null;
+
+  if (nJs > 0) {
+    const head = [
+      "/* MotionSpec-Compiler v" + VERSION + " - generiertes Artefakt. NICHT von Hand bearbeiten; die Spec ist die Quelle. */",
+      "/* Spec: " + specLabel + " */",
+      "(function () {",
+      "  if (typeof gsap === 'undefined') { console.warn('[motion] GSAP nicht geladen.'); return; }",
+      "  gsap.registerPlugin(ScrollTrigger);",
+    ];
+    if (respectRM) {
+      head.push("  var reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;");
+      head.push("  if (reduceMotion) return;  /* a11y: respectReducedMotion */");
+    }
+    jsOut = head.concat(js, ["})();", ""]).join("\n");
+  }
+
+  if (nCss > 0) {
+    let body = "/* MotionSpec-Compiler v" + VERSION + " - generiertes Artefakt. */\n";
+    if (respectRM) body += "@media (prefers-reduced-motion: no-preference) {\n" + css.join("\n") + "\n}\n";
+    else body += css.join("\n") + "\n";
+    cssOut = body;
+  }
+
+  return {
+    ok: true,
+    js: jsOut,
+    css: cssOut,
+    report: {
+      motions: spec.motions.length,
+      jsCount: nJs,
+      cssCount: nCss,
+      cost,
+      budget,
+      budgetOk: cost <= budget,
+      reducedMotion: respectRM,
+      specVersion: spec.specVersion,
+      deprecations,
+    },
+  };
+}
+
+module.exports = { compileSpec, fill, withDefaults, BUDGET };

package/src/compiler/validate.js

@@ -0,0 +1,264 @@
+"use strict";
+/*
+ * MotionSpec — Trust Boundary  (v0.3, Phase 2 / Sprint 2)
+ * ----------------------------------------------------------------------
+ * Anti-Corruption Layer zwischen dem Autor einer Spec (Modell oder Mensch)
+ * und dem Compiler. Prinzip: FAIL-CLOSED. Eine Spec passiert nur, wenn JEDE
+ * Pruefung besteht. Es wird niemals eine Teil-Ausgabe erzeugt.
+ *
+ * STABILE ERROR-CODES (Audit #15 / Sprint-2 S2-04):
+ *   Jeder Fehler traegt ein sprachneutrales Praefix [MS-XXX]. Integratoren
+ *   matchen auf den Code, nicht auf den (deutschen) Klartext. validateSpec
+ *   liefert zusaetzlich errorCodes[] fuer rein programmatische Nutzung.
+ *   Die Code-Liste ist API: Codes werden nie wiederverwendet/umdefiniert.
+ *
+ * Code-Registry:
+ *   MS-SPEC-OBJ      Spec ist kein Objekt
+ *   MS-SPEC-KEY      Unbekannter Top-Level-Schluessel
+ *   MS-SPEC-VER      specVersion fehlt/unbekannt
+ *   MS-SPEC-MOTIONS  motions fehlt/leer
+ *   MS-META-MISSING  meta fehlt
+ *   MS-META-KEY      Unbekannter meta-Schluessel
+ *   MS-META-TARGET   meta.target nicht unterstuetzt
+ *   MS-GLOBALS-OBJ   globals kein Objekt
+ *   MS-GLOBALS-KEY   unbekannter globals-Schluessel
+ *   MS-MOTION-OBJ    motion ist kein Objekt
+ *   MS-MOTION-KEY    Unbekannter motion-Schluessel
+ *   MS-ID-FORMAT     id fehlt/Format verletzt
+ *   MS-ID-DUP        id nicht eindeutig
+ *   MS-TARGET-UNSAFE target fehlt/unsicherer Selektor
+ *   MS-PRIM-MISSING  primitive fehlt
+ *   MS-PRIM-UNKNOWN  primitive nicht im Katalog (Allow-List)
+ *   MS-PARAM-UNKNOWN unbekannter Parameter
+ *   MS-PARAM-REQ     Pflichtparameter fehlt
+ *   MS-PARAM-TYPE    falscher Parameter-Typ
+ *   MS-PARAM-MIN     Parameter unter Minimum
+ *   MS-PARAM-MAX     Parameter ueber Maximum
+ *   MS-PARAM-CHARSET String-Parameter enthaelt unzulaessige Zeichen
+ *   MS-PARAM-UNSAFE  String-Parameter enthaelt gefaehrliches Token (javascript:, expression(, url(, ...)
+ *   MS-PARAM-PATTERN String-Parameter verletzt erlaubtes Muster
+ *   MS-PARAM-PATTERN-DEF paramSchema.pattern ist selbst ungueltig
+ *   MS-TRANSFORM-KEY unerlaubter Transform-Schluessel
+ *   MS-TRANSFORM-TYPE Transform-Wert keine Zahl
+ *   MS-TRIGGER-OBJ   trigger kein Objekt
+ *   MS-TRIGGER-KEY   unbekannter trigger-Schluessel
+ *   MS-TRIGGER-VAL   trigger-Positionswert ungueltig
+ *   MS-CATALOG-PIN     catalogVersion-Pin hat falsches Format
+ *   MS-CATALOG-PIN-MISMATCH catalogVersion-Pin passt nicht zum geladenen Katalog
+ *   MS-RESP-UNSUPPORTED responsive noch nicht unterstuetzt (-> specVersion 0.2)
+ *   MS-DEPRECATED-VERSION specVersion ist deprecated. KEIN harter Fehler:
+ *                     wird in validateSpec().deprecations[] UND im Compile-Report
+ *                     gemeldet (gemeinsame Quelle deprecationsFor; ADR-0001 D4).
+ */
+
+/* ADR-0001 (signed 2026-06-15): v1 carries "1.0". "0.1" stays accepted for
+ * one minor cycle (deprecated, compile report emits a note; removed in v1.2). */
+const SPEC_VERSIONS = ["1.0", "0.1"];
+const DEPRECATED_VERSIONS = ["0.1"];
+
+/* ADR-0001 D4: single source of the deprecation signal. Surfaced by BOTH
+ * validateSpec (so validate-only callers see it) and the compile report. */
+function deprecationsFor(specVersion) {
+  if (DEPRECATED_VERSIONS.indexOf(specVersion) === -1) return [];
+  return [{
+    code: "MS-DEPRECATED-VERSION",
+    message: 'specVersion "' + specVersion + '" is deprecated; migrate to "1.0". Accepted until v1.2.',
+  }];
+}
+const TARGETS = ["vanilla-gsap"];
+const TRANSFORM_KEYS = ["opacity", "x", "y", "scale", "rotation", "xPercent", "yPercent"];
+const TOP_KEYS = ["specVersion", "catalogVersion", "meta", "globals", "motions"];
+const CATALOG_PIN_RE = /^[0-9a-f]{16}$/;
+const META_KEYS = ["project", "target", "createdWith"];
+const GLOBALS_KEYS = ["respectReducedMotion", "defaultEase"];
+const MOTION_KEYS = ["id", "primitive", "target", "params", "trigger", "responsive"];
+
+const { catalogVersion } = require("./catalog.js");
+
+const ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const SELECTOR_RE = /^[A-Za-z0-9 _\-#.:,()>+~*=[\]"|^$]{1,200}$/;
+const STRING_PARAM_RE = /^[^\x00-\x1F\x7F`\\]{0,200}$/;
+
+/* Dangerous substrings that must never reach emitted JS/CSS, even when the
+ * charset gate would otherwise allow them (e.g. "url(javascript:…)",
+ * "expression(…)"). Checked by BOTH the validator (so motion_validate ok=true
+ * predicts compile success — closes the validate↔compile asymmetry) and the
+ * compiler's cssRaw (defense in depth). Lower-cased comparison. */
+const UNSAFE_TOKENS = [
+  "javascript:", "vbscript:", "expression(", "url(", "@import",
+  "behavior:", "-moz-binding", "</", "<script",
+];
+function unsafeToken(s) {
+  const l = String(s).toLowerCase();
+  for (const t of UNSAFE_TOKENS) if (l.indexOf(t) !== -1) return t;
+  return null;
+}
+
+function safeSelector(s) {
+  return (
+    typeof s === "string" &&
+    SELECTOR_RE.test(s) &&
+    s.indexOf("/*") === -1 &&
+    s.indexOf("*/") === -1
+  );
+}
+
+function validateParams(prim, params, at, push, partial) {
+  const schema = prim.paramSchema || {};
+  Object.keys(params).forEach((k) => {
+    if (!schema[k]) push("MS-PARAM-UNKNOWN", at + ': unbekannter Parameter "' + k + '" fuer Primitiv "' + prim.name + '".');
+  });
+  Object.keys(schema).forEach((k) => {
+    const def = schema[k];
+    const has = Object.prototype.hasOwnProperty.call(params, k);
+    if (!has) {
+      if (def.required && !partial) push("MS-PARAM-REQ", at + ': Pflichtparameter "' + k + '" fehlt.');
+      return;
+    }
+    const v = params[k];
+    if (def.type === "number") {
+      if (typeof v !== "number" || isNaN(v)) { push("MS-PARAM-TYPE", at + ': "' + k + '" muss eine Zahl sein.'); return; }
+      if (typeof def.min === "number" && v < def.min) push("MS-PARAM-MIN", at + ': "' + k + '" = ' + v + " liegt unter dem Minimum " + def.min + ".");
+      if (typeof def.max === "number" && v > def.max) push("MS-PARAM-MAX", at + ': "' + k + '" = ' + v + " liegt ueber dem Maximum " + def.max + ".");
+    } else if (def.type === "string") {
+      if (typeof v !== "string") push("MS-PARAM-TYPE", at + ': "' + k + '" muss ein String sein.');
+      else if (!STRING_PARAM_RE.test(v)) push("MS-PARAM-CHARSET", at + ': "' + k + '" enthaelt unzulaessige Zeichen (Steuerzeichen, Backslash, Backtick) oder ist zu lang.');
+      else if (unsafeToken(v)) push("MS-PARAM-UNSAFE", at + ': "' + k + '" enthaelt ein unzulaessiges Token "' + unsafeToken(v) + '" (z.B. javascript:, expression(, url(). Abgelehnt.');
+      else if (def.pattern) {
+        let re = null;
+        try { re = new RegExp(def.pattern); }
+        catch { push("MS-PARAM-PATTERN-DEF", at + ': paramSchema.pattern fuer "' + k + '" ist kein gueltiger regulaerer Ausdruck.'); }
+        if (re && !re.test(v))
+          push("MS-PARAM-PATTERN", at + ': "' + k + '" = "' + v + '" entspricht nicht dem erlaubten Muster ' + def.pattern + ".");
+      }
+    } else if (def.type === "boolean") {
+      if (typeof v !== "boolean") push("MS-PARAM-TYPE", at + ': "' + k + '" muss true oder false sein.');
+    } else if (def.type === "transform") {
+      if (typeof v !== "object" || v === null || Array.isArray(v)) {
+        push("MS-PARAM-TYPE", at + ': "' + k + '" muss ein Transform-Objekt sein.'); return;
+      }
+      Object.keys(v).forEach((tk) => {
+        if (TRANSFORM_KEYS.indexOf(tk) === -1)
+          push("MS-TRANSFORM-KEY", at + ': "' + k + "." + tk + '" ist kein erlaubter Transform-Schluessel (erlaubt: ' + TRANSFORM_KEYS.join(", ") + ").");
+        else if (typeof v[tk] !== "number")
+          push("MS-TRANSFORM-TYPE", at + ': "' + k + "." + tk + '" muss eine Zahl sein.');
+      });
+    }
+  });
+}
+
+function validateTrigger(trigger, at, push) {
+  if (typeof trigger !== "object" || trigger === null || Array.isArray(trigger)) {
+    push("MS-TRIGGER-OBJ", at + ": trigger muss ein Objekt sein."); return;
+  }
+  const KEYS = ["start", "end", "once"];
+  Object.keys(trigger).forEach((k) => {
+    if (KEYS.indexOf(k) === -1) push("MS-TRIGGER-KEY", at + ': trigger: unbekannter Schluessel "' + k + '".');
+  });
+  ["start", "end"].forEach((k) => {
+    if (trigger[k] !== undefined) {
+      if (typeof trigger[k] !== "string" || !/^[A-Za-z0-9 %+=.-]{1,40}$/.test(trigger[k]))
+        push("MS-TRIGGER-VAL", at + ": trigger." + k + ' muss ein einfacher Positions-String sein (z.B. "top 80%").');
+    }
+  });
+  if (trigger.once !== undefined && typeof trigger.once !== "boolean")
+    push("MS-TRIGGER-VAL", at + ": trigger.once muss true oder false sein.");
+}
+
+function validateSpec(spec, catalog) {
+  const errors = [];
+  const errorCodes = [];
+  /* push(code, msg) -> errors bekommt "[code] msg", errorCodes den Code. */
+  const push = (code, m) => { errors.push("[" + code + "] " + m); errorCodes.push(code); };
+
+  if (typeof spec !== "object" || spec === null || Array.isArray(spec))
+    return { ok: false, errors: ["[MS-SPEC-OBJ] Spec ist kein Objekt."], errorCodes: ["MS-SPEC-OBJ"], deprecations: [] };
+
+  const deprecations = deprecationsFor(spec.specVersion);
+
+  Object.keys(spec).forEach((k) => {
+    if (TOP_KEYS.indexOf(k) === -1) push("MS-SPEC-KEY", 'Unbekannter Schluessel auf oberster Ebene: "' + k + '".');
+  });
+
+  if (SPEC_VERSIONS.indexOf(spec.specVersion) === -1)
+    push("MS-SPEC-VER", "specVersion fehlt oder ist unbekannt (erlaubt: " + SPEC_VERSIONS.join(", ") + ").");
+
+  /* ADR-0001 D2: optional catalogVersion pin for reproducibility. If a spec
+   * pins a catalog hash, it MUST match the loaded catalog — fail-closed, so a
+   * spec written against a different catalog cannot silently compile differently. */
+  if (spec.catalogVersion !== undefined) {
+    if (typeof spec.catalogVersion !== "string" || !CATALOG_PIN_RE.test(spec.catalogVersion)) {
+      push("MS-CATALOG-PIN", "catalogVersion muss ein 16-stelliger Hex-Hash sein (oder weglassen).");
+    } else {
+      const actual = catalogVersion(catalog);
+      if (spec.catalogVersion !== actual)
+        push("MS-CATALOG-PIN-MISMATCH", "catalogVersion-Pin (" + spec.catalogVersion + ") passt nicht zum geladenen Katalog (" + actual + "). Spec wurde gegen einen anderen Katalog geschrieben.");
+    }
+  }
+
+  if (!spec.meta || typeof spec.meta !== "object") {
+    push("MS-META-MISSING", "meta fehlt.");
+  } else {
+    Object.keys(spec.meta).forEach((k) => {
+      if (META_KEYS.indexOf(k) === -1) push("MS-META-KEY", 'meta: unbekannter Schluessel "' + k + '".');
+    });
+    if (TARGETS.indexOf(spec.meta.target) === -1)
+      push("MS-META-TARGET", "meta.target fehlt oder wird nicht unterstuetzt (erlaubt: " + TARGETS.join(", ") + ").");
+  }
+
+  if (spec.globals !== undefined) {
+    if (typeof spec.globals !== "object" || spec.globals === null || Array.isArray(spec.globals)) {
+      push("MS-GLOBALS-OBJ", "globals muss ein Objekt sein.");
+    } else {
+      Object.keys(spec.globals).forEach((k) => {
+        if (GLOBALS_KEYS.indexOf(k) === -1) push("MS-GLOBALS-KEY", 'globals: unbekannter Schluessel "' + k + '" (erlaubt: ' + GLOBALS_KEYS.join(", ") + ").");
+      });
+    }
+  }
+
+  if (!Array.isArray(spec.motions) || spec.motions.length === 0) {
+    push("MS-SPEC-MOTIONS", "motions fehlt oder ist leer.");
+    return { ok: errors.length === 0, errors, errorCodes, deprecations };
+  }
+
+  const seen = {};
+  spec.motions.forEach((m, i) => {
+    const at = "motions[" + i + "]";
+    if (typeof m !== "object" || m === null) { push("MS-MOTION-OBJ", at + " ist kein Objekt."); return; }
+
+    Object.keys(m).forEach((k) => {
+      if (MOTION_KEYS.indexOf(k) === -1) push("MS-MOTION-KEY", at + ': unbekannter Schluessel "' + k + '".');
+    });
+
+    if (typeof m.id !== "string" || !ID_RE.test(m.id))
+      push("MS-ID-FORMAT", at + ": id fehlt oder verletzt das Format [A-Za-z0-9_-]{1,64}.");
+    else if (seen[m.id]) push("MS-ID-DUP", at + ': id "' + m.id + '" ist nicht eindeutig.');
+    else seen[m.id] = true;
+
+    if (!safeSelector(m.target))
+      push("MS-TARGET-UNSAFE", at + ": target fehlt oder ist kein sicherer CSS-Selektor (verboten: Quotes, Backslash, {, }, ;, @, Steuerzeichen; max. 200 Zeichen).");
+
+    /* --- Kern-Schutz: Primitive-Allow-List --- */
+    if (typeof m.primitive !== "string" || !m.primitive) {
+      push("MS-PRIM-MISSING", at + ": primitive fehlt.");
+    } else if (!catalog[m.primitive]) {
+      push("MS-PRIM-UNKNOWN", at + ': primitive "' + m.primitive + '" existiert nicht im Katalog. '
+        + "Erlaubt sind ausschliesslich: " + Object.keys(catalog).sort().join(", ") + ".");
+    } else {
+      const prim = catalog[m.primitive];
+      validateParams(prim, m.params || {}, at, push, false);
+      if (m.trigger !== undefined) validateTrigger(m.trigger, at, push);
+      if (m.responsive !== undefined) {
+        push("MS-RESP-UNSUPPORTED", at + ": responsive wird in dieser specVersion noch nicht unterstuetzt (geplant fuer 0.2). Feld entfernen.");
+      }
+    }
+  });
+
+  return { ok: errors.length === 0, errors, errorCodes, deprecations };
+}
+
+module.exports = {
+  validateSpec, safeSelector, ID_RE, deprecationsFor, unsafeToken,
+  SPEC_VERSIONS, DEPRECATED_VERSIONS, TARGETS,
+  TOP_KEYS, META_KEYS, GLOBALS_KEYS, MOTION_KEYS,
+};

package/src/demo/build-demo.js

@@ -0,0 +1,150 @@
+"use strict";
+/*
+ * Demo-Page-Generator (MS-01 / T01) — Geraete-Verifikation der Primitive.
+ *
+ *   node bin/motion.js demo   ->  out/demo/index.html
+ *
+ * Eine scrollbare Seite mit einer Sektion je Primitiv. Der Motion-Code ist
+ * ECHTER Compiler-Output (compileSpec) — verifiziert wird also exakt das,
+ * was Kunden bekommen, nicht eine Nachbildung.
+ *
+ * Reduced-Motion-Simulation: ?rm=1 ueberschreibt window.matchMedia VOR dem
+ * Motion-Skript — getestet wird der echte Gate-Pfad im kompilierten Code.
+ *
+ * Demo-Bloecke: jedes Primitiv KANN ein "demo"-Feld tragen
+ *   { html, params, trigger? }  — sonst greift der generische Block.
+ */
+const fs = require("fs");
+const path = require("path");
+const { loadCatalog, catalogVersion } = require("../compiler/catalog.js");
+const { compileSpec } = require("../compiler/compile.js");
+
+/* Fallback-Demos fuer den Bestand (Katalog-Definitionen ohne demo-Feld) */
+const BUILTIN_DEMOS = {
+  scrollReveal: {
+    html: '<h2 class="d-scrollReveal">scrollReveal — gleitet beim Eintritt herein</h2>',
+    params: { from: { opacity: 0, y: 48 }, duration: 0.8 },
+  },
+  staggerReveal: {
+    html: '<div class="grid"><div class="card d-staggerReveal">Karte 1</div><div class="card d-staggerReveal">Karte 2</div><div class="card d-staggerReveal">Karte 3</div></div>',
+    params: { from: { opacity: 0, y: 32 }, stagger: 0.15 },
+  },
+  parallaxLayer: {
+    html: '<div class="parallax-frame"><div class="bg d-parallaxLayer">PARALLAX</div><p>Vordergrund scrollt normal, Hintergrund versetzt.</p></div>',
+    params: { yPercent: -25, scrub: 1 },
+  },
+  pinnedSection: {
+    html: '<div class="pin-stage d-pinnedSection"><h2>pinnedSection</h2><p>Diese Sektion bleibt stehen, waehrend du weiterscrollst.</p></div>',
+    params: { distance: "+=80%" },
+  },
+  cssTransition: {
+    html: '<button class="cta d-cssTransition">Hover mich — cssTransition</button>',
+    params: { hoverValue: "translateY(-4px) scale(1.04)", duration: 0.25 },
+  },
+};
+
+const CHECKLIST = [
+  "Laeuft die Bewegung fluessig (kein Ruckeln) beim langsamen UND schnellen Scrollen?",
+  "Mobile: gleiche Pruefung auf einem echten Telefon (nicht nur DevTools).",
+  "?rm=1 anhaengen: Inhalte muessen sofort sichtbar sein, keine Bewegung.",
+  "Layout-Shift? Elemente duerfen vor Animation keinen Sprung verursachen.",
+  "Nach bestandener Pruefung: performance.verifiedAt im Primitiv setzen.",
+];
+
+function buildDemo(outDir) {
+  const catalog = loadCatalog();
+  const names = Object.keys(catalog).sort();
+  const motions = [];
+  const sections = [];
+
+  names.forEach((name) => {
+    const prim = catalog[name];
+    const demo = prim.demo || BUILTIN_DEMOS[name];
+    if (!demo) {
+      sections.push('<section class="prim"><h2>' + name + "</h2><p class='miss'>KEIN DEMO-BLOCK — Primitiv darf nicht verifiziert werden.</p></section>");
+      return;
+    }
+    const target = "." + "d-" + name;
+    motions.push(Object.assign(
+      { id: "demo-" + name, primitive: name, target, params: demo.params || {} },
+      demo.trigger ? { trigger: demo.trigger } : {}
+    ));
+    sections.push(
+      '<section class="prim" id="' + name + '">' +
+      "<h3>" + name + ' <span class="v">' + (prim.performance && prim.performance.verifiedAt ? "verifiziert " + prim.performance.verifiedAt : "UNVERIFIZIERT") + "</span></h3>" +
+      '<p class="purpose">' + (prim.purpose || "") + "</p>" +
+      '<div class="stage">' + demo.html + "</div>" +
+      "</section>"
+    );
+  });
+
+  const spec = {
+    specVersion: "1.0",
+    meta: { project: "demo", target: "vanilla-gsap", createdWith: "demo-generator" },
+    globals: { respectReducedMotion: true },
+    motions,
+  };
+  const res = compileSpec(spec, catalog, { specName: "demo" });
+  if (!res.ok) throw new Error("Demo-Spec abgewiesen:\n  " + res.errors.join("\n  "));
+
+  const html = `<!doctype html>
+<html lang="de">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MotionSpec — Verifikations-Demo (Katalog ${catalogVersion(catalog)})</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: system-ui, sans-serif; margin: 0; line-height: 1.5; }
+  header, footer { padding: 3rem 1.5rem; max-width: 52rem; margin: 0 auto; }
+  .prim { min-height: 90vh; padding: 4rem 1.5rem; max-width: 52rem; margin: 0 auto; border-top: 1px solid #8884; }
+  .stage { margin-top: 2rem; }
+  .grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 1rem; }
+  .card { padding: 2rem 1rem; border: 1px solid #8886; border-radius: 10px; text-align: center; }
+  .parallax-frame { position: relative; overflow: hidden; border-radius: 10px; padding: 4rem 1rem; border: 1px solid #8886; }
+  .parallax-frame .bg { position: absolute; inset: -30% 0; display: flex; align-items: center; justify-content: center; font-size: 4rem; opacity: .12; pointer-events: none; }
+  .pin-stage { padding: 3rem 1rem; border: 1px solid #8886; border-radius: 10px; }
+  .cta { font-size: 1rem; padding: .8rem 1.6rem; border-radius: 8px; border: 1px solid #8886; cursor: pointer; background: none; }
+  .counter { font-size: 3rem; font-weight: 700; }
+  .v { font-size: .65rem; padding: .15rem .5rem; border: 1px solid #8886; border-radius: 99px; vertical-align: middle; }
+  .miss { color: #c00; font-weight: 600; }
+  .purpose { opacity: .7; }
+  .rm-note { padding: .6rem 1rem; border: 1px dashed #8888; border-radius: 8px; font-size: .85rem; }
+  ol li { margin-bottom: .4rem; }
+  .marquee-track { overflow: hidden; white-space: nowrap; border: 1px solid #8886; border-radius: 10px; padding: 1rem 0; }
+</style>
+${res.css ? "<style>\n" + res.css + "</style>" : ""}
+</head>
+<body>
+<header>
+  <h1>MotionSpec — Verifikations-Demo</h1>
+  <p>Katalog <code>${catalogVersion(catalog)}</code> · ${names.length} Primitive · Compiler-Output 1:1 wie in Produktion.</p>
+  <p class="rm-note">Reduced-Motion-Pfad testen: <a href="?rm=1">?rm=1 anhaengen</a> — alles muss sofort sichtbar sein, ohne Bewegung.</p>
+  <details><summary><strong>Geraete-Checkliste (MS-02)</strong></summary><ol>${CHECKLIST.map((c) => "<li>" + c + "</li>").join("")}</ol></details>
+</header>
+${sections.join("\n")}
+<footer><p>Ende. Wenn alles oben fluessig lief: verifiedAt setzen, Kandidat befoerdern.</p></footer>
+<script>
+  if (new URLSearchParams(location.search).get("rm") === "1") {
+    const orig = window.matchMedia.bind(window);
+    window.matchMedia = (q) => q.includes("prefers-reduced-motion")
+      ? { matches: true, media: q, addEventListener(){}, removeEventListener(){} }
+      : orig(q);
+    document.title += " [reduced-motion simuliert]";
+  }
+</script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>
+<script>
+${res.js || ""}
+</script>
+</body>
+</html>`;
+
+  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+  const file = path.join(outDir, "index.html");
+  fs.writeFileSync(file, html);
+  return { file, primitives: names.length, motions: motions.length, report: res.report };
+}
+
+module.exports = { buildDemo, BUILTIN_DEMOS };

package/src/discover/discover.js

@@ -0,0 +1,92 @@
+"use strict";
+/*
+ * Client-Discovery (Sprint-2 S2-01) — Werkzeug, nicht der Lauf selbst.
+ *
+ * Eingabe: eine Brief-Datei (JSON), die beschreibt, welche Motions eine
+ * Seite WILL — in natuerlicher Sprache plus Ziel-Selektor:
+ *   { "project": "kunde-x", "intents": [
+ *       { "what": "Hero-Headline gleitet beim Scrollen herein", "target": ".hero h1" },
+ *       { "what": "Zahlen im Stats-Block zaehlen hoch", "target": ".stats .num" },
+ *       ... ] }
+ *
+ * Fuer jeden Intent versucht das Tool, ihn mit dem AKTUELLEN Katalog
+ * auszudruecken (heuristisches Mapping, gleiche Keyword-Logik wie der
+ * Mock-Router) und kompiliert. Ergebnis: ein Gap-Report (Markdown) mit
+ *   - abgedeckt:   Intent -> Primitiv, kompiliert
+ *   - LUECKE:      kein Primitiv passt -> benannte Katalog-Luecke
+ * Das Tool ENTSCHEIDET nichts und baut keine Primitive — es liefert die
+ * Daten, die Phase B (Freeze) und Phase C (Katalog) informieren.
+ *
+ * Anti-Goal-konform: Luecken werden GELOGGT, nie still gepatcht.
+ */
+const { loadCatalog } = require("../compiler/catalog.js");
+const { compileSpec } = require("../compiler/compile.js");
+
+/* Heuristisches Intent->Primitiv-Mapping (bewusst konservativ; ein echtes
+ * Modell kann das spaeter ersetzen — hier geht es nur um Gap-Findung). */
+const RULES = [
+  { re: /(stagger|nacheinander|gestaffelt|one after|cards?|karten|liste)/i, primitive: "staggerReveal", params: { from: { opacity: 0, y: 32 } } },
+  { re: /(z(ä|ae)hl|counter|hochz(ä|ae)hl|count up|nummer|zahl)/i, primitive: "counterUp", params: {} },
+  { re: /(parallax|tiefe|depth|layer|ebene)/i, primitive: "parallaxLayer", params: {} },
+  { re: /(pin|fixier|sticky|festhalten|haften)/i, primitive: "pinnedSection", params: {} },
+  { re: /(marquee|laufband|logo.?band|ticker|endlos)/i, primitive: "marquee", params: {} },
+  { re: /(skalier|scale|zoom|gr(ö|oe)(ß|ss)er werden)/i, primitive: "scaleOnScroll", params: {} },
+  { re: /(hover|maus|cursor|button)/i, primitive: "cssTransition", params: {} },
+  { re: /(reveal|einblend|fade|erscheinen|appear|headline|(ü|ue)berschrift|gleitet|scroll)/i, primitive: "scrollReveal", params: { from: { opacity: 0, y: 48 } } },
+];
+
+function mapIntent(what) {
+  for (const r of RULES) if (r.re.test(what)) return r;
+  return null;
+}
+
+function discover(brief) {
+  const catalog = loadCatalog();
+  const covered = [];
+  const gaps = [];
+  (brief.intents || []).forEach((intent, i) => {
+    const rule = mapIntent(intent.what || "");
+    if (!rule) {
+      gaps.push({ i, what: intent.what, target: intent.target, reason: "kein Katalog-Primitiv passt zur Absicht" });
+      return;
+    }
+    const spec = {
+      specVersion: "1.0",
+      meta: { project: brief.project || "discovery", target: "vanilla-gsap", createdWith: "discover" },
+      globals: { respectReducedMotion: true },
+      motions: [{ id: "intent-" + i, primitive: rule.primitive, target: intent.target || ".target", params: rule.params }],
+    };
+    const res = compileSpec(spec, catalog);
+    if (res.ok) covered.push({ i, what: intent.what, primitive: rule.primitive, budget: res.report.cost });
+    else gaps.push({ i, what: intent.what, target: intent.target, reason: "Mapping vorhanden, aber Compile/Validate scheiterte: " + (res.errors || []).join(" | ") });
+  });
+  return { project: brief.project || "discovery", total: (brief.intents || []).length, covered, gaps, catalogPrimitives: Object.keys(catalog).sort() };
+}
+
+function toMarkdown(r) {
+  const lines = [];
+  lines.push("# Gap-Report — " + r.project);
+  lines.push("");
+  lines.push("Erzeugt: " + new Date().toISOString().slice(0, 10) + " · Tool: `motion discover` (S2-01)");
+  lines.push("Katalog: " + r.catalogPrimitives.join(", "));
+  lines.push("");
+  lines.push("**" + r.covered.length + " / " + r.total + " Absichten abgedeckt · " + r.gaps.length + " Luecke(n).**");
+  lines.push("");
+  lines.push("> Heuristik errt bewusst Richtung „abgedeckt“ (Keyword-Mapping). „Abgedeckt“ ist daher EIN VORSCHLAG, der vom Menschen am echten Design bestaetigt werden muss (Anti-Goal A2: keine Schein-Abdeckung). Gemeldete LUECKEN sind dagegen hochsicher.");
+  lines.push("");
+  lines.push("## Abgedeckt");
+  if (r.covered.length === 0) lines.push("_keine_");
+  r.covered.forEach((c) => lines.push("- ✓ „" + c.what + "“ → `" + c.primitive + "` (cost " + c.budget + ")"));
+  lines.push("");
+  lines.push("## LUECKEN (Signal fuer Phase B + C — nichts wird still gepatcht)");
+  if (r.gaps.length === 0) lines.push("_keine — der aktuelle Katalog deckt die Seite vollstaendig._");
+  r.gaps.forEach((g) => lines.push("- ✗ „" + g.what + "“  (target: " + (g.target || "—") + ")\n  - " + g.reason));
+  lines.push("");
+  lines.push("## Naechster Schritt");
+  lines.push(r.gaps.length === 0
+    ? "Katalog reicht. Specs schreiben, kompilieren, Geraete-Check, ausliefern (S2-06)."
+    : "Luecken in S2-02 (Freeze: deckt v1 sie ab oder 0.2?) und S2-05 (neue Primitive nur fuer diese Luecken) einspeisen.");
+  return lines.join("\n");
+}
+
+module.exports = { discover, toMarkdown, mapIntent };