@ggui-ai/ui-gen 0.15.0 → 0.16.0

package/dist/{create-ui-generator-D6TKuv9V.d.ts → create-ui-generator-CCIeQaEe.d.ts}

@@ -1,8 +1,45 @@
+import { ModelRef } from '@ggui-ai/protocol';
 import { GadgetCatalogAdapter } from '@ggui-ai/gadgets';
 import { GeneratorTier, UiGenerator } from '@ggui-ai/mcp-server-core';
-import { Q as QualityConfig } from './types-public-CkNWEov9.js';
+import { GenerationResult } from './harness/result-types.js';
+import { D as DesignMode } from './design-mode-BHEE7flj.js';
+import { Q as QualityConfig } from './types-public-D24JLJgl.js';
 import { A as AgentConfig } from './llm-router-D7fjBhtr.js';
 
+/**
+ * `createUiGenerator` — full-harness UI generation factory.
+ *
+ * Returns a {@link UiGenerator} backed by `dispatchGeneration` — the
+ * same multi-turn coding-agent path the benchmark validates. OSS
+ * production (`ggui serve`, hosted `ggui_render`) all route through
+ * this seam, so bench == prod by construction.
+ *
+ * Pipeline:
+ *
+ *   1. `resolveRoute` + `applyRouteToEnv` — install BYOK key into
+ *      the process env so dispatch's adapters can read it.
+ *   2. `createGeneratorTools` — assemble the coding-agent tool surface
+ *      (compile_component, validate_component, self_check,
+ *      get_primitives, get_design_system).
+ *   3. `injectRenderingContext` + `injectContracts` — enrich the user
+ *      prompt with rendering hints + contract docs.
+ *   4. `dispatchGeneration` — multi-turn loop with apply_changes,
+ *      self-check, evaluate, regenerate. The harness builds its own
+ *      rich system prompt with primitives doc + design-system docs +
+ *      pitfalls.
+ *
+ * This factory deliberately keeps a minimal surface — provider
+ * routing, compilation, and the system prompt are all internal:
+ *
+ *   - `adapter` option — provider routing is internal to dispatch
+ *   - `compileFn` option — `compile_component` tool runs inline
+ *   - `systemPromptBuilder` option — harness builds its own
+ *   - `withBrowserCompile` wrapper — dispatch returns compiled JS
+ *
+ * Callers who want a lightweight single-shot path can build it
+ * themselves.
+ */
+
 interface CreateUiGeneratorOptions {
     /**
      * Wire `DEFAULT_RUNTIME_RENDER_CHECK` into the harness's check leg.
@@ -22,24 +59,25 @@ interface CreateUiGeneratorOptions {
     /** Quality config controlling eval tiers + improvement behavior. */
     readonly qualityConfig?: QualityConfig;
     /**
-     * Generator identity — registry key + parsed components.
+     * Generator identity — registry key + declared model.
      *
-     * The tier + model determine the {@link UiGenerator.slug} the
-     * factory bakes onto the returned generator. Defaults to
-     * `{tier: 'default', model: 'haiku-4-5'}` → slug
-     * `ui-gen-default-haiku-4-5`, the OSS seed.
+     * The tier alone determines the {@link UiGenerator.slug} the factory
+     * bakes onto the returned generator (`ui-gen-<tier>`); `model` is the
+     * generator's declared model field and is never part of the slug
+     * (ggui#923). Defaults to tier `'default'` → slug `ui-gen-default`,
+     * the OSS seed, with the factory's default model.
      *
      * The actual model used per request still comes from
      * `UiGenerateInput.llm.model` (operators may override via BYOK).
      * The identity here is the registry-level handle, not a runtime
      * model constraint.
      *
-     * Mutually-exclusive shortcut: pass `slug` instead and the factory
-     * parses it for you. The slug + tier/model overloads conflict; the
-     * factory throws if both are supplied.
+     * Mutually-exclusive shortcut: pass `slug` instead of `tier` and the
+     * factory parses the tier from it; `model` may accompany either form.
+     * The factory throws if `slug` and `tier` are both supplied.
      */
     readonly tier?: GeneratorTier;
-    readonly model?: string;
+    readonly model?: ModelRef;
     readonly slug?: string;
     /**
      * Per-deployment gadget descriptor source. Wired once at factory
@@ -99,6 +137,35 @@ interface CreateUiGeneratorOptions {
      * still log via `console.warn`, just without a caller-side hook.
      */
     readonly onRetry?: AgentConfig['onRetry'];
+    /**
+     * Generation observer. Invoked once per successful `generate()` with
+     * the FULL harness result — source, compiled code, token counters,
+     * timing breakdown, evaluation rounds and (when configured) the
+     * per-canvas visual scores — before it is projected onto the
+     * `UiGenerateResult` envelope, which carries only what the protocol
+     * needs. Lets a host record or forward the complete run without
+     * re-deriving it from the envelope. Bound ONCE at construction
+     * (mirrors `onRetry`); not invoked when generation fails. An
+     * exception thrown by the observer is the caller's own and fails
+     * that generation like any other error on the path — keep it
+     * non-throwing.
+     */
+    readonly onGenerated?: (result: GenerationResult) => void;
+    /**
+     * Which generation triad to run. `constrained` (default) is the
+     * design-system triad — byte-identical to the generator's behaviour
+     * before this option existed. `free` relaxes only the design
+     * vocabulary (raw HTML, inline CSS, literal spacing / typography /
+     * radius; the design package importable but optional) while keeping
+     * every hard contract: the boilerplate-typed wire hooks, the import
+     * allowlist + security bans, the host envelope, the budgets, the
+     * blueprint-reuse shape, and brand-bearing color on the closed
+     * `--ggui-color-*` token manifest. Reaches the prompt, boilerplate,
+     * tier-0 gate, axis checks and evaluator criteria through the harness.
+     * The rendering canvas the `free` prompt states is derived from
+     * `input.rendering` (device × shell, refined by viewport width).
+     */
+    readonly designMode?: DesignMode;
 }
 declare function createUiGenerator(options?: CreateUiGeneratorOptions): UiGenerator;
 declare function extractComponentCode(raw: string): string;

package/dist/design-mode-BHEE7flj.d.ts

@@ -0,0 +1,67 @@
+declare const DESIGN_MODES: readonly ["constrained", "free"];
+type DesignMode = (typeof DESIGN_MODES)[number];
+declare const DEFAULT_DESIGN_MODE: DesignMode;
+declare const CANVAS_CLASSES: readonly ["xs-chat-card", "mobile-fullscreen-small", "md", "lg", "xl"];
+type CanvasClass = (typeof CANVAS_CLASSES)[number];
+interface CanvasViewport {
+    readonly width: number;
+    readonly height: number;
+}
+/** The viewport (CSS px) each class is rendered + judged at. */
+declare const CANVAS_VIEWPORTS: Readonly<Record<CanvasClass, CanvasViewport>>;
+/**
+ * The two display modes the canvas derivation distinguishes. `inline`
+ * is the chat card (MCP Apps `inline` display mode / the `chat` shell);
+ * `fullscreen` is every surface the component owns edge to edge or as
+ * a panel (`fullscreen`, `pip`, the `spatial` and `partial` shells) —
+ * there the width decides the class.
+ */
+type CanvasDisplayMode = "inline" | "fullscreen";
+/**
+ * Map a shell name (`chat` / `fullscreen` / `spatial` / `partial`) or an
+ * MCP Apps display mode (`inline` / `fullscreen` / `pip`) onto the
+ * canvas display mode. Only `chat` and `inline` are the inline card;
+ * everything else is width-governed.
+ */
+declare function canvasDisplayModeForShell(shell: string | undefined): CanvasDisplayMode;
+/** Fullscreen-class breakpoints (inclusive lower bounds), CSS px. */
+declare const CANVAS_BREAKPOINTS: {
+    readonly md: 600;
+    readonly lg: 1024;
+    readonly xl: 1440;
+};
+/**
+ * Derive the canvas class from display mode + container width.
+ *
+ *   inline      → `xs-chat-card` at every width
+ *   fullscreen  → width <  600  → `mobile-fullscreen-small`
+ *                 600 – 1023    → `md`
+ *                 1024 – 1439   → `lg`
+ *                 ≥ 1440        → `xl`
+ */
+declare function canvasForViewportWidth(mode: CanvasDisplayMode, width: number): CanvasClass;
+/**
+ * Map today's shell × screen descriptors onto a canvas class when no
+ * width is known. `chat` is always the inline card; `spatial` is a
+ * ~600px floating panel (`md`); `fullscreen` follows the screen. Unknown
+ * values fall back to `lg` (the widest common fullscreen), matching the
+ * skeleton's `fullscreen` / `universal` defaults.
+ */
+declare function canvasForRendering(shellType: string | undefined, screen: string | undefined): CanvasClass;
+interface CanvasDescriptor {
+    /** Short human label. */
+    readonly label: string;
+    /** Inclusive width range the component must look right across, CSS px. */
+    readonly minWidthPx: number;
+    readonly maxWidthPx: number;
+    /** What the host draws around the component at this canvas. */
+    readonly host: string;
+}
+declare const CANVAS_DESCRIPTORS: Readonly<Record<CanvasClass, CanvasDescriptor>>;
+/**
+ * The explicit sentence the `free` prompt renders for a canvas — the
+ * agent is TOLD the canvas, it never guesses it.
+ */
+declare function describeCanvas(canvas: CanvasClass): string;
+
+export { type CanvasClass as C, type DesignMode as D, CANVAS_BREAKPOINTS as a, CANVAS_CLASSES as b, CANVAS_DESCRIPTORS as c, CANVAS_VIEWPORTS as d, type CanvasDescriptor as e, type CanvasDisplayMode as f, type CanvasViewport as g, DEFAULT_DESIGN_MODE as h, DESIGN_MODES as i, canvasDisplayModeForShell as j, canvasForRendering as k, canvasForViewportWidth as l, describeCanvas as m };

package/dist/{dispatch-BuZfTh9r.d.ts → dispatch-BA5dJcg-.d.ts}

@@ -1,12 +1,15 @@
 import { DataContract } from '@ggui-ai/protocol';
 import { C as Classification } from './axes-CzLEMDeB.js';
-import { E as EvalIssue } from './types-public-CkNWEov9.js';
+import { E as EvalIssue } from './types-public-D24JLJgl.js';
+import { D as DesignMode } from './design-mode-BHEE7flj.js';
 
 interface RunAxisChecksInput {
     sourceCode: string;
     compiledCode: string | null;
     contract?: DataContract;
     originalPrompt: string;
+    /** Which triad produced the source — see `AxisCheckInput.designMode`. */
+    designMode?: DesignMode;
 }
 declare function runAxisChecks(classification: Classification, input: RunAxisChecksInput): EvalIssue[];
 

package/dist/evaluation/axis-checks/index.d.ts

@@ -1,9 +1,10 @@
-export { R as RunAxisChecksInput, r as runAxisChecks } from '../../dispatch-BuZfTh9r.js';
+export { R as RunAxisChecksInput, r as runAxisChecks } from '../../dispatch-BA5dJcg-.js';
 export { REGISTRY } from './registry.js';
-import { A as AxisCheck } from '../../types-public-CkNWEov9.js';
-export { a as AxisCheckInput, m as matches } from '../../types-public-CkNWEov9.js';
+import { A as AxisCheck } from '../../types-public-D24JLJgl.js';
+export { a as AxisCheckInput, m as matches } from '../../types-public-D24JLJgl.js';
 import '@ggui-ai/protocol';
 import '../../axes-CzLEMDeB.js';
+import '../../design-mode-BHEE7flj.js';
 import '../../types-BOvHNG7K.js';
 
 declare const EXTRA_CHECKS: readonly AxisCheck[];

package/dist/evaluation/axis-checks/index.js

@@ -1152,6 +1152,7 @@ var stepperAdopted = {
   values: ["multi-step"],
   run(input) {
     if (input.compiledCode === null) return [];
+    if (input.designMode === "free") return [];
     if (/<Stepper[\s/>]/.test(input.sourceCode)) return [];
     return [
       mkIssue2(
@@ -1223,7 +1224,8 @@ function runAxisChecks(classification, input) {
     compiledCode: input.compiledCode,
     ...input.contract !== void 0 ? { contract: input.contract } : {},
     originalPrompt: input.originalPrompt,
-    classification
+    classification,
+    ...input.designMode !== void 0 ? { designMode: input.designMode } : {}
   };
   const issues = [];
   const firedIds = /* @__PURE__ */ new Set();