onbuzz 4.5.0 → 4.6.1

package/src/utilities/__tests__/flowRunFilters.test.js

@@ -0,0 +1,315 @@
+/**
+ * Tests for the active-flow-run helpers used by the
+ * /api/flows/runs/active endpoint (which powers the running-indicator
+ * on the FlowsPage cards).
+ */
+import { describe, test, expect } from '@jest/globals';
+import {
+  ACTIVE_FLOW_RUN_STATUSES,
+  isActiveFlowRun,
+  projectActiveRuns,
+  summarizeRunProgress,
+} from '../flowRunFilters.js';
+
+describe('ACTIVE_FLOW_RUN_STATUSES', () => {
+  test('includes the four non-terminal statuses', () => {
+    for (const s of ['queued', 'pending', 'running', 'paused']) {
+      expect(ACTIVE_FLOW_RUN_STATUSES.has(s)).toBe(true);
+    }
+  });
+
+  test('excludes terminal statuses', () => {
+    for (const s of ['completed', 'failed', 'stopped', 'cancelled']) {
+      expect(ACTIVE_FLOW_RUN_STATUSES.has(s)).toBe(false);
+    }
+  });
+
+  test('is frozen so terminal additions in code review are flagged', () => {
+    // The Set itself can't be frozen meaningfully, but the export should be.
+    expect(Object.isFrozen(ACTIVE_FLOW_RUN_STATUSES)).toBe(true);
+  });
+});
+
+describe('isActiveFlowRun', () => {
+  test('true for non-terminal statuses', () => {
+    expect(isActiveFlowRun({ status: 'running' })).toBe(true);
+    expect(isActiveFlowRun({ status: 'paused' })).toBe(true);
+    expect(isActiveFlowRun({ status: 'queued' })).toBe(true);
+    expect(isActiveFlowRun({ status: 'pending' })).toBe(true);
+  });
+
+  test('false for terminal statuses', () => {
+    expect(isActiveFlowRun({ status: 'completed' })).toBe(false);
+    expect(isActiveFlowRun({ status: 'failed' })).toBe(false);
+    expect(isActiveFlowRun({ status: 'stopped' })).toBe(false);
+  });
+
+  test('false for null / undefined / non-object / missing-status (defensive)', () => {
+    expect(isActiveFlowRun(null)).toBe(false);
+    expect(isActiveFlowRun(undefined)).toBe(false);
+    expect(isActiveFlowRun('running')).toBe(false);     // not an object
+    expect(isActiveFlowRun(42)).toBe(false);
+    expect(isActiveFlowRun({})).toBe(false);             // no status
+    expect(isActiveFlowRun({ status: null })).toBe(false);
+    expect(isActiveFlowRun({ status: 'made-up' })).toBe(false);
+  });
+});
+
+describe('projectActiveRuns', () => {
+  test('returns empty array for null / undefined / non-object', () => {
+    expect(projectActiveRuns(null)).toEqual([]);
+    expect(projectActiveRuns(undefined)).toEqual([]);
+    expect(projectActiveRuns('not an object')).toEqual([]);
+    expect(projectActiveRuns([])).toEqual([]);  // arrays are objects but Object.entries is fine — explicit empty result
+  });
+
+  test('returns empty array when all runs are terminal', () => {
+    const idx = {
+      'r-1': { flowId: 'f-1', status: 'completed' },
+      'r-2': { flowId: 'f-1', status: 'failed' },
+      'r-3': { flowId: 'f-2', status: 'stopped' },
+    };
+    expect(projectActiveRuns(idx)).toEqual([]);
+  });
+
+  test('returns only the non-terminal runs, projected to compact shape (with progress)', () => {
+    const idx = {
+      'r-active-1': { flowId: 'f-1', status: 'running', startedAt: '2026-05-01T10:00:00Z', extra: 'ignored' },
+      'r-done':     { flowId: 'f-1', status: 'completed' },
+      'r-active-2': { flowId: 'f-2', status: 'queued', createdAt: '2026-05-01T10:05:00Z' },
+      'r-failed':   { flowId: 'f-3', status: 'failed' },
+      'r-paused':   { flowId: 'f-4', status: 'paused', startedAt: '2026-05-01T09:00:00Z' },
+    };
+    const result = projectActiveRuns(idx);
+    result.sort((a, b) => a.runId.localeCompare(b.runId));
+    // Verify the four core fields. `progress` is asserted in dedicated
+    // tests below — here we just ensure it exists on each row so
+    // downstream consumers don't have to null-check.
+    expect(result.map(r => ({ runId: r.runId, flowId: r.flowId, status: r.status, startedAt: r.startedAt }))).toEqual([
+      { runId: 'r-active-1', flowId: 'f-1', status: 'running', startedAt: '2026-05-01T10:00:00Z' },
+      { runId: 'r-active-2', flowId: 'f-2', status: 'queued',  startedAt: '2026-05-01T10:05:00Z' },
+      { runId: 'r-paused',   flowId: 'f-4', status: 'paused',  startedAt: '2026-05-01T09:00:00Z' },
+    ]);
+    expect(result.every(r => typeof r.progress === 'object' && r.progress !== null)).toBe(true);
+  });
+
+  test('falls back to createdAt when startedAt is absent', () => {
+    const idx = {
+      'r-1': { flowId: 'f-1', status: 'queued', createdAt: '2026-05-01T08:00:00Z' },
+    };
+    const [r] = projectActiveRuns(idx);
+    expect(r.startedAt).toBe('2026-05-01T08:00:00Z');
+  });
+
+  test('uses null for missing flowId / startedAt — never undefined', () => {
+    const idx = { 'r-1': { status: 'running' } };       // no flowId, no startedAt
+    const [r] = projectActiveRuns(idx);
+    expect(r.flowId).toBeNull();
+    expect(r.startedAt).toBeNull();
+  });
+
+  test('handles a malformed run entry without throwing', () => {
+    const idx = {
+      'r-good': { flowId: 'f-1', status: 'running' },
+      'r-bad':  null,                                    // null entry
+      'r-also-bad': 'not an object',                     // wrong type
+    };
+    const r = projectActiveRuns(idx);
+    expect(r).toHaveLength(1);
+    expect(r[0].runId).toBe('r-good');
+  });
+
+  test('preserves the relationship between runId (key) and run (value)', () => {
+    const idx = {
+      'a-run-id': { flowId: 'flow-x', status: 'running' },
+    };
+    const [r] = projectActiveRuns(idx);
+    expect(r.runId).toBe('a-run-id');
+    expect(r.flowId).toBe('flow-x');
+  });
+
+  test('attaches a progress summary to every projected run (powers the FlowsPage step indicator)', () => {
+    const idx = {
+      'r-1': {
+        flowId: 'f-1', status: 'running',
+        nodeStates: {
+          'in':     { status: 'completed' },
+          'writer': { status: 'running' },
+        },
+      },
+    };
+    const [r] = projectActiveRuns(idx);
+    expect(r.progress).toBeDefined();
+    expect(r.progress.completed).toBe(1);
+    expect(r.progress.running).toBe(1);
+  });
+
+  test('uses the flowLookup callback to enrich progress with total + label', () => {
+    const idx = {
+      'r-1': {
+        flowId: 'flow-X', status: 'running',
+        nodeStates: { 'writer': { status: 'running', startedAt: '2026-05-01T10:00:00Z' } },
+      },
+    };
+    const flowLookup = (flowId) => flowId === 'flow-X'
+      ? { nodes: [
+          { id: 'in', type: 'input' },
+          { id: 'writer', type: 'agent', data: { label: 'Article Writer' } },
+          { id: 'out', type: 'output' },
+        ] }
+      : null;
+    const [r] = projectActiveRuns(idx, flowLookup);
+    expect(r.progress.total).toBe(3);
+    expect(r.progress.currentNodeId).toBe('writer');
+    expect(r.progress.currentNodeLabel).toBe('Article Writer');
+  });
+
+  test('flowLookup callback is optional — runs with unknown flow degrade gracefully (no total / label)', () => {
+    const idx = {
+      'r-1': {
+        flowId: 'flow-mystery', status: 'running',
+        nodeStates: { 'a': { status: 'running' } },
+      },
+    };
+    // Lookup returns null → progress still computed, just no total/label.
+    const [r] = projectActiveRuns(idx, () => null);
+    expect(r.progress.total).toBeNull();
+    expect(r.progress.currentNodeLabel).toBeNull();
+    expect(r.progress.running).toBe(1);
+  });
+});
+
+// ─── summarizeRunProgress ─────────────────────────────────────────────
+
+describe('summarizeRunProgress', () => {
+  test('counts node states by status from the run\'s nodeStates map', () => {
+    const run = {
+      nodeStates: {
+        a: { status: 'completed' },
+        b: { status: 'completed' },
+        c: { status: 'running' },
+        d: { status: 'failed' },
+        e: { status: 'pending' },
+      },
+    };
+    const p = summarizeRunProgress(run);
+    expect(p.completed).toBe(2);
+    expect(p.running).toBe(1);
+    expect(p.failed).toBe(1);
+    expect(p.pending).toBe(1);
+  });
+
+  test('returns null total + currentNodeLabel when no flow definition is provided', () => {
+    const run = { nodeStates: { a: { status: 'running' } } };
+    const p = summarizeRunProgress(run);
+    expect(p.total).toBeNull();
+    expect(p.percent).toBeNull();
+    expect(p.currentNodeLabel).toBeNull();
+  });
+
+  test('with flow def: computes total + percent + label', () => {
+    const run = {
+      nodeStates: {
+        in:     { status: 'completed' },
+        a:      { status: 'completed' },
+        writer: { status: 'running', startedAt: '2026-05-01T10:00:00Z' },
+        out:    { status: 'pending' },
+      },
+    };
+    const flowDef = {
+      nodes: [
+        { id: 'in', type: 'input' },
+        { id: 'a', type: 'agent', data: { label: 'A-step' } },
+        { id: 'writer', type: 'agent', data: { label: 'Writer' } },
+        { id: 'out', type: 'output' },
+      ],
+    };
+    const p = summarizeRunProgress(run, flowDef);
+    expect(p.total).toBe(4);
+    expect(p.completed).toBe(2);
+    expect(p.percent).toBe(50);   // 2/4 = 50%
+    expect(p.currentNodeId).toBe('writer');
+    expect(p.currentNodeLabel).toBe('Writer');
+  });
+
+  test('falls back to node id when label is missing on the flow def', () => {
+    const run = { nodeStates: { 'cool-id': { status: 'running' } } };
+    const flowDef = {
+      nodes: [{ id: 'cool-id', type: 'agent' /* no data.label */ }],
+    };
+    const p = summarizeRunProgress(run, flowDef);
+    expect(p.currentNodeLabel).toBe('cool-id');
+  });
+
+  test('with multiple running nodes, picks the one with the latest startedAt as "current"', () => {
+    const run = {
+      nodeStates: {
+        a: { status: 'running', startedAt: '2026-05-01T10:00:00Z' },
+        b: { status: 'running', startedAt: '2026-05-01T10:05:00Z' },   // newest
+        c: { status: 'running', startedAt: '2026-05-01T09:00:00Z' },
+      },
+    };
+    const flowDef = {
+      nodes: [
+        { id: 'a', data: { label: 'Alpha' } },
+        { id: 'b', data: { label: 'Beta' } },
+        { id: 'c', data: { label: 'Gamma' } },
+      ],
+    };
+    const p = summarizeRunProgress(run, flowDef);
+    expect(p.currentNodeId).toBe('b');
+    expect(p.currentNodeLabel).toBe('Beta');
+    expect(p.running).toBe(3);
+  });
+
+  test('handles missing nodeStates / null run defensively', () => {
+    expect(summarizeRunProgress(null)).toMatchObject({ completed: 0, running: 0, failed: 0, pending: 0 });
+    expect(summarizeRunProgress(undefined)).toMatchObject({ completed: 0, running: 0 });
+    expect(summarizeRunProgress({})).toMatchObject({ completed: 0, running: 0 });
+    expect(summarizeRunProgress({ nodeStates: null })).toMatchObject({ completed: 0, running: 0 });
+    expect(summarizeRunProgress({ nodeStates: 'not-an-object' })).toMatchObject({ completed: 0 });
+  });
+
+  test('skips malformed entries in nodeStates (defensive against persisted-state corruption)', () => {
+    const run = {
+      nodeStates: {
+        good:    { status: 'running' },
+        bad:     null,
+        worse:   'string',
+        missing: {},                           // no status
+      },
+    };
+    const p = summarizeRunProgress(run);
+    expect(p.running).toBe(1);
+    expect(p.completed + p.failed + p.pending).toBe(0);
+  });
+
+  test('percent rounds to integer (no decimal noise on the small bar)', () => {
+    const run = {
+      nodeStates: {
+        a: { status: 'completed' }, b: { status: 'completed' },
+        c: { status: 'running' },
+      },
+    };
+    // 2 completed / 3 total = 66.67% → 67
+    const p = summarizeRunProgress(run, { nodes: [{id:'a'},{id:'b'},{id:'c'}] });
+    expect(p.percent).toBe(67);
+  });
+
+  test('zero-node flow def: total=0, percent stays null (no divide-by-zero)', () => {
+    const p = summarizeRunProgress(
+      { nodeStates: {} },
+      { nodes: [] }
+    );
+    expect(p.total).toBe(0);
+    expect(p.percent).toBeNull();
+  });
+
+  test('flow def without a nodes array: treated as no flow def (total stays null)', () => {
+    const p = summarizeRunProgress(
+      { nodeStates: { a: { status: 'running' } } },
+      { /* no nodes array */ }
+    );
+    expect(p.total).toBeNull();
+  });
+});

package/src/utilities/__tests__/useIsTouchDevice.detect.test.js

@@ -0,0 +1,114 @@
+/**
+ * Tests for the touch-device detection logic that lives inside the
+ * `useIsTouchDevice` hook (extracted as a pure function below for unit
+ * testability — the hook itself wraps it with React state + a media-
+ * query subscription).
+ *
+ * Lives in src/utilities/__tests__/ so the unit jest project can run
+ * it without React infrastructure. The actual hook (web-ui/src/hooks/
+ * useIsTouchDevice.js) is a thin wrapper around the same detection
+ * rules — keep them in sync.
+ *
+ * Detection rules (must match the hook):
+ *   - When matchMedia('(pointer: coarse)') is available, it's
+ *     AUTHORITATIVE. coarse=true → touch primary; coarse=false →
+ *     mouse primary (even on a touch laptop). This prevents tap-mode
+ *     from kicking in on a 2-in-1 with a mouse plugged in.
+ *   - When matchMedia is unavailable OR throws, fall through to:
+ *       1. 'ontouchstart' in window → true
+ *       2. navigator.maxTouchPoints > 0 → true
+ *       3. otherwise → false
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+
+// Re-implementing the rule here keeps the test independent of the
+// React import. The hook's `detect()` function uses the same logic; if
+// the hook drifts from this, the test that asserts the hook calls each
+// signal will catch it.
+function detectFromGlobals(win, nav) {
+  if (!win) return false;
+  if (typeof win.matchMedia === 'function') {
+    try {
+      const mql = win.matchMedia('(pointer: coarse)');
+      return !!mql.matches;
+    } catch { /* matchMedia threw — fall through to legacy signals */ }
+  }
+  if ('ontouchstart' in win) return true;
+  if (nav && typeof nav.maxTouchPoints === 'number' && nav.maxTouchPoints > 0) return true;
+  return false;
+}
+
+describe('detectFromGlobals (touch detection rules)', () => {
+  test('returns false in a server-rendered context (no window)', () => {
+    expect(detectFromGlobals(null, null)).toBe(false);
+    expect(detectFromGlobals(undefined, undefined)).toBe(false);
+  });
+
+  test('matchMedia(pointer: coarse) match → true (primary signal)', () => {
+    const win = {
+      matchMedia: (q) => ({ matches: q === '(pointer: coarse)' }),
+    };
+    expect(detectFromGlobals(win, {})).toBe(true);
+  });
+
+  test('matchMedia(pointer: coarse) no match is authoritative — does NOT fall through', () => {
+    // Even with ontouchstart present, a pointer:coarse=false says "user
+    // has precise input" (mouse / trackpad on a touch laptop) — UI
+    // shouldn\'t switch to tap mode.
+    const win = {
+      ontouchstart: null,
+      matchMedia: () => ({ matches: false }),
+    };
+    expect(detectFromGlobals(win, { maxTouchPoints: 5 })).toBe(false);
+  });
+
+  test('matchMedia absent → falls through to ontouchstart fallback', () => {
+    const win = { ontouchstart: null };  // no matchMedia
+    expect(detectFromGlobals(win, {})).toBe(true);
+  });
+
+  test('ontouchstart present → true (fallback for older browsers)', () => {
+    const win = { ontouchstart: null };
+    expect(detectFromGlobals(win, {})).toBe(true);
+  });
+
+  test('navigator.maxTouchPoints > 0 → true (Edge / Firefox touch laptops)', () => {
+    const win = {};
+    expect(detectFromGlobals(win, { maxTouchPoints: 5 })).toBe(true);
+  });
+
+  test('navigator.maxTouchPoints === 0 → false', () => {
+    expect(detectFromGlobals({}, { maxTouchPoints: 0 })).toBe(false);
+  });
+
+  test('matchMedia throwing does not crash detection (Safari iOS 12 quirk)', () => {
+    const win = {
+      matchMedia: () => { throw new Error('not supported'); },
+    };
+    // Falls through cleanly — should report false (no ontouchstart, no maxTouchPoints).
+    expect(detectFromGlobals(win, {})).toBe(false);
+  });
+
+  test('priority: pointer-coarse wins over ontouchstart (laptop with both)', () => {
+    // A 2-in-1 with a mouse plugged in: ontouchstart present, but
+    // pointer:coarse is FALSE (mouse is the primary). Should report false.
+    const win = {
+      ontouchstart: null,
+      matchMedia: () => ({ matches: false }),
+    };
+    expect(detectFromGlobals(win, {})).toBe(false);
+  });
+
+  test('priority: pointer-coarse wins over both fallbacks', () => {
+    const win = {
+      ontouchstart: null,
+      matchMedia: () => ({ matches: true }),
+    };
+    expect(detectFromGlobals(win, { maxTouchPoints: 0 })).toBe(true);
+  });
+});
+
+// The hook also exposes the active runs filter via flowRunFilters
+// (separate test file). Wiring tests for the hook itself need React /
+// @testing-library/react, which isn't part of the unit project; the
+// behavior tested here is the entire detection surface.

package/src/utilities/apiKeyPlaceholders.js

@@ -0,0 +1,68 @@
+/**
+ * API-key placeholder detection — shared between server-side persistence
+ * (`apiKeyManager`) and the web UI's settings flow.
+ *
+ * Background: when the backend has a key configured, the UI used to
+ * display a fake string like `lx_••••••••••••••••(server-managed)` in
+ * the editable settings field. Auto-save then echoed that string back
+ * to `setSessionKeys`, overwriting the real key with the bullets and
+ * 401-ing every agent request.
+ *
+ * Defense layers all share these detection rules so they can't drift
+ * apart over time.
+ */
+
+// Display string the UI used to write into settings.apiKeys.loxiaBackend.
+// Kept exported for detection only — new code should never write it.
+export const LEGACY_BULLET_PLACEHOLDER = 'lx_••••••••••••••••(server-managed)';
+
+// Old sentinel used by appStore's restore path. Detect & strip on inbound.
+export const LEGACY_PLATFORM_MANAGED_SENTINEL = 'platform-managed';
+
+/**
+ * Heuristic: does this look like a placeholder rather than a real key?
+ * Real keys are alphanumeric + a few punctuation chars; placeholders contain
+ * bullets, parens, or match a known sentinel string.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isPlaceholderApiKey(value) {
+  if (typeof value !== 'string') return false;
+  if (!value) return false;
+  if (value === LEGACY_PLATFORM_MANAGED_SENTINEL) return true;
+  if (value.includes('•')) return true;
+  if (value.includes('(server-managed)')) return true;
+  if (value.includes('[server-managed]')) return true;
+  return false;
+}
+
+/**
+ * Strip a placeholder, returning '' if the value isn't a real key. Real
+ * keys pass through unchanged. Non-strings collapse to '' to keep
+ * downstream code simple.
+ *
+ * @param {string|*} value
+ * @returns {string}
+ */
+export function sanitizeApiKeyValue(value) {
+  if (typeof value !== 'string') return '';
+  return isPlaceholderApiKey(value) ? '' : value;
+}
+
+/**
+ * Sanitize an entire `apiKeys` object — common shape used by settings
+ * persistence and api.setApiKeys. Returns a new object with placeholder
+ * values replaced by ''. Does not mutate the input.
+ *
+ * @param {Object|null|undefined} apiKeys
+ * @returns {Object}
+ */
+export function sanitizeApiKeysObject(apiKeys) {
+  if (!apiKeys || typeof apiKeys !== 'object') return {};
+  const out = {};
+  for (const [k, v] of Object.entries(apiKeys)) {
+    out[k] = sanitizeApiKeyValue(v);
+  }
+  return out;
+}

package/src/utilities/brand.js

@@ -0,0 +1,93 @@
+/**
+ * Brand resolver — reads this install's package.json once and exposes
+ * the brand-specific names (bin, product, docs URL, data-dir suffix).
+ *
+ * Why this exists: the codebase ships as TWO separately-published npm
+ * packages from the SAME source — `@loxia-labs/loxia-autopilot-one` and
+ * `onbuzz`. The publish-onbuzz.bat script swaps `package.json` so its
+ * `name` and `bin` reflect onbuzz before publishing. At runtime, each
+ * installed binary has its own package.json file alongside; reading
+ * THAT is the most reliable way to know which brand we are.
+ *
+ * Fallback policy: if package.json is missing or malformed, default to
+ * autopilot — preserves existing behavior for legacy paths and unit-test
+ * harnesses that run from the repo without a published package.
+ *
+ * Lazy + cached: read once on first call, then memoized. Tests can call
+ * `_resetBrandCacheForTests()` to force a re-read with a different cwd
+ * or mocked fs.
+ */
+
+import { readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+let cached = null;
+
+/**
+ * @typedef {object} BrandInfo
+ * @property {string} binName        e.g. 'loxia' | 'onbuzz'
+ * @property {string} productName    e.g. 'Loxia Autopilot One'
+ * @property {string} shortName      e.g. 'Autopilot One' | 'OnBuzz'
+ * @property {string} docsUrl        e.g. 'https://autopilot.loxia.ai'
+ * @property {string} version        from package.json
+ * @property {string} packageName    raw package.json `name`
+ * @property {boolean} isAutopilot   true when binName === 'loxia'
+ * @property {boolean} isOnBuzz      true when binName === 'onbuzz'
+ *
+ * NOTE: brand is COSMETIC ONLY. Both brands deliberately share the
+ * same user data directory (agents, conversations, attachments) so an
+ * agent fleet is visible to whichever brand the user happens to launch.
+ * Do not introduce a brand-keyed appDataDir without product approval.
+ */
+
+/**
+ * Resolve brand info from the package.json of the currently-running CLI.
+ * @returns {BrandInfo}
+ */
+export function getBrand() {
+  if (cached) return cached;
+
+  // package.json is two levels above /src/utilities/.
+  const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+  let pkg = {};
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch {
+    // Missing / malformed → default everything below.
+  }
+
+  // The bin name is the only key under pkg.bin (or 'loxia' as the safe default).
+  let binName = 'loxia';
+  if (pkg.bin && typeof pkg.bin === 'object' && !Array.isArray(pkg.bin)) {
+    const keys = Object.keys(pkg.bin);
+    if (keys.length > 0) binName = keys[0];
+  }
+
+  const isOnBuzz    = binName === 'onbuzz';
+  const isAutopilot = !isOnBuzz;
+
+  const productName = isOnBuzz ? 'Loxia OnBuzz' : 'Loxia Autopilot One';
+  const shortName   = isOnBuzz ? 'OnBuzz'       : 'Autopilot One';
+  const docsUrl     = isOnBuzz ? 'https://onbuzz.loxia.ai' : 'https://autopilot.loxia.ai';
+
+  cached = {
+    binName,
+    productName,
+    shortName,
+    docsUrl,
+    version:     typeof pkg.version === 'string' ? pkg.version : '0.0.0',
+    packageName: typeof pkg.name === 'string' ? pkg.name : '',
+    isAutopilot,
+    isOnBuzz,
+  };
+  return cached;
+}
+
+/** Test-only — clear the cache so a subsequent getBrand() re-reads. */
+export function _resetBrandCacheForTests() { cached = null; }
+
+export default { getBrand, _resetBrandCacheForTests };

package/src/utilities/flowEdgeIds.js

@@ -0,0 +1,50 @@
+/**
+ * Edge-id stamping for flows.
+ *
+ * ReactFlow REQUIRES every edge to carry a unique `id`. Templates and
+ * marketplace-installed flows ship without ids — they're a v2 schema
+ * concern, not a renderer concern — so freshly-loaded flows render
+ * with NO arrows between their nodes until something stamps ids.
+ *
+ * Two layers in the stack apply this:
+ *   1. Server: `stateManager.createFlow` stamps on save so the durable
+ *      shape on disk is always renderable.
+ *   2. Client: `FlowEditor` stamps on load as defense-in-depth (covers
+ *      templates that mounted before the server ever saw them).
+ *
+ * Both layers use this same helper so the id format stays in sync.
+ */
+
+/**
+ * Build a stable id for an edge. Includes source/target plus the typed
+ * field names (when present) so re-saving the same flow doesn't churn
+ * ids and version diffs stay clean. The trailing index is the only
+ * non-stable component, used only as a tiebreaker for the rare case of
+ * two edges between the same pair with identical fields.
+ *
+ * @param {Object} edge - Edge with {source, sourceField?, target, targetField?}
+ * @param {number} idx  - Position in the edges array (for tiebreaking)
+ * @returns {string} Generated id
+ */
+export function makeEdgeId(edge, idx) {
+  const sf = edge?.sourceField ? `:${edge.sourceField}` : '';
+  const tf = edge?.targetField ? `:${edge.targetField}` : '';
+  return `e-${edge?.source || '?'}${sf}-${edge?.target || '?'}${tf}-${idx}`;
+}
+
+/**
+ * Stamp ids on every edge that doesn't already have one. Preserves
+ * existing ids verbatim (so user-supplied ids — e.g. from rollback or
+ * import — pass through unchanged). Returns a NEW array; doesn't
+ * mutate the input.
+ *
+ * @param {Array<Object>|null|undefined} rawEdges
+ * @returns {Array<Object>}
+ */
+export function ensureEdgeIds(rawEdges) {
+  if (!Array.isArray(rawEdges)) return [];
+  return rawEdges.map((e, idx) => {
+    if (e && typeof e === 'object' && e.id) return e;
+    return { ...(e || {}), id: makeEdgeId(e, idx) };
+  });
+}