@ai-matrx/rich-content 0.2.3 → 0.2.6

package/dist/utils/lifted/artifactId.d.ts

@@ -0,0 +1,34 @@
+/**
+ * isMaterializedArtifactId — the R3 recognition primitive.
+ *
+ * An `<artifact>` (and every artifact renderer) carries an `id` that is EITHER:
+ *  - a real `canvas_items` UUID → the artifact is MATERIALIZED (persisted). The
+ *    UI renders the live row by id; data-touching types (tasks) can link/convert
+ *    against the stable artifact id.
+ *  - the model's own `artifact_N` (or a splitter fallback like `artifact-3`, or
+ *    nothing) → NOT yet materialized → render inline; it's a materialization
+ *    candidate, not a known artifact.
+ *
+ * This single UUID-shape test is what makes the whole system safe (vision R3):
+ * it does NOT matter whether the model ever learns to emit the shape — a
+ * non-UUID id is always treated as "new / unmaterialized", a UUID as "this exact
+ * persisted artifact." Used by the renderers (render-by-id vs inline) and by
+ * materialization (skip-already-materialized vs create-new).
+ *
+ * See `/Users/armanisadeghi/code/common-docs/systems/publish/artifacts/VISION.md` (R1–R3).
+ */
+/** True only for a canonical UUID — i.e. a real, persisted `canvas_items.id`. */
+export declare function isMaterializedArtifactId(id?: string | null): boolean;
+/**
+ * readArtifactPointerId — the pointer-shape reader.
+ *
+ * A canvas item whose artifact has been MATERIALIZED stores only a POINTER in
+ * `content.data`: `{ artifactId }`. The body lives in the `canvas_items` row.
+ * Anything that consumes `content.data` (render, share, export) must recognise
+ * that shape instead of treating the pointer as the content — publishing a
+ * pointer produces a page with nothing in it.
+ *
+ * Returns the materialized artifact UUID, or undefined when `data` is real
+ * content (string, or an object that is not a pointer).
+ */
+export declare function readArtifactPointerId(data: unknown): string | undefined;

package/dist/utils/lifted/artifactId.js

@@ -0,0 +1,15 @@
+import { isUuidShape } from "@ai-matrx/kit/uuid";
+function isMaterializedArtifactId(id) {
+  return typeof id === "string" && isUuidShape(id.trim());
+}
+function readArtifactPointerId(data) {
+  if (typeof data !== "object" || data === null) return void 0;
+  if (!("artifactId" in data)) return void 0;
+  const id = data.artifactId;
+  if (typeof id !== "string") return void 0;
+  return isMaterializedArtifactId(id) ? id : void 0;
+}
+export {
+  isMaterializedArtifactId,
+  readArtifactPointerId
+};

package/dist/utils/lifted/canvasContent.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The canvas CONTENT vocabulary: every artifact/surface type the canvas can
+ * show, which of them can be saved as an artifact, and the title helpers.
+ *
+ * Framework-light on purpose: openers import this without pulling in a single
+ * renderer. Each content type is registered as its own `@ai-matrx/canvas` kind
+ * (features/canvas/host/artifactKinds.tsx).
+ */
+import { type ReactNode } from "react";
+export type CanvasContentType = "quiz" | "presentation" | "iframe" | "html" | "code" | "image" | "diagram" | "comparison" | "timeline" | "research" | "troubleshooting" | "decision-tree" | "flashcards" | "recipe" | "resources" | "code_preview" | "code_edit_error" | "progress" | "math_problem" | "mermaid" | "svg" | "chart" | "map" | "stats" | "diff" | "questionnaire" | "react" | "table" | "transcript" | "structured_info" | "tree" | "tasks" | "cloud_browser" | "udt_document" | "sandbox" | "topical_map" | "kind_value";
+/**
+ * Canvas content types that hold live, non-serializable runtime state —
+ * callbacks like `onApply` / `onDiscard` / `onCloseModal`. They are ephemeral
+ * editor surfaces, NOT artifacts. Persisting them serializes the callbacks to
+ * `null` and produces a corrupt, dead row that renders with no handlers, so
+ * saving them must be refused loudly rather than silently writing junk.
+ */
+export declare const NON_PERSISTABLE_CANVAS_TYPES: ReadonlySet<string>;
+export declare function isPersistableCanvasType(type: string): boolean;
+/** Admin-visible trace from ensureArtifactPersisted / cloud sync. */
+export interface ArtifactDebugTrace {
+    steps: string[];
+    errors: string[];
+    ensuredAt: number;
+    wasCreated: boolean;
+}
+export interface CanvasContent {
+    type: CanvasContentType;
+    data: any;
+    metadata?: {
+        title?: string | ReactNode;
+        subtitle?: string | ReactNode;
+        sourceMessageId?: string;
+        sourceTaskId?: string;
+        /** Optional chat linkage for canvas views (e.g. flashcards). */
+        conversationId?: string;
+        messageId?: string;
+        /** canvas_items row id when the open content is a persisted artifact —
+         *  editors use it to save new versions instead of creating new rows. */
+        canvasItemId?: string;
+        /** Persisted artifact version when known (display chip). */
+        artifactVersion?: number;
+        /**
+         * `html_pages.id` when the item shows a published HTML page — its identity
+         * for agents (read + edit through the page), independent of the URL.
+         */
+        htmlPageId?: string;
+        /** Per-artifact mermaid render options + diagram identity. */
+        mermaid?: Record<string, unknown>;
+    };
+}
+/** Convert a possibly-ReactNode title to plain text for fallback uses. */
+export declare function titleToString(title: string | ReactNode | undefined): string;
+/** Canonical fallback titles per type. */
+export declare function getDefaultTitle(type: string): string;
+/**
+ * The display label for a stored canvas type, for badges and filters. Known
+ * types read their canvas title; anything else is humanized from its key
+ * (`structured_info` → "Structured info"), never shown raw.
+ */
+export declare function getCanvasTypeLabel(type: string): string;
+/** Short subtitle per type — surfaces as the kind-of-thing label. */
+export declare function getSubtitle(type: string): string | undefined;

package/dist/utils/lifted/canvasContent.js

@@ -0,0 +1,98 @@
+import { isValidElement } from "react";
+const NON_PERSISTABLE_CANVAS_TYPES = /* @__PURE__ */ new Set([
+  "code_preview",
+  "code_edit_error",
+  // Live Cloud Browser: holds run/screenshot/controller/handoff state — a
+  // canvas_items row would freeze a dead pointer with no live session.
+  "cloud_browser",
+  // Live sandbox: a pty and a file tree against a running box. A canvas_items
+  // row would freeze a pointer to a box that is gone by the time it is read.
+  "sandbox",
+  // A cloud document owns its OWN append-only snapshot history
+  // (`udt_document_snapshots`) and saves itself as the user types. A
+  // `canvas_items` row would freeze a stale copy beside the live one, so the
+  // pane is a pointer and only a pointer. Unlike the other live surfaces it
+  // still HAS a real source — see `canvasSource.ts`.
+  "udt_document",
+  // A topical map pane is a pointer to live rows the workspace body reads; the
+  // rows are the truth and a frozen copy would drift on the next accepted
+  // proposal (see the type's comment above).
+  "topical_map"
+]);
+function isPersistableCanvasType(type) {
+  return !NON_PERSISTABLE_CANVAS_TYPES.has(type);
+}
+function titleToString(title) {
+  if (!title) return "";
+  if (typeof title === "string") return title;
+  if (typeof title === "number") return String(title);
+  if (typeof title === "boolean") return String(title);
+  if (Array.isArray(title)) {
+    return title.map(titleToString).filter(Boolean).join(" ");
+  }
+  if (isValidElement(title)) {
+    const children = title.props?.children;
+    if (children) {
+      const extracted = titleToString(children);
+      if (extracted) return extracted;
+    }
+    return "Canvas Content";
+  }
+  return "Canvas Content";
+}
+function getDefaultTitle(type) {
+  const titles = {
+    quiz: "Quiz",
+    presentation: "Presentation",
+    iframe: "Web View",
+    html: "HTML View",
+    code: "Code Viewer",
+    image: "Image",
+    diagram: "Diagram",
+    comparison: "Comparison",
+    timeline: "Timeline",
+    research: "Research",
+    troubleshooting: "Troubleshooting",
+    "decision-tree": "Decision Tree",
+    flashcards: "Flashcards",
+    recipe: "Recipe",
+    resources: "Resources",
+    progress: "Progress Tracker",
+    math_problem: "Math Problem",
+    mermaid: "Diagram",
+    code_preview: "Code Preview",
+    code_edit_error: "Code Edit Error",
+    cloud_browser: "Cloud Browser",
+    sandbox: "Sandbox",
+    udt_document: "Document",
+    topical_map: "Topical map"
+  };
+  return titles[type] || "Canvas View";
+}
+function getCanvasTypeLabel(type) {
+  const title = getDefaultTitle(type);
+  if (title !== "Canvas View") return title;
+  const words = type.trim().split(/[\s_-]+/).filter(Boolean);
+  if (words.length === 0) return "Canvas";
+  const sentence = words.join(" ").toLowerCase();
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+}
+function getSubtitle(type) {
+  const subtitles = {
+    quiz: "Interactive quiz",
+    presentation: "Slideshow presentation",
+    code: "Code snippet",
+    diagram: "Interactive diagram",
+    mermaid: "Editable diagram",
+    math_problem: "Step-by-step solution"
+  };
+  return subtitles[type];
+}
+export {
+  NON_PERSISTABLE_CANVAS_TYPES,
+  getCanvasTypeLabel,
+  getDefaultTitle,
+  getSubtitle,
+  isPersistableCanvasType,
+  titleToString
+};

package/dist/utils/lifted/captureReactError.d.ts

@@ -0,0 +1,24 @@
+/**
+ * captureReactError.ts
+ *
+ * Adapter for React render errors caught by an error boundary. Error
+ * boundaries SWALLOW the error (it never reaches `window` 'error'), so the
+ * global listener can't see it — a boundary must opt in by calling this.
+ *
+ * Any boundary in the app can adopt it: call `captureReactRenderError` from
+ * `componentDidCatch` and the failure shows up in the Error Inspector with the
+ * component stack. Wired into `OverlayErrorBoundary` today; other boundaries
+ * can follow the same one-liner.
+ */
+interface ReactErrorContext {
+    /** A name for the boundary that caught it (e.g. "OverlayErrorBoundary"). */
+    boundary?: string;
+    /** React's component stack from `ErrorInfo`. */
+    componentStack?: string | null;
+    /** For lazy overlays: the dynamic-import module path that failed. */
+    modulePath?: string | null;
+    /** What failed — e.g. a message id, route name, or `tool:<name>`. */
+    relation?: string;
+}
+export declare function captureReactRenderError(error: unknown, ctx?: ReactErrorContext): void;
+export {};

package/dist/utils/lifted/captureReactError.js

@@ -0,0 +1,28 @@
+import { captureError } from "../../host/diagnostics.js";
+import { extractErrorMessage } from "./errors.js";
+function captureReactRenderError(error, ctx = {}) {
+  try {
+    captureError({
+      source: "react-render",
+      relation: ctx.relation ?? ctx.boundary ?? ctx.modulePath ?? void 0,
+      message: extractErrorMessage(error) || "React render error",
+      name: error instanceof Error ? error.name : void 0,
+      stack: error instanceof Error ? error.stack : void 0,
+      // The component stack is the "where in the tree" answer — surface it as
+      // the call-site, mirroring the Supabase call-site field.
+      callSite: ctx.componentStack ?? void 0,
+      raw: {
+        boundary: ctx.boundary,
+        modulePath: ctx.modulePath,
+        componentStack: ctx.componentStack,
+        name: error instanceof Error ? error.name : void 0,
+        message: extractErrorMessage(error),
+        stack: error instanceof Error ? error.stack : void 0
+      }
+    });
+  } catch {
+  }
+}
+export {
+  captureReactRenderError
+};

package/dist/utils/lifted/chunk-load-recovery.d.ts

@@ -0,0 +1,25 @@
+/** Window event announcing a chunk-load failure. Detail: { message: string }. */
+export declare const CHUNK_LOAD_ERROR_EVENT = "matrx:chunk-load-error";
+/** Window flag set by NewVersionWatcher once React has booted. The boot
+ *  script checks it to decide reload (pre-boot) vs event (post-boot). */
+export declare const APP_BOOTED_FLAG = "__MATRX_APP_BOOTED__";
+/**
+ * THE one pattern set for explicit chunk/module-fetch failures. Every detector
+ * in the app tests against this list. These signatures identify what failed;
+ * they do not assert why it failed.
+ *
+ * Do not add generic runtime-integrity messages such as Turbopack's "module
+ * factory is not available" here. They can happen on a fresh document load and
+ * provide no evidence of a stale deployment. Misclassifying them hides the real
+ * exception from the Error Inspector and shows users a false diagnosis.
+ */
+export declare const CHUNK_LOAD_ERROR_PATTERNS: RegExp[];
+/** True when `haystack` carries an explicit chunk/module-fetch signature. */
+export declare function hasChunkLoadErrorSignature(haystack: string): boolean;
+export declare function isChunkLoadError(error: unknown): boolean;
+/**
+ * Announce a chunk-load failure so NewVersionWatcher can offer the user a
+ * refresh. Never reloads. Safe to call unconditionally — no-ops unless the
+ * error is chunk-shaped.
+ */
+export declare function notifyChunkLoadError(error: unknown): void;

package/dist/utils/lifted/chunk-load-recovery.js

@@ -0,0 +1,36 @@
+const CHUNK_LOAD_ERROR_EVENT = "matrx:chunk-load-error";
+const APP_BOOTED_FLAG = "__MATRX_APP_BOOTED__";
+const CHUNK_LOAD_ERROR_PATTERNS = [
+  /ChunkLoadError/i,
+  /Loading( CSS)? chunk [\w-]+ failed/i,
+  /Failed to load chunk/i,
+  /Failed to fetch dynamically imported module/i,
+  /error loading dynamically imported module/i,
+  /Importing a module script failed/i
+];
+function hasChunkLoadErrorSignature(haystack) {
+  return CHUNK_LOAD_ERROR_PATTERNS.some((pattern) => pattern.test(haystack));
+}
+function isChunkLoadError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  if (e.name === "ChunkLoadError") return true;
+  const msg = typeof e.message === "string" ? e.message : "";
+  return hasChunkLoadErrorSignature(msg);
+}
+function notifyChunkLoadError(error) {
+  if (typeof window === "undefined") return;
+  if (!isChunkLoadError(error)) return;
+  const message = error instanceof Error ? error.message : String(error ?? "ChunkLoadError");
+  window.dispatchEvent(
+    new CustomEvent(CHUNK_LOAD_ERROR_EVENT, { detail: { message } })
+  );
+}
+export {
+  APP_BOOTED_FLAG,
+  CHUNK_LOAD_ERROR_EVENT,
+  CHUNK_LOAD_ERROR_PATTERNS,
+  hasChunkLoadErrorSignature,
+  isChunkLoadError,
+  notifyChunkLoadError
+};

package/dist/utils/lifted/code-editor-agent-types.d.ts

@@ -0,0 +1,6 @@
+import type { MandateKey } from "@ai-matrx/agents/mandates";
+export interface CodeEditorAgentConfig {
+    mandateKey: MandateKey;
+    name: string;
+    codeVariableKey: string;
+}

package/dist/utils/lifted/code-editor-agents.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Code-editor agent configs — MANDATE KEYS, never agent ids.
+ *
+ * The code editor names WHICH JOB it is running (a `mandate_key`); the DATABASE
+ * decides which agent runs it (`agent.mandate` → system default, or the user's
+ * own binding). Every launch resolves the key at run time through the ONE
+ * launch funnel — `launchAgentExecution({ mandateKey })` /
+ * `useAgentLauncher().launchMandate` — which applies BOTH halves of the binding
+ * (agent AND `config_overrides`). Resolving a key yourself and passing the agent
+ * id into a launch silently drops the settings half; never do that. Recipe:
+ * `features/mandates/FEATURE.md` §"Migrating a hardcoded call site".
+ *
+ * All three mandates share provision `code_editor.session`, which offers
+ * `current_code` + `dynamic_context`; `codeVariableKey` names which of those
+ * the editor seeds on the first turn (the binding's consumption map decides what
+ * the bound agent actually consumes).
+ *
+ * **A raw agent UUID in this file is a defect.** Need a fourth editing job?
+ * Declare a mandate in aidream `services/mandates/client_mandates.py`, then add
+ * its key here.
+ */
+import type { CodeEditorAgentConfig } from "./code-editor-agent-types.js";
+export declare const GENERIC_CODE_EDITOR_AGENT: CodeEditorAgentConfig;
+export declare const PROMPT_APP_UI_EDITOR_AGENT: CodeEditorAgentConfig;
+export declare const DYNAMIC_CONTEXT_CODE_EDITOR_AGENT: CodeEditorAgentConfig;
+/** Every code-editor mandate, generic first. */
+export declare const CODE_EDITOR_AGENTS: CodeEditorAgentConfig[];
+/** Default picker roster: prompt-app first when invoked from a prompt-app. */
+export declare const PROMPT_APP_AGENT_PICKER: CodeEditorAgentConfig[];
+/** Default picker roster: generic first when invoked from a generic editor. */
+export declare const GENERIC_AGENT_PICKER: CodeEditorAgentConfig[];
+/** The legacy `promptKey` strings older call sites still pass. */
+export type CodeEditorPromptKey = "prompt-app-ui-editor" | "generic-code-editor" | "code-editor-dynamic-context";
+/**
+ * Lookup by legacy `promptKey` (e.g. "prompt-app-ui-editor") OR by mandate key.
+ * Unknown values fall back to the generic editor (the same posture the old
+ * lookup had) — the mandate itself is still resolved loudly at launch.
+ */
+export declare function agentForPromptKey(keyOrMandateKey: string | undefined): CodeEditorAgentConfig;

package/dist/utils/lifted/code-editor-agents.js

@@ -0,0 +1,52 @@
+import { MANDATE_KEYS } from "@ai-matrx/agents/mandates";
+const GENERIC_CODE_EDITOR_AGENT = {
+  mandateKey: MANDATE_KEYS.code_editor__code_edit,
+  name: "Code Editor",
+  codeVariableKey: "current_code"
+};
+const PROMPT_APP_UI_EDITOR_AGENT = {
+  mandateKey: MANDATE_KEYS.code_editor__prompt_app_ui_edit,
+  name: "Prompt App Code Editor",
+  codeVariableKey: "current_code"
+};
+const DYNAMIC_CONTEXT_CODE_EDITOR_AGENT = {
+  mandateKey: MANDATE_KEYS.code_editor__dynamic_context_edit,
+  name: "Code Editor (Dynamic Context)",
+  codeVariableKey: "dynamic_context"
+};
+const CODE_EDITOR_AGENTS = [
+  GENERIC_CODE_EDITOR_AGENT,
+  PROMPT_APP_UI_EDITOR_AGENT,
+  DYNAMIC_CONTEXT_CODE_EDITOR_AGENT
+];
+const PROMPT_APP_AGENT_PICKER = [
+  PROMPT_APP_UI_EDITOR_AGENT,
+  GENERIC_CODE_EDITOR_AGENT
+];
+const GENERIC_AGENT_PICKER = [
+  GENERIC_CODE_EDITOR_AGENT,
+  PROMPT_APP_UI_EDITOR_AGENT
+];
+function agentForPromptKey(keyOrMandateKey) {
+  switch (keyOrMandateKey) {
+    case "prompt-app-ui-editor":
+    case PROMPT_APP_UI_EDITOR_AGENT.mandateKey:
+      return PROMPT_APP_UI_EDITOR_AGENT;
+    case "code-editor-dynamic-context":
+    case DYNAMIC_CONTEXT_CODE_EDITOR_AGENT.mandateKey:
+      return DYNAMIC_CONTEXT_CODE_EDITOR_AGENT;
+    case "generic-code-editor":
+    case GENERIC_CODE_EDITOR_AGENT.mandateKey:
+    default:
+      return GENERIC_CODE_EDITOR_AGENT;
+  }
+}
+export {
+  CODE_EDITOR_AGENTS,
+  DYNAMIC_CONTEXT_CODE_EDITOR_AGENT,
+  GENERIC_AGENT_PICKER,
+  GENERIC_CODE_EDITOR_AGENT,
+  PROMPT_APP_AGENT_PICKER,
+  PROMPT_APP_UI_EDITOR_AGENT,
+  agentForPromptKey
+};

package/dist/utils/lifted/code-language-extension.d.ts

@@ -0,0 +1 @@
+export declare function codeLanguageToExtension(language: string): string;

package/dist/utils/lifted/code-language-extension.js

@@ -0,0 +1,60 @@
+function codeLanguageToExtension(language) {
+  const lang = (language ?? "").toLowerCase().trim();
+  const MAP = {
+    javascript: ".js",
+    typescript: ".ts",
+    jsx: ".jsx",
+    tsx: ".tsx",
+    python: ".py",
+    ruby: ".rb",
+    rust: ".rs",
+    go: ".go",
+    java: ".java",
+    kotlin: ".kt",
+    swift: ".swift",
+    "c++": ".cpp",
+    cpp: ".cpp",
+    "c#": ".cs",
+    csharp: ".cs",
+    c: ".c",
+    php: ".php",
+    scala: ".scala",
+    shell: ".sh",
+    bash: ".sh",
+    sh: ".sh",
+    zsh: ".sh",
+    powershell: ".ps1",
+    html: ".html",
+    css: ".css",
+    scss: ".scss",
+    sass: ".sass",
+    less: ".less",
+    json: ".json",
+    yaml: ".yaml",
+    yml: ".yml",
+    toml: ".toml",
+    xml: ".xml",
+    markdown: ".md",
+    md: ".md",
+    sql: ".sql",
+    graphql: ".graphql",
+    dockerfile: ".dockerfile",
+    makefile: ".makefile",
+    r: ".r",
+    matlab: ".m",
+    lua: ".lua",
+    perl: ".pl",
+    elixir: ".ex",
+    erlang: ".erl",
+    haskell: ".hs",
+    clojure: ".clj",
+    dart: ".dart",
+    vue: ".vue",
+    svelte: ".svelte"
+  };
+  if (!lang) return ".txt";
+  return MAP[lang] ?? `.${lang}`;
+}
+export {
+  codeLanguageToExtension
+};

package/dist/utils/lifted/custom-icons.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Custom SVG icons used by language-display + file-icon.
+ *
+ * Duplicated from components/DirectoryTree/custom-icons.tsx so features/code
+ * has no dependency on paths that are slated for deletion.
+ */
+import React from "react";
+interface TwoColorPythonIconProps {
+    size?: number;
+    className?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    strokeWidth?: number;
+}
+export declare const TwoColorPythonIcon: React.FC<TwoColorPythonIconProps>;
+export {};

package/dist/utils/lifted/custom-icons.js

@@ -0,0 +1,47 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+const TwoColorPythonIcon = ({
+  size = 18,
+  className = "",
+  primaryColor = "#4B8BBE",
+  secondaryColor = "#FFD43B",
+  strokeWidth = 2
+}) => {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      width: size,
+      height: size,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      strokeWidth,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      className,
+      children: [
+        /* @__PURE__ */ jsxs("defs", { children: [
+          /* @__PURE__ */ jsx("clipPath", { id: "mx-code-py-top", children: /* @__PURE__ */ jsx("rect", { x: "0", y: "0", width: "24", height: "12" }) }),
+          /* @__PURE__ */ jsx("clipPath", { id: "mx-code-py-bottom", children: /* @__PURE__ */ jsx("rect", { x: "0", y: "12", width: "24", height: "12" }) })
+        ] }),
+        /* @__PURE__ */ jsx("path", { stroke: "none", d: "M0 0h24v24H0z", fill: "none" }),
+        /* @__PURE__ */ jsxs("g", { clipPath: "url(#mx-code-py-top)", stroke: primaryColor, children: [
+          /* @__PURE__ */ jsx("path", { d: "M12 9h-7a2 2 0 0 0 -2 2v4a2 2 0 0 0 2 2h3" }),
+          /* @__PURE__ */ jsx("path", { d: "M12 15h7a2 2 0 0 0 2 -2v-4a2 2 0 0 0 -2 -2h-3" }),
+          /* @__PURE__ */ jsx("path", { d: "M8 9v-4a2 2 0 0 1 2 -2h4a2 2 0 0 1 2 2v5a2 2 0 0 1 -2 2h-4a2 2 0 0 0 -2 2v5a2 2 0 0 0 2 2h4a2 2 0 0 0 2 -2v-4" }),
+          /* @__PURE__ */ jsx("path", { d: "M11 6l0 .01" }),
+          /* @__PURE__ */ jsx("path", { d: "M13 18l0 .01" })
+        ] }),
+        /* @__PURE__ */ jsxs("g", { clipPath: "url(#mx-code-py-bottom)", stroke: secondaryColor, children: [
+          /* @__PURE__ */ jsx("path", { d: "M12 9h-7a2 2 0 0 0 -2 2v4a2 2 0 0 0 2 2h3" }),
+          /* @__PURE__ */ jsx("path", { d: "M12 15h7a2 2 0 0 0 2 -2v-4a2 2 0 0 0 -2 -2h-3" }),
+          /* @__PURE__ */ jsx("path", { d: "M8 9v-4a2 2 0 0 1 2 -2h4a2 2 0 0 1 2 2v5a2 2 0 0 1 -2 2h-4a2 2 0 0 0 -2 2v5a2 2 0 0 0 2 2h4a2 2 0 0 0 2 -2v-4" }),
+          /* @__PURE__ */ jsx("path", { d: "M11 6l0 .01" }),
+          /* @__PURE__ */ jsx("path", { d: "M13 18l0 .01" })
+        ] })
+      ]
+    }
+  );
+};
+export {
+  TwoColorPythonIcon
+};

package/dist/utils/lifted/durability.d.ts

@@ -0,0 +1,16 @@
+import { classifyMediaUrl, isDurableMediaUrl, shareableMediaUrl, type MediaUrlKind } from "@ai-matrx/data/files";
+export { classifyMediaUrl, isDurableMediaUrl, shareableMediaUrl };
+export type { MediaUrlKind };
+/**
+ * Recover the cld_files file_id from an our-own user-files signed S3 URL
+ * (`…/{user_id}/{file_id}?…`). Used to render via the handler (which
+ * re-mints) or to publish the file. Returns null for non-user-files URLs.
+ */
+export declare function fileIdFromUserFilesUrl(url: string): string | null;
+/**
+ * LOUD: log a durability violation. A non-public, expiring URL reaching
+ * `context` means the media was persisted wrong server-side. Returns true if
+ * it WAS a violation (so callers can trigger a heal), false otherwise. Never
+ * throws.
+ */
+export declare function reportMediaDurabilityViolation(url: string | null | undefined, context: string): boolean;

package/dist/utils/lifted/durability.js

@@ -0,0 +1,45 @@
+import {
+  classifyMediaUrl,
+  createFileUrlRecognizer,
+  isDurableMediaUrl,
+  shareableMediaUrl
+} from "@ai-matrx/data/files";
+import { captureError } from "../../host/diagnostics.js";
+const recognizer = createFileUrlRecognizer();
+function fileIdFromUserFilesUrl(url) {
+  return recognizer.fileIdFromUserFilesUrl(url);
+}
+function reportMediaDurabilityViolation(url, context) {
+  if (classifyMediaUrl(url) !== "expiring") return false;
+  try {
+    captureError({
+      source: "media-durability",
+      relation: context,
+      message: `Expiring media URL reached "${context}" \u2014 should be public/durable`,
+      details: String(url).slice(0, 300),
+      raw: { context, url: String(url) }
+    });
+  } catch {
+  }
+  console.error(
+    `
+================ MEDIA-DURABILITY VIOLATION ================
+A non-public, EXPIRING media URL reached "${context}".
+This must never be persisted/rendered for public or owned media \u2014 it WILL
+break when the signature expires. The media should have been saved PUBLIC
+at generation (durable CDN/public-bucket URL), or rendered via the file
+handler (<InlineMediaRef> + file_id, which re-mints). See the frontend
+FOUND_DEFECTS.md \u2192 'Media durability'.
+URL: ${String(url).slice(0, 180)}
+===========================================================
+`
+  );
+  return true;
+}
+export {
+  classifyMediaUrl,
+  fileIdFromUserFilesUrl,
+  isDurableMediaUrl,
+  reportMediaDurabilityViolation,
+  shareableMediaUrl
+};

package/dist/utils/lifted/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * utils/errors.ts — THE APP'S DOOR to the two halves of an error's audience.
+ *
+ * 🚨 THIS IS A DOOR, NOT A BODY. The bodies live in the packages and are
+ * re-exported here so this repo's ~500 `@/utils/errors` importers keep their
+ * import path:
+ *   - `extractErrorMessage` (LOGS and the Error Inspector: every scrap of
+ *     PostgREST detail) — `@ai-matrx/data/net`. The host body was deleted
+ *     2026-09-11 in the byte-size/error twins collapse.
+ *   - `operationFailed`, `makeAssertData`, `stripTerminalCodes`,
+ *     `humanizeBackendError` (what a PERSON reads) — `@ai-matrx/kit/errors`,
+ *     moved 2026-10-01 (chat-package independence P12).
+ * Never re-grow a body here; a fix goes into the package and is adopted.
+ * Guard: `pnpm check:package-twins`.
+ *
+ * Handing `error.message` straight to a user is the defect
+ * `pnpm check:access-errors` counts. When the failure is a single-record READ,
+ * render `<AccessGate token id error/>` instead (features/access-gate/).
+ */
+import { extractErrorMessage } from "@ai-matrx/data/net";
+export { extractErrorMessage };
+export { humanizeBackendError, makeAssertData, operationFailed, stripTerminalCodes, } from "@ai-matrx/kit/errors";
+/**
+ * Postgres governance guards use a machine code before a sentence deliberately
+ * written for the person making the change. Preserve only the allow-listed
+ * codes; every other PostgREST failure keeps the calm generic action message.
+ * (Host-owned: it composes `@ai-matrx/data/net` with `@ai-matrx/kit/errors`,
+ * and kit may not import data.)
+ */
+export declare function makeGovernedDataAsserter(action: string, governanceCode: RegExp): <T>(data: T | null, error: unknown, override?: string) => T;