@almadar/core 10.21.0 → 10.23.0

package/dist/{schema-BEL2Gr4v.d.ts → builders-BjButZdb.d.ts}

@@ -1,6 +1,7 @@
-import { E as Expression, S as SExpr } from './expression-BUIi9ezJ.js';
-import { T as TraitConfig, l as TraitConfigObject, S as ServiceRef, d as Entity, f as EntityField, g as EntityPersistence, i as TraitRef, m as EventPayloadField, n as ConfigFieldDeclaration, o as ServiceDefinition, a as Trait } from './trait-BcRvHKLW.js';
+import { bS as TraitConfig, bT as TraitConfigObject, bk as ServiceRef, a2 as Entity, E as EntityField, a as EntityPersistence, c3 as TraitRef, ai as EventPayloadField, O as ConfigFieldDeclaration, bg as ServiceDefinition, d as Trait, cf as UISlot, Z as Effect, aZ as RenderBinding, a$ as RenderUIEffect, T as TraitEventListener, C as CallSiteConfig, b$ as TraitEventContract, e as EntityRow, b as TraitReference } from './trait-Cs8Mrdw9.js';
 import { z } from 'zod';
+import { d as Expression, S as SExpr } from './expression-BVRFm0sV.js';
+import { AnyPatternConfig } from '@almadar/patterns';
 
 /**
  * Page view types.
@@ -59279,4 +59280,582 @@ declare function safeParseOrbitalSchema(data: unknown): z.SafeParseReturnType<{
 type OrbitalSchemaInput = z.input<typeof OrbitalSchemaSchema>;
 type OrbitalConfigInput = z.input<typeof OrbitalConfigSchema>;
 
-export { type EntitySemanticRole as $, AGENT_DOMAIN_CATEGORIES as A, type DesignPreferencesInput as B, type ColorSlice as C, type DensitySlice as D, type EntityRef as E, DesignPreferencesSchema as F, type DesignTokens as G, type DesignTokensInput as H, DesignTokensSchema as I, type DomainCategory as J, DomainCategorySchema as K, type DomainContext as L, type DomainContextInput as M, DomainContextSchema as N, type OrbitalSchema as O, type PageRef as P, type DomainVocabulary as Q, DomainVocabularySchema as R, type ElevationSlice as S, ElevationSliceSchema as T, type UseDeclaration as U, type ElevationTokens as V, ElevationTokensSchema as W, type EntityCall as X, EntityCallSchema as Y, EntityRefSchema as Z, EntityRefStringSchema as _, type OrbitalDefinition as a, PageSchema as a$, EntitySemanticRoleSchema as a0, type EventListener as a1, EventListenerSchema as a2, type EventSemanticRole as a3, EventSemanticRoleSchema as a4, type EventSource as a5, EventSourceSchema as a6, type Orbital as a7, type GameSubCategory as a8, GameSubCategorySchema as a9, MotionIntentMapSchema as aA, MotionIntentSchema as aB, type MotionSlice as aC, MotionSliceSchema as aD, type MotionTokens as aE, MotionTokensSchema as aF, type NodeClassification as aG, NodeClassificationSchema as aH, type OrbitalConfig as aI, type OrbitalConfigInput as aJ, OrbitalConfigSchema as aK, OrbitalDefinitionSchema as aL, type OrbitalInput as aM, type OrbitalPage as aN, type OrbitalPageInput as aO, OrbitalPageSchema as aP, type OrbitalPageStrictInput as aQ, OrbitalPageStrictSchema as aR, type OrbitalSchemaInput as aS, OrbitalSchemaSchema as aT, type OrbitalSchemaWithTraits as aU, type OrbitalUnit as aV, OrbitalUnitSchema as aW, OrbitalSchema$1 as aX, PageRefObjectSchema as aY, PageRefSchema as aZ, PageRefStringSchema as a_, type GeometrySlice as aa, GeometrySliceSchema as ab, type GeometryTokens as ac, GeometryTokensSchema as ad, type IconFamily as ae, IconFamilySchema as af, type IconographySlice as ag, IconographySliceSchema as ah, type IconographyTokens as ai, IconographyTokensSchema as aj, type IllustrationSlice as ak, IllustrationSliceSchema as al, type IllustrationStyle as am, IllustrationStyleSchema as an, type IllustrationTokens as ao, IllustrationTokensSchema as ap, type MotionDurationKey as aq, MotionDurationKeySchema as ar, type MotionDurationPalette as as, MotionDurationPaletteSchema as at, type MotionEasingKey as au, MotionEasingKeySchema as av, type MotionEasingPalette as aw, MotionEasingPaletteSchema as ax, type MotionIntent as ay, type MotionIntentMap as az, type Page as b, type PageTraitRef as b0, PageTraitRefSchema as b1, type RelatedLink as b2, RelatedLinkSchema as b3, type SchemaMetadata as b4, SchemaMetadataSchema as b5, type SkinSpec as b6, SkinSpecSchema as b7, type SpacingScale as b8, SpacingScaleSchema as b9, TypeSliceSchema as bA, type TypeSlot as bB, TypeSlotSchema as bC, type TypeWeight as bD, TypeWeightSchema as bE, type UXHints as bF, UXHintsSchema as bG, UseDeclarationSchema as bH, type UserPersona as bI, type UserPersonaInput as bJ, UserPersonaSchema as bK, type ViewType as bL, ViewTypeSchema as bM, isEntityCall as bN, isEntityReference as bO, isEntityReferenceAny as bP, isImportedTraitRef as bQ, isOrbitalDefinition as bR, isPageReference as bS, isPageReferenceObject as bT, isPageReferenceString as bU, isThemeReference as bV, parseEntityRef as bW, parseImportedTraitRef as bX, parseOrbitalSchema as bY, parsePageRef as bZ, safeParseOrbitalSchema as b_, type StateSemanticRole as ba, StateSemanticRoleSchema as bb, type SuggestedGuard as bc, SuggestedGuardSchema as bd, type ThemeDefinition as be, ThemeDefinitionSchema as bf, type ThemeRef as bg, ThemeRefSchema as bh, ThemeRefStringSchema as bi, type ThemeTokens as bj, ThemeTokensSchema as bk, type ThemeVariant as bl, ThemeVariantSchema as bm, type TypeIntent as bn, type TypeIntentMap as bo, TypeIntentMapSchema as bp, TypeIntentSchema as bq, type TypeScale as br, type TypeScaleEntry as bs, TypeScaleEntrySchema as bt, TypeScaleSchema as bu, type TypeScaleTokens as bv, TypeScaleTokensSchema as bw, type TypeSizeKey as bx, TypeSizeKeySchema as by, type TypeSlice as bz, type PageRefObject as c, ALLOWED_CUSTOM_COMPONENTS as d, type AgentDomainCategory as e, AgentDomainCategorySchema as f, type AllowedCustomComponent as g, ColorSliceSchema as h, type ColorTokens as i, ColorTokensSchema as j, type ComputedEventContract as k, ComputedEventContractSchema as l, type ComputedEventListener as m, ComputedEventListenerSchema as n, type ConfigProvenanceRecord as o, ConfigProvenanceRecordSchema as p, type CustomPatternDefinition as q, type CustomPatternDefinitionInput as r, CustomPatternDefinitionSchema as s, type CustomPatternMap as t, type CustomPatternMapInput as u, CustomPatternMapSchema as v, DensitySliceSchema as w, type DensityTokens as x, DensityTokensSchema as y, type DesignPreferences as z };
+/**
+ * Event Wiring
+ *
+ * Applies cross-orbital event wiring to orbital definitions.
+ * Adds emits/listens declarations to traits so they can communicate
+ * across orbital boundaries.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A single event wiring entry connecting two traits across orbitals.
+ */
+interface EventWiringEntry {
+    /** Source trait name or orbital name */
+    from: string;
+    /** Event name (UPPER_SNAKE_CASE) */
+    event: string;
+    /** Target trait name or orbital name */
+    to: string;
+    /** Event to trigger on the listener side */
+    triggers: string;
+}
+/**
+ * Apply event wiring to orbital definitions.
+ *
+ * For each wiring entry:
+ * 1. Find the source trait and add an external emit (if not already present)
+ * 2. Find the target trait and add an external listen (if not already present)
+ *
+ * Returns a new array of orbitals with wiring applied (deep-cloned).
+ */
+declare function applyEventWiring(orbitals: OrbitalDefinition[], wiring: EventWiringEntry[]): OrbitalDefinition[];
+
+/**
+ * Layout Strategy Detection
+ *
+ * Auto-detects the best layout strategy for a composed application
+ * based on the number of orbitals and their event wiring topology.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Layout strategy for the composed application.
+ *
+ * - 'single': One orbital, one page
+ * - 'tabs': 2-4 orbitals with no sequential chain
+ * - 'sidebar': 5+ orbitals (navigation-heavy)
+ * - 'dashboard': Single page with all orbitals visible
+ * - 'wizard-flow': Sequential event chain detected (A -> B -> C)
+ */
+type LayoutStrategy = 'sidebar' | 'tabs' | 'dashboard' | 'wizard-flow' | 'single';
+/**
+ * Detect the best layout strategy based on orbital count and event wiring.
+ *
+ * Heuristic:
+ * 1. Sequential event chain detected -> 'wizard-flow'
+ * 2. 1 orbital -> 'single'
+ * 3. 2-4 orbitals -> 'tabs'
+ * 4. 5+ orbitals -> 'sidebar'
+ */
+declare function detectLayoutStrategy(orbitals: OrbitalDefinition[], eventWiring?: EventWiringEntry[]): LayoutStrategy;
+
+/**
+ * Compose Behaviors
+ *
+ * Main entry point for composing multiple orbital definitions into
+ * a single OrbitalSchema application. Handles event wiring, layout
+ * strategy detection, and page generation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Input for composing behaviors into an application.
+ */
+interface ComposeBehaviorsInput {
+    /** Application name */
+    appName: string;
+    /** Orbital definitions (or schemas) to compose */
+    orbitals: (OrbitalDefinition | OrbitalSchema)[];
+    /** Layout strategy override, or 'auto' to detect */
+    layoutStrategy?: LayoutStrategy | 'auto';
+    /** Cross-orbital event wiring */
+    eventWiring?: EventWiringEntry[];
+    /** Optional entity name mappings (original -> renamed) */
+    entityMappings?: Record<string, string>;
+}
+/**
+ * Result of composing behaviors.
+ */
+interface ComposeBehaviorsResult {
+    /** The composed OrbitalSchema */
+    schema: OrbitalSchema;
+    /** Layout metadata */
+    layout: {
+        strategy: LayoutStrategy;
+        pageCount: number;
+    };
+    /** Wiring metadata */
+    wiring: {
+        connections: number;
+    };
+}
+/**
+ * Compose multiple orbital definitions into a single application schema.
+ *
+ * Steps:
+ * 1. Apply event wiring (adds emits/listens to traits)
+ * 2. Detect or use provided layout strategy
+ * 3. Generate pages based on the strategy
+ * 4. Build the final OrbitalSchema
+ */
+declare function composeBehaviors(input: ComposeBehaviorsInput): ComposeBehaviorsResult;
+
+/**
+ * Apply trait config overrides to a schema — pure, returns a new schema.
+ *
+ * Used by config-driven preview surfaces (the playground property inspector and
+ * the verify config-sweep) to render a behavior with different `config` values
+ * WITHOUT recompiling: the override is written onto the matching trait, then the
+ * schema is re-registered and re-rendered.
+ *
+ * The resolved schema's traits are inlined `Trait`s whose `config` is the
+ * DECLARED schema (`{ field: { type, default, ... } }`), so an override patches
+ * each field's `default`. A trait that instead carries call-site value config
+ * (a `{ ref, config }` reference) gets the values merged directly.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Return a new schema with `config` overrides applied to traits whose identity
+ * (`name`, falling back to `ref`) matches a key in `overrides`. Fields not
+ * declared on the trait are ignored — overrides never invent config.
+ */
+declare function applyTraitConfigOverrides(schema: OrbitalSchema, overrides: Readonly<Record<string, TraitConfig>>): OrbitalSchema;
+
+/**
+ * Layout-Trait Builders
+ *
+ * Helpers for constructing the canonical inline LayoutTrait pattern that
+ * std layout-shell molecules (`std-filtered-list`, `std-master-detail-layout`,
+ * etc.) use to wrap a set of atom trait references in a `(render-ui main)`
+ * effect with `@trait.X` slot embeds.
+ *
+ * The canonical LayoutTrait is stateless: ONE state (`composing`, initial),
+ * ONE transition (`INIT` self-loop) carrying two effects — `(fetch Entity
+ * {emit: {success, failure}})` and `(render-ui "main" <pattern-tree>)`. Atoms
+ * embedded via `@trait.X` slot references react to the bus events the fetch
+ * emits; the LayoutTrait owns no further state.
+ *
+ * Usage from a std layout-shell molecule:
+ *
+ * ```ts
+ * import { makeSlot, makeLayoutTrait } from '@almadar/core/builders';
+ *
+ * const layout = makeLayoutTrait({
+ *   name: 'DashboardLayout',
+ *   linkedEntity: 'Metric',
+ *   fetchEntity: 'Metric',
+ *   loadedEvent: 'MetricLoaded',
+ *   loadFailedEvent: 'MetricLoadFailed',
+ *   renderUI: {
+ *     type: 'stack',
+ *     direction: 'vertical',
+ *     children: [
+ *       makeSlot('StatsRow'),
+ *       makeSlot('ChartsRow'),
+ *       makeSlot('FeedRow'),
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build a `@trait.<name>` slot reference string. Used as a child entry in a
+ * pattern tree to embed another trait's render-ui at that position. The
+ * runtime resolves `@trait.X` to the matching trait's render-ui inline.
+ *
+ * @example makeSlot('FilteredItemSearch') // "@trait.FilteredItemSearch"
+ */
+declare function makeSlot(traitName: string): string;
+/**
+ * Build a `(render-ui <slot> <root>)` effect tuple. Pattern-typed sugar over
+ * the raw `RenderUIEffect` literal so callers don't have to spell out the
+ * three-element tuple form.
+ *
+ * @param slot - Canonical UI slot name (`'main'`, `'header'`, etc. — see UI_SLOTS).
+ * @param root - The pattern config for this slot's content, OR a `@`-binding
+ *   string ({@link RenderBinding}) pointing at a render tree in `config` /
+ *   `payload` (e.g. `'@config.bodyContent'`). Pass `null` to clear.
+ */
+declare function makeRenderUI(slot: UISlot, root: AnyPatternConfig | RenderBinding | null): RenderUIEffect;
+/**
+ * Options for {@link makeLayoutTrait}.
+ */
+interface MakeLayoutTraitOpts {
+    /** Trait name, e.g. `"DashboardGridLayout"`. */
+    name: string;
+    /** Entity this layout's emits/listens bind to. */
+    linkedEntity: string;
+    /** Optional human-readable description (carried through to `Trait.description`). */
+    description?: string;
+    /**
+     * Entity name to fetch on INIT. When set, a `(fetch <Entity> {emit:
+     * {success, failure}})` effect is prepended to the INIT transition. Omit
+     * for purely-presentational layouts that don't load data themselves.
+     */
+    fetchEntity?: string;
+    /**
+     * Event name emitted on successful fetch. Required when `fetchEntity` is
+     * set; the LayoutTrait declares this event in its `emits` and uses it as
+     * the `success` emit-name in the fetch effect.
+     * Convention: `"<Entity>Loaded"`.
+     */
+    loadedEvent?: string;
+    /**
+     * Event name emitted on fetch failure. Required when `fetchEntity` is
+     * set. Convention: `"<Entity>LoadFailed"`.
+     */
+    loadFailedEvent?: string;
+    /**
+     * Payload schema for the loaded event. Defaults to `[{ name: "data", type:
+     * "[<Entity>]" }]` when `fetchEntity` is set. Provide explicitly when the
+     * payload should carry additional fields.
+     */
+    loadedPayloadSchema?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>;
+    /**
+     * The pattern tree for the layout's main slot. Children may include
+     * `@trait.X` slot strings (built via {@link makeSlot}) interleaved with
+     * inline pattern configs (`{ type: 'stack', ... }`). The shape conforms to
+     * `AnyPatternConfig` from `@almadar/patterns`.
+     */
+    renderUI: AnyPatternConfig;
+    /**
+     * Override the slot the render-ui effect targets. Defaults to `'main'`.
+     * Specify when the layout shell should render into a sub-slot (rare).
+     */
+    slot?: UISlot;
+    /**
+     * Additional effects appended to the INIT transition AFTER the fetch +
+     * render-ui pair. Most layouts don't need this; provided for advanced
+     * cases (analytics emit, persistence seed, etc.).
+     */
+    extraEffects?: Effect[];
+}
+/**
+ * Build the canonical stateless LayoutTrait used by std layout-shell molecules.
+ *
+ * Result shape:
+ * - `category: 'interaction'`, `scope: 'instance'`
+ * - `linkedEntity` set per the option
+ * - `emits` declares the loaded + loadFailed events when `fetchEntity` is set
+ * - One state: `'composing'` (`isInitial: true`)
+ * - One transition: `composing → composing` on `INIT`, with effects:
+ *   - (when `fetchEntity` set) `['fetch', '<Entity>', { emit: { success, failure } }]`
+ *   - `['render-ui', slot, renderUI]`
+ *   - …`extraEffects` if provided
+ *
+ * Atoms whose trait names appear as `@trait.<name>` strings inside `renderUI`
+ * get embedded by the runtime when the orbital instantiates. The LayoutTrait
+ * itself stays stateless — all reactive behaviour lives in the embedded atoms.
+ */
+declare function makeLayoutTrait(opts: MakeLayoutTraitOpts): Trait;
+
+/**
+ * Orbital Builders
+ *
+ * Pure functions for constructing and composing Orbitals.
+ * No new types. Everything uses existing core types:
+ * Entity, Trait, Page, OrbitalDefinition, OrbitalSchema.
+ *
+ * Three categories:
+ * 1. Builders: construct Entity, Page from common params
+ * 2. Utilities: ensureIdField, resolveDefaults
+ * 3. Composition: connect, compose, pipe
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Ensure the fields array has an `id` field. Prepends one if missing.
+ */
+declare function ensureIdField(fields?: EntityField[]): EntityField[];
+/**
+ * Simple pluralization: append 's'.
+ */
+declare function plural(name: string): string;
+interface MakeEntityOpts {
+    name: string;
+    fields: EntityField[];
+    persistence?: EntityPersistence;
+    collection?: string;
+    /** Pre-authored seed data instances */
+    instances?: EntityRow[];
+}
+/**
+ * Build an Entity from options. Auto-adds id field, auto-derives collection.
+ */
+declare function makeEntity(opts: MakeEntityOpts): Entity;
+interface MakePageOpts {
+    name: string;
+    path: string;
+    traitName: string;
+    isInitial?: boolean;
+}
+/**
+ * Build a Page that binds to a single trait.
+ */
+declare function makePage(opts: MakePageOpts): Page;
+/**
+ * Build an OrbitalDefinition from its three components.
+ */
+declare function makeOrbital(name: string, entity: Entity, traits: Trait[], pages: Page[]): OrbitalDefinition;
+/**
+ * Options for {@link makeTraitRef}.
+ */
+interface MakeTraitRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link TraitReference.from}).
+     */
+    from?: string;
+    /** Trait reference string, e.g. "Browse.traits.BrowseItemBrowse". */
+    ref: string;
+    /** Rename the inlined trait at the call site. */
+    name?: string;
+    /** Rebind the trait to a different linkedEntity. */
+    linkedEntity?: string;
+    /** Per-key rename map, e.g. `{ OPEN: "ADD_ITEM" }`. */
+    events?: Record<string, string>;
+    /**
+     * Entity-field remap, e.g. `{ name: "title", folder: "parentId" }`. Rewrites
+     * the inlined trait's canonical `@entity.X` / `@payload.row.X` references to
+     * the consumer entity's field names. Mirrors {@link TraitReference.fields}.
+     */
+    fields?: Record<string, string>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names. See {@link TraitReference.effects} for the full contract.
+     */
+    effects?: Record<string, SExpr[]>;
+    /** Replace the imported trait's `listens` array entirely. */
+    listens?: TraitEventListener[];
+    /** Set every emit's scope. */
+    emitsScope?: 'internal' | 'external';
+    /**
+     * Call-site config overrides. Each entry is either a plain wiring value
+     * (`TraitConfigValue`) or a fully-annotated re-declaration
+     * (`ConfigFieldDeclaration`). Matches {@link TraitReference.config}.
+     */
+    config?: CallSiteConfig;
+}
+/**
+ * Typed-narrowing variant of {@link MakeTraitRefOpts} for callers that know
+ * the imported atom's overridable surfaces — its event-key set, listen-key
+ * set, and config shape. Generated std factories use this variant so an LLM
+ * tool consumer (orbital-agent) sees the closed event-name set and the
+ * config field schema instead of the un-narrowed `Record<string, string>` /
+ * `TraitConfig` defaults.
+ *
+ * Type parameters:
+ * - `EventKey`   — string union of the atom's emit event names. Narrows the
+ *   `events` rename map's keys to legal originals only.
+ * - `ConfigShape` — typed shape of the trait's `config { ... }` block (literal
+ *   unions intact). Narrows the `config` override to the atom's actual fields.
+ *   Extends `CallSiteConfig` to allow both plain wiring values and annotated
+ *   declarations. Existing callers using plain `TraitConfig` shapes are
+ *   unaffected (TraitConfig ⊆ CallSiteConfig).
+ * - `ListenKey`  — string union of the atom's listen-key contract. Narrows
+ *   each listens entry's `event` against the atom's real subscription set.
+ *
+ * Runtime behavior is unchanged — {@link makeTraitRef} accepts both the
+ * narrow and wide forms via the standard structural-typing rules. This is
+ * a type-level narrowing only; widening at the call boundary is intentional.
+ */
+interface MakeTraitRefOptsTyped<EventKey extends string = string, ConfigShape extends CallSiteConfig = Record<string, never>, ListenKey extends string = string> extends Omit<MakeTraitRefOpts, 'events' | 'effects' | 'listens' | 'config'> {
+    /** Per-key rename map, narrowed to the atom's actual event keys. */
+    events?: Partial<Record<EventKey, string>>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names so they're caller-defined (no narrowing here); values stay typed
+     * as `SExpr[]`.
+     */
+    effects?: Partial<Record<string, SExpr[]>>;
+    /**
+     * Replace the imported trait's `listens` array entirely. Each entry's
+     * `event` field is narrowed to {@link ListenKey} where the atom's
+     * subscription set is fixed; otherwise this widens to plain string.
+     */
+    listens?: Array<TraitEventListener & {
+        event?: ListenKey;
+    }>;
+    /** Typed call-site config overrides — narrowed to {@link ConfigShape}. */
+    config?: ConfigShape;
+}
+/**
+ * Build a {@link TraitReference} from options.
+ *
+ * Pass-through factory: copies only the fields that are actually provided,
+ * so optionals stay absent (no `key: undefined` slots) and the emitted
+ * object matches the inliner's expectation that "present = override".
+ */
+declare function makeTraitRef(opts: MakeTraitRefOpts): TraitReference;
+/**
+ * Options for {@link makePageRef}.
+ */
+interface MakePageRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link PageRefObject.from}).
+     */
+    from?: string;
+    /** Page reference string, e.g. "Browse.pages.BrowseItemPage". */
+    ref: string;
+    /** URL path override. */
+    path?: string;
+    /** Rebind the page's primary entity. */
+    linkedEntity?: string;
+    /** Replace the page's trait list. */
+    traits?: TraitRef[];
+}
+/**
+ * Typed-narrowing variant of {@link MakePageRefOpts}. Narrows the `traits`
+ * override array's entries to the orbital's known trait-name union — so the
+ * agent can't pass a trait name that doesn't exist on the page's owning
+ * orbital. Generated std page-helpers use this variant to surface the
+ * trait set in the tool schema; un-narrowed call sites stay compatible.
+ *
+ * Type parameter:
+ * - `TraitName` — string union of trait names the page may reference.
+ */
+interface MakePageRefOptsTyped<TraitName extends string = string> extends Omit<MakePageRefOpts, 'traits'> {
+    traits?: Array<{
+        ref: TraitName;
+    } | TraitRef>;
+}
+/**
+ * Build a {@link PageRefObject} from options. Pass-through factory — omits
+ * optional keys that are `undefined`.
+ */
+declare function makePageRef(opts: MakePageRefOpts): PageRefObject;
+/**
+ * Options for {@link makeOrbitalWithUses}.
+ */
+interface MakeOrbitalWithUsesOpts {
+    /** Orbital name. */
+    name: string;
+    /**
+     * Per-orbital `uses:` header entries (see CLAUDE.md "uses: lives inside
+     * the orbital").
+     */
+    uses: UseDeclaration[];
+    /** Entity (inline or reference form). */
+    entity: EntityRef;
+    /** Trait references. */
+    traits: TraitRef[];
+    /** Optional page references (omitted entirely when not provided). */
+    pages?: PageRef[];
+}
+/**
+ * Build an {@link OrbitalDefinition} with the `uses:` header set. Follows
+ * the convention that `uses:` lives on the orbital (not the schema).
+ *
+ * When `pages` is omitted, the result has no `pages` property (matches the
+ * existing {@link OrbitalDefinition.pages} optionality in descriptors that
+ * carry trait-only atoms).
+ */
+declare function makeOrbitalWithUses(opts: MakeOrbitalWithUsesOpts): OrbitalDefinition;
+/**
+ * Options for {@link makeAtomOrbital}.
+ *
+ * Overrides for the single trait reference. Mirrors the {@link MakeTraitRefOpts}
+ * subset that is meaningful at the atom-wrapping call site.
+ */
+interface MakeAtomOrbitalTraitOverrides {
+    name?: string;
+    events?: Record<string, string>;
+    effects?: Record<string, SExpr[]>;
+    listens?: TraitEventListener[];
+    emitsScope?: 'internal' | 'external';
+    config?: CallSiteConfig;
+}
+/**
+ * Options for {@link makeAtomOrbital}.
+ */
+interface MakeAtomOrbitalOpts {
+    /** Orbital name, e.g. `${entityName}Orbital`. */
+    name: string;
+    /** Atom registry path, e.g. `std/behaviors/atoms/std-browse`. */
+    atomPath: string;
+    /** Import alias (PascalCase), e.g. `Browse`. */
+    alias: string;
+    /** Entity definition to attach to the orbital. */
+    entity: Entity;
+    /** Trait reference string, e.g. `Browse.traits.BrowseItemBrowse`. */
+    traitRef: string;
+    /** Optional trait-level overrides applied at the call site. */
+    traitOverrides?: MakeAtomOrbitalTraitOverrides;
+    /** Optional page reference string, e.g. `Browse.pages.BrowseItemPage`. */
+    pageRef?: string;
+    /** Optional page-level overrides applied at the call site. */
+    pageOverrides?: {
+        path?: string;
+    };
+}
+/**
+ * Build a single-atom {@link OrbitalDefinition}.
+ *
+ * The common atom shape: one entity + one trait reference + (optionally) one
+ * page reference, all under a single `uses:` import. Wraps
+ * {@link makeTraitRef}, {@link makePageRef}, and {@link makeOrbitalWithUses}.
+ *
+ * The trait reference is linkedEntity-bound to `entity.name` by default so
+ * that the inliner's entity-substitution pass rewrites every `["ref", X]`
+ * and `@X.path` reference inside the atom.
+ */
+declare function makeAtomOrbital(opts: MakeAtomOrbitalOpts): OrbitalDefinition;
+/**
+ * Wrap one or more OrbitalDefinitions into an OrbitalSchema.
+ * Every .orb file should be a full OrbitalSchema — this is the builder for that.
+ */
+declare function makeSchema(name: string, ...definitions: OrbitalDefinition[]): OrbitalSchema;
+/**
+ * Merge multiple OrbitalDefinitions into one.
+ * Collects all traits from all sources into a single orbital with a shared entity.
+ * Pure: clones all traits, no mutation.
+ */
+declare function mergeOrbitals(name: string, entity: Entity, sources: OrbitalDefinition[], pages: Page[]): OrbitalDefinition;
+/**
+ * Wire an intra-orbital event between two traits.
+ * Adds emits to the source trait, listens to the target trait.
+ * Pure: returns cloned traits, no mutation.
+ */
+declare function wire(source: Trait, target: Trait, event: TraitEventContract, triggers: string): [Trait, Trait];
+/**
+ * Extract the first trait from an OrbitalDefinition or OrbitalSchema.
+ * If given an OrbitalSchema, unwraps to the first orbital inside it.
+ */
+declare function extractTrait(input: OrbitalDefinition | OrbitalSchema): Trait;
+/**
+ * Wire a cross-orbital event between two orbitals.
+ * Adds emits to a's first trait, listens to b's first trait.
+ * Pure: returns new orbitals, no mutation.
+ */
+declare function connect(a: OrbitalDefinition | OrbitalSchema, b: OrbitalDefinition | OrbitalSchema, event: TraitEventContract, triggers?: string): [OrbitalDefinition, OrbitalDefinition];
+interface ComposeConnection {
+    from: string;
+    to: string;
+    event: TraitEventContract;
+    triggers?: string;
+}
+interface ComposePage {
+    name: string;
+    path: string;
+    traits: string[];
+    isInitial?: boolean;
+}
+/**
+ * Compose multiple orbitals into a single OrbitalSchema (application).
+ * Applies connections (cross-orbital event wiring) and page assignments.
+ */
+declare function compose(orbitals: (OrbitalDefinition | OrbitalSchema)[], pages: ComposePage[], connections: ComposeConnection[], appName?: string): OrbitalSchema;
+/**
+ * Chain orbitals in sequence with automatic event wiring.
+ * Sugar over connect + compose: wires events[0] from orbital[0] to orbital[1], etc.
+ */
+declare function pipe(orbitals: (OrbitalDefinition | OrbitalSchema)[], events: TraitEventContract[], appName?: string): OrbitalSchema;
+
+export { EntitySemanticRoleSchema as $, AGENT_DOMAIN_CATEGORIES as A, type DesignPreferencesInput as B, type ColorSlice as C, type DensitySlice as D, DesignPreferencesSchema as E, type DesignTokens as F, type DesignTokensInput as G, DesignTokensSchema as H, type DomainCategory as I, DomainCategorySchema as J, type DomainContext as K, type DomainContextInput as L, type MakeTraitRefOpts as M, DomainContextSchema as N, type OrbitalSchema as O, type DomainVocabulary as P, DomainVocabularySchema as Q, type ElevationSlice as R, ElevationSliceSchema as S, type ElevationTokens as T, ElevationTokensSchema as U, type EntityCall as V, EntityCallSchema as W, type EntityRef as X, EntityRefSchema as Y, EntityRefStringSchema as Z, type EntitySemanticRole as _, type OrbitalDefinition as a, type PageRefObject as a$, type EventListener as a0, EventListenerSchema as a1, type EventSemanticRole as a2, EventSemanticRoleSchema as a3, type EventSource as a4, EventSourceSchema as a5, type EventWiringEntry as a6, type Orbital as a7, type GameSubCategory as a8, GameSubCategorySchema as a9, type MotionIntentMap as aA, MotionIntentMapSchema as aB, MotionIntentSchema as aC, type MotionSlice as aD, MotionSliceSchema as aE, type MotionTokens as aF, MotionTokensSchema as aG, type NodeClassification as aH, NodeClassificationSchema as aI, type OrbitalConfig as aJ, type OrbitalConfigInput as aK, OrbitalConfigSchema as aL, OrbitalDefinitionSchema as aM, type OrbitalInput as aN, type OrbitalPage as aO, type OrbitalPageInput as aP, OrbitalPageSchema as aQ, type OrbitalPageStrictInput as aR, OrbitalPageStrictSchema as aS, type OrbitalSchemaInput as aT, OrbitalSchemaSchema as aU, type OrbitalSchemaWithTraits as aV, type OrbitalUnit as aW, OrbitalUnitSchema as aX, OrbitalSchema$1 as aY, type Page as aZ, type PageRef as a_, type GeometrySlice as aa, GeometrySliceSchema as ab, type GeometryTokens as ac, GeometryTokensSchema as ad, type IconFamily as ae, IconFamilySchema as af, type IconographySlice as ag, IconographySliceSchema as ah, type IconographyTokens as ai, IconographyTokensSchema as aj, type IllustrationSlice as ak, IllustrationSliceSchema as al, type IllustrationStyle as am, IllustrationStyleSchema as an, type IllustrationTokens as ao, IllustrationTokensSchema as ap, type LayoutStrategy as aq, type MotionDurationKey as ar, MotionDurationKeySchema as as, type MotionDurationPalette as at, MotionDurationPaletteSchema as au, type MotionEasingKey as av, MotionEasingKeySchema as aw, type MotionEasingPalette as ax, MotionEasingPaletteSchema as ay, type MotionIntent as az, ALLOWED_CUSTOM_COMPONENTS as b, isPageReferenceObject as b$, PageRefObjectSchema as b0, PageRefSchema as b1, PageRefStringSchema as b2, PageSchema as b3, type PageTraitRef as b4, PageTraitRefSchema as b5, type RelatedLink as b6, RelatedLinkSchema as b7, type SchemaMetadata as b8, SchemaMetadataSchema as b9, TypeScaleTokensSchema as bA, type TypeSizeKey as bB, TypeSizeKeySchema as bC, type TypeSlice as bD, TypeSliceSchema as bE, type TypeSlot as bF, TypeSlotSchema as bG, type TypeWeight as bH, TypeWeightSchema as bI, type UXHints as bJ, UXHintsSchema as bK, type UseDeclaration as bL, UseDeclarationSchema as bM, type UserPersona as bN, type UserPersonaInput as bO, UserPersonaSchema as bP, type ViewType as bQ, ViewTypeSchema as bR, applyEventWiring as bS, composeBehaviors as bT, detectLayoutStrategy as bU, isEntityCall as bV, isEntityReference as bW, isEntityReferenceAny as bX, isImportedTraitRef as bY, isOrbitalDefinition as bZ, isPageReference as b_, type SkinSpec as ba, SkinSpecSchema as bb, type SpacingScale as bc, SpacingScaleSchema as bd, type StateSemanticRole as be, StateSemanticRoleSchema as bf, type SuggestedGuard as bg, SuggestedGuardSchema as bh, type ThemeDefinition as bi, ThemeDefinitionSchema as bj, type ThemeRef as bk, ThemeRefSchema as bl, ThemeRefStringSchema as bm, type ThemeTokens as bn, ThemeTokensSchema as bo, type ThemeVariant as bp, ThemeVariantSchema as bq, type TypeIntent as br, type TypeIntentMap as bs, TypeIntentMapSchema as bt, TypeIntentSchema as bu, type TypeScale as bv, type TypeScaleEntry as bw, TypeScaleEntrySchema as bx, TypeScaleSchema as by, type TypeScaleTokens as bz, type AgentDomainCategory as c, isPageReferenceString as c0, isThemeReference as c1, parseEntityRef as c2, parseImportedTraitRef as c3, parseOrbitalSchema as c4, parsePageRef as c5, safeParseOrbitalSchema as c6, type ComposeConnection as c7, type ComposePage as c8, type MakeAtomOrbitalOpts as c9, plural as cA, wire as cB, type MakeAtomOrbitalTraitOverrides as ca, type MakeEntityOpts as cb, type MakeLayoutTraitOpts as cc, type MakeOrbitalWithUsesOpts as cd, type MakePageOpts as ce, type MakePageRefOpts as cf, type MakePageRefOptsTyped as cg, type MakeTraitRefOptsTyped as ch, applyTraitConfigOverrides as ci, compose as cj, connect as ck, ensureIdField as cl, extractTrait as cm, makeAtomOrbital as cn, makeEntity as co, makeLayoutTrait as cp, makeOrbital as cq, makeOrbitalWithUses as cr, makePage as cs, makePageRef as ct, makeRenderUI as cu, makeSchema as cv, makeSlot as cw, makeTraitRef as cx, mergeOrbitals as cy, pipe as cz, AgentDomainCategorySchema as d, type AllowedCustomComponent as e, ColorSliceSchema as f, type ColorTokens as g, ColorTokensSchema as h, type ComposeBehaviorsInput as i, type ComposeBehaviorsResult as j, type ComputedEventContract as k, ComputedEventContractSchema as l, type ComputedEventListener as m, ComputedEventListenerSchema as n, type ConfigProvenanceRecord as o, ConfigProvenanceRecordSchema as p, type CustomPatternDefinition as q, type CustomPatternDefinitionInput as r, CustomPatternDefinitionSchema as s, type CustomPatternMap as t, type CustomPatternMapInput as u, CustomPatternMapSchema as v, DensitySliceSchema as w, type DensityTokens as x, DensityTokensSchema as y, type DesignPreferences as z };