@ai-matrx/code-runtime 0.1.4

package/dist/scope-lrQkC0jP.d.ts

@@ -0,0 +1,205 @@
+import * as React from 'react';
+
+/**
+ * The error every refusal carries. Structurally identical to
+ * `@ai-matrx/applets`' `AppletError` (CONTRACTS §0); mirrored here because
+ * applets depends on this package, never the reverse.
+ */
+interface CodeRuntimeError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    diagnostic?: string;
+}
+/**
+ * What a compile may import (CONTRACTS §7). `entries` are import paths from
+ * the one documented registry (`listScopeEntries()`); `overrides` are
+ * host-owned replacements by scope name (e.g. a runtime-aware MarkdownStream);
+ * `shadowDangerousGlobals` installs throwing stubs over fetch/eval/… for
+ * organization-authored code.
+ */
+interface ScopeSpec {
+    entries: string[];
+    overrides?: Record<string, unknown>;
+    shadowDangerousGlobals: boolean;
+}
+/** One name the code referenced that nothing could supply. */
+interface UnresolvedImport {
+    identifier: string;
+    /** null for a bare JSX reference with no import behind it. */
+    importPath: string | null;
+}
+type CompiledComponent = React.ComponentType<Record<string, unknown>>;
+type CompileResult = {
+    ok: true;
+    Component: CompiledComponent;
+    /** One readable line per unresolved name (`X from "path"`). */
+    unresolved: string[];
+    /** The same list, structured. */
+    unresolvedImports: UnresolvedImport[];
+} | {
+    ok: false;
+    error: CodeRuntimeError;
+};
+/** One source-gate finding (CONTRACTS §7). */
+interface Finding {
+    rule: string;
+    file: string;
+    line: number;
+    message: string;
+    severity: "refuse" | "warn";
+}
+/** One import specifier, recorded before the declaration is rewritten. */
+interface ImportBinding {
+    local: string;
+    source: string;
+    /** Exported name, `"default"`, or `"*"` for a namespace import. */
+    imported: string;
+}
+/** One transformed file: plain JSON, so it crosses `postMessage` unchanged. */
+interface TransformedModule {
+    file: string;
+    /** CommonJS-shaped JS (`require`, `module`, `exports` are supplied at run). */
+    code: string;
+    declaredTopLevel: string[];
+    /** Top-level PascalCase bindings in declaration order. */
+    componentCandidates: string[];
+    importBindings: ImportBinding[];
+}
+/** A whole transformed file graph — the parent → frame payload. */
+interface TransformedGraph {
+    entry: string;
+    modules: Record<string, TransformedModule>;
+}
+type TransformResult = {
+    ok: true;
+    graph: TransformedGraph;
+} | {
+    ok: false;
+    error: CodeRuntimeError;
+};
+/** Options every compile entry accepts (a superset of the contract call). */
+interface CompileOptions {
+    /**
+     * Which stored thing this is — `tool:<name>`, `applet:<id>`, `kind:<slug>`…
+     * Every unresolved name is reported under it.
+     */
+    origin?: string;
+    /** Where unresolved names are reported (default: one console warning per name). */
+    onUnresolved?: (origin: string, unresolved: readonly UnresolvedImport[]) => void;
+    /**
+     * With no default export, which top-level PascalCase binding is the
+     * component: `"last"` (default — the stored-component contract) or
+     * `"conventional"` (App, Main, Page, Component, Demo, Example or Root
+     * first, else the last — chat code blocks).
+     */
+    componentCandidate?: "last" | "conventional";
+}
+
+type AnyRecord = Record<string, unknown>;
+/**
+ * Throwing stubs for the globals stored code may not use. Named error, never
+ * silence: the reader's error boundary shows which global it reached for.
+ * BACKSTOP, not a sandbox — bare identifiers only; `window.fetch` still
+ * resolves. The write-time gate refuses `window.fetch`; the sandbox frame is
+ * the real boundary.
+ */
+declare function buildDangerousGlobalStubs(): AnyRecord;
+/**
+ * `buildScope` (CONTRACTS §7): the named, documented values a spec puts in
+ * scope. Async entries not yet prepared are absent (see `prepareScope`).
+ */
+declare function buildScope(spec: ScopeSpec): Record<string, unknown>;
+
+/**
+ * THE ONE DOCUMENTED SCOPE REGISTRY — every import path stored code may name.
+ *
+ * Merged from matrx-frontend's two registries (`agent-apps/utils/
+ * allowed-imports.ts` and `dynamic-react/toolRendererScope.ts`), which
+ * disagreed on strategies, lists and loading. Rules that hold:
+ *  - every entry is EXPLICITLY named and documented; no wildcard;
+ *  - nothing here reaches data: no database client, no fetch wrapper, no
+ *    store — data reach belongs to the host (CONTRACTS §1);
+ *  - an entry is `package`-owned (this package ships its module, so a plain
+ *    Vite page gets it) or `host`-owned (declared and documented here, the
+ *    module supplied by the host through `provideScopeModules`); a host entry
+ *    no host supplied renders named stand-ins and is reported, never crashes;
+ *  - `@/components/ui/*` are LEGACY ALIASES kept while stored code uses them
+ *    (census 2026-10-06: 67 kind components, 78 apps). Each names the same
+ *    design-system export the frontend file re-exports; new code imports
+ *    `@ai-matrx/design-system/controls` (the primary UI set).
+ *
+ * Pure data: no React, no module loads — `gate.ts` and servers read it.
+ * `gate-lists.json#allowedImports` must equal `listScopeEntryPaths()` sorted
+ * (guard: `scope-registry.test.ts`).
+ */
+type ScopeStrategy = "named" | "spread" | "namespace";
+interface ScopeEntryDeclaration {
+    /** The import path stored code writes. */
+    path: string;
+    /** `named`: listed exports; `spread`: every export; `namespace`: the module under `namespaceName`. */
+    strategy: ScopeStrategy;
+    exports?: readonly string[];
+    /** moduleKey → scope name (`{ default: "MarkdownStream" }`). */
+    exportMap?: Readonly<Record<string, string>>;
+    namespaceName?: string;
+    /** Missing PascalCase names resolve to a visible stand-in (icon sets). */
+    safeProxy?: boolean;
+    /** Always present for chat code blocks (cheap, already in shared chunks). */
+    core?: boolean;
+    /** Identifiers whose bare use implies this entry (heavy-lib demand detection). */
+    provides?: readonly string[];
+    owner: "package" | "host";
+    description: string;
+}
+declare const SCOPE_ENTRIES: readonly ScopeEntryDeclaration[];
+declare function getScopeEntry(path: string): ScopeEntryDeclaration | undefined;
+/** Every documented path, in registry order. */
+declare function listScopeEntryPaths(): string[];
+/** Every documented entry with its description (for builders, agents and docs). */
+declare function listScopeEntries(): readonly ScopeEntryDeclaration[];
+/**
+ * The default scope for stored components (kind components, tool renderers,
+ * Applets): everything except the heavy optional libraries, which are added
+ * by demand detection. Order is spread precedence: later entries win.
+ */
+declare function defaultComponentEntries(): string[];
+/** Paths always loaded for chat code blocks. */
+declare function coreEntryPaths(): string[];
+/**
+ * The entries a set of files needs: the core set, every documented path it
+ * imports, and every heavy library whose identifiers it uses bare.
+ */
+declare function detectEntries(files: Readonly<Record<string, string>>): string[];
+
+type ScopeModuleLoader = () => unknown;
+/**
+ * Supply (or replace) the modules for scope entries. Keys must be documented
+ * registry paths; an unknown key throws, because a module nobody documented
+ * is exactly the reach the registry exists to prevent.
+ */
+declare function provideScopeModules(map: Readonly<Record<string, ScopeModuleLoader>>): void;
+/** Resolve every async module the given entries need. Never rejects. */
+declare function prepareScopeModules(paths: readonly string[]): Promise<void>;
+/** Test seam: forget every provided and loaded module. */
+declare function resetScopeModules(): void;
+
+/**
+ * NOTHING FAILS SILENTLY. Stored code that names something the scope cannot
+ * supply still renders — one bad import must not blank a whole display — but
+ * the gap is SHOWN where it sits: a compact dashed chip carrying the missing
+ * name (tooltip: the import path), with the element's children rendered after
+ * it. Moved verbatim from matrx-frontend
+ * `features/agent-apps/utils/patch-scope-identifiers.ts`; the mark symbol is
+ * unchanged (`Symbol.for`) so stand-ins made by either copy are recognised.
+ */
+
+/** The stand-in's own record, or null when `value` is a real binding. */
+declare function readUnresolvedImportMark(value: unknown): UnresolvedImport | null;
+declare function createUnresolvedImportStandIn(identifier: string, importPath?: string | null): React.ForwardRefExoticComponent<{
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLSpanElement>>;
+/** One readable line per unresolved name. */
+declare function describeUnresolved(entry: UnresolvedImport): string;
+
+export { type CompileOptions as C, type Finding as F, type ImportBinding as I, type ScopeSpec as S, type TransformResult as T, type UnresolvedImport as U, type CompileResult as a, type CompiledComponent as b, type CodeRuntimeError as c, SCOPE_ENTRIES as d, type ScopeEntryDeclaration as e, type ScopeModuleLoader as f, type ScopeStrategy as g, type TransformedGraph as h, type TransformedModule as i, buildDangerousGlobalStubs as j, buildScope as k, coreEntryPaths as l, createUnresolvedImportStandIn as m, defaultComponentEntries as n, describeUnresolved as o, detectEntries as p, getScopeEntry as q, listScopeEntries as r, listScopeEntryPaths as s, provideScopeModules as t, readUnresolvedImportMark as u, resetScopeModules as v, prepareScopeModules as w };