@ai-matrx/rich-content 0.0.0 → 0.2.2

package/dist/kinds/react/useIrNode.js

@@ -0,0 +1,46 @@
+"use client";
+import { useRef, useSyncExternalStore } from "react";
+import { irPathKey } from "@ai-matrx/content-ir";
+import { getParseSession } from "@ai-matrx/content-ir";
+const noopSubscribe = () => () => {
+};
+function useIrNode(identity, path) {
+  const pathKey = typeof path === "string" ? path : irPathKey(path);
+  const subscribe = identity ? (onStoreChange) => {
+    const session = getParseSession(identity);
+    if (!session) return () => {
+    };
+    return session.subscribe(pathKey, onStoreChange);
+  } : noopSubscribe;
+  const getSnapshot = () => identity ? getParseSession(identity)?.getNode(pathKey) ?? null : null;
+  return useSyncExternalStore(subscribe, getSnapshot, () => null);
+}
+function useIrNodePaths(identity) {
+  const subscribe = identity ? (onStoreChange) => {
+    const session = getParseSession(identity);
+    if (!session) return () => {
+    };
+    return session.subscribeAny(onStoreChange);
+  } : noopSubscribe;
+  const cache = useRef({
+    key: null,
+    value: EMPTY_PATHS
+  });
+  const getSnapshot = () => {
+    if (!identity) return EMPTY_PATHS;
+    const session = getParseSession(identity);
+    if (!session) return EMPTY_PATHS;
+    const paths = session.listNodes().map((node) => node.pathKey);
+    const key = paths.join("\0");
+    if (key !== cache.current.key) {
+      cache.current = { key, value: paths };
+    }
+    return cache.current.value;
+  };
+  return useSyncExternalStore(subscribe, getSnapshot, () => EMPTY_PATHS);
+}
+const EMPTY_PATHS = [];
+export {
+  useIrNode,
+  useIrNodePaths
+};

package/dist/kinds/react/useLiveJsonRegion.d.ts

@@ -0,0 +1,15 @@
+import type { IrTreeNode } from "@ai-matrx/content-ir";
+import type { CanonicalBlockIR } from "@ai-matrx/content-ir";
+export interface UseLiveJsonRegionOptions {
+    /** Known-context root prediction (e.g. "flashcard_set" for the cards agent). */
+    expectedRootKind?: string;
+    /** True once the source stream has finished — ends the region. */
+    done?: boolean;
+}
+export interface LiveJsonRegion {
+    /** The root kind node — identity bumps on every tree change (COW spine). */
+    rootNode: IrTreeNode | null;
+    /** Current canonical envelope, or null before the region opens. */
+    envelope: CanonicalBlockIR | null;
+}
+export declare function useLiveJsonRegion(identity: string | null, text: string | null | undefined, options?: UseLiveJsonRegionOptions): LiveJsonRegion;

package/dist/kinds/react/useLiveJsonRegion.js

@@ -0,0 +1,84 @@
+"use client";
+import { sessionEnvelope } from "../registry/kind-correctors.js";
+import { useEffect, useRef } from "react";
+import {
+  disposeParseSession,
+  getParseSession,
+  openParseSession
+} from "@ai-matrx/content-ir";
+import { kindRegistry } from "../../host/kind-registry.js";
+import { componentRegistry } from "../../host/component-registry.js";
+import { useIrNode } from "./useIrNode.js";
+function useLiveJsonRegion(identity, text, options) {
+  const openedRef = useRef(null);
+  const fedLenRef = useRef(0);
+  const startedRef = useRef(false);
+  const expectedRootKind = options?.expectedRootKind;
+  const done = options?.done ?? false;
+  useEffect(() => {
+    if (!identity) return;
+    if (openedRef.current !== identity) {
+      if (openedRef.current) disposeParseSession(openedRef.current);
+      openedRef.current = identity;
+      fedLenRef.current = 0;
+      startedRef.current = false;
+      if (expectedRootKind) {
+        void kindRegistry.ensureWarm();
+        void componentRegistry.ensureWarm();
+      }
+      try {
+        openParseSession({
+          identity,
+          schemas: kindRegistry.resolver(),
+          expectedRootKind,
+          onSchemaArrived: (deliver) => kindRegistry.onSchemaArrived(deliver),
+          onEvent: (event) => {
+            if (event.type === "kind_identified" || event.type === "pending_schema") {
+              void kindRegistry.ensureWarm();
+              void componentRegistry.ensureWarm();
+              kindRegistry.requestSchema(event.kind);
+              componentRegistry.requestComponent(event.kind, "web", "output");
+            }
+          }
+        });
+      } catch {
+        return;
+      }
+    }
+    const session = getParseSession(identity);
+    if (!session) return;
+    if (session.isEnded) return;
+    const full = text ?? "";
+    if (!startedRef.current) {
+      const openIndex = full.indexOf("{");
+      if (openIndex === -1) {
+        return;
+      }
+      fedLenRef.current = openIndex;
+      startedRef.current = true;
+    }
+    if (full.length > fedLenRef.current) {
+      session.write(full.slice(fedLenRef.current));
+      fedLenRef.current = full.length;
+      session.flushNotify();
+    }
+    if (done) {
+      session.end();
+      session.flushNotify();
+    }
+  }, [identity, text, done, expectedRootKind]);
+  useEffect(() => {
+    return () => {
+      if (openedRef.current) {
+        disposeParseSession(openedRef.current);
+        openedRef.current = null;
+      }
+    };
+  }, []);
+  const rootNode = useIrNode(identity, "");
+  const envelope = identity && rootNode ? sessionEnvelope(getParseSession(identity)) : null;
+  return { rootNode, envelope };
+}
+export {
+  useLiveJsonRegion
+};

package/dist/kinds/redux/render-block-envelope.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Envelope helpers for hosts (accumulator / splitter / renderers):
+ * reading `metadata.__ir` off render blocks, reconstructing the full source
+ * object (schema values + residues merged back), and the Phase-2 shadow
+ * parity check that proves the kind parser and JSON.parse agree byte-for-
+ * byte on real traffic before any rendering flips.
+ */
+import { readEnvelope } from "@ai-matrx/content-ir";
+export { readEnvelope };
+export declare function sanitizeInboundEnvelopeMetadata(metadata: Record<string, unknown> | null | undefined, context: {
+    blockId: string;
+}): Record<string, unknown> | undefined;
+export { reconstructRegionValue, stripKindDeep } from "@ai-matrx/content-ir";
+export { envelopeMatchesParsedSource } from "@ai-matrx/content-ir/surfaces";

package/dist/kinds/redux/render-block-envelope.js

@@ -0,0 +1,26 @@
+import { readEnvelope } from "@ai-matrx/content-ir";
+import { sanitizeInboundEnvelopeMetadata as sanitizeInboundEnvelopeMetadataPure } from "@ai-matrx/content-ir";
+import { seedEnvelope } from "../registry/region-envelope-memo.js";
+import { captureError } from "../../host/diagnostics.js";
+function sanitizeInboundEnvelopeMetadata(metadata, context) {
+  return sanitizeInboundEnvelopeMetadataPure(metadata, context, {
+    seedEnvelope: (envelope) => seedEnvelope(envelope),
+    reportMalformed: ({ blockId, engine, raw }) => {
+      captureError({
+        source: "content-ir",
+        message: `render_block "${blockId}" carried a malformed metadata.__ir envelope (engine "${engine}") \u2014 dropped before Redux so it can't poison the pipeline`,
+        relation: engine,
+        raw
+      });
+    }
+  });
+}
+import { reconstructRegionValue, stripKindDeep } from "@ai-matrx/content-ir";
+import { envelopeMatchesParsedSource } from "@ai-matrx/content-ir/surfaces";
+export {
+  envelopeMatchesParsedSource,
+  readEnvelope,
+  reconstructRegionValue,
+  sanitizeInboundEnvelopeMetadata,
+  stripKindDeep
+};

package/dist/kinds/registry/kind-correctors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Kind correctors — a registered kind's value made to agree with its own rules BEFORE any
+ * renderer sees it. The client twin of aidream's
+ * `matrx_ai/processing/blocks/kind_correctors.py`.
+ *
+ * `draft_critique` (the Tough Editor) is the first: "the scale mapping is applied by code
+ * from the points, so the score can never disagree with the rubric". A renderer is never the
+ * place to fix it — a kind can be drawn by a compiled bridge, a db component, or the generic
+ * floor, and any one that forgot would show the model's arithmetic.
+ *
+ * THE ONE STEP. Every envelope this app builds comes from one of three kernel constructors —
+ * `envelopeFromCompleteValue` (stored values: reload, partial, nested kinds, XML finalize,
+ * progress data), `normalizeJsonRegion` (complete text: DB-loaded messages, the re-split) and
+ * a `ParseSession`'s `buildEnvelope()` (the live stream, live previews). This module owns the
+ * corrected form of all three, and `kind-correctors.guard.test.ts` refuses any host file that
+ * calls a raw constructor — so a new render path inherits the correction or fails CI.
+ * Direct-object renders (`KindInstanceRender`, the shape preview's "direct" path, every
+ * kind-instance load) correct their value in the host binding, and the db-component reader
+ * corrects whatever still reaches it uncorrected (a pasted block with no envelope).
+ *
+ * NEVER SILENT. A correction travels ON the envelope as a `residue.notices` entry with code
+ * `kind_corrected` — the envelope's own structured-warning channel, so it survives
+ * serialization, persistence and reload — and `kindCorrectionsOf(metadata)` reads those plus
+ * the server's `metadata.kindCorrections`. A corrector that throws leaves the value as written
+ * and says it could not be checked; it never blocks a render.
+ */
+import { envelopeFromCompleteValue as rawEnvelopeFromCompleteValue, normalizeJsonRegion as rawNormalizeJsonRegion, type CanonicalBlockIR } from "@ai-matrx/content-ir";
+/** Block metadata key the SERVER uses for the corrections it made (same as aidream). */
+export declare const KIND_CORRECTIONS_KEY = "kindCorrections";
+/** The `residue.notices` code a client-side correction is recorded under. */
+export declare const KIND_CORRECTED_NOTICE = "kind_corrected";
+export type KindCorrector = (value: Record<string, unknown>) => {
+    value: Record<string, unknown>;
+    corrections: string[];
+};
+/** Register the corrector for one kind (replaces an earlier one for the same kind). */
+export declare function registerKindCorrector(kind: string, corrector: KindCorrector): void;
+export declare function hasKindCorrector(kind: string | null | undefined): boolean;
+/**
+ * The value made to agree with its kind's rules, plus one line per change. Returns the SAME
+ * reference and no lines when there is no corrector or nothing to change.
+ */
+export declare function correctKindValue(kind: string | null | undefined, value: unknown): {
+    value: unknown;
+    corrections: string[];
+};
+/**
+ * The envelope with its COMPLETE root value corrected and each change recorded as a
+ * `kind_corrected` notice. Idempotent (an envelope already carrying the notice, or with
+ * nothing to change, comes back by reference); a streaming root is never touched — half a
+ * value cannot be scored.
+ */
+export declare function correctKindEnvelope<T extends CanonicalBlockIR | null | undefined>(envelope: T): T;
+/** `envelopeFromCompleteValue`, corrected. The only form host code may call. */
+export declare function envelopeFromCompleteValue(...args: Parameters<typeof rawEnvelopeFromCompleteValue>): CanonicalBlockIR;
+/** `normalizeJsonRegion`, corrected. The only form host code may call. */
+export declare function normalizeJsonRegion(...args: Parameters<typeof rawNormalizeJsonRegion>): CanonicalBlockIR;
+/** A `ParseSession`'s envelope, corrected once it is complete. Wrap every `buildEnvelope()`. */
+export declare function sessionEnvelope(session: {
+    buildEnvelope(): CanonicalBlockIR;
+} | null | undefined): CanonicalBlockIR | null;
+/** Every correction a block carries: the server's list plus the envelope's own notices. */
+export declare function kindCorrectionsOf(metadata: Record<string, unknown> | null | undefined): string[];

package/dist/kinds/registry/kind-correctors.js

@@ -0,0 +1,94 @@
+import {
+  envelopeFromCompleteValue as rawEnvelopeFromCompleteValue,
+  normalizeJsonRegion as rawNormalizeJsonRegion,
+  IR_ENVELOPE_KEY,
+  isCanonicalBlockIR
+} from "@ai-matrx/content-ir";
+const KIND_CORRECTIONS_KEY = "kindCorrections";
+const KIND_CORRECTED_NOTICE = "kind_corrected";
+const CORRECTORS_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.kind-correctors");
+const CORRECTORS = globalThis[CORRECTORS_KEY] ??= {};
+function registerKindCorrector(kind, corrector) {
+  CORRECTORS[kind] = corrector;
+}
+function hasKindCorrector(kind) {
+  return typeof kind === "string" && kind in CORRECTORS;
+}
+function correctKindValue(kind, value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { value, corrections: [] };
+  const slug = kind ?? value.__kind;
+  const corrector = typeof slug === "string" ? CORRECTORS[slug] : void 0;
+  if (!corrector) return { value, corrections: [] };
+  try {
+    const out = corrector(value);
+    if (out.corrections.length === 0) return { value, corrections: [] };
+    console.warn(`[content-ir] ${slug} corrected before render: ${out.corrections.join("; ")}`);
+    return { value: out.value, corrections: out.corrections };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[content-ir] ${slug} corrector failed: ${reason} \u2014 shown as written`);
+    return {
+      value,
+      corrections: [`${slug} could not be checked against its own rules (${reason}); shown as written`]
+    };
+  }
+}
+function correctKindEnvelope(envelope) {
+  if (!envelope || !isCanonicalBlockIR(envelope)) return envelope;
+  const root = envelope.root;
+  if (root.status !== "complete" || !hasKindCorrector(root.kind)) return envelope;
+  if (root.residue?.notices?.some((n) => n.code === KIND_CORRECTED_NOTICE)) return envelope;
+  const { value, corrections } = correctKindValue(root.kind, root.value);
+  if (corrections.length === 0) return envelope;
+  const notices = [
+    ...root.residue?.notices ?? [],
+    ...corrections.map((message) => ({ code: KIND_CORRECTED_NOTICE, message }))
+  ];
+  return {
+    ...envelope,
+    root: {
+      ...root,
+      value,
+      residue: {
+        extra: root.residue?.extra ?? null,
+        optionalMissing: root.residue?.optionalMissing ?? null,
+        notices
+      }
+    }
+  };
+}
+function envelopeFromCompleteValue(...args) {
+  return correctKindEnvelope(rawEnvelopeFromCompleteValue(...args));
+}
+function normalizeJsonRegion(...args) {
+  return correctKindEnvelope(rawNormalizeJsonRegion(...args));
+}
+function sessionEnvelope(session) {
+  return session ? correctKindEnvelope(session.buildEnvelope()) : null;
+}
+function kindCorrectionsOf(metadata) {
+  const out = [];
+  const server = metadata?.[KIND_CORRECTIONS_KEY];
+  if (Array.isArray(server)) {
+    for (const line of server) if (typeof line === "string" && line.trim()) out.push(line);
+  }
+  const envelope = metadata?.[IR_ENVELOPE_KEY];
+  if (isCanonicalBlockIR(envelope)) {
+    for (const n of envelope.root.residue?.notices ?? []) {
+      if (n.code === KIND_CORRECTED_NOTICE && !out.includes(n.message)) out.push(n.message);
+    }
+  }
+  return out;
+}
+export {
+  KIND_CORRECTED_NOTICE,
+  KIND_CORRECTIONS_KEY,
+  correctKindEnvelope,
+  correctKindValue,
+  envelopeFromCompleteValue,
+  hasKindCorrector,
+  kindCorrectionsOf,
+  normalizeJsonRegion,
+  registerKindCorrector,
+  sessionEnvelope
+};

package/dist/kinds/registry/legacy-quiz-envelope.d.ts

@@ -0,0 +1 @@
+export * from "@ai-matrx/content-ir/surfaces";

package/dist/kinds/registry/legacy-quiz-envelope.js

@@ -0,0 +1 @@
+export * from "@ai-matrx/content-ir/surfaces";

package/dist/kinds/registry/region-envelope-memo.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Memoized one-shot envelopes for the STATIC path (content-splitter-v2).
+ *
+ * The splitter runs on DB-loaded messages AND on the hot re-split path while
+ * a message streams, so this must be cheap and idempotent:
+ * - The hot splitter normalizes complete JSON only. Terminal renderers can
+ *   explicitly rehydrate interrupted kinds with the same parser as the stream,
+ *   retaining their error status and original bytes after a refresh.
+ * - Results are memoized by source text, so repeated re-splits of the same
+ *   message return the SAME envelope object (reference equality → React
+ *   bail-outs) and never re-parse.
+ *
+ * Phase 5 adds the PERSISTED-envelope seed: envelopes stamped on message
+ * parts at commit time (`core/envelope-cache.ts`) — or arriving pre-built on
+ * server render_blocks — are seeded here by fingerprint. A memo miss then
+ * consults the seed through `normalizeJsonRegion`'s `existing` fast path
+ * (`reuseEnvelopeIfCurrent`: exact fingerprint match of the region source),
+ * so a reload reuses the stream's envelope BY REFERENCE instead of parsing.
+ */
+import { type CanonicalBlockIR } from "@ai-matrx/content-ir";
+/**
+ * Seed a single already-validated envelope (e.g. a server render_block's
+ * `metadata.__ir` accepted by `sanitizeInboundEnvelopeMetadata`). Incomplete
+ * envelopes are ignored — they can never be reused.
+ */
+export declare function seedEnvelope(envelope: CanonicalBlockIR): void;
+/**
+ * Seed every envelope from a message part's persisted `metadata.__ir` cache
+ * (the `IrEnvelopeCache` stamped by `assembleMessageParts`). Call from the
+ * read boundaries that consume text parts — the subsequent splitter pass then
+ * reuses the persisted envelopes instead of re-parsing. Returns the number of
+ * envelopes seeded.
+ *
+ * A present-but-malformed cache is a write-side bug (only our commit path and
+ * aidream write this key) — it seeds NOTHING and screams via captureError,
+ * never poisoning the pipeline with half-trusted envelopes.
+ */
+export declare function seedPersistedEnvelopeCache(metadata: Record<string, unknown> | null | undefined): number;
+export declare function memoizedRegionEnvelope(source: string, options?: {
+    allowTerminalError?: boolean;
+}): CanonicalBlockIR | null;
+/** Merge an envelope into a block's metadata (no-op when not attachable). */
+export declare function withIrEnvelope(source: string, metadata: Record<string, unknown> | undefined, options?: {
+    allowTerminalError?: boolean;
+}): Record<string, unknown> | undefined;

package/dist/kinds/registry/region-envelope-memo.js

@@ -0,0 +1,94 @@
+import { IR_ENVELOPE_KEY } from "@ai-matrx/content-ir";
+import { isIrEnvelopeCache } from "@ai-matrx/content-ir";
+import { fingerprintText } from "@ai-matrx/content-ir";
+import { captureError } from "../../host/diagnostics.js";
+import { kindRegistry } from "../../host/kind-registry.js";
+import { componentRegistry } from "../../host/component-registry.js";
+import { normalizeJsonRegion } from "./kind-correctors.js";
+import { canonicalizeCompletedLegacyQuizEnvelope } from "./legacy-quiz-envelope.js";
+const memo = /* @__PURE__ */ new Map();
+const MEMO_CAP = 200;
+const seededByFingerprint = /* @__PURE__ */ new Map();
+const SEED_CAP = 300;
+const seenSeedSources = /* @__PURE__ */ new WeakSet();
+function seedOne(envelope) {
+  if (envelope.root.status !== "complete") return;
+  if (seededByFingerprint.size >= SEED_CAP) seededByFingerprint.clear();
+  seededByFingerprint.set(envelope.fingerprint, envelope);
+}
+function seedEnvelope(envelope) {
+  if (seenSeedSources.has(envelope)) return;
+  seenSeedSources.add(envelope);
+  seedOne(envelope);
+}
+function seedPersistedEnvelopeCache(metadata) {
+  const candidate = metadata?.[IR_ENVELOPE_KEY];
+  if (candidate === void 0 || candidate === null) return 0;
+  if (typeof candidate !== "object") return 0;
+  if (seenSeedSources.has(candidate)) return 0;
+  seenSeedSources.add(candidate);
+  if (!isIrEnvelopeCache(candidate)) {
+    captureError({
+      source: "content-ir",
+      message: "persisted metadata.__ir envelope cache failed validation \u2014 ignored (no envelopes seeded); the writer that stamped it has a bug",
+      raw: candidate
+    });
+    return 0;
+  }
+  const envelopes = Object.values(candidate.blocks);
+  for (const envelope of envelopes) seedOne(envelope);
+  return envelopes.length;
+}
+function seededEnvelopeFor(source) {
+  if (seededByFingerprint.size === 0) return void 0;
+  return seededByFingerprint.get(fingerprintText(source));
+}
+function looksLikeCompleteJsonObject(trimmed) {
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return false;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+  } catch {
+    return false;
+  }
+}
+function memoizedRegionEnvelope(source, options = {}) {
+  const trimmed = source.trim();
+  if (!trimmed.startsWith("{")) return null;
+  const cached = memo.get(source);
+  if (cached && (cached.root.status === "complete" || options.allowTerminalError))
+    return cached;
+  const completeJson = looksLikeCompleteJsonObject(trimmed);
+  if (!completeJson && (!options.allowTerminalError || !trimmed.includes("__kind")))
+    return null;
+  const parseSource = source;
+  const existing = seededEnvelopeFor(parseSource);
+  const parsedEnvelope = normalizeJsonRegion(parseSource, {
+    schemas: kindRegistry.resolver(),
+    existing
+  });
+  const envelope = parsedEnvelope === existing ? parsedEnvelope : canonicalizeCompletedLegacyQuizEnvelope(parsedEnvelope, parseSource);
+  if (!completeJson && !envelope.root.kind) return null;
+  if (envelope.root.kind) {
+    void kindRegistry.ensureWarm();
+    void componentRegistry.ensureWarm();
+  }
+  const rootKind = envelope.root.kind;
+  const schemaStillUnknown = envelope.root.kindState === "pending_schema" || (envelope.root.kindState === "raw" || envelope.root.kindState === "unverified") && !!rootKind && kindRegistry.getSchema(rootKind) === void 0;
+  if (!schemaStillUnknown) {
+    if (memo.size >= MEMO_CAP) memo.clear();
+    memo.set(source, envelope);
+  }
+  return envelope;
+}
+function withIrEnvelope(source, metadata, options = {}) {
+  const envelope = memoizedRegionEnvelope(source, options);
+  if (!envelope) return metadata;
+  return { ...metadata ?? {}, [IR_ENVELOPE_KEY]: envelope };
+}
+export {
+  memoizedRegionEnvelope,
+  seedEnvelope,
+  seedPersistedEnvelopeCache,
+  withIrEnvelope
+};

package/dist/kinds/registry/registry-debug.d.ts

@@ -0,0 +1,38 @@
+/**
+ * THE INSTRUMENT — a read-only snapshot of the component resolver's own state,
+ * on the page, in production.
+ *
+ * WHY THIS EXISTS. Between 2026-09-13 and 2026-09-14, four lanes chased one
+ * live defect: on `/shapes/<kind>/instances` a reader was handed the platform's
+ * bundled component while their organization's authored one was already in the
+ * browser. Every lane reasoned from tests and server logs because nobody could
+ * see what the resolver actually held at the moment of the wrong render, and
+ * three of the resulting fixes were proven by a clean-root test and disproven
+ * by production. The missing thing was never analysis, it was an instrument.
+ *
+ * So: with `?matrxKindDebug=1` on any page (or once per tab, after the flag has
+ * been used once), `window.__matrxKindRegistryDebug(kind?)` answers with what
+ * the resolver holds RIGHT NOW — which tier answered, whether a body is bound,
+ * whether the kind's read was refused, whether the warm list has landed, and
+ * the repaint counter the render seam keys on.
+ *
+ * Rules it keeps:
+ *  - READ-ONLY. It resolves, counts and copies; it never fetches, ingests,
+ *    clears a verdict or mutates a registry. Calling it cannot change a render.
+ *  - NEVER THROWS. Every field is guarded; a field it cannot read comes back
+ *    `null` rather than taking the page down.
+ *  - NO PAYLOADS. Component bodies are reported as LENGTHS, never as text, and
+ *    no kind instance value is read at all — this is registry state, not data.
+ *  - OFF BY DEFAULT. No flag, no global: `window.__matrxKindRegistryDebug` is
+ *    simply absent, so nothing ships an always-on hook into a reader's page.
+ */
+import type { RichContentComponentRegistry as ComponentRegistry } from "../../host/types.js";
+/** Query flag that arms the snapshot: `?matrxKindDebug=1`. */
+export declare const KIND_REGISTRY_DEBUG_FLAG = "matrxKindDebug";
+/** The global the flag installs. Named once, here. */
+export declare const KIND_REGISTRY_DEBUG_GLOBAL = "__matrxKindRegistryDebug";
+/**
+ * Install the snapshot global when the flag is armed. Idempotent, and a no-op
+ * on the server and on every un-flagged page.
+ */
+export declare function installKindRegistryDebug(registry: ComponentRegistry): void;

package/dist/kinds/registry/registry-debug.js

@@ -0,0 +1,39 @@
+"use client";
+const KIND_REGISTRY_DEBUG_FLAG = "matrxKindDebug";
+const KIND_REGISTRY_DEBUG_GLOBAL = "__matrxKindRegistryDebug";
+const DEBUG_LATCH_KEY = "matrx:kind-registry-debug";
+function armed() {
+  if (typeof window === "undefined") return false;
+  try {
+    const flag = new URLSearchParams(window.location.search).get(
+      KIND_REGISTRY_DEBUG_FLAG
+    );
+    if (flag !== null && flag !== "0" && flag !== "false") {
+      try {
+        window.sessionStorage.setItem(DEBUG_LATCH_KEY, "1");
+      } catch {
+      }
+      return true;
+    }
+    return window.sessionStorage.getItem(DEBUG_LATCH_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+function installKindRegistryDebug(registry) {
+  if (!armed()) return;
+  const host = window;
+  if (typeof host[KIND_REGISTRY_DEBUG_GLOBAL] === "function") return;
+  host[KIND_REGISTRY_DEBUG_GLOBAL] = (kind) => {
+    try {
+      return registry.debugSnapshot(kind ?? null);
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  };
+}
+export {
+  KIND_REGISTRY_DEBUG_FLAG,
+  KIND_REGISTRY_DEBUG_GLOBAL,
+  installKindRegistryDebug
+};

package/dist/markdown-core/MarkdownCore.d.ts

@@ -0,0 +1,6 @@
+import type { MarkdownCoreProps } from "./markdown-core-types.js";
+export type { MarkdownCoreProps, MarkdownPreset } from "./markdown-core-types.js";
+export declare function MarkdownCoreLoading({ error }: {
+    error?: Error | null;
+}): import("react").JSX.Element | null;
+export default function MarkdownCore({ streaming, children, ...rest }: MarkdownCoreProps): import("react").JSX.Element;

package/dist/markdown-core/MarkdownCore.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { clientLazy } from "../utils/client-lazy.js";
+import { healStreamingMarkdown } from "./stream-heal.js";
+import { useMarkdownStreaming } from "./streaming-context.js";
+function MarkdownCoreLoading({ error }) {
+  if (error) return null;
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      "aria-hidden": true,
+      "data-markdown-loading": true,
+      className: "inline-block h-[1em] w-2/3 max-w-full animate-pulse rounded bg-muted align-middle"
+    }
+  );
+}
+const MarkdownCoreLeaf = clientLazy(() => import("./MarkdownCoreImpl.js"), {
+  loading: MarkdownCoreLoading
+});
+function MarkdownCore({
+  streaming,
+  children,
+  ...rest
+}) {
+  const inLiveStream = useMarkdownStreaming();
+  const isStreaming = streaming ?? inLiveStream;
+  return /* @__PURE__ */ jsx(MarkdownCoreLeaf, { ...rest, children: isStreaming ? healStreamingMarkdown(children) : children });
+}
+export {
+  MarkdownCoreLoading,
+  MarkdownCore as default
+};

package/dist/markdown-core/MarkdownCoreImpl.d.ts

@@ -0,0 +1,3 @@
+import "katex/dist/katex.min.css";
+import type { MarkdownCoreProps } from "./markdown-core-types.js";
+export default function MarkdownCoreImpl({ children, preset, components, }: MarkdownCoreProps): import("react").JSX.Element;

package/dist/markdown-core/MarkdownCoreImpl.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import ReactMarkdown from "react-markdown";
+import "katex/dist/katex.min.css";
+import { MARKDOWN_PRESETS, prepareCoreSource, rehypeWithNumbering, remarkWithNumbering } from "./markdown-core-presets.js";
+import { useDocumentNumbering } from "./syntax/elements/DocumentNumbering.js";
+import { withCoreSyntaxElements } from "./syntax/elements/core-syntax-elements.js";
+function MarkdownCoreImpl({
+  children,
+  preset = "gfm",
+  components
+}) {
+  const plugins = MARKDOWN_PRESETS[preset];
+  const numbering = useDocumentNumbering();
+  return /* @__PURE__ */ jsx(
+    ReactMarkdown,
+    {
+      remarkPlugins: remarkWithNumbering(plugins.remark, numbering),
+      rehypePlugins: rehypeWithNumbering(plugins.rehype, numbering),
+      components: withCoreSyntaxElements(components),
+      children: prepareCoreSource(children, preset, numbering)
+    }
+  );
+}
+export {
+  MarkdownCoreImpl as default
+};

package/dist/markdown-core/MarkdownCoreServer.d.ts

@@ -0,0 +1,4 @@
+import "server-only";
+import "katex/dist/katex.min.css";
+import type { MarkdownCoreProps } from "./markdown-core-types.js";
+export default function MarkdownCoreServer({ children, preset, components, numbering, }: MarkdownCoreProps): import("react").JSX.Element;