storymapper 0.1.0

package/frontend/js/save-pipeline.js

@@ -0,0 +1,170 @@
+/**
+ * save-pipeline.js — shared debounced whole-snapshot persistence (SM-214).
+ *
+ * Extracted from main.js#installSaveSubscriber and the SM-157 duplicate in
+ * renderer-ticket-editor.js so BOTH surfaces share one tested behaviour:
+ *
+ *   - every store commit (except skipReasons: applyRemote/hydrate) schedules
+ *     a debounced `adapter.save(projectId, snapshot)`;
+ *   - SM-153 race guard: the project id is captured at SCHEDULE time, so a
+ *     project switch inside the debounce window can never PUT snapshot A
+ *     under project B;
+ *   - a failed save is retried once after RETRY_MS; only the terminal
+ *     failure surfaces via onError. A newer commit supersedes a pending
+ *     RETRY (generation counter) — a stale retry never fires after a newer
+ *     flush. (Two in-flight first-attempt PUTs can still land out of order;
+ *     that is the accepted E18 last-write-wins envelope, unchanged here.);
+ *   - flushPendingSave(): synchronous flush for pagehide/beforeunload.
+ *     Prefers `adapter.saveBeacon` (fetch keepalive — survives the page
+ *     teardown) and falls back to fire-and-forget `adapter.save`. Without
+ *     it, closing the tab inside the debounce window silently loses the
+ *     last commit.
+ *
+ * UMD-wrapped, dependency-free; pure timer logic — fully unit-testable.
+ */
+(function (root, factory) {
+  if (typeof module === "object" && module.exports) module.exports = factory();
+  else (root.STORYMAP = root.STORYMAP || {}).savePipeline = factory();
+}(typeof self !== "undefined" ? self : this, function () {
+  "use strict";
+
+  const SAVE_PIPELINE = {
+    DEBOUNCE_MS_DEFAULT: 300,   // matches BOOTSTRAP.SAVE_DEBOUNCE_MS history
+    RETRY_MS_DEFAULT: 1200,     // delay before retrying a failed PUT
+    MAX_RETRIES_DEFAULT: 3      // retry transient (network/5xx) failures a few times
+  };
+
+  /**
+   * createSavePipeline(opts) → { flushPendingSave, dispose }
+   *
+   * opts:
+   *   store        ProjectStore-like: subscribe((snap, reason) => …)
+   *   adapter      adapter object OR () => adapter (resolved per save)
+   *   projectId    fixed string OR () => current id (resolved at SCHEDULE time)
+   *   skipReasons  Set<string> of commit reasons that must not persist
+   *   debounceMs / retryMs / maxRetries   overrides for SAVE_PIPELINE values
+   *   onError(err) terminal-failure callback (after the retry)
+   *   win          window-like; when it has addEventListener, pagehide +
+   *                beforeunload are wired to flushPendingSave
+   */
+  function createSavePipeline(opts) {
+    opts = opts || {};
+    if (!opts.store || typeof opts.store.subscribe !== "function") {
+      throw new Error("createSavePipeline: opts.store with subscribe() is required");
+    }
+    const getAdapter = (typeof opts.adapter === "function") ? opts.adapter : function () { return opts.adapter; };
+    const getProjectId = (typeof opts.projectId === "function") ? opts.projectId : function () { return opts.projectId; };
+    const skip = (opts.skipReasons && typeof opts.skipReasons.has === "function") ? opts.skipReasons : null;
+    const debounceMs = Number.isFinite(opts.debounceMs) ? opts.debounceMs : SAVE_PIPELINE.DEBOUNCE_MS_DEFAULT;
+    const retryMs = Number.isFinite(opts.retryMs) ? opts.retryMs : SAVE_PIPELINE.RETRY_MS_DEFAULT;
+    const maxRetries = Number.isFinite(opts.maxRetries) ? opts.maxRetries : SAVE_PIPELINE.MAX_RETRIES_DEFAULT;
+    const onError = (typeof opts.onError === "function") ? opts.onError : function () {};
+    const win = opts.win || null;
+    const setTimeoutFn = (win && win.setTimeout) ? win.setTimeout.bind(win) : setTimeout;
+    const clearTimeoutFn = (win && win.clearTimeout) ? win.clearTimeout.bind(win) : clearTimeout;
+
+    let timer = null;
+    let pendingSnap = null;
+    let pendingProjectId = null;
+    // Each flush bumps the generation; a scheduled retry only fires while its
+    // generation is still current — a newer flush supersedes the stale retry.
+    let generation = 0;
+
+    function takePending() {
+      const snap = pendingSnap, pid = pendingProjectId;
+      pendingSnap = null; pendingProjectId = null;
+      if (timer) { clearTimeoutFn(timer); timer = null; }
+      return (snap && pid) ? { snap, pid } : null;
+    }
+
+    // SM-244: a genuine HTTP client rejection (4xx — bad request, payload too
+    // large, validation) is DETERMINISTIC — retrying can't help, so surface it
+    // immediately. Everything else (a network/connection error with no
+    // statusCode — e.g. a stale keep-alive socket reset — or a 5xx) is
+    // TRANSIENT: the retry runs on a fresh connection and usually succeeds.
+    // The whole-snapshot PUT is idempotent (replace), so re-sending is safe.
+    function isRetriable(err) {
+      const sc = err && err.statusCode;
+      if (typeof sc === "number" && sc >= 400 && sc < 500) return false;
+      return true;
+    }
+
+    function attemptSave(pid, snap, retriesLeft, gen) {
+      Promise.resolve()
+        .then(function () { return getAdapter().save(pid, snap); })
+        .catch(function (err) {
+          if (gen !== generation) return;          // superseded by a newer flush
+          if (retriesLeft > 0 && isRetriable(err)) {
+            setTimeoutFn(function () {
+              if (gen !== generation) return;      // superseded while waiting
+              attemptSave(pid, snap, retriesLeft - 1, gen);
+            }, retryMs);
+            return;
+          }
+          onError(err);
+        });
+    }
+
+    function flush() {
+      timer = null;
+      const p = takePending();
+      if (!p) return;
+      generation++;
+      attemptSave(p.pid, p.snap, maxRetries, generation);
+    }
+
+    /**
+     * Synchronous flush for page teardown. Returns true when a pending save
+     * was sent. NOTE: browser keepalive bodies are capped (~64 KiB in-flight);
+     * a very large snapshot may still be dropped by the browser — best-effort,
+     * strictly better than losing the commit unconditionally.
+     */
+    function flushPendingSave() {
+      const p = takePending();
+      if (!p) return false;
+      generation++;                                // cancel any in-flight retry
+      const adapter = getAdapter();
+      let sent = false;
+      if (adapter && typeof adapter.saveBeacon === "function") {
+        // saveBeacon returns false when keepalive can't carry the snapshot
+        // (e.g. body above the browser cap) — fall through to a plain save.
+        try { sent = adapter.saveBeacon(p.pid, p.snap) !== false; }
+        catch (_) { sent = false; }
+      }
+      if (!sent && adapter) {
+        try { Promise.resolve(adapter.save(p.pid, p.snap)).catch(function () {}); }
+        catch (_) { /* ignore */ }
+      }
+      return true;
+    }
+
+    const unsubscribe = opts.store.subscribe(function (snap, reason) {
+      if (skip && skip.has(reason)) return;
+      pendingSnap = snap;
+      // SM-153: capture at SCHEDULE time, not flush time.
+      pendingProjectId = getProjectId();
+      if (timer) clearTimeoutFn(timer);
+      timer = setTimeoutFn(flush, debounceMs);
+    });
+
+    const onPageHide = function () { flushPendingSave(); };
+    if (win && typeof win.addEventListener === "function") {
+      win.addEventListener("pagehide", onPageHide);
+      win.addEventListener("beforeunload", onPageHide);
+    }
+
+    function dispose() {
+      if (timer) { clearTimeoutFn(timer); timer = null; }
+      generation++;
+      if (typeof unsubscribe === "function") { try { unsubscribe(); } catch (_) {} }
+      if (win && typeof win.removeEventListener === "function") {
+        win.removeEventListener("pagehide", onPageHide);
+        win.removeEventListener("beforeunload", onPageHide);
+      }
+    }
+
+    return { flushPendingSave, dispose };
+  }
+
+  return { SAVE_PIPELINE, createSavePipeline };
+}));

package/frontend/js/smartbar-autocomplete.js

@@ -0,0 +1,162 @@
+/**
+ * SM-216 — smart-bar autocomplete dropdown (browser UI).
+ *
+ * Attaches a Jira-style suggestion dropdown to a text input. Pure suggestion
+ * logic lives in shared/query-autocomplete.js; this module is just the DOM:
+ * render the candidates, keyboard-navigate and insert the chosen completion
+ * at the cursor. UMD-wrapped so the SAME file is require()d in jsdom tests
+ * and <script src>'d in the browser.
+ *
+ * Key semantics (SM-293): nothing is auto-highlighted. ↑/↓ choose, Enter
+ * accepts ONLY an explicitly chosen suggestion (otherwise it closes the menu
+ * and falls through so the input's own handler runs the query), Tab eagerly
+ * accepts the highlighted/first suggestion, Esc closes.
+ *
+ *   attachAutocomplete(inputEl, { getSnapshot, onAccept }) → { detach, _refresh }
+ *
+ * getSnapshot() → the current project snapshot (feeds field VALUE suggestions).
+ * onAccept()    → called after a completion is inserted (the smart-bar re-runs
+ *                 the query so the view + count update).
+ */
+(function (global, factory) {
+  if (typeof module === "object" && module.exports) module.exports = factory();
+  else {
+    const ns = (global.STORYMAP = global.STORYMAP || {});
+    ns.smartbarAutocomplete = factory();
+  }
+}(typeof window !== "undefined" ? window : globalThis, function () {
+  "use strict";
+
+  function attachAutocomplete(input, opts) {
+    opts = opts || {};
+    const doc = input.ownerDocument;
+    const ns = (input.ownerDocument.defaultView || global).STORYMAP || {};
+    const ac = ns.queryAutocomplete;
+    if (!ac) return { detach: function () {}, _refresh: function () {} };
+
+    const menu = doc.createElement("div");
+    menu.className = "smartbar-ac";
+    menu.setAttribute("role", "listbox");
+    menu.hidden = true;
+    doc.body.appendChild(menu);
+
+    let items = [];      // current suggestion objects
+    let active = -1;     // highlighted index
+
+    function snapshot() {
+      try { return (typeof opts.getSnapshot === "function" && opts.getSnapshot()) || { tickets: [] }; }
+      catch (_e) { return { tickets: [] }; }
+    }
+    function position() {
+      const r = input.getBoundingClientRect();
+      menu.style.left = r.left + "px";
+      menu.style.top = (r.bottom + 2) + "px";
+      menu.style.minWidth = r.width + "px";
+    }
+    function hide() { menu.hidden = true; menu.innerHTML = ""; items = []; active = -1; }
+
+    function render() {
+      const cursor = input.selectionStart == null ? input.value.length : input.selectionStart;
+      items = ac.suggest(input.value, cursor, snapshot());
+      if (!items.length) { hide(); return; }
+      // SM-293: NO auto-highlight. Enter must run the query, not silently
+      // accept a suggestion the user never chose — a suggestion becomes
+      // active only via explicit arrow navigation (Tab still accepts the
+      // first one without navigating).
+      active = -1;
+      menu.innerHTML = "";
+      items.forEach(function (s, i) {
+        const row = doc.createElement("div");
+        row.className = "smartbar-ac-item";
+        row.setAttribute("role", "option");
+        row.dataset.index = String(i);
+        const lab = doc.createElement("span");
+        lab.className = "smartbar-ac-label";
+        lab.textContent = s.label;
+        const kind = doc.createElement("span");
+        kind.className = "smartbar-ac-kind";
+        kind.textContent = s.kind;
+        row.appendChild(lab); row.appendChild(kind);
+        row.addEventListener("mousedown", function (ev) {
+          // mousedown (not click) so the input doesn't blur before we accept.
+          ev.preventDefault();
+          accept(i);
+        });
+        menu.appendChild(row);
+      });
+      position();
+      menu.hidden = false;
+    }
+
+    function highlight(next) {
+      if (!items.length) return;
+      active = (next + items.length) % items.length;
+      Array.prototype.forEach.call(menu.children, function (el, i) {
+        el.classList.toggle("active", i === active);
+      });
+      const el = menu.children[active];
+      if (el && el.scrollIntoView) el.scrollIntoView({ block: "nearest" });
+    }
+
+    function accept(i) {
+      const s = items[i];
+      if (!s) return;
+      const before = input.value.slice(0, s.replaceStart);
+      const afterText = input.value.slice(s.replaceEnd);
+      input.value = before + s.insertText + afterText;
+      const caret = (before + s.insertText).length;
+      input.setSelectionRange(caret, caret);
+      input.focus();
+      hide();
+      // chain: show the next set of suggestions (e.g. field → operator) and let
+      // the smart-bar re-run the (possibly now-complete) query.
+      if (typeof opts.onAccept === "function") opts.onAccept();
+      render();
+    }
+
+    function onKeydown(ev) {
+      if (menu.hidden) return;   // let Esc etc. fall through to the smart-bar
+      if (ev.key === "ArrowDown") {
+        ev.preventDefault();
+        highlight(active === -1 ? 0 : active + 1);
+      } else if (ev.key === "ArrowUp") {
+        ev.preventDefault();
+        highlight(active === -1 ? items.length - 1 : active - 1);
+      } else if (ev.key === "Enter") {
+        // SM-293: Enter accepts ONLY an explicitly chosen suggestion.
+        // Without one it closes the dropdown and falls through, so the
+        // input's own handler runs the query.
+        if (active >= 0) { ev.preventDefault(); ev.stopPropagation(); accept(active); }
+        else hide();
+      } else if (ev.key === "Tab") {
+        // Tab keeps the eager behavior: accept the highlighted or first one.
+        ev.preventDefault(); ev.stopPropagation(); accept(active >= 0 ? active : 0);
+      } else if (ev.key === "Escape") {
+        ev.preventDefault(); ev.stopPropagation(); hide();
+      }
+    }
+    function onInput() { render(); }
+    function onBlur() { setTimeout(hide, 120); }   // allow mousedown-accept first
+    function onFocus() { render(); }
+
+    input.addEventListener("keydown", onKeydown, true);
+    input.addEventListener("input", onInput);
+    input.addEventListener("focus", onFocus);
+    input.addEventListener("blur", onBlur);
+
+    return {
+      detach: function () {
+        input.removeEventListener("keydown", onKeydown, true);
+        input.removeEventListener("input", onInput);
+        input.removeEventListener("focus", onFocus);
+        input.removeEventListener("blur", onBlur);
+        if (menu.parentNode) menu.parentNode.removeChild(menu);
+      },
+      _menu: menu,
+      _refresh: render,
+      _accept: accept
+    };
+  }
+
+  return { attachAutocomplete: attachAutocomplete };
+}));

package/frontend/js/store.js

@@ -0,0 +1,197 @@
+/**
+ * ProjectStore — local mutable wrapper around a snapshot with undo/redo and
+ * the same applyRemote/hydrate semantics cmapper proved out.
+ *
+ * Three ways to install a fresh snapshot:
+ *   - applySnapshot(snap)  → user-driven (paste / load), commits as undo entry
+ *   - applyRemote(snap)    → WebSocket push, commits as undo entry but is a
+ *                            no-op when the incoming snapshot equals current
+ *   - hydrate(snap)        → initial load / project switch, WIPES undo stack
+ *
+ * applyRemote MUST NOT call hydrate — otherwise every WS round-trip nukes
+ * the user's undo history.
+ */
+(function (root, factory) {
+  if (typeof module === "object" && module.exports) module.exports = factory(require("./core.js"));
+  else (root.STORYMAP = root.STORYMAP || {}).store = factory(root.STORYMAP && root.STORYMAP.core);
+}(typeof self !== "undefined" ? self : this, function (core) {
+  "use strict";
+
+  if (!core) throw new Error("store.js: core module missing (load order: core.js BEFORE store.js)");
+
+  const MAX_UNDO = 200;
+
+  /**
+   * Named reasons that the store may pass to subscribers. The save-subscriber
+   * in main.js skips persistence on `applyRemote` (echo from WS) and `hydrate`
+   * (initial load / project switch); every other reason → debounced PUT.
+   * `op:*` is a stand-in for every dynamically wrapped core.ops entry
+   * (createTicket, updateProject, reorderTickets, …) — wrapOp uses the op
+   * name verbatim as the reason.
+   */
+  const STORE_REASONS = Object.freeze({
+    APPLY_REMOTE:   "applyRemote",
+    HYDRATE:        "hydrate",
+    APPLY_SNAPSHOT: "applySnapshot",
+    UNDO:           "undo",
+    REDO:           "redo"
+  });
+
+  /** Reasons the save-subscriber MUST NOT persist (would echo back to the
+   *  server and cause a ping-pong). */
+  const SKIP_PERSIST_REASONS = Object.freeze(new Set([
+    STORE_REASONS.APPLY_REMOTE,
+    STORE_REASONS.HYDRATE
+  ]));
+
+  function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+
+  // SM-220: a cheap O(N) change-signal over the snapshot. Every op bumps the
+  // touched entity's monotonic `version` (and create/delete changes a
+  // collection length), so this integer signature differs for essentially
+  // every real mutation — letting `applyRemote` skip the expensive
+  // JSON.stringify deepEqual on the common WS-push (real-change) path and
+  // commit straight away. A signal MATCH is NOT proof of equality (versions +
+  // lengths can coincide), so the echo path still confirms with deepEqual:
+  // AC3 — same metadata, different content is still detected as a change.
+  function snapshotSignal(snap) {
+    if (!snap) return "0|0|0|0";
+    const t = snap.tickets || [], r = snap.releases || [], p = snap.processSteps || [];
+    let v = (snap.project && (snap.project.version | 0)) || 0;
+    for (let i = 0; i < t.length; i++) v += (t[i].version | 0);
+    for (let i = 0; i < r.length; i++) v += (r[i].version | 0);
+    for (let i = 0; i < p.length; i++) v += (p[i].version | 0);
+    return t.length + "|" + r.length + "|" + p.length + "|" + v;
+  }
+
+  function emptySnapshot(projectId) {
+    return core.normalizeSnapshot({
+      project: { id: projectId || "untitled", name: projectId || "Untitled" }
+    });
+  }
+
+  function ProjectStore(initial) {
+    this._snap = core.normalizeSnapshot(initial || emptySnapshot());
+    this._signal = snapshotSignal(this._snap);   // SM-220: cached change-signal
+    this._past = [];
+    this._future = [];
+    this._listeners = new Set();
+  }
+
+  ProjectStore.prototype.get = function () {
+    return this._snap;
+  };
+
+  ProjectStore.prototype.subscribe = function (fn) {
+    this._listeners.add(fn);
+    return () => this._listeners.delete(fn);
+  };
+
+  ProjectStore.prototype._emit = function (reason) {
+    for (const fn of this._listeners) {
+      try { fn(this._snap, reason); } catch (_) { /* ignore listener errors */ }
+    }
+  };
+
+  // SM-240 (normalize-only-at-edges): _commit no longer runs the full
+  // normalizeSnapshot — every caller hands it an already-normalized snapshot.
+  // The OUTER entry points normalize (applySnapshot below, applyRemote,
+  // hydrate, the constructor); the op path doesn't need to: core.ops outputs
+  // are normalize-invariant (pinned per op by tests/test-core-cow.js (c)),
+  // and re-normalizing here would destroy the structural sharing COW just
+  // created (every entity object rebuilt → no reference equality, bloated
+  // undo stack).
+  ProjectStore.prototype._commit = function (next, reason) {
+    this._past.push(this._snap);
+    if (this._past.length > MAX_UNDO) this._past.shift();
+    this._future = [];
+    this._snap = next;
+    this._signal = snapshotSignal(this._snap);   // SM-220: keep signal in lockstep with _snap
+    this._emit(reason || "commit");
+  };
+
+  // ---- The three install paths ------------------------------------------
+
+  ProjectStore.prototype.applySnapshot = function (snap) {
+    this._commit(core.normalizeSnapshot(snap), "applySnapshot");
+  };
+
+  ProjectStore.prototype.applyRemote = function (snap) {
+    const incoming = core.normalizeSnapshot(snap);
+    // SM-220: cheap signal first. A differing signal proves a real change —
+    // commit straight away, skipping the two full JSON.stringify passes. Only
+    // when the signal matches (true echo, or the pathological same-metadata
+    // case) do we pay the authoritative deepEqual. WS-echo no-op is preserved.
+    if (snapshotSignal(incoming) === this._signal && deepEqual(incoming, this._snap)) {
+      return;  // confirmed echo → no-op, no undo entry
+    }
+    this._commit(incoming, "applyRemote");
+  };
+
+  ProjectStore.prototype.hydrate = function (snap) {
+    this._snap = core.normalizeSnapshot(snap || emptySnapshot());
+    this._signal = snapshotSignal(this._snap);   // SM-220
+    this._past = [];
+    this._future = [];
+    this._emit("hydrate");
+  };
+
+  // ---- Undo / Redo ------------------------------------------------------
+
+  ProjectStore.prototype.canUndo = function () { return this._past.length > 0; };
+  ProjectStore.prototype.canRedo = function () { return this._future.length > 0; };
+
+  ProjectStore.prototype.undo = function () {
+    if (this._past.length === 0) return false;
+    this._future.push(this._snap);
+    this._snap = this._past.pop();
+    this._signal = snapshotSignal(this._snap);   // SM-220
+    this._emit("undo");
+    return true;
+  };
+
+  ProjectStore.prototype.redo = function () {
+    if (this._future.length === 0) return false;
+    this._past.push(this._snap);
+    this._snap = this._future.pop();
+    this._signal = snapshotSignal(this._snap);   // SM-220
+    this._emit("redo");
+    return true;
+  };
+
+  // ---- Op wrappers — each commit becomes a single undo entry -----------
+
+  function wrapOp(opName) {
+    return function (...args) {
+      const actor = args[args.length - 1] && typeof args[args.length - 1] === "object" && args[args.length - 1].type
+        ? args.pop()
+        : { type: "human", id: "local", name: "Local" };
+      const next = core.ops[opName](this._snap, ...args, actor);
+      this._commit(next, opName);
+      return this._snap;
+    };
+  }
+
+  for (const opName of Object.keys(core.ops)) {
+    ProjectStore.prototype[opName] = wrapOp(opName);
+  }
+
+  // E18.D: changeStatusGated validiert die Transition (DoR/DoD) VOR dem
+  // Commit. Wirft `{statusCode, kind, missing}` bei Verletzung — Callsite
+  // fängt ab und zeigt `flashStatus(err.kind + ...)`. Bei Erfolg läuft
+  // dieselbe `changeStatus`-Op wie sonst auch (1 Undo-Eintrag).
+  ProjectStore.prototype.changeStatusGated = function (ticketId, newStatus, actor) {
+    const ticket = this._snap.tickets.find(t => t.id === ticketId);
+    if (!ticket) {
+      const e = new Error("ticket not found: " + ticketId);
+      e.statusCode = 404;
+      throw e;
+    }
+    core.validateStatusTransition(ticket, newStatus, this._snap.project);
+    return this.changeStatus(ticketId, newStatus, actor);
+  };
+
+  return { ProjectStore, emptySnapshot, deepEqual, snapshotSignal, STORE_REASONS, SKIP_PERSIST_REASONS };
+}));

package/frontend/js/ticket-editor-boot.js

@@ -0,0 +1,24 @@
+/**
+ * ticket-editor-boot.js — page bootstrap for /editor (ticket-editor.html).
+ *
+ * SM-214: extracted from an inline <script> block — the SM-211 CSP pins
+ * `script-src 'self'`, which forbids inline scripts. Classic script tag,
+ * no UMD needed (browser-only entry point, like main.js).
+ */
+(function () {
+  "use strict";
+  function boot() {
+    var SM = window.STORYMAP;
+    if (!SM || !SM.rendererTicketEditor) {
+      document.getElementById("editor-host").textContent = "editor bootstrap: missing modules";
+      return;
+    }
+    SM.rendererTicketEditor.bootstrap().catch(function (e) {
+      console.error("editor bootstrap failed:", e);
+      var h = document.getElementById("editor-host");
+      if (h) h.textContent = "editor failed to load: " + (e && e.message || e);
+    });
+  }
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot);
+  else boot();
+}());