@ultrst-armada/floks 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultrst-armada/floks",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -44,13 +44,6 @@
       "default": "./packages/contracts/dist/index.js"
     }
   },
-  "scripts": {
-    "build": "pnpm -r run build",
-    "postbuild": "node -e \"import('fs').then(fs => { for (const pkg of fs.readdirSync('packages')) { const d = 'packages/' + pkg + '/dist'; if (!fs.existsSync(d)) continue; for (const f of fs.readdirSync(d, { recursive: true })) { const p = d + '/' + f; if (fs.statSync(p).isFile() && (p.endsWith('.js') || p.endsWith('.d.ts'))) { const c = fs.readFileSync(p, 'utf8'); const n = c.replaceAll('@kloks/', '@ultrst-armada/kloks/').replaceAll('@floks/', '@ultrst-armada/floks/').replaceAll('@ultrst/kloks/', '@ultrst-armada/kloks/').replaceAll('@ultrst/floks/', '@ultrst-armada/floks/').replaceAll('\\\"kloks/', '\\\"@ultrst-armada/kloks/').replaceAll('\\'kloks/', '\\'@ultrst-armada/kloks/').replaceAll('\\\"floks/', '\\\"@ultrst-armada/floks/').replaceAll('\\'floks/', '\\'@ultrst-armada/floks/'); if (c !== n) fs.writeFileSync(p, n); } } } })\"",
-    "test": "vitest run",
-    "typecheck": "pnpm -r run typecheck",
-    "clean": "pnpm -r run clean"
-  },
   "dependencies": {
     "zod": "^3.24.1"
   },
@@ -72,5 +65,11 @@
     "typescript": "^5.7.3",
     "vitest": "^3.1.0"
   },
-  "packageManager": "pnpm@9.15.0"
-}
+  "scripts": {
+    "build": "pnpm -r run build",
+    "postbuild": "node -e \"import('fs').then(fs => { for (const pkg of fs.readdirSync('packages')) { const d = 'packages/' + pkg + '/dist'; if (!fs.existsSync(d)) continue; for (const f of fs.readdirSync(d, { recursive: true })) { const p = d + '/' + f; if (fs.statSync(p).isFile() && (p.endsWith('.js') || p.endsWith('.d.ts'))) { const c = fs.readFileSync(p, 'utf8'); const n = c.replaceAll('@kloks/', '@ultrst-armada/kloks/').replaceAll('@floks/', '@ultrst-armada/floks/').replaceAll('@ultrst/kloks/', '@ultrst-armada/kloks/').replaceAll('@ultrst/floks/', '@ultrst-armada/floks/').replaceAll('\\\"kloks/', '\\\"@ultrst-armada/kloks/').replaceAll('\\'kloks/', '\\'@ultrst-armada/kloks/').replaceAll('\\\"floks/', '\\\"@ultrst-armada/floks/').replaceAll('\\'floks/', '\\'@ultrst-armada/floks/'); if (c !== n) fs.writeFileSync(p, n); } } } })\"",
+    "test": "vitest run",
+    "typecheck": "pnpm -r run typecheck",
+    "clean": "pnpm -r run clean"
+  }
+}

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

@@ -391,4 +391,117 @@ interface ThemeValidationResult {
 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 };
+/**
+ * @file snapshot.ts
+ * @description Floks Contract Snapshot Generator, Diff Engine & Canonical Contract Definition.
+ * Enforces docs/04_THETA_COMPONENT_CONTRACTS.md and IMPLEMENTATION-SPEC.md:
+ *   implementation_only      => PATCH
+ *   additive_compatible       => MINOR
+ *   breaking_contract_change => MAJOR
+ */
+
+declare const FLOKS_PUBLIC_SYMBOLS: string[];
+declare const FloksContractSnapshotSchema: z.ZodObject<{
+    package: z.ZodLiteral<"@ultrst-armada/floks">;
+    version: z.ZodString;
+    timestamp: z.ZodNumber;
+    checksum: z.ZodString;
+    publicSymbols: z.ZodArray<z.ZodString, "many">;
+    components: z.ZodRecord<z.ZodString, z.ZodObject<{
+        componentId: z.ZodString;
+        componentVersion: z.ZodString;
+        slots: z.ZodArray<z.ZodString, "many">;
+        states: z.ZodArray<z.ZodString, "many">;
+        parameters: z.ZodArray<z.ZodString, "many">;
+        assets: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        parameters?: string[];
+        componentId?: string;
+        componentVersion?: string;
+        slots?: string[];
+        states?: string[];
+        assets?: string[];
+    }, {
+        parameters?: string[];
+        componentId?: string;
+        componentVersion?: string;
+        slots?: string[];
+        states?: string[];
+        assets?: string[];
+    }>>;
+    errorCodes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    version?: string;
+    package?: "@ultrst-armada/floks";
+    timestamp?: number;
+    checksum?: string;
+    publicSymbols?: string[];
+    components?: Record<string, {
+        parameters?: string[];
+        componentId?: string;
+        componentVersion?: string;
+        slots?: string[];
+        states?: string[];
+        assets?: string[];
+    }>;
+    errorCodes?: string[];
+}, {
+    version?: string;
+    package?: "@ultrst-armada/floks";
+    timestamp?: number;
+    checksum?: string;
+    publicSymbols?: string[];
+    components?: Record<string, {
+        parameters?: string[];
+        componentId?: string;
+        componentVersion?: string;
+        slots?: string[];
+        states?: string[];
+        assets?: string[];
+    }>;
+    errorCodes?: string[];
+}>;
+type FloksContractSnapshot = z.infer<typeof FloksContractSnapshotSchema>;
+interface ContractDiffResult {
+    versionRecommendation: 'PATCH' | 'MINOR' | 'MAJOR';
+    hasBreakingChanges: boolean;
+    hasAdditiveChanges: boolean;
+    isIdentical: boolean;
+    removedSymbols: string[];
+    addedSymbols: string[];
+    removedComponents: string[];
+    addedComponents: string[];
+    changedComponents: string[];
+    summary: string;
+}
+/**
+ * Generate canonical contract snapshot for Floks.
+ */
+declare function createFloksSnapshot(version?: string, registry?: Record<string, ComponentThemeContract>, publicSymbols?: string[]): FloksContractSnapshot;
+/**
+ * Computes semantic diff between previous and current Floks contract snapshots.
+ */
+declare function diffContractSnapshots(previous: FloksContractSnapshot, current: FloksContractSnapshot): ContractDiffResult;
+declare const FLOKS_CANONICAL_CONTRACT: {
+    package: string;
+    version: string;
+    getSnapshot: () => {
+        version?: string;
+        package?: "@ultrst-armada/floks";
+        timestamp?: number;
+        checksum?: string;
+        publicSymbols?: string[];
+        components?: Record<string, {
+            parameters?: string[];
+            componentId?: string;
+            componentVersion?: string;
+            slots?: string[];
+            states?: string[];
+            assets?: string[];
+        }>;
+        errorCodes?: string[];
+    };
+    validateCompatibility: (themePack: ThemePack) => ThemeValidationResult;
+};
+
+export { type ComponentThemeContract, ComponentThemeContractSchema, type ContractDiffResult, FLOKS_CANONICAL_CONTRACT, FLOKS_COMPONENT_REGISTRY, FLOKS_PUBLIC_SYMBOLS, type FloksContractSnapshot, FloksContractSnapshotSchema, type ThemePack, ThemePackSchema, type ThemePackSlotBinding, ThemePackSlotBindingSchema, type ThemePackStateMapping, ThemePackStateMappingSchema, type ThemeTarget, ThemeTargetSchema, type ThemeValidationResult, type VisualParameter, VisualParameterSchema, type VisualSlot, VisualSlotSchema, type VisualState, VisualStateSchema, createFloksSnapshot, diffContractSnapshots, getComponentContract, listComponentContracts, loadThemePack, validateThemePackAgainstContract };

package/packages/contracts/dist/index.js

@@ -307,9 +307,171 @@ function loadThemePack(raw) {
   }
   return parsed;
 }
+
+// src/snapshot.ts
+import { z as z2 } from "zod";
+var FLOKS_PUBLIC_SYMBOLS = [
+  // UI Layout & Containers
+  "AppShell",
+  "TopToolbar",
+  "BottomStrip",
+  "FloatingDetailsPanel",
+  "SettingsTab",
+  "WorkspaceTilesMenu",
+  "UIParent",
+  "PanelModel",
+  "PanelProps",
+  // UI Base Primitives & Forms
+  "BaseButton",
+  "BaseCard",
+  "BaseInput",
+  "BaseSelect",
+  "BaseToggle",
+  "BaseBadge",
+  "ButtonModel",
+  "ButtonProps",
+  "CredentialField",
+  "LoginModal",
+  "ConfirmDialog",
+  "StatusIndicator",
+  // Canvas 2D
+  "InfiniteCanvas",
+  "DockBar",
+  "TileGrid",
+  "MonacoEditor",
+  // Contracts & Theta
+  "FLOKS_CANONICAL_CONTRACT",
+  "FLOKS_COMPONENT_REGISTRY",
+  "getComponentContract",
+  "listComponentContracts",
+  "validateThemePackAgainstContract",
+  "loadThemePack",
+  "createFloksSnapshot",
+  "diffContractSnapshots",
+  "ComponentThemeContractSchema",
+  "VisualSlotSchema",
+  "VisualStateSchema",
+  "VisualParameterSchema",
+  "ThemeTargetSchema",
+  "ThemePackSchema"
+];
+var FloksContractSnapshotSchema = z2.object({
+  package: z2.literal("@ultrst-armada/floks"),
+  version: z2.string(),
+  timestamp: z2.number(),
+  checksum: z2.string(),
+  publicSymbols: z2.array(z2.string()),
+  components: z2.record(
+    z2.object({
+      componentId: z2.string(),
+      componentVersion: z2.string(),
+      slots: z2.array(z2.string()),
+      states: z2.array(z2.string()),
+      parameters: z2.array(z2.string()),
+      assets: z2.array(z2.string())
+    })
+  ),
+  errorCodes: z2.array(z2.string())
+});
+function createFloksSnapshot(version = "1.1.1", registry = FLOKS_COMPONENT_REGISTRY, publicSymbols = FLOKS_PUBLIC_SYMBOLS) {
+  const sortedSymbols = [...publicSymbols].sort();
+  const components = {};
+  for (const [compId, contract] of Object.entries(registry)) {
+    components[compId] = {
+      componentId: contract.componentId,
+      componentVersion: contract.componentVersion,
+      slots: contract.slots.map((s) => s.id).sort(),
+      states: contract.states.map((s) => s.id).sort(),
+      parameters: contract.parameters.map((p) => p.id).sort(),
+      assets: [...contract.assets].sort()
+    };
+  }
+  const errorCodes = [
+    "ERR_CONTRACT_VIOLATION",
+    "ERR_INTERNAL_IMPORT_FORBIDDEN",
+    "ERR_LOCAL_SHIM_DETECTED",
+    "ERR_THEME_TARGET_MISMATCH",
+    "ERR_SLOT_REJECTED",
+    "ERR_UNRECOGNIZED_STATE"
+  ];
+  const rawJson = JSON.stringify({ sortedSymbols, components });
+  let hash = 0;
+  for (let i = 0; i < rawJson.length; i++) {
+    hash = (hash << 5) - hash + rawJson.charCodeAt(i);
+    hash |= 0;
+  }
+  const checksum = `sha256-${Math.abs(hash).toString(16)}`;
+  const snapshot = {
+    package: "@ultrst-armada/floks",
+    version,
+    timestamp: 176043e7,
+    checksum,
+    publicSymbols: sortedSymbols,
+    components,
+    errorCodes
+  };
+  return FloksContractSnapshotSchema.parse(snapshot);
+}
+function diffContractSnapshots(previous, current) {
+  const prevSymbols = new Set(previous.publicSymbols);
+  const currSymbols = new Set(current.publicSymbols);
+  const removedSymbols = previous.publicSymbols.filter((s) => !currSymbols.has(s));
+  const addedSymbols = current.publicSymbols.filter((s) => !prevSymbols.has(s));
+  const prevCompIds = Object.keys(previous.components);
+  const currCompIds = new Set(Object.keys(current.components));
+  const removedComponents = prevCompIds.filter((id) => !currCompIds.has(id));
+  const addedComponents = Object.keys(current.components).filter((id) => !previous.components[id]);
+  const changedComponents = [];
+  for (const compId of Object.keys(current.components)) {
+    if (previous.components[compId]) {
+      const prevC = previous.components[compId];
+      const currC = current.components[compId];
+      const removedSlots = prevC.slots.filter((s) => !currC.slots.includes(s));
+      const removedStates = prevC.states.filter((s) => !currC.states.includes(s));
+      if (removedSlots.length > 0 || removedStates.length > 0) {
+        changedComponents.push(
+          `${compId} breaking: removed slots [${removedSlots.join(", ")}], removed states [${removedStates.join(", ")}]`
+        );
+      } else if (prevC.slots.length !== currC.slots.length || prevC.states.length !== currC.states.length || prevC.parameters.length !== currC.parameters.length) {
+        changedComponents.push(`${compId} additive extension`);
+      }
+    }
+  }
+  const hasBreakingChanges = removedSymbols.length > 0 || removedComponents.length > 0 || changedComponents.some((c) => c.includes("breaking"));
+  const hasAdditiveChanges = addedSymbols.length > 0 || addedComponents.length > 0 || changedComponents.some((c) => c.includes("additive"));
+  const isIdentical = !hasBreakingChanges && !hasAdditiveChanges;
+  let versionRecommendation = "PATCH";
+  if (hasBreakingChanges) {
+    versionRecommendation = "MAJOR";
+  } else if (hasAdditiveChanges) {
+    versionRecommendation = "MINOR";
+  }
+  const summary = isIdentical ? "Identical public contract surface (PATCH compatible)." : hasBreakingChanges ? `Breaking contract change detected: ${removedSymbols.length} removed symbols, ${removedComponents.length} removed components (MAJOR bump required).` : `Additive compatible changes: ${addedSymbols.length} added symbols, ${addedComponents.length} added components (MINOR bump required).`;
+  return {
+    versionRecommendation,
+    hasBreakingChanges,
+    hasAdditiveChanges,
+    isIdentical,
+    removedSymbols,
+    addedSymbols,
+    removedComponents,
+    addedComponents,
+    changedComponents,
+    summary
+  };
+}
+var FLOKS_CANONICAL_CONTRACT = {
+  package: "@ultrst-armada/floks",
+  version: "1.1.1",
+  getSnapshot: () => createFloksSnapshot("1.1.1"),
+  validateCompatibility: (themePack) => validateThemePackAgainstContract(themePack)
+};
 export {
   ComponentThemeContractSchema,
+  FLOKS_CANONICAL_CONTRACT,
   FLOKS_COMPONENT_REGISTRY,
+  FLOKS_PUBLIC_SYMBOLS,
+  FloksContractSnapshotSchema,
   ThemePackSchema,
   ThemePackSlotBindingSchema,
   ThemePackStateMappingSchema,
@@ -317,6 +479,8 @@ export {
   VisualParameterSchema,
   VisualSlotSchema,
   VisualStateSchema,
+  createFloksSnapshot,
+  diffContractSnapshots,
   getComponentContract,
   listComponentContracts,
   loadThemePack,

package/packages/contracts/floks.manifest.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://skipo.dev/schemas/floks-manifest.v1.json",
+  "package": "@floks/contracts",
+  "version": "1.0.0",
+  "components": [
+    {
+      "id": "canonical-component-contracts",
+      "name": "Canonical Component Contracts & Snapshot Engine",
+      "export": "FLOKS_CANONICAL_CONTRACT",
+      "subpath": "contracts",
+      "targetTypes": ["App.contracts", "App.governance"]
+    }
+  ]
+}

package/packages/ui/dist/hierarchy/index.d.ts

@@ -1,7 +1,7 @@
 import React__default from 'react';
-import { GraphEntityParent } from '@ultrst-armada/kloks/state-graph';
+import { GraphEntityParent, GraphEntityMetadata } from '@ultrst-armada/kloks/state-graph';
+export { GraphEntityMetadata } from '@ultrst-armada/kloks/state-graph';
 
-type GraphEntityMetadata = Record<string, any>;
 interface UIInteractionState {
     isHovered?: boolean;
     isActive?: boolean;
@@ -230,4 +230,4 @@ declare class BadgeModel extends UIElementBase {
 }
 type BadgeTone = 'primary' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
 
-export { ActionButton, Badge, BadgeModel, type BadgeProps, type BadgeTone, ButtonModel, ButtonParent, type ButtonParentProps, type ButtonProps, type ButtonSize, type ButtonVariant, CardPanel, CategoryCardTile, ChannelStripTile, ClipCardTile, type ColorPalette, DangerButton, GhostButton, type GraphEntityMetadata, IconButton, InputModel, InspectorPanel, ModalPanel, PanelModel, PanelParent, type PanelParentProps, type PanelProps, type PanelVariant, SelectInput, type SelectInputProps, SliderInput, type SliderInputProps, SpawnOptionTile, StatusDot, type StatusDotProps, TelemetryPill, type TelemetryPillProps, TextInput, type TextInputProps, TileModel, TileParent, type TileParentProps, type TileVariant, ToggleButton, ToggleInput, type ToggleInputProps, ToolbarPanel, type TooltipDirection, type UIBaseProps, UIElementBase, type UIInteractionState, UIModel, UIParent, type UIParentProps, type UIProps, type UIRole, type UISize, type UIStyleTokens, type UIVariant, registerPaletteResolver };
+export { ActionButton, Badge, BadgeModel, type BadgeProps, type BadgeTone, ButtonModel, ButtonParent, type ButtonParentProps, type ButtonProps, type ButtonSize, type ButtonVariant, CardPanel, CategoryCardTile, ChannelStripTile, ClipCardTile, type ColorPalette, DangerButton, GhostButton, IconButton, InputModel, InspectorPanel, ModalPanel, PanelModel, PanelParent, type PanelParentProps, type PanelProps, type PanelVariant, SelectInput, type SelectInputProps, SliderInput, type SliderInputProps, SpawnOptionTile, StatusDot, type StatusDotProps, TelemetryPill, type TelemetryPillProps, TextInput, type TextInputProps, TileModel, TileParent, type TileParentProps, type TileVariant, ToggleButton, ToggleInput, type ToggleInputProps, ToolbarPanel, type TooltipDirection, type UIBaseProps, UIElementBase, type UIInteractionState, UIModel, UIParent, type UIParentProps, type UIProps, type UIRole, type UISize, type UIStyleTokens, type UIVariant, registerPaletteResolver };

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

@@ -10,7 +10,7 @@ export { SettingsTab, SettingsTabProps, ThemeSettingsSection } from './component
 export { LoginModal, LoginModalProps } from './components/auth/index.js';
 export { SrklBackblazeAccount, SrklBackblazeTile, StorageOptionTiles, StoragePresetTile, StorageSelection, WorkspaceRecord, WorkspaceSecondaryClone, WorkspaceSecondaryClonesPanel, WorkspaceStorageReadonlyPanel, WorkspaceTilesMenu, WorkspaceTilesMenuProps } from './components/workspace/index.js';
 export { DEFAULT_PALETTE_ID, THEME_STORAGE_KEY, ThemeContextValue, ThemeProvider, ThemeProviderProps, applyPaletteToDocument, getActivePalette, paletteToSkipoThemePack, subscribeToPalette, usePalette, useTheme } from './palette/index.js';
-export { ActionButton, Badge, BadgeModel, BadgeProps, BadgeTone, ButtonModel, ButtonParent, ButtonParentProps, ButtonProps, ButtonSize, ButtonVariant, CardPanel, CategoryCardTile, ChannelStripTile, ClipCardTile, DangerButton, GhostButton, GraphEntityMetadata, IconButton, InputModel, InspectorPanel, ModalPanel, PanelModel, PanelParent, PanelParentProps, PanelProps, PanelVariant, SelectInput, SelectInputProps, SliderInput, SliderInputProps, SpawnOptionTile, StatusDot, StatusDotProps, TelemetryPill, TelemetryPillProps, TextInput, TextInputProps, TileModel, TileParent, TileParentProps, TileVariant, ToggleButton, ToggleInput, ToggleInputProps, ToolbarPanel, TooltipDirection, UIBaseProps, UIElementBase, UIInteractionState, UIModel, UIParent, UIParentProps, UIProps, UIRole, UISize, UIStyleTokens, UIVariant, registerPaletteResolver } from './hierarchy/index.js';
+export { ActionButton, Badge, BadgeModel, BadgeProps, BadgeTone, ButtonModel, ButtonParent, ButtonParentProps, ButtonProps, ButtonSize, ButtonVariant, CardPanel, CategoryCardTile, ChannelStripTile, ClipCardTile, DangerButton, GhostButton, IconButton, InputModel, InspectorPanel, ModalPanel, PanelModel, PanelParent, PanelParentProps, PanelProps, PanelVariant, SelectInput, SelectInputProps, SliderInput, SliderInputProps, SpawnOptionTile, StatusDot, StatusDotProps, TelemetryPill, TelemetryPillProps, TextInput, TextInputProps, TileModel, TileParent, TileParentProps, TileVariant, ToggleButton, ToggleInput, ToggleInputProps, ToolbarPanel, TooltipDirection, UIBaseProps, UIElementBase, UIInteractionState, UIModel, UIParent, UIParentProps, UIProps, UIRole, UISize, UIStyleTokens, UIVariant, registerPaletteResolver } from './hierarchy/index.js';
+export { GraphEntityMetadata } from '@ultrst-armada/kloks/state-graph';
 import 'zod';
 import 'react';
-import '@ultrst-armada/kloks/state-graph';

package/packages/ui/dist/index.js

@@ -129,6 +129,13 @@ 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,
@@ -137,13 +144,6 @@ import {
   StatusLight,
   SystemMessageDisplay
 } from "./chunk-C3L53YN4.js";
-import {
-  BaseSelect,
-  BaseTextarea,
-  BaseToggle,
-  CredentialField,
-  KNOWN_CREDENTIAL_URLS
-} from "./chunk-KIFQA7L6.js";
 import {
   ConfirmDialog,
   CopyableErrorAlert,