@kubuild/core 0.8.1 → 0.8.2

package/dist/io/exporter.d.cts

@@ -0,0 +1,89 @@
+import { PageDocument, DocumentMetadata, Manifest } from '@kubuild/schema';
+import { DocumentValidationError, ValidationOptions, ComponentRegistryLike } from '../validation/validator.cjs';
+import { CollectedAssetReference } from '../document/document-utils.cjs';
+import type { AssetProvider } from '../types/interfaces.cjs';
+export interface ExportAssetData {
+    data: Uint8Array | ArrayBuffer | Blob | string;
+    mimeType?: string;
+    filename?: string;
+}
+export type AssetBytesProvider = (assetId: string, assetRef: CollectedAssetReference) => Promise<Uint8Array | ArrayBuffer | Blob | string | ExportAssetData | null | undefined> | Uint8Array | ArrayBuffer | Blob | string | ExportAssetData | null | undefined;
+export interface ExportPackageOptions {
+    /**
+     * Component registry to validate document components and extract requirements.
+     */
+    componentRegistry?: ComponentRegistryLike;
+    /**
+     * Known component types if registry is not passed.
+     */
+    knownComponentTypes?: string[] | Set<string>;
+    /**
+     * Directly supplied asset binary map (keyed by assetId).
+     */
+    assets?: Record<string, Uint8Array | ArrayBuffer | Blob | string | ExportAssetData> | Map<string, Uint8Array | ArrayBuffer | Blob | string | ExportAssetData>;
+    /**
+     * Host function to retrieve asset binary data dynamically.
+     */
+    getAssetBytes?: AssetBytesProvider;
+    /**
+     * Host AssetProvider instance to resolve assets if bytes provider is not present.
+     */
+    assetProvider?: AssetProvider;
+    /**
+     * Package version to write in manifest (defaults to "1.0.0").
+     */
+    packageVersion?: string;
+    /**
+     * Builder compatibility semver range (defaults to ">=0.1.0").
+     */
+    builderCompatibility?: string;
+    /**
+     * If true, assets that have a fallbackUrl or are externally hosted will not cause export failure if local bytes are missing.
+     * If false and a referenced asset has no bytes available, export fails.
+     */
+    allowExternalFallback?: boolean;
+    /**
+     * Additional validation options passed to validateDocument.
+     */
+    validationOptions?: ValidationOptions;
+    /**
+     * Optional metadata overrides (e.g. author, tags).
+     */
+    metadata?: Partial<DocumentMetadata>;
+}
+export interface ExportPackageSuccess {
+    success: true;
+    archive: Uint8Array;
+    manifest: Manifest;
+    page: PageDocument;
+    metadata: DocumentMetadata;
+    assetCount: number;
+}
+export interface ExportPackageFailure {
+    success: false;
+    errors: DocumentValidationError[];
+    diagnosticMessage: string;
+}
+export type ExportPackageResult = ExportPackageSuccess | ExportPackageFailure;
+/**
+ * Pure TypeScript SHA-256 implementation (zero native dependencies, deterministic).
+ */
+export declare function sha256Sync(data: Uint8Array): string;
+/**
+ * Compute SHA-256 checksum with "sha256:" prefix.
+ */
+export declare function calculateChecksum(data: Uint8Array): Promise<string>;
+/**
+ * Sanitize asset file names to prevent zip-slip or directory traversal vulnerabilities.
+ */
+export declare function sanitizeFilename(filename: string | undefined, assetId: string, mimeType?: string): string;
+/**
+ * Validates document, collects asset references, resolves local asset bytes,
+ * writes manifest.json, page.json, metadata.json, and packages everything into a .stora archive.
+ */
+export declare function exportPackage(document: unknown, options?: ExportPackageOptions): Promise<ExportPackageResult>;
+/**
+ * Alias for exportPackage.
+ */
+export declare const exportStoraPackage: typeof exportPackage;
+//# sourceMappingURL=exporter.d.cts.map

package/dist/io/exporter.d.cts.map

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

package/dist/io/exporter.d.ts

@@ -1,7 +1,7 @@
 import { PageDocument, DocumentMetadata, Manifest } from '@kubuild/schema';
-import { DocumentValidationError, ValidationOptions, ComponentRegistryLike } from '../validation/validator';
-import { CollectedAssetReference } from '../document/document-utils';
-import type { AssetProvider } from '../types/interfaces';
+import { DocumentValidationError, ValidationOptions, ComponentRegistryLike } from '../validation/validator.js';
+import { CollectedAssetReference } from '../document/document-utils.js';
+import type { AssetProvider } from '../types/interfaces.js';
 export interface ExportAssetData {
     data: Uint8Array | ArrayBuffer | Blob | string;
     mimeType?: string;

package/dist/io/exporter.d.ts.map

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

package/dist/io/importer.d.cts

@@ -0,0 +1,245 @@
+import { PageDocument, DocumentMetadata, Manifest, ManifestAssetItem } from '@kubuild/schema';
+import { ComponentRegistryLike } from '../validation/validator.cjs';
+import { MigrationRegistry } from './migration.cjs';
+import type { AssetProvider, AssetInfo } from '../types/interfaces.cjs';
+export interface SecurityLimits {
+    /**
+     * Maximum allowed size for the compressed archive in bytes (default: 50MB).
+     */
+    maxArchiveSize?: number;
+    /**
+     * Maximum total uncompressed size across all files in bytes (default: 100MB).
+     */
+    maxUncompressedSize?: number;
+    /**
+     * Maximum number of files in the archive (default: 1000).
+     */
+    maxFileCount?: number;
+    /**
+     * Maximum size for any individual asset in bytes (default: 25MB).
+     */
+    maxAssetSize?: number;
+}
+export declare const DEFAULT_SECURITY_LIMITS: Required<SecurityLimits>;
+export type MissingDependencyPolicy = 'cancel' | 'import-with-placeholder' | 'install-or-register-before-import';
+export type AssetCollisionStrategy = 'reject' | 'rename' | 'overwrite' | 'reuse-existing';
+export interface AssetConflict {
+    assetId: string;
+    path: string;
+    mimeType: string;
+    size: number;
+    existingAsset?: AssetInfo | Record<string, unknown>;
+}
+export interface AssetConflictResolution {
+    action: AssetCollisionStrategy;
+    newAssetId?: string;
+}
+export type PreflightDiagnosticCode = 'ARCHIVE_EMPTY' | 'ARCHIVE_CORRUPT' | 'SIZE_LIMIT_EXCEEDED' | 'FILE_COUNT_EXCEEDED' | 'ZIP_SLIP_DETECTED' | 'EXECUTABLE_ASSET_DETECTED' | 'PROTOTYPE_POLLUTION_DETECTED' | 'MISSING_MANIFEST' | 'INVALID_MANIFEST' | 'MISSING_PAGE_DOCUMENT' | 'INVALID_PAGE_DOCUMENT' | 'UNSUPPORTED_SCHEMA_VERSION' | 'NO_MIGRATION_PATH' | 'MIGRATION_FAILED' | 'ASSET_FILE_MISSING' | 'ASSET_SIZE_MISMATCH' | 'ASSET_CHECKSUM_MISMATCH' | 'ASSET_LIMIT_EXCEEDED' | 'ASSET_CONFLICT' | 'MISSING_COMPONENTS' | 'MISSING_CAPABILITIES' | 'HOST_ADAPTER_ERROR' | 'TRACKING_SECRET_REMOVED';
+export interface PreflightDiagnostic {
+    code: PreflightDiagnosticCode;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    path?: string;
+    details?: Record<string, unknown>;
+}
+export interface PreflightOptions {
+    /**
+     * Component registry to check required custom components.
+     */
+    componentRegistry?: ComponentRegistryLike;
+    /**
+     * Allowlist of known component type names (used if componentRegistry is not provided or in combination).
+     */
+    knownComponentTypes?: string[] | Set<string>;
+    /**
+     * Allowlist of capabilities supported by host.
+     */
+    supportedCapabilities?: string[] | Set<string>;
+    /**
+     * Security limits for archive and files.
+     */
+    securityLimits?: SecurityLimits;
+    /**
+     * Custom migration registry.
+     */
+    migrationRegistry?: MigrationRegistry;
+    /**
+     * Target schema version (defaults to CURRENT_SCHEMA_VERSION).
+     */
+    targetSchemaVersion?: string;
+    /**
+     * Policy for handling missing custom components and capabilities.
+     * - 'cancel' (default): Abort import with blocking errors when components/capabilities are missing.
+     * - 'import-with-placeholder': Allow import, keeping missing component nodes and props intact for placeholder rendering.
+     * - 'install-or-register-before-import': Call onMissingDependency to register/install before finalizing import.
+     */
+    dependencyPolicy?: MissingDependencyPolicy;
+    /**
+     * Hook called when dependencyPolicy is 'install-or-register-before-import'.
+     */
+    onMissingDependency?: (missing: {
+        components: string[];
+        capabilities: string[];
+    }, preflight: PreflightReport) => Promise<boolean | void> | boolean | void;
+    /**
+     * If true, missing components are treated as warnings rather than blocking errors.
+     * (Equivalent to setting dependencyPolicy: 'import-with-placeholder')
+     */
+    allowMissingComponents?: boolean;
+    /**
+     * If true, missing capabilities are treated as warnings rather than blocking errors.
+     * (Equivalent to setting dependencyPolicy: 'import-with-placeholder')
+     */
+    allowMissingCapabilities?: boolean;
+    /**
+     * Strategy for resolving asset collisions with existing host assets.
+     * - 'reject' (default): Refuse import if asset collision is detected without an explicit resolution strategy.
+     * - 'rename': Rename the incoming asset to avoid overwriting host assets, and automatically remap document asset references.
+     * - 'overwrite': Explicitly overwrite host assets with incoming archive assets.
+     * - 'reuse-existing': Reuse existing host assets and skip writing archive asset binaries.
+     */
+    assetCollisionStrategy?: AssetCollisionStrategy;
+    /**
+     * Existing host asset IDs or checker function to detect collisions.
+     */
+    existingAssetIds?: string[] | Set<string> | ((assetId: string) => boolean | Promise<boolean>);
+    /**
+     * Custom naming function when renaming colliding assets.
+     */
+    renameAssetStrategy?: (incoming: ManifestAssetItem, existingIds: Set<string>) => string;
+    /**
+     * Host AssetProvider to resolve existing assets or upload extracted local assets.
+     */
+    assetProvider?: AssetProvider;
+    /**
+     * Fine-grained callback for resolving individual asset conflicts.
+     */
+    onAssetConflict?: (conflict: AssetConflict) => Promise<AssetConflictResolution | AssetCollisionStrategy> | AssetConflictResolution | AssetCollisionStrategy;
+}
+export interface PreflightReport {
+    /**
+     * True if archive is completely safe and syntactically valid.
+     */
+    valid: boolean;
+    /**
+     * True if archive can be safely imported given the host's supported components/capabilities and asset policies.
+     */
+    canImport: boolean;
+    /**
+     * Parsed manifest if available.
+     */
+    manifest?: Manifest;
+    /**
+     * Parsed metadata if available.
+     */
+    rawMetadata?: DocumentMetadata;
+    /**
+     * Schema version reported in the document/manifest.
+     */
+    sourceVersion?: string;
+    /**
+     * Target schema version.
+     */
+    targetVersion: string;
+    /**
+     * True if the document version differs from target version and requires migration.
+     */
+    requiresMigration: boolean;
+    /**
+     * Migration path version sequence if migration is needed.
+     */
+    migrationPath?: string[];
+    /**
+     * List of custom component types required by package that are missing in host.
+     */
+    missingComponents: string[];
+    /**
+     * List of capabilities required by package that are missing in host.
+     */
+    missingCapabilities: string[];
+    /**
+     * Active policy for missing dependencies.
+     */
+    dependencyPolicy: MissingDependencyPolicy;
+    /**
+     * Number of valid local assets declared in manifest.
+     */
+    assetCount: number;
+    /**
+     * List of detected asset collisions with existing host assets.
+     */
+    assetConflicts: AssetConflict[];
+    /**
+     * Active strategy for handling asset collisions.
+     */
+    assetCollisionStrategy: AssetCollisionStrategy;
+    /**
+     * Total uncompressed size of all files in archive.
+     */
+    totalUncompressedBytes: number;
+    /**
+     * Diagnostics collected during inspection.
+     */
+    diagnostics: PreflightDiagnostic[];
+}
+export interface ImportPackageOptions extends PreflightOptions {
+    /**
+     * Custom asset importer hook called for each extracted asset.
+     */
+    onAssetImport?: (assetId: string, assetBytes: Uint8Array, assetMeta: ManifestAssetItem) => Promise<AssetInfo | string | void> | AssetInfo | string | void;
+}
+export interface ExtractedAsset {
+    bytes: Uint8Array;
+    meta: ManifestAssetItem;
+    hostInfo?: AssetInfo | string;
+}
+export interface ImportPackageSuccess {
+    success: true;
+    document: PageDocument;
+    manifest: Manifest;
+    metadata: DocumentMetadata;
+    extractedAssets: Map<string, ExtractedAsset>;
+    renamedAssets?: Record<string, string>;
+    preflight: PreflightReport;
+    /** Non-fatal notes produced while importing (e.g. tracking secrets stripped). */
+    warnings?: PreflightDiagnostic[];
+}
+export interface ImportPackageFailure {
+    success: false;
+    errors: PreflightDiagnostic[];
+    diagnosticMessage: string;
+    preflight?: PreflightReport;
+}
+export type ImportPackageResult = ImportPackageSuccess | ImportPackageFailure;
+/**
+ * Checks if a zip entry path contains zip-slip or directory traversal attempts.
+ */
+export declare function isDangerousPath(filepath: string): boolean;
+/**
+ * Inspects a .stora archive and runs non-destructive preflight validation.
+ * Verifies security limits, path safety, manifest, checksums, component/capability requirements, and migration status.
+ */
+export declare function preflightPackage(archiveData: Uint8Array | ArrayBuffer, options?: PreflightOptions): Promise<PreflightReport>;
+/**
+ * Preview a .stora package without mutating host state.
+ * Returns missing dependencies, asset conflicts, schema migration status, and diagnostics.
+ */
+export declare const previewImportPackage: typeof preflightPackage;
+/**
+ * Alias for preflightPackage.
+ */
+export declare const inspectPackage: typeof preflightPackage;
+/**
+ * Default generator for renaming colliding asset IDs.
+ */
+export declare function defaultRenameAssetStrategy(incoming: ManifestAssetItem, existingIds: Set<string>): string;
+/**
+ * Imports a .stora package with preflight safety checks, schema migration, missing dependency policy,
+ * and host-controlled asset collision handling.
+ */
+export declare function importPackage(archiveData: Uint8Array | ArrayBuffer, options?: ImportPackageOptions): Promise<ImportPackageResult>;
+/**
+ * Alias for importPackage.
+ */
+export declare const importStoraPackage: typeof importPackage;
+//# sourceMappingURL=importer.d.cts.map

package/dist/io/importer.d.cts.map

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

package/dist/io/importer.d.ts

@@ -1,7 +1,7 @@
 import { PageDocument, DocumentMetadata, Manifest, ManifestAssetItem } from '@kubuild/schema';
-import { ComponentRegistryLike } from '../validation/validator';
-import { MigrationRegistry } from './migration';
-import type { AssetProvider, AssetInfo } from '../types/interfaces';
+import { ComponentRegistryLike } from '../validation/validator.js';
+import { MigrationRegistry } from './migration.js';
+import type { AssetProvider, AssetInfo } from '../types/interfaces.js';
 export interface SecurityLimits {
     /**
      * Maximum allowed size for the compressed archive in bytes (default: 50MB).

package/dist/io/importer.d.ts.map

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

package/dist/io/index.d.cts

@@ -0,0 +1,8 @@
+export * from './exporter.cjs';
+export * from './importer.cjs';
+export * from './migration.cjs';
+export * from './load-project.cjs';
+export * from './round-trip-comparator.cjs';
+export * from './template-utils.cjs';
+export * from './tracking-sanitizer.cjs';
+//# sourceMappingURL=index.d.cts.map

package/dist/io/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/io/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AAEpC,cAAc,yBAAyB,CAAC"}

package/dist/io/index.d.ts

@@ -1,8 +1,8 @@
-export * from './exporter';
-export * from './importer';
-export * from './migration';
-export * from './load-project';
-export * from './round-trip-comparator';
-export * from './template-utils';
-export * from './tracking-sanitizer';
+export * from './exporter.js';
+export * from './importer.js';
+export * from './migration.js';
+export * from './load-project.js';
+export * from './round-trip-comparator.js';
+export * from './template-utils.js';
+export * from './tracking-sanitizer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/io/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/io/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/io/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AAEpC,cAAc,yBAAyB,CAAC"}

package/dist/io/load-project.d.cts

@@ -0,0 +1,42 @@
+import { PageDocument, ProjectDocument } from '@kubuild/schema';
+export type ProjectLoadErrorCode = 'INVALID_SOURCE' | 'PROJECT_SCHEMA_INVALID' | 'LEGACY_MIGRATION_FAILED';
+export interface ProjectLoadError {
+    code: ProjectLoadErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface ProjectLoadResult {
+    success: boolean;
+    project?: ProjectDocument;
+    /** True when the payload arrived as a legacy single-page document and was wrapped. */
+    wrappedFromLegacyPage: boolean;
+    errors: ProjectLoadError[];
+}
+export interface WrapPageAsProjectOptions {
+    artboardId?: string;
+    name?: string;
+    slug?: string;
+    width?: number;
+}
+/**
+ * Wrap a single PageDocument into a one-artboard ProjectDocument.
+ * Used both by the legacy load path and by consumers that still hold a lone page.
+ */
+export declare function wrapPageDocumentAsProject(document: PageDocument, options?: WrapPageAsProjectOptions): ProjectDocument;
+/**
+ * Load a raw payload as a ProjectDocument.
+ *
+ * `PageDocument -> ProjectDocument` is a schema *kind* switch (`document` singular vs.
+ * `artboards[]`, different `schema` literal), not a version step, so it cannot be expressed
+ * as a MigrationRegistry step. This loader sniffs the shape and routes accordingly:
+ *
+ * - already a project (`schema === 'stora.project'` or has `artboards[]`) -> parse as a project
+ * - anything else -> run the existing page migration pipeline untouched, then wrap the
+ *   fully-migrated page into a single-artboard project
+ *
+ * Legacy inline modal/drawer/collapsible nodes are deliberately NOT auto-extracted into
+ * component artboards here; that stays an explicit, author-triggered action so no existing
+ * document silently changes how it renders.
+ */
+export declare function loadProjectDocument(raw: unknown): ProjectLoadResult;
+//# sourceMappingURL=load-project.d.cts.map

package/dist/io/load-project.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-project.d.cts","sourceRoot":"","sources":["../../src/io/load-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,YAAY,EACZ,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AAqBzB,MAAM,MAAM,oBAAoB,GAC5B,gBAAgB,GAChB,wBAAwB,GACxB,yBAAyB,CAAC;AAE9B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,sFAAsF;IACtF,qBAAqB,EAAE,OAAO,CAAC;IAC/B,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAkBjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CA4DnE"}

package/dist/io/migration.d.cts

@@ -0,0 +1,112 @@
+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 type MigrationWarningCode = 'TRACKING_SECRET_REMOVED' | 'PROP_ALIAS_MIGRATED';
+/**
+ * Non-fatal note emitted by a migration step (the migration still succeeds).
+ */
+export interface MigrationWarning {
+    code: MigrationWarningCode | (string & {});
+    message: string;
+    /** Step that emitted the warning, e.g. "1.0.0->1.1.0". */
+    step?: string;
+    /** Dotted document paths affected. */
+    paths?: string[];
+}
+export interface MigrationDiagnostic {
+    success: boolean;
+    sourceVersion: string;
+    targetVersion: string;
+    migrationPath: string[];
+    stepsApplied: number;
+    dryRun: boolean;
+    errors?: MigrationError[];
+    /** Non-fatal notes, e.g. tracking secrets stripped from the document. */
+    warnings?: MigrationWarning[];
+}
+export interface MigrationResult {
+    success: boolean;
+    document?: PageDocument;
+    diagnostic: MigrationDiagnostic;
+}
+export interface MigrateOptions {
+    /**
+     * Target schema version (defaults to CURRENT_SCHEMA_VERSION).
+     */
+    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;
+}
+/** Context handed to each migration step. */
+export interface MigrationStepContext {
+    /** Records a non-fatal warning on the final `MigrationDiagnostic`. */
+    warn: (warning: MigrationWarning) => void;
+}
+export type MigrationFunction = (rawDoc: Record<string, unknown>, context: MigrationStepContext) => 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;
+/**
+ * Moves deprecated text-prop aliases (`content`, `label`, `quote`, ...) onto each
+ * component's canonical prop name (STORA-550), in place. The canonical value becomes
+ * whatever the pre-1.2.0 renderer actually displayed (its `legacyReadOrder`), so a
+ * migrated document renders identically. Returns the dotted paths of rewritten props.
+ */
+export declare function canonicalizeTextPropsInPlace(root: unknown, basePath?: string): string[];
+/**
+ * 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.cts.map

package/dist/io/migration.d.cts.map

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