@ai-matrx/content-ir-react 0.7.1 → 0.8.0

package/dist/resolver.cjs

@@ -0,0 +1,327 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// resolver.ts
+var resolver_exports = {};
+__export(resolver_exports, {
+  ComponentResolver: () => ComponentResolver
+});
+module.exports = __toCommonJS(resolver_exports);
+
+// host/error-report.ts
+var consoleErrorReporter = (report) => {
+  console.error(`[content-ir] ${report.message}`, report.raw ?? "");
+};
+
+// resolver/component-resolver.ts
+var KEY_SEPARATOR = String.fromCharCode(1);
+function keyOf(kind, platform, role) {
+  return `${kind}${KEY_SEPARATOR}${platform}${KEY_SEPARATOR}${role}`;
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function errorFields(error) {
+  if (!(error instanceof Error)) return {};
+  return {
+    name: error.name,
+    ...error.stack === void 0 ? {} : { stack: error.stack }
+  };
+}
+var ComponentResolver = class {
+  compiled = null;
+  db = /* @__PURE__ */ new Map();
+  warmPromise = null;
+  warmFailureLogged = false;
+  /**
+   * When the last successful wholesale refresh landed, or null for "never".
+   * Explicitly nullable rather than 0: with a host-supplied clock that starts
+   * near zero, a `0` sentinel makes the FIRST refresh look rate-limited and
+   * silently skip.
+   */
+  lastRefreshAt = null;
+  refreshPromise = null;
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Cold single-kind fetch dedupe (streaming eager path). In-flight is keyed
+   * by (kind, platform) — the fetch unit; misses are keyed by (kind, platform,
+   * role) so a miss on web/output never suppresses other roles, and CLEARED on
+   * every wholesale refresh (a component created mid-session becomes eagerly
+   * fetchable again — misses are cheap to re-verify).
+   */
+  coldInFlight = /* @__PURE__ */ new Set();
+  coldMisses = /* @__PURE__ */ new Set();
+  /** Monotonic db-tier version — the repaint hook's snapshot key. */
+  version = 0;
+  /** Per-kind versions + listeners (granular repaint) + wholesale epoch. */
+  kindVersions = /* @__PURE__ */ new Map();
+  kindListeners = /* @__PURE__ */ new Map();
+  epoch = 0;
+  reportError;
+  now;
+  options;
+  // Explicit field, not a parameter property: consumers compile this source
+  // directly, and a strict host (the dashboard) sets `erasableSyntaxOnly`,
+  // under which parameter properties are a hard error.
+  constructor(options = {}) {
+    this.options = options;
+    this.reportError = options.reportError ?? consoleErrorReporter;
+    this.now = options.now ?? (() => Date.now());
+  }
+  compiledMap() {
+    if (!this.compiled) {
+      this.compiled = /* @__PURE__ */ new Map();
+      for (const entry of this.options.compiledEntries?.() ?? []) {
+        this.compiled.set(keyOf(entry.kind, entry.platform, entry.role), entry);
+      }
+    }
+    return this.compiled;
+  }
+  /**
+   * Synchronous resolve — the render seam's per-block call. DB override first
+   * (once warm), compiled floor second, null for unknown.
+   */
+  resolve(kind, platform, role) {
+    const key = keyOf(kind, platform, role);
+    const dbRow = this.db.get(key);
+    if (dbRow) {
+      return {
+        componentKey: dbRow.componentKey,
+        source: dbRow.source,
+        config: dbRow.config,
+        isActive: dbRow.isActive,
+        resolvedBy: "db",
+        componentSource: dbRow.componentSource,
+        propsTransform: dbRow.propsTransform,
+        hasComponentSource: dbRow.hasComponentSource ?? Boolean(dbRow.componentSource && dbRow.componentSource.trim()),
+        pinnedKindVersion: dbRow.pinnedKindVersion,
+        updatedAt: dbRow.updatedAt,
+        createdBy: dbRow.createdBy
+      };
+    }
+    const compiledEntry = this.compiledMap().get(key);
+    if (compiledEntry) {
+      return {
+        componentKey: compiledEntry.componentKey,
+        source: compiledEntry.source,
+        config: compiledEntry.config,
+        isActive: true,
+        // trusted at bootstrap (R6)
+        resolvedBy: "compiled",
+        componentSource: null,
+        propsTransform: null,
+        hasComponentSource: false,
+        pinnedKindVersion: null,
+        updatedAt: null,
+        createdBy: null
+      };
+    }
+    return null;
+  }
+  /** R6 floor check: compiled-bootstrap membership = always render-trusted. */
+  hasCompiled(kind, platform, role) {
+    return this.compiledMap().has(keyOf(kind, platform, role));
+  }
+  /**
+   * Pure ingest — the warm landing point and the unit-test seam. First row per
+   * key wins: rows arrive is_default-first / sort_order-asc from the source.
+   */
+  ingestDbRows(rows) {
+    const changedKinds = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      const key = keyOf(row.kind, row.platform, row.role);
+      if (!this.db.has(key)) {
+        this.db.set(key, row);
+        changedKinds.add(row.kind);
+      }
+    }
+    if (changedKinds.size > 0) {
+      for (const kind of changedKinds) this.bumpKind(kind);
+      this.notifyChanged();
+    }
+  }
+  /**
+   * Refresh landing point: REPLACE the db tier wholesale (same
+   * first-row-per-key contract as {@link ingestDbRows}) so edits, deletions,
+   * and is_active flips all take effect. Always notifies.
+   */
+  replaceDbRows(rows) {
+    this.db.clear();
+    this.coldMisses.clear();
+    for (const row of rows) {
+      const key = keyOf(row.kind, row.platform, row.role);
+      if (!this.db.has(key)) this.db.set(key, row);
+    }
+    this.epoch += 1;
+    for (const set of this.kindListeners.values()) {
+      for (const listener of set) listener();
+    }
+    this.notifyChanged();
+  }
+  getVersion() {
+    return this.version;
+  }
+  getKindVersion(kind) {
+    return this.epoch + (this.kindVersions.get(kind) ?? 0);
+  }
+  subscribeKind(kind, listener) {
+    const set = this.kindListeners.get(kind) ?? /* @__PURE__ */ new Set();
+    set.add(listener);
+    this.kindListeners.set(kind, set);
+    return () => {
+      set.delete(listener);
+      if (set.size === 0) this.kindListeners.delete(kind);
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  bumpKind(kind) {
+    this.kindVersions.set(kind, (this.kindVersions.get(kind) ?? 0) + 1);
+    const listeners = this.kindListeners.get(kind);
+    if (listeners) for (const listener of listeners) listener();
+  }
+  notifyChanged() {
+    this.version += 1;
+    for (const listener of this.listeners) listener();
+  }
+  /**
+   * A warm metadata shell is resolved enough for routing, but not for the
+   * host's db-component renderer. Its body must still come from the cold
+   * single-kind loader.
+   */
+  needsColdFetch(kind, platform, role) {
+    const resolution = this.resolve(kind, platform, role);
+    return resolution === null || resolution.resolvedBy === "db" && resolution.hasComponentSource && resolution.componentSource === null;
+  }
+  /**
+   * Cold rows are the authoritative heavy form of warm metadata shells. Keep
+   * the same first-row-per-key winner contract, but replace an existing shell
+   * so `componentSource` / `propsTransform` can land and repaint the kind.
+   */
+  ingestColdRows(rows) {
+    const winners = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const key = keyOf(row.kind, row.platform, row.role);
+      if (!winners.has(key)) winners.set(key, row);
+    }
+    if (winners.size === 0) return;
+    const changedKinds = /* @__PURE__ */ new Set();
+    for (const [key, row] of winners) {
+      this.db.set(key, row);
+      changedKinds.add(row.kind);
+    }
+    for (const kind of changedKinds) this.bumpKind(kind);
+    this.notifyChanged();
+  }
+  /**
+   * The eager lightweight single-kind fetch (streaming path): the moment a
+   * cloud kind is identified mid-stream, pull ONLY that kind's resolver rows
+   * and ingest them so {@link resolve} can answer before — or shortly after —
+   * the region completes. Deduped in-flight and by known-miss. Fire-and-forget;
+   * failures are loud (the warm list remains the backstop).
+   */
+  requestComponent(kind, platform, role) {
+    const loadForKind = this.options.loadForKind;
+    if (!loadForKind) return;
+    if (!this.needsColdFetch(kind, platform, role)) return;
+    const missKey = keyOf(kind, platform, role);
+    const flightKey = `${kind}${KEY_SEPARATOR}${platform}`;
+    if (this.coldInFlight.has(flightKey) || this.coldMisses.has(missKey)) {
+      return;
+    }
+    this.coldInFlight.add(flightKey);
+    void (async () => {
+      try {
+        this.ingestColdRows(await loadForKind(kind, platform));
+        if (this.needsColdFetch(kind, platform, role)) {
+          this.coldMisses.add(missKey);
+        }
+      } catch (error) {
+        this.reportError({
+          source: "content-ir",
+          message: `component-resolver cold fetch failed for "${kind}": ${describe(error)}`,
+          ...errorFields(error),
+          raw: error
+        });
+      } finally {
+        this.coldInFlight.delete(flightKey);
+      }
+    })();
+  }
+  /**
+   * Refresh-on-view: re-fetch the warm list and REPLACE the db tier, so an
+   * edited `source='db'` component (its `updated_at` bump re-keys the host's
+   * compile cache) renders fresh on the next view. Deduped in-flight and
+   * rate-limited by `maxAgeMs` (default 10s) — mounting several previews costs
+   * one fetch. Server-side edits do NOT push to open clients; the contract is
+   * refresh-on-view via this call.
+   */
+  refresh(maxAgeMs = 1e4) {
+    const loadAll = this.options.loadAll;
+    if (!loadAll) return Promise.resolve();
+    if (this.refreshPromise) return this.refreshPromise;
+    if (this.lastRefreshAt !== null && this.now() - this.lastRefreshAt < maxAgeMs) {
+      return Promise.resolve();
+    }
+    this.coldMisses.clear();
+    this.refreshPromise = loadAll().then((rows) => {
+      this.lastRefreshAt = this.now();
+      this.replaceDbRows(rows);
+    }).catch((error) => {
+      this.reportError({
+        source: "content-ir",
+        message: `component-resolver refresh failed (current resolver tier still serving): ${describe(error)}`,
+        ...errorFields(error),
+        raw: error
+      });
+    }).finally(() => {
+      this.refreshPromise = null;
+    });
+    return this.refreshPromise;
+  }
+  /** One list fetch per app session; failed loads retry on the next call. */
+  ensureWarm() {
+    const loadAll = this.options.loadAll;
+    if (!loadAll) return Promise.resolve();
+    if (!this.warmPromise) {
+      this.warmPromise = loadAll().then((rows) => {
+        this.ingestDbRows(rows);
+      }).catch((error) => {
+        const message = `component-resolver warm load failed (compiled bootstrap still serving): ${describe(error)}`;
+        if (!this.warmFailureLogged) {
+          this.warmFailureLogged = true;
+          console.error(`[content-ir] ${message}`);
+        }
+        this.reportError({
+          source: "content-ir",
+          message,
+          ...errorFields(error),
+          raw: error
+        });
+        this.warmPromise = null;
+      });
+    }
+    return this.warmPromise;
+  }
+};
+//# sourceMappingURL=resolver.cjs.map

package/dist/resolver.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../resolver.ts","../host/error-report.ts","../resolver/component-resolver.ts"],"sourcesContent":["/**\n * `@ai-matrx/content-ir-react/resolver` — (kind, platform, role) → component:\n * the `kind_component` row vocabulary and the `ComponentResolver` (compiled\n * floor, DB override, granular per-kind repaint, cold-fetch dedupe,\n * warm/refresh with loud recovery). Pure TS — no React runtime; deliberately\n * unstamped so server graphs can import it.\n */\nexport * from \"./resolver/component-resolution.types\";\nexport * from \"./resolver/component-resolver\";\n","/**\n * THE SCREAM SEAM.\n *\n * Every recovery path in this package is loud: a defective component row, a\n * failed resolver load, a kind whose component throws on a provisional value.\n * The package refuses to own where those screams land — matrx-frontend routes\n * them to the Error Inspector, the dashboard to its own log, the extension to\n * its background page. Each host binds one function.\n *\n * A host that binds a no-op has chosen silence, which is a defect in itself;\n * {@link consoleErrorReporter} is the honest default.\n */\n\nexport interface ContentIrErrorReport {\n  /** Always `\"content-ir\"` — hosts key their capture stores on it. */\n  source: \"content-ir\";\n  message: string;\n  name?: string;\n  stack?: string;\n  /** Free-form grouping key (the host's `relation`), e.g. `\"partial-kind\"`. */\n  relation?: string;\n  raw?: unknown;\n}\n\nexport type ContentIrErrorReporter = (report: ContentIrErrorReport) => void;\n\n/** The default when a host binds nothing: never silent. */\nexport const consoleErrorReporter: ContentIrErrorReporter = (report) => {\n  console.error(`[content-ir] ${report.message}`, report.raw ?? \"\");\n};\n","/**\n * The Shape System component RESOLVER (rulings R1 + R6): (kind, platform,\n * role) → component, with two tiers:\n *\n * - eager: a COMPILED bootstrap the host ships in its bundle — the\n *   trusted-at-boot floor, available at import so the render seam can gate\n *   synchronously from the first streamed byte.\n * - warm:  one `content_ir.kind_component` list fetch per app session\n *   (`ensureWarm`). A DB row for a (kind, platform, role) OVERRIDES the\n *   compiled entry once warm; the compiled floor keeps answering until then\n *   (and forever, on DB failure).\n *\n * Resolution is SYNCHRONOUS (the render seam calls it per block); the only\n * async work is the loading, off the render path.\n *\n * WHAT MOVED AND WHY. This class was matrx-frontend's `ComponentRegistry`. It\n * is a large part of why a second UI could not render a kind: every tier rule,\n * every repaint counter, every dedupe latch lived in one app. Nothing about it\n * is Next.js, Redux, or Supabase — the only host-specific parts were the two\n * loaders and the error sink, which are now constructor arguments.\n */\n\nimport type { ContentIrErrorReporter } from \"../host/error-report\";\nimport { consoleErrorReporter } from \"../host/error-report\";\nimport type {\n  ComponentResolution,\n  ComponentResolutionSource,\n  ComponentRole,\n  KindComponentRow,\n  SystemComponentEntry,\n} from \"./component-resolution.types\";\n\nexport interface ComponentResolverOptions {\n  /**\n   * The compiled bootstrap, as a THUNK resolved on first use: a host's system\n   * component table is often mid-initialization when this module evaluates\n   * (matrx-frontend's registry cluster has a deliberate import cycle).\n   */\n  compiledEntries?: () => SystemComponentEntry[];\n  /** The warm/refresh list load — every `kind_component` row the user may see. */\n  loadAll?: () => Promise<KindComponentRow[]>;\n  /** The eager single-kind load fired the moment a kind is identified mid-stream. */\n  loadForKind?: (kind: string, platform: string) => Promise<KindComponentRow[]>;\n  /** Where recovery screams land. Defaults to `console.error`, never silence. */\n  reportError?: ContentIrErrorReporter;\n  /** Clock seam — the refresh rate limiter. Defaults to `Date.now`. */\n  now?: () => number;\n}\n\n/** Unit separator — a character no kind slug, platform, or role can contain. */\nconst KEY_SEPARATOR = String.fromCharCode(1);\n\nfunction keyOf(kind: string, platform: string, role: string): string {\n  return `${kind}${KEY_SEPARATOR}${platform}${KEY_SEPARATOR}${role}`;\n}\n\nfunction describe(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** Error-shaped fields, spread-safe under `exactOptionalPropertyTypes`. */\nfunction errorFields(error: unknown): { name?: string; stack?: string } {\n  if (!(error instanceof Error)) return {};\n  return {\n    name: error.name,\n    ...(error.stack === undefined ? {} : { stack: error.stack }),\n  };\n}\n\nexport class ComponentResolver implements ComponentResolutionSource {\n  private compiled: Map<string, SystemComponentEntry> | null = null;\n  private readonly db = new Map<string, KindComponentRow>();\n  private warmPromise: Promise<void> | null = null;\n  private warmFailureLogged = false;\n  /**\n   * When the last successful wholesale refresh landed, or null for \"never\".\n   * Explicitly nullable rather than 0: with a host-supplied clock that starts\n   * near zero, a `0` sentinel makes the FIRST refresh look rate-limited and\n   * silently skip.\n   */\n  private lastRefreshAt: number | null = null;\n  private refreshPromise: Promise<void> | null = null;\n  private readonly listeners = new Set<() => void>();\n  /**\n   * Cold single-kind fetch dedupe (streaming eager path). In-flight is keyed\n   * by (kind, platform) — the fetch unit; misses are keyed by (kind, platform,\n   * role) so a miss on web/output never suppresses other roles, and CLEARED on\n   * every wholesale refresh (a component created mid-session becomes eagerly\n   * fetchable again — misses are cheap to re-verify).\n   */\n  private readonly coldInFlight = new Set<string>();\n  private readonly coldMisses = new Set<string>();\n  /** Monotonic db-tier version — the repaint hook's snapshot key. */\n  private version = 0;\n  /** Per-kind versions + listeners (granular repaint) + wholesale epoch. */\n  private readonly kindVersions = new Map<string, number>();\n  private readonly kindListeners = new Map<string, Set<() => void>>();\n  private epoch = 0;\n\n  private readonly reportError: ContentIrErrorReporter;\n  private readonly now: () => number;\n\n  private readonly options: ComponentResolverOptions;\n\n  // Explicit field, not a parameter property: consumers compile this source\n  // directly, and a strict host (the dashboard) sets `erasableSyntaxOnly`,\n  // under which parameter properties are a hard error.\n  constructor(options: ComponentResolverOptions = {}) {\n    this.options = options;\n    this.reportError = options.reportError ?? consoleErrorReporter;\n    this.now = options.now ?? (() => Date.now());\n  }\n\n  private compiledMap(): Map<string, SystemComponentEntry> {\n    if (!this.compiled) {\n      this.compiled = new Map();\n      for (const entry of this.options.compiledEntries?.() ?? []) {\n        this.compiled.set(keyOf(entry.kind, entry.platform, entry.role), entry);\n      }\n    }\n    return this.compiled;\n  }\n\n  /**\n   * Synchronous resolve — the render seam's per-block call. DB override first\n   * (once warm), compiled floor second, null for unknown.\n   */\n  resolve(\n    kind: string,\n    platform: string,\n    role: ComponentRole,\n  ): ComponentResolution | null {\n    const key = keyOf(kind, platform, role);\n\n    const dbRow = this.db.get(key);\n    if (dbRow) {\n      return {\n        componentKey: dbRow.componentKey,\n        source: dbRow.source,\n        config: dbRow.config,\n        isActive: dbRow.isActive,\n        resolvedBy: \"db\",\n        componentSource: dbRow.componentSource,\n        propsTransform: dbRow.propsTransform,\n        hasComponentSource:\n          dbRow.hasComponentSource ??\n          Boolean(dbRow.componentSource && dbRow.componentSource.trim()),\n        pinnedKindVersion: dbRow.pinnedKindVersion,\n        updatedAt: dbRow.updatedAt,\n        createdBy: dbRow.createdBy,\n      };\n    }\n\n    const compiledEntry = this.compiledMap().get(key);\n    if (compiledEntry) {\n      return {\n        componentKey: compiledEntry.componentKey,\n        source: compiledEntry.source,\n        config: compiledEntry.config,\n        isActive: true, // trusted at bootstrap (R6)\n        resolvedBy: \"compiled\",\n        componentSource: null,\n        propsTransform: null,\n        hasComponentSource: false,\n        pinnedKindVersion: null,\n        updatedAt: null,\n        createdBy: null,\n      };\n    }\n\n    return null;\n  }\n\n  /** R6 floor check: compiled-bootstrap membership = always render-trusted. */\n  hasCompiled(kind: string, platform: string, role: ComponentRole): boolean {\n    return this.compiledMap().has(keyOf(kind, platform, role));\n  }\n\n  /**\n   * Pure ingest — the warm landing point and the unit-test seam. First row per\n   * key wins: rows arrive is_default-first / sort_order-asc from the source.\n   */\n  ingestDbRows(rows: readonly KindComponentRow[]): void {\n    const changedKinds = new Set<string>();\n    for (const row of rows) {\n      const key = keyOf(row.kind, row.platform, row.role);\n      if (!this.db.has(key)) {\n        this.db.set(key, row);\n        changedKinds.add(row.kind);\n      }\n    }\n    // Warm/cold ingest is a resolver-tier change the render seam must see — a\n    // db component landing AFTER a region finalized re-runs the route via the\n    // repaint hook. Per-kind bumps keep the repaint granular.\n    if (changedKinds.size > 0) {\n      for (const kind of changedKinds) this.bumpKind(kind);\n      this.notifyChanged();\n    }\n  }\n\n  /**\n   * Refresh landing point: REPLACE the db tier wholesale (same\n   * first-row-per-key contract as {@link ingestDbRows}) so edits, deletions,\n   * and is_active flips all take effect. Always notifies.\n   */\n  replaceDbRows(rows: readonly KindComponentRow[]): void {\n    this.db.clear();\n    // Wholesale invalidation: every recorded miss is stale (a component\n    // created mid-session must become eagerly fetchable again).\n    this.coldMisses.clear();\n    for (const row of rows) {\n      const key = keyOf(row.kind, row.platform, row.role);\n      if (!this.db.has(key)) this.db.set(key, row);\n    }\n    // A wholesale replace ALWAYS notifies (deletions/flips count too), and\n    // bumps the epoch so EVERY per-kind subscriber re-snapshots.\n    this.epoch += 1;\n    for (const set of this.kindListeners.values()) {\n      for (const listener of set) listener();\n    }\n    this.notifyChanged();\n  }\n\n  getVersion(): number {\n    return this.version;\n  }\n\n  getKindVersion(kind: string): number {\n    return this.epoch + (this.kindVersions.get(kind) ?? 0);\n  }\n\n  subscribeKind(kind: string, listener: () => void): () => void {\n    const set = this.kindListeners.get(kind) ?? new Set<() => void>();\n    set.add(listener);\n    this.kindListeners.set(kind, set);\n    return () => {\n      set.delete(listener);\n      if (set.size === 0) this.kindListeners.delete(kind);\n    };\n  }\n\n  subscribe(listener: () => void): () => void {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  private bumpKind(kind: string): void {\n    this.kindVersions.set(kind, (this.kindVersions.get(kind) ?? 0) + 1);\n    const listeners = this.kindListeners.get(kind);\n    if (listeners) for (const listener of listeners) listener();\n  }\n\n  private notifyChanged(): void {\n    this.version += 1;\n    for (const listener of this.listeners) listener();\n  }\n\n  /**\n   * A warm metadata shell is resolved enough for routing, but not for the\n   * host's db-component renderer. Its body must still come from the cold\n   * single-kind loader.\n   */\n  private needsColdFetch(\n    kind: string,\n    platform: string,\n    role: ComponentRole,\n  ): boolean {\n    const resolution = this.resolve(kind, platform, role);\n    return (\n      resolution === null ||\n      (resolution.resolvedBy === \"db\" &&\n        resolution.hasComponentSource &&\n        resolution.componentSource === null)\n    );\n  }\n\n  /**\n   * Cold rows are the authoritative heavy form of warm metadata shells. Keep\n   * the same first-row-per-key winner contract, but replace an existing shell\n   * so `componentSource` / `propsTransform` can land and repaint the kind.\n   */\n  private ingestColdRows(rows: readonly KindComponentRow[]): void {\n    const winners = new Map<string, KindComponentRow>();\n    for (const row of rows) {\n      const key = keyOf(row.kind, row.platform, row.role);\n      if (!winners.has(key)) winners.set(key, row);\n    }\n    if (winners.size === 0) return;\n\n    const changedKinds = new Set<string>();\n    for (const [key, row] of winners) {\n      this.db.set(key, row);\n      changedKinds.add(row.kind);\n    }\n    for (const kind of changedKinds) this.bumpKind(kind);\n    this.notifyChanged();\n  }\n\n  /**\n   * The eager lightweight single-kind fetch (streaming path): the moment a\n   * cloud kind is identified mid-stream, pull ONLY that kind's resolver rows\n   * and ingest them so {@link resolve} can answer before — or shortly after —\n   * the region completes. Deduped in-flight and by known-miss. Fire-and-forget;\n   * failures are loud (the warm list remains the backstop).\n   */\n  requestComponent(kind: string, platform: string, role: ComponentRole): void {\n    const loadForKind = this.options.loadForKind;\n    if (!loadForKind) return;\n    if (!this.needsColdFetch(kind, platform, role)) return;\n    const missKey = keyOf(kind, platform, role);\n    const flightKey = `${kind}${KEY_SEPARATOR}${platform}`;\n    if (this.coldInFlight.has(flightKey) || this.coldMisses.has(missKey)) {\n      return;\n    }\n    this.coldInFlight.add(flightKey);\n\n    void (async () => {\n      try {\n        this.ingestColdRows(await loadForKind(kind, platform));\n        // Record the miss for exactly the requested (kind, platform, role) —\n        // rows may exist for OTHER roles on this platform; those must not be\n        // suppressed, and this one must not be re-fetched until a refresh.\n        if (this.needsColdFetch(kind, platform, role)) {\n          this.coldMisses.add(missKey);\n        }\n      } catch (error) {\n        this.reportError({\n          source: \"content-ir\",\n          message: `component-resolver cold fetch failed for \"${kind}\": ${describe(error)}`,\n          ...errorFields(error),\n          raw: error,\n        });\n      } finally {\n        this.coldInFlight.delete(flightKey);\n      }\n    })();\n  }\n\n  /**\n   * Refresh-on-view: re-fetch the warm list and REPLACE the db tier, so an\n   * edited `source='db'` component (its `updated_at` bump re-keys the host's\n   * compile cache) renders fresh on the next view. Deduped in-flight and\n   * rate-limited by `maxAgeMs` (default 10s) — mounting several previews costs\n   * one fetch. Server-side edits do NOT push to open clients; the contract is\n   * refresh-on-view via this call.\n   */\n  refresh(maxAgeMs = 10_000): Promise<void> {\n    const loadAll = this.options.loadAll;\n    if (!loadAll) return Promise.resolve();\n    if (this.refreshPromise) return this.refreshPromise;\n    if (\n      this.lastRefreshAt !== null &&\n      this.now() - this.lastRefreshAt < maxAgeMs\n    ) {\n      return Promise.resolve();\n    }\n    // Any refresh intent invalidates recorded misses immediately (also cleared\n    // in replaceDbRows when the fetch lands) — cheap to re-verify.\n    this.coldMisses.clear();\n\n    this.refreshPromise = loadAll()\n      .then((rows) => {\n        this.lastRefreshAt = this.now();\n        this.replaceDbRows(rows);\n      })\n      .catch((error: unknown) => {\n        // Loud recovery: the current tier keeps answering; a refresh failure is\n        // a real defect (same posture as the warm loader).\n        this.reportError({\n          source: \"content-ir\",\n          message: `component-resolver refresh failed (current resolver tier still serving): ${describe(error)}`,\n          ...errorFields(error),\n          raw: error,\n        });\n      })\n      .finally(() => {\n        this.refreshPromise = null;\n      });\n    return this.refreshPromise;\n  }\n\n  /** One list fetch per app session; failed loads retry on the next call. */\n  ensureWarm(): Promise<void> {\n    const loadAll = this.options.loadAll;\n    if (!loadAll) return Promise.resolve();\n    if (!this.warmPromise) {\n      this.warmPromise = loadAll()\n        .then((rows) => {\n          this.ingestDbRows(rows);\n        })\n        .catch((error: unknown) => {\n          // Loud recovery: the compiled floor keeps rendering, but a warm\n          // failure is a real defect — one console scream (first failure) plus\n          // a structured report per attempt, then retryable.\n          const message = `component-resolver warm load failed (compiled bootstrap still serving): ${describe(error)}`;\n          if (!this.warmFailureLogged) {\n            this.warmFailureLogged = true;\n            console.error(`[content-ir] ${message}`);\n          }\n          this.reportError({\n            source: \"content-ir\",\n            message,\n            ...errorFields(error),\n            raw: error,\n          });\n          this.warmPromise = null;\n        });\n    }\n    return this.warmPromise;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/resolver.d.cts

@@ -0,0 +1,133 @@
+import { C as ComponentResolutionSource, S as SystemComponentEntry, K as KindComponentRow, b as ContentIrErrorReporter, c as ComponentRole, a as ComponentResolution } from './component-resolution.types-fvR92hW7.cjs';
+export { J as JsonObject } from './component-resolution.types-fvR92hW7.cjs';
+
+/**
+ * The Shape System component RESOLVER (rulings R1 + R6): (kind, platform,
+ * role) → component, with two tiers:
+ *
+ * - eager: a COMPILED bootstrap the host ships in its bundle — the
+ *   trusted-at-boot floor, available at import so the render seam can gate
+ *   synchronously from the first streamed byte.
+ * - warm:  one `content_ir.kind_component` list fetch per app session
+ *   (`ensureWarm`). A DB row for a (kind, platform, role) OVERRIDES the
+ *   compiled entry once warm; the compiled floor keeps answering until then
+ *   (and forever, on DB failure).
+ *
+ * Resolution is SYNCHRONOUS (the render seam calls it per block); the only
+ * async work is the loading, off the render path.
+ *
+ * WHAT MOVED AND WHY. This class was matrx-frontend's `ComponentRegistry`. It
+ * is a large part of why a second UI could not render a kind: every tier rule,
+ * every repaint counter, every dedupe latch lived in one app. Nothing about it
+ * is Next.js, Redux, or Supabase — the only host-specific parts were the two
+ * loaders and the error sink, which are now constructor arguments.
+ */
+
+interface ComponentResolverOptions {
+    /**
+     * The compiled bootstrap, as a THUNK resolved on first use: a host's system
+     * component table is often mid-initialization when this module evaluates
+     * (matrx-frontend's registry cluster has a deliberate import cycle).
+     */
+    compiledEntries?: () => SystemComponentEntry[];
+    /** The warm/refresh list load — every `kind_component` row the user may see. */
+    loadAll?: () => Promise<KindComponentRow[]>;
+    /** The eager single-kind load fired the moment a kind is identified mid-stream. */
+    loadForKind?: (kind: string, platform: string) => Promise<KindComponentRow[]>;
+    /** Where recovery screams land. Defaults to `console.error`, never silence. */
+    reportError?: ContentIrErrorReporter;
+    /** Clock seam — the refresh rate limiter. Defaults to `Date.now`. */
+    now?: () => number;
+}
+declare class ComponentResolver implements ComponentResolutionSource {
+    private compiled;
+    private readonly db;
+    private warmPromise;
+    private warmFailureLogged;
+    /**
+     * When the last successful wholesale refresh landed, or null for "never".
+     * Explicitly nullable rather than 0: with a host-supplied clock that starts
+     * near zero, a `0` sentinel makes the FIRST refresh look rate-limited and
+     * silently skip.
+     */
+    private lastRefreshAt;
+    private refreshPromise;
+    private readonly listeners;
+    /**
+     * Cold single-kind fetch dedupe (streaming eager path). In-flight is keyed
+     * by (kind, platform) — the fetch unit; misses are keyed by (kind, platform,
+     * role) so a miss on web/output never suppresses other roles, and CLEARED on
+     * every wholesale refresh (a component created mid-session becomes eagerly
+     * fetchable again — misses are cheap to re-verify).
+     */
+    private readonly coldInFlight;
+    private readonly coldMisses;
+    /** Monotonic db-tier version — the repaint hook's snapshot key. */
+    private version;
+    /** Per-kind versions + listeners (granular repaint) + wholesale epoch. */
+    private readonly kindVersions;
+    private readonly kindListeners;
+    private epoch;
+    private readonly reportError;
+    private readonly now;
+    private readonly options;
+    constructor(options?: ComponentResolverOptions);
+    private compiledMap;
+    /**
+     * Synchronous resolve — the render seam's per-block call. DB override first
+     * (once warm), compiled floor second, null for unknown.
+     */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** R6 floor check: compiled-bootstrap membership = always render-trusted. */
+    hasCompiled(kind: string, platform: string, role: ComponentRole): boolean;
+    /**
+     * Pure ingest — the warm landing point and the unit-test seam. First row per
+     * key wins: rows arrive is_default-first / sort_order-asc from the source.
+     */
+    ingestDbRows(rows: readonly KindComponentRow[]): void;
+    /**
+     * Refresh landing point: REPLACE the db tier wholesale (same
+     * first-row-per-key contract as {@link ingestDbRows}) so edits, deletions,
+     * and is_active flips all take effect. Always notifies.
+     */
+    replaceDbRows(rows: readonly KindComponentRow[]): void;
+    getVersion(): number;
+    getKindVersion(kind: string): number;
+    subscribeKind(kind: string, listener: () => void): () => void;
+    subscribe(listener: () => void): () => void;
+    private bumpKind;
+    private notifyChanged;
+    /**
+     * A warm metadata shell is resolved enough for routing, but not for the
+     * host's db-component renderer. Its body must still come from the cold
+     * single-kind loader.
+     */
+    private needsColdFetch;
+    /**
+     * Cold rows are the authoritative heavy form of warm metadata shells. Keep
+     * the same first-row-per-key winner contract, but replace an existing shell
+     * so `componentSource` / `propsTransform` can land and repaint the kind.
+     */
+    private ingestColdRows;
+    /**
+     * The eager lightweight single-kind fetch (streaming path): the moment a
+     * cloud kind is identified mid-stream, pull ONLY that kind's resolver rows
+     * and ingest them so {@link resolve} can answer before — or shortly after —
+     * the region completes. Deduped in-flight and by known-miss. Fire-and-forget;
+     * failures are loud (the warm list remains the backstop).
+     */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /**
+     * Refresh-on-view: re-fetch the warm list and REPLACE the db tier, so an
+     * edited `source='db'` component (its `updated_at` bump re-keys the host's
+     * compile cache) renders fresh on the next view. Deduped in-flight and
+     * rate-limited by `maxAgeMs` (default 10s) — mounting several previews costs
+     * one fetch. Server-side edits do NOT push to open clients; the contract is
+     * refresh-on-view via this call.
+     */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** One list fetch per app session; failed loads retry on the next call. */
+    ensureWarm(): Promise<void>;
+}
+
+export { ComponentResolution, ComponentResolutionSource, ComponentResolver, type ComponentResolverOptions, ComponentRole, KindComponentRow, SystemComponentEntry };

package/dist/resolver.d.ts

@@ -0,0 +1,133 @@
+import { C as ComponentResolutionSource, S as SystemComponentEntry, K as KindComponentRow, b as ContentIrErrorReporter, c as ComponentRole, a as ComponentResolution } from './component-resolution.types-fvR92hW7.js';
+export { J as JsonObject } from './component-resolution.types-fvR92hW7.js';
+
+/**
+ * The Shape System component RESOLVER (rulings R1 + R6): (kind, platform,
+ * role) → component, with two tiers:
+ *
+ * - eager: a COMPILED bootstrap the host ships in its bundle — the
+ *   trusted-at-boot floor, available at import so the render seam can gate
+ *   synchronously from the first streamed byte.
+ * - warm:  one `content_ir.kind_component` list fetch per app session
+ *   (`ensureWarm`). A DB row for a (kind, platform, role) OVERRIDES the
+ *   compiled entry once warm; the compiled floor keeps answering until then
+ *   (and forever, on DB failure).
+ *
+ * Resolution is SYNCHRONOUS (the render seam calls it per block); the only
+ * async work is the loading, off the render path.
+ *
+ * WHAT MOVED AND WHY. This class was matrx-frontend's `ComponentRegistry`. It
+ * is a large part of why a second UI could not render a kind: every tier rule,
+ * every repaint counter, every dedupe latch lived in one app. Nothing about it
+ * is Next.js, Redux, or Supabase — the only host-specific parts were the two
+ * loaders and the error sink, which are now constructor arguments.
+ */
+
+interface ComponentResolverOptions {
+    /**
+     * The compiled bootstrap, as a THUNK resolved on first use: a host's system
+     * component table is often mid-initialization when this module evaluates
+     * (matrx-frontend's registry cluster has a deliberate import cycle).
+     */
+    compiledEntries?: () => SystemComponentEntry[];
+    /** The warm/refresh list load — every `kind_component` row the user may see. */
+    loadAll?: () => Promise<KindComponentRow[]>;
+    /** The eager single-kind load fired the moment a kind is identified mid-stream. */
+    loadForKind?: (kind: string, platform: string) => Promise<KindComponentRow[]>;
+    /** Where recovery screams land. Defaults to `console.error`, never silence. */
+    reportError?: ContentIrErrorReporter;
+    /** Clock seam — the refresh rate limiter. Defaults to `Date.now`. */
+    now?: () => number;
+}
+declare class ComponentResolver implements ComponentResolutionSource {
+    private compiled;
+    private readonly db;
+    private warmPromise;
+    private warmFailureLogged;
+    /**
+     * When the last successful wholesale refresh landed, or null for "never".
+     * Explicitly nullable rather than 0: with a host-supplied clock that starts
+     * near zero, a `0` sentinel makes the FIRST refresh look rate-limited and
+     * silently skip.
+     */
+    private lastRefreshAt;
+    private refreshPromise;
+    private readonly listeners;
+    /**
+     * Cold single-kind fetch dedupe (streaming eager path). In-flight is keyed
+     * by (kind, platform) — the fetch unit; misses are keyed by (kind, platform,
+     * role) so a miss on web/output never suppresses other roles, and CLEARED on
+     * every wholesale refresh (a component created mid-session becomes eagerly
+     * fetchable again — misses are cheap to re-verify).
+     */
+    private readonly coldInFlight;
+    private readonly coldMisses;
+    /** Monotonic db-tier version — the repaint hook's snapshot key. */
+    private version;
+    /** Per-kind versions + listeners (granular repaint) + wholesale epoch. */
+    private readonly kindVersions;
+    private readonly kindListeners;
+    private epoch;
+    private readonly reportError;
+    private readonly now;
+    private readonly options;
+    constructor(options?: ComponentResolverOptions);
+    private compiledMap;
+    /**
+     * Synchronous resolve — the render seam's per-block call. DB override first
+     * (once warm), compiled floor second, null for unknown.
+     */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** R6 floor check: compiled-bootstrap membership = always render-trusted. */
+    hasCompiled(kind: string, platform: string, role: ComponentRole): boolean;
+    /**
+     * Pure ingest — the warm landing point and the unit-test seam. First row per
+     * key wins: rows arrive is_default-first / sort_order-asc from the source.
+     */
+    ingestDbRows(rows: readonly KindComponentRow[]): void;
+    /**
+     * Refresh landing point: REPLACE the db tier wholesale (same
+     * first-row-per-key contract as {@link ingestDbRows}) so edits, deletions,
+     * and is_active flips all take effect. Always notifies.
+     */
+    replaceDbRows(rows: readonly KindComponentRow[]): void;
+    getVersion(): number;
+    getKindVersion(kind: string): number;
+    subscribeKind(kind: string, listener: () => void): () => void;
+    subscribe(listener: () => void): () => void;
+    private bumpKind;
+    private notifyChanged;
+    /**
+     * A warm metadata shell is resolved enough for routing, but not for the
+     * host's db-component renderer. Its body must still come from the cold
+     * single-kind loader.
+     */
+    private needsColdFetch;
+    /**
+     * Cold rows are the authoritative heavy form of warm metadata shells. Keep
+     * the same first-row-per-key winner contract, but replace an existing shell
+     * so `componentSource` / `propsTransform` can land and repaint the kind.
+     */
+    private ingestColdRows;
+    /**
+     * The eager lightweight single-kind fetch (streaming path): the moment a
+     * cloud kind is identified mid-stream, pull ONLY that kind's resolver rows
+     * and ingest them so {@link resolve} can answer before — or shortly after —
+     * the region completes. Deduped in-flight and by known-miss. Fire-and-forget;
+     * failures are loud (the warm list remains the backstop).
+     */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /**
+     * Refresh-on-view: re-fetch the warm list and REPLACE the db tier, so an
+     * edited `source='db'` component (its `updated_at` bump re-keys the host's
+     * compile cache) renders fresh on the next view. Deduped in-flight and
+     * rate-limited by `maxAgeMs` (default 10s) — mounting several previews costs
+     * one fetch. Server-side edits do NOT push to open clients; the contract is
+     * refresh-on-view via this call.
+     */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** One list fetch per app session; failed loads retry on the next call. */
+    ensureWarm(): Promise<void>;
+}
+
+export { ComponentResolution, ComponentResolutionSource, ComponentResolver, type ComponentResolverOptions, ComponentRole, KindComponentRow, SystemComponentEntry };