@yaklabs-ai/plugin-sdk 0.46.0 → 0.47.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.46.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.47.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.46.0" },
+  "compatibility": { "sdk": "^0.47.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [
@@ -34,6 +34,17 @@
       "licenseSource": "https://github.com/sinclairzx81/typebox/blob/1.3.27/license",
       "upstreamCommit": "ffe23ba614322bf0dcb846ceaf7c1bbc7ef0bba6",
       "noticeFile": "THIRD-PARTY-NOTICES.md"
+    },
+    {
+      "name": "@json-render/core",
+      "version": "0.19.0",
+      "license": "Apache-2.0",
+      "copyright": "Copyright 2025 Vercel Inc.",
+      "source": "https://github.com/vercel-labs/json-render/tree/0bbe6ed6394b23b5aee25320d03c9b7ac717e5b7/packages/core",
+      "licenseSource": "https://github.com/vercel-labs/json-render/blob/0bbe6ed6394b23b5aee25320d03c9b7ac717e5b7/LICENSE",
+      "upstreamCommit": "0bbe6ed6394b23b5aee25320d03c9b7ac717e5b7",
+      "note": "Type declarations are flattened into this package; runtime code is not bundled.",
+      "noticeFile": "THIRD-PARTY-NOTICES.md"
     }
   ],
   "external": [

package/THIRD-PARTY-NOTICES.md

@@ -1,16 +1,18 @@
 # Third-party notices
 
-This package bundles 3 first-party-selected component(s). The notices below are reproduced verbatim from each component's upstream MIT license source.
+This package bundles 4 first-party-selected component(s). The notices below are reproduced verbatim from each component's upstream license source.
 
 ## @earendil-works/pi-ai@1.4.0
 
 - Source: https://github.com/earendil-works/pi/tree/v1.4.0/packages/ai
+- License: MIT
 - License source: https://github.com/earendil-works/pi/blob/v1.4.0/LICENSE
 - Upstream commit: 4a080252f06caf63a525d7873c5d94d3c23887e0
 
 ## @earendil-works/chord@1.4.0
 
 - Source: https://github.com/earendil-works/pi/tree/v1.4.0/packages/chord
+- License: MIT
 - License source: https://github.com/earendil-works/pi/blob/v1.4.0/LICENSE
 - Upstream commit: 4a080252f06caf63a525d7873c5d94d3c23887e0
 
@@ -41,6 +43,7 @@ SOFTWARE.
 ## typebox@1.3.27
 
 - Source: https://github.com/sinclairzx81/typebox/tree/1.3.27
+- License: MIT
 - License source: https://github.com/sinclairzx81/typebox/blob/1.3.27/license
 - Upstream commit: ffe23ba614322bf0dcb846ceaf7c1bbc7ef0bba6
 
@@ -70,4 +73,216 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+## @json-render/core@0.19.0
+
+- Source: https://github.com/vercel-labs/json-render/tree/0bbe6ed6394b23b5aee25320d03c9b7ac717e5b7/packages/core
+- License: Apache-2.0
+- License source: https://github.com/vercel-labs/json-render/blob/0bbe6ed6394b23b5aee25320d03c9b7ac717e5b7/LICENSE
+- Upstream commit: 0bbe6ed6394b23b5aee25320d03c9b7ac717e5b7
+- Integration: Type declarations are flattened into this package; runtime code is not bundled.
+
+License text for the component(s) above, verbatim from the license source:
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 Vercel Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
 The package's own code is licensed under the MIT License in `LICENSE`.

package/dist/canonical-transcript.d.ts

@@ -6902,6 +6902,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodNumber>;
         editIndex: z.ZodOptional<z.ZodNumber>;
         occurrences: z.ZodOptional<z.ZodNumber>;

package/dist/canonical-transcript.js

@@ -730,6 +730,7 @@ var toolCallFailureDetailsSchema = z5.strictObject({
   errorName: z5.string().optional(),
   errorCode: z5.string().optional(),
   providerCode: z5.string().optional(),
+  provider: z5.string().optional(),
   status: z5.number().int().min(100).max(599).optional(),
   editIndex: count.optional(),
   occurrences: count.optional(),

package/dist/disclosure.d.ts

@@ -2442,8 +2442,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
+ *
+ * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7819,6 +7821,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodNumber>;
         editIndex: z.ZodOptional<z.ZodNumber>;
         occurrences: z.ZodOptional<z.ZodNumber>;
@@ -10533,9 +10536,6 @@ declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
-    presentation: z.ZodOptional<z.ZodObject<{
-        app: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-agent-testing.d.ts

@@ -2496,8 +2496,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
+ *
+ * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4872,9 +4874,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             storage: "storage";
             uriModule: "uriModule";
             authService: "authService";
-            app: "app";
             command: "command";
-            configSection: "configSection";
+            app: "app";
             skill: "skill";
             converter: "converter";
             artifactUriModule: "artifactUriModule";
@@ -4897,11 +4898,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             mcpServer: "mcpServer";
             uiCommand: "uiCommand";
             uiSlot: "uiSlot";
-            settingsPanel: "settingsPanel";
-            resultRenderer: "resultRenderer";
             referencePresentation: "referencePresentation";
-            view: "view";
             theme: "theme";
+            configSection: "configSection";
         }>;
         localId: z.ZodString;
         globalId: z.ZodString;
@@ -5754,9 +5753,6 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             bodyField: z.ZodString;
         }, z.core.$strict>], "kind">;
         valueSchema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
-        presentation: z.ZodOptional<z.ZodObject<{
-            app: z.ZodString;
-        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     kayAppMcpServers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -8996,6 +8992,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodNumber>;
         editIndex: z.ZodOptional<z.ZodNumber>;
         occurrences: z.ZodOptional<z.ZodNumber>;
@@ -11710,9 +11707,6 @@ declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
-    presentation: z.ZodOptional<z.ZodObject<{
-        app: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-agent.d.ts

@@ -2771,8 +2771,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
+ *
+ * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -9049,6 +9051,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodNumber>;
         editIndex: z.ZodOptional<z.ZodNumber>;
         occurrences: z.ZodOptional<z.ZodNumber>;
@@ -12058,9 +12061,6 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
-    presentation: z.ZodOptional<z.ZodObject<{
-        app: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-app.d.ts

@@ -34,6 +34,60 @@ export declare interface AccessApprovalTypeDefinition {
     }, ctx: AccessApprovalContext) => Promise<FinalizedAccessApproval>;
 }
 
+/**
+ * Action binding — maps an event to an action invocation.
+ *
+ * Used inside the `on` field of a UIElement:
+ * ```json
+ * { "on": { "press": { "action": "setState", "params": { "statePath": "/x", "value": 1 } } } }
+ * ```
+ */
+declare interface ActionBinding {
+    /** Action name (must be in catalog) */
+    action: string;
+    /** Parameters to pass to the action handler */
+    params?: Record<string, DynamicValue>;
+    /** Confirmation dialog before execution */
+    confirm?: ActionConfirm;
+    /** Handler after successful execution */
+    onSuccess?: ActionOnSuccess;
+    /** Handler after failed execution */
+    onError?: ActionOnError;
+    /** Whether to prevent default browser behavior (e.g. navigation on links) */
+    preventDefault?: boolean;
+}
+
+/**
+ * Confirmation dialog configuration
+ */
+declare interface ActionConfirm {
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    variant?: "default" | "danger";
+}
+
+/**
+ * Action error handler
+ */
+declare type ActionOnError = {
+    set: Record<string, unknown>;
+} | {
+    action: string;
+};
+
+/**
+ * Action success handler
+ */
+declare type ActionOnSuccess = {
+    navigate: string;
+} | {
+    set: Record<string, unknown>;
+} | {
+    action: string;
+};
+
 declare const AdapterPlacement: z.ZodEnum<{
     "local-only": "local-only";
     anywhere: "anywhere";
@@ -107,6 +161,15 @@ export declare type AgentToolUpdateCallback<T = any> = (partialResult: AgentTool
 
 declare const Alpha: TAlpha;
 
+/**
+ * AND wrapper — all child conditions must be true.
+ * This is the explicit form of the implicit array AND (`SingleCondition[]`).
+ * Unlike the implicit form, `$and` supports nested `$or` and `$and` conditions.
+ */
+declare type AndCondition = {
+    $and: VisibilityCondition[];
+};
+
 /** Compatibility settings for Anthropic Messages-compatible APIs. */
 declare interface AnthropicMessagesCompat extends Static<typeof AnthropicMessagesCompatSchema> {
 }
@@ -581,6 +644,9 @@ declare function Capitalize_2<Type extends TSchema>(type: Type, options?: TSchem
 /** Creates a deferred Capitalize action. */
 declare function CapitalizeDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TCapitalizeDeferred<Type>;
 
+/** Build a json-render card; state is shared by every child through JSON pointers. */
+export declare function card(title: string, children: readonly KayAppCardLayout[], state?: Record<string, unknown>): KayAppCardLayout;
+
 declare namespace Char {
     export {
         TAlpha,
@@ -676,6 +742,34 @@ declare const CompareResultLeftInside = 2;
 
 declare const CompareResultRightInside = 3;
 
+/**
+ * Shared comparison operators for visibility conditions.
+ *
+ * Use at most ONE comparison operator per condition. If multiple are
+ * provided, only the first matching one is evaluated (precedence:
+ * eq > neq > gt > gte > lt > lte). With no operator, truthiness is checked.
+ *
+ * `not` inverts the final result of whichever operator (or truthiness
+ * check) is used.
+ */
+declare type ComparisonOperators = {
+    eq?: unknown;
+    neq?: unknown;
+    gt?: number | {
+        $state: string;
+    };
+    gte?: number | {
+        $state: string;
+    };
+    lt?: number | {
+        $state: string;
+    };
+    lte?: number | {
+        $state: string;
+    };
+    not?: true;
+};
+
 declare const COMPOSER_REFERENCES_CUSTOM_TYPE = "composer_references";
 
 declare interface ComposerReferencesDetails {
@@ -1193,6 +1287,16 @@ declare interface DynamicContextSection {
     readonly items?: readonly DynamicContextItem[];
 }
 
+/**
+ * Dynamic value - can be a literal or a `{ $state }` reference to the state model.
+ *
+ * Used in action params and validation args where values can either be
+ * hardcoded or resolved from state at runtime.
+ */
+declare type DynamicValue<T = unknown> = T | {
+    $state: string;
+};
+
 declare const Element: (input: string) => [unknown, string] | [];
 
 declare const ElementBase: (input: string) => [unknown, string] | [];
@@ -1715,6 +1819,14 @@ declare const IndexArray_0: (input: string, result?: unknown[]) => [unknown[], s
 
 declare function IndexArrayMapping(input: ([unknown, unknown, unknown] | [unknown, unknown])[]): unknown;
 
+/**
+ * A condition that resolves `$index` to the current repeat array index.
+ * Only meaningful inside a `repeat` scope.
+ */
+declare type IndexCondition = {
+    $index: true;
+} & ComparisonOperators;
+
 /** Creates a deferred Index action. */
 declare function IndexDeferred<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer, options?: TSchemaOptions): TIndexDeferred<Type, Indexer>;
 
@@ -2005,6 +2117,16 @@ declare function IsUnsafe(value: unknown): value is TUnsafe;
 /** Returns true if the given value is TVoid. */
 declare function IsVoid(value: unknown): value is TVoid;
 
+/**
+ * A condition that resolves `$item` to a field on the current repeat item.
+ * Only meaningful inside a `repeat` scope.
+ *
+ * Use `""` to reference the whole item, or `"field"` for a specific field.
+ */
+declare type ItemCondition = {
+    $item: string;
+} & ComparisonOperators;
+
 declare const JsonObject: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
 
 declare type JsonObject = z.infer<typeof JsonObject>;
@@ -2756,8 +2878,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
+ *
+ * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3983,17 +4107,38 @@ export declare interface KayAppBackgroundCredentialRequest {
     readonly jobId: string;
 }
 
+export declare interface KayAppCardFieldOptions {
+    readonly label: string;
+    readonly placeholder?: string;
+    readonly required?: boolean;
+}
+
 /** The background operations of a manifest-declared plugin card. */
 export declare interface KayAppCardImplementation<Input = unknown, Data = unknown, Values = unknown> {
-    read(inputs: Input): KayAppCardResult<Data> | Promise<KayAppCardResult<Data>>;
+    read(inputs: Input): KayAppCardReadResult<Data> | Promise<KayAppCardReadResult<Data>>;
     submit(request: {
         readonly inputs: Input;
         readonly values: Values;
-    }): KayAppCardResult<Data> | Promise<KayAppCardResult<Data>>;
+    }): KayAppCardSubmitResult<Data> | Promise<KayAppCardSubmitResult<Data>>;
 }
 
+export declare type KayAppCardLayout = Extract<PluginCardReadResult<never>, {
+    presentation: "layout";
+}>["layout"];
+
+export declare type KayAppCardReadResult<T> = PluginCardReadResult<T>;
+
 export declare type KayAppCardResult<T> = PluginCardResult<T>;
 
+export declare interface KayAppCardSelectOptions extends KayAppCardFieldOptions {
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+}
+
+export declare type KayAppCardSubmitResult<T> = PluginCardSubmitResult<T>;
+
 /**
  * The `kay.app` system-prompt contract (`app.systemPrompt`): text a plugin adds to every chat's
  * system prompt, rendered by the daemon from a few facts about the chat and reused across chats.
@@ -9061,6 +9206,8 @@ declare function ModuleDeferred<Declarations extends TProperties>(declarations:
 
 declare function ModuleMapping(input: [unknown, unknown]): unknown;
 
+export declare function multiSelect(name: string, options: KayAppCardSelectOptions): KayAppCardLayout;
+
 /** A tool call that another tool made while it ran, for example from a codemode script. */
 declare interface NestedToolCallRecord {
     id: string;
@@ -9326,6 +9473,13 @@ declare const OptionalSemiColon: (input: string) => [unknown, string] | [];
 
 declare function OptionalSemiColonMapping(input: [unknown] | []): unknown;
 
+/**
+ * OR wrapper — at least one child condition must be true.
+ */
+declare type OrCondition = {
+    $or: VisibilityCondition[];
+};
+
 declare const PackageAssetPath: z.ZodString;
 
 declare type PackageAssetPath = z.infer<typeof PackageAssetPath>;
@@ -9828,6 +9982,12 @@ export declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
 
 export declare type PluginAgentDefinitionPermissionRule = z.infer<typeof PluginAgentDefinitionPermissionRule>;
 
+declare type PluginCardReadResult<T> = PluginCardResult<T> | {
+    readonly ok: true;
+    readonly presentation: "layout";
+    readonly layout: Spec;
+};
+
 declare type PluginCardResult<T> = {
     readonly ok: true;
     readonly data: T;
@@ -9837,6 +9997,14 @@ declare type PluginCardResult<T> = {
     readonly message: string;
 };
 
+declare type PluginCardSubmitResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+    readonly summary: string;
+} | Extract<PluginCardResult<T>, {
+    readonly ok: false;
+}>;
+
 export declare const PluginEventEnvelope: z.ZodObject<{
     id: z.ZodString;
     localId: z.ZodString;
@@ -10450,6 +10618,8 @@ declare function ReturnType_2<Type extends TSchema>(type: Type, options?: TSchem
 /** Creates a deferred ReturnType action. */
 declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TReturnTypeDeferred<Type>;
 
+export declare function row(children: readonly KayAppCardLayout[]): KayAppCardLayout;
+
 /**
  * The hidden message a continued run rides as its admission ticket (a mid-turn compaction
  * resume, a run-recovery re-drive). The engine writes it; this package's placement rows keep it
@@ -11025,6 +11195,8 @@ declare const SdkSessionDoor: z.ZodEnum<{
 
 declare type SdkSessionDoor = z.infer<typeof SdkSessionDoor>;
 
+export declare function select(name: string, options: KayAppCardSelectOptions): KayAppCardLayout;
+
 declare type SelectorDisposition = {
     readonly kind: "deferred";
     readonly window?: LineSelector;
@@ -11293,6 +11465,9 @@ declare const SignedInStatusCode: z.ZodNumber;
 
 declare type SignedInStatusCode = z.infer<typeof SignedInStatusCode>;
 
+/** A single visibility condition (state, item, or index). */
+declare type SingleCondition = StateCondition | ItemCondition | IndexCondition;
+
 declare interface SourceInfo {
     path: string;
     source: string;
@@ -11315,6 +11490,33 @@ declare type SourceScope = "user" | "project" | "temporary";
 /** Matches from Start and End capturing everything in-between. Start and End are consumed. */
 declare function Span<Start extends string, End extends string, MultiLine extends boolean, Input extends string>(start: Start, end: End, multiLine: MultiLine, input: Input): TSpan<Start, End, MultiLine, Input>;
 
+/**
+ * Flat UI tree structure (optimized for LLM generation)
+ */
+declare interface Spec {
+    /** Root element key */
+    root: string;
+    /** Flat map of elements by key */
+    elements: Record<string, UIElement>;
+    /** Optional initial state to seed the state model.
+     *  Components using statePath will read from / write to this state. */
+    state?: Record<string, unknown>;
+}
+
+export declare function stack(children: readonly KayAppCardLayout[]): KayAppCardLayout;
+
+/**
+ * A single state-based condition.
+ * Resolves `$state` to a value from the state model, then applies the operator.
+ * Without an operator, checks truthiness.
+ *
+ * When `not` is `true`, the result of the entire condition is inverted.
+ * For example `{ $state: "/count", gt: 5, not: true }` means "NOT greater than 5".
+ */
+declare type StateCondition = {
+    $state: string;
+} & ComparisonOperators;
+
 /** Infers a static type from a TypeBox type. */
 declare type Static<Type extends TSchema, Context extends TProperties = {}, Result extends unknown = StaticType<[], 'Encode', Context, {}, Type>> = Result;
 
@@ -11509,6 +11711,8 @@ declare type SubagentResultMessage = CustomMessage<SubagentResultDetails> & {
     readonly display: boolean;
 };
 
+export declare function submit(label: string): KayAppCardLayout;
+
 export declare interface SummarizeSessionInput {
     readonly sessions: KayAppSessions;
     readonly models: KayAppModels;
@@ -11520,6 +11724,8 @@ export declare interface SummarizeSessionInput {
 
 declare const SUMMARY_VERSION: 4;
 
+export declare function switchField(name: string, options: KayAppCardFieldOptions): KayAppCardLayout;
+
 /** Creates a Symbol type. */
 declare function Symbol_2(options?: TSchemaOptions): TSymbol;
 
@@ -12538,6 +12744,8 @@ declare type TExprTermTail<Input extends string> = ((Token.TConst<'&', Input> ex
 
 declare type TExprTermTailMapping<Input extends [unknown, unknown, unknown] | []> = (Input);
 
+export declare function textArea(name: string, options: KayAppCardFieldOptions): KayAppCardLayout;
+
 declare interface TextContent {
     type: "text";
     text: string;
@@ -12686,6 +12894,8 @@ declare type TExtendsUnknown<Inferred extends TProperties, Left extends TUnknown
 
 declare type TExtendsVoid<Inferred extends TProperties, Left extends TVoid, Right extends TSchema> = (Right extends TVoid ? ExtendsResult_2.TExtendsTrue<Inferred> : TExtendsRight<Inferred, Left, Right>);
 
+export declare function textField(name: string, options: KayAppCardFieldOptions): KayAppCardLayout;
+
 /** Applies an Extract action using the given types. */
 declare type TExtract<Left extends TSchema, Right extends TSchema> = (TExtractAction<Left, Right>);
 
@@ -13913,6 +14123,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodNumber>;
         editIndex: z.ZodOptional<z.ZodNumber>;
         occurrences: z.ZodOptional<z.ZodNumber>;
@@ -15520,6 +15731,33 @@ declare type UiActionMessage = CustomMessage<UiActionDetails> & {
     readonly display: true;
 };
 
+/**
+ * Base UI element structure for v2
+ */
+declare interface UIElement<T extends string = string, P = Record<string, unknown>> {
+    /** Component type from the catalog */
+    type: T;
+    /** Component props */
+    props: P;
+    /** Child element keys (flat structure) */
+    children?: string[];
+    /** Visibility condition */
+    visible?: VisibilityCondition;
+    /** Event bindings — maps event names to action bindings */
+    on?: Record<string, ActionBinding | ActionBinding[]>;
+    /** Repeat children once per item in a state array */
+    repeat?: {
+        statePath: string;
+        key?: string;
+    };
+    /**
+     * State watchers — maps JSON Pointer state paths to action bindings.
+     * When the value at a watched path changes, the bound actions fire.
+     * Useful for cascading dependencies (e.g. country → city option loading).
+     */
+    watch?: Record<string, ActionBinding | ActionBinding[]>;
+}
+
 /** Applies a Uncapitalize action to the given type. */
 declare function Uncapitalize_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TUncapitalize<Type>;
 
@@ -16845,6 +17083,16 @@ declare type VendoredMcpOutcome =
     readonly serviceId?: string;
 };
 
+/**
+ * Visibility condition types.
+ * - `boolean` — always/never
+ * - `SingleCondition` — single condition (`$state`, `$item`, or `$index`)
+ * - `SingleCondition[]` — implicit AND (all must be true)
+ * - `AndCondition` — `{ $and: [...] }`, explicit AND (all must be true)
+ * - `OrCondition` — `{ $or: [...] }`, at least one must be true
+ */
+declare type VisibilityCondition = boolean | SingleCondition | SingleCondition[] | AndCondition | OrCondition;
+
 /** Creates a Void type. */
 declare function Void(options?: TSchemaOptions): TVoid;
 
@@ -16964,9 +17212,6 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
-    presentation: z.ZodOptional<z.ZodObject<{
-        app: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-app.js

@@ -70,6 +70,65 @@ var JsonValue = z.lazy(() => z.union([
 var JsonObject = z.record(z.string(), JsonValue);
 var JsonSchema = z.record(z.string(), JsonValue);
 
+// packages/plugin-sdk/dist/kay-app/card-layout.js
+function element(type, props) {
+  return { root: "root", elements: { root: { type, props } } };
+}
+function group(type, props, children) {
+  const layout = element(type, props);
+  layout.elements.root.children = children.map((child, index) => {
+    const prefix = `${index}-`;
+    for (const [key, value] of Object.entries(child.elements)) {
+      layout.elements[prefix + key] = {
+        ...value,
+        ...value.children ? { children: value.children.map((id) => prefix + id) } : {}
+      };
+    }
+    return prefix + child.root;
+  });
+  return layout;
+}
+function card(title, children, state) {
+  return { ...group("Card", { title }, children), ...state ? { state } : {} };
+}
+function row(children) {
+  return group("Row", {}, children);
+}
+function stack(children) {
+  return group("Stack", {}, children);
+}
+function field(type, name, options) {
+  const key = name.replaceAll("~", "~0").replaceAll("/", "~1");
+  return element(type, { ...options, value: { $bindState: `/form/${key}` } });
+}
+function textField(name, options) {
+  return field("Field", name, options);
+}
+function textArea(name, options) {
+  return field("TextArea", name, options);
+}
+function select(name, options) {
+  return field("Select", name, options);
+}
+function multiSelect(name, options) {
+  return field("MultiSelect", name, options);
+}
+function switchField(name, options) {
+  return field("Switch", name, options);
+}
+function submit(label) {
+  return {
+    root: "root",
+    elements: {
+      root: {
+        type: "Button",
+        props: { label },
+        on: { press: { action: "submit" } }
+      }
+    }
+  };
+}
+
 // packages/plugin-sdk/dist/signals.js
 import { z as z2 } from "zod";
 function createFallbackOnlySignals() {
@@ -125,8 +184,8 @@ var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)
 function grammarProblem(input) {
   const shape = ObserveShape.safeParse(input);
   if (!shape.success) {
-    const field = shape.error.issues[0]?.path.join(".") ?? "";
-    return field === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field}\` is missing or has the wrong type.`;
+    const field2 = shape.error.issues[0]?.path.join(".") ?? "";
+    return field2 === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field2}\` is missing or has the wrong type.`;
   }
   const { detector, source, questions, subject, after, reuse } = shape.data;
   const { state } = input;
@@ -139,7 +198,7 @@ function grammarProblem(input) {
   if (!fits(detector.version, VERSION)) {
     return "`detector.version` must be at most 64 characters: letters and digits in parts joined by single `.`, `-`, or `_`.";
   }
-  for (const [field, grammar, rule] of [
+  for (const [field2, grammar, rule] of [
     ["sessionId", POINTER, POINTER_RULE],
     ["entryId", POINTER, POINTER_RULE],
     ["openerEntryId", POINTER, POINTER_RULE],
@@ -149,9 +208,9 @@ function grammarProblem(input) {
       `1 to ${MAX_POINTER} characters with no control character`
     ]
   ]) {
-    const id = source[field];
+    const id = source[field2];
     if (id !== void 0 && !(id.length <= MAX_POINTER && grammar.test(id))) {
-      return `\`source.${field}\` must be ${rule}.`;
+      return `\`source.${field2}\` must be ${rule}.`;
     }
   }
   const occurredAtMs = source.occurredAtMs;
@@ -964,6 +1023,7 @@ export {
   UriProviderError,
   UriUnsupportedOperationError,
   UriValidationError,
+  card,
   createConsoleKayPluginLog,
   createFallbackOnlySignals,
   createKayPluginLog,
@@ -976,12 +1036,20 @@ export {
   invalidObservation,
   isCredentialShapedText,
   isRetryable,
+  multiSelect,
   parseLineSelector,
   parseStoredTranscriptKindFilter,
   pathToFileURL,
   payload,
   requireWriteContent,
+  row,
+  select,
+  stack,
   storedTranscriptKindOf,
+  submit,
+  switchField,
+  textArea,
+  textField,
   transcriptMessageText,
   transcriptMessageTexts,
   transcriptRoleLabel,

package/dist/whiteboard.d.ts

@@ -72,9 +72,6 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
-    presentation: z.ZodOptional<z.ZodObject<{
-        app: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/whiteboard.js

@@ -160,11 +160,7 @@ var WhiteboardTypeInfo = z4.strictObject({
   typeId: GlobalContributionId,
   displayName: NonEmptyString,
   schemaVersion: z4.number().int().positive(),
-  available: z4.boolean(),
-  /** A plugin-owned readonly presentation; absent types use the host fallback. */
-  presentation: z4.strictObject({
-    app: GlobalContributionId
-  }).optional()
+  available: z4.boolean()
 });
 export {
   JsonValue,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",