@ggui-ai/ui-gen 0.15.0 → 0.16.0

package/src/harness/llm-trace-sink.ts

@@ -21,9 +21,9 @@
  * (createAgent → run-coding-turn → llm-evaluator → file-agent → …)
  * touches ~5 packages for a devtools-only surface. The OSS ggui server
  * is a single process per CLI invocation — global state has no
- * confusion-cost there. A hosted closed runtime isolates per request
- * via process-pool, so a global per-pool is also safe. If we ever
- * multi-tenant inside one process we'll thread it then.
+ * confusion-cost there. A hosted deployment isolates per request via a
+ * process pool, so a global per-pool is also safe. If we ever serve
+ * several apps inside one process we'll thread it then.
  *
  * **Default = no sink.** When unset, the router emits nothing and
  * spends no CPU formatting events. Passing `null` removes a previously

package/src/harness/result-types.ts

@@ -12,8 +12,8 @@
 import type { DataContract, JsonObject } from "@ggui-ai/protocol";
 import type { AdapterResult } from "../adapters/types.js";
 import type { RenderingContext } from "../contract-context.js";
-import type { EvaluationResult } from "../evaluation/types.js";
 import type { EvalResult } from "../evaluation/types-public.js";
+import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // =============================================================================
 // Model Roles
@@ -52,8 +52,6 @@ export type ModelRoles = Partial<Record<ModelRole, string>>;
 export interface GenerationResult extends AdapterResult {
   /** Number of generation passes the harness performed */
   passesUsed: number;
-  /** Evaluation results per round (legacy numeric scoring — backward compat) */
-  evaluations?: EvaluationResult[];
   /** Three-tier evaluation result (tier 0 + LLM tier 1+2 + visual) */
   evalResult?: EvalResult;
   /** Whether background improvement should be spawned (auto-improve mode) */
@@ -62,6 +60,20 @@ export interface GenerationResult extends AdapterResult {
   selfCheckPassed?: boolean;
   /** Which model was used for each role (for benchmark reporting) */
   modelRolesUsed?: Record<string, string>;
+  /**
+   * The triad this generation ran under — recorded ONLY when the caller
+   * set `designMode` on the dispatch (a bench arm switch, an operator
+   * option). Absent = the constrained default path, byte-identical to
+   * the pre-`designMode` result.
+   */
+  designMode?: DesignMode;
+  /**
+   * The canvas class the `free` prompt stated — the explicit `canvas`
+   * when the caller passed one, else the shell × screen derivation the
+   * prompt itself used. Absent in constrained mode (that prompt states
+   * no canvas) unless the caller passed one explicitly.
+   */
+  canvas?: CanvasClass;
   /** Phase-level timing breakdown (ms) */
   timing?: Record<string, number>;
   /** Per-turn/per-outcome breakdown for benchmark analysis.

package/src/harness/runtime.ts

@@ -32,6 +32,7 @@ import { renderPitfallsBlock } from "./pitfalls.js";
 import type { GadgetDescriptor, DataContract, JsonObject } from "@ggui-ai/protocol";
 import { buildSystemPrompt as buildSystemPromptSkeleton } from "../boilerplate.js";
 import type { AgentConfig } from "./llm-router.js";
+import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // Re-export the boilerplate generator so existing internal importers
 // (create-harness.ts, benchmarks/preview-boilerplate.ts) keep working.
@@ -82,6 +83,13 @@ export interface SingleComponentParams {
     passThreshold?: number;
     sampleProps?: JsonObject;
     viewport?: { width: number; height: number };
+    /**
+     * Per-canvas judging — see `VisualEvalConfig.canvases`. When set, the
+     * eval round screenshots + judges once per class and the harness
+     * stamps `EvalResult.visual` with the PNG-free summary. Unset =
+     * today's single screenshot at `viewport`.
+     */
+    canvases?: readonly CanvasClass[];
   };
   onProgress?: (event: unknown) => void;
   onInitialResult?: (result: {
@@ -133,6 +141,14 @@ export function buildSystemPrompt(
    * stdlib gadgets do not need one.
    */
   gadgetTypes?: Readonly<Record<string, string>>,
+  /**
+   * Which triad to teach — see `SystemPromptInputs.designMode`. Omitted
+   * (every pre-existing caller) means `constrained`, byte-identical to
+   * the pre-`designMode` prompt.
+   */
+  designMode?: DesignMode,
+  /** Rendering canvas class (`free` mode) — see `SystemPromptInputs.canvas`. */
+  canvas?: CanvasClass,
 ): string {
   return buildSystemPromptSkeleton({
     userRequest,
@@ -145,6 +161,8 @@ export function buildSystemPrompt(
     wireDoc: WIRE_DOCUMENTATION,
     appGadgets,
     gadgetTypes,
+    designMode,
+    canvas,
     // criteriaBlock left undefined — ui-gen fills default from open CRITERIA.
   });
 }

package/src/harness/types-public.ts

@@ -24,6 +24,7 @@ import type { EvalIssue, EvalTier, AxisCheck, RuntimeProbeStatus } from "../eval
 import type { LLMToolDef } from "../llm.js";
 import type { CacheTier, HarnessFragment } from "../fragments/index.js";
 import type { HarnessPolicy, ProcessMode } from "../policy.js";
+import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 export type { ProcessMode };
 
@@ -293,6 +294,14 @@ export interface Harness {
   readonly id: HarnessId;
   readonly name: HarnessName;
   readonly classification: Classification;
+  /**
+   * Which triad this harness materialised — threaded from
+   * `CreateHarnessInput.designMode` into the HOW leg (prompt), the WHAT
+   * leg (boilerplate) and every CHECK consumer (tier-0 gate, axis
+   * checks, evaluator criteria). `constrained` unless the caller opted
+   * into `free`.
+   */
+  readonly designMode: DesignMode;
 
   readonly how: HowLeg;
   readonly what: WhatLeg;
@@ -383,6 +392,10 @@ export type SystemPromptBuilder = (input: {
   readonly shellType?: string;
   readonly screen?: string;
   readonly axisDelta?: string;
+  /** Which triad to teach — see `CreateHarnessInput.designMode`. */
+  readonly designMode?: DesignMode;
+  /** Rendering canvas class (`free` mode) — see `CreateHarnessInput.canvas`. */
+  readonly canvas?: CanvasClass;
 }) => string;
 
 export interface CreateHarnessInput {
@@ -392,6 +405,20 @@ export interface CreateHarnessInput {
   readonly shellType?: "chat" | "fullscreen" | "spatial";
   readonly screen?: "mobile" | "tablet" | "desktop" | "universal";
   readonly overrides?: HarnessOverrides;
+  /**
+   * Which triad to materialise. `constrained` (default) is today's
+   * design-system triad, byte-identical to the pre-`designMode`
+   * harness (same prompt, boilerplate, tier-0 legs, criteria and id).
+   * `free` relaxes only the design vocabulary; every hard contract
+   * stays. See `../design-mode.ts`.
+   */
+  readonly designMode?: DesignMode;
+  /**
+   * Rendering canvas class the `free` prompt states explicitly. When
+   * omitted the prompt derives it from `shellType` × `screen`. Ignored
+   * by the `constrained` prompt.
+   */
+  readonly canvas?: CanvasClass;
   /**
    * Pre-resolved static harness policy. When omitted, `createHarness`
    * falls back to `DEFAULT_HARNESS_POLICY` from `@ggui-ai/ui-gen/policy`.

package/src/index.ts

@@ -21,6 +21,7 @@ export {
 } from './create-ui-generator.js';
 export type { CreateUiGeneratorOptions } from './create-ui-generator.js';
 export type { ProviderRetryInfo } from './harness/llm-router.js';
+export type { GenerationResult } from './harness/result-types.js';
 
 // Generator registry seam re-export. The interface + slug helpers live
 // in `@ggui-ai/mcp-server-core`; the in-memory factory lives in
@@ -49,6 +50,31 @@ export {
   injectVariance,
 } from './contract-context.js';
 export type { RenderingContext } from './contract-context.js';
+export { canvasForRenderingContext } from './contract-context.js';
+
+// ── Design mode ──────────────────────────────────────────────────────
+//
+// `createUiGenerator({ designMode })` — `constrained` (default) or
+// `free`; the canvas vocabulary the `free` prompt states.
+export {
+  DESIGN_MODES,
+  DEFAULT_DESIGN_MODE,
+  CANVAS_CLASSES,
+  CANVAS_VIEWPORTS,
+  CANVAS_BREAKPOINTS,
+  CANVAS_DESCRIPTORS,
+  canvasDisplayModeForShell,
+  canvasForRendering,
+  canvasForViewportWidth,
+  describeCanvas,
+} from './design-mode.js';
+export type {
+  DesignMode,
+  CanvasClass,
+  CanvasViewport,
+  CanvasDisplayMode,
+  CanvasDescriptor,
+} from './design-mode.js';
 
 // ── Anthropic SDK construction ──────────────────────────────────────
 //

package/src/internal/extract-call-signatures.ts

@@ -419,7 +419,7 @@ export function extractCallSignaturesFromDts(
     return {};
   }
 
-  const cacheKey = `${dtsContent}${[...hookNames].sort().join(',')}`;
+  const cacheKey = `${dtsContent}\u0000${[...hookNames].sort().join(',')}`;
   const cached = callSignatureCache.get(cacheKey);
   if (cached !== undefined) return cached;
 
@@ -470,7 +470,7 @@ export function extractComponentPropsFromDts(
     return {};
   }
 
-  const cacheKey = `${dtsContent}${[...componentNames].sort().join(',')}`;
+  const cacheKey = `${dtsContent}\u0000${[...componentNames].sort().join(',')}`;
   const cached = componentPropsCache.get(cacheKey);
   if (cached !== undefined) return cached;
 

package/src/providers/bedrock.ts

@@ -2,13 +2,13 @@
  * Concrete AWS Bedrock `ProviderAdapter` — invokes Anthropic Claude
  * models on Bedrock via the official `@anthropic-ai/bedrock-sdk`
  * package. IAM-based auth (no API key in flight); the AWS credential
- * chain (IRSA pod token / `~/.aws/credentials` / env vars) supplies
+ * chain (a workload-identity token / `~/.aws/credentials` / env vars) supplies
  * SigV4 signatures automatically.
  *
  * ## Why this adapter exists
  *
  * Anyone running a one-shot LLM caller on an AWS-credentialed host
- * (EC2, ECS, Lambda, EKS) can target Bedrock without managing API keys: IAM is
+ * (EC2, ECS, Lambda and the like) can target Bedrock without managing API keys: IAM is
  * the auth boundary, AWS rotates host credentials automatically, and
  * a misconfigured IAM role surfaces as a clear `AccessDeniedException`
  * the SDK funnels through `mapError`. The alternative — parking a
@@ -165,8 +165,8 @@ export function bedrockEndpointFor(model: string): BedrockEndpoint {
  * Constructor options for the Bedrock adapter.
  *
  * `region` is the only required option in the common case — IAM
- * credentials come from the standard AWS chain (IRSA pod token in
- * EKS, instance role on EC2, env vars or shared credentials file
+ * credentials come from the standard AWS chain (a workload-identity token in
+ * a container cluster, instance role on EC2, env vars or shared credentials file
  * locally). Tests pass `clientFactory` to inject a mock SDK client.
  */
 export interface BedrockAdapterOptions {

package/src/run-check.ts

@@ -113,6 +113,7 @@ export async function runCheck(input: RunCheckInput): Promise<CheckResult> {
     contract: contract,
     originalPrompt: prompt,
     classification: harness.classification,
+    designMode: harness.designMode,
   };
   let axisIssueCount = 0;
   const seenAxisIds = new Set<string>();