@ultrst-armada/floks 1.0.1 → 1.1.0

package/index.d.ts

@@ -1,2 +1,3 @@
 export * from './packages/ui/dist/index.d.ts';
 export * from './packages/canvas-ui/dist/index.d.ts';
+export * from './packages/contracts/dist/index.d.ts';

package/index.js

@@ -1,2 +1,3 @@
 export * from './packages/ui/dist/index.js';
 export * from './packages/canvas-ui/dist/index.js';
+export * from './packages/contracts/dist/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultrst-armada/floks",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -37,6 +37,11 @@
       "types": "./packages/canvas-ui/dist/index.d.ts",
       "import": "./packages/canvas-ui/dist/index.js",
       "default": "./packages/canvas-ui/dist/index.js"
+    },
+    "./contracts": {
+      "types": "./packages/contracts/dist/index.d.ts",
+      "import": "./packages/contracts/dist/index.js",
+      "default": "./packages/contracts/dist/index.js"
     }
   },
   "scripts": {

package/packages/contracts/dist/index.d.ts

@@ -0,0 +1,394 @@
+import { z } from 'zod';
+
+/**
+ * @file schemas.ts
+ * @description Zod Schemas for Floks Component Theme Contracts & ThemePacks.
+ * Enforces docs/04_THETA_COMPONENT_CONTRACTS.md:
+ * - ComponentThemeContract
+ * - VisualSlot
+ * - VisualState
+ * - VisualParameter
+ * - ThemeTarget
+ * - ThemePack
+ */
+
+declare const VisualSlotSchema: z.ZodObject<{
+    id: z.ZodString;
+    acceptedElementTypes: z.ZodArray<z.ZodString, "many">;
+    required: z.ZodDefault<z.ZodBoolean>;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id?: string;
+    acceptedElementTypes?: string[];
+    required?: boolean;
+    constraints?: Record<string, unknown>;
+}, {
+    id?: string;
+    acceptedElementTypes?: string[];
+    required?: boolean;
+    constraints?: Record<string, unknown>;
+}>;
+type VisualSlot = z.infer<typeof VisualSlotSchema>;
+declare const VisualParameterSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["color", "dimension", "number", "string", "boolean", "gradient", "shadow"]>;
+    default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id?: string;
+    type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+    constraints?: Record<string, unknown>;
+    default?: string | number | boolean;
+}, {
+    id?: string;
+    type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+    constraints?: Record<string, unknown>;
+    default?: string | number | boolean;
+}>;
+type VisualParameter = z.infer<typeof VisualParameterSchema>;
+declare const VisualStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    parameters: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["color", "dimension", "number", "string", "boolean", "gradient", "shadow"]>;
+        default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }, {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }>, "many">;
+    transitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    id?: string;
+    parameters?: {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }[];
+    transitions?: Record<string, string>;
+}, {
+    id?: string;
+    parameters?: {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }[];
+    transitions?: Record<string, string>;
+}>;
+type VisualState = z.infer<typeof VisualStateSchema>;
+declare const ThemeTargetSchema: z.ZodObject<{
+    library: z.ZodLiteral<"@ultrst-armada/floks">;
+    componentId: z.ZodString;
+    componentVersion: z.ZodString;
+    contractVersion: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    library?: "@ultrst-armada/floks";
+    componentId?: string;
+    componentVersion?: string;
+    contractVersion?: string;
+}, {
+    library?: "@ultrst-armada/floks";
+    componentId?: string;
+    componentVersion?: string;
+    contractVersion?: string;
+}>;
+type ThemeTarget = z.infer<typeof ThemeTargetSchema>;
+declare const ComponentThemeContractSchema: z.ZodObject<{
+    componentId: z.ZodString;
+    componentVersion: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    slots: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        acceptedElementTypes: z.ZodArray<z.ZodString, "many">;
+        required: z.ZodDefault<z.ZodBoolean>;
+        constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string;
+        acceptedElementTypes?: string[];
+        required?: boolean;
+        constraints?: Record<string, unknown>;
+    }, {
+        id?: string;
+        acceptedElementTypes?: string[];
+        required?: boolean;
+        constraints?: Record<string, unknown>;
+    }>, "many">;
+    states: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parameters: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodEnum<["color", "dimension", "number", "string", "boolean", "gradient", "shadow"]>;
+            default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+            constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            id?: string;
+            type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+            constraints?: Record<string, unknown>;
+            default?: string | number | boolean;
+        }, {
+            id?: string;
+            type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+            constraints?: Record<string, unknown>;
+            default?: string | number | boolean;
+        }>, "many">;
+        transitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string;
+        parameters?: {
+            id?: string;
+            type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+            constraints?: Record<string, unknown>;
+            default?: string | number | boolean;
+        }[];
+        transitions?: Record<string, string>;
+    }, {
+        id?: string;
+        parameters?: {
+            id?: string;
+            type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+            constraints?: Record<string, unknown>;
+            default?: string | number | boolean;
+        }[];
+        transitions?: Record<string, string>;
+    }>, "many">;
+    parameters: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["color", "dimension", "number", "string", "boolean", "gradient", "shadow"]>;
+        default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }, {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }>, "many">;
+    assets: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    parameters?: {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }[];
+    componentId?: string;
+    componentVersion?: string;
+    displayName?: string;
+    slots?: {
+        id?: string;
+        acceptedElementTypes?: string[];
+        required?: boolean;
+        constraints?: Record<string, unknown>;
+    }[];
+    states?: {
+        id?: string;
+        parameters?: {
+            id?: string;
+            type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+            constraints?: Record<string, unknown>;
+            default?: string | number | boolean;
+        }[];
+        transitions?: Record<string, string>;
+    }[];
+    assets?: string[];
+}, {
+    parameters?: {
+        id?: string;
+        type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+        constraints?: Record<string, unknown>;
+        default?: string | number | boolean;
+    }[];
+    componentId?: string;
+    componentVersion?: string;
+    displayName?: string;
+    slots?: {
+        id?: string;
+        acceptedElementTypes?: string[];
+        required?: boolean;
+        constraints?: Record<string, unknown>;
+    }[];
+    states?: {
+        id?: string;
+        parameters?: {
+            id?: string;
+            type?: "string" | "number" | "boolean" | "color" | "dimension" | "gradient" | "shadow";
+            constraints?: Record<string, unknown>;
+            default?: string | number | boolean;
+        }[];
+        transitions?: Record<string, string>;
+    }[];
+    assets?: string[];
+}>;
+type ComponentThemeContract = z.infer<typeof ComponentThemeContractSchema>;
+declare const ThemePackSlotBindingSchema: z.ZodObject<{
+    slotId: z.ZodString;
+    elementType: z.ZodString;
+    assetRef: z.ZodOptional<z.ZodString>;
+    styles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    slotId?: string;
+    elementType?: string;
+    assetRef?: string;
+    styles?: Record<string, string>;
+}, {
+    slotId?: string;
+    elementType?: string;
+    assetRef?: string;
+    styles?: Record<string, string>;
+}>;
+type ThemePackSlotBinding = z.infer<typeof ThemePackSlotBindingSchema>;
+declare const ThemePackStateMappingSchema: z.ZodObject<{
+    stateId: z.ZodString;
+    parameterOverrides: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, "strip", z.ZodTypeAny, {
+    stateId?: string;
+    parameterOverrides?: Record<string, string | number | boolean>;
+}, {
+    stateId?: string;
+    parameterOverrides?: Record<string, string | number | boolean>;
+}>;
+type ThemePackStateMapping = z.infer<typeof ThemePackStateMappingSchema>;
+declare const ThemePackSchema: z.ZodObject<{
+    themeId: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    target: z.ZodObject<{
+        library: z.ZodLiteral<"@ultrst-armada/floks">;
+        componentId: z.ZodString;
+        componentVersion: z.ZodString;
+        contractVersion: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        library?: "@ultrst-armada/floks";
+        componentId?: string;
+        componentVersion?: string;
+        contractVersion?: string;
+    }, {
+        library?: "@ultrst-armada/floks";
+        componentId?: string;
+        componentVersion?: string;
+        contractVersion?: string;
+    }>;
+    slots: z.ZodArray<z.ZodObject<{
+        slotId: z.ZodString;
+        elementType: z.ZodString;
+        assetRef: z.ZodOptional<z.ZodString>;
+        styles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        slotId?: string;
+        elementType?: string;
+        assetRef?: string;
+        styles?: Record<string, string>;
+    }, {
+        slotId?: string;
+        elementType?: string;
+        assetRef?: string;
+        styles?: Record<string, string>;
+    }>, "many">;
+    states: z.ZodArray<z.ZodObject<{
+        stateId: z.ZodString;
+        parameterOverrides: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, "strip", z.ZodTypeAny, {
+        stateId?: string;
+        parameterOverrides?: Record<string, string | number | boolean>;
+    }, {
+        stateId?: string;
+        parameterOverrides?: Record<string, string | number | boolean>;
+    }>, "many">;
+    parameters: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    assetTypes: z.ZodArray<z.ZodString, "many">;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    parameters?: Record<string, string | number | boolean>;
+    slots?: {
+        slotId?: string;
+        elementType?: string;
+        assetRef?: string;
+        styles?: Record<string, string>;
+    }[];
+    states?: {
+        stateId?: string;
+        parameterOverrides?: Record<string, string | number | boolean>;
+    }[];
+    themeId?: string;
+    name?: string;
+    version?: string;
+    target?: {
+        library?: "@ultrst-armada/floks";
+        componentId?: string;
+        componentVersion?: string;
+        contractVersion?: string;
+    };
+    assetTypes?: string[];
+    metadata?: Record<string, unknown>;
+}, {
+    parameters?: Record<string, string | number | boolean>;
+    slots?: {
+        slotId?: string;
+        elementType?: string;
+        assetRef?: string;
+        styles?: Record<string, string>;
+    }[];
+    states?: {
+        stateId?: string;
+        parameterOverrides?: Record<string, string | number | boolean>;
+    }[];
+    themeId?: string;
+    name?: string;
+    version?: string;
+    target?: {
+        library?: "@ultrst-armada/floks";
+        componentId?: string;
+        componentVersion?: string;
+        contractVersion?: string;
+    };
+    assetTypes?: string[];
+    metadata?: Record<string, unknown>;
+}>;
+type ThemePack = z.infer<typeof ThemePackSchema>;
+
+/**
+ * @file registry.ts
+ * @description Canonical Floks Component Theme Contract Registry.
+ * Supplies explicit visual contracts for Button, Panel, SliderInput, Badge, Socket2D, Wire2D, Node2DBase.
+ */
+
+declare const FLOKS_COMPONENT_REGISTRY: Record<string, ComponentThemeContract>;
+declare function getComponentContract(componentId: string): ComponentThemeContract | undefined;
+declare function listComponentContracts(): ComponentThemeContract[];
+
+/**
+ * @file validator.ts
+ * @description Deterministic ThemePack compatibility validator.
+ * Enforces docs/04_THETA_COMPONENT_CONTRACTS.md:
+ * Validate(theme, component)
+ * <=>
+ *   Target(theme) = component
+ *   ^ theme.slots ⊆ component.slots
+ *   ^ theme.states ⊆ component.states
+ *   ^ theme.parameters ⊆ component.parameters
+ *   ^ theme.assetTypes ⊆ component.acceptedAssetTypes
+ */
+
+interface ThemeValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    targetComponentId: string;
+}
+declare function validateThemePackAgainstContract(themePack: ThemePack, contract?: ComponentThemeContract): ThemeValidationResult;
+declare function loadThemePack(raw: unknown): ThemePack;
+
+export { type ComponentThemeContract, ComponentThemeContractSchema, FLOKS_COMPONENT_REGISTRY, type ThemePack, ThemePackSchema, type ThemePackSlotBinding, ThemePackSlotBindingSchema, type ThemePackStateMapping, ThemePackStateMappingSchema, type ThemeTarget, ThemeTargetSchema, type ThemeValidationResult, type VisualParameter, VisualParameterSchema, type VisualSlot, VisualSlotSchema, type VisualState, VisualStateSchema, getComponentContract, listComponentContracts, loadThemePack, validateThemePackAgainstContract };

package/packages/contracts/dist/index.js

@@ -0,0 +1,324 @@
+// src/schemas.ts
+import { z } from "zod";
+var VisualSlotSchema = z.object({
+  id: z.string(),
+  acceptedElementTypes: z.array(z.string()),
+  required: z.boolean().default(false),
+  constraints: z.record(z.unknown()).optional()
+});
+var VisualParameterSchema = z.object({
+  id: z.string(),
+  type: z.enum(["color", "dimension", "number", "string", "boolean", "gradient", "shadow"]),
+  default: z.union([z.string(), z.number(), z.boolean()]),
+  constraints: z.record(z.unknown()).optional()
+});
+var VisualStateSchema = z.object({
+  id: z.string(),
+  parameters: z.array(VisualParameterSchema),
+  transitions: z.record(z.string()).optional()
+});
+var ThemeTargetSchema = z.object({
+  library: z.literal("@ultrst-armada/floks"),
+  componentId: z.string(),
+  componentVersion: z.string(),
+  contractVersion: z.string().default("1.0.0")
+});
+var ComponentThemeContractSchema = z.object({
+  componentId: z.string(),
+  componentVersion: z.string(),
+  displayName: z.string().optional(),
+  slots: z.array(VisualSlotSchema),
+  states: z.array(VisualStateSchema),
+  parameters: z.array(VisualParameterSchema),
+  assets: z.array(z.string())
+});
+var ThemePackSlotBindingSchema = z.object({
+  slotId: z.string(),
+  elementType: z.string(),
+  assetRef: z.string().optional(),
+  styles: z.record(z.string()).optional()
+});
+var ThemePackStateMappingSchema = z.object({
+  stateId: z.string(),
+  parameterOverrides: z.record(z.union([z.string(), z.number(), z.boolean()]))
+});
+var ThemePackSchema = z.object({
+  themeId: z.string(),
+  name: z.string(),
+  version: z.string(),
+  target: ThemeTargetSchema,
+  slots: z.array(ThemePackSlotBindingSchema),
+  states: z.array(ThemePackStateMappingSchema),
+  parameters: z.record(z.union([z.string(), z.number(), z.boolean()])),
+  assetTypes: z.array(z.string()),
+  metadata: z.record(z.unknown()).optional()
+});
+
+// src/registry.ts
+var FLOKS_COMPONENT_REGISTRY = {
+  // 1. Button Parent
+  "floks.button": ComponentThemeContractSchema.parse({
+    componentId: "floks.button",
+    componentVersion: "1.0.0",
+    displayName: "Button Component",
+    slots: [
+      { id: "container", acceptedElementTypes: ["shape", "frame", "mesh"], required: true },
+      { id: "icon", acceptedElementTypes: ["icon", "svg", "glyph"], required: false },
+      { id: "label", acceptedElementTypes: ["text", "typography"], required: true },
+      { id: "indicator", acceptedElementTypes: ["badge", "dot", "counter"], required: false }
+    ],
+    states: [
+      { id: "idle", parameters: [] },
+      { id: "hover", parameters: [] },
+      { id: "active", parameters: [] },
+      { id: "disabled", parameters: [] },
+      { id: "focus", parameters: [] }
+    ],
+    parameters: [
+      { id: "background", type: "color", default: "var(--skipo-surface-2)" },
+      { id: "textColor", type: "color", default: "var(--skipo-text-primary)" },
+      { id: "borderColor", type: "color", default: "var(--skipo-border)" },
+      { id: "borderWidth", type: "dimension", default: "1px" },
+      { id: "borderRadius", type: "dimension", default: "6px" },
+      { id: "padding", type: "dimension", default: "8px 16px" },
+      { id: "fontSize", type: "dimension", default: "13px" }
+    ],
+    assets: ["svg", "bitmap"]
+  }),
+  // 2. Panel Parent
+  "floks.panel": ComponentThemeContractSchema.parse({
+    componentId: "floks.panel",
+    componentVersion: "1.0.0",
+    displayName: "Panel Component",
+    slots: [
+      { id: "header", acceptedElementTypes: ["frame", "strip"], required: false },
+      { id: "content", acceptedElementTypes: ["container", "layout"], required: true },
+      { id: "footer", acceptedElementTypes: ["strip", "action-bar"], required: false },
+      { id: "border-frame", acceptedElementTypes: ["frame", "shape"], required: false }
+    ],
+    states: [
+      { id: "default", parameters: [] },
+      { id: "expanded", parameters: [] },
+      { id: "collapsed", parameters: [] },
+      { id: "minimized", parameters: [] }
+    ],
+    parameters: [
+      { id: "background", type: "color", default: "var(--skipo-surface-1)" },
+      { id: "borderColor", type: "color", default: "var(--skipo-border)" },
+      { id: "borderRadius", type: "dimension", default: "8px" },
+      { id: "elevation", type: "shadow", default: "0 4px 12px rgba(0,0,0,0.4)" },
+      { id: "padding", type: "dimension", default: "12px" }
+    ],
+    assets: ["svg", "bitmap", "shader"]
+  }),
+  // 3. Slider Input
+  "floks.input.slider": ComponentThemeContractSchema.parse({
+    componentId: "floks.input.slider",
+    componentVersion: "1.0.0",
+    displayName: "Slider Input Component",
+    slots: [
+      { id: "track", acceptedElementTypes: ["bar", "curve"], required: true },
+      { id: "fill", acceptedElementTypes: ["bar", "gradient"], required: true },
+      { id: "thumb", acceptedElementTypes: ["handle", "circle", "icon"], required: true },
+      { id: "value-label", acceptedElementTypes: ["text", "bubble"], required: false }
+    ],
+    states: [
+      { id: "idle", parameters: [] },
+      { id: "hover", parameters: [] },
+      { id: "dragging", parameters: [] },
+      { id: "disabled", parameters: [] }
+    ],
+    parameters: [
+      { id: "trackColor", type: "color", default: "var(--skipo-surface-3)" },
+      { id: "fillColor", type: "color", default: "var(--skipo-accent)" },
+      { id: "thumbColor", type: "color", default: "var(--skipo-surface-1)" },
+      { id: "thumbSize", type: "dimension", default: "14px" },
+      { id: "height", type: "dimension", default: "6px" }
+    ],
+    assets: ["svg", "bitmap"]
+  }),
+  // 4. Badge
+  "floks.badge": ComponentThemeContractSchema.parse({
+    componentId: "floks.badge",
+    componentVersion: "1.0.0",
+    displayName: "Badge Component",
+    slots: [
+      { id: "pill", acceptedElementTypes: ["shape", "pill"], required: true },
+      { id: "indicator-dot", acceptedElementTypes: ["dot", "icon"], required: false },
+      { id: "text", acceptedElementTypes: ["typography"], required: true }
+    ],
+    states: [
+      { id: "default", parameters: [] },
+      { id: "pulse", parameters: [] }
+    ],
+    parameters: [
+      { id: "background", type: "color", default: "var(--skipo-surface-2)" },
+      { id: "textColor", type: "color", default: "var(--skipo-text-secondary)" },
+      { id: "dotColor", type: "color", default: "var(--skipo-accent)" }
+    ],
+    assets: ["svg"]
+  }),
+  // 5. 2D Graph Socket
+  "floks.socket2d": ComponentThemeContractSchema.parse({
+    componentId: "floks.socket2d",
+    componentVersion: "1.0.0",
+    displayName: "2D Graph Socket",
+    slots: [
+      { id: "ring", acceptedElementTypes: ["circle", "ring"], required: true },
+      { id: "indicator-dot", acceptedElementTypes: ["circle", "dot"], required: false },
+      { id: "glow", acceptedElementTypes: ["radial-glow"], required: false }
+    ],
+    states: [
+      { id: "idle", parameters: [] },
+      { id: "hover", parameters: [] },
+      { id: "connected", parameters: [] },
+      { id: "compatible-hover", parameters: [] }
+    ],
+    parameters: [
+      { id: "color", type: "color", default: "#ffaa00" },
+      { id: "radius", type: "dimension", default: "6px" },
+      { id: "glowRadius", type: "dimension", default: "12px" }
+    ],
+    assets: ["svg"]
+  }),
+  // 6. 2D Graph Wire
+  "floks.wire2d": ComponentThemeContractSchema.parse({
+    componentId: "floks.wire2d",
+    componentVersion: "1.0.0",
+    displayName: "2D Graph Wire",
+    slots: [
+      { id: "trace", acceptedElementTypes: ["path", "spline"], required: true },
+      { id: "pulse-particle", acceptedElementTypes: ["particle", "pulse"], required: false },
+      { id: "endpoint", acceptedElementTypes: ["handle", "arrow"], required: false }
+    ],
+    states: [
+      { id: "idle", parameters: [] },
+      { id: "active", parameters: [] },
+      { id: "selected", parameters: [] },
+      { id: "error", parameters: [] }
+    ],
+    parameters: [
+      { id: "strokeColor", type: "color", default: "#00ffff" },
+      { id: "strokeWidth", type: "dimension", default: "2px" },
+      { id: "opacity", type: "number", default: 1 }
+    ],
+    assets: ["svg", "particle"]
+  }),
+  // 7. 2D Node Base
+  "floks.node2d": ComponentThemeContractSchema.parse({
+    componentId: "floks.node2d",
+    componentVersion: "1.0.0",
+    displayName: "2D Graph Node Card",
+    slots: [
+      { id: "header", acceptedElementTypes: ["strip", "banner"], required: true },
+      { id: "body", acceptedElementTypes: ["container", "surface"], required: true },
+      { id: "footer", acceptedElementTypes: ["strip"], required: false },
+      { id: "socket-strip", acceptedElementTypes: ["column", "row"], required: true }
+    ],
+    states: [
+      { id: "idle", parameters: [] },
+      { id: "selected", parameters: [] },
+      { id: "running", parameters: [] },
+      { id: "bypassed", parameters: [] },
+      { id: "minimized", parameters: [] }
+    ],
+    parameters: [
+      { id: "headerColor", type: "color", default: "var(--skipo-surface-2)" },
+      { id: "bodyColor", type: "color", default: "var(--skipo-surface-1)" },
+      { id: "borderColor", type: "color", default: "var(--skipo-border)" },
+      { id: "cornerRadius", type: "dimension", default: "8px" }
+    ],
+    assets: ["svg", "bitmap"]
+  })
+};
+function getComponentContract(componentId) {
+  return FLOKS_COMPONENT_REGISTRY[componentId];
+}
+function listComponentContracts() {
+  return Object.values(FLOKS_COMPONENT_REGISTRY);
+}
+
+// src/validator.ts
+function validateThemePackAgainstContract(themePack, contract) {
+  const errors = [];
+  const warnings = [];
+  const targetCompId = themePack.target.componentId;
+  const targetContract = contract ?? FLOKS_COMPONENT_REGISTRY[targetCompId];
+  if (!targetContract) {
+    return {
+      valid: false,
+      errors: [`Target component '${targetCompId}' is not registered in Floks ComponentThemeContract registry.`],
+      warnings: [],
+      targetComponentId: targetCompId
+    };
+  }
+  if (themePack.target.library !== "@ultrst-armada/floks") {
+    errors.push(`Invalid target library '${themePack.target.library}'. Must be '@ultrst-armada/floks'.`);
+  }
+  const allowedSlotIds = new Set(targetContract.slots.map((s) => s.id));
+  for (const s of themePack.slots) {
+    if (!allowedSlotIds.has(s.slotId)) {
+      errors.push(`Slot '${s.slotId}' is not defined in contract for '${targetCompId}'.`);
+    } else {
+      const slotDef = targetContract.slots.find((slot) => slot.id === s.slotId);
+      if (slotDef && !slotDef.acceptedElementTypes.includes(s.elementType)) {
+        errors.push(
+          `Slot '${s.slotId}' rejects element type '${s.elementType}'. Accepted types: [${slotDef.acceptedElementTypes.join(", ")}]`
+        );
+      }
+    }
+  }
+  const presentSlotIds = new Set(themePack.slots.map((s) => s.slotId));
+  for (const requiredSlot of targetContract.slots.filter((s) => s.required)) {
+    if (!presentSlotIds.has(requiredSlot.id)) {
+      warnings.push(`Required slot '${requiredSlot.id}' is not explicitly bound in theme.`);
+    }
+  }
+  const allowedStateIds = new Set(targetContract.states.map((st) => st.id));
+  for (const st of themePack.states) {
+    if (!allowedStateIds.has(st.stateId)) {
+      errors.push(`State '${st.stateId}' is not recognized by contract for '${targetCompId}'.`);
+    }
+  }
+  const allowedParamIds = new Set(targetContract.parameters.map((p) => p.id));
+  for (const paramKey of Object.keys(themePack.parameters)) {
+    if (!allowedParamIds.has(paramKey)) {
+      warnings.push(`Unknown visual parameter '${paramKey}' ignored by '${targetCompId}'.`);
+    }
+  }
+  const allowedAssets = new Set(targetContract.assets);
+  for (const asset of themePack.assetTypes) {
+    if (!allowedAssets.has(asset)) {
+      errors.push(`Asset type '${asset}' is not accepted by '${targetCompId}'. Allowed: [${targetContract.assets.join(", ")}]`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    targetComponentId: targetCompId
+  };
+}
+function loadThemePack(raw) {
+  const parsed = ThemePackSchema.parse(raw);
+  const result = validateThemePackAgainstContract(parsed);
+  if (!result.valid) {
+    throw new Error(`Invalid Floks ThemePack: ${result.errors.join("; ")}`);
+  }
+  return parsed;
+}
+export {
+  ComponentThemeContractSchema,
+  FLOKS_COMPONENT_REGISTRY,
+  ThemePackSchema,
+  ThemePackSlotBindingSchema,
+  ThemePackStateMappingSchema,
+  ThemeTargetSchema,
+  VisualParameterSchema,
+  VisualSlotSchema,
+  VisualStateSchema,
+  getComponentContract,
+  listComponentContracts,
+  loadThemePack,
+  validateThemePackAgainstContract
+};

package/packages/contracts/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@floks/contracts",
+  "version": "1.0.0",
+  "description": "Floks Canonical Component Theme Contracts, Visual Slots, States, Parameters, and Compatibility Validation for Theta Engine",
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "skipoManifest": "./floks.manifest.json",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external zod",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  }
+}

package/packages/ui/dist/index.js

@@ -1,9 +1,3 @@
-import {
-  AppShell,
-  BreadcrumbNav,
-  HeaderBar,
-  TopToolbar
-} from "./chunk-GWW3BGOB.js";
 import {
   DEFAULT_PANEL_GEOMETRY,
   DrawerContainer,
@@ -18,6 +12,12 @@ import {
   usePanelGeometry,
   usePanelInteraction
 } from "./chunk-TXKLROFC.js";
+import {
+  AppShell,
+  BreadcrumbNav,
+  HeaderBar,
+  TopToolbar
+} from "./chunk-GWW3BGOB.js";
 import {
   SettingsTab,
   ThemeSettingsSection
@@ -129,13 +129,6 @@ import {
 import {
   LoginModal
 } from "./chunk-S227WJ5E.js";
-import {
-  BaseSelect,
-  BaseTextarea,
-  BaseToggle,
-  CredentialField,
-  KNOWN_CREDENTIAL_URLS
-} from "./chunk-KIFQA7L6.js";
 import "./chunk-5ZMXFCD4.js";
 import {
   ApiCallIndicator,
@@ -144,6 +137,13 @@ import {
   StatusLight,
   SystemMessageDisplay
 } from "./chunk-C3L53YN4.js";
+import {
+  BaseSelect,
+  BaseTextarea,
+  BaseToggle,
+  CredentialField,
+  KNOWN_CREDENTIAL_URLS
+} from "./chunk-KIFQA7L6.js";
 import {
   ConfirmDialog,
   CopyableErrorAlert,