import type { EcsError, EntityHandle, World } from '@forgeax/engine-ecs';
import type { PackError } from '@forgeax/engine-pack/errors';
import { type Result } from '@forgeax/engine-rhi';
import type { SkinError } from '@forgeax/engine-skinning';
import { type Asset, AssetError, type Handle, type SceneAsset, type SkinAsset, type TagOf } from '@forgeax/engine-types';
import type { AssetRegistry } from '../asset-registry';
import { type ScenePublicationFence, type ScenePublicationFenceError } from './scene-publication-fence';
/**
 * Resolver contract consumed by {@link postSpawnResolveJoints} (D-1: relocated
 * here from scene-instances/post-spawn-resolve-joints.ts so the hook contract
 * travels with the instantiate cluster into @forgeax/engine-assets-runtime).
 */
export interface SkinJointResolver {
    resolveSkinAsset(skeletonHandleRaw: number): SkinAsset | undefined;
}
/** Derive a publication fence from the registry's unified live projections. */
export declare function scenePublicationFenceFromRegistry(registry: AssetRegistry, outputGuid: string): Result<ScenePublicationFence, ScenePublicationFenceError>;
/**
 * Validate the producer receipt for every keyed instance edge before the
 * Scene owner starts spawning. The authored declaration carries only the
 * child GUID; the expected generation/digest comes from the parent
 * publication's external evidence, so publication state never leaks into the
 * SceneAsset model.
 */
/** @internal */
export declare function validateKeyedScenePublication(registry: AssetRegistry, scene: SceneAsset, rootGuid: string | undefined): Result<void, ScenePublicationFenceError>;
/** Resolve one schema-declared shared-field GUID to a World-owned handle. */
export declare function resolveHandleGuid(registry: AssetRegistry, world: World, guidString: string, guidToHandle: Map<string, number>, fieldPath: string, location: string): Result<number, AssetError>;
/**
 * Post-spawn hook contract (D-1). A hook runs after instantiate spawns the
 * scene subtree; the shipped implementation is runtime's `postSpawnResolveJoints`
 * (auto-wire Skin.joints). Injected at the sole production assembly point
 * (createRenderer) in w9/w10; when absent, instantiate skips joint wiring.
 */
export type PostSpawnHook = (world: World, resolver: SkinJointResolver, root: EntityHandle) => {
    ok: true;
} | {
    ok: false;
    error: SkinError;
};
/** All structured failures produced by either public Scene spawn shape. */
export type SceneInstantiateError = AssetError | PackError | EcsError | ScenePublicationFenceError | SkinError;
/**
 * Materialise a `SceneAsset` into an existing `World` and return the
 * synthetic root `Entity` (feat-20260514 w31 sugar wrapper; AC-03 +
 * requirements §IN-3; M3: returns Entity not SceneInstanceId).
 *
 * Before spawning, handle-type component fields (e.g. `assetHandle`,
 * `material`, `skeleton`) containing GUID strings are resolved to fresh
 * user-tier `Handle` numbers via `world.allocSharedRef` (feat-20260614 M8
 * D-19 instantiate-time GUID->handle mint; supersedes the pre-D-17
 * `resolveGuid` map). GUIDs that fail to parse or are not catalogued return
 * `AssetError(code='asset-not-found')` with a hint containing the GUID,
 * node localId, and field name.
 *
 * Errors propagate verbatim through the closed
 * `AssetError | PackError | EcsError` union so AI users that already
 * narrow `loadByGuid<SceneAsset>` results reuse the same `switch
 * (err.code)` exhaustively (charter proposition 3 machine-readable
 * union; plan-strategy §3.3 closed-union transparency).
 *
 * @example
 * ```ts
 * const sceneRes = await engine.assets.loadByGuid<SceneAsset>(roomGuid); // payload (D-17)
 * if (!sceneRes.ok) return;
 * const handle = world.allocSharedRef('SceneAsset', sceneRes.value);     // mint column handle
 * const r = engine.assets.instantiate(handle, world);
 * if (!r.ok) {
 *   switch (r.error.code) {
 *     case 'asset-not-found':
 *     case 'pack-cyclic-reference':
 *     // ... AssetErrorCode | PackErrorCode | EcsErrorCode exhaustive
 *   }
 * }
 * ```
 */
export declare function instantiate<T extends SceneAsset>(registry: AssetRegistry, handle: Handle<TagOf<T>, 'shared'>, world: World, parent?: EntityHandle, expectedPublication?: ScenePublicationFence): Result<EntityHandle, SceneInstantiateError>;
/**
 * Materialise a `SceneAsset` FLAT into an existing `World` — the "edit the
 * scene itself" registry entry (#655). Shares the GUID-resolution + shared-ref +
 * SceneAssetResolver prelude with {@link instantiate}, but calls
 * `worldInstantiateSceneFlat` instead of `worldInstantiateScene`: NO synthetic
 * SceneInstance root, NO forced `ChildOf` on top-level members. The scene's own
 * entities become plain top-level world entities; nested prefabs (`mounts[]`)
 * still become their own SceneInstance anchors. Returns the set of top-level
 * entity handles.
 *
 * Use this to OPEN a scene for authoring; use {@link instantiate} (anchor) at
 * runtime / Play and for nested prefabs.
 *
 * The post-spawn Skin.joints hook (when wired via `registry.postSpawnHook`)
 * runs once per top-level root: each GLB root keeps its own `ChildOf` subtree,
 * so joint resolution is scoped to each subtree exactly as the anchor path
 * scopes it to the single synthetic root.
 */
export declare function instantiateFlat<T extends SceneAsset>(registry: AssetRegistry, handle: Handle<TagOf<T>, 'shared'>, world: World, expectedPublication?: ScenePublicationFence): Result<EntityHandle[], SceneInstantiateError>;
/**
 * tweak-20260609 M1 helper: build the per-sub-ref parent context for a
 * SceneAsset child. feat-20260622 M3 / w9: re-sourced to lookup in the
 * scene envelope's ``refs[]`` edges instead of walking entity components
 * via extractSceneEntityHandleGuids (D-7). When the scene envelope is not
 * found in the catalog, falls back to the entity-walk path (backward compat
 * for call sites that lack a catalogued envelope).
 *
 * Texture edges (sourceField=undefined) produce ``componentField:
 * undefined`` — the breadcrumb will show GUID+kind only, no per-entity
 * detail (D-2: texture has no per-entity origin).
 */
export declare function buildSceneChildContext(registry: AssetRegistry, scene: Asset & {
    kind: 'scene';
}, subGuidKey: string, sceneGuidKey?: string): {
    sceneEntityKey?: string;
    componentField?: string;
    sourceField?: {
        componentName?: string;
        fieldName: string;
        arrayIndex?: number;
    };
} | undefined;
/** @internal One synchronous dependency traversal owns this lazy origin index. */
export declare function createSceneChildContextLookup(registry: AssetRegistry, scene: Asset & {
    kind: 'scene';
}): (subGuidKey: string, sceneGuidKey?: string) => ReturnType<typeof buildSceneChildContext>;
/**
 * tweak-20260609 M1 helper: build the error-hint breadcrumb string
 * containing the parent asset's GUID + kind, enriched with the
 * caller-provided `parentContext` (entity localId + component.field).
 *
 * Per D-7 / B-8: the breadcrumb appears before the sub-asset's own hint,
 * separated by " / ".
 */
export declare function buildBreadcrumbHint(parentGuidKey: string, parentKind: string, subGuidKey: string, parentContext?: {
    sceneEntityKey?: string;
    componentField?: string;
}): string;
//# sourceMappingURL=instantiate.d.ts.map