@ryuhq/sdk 0.1.12 → 0.1.14

package/dist/{chunk-CUY2QOFC.js → chunk-AO2KJRDD.js}

@@ -293,6 +293,24 @@ var SurfaceSchema = z.enum([
   /** The terminal client. */
   "cli"
 ]);
+var EnginesReqSchema = z.object({
+  /** Floor for the terminal (`cli`) surface. */
+  cli: z.string().optional(),
+  /** Floor for the Tauri desktop app. */
+  desktop: z.string().optional(),
+  /** Floor for the browser extension. */
+  extension: z.string().optional(),
+  /** Floor for the Ryu Gateway. */
+  gateway: z.string().optional(),
+  /** Floor for the dynamic-island companion. */
+  island: z.string().optional(),
+  /** Floor for the mobile app. */
+  mobile: z.string().optional(),
+  /** Floor for the running **Core** (e.g. `">=0.3.0"`). Required. */
+  ryu: z.string().min(1, "engines.ryu is required when engines is present"),
+  /** Floor for the Next.js web app. */
+  web: z.string().optional()
+});
 var PluginManifestSchema = z.object({
   /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
   id: z.string().min(1, "id is required"),
@@ -359,6 +377,22 @@ var PluginManifestSchema = z.object({
    * an unsupported-target plugin stays installable and inspectable.
    */
   targets: z.array(SurfaceSchema).default([]),
+  /**
+   * Host version floors — the semver requirement each surface must satisfy for
+   * this plugin to install. Mirrors Core's `EnginesReq`
+   * (`crates/core/kernel-contracts/src/manifest.rs`).
+   *
+   * `ryu` is the **Core** floor and the only required key (it is the legacy
+   * spelling; every manifest in the wild carries just that one). The rest are
+   * optional per-surface floors.
+   *
+   * REGRESSION THIS FIXES: `engines` was absent from this schema entirely, and
+   * zod strips unlisted keys — so `ryu pack` silently dropped the whole block
+   * from every bundle it produced. A plugin could declare a Core floor, publish,
+   * and ship a bundle that declared none. Any new host floor MUST be added here
+   * as well as in the Rust contract, or it does not survive packing.
+   */
+  engines: EnginesReqSchema.optional(),
   /**
    * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
    * referred user buys this (paid) item. `value` is basis points for `percent`
@@ -477,6 +511,7 @@ export {
   CapabilityReqSchema,
   RequiresSchema,
   SurfaceSchema,
+  EnginesReqSchema,
   PluginManifestSchema,
   validatePluginId,
   validateManifestStrict,

package/dist/cli.cjs

@@ -777,6 +777,24 @@ var SurfaceSchema = import_zod.z.enum([
   /** The terminal client. */
   "cli"
 ]);
+var EnginesReqSchema = import_zod.z.object({
+  /** Floor for the terminal (`cli`) surface. */
+  cli: import_zod.z.string().optional(),
+  /** Floor for the Tauri desktop app. */
+  desktop: import_zod.z.string().optional(),
+  /** Floor for the browser extension. */
+  extension: import_zod.z.string().optional(),
+  /** Floor for the Ryu Gateway. */
+  gateway: import_zod.z.string().optional(),
+  /** Floor for the dynamic-island companion. */
+  island: import_zod.z.string().optional(),
+  /** Floor for the mobile app. */
+  mobile: import_zod.z.string().optional(),
+  /** Floor for the running **Core** (e.g. `">=0.3.0"`). Required. */
+  ryu: import_zod.z.string().min(1, "engines.ryu is required when engines is present"),
+  /** Floor for the Next.js web app. */
+  web: import_zod.z.string().optional()
+});
 var PluginManifestSchema = import_zod.z.object({
   /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
   id: import_zod.z.string().min(1, "id is required"),
@@ -843,6 +861,22 @@ var PluginManifestSchema = import_zod.z.object({
    * an unsupported-target plugin stays installable and inspectable.
    */
   targets: import_zod.z.array(SurfaceSchema).default([]),
+  /**
+   * Host version floors — the semver requirement each surface must satisfy for
+   * this plugin to install. Mirrors Core's `EnginesReq`
+   * (`crates/core/kernel-contracts/src/manifest.rs`).
+   *
+   * `ryu` is the **Core** floor and the only required key (it is the legacy
+   * spelling; every manifest in the wild carries just that one). The rest are
+   * optional per-surface floors.
+   *
+   * REGRESSION THIS FIXES: `engines` was absent from this schema entirely, and
+   * zod strips unlisted keys — so `ryu pack` silently dropped the whole block
+   * from every bundle it produced. A plugin could declare a Core floor, publish,
+   * and ship a bundle that declared none. Any new host floor MUST be added here
+   * as well as in the Rust contract, or it does not survive packing.
+   */
+  engines: EnginesReqSchema.optional(),
   /**
    * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
    * referred user buys this (paid) item. `value` is basis points for `percent`

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import {
   PluginManifestSchema
-} from "./chunk-CUY2QOFC.js";
+} from "./chunk-AO2KJRDD.js";
 import {
   AGENT_PLUGIN_MANIFEST_FILE,
   AGENT_PLUGIN_MCP_FILE,

package/dist/index.cjs

@@ -1123,6 +1123,24 @@ var SurfaceSchema = import_zod.z.enum([
   /** The terminal client. */
   "cli"
 ]);
+var EnginesReqSchema = import_zod.z.object({
+  /** Floor for the terminal (`cli`) surface. */
+  cli: import_zod.z.string().optional(),
+  /** Floor for the Tauri desktop app. */
+  desktop: import_zod.z.string().optional(),
+  /** Floor for the browser extension. */
+  extension: import_zod.z.string().optional(),
+  /** Floor for the Ryu Gateway. */
+  gateway: import_zod.z.string().optional(),
+  /** Floor for the dynamic-island companion. */
+  island: import_zod.z.string().optional(),
+  /** Floor for the mobile app. */
+  mobile: import_zod.z.string().optional(),
+  /** Floor for the running **Core** (e.g. `">=0.3.0"`). Required. */
+  ryu: import_zod.z.string().min(1, "engines.ryu is required when engines is present"),
+  /** Floor for the Next.js web app. */
+  web: import_zod.z.string().optional()
+});
 var PluginManifestSchema = import_zod.z.object({
   /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
   id: import_zod.z.string().min(1, "id is required"),
@@ -1189,6 +1207,22 @@ var PluginManifestSchema = import_zod.z.object({
    * an unsupported-target plugin stays installable and inspectable.
    */
   targets: import_zod.z.array(SurfaceSchema).default([]),
+  /**
+   * Host version floors — the semver requirement each surface must satisfy for
+   * this plugin to install. Mirrors Core's `EnginesReq`
+   * (`crates/core/kernel-contracts/src/manifest.rs`).
+   *
+   * `ryu` is the **Core** floor and the only required key (it is the legacy
+   * spelling; every manifest in the wild carries just that one). The rest are
+   * optional per-surface floors.
+   *
+   * REGRESSION THIS FIXES: `engines` was absent from this schema entirely, and
+   * zod strips unlisted keys — so `ryu pack` silently dropped the whole block
+   * from every bundle it produced. A plugin could declare a Core floor, publish,
+   * and ship a bundle that declared none. Any new host floor MUST be added here
+   * as well as in the Rust contract, or it does not survive packing.
+   */
+  engines: EnginesReqSchema.optional(),
   /**
    * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
    * referred user buys this (paid) item. `value` is basis points for `percent`

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   coreManifestJsonSchema,
   validateManifestStrict,
   validatePluginId
-} from "./chunk-CUY2QOFC.js";
+} from "./chunk-AO2KJRDD.js";
 import {
   Agent,
   PRIMITIVE_BINDINGS,

package/dist/manifest.cjs

@@ -24,6 +24,7 @@ __export(manifest_exports, {
   CapabilityReqSchema: () => CapabilityReqSchema,
   CompanionSurfaceSchema: () => CompanionSurfaceSchema,
   ContributesSchema: () => ContributesSchema,
+  EnginesReqSchema: () => EnginesReqSchema,
   HookEventContributionSchema: () => HookEventContributionSchema,
   OutputStyleContributionSchema: () => OutputStyleContributionSchema,
   PiExtensionContributionSchema: () => PiExtensionContributionSchema,
@@ -342,6 +343,24 @@ var SurfaceSchema = import_zod.z.enum([
   /** The terminal client. */
   "cli"
 ]);
+var EnginesReqSchema = import_zod.z.object({
+  /** Floor for the terminal (`cli`) surface. */
+  cli: import_zod.z.string().optional(),
+  /** Floor for the Tauri desktop app. */
+  desktop: import_zod.z.string().optional(),
+  /** Floor for the browser extension. */
+  extension: import_zod.z.string().optional(),
+  /** Floor for the Ryu Gateway. */
+  gateway: import_zod.z.string().optional(),
+  /** Floor for the dynamic-island companion. */
+  island: import_zod.z.string().optional(),
+  /** Floor for the mobile app. */
+  mobile: import_zod.z.string().optional(),
+  /** Floor for the running **Core** (e.g. `">=0.3.0"`). Required. */
+  ryu: import_zod.z.string().min(1, "engines.ryu is required when engines is present"),
+  /** Floor for the Next.js web app. */
+  web: import_zod.z.string().optional()
+});
 var PluginManifestSchema = import_zod.z.object({
   /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
   id: import_zod.z.string().min(1, "id is required"),
@@ -408,6 +427,22 @@ var PluginManifestSchema = import_zod.z.object({
    * an unsupported-target plugin stays installable and inspectable.
    */
   targets: import_zod.z.array(SurfaceSchema).default([]),
+  /**
+   * Host version floors — the semver requirement each surface must satisfy for
+   * this plugin to install. Mirrors Core's `EnginesReq`
+   * (`crates/core/kernel-contracts/src/manifest.rs`).
+   *
+   * `ryu` is the **Core** floor and the only required key (it is the legacy
+   * spelling; every manifest in the wild carries just that one). The rest are
+   * optional per-surface floors.
+   *
+   * REGRESSION THIS FIXES: `engines` was absent from this schema entirely, and
+   * zod strips unlisted keys — so `ryu pack` silently dropped the whole block
+   * from every bundle it produced. A plugin could declare a Core floor, publish,
+   * and ship a bundle that declared none. Any new host floor MUST be added here
+   * as well as in the Rust contract, or it does not survive packing.
+   */
+  engines: EnginesReqSchema.optional(),
   /**
    * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
    * referred user buys this (paid) item. `value` is basis points for `percent`
@@ -514,6 +549,7 @@ function coreManifestJsonSchema() {
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
+  EnginesReqSchema,
   HookEventContributionSchema,
   OutputStyleContributionSchema,
   PiExtensionContributionSchema,

package/dist/manifest.d.cts

@@ -334,6 +334,31 @@ declare const SurfaceSchema: z.ZodEnum<{
     cli: "cli";
 }>;
 type Surface = z.infer<typeof SurfaceSchema>;
+/**
+ * The `engines` block: a semver **requirement** per host surface, mirroring
+ * VS-Code's `engines.vscode`. Mirrors Core's `EnginesReq`.
+ *
+ * `ryu` is the Core floor, named that way for backwards compatibility — every
+ * manifest written before per-surface floors existed spells it `ryu`, and Core's
+ * `EnginesReq::floor_for` maps the `core` surface onto it. The remaining keys are
+ * optional floors for the surfaces a plugin actually touches.
+ *
+ * Values are NOT validated as semver ranges here: Core is the authority and
+ * rejects an unparseable requirement at manifest load with a precise message.
+ * Duplicating a range parser in the SDK would only create a second, drifting
+ * opinion about what `">=1.2, <2"` means.
+ */
+declare const EnginesReqSchema: z.ZodObject<{
+    cli: z.ZodOptional<z.ZodString>;
+    desktop: z.ZodOptional<z.ZodString>;
+    extension: z.ZodOptional<z.ZodString>;
+    gateway: z.ZodOptional<z.ZodString>;
+    island: z.ZodOptional<z.ZodString>;
+    mobile: z.ZodOptional<z.ZodString>;
+    ryu: z.ZodString;
+    web: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EnginesReq = z.infer<typeof EnginesReqSchema>;
 /**
  * Full schema for a `manifest.json` Plugin manifest. Mirrors `PluginManifest` in
  * `apps/core/src/plugin_manifest/mod.rs`.
@@ -434,6 +459,16 @@ declare const PluginManifestSchema: z.ZodObject<{
         web: "web";
         cli: "cli";
     }>>>;
+    engines: z.ZodOptional<z.ZodObject<{
+        cli: z.ZodOptional<z.ZodString>;
+        desktop: z.ZodOptional<z.ZodString>;
+        extension: z.ZodOptional<z.ZodString>;
+        gateway: z.ZodOptional<z.ZodString>;
+        island: z.ZodOptional<z.ZodString>;
+        mobile: z.ZodOptional<z.ZodString>;
+        ryu: z.ZodString;
+        web: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     affiliate: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         rule: z.ZodOptional<z.ZodObject<{
@@ -508,4 +543,4 @@ declare function validateManifestStrict(manifestJson: string): string;
  */
 declare function coreManifestJsonSchema(): unknown;
 
-export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type HookEventContribution, HookEventContributionSchema, type OutputStyleContribution, OutputStyleContributionSchema, type PiExtensionContribution, PiExtensionContributionSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };
+export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type EnginesReq, EnginesReqSchema, type HookEventContribution, HookEventContributionSchema, type OutputStyleContribution, OutputStyleContributionSchema, type PiExtensionContribution, PiExtensionContributionSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };

package/dist/manifest.d.ts

@@ -334,6 +334,31 @@ declare const SurfaceSchema: z.ZodEnum<{
     cli: "cli";
 }>;
 type Surface = z.infer<typeof SurfaceSchema>;
+/**
+ * The `engines` block: a semver **requirement** per host surface, mirroring
+ * VS-Code's `engines.vscode`. Mirrors Core's `EnginesReq`.
+ *
+ * `ryu` is the Core floor, named that way for backwards compatibility — every
+ * manifest written before per-surface floors existed spells it `ryu`, and Core's
+ * `EnginesReq::floor_for` maps the `core` surface onto it. The remaining keys are
+ * optional floors for the surfaces a plugin actually touches.
+ *
+ * Values are NOT validated as semver ranges here: Core is the authority and
+ * rejects an unparseable requirement at manifest load with a precise message.
+ * Duplicating a range parser in the SDK would only create a second, drifting
+ * opinion about what `">=1.2, <2"` means.
+ */
+declare const EnginesReqSchema: z.ZodObject<{
+    cli: z.ZodOptional<z.ZodString>;
+    desktop: z.ZodOptional<z.ZodString>;
+    extension: z.ZodOptional<z.ZodString>;
+    gateway: z.ZodOptional<z.ZodString>;
+    island: z.ZodOptional<z.ZodString>;
+    mobile: z.ZodOptional<z.ZodString>;
+    ryu: z.ZodString;
+    web: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EnginesReq = z.infer<typeof EnginesReqSchema>;
 /**
  * Full schema for a `manifest.json` Plugin manifest. Mirrors `PluginManifest` in
  * `apps/core/src/plugin_manifest/mod.rs`.
@@ -434,6 +459,16 @@ declare const PluginManifestSchema: z.ZodObject<{
         web: "web";
         cli: "cli";
     }>>>;
+    engines: z.ZodOptional<z.ZodObject<{
+        cli: z.ZodOptional<z.ZodString>;
+        desktop: z.ZodOptional<z.ZodString>;
+        extension: z.ZodOptional<z.ZodString>;
+        gateway: z.ZodOptional<z.ZodString>;
+        island: z.ZodOptional<z.ZodString>;
+        mobile: z.ZodOptional<z.ZodString>;
+        ryu: z.ZodString;
+        web: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     affiliate: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         rule: z.ZodOptional<z.ZodObject<{
@@ -508,4 +543,4 @@ declare function validateManifestStrict(manifestJson: string): string;
  */
 declare function coreManifestJsonSchema(): unknown;
 
-export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type HookEventContribution, HookEventContributionSchema, type OutputStyleContribution, OutputStyleContributionSchema, type PiExtensionContribution, PiExtensionContributionSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };
+export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type EnginesReq, EnginesReqSchema, type HookEventContribution, HookEventContributionSchema, type OutputStyleContribution, OutputStyleContributionSchema, type PiExtensionContribution, PiExtensionContributionSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };

package/dist/manifest.js

@@ -3,6 +3,7 @@ import {
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
+  EnginesReqSchema,
   HookEventContributionSchema,
   OutputStyleContributionSchema,
   PiExtensionContributionSchema,
@@ -19,12 +20,13 @@ import {
   labelImpersonatesSystemChrome,
   validateManifestStrict,
   validatePluginId
-} from "./chunk-CUY2QOFC.js";
+} from "./chunk-AO2KJRDD.js";
 export {
   AppDependencySchema,
   CapabilityReqSchema,
   CompanionSurfaceSchema,
   ContributesSchema,
+  EnginesReqSchema,
   HookEventContributionSchema,
   OutputStyleContributionSchema,
   PiExtensionContributionSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuhq/sdk",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "description": "Ryu developer SDK: typed builders and CLI for authoring manifest.json Plugin bundles",
   "main": "./dist/index.cjs",
@@ -49,7 +49,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@ryuhq/sdk-native": "0.1.12",
+    "@ryuhq/sdk-native": "0.1.14",
     "zod": "^4.1.13"
   },
   "devDependencies": {

package/src/generated/plugin-manifest.ts

@@ -117,7 +117,33 @@ export interface PluginManifest {
 	 */
 	backend_sha256?: string | null;
 	/**
-	 * Detail-page hero banner spec ({colors,style,seed}); opaque passthrough (Ryu ext).
+	 * Detail-page hero banner spec; opaque passthrough (Ryu ext).
+	 *
+	 * The banner is the listing's OWN background, not its icon enlarged. Declared
+	 * or not, the hero always paints something: with no `banner` the detail page
+	 * derives its wash from `icon_dither`, so an app that never thinks about this
+	 * key still opens on its own colour rather than a grey slab. Declaring one is
+	 * how an author says "my hero is not just my icon, bigger".
+	 *
+	 * Accepted keys, all optional — the render layer picks the first that paints
+	 * and falls back down the list, so an unknown or malformed value degrades to
+	 * the derived wash rather than failing:
+	 *
+	 * - `background` — a flat CSS background (a colour, a `linear-gradient(…)`).
+	 * - `imageUrl` — a raster banner, painted `object-cover`. http(s) only.
+	 * - `colors: [String]` — two or more stops, ramped 135°.
+	 * - `style: "gradient" | "dither" | "flat" | "image"` — how to treat the
+	 *   above; `dither` adds the noise overlay, `flat`/`image` select `background`
+	 *   / `imageUrl` explicitly.
+	 * - `seed: Number` — the dither noise seed, so two apps sharing a palette do
+	 *   not share a texture.
+	 *
+	 * Kept as raw JSON like `icon_dither`, for the same reason: this is
+	 * PUBLISHER-supplied and reaches a CSS background, so it must never fail the
+	 * manifest parse, and the client validates before painting (`safeHttpUrl` for
+	 * `imageUrl`; the flat string is trusted exactly as far as `icon_background`
+	 * already is). Core does not read any of these keys — it copies the whole
+	 * value onto the catalog entry — so a new one needs no Core release.
 	 */
 	banner?: {
 		[k: string]: unknown;
@@ -214,6 +240,24 @@ export interface PluginManifest {
 	iconDither?: {
 		[k: string]: unknown;
 	};
+	/**
+	 * Inset for the card's icon square (Ryu extension: `iconPadding`).
+	 *
+	 * A product LOGO that is edge-to-edge in its own art has no breathing room
+	 * inside the square and reads as a sticker rather than an icon. One of
+	 * `none` | `sm` | `md` | `lg`.
+	 *
+	 * Any value other than `none` ALSO letterboxes the art (`object-contain`)
+	 * instead of cropping it. That coupling is load-bearing, not a convenience:
+	 * a listing declaring a bare `iconUrl` (no `icon`) is not in the brand lane,
+	 * so it is painted `object-cover` — inset alone would be silently inert for
+	 * exactly the raw-logo case this field exists for.
+	 *
+	 * `Option<String>` rather than a Rust enum, for the same forward-compat
+	 * reason `icon_dither` is raw JSON: an unknown value must never fail the
+	 * manifest parse. The render layer validates and falls back.
+	 */
+	iconPadding?: string | null;
 	/**
 	 * Logo URL (contract key `iconUrl`; Ryu extension).
 	 */
@@ -595,6 +639,22 @@ export interface Contributes {
 	 * [`Contributes::message_actions`].
 	 */
 	context_menu_items?: ContextMenuContribution[];
+	/**
+	 * "New X" rows the app contributes to the shell's create menu (the sidebar
+	 * footer "+"). See [`CreateActionContribution`].
+	 *
+	 * This exists because the create menu's only app seam used to be
+	 * `sidebar_sections[].spec.create` — section-scoped, so an app that
+	 * contributes no sidebar section could not put a row there at all. The shell
+	 * therefore hardcoded rows for apps it happened to know about, and those rows
+	 * stayed in the menu when the app was not installed, leading straight to an
+	 * error page. A create action is its own contribution precisely so the row
+	 * appears and disappears with the app.
+	 *
+	 * **Stored raw, validated at the chokepoint** — same rule as
+	 * [`Contributes::context_menu_items`].
+	 */
+	create_actions?: CreateActionContribution[];
 	/**
 	 * **Deletable data categories** the app owns — one "Delete all X" row in
 	 * Settings → Danger Zone (see [`DataCategoryContribution`]).
@@ -847,6 +907,24 @@ export interface Contributes {
 	 * (no live list, just a label/icon + a client route). See [`SidebarButtonContribution`].
 	 */
 	sidebar_buttons?: SidebarButtonContribution[];
+	/**
+	 * App-registered sidebar **modes** — a named preset of the whole left sidebar:
+	 * which sections it offers as tabs, and which one it opens on.
+	 *
+	 * The third axis of the sidebar contract, after "what sections exist"
+	 * ([`Contributes::sidebar_sections`]) and "what nav rows exist"
+	 * ([`Contributes::sidebar_buttons`]): **how the sidebar as a whole is
+	 * arranged**. The shell ships three modes of its own (every section stacked;
+	 * every section as a tab; Agent mode, which is the pair Sessions ⇄ Agents), and
+	 * before this member an app could add a section to that list but could not
+	 * propose an arrangement — so a plugin wanting the Grok/Hermes bot-mode posture
+	 * had to ask for a shell change. See [`SidebarModeContribution`].
+	 *
+	 * Self-contained (it names sections, not runnables), so it stays out of
+	 * [`Contributes::referenced_ids`]; served + tagged with the owning `plugin` id
+	 * at `GET /api/plugins/contributions`.
+	 */
+	sidebar_modes?: SidebarModeContribution[];
 	/**
 	 * App-registered sidebar **sections** — a header plus a live list of rows the
 	 * shell fetches from a declared Core `/api/` path. Lets an app own its sidebar
@@ -1031,6 +1109,47 @@ export interface ContextMenuContribution {
 	 */
 	order?: number | null;
 }
+/**
+ * One "New X" row a plugin contributes to the shell's create menu (see
+ * [`Contributes::create_actions`]).
+ */
+export interface CreateActionContribution {
+	args?: unknown;
+	/**
+	 * Granted capability to invoke instead of navigating, plus static `args` —
+	 * for a create that is an action rather than a destination. Dispatched
+	 * through the same host seam as a context-menu row.
+	 */
+	capability?: string | null;
+	/**
+	 * Optional glyph id resolved by the shell's Icon primitive. The desktop's
+	 * create menu draws no icons today (its rows are label-only by design), so
+	 * this is read and ignored there — it exists for shells that do.
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this row within the plugin.
+	 */
+	id: string;
+	/**
+	 * Row label, written as the user reads it — "New workflow", not "Workflow".
+	 */
+	label: string;
+	/**
+	 * Sort position among contributed rows (ascending).
+	 */
+	order?: number | null;
+	/**
+	 * In-app route the shell opens, e.g. `/workflows/new`. Must be a path, not a
+	 * URL: this is a navigation inside the shell, and accepting a scheme here
+	 * would turn a create row into an arbitrary-link affordance.
+	 */
+	target?: string | null;
+	/**
+	 * Title for the tab `target` opens. Falls back to `label`.
+	 */
+	title?: string | null;
+}
 /**
  * One **deletable data category** an app owns (see [`Contributes::data_categories`]).
  *
@@ -1598,6 +1717,68 @@ export interface SidebarButtonContribution {
 	 */
 	title: string;
 }
+/**
+ * One app-registered **sidebar mode** — a named arrangement of the whole left
+ * sidebar: the sections it offers as tabs, and the one it opens on.
+ *
+ * The shape is deliberately thin, and every field it does NOT have is the point:
+ *
+ * - **No renderer, no code.** A mode names existing sections. It cannot draw a row,
+ *   which is why it needs no grants and cannot be a carriage channel — the worst a
+ *   hostile mode can do is offer a tab list the user does not want, one menu row
+ *   away from being switched off.
+ * - **No row style.** How a section's rows draw belongs to that SECTION
+ *   (`SidebarSectionSpec.rowStyle` in `@ryu/app-host/views`), because it is a
+ *   property of the feed, not of an arrangement: a roster of named bots wants
+ *   avatars whether or not the user is in a mode that features it. Putting it here
+ *   would also mean a mode reaching across into another contribution's rendering,
+ *   which is the coupling this member exists to avoid.
+ * - **No `hidden` list.** A mode is a positive statement about what to show. The
+ *   sections it does not name are simply not tabs in it.
+ *
+ * Section ids are the shell's own keys (`agents`, `chats`, `spaces`, …) or another
+ * contributed section's namespaced key (`plugin:<pluginId>:<sectionId>`). A named
+ * section that does not resolve is dropped rather than failing the mode — an app
+ * may legitimately name a section from a sibling app the user has not installed,
+ * and losing one tab is a better answer than losing the mode.
+ */
+export interface SidebarModeContribution {
+	/**
+	 * Which of `sections` the mode opens on. Absent (or naming a section not in
+	 * `sections`) = the first one. This is the field that makes a mode an opinion
+	 * rather than a filter: the shell's own Agent mode lists Sessions first but
+	 * opens on Agents, because the roster is what the mode is for.
+	 */
+	default_section?: string | null;
+	/**
+	 * One-line description shown under the title where the mode is offered.
+	 */
+	description?: string | null;
+	/**
+	 * Optional glyph id resolved by the shell's Icon primitive (Iconify/Hugeicons).
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this mode within the plugin (namespaced by the shell into the
+	 * stored mode key as `plugin:<pluginId>:<id>`, so two apps can both ship a
+	 * `bots` mode).
+	 */
+	id: string;
+	/**
+	 * Optional ordering hint among the modes on offer (lower = earlier).
+	 */
+	order?: number | null;
+	/**
+	 * The sections this mode offers as tabs, in display order. Empty = the mode is
+	 * inert and the shell ignores it; a mode with one entry is a legitimate
+	 * single-surface arrangement, not an error.
+	 */
+	sections?: string[];
+	/**
+	 * Label shown in the sidebar's mode menu and the Appearance tab.
+	 */
+	title: string;
+}
 /**
  * One app-registered **sidebar section** — a header plus a live list of rows the
  * desktop's compact sidebar renderer draws (the app-owned replacement for the
@@ -1914,16 +2095,78 @@ export interface WidgetContribution {
 	uri: string;
 }
 /**
- * `engines` block — the required Ryu version, mirroring VS-Code's
- * `engines.vscode`. `ryu` is a semver **requirement** string.
+ * `engines` block — the **host** version floors, mirroring VS-Code's
+ * `engines.vscode`. Every value is a semver **requirement** string.
+ *
+ * `ryu` is the Core floor and is the only required key (every manifest written
+ * before per-surface floors existed carries just that one). The rest are optional
+ * per-[`Surface`] floors: a plugin that needs a Gateway API added in 0.1.5 and a
+ * desktop panel API added in 0.2.0 says so, instead of over-declaring one Core
+ * floor and hoping the release train kept them in step.
+ *
+ * ## Why this is a flat struct and not a `BTreeMap<Surface, String>`
+ *
+ * The [`PluginManifest::surfaces`] map would be the obvious home, but it is
+ * **absent from the SDK's zod mirror** (`packages/sdk/src/manifest.ts`), and zod
+ * strips unlisted keys — so a floor declared there would be silently dropped from
+ * every bundle `ryu pack` produces. `engines` is the block that already means
+ * "host floor", it is what a manifest author reaches for, and mirroring it costs
+ * one schema addition rather than a nested map.
+ *
+ * ## Unknown ≠ unsatisfied
+ *
+ * Core observes its own version and (via `/health`) the Gateway's. It does NOT
+ * know the desktop, island, mobile, extension or web version — those are separate
+ * installs that never report in. A floor against a surface whose version is
+ * unknown is therefore **advisory, never blocking**: see
+ * `HostVersions::evaluate`. Blocking on unknown would delist every plugin from
+ * every surface Core cannot see, which is most of them.
  */
 export interface EnginesReq {
 	/**
-	 * Semver requirement the running Core version must satisfy (e.g. `">=0.3.0"`,
-	 * `"^1.2"`). Parsed as a [`semver::VersionReq`]; an unparseable value or an
-	 * unsatisfied requirement causes the loader to reject the manifest.
+	 * Floor for the **terminal** (`cli`) surface — the TUI that dispatches
+	 * `ryu <app> <cmd>`.
+	 */
+	cli?: string | null;
+	/**
+	 * Floor for the **desktop** app (Tauri shell).
+	 */
+	desktop?: string | null;
+	/**
+	 * Floor for the **browser extension** surface.
+	 */
+	extension?: string | null;
+	/**
+	 * Floor for the **Gateway**. The one non-Core surface Core can actually
+	 * observe (it spawns the Gateway and reads `version` from its `/health`), so a
+	 * floor here is genuinely enforceable rather than advisory.
+	 */
+	gateway?: string | null;
+	/**
+	 * Floor for the **island** (the always-on overlay surface).
+	 */
+	island?: string | null;
+	/**
+	 * Floor for the **mobile** app. The one surface with a genuinely independent
+	 * release train (App Store / Play review lag), so it is the floor most likely
+	 * to be unsatisfied in practice.
+	 */
+	mobile?: string | null;
+	/**
+	 * Semver requirement the running **Core** version must satisfy (e.g.
+	 * `">=0.3.0"`, `"^1.2"`). Parsed as a [`semver::VersionReq`]; an unparseable
+	 * value causes the loader to reject the manifest, and an unsatisfied one moves
+	 * it to the incompatible lane (shown in the marketplace, refused at install).
+	 *
+	 * Named `ryu` rather than `core` for backwards compatibility: every manifest
+	 * in the wild spells it this way. [`EnginesReq::floor_for`] maps
+	 * [`Surface::Core`] onto it.
 	 */
 	ryu: string;
+	/**
+	 * Floor for the **web** surface.
+	 */
+	web?: string | null;
 }
 /**
  * One declarative **stdio MCP server** a plugin registers (see

package/src/manifest.test.ts

@@ -455,6 +455,88 @@ describe("AppBuilder", () => {
 // silently delete a plugin's dependencies BEFORE the manifest is signed. So every
 // case below asserts the field SURVIVES the parse, not merely that it parses.
 
+describe("engines (host version floors)", () => {
+	/** The regression: `engines` was absent from `PluginManifestSchema`, and zod
+	 *  strips unlisted keys — so `ryu pack` dropped the block from every bundle. A
+	 *  plugin could declare a Core floor, publish, and ship a bundle declaring none. */
+	it("does not strip `engines` — the whole block survives the parse", () => {
+		const parsed = PluginManifestSchema.safeParse({
+			engines: {
+				cli: ">=0.1.0",
+				desktop: ">=0.2.0",
+				extension: ">=0.1.0",
+				gateway: ">=0.1.5",
+				island: ">=0.1.0",
+				mobile: ">=1.0.0",
+				ryu: ">=0.1.0",
+				web: ">=0.1.0",
+			},
+			id: "com.example.floors",
+			name: "Floors",
+			runnables: [],
+			version: "1.0.0",
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		expect(parsed.data.engines).toEqual({
+			cli: ">=0.1.0",
+			desktop: ">=0.2.0",
+			extension: ">=0.1.0",
+			gateway: ">=0.1.5",
+			island: ">=0.1.0",
+			mobile: ">=1.0.0",
+			ryu: ">=0.1.0",
+			web: ">=0.1.0",
+		});
+	});
+
+	it("keeps a legacy `{ ryu }`-only block intact and adds no sibling keys", () => {
+		const parsed = PluginManifestSchema.safeParse({
+			engines: { ryu: ">=0.1.0" },
+			id: "com.example.legacy-engines",
+			name: "Legacy",
+			runnables: [],
+			version: "1.0.0",
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		expect(parsed.data.engines).toEqual({ ryu: ">=0.1.0" });
+	});
+
+	it("leaves `engines` undefined when the manifest declares none", () => {
+		const parsed = PluginManifestSchema.safeParse({
+			id: "com.example.no-engines",
+			name: "None",
+			runnables: [],
+			version: "1.0.0",
+		});
+
+		expect(parsed.success).toBe(true);
+		if (!parsed.success) {
+			return;
+		}
+		expect(parsed.data.engines).toBeUndefined();
+	});
+
+	it("rejects an `engines` block with no Core floor", () => {
+		const parsed = PluginManifestSchema.safeParse({
+			engines: { desktop: ">=0.2.0" },
+			id: "com.example.bad-engines",
+			name: "Bad",
+			runnables: [],
+			version: "1.0.0",
+		});
+
+		expect(parsed.success).toBe(false);
+	});
+});
+
 describe("requires / targets", () => {
 	it("keeps a manifest with NEITHER requires nor targets valid (all 37 shipped plugins)", () => {
 		const parsed = PluginManifestSchema.safeParse({

package/src/manifest.ts

@@ -578,6 +578,43 @@ export const SurfaceSchema = z.enum([
 
 export type Surface = z.infer<typeof SurfaceSchema>;
 
+// ── engines (host version floors) ────────────────────────────────────────────
+
+/**
+ * The `engines` block: a semver **requirement** per host surface, mirroring
+ * VS-Code's `engines.vscode`. Mirrors Core's `EnginesReq`.
+ *
+ * `ryu` is the Core floor, named that way for backwards compatibility — every
+ * manifest written before per-surface floors existed spells it `ryu`, and Core's
+ * `EnginesReq::floor_for` maps the `core` surface onto it. The remaining keys are
+ * optional floors for the surfaces a plugin actually touches.
+ *
+ * Values are NOT validated as semver ranges here: Core is the authority and
+ * rejects an unparseable requirement at manifest load with a precise message.
+ * Duplicating a range parser in the SDK would only create a second, drifting
+ * opinion about what `">=1.2, <2"` means.
+ */
+export const EnginesReqSchema = z.object({
+	/** Floor for the terminal (`cli`) surface. */
+	cli: z.string().optional(),
+	/** Floor for the Tauri desktop app. */
+	desktop: z.string().optional(),
+	/** Floor for the browser extension. */
+	extension: z.string().optional(),
+	/** Floor for the Ryu Gateway. */
+	gateway: z.string().optional(),
+	/** Floor for the dynamic-island companion. */
+	island: z.string().optional(),
+	/** Floor for the mobile app. */
+	mobile: z.string().optional(),
+	/** Floor for the running **Core** (e.g. `">=0.3.0"`). Required. */
+	ryu: z.string().min(1, "engines.ryu is required when engines is present"),
+	/** Floor for the Next.js web app. */
+	web: z.string().optional(),
+});
+
+export type EnginesReq = z.infer<typeof EnginesReqSchema>;
+
 // ── PluginManifest ───────────────────────────────────────────────────────────
 
 /**
@@ -669,6 +706,23 @@ export const PluginManifestSchema = z.object({
 	 */
 	targets: z.array(SurfaceSchema).default([]),
 
+	/**
+	 * Host version floors — the semver requirement each surface must satisfy for
+	 * this plugin to install. Mirrors Core's `EnginesReq`
+	 * (`crates/core/kernel-contracts/src/manifest.rs`).
+	 *
+	 * `ryu` is the **Core** floor and the only required key (it is the legacy
+	 * spelling; every manifest in the wild carries just that one). The rest are
+	 * optional per-surface floors.
+	 *
+	 * REGRESSION THIS FIXES: `engines` was absent from this schema entirely, and
+	 * zod strips unlisted keys — so `ryu pack` silently dropped the whole block
+	 * from every bundle it produced. A plugin could declare a Core floor, publish,
+	 * and ship a bundle that declared none. Any new host floor MUST be added here
+	 * as well as in the Rust contract, or it does not survive packing.
+	 */
+	engines: EnginesReqSchema.optional(),
+
 	/**
 	 * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
 	 * referred user buys this (paid) item. `value` is basis points for `percent`

package/src/runnable/primitives.ts

@@ -204,9 +204,12 @@ export function httpPrimitiveTransport(
 		return (parsed.text ?? "").trim();
 	};
 
-	// `/api/voice/speak` — Core streams raw `audio/wav` bytes back (not JSON, not a
-	// data: URL). Convert the response to a renderable data: URL, as the desktop
-	// host's rpc.ts does, so the shipped type contract ("returns a data: URL") holds.
+	// `/api/voice/speak` — Core streams raw audio bytes back (not JSON, not a
+	// data: URL). Usually `audio/wav`; the cloud engine (`engine: "gateway"`) can
+	// answer with whatever the routed provider produced, so the media type is read
+	// off the response rather than assumed. Convert to a renderable data: URL, as
+	// the desktop host's rpc.ts does, so the shipped type contract ("returns a
+	// data: URL") holds.
 	const speakDirect = async (body: unknown): Promise<string> => {
 		const res = await doFetch(`${base}/api/voice/speak`, {
 			method: "POST",