@kubuild/core 0.0.1

package/dist/interfaces.d.ts

@@ -0,0 +1,71 @@
+import { PageDocument } from '@kubuild/schema';
+export interface AssetInfo {
+    id: string;
+    url: string;
+    mimeType: string;
+    size?: number;
+    alt?: string;
+}
+export interface AssetProvider {
+    resolve(assetIdOrUri: string): Promise<string> | string;
+    upload?(file: File | Blob, metadata?: Record<string, unknown>): Promise<AssetInfo>;
+    delete?(assetId: string): Promise<boolean>;
+    list?(): Promise<AssetInfo[]>;
+}
+export interface ActionExecutionContext {
+    nodeId?: string;
+    document: PageDocument;
+    variables?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export type ActionHandler = (payload: Record<string, unknown> | undefined, context: ActionExecutionContext) => Promise<void> | void;
+export interface ActionRegistry {
+    get(actionType: string): ActionHandler | undefined;
+    register(actionType: string, handler: ActionHandler): void;
+    unregister(actionType: string): void;
+}
+export interface ActionDiagnostic {
+    code: 'UNKNOWN_ACTION' | 'ACTION_EXECUTION_ERROR' | 'INVALID_ACTION_PAYLOAD' | 'INVALID_ACTION_BINDING';
+    actionType: string;
+    nodeId?: string;
+    message: string;
+    error?: unknown;
+    invalidPaths?: string[];
+}
+export interface PropBindingDiagnostic {
+    code: 'INCOMPATIBLE_BINDING_TYPE';
+    nodeId?: string;
+    propName: string;
+    expectedType: string;
+    actualType: string;
+    message: string;
+}
+export interface CollectionDiagnostic {
+    code: 'INVALID_COLLECTION_SOURCE';
+    nodeId?: string;
+    propName: string;
+    message: string;
+}
+export type Diagnostic = ActionDiagnostic | PropBindingDiagnostic | CollectionDiagnostic;
+export type RenderContext = Readonly<{
+    variables?: Readonly<Record<string, unknown>>;
+    assetProvider?: AssetProvider;
+    actionRegistry?: ActionRegistry;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}>;
+export type RuntimeContext = RenderContext;
+export type VariableValueType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+/**
+ * Host-declared catalog entry describing a bindable variable and an editor/preview-only
+ * sample value. `sampleValue` must never be written into a `PageDocument` — it exists so
+ * the builder can preview bindings without persisting host data into the portable document.
+ */
+export interface VariableDefinition {
+    key: string;
+    label: string;
+    type: VariableValueType;
+    sampleValue: unknown;
+    description?: string;
+}
+export type VariableCatalog = VariableDefinition[];
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"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"}

package/dist/migration.d.ts

@@ -0,0 +1,86 @@
+import { PageDocument } from '@kubuild/schema';
+export type MigrationErrorCode = 'NO_MIGRATION_PATH' | 'UNSUPPORTED_SCHEMA_VERSION' | 'INVALID_SOURCE_DOCUMENT' | 'MIGRATION_EXECUTION_FAILED';
+export interface MigrationError {
+    code: MigrationErrorCode;
+    message: string;
+    sourceVersion: string;
+    targetVersion: string;
+    details?: Record<string, unknown>;
+}
+export interface MigrationDiagnostic {
+    success: boolean;
+    sourceVersion: string;
+    targetVersion: string;
+    migrationPath: string[];
+    stepsApplied: number;
+    dryRun: boolean;
+    errors?: MigrationError[];
+}
+export interface MigrationResult {
+    success: boolean;
+    document?: PageDocument;
+    diagnostic: MigrationDiagnostic;
+}
+export interface MigrateOptions {
+    /**
+     * Target schema version (defaults to CURRENT_SCHEMA_VERSION = "1.0.0").
+     */
+    targetVersion?: string;
+    /**
+     * If true, validates path and simulates migration without modifying production data.
+     */
+    dryRun?: boolean;
+    /**
+     * Custom migration registry (defaults to defaultMigrationRegistry).
+     */
+    registry?: MigrationRegistry;
+    /**
+     * Validate document with schema validator after migration (default: true).
+     */
+    validate?: boolean;
+}
+export type MigrationFunction = (rawDoc: Record<string, unknown>) => Record<string, unknown>;
+export interface MigrationStep {
+    fromVersion: string;
+    toVersion: string;
+    migrate: MigrationFunction;
+    description?: string;
+}
+/**
+ * Migration Registry to manage version transition steps.
+ */
+export declare class MigrationRegistry {
+    private steps;
+    /**
+     * Register a migration step from one version to another.
+     */
+    register(step: MigrationStep): void;
+    private getKey;
+    /**
+     * Find shortest path of versions to migrate from source to target using BFS.
+     */
+    findPath(sourceVersion: string, targetVersion: string): string[] | null;
+    /**
+     * Check if a valid migration path exists between source and target versions.
+     */
+    hasPath(sourceVersion: string, targetVersion: string): boolean;
+    /**
+     * Get the migration step handler for a direct version step.
+     */
+    getStep(fromVersion: string, toVersion: string): MigrationStep | undefined;
+}
+export declare const defaultMigrationRegistry: MigrationRegistry;
+/**
+ * Check whether a migration path exists between source and target versions.
+ */
+export declare function canMigrate(sourceVersion: string, targetVersion?: string, registry?: MigrationRegistry): boolean;
+/**
+ * Get the sequence of versions forming the migration path.
+ */
+export declare function getMigrationPath(sourceVersion: string, targetVersion?: string, registry?: MigrationRegistry): string[] | null;
+/**
+ * Migrate a page document from an older schema version to current (or specified) schema version.
+ * Supports dry-run execution, step diagnostics, and structured error reporting.
+ */
+export declare function migrateDocument(rawDocument: unknown, options?: MigrateOptions): MigrationResult;
+//# sourceMappingURL=migration.d.ts.map

package/dist/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAKb,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,kBAAkB,GAC1B,mBAAmB,GACnB,4BAA4B,GAC5B,yBAAyB,GACzB,4BAA4B,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7F,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAyC;IAEtD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAKnC,OAAO,CAAC,MAAM;IAId;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IA+BvE;;OAEG;IACH,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAI9D;;OAEG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAG3E;AA0BD,eAAO,MAAM,wBAAwB,mBAA0B,CAAC;AAqGhE;;GAEG;AACH,wBAAgB,UAAU,CACxB,aAAa,EAAE,MAAM,EACrB,aAAa,GAAE,MAA+B,EAC9C,QAAQ,GAAE,iBAA4C,GACrD,OAAO,CAIT;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,aAAa,GAAE,MAA+B,EAC9C,QAAQ,GAAE,iBAA4C,GACrD,MAAM,EAAE,GAAG,IAAI,CAGjB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,OAAO,EACpB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CA0MjB"}

package/dist/round-trip-comparator.d.ts

@@ -0,0 +1,38 @@
+import { PageDocument, Manifest } from '@kubuild/schema';
+export type SemanticDifferenceKind = 'METADATA_MISMATCH' | 'NODE_MISSING' | 'NODE_EXTRA' | 'NODE_ORDER' | 'NODE_TYPE' | 'PROP_MISMATCH' | 'STYLE_MISMATCH' | 'BINDING_MISMATCH' | 'ACTION_MISMATCH' | 'ASSET_MISMATCH' | 'DEPENDENCY_MISMATCH';
+export interface SemanticDifference {
+    path: string;
+    kind: SemanticDifferenceKind;
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+export interface SemanticCompareOptions {
+    /**
+     * Optional map of original asset IDs to host-remapped asset IDs.
+     * Used when host renamed colliding assets during import.
+     */
+    assetIdMap?: Record<string, string> | Map<string, string>;
+    /**
+     * Whether to ignore transient timestamp fields (e.g. createdAt/updatedAt).
+     * Default: true.
+     */
+    ignoreTimestamps?: boolean;
+}
+export interface SemanticComparisonResult {
+    equivalent: boolean;
+    differences: SemanticDifference[];
+}
+/**
+ * Semantically compares two PageDocuments, checking metadata, tree structure,
+ * node order, props, responsive styles, bindings, action references, and asset mappings.
+ *
+ * Only documented transient fields (e.g. transient timestamps, host-generated asset IDs)
+ * are ignored or normalized per options.
+ */
+export declare function compareDocumentsSemantically(expected: PageDocument, actual: PageDocument, options?: SemanticCompareOptions): SemanticComparisonResult;
+/**
+ * Semantically compares exported and imported package manifests.
+ */
+export declare function compareManifestsSemantically(expected: Manifest, actual: Manifest, options?: SemanticCompareOptions): SemanticComparisonResult;
+//# sourceMappingURL=round-trip-comparator.d.ts.map

package/dist/round-trip-comparator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-trip-comparator.d.ts","sourceRoot":"","sources":["../src/round-trip-comparator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAIZ,QAAQ,EAIT,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,sBAAsB,GAC9B,mBAAmB,GACnB,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1D;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAiYD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,sBAA2B,GACnC,wBAAwB,CA2D1B;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,QAAQ,EAChB,OAAO,GAAE,sBAA2B,GACnC,wBAAwB,CAuF1B"}

package/dist/security.d.ts

@@ -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.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/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/template-utils.d.ts

@@ -0,0 +1,124 @@
+import { type TemplateRecord, type TemplateRequirements, type PageDocument, type Node } from '@kubuild/schema';
+/**
+ * Standard core built-in component types
+ */
+export declare const CORE_BUILTIN_COMPONENTS: Set<string>;
+/**
+ * Structured validation error entry
+ */
+export interface TemplateValidationError {
+    code: string;
+    message: string;
+    path: string;
+}
+/**
+ * Result of template record validation
+ */
+export interface TemplateValidationResult {
+    valid: boolean;
+    data?: TemplateRecord;
+    errors?: TemplateValidationError[];
+}
+/**
+ * Validates a template record value against TemplateRecordSchema and returns structured errors.
+ */
+export declare function validateTemplate(value: unknown): TemplateValidationResult;
+/**
+ * Extracts required components and capabilities from a PageDocument.
+ * Detects any custom/non-core component types used in the document tree.
+ */
+export declare function extractTemplateRequirements(doc: PageDocument, builtinComponents?: Set<string>): TemplateRequirements;
+/**
+ * Parameters for creating a TemplateRecord
+ */
+export interface CreateTemplateParams {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    thumbnail?: TemplateRecord['thumbnail'];
+    author?: string;
+    version?: string;
+    document?: PageDocument;
+    packageReference?: TemplateRecord['packageReference'];
+    requirements?: TemplateRequirements;
+    createdAt?: string;
+    updatedAt?: string;
+    custom?: Record<string, unknown>;
+}
+/**
+ * Creates and validates a TemplateRecord.
+ * Automatically extracts requirements from the embedded document if requirements are not explicitly supplied.
+ */
+export declare function createTemplateRecord(params: CreateTemplateParams): TemplateRecord;
+/**
+ * Required metadata parameters for saving a draft as a template.
+ * id and name are strictly required and non-empty.
+ */
+export interface SaveTemplateMetadata {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    thumbnail?: TemplateRecord['thumbnail'];
+    author?: string;
+    version?: string;
+    custom?: Record<string, unknown>;
+}
+export interface SaveDraftAsTemplateOptions {
+    validateDraft?: boolean;
+    requirements?: TemplateRequirements;
+}
+/**
+ * Exports a draft document snapshot as an immutable reusable TemplateRecord.
+ * - Requires mandatory metadata (id, name).
+ * - Validates draft document structure.
+ * - Extracts component/capability requirements.
+ * - Creates a deep-cloned immutable snapshot completely decoupled from the active draft.
+ */
+export declare function saveDraftAsTemplate(draft: PageDocument, metadata: SaveTemplateMetadata, options?: SaveDraftAsTemplateOptions): TemplateRecord;
+/**
+ * Options for cloning/instantiating a template into a new page document.
+ */
+export interface CloneTemplateOptions {
+    /**
+     * Title for the newly created page document. Defaults to template name or document title.
+     */
+    title?: string;
+    /**
+     * Author for the newly created page document.
+     */
+    author?: string;
+    /**
+     * Optional custom ID generator function for node duplication.
+     */
+    idGenerator?: (oldId: string, node: Node) => string;
+    /**
+     * Custom ID prefix for freshly generated node IDs. Defaults to random string / timestamp.
+     */
+    idPrefix?: string;
+    /**
+     * Whether to record origin template metadata in metadata.custom.originTemplate (defaults to true).
+     */
+    recordOrigin?: boolean;
+    /**
+     * Additional custom metadata for the new document.
+     */
+    customMetadata?: Record<string, unknown>;
+}
+/**
+ * Clones a template (or existing document) into a brand new PageDocument.
+ * - Generates ALL NEW node IDs across the entire tree (root page node and all children).
+ * - Ensures 100% ID difference from the source template.
+ * - Sets fresh creation/update timestamps.
+ * - Preserves origin template version/id in custom metadata.
+ * - Guarantees full memory and reference isolation from the template source.
+ */
+export declare function cloneTemplateAsPage(templateOrDoc: TemplateRecord | PageDocument, options?: CloneTemplateOptions): PageDocument;
+/**
+ * Helper to verify that two PageDocuments share ZERO overlapping node IDs.
+ */
+export declare function areNodeIdsCompletelyDistinct(docA: PageDocument, docB: PageDocument): boolean;
+//# sourceMappingURL=template-utils.d.ts.map

package/dist/template-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-utils.d.ts","sourceRoot":"","sources":["../src/template-utils.ts"],"names":[],"mappings":"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"}

package/dist/validator.d.ts

@@ -0,0 +1,43 @@
+import { PageDocument } from '@kubuild/schema';
+import { DocumentSecurityLimits } from './security';
+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 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;
+    checkAssetReferences?: boolean;
+    checkVariableBindings?: boolean;
+    checkActionBindings?: boolean;
+    securityLimits?: DocumentSecurityLimits;
+}
+export interface DocumentValidationResult {
+    valid: boolean;
+    success: boolean;
+    errors: DocumentValidationError[];
+    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.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/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,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,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,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,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,wBAAwB,CAiJ1B"}

package/dist/variable-catalog.d.ts

@@ -0,0 +1,9 @@
+import type { VariableCatalog } from './interfaces';
+/**
+ * Expands a host `VariableCatalog`'s dotted `sampleValue` keys (e.g. `'site.name'`,
+ * `'products'`) into a nested object shaped the same way `resolveBinding` expects
+ * `context.variables` to be shaped. Editor/preview-only: the result should be merged
+ * into a `RuntimeContext.variables` for canvas preview, never written to a document.
+ */
+export declare function buildSampleVariablesFromCatalog(catalog?: VariableCatalog): Record<string, unknown>;
+//# sourceMappingURL=variable-catalog.d.ts.map

package/dist/variable-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variable-catalog.d.ts","sourceRoot":"","sources":["../src/variable-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAQpD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBlG"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@kubuild/core",
+  "version": "0.0.1",
+  "description": "Framework-agnostic engine for KUBUILD: document utilities, command engine, history, migration, and validation",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kustora/kubuild.git"
+  },
+  "keywords": [
+    "page-builder",
+    "visual-editor",
+    "low-code",
+    "website-builder",
+    "stora",
+    "kubuild"
+  ],
+  "author": "KUBUILD",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kustora/kubuild/issues"
+  },
+  "homepage": "https://github.com/kustora/kubuild#readme",
+  "dependencies": {
+    "@kubuild/schema": "workspace:*",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^6.0.0",
+    "vitest": "^3.0.5"
+  }
+}