@ggui-ai/ui-gen 0.22.0 → 0.24.0

package/dist/adapter-Du7P_5Fx.d.ts

@@ -0,0 +1,201 @@
+import { RuntimeRenderCheck } from './harness/types-public.js';
+import { GenerationRuntimeProbeCheck } from '@ggui-ai/mcp-server-core';
+import { JsonObject, DataContract } from '@ggui-ai/protocol';
+import { P as ProbeHostLoad } from './types-public-Bk6d1WLN.js';
+
+/**
+ * The subprocess bounds of one isolated check (ggui#1380). They are
+ * INPUTS of the host, not constants: a serving deployment runs the probe
+ * under its own memory and latency budget and sets them per check
+ * instance (`createRuntimeRenderCheck`); the evaluation lane runs on the
+ * defaults below, which are the values the host always used.
+ */
+interface RenderCheckHostBounds {
+    /**
+     * Wall-clock bound for one isolated check. The rich probe renders,
+     * clicks every declared action, and re-renders streams — slower than
+     * the smoke worker's 12s budget; 30s bounds runaway components while
+     * staying far under any generation-turn budget.
+     */
+    readonly timeoutMs: number;
+    /**
+     * V8 heap cap. The worker realm loads react-dom, happy-dom and
+     * testing-library on top of the component itself; 512 MB leaves
+     * headroom while still bounding pathological allocation.
+     */
+    readonly heapMb: number;
+    /**
+     * Grace between SIGTERM and SIGKILL once the bound is crossed. The
+     * effective value is `min(gracePeriodMs, floor(timeoutMs / 2))` —
+     * `runSandboxed` requires the grace to be strictly below the bound, so
+     * a short bound never trips its RangeError.
+     */
+    readonly gracePeriodMs: number;
+}
+/** Options of {@link runRenderCheckViaWorker}. */
+interface RenderCheckHostOptions {
+    /** Subprocess bounds; every field omitted falls to {@link DEFAULT_RENDER_CHECK_HOST_BOUNDS}. */
+    readonly bounds?: Partial<RenderCheckHostBounds>;
+}
+
+/**
+ * 3-state outcome. Internal to runtime-render.
+ * The adapter maps this to existing EvalIssue shapes:
+ *   verified   → no issue
+ *   failed     → fail
+ *   unverified → warn
+ *   skipped    → no issue
+ */
+type CheckOutcome = "verified" | "failed" | "unverified" | "skipped";
+/**
+ * The checks this probe runs, by name (ggui#1380). ONE union: the same
+ * values a generation's metadata lists in `failChecks`
+ * (`GenerationRuntimeProbeCheck` in `@ggui-ai/mcp-server-core`), declared
+ * there and named here — the same pattern as `RuntimeProbeStatus`.
+ */
+type RenderCheckKind = GenerationRuntimeProbeCheck;
+/**
+ * Every {@link RenderCheckKind}, once, in the order the union declares them.
+ * The order is the order a probe's `failChecks` lists the checks that failed,
+ * so a render crash always reads first. `satisfies` refuses a kind outside
+ * the union; the pin beside the adapter refuses a member missing here.
+ */
+declare const RENDER_CHECK_KINDS: readonly ["render-no-throw", "prop-sensitivity", "action-wiring", "selection-identity", "prop-coverage", "optional-props-omitted", "stream-rerender"];
+interface RenderCheckIssue {
+    readonly check: RenderCheckKind;
+    readonly outcome: CheckOutcome;
+    readonly subject?: string;
+    readonly reason: string;
+    /** Optional element description ("button[aria-label='Save']") for action-wiring failures. */
+    readonly elementHint?: string;
+    /**
+     * Diagnostic context from probe + AST analysis. Populated for richer feedback
+     * to the coding agent (which native props the callback flows into, what the
+     * probe observed firing, etc.).
+     */
+    readonly diagnostics?: {
+        readonly observedJsxElements?: readonly string[];
+        readonly observedNativeProps?: readonly string[];
+        readonly observedCustomProps?: readonly string[];
+        /** For action-wiring: which actions DID fire from probe clicks (helps surface mis-wiring). */
+        readonly actionsFiredFromClicks?: readonly string[];
+        /** Surfaced to the agent: prop sourceTool hints from the contract (only if present). */
+        readonly sourceToolHints?: Readonly<Record<string, string>>;
+        /**
+         * For action-wiring (ggui#1187): what input priming did before the
+         * synthetic dispatch — how many controls it filled, or why it could not
+         * run. A "did not dispatch it" on an input-gated action reads differently
+         * beside `{ primed: 0 }` or `{ error }` than beside `{ primed: 1 }`.
+         */
+        readonly inputPriming?: InputPrimingDiagnostic;
+    };
+}
+/**
+ * Outcome of `primeInputs` before the action-wiring probe (ggui#1187). A
+ * priming failure never aborts the check — it is recorded here, on every
+ * action-wiring issue, so it is visible in the feedback instead of vanishing.
+ */
+type InputPrimingDiagnostic = {
+    readonly primed: number;
+} | {
+    readonly error: string;
+};
+/**
+ * The check started but did not finish (ggui#1299). The only kind is a
+ * wall-clock timeout in the isolated worker. It is not a verdict on the
+ * component: `issues` is empty and `ok` is false because nothing was
+ * verified, never because something failed.
+ */
+interface RenderCheckIncomplete {
+    readonly kind: "timeout";
+    /** How long the worker ran before it was stopped. */
+    readonly elapsedMs: number;
+    /** The wall-clock bound it crossed. */
+    readonly boundMs: number;
+}
+interface RenderCheckResult {
+    readonly ok: boolean;
+    readonly issues: readonly RenderCheckIssue[];
+    /** Present only when the check did not finish; see {@link RenderCheckIncomplete}. */
+    readonly incomplete?: RenderCheckIncomplete;
+    readonly stats: {
+        readonly actionsChecked: number;
+        readonly streamsChecked: number;
+        readonly renderMs: number;
+        /** Host load around an isolated check (absent in-process). */
+        readonly hostLoad?: ProbeHostLoad;
+    };
+}
+interface RunRenderCheckInput {
+    readonly sourceCode: string;
+    readonly mockupProps: JsonObject;
+    readonly contract?: DataContract;
+}
+/**
+ * Options of {@link runRenderCheck} (ggui#1380): the host's options —
+ * `bounds` are the isolated subprocess's wall-clock, heap and grace (see
+ * `RenderCheckHostBounds`); they apply to the worker path only and are
+ * ignored in-process. One shape, declared once on the host.
+ */
+type RunRenderCheckOptions = RenderCheckHostOptions;
+/**
+ * Run the in-loop runtime render check.
+ *
+ * Isolation dispatcher (#592): when the CALLING environment already
+ * owns a DOM (`window` + `document` on `globalThis` — e.g. a vitest
+ * `happy-dom` environment, where the environment owner installed the
+ * globals deliberately), the check runs in-process exactly as before.
+ * In a plain Node process it runs in an ISOLATED SUBPROCESS
+ * (`render-check-host.ts` → `render-check-worker.ts`), because the
+ * in-process path installs happy-dom globals on `globalThis`
+ * process-wide — a TOCTOU hazard for anything that sniffs `window`
+ * concurrently (provider SDKs throw "browser-like environment" at
+ * client construction; two overlapping checks corrupt each other's
+ * teardown). See #592 for the measured incident (4 bench cells hard-
+ * failed on the 2026-08-19 run).
+ *
+ * The host is loaded lazily so the worker bundle (which imports this
+ * module for `runRenderCheckInProcess`) never drags in the sandbox
+ * spawn machinery.
+ */
+declare function runRenderCheck(input: RunRenderCheckInput, options?: RunRenderCheckOptions): Promise<RenderCheckResult>;
+
+/**
+ * How one runtime-render check instance runs its isolated worker
+ * (ggui#1380). A serving deployment sets the probe's wall-clock bound,
+ * worker heap and concurrency here; every field omitted is the evaluation
+ * lane's behaviour — the host's default bounds and no concurrency cap.
+ */
+interface RuntimeRenderProbeConfig {
+    /** Wall-clock bound of one isolated check, ms. Default: the host's (30 000). */
+    readonly timeoutMs?: number;
+    /** V8 heap cap of the worker, MB. Default: the host's (512). */
+    readonly heapMb?: number;
+    /**
+     * Live workers this instance may have at once. The (K+1)th check waits
+     * in FIFO order and spawns only when a slot frees; a check that throws
+     * releases its slot. Default: unbounded. Must be a positive integer.
+     */
+    readonly maxConcurrent?: number;
+}
+/**
+ * Build a runtime-render check instance. One FIFO limiter per instance;
+ * the bounds reach `runRenderCheck` on every run. `createRuntimeRenderCheck()`
+ * with no config is {@link DEFAULT_RUNTIME_RENDER_CHECK}'s behaviour.
+ */
+declare function createRuntimeRenderCheck(config?: RuntimeRenderProbeConfig): RuntimeRenderCheck;
+/** The evaluation lane's instance: the host's default bounds, no concurrency cap. */
+declare const DEFAULT_RUNTIME_RENDER_CHECK: RuntimeRenderCheck;
+declare function isRecoverableRenderCrash(reason: string): boolean;
+declare function classifyRenderCrashFix(reason: string): string;
+/**
+ * The check a probe issue's subcategory names (ggui#1380) — the inverse of
+ * the `runtime:<check>[:<subject>]` form {@link toEvalIssue} writes, so a
+ * round can list WHICH checks failed from the issues alone. `undefined` for
+ * anything that is not a probe subcategory naming a member of
+ * {@link RENDER_CHECK_KINDS} (an axis check's subcategory, a did-not-run
+ * code such as `runtime:probe-timeout`, a bare check name).
+ */
+declare function parseRuntimeSubcategory(subcategory: string): RenderCheckKind | undefined;
+
+export { DEFAULT_RUNTIME_RENDER_CHECK as D, type RuntimeRenderProbeConfig as R, type RenderCheckIssue as a, type RenderCheckHostBounds as b, RENDER_CHECK_KINDS as c, type RenderCheckHostOptions as d, type RenderCheckKind as e, type RenderCheckResult as f, classifyRenderCrashFix as g, createRuntimeRenderCheck as h, isRecoverableRenderCrash as i, parseRuntimeSubcategory as p, runRenderCheck as r };

package/dist/adapters/generation-dispatch.d.ts

@@ -1,16 +1,19 @@
 import { EvaluationConfig } from '../evaluation/types.js';
+import { RuntimeRenderCheck } from '../harness/types-public.js';
 import { ModelRoles, GenerationResult } from '../harness/result-types.js';
 import { ProviderName, ToolDefinition } from './types.js';
-import { Q as QualityConfig } from '../types-public-mM_-1Yk3.js';
+import { Q as QualityConfig } from '../types-public-Bk6d1WLN.js';
 import { A as AgentConfig } from '../llm-router-DwwUK1bz.js';
 import { DataContract, JsonObject, GadgetDescriptor } from '@ggui-ai/protocol';
 import { C as CanvasClass, D as DesignMode } from '../design-mode-DLufhrNp.js';
 import { G as GenerationProfileInput } from '../styling-profile-CxfvV48g.js';
 import { R as RenderingContext } from '../prompts-YU9piOgs.js';
-import 'zod';
 import '../axes-CzLEMDeB.js';
-import '../types-BOvHNG7K.js';
 import '../llm.js';
+import '../types-BOvHNG7K.js';
+import '../policy.js';
+import 'zod';
+import '@ggui-ai/mcp-server-core';
 
 interface GenerationDispatchParams {
     provider: ProviderName;
@@ -75,20 +78,38 @@ interface GenerationDispatchParams {
      */
     fixtureProps?: JsonObject;
     /**
-     * Whether to wire `DEFAULT_RUNTIME_RENDER_CHECK` into the harness's
-     * check leg. When `true` (default), the probe runs every coding turn
-     * and feeds wiring-check failures back to the coding agent — useful
-     * for quality gating but ~3-5s per call adds wall-clock per turn.
+     * Whether to wire the runtime-render check (`runtimeRender` when given,
+     * else `DEFAULT_RUNTIME_RENDER_CHECK`) into the harness's check leg.
+     * When `true` (default), the runtime-render probe runs ONCE
+     * at the exit decision, after the coding turns, in an isolated
+     * subprocess — never on the per-turn hot path. Without an `evaluation`
+     * config that round is observe + one repair turn (ggui#1380): a
+     * recoverable render crash buys exactly one repair turn and one
+     * re-probe, then the generation serves what it has; a probe that timed
+     * out, could not run, or had nothing to probe never blocks and never
+     * repairs. With an `evaluation` config the probe is the evaluation
+     * round's exit gate. Its status and timing land on
+     * `evalResult.runtimeProbe` (and on the generation's metadata through
+     * `createUiGenerator`).
      *
-     * When `false`, the harness omits runtime-render from the in-loop
-     * check pipeline. Cloud production runs with this off (per the
-     * migration plan — probe was never in the production hot path).
-     * Bench callers can run the probe externally as a final post-gen
-     * check to get pass/fail visibility without slowing the loop.
+     * When `false`, the harness omits runtime-render entirely: no probe
+     * round runs, and a caller can run the probe externally as a final
+     * post-generation check instead.
      *
      * Default: `true`.
      */
     enableRuntimeRender?: boolean;
+    /**
+     * The runtime-render check to wire (ggui#1380) — built by the CALLER with
+     * `createRuntimeRenderCheck(config)` and kept for the caller's lifetime,
+     * because the check instance owns the probe's concurrency cap: one
+     * instance per generator bounds the workers a serving deployment has
+     * live at once; one per dispatch would give every generation its own
+     * free slots and bound nothing. Absent ⇒ `DEFAULT_RUNTIME_RENDER_CHECK`
+     * (the evaluation lane's bounds, no concurrency cap). Only read when
+     * `enableRuntimeRender` is on.
+     */
+    runtimeRender?: RuntimeRenderCheck;
     /**
      * Operator-registered gadget catalog forwarded to the
      * code-gen system prompt's `clientCapabilities — registered