@object-ui/core 2.0.0 → 3.0.1

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @object-ui/core@2.0.0 build /home/runner/work/objectui/objectui/packages/core
+> @object-ui/core@3.0.1 build /home/runner/work/objectui/objectui/packages/core
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @object-ui/core
 
+## 3.0.1
+
+### Patch Changes
+
+- @object-ui/types@3.0.1
+
+## 3.0.0
+
+### Minor Changes
+
+- 87979c3: Upgrade to @objectstack v3.0.0 and console bundle optimization
+  - Upgraded all @objectstack/\* packages from ^2.0.7 to ^3.0.0
+  - Breaking change migrations: Hub → Cloud namespace, definePlugin removed, PaginatedResult.value → .records, PaginatedResult.count → .total, client.meta.getObject() → client.meta.getItem()
+  - Console bundle optimization: split monolithic 3.7 MB chunk into 17 granular cacheable chunks (95% main entry reduction)
+  - Added gzip + brotli pre-compression via vite-plugin-compression2
+  - Lazy MSW loading for build:server (~150 KB gzip saved)
+  - Added bundle analysis with rollup-plugin-visualizer
+
+### Patch Changes
+
+- Updated dependencies [87979c3]
+  - @object-ui/types@3.0.0
+
 ## 2.0.0
 
 ### Major Changes

package/dist/__benchmarks__/core.bench.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export {};

package/dist/__benchmarks__/core.bench.js

@@ -0,0 +1,53 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Performance benchmark suite for @object-ui/core.
+ *
+ * Part of Q1 2026 roadmap §1.4 Test Coverage Improvement.
+ *
+ * Run with: npx vitest bench packages/core/src/__benchmarks__/
+ */
+import { bench, describe } from 'vitest';
+import { ExpressionEvaluator } from '@object-ui/core';
+import { ComponentRegistry } from '@object-ui/core';
+import { contrastRatio, meetsContrastLevel, hexToHSL } from '@object-ui/core';
+describe('ExpressionEvaluator performance', () => {
+    const evaluator = new ExpressionEvaluator({ data: { name: 'Alice', age: 30, active: true } });
+    bench('evaluate simple string', () => {
+        evaluator.evaluate('Hello ${data.name}');
+    });
+    bench('evaluate 100 expressions', () => {
+        for (let i = 0; i < 100; i++) {
+            evaluator.evaluate('Hello ${data.name}');
+        }
+    });
+});
+describe('ComponentRegistry performance', () => {
+    bench('get registered component', () => {
+        ComponentRegistry.get('button');
+    });
+    bench('has check', () => {
+        ComponentRegistry.has('button');
+    });
+});
+describe('Theme utilities performance', () => {
+    bench('hexToHSL conversion', () => {
+        hexToHSL('#336699');
+    });
+    bench('contrastRatio calculation', () => {
+        contrastRatio('#000000', '#ffffff');
+    });
+    bench('meetsContrastLevel check', () => {
+        meetsContrastLevel('#000000', '#ffffff', 'AA');
+    });
+    bench('100 contrast checks', () => {
+        for (let i = 0; i < 100; i++) {
+            meetsContrastLevel('#336699', '#ffffff', 'AA');
+        }
+    });
+});

package/dist/errors/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface ErrorCodeEntry {
+    code: string;
+    message: string;
+    suggestion: string;
+    docUrl: string;
+}
+export declare const ERROR_CODES: Record<string, ErrorCodeEntry>;
+/**
+ * Check whether a string is a known ObjectUI error code.
+ */
+export declare function isErrorCode(code: unknown): code is keyof typeof ERROR_CODES;
+/**
+ * Base error class for all ObjectUI errors.
+ */
+export declare class ObjectUIError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+    /**
+     * Convert error to JSON for logging / debugging.
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        details: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Type guard to check if an error is an ObjectUIError.
+ */
+export declare function isObjectUIError(error: unknown): error is ObjectUIError;
+/** Thrown when a schema is invalid or fails validation. */
+export declare class SchemaError extends ObjectUIError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Thrown when a registry operation fails. */
+export declare class RegistryError extends ObjectUIError {
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+/** Thrown when expression evaluation fails. */
+export declare class ExpressionError extends ObjectUIError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Thrown when a plugin operation fails. */
+export declare class PluginError extends ObjectUIError {
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+/** Thrown when validation of user input / field config fails. */
+export declare class FieldValidationError extends ObjectUIError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Create an `ObjectUIError` (or subclass) from a known error code.
+ *
+ * @param code   - A registered error code (e.g. `"OBJUI-001"`).
+ * @param params - Values to interpolate into the message template.
+ * @param details - Optional extra details attached to the error.
+ */
+export declare function createError(code: string, params?: Record<string, string>, details?: Record<string, unknown>): ObjectUIError;
+/**
+ * Format an error message with actionable fix suggestions in development mode.
+ *
+ * @param error - The `ObjectUIError` to format.
+ * @param isDev - When `true`, appends the suggestion and documentation link.
+ */
+export declare function formatErrorMessage(error: ObjectUIError, isDev?: boolean): string;

package/dist/errors/index.js

@@ -0,0 +1,224 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const BASE_DOC_URL = 'https://objectui.dev/docs/errors';
+export const ERROR_CODES = {
+    'OBJUI-001': {
+        code: 'OBJUI-001',
+        message: 'Unknown component type: "${type}"',
+        suggestion: 'Ensure the component is registered via registry.register() before rendering. Check for typos in the component type name.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-001`,
+    },
+    'OBJUI-002': {
+        code: 'OBJUI-002',
+        message: 'Schema validation failed: ${reason}',
+        suggestion: 'Verify the schema against the ObjectUI JSON spec. Run the built-in schema validator for details.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-002`,
+    },
+    'OBJUI-003': {
+        code: 'OBJUI-003',
+        message: 'Expression evaluation failed: ${expression}',
+        suggestion: 'Check the expression syntax and ensure all referenced variables exist in the current data scope.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-003`,
+    },
+    'OBJUI-004': {
+        code: 'OBJUI-004',
+        message: 'Plugin dependency missing: "${dependency}"',
+        suggestion: 'Install the required dependency and register it before loading this plugin.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-004`,
+    },
+    'OBJUI-005': {
+        code: 'OBJUI-005',
+        message: 'Plugin already loaded: "${plugin}"',
+        suggestion: 'A plugin with the same name is already registered. Remove the duplicate or use a unique plugin name.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-005`,
+    },
+    'OBJUI-006': {
+        code: 'OBJUI-006',
+        message: 'Plugin not found: "${plugin}"',
+        suggestion: 'Verify the plugin name and ensure it has been registered before access.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-006`,
+    },
+    'OBJUI-007': {
+        code: 'OBJUI-007',
+        message: 'Registry namespace deprecated: "${namespace}"',
+        suggestion: 'Migrate to the new namespace format. See the migration guide for details.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-007`,
+    },
+    'OBJUI-008': {
+        code: 'OBJUI-008',
+        message: 'Read-only scope violation: "${scope}"',
+        suggestion: 'You are trying to mutate a read-only data scope. Use a writable scope or clone the data before modifying.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-008`,
+    },
+    'OBJUI-009': {
+        code: 'OBJUI-009',
+        message: 'Invalid field configuration: "${field}"',
+        suggestion: 'Check the field schema for required properties (type, name). Ensure the field widget is registered.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-009`,
+    },
+    'OBJUI-010': {
+        code: 'OBJUI-010',
+        message: 'Action execution failed: "${action}"',
+        suggestion: 'Verify the action handler is registered and that all required parameters are provided.',
+        docUrl: `${BASE_DOC_URL}/OBJUI-010`,
+    },
+};
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a string is a known ObjectUI error code.
+ */
+export function isErrorCode(code) {
+    return typeof code === 'string' && code in ERROR_CODES;
+}
+// ---------------------------------------------------------------------------
+// Base Error Class
+// ---------------------------------------------------------------------------
+/**
+ * Base error class for all ObjectUI errors.
+ */
+export class ObjectUIError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: code
+        });
+        Object.defineProperty(this, "details", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: details
+        });
+        this.name = 'ObjectUIError';
+        // Maintains proper stack trace for where error was thrown (only in V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Convert error to JSON for logging / debugging.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            details: this.details,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Type guard to check if an error is an ObjectUIError.
+ */
+export function isObjectUIError(error) {
+    return error instanceof ObjectUIError;
+}
+// ---------------------------------------------------------------------------
+// Specialized Error Classes
+// ---------------------------------------------------------------------------
+/** Thrown when a schema is invalid or fails validation. */
+export class SchemaError extends ObjectUIError {
+    constructor(message, details) {
+        super(message, 'OBJUI-002', details);
+        this.name = 'SchemaError';
+    }
+}
+/** Thrown when a registry operation fails. */
+export class RegistryError extends ObjectUIError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = 'RegistryError';
+    }
+}
+/** Thrown when expression evaluation fails. */
+export class ExpressionError extends ObjectUIError {
+    constructor(message, details) {
+        super(message, 'OBJUI-003', details);
+        this.name = 'ExpressionError';
+    }
+}
+/** Thrown when a plugin operation fails. */
+export class PluginError extends ObjectUIError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = 'PluginError';
+    }
+}
+/** Thrown when validation of user input / field config fails. */
+export class FieldValidationError extends ObjectUIError {
+    constructor(message, details) {
+        super(message, 'OBJUI-009', details);
+        this.name = 'FieldValidationError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory & Formatting Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Interpolate a template string with the given params.
+ * Template variables use the `${key}` syntax.
+ */
+function interpolate(template, params) {
+    return template.replace(/\$\{(\w+)\}/g, (_match, key) => {
+        if (!(key in params) && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+            console.warn(`[ObjectUI] Missing interpolation parameter "${key}" in error message template.`);
+        }
+        return params[key] ?? `\${${key}}`;
+    });
+}
+/**
+ * Create an `ObjectUIError` (or subclass) from a known error code.
+ *
+ * @param code   - A registered error code (e.g. `"OBJUI-001"`).
+ * @param params - Values to interpolate into the message template.
+ * @param details - Optional extra details attached to the error.
+ */
+export function createError(code, params = {}, details) {
+    const entry = ERROR_CODES[code];
+    const message = entry
+        ? interpolate(entry.message, params)
+        : `Unknown error code: ${code}`;
+    switch (code) {
+        case 'OBJUI-002':
+            return new SchemaError(message, details);
+        case 'OBJUI-003':
+            return new ExpressionError(message, details);
+        case 'OBJUI-004':
+        case 'OBJUI-005':
+        case 'OBJUI-006':
+            return new PluginError(message, code, details);
+        case 'OBJUI-007':
+        case 'OBJUI-001':
+            return new RegistryError(message, code, details);
+        case 'OBJUI-009':
+            return new FieldValidationError(message, details);
+        default:
+            return new ObjectUIError(message, code, details);
+    }
+}
+/**
+ * Format an error message with actionable fix suggestions in development mode.
+ *
+ * @param error - The `ObjectUIError` to format.
+ * @param isDev - When `true`, appends the suggestion and documentation link.
+ */
+export function formatErrorMessage(error, isDev = typeof process !== 'undefined' &&
+    process.env?.NODE_ENV !== 'production') {
+    const entry = ERROR_CODES[error.code];
+    let formatted = `[${error.code}] ${error.message}`;
+    if (isDev && entry) {
+        formatted += `\n\n💡 Suggestion: ${entry.suggestion}`;
+        formatted += `\n📖 Docs: ${entry.docUrl}`;
+    }
+    return formatted;
+}

package/dist/index.d.ts

@@ -19,3 +19,5 @@ export * from './query/index.js';
 export * from './adapters/index.js';
 export * from './theme/index.js';
 export * from './data-scope/index.js';
+export * from './errors/index.js';
+export * from './utils/debug.js';

package/dist/index.js

@@ -18,3 +18,5 @@ export * from './query/index.js';
 export * from './adapters/index.js';
 export * from './theme/index.js';
 export * from './data-scope/index.js';
+export * from './errors/index.js';
+export * from './utils/debug.js';

package/dist/registry/Registry.js

@@ -37,7 +37,13 @@ export class Registry {
         // Warn if registering without namespace (deprecated pattern)
         if (!meta?.namespace) {
             console.warn(`Registering component "${type}" without a namespace is deprecated. ` +
-                `Please provide a namespace in the meta parameter.`);
+                `Please provide a namespace in the meta parameter.\n\n` +
+                `  Migration:\n` +
+                `  // Before (deprecated):\n` +
+                `  registry.register('${type}', MyComponent);\n\n` +
+                `  // After:\n` +
+                `  registry.register('${type}', MyComponent, { namespace: 'my-plugin' });\n\n` +
+                `  See: https://github.com/objectstack-ai/objectui/blob/main/MIGRATION_GUIDE.md`);
         }
         if (this.components.has(fullType)) {
             // console.warn(`Component type "${fullType}" is already registered. Overwriting.`);

package/dist/theme/ThemeEngine.d.ts

@@ -80,3 +80,26 @@ export declare function resolveThemeInheritance(theme: Theme, registry: Map<stri
  * @returns 'light' or 'dark'
  */
 export declare function resolveMode(mode?: ThemeMode, systemDark?: boolean): 'light' | 'dark';
+/**
+ * Calculate the WCAG 2.1 contrast ratio between two hex colors.
+ * Returns a value between 1 and 21.
+ *
+ * @param hex1 - First color in hex format (#RGB or #RRGGBB)
+ * @param hex2 - Second color in hex format (#RGB or #RRGGBB)
+ * @returns Contrast ratio (1-21), or null if colors are invalid
+ */
+export declare function contrastRatio(hex1: string, hex2: string): number | null;
+/**
+ * Check if two colors meet the specified WCAG contrast level.
+ *
+ * WCAG levels:
+ * - AA: 4.5:1 for normal text, 3:1 for large text
+ * - AAA: 7:1 for normal text, 4.5:1 for large text
+ *
+ * @param hex1 - First color in hex format
+ * @param hex2 - Second color in hex format
+ * @param level - WCAG level: 'AA' or 'AAA'
+ * @param isLargeText - Whether the text is large (18pt+ or 14pt+ bold)
+ * @returns true if the color pair meets the required contrast level
+ */
+export declare function meetsContrastLevel(hex1: string, hex2: string, level?: 'AA' | 'AAA', isLargeText?: boolean): boolean;

package/dist/theme/ThemeEngine.js

@@ -398,3 +398,72 @@ export function resolveMode(mode = 'auto', systemDark) {
     }
     return 'light'; // fallback
 }
+// ============================================================================
+// WCAG Contrast Checking (v2.0.7)
+// ============================================================================
+/**
+ * Parse a hex color string to RGB values [0-255].
+ */
+function hexToRGB(hex) {
+    let clean = hex.replace(/^#/, '');
+    if (clean.length === 3) {
+        clean = clean[0] + clean[0] + clean[1] + clean[1] + clean[2] + clean[2];
+    }
+    const match = /^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(clean);
+    if (!match)
+        return null;
+    return [parseInt(match[1], 16), parseInt(match[2], 16), parseInt(match[3], 16)];
+}
+/**
+ * Calculate relative luminance per WCAG 2.1 spec.
+ * @see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function relativeLuminance(r, g, b) {
+    const [rs, gs, bs] = [r, g, b].map(c => {
+        const s = c / 255;
+        return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+/**
+ * Calculate the WCAG 2.1 contrast ratio between two hex colors.
+ * Returns a value between 1 and 21.
+ *
+ * @param hex1 - First color in hex format (#RGB or #RRGGBB)
+ * @param hex2 - Second color in hex format (#RGB or #RRGGBB)
+ * @returns Contrast ratio (1-21), or null if colors are invalid
+ */
+export function contrastRatio(hex1, hex2) {
+    const rgb1 = hexToRGB(hex1);
+    const rgb2 = hexToRGB(hex2);
+    if (!rgb1 || !rgb2)
+        return null;
+    const l1 = relativeLuminance(...rgb1);
+    const l2 = relativeLuminance(...rgb2);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * Check if two colors meet the specified WCAG contrast level.
+ *
+ * WCAG levels:
+ * - AA: 4.5:1 for normal text, 3:1 for large text
+ * - AAA: 7:1 for normal text, 4.5:1 for large text
+ *
+ * @param hex1 - First color in hex format
+ * @param hex2 - Second color in hex format
+ * @param level - WCAG level: 'AA' or 'AAA'
+ * @param isLargeText - Whether the text is large (18pt+ or 14pt+ bold)
+ * @returns true if the color pair meets the required contrast level
+ */
+export function meetsContrastLevel(hex1, hex2, level = 'AA', isLargeText = false) {
+    const ratio = contrastRatio(hex1, hex2);
+    if (ratio === null)
+        return false;
+    if (level === 'AAA') {
+        return isLargeText ? ratio >= 4.5 : ratio >= 7;
+    }
+    // AA
+    return isLargeText ? ratio >= 3 : ratio >= 4.5;
+}

package/dist/theme/index.d.ts

@@ -5,4 +5,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';

package/dist/theme/index.js

@@ -5,4 +5,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';

package/dist/utils/debug.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render';
+/**
+ * Log a debug message when OBJECTUI_DEBUG is enabled.
+ * No-op in production or when debug mode is off.
+ *
+ * @example
+ * ```ts
+ * // Enable debug mode
+ * globalThis.OBJECTUI_DEBUG = true;
+ *
+ * debugLog('schema', 'Resolving component', { type: 'Button' });
+ * // [ObjectUI Debug][schema] Resolving component { type: 'Button' }
+ * ```
+ */
+export declare function debugLog(category: DebugCategory, message: string, data?: unknown): void;
+/**
+ * Start a debug timer. Pair with {@link debugTimeEnd}.
+ */
+export declare function debugTime(label: string): void;
+/**
+ * End a debug timer and log the elapsed time.
+ */
+export declare function debugTimeEnd(label: string): void;
+export {};

package/dist/utils/debug.js

@@ -0,0 +1,62 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+function isDebugEnabled() {
+    try {
+        const g = typeof globalThis !== 'undefined' && globalThis.OBJECTUI_DEBUG;
+        return ((g === true || g === 'true') ||
+            (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Log a debug message when OBJECTUI_DEBUG is enabled.
+ * No-op in production or when debug mode is off.
+ *
+ * @example
+ * ```ts
+ * // Enable debug mode
+ * globalThis.OBJECTUI_DEBUG = true;
+ *
+ * debugLog('schema', 'Resolving component', { type: 'Button' });
+ * // [ObjectUI Debug][schema] Resolving component { type: 'Button' }
+ * ```
+ */
+export function debugLog(category, message, data) {
+    if (!isDebugEnabled())
+        return;
+    if (data !== undefined) {
+        console.log(`[ObjectUI Debug][${category}] ${message}`, data);
+    }
+    else {
+        console.log(`[ObjectUI Debug][${category}] ${message}`);
+    }
+}
+const timers = new Map();
+/**
+ * Start a debug timer. Pair with {@link debugTimeEnd}.
+ */
+export function debugTime(label) {
+    if (!isDebugEnabled())
+        return;
+    timers.set(label, performance.now());
+}
+/**
+ * End a debug timer and log the elapsed time.
+ */
+export function debugTimeEnd(label) {
+    if (!isDebugEnabled())
+        return;
+    const start = timers.get(label);
+    if (start !== undefined) {
+        const elapsed = (performance.now() - start).toFixed(2);
+        console.log(`[ObjectUI Debug][perf] ${label}: ${elapsed}ms`);
+        timers.delete(label);
+    }
+}

package/dist/validation/validation-engine.js

@@ -336,7 +336,13 @@ export class ValidationEngine {
      */
     evaluateCondition(condition, values) {
         if (typeof condition === 'function') {
-            console.warn('Function-based conditions are deprecated and will be removed. Use declarative conditions instead.');
+            console.warn('Function-based conditions are deprecated and will be removed. Use declarative conditions instead.\n\n' +
+                '  Migration:\n' +
+                '  // Before (deprecated):\n' +
+                '  { condition: (values) => values.age > 18 }\n\n' +
+                '  // After:\n' +
+                '  { condition: { field: "age", operator: ">", value: 18 } }\n\n' +
+                '  See: https://github.com/objectstack-ai/objectui/blob/main/MIGRATION_GUIDE.md');
             return false; // Security: reject function-based conditions
         }
         if (typeof condition === 'object' && condition.field) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -24,10 +24,10 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^2.0.7",
+    "@objectstack/spec": "^3.0.2",
     "lodash": "^4.17.23",
     "zod": "^4.3.6",
-    "@object-ui/types": "2.0.0"
+    "@object-ui/types": "3.0.1"
   },
   "devDependencies": {
     "typescript": "^5.9.3",