@ggui-ai/project-config 0.1.0-rc.3 → 0.2.0-alpha.1

package/README.md

@@ -59,7 +59,7 @@ if (path) {
 
 `protocol` MUST match `PROTOCOL_VERSION` exported by `@ggui-ai/protocol` in the version installed.
 
-Optional blocks: `storage` (sessions / vectors / threads via `memory` or `sqlite`), `theme`, `primitives`, `blueprints`, `mcpMounts`, and `operator`. See the exported Zod schema for the full, authoritative shape.
+Optional blocks: `storage` (renders / vectors / threads via `memory` or `sqlite`), `theme`, `primitives`, `blueprints`, `mcpMounts`, and `operator`. See the exported Zod schema for the full, authoritative shape.
 
 ## License
 

package/dist/schema.d.ts

@@ -123,9 +123,9 @@ declare const StorageSurfaceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     path: z.ZodString;
 }, z.core.$strict>], "driver">;
 declare const StorageSchema: z.ZodObject<{
-    /** Session persistence (events + stack + identity). Absent =
-     * in-memory (sessions reset on restart). */
-    sessions: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    /** Render persistence (events + identity). Absent = in-memory
+     * (renders reset on restart). */
+    renders: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         driver: z.ZodLiteral<"memory">;
     }, z.core.$strict>, z.ZodObject<{
         driver: z.ZodLiteral<"sqlite">;
@@ -150,7 +150,7 @@ declare const StorageSchema: z.ZodObject<{
      * deployment Portal's self-hosted flow talks to). Pair with
      * `driver: 'sqlite'` + a `path` for durable local storage; the
      * `@ggui-ai/mcp-server-core/sqlite#SqliteThreadStore` reference
-     * impl consumes the same file-per-surface layout the sessions/
+     * impl consumes the same file-per-surface layout the renders/
      * vectors drivers already use. */
     threads: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         driver: z.ZodLiteral<"memory">;
@@ -163,13 +163,56 @@ declare const StorageSchema: z.ZodObject<{
     }, z.core.$strict>], "driver">>;
 }, z.core.$strict>;
 /**
- * Public type alias for one storage surface's config (sessions or
+ * Public type alias for one storage surface's config (renders or
  * vectors). Callers instantiating adapters from a parsed manifest
  * pattern-match on `driver`.
  */
 export type StorageSurfaceConfig = z.infer<typeof StorageSurfaceSchema>;
 /** Public type alias for the full storage block. */
 export type StorageConfig = z.infer<typeof StorageSchema>;
+/**
+ * Explicit LLM-route selection for UI generation. The operator
+ * declares which `(provider, model)` the OSS `ggui serve` runs
+ * against — eliminates the surprise where exporting `OPENAI_API_KEY`
+ * silently picks the OpenAI default model.
+ *
+ * `model` accepts EITHER serialization:
+ *   - **Canonical** — `provider:model` (e.g. `anthropic:claude-haiku-4-5-20251001`)
+ *   - **LiteLLM compat** — `provider/model` (e.g. `anthropic/claude-haiku-4-5`)
+ *
+ * Parsed at schema-load time via `parseAnyLlmRoute` and surfaced
+ * as a typed `LlmRoute` for downstream consumers (zero string
+ * threading through the dispatch path).
+ */
+declare const GenerationSchema: z.ZodObject<{
+    /**
+     * Typed LLM route — `(provider, model)` parsed at the schema
+     * boundary into a discriminated `LlmRoute`. See
+     * `docs/principles/model-string-convention.md`.
+     */
+    model: z.ZodPipe<z.ZodString, z.ZodTransform<{
+        provider: "anthropic";
+        model: "claude-haiku-4-5-20251001" | "claude-sonnet-4-6" | "claude-opus-4-7" | "claude-opus-4-6";
+    } | {
+        provider: "openai";
+        model: "gpt-5.5" | "gpt-5.5-2026-04-23" | "gpt-5.5-pro" | "gpt-5.5-pro-2026-04-23" | "gpt-5.4" | "gpt-5.4-2026-03-05" | "gpt-5.4-mini" | "gpt-5.4-mini-2026-03-17" | "gpt-5.4-nano" | "gpt-5.4-nano-2026-03-17" | "gpt-5.3-codex";
+    } | {
+        provider: "google";
+        model: "gemini-3.5-flash" | "gemini-flash-latest" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.1-flash-lite-preview" | "gemini-3-flash-preview";
+    } | {
+        provider: "bedrock";
+        model: (string & {}) | "us.anthropic.claude-haiku-4-5-20251001-v1:0" | "eu.anthropic.claude-haiku-4-5-20251001-v1:0" | "apac.anthropic.claude-haiku-4-5-20251001-v1:0" | "global.anthropic.claude-haiku-4-5-20251001-v1:0" | "us.anthropic.claude-sonnet-4-6" | "eu.anthropic.claude-sonnet-4-6" | "apac.anthropic.claude-sonnet-4-6" | "us.anthropic.claude-opus-4-7" | "eu.anthropic.claude-opus-4-7" | "apac.anthropic.claude-opus-4-7" | "global.anthropic.claude-opus-4-7" | "us.anthropic.claude-opus-4-6-v1";
+    } | {
+        provider: "openrouter";
+        model: (string & {}) | "anthropic/claude-haiku-4.5" | "anthropic/claude-sonnet-4.6" | "anthropic/claude-opus-4.7" | "openai/gpt-5.5" | "openai/gpt-5.5-pro" | "openai/gpt-5.4-mini" | "openai/gpt-5.4-nano" | "google/gemini-3.5-flash" | "google/gemini-3.1-pro-preview" | "google/gemini-3.1-flash-lite" | "x-ai/grok-4.3" | "meta-llama/llama-4-maverick" | "meta-llama/llama-3.3-70b-instruct" | "deepseek/deepseek-v4-pro" | "deepseek/deepseek-r1-0528" | "qwen/qwen3.7-max" | "qwen/qwen3-coder" | "mistralai/mistral-large-2512" | "openai/gpt-oss-120b";
+    }, string>>;
+}, z.core.$strict>;
+/**
+ * Public type alias for the parsed generation block. `model` is the
+ * typed `LlmRoute`, NOT the raw string — schema-side transform fires
+ * at parse time so downstream consumers never see the string form.
+ */
+export type GenerationConfig = z.infer<typeof GenerationSchema>;
 /**
  * Public type alias for the resolved theme selection (post-parse).
  *
@@ -302,17 +345,26 @@ export declare const GguiJsonV1: z.ZodObject<{
          */
         publicEnv: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
         /**
-         * MCP-Apps presentation mode (canvas slice). `'canvas'` makes
-         * `ggui_new_session` mint a session-scoped iframe
-         * (`ui://ggui/session/<sessionId>`) and route subsequent pushes
-         * through the session WebSocket channel instead of returning a
-         * per-push `ui://ggui/render/<shortCode>` resource. `'inline'`
-         * (default when omitted) preserves the per-push iframe behavior
-         * that flagship MCP-Apps hosts already expect.
+         * App-default display-mode hint stamped on every `ggui_render` from
+         * this app via `_meta.ui.displayMode`. Spec-aligned with MCP App
+         * display literals (`'inline' | 'fullscreen' | 'pip'`).
+         *
+         * Honored by hosts as a PRESENTATION preference — `'fullscreen'`
+         * says "render as a main view"; `'inline'` says "stack vertically in
+         * the chat log"; `'pip'` says "render as picture-in-picture overlay".
+         * The wire mechanism is identical regardless of mode (every push
+         * stamps its own `_meta.ui.resourceUri` and every iframe goes
+         * through the same runtime mount path); display mode controls ONLY
+         * how the host arranges the iframes it mounts. Agents can override
+         * per push via `ggui_render.input.displayMode`.
+         *
+         * Absent ⇒ no per-push hint stamped (host falls back to its own
+         * default, typically `'inline'`).
          */
-        defaultMcpAppsMode: z.ZodOptional<z.ZodEnum<{
+        defaultDisplayMode: z.ZodOptional<z.ZodEnum<{
             inline: "inline";
-            canvas: "canvas";
+            fullscreen: "fullscreen";
+            pip: "pip";
         }>>;
     }, z.core.$strict>;
     /** Operator identity — who's running this server. Optional;
@@ -398,9 +450,9 @@ export declare const GguiJsonV1: z.ZodObject<{
      * — no surface silently creates a file on disk. See
      * {@link StorageConfig}. */
     storage: z.ZodOptional<z.ZodObject<{
-        /** Session persistence (events + stack + identity). Absent =
-         * in-memory (sessions reset on restart). */
-        sessions: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        /** Render persistence (events + identity). Absent = in-memory
+         * (renders reset on restart). */
+        renders: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             driver: z.ZodLiteral<"memory">;
         }, z.core.$strict>, z.ZodObject<{
             driver: z.ZodLiteral<"sqlite">;
@@ -425,7 +477,7 @@ export declare const GguiJsonV1: z.ZodObject<{
          * deployment Portal's self-hosted flow talks to). Pair with
          * `driver: 'sqlite'` + a `path` for durable local storage; the
          * `@ggui-ai/mcp-server-core/sqlite#SqliteThreadStore` reference
-         * impl consumes the same file-per-surface layout the sessions/
+         * impl consumes the same file-per-surface layout the renders/
          * vectors drivers already use. */
         threads: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             driver: z.ZodLiteral<"memory">;
@@ -437,6 +489,40 @@ export declare const GguiJsonV1: z.ZodObject<{
             path: z.ZodString;
         }, z.core.$strict>], "driver">>;
     }, z.core.$strict>>;
+    /**
+     * Explicit UI-generation LLM route. Absent + a boot-time provider
+     * key resolves → `ggui serve` hard-fails with an actionable error
+     * pointing here. Absent + no key → graceful boot (the
+     * Connect-Claude card flow handles per-user keys at request time).
+     * Present → use this route verbatim; the schema-side
+     * `parseAnyLlmRoute` transform yields a typed `LlmRoute` so the
+     * dispatch path never sees a string.
+     *
+     * See {@link GenerationConfig}.
+     */
+    generation: z.ZodOptional<z.ZodObject<{
+        /**
+         * Typed LLM route — `(provider, model)` parsed at the schema
+         * boundary into a discriminated `LlmRoute`. See
+         * `docs/principles/model-string-convention.md`.
+         */
+        model: z.ZodPipe<z.ZodString, z.ZodTransform<{
+            provider: "anthropic";
+            model: "claude-haiku-4-5-20251001" | "claude-sonnet-4-6" | "claude-opus-4-7" | "claude-opus-4-6";
+        } | {
+            provider: "openai";
+            model: "gpt-5.5" | "gpt-5.5-2026-04-23" | "gpt-5.5-pro" | "gpt-5.5-pro-2026-04-23" | "gpt-5.4" | "gpt-5.4-2026-03-05" | "gpt-5.4-mini" | "gpt-5.4-mini-2026-03-17" | "gpt-5.4-nano" | "gpt-5.4-nano-2026-03-17" | "gpt-5.3-codex";
+        } | {
+            provider: "google";
+            model: "gemini-3.5-flash" | "gemini-flash-latest" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.1-flash-lite-preview" | "gemini-3-flash-preview";
+        } | {
+            provider: "bedrock";
+            model: (string & {}) | "us.anthropic.claude-haiku-4-5-20251001-v1:0" | "eu.anthropic.claude-haiku-4-5-20251001-v1:0" | "apac.anthropic.claude-haiku-4-5-20251001-v1:0" | "global.anthropic.claude-haiku-4-5-20251001-v1:0" | "us.anthropic.claude-sonnet-4-6" | "eu.anthropic.claude-sonnet-4-6" | "apac.anthropic.claude-sonnet-4-6" | "us.anthropic.claude-opus-4-7" | "eu.anthropic.claude-opus-4-7" | "apac.anthropic.claude-opus-4-7" | "global.anthropic.claude-opus-4-7" | "us.anthropic.claude-opus-4-6-v1";
+        } | {
+            provider: "openrouter";
+            model: (string & {}) | "anthropic/claude-haiku-4.5" | "anthropic/claude-sonnet-4.6" | "anthropic/claude-opus-4.7" | "openai/gpt-5.5" | "openai/gpt-5.5-pro" | "openai/gpt-5.4-mini" | "openai/gpt-5.4-nano" | "google/gemini-3.5-flash" | "google/gemini-3.1-pro-preview" | "google/gemini-3.1-flash-lite" | "x-ai/grok-4.3" | "meta-llama/llama-4-maverick" | "meta-llama/llama-3.3-70b-instruct" | "deepseek/deepseek-v4-pro" | "deepseek/deepseek-r1-0528" | "qwen/qwen3.7-max" | "qwen/qwen3-coder" | "mistralai/mistral-large-2512" | "openai/gpt-oss-120b";
+        }, string>>;
+    }, z.core.$strict>>;
     /**
      * Default plugin-registry URL for this app.
      *
@@ -468,7 +554,7 @@ export declare const GguiJsonV1: z.ZodObject<{
     /**
      * Local MCP tool mounts — the operator-facing seam for declaring
      * additional tool surfaces that aggregate onto `/mcp` alongside
-     * ggui-native tools (`ggui_push`, etc.). Each entry is a module
+     * ggui-native tools (`ggui_render`, etc.). Each entry is a module
      * specifier:
      *
      *   - Relative paths (`./path/to/mount.js`, `../local/mcp.mjs`)

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyGxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAA,MAAM,cAAc;IAClB;sDACkD;;IAElD;8CAC0C;;IAI1C;;uDAEmD;;IAEnD;;;8CAG0C;;kBAI1C,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AA+H5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;oBAI5B,CAAC;AAqEH;;;;;GAKG;AACH,QAAA,MAAM,oBAAoB;;;;IAZxB;;oDAEgD;;8BAahD,CAAC;AAEH,QAAA,MAAM,aAAa;IACjB;gDAC4C;;;;;QAnB5C;;wDAEgD;;;IAmBhD;gDAC4C;;;;;QAtB5C;;wDAEgD;;;IAsBhD;;;;;;sCAMkC;;;;;QA9BlC;;wDAEgD;;;kBA8BhD,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;IACrB;uEACmE;;IAOnE,iDAAiD;;IAKjD,oBAAoB;;;;QA9XpB;;;;;;;;;;;;;;;WAeG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAIH;;;;;;;;;;;;;;;;;WAiBG;;QAEH;;;;;;;;WAQG;;;;;;IAqVH;;;kDAG8C;;QA/T9C;0DACkD;;QAElD;kDAC0C;;QAI1C;;2DAEmD;;QAEnD;;;kDAG0C;;;IAqT1C,+DAA+D;;QAhS/D;sDAC8C;;;IAoS9C;qEACiE;;;;;IAQjE;;;;;;;;;;;;;;;;;;OAkBG;;;;;;;;;;;;;;;IAKH;0DACsD;;QAhRtD;;;;;kDAK0C;;;IAgR1C;;;;gCAI4B;;QA5H5B;oDAC4C;;;;;YAnB5C;;4DAEgD;;;QAmBhD;oDAC4C;;;;;YAtB5C;;4DAEgD;;;QAsBhD;;;;;;0CAMkC;;;;;YA9BlC;;4DAEgD;;;;IAiJhD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;IAQH;;;;;;;;;;;;;;;;;;;;;;;;6EAwByE;;kBASzE,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,UAAU,CAAC,SAAS,CAAC,CAEzC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmHxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAA,MAAM,cAAc;IAClB;sDACkD;;IAElD;8CAC0C;;IAI1C;;uDAEmD;;IAEnD;;;8CAG0C;;kBAI1C,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AA+H5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;oBAI5B,CAAC;AAqEH;;;;;GAKG;AACH,QAAA,MAAM,oBAAoB;;;;IAZxB;;oDAEgD;;8BAahD,CAAC;AAEH,QAAA,MAAM,aAAa;IACjB;qCACiC;;;;;QAnBjC;;wDAEgD;;;IAmBhD;gDAC4C;;;;;QAtB5C;;wDAEgD;;;IAsBhD;;;;;;sCAMkC;;;;;QA9BlC;;wDAEgD;;;kBA8BhD,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,gBAAgB;IACpB;;;;OAIG;;;;;;;;;;;;;;;;;kBAoBH,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;IACrB;uEACmE;;IAOnE,iDAAiD;;IAKjD,oBAAoB;;;;QAtbpB;;;;;;;;;;;;;;;WAeG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAIH;;;;;;;;;;;;;;;;;WAiBG;;QAEH;;;;;;;;;;;;;;;;WAgBG;;;;;;;IAqYH;;;kDAG8C;;QA/W9C;0DACkD;;QAElD;kDAC0C;;QAI1C;;2DAEmD;;QAEnD;;;kDAG0C;;;IAqW1C,+DAA+D;;QAhV/D;sDAC8C;;;IAoV9C;qEACiE;;;;;IAQjE;;;;;;;;;;;;;;;;;;OAkBG;;;;;;;;;;;;;;;IAKH;0DACsD;;QAhUtD;;;;;kDAK0C;;;IAgU1C;;;;gCAI4B;;QA5K5B;yCACiC;;;;;YAnBjC;;4DAEgD;;;QAmBhD;oDAC4C;;;;;YAtB5C;;4DAEgD;;;QAsBhD;;;;;;0CAMkC;;;;;YA9BlC;;4DAEgD;;;;IAiMhD;;;;;;;;;;OAUG;;QAlJH;;;;WAIG;;;;;;;;;;;;;;;;;;IAmJH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;IAQH;;;;;;;;;;;;;;;;;;;;;;;;6EAwByE;;kBASzE,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,UAAU,CAAC,SAAS,CAAC,CAEzC"}

package/dist/schema.js

@@ -41,7 +41,7 @@
  * schema change, not a drive-by.
  */
 import { z } from 'zod';
-import { appPublicEnvSchema, strictGadgetDescriptorSchema, } from '@ggui-ai/protocol';
+import { appPublicEnvSchema, parseAnyLlmRoute, strictGadgetDescriptorSchema, } from '@ggui-ai/protocol';
 /**
  * App slug — URL-safe identifier. 2–64 chars, lowercase
  * alphanumeric + hyphens, no leading/trailing hyphen. Used as a
@@ -123,15 +123,23 @@ const AppSchema = z.strictObject({
      */
     publicEnv: appPublicEnvSchema.optional(),
     /**
-     * MCP-Apps presentation mode (canvas slice). `'canvas'` makes
-     * `ggui_new_session` mint a session-scoped iframe
-     * (`ui://ggui/session/<sessionId>`) and route subsequent pushes
-     * through the session WebSocket channel instead of returning a
-     * per-push `ui://ggui/render/<shortCode>` resource. `'inline'`
-     * (default when omitted) preserves the per-push iframe behavior
-     * that flagship MCP-Apps hosts already expect.
+     * App-default display-mode hint stamped on every `ggui_render` from
+     * this app via `_meta.ui.displayMode`. Spec-aligned with MCP App
+     * display literals (`'inline' | 'fullscreen' | 'pip'`).
+     *
+     * Honored by hosts as a PRESENTATION preference — `'fullscreen'`
+     * says "render as a main view"; `'inline'` says "stack vertically in
+     * the chat log"; `'pip'` says "render as picture-in-picture overlay".
+     * The wire mechanism is identical regardless of mode (every push
+     * stamps its own `_meta.ui.resourceUri` and every iframe goes
+     * through the same runtime mount path); display mode controls ONLY
+     * how the host arranges the iframes it mounts. Agents can override
+     * per push via `ggui_render.input.displayMode`.
+     *
+     * Absent ⇒ no per-push hint stamped (host falls back to its own
+     * default, typically `'inline'`).
      */
-    defaultMcpAppsMode: z.enum(['inline', 'canvas']).optional(),
+    defaultDisplayMode: z.enum(['inline', 'fullscreen', 'pip']).optional(),
 });
 /**
  * Operator identity — who's running this server. Surfaced on the
@@ -318,9 +326,9 @@ export const ThemeConfigSchema = z.union([
  * adapters; no surface ever silently creates a file on disk without
  * the operator declaring it here.
  *
- * ## Why `{sessions, vectors}` together
+ * ## Why `{renders, vectors}` together
  *
- * Sessions + vectors are the two substantial persistence surfaces
+ * Renders + vectors are the two substantial persistence surfaces
  * the OSS server honors today. Shipping them in the same block from
  * v1 avoids a second schema churn when vectors or a future store
  * (e.g. threads) lands — there's one `storage` shape and each known
@@ -333,14 +341,14 @@ export const ThemeConfigSchema = z.union([
  * Explicit driver makes the choice visible at a glance — both to
  * the operator reading the file and to future adapters that land
  * against the same interfaces (`postgres`, `redis`, `libsql`, …).
- * A flat `sessions: "./path.sqlite"` shape would bake sqlite into
+ * A flat `renders: "./path.sqlite"` shape would bake sqlite into
  * the schema and force a breaking redesign the first time another
  * driver landed.
  *
  * ## Why per-surface `path` instead of a shared root
  *
- * Sessions + vectors can (and typically should) live in separate
- * files: session data is small + hot-path; vector data is large +
+ * Renders + vectors can (and typically should) live in separate
+ * files: render data is small + hot-path; vector data is large +
  * append-heavy. Coupling them into one file conflates two different
  * IO profiles. Operators who want co-located storage can point both
  * paths at the same file — but the schema doesn't force that.
@@ -360,7 +368,7 @@ export const ThemeConfigSchema = z.union([
  *
  * ## Strictness
  *
- * Root `storage` is strict — unknown surface keys (`sesions: …`,
+ * Root `storage` is strict — unknown surface keys (`rendrs: …`,
  * `vectros: …`, `blueprints: …`) fail parse. Per-surface shapes
  * are discriminated on `driver`; each variant is strict so typos
  * like `{driver: 'sqlite', paht: './x'}` fail immediately.
@@ -386,9 +394,9 @@ const StorageSurfaceSchema = z.discriminatedUnion('driver', [
     StorageSqliteSchema,
 ]);
 const StorageSchema = z.strictObject({
-    /** Session persistence (events + stack + identity). Absent =
-     * in-memory (sessions reset on restart). */
-    sessions: StorageSurfaceSchema.optional(),
+    /** Render persistence (events + identity). Absent = in-memory
+     * (renders reset on restart). */
+    renders: StorageSurfaceSchema.optional(),
     /** Vector index persistence (RAG, blueprint embeddings). Absent =
      * in-memory (index rebuilds on restart). */
     vectors: StorageSurfaceSchema.optional(),
@@ -397,10 +405,49 @@ const StorageSchema = z.strictObject({
      * deployment Portal's self-hosted flow talks to). Pair with
      * `driver: 'sqlite'` + a `path` for durable local storage; the
      * `@ggui-ai/mcp-server-core/sqlite#SqliteThreadStore` reference
-     * impl consumes the same file-per-surface layout the sessions/
+     * impl consumes the same file-per-surface layout the renders/
      * vectors drivers already use. */
     threads: StorageSurfaceSchema.optional(),
 });
+/**
+ * Explicit LLM-route selection for UI generation. The operator
+ * declares which `(provider, model)` the OSS `ggui serve` runs
+ * against — eliminates the surprise where exporting `OPENAI_API_KEY`
+ * silently picks the OpenAI default model.
+ *
+ * `model` accepts EITHER serialization:
+ *   - **Canonical** — `provider:model` (e.g. `anthropic:claude-haiku-4-5-20251001`)
+ *   - **LiteLLM compat** — `provider/model` (e.g. `anthropic/claude-haiku-4-5`)
+ *
+ * Parsed at schema-load time via `parseAnyLlmRoute` and surfaced
+ * as a typed `LlmRoute` for downstream consumers (zero string
+ * threading through the dispatch path).
+ */
+const GenerationSchema = z.strictObject({
+    /**
+     * Typed LLM route — `(provider, model)` parsed at the schema
+     * boundary into a discriminated `LlmRoute`. See
+     * `docs/principles/model-string-convention.md`.
+     */
+    model: z
+        .string()
+        .min(1, 'generation.model must not be empty')
+        .transform((raw, ctx) => {
+        const parsed = parseAnyLlmRoute(raw);
+        if (!parsed) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `generation.model "${raw}" is not a recognized LlmRoute. ` +
+                    `Use the canonical form "provider:model" (e.g. ` +
+                    `"anthropic:claude-haiku-4-5-20251001") or the LiteLLM ` +
+                    `form "provider/model" (e.g. "anthropic/claude-haiku-4-5"). ` +
+                    `See docs/principles/model-string-convention.md.`,
+            });
+            return z.NEVER;
+        }
+        return parsed;
+    }),
+});
 /**
  * The authoritative v1 schema. `z.infer<typeof GguiJsonV1>` yields
  * the static TypeScript type. A valid document round-trips cleanly:
@@ -466,7 +513,19 @@ export const GguiJsonV1 = z.strictObject({
      * default). Present means the operator has opted in per surface
      * — no surface silently creates a file on disk. See
      * {@link StorageConfig}. */
-    storage: StorageSchema.optional().describe('Per-surface storage adapter declarations. Absent = every persistence surface (sessions, threads, vectors, kv) stays in-memory (zero-config OSS default). Present = opt-in per surface; no surface silently creates a file on disk.'),
+    storage: StorageSchema.optional().describe('Per-surface storage adapter declarations. Absent = every persistence surface (renders, threads, vectors, kv) stays in-memory (zero-config OSS default). Present = opt-in per surface; no surface silently creates a file on disk.'),
+    /**
+     * Explicit UI-generation LLM route. Absent + a boot-time provider
+     * key resolves → `ggui serve` hard-fails with an actionable error
+     * pointing here. Absent + no key → graceful boot (the
+     * Connect-Claude card flow handles per-user keys at request time).
+     * Present → use this route verbatim; the schema-side
+     * `parseAnyLlmRoute` transform yields a typed `LlmRoute` so the
+     * dispatch path never sees a string.
+     *
+     * See {@link GenerationConfig}.
+     */
+    generation: GenerationSchema.optional().describe('Explicit UI-generation LLM route. `model` accepts canonical `provider:model` or LiteLLM `provider/model` form. Absent + a boot key resolves → server hard-fails (operator must pick a model). Absent + no key → graceful per-user fallback flow.'),
     /**
      * Default plugin-registry URL for this app.
      *
@@ -501,7 +560,7 @@ export const GguiJsonV1 = z.strictObject({
     /**
      * Local MCP tool mounts — the operator-facing seam for declaring
      * additional tool surfaces that aggregate onto `/mcp` alongside
-     * ggui-native tools (`ggui_push`, etc.). Each entry is a module
+     * ggui-native tools (`ggui_render`, etc.). Each entry is a module
      * specifier:
      *
      *   - Relative paths (`./path/to/mount.js`, `../local/mcp.mjs`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/project-config",
-  "version": "0.1.0-rc.3",
+  "version": "0.2.0-alpha.1",
   "description": "Schema and loader for `ggui.json` — the portable app/agent manifest for the ggui protocol. Vendor-neutral. Consumed by the `ggui` CLI and any host that reconstitutes an agent from the manifest.",
   "keywords": [
     "ggui",
@@ -33,8 +33,8 @@
   "dependencies": {
     "tinyglobby": "^0.2.16",
     "zod": "^4.3.6",
-    "@ggui-ai/protocol": "0.1.0-rc.3",
-    "@ggui-ai/design": "0.1.0-rc.3"
+    "@ggui-ai/protocol": "0.2.0-alpha.1",
+    "@ggui-ai/design": "0.2.0-alpha.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",