@livestore/livestore 0.4.0-dev.9 → 0.5.0-dev.0

package/dist/store/store-types.d.ts

@@ -1,52 +1,169 @@
-import type { ClientSession, ClientSessionSyncProcessorSimulationParams, IntentionalShutdownCause, InvalidPullError, IsOfflineError, MaterializeError, StoreInterrupted, SyncError, UnexpectedError } from '@livestore/common';
-import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema';
-import type { Effect, Runtime, Scope } from '@livestore/utils/effect';
-import { Deferred } from '@livestore/utils/effect';
 import type * as otel from '@opentelemetry/api';
-import type { DebugRefreshReasonBase } from '../reactive.ts';
+import { type BackendIdMismatchError, type ClientSession, type ClientSessionSyncProcessor, type IntentionalShutdownCause, type MaterializeError, type QueryBuilder, type StoreInterrupted, type UnknownError } from '@livestore/common';
+import type { StreamEventsOptions } from '@livestore/common/leader-thread';
+import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema';
+import { type Context, Deferred, type Effect, type Schema, type Scope } from '@livestore/utils/effect';
+import type { LiveQuery, LiveQueryDef, ReactivityGraph, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts';
+import { isLiveQueryDef } from '../live-queries/base-class.ts';
+import type { DebugRefreshReasonBase, Ref } from '../reactive.ts';
+import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts';
+import type { ReferenceCountedSet } from '../utils/data-structures.ts';
 import type { StackInfo } from '../utils/stack-info.ts';
 import type { Store } from './store.ts';
-export type LiveStoreContext = LiveStoreContextRunning | {
+/**
+ * Union type representing the possible states of a LiveStore context.
+ *
+ * Used by framework integrations (React, Solid, etc.) to track Store lifecycle:
+ * - `running`: Store is active and ready for queries/commits
+ * - `error`: Store failed during boot or operation
+ * - `shutdown`: Store was intentionally shut down or interrupted
+ *
+ * @typeParam TSchema - The LiveStore schema type. Defaults to `LiveStoreSchema.Any`.
+ */
+export type LiveStoreContext<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = LiveStoreContextRunning<TSchema> | {
     stage: 'error';
-    error: UnexpectedError | unknown;
+    error: unknown;
 } | {
     stage: 'shutdown';
-    cause: IntentionalShutdownCause | StoreInterrupted | SyncError;
+    cause: IntentionalShutdownCause | StoreInterrupted | UnknownError;
 };
-export type ShutdownDeferred = Deferred.Deferred<IntentionalShutdownCause, UnexpectedError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError>;
+export type ShutdownDeferred = Deferred.Deferred<IntentionalShutdownCause, UnknownError | StoreInterrupted | MaterializeError | BackendIdMismatchError>;
 export declare const makeShutdownDeferred: Effect.Effect<ShutdownDeferred>;
-export type LiveStoreContextRunning = {
+/**
+ * Context state when the Store is active and ready for use.
+ *
+ * This is the normal operating state where you can query data, commit events,
+ * and subscribe to changes.
+ *
+ * @typeParam TSchema - The LiveStore schema type. Defaults to `LiveStoreSchema.Any`
+ *   for backwards compatibility, but prefer providing the concrete schema type
+ *   for full type safety.
+ */
+export type LiveStoreContextRunning<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = {
     stage: 'running';
-    store: Store;
+    store: Store<TSchema>;
 };
 export type OtelOptions = {
     tracer: otel.Tracer;
     rootSpanContext: otel.Context;
 };
-export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
+export declare const StoreInternalsSymbol: unique symbol;
+export type StoreInternalsSymbol = typeof StoreInternalsSymbol;
+/**
+ * Opaque bag containing the Store's implementation details.
+ *
+ * Not part of the public API — shapes and semantics may change without notice.
+ * Access only from within the @livestore/livestore package (and Devtools) via
+ * `StoreInternalsSymbol` to avoid accidental coupling in application code.
+ */
+export type StoreInternals = {
+    /**
+     * Runtime event schema used for encoding/decoding events.
+     *
+     * Exposed primarily for Devtools (e.g. databrowser) to validate ad‑hoc
+     * event payloads. Application code should not depend on it directly.
+     */
+    readonly eventSchema: Schema.Codec<LiveStoreEvent.Client.Decoded, LiveStoreEvent.Client.Encoded>;
+    /**
+     * The active client session backing this Store. Provides access to the
+     * leader thread, network status, and shutdown signaling.
+     *
+     * Do not close or mutate directly — use `store.shutdown(...)`.
+     */
+    readonly clientSession: ClientSession;
+    /**
+     * Wrapper around the local SQLite state database. Centralizes query
+     * planning, caching, and change tracking used by reads and materializers.
+     */
+    readonly sqliteDbWrapper: SqliteDbWrapper;
+    /**
+     * Effect context and scope used to fork background fibers for the Store.
+     *
+     * - `services` provides services when executing effects from imperative Store APIs.
+     * - `lifetimeScope` owns forked fibers; closed during Store shutdown.
+     */
+    readonly effectContext: {
+        /** Effect context used to run Store effects with proper services. */
+        readonly services: Context.Context<Scope.Scope>;
+        /** Scope that owns all long‑lived fibers spawned by the Store. */
+        readonly lifetimeScope: Scope.Scope;
+    };
+    /**
+     * OpenTelemetry primitives used for instrumentation of commits, queries,
+     * and Store boot lifecycle.
+     */
+    readonly otel: StoreOtel;
+    /**
+     * The Store's reactive graph instance used to model dependencies and
+     * propagate updates. Provides APIs to create refs/thunks/effects and to
+     * subscribe to refresh cycles.
+     */
+    readonly reactivityGraph: ReactivityGraph;
+    /**
+     * Per‑table reactive refs used to broadcast invalidations when materializers
+     * write to tables. Values are always `null`; equality is intentionally
+     * `false` to force recomputation.
+     *
+     * Keys are SQLite table names (user tables; some system tables may be
+     * intentionally excluded from refresh).
+     */
+    readonly tableRefs: Readonly<Record<string, Ref<null, ReactivityGraphContext, RefreshReason>>>;
+    /**
+     * Set of currently subscribed LiveQuery instances (reference‑counted).
+     * Used for Devtools and diagnostics.
+     */
+    readonly activeQueries: ReferenceCountedSet<LiveQuery<any>>;
+    /**
+     * Client‑session sync processor orchestrating push/pull and materialization
+     * of events into local state.
+     */
+    readonly syncProcessor: ClientSessionSyncProcessor;
+    /**
+     * Starts background fibers for sync and observation. Must be run exactly
+     * once per Store instance. Scoped; installs finalizers to end spans and
+     * detach reactive refs.
+     */
+    readonly boot: Effect.Effect<void, UnknownError, Scope.Scope>;
+    /**
+     * Tracks whether the Store has been shut down. When true, mutating APIs
+     * should reject via `checkShutdown`.
+     */
+    isShutdown: boolean;
+};
+/**
+ * Parameters for constructing a Store instance.
+ *
+ * @internal This type is used by the Store constructor and is not part of the public API.
+ * For creating stores, use `createStore()` or `StoreRegistry` instead.
+ */
+export type StoreConstructorParams<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
     clientSession: ClientSession;
     schema: TSchema;
     storeId: string;
     context: TContext;
     otelOptions: OtelOptions;
     effectContext: {
-        runtime: Runtime.Runtime<Scope.Scope>;
+        services: Context.Context<Scope.Scope>;
         lifetimeScope: Scope.Scope;
     };
     confirmUnsavedChanges: boolean;
     batchUpdates: (runUpdates: () => void) => void;
     params: {
         leaderPushBatchSize: number;
-        simulation?: {
-            clientSessionSyncProcessor: typeof ClientSessionSyncProcessorSimulationParams.Type;
-        };
+        eventQueryBatchSize?: number;
     };
     __runningInDevtools: boolean;
 };
+/**
+ * Tagged union describing why a reactive refresh occurred.
+ *
+ * Used internally for debugging and devtools to trace the cause of query re-evaluations.
+ * Each variant includes context about what triggered the refresh.
+ */
 export type RefreshReason = DebugRefreshReasonBase | {
     _tag: 'commit';
     /** The events that were applied */
-    events: ReadonlyArray<LiveStoreEvent.AnyDecoded | LiveStoreEvent.PartialAnyDecoded>;
+    events: ReadonlyArray<LiveStoreEvent.Client.Decoded | LiveStoreEvent.Input.Decoded>;
     /** The tables that were written to by the event */
     writeTables: ReadonlyArray<string>;
 } | {
@@ -64,10 +181,19 @@ export type RefreshReason = DebugRefreshReasonBase | {
     _tag: 'manual';
     label?: string;
 };
+/**
+ * Debug information captured for each query execution.
+ *
+ * Used by devtools and performance monitoring to track query behavior.
+ */
 export type QueryDebugInfo = {
+    /** Query type discriminator ('db', 'computed', etc.) */
     _tag: string;
+    /** Human-readable query label */
     label: string;
+    /** SQL query string or computed function representation */
     query: string;
+    /** Execution time in milliseconds */
     durationMs: number;
 };
 export type StoreOtel = {
@@ -82,27 +208,141 @@ export type StoreCommitOptions = {
     spanLinks?: otel.Link[];
     otelContext?: otel.Context;
 };
-export type StoreEventsOptions<TSchema extends LiveStoreSchema> = {
-    /**
-     * By default only new events are returned.
-     * Use this to get all events from a specific point in time.
-     */
-    cursor?: EventSequenceNumber.EventSequenceNumber;
+/**
+ * filter: Narrowed to the store's event types
+ * includeClientOnly: Omitted from public API until supported
+ */
+export type StoreEventsOptions<TSchema extends LiveStoreSchema> = Omit<StreamEventsOptions, 'filter' | 'includeClientOnly'> & {
     /**
-     * Only include events of the given names
+     * Only include events of the given names.
      * @default undefined (include all)
      */
     filter?: ReadonlyArray<keyof TSchema['_EventDefMapType']>;
+};
+/**
+ * Function returned by `store.subscribe()` to stop receiving updates.
+ *
+ * Call this to unsubscribe from a query and release the associated resources.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = store.subscribe(todos$, (todos) => console.log(todos))
+ * // Later...
+ * unsubscribe()
+ * ```
+ */
+export type Unsubscribe = () => void;
+/**
+ * Options for `store.subscribe()`.
+ *
+ * @typeParam TResult - The result type of the subscribed query
+ */
+export type SubscribeOptions<TResult> = {
+    /** Callback invoked when the subscription is established (receives the live query instance) */
+    onSubscribe?: (query$: LiveQuery<TResult>) => void;
+    /** Callback invoked when the subscription is terminated */
+    onUnsubsubscribe?: () => void;
+    /** Label for debugging and devtools */
+    label?: string;
+    /** If true, skips invoking the callback for the initial value */
+    skipInitialRun?: boolean;
+    /** OpenTelemetry context for tracing */
+    otelContext?: otel.Context;
+    /** Stack trace info for debugging subscription origins */
+    stackInfo?: StackInfo;
+};
+/** All query definitions or instances the store can execute or subscribe to. */
+export type Queryable<TResult> = LiveQueryDef<TResult> | SignalDef<TResult> | LiveQuery<TResult> | QueryBuilder<TResult, any, any>;
+/**
+ * Helper types for `Queryable`.
+ *
+ * Provides type-level utilities to work with `Queryable` values.
+ */
+export declare namespace Queryable {
     /**
-     * Whether to include client-only events or only return synced events
-     * @default true
+     * Extracts the result type from a `Queryable`.
+     *
+     * Example:
+     * - `Queryable.Result<LiveQueryDef<number>>` → `number`
+     * - `Queryable.Result<SignalDef<string>>` → `string`
+     * - `Queryable.Result<LiveQuery<{ id: string }>>` → `{ id: string }`
+     * - `Queryable.Result<LiveQueryDef<A> | SignalDef<B>>` → `A | B`
      */
-    includeClientOnly?: boolean;
+    type Result<TQueryable extends Queryable<any>> = TQueryable extends Queryable<infer TResult> ? TResult : never;
+}
+export { isLiveQueryDef };
+/**
+ * Type guard that checks if a value is a live query instance.
+ *
+ * Live query instances are stateful objects bound to a Store's reactivity graph.
+ * They're created internally when you use a definition with `store.query()` or `store.subscribe()`.
+ *
+ * @example
+ * ```ts
+ * const [, , , query$] = useClientDocument(tables.uiState)
+ *
+ * if (isLiveQueryInstance(query$)) {
+ *   console.log('Execution count:', query$.runs)
+ * }
+ * ```
+ */
+export declare const isLiveQueryInstance: (value: unknown) => value is LiveQuery<any>;
+/**
+ * Type guard that checks if a value can be used with `store.query()` or `store.subscribe()`.
+ *
+ * Queryable values include:
+ * - Query definitions (`LiveQueryDef` from `queryDb()`, `computed()`)
+ * - Signal definitions (`SignalDef` from `signal()`)
+ * - Live query instances (`LiveQuery`)
+ * - Query builders (e.g., `tables.todos.where(...)`)
+ *
+ * @example
+ * ```ts
+ * const handleQuery = (input: unknown) => {
+ *   if (isQueryable(input)) {
+ *     return store.query(input)
+ *   }
+ *   throw new Error('Not a valid query')
+ * }
+ * ```
+ */
+export declare const isQueryable: (value: unknown) => value is Queryable<unknown>;
+/**
+ * Represents the current synchronization status of the store.
+ *
+ * This provides visibility into the sync state between the client session
+ * and the leader thread, allowing applications to show sync indicators
+ * or determine backend health.
+ *
+ * @example
+ * ```ts
+ * const status = store.syncStatus()
+ * if (status.isSynced) {
+ *   console.log('All changes synced')
+ * } else {
+ *   console.log(`${status.pendingCount} events pending sync`)
+ * }
+ * ```
+ */
+export type SyncStatus = {
     /**
-     * Exclude own events that have not been pushed to the sync backend yet
-     * @default false
+     * The local head sequence number (most recent event in the client session).
+     * Represented as a string in the format "e{global}.{client}" (e.g., "e5.2").
      */
-    excludeUnpushed?: boolean;
+    localHead: string;
+    /**
+     * The upstream head sequence number (what the leader thread has confirmed).
+     * Represented as a string in the format "e{global}" (e.g., "e3").
+     */
+    upstreamHead: string;
+    /**
+     * Number of events pending synchronization to the leader thread.
+     */
+    pendingCount: number;
+    /**
+     * Whether the client session is fully synced with the leader thread.
+     * True when there are no pending events (pendingCount === 0).
+     */
+    isSynced: boolean;
 };
-export type Unsubscribe = () => void;
 //# sourceMappingURL=store-types.d.ts.map

package/dist/store/store-types.d.ts.map

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

package/dist/store/store-types.js

@@ -1,3 +1,43 @@
-import { Deferred } from '@livestore/utils/effect';
+import { isQueryBuilder, } from '@livestore/common';
+import { Deferred, Predicate } from '@livestore/utils/effect';
+import { isLiveQueryDef, TypeId } from "../live-queries/base-class.js";
 export const makeShutdownDeferred = Deferred.make();
+export const StoreInternalsSymbol = Symbol.for('livestore.StoreInternals');
+export { isLiveQueryDef };
+/**
+ * Type guard that checks if a value is a live query instance.
+ *
+ * Live query instances are stateful objects bound to a Store's reactivity graph.
+ * They're created internally when you use a definition with `store.query()` or `store.subscribe()`.
+ *
+ * @example
+ * ```ts
+ * const [, , , query$] = useClientDocument(tables.uiState)
+ *
+ * if (isLiveQueryInstance(query$)) {
+ *   console.log('Execution count:', query$.runs)
+ * }
+ * ```
+ */
+export const isLiveQueryInstance = (value) => Predicate.hasProperty(value, TypeId);
+/**
+ * Type guard that checks if a value can be used with `store.query()` or `store.subscribe()`.
+ *
+ * Queryable values include:
+ * - Query definitions (`LiveQueryDef` from `queryDb()`, `computed()`)
+ * - Signal definitions (`SignalDef` from `signal()`)
+ * - Live query instances (`LiveQuery`)
+ * - Query builders (e.g., `tables.todos.where(...)`)
+ *
+ * @example
+ * ```ts
+ * const handleQuery = (input: unknown) => {
+ *   if (isQueryable(input)) {
+ *     return store.query(input)
+ *   }
+ *   throw new Error('Not a valid query')
+ * }
+ * ```
+ */
+export const isQueryable = (value) => isQueryBuilder(value) || isLiveQueryInstance(value) || isLiveQueryDef(value);
 //# sourceMappingURL=store-types.js.map

package/dist/store/store-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-types.js","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAsBlD,MAAM,CAAC,MAAM,oBAAoB,GAAoC,QAAQ,CAAC,IAAI,EAG/E,CAAA"}
+{"version":3,"file":"store-types.js","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,cAAc,GAKf,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAgB,QAAQ,EAAe,SAAS,EAA2B,MAAM,yBAAyB,CAAA;AASjH,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAgCtE,MAAM,CAAC,MAAM,oBAAoB,GAAoC,QAAQ,CAAC,IAAI,EAG/E,CAAA;AAsBH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;AA2P1E,OAAO,EAAE,cAAc,EAAE,CAAA;AAEzB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAc,EAA2B,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEpH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAA+B,EAAE,CACzE,cAAc,CAAC,KAAK,CAAC,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA"}

package/dist/store/store-types.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=store-types.test.d.ts.map

package/dist/store/store-types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-types.test.d.ts","sourceRoot":"","sources":["../../src/store/store-types.test.ts"],"names":[],"mappings":""}

package/dist/store/store-types.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { QueryBuilderTypeId } from '@livestore/common';
+import { Schema } from '@livestore/utils/effect';
+import { TypeId } from "../live-queries/base-class.js";
+import { queryDb, signal } from "../live-queries/mod.js";
+import { isQueryable } from "./store-types.js";
+const makeQueryBuilder = () => ({
+    [QueryBuilderTypeId]: QueryBuilderTypeId,
+    ResultType: null,
+    asSql: () => ({ query: 'select 1', bindValues: [], usedTables: new Set() }),
+    toString: () => 'select 1',
+});
+describe('isQueryable', () => {
+    it('identifies live query definitions', () => {
+        const def = queryDb({
+            query: 'select 1 as value',
+            schema: Schema.Array(Schema.Struct({ value: Schema.Finite })),
+        });
+        expect(isQueryable(def)).toBe(true);
+    });
+    it('identifies signal definitions', () => {
+        const sig = signal(0, { label: 'count' });
+        expect(isQueryable(sig)).toBe(true);
+    });
+    it('identifies live query instances', () => {
+        const liveQueryLike = { [TypeId]: TypeId };
+        expect(isQueryable(liveQueryLike)).toBe(true);
+    });
+    it('identifies query builders', () => {
+        const qb = makeQueryBuilder();
+        expect(isQueryable(qb)).toBe(true);
+    });
+    it('rejects unrelated values', () => {
+        expect(isQueryable(null)).toBe(false);
+        expect(isQueryable(undefined)).toBe(false);
+        expect(isQueryable({})).toBe(false);
+    });
+});
+//# sourceMappingURL=store-types.test.js.map

package/dist/store/store-types.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-types.test.js","sourceRoot":"","sources":["../../src/store/store-types.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAG7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,MAAM,gBAAgB,GAAG,GAAgC,EAAE,CACzD,CAAC;IACC,CAAC,kBAAkB,CAAC,EAAE,kBAAkB;IACxC,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,GAAG,EAAU,EAAE,CAAC;IACnF,QAAQ,EAAE,GAAG,EAAE,CAAC,UAAU;CAC3B,CAA2C,CAAA;AAE9C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC;YAClB,KAAK,EAAE,mBAAmB;YAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;SAC9D,CAAC,CAAA;QAEF,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;QAEzC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,aAAa,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAW,CAAA;QAEnD,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAA;QAE7B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1C,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}