@xemahq/kernel-contracts 0.49.2 → 0.49.3

package/dist/app-definition/index.d.ts

@@ -1,5 +1,6 @@
 export * from './lib/field-type';
 export * from './lib/page-kind';
+export * from './lib/component';
 export * from './lib/widget';
 export * from './lib/action';
 export * from './lib/automation';

package/dist/app-definition/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app-definition/index.ts"],"names":[],"mappings":"AAMA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app-definition/index.ts"],"names":[],"mappings":"AAMA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/dist/app-definition/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./lib/field-type"), exports);
 __exportStar(require("./lib/page-kind"), exports);
+__exportStar(require("./lib/component"), exports);
 __exportStar(require("./lib/widget"), exports);
 __exportStar(require("./lib/action"), exports);
 __exportStar(require("./lib/automation"), exports);

package/dist/app-definition/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app-definition/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAMA,mDAAiC;AACjC,kDAAgC;AAChC,+CAA6B;AAC7B,+CAA6B;AAC7B,mDAAiC;AACjC,sDAAoC;AACpC,kDAAgC;AAChC,mDAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app-definition/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAMA,mDAAiC;AACjC,kDAAgC;AAChC,kDAAgC;AAChC,+CAA6B;AAC7B,+CAA6B;AAC7B,mDAAiC;AACjC,sDAAoC;AACpC,kDAAgC;AAChC,mDAAiC"}

package/dist/app-definition/lib/component.d.ts

@@ -0,0 +1,8 @@
+export declare enum AppComponentKind {
+    Code = "code"
+}
+export interface AppCodeComponent {
+    readonly kind: AppComponentKind.Code;
+    readonly source: string;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/app-definition/lib/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/app-definition/lib/component.ts"],"names":[],"mappings":"AA+BA,oBAAY,gBAAgB;IAE1B,IAAI,SAAS;CACd;AASD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC;IAErC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/dist/app-definition/lib/component.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppComponentKind = void 0;
+var AppComponentKind;
+(function (AppComponentKind) {
+    AppComponentKind["Code"] = "code";
+})(AppComponentKind || (exports.AppComponentKind = AppComponentKind = {}));
+//# sourceMappingURL=component.js.map

package/dist/app-definition/lib/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/app-definition/lib/component.ts"],"names":[],"mappings":";;;AA+BA,IAAY,gBAGX;AAHD,WAAY,gBAAgB;IAE1B,iCAAa,CAAA;AACf,CAAC,EAHW,gBAAgB,gCAAhB,gBAAgB,QAG3B"}

package/dist/app-definition/lib/definition.d.ts

@@ -3,6 +3,7 @@ import { AppPageKind } from './page-kind';
 import { AppAction } from './action';
 import { AppAutomation } from './automation';
 import { AppWidget } from './widget';
+import { AppCodeComponent } from './component';
 export interface AppField {
     key: string;
     label: string;
@@ -36,6 +37,7 @@ export interface AppPage {
     widgets?: AppWidget[];
     dateField?: string;
     linkKey?: string;
+    component?: AppCodeComponent;
 }
 export interface AppLink {
     key: string;

package/dist/app-definition/lib/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../../src/app-definition/lib/definition.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAMrC,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB,eAAe,CAAC,EAAE,MAAM,CAAC;IAKzB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAQD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IAExB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IAEtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,KAAK,EAAE,OAAO,EAAE,CAAC;IAEjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAE9B,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../../src/app-definition/lib/definition.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAM/C,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB,eAAe,CAAC,EAAE,MAAM,CAAC;IAKzB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAQD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IAExB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IAEtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,OAAO,CAAC,EAAE,MAAM,CAAC;IAOjB,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AASD,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,KAAK,EAAE,OAAO,EAAE,CAAC;IAEjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAE9B,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB"}

package/dist/app-definition/lib/widget.d.ts

@@ -1,3 +1,4 @@
+import { AppCodeComponent } from './component';
 export declare enum AppWidgetKind {
     Stat = "stat",
     Table = "table",
@@ -39,5 +40,6 @@ export interface AppWidget {
     aggregate?: AppWidgetAggregate;
     filter?: Record<string, string | number | boolean>;
     series?: AppWidgetSeriesSource;
+    component?: AppCodeComponent;
 }
 //# sourceMappingURL=widget.d.ts.map

package/dist/app-definition/lib/widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../../../src/app-definition/lib/widget.ts"],"names":[],"mappings":"AAQA,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,KAAK,UAAU;IAMf,KAAK,UAAU;CAChB;AAQD,oBAAY,mBAAmB;IAC7B,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,MAAM,WAAW;CAClB;AAGD,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;CAChB;AAOD,oBAAY,YAAY;IACtB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAMD,oBAAY,sBAAsB;IAChC,KAAK,UAAU;IACf,GAAG,QAAQ;CACZ;AAMD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,sBAAsB,CAAC,KAAK,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,sBAAsB,CAAC,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAOxD,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,YAAY,CAAC;CACzB;AAQD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IAKd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAE/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAEnD,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC"}
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../../../src/app-definition/lib/widget.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,KAAK,UAAU;IAMf,KAAK,UAAU;CAChB;AAQD,oBAAY,mBAAmB;IAC7B,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,MAAM,WAAW;CAClB;AAGD,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;CAChB;AAOD,oBAAY,YAAY;IACtB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAMD,oBAAY,sBAAsB;IAChC,KAAK,UAAU;IACf,GAAG,QAAQ;CACZ;AAMD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,sBAAsB,CAAC,KAAK,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,sBAAsB,CAAC,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAOxD,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,YAAY,CAAC;CACzB;AAQD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IAKd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAE/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAEnD,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAO/B,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B"}

package/dist/app-definition/lib/widget.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget.js","sourceRoot":"","sources":["../../../src/app-definition/lib/widget.ts"],"names":[],"mappings":";;;AAQA,IAAY,aASX;AATD,WAAY,aAAa;IACvB,8BAAa,CAAA;IACb,gCAAe,CAAA;IAMf,gCAAe,CAAA;AACjB,CAAC,EATW,aAAa,6BAAb,aAAa,QASxB;AAQD,IAAY,mBAIX;AAJD,WAAY,mBAAmB;IAC7B,wCAAiB,CAAA;IACjB,gDAAyB,CAAA;IACzB,wCAAiB,CAAA;AACnB,CAAC,EAJW,mBAAmB,mCAAnB,mBAAmB,QAI9B;AAGD,IAAY,kBAEX;AAFD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;AACjB,CAAC,EAFW,kBAAkB,kCAAlB,kBAAkB,QAE7B;AAOD,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,2BAAW,CAAA;IACX,6BAAa,CAAA;IACb,+BAAe,CAAA;AACjB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAMD,IAAY,sBAGX;AAHD,WAAY,sBAAsB;IAChC,yCAAe,CAAA;IACf,qCAAW,CAAA;AACb,CAAC,EAHW,sBAAsB,sCAAtB,sBAAsB,QAGjC"}
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../../../src/app-definition/lib/widget.ts"],"names":[],"mappings":";;;AASA,IAAY,aASX;AATD,WAAY,aAAa;IACvB,8BAAa,CAAA;IACb,gCAAe,CAAA;IAMf,gCAAe,CAAA;AACjB,CAAC,EATW,aAAa,6BAAb,aAAa,QASxB;AAQD,IAAY,mBAIX;AAJD,WAAY,mBAAmB;IAC7B,wCAAiB,CAAA;IACjB,gDAAyB,CAAA;IACzB,wCAAiB,CAAA;AACnB,CAAC,EAJW,mBAAmB,mCAAnB,mBAAmB,QAI9B;AAGD,IAAY,kBAEX;AAFD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;AACjB,CAAC,EAFW,kBAAkB,kCAAlB,kBAAkB,QAE7B;AAOD,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,2BAAW,CAAA;IACX,6BAAa,CAAA;IACb,+BAAe,CAAA;AACjB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAMD,IAAY,sBAGX;AAHD,WAAY,sBAAsB;IAChC,yCAAe,CAAA;IACf,qCAAW,CAAA;AACb,CAAC,EAHW,sBAAsB,sCAAtB,sBAAsB,QAGjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.49.2",
+  "version": "0.49.3",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/app-definition/index.ts

@@ -6,6 +6,7 @@
 // the richer zod-inferred `*Def` types stay in the app-forge server.
 export * from './lib/field-type';
 export * from './lib/page-kind';
+export * from './lib/component';
 export * from './lib/widget';
 export * from './lib/action';
 export * from './lib/automation';

package/src/app-definition/lib/component.ts

@@ -0,0 +1,48 @@
+/**
+ * Custom-UI code component — the ADDITIVE Wave-12 extension to the App Forge
+ * declarative definition (plan `runtime-app-platform.md` Wave 12 / D19). A page
+ * or widget MAY carry a `component: { kind: 'code', source }` to render an
+ * author-written UI component INSTEAD of the generic declarative renderer.
+ *
+ * This surface is the SHAPE contract only — the closed `AppComponentKind` enum
+ * plus the plain {@link AppCodeComponent} interface shared, byte-identically,
+ * by the app-forge server (whose zod schema validates it) and the App Forge web
+ * renderer (which draws it). The COMPILE step (server-side esbuild against a
+ * pinned `@xemahq/app-ui`, the SRI'd ESM chunk, and the opaque-origin iframe
+ * runtime) is NOT part of this contract — it is the large multi-wave runtime the
+ * plan defers. Declaring a code component is additive: an absent `component`
+ * (the default on every page/widget today) preserves the current declarative
+ * behavior exactly.
+ *
+ * **Cost is not free and the platform must say so.** The moment a definition
+ * carries a code component, publishing it means COMPILING it, and the app stops
+ * being live-on-keystroke (plan Wave 12). Until the compiler + iframe runtime
+ * ship, the app-forge publish path FAILS CLOSED on any definition containing a
+ * code component (`APP_CUSTOM_UI_NOT_YET_AVAILABLE`) — it never silently accepts
+ * or ignores one.
+ */
+
+/**
+ * Closed set of custom-UI component kinds. Only `code` exists — a
+ * server-compiled, author-authored component. A future non-code kind (e.g. a
+ * pinned marketplace component) is a one-line addition here plus a matching
+ * discriminated variant. Stable wire string; never compare against a free-form
+ * string.
+ */
+export enum AppComponentKind {
+  /** An author-written UI component, compiled server-side against `@xemahq/app-ui`. */
+  Code = 'code',
+}
+
+/**
+ * A `kind: 'code'` custom-UI component authored against the pinned
+ * `@xemahq/app-ui` surface. `source` is the raw component module text; it is
+ * validated (length-bounded) and — once the compiler ships — type-checked and
+ * responsive-linted at PUBLISH time, never at author-keystroke time. Carried
+ * inside the opaque app-definition JSON on a page or widget.
+ */
+export interface AppCodeComponent {
+  readonly kind: AppComponentKind.Code;
+  /** The raw component module source authored against `@xemahq/app-ui`. */
+  readonly source: string;
+}

package/src/app-definition/lib/definition.ts

@@ -14,6 +14,7 @@ import { AppPageKind } from './page-kind';
 import { AppAction } from './action';
 import { AppAutomation } from './automation';
 import { AppWidget } from './widget';
+import { AppCodeComponent } from './component';
 
 /**
  * One entity field. `object`/`list` fields carry a recursive nested `fields[]`
@@ -76,6 +77,13 @@ export interface AppPage {
   dateField?: string;
   /** related: key of the {@link AppLink} this page reverse-looks-up. */
   linkKey?: string;
+  /**
+   * Custom-UI (Wave 12): an author-written code component that renders this page
+   * INSTEAD of the generic declarative renderer. Additive — absent ⇒ the page
+   * renders declaratively (today's behavior). A definition carrying any code
+   * component is compile-gated at publish (see {@link AppCodeComponent}).
+   */
+  component?: AppCodeComponent;
 }
 
 /**

package/src/app-definition/lib/widget.ts

@@ -4,6 +4,7 @@
  * app-forge server's zod schema and the web renderer. All values are stable
  * wire strings — never compare against a free-form string.
  */
+import { AppCodeComponent } from './component';
 
 /** Closed set of dashboard widget kinds. */
 export enum AppWidgetKind {
@@ -94,4 +95,11 @@ export interface AppWidget {
   filter?: Record<string, string | number | boolean>;
   /** Series (chart) source — present iff `kind === AppWidgetKind.Chart`. */
   series?: AppWidgetSeriesSource;
+  /**
+   * Custom-UI (Wave 12): an author-written code component that renders this
+   * widget INSTEAD of the generic declarative widget renderer. Additive — absent
+   * ⇒ the widget renders declaratively (today's behavior). Compile-gated at
+   * publish (see {@link AppCodeComponent}).
+   */
+  component?: AppCodeComponent;
 }