@civitai/app-sdk 0.61.0 → 0.63.0

package/dist/blocks/index.d.ts

@@ -109,7 +109,7 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, } from './types.js';
 /**
  * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
  * civitai/civitai's zod — see `WorkflowBodyTraining`.

package/dist/blocks/messages.d.ts

@@ -521,6 +521,8 @@ export type ParentToBlockMessage = {
     payload: {
         requestId: string;
         selected?: BlockUploadedImageInfo | BlockGenerationSourceImageInfo | BlockPendingImageInfo;
+        /** A `bytes` upload's refusal or failure: a host string or a forwarded server message. */
+        error?: string;
     };
 } | {
     type: 'IMAGE_SCAN_RESOLVED';
@@ -836,6 +838,10 @@ export type BlockToParentMessage = {
         requestId: string;
         purpose?: BlockUploadPurpose;
         asyncScan?: boolean;
+        /** In-tab image bytes; no picker. Page apps only. See the comment above. */
+        bytes?: ArrayBuffer;
+        /** Optional name for a `bytes` upload (host-sanitised). */
+        filename?: string;
     };
 } | {
     type: 'SET_USER_CHECKPOINT';

package/dist/blocks/types.d.ts

@@ -1859,6 +1859,57 @@ export interface ManifestPreview {
     description: string;
     screenshots?: string[];
 }
+/**
+ * One declared property of a custom event — see {@link BlockManifestV1.analytics}.
+ *
+ * Exactly three types, and deliberately NO free-text string:
+ *
+ * - `enum` — a string drawn from `values`: 1 to 50 distinct, non-empty strings of
+ *   at most 64 characters (Unicode code points) each. A string that is not one of
+ *   the declared values will never be recorded.
+ * - `number` — not range-limited, so do not use one to carry an identifier.
+ * - `boolean`.
+ *
+ * No other key is allowed on a declaration (`values` only on an `enum`).
+ * Mirrors the canonical schema's `analytics.events.*.properties.*`.
+ */
+export type BlockAnalyticsPropertyDeclaration = {
+    type: 'enum';
+    values: string[];
+} | {
+    type: 'number';
+} | {
+    type: 'boolean';
+};
+/**
+ * One declared custom event — see {@link BlockManifestV1.analytics}. Mirrors the
+ * canonical schema's `analytics.events.*`.
+ */
+export interface BlockAnalyticsEventDeclaration {
+    /**
+     * Optional human-readable meaning of the event, shown to reviewers and in
+     * your analytics. At most 200 characters (Unicode code points).
+     */
+    description?: string;
+    /**
+     * Property name → declaration. At most 10 properties per event. A property
+     * name follows the same rule as an event name: lowercase snake_case, a letter
+     * then up to 63 of `a-z`, `0-9` or `_` (`^[a-z][a-z0-9_]{0,63}$`).
+     */
+    properties?: Record<string, BlockAnalyticsPropertyDeclaration>;
+}
+/**
+ * The manifest's `analytics` object — see {@link BlockManifestV1.analytics}.
+ * Mirrors the canonical schema's `analytics`; no other key is allowed.
+ */
+export interface BlockAnalyticsDeclaration {
+    /**
+     * Event name → declaration. At most 50 events. An event name is lowercase
+     * snake_case: a letter, then up to 63 of `a-z`, `0-9` or `_`
+     * (`^[a-z][a-z0-9_]{0,63}$`).
+     */
+    events?: Record<string, BlockAnalyticsEventDeclaration>;
+}
 /**
  * One entry of a manifest's `goods[]`. Mirrors the canonical schema exactly;
  * `id`, `title` and `priceBuzz` are required there and so are they here.
@@ -1978,6 +2029,26 @@ export interface BlockManifestV1 {
      * Kept in lockstep with the canonical schema's `goods`.
      */
     goods?: BlockManifestGood[];
+    /**
+     * Optional CUSTOM EVENTS declaration. `events` names every event the app may
+     * send and the properties each event may carry. Manifest-governed and
+     * REVIEW-GATED: the declaration a moderator approves is the only one the
+     * platform accepts events against, so a reviewer can see what the app tracks.
+     *
+     * Properties are typed `enum` (a declared list of string values), `number` or
+     * `boolean` ONLY — free-text strings are deliberately not supported, so a
+     * string that is not one of an enum's declared values will never be recorded.
+     * That is what keeps prompts, emails and usernames out of string properties.
+     * Owners see aggregates only, never individual events.
+     *
+     * Limits (the canonical schema's, which this type cannot express): event and
+     * property names match `^[a-z][a-z0-9_]{0,63}$`; at most 50 events and 10
+     * properties per event; an enum declares 1 to 50 distinct non-empty values of
+     * at most 64 code points; a `description` is at most 200 code points. The
+     * platform's manifest validator is authoritative. Kept in lockstep with the
+     * canonical schema's `analytics`.
+     */
+    analytics?: BlockAnalyticsDeclaration;
     /** Optional; the canonical declares no required sub-field. */
     iframe?: ManifestIframe;
     /** Full-page surface descriptor (W10). */
@@ -2429,7 +2500,11 @@ export type BlockPostSource = {
     imageIndexes?: number[];
 } | {
     kind: 'published';
-    /** Ids returned by a previous `usePublishGenerationOutputs()` publish. */
+    /**
+     * Ids returned by a previous `usePublishGenerationOutputs()` publish, or
+     * by an in-tab `bytes` upload (`useUploadImageBytes()` in
+     * `@civitai/blocks-react`; page apps only).
+     */
     imageIds: number[];
 };
 /**

package/dist/index.d.ts

@@ -25,11 +25,11 @@
  *
  *  - **`./blocks`** — importing it RUNS `./safe-storage` for its side effect
  *    (repairing `localStorage`/`sessionStorage` at an opaque origin). Folding
- *    154 symbols and that side effect into the root would make every OAuth app
+ *    157 symbols and that side effect into the root would make every OAuth app
  *    that writes `import { exchangeCode } from '@civitai/app-sdk'` pay for the
  *    Civitai-Apps contract it does not use. Blocks and OAuth apps are disjoint
  *    audiences; see this package's README.
- *    🔴 That 154 is ASSERTED, not merely quoted — by
+ *    🔴 That 157 is ASSERTED, not merely quoted — by
  *    `packages/civitai-app-sdk/test/export-surface.test.ts`, which pins
  *    `surface.get('./blocks').size`. It said 119 here against a real 125 until
  *    2026-10-04, because the existing checks pin the root as an exact union and

package/dist/index.js

@@ -25,11 +25,11 @@
  *
  *  - **`./blocks`** — importing it RUNS `./safe-storage` for its side effect
  *    (repairing `localStorage`/`sessionStorage` at an opaque origin). Folding
- *    154 symbols and that side effect into the root would make every OAuth app
+ *    157 symbols and that side effect into the root would make every OAuth app
  *    that writes `import { exchangeCode } from '@civitai/app-sdk'` pay for the
  *    Civitai-Apps contract it does not use. Blocks and OAuth apps are disjoint
  *    audiences; see this package's README.
- *    🔴 That 154 is ASSERTED, not merely quoted — by
+ *    🔴 That 157 is ASSERTED, not merely quoted — by
  *    `packages/civitai-app-sdk/test/export-surface.test.ts`, which pins
  *    `surface.get('./blocks').size`. It said 119 here against a real 125 until
  *    2026-10-04, because the existing checks pin the root as an exact union and

package/dist/manifest/defineBlock.js

@@ -45,6 +45,7 @@ import { readFileSync } from 'node:fs';
 import Ajv2020 from 'ajv/dist/2020.js';
 import { BlockManifestError } from '../blocks/manifestError.js';
 import { BLOCK_SCOPES } from '../blocks/scopes.js';
+import { preferDiscriminatedBranch } from './discriminatedBranch.js';
 /**
  * Rules `defineBlock` applies that the canonical schema does NOT express in
  * machine-checkable form.
@@ -173,7 +174,11 @@ function canonicalValidator() {
     // scaffold. The gap is recorded in KNOWN_GAPS, not shouted at the author on
     // every boot. NOTE this silences Ajv's own diagnostics only; validation
     // errors are returned in `validate.errors`, never logged.
-    const ajv = new Ajv2020({ allErrors: true, strict: false, logger: false });
+    //
+    // `verbose: true` puts the failed keyword's own `schema` and the offending
+    // `data` on each error. `preferDiscriminatedBranch` reads both off a failed
+    // `oneOf` / `anyOf`; it changes which error is REPORTED, never the verdict.
+    const ajv = new Ajv2020({ allErrors: true, strict: false, logger: false, verbose: true });
     compiled = ajv.compile(loadCanonicalSchema());
     return compiled;
 }
@@ -194,12 +199,14 @@ function toDotPath(instancePath) {
 }
 const PASCAL_CASE_PATTERN = /^[A-Z][A-Za-z0-9]*$/;
 /**
- * Turns the FIRST Ajv error into a `BlockManifestError`. Ajv's own wording is
- * kept (it is derived from the schema, so it cannot drift); only the field path
- * is reshaped, and one case gets an extra hint because it is the mistake the
+ * Turns ONE Ajv error (the one {@link preferDiscriminatedBranch} picked) into a
+ * `BlockManifestError`. Ajv's own wording is kept (it is derived from the
+ * schema, so it cannot drift); only the field path is reshaped, and two cases
+ * get extra wording: an unknown key inside a discriminated branch says which
+ * branch, and a PascalCase scope gets a hint because it is the mistake the
  * docs see most.
  */
-function toManifestError(error, manifest) {
+function toManifestError(error, manifest, discriminator) {
     const base = toDotPath(error.instancePath);
     if (error.keyword === 'required') {
         const missing = error.params.missingProperty;
@@ -216,7 +223,10 @@ function toManifestError(error, manifest) {
     }
     if (error.keyword === 'additionalProperties') {
         const extra = error.params.additionalProperty;
-        message = `${shown}.${extra} is not a known property here`;
+        message = discriminator
+            ? `${shown}.${extra} is not a known property when \`${discriminator.key}\` is ` +
+                JSON.stringify(discriminator.value)
+            : `${shown}.${extra} is not a known property here`;
         return new BlockManifestError(message, field === '' ? extra : `${field}.${extra}`);
     }
     // The one hint worth adding: block scopes are colon-separated lowercase, and
@@ -281,12 +291,11 @@ export function defineBlock(config) {
     // whatever Ajv rejects, this rejects.
     const validate = canonicalValidator();
     if (!validate(manifest)) {
-        const errors = validate.errors ?? [];
-        const first = errors[0];
+        const picked = preferDiscriminatedBranch(validate.errors ?? []);
         /* c8 ignore next */
-        if (!first)
+        if (!picked)
             throw new BlockManifestError('manifest failed schema validation');
-        throw toManifestError(first, manifest);
+        throw toManifestError(picked.error, manifest, picked.discriminator);
     }
     // (2) The prose-only server rejections. Strictly additive, one per
     // SCHEMA_DIVERGENCES entry, in the table's order.

package/dist/manifest/discriminatedBranch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which validation error to REPORT when a `oneOf` / `anyOf` fails.
+ *
+ * INTERNAL to `./defineBlock` — not re-exported from `./index`, and typed
+ * structurally (no Ajv import) so it can be exercised against small synthetic
+ * schemas in `test/manifest/discriminated-branch.test.ts`.
+ */
+/** The fields of an Ajv `ErrorObject` this reads. `schema` and `data` need Ajv's `verbose: true`. */
+export interface ValidationErrorLike {
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+    schema?: unknown;
+    data?: unknown;
+}
+/** The discriminator that selected the member an error is reported from. */
+export interface Discriminator {
+    key: string;
+    value: unknown;
+}
+/**
+ * Picks the error to REPORT. Ajv (with `allErrors`) validates every member of
+ * a failed `oneOf` / `anyOf` and lists all their errors in member order, so
+ * the plain first error is the FIRST MEMBER's complaint whichever member the
+ * author was writing: a `{ type: 'number', min: 0 }` property declaration used
+ * to be reported as "`values` is required", the `enum` member's rule.
+ *
+ * Where the members discriminate on a `const` (see {@link discriminatorKey})
+ * and the instance's value for that key equals exactly one member's, that
+ * member is the one the author meant: errors from the OTHER members, on that
+ * instance, are skipped, and the first error left is returned. (The summary
+ * `oneOf` / `anyOf` error needs no handling: Ajv lists it after the members'
+ * own errors.) `discriminator` is set when the returned error is on the
+ * discriminated object itself, so the message can say which member it is from.
+ *
+ * Any other failed composition — no shared `const` property, or a value no
+ * member names, or more than one member naming it — is left exactly as it
+ * was: the first error wins.
+ *
+ * 🔴 SELECTION ONLY. It is given the errors of a manifest Ajv has already
+ * rejected and returns one of them (the plain first if it would otherwise skip
+ * everything; `undefined` only for an empty list), so it cannot turn a
+ * rejection into an acceptance or the reverse.
+ *
+ * Members reached through `$ref` report a `schemaPath` relative to the
+ * referenced schema, so their errors are not recognised as a member's and are
+ * never skipped — that site degrades to "first error not from a recognised
+ * other member". The canonical uses no `$ref` today.
+ */
+export declare function preferDiscriminatedBranch<E extends ValidationErrorLike>(errors: E[]): {
+    error: E;
+    discriminator?: Discriminator;
+} | undefined;
+//# sourceMappingURL=discriminatedBranch.d.ts.map

package/dist/manifest/discriminatedBranch.js

@@ -0,0 +1,100 @@
+/**
+ * Which validation error to REPORT when a `oneOf` / `anyOf` fails.
+ *
+ * INTERNAL to `./defineBlock` — not re-exported from `./index`, and typed
+ * structurally (no Ajv import) so it can be exercised against small synthetic
+ * schemas in `test/manifest/discriminated-branch.test.ts`.
+ */
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** `{ value }` when `member.properties[key]` pins a primitive `const`, else `null`. */
+function constOf(member, key) {
+    const prop = isRecord(member) && isRecord(member.properties) ? member.properties[key] : undefined;
+    if (!isRecord(prop) || !('const' in prop))
+        return null;
+    return typeof prop.const === 'object' && prop.const !== null ? null : { value: prop.const };
+}
+/**
+ * The property every member of a `oneOf` / `anyOf` pins to its own `const` —
+ * `type` in `[{ properties: { type: { const: 'enum' } } }, { … 'number' }, …]` —
+ * or `undefined` when the members do not discriminate that way. Read from the
+ * schema, so nothing here names a manifest field.
+ */
+function discriminatorKey(members) {
+    const first = members[0];
+    if (!isRecord(first) || !isRecord(first.properties))
+        return undefined;
+    return Object.keys(first.properties).find((key) => members.every((member) => constOf(member, key) !== null));
+}
+/**
+ * Picks the error to REPORT. Ajv (with `allErrors`) validates every member of
+ * a failed `oneOf` / `anyOf` and lists all their errors in member order, so
+ * the plain first error is the FIRST MEMBER's complaint whichever member the
+ * author was writing: a `{ type: 'number', min: 0 }` property declaration used
+ * to be reported as "`values` is required", the `enum` member's rule.
+ *
+ * Where the members discriminate on a `const` (see {@link discriminatorKey})
+ * and the instance's value for that key equals exactly one member's, that
+ * member is the one the author meant: errors from the OTHER members, on that
+ * instance, are skipped, and the first error left is returned. (The summary
+ * `oneOf` / `anyOf` error needs no handling: Ajv lists it after the members'
+ * own errors.) `discriminator` is set when the returned error is on the
+ * discriminated object itself, so the message can say which member it is from.
+ *
+ * Any other failed composition — no shared `const` property, or a value no
+ * member names, or more than one member naming it — is left exactly as it
+ * was: the first error wins.
+ *
+ * 🔴 SELECTION ONLY. It is given the errors of a manifest Ajv has already
+ * rejected and returns one of them (the plain first if it would otherwise skip
+ * everything; `undefined` only for an empty list), so it cannot turn a
+ * rejection into an acceptance or the reverse.
+ *
+ * Members reached through `$ref` report a `schemaPath` relative to the
+ * referenced schema, so their errors are not recognised as a member's and are
+ * never skipped — that site degrades to "first error not from a recognised
+ * other member". The canonical uses no `$ref` today.
+ */
+export function preferDiscriminatedBranch(errors) {
+    // One entry per member of each discriminated composition that failed: where
+    // its errors live (`prefix`), on which instance, and — for the member the
+    // instance's discriminator names — the discriminator (`chosen`).
+    const scopes = [];
+    for (const error of errors) {
+        if (error.keyword !== 'oneOf' && error.keyword !== 'anyOf')
+            continue;
+        const members = error.schema;
+        if (!Array.isArray(members) || !isRecord(error.data))
+            continue;
+        const key = discriminatorKey(members);
+        if (key === undefined)
+            continue;
+        const value = error.data[key];
+        const matching = members.flatMap((member, index) => constOf(member, key)?.value === value ? [index] : []);
+        if (matching.length !== 1)
+            continue;
+        members.forEach((_member, index) => {
+            scopes.push({
+                prefix: `${error.schemaPath}/${index}/`,
+                instancePath: error.instancePath,
+                ...(index === matching[0] ? { chosen: { key, value } } : {}),
+            });
+        });
+    }
+    for (const error of errors) {
+        // Compositions nest, so an error can sit inside several members at once.
+        const within = scopes.filter((s) => error.schemaPath.startsWith(s.prefix) &&
+            (error.instancePath === s.instancePath ||
+                error.instancePath.startsWith(`${s.instancePath}/`)));
+        // Inside a member, at any level, that its instance's discriminator does not name.
+        if (within.some((s) => !s.chosen))
+            continue;
+        // The member is named in the message only for an error ON the discriminated
+        // object itself (the innermost one), not for one on something nested inside it.
+        const innermost = within.reduce((a, b) => (a && a.prefix.length >= b.prefix.length ? a : b), undefined);
+        return innermost?.chosen && error.instancePath === innermost.instancePath
+            ? { error, discriminator: innermost.chosen }
+            : { error };
+    }
+    return errors[0] ? { error: errors[0] } : undefined;
+}
+//# sourceMappingURL=discriminatedBranch.js.map

package/dist/manifest/index.d.ts

@@ -15,5 +15,5 @@
 export { defineBlock, SCHEMA_DIVERGENCES, KNOWN_GAPS, loadCanonicalSchema } from './defineBlock.js';
 export type { DefineBlockConfig } from './defineBlock.js';
 export { BlockManifestError } from '../blocks/manifestError.js';
-export type { BlockManifest, BlockManifestGood, BlockManifestV1 } from '../blocks/types.js';
+export type { BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, } from '../blocks/types.js';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",

package/schemas/app-block/v1.json

@@ -275,6 +275,104 @@
         }
       }
     },
+    "analytics": {
+      "type": "object",
+      "description": "Optional CUSTOM EVENTS declaration. `events` names every event your app may send with `useBlockAnalytics().track(name, properties)` and the properties each event may carry. Manifest-governed and REVIEW-GATED: the declaration a moderator approves is the only one the platform will accept events against, so a reviewer can see what your app tracks. Properties are typed `enum` (a declared list of string values), `number` or `boolean` ONLY — free-text strings are deliberately not supported, so a string that is not one of an enum's declared values will never be recorded. That is what keeps prompts, emails and usernames out of string properties (a `number` property is not range-limited, so do not use one to carry an identifier). Owners will see aggregates only, never individual events. The platform's manifest validator is authoritative.",
+      "additionalProperties": false,
+      "properties": {
+        "events": {
+          "type": "object",
+          "description": "Map of event name → declaration. At most 50 events. An event name is lowercase snake_case: a letter, then up to 63 of a-z, 0-9 or _.",
+          "maxProperties": 50,
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[a-z][a-z0-9_]{0,63}$": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "description": {
+                  "type": "string",
+                  "description": "Optional human-readable meaning of the event, shown to reviewers and in your analytics.",
+                  "maxLength": 200
+                },
+                "properties": {
+                  "type": "object",
+                  "description": "Map of property name → declaration. At most 10 properties per event. A property name follows the same rule as an event name.",
+                  "maxProperties": 10,
+                  "additionalProperties": false,
+                  "patternProperties": {
+                    "^[a-z][a-z0-9_]{0,63}$": {
+                      "type": "object",
+                      "allOf": [
+                        {
+                          "$comment": "Checked FIRST, before the oneOf below, so a wrong type is reported as such rather than as a missing `values`.",
+                          "required": ["type"],
+                          "properties": {
+                            "type": {
+                              "description": "The property's type. There is no free-text string type: declare an enum.",
+                              "enum": ["enum", "number", "boolean"]
+                            }
+                          }
+                        },
+                        {
+                          "oneOf": [
+                            {
+                              "type": "object",
+                              "description": "A string drawn from a declared list. A string outside `values` will not be recorded.",
+                              "additionalProperties": false,
+                              "required": ["type", "values"],
+                              "properties": {
+                                "type": {
+                                  "const": "enum"
+                                },
+                                "values": {
+                                  "type": "array",
+                                  "description": "The allowed values: 1 to 50 distinct non-empty strings of at most 64 characters (Unicode code points) each.",
+                                  "minItems": 1,
+                                  "maxItems": 50,
+                                  "uniqueItems": true,
+                                  "items": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": 64
+                                  }
+                                }
+                              }
+                            },
+                            {
+                              "type": "object",
+                              "description": "A number.",
+                              "additionalProperties": false,
+                              "required": ["type"],
+                              "properties": {
+                                "type": {
+                                  "const": "number"
+                                }
+                              }
+                            },
+                            {
+                              "type": "object",
+                              "description": "A boolean.",
+                              "additionalProperties": false,
+                              "required": ["type"],
+                              "properties": {
+                                "type": {
+                                  "const": "boolean"
+                                }
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "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.",