@kosdev-code/kos-ui-sdk 3.0.14 → 3.0.16

package/index.js

@@ -49,10 +49,6 @@ var KosWsEvents = /* @__PURE__ */ ((KosWsEvents2) => {
   KosWsEvents2["RECEIVED"] = "/ws/log/msg/receive";
   return KosWsEvents2;
 })(KosWsEvents || {});
-var KosMockEvents = /* @__PURE__ */ ((KosMockEvents2) => {
-  KosMockEvents2["MSG_RECEIVE"] = "/mock/msg/receive";
-  return KosMockEvents2;
-})(KosMockEvents || {});
 const EVENT_KOS_MODEL_READY = "/kos/model/ready/";
 log$R.info("Initializing event bus");
 globalThis.kos = globalThis.kos || {};
@@ -7572,6 +7568,1822 @@ const abortableWhen = async (predicate, signal) => {
     pending.cancel();
   }
 };
+const KOS_HTTP_REQUEST_TYPE = "kos.http.request";
+const KOS_HTTP_RESPONSE_TYPE = "kos.http.response";
+const KOS_FUTURE_TYPE = "kos.future";
+const KOS_BROKER_SUBSCRIBE_TYPE = "kos.broker.subscribe";
+const KOS_BROKER_UNSUBSCRIBE_TYPE = "kos.broker.unsubscribe";
+const KOS_MOCKED_HEADER = "kos-mocked";
+const KOS_MOCK_FIXTURE_HEADER = "kos-mock-fixture";
+const KOS_MOCK_TRANSFORMED_HEADER = "kos-mock-transformed";
+const CONTENT_TYPE_HEADER = "content-type";
+const MESSAGE_SEPARATOR = "\n\n";
+const toTransportString = (data) => typeof data === "string" ? data : void 0;
+function peekFrameType(data) {
+  const text = toTransportString(data);
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return processKosMessage(text).headers[HEADER_REQUEST_TYPE];
+  } catch {
+    return void 0;
+  }
+}
+function decodeRequestFrame(data) {
+  const text = toTransportString(data);
+  if (!text) {
+    return void 0;
+  }
+  let headers;
+  let body;
+  try {
+    ({ headers, body } = processKosMessage(text));
+  } catch {
+    return void 0;
+  }
+  if (headers[HEADER_REQUEST_TYPE] !== KOS_HTTP_REQUEST_TYPE) {
+    return void 0;
+  }
+  const method = headers[HEADER_METHOD];
+  const url = headers[HEADER_URL];
+  const requestId = headers[HEADER_REQUEST_ID];
+  if (!method || !url || !requestId) {
+    return void 0;
+  }
+  return {
+    method,
+    url,
+    requestId,
+    tracker: headers[HEADER_WORK_TRACKER],
+    ordered: headers[HEADER_ORDERED] === "true",
+    headers,
+    rawBody: body || void 0
+  };
+}
+function decodeSubscribeTopics(data) {
+  const text = toTransportString(data);
+  if (!text) {
+    return void 0;
+  }
+  let headers;
+  let body;
+  try {
+    ({ headers, body } = processKosMessage(text));
+  } catch {
+    return void 0;
+  }
+  const frameType = headers[HEADER_REQUEST_TYPE];
+  if (frameType !== KOS_BROKER_SUBSCRIBE_TYPE && frameType !== KOS_BROKER_UNSUBSCRIBE_TYPE) {
+    return void 0;
+  }
+  let topics = [];
+  try {
+    const parsed = JSON.parse(body);
+    if (Array.isArray(parsed)) {
+      topics = parsed.filter(
+        (topic) => typeof topic === "string"
+      );
+    }
+  } catch {
+  }
+  return {
+    type: frameType === KOS_BROKER_SUBSCRIBE_TYPE ? "subscribe" : "unsubscribe",
+    topics
+  };
+}
+const assertHeaderSafe = (name, value) => {
+  if (value.includes("\n")) {
+    throw new Error(`KosMock frame ${name} must not contain newlines`);
+  }
+};
+const encodeFrame$1 = (headers, body) => {
+  const lines = headers.map(([name, value]) => {
+    assertHeaderSafe(name, value);
+    return `${name}:${value}`;
+  });
+  return `${lines.join("\n")}${MESSAGE_SEPARATOR}${body}`;
+};
+function encodeRawFrame(headers, body) {
+  return encodeFrame$1(Object.entries(headers), body);
+}
+function encodeHttpResponseFrame({
+  requestId,
+  status = 200,
+  data,
+  headers = {},
+  raw
+}) {
+  const body = raw ?? JSON.stringify({ status, data: data ?? {} });
+  return encodeFrame$1(
+    [
+      [HEADER_RESPONSE_ID, requestId],
+      [STATUS, `${status}`],
+      [CONTENT_TYPE_HEADER, "application/json"],
+      ...Object.entries(headers),
+      [HEADER_REQUEST_TYPE, KOS_HTTP_RESPONSE_TYPE]
+    ],
+    body
+  );
+}
+function encodeTopicFrame(topic, body, headers = {}) {
+  return encodeFrame$1(
+    [[HEADER_TOPIC, topic], ...Object.entries(headers)],
+    typeof body === "string" ? body : JSON.stringify(body ?? {})
+  );
+}
+function encodeFutureFrame(future) {
+  return encodeFrame$1(
+    [[HEADER_REQUEST_TYPE, KOS_FUTURE_TYPE]],
+    JSON.stringify(future)
+  );
+}
+const DEFAULT_DURATION_MS = 5e3;
+const DEFAULT_INTERVAL_MS = 250;
+class KosMockFutureHandle {
+  constructor(options, emitFrame) {
+    this.emitFrame = emitFrame;
+    this.id = options.id ?? uuid();
+    this.tracker = options.tracker;
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.targetEndState = options.endState ?? "SUCCESS";
+    this.targetReason = options.reason;
+    this.clientData = options.clientData;
+    this.remainingTimeMs = this.durationMs;
+  }
+  emitFrame;
+  id;
+  tracker;
+  progress = 0;
+  done = false;
+  remainingTimeMs;
+  elapsedMs = 0;
+  endStateValue;
+  reasonValue;
+  timer;
+  started = false;
+  durationMs;
+  intervalMs;
+  targetEndState;
+  targetReason;
+  clientData;
+  snapshot() {
+    return {
+      id: this.id,
+      tracker: this.tracker,
+      progress: this.progress,
+      remainingTimeMs: this.remainingTimeMs,
+      endState: this.endStateValue,
+      reason: this.reasonValue,
+      clientData: this.clientData
+    };
+  }
+  start() {
+    if (this.started || this.done) {
+      return;
+    }
+    this.started = true;
+    this.timer = setInterval(() => this.tick(), this.intervalMs);
+  }
+  tick() {
+    this.elapsedMs += this.intervalMs;
+    if (this.elapsedMs >= this.durationMs) {
+      this.complete(this.targetEndState, this.targetReason);
+    } else {
+      this.emitProgress(
+        this.elapsedMs / this.durationMs,
+        this.durationMs - this.elapsedMs
+      );
+    }
+  }
+  emitProgress(progress, remainingTimeMs) {
+    if (this.done) {
+      return;
+    }
+    this.progress = progress;
+    if (remainingTimeMs !== void 0) {
+      this.remainingTimeMs = remainingTimeMs;
+    }
+    this.emitFrame(encodeFutureFrame(this.snapshot()));
+  }
+  complete(endState = "SUCCESS", reason) {
+    if (this.done) {
+      return;
+    }
+    this.stopTimer();
+    this.done = true;
+    this.endStateValue = endState;
+    this.reasonValue = reason;
+    this.remainingTimeMs = 0;
+    if (endState === "SUCCESS") {
+      this.progress = 1;
+    }
+    this.emitFrame(encodeFutureFrame(this.snapshot()));
+  }
+  cancel() {
+    this.complete("CANCEL", this.reasonValue ?? "canceled by mock");
+  }
+  dispose() {
+    this.stopTimer();
+    this.done = true;
+  }
+  stopTimer() {
+    if (this.timer !== void 0) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+  }
+}
+class KosMockFutureSimulator {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  futures = /* @__PURE__ */ new Map();
+  create(options = {}) {
+    const handle = new KosMockFutureHandle(options, this.deps.emitFrame);
+    this.futures.set(handle.id, handle);
+    if (options.registerCancelRoute !== false) {
+      this.deps.ensureCancelRoutes();
+    }
+    if (!options.tracker) {
+      KosLog.warn(
+        `KosMock future ${handle.id} has no tracker — models will not link it to their request; prefer futures.fromRequest`
+      );
+    }
+    if (options.autoStart !== false) {
+      handle.start();
+    }
+    return handle;
+  }
+  fromRequest(req, options = {}) {
+    return this.create({ tracker: req.tracker, ...options });
+  }
+  get(idOrTracker) {
+    const byId = this.futures.get(idOrTracker);
+    if (byId) {
+      return byId;
+    }
+    for (const handle of this.futures.values()) {
+      if (handle.tracker === idOrTracker) {
+        return handle;
+      }
+    }
+    return void 0;
+  }
+  get active() {
+    return [...this.futures.values()].filter((handle) => !handle.done);
+  }
+  clear() {
+    this.futures.forEach((handle) => handle.dispose());
+    this.futures.clear();
+  }
+}
+const DEFAULT_FIXTURE_SERVER_URL = "http://localhost:5676";
+const DB_NAME = "kos-mock-fixtures";
+const STORE_NAME = "fixtures";
+const summarize = (name, fixture) => {
+  return {
+    name,
+    capturedAt: fixture.capturedAt,
+    exchanges: fixture.exchanges.length,
+    pushes: fixture.pushes.length
+  };
+};
+const openDb = () => new Promise((resolve, reject) => {
+  const request2 = indexedDB.open(DB_NAME, 1);
+  request2.onupgradeneeded = () => {
+    if (!request2.result.objectStoreNames.contains(STORE_NAME)) {
+      request2.result.createObjectStore(STORE_NAME);
+    }
+  };
+  request2.onsuccess = () => resolve(request2.result);
+  request2.onerror = () => reject(request2.error);
+});
+const withStore = async (mode, operation) => {
+  const db = await openDb();
+  try {
+    return await new Promise((resolve, reject) => {
+      const request2 = operation(
+        db.transaction(STORE_NAME, mode).objectStore(STORE_NAME)
+      );
+      request2.onsuccess = () => resolve(request2.result);
+      request2.onerror = () => reject(request2.error);
+    });
+  } finally {
+    db.close();
+  }
+};
+class BrowserFixtureBackend {
+  get available() {
+    return typeof indexedDB !== "undefined";
+  }
+  async save(name, fixture) {
+    if (!this.available) {
+      throw new Error("IndexedDB is not available in this environment");
+    }
+    await withStore("readwrite", (store) => store.put(fixture, name));
+  }
+  async load(name) {
+    if (!this.available) {
+      return void 0;
+    }
+    return withStore(
+      "readonly",
+      (store) => store.get(name)
+    );
+  }
+  async list() {
+    if (!this.available) {
+      return [];
+    }
+    const [keys, values] = await Promise.all([
+      withStore("readonly", (store) => store.getAllKeys()),
+      withStore("readonly", (store) => store.getAll())
+    ]);
+    return keys.map((key, index2) => summarize(String(key), values[index2]));
+  }
+  async delete(name) {
+    if (!this.available) {
+      return false;
+    }
+    const existing = await this.load(name);
+    if (!existing) {
+      return false;
+    }
+    await withStore("readwrite", (store) => store.delete(name));
+    return true;
+  }
+}
+class ServerFixtureBackend {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+  baseUrl;
+  url(name) {
+    const base = this.baseUrl.replace(/\/$/, "");
+    return name ? `${base}/fixtures/${encodeURIComponent(name)}` : `${base}/fixtures`;
+  }
+  async save(name, fixture) {
+    const response = await fetch(this.url(name), {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(fixture)
+    });
+    if (!response.ok) {
+      throw new Error(`Fixture server rejected save: ${response.status}`);
+    }
+  }
+  async load(name) {
+    const response = await fetch(this.url(name));
+    if (!response.ok) {
+      return void 0;
+    }
+    return await response.json();
+  }
+  async list() {
+    const response = await fetch(this.url());
+    if (!response.ok) {
+      return [];
+    }
+    const payload = await response.json();
+    return payload.fixtures ?? [];
+  }
+  async delete(name) {
+    const response = await fetch(this.url(name), { method: "DELETE" });
+    return response.ok;
+  }
+}
+function createFixtureStore(registry, deps = {}) {
+  const browser = deps.browserBackend ?? new BrowserFixtureBackend();
+  const serverFactory = deps.serverBackendFactory ?? ((url) => new ServerFixtureBackend(url));
+  let server;
+  let serverUrl;
+  const resolveName = (fixture, name) => {
+    const resolved = name ?? fixture.name;
+    if (!resolved) {
+      throw new Error(
+        "Fixture has no name — pass one: fixtures.save(fixture, {name})"
+      );
+    }
+    return resolved;
+  };
+  const store = {
+    get serverUrl() {
+      return serverUrl;
+    },
+    useServer(url) {
+      if (url === void 0) {
+        server = void 0;
+        serverUrl = void 0;
+        return;
+      }
+      serverUrl = url === true ? DEFAULT_FIXTURE_SERVER_URL : url;
+      server = serverFactory(serverUrl);
+    },
+    async save(fixture, options = {}) {
+      const name = resolveName(fixture, options.name);
+      const named = { ...fixture, name };
+      const target = options.to === "browser" ? browser : options.to === "server" ? server : server ?? browser;
+      if (!target) {
+        throw new Error(
+          "No fixture server configured — useServer() or save to the browser"
+        );
+      }
+      await target.save(name, named);
+      KosLog.info(`KosMock fixture "${name}" saved`);
+      return name;
+    },
+    saveRecording(name) {
+      return store.save(registry.recorder.toFixture(), { name });
+    },
+    async load(name) {
+      if (server) {
+        const fromServer = await server.load(name).catch(() => void 0);
+        if (fromServer) {
+          return fromServer;
+        }
+      }
+      return browser.load(name).catch(() => void 0);
+    },
+    async list() {
+      const summaries = [];
+      if (server) {
+        try {
+          (await server.list()).forEach(
+            (summary) => summaries.push({ ...summary, source: "server" })
+          );
+        } catch {
+          KosLog.warn(`KosMock fixture server unreachable at ${serverUrl}`);
+        }
+      }
+      try {
+        (await browser.list()).forEach(
+          (summary) => summaries.push({ ...summary, source: "browser" })
+        );
+      } catch {
+      }
+      return summaries;
+    },
+    async delete(name) {
+      let deleted = false;
+      if (server) {
+        deleted = await server.delete(name).catch(() => false) || deleted;
+      }
+      deleted = await browser.delete(name).catch(() => false) || deleted;
+      return deleted;
+    },
+    async import() {
+      if (typeof document === "undefined") {
+        KosLog.warn(`KosMock fixture import requires a browser environment`);
+        return void 0;
+      }
+      return new Promise((resolve) => {
+        const input = document.createElement("input");
+        input.type = "file";
+        input.accept = ".json,application/json";
+        input.onchange = async () => {
+          const file = input.files?.[0];
+          if (!file) {
+            resolve(void 0);
+            return;
+          }
+          try {
+            const fixture = JSON.parse(await file.text());
+            const name = await store.save(fixture, {
+              name: fixture.name ?? file.name.replace(/\.json$/, "")
+            });
+            resolve(name);
+          } catch (error) {
+            KosLog.error(`KosMock fixture import failed`, error?.message);
+            resolve(void 0);
+          }
+        };
+        input.click();
+      });
+    },
+    async play(name, options) {
+      const fixture = await store.load(name);
+      if (!fixture) {
+        throw new Error(
+          `No fixture named "${name}" in the store${serverUrl ? ` or at ${serverUrl}` : ""}`
+        );
+      }
+      return registry.loadFixture(fixture, options);
+    }
+  };
+  return store;
+}
+const REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+const escapeLiteral = (segment) => segment.replace(REGEX_SPECIALS, "\\$&");
+const normalizePath = (path) => path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+function compileRoutePattern(pattern) {
+  const paramNames = [];
+  const segments = normalizePath(pattern).split("/");
+  const parts = segments.map((segment, index2) => {
+    if (segment.startsWith(":") && segment.length > 1) {
+      paramNames.push(segment.slice(1));
+      return "([^/]+)";
+    }
+    if (segment === "*") {
+      if (index2 === segments.length - 1) {
+        paramNames.push("*");
+        return "(.*)";
+      }
+      return "[^/]+";
+    }
+    return escapeLiteral(segment);
+  });
+  return {
+    pattern,
+    regex: new RegExp(`^${parts.join("/")}$`),
+    paramNames
+  };
+}
+function matchRoutePattern(compiled, path) {
+  const result = compiled.regex.exec(normalizePath(path));
+  if (!result) {
+    return void 0;
+  }
+  const params2 = {};
+  compiled.paramNames.forEach((name, index2) => {
+    params2[name] = result[index2 + 1];
+  });
+  return params2;
+}
+function splitUrl(url) {
+  const queryIndex = url.indexOf("?");
+  if (queryIndex === -1) {
+    return { path: url, query: {} };
+  }
+  const path = url.slice(0, queryIndex);
+  const query = {};
+  for (const pair of url.slice(queryIndex + 1).split("&")) {
+    if (!pair) {
+      continue;
+    }
+    const [key, value] = pair.split("=");
+    query[decodeURIComponent(key)] = decodeURIComponent(value || "");
+  }
+  return { path, query };
+}
+function methodMatches(routeMethod, requestMethod) {
+  return routeMethod === "*" || routeMethod.toUpperCase() === requestMethod.toUpperCase();
+}
+const rewriteTrackers = (raw, trackerMap) => {
+  let out = raw;
+  trackerMap.forEach((liveTracker, capturedTracker) => {
+    out = out.split(capturedTracker).join(liveTracker);
+  });
+  return out;
+};
+const discriminatorKey = (spec, body) => {
+  try {
+    if (typeof spec === "function") {
+      return String(spec(body));
+    }
+    let current = body;
+    for (const part of spec.split(".")) {
+      if (current === null || typeof current !== "object") {
+        return String(void 0);
+      }
+      current = current[part];
+    }
+    return String(current);
+  } catch {
+    return String(void 0);
+  }
+};
+function installFixturePlayback(registry, fixture, options = {}) {
+  const name = options.name ?? fixture.name;
+  const speed = options.speed ?? 1;
+  const consume = options.consume ?? (registry.standalone ? "repeat-last" : "once");
+  const discriminators = {
+    ...fixture.discriminators,
+    ...options.discriminators
+  };
+  const trackerMap = /* @__PURE__ */ new Map();
+  const timers2 = /* @__PURE__ */ new Set();
+  let stopped = false;
+  const schedule = (delayMs, fire) => {
+    const timer = setTimeout(() => {
+      timers2.delete(timer);
+      fire();
+    }, Math.max(0, delayMs));
+    timers2.add(timer);
+  };
+  const firePush = (push) => {
+    if (push.kind === "topic" && push.topic) {
+      registry.publishFrame(encodeTopicFrame(push.topic, push.body));
+    } else if (push.kind === "future") {
+      registry.publishFrame(
+        `type:${KOS_FUTURE_TYPE}
+
+${rewriteTrackers(push.body, trackerMap)}`
+      );
+    }
+  };
+  const capturedTrackers = new Set(
+    fixture.exchanges.map((exchange) => exchange.tracker).filter((tracker) => !!tracker)
+  );
+  const anchoredByTracker = /* @__PURE__ */ new Map();
+  const unanchored = [];
+  for (const push of fixture.pushes) {
+    if (push.kind === "future" && push.tracker && capturedTrackers.has(push.tracker)) {
+      const list = anchoredByTracker.get(push.tracker) ?? [];
+      list.push(push);
+      anchoredByTracker.set(push.tracker, list);
+    } else {
+      unanchored.push(push);
+    }
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const exchange of fixture.exchanges) {
+    const { path } = splitUrl(exchange.url);
+    const key = `${exchange.method.toUpperCase()} ${path}`;
+    const group = groups.get(key) ?? {
+      method: exchange.method.toUpperCase(),
+      path,
+      queue: []
+    };
+    group.queue.push(exchange);
+    groups.set(key, group);
+  }
+  const anchorsScheduled = /* @__PURE__ */ new Set();
+  const routeHandles = [];
+  groups.forEach((group, groupKey) => {
+    const spec = discriminators[groupKey];
+    const wholeGroup = { queue: group.queue, served: 0 };
+    let buckets;
+    if (spec !== void 0) {
+      buckets = /* @__PURE__ */ new Map();
+      for (const exchange of group.queue) {
+        let parsedBody;
+        try {
+          parsedBody = exchange.requestBody ? JSON.parse(exchange.requestBody) : void 0;
+        } catch {
+          parsedBody = void 0;
+        }
+        const key = discriminatorKey(spec, parsedBody);
+        const bucket = buckets.get(key) ?? { queue: [], served: 0 };
+        bucket.queue.push(exchange);
+        buckets.set(key, bucket);
+      }
+    }
+    routeHandles.push(
+      registry.route(
+        group.method,
+        group.path,
+        (req) => {
+          if (stopped) {
+            return void 0;
+          }
+          let serveQueue;
+          if (buckets && spec !== void 0) {
+            serveQueue = buckets.get(discriminatorKey(spec, req.json()));
+            if (!serveQueue) {
+              return void 0;
+            }
+          } else {
+            serveQueue = wholeGroup;
+          }
+          if (serveQueue.served >= serveQueue.queue.length) {
+            if (consume === "once") {
+              return void 0;
+            }
+            serveQueue.served = serveQueue.queue.length - 1;
+          }
+          const exchange = serveQueue.queue[serveQueue.served];
+          serveQueue.served += 1;
+          if (exchange.tracker && req.tracker) {
+            trackerMap.set(exchange.tracker, req.tracker);
+          }
+          if (exchange.tracker && !anchorsScheduled.has(exchange.tracker)) {
+            anchorsScheduled.add(exchange.tracker);
+            const anchored = anchoredByTracker.get(exchange.tracker) ?? [];
+            anchored.forEach(
+              (push) => schedule((push.tMs - exchange.tMs) / speed, () => firePush(push))
+            );
+          }
+          return {
+            status: exchange.status,
+            raw: rewriteTrackers(exchange.responseBody, trackerMap),
+            delayMs: options.ignoreLatency ? 0 : (exchange.latencyMs ?? 0) / speed
+          };
+        },
+        {
+          fixture: name,
+          description: `fixture replay: ${group.method} ${group.path} (${group.queue.length} captured${spec !== void 0 ? ", discriminated" : ""})`
+        }
+      )
+    );
+  });
+  let pushesStarted = false;
+  const startPushes = () => {
+    if (pushesStarted) {
+      return;
+    }
+    pushesStarted = true;
+    unanchored.forEach(
+      (push) => schedule(push.tMs / speed, () => firePush(push))
+    );
+  };
+  if ((options.pushes ?? "scheduled") === "scheduled") {
+    startPushes();
+  }
+  KosLog.info(
+    `KosMock fixture${name ? ` "${name}"` : ""} loaded: ${groups.size} routes, ${fixture.pushes.length} pushes (${fixture.pushes.length - unanchored.length} anchored), consume: ${consume}`
+  );
+  return {
+    name,
+    startPushes,
+    stop: () => {
+      stopped = true;
+      routeHandles.forEach((handle) => handle.remove());
+      timers2.forEach((timer) => clearTimeout(timer));
+      timers2.clear();
+    }
+  };
+}
+class KosMockRecorder {
+  recording = false;
+  name;
+  startedAt = 0;
+  capturedAt;
+  pending = /* @__PURE__ */ new Map();
+  exchanges = [];
+  pushes = [];
+  get isRecording() {
+    return this.recording;
+  }
+  start(options = {}) {
+    this.recording = true;
+    this.name = options.name;
+    this.startedAt = Date.now();
+    this.capturedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.pending.clear();
+    this.exchanges = [];
+    this.pushes = [];
+    KosLog.info(
+      `KosMock recorder started${options.name ? ` (${options.name})` : ""}`
+    );
+  }
+  stop() {
+    const fixture = this.toFixture();
+    this.recording = false;
+    KosLog.info(
+      `KosMock recorder stopped: ${fixture.exchanges.length} exchanges, ${fixture.pushes.length} pushes`
+    );
+    return fixture;
+  }
+  toFixture() {
+    return {
+      version: 1,
+      name: this.name,
+      capturedAt: this.capturedAt,
+      exchanges: [...this.exchanges],
+      pushes: [...this.pushes]
+    };
+  }
+  download(filename) {
+    if (typeof document === "undefined") {
+      KosLog.warn(`KosMock recorder download requires a browser environment`);
+      return;
+    }
+    const fixture = this.toFixture();
+    const blob = new Blob([JSON.stringify(fixture, null, 2)], {
+      type: "application/json"
+    });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = filename ?? `${fixture.name ?? "kos-mock-fixture"}.json`;
+    anchor.click();
+    URL.revokeObjectURL(url);
+  }
+  elapsed() {
+    return Date.now() - this.startedAt;
+  }
+  /** Interceptor tap: every outbound frame. Internal. */
+  noteOutbound(data) {
+    if (!this.recording) {
+      return;
+    }
+    const frame = decodeRequestFrame(data);
+    if (!frame) {
+      return;
+    }
+    this.pending.set(frame.requestId, {
+      tMs: this.elapsed(),
+      method: frame.method,
+      url: frame.url,
+      tracker: frame.tracker,
+      requestBody: frame.rawBody
+    });
+  }
+  /** Interceptor tap: every inbound frame (real, mocked, injected). Internal. */
+  noteInbound(frame) {
+    if (!this.recording) {
+      return;
+    }
+    let headers;
+    let body;
+    try {
+      ({ headers, body } = processKosMessage(frame));
+    } catch {
+      return;
+    }
+    const responseId = headers["response-id"];
+    if (responseId) {
+      const request2 = this.pending.get(responseId);
+      if (!request2) {
+        return;
+      }
+      this.pending.delete(responseId);
+      this.exchanges.push({
+        ...request2,
+        status: parseInt(headers["status"] ?? "200", 10) || 200,
+        responseBody: body ?? "",
+        latencyMs: Math.max(0, this.elapsed() - request2.tMs),
+        ...headers[KOS_MOCKED_HEADER] === "true" ? { mocked: true } : {}
+      });
+      return;
+    }
+    const topic = headers["subscription"] || headers["topic"];
+    if (topic) {
+      this.pushes.push({
+        tMs: this.elapsed(),
+        kind: "topic",
+        topic,
+        body: body ?? ""
+      });
+      return;
+    }
+    if (headers["type"] === KOS_FUTURE_TYPE) {
+      let tracker;
+      try {
+        tracker = JSON.parse(body)?.tracker;
+      } catch {
+      }
+      this.pushes.push({
+        tMs: this.elapsed(),
+        kind: "future",
+        tracker,
+        body: body ?? ""
+      });
+    }
+  }
+}
+const dynamicImport = (url) => import(
+  /* @vite-ignore */
+  /* webpackIgnore: true */
+  url
+);
+function createSetupStore(registry, deps = {}) {
+  const loadModule = deps.loadModule ?? dynamicImport;
+  const activeSetups = /* @__PURE__ */ new Map();
+  const serverBase = () => (registry.fixtures.serverUrl ?? DEFAULT_FIXTURE_SERVER_URL).replace(
+    /\/$/,
+    ""
+  );
+  const resolve = (nameOrUrl) => {
+    if (/^https?:\/\//.test(nameOrUrl)) {
+      const stem = nameOrUrl.split("/").pop() ?? nameOrUrl;
+      return { name: stem.replace(/\.mjs$/, ""), url: nameOrUrl };
+    }
+    const name = nameOrUrl.replace(/\.mjs$/, "");
+    return {
+      name,
+      url: `${serverBase()}/setups/${encodeURIComponent(name)}.mjs`
+    };
+  };
+  const runTeardown = (name) => {
+    const entry = activeSetups.get(name);
+    if (!entry) {
+      return false;
+    }
+    activeSetups.delete(name);
+    try {
+      entry.teardown?.();
+    } catch (error) {
+      KosLog.error(`KosMock setup "${name}" teardown threw`, error?.message);
+    }
+    return true;
+  };
+  const store = {
+    async load(nameOrUrl) {
+      const { name, url } = resolve(nameOrUrl);
+      const module = await loadModule(url);
+      const setup = module?.default;
+      if (typeof setup !== "function") {
+        throw new Error(
+          `Setup module ${url} has no default-export function (see KosMockSetupModule)`
+        );
+      }
+      runTeardown(name);
+      const result = await setup(registry);
+      const handle = {
+        name,
+        url,
+        unload: () => {
+          runTeardown(name);
+        }
+      };
+      activeSetups.set(name, {
+        handle,
+        teardown: typeof result === "function" ? result : void 0
+      });
+      KosLog.info(`KosMock setup "${name}" installed from ${url}`);
+      return handle;
+    },
+    async list() {
+      const response = await fetch(`${serverBase()}/setups`);
+      if (!response.ok) {
+        return [];
+      }
+      const payload = await response.json();
+      return payload.setups ?? [];
+    },
+    active() {
+      return [...activeSetups.values()].map((entry) => entry.handle);
+    },
+    unload(name) {
+      return runTeardown(name);
+    },
+    clear() {
+      [...activeSetups.keys()].forEach((name) => runTeardown(name));
+    }
+  };
+  return store;
+}
+const asWireValue = (value) => typeof value === "string" ? value : JSON.stringify(value);
+const configTopic = (beanId) => `/kos/config/${beanId}`;
+const changeEnvelope = (props, previousValues = {}) => {
+  return {
+    changes: Object.entries(props).map(([attr, value]) => {
+      return {
+        attr,
+        currentValue: asWireValue(value),
+        previousValue: previousValues[attr] === void 0 ? "" : asWireValue(previousValues[attr])
+      };
+    }),
+    scopedChanges: [],
+    errors: []
+  };
+};
+function createConfigFacade(registry) {
+  const update = (beanId, props, options = {}) => {
+    registry.publishTopic(
+      configTopic(beanId),
+      changeEnvelope(props, options.previousValues)
+    );
+  };
+  const inject = (beanId, injection) => {
+    const current = { ...injection.props };
+    const schema = injection.schema ?? {};
+    const transformerHandle = registry.transformResponse(
+      "GET",
+      `/api/kos/config/details/${beanId}/:depth`,
+      (body) => {
+        if (!body || typeof body !== "object") {
+          return void 0;
+        }
+        const details = Array.isArray(body.data?.details) ? body.data.details : void 0;
+        if (!details) {
+          return void 0;
+        }
+        const detail = details[0] ?? {};
+        details[0] = {
+          ...detail,
+          bean: { ...detail.bean, ...current },
+          schema: {
+            paths: [
+              ...detail.schema?.paths ?? [],
+              ...Object.keys(schema).filter(
+                (key) => !(detail.schema?.paths ?? []).includes(key)
+              )
+            ],
+            schema: { ...detail.schema?.schema, ...schema }
+          }
+        };
+        return body;
+      },
+      { description: `config.inject ${beanId}` }
+    );
+    const routeHandle = registry.post(
+      `/api/kos/config/${beanId}`,
+      (req) => {
+        const requested = req.json();
+        if (!requested) {
+          return void 0;
+        }
+        const keys = Object.keys(requested);
+        const injectedKeys = keys.filter((key) => key in current);
+        if (injectedKeys.length === 0) {
+          return void 0;
+        }
+        if (injectedKeys.length < keys.length) {
+          KosLog.warn(
+            `KosMock config.inject ${beanId}: mixed write passes through; injected props will be rejected by the backend: ${injectedKeys.join(
+              ", "
+            )}`
+          );
+          return void 0;
+        }
+        const previousValues = { ...current };
+        Object.assign(current, requested);
+        update(beanId, requested, { previousValues });
+        return { data: {} };
+      },
+      { description: `config.inject ${beanId} writes` }
+    );
+    const handle = {
+      id: routeHandle.id,
+      set: (props) => {
+        const previousValues = { ...current };
+        Object.assign(current, props);
+        update(beanId, props, { previousValues });
+      },
+      remove: () => {
+        transformerHandle.remove();
+        routeHandle.remove();
+      },
+      enable: () => void 0,
+      disable: () => {
+        transformerHandle.remove();
+        routeHandle.remove();
+      }
+    };
+    return handle;
+  };
+  return { update, inject };
+}
+const PENDING_REQUEST_CAP = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const asHandler = (handler) => typeof handler === "function" ? handler : () => handler;
+class KosMockRegistry {
+  routes = [];
+  settings = {};
+  enabledFlag = false;
+  injectors = /* @__PURE__ */ new Set();
+  subscribedTopicSet = /* @__PURE__ */ new Set();
+  emitters = /* @__PURE__ */ new Map();
+  scenarioTeardowns = /* @__PURE__ */ new Map();
+  cancelRoutesRegistered = false;
+  state = /* @__PURE__ */ new Map();
+  futures = new KosMockFutureSimulator({
+    emitFrame: (frame) => this.publishFrame(frame),
+    ensureCancelRoutes: () => this.ensureFutureCancelRoutes()
+  });
+  recorder = new KosMockRecorder();
+  config = createConfigFacade(this);
+  fixtures = createFixtureStore(this);
+  setups = createSetupStore(this);
+  /**
+   * Internal: when set (a boot fixture is loading), the standalone socket
+   * delays its open until this settles, so replayed routes exist before the
+   * app's boot requests fire. Always resolves (errors are logged upstream).
+   */
+  bootGate;
+  observers = /* @__PURE__ */ new Set();
+  transformers = [];
+  pendingRequests = /* @__PURE__ */ new Map();
+  transformResponse(method, pattern, transform, options = {}) {
+    const registered = {
+      id: options.id ?? uuid(),
+      method,
+      pattern,
+      compiled: compileRoutePattern(pattern),
+      transform,
+      description: options.description
+    };
+    this.transformers.push(registered);
+    const remove = () => {
+      this.transformers = this.transformers.filter(
+        (candidate) => candidate.id !== registered.id
+      );
+    };
+    return {
+      id: registered.id,
+      remove,
+      enable: () => void 0,
+      disable: remove
+    };
+  }
+  /**
+   * Interceptor seam: patches a matching inbound response frame through the
+   * transformer chain before it reaches the app. Returns the (possibly
+   * modified) frame. Internal.
+   */
+  transformInboundFrame(frame) {
+    if (this.transformers.length === 0) {
+      return frame;
+    }
+    let headers;
+    let body;
+    try {
+      ({ headers, body } = processKosMessage(frame));
+    } catch {
+      return frame;
+    }
+    const responseId = headers["response-id"];
+    if (!responseId) {
+      return frame;
+    }
+    const request2 = this.pendingRequests.get(responseId);
+    this.pendingRequests.delete(responseId);
+    if (!request2) {
+      return frame;
+    }
+    const matching = this.transformers.filter(
+      (transformer) => methodMatches(transformer.method, request2.method) && matchRoutePattern(transformer.compiled, request2.path) !== void 0
+    );
+    if (matching.length === 0) {
+      return frame;
+    }
+    let parsed;
+    try {
+      parsed = body ? JSON.parse(body) : void 0;
+    } catch {
+      return frame;
+    }
+    const info = {
+      request: request2,
+      headers,
+      status: parseInt(headers["status"] ?? "200", 10) || 200,
+      mocked: headers[KOS_MOCKED_HEADER] === "true"
+    };
+    let current = parsed;
+    let changed = false;
+    for (const transformer of matching) {
+      try {
+        const result = transformer.transform(current, info);
+        if (result !== void 0) {
+          current = result;
+          changed = true;
+        }
+      } catch (error) {
+        KosLog.error(
+          `KosMock transformer for ${transformer.method} ${transformer.pattern} threw`,
+          error?.message
+        );
+      }
+    }
+    if (!changed) {
+      return frame;
+    }
+    return encodeRawFrame(
+      { ...headers, [KOS_MOCK_TRANSFORMED_HEADER]: "true" },
+      JSON.stringify(current)
+    );
+  }
+  playbacks = /* @__PURE__ */ new Set();
+  observe(observer3) {
+    this.observers.add(observer3);
+    return () => this.observers.delete(observer3);
+  }
+  /**
+   * Transport-integration tap: every outbound frame passes through here
+   * (recorder + observers), independent of the enabled flag. Internal.
+   */
+  noteOutboundFrame(data) {
+    this.recorder.noteOutbound(data);
+    const hasRequestObservers = [...this.observers].some(
+      (observer3) => observer3.onRequest
+    );
+    if (!hasRequestObservers && this.transformers.length === 0) {
+      return;
+    }
+    const frame = decodeRequestFrame(data);
+    if (!frame) {
+      return;
+    }
+    const { path, query } = splitUrl(frame.url);
+    const observation = {
+      method: frame.method,
+      url: frame.url,
+      path,
+      query,
+      requestId: frame.requestId,
+      tracker: frame.tracker,
+      rawBody: frame.rawBody
+    };
+    if (this.transformers.length > 0) {
+      if (this.pendingRequests.size >= PENDING_REQUEST_CAP) {
+        const oldest = this.pendingRequests.keys().next().value;
+        if (oldest !== void 0) {
+          this.pendingRequests.delete(oldest);
+        }
+      }
+      this.pendingRequests.set(frame.requestId, observation);
+    }
+    if (hasRequestObservers) {
+      this.observers.forEach(
+        (observer3) => this.notifyObserver(() => observer3.onRequest?.(observation))
+      );
+    }
+  }
+  /**
+   * Transport-integration tap: every inbound frame (real, mocked, injected)
+   * passes through here. Internal.
+   */
+  noteInboundFrame(frame) {
+    this.recorder.noteInbound(frame);
+    if (this.observers.size === 0) {
+      return;
+    }
+    let headers;
+    let body;
+    try {
+      ({ headers, body } = processKosMessage(frame));
+    } catch {
+      return;
+    }
+    const responseId = headers["response-id"];
+    if (responseId) {
+      const observation = {
+        requestId: responseId,
+        status: parseInt(headers["status"] ?? "200", 10) || 200,
+        mocked: headers[KOS_MOCKED_HEADER] === "true",
+        fixture: headers[KOS_MOCK_FIXTURE_HEADER],
+        body: body ?? "",
+        headers
+      };
+      this.observers.forEach(
+        (observer3) => this.notifyObserver(() => observer3.onResponse?.(observation))
+      );
+      return;
+    }
+    const topic = headers["subscription"] || headers["topic"];
+    if (topic) {
+      const observation = { topic, body: body ?? "", headers };
+      this.observers.forEach(
+        (observer3) => this.notifyObserver(() => observer3.onTopic?.(observation))
+      );
+      return;
+    }
+    if (headers["type"] === KOS_FUTURE_TYPE) {
+      let future;
+      try {
+        future = JSON.parse(body);
+      } catch {
+        return;
+      }
+      this.observers.forEach(
+        (observer3) => this.notifyObserver(() => observer3.onFuture?.(future))
+      );
+    }
+  }
+  /** An observer throwing must never disturb transport flow. */
+  notifyObserver(notify) {
+    try {
+      notify();
+    } catch (error) {
+      KosLog.error(`KosMock observer threw`, error?.message);
+    }
+  }
+  loadFixture(fixture, options) {
+    const inner = installFixturePlayback(this, fixture, options);
+    const handle = {
+      name: inner.name,
+      startPushes: inner.startPushes,
+      stop: () => {
+        this.playbacks.delete(handle);
+        inner.stop();
+      }
+    };
+    this.playbacks.add(handle);
+    return handle;
+  }
+  // -- activation ------------------------------------------------------------
+  get enabled() {
+    return this.enabledFlag;
+  }
+  enable() {
+    if (!this.enabledFlag) {
+      this.enabledFlag = true;
+      KosLog.info(`KosMock enabled`);
+    }
+  }
+  disable() {
+    if (this.enabledFlag) {
+      this.enabledFlag = false;
+      KosLog.info(`KosMock disabled`);
+    }
+  }
+  get standalone() {
+    return !!this.settings.standalone;
+  }
+  /** Internal: whether the standalone socket self-authorizes on open. */
+  get authorizeOnOpen() {
+    return this.settings.authorize !== false;
+  }
+  configure(config2) {
+    this.settings = { ...this.settings, ...config2 };
+    if (config2.standalone) {
+      this.enable();
+    }
+  }
+  // -- routes ----------------------------------------------------------------
+  route(method, pattern, handler, options = {}) {
+    const registered = {
+      id: options.id ?? uuid(),
+      method,
+      pattern,
+      compiled: compileRoutePattern(pattern),
+      handler: asHandler(handler),
+      description: options.description,
+      once: !!options.once,
+      enabled: options.enabled !== false,
+      delayMs: options.delayMs,
+      fixture: options.fixture,
+      when: options.when,
+      hitCount: 0
+    };
+    this.routes.push(registered);
+    this.enable();
+    return {
+      id: registered.id,
+      remove: () => this.removeRoute(registered.id),
+      enable: () => this.setRouteEnabled(registered.id, true),
+      disable: () => this.setRouteEnabled(registered.id, false)
+    };
+  }
+  get(pattern, handler, options) {
+    return this.route("GET", pattern, handler, options);
+  }
+  post(pattern, handler, options) {
+    return this.route("POST", pattern, handler, options);
+  }
+  put(pattern, handler, options) {
+    return this.route("PUT", pattern, handler, options);
+  }
+  del(pattern, handler, options) {
+    return this.route("DELETE", pattern, handler, options);
+  }
+  removeRoute(id) {
+    this.routes = this.routes.filter((route) => route.id !== id);
+  }
+  setRouteEnabled(id, enabled) {
+    const route = this.routes.find((candidate) => candidate.id === id);
+    if (route) {
+      route.enabled = enabled;
+    }
+  }
+  // -- inbound injection -----------------------------------------------------
+  /**
+   * Transport integrations register how inbound frames reach the receive
+   * path. Internal — not part of IKosMockControl.
+   */
+  registerInjector(inject) {
+    this.injectors.add(inject);
+    return () => this.injectors.delete(inject);
+  }
+  publishTopic(topic, body, headers) {
+    this.publishFrame(encodeTopicFrame(topic, body, headers));
+  }
+  publishFrame(rawFrame) {
+    if (this.injectors.size === 0) {
+      KosLog.warn(
+        `KosMock.publishFrame: no active transport to deliver the frame`
+      );
+      return;
+    }
+    this.injectors.forEach((inject) => inject(rawFrame));
+  }
+  topicEmitter(topic, options) {
+    const id = uuid();
+    let tick = 0;
+    const start = () => {
+      const timer = setInterval(() => {
+        this.publishTopic(topic, options.body(tick));
+        tick += 1;
+      }, options.intervalMs);
+      this.emitters.set(id, timer);
+    };
+    const stop = () => {
+      const timer = this.emitters.get(id);
+      if (timer !== void 0) {
+        clearInterval(timer);
+        this.emitters.delete(id);
+      }
+    };
+    start();
+    return {
+      id,
+      remove: stop,
+      enable: () => {
+        if (!this.emitters.has(id)) {
+          start();
+        }
+      },
+      disable: stop
+    };
+  }
+  // -- scenarios ---------------------------------------------------------------
+  scenario(scenario) {
+    const id = `scenario:${scenario.name}:${uuid()}`;
+    const teardown = scenario.setup(this);
+    if (teardown) {
+      this.scenarioTeardowns.set(id, teardown);
+    }
+    KosLog.info(`KosMock scenario "${scenario.name}" installed`);
+    const remove = () => {
+      const dispose = this.scenarioTeardowns.get(id);
+      this.scenarioTeardowns.delete(id);
+      dispose?.();
+    };
+    return { id, remove, enable: () => void 0, disable: remove };
+  }
+  // -- introspection -----------------------------------------------------------
+  list() {
+    return this.routes.map((route) => {
+      return {
+        id: route.id,
+        method: route.method,
+        pattern: route.pattern,
+        description: route.description,
+        enabled: route.enabled,
+        hitCount: route.hitCount
+      };
+    });
+  }
+  describe() {
+    return {
+      enabled: this.enabled,
+      standalone: this.standalone,
+      routes: this.list(),
+      transformers: this.transformers.map((transformer) => {
+        return {
+          id: transformer.id,
+          method: transformer.method,
+          pattern: transformer.pattern,
+          description: transformer.description
+        };
+      }),
+      setups: this.setups.active().map((setup) => {
+        return { name: setup.name, url: setup.url };
+      }),
+      activeFutures: this.futures.active.map((future) => future.id),
+      subscribedTopics: this.subscribedTopics
+    };
+  }
+  get subscribedTopics() {
+    return [...this.subscribedTopicSet];
+  }
+  clear() {
+    this.setups.clear();
+    [...this.playbacks].forEach((playback) => playback.stop());
+    this.routes = [];
+    this.transformers = [];
+    this.pendingRequests.clear();
+    this.cancelRoutesRegistered = false;
+    this.emitters.forEach((timer) => clearInterval(timer));
+    this.emitters.clear();
+    this.scenarioTeardowns.forEach((teardown) => teardown());
+    this.scenarioTeardowns.clear();
+    this.futures.clear();
+    this.state.clear();
+    this.subscribedTopicSet.clear();
+  }
+  // -- frame handling (internal seam for transport integrations) --------------
+  /**
+   * Inspects an outbound frame. Returns true when the registry takes
+   * ownership (it will deliver a response or forward asynchronously); false
+   * means the caller sends the frame as usual. Internal — not part of
+   * IKosMockControl.
+   */
+  handleOutboundFrame(data, io) {
+    if (!this.enabledFlag) {
+      return false;
+    }
+    const subscription = decodeSubscribeTopics(data);
+    if (subscription) {
+      subscription.topics.forEach((topic) => {
+        if (subscription.type === "subscribe") {
+          this.subscribedTopicSet.add(topic);
+        } else {
+          this.subscribedTopicSet.delete(topic);
+        }
+      });
+      return false;
+    }
+    const frame = decodeRequestFrame(data);
+    if (!frame) {
+      return false;
+    }
+    const { path, query } = splitUrl(frame.url);
+    const candidates = this.routes.map((route) => {
+      return {
+        route,
+        params: route.enabled && methodMatches(route.method, frame.method) ? matchRoutePattern(route.compiled, path) : void 0
+      };
+    }).filter(
+      (candidate) => candidate.params !== void 0
+    );
+    const policy = this.unmatchedPolicy();
+    if (candidates.length === 0) {
+      if (policy === "respond404") {
+        this.deliverResponse(io, frame.requestId, {
+          status: 404,
+          data: { message: `KosMock: no route for ${frame.method} ${path}` }
+        });
+        return true;
+      }
+      if (policy === "warn") {
+        KosLog.warn(`KosMock: unmatched ${frame.method} ${path}`);
+      }
+      return false;
+    }
+    const request2 = {
+      method: frame.method,
+      url: frame.url,
+      path,
+      query,
+      headers: frame.headers,
+      requestId: frame.requestId,
+      tracker: frame.tracker,
+      ordered: frame.ordered,
+      rawBody: frame.rawBody,
+      json: () => {
+        if (!frame.rawBody) {
+          return void 0;
+        }
+        try {
+          return JSON.parse(frame.rawBody);
+        } catch {
+          return void 0;
+        }
+      }
+    };
+    void this.resolve(request2, candidates, io, policy);
+    return true;
+  }
+  async resolve(request2, candidates, io, policy) {
+    for (const { route, params: params2 } of candidates) {
+      const scopedRequest = { ...request2, params: params2 };
+      if (route.when) {
+        let accepted = false;
+        try {
+          accepted = route.when(scopedRequest);
+        } catch (error) {
+          KosLog.error(
+            `KosMock \`when\` guard for ${route.method} ${route.pattern} threw`,
+            error?.message
+          );
+        }
+        if (!accepted) {
+          continue;
+        }
+      }
+      let response;
+      try {
+        response = await route.handler(scopedRequest, this.context());
+      } catch (error) {
+        KosLog.error(
+          `KosMock handler for ${route.method} ${route.pattern} threw`,
+          error?.message
+        );
+        response = {
+          status: 500,
+          data: { message: `KosMock handler error: ${error?.message}` }
+        };
+      }
+      if (!response) {
+        continue;
+      }
+      const delayMs = response.delayMs ?? route.delayMs ?? this.settings.defaultDelayMs;
+      if (delayMs) {
+        await sleep(delayMs);
+      }
+      route.hitCount += 1;
+      if (route.once) {
+        this.removeRoute(route.id);
+      }
+      this.deliverResponse(io, request2.requestId, response, route);
+      return;
+    }
+    if (policy === "respond404") {
+      this.deliverResponse(io, request2.requestId, {
+        status: 404,
+        data: {
+          message: `KosMock: all routes declined ${request2.method} ${request2.path}`
+        }
+      });
+      return;
+    }
+    if (policy === "warn") {
+      KosLog.warn(
+        `KosMock: all routes declined ${request2.method} ${request2.path}`
+      );
+    }
+    io.forward();
+  }
+  /**
+   * Every mock-origin response is stamped `kos-mocked: true` (plus
+   * `kos-mock-fixture` when the route belongs to a fixture) so mocked traffic
+   * is detectable in devtools and on the fetch response headers.
+   */
+  deliverResponse(io, requestId, response, route) {
+    io.deliver(
+      encodeHttpResponseFrame({
+        requestId,
+        status: response.status,
+        data: response.data,
+        raw: response.raw,
+        headers: {
+          [KOS_MOCKED_HEADER]: "true",
+          ...route?.fixture ? { [KOS_MOCK_FIXTURE_HEADER]: route.fixture } : {},
+          ...response.headers
+        }
+      })
+    );
+  }
+  context() {
+    return {
+      state: this.state,
+      futures: this.futures,
+      publishTopic: (topic, body, headers) => this.publishTopic(topic, body, headers)
+    };
+  }
+  unmatchedPolicy() {
+    return this.settings.onUnmatched ?? (this.standalone ? "respond404" : "passthrough");
+  }
+  /**
+   * Shared cancel routes for simulated futures. They decline unknown ids, so
+   * in hybrid mode cancellation of real futures still reaches the device.
+   */
+  ensureFutureCancelRoutes() {
+    if (this.cancelRoutesRegistered) {
+      return;
+    }
+    this.cancelRoutesRegistered = true;
+    const cancelHandler = (req) => {
+      const future = this.futures.get(req.params.id);
+      if (!future || future.done) {
+        return void 0;
+      }
+      future.cancel();
+      return { data: {} };
+    };
+    this.route("POST", "/api/kos/future/:id/cancel", cancelHandler, {
+      id: "kos-mock-future-cancel",
+      description: "KosMock simulated future cancel"
+    });
+    this.route("DELETE", "/api/kos/future/:id", cancelHandler, {
+      id: "kos-mock-future-delete",
+      description: "KosMock simulated future delete"
+    });
+  }
+}
+const resolveSingleton = () => {
+  if (typeof window !== "undefined") {
+    const existing = window.KosMock;
+    if (existing instanceof KosMockRegistry) {
+      return existing;
+    }
+    const registry = new KosMockRegistry();
+    window.KosMock = registry;
+    return registry;
+  }
+  return new KosMockRegistry();
+};
+const kosMockRegistry = resolveSingleton();
+const KosMock = kosMockRegistry;
+if (typeof window !== "undefined" && window.location?.search) {
+  const params2 = getQueryParams();
+  if (params2["kosMock"] === "standalone") {
+    KosMock.configure({ standalone: true });
+  } else if (params2["kosMock"] === "on") {
+    KosMock.enable();
+  }
+  if (params2["kosRecord"] !== void 0) {
+    KosMock.recorder.start({ name: params2["kosRecord"] || void 0 });
+  }
+  if (params2["kosFixtureServer"] !== void 0) {
+    KosMock.fixtures.useServer(params2["kosFixtureServer"] || true);
+  }
+  const bootLoads = [];
+  if (params2["kosFixture"]) {
+    bootLoads.push(
+      KosMock.fixtures.play(params2["kosFixture"]).then(() => void 0).catch(
+        (error) => KosLog.error(
+          `KosMock: boot fixture "${params2["kosFixture"]}" failed to load`,
+          error?.message
+        )
+      )
+    );
+  }
+  if (params2["kosSetup"]) {
+    for (const name of params2["kosSetup"].split(",").filter(Boolean)) {
+      bootLoads.push(
+        KosMock.setups.load(name).then(() => void 0).catch(
+          (error) => KosLog.error(
+            `KosMock: boot setup "${name}" failed to load`,
+            error?.message
+          )
+        )
+      );
+    }
+  }
+  if (bootLoads.length > 0) {
+    kosMockRegistry.bootGate = Promise.all(bootLoads).then(() => void 0);
+  }
+}
+class MockInterceptorTransport {
+  constructor(inner, registry) {
+    this.inner = inner;
+    this.registry = registry;
+    this.unregisterInjector = registry.registerInjector(
+      (frame) => this.deliver(frame)
+    );
+    inner.onmessage = (ev) => {
+      if (typeof ev.data === "string") {
+        this.deliver(ev.data);
+      } else {
+        this.messageHandler?.(ev);
+      }
+    };
+    inner.onopen = () => {
+      const ev = { currentTarget: this };
+      this.openHandler?.(ev);
+    };
+    inner.onclose = (ev) => {
+      this.unregisterInjector();
+      this.closeHandler?.(ev);
+    };
+    inner.onerror = (ev) => this.errorHandler?.(ev);
+  }
+  inner;
+  registry;
+  messageHandler = null;
+  openHandler = null;
+  closeHandler = null;
+  errorHandler = null;
+  unregisterInjector;
+  /**
+   * Every inbound frame's path to the app: transform → deliver → observe.
+   * Observation runs last so a reacting observer's injections land AFTER the
+   * frame that caused them, as a real backend's consequences would; observers
+   * and the recorder see the transformed frame — what the app saw.
+   */
+  deliver(frame) {
+    const transformed = this.registry.transformInboundFrame(frame);
+    this.messageHandler?.({ data: transformed });
+    this.registry.noteInboundFrame(transformed);
+  }
+  get onmessage() {
+    return this.messageHandler;
+  }
+  set onmessage(handler) {
+    this.messageHandler = handler;
+  }
+  get onopen() {
+    return this.openHandler;
+  }
+  set onopen(handler) {
+    this.openHandler = handler;
+  }
+  get onclose() {
+    return this.closeHandler;
+  }
+  set onclose(handler) {
+    this.closeHandler = handler;
+  }
+  get onerror() {
+    return this.errorHandler;
+  }
+  set onerror(handler) {
+    this.errorHandler = handler;
+  }
+  send(data) {
+    this.registry.noteOutboundFrame(data);
+    const owned = this.registry.handleOutboundFrame(data, {
+      deliver: (frame) => this.deliver(frame),
+      forward: () => this.inner.send(data)
+    });
+    if (!owned) {
+      this.inner.send(data);
+    }
+  }
+  close() {
+    this.unregisterInjector();
+    return this.inner.close();
+  }
+  addEventListener(type, listener, options) {
+    this.inner.addEventListener(type, listener, options);
+  }
+  removeEventListener(type, listener, options) {
+    this.inner.removeEventListener(type, listener, options);
+  }
+  dispatchEvent(event) {
+    return this.inner.dispatchEvent(event);
+  }
+}
+function installMockInterceptor(inner, registry = kosMockRegistry) {
+  return new MockInterceptorTransport(inner, registry);
+}
 class WebSocketBridgeTransport extends WebSocket {
   constructor(address) {
     super(address);
@@ -7586,13 +9398,13 @@ var WebSocketEvents = /* @__PURE__ */ ((WebSocketEvents2) => {
   return WebSocketEvents2;
 })(WebSocketEvents || {});
 function processKosMessage(data) {
-  const MESSAGE_SEPARATOR = `
+  const MESSAGE_SEPARATOR2 = `
 
 `;
   const SEPARATOR = `
 `;
   const HEADER_SEPARATOR = /:(.*)/s;
-  const [headerText, body] = data.split(MESSAGE_SEPARATOR).map((line) => line.trim());
+  const [headerText, body] = data.split(MESSAGE_SEPARATOR2).map((line) => line.trim());
   const headers = headerText.split(SEPARATOR).reduce((acc, curr) => {
     const [header, value] = curr.split(HEADER_SEPARATOR).map((raw) => raw.trim());
     if (header && value) {
@@ -7606,13 +9418,13 @@ function processKosMessage(data) {
   };
 }
 function processKosSnifferMessage(data) {
-  const MESSAGE_SEPARATOR = `
+  const MESSAGE_SEPARATOR2 = `
 
 `;
   const SEPARATOR = `
 `;
   const HEADER_SEPARATOR = /:(.*)/s;
-  const [, headerText, body] = data.split(MESSAGE_SEPARATOR).map((line) => line.trim());
+  const [, headerText, body] = data.split(MESSAGE_SEPARATOR2).map((line) => line.trim());
   const headers = headerText.split(SEPARATOR).reduce((acc, curr) => {
     const [header, value] = curr.split(HEADER_SEPARATOR).map((raw) => raw.trim());
     if (header && value) {
@@ -7651,8 +9463,8 @@ class BaseTransport {
     this.onConnectionEstablished = onConnectionEstablished;
     this.onConnectionLost = onConnectionLost;
     this.alias = alias;
-    this.socket = new Transport2(
-      `${this.protocol}${this.host}:${this.port}/events`
+    this.socket = installMockInterceptor(
+      new Transport2(`${this.protocol}${this.host}:${this.port}/events`)
     );
     this.socket.onmessage = this.onMessage.bind(this);
     this.socket.onopen = this.onOpen.bind(this);
@@ -7660,15 +9472,6 @@ class BaseTransport {
     this.socket.onerror = this.onError.bind(this);
     this.oldSend = this.socket.send;
     this.connectionEstablished = false;
-    subscribe("/mock/msg/receive", (data) => {
-      if (data?.body) {
-        KosLog.wsReceive(data?.body);
-        const msg = {
-          data: data.body
-        };
-        this.socket?.onmessage?.(msg);
-      }
-    });
     makeObservable(this, {
       connectionEstablished: observable
     });
@@ -7793,23 +9596,7 @@ alias:${this.alias}
       const { headers, body } = processKosMessage(String(data));
       publish(KosWsEvents.SEND, { headers, body });
     }
-    if (window.kosTopicIntercept && window.kosEnableMocks) {
-      const { handler, requestId } = window.kosTopicIntercept(data);
-      if (handler) {
-        data = `mocked:true
-${data}`;
-        const msg = handler(requestId);
-        const returnData = {
-          data: `mocked:true
-${msg}`
-        };
-        this.socket?.onmessage?.(returnData);
-      } else {
-        this.oldSend.call(this.socket, data);
-      }
-    } else {
-      this.oldSend.call(this.socket, data);
-    }
+    this.oldSend.call(this.socket, data);
   }
 }
 class BridgeTransport {
@@ -7930,7 +9717,65 @@ class KosTransport extends BaseTransport {
     this.RESPONSE_ID_HEADER = `response-id`;
   }
 }
-window.kosEnableMocks = process.env.KOS_MOCK_WS === "true";
+const LOGGED_IN_FRAME = `topic:/studioServer/auth/LOGGED_IN
+type:kos.broker.topic
+
+{}`;
+class StandaloneMockSocket {
+  onclose = null;
+  onerror = null;
+  onmessage = null;
+  onopen = null;
+  constructor(url) {
+    KosLog.info(`KosMock standalone socket replacing ${url}`);
+    setTimeout(async () => {
+      await kosMockRegistry.bootGate;
+      this.onopen?.({ currentTarget: this });
+      if (kosMockRegistry.authorizeOnOpen) {
+        this.onmessage?.({ data: LOGGED_IN_FRAME });
+      }
+    }, 0);
+  }
+  send(data) {
+    if (peekFrameType(data) === KOS_HTTP_REQUEST_TYPE) {
+      KosLog.warn(
+        `KosMock standalone: unmatched request reached the loopback socket and will hang — add a route or use onUnmatched: "respond404"`,
+        String(data).split("\n", 2).join(" ")
+      );
+    }
+  }
+  close() {
+  }
+  addEventListener() {
+  }
+  removeEventListener() {
+  }
+  dispatchEvent() {
+    return true;
+  }
+}
+class MockMessageTransport extends BaseTransport {
+  RESPONSE_ID_HEADER;
+  constructor({
+    host,
+    port,
+    protocol,
+    alias,
+    onConnectionEstablished,
+    onConnectionLost
+  }) {
+    super({
+      host,
+      port,
+      protocol,
+      alias,
+      onConnectionEstablished,
+      onConnectionLost,
+      Transport: StandaloneMockSocket
+    });
+    this.RESPONSE_ID_HEADER = `response-id`;
+  }
+}
 window.kosLogEvents = process.env.KOS_LOG_WS === "true";
 class TransportFactory {
   static build({
@@ -7947,7 +9792,18 @@ class TransportFactory {
       `kosWindowWebsocketOpen: ${globalThis.kosWindowWebsocketOpen ? `true` : `false`}`
     );
     KosLog.warn(`fos: ${fos ? `true` : `false`}`);
-    if (window.kosMockWs || globalThis.kosWindowWebsocketOpen && !fos) {
+    if (KosMock.standalone && !fos) {
+      KosLog.warn(`Using KosMock standalone transport`);
+      return new MockMessageTransport({
+        host,
+        port,
+        protocol,
+        alias,
+        onConnectionEstablished,
+        onConnectionLost
+      });
+    }
+    if (globalThis.kosWindowWebsocketOpen && !fos) {
       KosLog.warn(`Using bridged message transport`);
       const transport = new BridgeMessageTransport({
         host,
@@ -27058,7 +28914,7 @@ function withProjectReloading(WrappedComponent) {
     return reloading ? /* @__PURE__ */ jsx(LoadingMessage, { message: "Wait a moment while your project reloads..." }) : /* @__PURE__ */ jsx(WrappedComponent, { ...props });
   };
 }
-registerApiLevels({ "kos-ui-sdk": 22 });
+registerApiLevels({ "kos-ui-sdk": 24 });
 export {
   AncestorPathVisitor,
   AuthState,
@@ -27169,7 +29025,7 @@ export {
   KosLogManager,
   index$b as KosLogManagerServices,
   KosLoggerFactory,
-  KosMockEvents,
+  KosMock,
   KosModel,
   KosModelCollectionProvider,
   KosModelContainer,