//! `maat` — unified façade crate for the Metagamer SDK.
//!
//! This crate is the single dependency plugin and capability authors need.
//! It re-exports every Layer-2 sub-crate under a named sub-module and
//! provides a curated [`prelude`] that covers 95 % of plugin work.
//!
//! # Quick start
//!
//! ```toml
//! # Cargo.toml (plugin or capability)
//! [dependencies]
//! maat = { workspace = true }
//! ```
//!
//! ```rust,ignore
//! use maat::prelude::*;
//!
//! #[plugin("github.com/my-org/my-plugin")]
//! #[model_plugin]
//! pub struct MyPlugin;
//! ```
//!
//! # Sub-module access
//!
//! For rarer types not in the prelude, use the sub-module re-exports:
//!
//! | Path | Purpose |
//! |------|---------|
//! | `maat::prelude` | daily rules + entity authoring (95% case) |
//! | `maat::traits` | plugin extension-point traits (`CapabilityPlugin`, `ViewPluginMetadata`, etc.) |
//! | `maat::manifest` | plugin manifest types (mostly tests + dynamic plugins) |
//! | `maat::view` | view template machinery beyond the renderer trait |
//! | `maat::types` | escape hatch — full `maat-sdk-types` |
//! | `maat::derive` | proc-macros |

pub mod prelude;

// ── Sub-preludes ──────────────────────────────────────────────────────────

/// Plugin extension-point traits. Explicit import for capability and
/// view-metadata authors.
///
/// 0250 phase A-fu1: previously globbed from `maat_sdk_traits`. After
/// the sdk-traits collapse the same five symbols now live in
/// `maat_sdk`; we re-export them by name rather than glob-importing
/// the whole sdk crate to keep `maat::traits` scoped to the trait
/// surface plugin authors care about.
pub mod traits {
    pub use maat_sdk::{
        CapabilityPlugin, EntityTypeDeclaration, LocalHandlerId, ModelPlugin,
        SetupContext, TagSpec, ViewPluginMetadata,
    };
    pub use maat_sdk::compose::{
        ComposeEntry, CreationComposeThunk, DistanceMetricThunk, LevelUpComposeThunk,
        WizardComposeThunk,
    };
    pub use maat_sdk::post_install_context::{
        EmptyPostInstallContext, PostInstallContext, PostInstallContextExt,
    };
}

/// Plugin manifest types. Macro-generated by `#[plugin]`/`#[capability_plugin]`/
/// `#[view_plugin]` for the common case; this sub-module is the hand-rolling
/// escape hatch (tests, dynamic plugins, custom tooling).
pub mod manifest {
    // Registry manifest (the one `#[plugin]`/`#[capability_plugin]`/
    // `#[view_plugin]` macros generate). This is what plugin authors use.
    pub use maat_sdk_types::plugin_manifest::*;
    pub use maat_sdk_types::plugin_id::*;
    pub use maat_sdk_types::plugin_version::*;
    // The legacy lightweight manifest is reachable via its module path for
    // the rare consumer that needs it explicitly.
    pub use maat_sdk_types::manifest as legacy_manifest;
}

/// View template machinery beyond the renderer trait — widget registry,
/// template DSL primitives, scene-node primitives.
pub mod view {
    pub use maat_sdk_types::view::*;
}

// ── Sub-crate access (escape hatches) ─────────────────────────────────────

/// Full `maat-sdk-types` re-export. Escape hatch for rare types.
pub use maat_sdk_types as types;

/// Derive and attribute macros from `maat-sdk-derive`.
pub use maat_sdk_derive as derive;

/// Wire protocol types from `maat-sdk-wire`.
/// Enabled with the `wire` Cargo feature; not needed by most plugins.
#[cfg(feature = "wire")]
pub use maat_sdk_wire as wire;

// ── Macro support module (private — not for plugin authors) ───────────────

/// Internal alias used by the proc-macros in `maat-sdk-derive` to
/// find types/traits/macros they emit code referring to. Plugin authors
/// should not use this path directly — use the `prelude` or sub-crate
/// paths instead.
#[doc(hidden)]
pub mod __sdk {
    // linkme crate re-export so `#[::maat::__sdk::linkme::distributed_slice(...)]`
    // resolves in macro output.
    pub use maat_sdk_types::linkme;

    // Predicate sub-module — `gate!` emits `::maat::__sdk::predicate::Predicate::All` etc.
    pub use maat_sdk_types::predicate;

    // linkme static slices + their registration types.
    pub use maat_sdk_types::plugin_slices::{
        CapabilityRegistration, EntityRegistration, GameContext, HandlerRegistration,
        HandlerThunk, PhaseRegistration, PluginInstance, REGISTERED_CAPABILITIES,
        REGISTERED_ENTITIES, REGISTERED_HANDLERS, REGISTERED_PHASES,
        REGISTERED_WIRE_FRAMES, WireFrameRegistration,
    };

    // Core types macros reference.
    pub use maat_sdk_types::blueprint::EntityBlueprint;
    pub use maat_sdk_types::events::GameEvent;
    pub use maat_sdk_types::handler::{Decision, HandlerResponse};
    pub use maat_sdk_types::priority::Priority;
    pub use maat_sdk_types::types::EntityTypeId;

    // Trait data types `#[derive(EntityType)]` constructs from struct fields.
    pub use maat_sdk_types::trait_data::{NamedData, OwnableData, TangibleData};

    // Plugin manifest (registry variant) + identifiers `#[plugin]`/
    // `#[capability_plugin]`/`#[view_plugin]` macros assemble.
    pub use maat_sdk_types::plugin_id::CanonicalId;
    pub use maat_sdk_types::plugin_manifest::{
        compute_interface_hash, parse_semver_or_default,
        CapabilityDeclaration, HandlerDeclaration, PhaseDeclaration,
        PluginBackend, PluginDependency, PluginKind, PluginManifest,
        ScenarioDeclaration, SpdxLicenseId, StructuralNeeds, TypeDeclaration,
        WireFrameDeclaration, DISPATCH_ABI_V1,
    };

    // Capability + LocalId types used in handler / capability macro emission.
    pub use maat_sdk_types::capability::{CapabilityId, CapabilityResult};
    pub use maat_sdk::LocalHandlerId;
    pub use maat_sdk::post_install_context::PostInstallContext;

    // WizardKind stays — plugins emit Decision::Wizard(StagedDecision::new(_, kind, _))
    // through their Filter handlers. The composer driver pair
    // (ComposerAction/ComposerResponse) is engine-internal as of WI1-7.
    pub use maat_sdk_types::staged_decision::WizardKind;

    // WASM1 Phase 3c-compose-macro — types referenced by `#[compose]`
    // emission. `ComposeEntry` and its kind-tagged variants live in
    // `maat-sdk-traits::compose`; the macro emits a `&[ComposeEntry]`
    // slice and a `register_composes` inherent method that walks it.
    pub use maat_sdk::compose::{
        ComposeEntry, CreationComposeThunk, DistanceMetricThunk,
        LevelUpComposeThunk, WizardComposeThunk,
    };
    pub use maat_sdk::SetupContext;
    pub use maat_sdk_types::creation::{ComposeCtx, CreationHistory, CreationSpec};
    pub use maat_sdk_types::creation_registry::CreationSpecFn;
    pub use maat_sdk_types::level_up_registry::LevelUpSpecFn;
    pub use maat_sdk_types::composition_registry::{CompositionSpecFn, ComposeResult};
    pub use maat_sdk_types::distance::{DistanceError, MetricKey};
    pub use maat_sdk_types::staged_decision::ResolvedGroup;
    pub use maat_sdk_types::types::EntityId;
    pub use maat_sdk_types::board::BoardGraph;
    pub use maat_sdk_types::board::ids::FaceId;
}
