@aephia/atlas-kit 0.6.0-next.16 → 0.6.0-next.160

package/dist/scanning/index.js

@@ -1,23 +1,15 @@
 import { AccountDecodeError, entityRef, } from '../client/index.js';
 import { discoverScanPatternAccounts, deriveScanPatternAddress, scanPatternAccountDefinition, } from '../internal/c4/scanning.js';
 import { assertCanonicalFleetAddress, fleetAccountDefinition, } from '../internal/c4/fleet.js';
-import { characterAccountDefinition, findCharacterPda, } from '../internal/c4/identity.js';
+import { characterAccountDefinition, findCharacterPda, } from '../internal/c4/character.js';
 import { requireGameAddress } from '../internal/game-context.js';
 import { attachJsonSerialization } from '../internal/json.js';
-import { attachReadMeta, readMeta } from '../internal/read-meta.js';
+import { attachReadMeta, envelopeMeta, readMeta, } from '../internal/read-meta.js';
 import { freezeResolvedSnapshot } from '../internal/resolved-snapshot.js';
 import { resolveCargo, } from '../registry/index.js';
 const PATTERN_SNAPSHOTS = new WeakMap();
 const FLEET_SNAPSHOTS = new WeakMap();
 const CHARACTER_SNAPSHOTS = new WeakMap();
-function metadata(envelope, strategy = 'direct') {
-    return {
-        commitment: envelope.commitment,
-        slot: envelope.slot,
-        source: envelope.source,
-        strategy,
-    };
-}
 async function createPatternSnapshot(context, envelope, strategy) {
     const game = requireGameAddress(context);
     if (envelope.data.game !== game) {
@@ -45,10 +37,10 @@ async function createPatternSnapshot(context, envelope, strategy) {
             xpValue: outcome.xpValue,
         }))),
         name: envelope.data.name,
-        noiseMaps: envelope.data.noiseMaps,
+        noiseMapCount: envelope.data.noiseMapCount,
         status: envelope.data.status,
         version: envelope.data.version,
-    }), metadata(envelope, strategy)));
+    }), envelopeMeta(envelope, strategy)));
 }
 function patternSnapshot(context, envelope, strategy) {
     let cache = PATTERN_SNAPSHOTS.get(envelope);
@@ -64,6 +56,11 @@ function patternSnapshot(context, envelope, strategy) {
     void pending.catch(() => cache.delete(strategy));
     return pending;
 }
+function assertDerivedPatternId(envelope, patternId) {
+    if (envelope.data.id !== patternId) {
+        throw new AccountDecodeError('scanPattern', envelope.address, new RangeError('The ScanPattern id contradicted its derived seeds.'), `ScanPattern ${envelope.address} stores id ${String(envelope.data.id)}, not derived id ${String(patternId)}. Verify the configured cluster and pinned PDA recipe before retrying.`);
+    }
+}
 /** Derives and reads one required ScanPattern for the configured Game.
  * @example
  * ```ts
@@ -75,9 +72,7 @@ export async function getScanPattern(context, patternId, options) {
     const game = requireGameAddress(context);
     const address = await deriveScanPatternAddress(game, patternId);
     const envelope = await context.data.read(scanPatternAccountDefinition, address, options);
-    if (envelope.data.id !== patternId) {
-        throw new AccountDecodeError('scanPattern', address, new RangeError('The ScanPattern id contradicted its derived seeds.'), `ScanPattern ${address} stores id ${String(envelope.data.id)}, not derived id ${String(patternId)}. Verify the configured cluster and pinned PDA recipe before retrying.`);
-    }
+    assertDerivedPatternId(envelope, patternId);
     return patternSnapshot(context, envelope, 'derived');
 }
 /** Derives and reads one optional ScanPattern for the configured Game.
@@ -93,9 +88,7 @@ export async function maybeGetScanPattern(context, patternId, options) {
     const [envelope] = await context.data.readMany(scanPatternAccountDefinition, [address], options);
     if (envelope === undefined)
         return undefined;
-    if (envelope.data.id !== patternId) {
-        throw new AccountDecodeError('scanPattern', address, new RangeError('The ScanPattern id contradicted its derived seeds.'));
-    }
+    assertDerivedPatternId(envelope, patternId);
     return patternSnapshot(context, envelope, 'derived');
 }
 /** Discovers the configured Game's ScanPattern catalog with targeted filters.
@@ -136,12 +129,12 @@ export async function getFleetScanningState(context, address, options) {
         kind: 'fleetScanningState',
         ownerProfile: entityRef('profile', envelope.data.ownerProfile),
         stats: {
-            bonus: misc.scanBonus,
-            cooldownSeconds: misc.scanCoolDownSeconds,
+            bonus: misc.scanBonus.value,
+            cooldownSeconds: misc.scanCoolDownSeconds.value,
             cost: misc.scanCost,
-            power: misc.scanPower,
+            power: misc.scanPower.value,
         },
-    }), metadata(envelope)));
+    }), envelopeMeta(envelope, 'direct')));
     FLEET_SNAPSHOTS.set(envelope, snapshot);
     return snapshot;
 }
@@ -184,7 +177,7 @@ export async function getCharacterScanningState(context, profile, options) {
         },
         profile: entityRef('profile', profile),
         researchTagIds: modifiers.values.researchTags,
-    }), metadata(envelope, 'derived')));
+    }), envelopeMeta(envelope, 'derived')));
     CHARACTER_SNAPSHOTS.set(envelope, snapshot);
     return snapshot;
 }
@@ -204,4 +197,7 @@ export function deriveScanCooldownState(fleet, atUnixSeconds) {
         remainingSeconds: fleet.cooldownEndsAtUnixSeconds - atUnixSeconds,
     };
 }
+export { getScanSignalForFleet, maybeGetScanSignalForFleet, getScanPatternPolicy, maybeGetScanPatternPolicy, getScanLootProfile, maybeGetScanLootProfile, } from './signals.js';
+export { deriveScanSignalTiming, deriveScanRecoveryRange, } from './lifecycle.js';
+export { deriveScanLootOdds, deriveCommittedScanLootOdds, deriveScanExhaustion, } from './odds.js';
 //# sourceMappingURL=index.js.map

package/dist/scanning/index.js.map

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

package/dist/scanning/lifecycle.d.ts

@@ -0,0 +1,77 @@
+import type { ScanCoordinates, ScanSignalSnapshot, ScanSignalStatus } from './signals.js';
+/** Explicit chain clock inputs; slots and Unix seconds are independent units.
+ * @example
+ * ```ts
+ * const clock: ScanSignalClock = { slot: 54_000_000n, unixSeconds: 1_790_000_000n };
+ * ```
+ */
+export interface ScanSignalClock {
+    readonly slot: bigint;
+    readonly unixSeconds: bigint;
+}
+/** Timing observations from the fingerprinted client, not permission to execute a scan action.
+ * @example
+ * ```ts
+ * declare const result: ScanSignalTiming;
+ * console.log(result.entropy?.phase, result.cooldownRemainingSeconds);
+ * ```
+ */
+export interface ScanSignalTiming {
+    readonly status: ScanSignalStatus | 'absent';
+    readonly cooldownRemainingSeconds: bigint;
+    readonly entropy: Readonly<{
+        phase: 'waiting' | 'ready' | 'expired';
+        readyAtSlot: bigint;
+        deadlineSlot: bigint;
+        slotsUntilReady: bigint;
+    }> | undefined;
+    readonly contactExpiry: Readonly<{
+        expired: boolean;
+        remainingSeconds: bigint;
+    }> | undefined;
+    toJSON(): unknown;
+}
+/** Exact geometric comparison; squared raw values use a 2^112 scale, not map units.
+ * No-contact means geometry is unavailable, not that an action is allowed.
+ * @example
+ * ```ts
+ * declare const result: ScanRecoveryRange;
+ * if (result.kind === 'contact') console.log(result.withinRange);
+ * ```
+ */
+export type ScanRecoveryRange = (Readonly<{
+    kind: 'no-contact';
+}> | Readonly<{
+    kind: 'contact';
+    withinRange: boolean;
+    distanceSquaredRaw: bigint;
+    radiusSquaredRaw: bigint;
+}>) & {
+    toJSON(): unknown;
+};
+/** Projects signal cooldown, pending entropy and contact expiry using explicit clock values.
+ * Reveal starts at commitSlot + 10 and ends exclusively 256 slots later, matching
+ * the fingerprinted client. No network, polling, clock access or acknowledgement
+ * eligibility is implied; abandonment acknowledgement can shorten cooldown.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot | undefined;
+ * const timing = deriveScanSignalTiming(signal, { slot: 54_000_000n, unixSeconds: 1_790_000_000n });
+ * console.log(timing.entropy?.phase);
+ * ```
+ */
+export declare function deriveScanSignalTiming(signal: ScanSignalSnapshot | undefined, clock: ScanSignalClock): ScanSignalTiming;
+/** Compares a contact's recovery radius with exact raw I8F56 coordinates, boundary included.
+ * Supply current raw I8F56 coordinates, not Fleet display coordinates or the
+ * original scan-attempt position. Never reconstruct exact bits from rounded values.
+ * Uses raw components only. This is geometry, not expiry, authority, capacity or
+ * instruction eligibility; an expired Contact still has measurable geometry.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot | undefined, location: ScanCoordinates;
+ * const range = deriveScanRecoveryRange(signal, location);
+ * if (range.kind === 'contact') console.log(range.withinRange);
+ * ```
+ */
+export declare function deriveScanRecoveryRange(signal: ScanSignalSnapshot | undefined, location: ScanCoordinates): ScanRecoveryRange;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/scanning/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/scanning/lifecycle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AACD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,CAAC;IAC7C,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,OAAO,EACZ,QAAQ,CAAC;QACP,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;QACvC,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC,GACF,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,EACpB,QAAQ,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC;IACvE,MAAM,IAAI,OAAO,CAAC;CACnB;AACD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC5B,QAAQ,CAAC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,GAChC,QAAQ,CAAC;IACP,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC,CACL,GAAG;IAAE,MAAM,IAAI,OAAO,CAAA;CAAE,CAAC;AAwB1B;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,KAAK,EAAE,eAAe,GACrB,gBAAgB,CAqClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,QAAQ,EAAE,eAAe,GACxB,iBAAiB,CAenB"}

package/dist/scanning/lifecycle.js

@@ -0,0 +1,93 @@
+import { SageSdkError, InvalidDerivationInputError } from '../client/errors.js';
+import { attachJsonSerialization } from '../internal/json.js';
+import { freezeResolvedSnapshot } from '../internal/resolved-snapshot.js';
+function nonnegative(field, value) {
+    if (value < 0n)
+        throw new InvalidDerivationInputError(field, value, 'Supply a nonnegative slot or radius from a fresh scan snapshot before deriving scan timing or range.');
+}
+function required(value, field) {
+    if (value === undefined)
+        throw new SageSdkError('INVALID_DERIVATION_INPUT', `The scan signal is missing ${field} required by its state. Refetch the signal snapshot before deriving scan timing or range.`);
+    return value;
+}
+function remaining(end, now) {
+    return end > now ? end - now : 0n;
+}
+function finish(value) {
+    return freezeResolvedSnapshot(attachJsonSerialization(value));
+}
+/** Projects signal cooldown, pending entropy and contact expiry using explicit clock values.
+ * Reveal starts at commitSlot + 10 and ends exclusively 256 slots later, matching
+ * the fingerprinted client. No network, polling, clock access or acknowledgement
+ * eligibility is implied; abandonment acknowledgement can shorten cooldown.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot | undefined;
+ * const timing = deriveScanSignalTiming(signal, { slot: 54_000_000n, unixSeconds: 1_790_000_000n });
+ * console.log(timing.entropy?.phase);
+ * ```
+ */
+export function deriveScanSignalTiming(signal, clock) {
+    nonnegative('clock.slot', clock.slot);
+    let entropy;
+    let contactExpiry;
+    if (signal?.status === 'pending-entropy') {
+        const { commitSlot } = required(signal.attempt, 'attempt');
+        nonnegative('attempt.commitSlot', commitSlot);
+        const readyAtSlot = commitSlot + 10n;
+        const deadlineSlot = readyAtSlot + 256n;
+        entropy = {
+            phase: clock.slot < readyAtSlot
+                ? 'waiting'
+                : clock.slot < deadlineSlot
+                    ? 'ready'
+                    : 'expired',
+            readyAtSlot,
+            deadlineSlot,
+            slotsUntilReady: remaining(readyAtSlot, clock.slot),
+        };
+    }
+    if (signal?.status === 'contact') {
+        const { expiresAtUnixSeconds } = required(signal.contact, 'contact');
+        contactExpiry = {
+            expired: clock.unixSeconds >= expiresAtUnixSeconds,
+            remainingSeconds: remaining(expiresAtUnixSeconds, clock.unixSeconds),
+        };
+    }
+    return finish({
+        status: signal?.status ?? 'absent',
+        cooldownRemainingSeconds: signal === undefined
+            ? 0n
+            : remaining(signal.cooldownEndsAtUnixSeconds, clock.unixSeconds),
+        entropy,
+        contactExpiry,
+    });
+}
+/** Compares a contact's recovery radius with exact raw I8F56 coordinates, boundary included.
+ * Supply current raw I8F56 coordinates, not Fleet display coordinates or the
+ * original scan-attempt position. Never reconstruct exact bits from rounded values.
+ * Uses raw components only. This is geometry, not expiry, authority, capacity or
+ * instruction eligibility; an expired Contact still has measurable geometry.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot | undefined, location: ScanCoordinates;
+ * const range = deriveScanRecoveryRange(signal, location);
+ * if (range.kind === 'contact') console.log(range.withinRange);
+ * ```
+ */
+export function deriveScanRecoveryRange(signal, location) {
+    if (signal?.status !== 'contact')
+        return finish({ kind: 'no-contact' });
+    const { target, targetRadius } = required(signal.contact, 'contact');
+    nonnegative('contact.targetRadius.raw', targetRadius.raw);
+    const dx = location.x.raw - target.x.raw, dy = location.y.raw - target.y.raw;
+    const distanceSquaredRaw = dx * dx + dy * dy;
+    const radiusSquaredRaw = targetRadius.raw * targetRadius.raw;
+    return finish({
+        kind: 'contact',
+        withinRange: distanceSquaredRaw <= radiusSquaredRaw,
+        distanceSquaredRaw,
+        radiusSquaredRaw,
+    });
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/scanning/lifecycle.js.map

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

package/dist/scanning/odds.d.ts

@@ -0,0 +1,115 @@
+import type { ScanPatternPolicySnapshot, ScanLootProfileSnapshot, ScanSignalSnapshot } from './signals.js';
+type Policy = ScanPatternPolicySnapshot;
+type Profile = ScanLootProfileSnapshot;
+type Row = Profile['loot'][number];
+type Focus = Row['category'];
+type UnavailableReason = 'missing-policy' | 'missing-loot-profile' | 'unsupported-version' | 'unsupported-pattern' | 'unsupported-loot-layout' | 'game-mismatch' | 'inactive-policy' | 'inactive-loot-profile' | 'pattern-research-locked' | 'region-research-locked' | 'focus-not-allowed' | 'empty-weighted-pool' | 'signal-not-pending' | 'committed-configuration-mismatch';
+type Exclusion = 'pattern' | 'rarity' | 'value-budget' | 'focus' | 'research' | 'not-committed';
+type Provenance = Readonly<{
+    policy: Readonly<Pick<Policy, 'address' | 'game' | 'patternId' | 'revision' | 'contentFingerprint'>> | undefined;
+    lootProfile: Readonly<Pick<Profile, 'address' | 'game' | 'regionId' | 'revision' | 'contentFingerprint'>> | undefined;
+    signal: Readonly<Pick<ScanSignalSnapshot, 'address' | 'sequence'>> | undefined;
+}>;
+type Share = Readonly<{
+    cargo: Row['cargo'];
+    weight: bigint;
+    conditionalProbability: number;
+    perScanProbability: number;
+}>;
+/** Explicit eligibility knowledge for prospective client estimates. Empty tag arrays mean known none.
+ * Regional requirements must describe the supplied loot profile's region. Focus defaults to any.
+ * @example
+ * ```ts
+ * const options: ScanLootOddsOptions = { unlockedResearchTagIds: [12], requiredRegionResearchTagIds: [], exhaustionBasisPoints: 0 };
+ * ```
+ */
+export interface ScanLootOddsOptions {
+    readonly unlockedResearchTagIds: readonly number[];
+    readonly requiredRegionResearchTagIds: readonly number[];
+    readonly exhaustionBasisPoints: number;
+    readonly focus?: Focus;
+}
+/** Selection estimates from loaded snapshots and the caller's eligibility inputs.
+ * The arithmetic matches the game's draw: a uniform basis-point contact roll
+ * against the exhaustion-reduced contact chance, then a row drawn in proportion
+ * to its raw roll weight over the eligible rows. The result is still an estimate:
+ * the eligibility inputs can be wrong and it promises no recovery quantity.
+ * Unavailable results deliberately contain no probability fields. Conditional shares remain meaningful
+ * when contact probability is zero. Probabilities are numeric fractions from zero through one.
+ * @example
+ * ```ts
+ * declare const odds: ScanLootOdds;
+ * if (odds.status === 'available') console.log(odds.resources[0]?.perScanProbability);
+ * ```
+ */
+export type ScanLootOdds = Readonly<{
+    kind: 'client-derived-estimate';
+    basis: 'prospective' | 'committed';
+    provenance: Provenance;
+    toJSON(): unknown;
+}> & (Readonly<{
+    status: 'unavailable';
+    reasons: readonly UnavailableReason[];
+}> | Readonly<{
+    status: 'available';
+    contactChanceBasisPoints: number;
+    contactProbability: number;
+    noContactProbability: number;
+    totalWeight: bigint;
+    eligibleRows: readonly (Share & Readonly<{
+        rowIndex: number;
+    }>)[];
+    excludedRows: readonly Readonly<{
+        rowIndex: number;
+        reasons: readonly Exclusion[];
+    }>[];
+    resources: readonly Share[];
+}>);
+/** Client-derived exhaustion from an explicit clock and retained recovery history.
+ * @example
+ * ```ts
+ * declare const exhaustion: ScanExhaustion;
+ * console.log(exhaustion.exhaustionBasisPoints, exhaustion.effectiveRecoveries);
+ * ```
+ */
+export interface ScanExhaustion {
+    readonly kind: 'client-derived-estimate';
+    readonly exhaustionBasisPoints: number;
+    readonly effectiveRecoveries: number;
+    toJSON(): unknown;
+}
+/** Estimates prospective contact and cargo-selection odds using the fingerprinted client's eligibility rules.
+ * Requires explicit research and exhaustion knowledge. This is not full scan-launch readiness:
+ * permissions, costs, Fleet state, cooldown, target and recovery capacity are outside this calculation.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot, loot: ScanLootProfileSnapshot;
+ * const odds = deriveScanLootOdds(policy, loot, { unlockedResearchTagIds: [], requiredRegionResearchTagIds: [], exhaustionBasisPoints: 0 });
+ * ```
+ */
+export declare function deriveScanLootOdds(policy: Policy | undefined, profile: Profile | undefined, options: ScanLootOddsOptions): ScanLootOdds;
+/** Estimates a pending signal's recorded draw using its committed rows and contact chance.
+ * Revisions AND full fingerprints must match. Current activity, focus and research do not
+ * replace committed eligibility; terminal signals are not random forecasts.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot, policy: ScanPatternPolicySnapshot, loot: ScanLootProfileSnapshot;
+ * const odds = deriveCommittedScanLootOdds(signal, policy, loot);
+ * ```
+ */
+export declare function deriveCommittedScanLootOdds(signal: ScanSignalSnapshot | undefined, policy: Policy | undefined, profile: Profile | undefined): ScanLootOdds;
+/** Applies the client exhaustion decay rule with explicit region and Unix seconds, without clock reads.
+ * An absent signal means known absence of recovery history, not an unknown/unread signal.
+ * Another region, disabled decay or a clock before the last recovery produce zero exhaustion.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot, signal: ScanSignalSnapshot | undefined;
+ * const exhaustion = deriveScanExhaustion(policy, signal, { regionId: 3, unixSeconds: 1_790_000_000n });
+ * ```
+ */
+export declare function deriveScanExhaustion(policy: Policy, signal: ScanSignalSnapshot | undefined, options: Readonly<{
+    regionId: number;
+    unixSeconds: bigint;
+}>): ScanExhaustion;
+export {};
+//# sourceMappingURL=odds.d.ts.map

package/dist/scanning/odds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odds.d.ts","sourceRoot":"","sources":["../../src/scanning/odds.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,KAAK,MAAM,GAAG,yBAAyB,CAAC;AACxC,KAAK,OAAO,GAAG,uBAAuB,CAAC;AACvC,KAAK,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AACnC,KAAK,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;AAgB7B,KAAK,iBAAiB,GAClB,gBAAgB,GAChB,sBAAsB,GACtB,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,GACzB,eAAe,GACf,iBAAiB,GACjB,uBAAuB,GACvB,yBAAyB,GACzB,wBAAwB,GACxB,mBAAmB,GACnB,qBAAqB,GACrB,oBAAoB,GACpB,kCAAkC,CAAC;AACvC,KAAK,SAAS,GACV,SAAS,GACT,QAAQ,GACR,cAAc,GACd,OAAO,GACP,UAAU,GACV,eAAe,CAAC;AACpB,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,MAAM,EACF,QAAQ,CACN,IAAI,CACF,MAAM,EACN,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,oBAAoB,CACrE,CACF,GACD,SAAS,CAAC;IACd,WAAW,EACP,QAAQ,CACN,IAAI,CACF,OAAO,EACP,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,oBAAoB,CACpE,CACF,GACD,SAAS,CAAC;IACd,MAAM,EACJ,QAAQ,CAAC,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC;CAC1E,CAAC,CAAC;AACH,KAAK,KAAK,GAAG,QAAQ,CAAC;IACpB,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AACH;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,4BAA4B,EAAE,SAAS,MAAM,EAAE,CAAC;IACzD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AACD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,yBAAyB,CAAC;IAChC,KAAK,EAAE,aAAa,GAAG,WAAW,CAAC;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;CACnB,CAAC,GACA,CACI,QAAQ,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAAE,CAAC,GAC1E,QAAQ,CAAC;IACP,MAAM,EAAE,WAAW,CAAC;IACpB,wBAAwB,EAAE,MAAM,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,SAAS,CAAC,KAAK,GAAG,QAAQ,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAAE,CAAC;IAClE,YAAY,EAAE,SAAS,QAAQ,CAAC;QAC9B,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;KAC/B,CAAC,EAAE,CAAC;IACL,SAAS,EAAE,SAAS,KAAK,EAAE,CAAC;CAC7B,CAAC,CACL,CAAC;AACJ;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,MAAM,IAAI,OAAO,CAAC;CACnB;AAgJD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CAiEd;AACD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,YAAY,CAoEd;AACD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,OAAO,EAAE,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3D,cAAc,CA2DhB"}