@civitai/app-sdk 0.13.0 → 0.14.0

package/schemas/app-block/v1.json

@@ -1,184 +1,195 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://civitai.com/schemas/app-block/v1.json",
-  "title": "Civitai App Block Manifest v1",
-  "description": "Manifest shape for a Civitai App Block. Mirrors the runtime check performed by defineBlock() in @civitai/app-sdk/blocks.",
+  "title": "Civitai App Block Manifest",
+  "description": "THE canonical, server-published schema for block.manifest.json — the ONLY mandatory file in a Civitai App Block. Published at https://civitai.com/schemas/app-block/v1.json. This is the single source of truth for the block manifest contract: the platform's server-side validator (src/server/services/block-manifest-validator.service.ts) and the `civitai` CLI both validate against these same rules. Set this URL as your manifest's `$schema` for editor validation.",
   "type": "object",
-  "required": [
-    "$schema",
-    "appId",
-    "blockId",
-    "version",
-    "name",
-    "type",
-    "targets",
-    "scopes",
-    "iframe",
-    "contentRating",
-    "minApiVersion"
-  ],
-  "additionalProperties": true,
+  "required": ["blockId", "version", "name", "contentRating", "scopes"],
   "properties": {
     "$schema": {
       "type": "string",
-      "const": "https://civitai.com/schemas/app-block/v1.json"
-    },
-    "appId": {
-      "type": "string",
-      "minLength": 1
+      "description": "Optional JSON-Schema reference; ignored by the platform validator."
     },
     "blockId": {
       "type": "string",
-      "pattern": "^[a-z0-9-]{3,64}$",
-      "description": "Immutable block identifier. Lowercase letters, digits, and hyphens; 3-64 characters."
+      "description": "The block slug. Becomes the canonical submission slug. Lowercase, starts with a letter, hyphen-separated, 3-40 chars.",
+      "minLength": 3,
+      "maxLength": 40,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
     },
     "version": {
       "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
-      "description": "Semver."
+      "description": "Semantic version (x.y.z, optional -prerelease).",
+      "minLength": 1,
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$"
     },
     "name": {
       "type": "string",
-      "minLength": 1,
-      "maxLength": 80
+      "description": "Human-readable display name. The server only requires a non-empty string (no length cap), so the CLI does not impose one either.",
+      "minLength": 1
     },
     "type": {
       "type": "string",
-      "enum": ["block", "embed"]
+      "description": "Free-form descriptor used by some examples (e.g. \"block\"). Not validated by the platform.",
+      "enum": ["block"]
     },
-    "targets": {
+    "contentRating": {
+      "type": "string",
+      "description": "Content rating of the app surface.",
+      "enum": ["g", "pg", "pg13", "r", "x"]
+    },
+    "renderMode": {
+      "type": "string",
+      "description": "How the block renders. Defaults to \"iframe\". \"inline\"/\"hybrid\" require a verified/internal trust tier (server-assigned), so authors should leave this as iframe.",
+      "enum": ["iframe", "inline", "hybrid"]
+    },
+    "trustTier": {
+      "type": "string",
+      "description": "SERVER-OWNED. Do NOT set this in your manifest — the platform assigns the trust tier during review. Present here only to reject dev-set values.",
+      "$comment": "Rejected via 'not' below.",
+      "enum": ["unverified", "verified", "internal"]
+    },
+    "scopes": {
       "type": "array",
-      "minItems": 1,
+      "description": "Capabilities the block requests. Must be a strict subset of what review grants. Each scope is lowercase colon-separated.",
       "items": {
-        "type": "object",
-        "required": ["slotId", "priority"],
-        "properties": {
-          "slotId": { "type": "string", "minLength": 1 },
-          "priority": { "type": "integer" },
-          "requiredContext": {
-            "type": "array",
-            "items": { "type": "string" }
-          }
-        }
+        "type": "string",
+        "enum": [
+          "models:read:self",
+          "media:read:owned",
+          "user:read:self",
+          "ai:write:budgeted",
+          "buzz:read:self",
+          "block:settings:read",
+          "block:settings:write",
+          "social:tip:self",
+          "apps:storage:read",
+          "apps:storage:write"
+        ]
       }
     },
-    "scopes": {
+    "minApiVersion": {
+      "type": "string",
+      "description": "Minimum App SDK API version the block targets (informational).",
+      "pattern": "^\\d+(\\.\\d+)*$"
+    },
+    "buildCommand": {
+      "type": "string",
+      "description": "Config-as-code: command the platform runs to build the static bundle (e.g. \"npm run build\"). Omit for no-build (static) apps. When set, outputDir must also be set.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "outputDir": {
+      "type": "string",
+      "description": "Config-as-code: directory (relative to the project root) the buildCommand emits static files into (e.g. \"dist\"). Required when buildCommand is set.",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^[^/].*"
+    },
+    "publicSettingsKeys": {
       "type": "array",
-      "minItems": 1,
+      "description": "Allowlist of settings keys exposed to anonymous viewers. Default (omitted) = none exposed.",
+      "maxItems": 32,
       "items": {
         "type": "string",
-        "pattern": "^[a-z]+:[a-z]+:[a-z]+$",
-        "description": "Colon-separated lowercase, e.g. models:read:self. PascalCase is rejected."
+        "minLength": 1,
+        "maxLength": 64
       }
     },
+    "assetBundleUrl": {
+      "type": "string",
+      "description": "Optional v2 surface — HTTPS URL to a hosted asset bundle. Must be a public https URL.",
+      "format": "uri",
+      "pattern": "^https://"
+    },
     "iframe": {
       "type": "object",
-      "required": ["src", "minHeight", "resizable", "sandbox"],
+      "description": "iframe envelope. NOTE: iframe.src is SERVER-OWNED — do NOT set it; the platform stamps the canonical bundle URL during build/approve.",
+      "additionalProperties": false,
       "properties": {
         "src": {
-          "type": "string",
-          "description": "HTTPS URL of the block app. http://localhost or http://127.0.0.1 also accepted for local dev."
+          "description": "SERVER-OWNED. Do NOT set iframe.src — the platform assigns it. Present here only so the schema can reject dev-set values.",
+          "$comment": "Rejected via 'not' below."
+        },
+        "minHeight": {
+          "type": "integer",
+          "description": "Minimum iframe height in px.",
+          "minimum": 40,
+          "maximum": 4000
+        },
+        "maxHeight": {
+          "description": "Maximum iframe height in px, or null for unbounded.",
+          "type": ["integer", "null"],
+          "minimum": 40,
+          "maximum": 4000
+        },
+        "resizable": {
+          "type": "boolean",
+          "description": "Whether the host honours RESIZE_IFRAME messages."
         },
-        "minHeight": { "type": "integer", "exclusiveMinimum": 0 },
-        "maxHeight": { "type": ["integer", "null"] },
-        "resizable": { "type": "boolean" },
         "sandbox": {
           "type": "string",
-          "allOf": [
-            {
-              "not": { "pattern": "(^|\\s)allow-same-origin(\\s|$)" },
-              "description": "Must not contain allow-same-origin — combined with allow-scripts it defeats the sandbox."
-            },
-            {
-              "not": { "pattern": "(^|\\s)allow-top-navigation(\\s|$)" },
-              "description": "Must not contain allow-top-navigation — use the NAVIGATE postMessage instead."
-            },
-            {
-              "not": { "pattern": "(^|\\s)allow-top-navigation-by-user-activation(\\s|$)" },
-              "description": "Must not contain allow-top-navigation-by-user-activation — same threat as allow-top-navigation, gated on a user gesture."
-            },
-            {
-              "not": { "pattern": "(^|\\s)allow-top-navigation-to-custom-protocols(\\s|$)" },
-              "description": "Must not contain allow-top-navigation-to-custom-protocols — same threat as allow-top-navigation, restricted to non-fetch schemes."
-            }
-          ]
+          "description": "Space-separated iframe sandbox tokens. Unverified tier allows only: allow-scripts, allow-forms. Never combine allow-same-origin with allow-scripts.",
+          "minLength": 1
         }
       }
     },
-    "assets": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["url", "integrity"],
-        "properties": {
-          "url": { "type": "string" },
-          "integrity": {
-            "type": "string",
-            "pattern": "^sha(256|384|512)-[A-Za-z0-9+/=]+$"
-          }
+    "page": {
+      "type": "object",
+      "description": "Full-page surface descriptor (W10). Page apps mount at /apps/run/<slug>.",
+      "additionalProperties": false,
+      "required": ["path", "title"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Sub-path the page mounts at; must start with '/'.",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^/"
+        },
+        "title": {
+          "type": "string",
+          "description": "Title shown in host chrome.",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "icon": {
+          "type": "string",
+          "description": "Optional icon name.",
+          "maxLength": 128
+        },
+        "buzzBudgetPerGen": {
+          "type": "integer",
+          "description": "Optional per-generation Buzz budget for ai:write:budgeted tokens. Positive integer; server-clamped to the per-gen cap.",
+          "exclusiveMinimum": 0
         }
       }
     },
-    "settings": {
+    "targets": {
       "type": "array",
+      "description": "Model-page slot targets. Each target's slotId must be a known registered model slot (not the page slot). Optional for page-only apps.",
+      "maxItems": 16,
       "items": {
         "type": "object",
-        "required": ["id", "type", "label"],
+        "required": ["slotId"],
         "properties": {
-          "id": { "type": "string", "minLength": 1 },
-          "type": { "type": "string", "enum": ["string", "number", "boolean", "select"] },
-          "label": { "type": "string", "minLength": 1 },
-          "default": {},
-          "options": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": ["value", "label"],
-              "properties": {
-                "value": { "type": "string" },
-                "label": { "type": "string" }
-              }
-            }
-          },
-          "min": { "type": "number" },
-          "max": { "type": "number" },
-          "required": { "type": "boolean" }
-        }
-      }
-    },
-    "contentRating": {
-      "type": "string",
-      "enum": ["g", "pg", "pg13", "r", "x"]
-    },
-    "preview": {
-      "type": "object",
-      "required": ["thumbnail", "description"],
-      "properties": {
-        "thumbnail": { "type": "string" },
-        "description": { "type": "string" },
-        "screenshots": {
-          "type": "array",
-          "items": { "type": "string" }
+          "slotId": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       }
-    },
-    "promotionEligible": { "type": "boolean" },
-    "minApiVersion": { "type": "string" },
-    "renderMode": {
-      "type": "string",
-      "enum": ["iframe", "inline", "hybrid"],
-      "description": "Optional. Defaults to iframe. v1 manifests may omit."
-    },
-    "assetBundle": {
-      "type": "object",
-      "properties": {
-        "url": { "type": ["string", "null"] },
-        "sha256": { "type": ["string", "null"] }
+    }
+  },
+  "allOf": [
+    {
+      "$comment": "outputDir is required whenever buildCommand is set. NOTE: the server-owned iframe.src and trustTier fields are rejected by the platform validator (and the CLI in Go) with clearer error messages than JSON Schema's `not`; they are declared in `properties` above only so the schema documents them.",
+      "if": {
+        "required": ["buildCommand"]
+      },
+      "then": {
+        "required": ["outputDir"]
       }
-    },
-    "trustTier": {
-      "type": "string",
-      "enum": ["unverified", "verified", "internal"]
     }
-  }
+  ]
 }