desen-core 1.0.0-draft

package/dist/schemas/element.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.elementSpec = void 0;
+const zod_1 = require("zod");
+const binding_1 = require("./binding");
+const telemetry_1 = require("./telemetry");
+// ─── ElementSpec ─────────────────────────────────────────────────
+// SPEC.md §2.2: type, id, props REQUIRED.
+//
+// CRITICAL RULE: ElementSpec MUST NOT contain `children` or `layout`.
+// These belong exclusively to CompositionSpec (§2.3).
+// Enforced via .refine() to reject any payload with these fields.
+exports.elementSpec = zod_1.z.object({
+    type: zod_1.z.string().min(1),
+    id: zod_1.z.string().min(1),
+    props: zod_1.z.record(zod_1.z.any()),
+    constraints: zod_1.z.object({
+        a11y: zod_1.z.object({
+            aria_label: zod_1.z.string().optional(),
+            aria_role: zod_1.z.string().optional(),
+            min_contrast_ratio: zod_1.z.number().min(1).optional(),
+            focusable: zod_1.z.boolean().optional(),
+        }).optional(),
+    }).passthrough().optional(),
+    modifiers: binding_1.modifiersSpec.optional(),
+    telemetry: telemetry_1.telemetrySpec.optional(),
+}).passthrough()
+    .refine((data) => !("children" in data), { message: "ElementSpec MUST NOT contain 'children'. Use CompositionSpec for containers." })
+    .refine((data) => !("layout" in data), { message: "ElementSpec MUST NOT contain 'layout'. Use CompositionSpec for layout." });

package/dist/schemas/style.d.ts

@@ -0,0 +1,192 @@
+import { z } from "zod";
+export declare const styleSpec: z.ZodObject<{
+    bg_color: z.ZodOptional<z.ZodString>;
+    bg_color_token: z.ZodOptional<z.ZodString>;
+    text_color: z.ZodOptional<z.ZodString>;
+    text_color_token: z.ZodOptional<z.ZodString>;
+    border_color: z.ZodOptional<z.ZodString>;
+    border_color_token: z.ZodOptional<z.ZodString>;
+    font_family: z.ZodOptional<z.ZodString>;
+    font_family_token: z.ZodOptional<z.ZodString>;
+    font_size: z.ZodOptional<z.ZodNumber>;
+    font_size_token: z.ZodOptional<z.ZodString>;
+    font_weight: z.ZodOptional<z.ZodNumber>;
+    font_weight_token: z.ZodOptional<z.ZodString>;
+    line_height: z.ZodOptional<z.ZodNumber>;
+    line_height_token: z.ZodOptional<z.ZodString>;
+    padding: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }>]>>;
+    padding_token: z.ZodOptional<z.ZodString>;
+    margin: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }>]>>;
+    margin_token: z.ZodOptional<z.ZodString>;
+    border_radius: z.ZodOptional<z.ZodNumber>;
+    border_radius_token: z.ZodOptional<z.ZodString>;
+    border_width: z.ZodOptional<z.ZodNumber>;
+    border_width_token: z.ZodOptional<z.ZodString>;
+    min_height: z.ZodOptional<z.ZodNumber>;
+    min_height_token: z.ZodOptional<z.ZodString>;
+    min_width: z.ZodOptional<z.ZodNumber>;
+    min_width_token: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    width_token: z.ZodOptional<z.ZodString>;
+    height: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    height_token: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    opacity_token: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    bg_color: z.ZodOptional<z.ZodString>;
+    bg_color_token: z.ZodOptional<z.ZodString>;
+    text_color: z.ZodOptional<z.ZodString>;
+    text_color_token: z.ZodOptional<z.ZodString>;
+    border_color: z.ZodOptional<z.ZodString>;
+    border_color_token: z.ZodOptional<z.ZodString>;
+    font_family: z.ZodOptional<z.ZodString>;
+    font_family_token: z.ZodOptional<z.ZodString>;
+    font_size: z.ZodOptional<z.ZodNumber>;
+    font_size_token: z.ZodOptional<z.ZodString>;
+    font_weight: z.ZodOptional<z.ZodNumber>;
+    font_weight_token: z.ZodOptional<z.ZodString>;
+    line_height: z.ZodOptional<z.ZodNumber>;
+    line_height_token: z.ZodOptional<z.ZodString>;
+    padding: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }>]>>;
+    padding_token: z.ZodOptional<z.ZodString>;
+    margin: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }>]>>;
+    margin_token: z.ZodOptional<z.ZodString>;
+    border_radius: z.ZodOptional<z.ZodNumber>;
+    border_radius_token: z.ZodOptional<z.ZodString>;
+    border_width: z.ZodOptional<z.ZodNumber>;
+    border_width_token: z.ZodOptional<z.ZodString>;
+    min_height: z.ZodOptional<z.ZodNumber>;
+    min_height_token: z.ZodOptional<z.ZodString>;
+    min_width: z.ZodOptional<z.ZodNumber>;
+    min_width_token: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    width_token: z.ZodOptional<z.ZodString>;
+    height: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    height_token: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    opacity_token: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    bg_color: z.ZodOptional<z.ZodString>;
+    bg_color_token: z.ZodOptional<z.ZodString>;
+    text_color: z.ZodOptional<z.ZodString>;
+    text_color_token: z.ZodOptional<z.ZodString>;
+    border_color: z.ZodOptional<z.ZodString>;
+    border_color_token: z.ZodOptional<z.ZodString>;
+    font_family: z.ZodOptional<z.ZodString>;
+    font_family_token: z.ZodOptional<z.ZodString>;
+    font_size: z.ZodOptional<z.ZodNumber>;
+    font_size_token: z.ZodOptional<z.ZodString>;
+    font_weight: z.ZodOptional<z.ZodNumber>;
+    font_weight_token: z.ZodOptional<z.ZodString>;
+    line_height: z.ZodOptional<z.ZodNumber>;
+    line_height_token: z.ZodOptional<z.ZodString>;
+    padding: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }>]>>;
+    padding_token: z.ZodOptional<z.ZodString>;
+    margin: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }, {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    }>]>>;
+    margin_token: z.ZodOptional<z.ZodString>;
+    border_radius: z.ZodOptional<z.ZodNumber>;
+    border_radius_token: z.ZodOptional<z.ZodString>;
+    border_width: z.ZodOptional<z.ZodNumber>;
+    border_width_token: z.ZodOptional<z.ZodString>;
+    min_height: z.ZodOptional<z.ZodNumber>;
+    min_height_token: z.ZodOptional<z.ZodString>;
+    min_width: z.ZodOptional<z.ZodNumber>;
+    min_width_token: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    width_token: z.ZodOptional<z.ZodString>;
+    height: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    height_token: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    opacity_token: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type StyleSpec = z.infer<typeof styleSpec>;

package/dist/schemas/style.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.styleSpec = void 0;
+const zod_1 = require("zod");
+// ─── Token-Aware Style Schema ────────────────────────────────────
+// SPEC.md §2.6: Properties support both literal and token-based config.
+// Convention: literal `bg_color` + parallel `bg_color_token` (DTCG path).
+//
+// When both are present, runtimes MUST attempt token resolution first.
+// If token resolution fails and literal is type-compatible, runtimes
+// MAY use literal as graceful degradation.
+// DTCG token path: e.g. "color.bg.primary"
+const dtcgTokenPath = zod_1.z.string().min(1);
+exports.styleSpec = zod_1.z.object({
+    // ── Color Properties ──
+    bg_color: zod_1.z.string().optional(),
+    bg_color_token: dtcgTokenPath.optional(),
+    text_color: zod_1.z.string().optional(),
+    text_color_token: dtcgTokenPath.optional(),
+    border_color: zod_1.z.string().optional(),
+    border_color_token: dtcgTokenPath.optional(),
+    // ── Typography Properties ──
+    font_family: zod_1.z.string().optional(),
+    font_family_token: dtcgTokenPath.optional(),
+    font_size: zod_1.z.number().optional(),
+    font_size_token: dtcgTokenPath.optional(),
+    font_weight: zod_1.z.number().optional(),
+    font_weight_token: dtcgTokenPath.optional(),
+    line_height: zod_1.z.number().optional(),
+    line_height_token: dtcgTokenPath.optional(),
+    // ── Spacing Properties ──
+    padding: zod_1.z.union([
+        zod_1.z.number(),
+        zod_1.z.object({
+            top: zod_1.z.number().optional(),
+            right: zod_1.z.number().optional(),
+            bottom: zod_1.z.number().optional(),
+            left: zod_1.z.number().optional(),
+        }),
+    ]).optional(),
+    padding_token: dtcgTokenPath.optional(),
+    margin: zod_1.z.union([
+        zod_1.z.number(),
+        zod_1.z.object({
+            top: zod_1.z.number().optional(),
+            right: zod_1.z.number().optional(),
+            bottom: zod_1.z.number().optional(),
+            left: zod_1.z.number().optional(),
+        }),
+    ]).optional(),
+    margin_token: dtcgTokenPath.optional(),
+    // ── Border Properties ──
+    border_radius: zod_1.z.number().optional(),
+    border_radius_token: dtcgTokenPath.optional(),
+    border_width: zod_1.z.number().optional(),
+    border_width_token: dtcgTokenPath.optional(),
+    // ── Dimension Properties ──
+    min_height: zod_1.z.number().optional(),
+    min_height_token: dtcgTokenPath.optional(),
+    min_width: zod_1.z.number().optional(),
+    min_width_token: dtcgTokenPath.optional(),
+    width: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]).optional(),
+    width_token: dtcgTokenPath.optional(),
+    height: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]).optional(),
+    height_token: dtcgTokenPath.optional(),
+    // ── Opacity ──
+    opacity: zod_1.z.number().min(0).max(1).optional(),
+    opacity_token: dtcgTokenPath.optional(),
+}).passthrough(); // Allow vendor extensions (§2.9)

package/dist/schemas/surface.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export declare const surfaceSpec: z.ZodObject<{
+    id: z.ZodString;
+    root: z.ZodType<any, z.ZodTypeDef, any>;
+    telemetry: z.ZodObject<{
+        emit: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        emit: string[];
+    }, {
+        emit: string[];
+    }>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    root: z.ZodType<any, z.ZodTypeDef, any>;
+    telemetry: z.ZodObject<{
+        emit: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        emit: string[];
+    }, {
+        emit: string[];
+    }>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    root: z.ZodType<any, z.ZodTypeDef, any>;
+    telemetry: z.ZodObject<{
+        emit: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        emit: string[];
+    }, {
+        emit: string[];
+    }>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type SurfaceSpec = z.infer<typeof surfaceSpec>;

package/dist/schemas/surface.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.surfaceSpec = void 0;
+const zod_1 = require("zod");
+const composition_1 = require("./composition");
+const telemetry_1 = require("./telemetry");
+// ─── SurfaceSpec ─────────────────────────────────────────────────
+// SPEC.md §2.8: id, root, telemetry REQUIRED.
+//
+// CRITICAL RULE: root MUST be a CompositionSpec.
+// It MUST NOT be an ElementSpec. An Element cannot exist at the
+// root level; it must be contained within a Composition.
+exports.surfaceSpec = zod_1.z.object({
+    id: zod_1.z.string().min(1).regex(/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/),
+    root: composition_1.compositionSpec,
+    telemetry: telemetry_1.telemetrySpec,
+    metadata: zod_1.z.record(zod_1.z.any()).optional(),
+    environment: zod_1.z.record(zod_1.z.any()).optional(),
+}).passthrough();

package/dist/schemas/telemetry.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+export declare const telemetrySpec: z.ZodObject<{
+    emit: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    emit: string[];
+}, {
+    emit: string[];
+}>;
+export declare const telemetryEnvelopeSpec: z.ZodObject<{
+    session_id: z.ZodString;
+    element_id: z.ZodString;
+    timestamp: z.ZodString;
+    revision_id: z.ZodString;
+    event_type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    session_id: z.ZodString;
+    element_id: z.ZodString;
+    timestamp: z.ZodString;
+    revision_id: z.ZodString;
+    event_type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    session_id: z.ZodString;
+    element_id: z.ZodString;
+    timestamp: z.ZodString;
+    revision_id: z.ZodString;
+    event_type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, z.ZodTypeAny, "passthrough">>;
+export type TelemetrySpec = z.infer<typeof telemetrySpec>;
+export type TelemetryEnvelope = z.infer<typeof telemetryEnvelopeSpec>;

package/dist/schemas/telemetry.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryEnvelopeSpec = exports.telemetrySpec = void 0;
+const zod_1 = require("zod");
+// ─── telemetrySpec ───────────────────────────────────────────────
+// SPEC.md §2.3/$defs/telemetrySpec: object with emit string array
+exports.telemetrySpec = zod_1.z.object({
+    emit: zod_1.z.array(zod_1.z.string()),
+});
+// ─── TelemetryEnvelope ───────────────────────────────────────────
+// SPEC.md §4.5: All telemetry events MUST share this common envelope.
+// All fields are REQUIRED per the normative schema.
+exports.telemetryEnvelopeSpec = zod_1.z.object({
+    session_id: zod_1.z.string().min(1),
+    element_id: zod_1.z.string().min(1),
+    timestamp: zod_1.z.string(), // ISO 8601 UTC
+    revision_id: zod_1.z.string().min(1),
+    event_type: zod_1.z.string().min(1),
+    payload: zod_1.z.record(zod_1.z.any()),
+}).passthrough(); // additionalProperties: true per §4.5

package/dist/schemas/token.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const dtcgTokenLeaf: z.ZodObject<{
+    $type: z.ZodString;
+    $value: z.ZodAny;
+    $description: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    $type: z.ZodString;
+    $value: z.ZodAny;
+    $description: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    $type: z.ZodString;
+    $value: z.ZodAny;
+    $description: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type DTCGTokenGroup = {
+    [key: string]: DTCGTokenGroup | {
+        $type: string;
+        $value: any;
+        $description?: string;
+    };
+};
+export declare const tokenThemeSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
+export type DTCGTokenLeaf = z.infer<typeof dtcgTokenLeaf>;
+export type TokenTheme = z.infer<typeof tokenThemeSchema>;

package/dist/schemas/token.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenThemeSchema = exports.dtcgTokenLeaf = void 0;
+const zod_1 = require("zod");
+// ─── DTCG Token Format Schema ────────────────────────────────────
+// SPEC.md §2.6: DESEN MUST reuse the Design Tokens Community Group
+// (DTCG) Design Tokens Format Module.
+//
+// A token leaf node has { $type, $value } (required) and
+// optional $description. Non-leaf nodes are groups that contain
+// other token nodes or groups (recursive).
+//
+// Example:
+// {
+//   "color": {
+//     "bg": {
+//       "primary": { "$type": "color", "$value": "#0B5FFF" }
+//     }
+//   }
+// }
+// Leaf token node — the actual design token
+exports.dtcgTokenLeaf = zod_1.z.object({
+    $type: zod_1.z.string().min(1),
+    $value: zod_1.z.any(),
+    $description: zod_1.z.string().optional(),
+}).passthrough();
+// The full token theme is a recursive structure.
+// We use z.record + z.lazy for recursive validation.
+const dtcgTokenNode = zod_1.z.lazy(() => zod_1.z.union([
+    exports.dtcgTokenLeaf,
+    zod_1.z.record(dtcgTokenNode),
+]));
+// ─── TokenThemeSchema ────────────────────────────────────────────
+// Top-level theme file: a record of token groups
+// e.g. { "color": { "bg": { "primary": { "$type": "color", "$value": "#0B5FFF" } } } }
+exports.tokenThemeSchema = zod_1.z.record(dtcgTokenNode);

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "desen-core",
+  "version": "1.0.0-draft",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+// ─── desen-core ─────────────────────────────────────────────────
+// DESEN Protocol Validation Engine
+// Pure TypeScript + Zod — Zero UI dependencies
+//
+// All schemas and types adhere to SPEC.md v1.0.0-RC
+
+// ── Binding & Modifiers (§2.7, §2.11) ──
+export {
+    bindingSourceEnum,
+    bindingSpec,
+    bindWrapper,
+    modifiersSpec,
+} from "./schemas/binding";
+export type {
+    BindingSource,
+    BindingSpec,
+    BindWrapper,
+    ModifiersSpec,
+} from "./schemas/binding";
+
+// ── Telemetry (§2.3, §4.5) ──
+export {
+    telemetrySpec,
+    telemetryEnvelopeSpec,
+} from "./schemas/telemetry";
+export type {
+    TelemetrySpec,
+    TelemetryEnvelope,
+} from "./schemas/telemetry";
+
+// ── Actions (§2.4) ──
+export { actionSpec } from "./schemas/action";
+export type { ActionSpec } from "./schemas/action";
+
+// ── Style & Tokens (§2.6) ──
+export { styleSpec } from "./schemas/style";
+export type { StyleSpec } from "./schemas/style";
+export { dtcgTokenLeaf, tokenThemeSchema } from "./schemas/token";
+export type { DTCGTokenLeaf, DTCGTokenGroup, TokenTheme } from "./schemas/token";
+
+// ── Element (§2.2) ──
+export { elementSpec } from "./schemas/element";
+export type { ElementSpec } from "./schemas/element";
+
+// ── Composition, Layout, Repeater, Node (§2.3, §2.5, §3.5) ──
+export {
+    positioningSpec,
+    layoutSpec,
+    nodeSpec,
+    compositionSpec,
+    repeaterSpec,
+} from "./schemas/composition";
+export type {
+    PositioningSpec,
+    LayoutSpec,
+    NodeSpec,
+    CompositionSpec,
+    RepeaterSpec,
+} from "./schemas/composition";
+
+// ── Surface (§2.8) ──
+export { surfaceSpec } from "./schemas/surface";
+export type { SurfaceSpec } from "./schemas/surface";

package/src/schemas/action.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+// ─── ActionSpec ──────────────────────────────────────────────────
+// SPEC.md §2.4: Standardized behavior primitives.
+// kind is REQUIRED; target, params, actions are optional.
+// "sequence" kind uses recursive `actions` array.
+export const actionSpec: z.ZodType<any> = z.lazy(() =>
+    z.object({
+        kind: z.enum(["navigate", "mutate", "trigger_event", "sequence"]),
+        target: z.string().optional(),
+        params: z.record(z.any()).optional(),
+        actions: z.array(actionSpec).optional(),
+    }).passthrough()
+);
+
+// ─── Types ───────────────────────────────────────────────────────
+export type ActionSpec = z.infer<typeof actionSpec>;

package/src/schemas/binding.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+// ─── Binding Sources ─────────────────────────────────────────────
+// SPEC.md §2.7: source MUST be an implementation-defined identifier
+// for a trusted data source. Runtimes MUST maintain a fixed allowlist.
+export const bindingSourceEnum = z.enum([
+    "session",
+    "backend",
+    "local",
+    "feature_flag",
+]);
+
+// ─── bindingSpec ─────────────────────────────────────────────────
+// SPEC.md §2.7: { source, path } required; fallback optional
+export const bindingSpec = z.object({
+    source: bindingSourceEnum,
+    path: z.string().min(1),
+    fallback: z.any().optional(),
+});
+
+// ─── Bind Wrapper ────────────────────────────────────────────────
+// Standard wrapper: { bind: bindingSpec }
+export const bindWrapper = z.object({
+    bind: bindingSpec,
+});
+
+// ─── modifiersSpec ───────────────────────────────────────────────
+// SPEC.md §2.11: visible can be a boolean or a bind reference.
+// If binding fails and no fallback is present, default is false (fail-closed).
+export const modifiersSpec = z.object({
+    visible: z.union([z.boolean(), bindWrapper]).optional(),
+});
+
+// ─── Types ───────────────────────────────────────────────────────
+export type BindingSource = z.infer<typeof bindingSourceEnum>;
+export type BindingSpec = z.infer<typeof bindingSpec>;
+export type BindWrapper = z.infer<typeof bindWrapper>;
+export type ModifiersSpec = z.infer<typeof modifiersSpec>;