@kubuild/core 0.8.1 → 0.8.2

package/dist/validation/project-validator.d.cts

@@ -0,0 +1,38 @@
+import { Node, ProjectDocument } from '@kubuild/schema';
+import { DocumentValidationError, ValidationOptions } from './validator.cjs';
+export type ProjectValidationErrorCode = 'PROJECT_SCHEMA_INVALID' | 'DUPLICATE_ARTBOARD_ID' | 'DUPLICATE_NODE_ID_ACROSS_ARTBOARDS' | 'DANGLING_ARTBOARD_REFERENCE' | 'DUPLICATE_TRIGGER_ID' | 'INVALID_ACTIVE_ARTBOARD' | 'ARTBOARD_DOCUMENT_INVALID';
+export interface ProjectValidationError {
+    code: ProjectValidationErrorCode;
+    message: string;
+    path: string;
+    artboardId?: string;
+    nodeId?: string;
+    details?: Record<string, unknown>;
+}
+export interface ProjectValidationResult {
+    valid: boolean;
+    success: boolean;
+    errors: ProjectValidationError[];
+    /** Per-artboard results from the existing single-document validator. */
+    artboardErrors: Record<string, DocumentValidationError[]>;
+    data?: ProjectDocument;
+}
+/**
+ * Validate a multi-artboard project.
+ *
+ * Each artboard's document is handed to the existing `validateDocument` unchanged; this
+ * function only adds the checks that cannot exist at single-document scope:
+ * artboard-id uniqueness, node-id uniqueness *across* artboards (so content moved between
+ * artboards can't silently collide), duplicate component trigger ids, and reference stubs
+ * that point at an artboard which no longer exists.
+ */
+export declare function validateProject(input: unknown, options?: ValidationOptions): ProjectValidationResult;
+/**
+ * Collect artboard-reference stubs in a single page document. Used by the exporter guard
+ * to refuse silently-incomplete single-page exports.
+ */
+export declare function collectArtboardReferenceNodes(root: Node): Array<{
+    nodeId: string;
+    artboardId?: string;
+}>;
+//# sourceMappingURL=project-validator.d.cts.map

package/dist/validation/project-validator.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-validator.d.cts","sourceRoot":"","sources":["../../src/validation/project-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,IAAI,EACJ,eAAe,EAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EAElB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,0BAA0B,GAClC,wBAAwB,GACxB,uBAAuB,GACvB,oCAAoC,GACpC,6BAA6B,GAC7B,sBAAsB,GACtB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,uBAAuB,CAkIzB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CASxG"}

package/dist/validation/project-validator.d.ts

@@ -1,5 +1,5 @@
 import { Node, ProjectDocument } from '@kubuild/schema';
-import { DocumentValidationError, ValidationOptions } from './validator';
+import { DocumentValidationError, ValidationOptions } from './validator.js';
 export type ProjectValidationErrorCode = 'PROJECT_SCHEMA_INVALID' | 'DUPLICATE_ARTBOARD_ID' | 'DUPLICATE_NODE_ID_ACROSS_ARTBOARDS' | 'DANGLING_ARTBOARD_REFERENCE' | 'DUPLICATE_TRIGGER_ID' | 'INVALID_ACTIVE_ARTBOARD' | 'ARTBOARD_DOCUMENT_INVALID';
 export interface ProjectValidationError {
     code: ProjectValidationErrorCode;

package/dist/validation/project-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-validator.d.ts","sourceRoot":"","sources":["../../src/validation/project-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,IAAI,EACJ,eAAe,EAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,0BAA0B,GAClC,wBAAwB,GACxB,uBAAuB,GACvB,oCAAoC,GACpC,6BAA6B,GAC7B,sBAAsB,GACtB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,uBAAuB,CAkIzB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CASxG"}
+{"version":3,"file":"project-validator.d.ts","sourceRoot":"","sources":["../../src/validation/project-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,IAAI,EACJ,eAAe,EAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EAElB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,0BAA0B,GAClC,wBAAwB,GACxB,uBAAuB,GACvB,oCAAoC,GACpC,6BAA6B,GAC7B,sBAAsB,GACtB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,uBAAuB,CAkIzB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CASxG"}

package/dist/validation/security.d.cts

@@ -0,0 +1,99 @@
+/**
+ * Security Limits and Sanitization Utilities for KUBUILD documents, assets, and actions.
+ */
+export interface DocumentSecurityLimits {
+    /**
+     * Maximum allowed total nodes in the document tree (default: 5000).
+     */
+    maxNodeCount?: number;
+    /**
+     * Maximum allowed nesting depth of nodes (default: 32).
+     */
+    maxTreeDepth?: number;
+    /**
+     * Maximum number of direct properties per node (default: 200).
+     */
+    maxPropsCount?: number;
+    /**
+     * Maximum character length for any individual string property (default: 100,000).
+     */
+    maxStringLength?: number;
+    /**
+     * Maximum number of direct children per node (default: 1000).
+     */
+    maxChildrenPerNode?: number;
+    /**
+     * Maximum allowed JSON serialized size in bytes (default: 10MB).
+     */
+    maxDocumentSizeBytes?: number;
+    /**
+     * Allowed URL schemes for links and media.
+     * Default: ['http:', 'https:', 'mailto:', 'tel:', '#', 'relative', 'data:image/']
+     */
+    allowedUrlSchemes?: string[];
+    /**
+     * Prohibited property keys to defend against Prototype Pollution.
+     * Default: ['__proto__', 'constructor', 'prototype', '__defineGetter__', '__defineSetter__', '__lookupGetter__', '__lookupSetter__']
+     */
+    prohibitedPropertyKeys?: string[];
+    /**
+     * Prohibited asset file extensions to prevent executable uploads.
+     * Default: ['.exe', '.dll', '.so', '.sh', '.bat', '.cmd', '.js', '.mjs', '.cjs', '.php', '.py', '.vbs', '.wasm', '.bin', '.com', '.scr', '.pif']
+     */
+    prohibitedAssetExtensions?: string[];
+    /**
+     * Maximum compression expansion ratio before flagging potential zip bomb (default: 100).
+     */
+    maxZipExpansionRatio?: number;
+}
+export declare const DEFAULT_DOCUMENT_SECURITY_LIMITS: Required<DocumentSecurityLimits>;
+export interface SecurityViolation {
+    code: 'PROTOTYPE_POLLUTION_DETECTED' | 'MAX_NODE_COUNT_EXCEEDED' | 'MAX_TREE_DEPTH_EXCEEDED' | 'MAX_PROPS_COUNT_EXCEEDED' | 'MAX_STRING_LENGTH_EXCEEDED' | 'MAX_CHILDREN_COUNT_EXCEEDED' | 'MAX_DOCUMENT_SIZE_EXCEEDED' | 'UNSAFE_URL_DETECTED' | 'EXECUTABLE_ASSET_DETECTED' | 'ZIP_BOMB_DETECTED';
+    message: string;
+    path?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Checks whether a URL is safe according to the allowed URL schemes.
+ * Rejects dangerous schemes such as javascript:, vbscript:, data:text/html, etc.
+ */
+export declare function isSafeUrl(url: unknown, options?: {
+    allowedSchemes?: string[];
+    allowDataImage?: boolean;
+    /** Allow `blob:` URLs (runtime-only, e.g. in-memory uploaded media previews). */
+    allowBlobMedia?: boolean;
+}): boolean;
+/**
+ * Sanitizes a URL, returning a safe URL or a fallback (default empty string or '#').
+ */
+export declare function sanitizeUrl(url: unknown, fallback?: string, options?: Parameters<typeof isSafeUrl>[1]): string;
+/**
+ * Checks an object recursively for prohibited prototype pollution keys.
+ */
+export declare function containsProhibitedKeys(obj: unknown, prohibitedKeys?: string[]): {
+    found: boolean;
+    path: string;
+    key: string;
+};
+/**
+ * Validates a document against security limits (node count, tree depth, props count, string length, prototype pollution).
+ */
+export declare function validateDocumentSecurity(doc: unknown, customLimits?: DocumentSecurityLimits): {
+    safe: boolean;
+    errors: SecurityViolation[];
+};
+/**
+ * Checks if an asset filename has a dangerous or executable extension.
+ */
+export declare function isDangerousAssetFilename(filename: string, prohibitedExtensions?: string[]): boolean;
+/**
+ * Checks whether an archive expansion ratio indicates a zip bomb attack.
+ */
+export declare function checkZipBomb(compressedSize: number, uncompressedSize: number, maxRatio?: number): boolean;
+/**
+ * Sanitizes an HTML string by stripping unsafe tags (<script>, <object>, <embed>, <applet>, <base>, <link rel="import">),
+ * removing inline event handlers (on* attributes like onclick, onerror, onload, etc.),
+ * and disarming javascript:/vbscript:/data:text/html URLs in attributes.
+ */
+export declare function sanitizeHtml(rawHtml: unknown): string;
+//# sourceMappingURL=security.d.cts.map

package/dist/validation/security.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.cts","sourceRoot":"","sources":["../../src/validation/security.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAElC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IAErC;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,gCAAgC,EAAE,QAAQ,CAAC,sBAAsB,CAuC7E,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,8BAA8B,GAC9B,yBAAyB,GACzB,yBAAyB,GACzB,0BAA0B,GAC1B,4BAA4B,GAC5B,6BAA6B,GAC7B,4BAA4B,GAC5B,qBAAqB,GACrB,2BAA2B,GAC3B,mBAAmB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GACA,OAAO,CAiET;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,QAAQ,GAAE,MAAW,EACrB,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAGR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,EACZ,cAAc,GAAE,MAAM,EAA4D,GACjF;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA0C/C;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EACZ,YAAY,CAAC,EAAE,sBAAsB,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAoHhD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,oBAAoB,GAAE,MAAM,EAA+D,GAC1F,OAAO,CAUT;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,GAAE,MAA8D,GACvE,OAAO,CAQT;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAwBrD"}

package/dist/validation/validation-engine.d.cts

@@ -0,0 +1,39 @@
+import type { FormFieldBinding, ValidationRule } from '@kubuild/schema';
+/**
+ * Checks whether a field value is considered empty.
+ * Empty values include undefined, null, empty string, empty array, or boolean false.
+ */
+export declare function isEmptyValue(value: unknown): boolean;
+/**
+ * Applies a value transformation to a field value prior to validation.
+ */
+export declare function applyFieldTransform(value: unknown, transform?: 'trim' | 'lowercase' | 'uppercase' | 'number' | string): unknown;
+/**
+ * Evaluates a single validation rule against a field value.
+ * Returns the rule's error message if invalid, or null if valid.
+ */
+export declare function evaluateRule(rule: ValidationRule, value: unknown, allFormValues?: Record<string, unknown>): string | null;
+/**
+ * Validates a single field value against an array of ValidationRules.
+ * Returns the first failing error message, or null if all rules pass.
+ */
+export declare function validateFieldValue(value: unknown, rules?: ValidationRule[] | null, allFormValues?: Record<string, unknown>): string | null;
+/**
+ * Asynchronously validates a single field value against an array of ValidationRules.
+ */
+export declare function validateFieldValueAsync(value: unknown, rules?: ValidationRule[] | null, allFormValues?: Record<string, unknown>): Promise<string | null>;
+/**
+ * Validates an entire form values object against field configs.
+ * Returns a map of field names to error messages (Record<string, string>).
+ * If all fields are valid, returns an empty object {}.
+ */
+export declare function validateForm(values: Record<string, unknown>, fieldConfigs: FormFieldBinding[] | Record<string, FormFieldBinding | ValidationRule[]>): Record<string, string>;
+/**
+ * Asynchronously validates an entire form values object against field configs.
+ */
+export declare function validateFormAsync(values: Record<string, unknown>, fieldConfigs: FormFieldBinding[] | Record<string, FormFieldBinding | ValidationRule[]>): Promise<Record<string, string>>;
+/**
+ * Convenience helper to determine if a form error map is completely valid (no errors).
+ */
+export declare function isFormValid(errors: Record<string, string>): boolean;
+//# sourceMappingURL=validation-engine.d.cts.map

package/dist/validation/validation-engine.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-engine.d.cts","sourceRoot":"","sources":["../../src/validation/validation-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAExE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcpD;AAYD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GACjE,OAAO,CA6BT;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,MAAM,GAAG,IAAI,CAoGf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,EAC/B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,MAAM,GAAG,IAAI,CAaf;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,EAC/B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,YAAY,EACR,gBAAgB,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAAC,GACtD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2DxB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,YAAY,EACR,gBAAgB,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAAC,GACtD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEjC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAEnE"}

package/dist/validation/validator.d.cts

@@ -0,0 +1,80 @@
+import { PageDocument } from '@kubuild/schema';
+import { DocumentSecurityLimits } from './security.cjs';
+export type DocumentValidationErrorCode = 'GLOBAL_SCHEMA_INVALID' | 'ROOT_NODE_INVALID' | 'NODE_SHAPE_INVALID' | 'DUPLICATE_NODE_ID' | 'TREE_CYCLE_DETECTED' | 'UNKNOWN_COMPONENT_TYPE' | 'CHILD_POLICY_VIOLATION' | 'INVALID_ASSET_REFERENCE' | 'INVALID_VARIABLE_BINDING' | 'INVALID_ACTION_BINDING' | 'INVALID_METADATA' | 'PROTOTYPE_POLLUTION_DETECTED' | 'SECURITY_LIMIT_EXCEEDED';
+export interface DocumentValidationError {
+    code: DocumentValidationErrorCode;
+    message: string;
+    path: string;
+    nodeId?: string;
+    details?: Record<string, unknown>;
+}
+export type DocumentValidationWarningCode = 'CHILD_POLICY_VIOLATION' | 'UNKNOWN_COMPONENT_TYPE' | 'UNRESOLVED_ASSET_REFERENCE' | (string & {});
+export interface DocumentValidationWarning {
+    code: DocumentValidationWarningCode;
+    message: string;
+    path: string;
+    nodeId?: string;
+    details?: Record<string, unknown>;
+}
+export interface ComponentDefinitionLike {
+    type: string;
+    category?: string;
+    capabilities?: string[];
+    acceptsChildren?: boolean;
+    allowedChildren?: string[];
+    disallowedParents?: string[];
+}
+export interface ComponentRegistryLike {
+    get(type: string): ComponentDefinitionLike | undefined;
+    has(type: string): boolean;
+}
+export interface ValidationOptions {
+    componentRegistry?: ComponentRegistryLike;
+    knownComponentTypes?: string[] | Set<string>;
+    strictComponentTypes?: boolean;
+    /**
+     * Whether to treat child policy mismatches (e.g. allowedChildren) strictly as blocking errors.
+     * If false or undefined (default), allowedChildren mismatches are emitted as non-blocking warnings.
+     */
+    strictChildPolicy?: boolean;
+    /**
+     * Validate asset references (`{ type: 'asset', assetId, fallbackUrl? }`) found in node props.
+     * Checks that `assetId` is a non-empty string and `fallbackUrl` (if present) is a string.
+     * When `knownAssetIds` is also supplied, every referenced `assetId` must be in that set.
+     * Defaults to `true`.
+     */
+    checkAssetReferences?: boolean;
+    /**
+     * Known asset IDs used to verify that asset references resolve. A `PageDocument` carries
+     * no asset registry of its own (assets live in the `.stora` manifest or the host's asset
+     * provider), so this existence check only runs when the caller supplies the IDs.
+     * An unresolved reference is an `INVALID_ASSET_REFERENCE` error, or a non-blocking
+     * `UNRESOLVED_ASSET_REFERENCE` warning when the reference has a `fallbackUrl`.
+     * Ignored when `checkAssetReferences` is `false`.
+     */
+    knownAssetIds?: string[] | Set<string>;
+    /**
+     * Validate variable bindings (`{ type: 'variable', key }`) in node props: `key` must be a
+     * non-empty string. Defaults to `true`.
+     */
+    checkVariableBindings?: boolean;
+    /**
+     * Validate action bindings in node props (a prop named `action`, or any object with a string
+     * `type` and a `payload`): `type` must be a non-empty string. Defaults to `true`.
+     */
+    checkActionBindings?: boolean;
+    securityLimits?: DocumentSecurityLimits;
+}
+export interface DocumentValidationResult {
+    valid: boolean;
+    success: boolean;
+    errors: DocumentValidationError[];
+    warnings: DocumentValidationWarning[];
+    data?: PageDocument;
+}
+/**
+ * Validate a page document against global schema, node shape, child policy,
+ * ID uniqueness, cycles, unknown component types, and structural bindings.
+ */
+export declare function validateDocument(input: unknown, options?: ValidationOptions): DocumentValidationResult;
+//# sourceMappingURL=validator.d.cts.map

package/dist/validation/validator.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.cts","sourceRoot":"","sources":["../../src/validation/validator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAGb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,sBAAsB,EAEvB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,2BAA2B,GACnC,uBAAuB,GACvB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,wBAAwB,GACxB,wBAAwB,GACxB,yBAAyB,GACzB,0BAA0B,GAC1B,wBAAwB,GACxB,kBAAkB,GAClB,8BAA8B,GAC9B,yBAAyB,CAAC;AAE9B,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,6BAA6B,GACrC,wBAAwB,GACxB,wBAAwB,GACxB,4BAA4B,GAC5B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,6BAA6B,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAAC;IACvD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,wBAAwB,CAwJ1B"}

package/dist/validation/validator.d.ts

@@ -1,5 +1,5 @@
 import { PageDocument } from '@kubuild/schema';
-import { DocumentSecurityLimits } from './security';
+import { DocumentSecurityLimits } from './security.js';
 export type DocumentValidationErrorCode = 'GLOBAL_SCHEMA_INVALID' | 'ROOT_NODE_INVALID' | 'NODE_SHAPE_INVALID' | 'DUPLICATE_NODE_ID' | 'TREE_CYCLE_DETECTED' | 'UNKNOWN_COMPONENT_TYPE' | 'CHILD_POLICY_VIOLATION' | 'INVALID_ASSET_REFERENCE' | 'INVALID_VARIABLE_BINDING' | 'INVALID_ACTION_BINDING' | 'INVALID_METADATA' | 'PROTOTYPE_POLLUTION_DETECTED' | 'SECURITY_LIMIT_EXCEEDED';
 export interface DocumentValidationError {
     code: DocumentValidationErrorCode;

package/dist/validation/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validation/validator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAGb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,2BAA2B,GACnC,uBAAuB,GACvB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,wBAAwB,GACxB,wBAAwB,GACxB,yBAAyB,GACzB,0BAA0B,GAC1B,wBAAwB,GACxB,kBAAkB,GAClB,8BAA8B,GAC9B,yBAAyB,CAAC;AAE9B,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,6BAA6B,GACrC,wBAAwB,GACxB,wBAAwB,GACxB,4BAA4B,GAC5B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,6BAA6B,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAAC;IACvD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,wBAAwB,CAwJ1B"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validation/validator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAGb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,sBAAsB,EAEvB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,2BAA2B,GACnC,uBAAuB,GACvB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,wBAAwB,GACxB,wBAAwB,GACxB,yBAAyB,GACzB,0BAA0B,GAC1B,wBAAwB,GACxB,kBAAkB,GAClB,8BAA8B,GAC9B,yBAAyB,CAAC;AAE9B,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,6BAA6B,GACrC,wBAAwB,GACxB,wBAAwB,GACxB,4BAA4B,GAC5B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,6BAA6B,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAAC;IACvD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,wBAAwB,CAwJ1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubuild/core",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Framework-agnostic engine for KUBUILD: document utilities, command engine, history, migration, and validation",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -8,9 +8,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -41,7 +46,7 @@
   "homepage": "https://github.com/kustora/kubuild#readme",
   "dependencies": {
     "fflate": "^0.8.3",
-    "@kubuild/schema": "0.8.1"
+    "@kubuild/schema": "0.8.2"
   },
   "devDependencies": {
     "tsup": "^8.3.6",
@@ -49,7 +54,7 @@
     "vitest": "^3.0.5"
   },
   "scripts": {
-    "build": "tsup && tsc --emitDeclarationOnly",
+    "build": "tsup && tsc --emitDeclarationOnly && node ../../scripts/emit-cjs-dts.mjs",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",