@ggui-ai/mcp-server-handlers 0.15.0 → 0.16.0

package/dist/app-discovery/errors.d.ts

@@ -6,10 +6,10 @@
  * handler-flow diagnostics, not contract-shape violations.
  */
 /**
- * Thrown by `ggui_list_gadgets` (and any future tenant-
+ * Thrown by `ggui_list_gadgets` (and any future app-
  * scoped app-discovery tool) when the caller supplies an explicit
  * `appId` that does NOT match `ctx.appId` resolved by the upstream
- * auth adapter. Cross-tenant probes get a uniform error so the
+ * auth adapter. Cross-app probes get a uniform error so the
  * existence of an alternate `appId` is not leaked.
  *
  * Recovery: omit `appId` to default to `ctx.appId`, or call from a

package/dist/app-discovery/errors.js

@@ -6,10 +6,10 @@
  * handler-flow diagnostics, not contract-shape violations.
  */
 /**
- * Thrown by `ggui_list_gadgets` (and any future tenant-
+ * Thrown by `ggui_list_gadgets` (and any future app-
  * scoped app-discovery tool) when the caller supplies an explicit
  * `appId` that does NOT match `ctx.appId` resolved by the upstream
- * auth adapter. Cross-tenant probes get a uniform error so the
+ * auth adapter. Cross-app probes get a uniform error so the
  * existence of an alternate `appId` is not leaked.
  *
  * Recovery: omit `appId` to default to `ctx.appId`, or call from a

package/dist/app-discovery/list-gadgets.d.ts

@@ -14,7 +14,7 @@
  *      `appId` defaults to `ctx.appId` resolved by the upstream auth
  *      adapter.
  *   2. When `appId` is supplied explicitly, asserts it matches
- *      `ctx.appId`; cross-tenant requests fail with
+ *      `ctx.appId`; cross-app requests fail with
  *      {@link AppAccessDeniedError}.
  *   3. Reads `app.gadgets` from the bound {@link AppMetadataStore}
  *      and resolves the effective catalog via `resolveAppGadgets`
@@ -22,7 +22,7 @@
  *      `null` (app not registered — common for OSS sandbox apps that
  *      bypass an explicit register call) the resolution yields
  *      exactly `STDLIB_GADGETS`, so callers always get a meaningful
- *      catalog. This is a permitted-error path, not a tenancy
+ *      catalog. This is a permitted-error path, not an app-scope
  *      escape — `ctx.appId` was already proved by the auth adapter;
  *      the absence of a registry row just means the deployment runs
  *      default-seeded.

package/dist/app-discovery/list-gadgets.js

@@ -14,7 +14,7 @@
  *      `appId` defaults to `ctx.appId` resolved by the upstream auth
  *      adapter.
  *   2. When `appId` is supplied explicitly, asserts it matches
- *      `ctx.appId`; cross-tenant requests fail with
+ *      `ctx.appId`; cross-app requests fail with
  *      {@link AppAccessDeniedError}.
  *   3. Reads `app.gadgets` from the bound {@link AppMetadataStore}
  *      and resolves the effective catalog via `resolveAppGadgets`
@@ -22,7 +22,7 @@
  *      `null` (app not registered — common for OSS sandbox apps that
  *      bypass an explicit register call) the resolution yields
  *      exactly `STDLIB_GADGETS`, so callers always get a meaningful
- *      catalog. This is a permitted-error path, not a tenancy
+ *      catalog. This is a permitted-error path, not an app-scope
  *      escape — `ctx.appId` was already proved by the auth adapter;
  *      the absence of a registry row just means the deployment runs
  *      default-seeded.
@@ -50,7 +50,7 @@ const inputSchema = {
         .string()
         .min(1)
         .optional()
-        .describe('The app id whose gadget catalog to return. Defaults to the caller-resolved app id from the auth header. Cross-tenant requests fail with app_access_denied.'),
+        .describe('The app id whose gadget catalog to return. Defaults to the caller-resolved app id from the auth header. Cross-app requests fail with app_access_denied.'),
 };
 /**
  * Output wire schema for one catalog entry. The handler returns

package/dist/app-discovery/list-themes.d.ts

@@ -9,7 +9,7 @@
  *
  * ## Behavior
  *
- *   1. Validates input shape (`{appId?: string}`). Cross-tenant
+ *   1. Validates input shape (`{appId?: string}`). Cross-app
  *      access protected the same way as `ggui_list_gadgets`.
  *   2. Reads the global theme catalog via the bound `themes` dep
  *      (a `() => readonly ThemeCatalogEntry[]` resolver — keeps the

package/dist/app-discovery/list-themes.js

@@ -9,7 +9,7 @@
  *
  * ## Behavior
  *
- *   1. Validates input shape (`{appId?: string}`). Cross-tenant
+ *   1. Validates input shape (`{appId?: string}`). Cross-app
  *      access protected the same way as `ggui_list_gadgets`.
  *   2. Reads the global theme catalog via the bound `themes` dep
  *      (a `() => readonly ThemeCatalogEntry[]` resolver — keeps the
@@ -31,7 +31,7 @@ const inputSchema = {
         .string()
         .min(1)
         .optional()
-        .describe('App id whose theme catalog to return. Defaults to the caller-resolved app id from the auth header. Cross-tenant requests fail with app_access_denied.'),
+        .describe('App id whose theme catalog to return. Defaults to the caller-resolved app id from the auth header. Cross-app requests fail with app_access_denied.'),
 };
 /**
  * Wire shape for a single theme entry. Mirrors `@ggui-ai/design`'s

package/dist/credits/get-credit-balance.d.ts

@@ -11,13 +11,13 @@
  *
  * Identity scope: credit rows are keyed by USER identity, so the
  * handler reads `ctx.userId` when the host's auth layer resolves a
- * distinct per-user identity (multi-tenant hosts where `ctx.appId`
+ * distinct per-user identity (multi-app hosts where `ctx.appId`
  * names the caller's active app, not the caller), and falls back to
- * `ctx.appId` for single-tenant hosts whose auth adapter folds the
+ * `ctx.appId` for single-app hosts whose auth adapter folds the
  * user into the app slot (`appId = workspaceId ?? userId` — see
  * `packages/mcp-server/src/auth.ts#defaultAppIdFromIdentity`).
  * Reading `ctx.appId` alone silently returns the zero-row fallback
- * for every multi-tenant caller — an app id never keys a credit row.
+ * for every multi-app caller — an app id never keys a credit row.
  * The tool is registered on every deployment kind; callers without a
  * credit account (e.g. agent-builder identities) get the zero-row
  * fallback.

package/dist/credits/get-credit-balance.js

@@ -11,13 +11,13 @@
  *
  * Identity scope: credit rows are keyed by USER identity, so the
  * handler reads `ctx.userId` when the host's auth layer resolves a
- * distinct per-user identity (multi-tenant hosts where `ctx.appId`
+ * distinct per-user identity (multi-app hosts where `ctx.appId`
  * names the caller's active app, not the caller), and falls back to
- * `ctx.appId` for single-tenant hosts whose auth adapter folds the
+ * `ctx.appId` for single-app hosts whose auth adapter folds the
  * user into the app slot (`appId = workspaceId ?? userId` — see
  * `packages/mcp-server/src/auth.ts#defaultAppIdFromIdentity`).
  * Reading `ctx.appId` alone silently returns the zero-row fallback
- * for every multi-tenant caller — an app id never keys a credit row.
+ * for every multi-app caller — an app id never keys a credit row.
  * The tool is registered on every deployment kind; callers without a
  * credit account (e.g. agent-builder identities) get the zero-row
  * fallback.
@@ -43,13 +43,13 @@ export function createGetCreditBalanceHandler(deps) {
         description: "Returns the calling user's prepaid Anthropic-pool credit balance. Surfaces balanceCents (current spendable), lifetimeGrantedCents (total received including the $5 welcome credit), and lifetimeSpentCents (cumulative charges). For non-Anthropic providers, configure a BYOK key at console.ggui.ai/keys/providers — credit doesn't apply. Composing blueprints in Claude Desktop bypasses credits entirely.",
         inputSchema,
         outputSchema,
-        // No `allowedFor` — same toolset on every pod kind. Callers
+        // No `allowedFor` — same toolset on every deployment kind. Callers
         // without a credit account get the zero-row fallback below; no
         // separate "tool not registered" UX needed.
         async handler(_input, ctx) {
-            // USER identity first — on multi-tenant hosts `ctx.appId` is the
+            // USER identity first — on multi-app hosts `ctx.appId` is the
             // caller's active app, which never keys a credit row (see the
-            // module docstring). Single-tenant hosts leave `ctx.userId`
+            // module docstring). Single-app hosts leave `ctx.userId`
             // unset and fold the user into the app slot.
             const userId = ctx.userId ?? ctx.appId;
             if (!userId) {

package/dist/credits/list-credit-transactions.d.ts

@@ -12,15 +12,14 @@
  *
  * Identity scope mirrors get-credit-balance: `ctx.userId` when the
  * host resolves a distinct per-user identity, else `ctx.appId` (the
- * single-tenant fold) — see that module's docstring for why reading
- * `ctx.appId` alone loses every multi-tenant caller.
+ * single-app fold) — see that module's docstring for why reading
+ * `ctx.appId` alone loses every multi-app caller.
  */
 import { z } from 'zod';
 /**
- * Read-only seam for the credit-transaction ledger. The pod's
- * `DdbCreditStore.listTransactions` (in
- * `mcp-servers/ggui-protocol/src/adapters/credit-store.ts`) implements
- * this directly via raw DDB Query.
+ * Read-only seam for the credit-transaction ledger. A production deployment
+ * implements this against its own ledger store; tests use in-memory
+ * state.
  */
 export interface CreditTransactionSource {
     list(args: {

package/dist/credits/list-credit-transactions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-credit-transactions.d.ts","sourceRoot":"","sources":["../../src/credits/list-credit-transactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,IAAI,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,oCAAoC;QACpC,KAAK,EAAE,MAAM,CAAC;QACd,4EAA4E;QAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QACV,YAAY,EAAE,qBAAqB,EAAE,CAAC;QACtC,6CAA6C;QAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,kBAAkB,EAAE,uBAAuB,CAAC;CACtD;AAyBD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,qBAAqB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,0BAA0B;IA5BhC,2BAA2B;;IAE3B,kEAAkE;;;;;;;;;;;;;;;;;IAgBlE,oFAAoF;;;;;GAgDrF"}
+{"version":3,"file":"list-credit-transactions.d.ts","sourceRoot":"","sources":["../../src/credits/list-credit-transactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,IAAI,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,oCAAoC;QACpC,KAAK,EAAE,MAAM,CAAC;QACd,4EAA4E;QAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QACV,YAAY,EAAE,qBAAqB,EAAE,CAAC;QACtC,6CAA6C;QAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,kBAAkB,EAAE,uBAAuB,CAAC;CACtD;AAyBD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,qBAAqB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,0BAA0B;IA5BhC,2BAA2B;;IAE3B,kEAAkE;;;;;;;;;;;;;;;;;IAgBlE,oFAAoF;;;;;GAgDrF"}

package/dist/credits/list-credit-transactions.js

@@ -12,8 +12,8 @@
  *
  * Identity scope mirrors get-credit-balance: `ctx.userId` when the
  * host resolves a distinct per-user identity, else `ctx.appId` (the
- * single-tenant fold) — see that module's docstring for why reading
- * `ctx.appId` alone loses every multi-tenant caller.
+ * single-app fold) — see that module's docstring for why reading
+ * `ctx.appId` alone loses every multi-app caller.
  */
 import { z } from 'zod';
 import { defineHandler } from '../types.js';
@@ -44,11 +44,11 @@ export function createListCreditTransactionsHandler(deps) {
         description: "Returns the calling user's credit transaction ledger, newest-first. Each row carries kind ('free_credit' | 'render_charge' | 'topup' | 'refund'), deltaCents (signed — positive for grants/topups, negative for charges), balanceAfterCents (snapshot at time of write), reason (human-readable), and optional relatedSessionId for render_charge rows. Default limit 20, cap 100; pass `cursor` from the previous response's `nextCursor` for paging.",
         inputSchema,
         outputSchema,
-        // No `allowedFor` — same toolset on every pod kind. Callers
+        // No `allowedFor` — same toolset on every deployment kind. Callers
         // without a credit account see an empty ledger.
         async handler(rawInput, ctx) {
             // USER identity first — `ctx.appId` is the active app on
-            // multi-tenant hosts and never keys a ledger row (see
+            // multi-app hosts and never keys a ledger row (see
             // get-credit-balance's module docstring).
             const userId = ctx.userId ?? ctx.appId;
             if (!userId) {

package/dist/ops-apps/delete-app.d.ts

@@ -2,7 +2,7 @@
  * `ggui_ops_delete_app` — hard-delete an app record owned by the
  * caller.
  *
- * Tenancy: cross-tenant probes return the success shape WITHOUT
+ * Ownership: cross-user probes return the success shape WITHOUT
  * touching the row (uniform shape; no existence leak). Idempotent —
  * a second delete of the same id resolves cleanly.
  *
@@ -12,7 +12,7 @@
  *
  * The check runs AFTER the ownership read. `getDefault(ownerSub)`
  * only ever reads the caller's own row, so ordering is not what keeps
- * another tenant's default secret — nothing here could read it under
+ * another owner's default secret — nothing here could read it under
  * any ordering. What ordering buys is SHAPE UNIFORMITY in the one
  * state where the two branches disagree: the caller's own default
  * naming an app the caller does not own. Ownership first answers that

package/dist/ops-apps/delete-app.js

@@ -2,7 +2,7 @@
  * `ggui_ops_delete_app` — hard-delete an app record owned by the
  * caller.
  *
- * Tenancy: cross-tenant probes return the success shape WITHOUT
+ * Ownership: cross-user probes return the success shape WITHOUT
  * touching the row (uniform shape; no existence leak). Idempotent —
  * a second delete of the same id resolves cleanly.
  *
@@ -12,7 +12,7 @@
  *
  * The check runs AFTER the ownership read. `getDefault(ownerSub)`
  * only ever reads the caller's own row, so ordering is not what keeps
- * another tenant's default secret — nothing here could read it under
+ * another owner's default secret — nothing here could read it under
  * any ordering. What ordering buys is SHAPE UNIFORMITY in the one
  * state where the two branches disagree: the caller's own default
  * naming an app the caller does not own. Ownership first answers that
@@ -48,7 +48,7 @@ export function createDeleteAppHandler(deps) {
         name: 'ggui_ops_delete_app',
         title: 'Delete app',
         audience: ['ops'],
-        description: "Hard-delete an app owned by the calling user. Removes the APP RECORD only — data other stores hold for that app (saved blueprints, per-app provider keys, marketplace installs, issued keys) is not removed by this call, and whether the deployment cleans it up separately is the deployment's own policy. Idempotent — a second delete returns `{deleted: true}`. Cross-tenant probes return the same shape without touching foreign rows (no existence leak). Throws `default_app_delete_blocked` when the target is the caller's default app — set a different default first.",
+        description: "Hard-delete an app owned by the calling user. Removes the APP RECORD only — data other stores hold for that app (saved blueprints, per-app provider keys, marketplace installs, issued keys) is not removed by this call, and whether the deployment cleans it up separately is the deployment's own policy. Idempotent — a second delete returns `{deleted: true}`. Probes at an app owned by another user return the same shape without touching foreign rows (no existence leak). Throws `default_app_delete_blocked` when the target is the caller's default app — set a different default first.",
         inputSchema,
         outputSchema,
         async handler(rawInput, ctx) {
@@ -62,7 +62,7 @@ export function createDeleteAppHandler(deps) {
                 // Either the row doesn't exist or it lives under a different
                 // owner. Either way: return the success shape without
                 // touching the store. Uniform across "missing" and
-                // "cross-tenant" prevents id-existence leak.
+                // "cross-user" prevents id-existence leak.
                 return { deleted: true };
             }
             // AFTER the ownership read, so a caller whose own default names

package/dist/ops-apps/identity.d.ts

@@ -2,7 +2,7 @@
  * Per-call identity resolution for `ops-apps` handlers. The console
  * surfaces these tools call against `kind: 'user'` identities — the
  * upstream `AuthAdapter` populates `ctx.userId` directly. OSS
- * single-tenant mode (where the auth adapter collapses `appId =
+ * single-app mode (where the auth adapter collapses `appId =
  * workspaceId ?? userId`) leaves `ctx.userId` undefined and the same
  * value sits on `ctx.appId`. Read whichever is set; fail when neither
  * is.

package/dist/ops-apps/index.d.ts

@@ -21,8 +21,8 @@ export { createCreateAppHandler } from './create-app.js';
 export type { CreateAppDeps, CreateAppOutput } from './create-app.js';
 export { createUpdateAppHandler } from './update-app.js';
 export type { UpdateAppDeps, UpdateAppOutput } from './update-app.js';
-export { createSetAppThemeHandler } from './set-app-theme.js';
-export type { SetAppThemeDeps, SetAppThemeOutput, } from './set-app-theme.js';
+export { createSetAppThemeHandler, admitAppTheme } from './set-app-theme.js';
+export type { SetAppThemeDeps, SetAppThemeOutput, OverlayCoverageValidator, AppThemeAdmission, } from './set-app-theme.js';
 export { createDeleteAppHandler } from './delete-app.js';
 export type { DeleteAppDeps, DeleteAppOutput } from './delete-app.js';
 export { createSetDefaultAppHandler } from './set-default-app.js';

package/dist/ops-apps/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ops-apps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ops-apps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7E,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}

package/dist/ops-apps/index.js

@@ -17,6 +17,6 @@ export { AppNotFoundError, DefaultAppDeleteBlockedError, OpsAppsAccessDeniedErro
 export { createListAppsHandler } from './list-apps.js';
 export { createCreateAppHandler } from './create-app.js';
 export { createUpdateAppHandler } from './update-app.js';
-export { createSetAppThemeHandler } from './set-app-theme.js';
+export { createSetAppThemeHandler, admitAppTheme } from './set-app-theme.js';
 export { createDeleteAppHandler } from './delete-app.js';
 export { createSetDefaultAppHandler } from './set-default-app.js';

package/dist/ops-apps/list-apps.d.ts

@@ -2,12 +2,12 @@
  * `ggui_ops_list_apps` — enumerate the calling user's `GguiApp` rows.
  *
  * Sibling of the console's Apps section (`apps/console/src/.../apps/`)
- * — same data, MCP surface. Pure over the {@link AppsSource} seam; the
- * cloud pod binds an AppSync-backed implementation, tests bind an
+ * — same data, MCP surface. Pure over the {@link AppsSource} seam; a
+ * production deployment binds its own implementation, tests bind an
  * in-memory Map.
  *
  * Identity scope: caller's Cognito sub from `ctx.userId` (or
- * `ctx.appId` in OSS single-tenant mode). Cross-user list is impossible
+ * `ctx.appId` in OSS single-app mode). Cross-user list is impossible
  * by construction — `AppsSource.list` only returns rows whose
  * `ownerSub` matches.
  */

package/dist/ops-apps/list-apps.js

@@ -2,12 +2,12 @@
  * `ggui_ops_list_apps` — enumerate the calling user's `GguiApp` rows.
  *
  * Sibling of the console's Apps section (`apps/console/src/.../apps/`)
- * — same data, MCP surface. Pure over the {@link AppsSource} seam; the
- * cloud pod binds an AppSync-backed implementation, tests bind an
+ * — same data, MCP surface. Pure over the {@link AppsSource} seam; a
+ * production deployment binds its own implementation, tests bind an
  * in-memory Map.
  *
  * Identity scope: caller's Cognito sub from `ctx.userId` (or
- * `ctx.appId` in OSS single-tenant mode). Cross-user list is impossible
+ * `ctx.appId` in OSS single-app mode). Cross-user list is impossible
  * by construction — `AppsSource.list` only returns rows whose
  * `ownerSub` matches.
  */

package/dist/ops-apps/set-app-theme.d.ts

@@ -1,95 +1,216 @@
 /**
  * `ggui_ops_set_app_theme` — replace the theme on a `GguiApp` row the
- * caller owns.
+ * caller owns. The MCP write door for the per-app theme (ggui#987
+ * §3.4).
  *
- * The theme payload is validated with the protocol's canonical
- * {@link appThemeSchema} — the SAME validator every other write
- * surface for `GguiApp.theme` runs — so no surface can persist a
- * theme another surface would reject: `--ggui-*` CSS-variable keys
- * only, value-level breakout characters forbidden, ≤200 variables.
+ * A theme is the PROJECTION: both modes' derived `--ggui-*` sets plus
+ * the attestation that names them. The door admits it in three
+ * checks, the SAME three every other write door for `GguiApp.theme`
+ * runs, so no surface can persist a theme another surface would
+ * refuse:
  *
- * Tenancy: `AppsSource.get` first (scoped by `ownerSub`); cross-user
+ *   1. shape — protocol's `appThemeSchema` (v2, `.strict()`); the
+ *      retired one-palette body is named as such (`refused: 'v1
+ *      shape'`) rather than failing as a pile of missing fields;
+ *   2. attestation — `overlayHash` is recomputed with
+ *      `canonicalOverlayHash` and a mismatch is refused;
+ *   3. coverage — the injected overlay validator judges each mode's
+ *      set against the consumed-token manifest: a key outside the
+ *      manifest (`unknown`) or a consumed token left unset
+ *      (`uncovered`) is refused, per mode.
+ *
+ * A refusal is a schema-conformant `{ ok: false, code:
+ * 'invalid_app_config', refusal }` RESULT (not a thrown error): the
+ * body is one of the four the protocol names
+ * (`appThemeRefusalBodySchema`), so a client reads the same refusal
+ * from REST, AppSync and this door.
+ *
+ * Ownership: `AppsSource.get` first (scoped by `ownerSub`); cross-user
  * probes return the uniform "not found" shape. The store scopes the
  * write itself to the owner as well.
  *
- * Pure over the {@link AppsSource} seam.
+ * Pure over the {@link AppsSource} seam + the injected validator.
  */
-import { appThemeSchema } from '@ggui-ai/protocol';
+import { type AppTheme, type AppThemeRefusalBody } from '@ggui-ai/protocol';
 import { z } from 'zod';
+import { type SharedHandlerResult } from '../types.js';
 import type { AppsSource } from './types.js';
-export interface SetAppThemeOutput {
-    readonly appId: string;
-    readonly theme: z.infer<typeof appThemeSchema>;
-    readonly updatedAt: string;
-    readonly warning?: string;
-}
+/**
+ * The coverage judgement over ONE mode's overlay, as `@ggui-ai/design`'s
+ * `validateOverlayCoverage` reports it. Injected rather than imported:
+ * the manifest is the design package's, and the composer binds it.
+ */
+export type OverlayCoverageValidator = (overlay: Readonly<Record<string, string>>) => {
+    readonly uncovered: readonly string[];
+    readonly unknown: readonly string[];
+    readonly warnings: readonly string[];
+};
+declare const outputSchema: {
+    readonly ok: z.ZodBoolean;
+    readonly appId: z.ZodOptional<z.ZodString>;
+    readonly theme: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+        overlayHash: z.ZodString;
+        overlays: z.ZodObject<{
+            light: z.ZodRecord<z.ZodString, z.ZodString>;
+            dark: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>;
+        cssVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        keyframes: z.ZodOptional<z.ZodObject<{
+            light: z.ZodOptional<z.ZodString>;
+            dark: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        frameless: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    readonly updatedAt: z.ZodOptional<z.ZodString>;
+    /** Present on a refusal: the one refusal class this door emits. */
+    readonly code: z.ZodOptional<z.ZodLiteral<"invalid_app_config">>;
+    /** Present on a coverage / attestation / v1-shape refusal — one of the four protocol-named bodies. */
+    readonly refusal: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        uncovered: z.ZodObject<{
+            light: z.ZodArray<z.ZodString>;
+            dark: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        unknown: z.ZodObject<{
+            light: z.ZodArray<z.ZodString>;
+            dark: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        overlayHash: z.ZodLiteral<"mismatch">;
+    }, z.core.$strict>, z.ZodObject<{
+        refused: z.ZodLiteral<"v1 shape">;
+    }, z.core.$strict>]>>;
+    /** Present on a shape refusal the schema itself raised — its messages, one per issue. */
+    readonly issues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+};
+/** Derived from the output schema — one shape, never a hand mirror. */
+export type SetAppThemeOutput = z.infer<z.ZodObject<typeof outputSchema>>;
 export interface SetAppThemeDeps {
     readonly apps: AppsSource;
-    /**
-     * Known theme ids (built-in presets + registered) for the
-     * brand-shaped-overlay WARN's name resolution. Absent = names cannot
-     * be resolved, so brand-scale coverage always draws the nudge.
-     */
-    readonly knownThemeIds?: readonly string[];
+    /** Coverage judgement per mode — bind to `validateOverlayCoverage` from `@ggui-ai/design`. */
+    readonly overlayCoverage: OverlayCoverageValidator;
 }
+/** The door's verdict on a raw body: the theme to persist, or why not. */
+export type AppThemeAdmission = {
+    readonly ok: true;
+    readonly theme: AppTheme;
+} | {
+    readonly ok: false;
+    readonly refusal: AppThemeRefusalBody;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
 /**
- * Detect a BRAND-SHAPED overlay (ggui#598 slice 3): ≥3 distinct color
- * families in the variable map while the overlay's `name` resolves to
- * no known theme. A brand living in the accent tier is the round-3
- * mechanism — the overlay inherits every unmapped token from someone
- * else's ladder. The WARN names the registration path; it never
- * blocks. Exported for its unit pins.
- *
- * @internal
+ * Admit a raw theme body: shape, attestation, coverage — in that order,
+ * first failure wins; `unknown` outranks `uncovered` because a key the
+ * manifest does not name is the more fundamental disagreement. Exported
+ * so any other in-process door runs exactly these checks.
  */
-export declare function detectBrandShapedOverlay(theme: z.infer<typeof appThemeSchema>, deps: Pick<SetAppThemeDeps, 'knownThemeIds'>): string | undefined;
+export declare function admitAppTheme(raw: unknown, overlayCoverage: OverlayCoverageValidator): Promise<AppThemeAdmission>;
 export declare function createSetAppThemeHandler(deps: SetAppThemeDeps): import("../types.js").SharedHandler<{
     readonly appId: z.ZodString;
     readonly theme: z.ZodObject<{
-        mode: z.ZodEnum<{
+        mode: z.ZodOptional<z.ZodEnum<{
             light: "light";
             dark: "dark";
-        }>;
-        cssVariables: z.ZodRecord<z.ZodString, z.ZodString>;
+        }>>;
         name: z.ZodOptional<z.ZodString>;
-        base: z.ZodOptional<z.ZodObject<{
-            documentHash: z.ZodString;
+        overlayHash: z.ZodString;
+        overlays: z.ZodObject<{
             light: z.ZodRecord<z.ZodString, z.ZodString>;
             dark: z.ZodRecord<z.ZodString, z.ZodString>;
-            keyframes: z.ZodOptional<z.ZodObject<{
-                light: z.ZodOptional<z.ZodString>;
-                dark: z.ZodOptional<z.ZodString>;
-            }, z.core.$strict>>;
-            frameless: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        cssVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        keyframes: z.ZodOptional<z.ZodObject<{
+            light: z.ZodOptional<z.ZodString>;
+            dark: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+        frameless: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
 }, {
-    readonly appId: z.ZodString;
-    readonly theme: z.ZodObject<{
-        mode: z.ZodEnum<{
+    readonly ok: z.ZodBoolean;
+    readonly appId: z.ZodOptional<z.ZodString>;
+    readonly theme: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
             light: "light";
             dark: "dark";
-        }>;
-        cssVariables: z.ZodRecord<z.ZodString, z.ZodString>;
+        }>>;
         name: z.ZodOptional<z.ZodString>;
-        base: z.ZodOptional<z.ZodObject<{
-            documentHash: z.ZodString;
+        overlayHash: z.ZodString;
+        overlays: z.ZodObject<{
             light: z.ZodRecord<z.ZodString, z.ZodString>;
             dark: z.ZodRecord<z.ZodString, z.ZodString>;
-            keyframes: z.ZodOptional<z.ZodObject<{
-                light: z.ZodOptional<z.ZodString>;
-                dark: z.ZodOptional<z.ZodString>;
-            }, z.core.$strict>>;
-            frameless: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        cssVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        keyframes: z.ZodOptional<z.ZodObject<{
+            light: z.ZodOptional<z.ZodString>;
+            dark: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
-    }, z.core.$strict>;
-    readonly updatedAt: z.ZodString;
-    /**
-     * Migration nudge (ggui#598 slice 3): present when the overlay is
-     * BRAND-SHAPED — ≥3 color families over a name that resolves to no
-     * registered theme. The write still succeeds (overlays stay legal);
-     * the tier just stops being silent about brands living in it.
-     */
-    readonly warning: z.ZodOptional<z.ZodString>;
-}, SetAppThemeOutput>;
+        frameless: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    readonly updatedAt: z.ZodOptional<z.ZodString>;
+    /** Present on a refusal: the one refusal class this door emits. */
+    readonly code: z.ZodOptional<z.ZodLiteral<"invalid_app_config">>;
+    /** Present on a coverage / attestation / v1-shape refusal — one of the four protocol-named bodies. */
+    readonly refusal: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        uncovered: z.ZodObject<{
+            light: z.ZodArray<z.ZodString>;
+            dark: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        unknown: z.ZodObject<{
+            light: z.ZodArray<z.ZodString>;
+            dark: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        overlayHash: z.ZodLiteral<"mismatch">;
+    }, z.core.$strict>, z.ZodObject<{
+        refused: z.ZodLiteral<"v1 shape">;
+    }, z.core.$strict>]>>;
+    /** Present on a shape refusal the schema itself raised — its messages, one per issue. */
+    readonly issues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, SharedHandlerResult<{
+    ok: boolean;
+    appId?: string | undefined;
+    theme?: {
+        overlayHash: string;
+        overlays: {
+            light: Record<string, string>;
+            dark: Record<string, string>;
+        };
+        mode?: "light" | "dark" | undefined;
+        name?: string | undefined;
+        cssVariables?: Record<string, string> | undefined;
+        keyframes?: {
+            light?: string | undefined;
+            dark?: string | undefined;
+        } | undefined;
+        frameless?: boolean | undefined;
+    } | undefined;
+    updatedAt?: string | undefined;
+    code?: "invalid_app_config" | undefined;
+    refusal?: {
+        uncovered: {
+            light: string[];
+            dark: string[];
+        };
+    } | {
+        unknown: {
+            light: string[];
+            dark: string[];
+        };
+    } | {
+        overlayHash: "mismatch";
+    } | {
+        refused: "v1 shape";
+    } | undefined;
+    issues?: string[] | undefined;
+}>>;
+export {};
 //# sourceMappingURL=set-app-theme.d.ts.map