@configbutler/krm-stream 0.1.0 → 0.2.0

package/README.md

@@ -21,6 +21,30 @@ connectWithEventSource(
 );
 ```
 
-The unscoped `krm-stream` package is a compatibility forwarder. This project is pre-1.0 and has not
-been published to npm yet. See the repository [README](../../README.md),
+## Vendoring it without a bundler
+
+The default entry point is the per-module build: `dist/index.js` imports `./store.js`, which imports
+`./merge.js`, and so on. A bundler resolves that graph and tree-shakes it, and a browser resolves it
+at runtime, so every file has to be there.
+
+If you have no bundler and no `node_modules` — you copy the library in and serve it yourself — import
+the flattened build instead. Same public API, one file, no relative imports left to resolve:
+
+```ts
+import { LiveResourceStore } from "@configbutler/krm-stream/bundle";
+```
+
+Vendored, that is one file to copy (`dist/krm-stream.js`) and one path to serve:
+
+```js
+import { LiveResourceStore, connectWithEventSource } from "/krm-stream/krm-stream.js";
+```
+
+Both entry points are built from the same source and are exercised by the same browser test suite
+against a real `EventSource`. Neither has a runtime dependency.
+
+## Status
+
+The unscoped `krm-stream` package is a compatibility forwarder. This project is pre-1.0: the protocol
+and the API may still change before 1.0. See the repository [README](../../README.md),
 [client state model](../../docs/client-state-model.md), and [release guide](../../docs/releasing.md).

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { get, has, isPrefix, parsePointer, pathKey } from "./path.ts";
 export { DEFAULT_EDITABLE_REGIONS, defaultPolicy, readOnlyPolicy, regionPolicy } from "./policy.ts";
 export type { KubernetesStructuralSchema } from "./schema.ts";
 export { withOpenAPIKeyedLists } from "./schema.ts";
-export type { StreamHandle, StreamOptions } from "./sse.ts";
+export type { StreamChange, StreamHandle, StreamOptions } from "./sse.ts";
 export { applyStreamEvent, connectResourceStream, connectWithEventSource, SSEDecoder, StreamSequence } from "./sse.ts";
 export type { ApplyOptions, ApplyResult } from "./store.ts";
 export { LiveResourceStore } from "./store.ts";

package/dist/index.js

@@ -1,4 +1,4 @@
-// krm-stream — a live, honest window onto Kubernetes resources, in the browser.
+// krm-stream — live Kubernetes resource updates and three-way merges for browser applications.
 //
 // The public surface is small on purpose:
 //

package/dist/krm-stream.js

@@ -0,0 +1,862 @@
+// dist/deep.js
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function deepEqual(a, b) {
+  if (Object.is(a, b))
+    return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+      return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length)
+      return false;
+    return ka.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+function clone(v) {
+  if (Array.isArray(v))
+    return v.map(clone);
+  if (isPlainObject(v)) {
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+      out[k] = clone(x);
+    return out;
+  }
+  return v;
+}
+
+// dist/path.js
+function pathKey(path) {
+  return JSON.stringify(path);
+}
+function isPrefix(prefix, path) {
+  if (prefix.length > path.length)
+    return false;
+  return prefix.every((seg, i) => String(seg) === String(path[i]));
+}
+function at(value, seg) {
+  if (Array.isArray(value))
+    return value[Number(seg)];
+  if (isPlainObject(value))
+    return value[String(seg)];
+  return void 0;
+}
+function get(value, path) {
+  let cur = value;
+  for (const seg of path)
+    cur = at(cur, seg);
+  return cur;
+}
+function has(value, path) {
+  let cur = value;
+  for (const seg of path) {
+    if (Array.isArray(cur)) {
+      if (Number(seg) >= cur.length)
+        return false;
+    } else if (isPlainObject(cur)) {
+      if (!Object.hasOwn(cur, String(seg)))
+        return false;
+    } else {
+      return false;
+    }
+    cur = at(cur, seg);
+  }
+  return cur !== void 0;
+}
+function setAt(root, path, value) {
+  if (path.length === 0)
+    throw new Error("krm-stream: cannot set the root of an object");
+  let cur = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const seg = path[i];
+    let next = at(cur, seg);
+    if (!isPlainObject(next) && !Array.isArray(next)) {
+      next = typeof path[i + 1] === "number" ? [] : {};
+      assign(cur, seg, next);
+    }
+    cur = next;
+  }
+  assign(cur, path[path.length - 1], value);
+}
+function removeAt(root, path) {
+  if (path.length === 0)
+    throw new Error("krm-stream: cannot remove the root of an object");
+  const parent = get(root, path.slice(0, -1));
+  const last = path[path.length - 1];
+  if (Array.isArray(parent))
+    parent.splice(Number(last), 1);
+  else if (isPlainObject(parent))
+    delete parent[String(last)];
+}
+function assign(container, seg, value) {
+  if (Array.isArray(container))
+    container[Number(seg)] = value;
+  else
+    container[String(seg)] = value;
+}
+function parsePointer(pointer) {
+  if (pointer === "")
+    return [];
+  if (!pointer.startsWith("/"))
+    throw new Error(`krm-stream: not an RFC 6901 pointer: ${JSON.stringify(pointer)}`);
+  return pointer.slice(1).split("/").map((seg) => seg.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+
+// dist/policy.js
+var DEFAULT_EDITABLE_REGIONS = [
+  ["spec"],
+  ["metadata", "labels"],
+  ["metadata", "annotations"],
+  ["data"],
+  ["stringData"]
+];
+function regionPolicy(roots) {
+  return {
+    isEditable: (_obj, path) => roots.some((root) => isPrefix(root, path)),
+    // A path that is not editable itself but that an editable region lives UNDER — `[]` and
+    // `["metadata"]` for the defaults. The merge must recurse through these rather than replacing
+    // them wholesale, or an edit to `metadata.labels` would be clobbered by the read-only handling
+    // of `metadata.name` sitting beside it.
+    containsEditable: (_obj, path) => roots.some((root) => root.length > path.length && isPrefix(path, root))
+  };
+}
+var defaultPolicy = regionPolicy(DEFAULT_EDITABLE_REGIONS);
+var readOnlyPolicy = regionPolicy([]);
+
+// dist/schema.js
+function withOpenAPIKeyedLists(policy, schema) {
+  return {
+    ...policy,
+    listMapKeys: (object, path) => policy.listMapKeys?.(object, path) ?? mapKeysAt(schema, path)
+  };
+}
+function mapKeysAt(root, path) {
+  let schema = root;
+  for (const segment of path) {
+    schema = typeof segment === "number" ? schema?.items : schema?.properties?.[segment];
+    if (!schema)
+      return void 0;
+  }
+  const keys = schema["x-kubernetes-list-map-keys"];
+  if (schema["x-kubernetes-list-type"] !== "map" || !keys || keys.length === 0)
+    return void 0;
+  return keys;
+}
+
+// dist/sse.js
+var SSEDecoder = class {
+  #buffer = "";
+  /** Feed a chunk of the stream; get back the events that completed with it. */
+  push(chunk) {
+    this.#buffer += chunk;
+    const out = [];
+    const trailingCR = this.#buffer.endsWith("\r");
+    const complete = trailingCR ? this.#buffer.slice(0, -1) : this.#buffer;
+    this.#buffer = complete.replace(/\r\n|\r/g, "\n") + (trailingCR ? "\r" : "");
+    for (; ; ) {
+      const sep = this.#buffer.indexOf("\n\n");
+      if (sep === -1)
+        break;
+      const frame = this.#buffer.slice(0, sep);
+      this.#buffer = this.#buffer.slice(sep + 2);
+      const ev = parseFrame(frame);
+      if (ev)
+        out.push(ev);
+    }
+    return out;
+  }
+};
+var StreamSequence = class {
+  #next = 1;
+  observe(event) {
+    if (!Number.isSafeInteger(event.seq) || event.seq !== this.#next) {
+      return { expected: this.#next, received: event.seq };
+    }
+    this.#next++;
+    return null;
+  }
+};
+function parseFrame(frame) {
+  const data = [];
+  for (const line of frame.split("\n")) {
+    if (line === "" || line.startsWith(":"))
+      continue;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" "))
+      value = value.slice(1);
+    if (field === "data")
+      data.push(value);
+  }
+  if (data.length === 0)
+    return null;
+  try {
+    return JSON.parse(data.join("\n"));
+  } catch {
+    return null;
+  }
+}
+function applyStreamEvent(store, ev) {
+  switch (ev.type) {
+    case "reset":
+      store.beginSnapshot();
+      return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
+    case "added":
+    case "modified": {
+      if (!ev.object)
+        return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
+      const result = store.applyServerEvent(ev.object, { redacted: ev.redacted });
+      return { type: ev.type, uid: ev.object.metadata.uid, ...result };
+    }
+    case "deleted": {
+      const uid = ev.identity?.uid;
+      if (uid)
+        store.removeResource(uid);
+      return { type: ev.type, uid, added: false, structural: true, flashed: [], conflicts: [] };
+    }
+    case "synced":
+      store.endSnapshot();
+      return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
+    default:
+      return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
+  }
+}
+function connectResourceStream(url, store, opts = {}) {
+  if (opts.signal?.aborted)
+    return { close: () => {
+    }, closed: Promise.resolve() };
+  const controller = new AbortController();
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  opts.signal?.addEventListener("abort", () => controller.abort(), { once: true });
+  const closed = (async () => {
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { Accept: "text/event-stream", ...opts.headers },
+      // The stream IS the response body; a cached one is a stream that never moves.
+      cache: "no-store"
+    });
+    if (!res.ok || !res.body) {
+      opts.onError?.("INTERNAL", `stream: HTTP ${res.status}`, true);
+      return;
+    }
+    const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+    const decoder = new SSEDecoder();
+    const sequence = new StreamSequence();
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done)
+          return;
+        for (const ev of decoder.push(value)) {
+          if (feed(store, sequence, ev, opts)) {
+            controller.abort();
+            return;
+          }
+        }
+      }
+    } catch (err) {
+      if (!controller.signal.aborted)
+        throw err;
+    } finally {
+      reader.cancel().catch(() => {
+      });
+    }
+  })();
+  return {
+    close: () => controller.abort(),
+    closed: closed.catch(() => {
+    })
+  };
+}
+function connectWithEventSource(url, store, opts = {}) {
+  if (opts.signal?.aborted)
+    return { close: () => {
+    }, closed: Promise.resolve() };
+  const es = new EventSource(url, { withCredentials: true });
+  const sequence = new StreamSequence();
+  let resolve;
+  const closed = new Promise((r) => {
+    resolve = r;
+  });
+  const shut = () => {
+    es.close();
+    resolve();
+  };
+  es.onmessage = (e) => {
+    let ev;
+    try {
+      ev = JSON.parse(e.data);
+    } catch {
+      return;
+    }
+    if (feed(store, sequence, ev, opts))
+      shut();
+  };
+  es.onerror = () => {
+    if (es.readyState === EventSource.CLOSED)
+      resolve();
+  };
+  opts.signal?.addEventListener("abort", shut, { once: true });
+  return { close: shut, closed };
+}
+function feed(store, sequence, ev, opts) {
+  const gap = sequence.observe(ev);
+  if (gap) {
+    opts.onGap?.(gap.expected, gap.received);
+    return true;
+  }
+  if (ev.type === "error") {
+    opts.onError?.(ev.code ?? "INTERNAL", ev.message ?? "", ev.terminal ?? false);
+    return ev.terminal === true;
+  }
+  const change = applyStreamEvent(store, ev);
+  if (ev.type === "synced")
+    opts.onSynced?.();
+  opts.onChange?.(change);
+  return false;
+}
+
+// dist/merge.js
+function reconcile(s, base, ours, theirs) {
+  return node(s, [], base, ours, theirs);
+}
+function node(s, path, base, ours, theirs) {
+  if (s.regions.editable(path))
+    return mergeEditable(s, path, base, ours, theirs);
+  if (s.regions.container(path))
+    return mergeContainer(s, path, base, ours, theirs);
+  return follow(s, path, base, theirs);
+}
+function follow(s, path, base, theirs) {
+  if (isPlainObject(base) && isPlainObject(theirs)) {
+    const out = {};
+    for (const k of unionKeys(base, theirs)) {
+      const v = follow(s, [...path, k], at(base, k), at(theirs, k));
+      if (v !== void 0)
+        out[k] = v;
+    }
+    return out;
+  }
+  if (!deepEqual(base, theirs))
+    s.flashed.push(path);
+  return clone(theirs);
+}
+function mergeContainer(s, path, base, ours, theirs) {
+  if (!isPlainObject(base) && !isPlainObject(ours) && !isPlainObject(theirs)) {
+    return follow(s, path, base, theirs);
+  }
+  return recurse(s, path, base, ours, theirs);
+}
+function mergeEditable(s, path, base, ours, theirs) {
+  const keys = s.regions.listMapKeys(path);
+  if (keys && isAssociativeList(base, keys) && isAssociativeList(ours, keys) && isAssociativeList(theirs, keys)) {
+    return mergeAssociativeList(s, path, keys, base, ours, theirs);
+  }
+  const defined = [base, ours, theirs].filter((v) => v !== void 0);
+  if (defined.length > 0 && defined.every(isPlainObject))
+    return recurse(s, path, base, ours, theirs);
+  if (deepEqual(base, ours)) {
+    if (!deepEqual(base, theirs))
+      s.flashed.push(path);
+    clearConflict(s, path);
+    return clone(theirs);
+  }
+  if (deepEqual(base, theirs))
+    return clone(ours);
+  if (deepEqual(ours, theirs)) {
+    clearConflict(s, path);
+    return clone(ours);
+  }
+  setConflict(s, path, theirs);
+  return clone(ours);
+}
+function mergeAssociativeList(s, path, keys, base, ours, theirs) {
+  const baseByKey = indexAssociativeList(base, keys);
+  const oursByKey = indexAssociativeList(ours, keys);
+  const theirsByKey = indexAssociativeList(theirs, keys);
+  if (!baseByKey || !oursByKey || !theirsByKey)
+    return mergeAtomic(s, path, base, ours, theirs);
+  const order = unique([...theirsByKey.order, ...oursByKey.order, ...baseByKey.order]);
+  const outputKeys = order.filter((key) => associativeEntrySurvives(oursByKey.values.get(key), theirsByKey.values.get(key)));
+  remapListConflicts(s, path, oursByKey.order, outputKeys);
+  const out = [];
+  for (const key of outputKeys) {
+    const value = mergeAssociativeEntry(s, [...path, out.length], baseByKey.values.get(key), oursByKey.values.get(key), theirsByKey.values.get(key));
+    if (value !== void 0)
+      out.push(value);
+  }
+  return out;
+}
+function associativeEntrySurvives(ours, theirs) {
+  return ours !== void 0 || theirs !== void 0;
+}
+function remapListConflicts(s, path, previousOrder, outputKeys) {
+  const outputIndex = new Map(outputKeys.map((key, index) => [key, index]));
+  const moved = [];
+  for (const [encoded, conflict] of s.conflicts) {
+    const segment = conflict.path[path.length];
+    if (!isPrefix(path, conflict.path) || typeof segment !== "number")
+      continue;
+    const key = previousOrder[segment];
+    const nextIndex = key === void 0 ? void 0 : outputIndex.get(key);
+    if (nextIndex === void 0 || nextIndex === segment)
+      continue;
+    s.conflicts.delete(encoded);
+    moved.push({ ...conflict, path: [...path, nextIndex, ...conflict.path.slice(path.length + 1)] });
+  }
+  for (const conflict of moved)
+    s.conflicts.set(pathKey(conflict.path), conflict);
+}
+function mergeAssociativeEntry(s, path, base, ours, theirs) {
+  if (base === void 0 || ours === void 0 || theirs === void 0)
+    return mergeAtomic(s, path, base, ours, theirs);
+  return node(s, path, base, ours, theirs);
+}
+function mergeAtomic(s, path, base, ours, theirs) {
+  if (deepEqual(base, ours)) {
+    if (!deepEqual(base, theirs))
+      s.flashed.push(path);
+    clearConflict(s, path);
+    return clone(theirs);
+  }
+  if (deepEqual(base, theirs))
+    return clone(ours);
+  if (deepEqual(ours, theirs)) {
+    clearConflict(s, path);
+    return clone(ours);
+  }
+  setConflict(s, path, theirs);
+  return clone(ours);
+}
+function isAssociativeList(value, keys) {
+  return Array.isArray(value) && indexAssociativeList(value, keys) !== void 0;
+}
+function indexAssociativeList(values, keys) {
+  const indexed = { order: [], values: /* @__PURE__ */ new Map() };
+  for (const value of values) {
+    if (!isPlainObject(value))
+      return void 0;
+    const identity = keys.map((key) => value[key]);
+    if (identity.some((part) => part === void 0 || part === null || typeof part === "object"))
+      return void 0;
+    const encoded = JSON.stringify(identity);
+    if (indexed.values.has(encoded))
+      return void 0;
+    indexed.order.push(encoded);
+    indexed.values.set(encoded, value);
+  }
+  return indexed;
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function recurse(s, path, base, ours, theirs) {
+  const out = {};
+  for (const k of unionKeys(base, ours, theirs)) {
+    const v = node(s, [...path, k], at(base, k), at(ours, k), at(theirs, k));
+    if (v !== void 0)
+      out[k] = v;
+  }
+  if (theirs === void 0 && Object.keys(out).length === 0)
+    return void 0;
+  return out;
+}
+function unionKeys(...values) {
+  const keys = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    if (!isPlainObject(v))
+      continue;
+    for (const k of Object.keys(v)) {
+      if (seen.has(k))
+        continue;
+      seen.add(k);
+      keys.push(k);
+    }
+  }
+  return keys;
+}
+function setConflict(s, path, theirs) {
+  s.conflicts.set(pathKey(path), { path: [...path], theirs: clone(theirs) });
+}
+function clearConflict(s, path) {
+  s.conflicts.delete(pathKey(path));
+}
+
+// dist/store.js
+var LiveResourceStore = class {
+  #policy;
+  #resources = /* @__PURE__ */ new Map();
+  #subscribers = /* @__PURE__ */ new Set();
+  /** Non-null exactly while a snapshot cycle is open: the uids seen since `beginSnapshot()`.
+   * Pruning reads it in `endSnapshot()` and NOWHERE else — a cycle that never completes must prune
+   * nothing, or a network hiccup makes the user watch half their resources evaporate (spec §5). */
+  #seen = null;
+  constructor(policy = defaultPolicy) {
+    this.#policy = policy;
+  }
+  // ------------------------------------------------------------------ the stream in --
+  /** `added` and `modified` — the only two upsert spellings, and they are treated identically
+   * (spec §4). Both mean "here is this object's complete current state". */
+  applyServerEvent(object, opts = {}) {
+    const id = object.metadata.uid;
+    const incoming = clone(object);
+    const redacted = (opts.redacted ?? []).map((entry) => ({
+      path: typeof entry.path === "string" ? parsePointer(entry.path) : [...entry.path],
+      rev: entry.rev
+    }));
+    this.#seen?.add(id);
+    const existing = this.#resources.get(id);
+    if (!existing) {
+      this.#resources.set(id, { server: incoming, draft: clone(incoming), redacted, conflicts: /* @__PURE__ */ new Map() });
+      this.#notify();
+      return { added: true, structural: true, flashed: [], conflicts: [] };
+    }
+    const state = {
+      regions: this.#regionsFor(incoming, redacted.map((r) => r.path)),
+      conflicts: existing.conflicts,
+      flashed: []
+    };
+    const merged = reconcile(state, existing.server, existing.draft, incoming);
+    const structural = !sameShape(existing.draft, merged);
+    existing.server = incoming;
+    existing.draft = merged;
+    existing.redacted = redacted;
+    this.#notify();
+    return {
+      added: false,
+      structural,
+      flashed: state.flashed,
+      conflicts: [...existing.conflicts.values()].map((c) => c.path)
+    };
+  }
+  /** `deleted`. The object is gone, and so is any draft of it — the user was editing something that
+   * no longer exists. (A recreate under the same name is a DIFFERENT uid and starts clean; that is
+   * the whole reason identity is the uid.) */
+  removeResource(id) {
+    if (this.#resources.delete(id))
+      this.#notify();
+  }
+  /** `reset`. Mark every known uid unseen — and prune NOTHING yet. */
+  beginSnapshot() {
+    this.#seen = /* @__PURE__ */ new Set();
+  }
+  /** `synced`. The snapshot is complete, so what it did not mention is genuinely gone. This is the
+   * only place anything is pruned, and it is what removes an object deleted while the consumer was
+   * disconnected — the one event the consumer never saw. */
+  endSnapshot() {
+    const seen = this.#seen;
+    if (!seen)
+      return;
+    this.#seen = null;
+    let pruned = false;
+    for (const id of [...this.#resources.keys()]) {
+      if (!seen.has(id)) {
+        this.#resources.delete(id);
+        pruned = true;
+      }
+    }
+    if (pruned)
+      this.#notify();
+  }
+  /** The save succeeded and this is the object it produced. The watch will echo it too — and that
+   * echo is a harmless no-op (I-IDEMPOTENT) — but a UI should not have to wait for it to stop
+   * showing the field as dirty. */
+  /** Adopt the object a save returned.
+   *
+   * `object` MUST be projected — the same projection the stream uses. An object straight from a
+   * Kubernetes client carries managedFields, status and the Secret values the projection withholds,
+   * and handing it here puts all of them in the browser through the one endpoint the stream does not
+   * guard. Project it on the server with `gateway.Project` first.
+   *
+   * You probably do not need this. The recommended save is 204: the write reaches the API server, the
+   * watch echoes it back down the stream already projected, and the store converges. Dirty state is
+   * derived from draft-versus-server, so there is nothing to adopt. Use this only when a host cannot
+   * wait for the echo. See docs/saving.md. */
+  adoptSaved(object) {
+    const existing = this.#resources.get(object.metadata.uid);
+    if (!existing) {
+      this.applyServerEvent(object);
+      return;
+    }
+    this.applyServerEvent(object, { redacted: existing.redacted });
+  }
+  // ------------------------------------------------------------------------- edits --
+  setValue(id, path, value) {
+    const res = this.#editable(id, path);
+    setAt(res.draft, path, clone(value));
+    this.#settle(res, path);
+  }
+  /** For a map entry or an object key the user deleted. It stays deleted across watch events (the
+   * merge sees ours=undefined, base=theirs and keeps the deletion) and becomes a `null` in the patch. */
+  removeKey(id, path) {
+    const res = this.#editable(id, path);
+    removeAt(res.draft, path);
+    this.#settle(res, path);
+  }
+  /** `path` addresses the MAP; `key` is the new entry. A new row in a UI starts empty. */
+  addKey(id, path, key, value = "") {
+    const res = this.#editable(id, [...path, key]);
+    setAt(res.draft, [...path, key], clone(value));
+    this.#settle(res, [...path, key]);
+  }
+  /** `path` addresses the MAP. Order is preserved — renaming a label must not make its row jump to
+   * the bottom of the list while the user is typing in it. */
+  renameKey(id, path, oldKey, newKey) {
+    const res = this.#editable(id, [...path, oldKey]);
+    this.#editable(id, [...path, newKey]);
+    const map = get(res.draft, path);
+    if (!isPlainObject(map))
+      throw new Error(`krm-stream: ${pathKey(path)} is not a map`);
+    if (!Object.hasOwn(map, oldKey))
+      throw new Error(`krm-stream: key ${JSON.stringify(oldKey)} does not exist`);
+    if (oldKey !== newKey && Object.hasOwn(map, newKey)) {
+      throw new Error(`krm-stream: key ${JSON.stringify(newKey)} already exists`);
+    }
+    const renamed = {};
+    for (const [k, v] of Object.entries(map))
+      renamed[k === oldKey ? newKey : k] = v;
+    setAt(res.draft, path, renamed);
+    this.#settle(res, [...path, oldKey]);
+    this.#settle(res, [...path, newKey]);
+  }
+  /** Throw the local edit away and take the server's value — which is also how a conflict is
+   * resolved in the server's favour. */
+  revert(id, path) {
+    const res = this.#editable(id, path);
+    if (has(res.server, path))
+      setAt(res.draft, path, clone(get(res.server, path)));
+    else
+      removeAt(res.draft, path);
+    this.#settle(res, path);
+  }
+  /** Resolve a conflict by keeping the server's value. */
+  takeTheirs(id, path) {
+    this.revert(id, path);
+  }
+  // ----------------------------------------------------------------------- queries --
+  ids() {
+    return [...this.#resources.keys()];
+  }
+  /** The authoritative server object, including live `status`. */
+  server(id) {
+    return clone(this.#must(id).server);
+  }
+  /** The server object with the editable regions merged over it. What a UI renders and edits. */
+  draft(id) {
+    return clone(this.#must(id).draft);
+  }
+  /** Read-only convenience for the watch UI. A kind with no status simply has none. */
+  status(id) {
+    return clone(this.#must(id).server.status);
+  }
+  /** Every pending edit, derived fresh by comparing the draft to the server object. Arrays appear
+   * whole (§4.1), which is also what RFC 7386 wants. */
+  changes(id) {
+    const res = this.#must(id);
+    const out = [];
+    this.#diff(this.#regionsFor(res.server, res.redacted.map((r) => r.path)), [], res.server, res.draft, out);
+    return out;
+  }
+  /** R-DERIVED: never a stored flag. A read-only path is never dirty by construction. */
+  isDirty(id, path) {
+    const res = this.#must(id);
+    if (this.isEditable(id, path))
+      return !deepEqual(get(res.server, path), get(res.draft, path));
+    if (!this.#policy.containsEditable(res.server, path))
+      return false;
+    return this.changes(id).some((c) => isPrefix(path, c.path));
+  }
+  conflicts(id) {
+    return [...this.#must(id).conflicts.values()].map((c) => ({ path: [...c.path], theirs: clone(c.theirs) }));
+  }
+  /** The policy, minus this object's redacted paths. A redacted value is read-only for exactly the
+   * same reason `status` is: it is not the user's to change — and here, they never even saw it. */
+  isEditable(id, path) {
+    const res = this.#must(id);
+    return this.#regionsFor(res.server, res.redacted.map((r) => r.path)).editable(path);
+  }
+  /**
+   * The paths whose values the gateway withheld. **This is the only place a consumer learns that a
+   * redacted field exists**, and rendering it is the whole of keys-only disclosure.
+   *
+   * The value itself is not in the object — there is no mask, no placeholder, nothing (spec §3). So a
+   * UI showing `token ••••••` reads it from HERE, not from the object:
+   *
+   * ```ts
+   * for (const { path } of store.redactions(uid)) row(path, "••••••", { readOnly: true });
+   * ```
+   *
+   * That is deliberate. A placeholder sitting in the object is a value a browser can save back — and
+   * a merge patch carrying it writes the placeholder over the real Secret.
+   */
+  redactions(id) {
+    return this.#must(id).redacted.map((r) => ({ path: [...r.path], rev: r.rev }));
+  }
+  /** An RFC 7386 merge patch of the editable changes, or null when there is nothing to save.
+   *
+   * Built from the user's EDITS — never from a diff of the whole object against the server. The
+   * object on the wire is a projection: a path the projection removed is simply not there, and a
+   * whole-object diff would read that absence as a deletion and try to patch it away (spec §3). */
+  patch(id) {
+    const changes = this.changes(id);
+    if (changes.length === 0)
+      return null;
+    const out = {};
+    for (const c of changes)
+      setAt(out, c.path, c.new === void 0 ? null : clone(c.new));
+    return out;
+  }
+  /** A coarse "something changed" signal — the host re-renders and re-queries. Returns an
+   * unsubscribe. */
+  subscribe(cb) {
+    this.#subscribers.add(cb);
+    return () => this.#subscribers.delete(cb);
+  }
+  // ---------------------------------------------------------------------- internals --
+  #must(id) {
+    const res = this.#resources.get(id);
+    if (!res)
+      throw new Error(`krm-stream: no resource ${JSON.stringify(id)}`);
+    return res;
+  }
+  /** Every edit goes through here: a write to `status`, to `metadata.name`, or to a redacted path is
+   * refused. The engine is not the security boundary — the gateway rejects such a patch too — but a
+   * UI that cannot even form the edit is safer than one that relies on client cooperation. */
+  #editable(id, path) {
+    const res = this.#must(id);
+    if (!this.isEditable(id, path)) {
+      throw new Error(`krm-stream: ${pathKey(path)} is read-only`);
+    }
+    return res;
+  }
+  #regionsFor(object, redacted) {
+    const insideRedacted = (path) => redacted.some((r) => isPrefix(r, path));
+    const containsRedacted = (path) => redacted.some((r) => isPrefix(path, r));
+    return {
+      editable: (path) => !insideRedacted(path) && !containsRedacted(path) && this.#policy.isEditable(object, path),
+      container: (path) => !insideRedacted(path) && this.#policy.containsEditable(object, path),
+      listMapKeys: (path) => this.#policy.listMapKeys?.(object, path)
+    };
+  }
+  /** After an edit: a conflict whose path the draft has now brought back to the server's value is no
+   * longer a conflict. (Typing the server's value by hand resolves it, and so does `revert`.) */
+  #settle(res, path) {
+    for (const [k, c] of res.conflicts) {
+      if (!isPrefix(c.path, path) && !isPrefix(path, c.path))
+        continue;
+      if (deepEqual(get(res.server, c.path), get(res.draft, c.path)))
+        res.conflicts.delete(k);
+    }
+    this.#notify();
+  }
+  #diff(regions, path, srv, drf, out) {
+    if (regions.editable(path)) {
+      const defined = [srv, drf].filter((v) => v !== void 0);
+      if (defined.length > 0 && defined.every(isPlainObject)) {
+        for (const k of unionKeys2(srv, drf)) {
+          this.#diff(regions, [...path, k], srv?.[k], drf?.[k], out);
+        }
+        return;
+      }
+      if (!deepEqual(srv, drf)) {
+        const kind = srv === void 0 ? "add" : drf === void 0 ? "delete" : "update";
+        out.push({ path: [...path], kind, old: clone(srv), new: clone(drf) });
+      }
+      return;
+    }
+    if (regions.container(path)) {
+      for (const k of unionKeys2(srv, drf)) {
+        this.#diff(regions, [...path, k], srv?.[k], drf?.[k], out);
+      }
+    }
+  }
+  #notify() {
+    for (const cb of this.#subscribers)
+      cb();
+  }
+};
+function unionKeys2(...values) {
+  const keys = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    if (!isPlainObject(v))
+      continue;
+    for (const k of Object.keys(v)) {
+      if (!seen.has(k)) {
+        seen.add(k);
+        keys.push(k);
+      }
+    }
+  }
+  return keys;
+}
+function sameShape(a, b) {
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length)
+      return false;
+    return ka.every((k) => Object.hasOwn(b, k) && sameShape(a[k], b[k]));
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((x, i) => sameShape(x, b[i]));
+  }
+  return isPlainObject(a) === isPlainObject(b) && Array.isArray(a) === Array.isArray(b);
+}
+
+// dist/url.js
+function resourceStreamURL(base, scope) {
+  if (!scope.resource)
+    throw new Error("krm-stream: scope needs a `resource` (the plural, lowercase API name)");
+  if (!scope.version)
+    throw new Error("krm-stream: scope needs a `version` (there is no default: v1 and v1beta1 differ)");
+  const q = new URLSearchParams();
+  const set = (k, v) => {
+    if (v)
+      q.append(k, v);
+  };
+  set("target", scope.target);
+  set("group", scope.group);
+  set("version", scope.version);
+  set("resource", scope.resource);
+  set("namespace", scope.namespace);
+  set("name", scope.name);
+  set("labelSelector", scope.labelSelector);
+  set("projection", scope.projection);
+  return `${base}${base.includes("?") ? "&" : "?"}${q.toString()}`;
+}
+
+// dist/version.js
+var VERSION = "0.2.0";
+var PROTOCOL_VERSION = 1;
+export {
+  DEFAULT_EDITABLE_REGIONS,
+  LiveResourceStore,
+  PROTOCOL_VERSION,
+  SSEDecoder,
+  StreamSequence,
+  VERSION,
+  applyStreamEvent,
+  clone,
+  connectResourceStream,
+  connectWithEventSource,
+  deepEqual,
+  defaultPolicy,
+  get,
+  has,
+  isPrefix,
+  parsePointer,
+  pathKey,
+  readOnlyPolicy,
+  regionPolicy,
+  resourceStreamURL,
+  withOpenAPIKeyedLists
+};

package/dist/sse.d.ts

@@ -1,5 +1,5 @@
 import type { LiveResourceStore } from "./store.ts";
-import type { ErrorCode, Path, StreamEvent } from "./types.ts";
+import type { ErrorCode, EventType, Path, StreamEvent } from "./types.ts";
 /** Incremental SSE parser. Bytes arrive in whatever chunks the network feels like — a frame can be
  * split down the middle, and it WILL be, under exactly the load where you least want to debug it —
  * so this buffers and only yields complete frames. */
@@ -21,16 +21,38 @@ export declare class StreamSequence {
  * it is exported because it IS the protocol — a host feeding a store from its own transport should
  * not have to reimplement the switch and get `synced` subtly wrong.
  *
- * Returns the paths that flashed, so a UI can highlight them. */
-export declare function applyStreamEvent(store: LiveResourceStore, ev: StreamEvent): Path[];
+ * Returns the complete StreamChange — which resource, and what happened to it. */
+export declare function applyStreamEvent(store: LiveResourceStore, ev: StreamEvent): StreamChange;
+/** What one stream event did to the store.
+ *
+ * This is the whole ApplyResult and the uid it belongs to, because anything less makes a host
+ * reimplement the stream loop to get the rest back. A UI rendering more than ONE resource per stream
+ * — which is most of them — cannot use a bare list of paths: it knows what moved and not what moved.
+ *
+ * Each field answers a question a renderer actually has:
+ *
+ *   uid         which resource. Absent only on reset/synced, which are about the stream, not an object.
+ *   added       an arrival, not a change. Animate it in; do not flash it as if a value moved.
+ *   structural  keys or rows appeared or disappeared. REBUILD the list; re-reading values is not enough.
+ *   flashed     the paths the server moved. Highlight these.
+ *   conflicts   the paths now conflicted, complete — not just the new ones.
+ */
+export interface StreamChange {
+    type: EventType;
+    uid?: string;
+    added: boolean;
+    structural: boolean;
+    flashed: Path[];
+    conflicts: Path[];
+}
 export interface StreamOptions {
     /** Called for every `error` event. A terminal one has already closed the connection by the time
      * this returns — there is nothing to retry, and retrying is the bug. */
     onError?: (code: ErrorCode, message: string, terminal: boolean) => void;
     /** Called at the end of every snapshot cycle. The store is now consistent: a good moment to paint. */
     onSynced?: () => void;
-    /** Called after any change, with the paths that flashed. */
-    onChange?: (flashed: Path[]) => void;
+    /** Called after any change, with what the event did and which resource it did it to. */
+    onChange?: (change: StreamChange) => void;
     /** A missing or duplicated event was observed. The connection is closed; reconnect for a snapshot. */
     onGap?: (expected: number, received: number) => void;
     /** Abort the stream from outside. */

package/dist/sse.js

@@ -87,28 +87,34 @@ function parseFrame(frame) {
  * it is exported because it IS the protocol — a host feeding a store from its own transport should
  * not have to reimplement the switch and get `synced` subtly wrong.
  *
- * Returns the paths that flashed, so a UI can highlight them. */
+ * Returns the complete StreamChange — which resource, and what happened to it. */
 export function applyStreamEvent(store, ev) {
     switch (ev.type) {
         case "reset":
             store.beginSnapshot();
-            return [];
+            return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
         case "added":
-        case "modified":
+        case "modified": {
             if (!ev.object)
-                return [];
-            return store.applyServerEvent(ev.object, { redacted: ev.redacted }).flashed;
-        case "deleted":
-            if (ev.identity?.uid)
-                store.removeResource(ev.identity.uid);
-            return [];
+                return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
+            const result = store.applyServerEvent(ev.object, { redacted: ev.redacted });
+            return { type: ev.type, uid: ev.object.metadata.uid, ...result };
+        }
+        case "deleted": {
+            const uid = ev.identity?.uid;
+            if (uid)
+                store.removeResource(uid);
+            // A removal IS structural: a row left the collection, and a UI that only re-reads values would
+            // keep rendering it.
+            return { type: ev.type, uid, added: false, structural: true, flashed: [], conflicts: [] };
+        }
         case "synced":
             store.endSnapshot();
-            return [];
+            return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
         default:
             // An unknown event type MUST be ignored, not treated as an error (spec §0). That is what lets
             // the gateway add an optional event type later without breaking a browser nobody can update.
-            return [];
+            return { type: ev.type, added: false, structural: false, flashed: [], conflicts: [] };
     }
 }
 /** Consume a resource stream over fetch, feeding a store. Use this when the gateway authenticates
@@ -207,9 +213,9 @@ function feed(store, sequence, ev, opts) {
         opts.onError?.(ev.code ?? "INTERNAL", ev.message ?? "", ev.terminal ?? false);
         return ev.terminal === true;
     }
-    const flashed = applyStreamEvent(store, ev);
+    const change = applyStreamEvent(store, ev);
     if (ev.type === "synced")
         opts.onSynced?.();
-    opts.onChange?.(flashed);
+    opts.onChange?.(change);
     return false;
 }

package/dist/store.d.ts

@@ -37,6 +37,17 @@ export declare class LiveResourceStore {
     /** The save succeeded and this is the object it produced. The watch will echo it too — and that
      * echo is a harmless no-op (I-IDEMPOTENT) — but a UI should not have to wait for it to stop
      * showing the field as dirty. */
+    /** Adopt the object a save returned.
+     *
+     * `object` MUST be projected — the same projection the stream uses. An object straight from a
+     * Kubernetes client carries managedFields, status and the Secret values the projection withholds,
+     * and handing it here puts all of them in the browser through the one endpoint the stream does not
+     * guard. Project it on the server with `gateway.Project` first.
+     *
+     * You probably do not need this. The recommended save is 204: the write reaches the API server, the
+     * watch echoes it back down the stream already projected, and the store converges. Dirty state is
+     * derived from draft-versus-server, so there is nothing to adopt. Use this only when a host cannot
+     * wait for the echo. See docs/saving.md. */
     adoptSaved(object: KRMObject): void;
     setValue(id: string, path: Path, value: unknown): void;
     /** For a map entry or an object key the user deleted. It stays deleted across watch events (the

package/dist/store.js

@@ -98,6 +98,17 @@ export class LiveResourceStore {
     /** The save succeeded and this is the object it produced. The watch will echo it too — and that
      * echo is a harmless no-op (I-IDEMPOTENT) — but a UI should not have to wait for it to stop
      * showing the field as dirty. */
+    /** Adopt the object a save returned.
+     *
+     * `object` MUST be projected — the same projection the stream uses. An object straight from a
+     * Kubernetes client carries managedFields, status and the Secret values the projection withholds,
+     * and handing it here puts all of them in the browser through the one endpoint the stream does not
+     * guard. Project it on the server with `gateway.Project` first.
+     *
+     * You probably do not need this. The recommended save is 204: the write reaches the API server, the
+     * watch echoes it back down the stream already projected, and the store converges. Dirty state is
+     * derived from draft-versus-server, so there is nothing to adopt. Use this only when a host cannot
+     * wait for the echo. See docs/saving.md. */
     adoptSaved(object) {
         const existing = this.#resources.get(object.metadata.uid);
         if (!existing) {
@@ -250,8 +261,7 @@ export class LiveResourceStore {
     }
     /** Every edit goes through here: a write to `status`, to `metadata.name`, or to a redacted path is
      * refused. The engine is not the security boundary — the gateway rejects such a patch too — but a
-     * UI that cannot even form the edit is the difference between "safe" and "safe if the client is
-     * honest". */
+     * UI that cannot even form the edit is safer than one that relies on client cooperation. */
     #editable(id, path) {
         const res = this.#must(id);
         if (!this.isEditable(id, path)) {

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** The npm package version of this build. Assert it against the copy you vendored. */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 /** The wire protocol this build speaks (spec/v1.md). The gateway sends it as `X-KRM-Stream-Protocol`. */
 export declare const PROTOCOL_VERSION = 1;

package/dist/version.js

@@ -21,6 +21,6 @@
 // release-please-config.json). Do not edit it by hand: the release PR bumps package.json and this
 // line together, and version.test.ts fails if they ever disagree.
 /** The npm package version of this build. Assert it against the copy you vendored. */
-export const VERSION = "0.1.0"; // x-release-please-version
+export const VERSION = "0.2.0"; // x-release-please-version
 /** The wire protocol this build speaks (spec/v1.md). The gateway sends it as `X-KRM-Stream-Protocol`. */
 export const PROTOCOL_VERSION = 1;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@configbutler/krm-stream",
-  "version": "0.1.0",
-  "description": "A live, honest window onto Kubernetes resources, in the browser: consume a KRM resource stream, three-way merge local edits, build a merge patch.",
+  "version": "0.2.0",
+  "description": "Receive live Kubernetes resource updates in browser apps and three-way merge them with form edits.",
   "keywords": [
     "kubernetes",
     "krm",
+    "config-as-data",
     "sse",
     "watch",
     "live",
@@ -24,6 +25,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./bundle": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/krm-stream.js"
     }
   },
   "files": [
@@ -34,16 +39,19 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run build:bundle",
+    "//build:bundle": "Flatten the emitted module graph into ONE file for hosts with no bundler and no node_modules — the ones that vendor the library by copying it and serving it. Bundling dist/index.js (not src/) keeps a single source of truth: the file a bundler-based consumer imports is the file this flattens. --target=es2022 pins it to the same output tsconfig emits, so a bundle can never quietly acquire a polyfill the per-module build does not have. No sourcemap: a host serving this publicly should not have to also serve a .map, or field a console warning for not doing so.",
+    "build:bundle": "esbuild dist/index.js --bundle --format=esm --target=es2022 --legal-comments=none --outfile=dist/krm-stream.js",
     "test": "node --test",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "lint": "biome check",
     "format": "biome check --write"
   },
-  "//": "ZERO dependencies, and that one is absolute: the engine emits plain ESM a browser imports with no bundler, and gitops-api has no bundler and is not getting one. devDependencies ship NOTHING and are kept to the three that pay for themselves: typescript (the compiler), @types/node (without it `tsc` cannot see test/ at all, because the tests import node:test — and `node --test` STRIPS types rather than checking them, so the suite that IS the contract check would be the one unverified file in the repo), and biome (lint + format in one binary, the TypeScript half of what gofmt/go vet/golangci-lint do for the gateway).",
+  "//": "ZERO dependencies, and that one is absolute: the engine emits plain ESM a browser imports with no bundler, and gitops-api has no bundler and is not getting one. devDependencies ship NOTHING and are kept to the four that pay for themselves: typescript (the compiler), @types/node (without it `tsc` cannot see test/ at all, because the tests import node:test — and `node --test` STRIPS types rather than checking them, so the suite that IS the contract check would be the one unverified file in the repo), biome (lint + format in one binary, the TypeScript half of what gofmt/go vet/golangci-lint do for the gateway), and esbuild (flattens dist/ into the single-file ./bundle — it runs ONCE per release here, so that every no-bundler consumer does not each reinvent it, and it is the reason a host can vendor ONE file instead of eleven; it emits no polyfill and no runtime dependency, and if it ever needs to, the bundle is wrong).",
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
     "@types/node": "^26.1.1",
-    "typescript": "^5.9.0"
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.2"
   }
 }