@pie-players/pie-assessment-toolkit 0.3.30 → 0.3.32

package/dist/runtime/SectionRuntimeEngine.d.ts

@@ -1,7 +1,73 @@
+/**
+ * Section runtime engine — public facade (M7 — Variant C, layered).
+ *
+ * The facade is the narrow, stable entry point hosts use to mount,
+ * drive, and dispose a section runtime. It composes three layers
+ * introduced in earlier M7 PRs:
+ *
+ *   - the **registry** (`RuntimeRegistry`) — registered item/passage
+ *     shells in document order, used for canonical-id lookup;
+ *   - the **adapter** (`SectionEngineAdapter`) — single I/O seam over
+ *     the pure FSM core, fanning outputs to the DOM, framework-error
+ *     bus, legacy events, instrumentation hook, and host subscribers;
+ *   - the **resolver** (`resolveSectionEngineRuntimeState`) — the
+ *     toolkit-side resolution helper that produces the effective
+ *     runtime + tools snapshot a host feeds to the FSM core.
+ *
+ * **Two callsite generations.** During the M7 migration window the
+ * facade carries two surface generations side-by-side:
+ *
+ *   1. The **engine-side** surface (`attachHost`, `dispatchInput`,
+ *      `subscribe`, `getState`, `getEffectiveRuntime`,
+ *      `setInstrumentationHook`). This is what the kernel and the
+ *      `pie-assessment-toolkit` CE will switch onto in M7 PR 5 and
+ *      PR 6. Construction is lazy: `attachHost(...)` builds the
+ *      adapter on first call, with the supplied host element,
+ *      framework-error bus, and (optional) coordinator. After
+ *      construction, host re-attachments (e.g. cohort change with a
+ *      new layout shell) update the adapter's host element via
+ *      `setHost(...)`.
+ *
+ *   2. The **legacy controller-side** surface (`initialize`,
+ *      `register`, `unregister`, `handleContent*`, `updateItemSession`,
+ *      `navigateToItem`, `persist`, `hydrate`, `dispose`). The
+ *      `PieAssessmentToolkit.svelte` CE still drives the seed via this
+ *      surface in PR 3 — observable behavior is identical to pre-PR 3.
+ *      PR 6 deletes the toolkit's reliance on this surface; PR 7
+ *      removes the methods that the engine FSM has fully absorbed.
+ *
+ * The two surfaces share `RuntimeRegistry` (the only piece both
+ * generations consult) and the resolved `SectionControllerHandle` the
+ * legacy generation holds inline. The adapter holds its own
+ * `coordinator-bridge` independently — the legacy `initialize(...)` and
+ * the engine-side `dispatchInput({ kind: "initialize" })` do **not**
+ * fight over the coordinator because PR 3 only activates one of them
+ * per host (legacy from the toolkit CE, engine-side from the PR 5+
+ * tests and the kernel/toolkit switches).
+ *
+ * **Why the legacy surface stays.** The plan's PR-3 acceptance criterion
+ * is "existing toolkit tests still pass; no section-player or toolkit
+ * CE code changes yet" — so PR 3 cannot delete the controller-side
+ * methods. PR 6 (toolkit switch) and PR 7 (rip-out) will remove them
+ * once the engine surface is the only consumer.
+ */
 import type { ToolkitCoordinator } from "../services/ToolkitCoordinator.js";
+import type { FrameworkErrorReporter } from "../services/framework-error-bus.js";
 import type { SectionControllerEvent, SectionControllerHandle } from "../services/section-controller-types.js";
+import { type SectionEngineAdapterOptions } from "./adapter/SectionEngineAdapter.js";
+import type { InstrumentationHook } from "./adapter/instrumentation-bridge.js";
+import type { EngineOutputListener } from "./adapter/subscriber-fanout.js";
+import type { SectionEngineInput } from "./core/engine-input.js";
+import type { SectionEngineOutput } from "./core/engine-output.js";
+import { type EffectiveRuntime, type RuntimeInputs } from "./core/engine-resolver.js";
+import { type SectionEngineState } from "./core/engine-state.js";
 import type { RuntimeRegistrationDetail } from "./registration-events.js";
 import { RuntimeRegistry } from "./RuntimeRegistry.js";
+/**
+ * Structural view of the resolved section controller, widened with the
+ * extra methods the toolkit's runtime CE calls directly. Optional so
+ * stub controllers used in tests do not need every entry point.
+ */
 interface RuntimeController extends SectionControllerHandle {
     getCompositionModel?: () => unknown;
     getCanonicalItemId?: (itemId: string) => string;
@@ -43,6 +109,12 @@ interface RuntimeController extends SectionControllerHandle {
     subscribe?: (listener: (event: SectionControllerEvent) => void) => () => void;
     navigateToItem?: (index: number) => unknown;
 }
+/**
+ * Legacy initialize args. Pre-PR 6 callers (the toolkit CE) drive the
+ * coordinator + section controller through this method. PR 6 will
+ * delete this in favor of the engine-side `attachHost` +
+ * `dispatchInput({ kind: "initialize" })` flow.
+ */
 interface EngineInitArgs {
     coordinator: ToolkitCoordinator;
     section: unknown;
@@ -53,14 +125,87 @@ interface EngineInitArgs {
     createDefaultController: () => Promise<RuntimeController> | RuntimeController;
     onCompositionChanged?: (composition: unknown) => void;
 }
+/**
+ * Engine-side `attachHost` args. The host element, framework-error bus,
+ * and `sourceCe` together let the adapter dispatch DOM events and bus
+ * fan-outs identically to the legacy kernel emit chain.
+ */
+export interface SectionRuntimeEngineHostArgs {
+    host: EventTarget;
+    sourceCe: string;
+    frameworkErrorBus: FrameworkErrorReporter;
+    coordinator?: SectionEngineAdapterOptions["coordinator"];
+    instrumentationHook?: InstrumentationHook;
+    now?: () => string;
+}
 export declare class SectionRuntimeEngine {
     private readonly registry;
+    private readonly runtimeId;
+    private adapter;
     private controller;
     private coordinator;
     private sectionId;
     private attemptId;
     private unsubscribeController;
     private activeInitToken;
+    /**
+     * Attach the host element + framework-error bus + sourceCe so the
+     * adapter can dispatch DOM events and bus errors. Required before
+     * `dispatchInput` / `subscribe` produce observable effects.
+     *
+     * Constructs the adapter on the first call. Subsequent calls keep
+     * the adapter and update its host element / instrumentation hook
+     * (used by layout-shell rollovers and instrumentation reconfig).
+     */
+    attachHost(args: SectionRuntimeEngineHostArgs): void;
+    /**
+     * Forward a host-constructed input to the FSM core via the adapter.
+     * Returns the outputs the transition produced (subscribers and the
+     * DOM/legacy/framework-error/instrumentation bridges have already
+     * received them).
+     *
+     * No-op (returns `[]`) before `attachHost(...)` so callers that
+     * dispatch optimistically during teardown do not throw.
+     */
+    dispatchInput(input: SectionEngineInput): readonly SectionEngineOutput[];
+    /**
+     * Subscribe to batched engine outputs (one batch per
+     * `dispatchInput`). Returns an idempotent disposer. Pre-`attachHost`
+     * subscriptions return a no-op disposer so callers can wire
+     * subscriptions early without lifecycle-ordering hazards.
+     */
+    subscribe(listener: EngineOutputListener): () => void;
+    /**
+     * Read-only snapshot of the FSM state. Returns the initial idle
+     * state before `attachHost` so callers can probe state without
+     * special-casing the pre-attach phase.
+     */
+    getState(): Readonly<SectionEngineState>;
+    /**
+     * Resolve the effective runtime + tools snapshot for the given
+     * two-tier inputs. This is a pure function over the resolver — it
+     * does not depend on adapter state — so callers can use it both
+     * pre- and post-`attachHost`. The kernel uses it to seed
+     * `dispatchInput({ kind: "initialize", effectiveRuntime, ... })`.
+     */
+    getEffectiveRuntime<P>(args: RuntimeInputs, deps: {
+        resolvePlayerRuntime: (resolverArgs: {
+            effectiveRuntime: Record<string, unknown>;
+            playerType: string;
+            env: Record<string, unknown> | null;
+        }) => P;
+    }): EffectiveRuntime;
+    /**
+     * Update the adapter's instrumentation hook. No-op pre-attach.
+     * Hosts that always want a hook should pass it via `attachHost`.
+     */
+    setInstrumentationHook(hook: InstrumentationHook | undefined): void;
+    /**
+     * Stable per-engine runtime id used to scope DOM-event details and
+     * registry telemetry. Exposed so tests and instrumentation can pin
+     * the value the bridges emit.
+     */
+    getRuntimeId(): string;
     initialize(args: EngineInitArgs): Promise<void>;
     register(detail: RuntimeRegistrationDetail): boolean;
     unregister(element: HTMLElement): boolean;

package/dist/runtime/SectionRuntimeEngine.d.ts.map

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

package/dist/runtime/SectionRuntimeEngine.js

@@ -1,12 +1,162 @@
+/**
+ * Section runtime engine — public facade (M7 — Variant C, layered).
+ *
+ * The facade is the narrow, stable entry point hosts use to mount,
+ * drive, and dispose a section runtime. It composes three layers
+ * introduced in earlier M7 PRs:
+ *
+ *   - the **registry** (`RuntimeRegistry`) — registered item/passage
+ *     shells in document order, used for canonical-id lookup;
+ *   - the **adapter** (`SectionEngineAdapter`) — single I/O seam over
+ *     the pure FSM core, fanning outputs to the DOM, framework-error
+ *     bus, legacy events, instrumentation hook, and host subscribers;
+ *   - the **resolver** (`resolveSectionEngineRuntimeState`) — the
+ *     toolkit-side resolution helper that produces the effective
+ *     runtime + tools snapshot a host feeds to the FSM core.
+ *
+ * **Two callsite generations.** During the M7 migration window the
+ * facade carries two surface generations side-by-side:
+ *
+ *   1. The **engine-side** surface (`attachHost`, `dispatchInput`,
+ *      `subscribe`, `getState`, `getEffectiveRuntime`,
+ *      `setInstrumentationHook`). This is what the kernel and the
+ *      `pie-assessment-toolkit` CE will switch onto in M7 PR 5 and
+ *      PR 6. Construction is lazy: `attachHost(...)` builds the
+ *      adapter on first call, with the supplied host element,
+ *      framework-error bus, and (optional) coordinator. After
+ *      construction, host re-attachments (e.g. cohort change with a
+ *      new layout shell) update the adapter's host element via
+ *      `setHost(...)`.
+ *
+ *   2. The **legacy controller-side** surface (`initialize`,
+ *      `register`, `unregister`, `handleContent*`, `updateItemSession`,
+ *      `navigateToItem`, `persist`, `hydrate`, `dispose`). The
+ *      `PieAssessmentToolkit.svelte` CE still drives the seed via this
+ *      surface in PR 3 — observable behavior is identical to pre-PR 3.
+ *      PR 6 deletes the toolkit's reliance on this surface; PR 7
+ *      removes the methods that the engine FSM has fully absorbed.
+ *
+ * The two surfaces share `RuntimeRegistry` (the only piece both
+ * generations consult) and the resolved `SectionControllerHandle` the
+ * legacy generation holds inline. The adapter holds its own
+ * `coordinator-bridge` independently — the legacy `initialize(...)` and
+ * the engine-side `dispatchInput({ kind: "initialize" })` do **not**
+ * fight over the coordinator because PR 3 only activates one of them
+ * per host (legacy from the toolkit CE, engine-side from the PR 5+
+ * tests and the kernel/toolkit switches).
+ *
+ * **Why the legacy surface stays.** The plan's PR-3 acceptance criterion
+ * is "existing toolkit tests still pass; no section-player or toolkit
+ * CE code changes yet" — so PR 3 cannot delete the controller-side
+ * methods. PR 6 (toolkit switch) and PR 7 (rip-out) will remove them
+ * once the engine surface is the only consumer.
+ */
+import { SectionEngineAdapter, } from "./adapter/SectionEngineAdapter.js";
+import { resolveSectionEngineRuntimeState, } from "./core/engine-resolver.js";
+import { createInitialEngineState, } from "./core/engine-state.js";
 import { RuntimeRegistry } from "./RuntimeRegistry.js";
+import { createRuntimeId } from "./runtime-id.js";
 export class SectionRuntimeEngine {
     registry = new RuntimeRegistry();
+    runtimeId = createRuntimeId("section-engine");
+    // Engine-side state (PR 3+).
+    adapter = null;
+    // Legacy controller-side state (until PR 6).
     controller = null;
     coordinator = null;
     sectionId = "";
     attemptId;
     unsubscribeController = null;
     activeInitToken = 0;
+    // ============================================================
+    // Engine-side surface (PR 3+; driven by the kernel from PR 5,
+    // by the toolkit CE from PR 6, and by the facade smoke test today).
+    // ============================================================
+    /**
+     * Attach the host element + framework-error bus + sourceCe so the
+     * adapter can dispatch DOM events and bus errors. Required before
+     * `dispatchInput` / `subscribe` produce observable effects.
+     *
+     * Constructs the adapter on the first call. Subsequent calls keep
+     * the adapter and update its host element / instrumentation hook
+     * (used by layout-shell rollovers and instrumentation reconfig).
+     */
+    attachHost(args) {
+        if (this.adapter) {
+            this.adapter.setHost(args.host);
+            if (args.instrumentationHook !== undefined) {
+                this.adapter.setInstrumentationHook(args.instrumentationHook);
+            }
+            return;
+        }
+        this.adapter = new SectionEngineAdapter({
+            host: args.host,
+            runtimeId: this.runtimeId,
+            sourceCe: args.sourceCe,
+            frameworkErrorBus: args.frameworkErrorBus,
+            coordinator: args.coordinator,
+            instrumentationHook: args.instrumentationHook,
+            now: args.now,
+        });
+    }
+    /**
+     * Forward a host-constructed input to the FSM core via the adapter.
+     * Returns the outputs the transition produced (subscribers and the
+     * DOM/legacy/framework-error/instrumentation bridges have already
+     * received them).
+     *
+     * No-op (returns `[]`) before `attachHost(...)` so callers that
+     * dispatch optimistically during teardown do not throw.
+     */
+    dispatchInput(input) {
+        return this.adapter?.dispatchInput(input) ?? [];
+    }
+    /**
+     * Subscribe to batched engine outputs (one batch per
+     * `dispatchInput`). Returns an idempotent disposer. Pre-`attachHost`
+     * subscriptions return a no-op disposer so callers can wire
+     * subscriptions early without lifecycle-ordering hazards.
+     */
+    subscribe(listener) {
+        return this.adapter?.subscribe(listener) ?? noopDispose;
+    }
+    /**
+     * Read-only snapshot of the FSM state. Returns the initial idle
+     * state before `attachHost` so callers can probe state without
+     * special-casing the pre-attach phase.
+     */
+    getState() {
+        return this.adapter?.getState() ?? createInitialEngineState();
+    }
+    /**
+     * Resolve the effective runtime + tools snapshot for the given
+     * two-tier inputs. This is a pure function over the resolver — it
+     * does not depend on adapter state — so callers can use it both
+     * pre- and post-`attachHost`. The kernel uses it to seed
+     * `dispatchInput({ kind: "initialize", effectiveRuntime, ... })`.
+     */
+    getEffectiveRuntime(args, deps) {
+        return resolveSectionEngineRuntimeState(args, deps).effectiveRuntime;
+    }
+    /**
+     * Update the adapter's instrumentation hook. No-op pre-attach.
+     * Hosts that always want a hook should pass it via `attachHost`.
+     */
+    setInstrumentationHook(hook) {
+        this.adapter?.setInstrumentationHook(hook);
+    }
+    /**
+     * Stable per-engine runtime id used to scope DOM-event details and
+     * registry telemetry. Exposed so tests and instrumentation can pin
+     * the value the bridges emit.
+     */
+    getRuntimeId() {
+        return this.runtimeId;
+    }
+    // ============================================================
+    // Legacy controller-side surface (kept until PR 6; behavior
+    // identical to pre-PR 3).
+    // ============================================================
     async initialize(args) {
         this.activeInitToken += 1;
         const token = this.activeInitToken;
@@ -30,9 +180,10 @@ export class SectionRuntimeEngine {
         this.unsubscribeController?.();
         this.controller = resolved;
         args.onCompositionChanged?.(resolved.getCompositionModel?.());
-        this.unsubscribeController = resolved.subscribe?.(() => {
-            args.onCompositionChanged?.(resolved.getCompositionModel?.());
-        }) || null;
+        this.unsubscribeController =
+            resolved.subscribe?.(() => {
+                args.onCompositionChanged?.(resolved.getCompositionModel?.());
+            }) || null;
     }
     register(detail) {
         return this.registry.register(detail);
@@ -99,6 +250,16 @@ export class SectionRuntimeEngine {
         this.registry.clear();
         this.controller = null;
         this.coordinator = null;
+        // Tear down the engine-side adapter (if attached) last so any
+        // `dispose` FSM input flows through the bridges before they
+        // detach. Adapter disposal is idempotent and safe even when
+        // nothing is attached.
+        if (this.adapter) {
+            const adapter = this.adapter;
+            this.adapter = null;
+            await adapter.dispose();
+        }
     }
 }
+const noopDispose = () => { };
 //# sourceMappingURL=SectionRuntimeEngine.js.map

package/dist/runtime/SectionRuntimeEngine.js.map

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

package/dist/runtime/adapter/SectionEngineAdapter.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Section runtime engine adapter (M7 — Variant C, layered).
+ *
+ * The adapter is the single I/O seam between the pure FSM core
+ * (`SectionEngineCore`) and the rest of the world (DOM, coordinator,
+ * framework-error bus, host subscribers, instrumentation). It does
+ * exactly two jobs:
+ *
+ *   1. Translate **host inputs** (from kernels, the toolkit CE, or
+ *      direct facade callers) into `SectionEngineInput`s and forward
+ *      them to the core via `core.dispatch(input)`.
+ *
+ *   2. Subscribe to the core's output stream and **route each output**
+ *      through the bridges in a deterministic order so the public DOM
+ *      surface, framework-error bus, instrumentation hook, and host
+ *      subscribers all see exactly the same fan-out with
+ *      byte-identical detail shapes.
+ *
+ * Output routing is a single exhaustive `switch` (`assertNever` on
+ * the default branch) so adding a new `SectionEngineOutput` kind in
+ * `engine-output.ts` is a compile error here until the adapter knows
+ * what to do with it.
+ *
+ * **Routing order per output:**
+ *   - canonical DOM event (`pie-stage-change`, `pie-loading-complete`,
+ *     `framework-error`)
+ *   - framework-error bus (single fan-out for in-process subscribers)
+ *   - instrumentation hook
+ *   - public subscriber fan-out (batched, runs once per
+ *     `core.dispatch`)
+ *
+ * The deprecated `readiness-change` / `interaction-ready` / `ready`
+ * DOM events and their `legacy-event-bridge.ts` were removed in the
+ * broad architecture review compat sweep; the corresponding output
+ * kinds are gone from `engine-output.ts`.
+ *
+ * **Layering constraint.** The adapter is plain TS. It must not
+ * import `svelte` — the M7 implementation plan and
+ * `scripts/check-engine-core-purity.mjs` enforce the core's purity;
+ * the adapter follows the same constraint by convention so it stays
+ * usable from non-Svelte hosts (Node tests, Storybook, or future
+ * non-Svelte consumers). `bun run check:custom-elements` already
+ * blocks `.svelte` imports in published `dist`; adding a Svelte
+ * dependency here would also leak through that gate.
+ */
+import type { FrameworkErrorReporter } from "../../services/framework-error-bus.js";
+import { SectionEngineCore } from "../core/SectionEngineCore.js";
+import type { SectionEngineInput } from "../core/engine-input.js";
+import type { SectionEngineOutput } from "../core/engine-output.js";
+import type { SectionEngineState } from "../core/engine-state.js";
+import { type CoordinatorPort, type ResolveSectionControllerArgs } from "./coordinator-bridge.js";
+import { type InstrumentationHook } from "./instrumentation-bridge.js";
+import { type EngineOutputListener } from "./subscriber-fanout.js";
+export interface SectionEngineAdapterOptions {
+    /** Element on which DOM events are dispatched. */
+    host: EventTarget;
+    /** Stable runtime id for this engine instance. */
+    runtimeId: string;
+    /**
+     * Tag name of the host CE without the `--version-<encoded>` suffix.
+     */
+    sourceCe: string;
+    /**
+     * Framework-error bus (write side). Shared with the toolkit CE so
+     * subscribers via `coordinator.subscribeFrameworkErrors` see the
+     * same fan-out.
+     */
+    frameworkErrorBus: FrameworkErrorReporter;
+    /**
+     * Optional toolkit coordinator. When supplied, the adapter wires
+     * its framework-error subscription, controller resolution, and
+     * disposal through the coordinator-bridge. Standalone callers (no
+     * coordinator) can omit this and feed `framework-error` and
+     * `section-controller-resolved` inputs directly.
+     */
+    coordinator?: CoordinatorPort;
+    /** Optional one-shot observability hook. */
+    instrumentationHook?: InstrumentationHook;
+    /** Clock injection for the DOM bridge. Defaults to `Date.now()`. */
+    now?: () => string;
+    /**
+     * Optional pre-constructed core. Defaults to a fresh
+     * `SectionEngineCore`. Tests pass a mocked core to assert dispatch
+     * ordering; production callers use the default.
+     */
+    core?: SectionEngineCore;
+}
+export declare class SectionEngineAdapter {
+    private readonly core;
+    private readonly domEventBridge;
+    private readonly frameworkErrorBridge;
+    private readonly instrumentationBridge;
+    private readonly subscriberFanout;
+    private readonly coordinatorBridge;
+    private readonly unsubscribeCore;
+    private disposed;
+    constructor(options: SectionEngineAdapterOptions);
+    /**
+     * Read-only snapshot of the FSM state. Mirrors
+     * `SectionEngineCore.getState()`.
+     */
+    getState(): Readonly<SectionEngineState>;
+    /**
+     * Forward a host-constructed input to the core. Returns the outputs
+     * that resulted (the bridges have already received them).
+     */
+    dispatchInput(input: SectionEngineInput): readonly SectionEngineOutput[];
+    /**
+     * Subscribe to batched output streams, one batch per
+     * `dispatchInput`.
+     */
+    subscribe(listener: EngineOutputListener): () => void;
+    /**
+     * Update the host element after construction (e.g. when the kernel
+     * receives its host element via Svelte action / context).
+     */
+    setHost(host: EventTarget): void;
+    /**
+     * Update the instrumentation hook at runtime.
+     */
+    setInstrumentationHook(hook: InstrumentationHook | undefined): void;
+    /**
+     * Resolve a section controller through the configured coordinator.
+     *
+     * Throws if the adapter was constructed without a coordinator.
+     * Standalone callers should manually feed
+     * `{ kind: "section-controller-resolved" }` after their own
+     * controller resolution path completes.
+     */
+    resolveSectionController(args: ResolveSectionControllerArgs): Promise<void>;
+    /**
+     * Tear the adapter down. Safe to call more than once. Disposes the
+     * coordinator bridge (which in turn disposes the section
+     * controller for the current cohort), detaches the core
+     * subscription, and clears subscribers.
+     *
+     * Does **not** dispose the framework-error bus — its lifetime is
+     * owned by the toolkit CE / host.
+     */
+    dispose(): Promise<void>;
+    private routeOutputs;
+    private routeOne;
+}
+//# sourceMappingURL=SectionEngineAdapter.d.ts.map

package/dist/runtime/adapter/SectionEngineAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SectionEngineAdapter.d.ts","sourceRoot":"","sources":["../../../src/runtime/adapter/SectionEngineAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAGN,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,MAAM,yBAAyB,CAAC;AASjC,OAAO,EAGN,KAAK,mBAAmB,EACxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAEN,KAAK,oBAAoB,EAEzB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,2BAA2B;IAC3C,kDAAkD;IAClD,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,iBAAiB,EAAE,sBAAsB,CAAC;IAC1C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,4CAA4C;IAC5C,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA8B;IACpE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiC;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAa;IAC7C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,2BAA2B;IA2BhD;;;OAGG;IACH,QAAQ,IAAI,QAAQ,CAAC,kBAAkB,CAAC;IAIxC;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,mBAAmB,EAAE;IAKxE;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAIrD;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIhC;;OAEG;IACH,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,GAAG,IAAI;IAInE;;;;;;;OAOG;IACH,wBAAwB,CAAC,IAAI,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC;IAS3E;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,QAAQ;CAkBhB"}