@camstack/types 0.1.14 → 0.1.16

package/dist/device/base-device.d.ts

@@ -0,0 +1,287 @@
+import { z } from 'zod';
+import { DeviceConfig } from './device-config.js';
+import type { IDeviceRuntimeState } from './device-runtime-state.js';
+import type { DeviceType, DeviceFeature, DeviceRole } from './device-type.js';
+import type { DeviceContext } from './device-context.js';
+import type { IDevice } from './device.js';
+import type { ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
+import type { CapabilityDefinition, InferRuntimeState } from '../capabilities/capability-definition.js';
+import { type DeviceLocalState } from '../generated/device-local-state.js';
+export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseShape> = z.ZodObject<z.ZodRawShape>> implements IDevice {
+    readonly id: number;
+    readonly stableId: string;
+    readonly type: DeviceType;
+    readonly name: string;
+    readonly parentDeviceId: number | null;
+    readonly role?: DeviceRole;
+    /**
+     * Cap-keyed runtime-state slice is the single source of truth for
+     * `online`. Both getter and setter proxy to the slice — drivers can
+     * write `this.online = true` ergonomically, and the cap event fires
+     * automatically through the runtime-state writer. `markOnline()` is
+     * kept as the explicit method form mandated by `IDevice`.
+     */
+    get online(): boolean;
+    set online(value: boolean);
+    /**
+     * Generic per-cap runtime-state namespace. One entry per cap with
+     * `runtimeState:` declared, auto-generated by codegen — see
+     * `device-local-state.ts`. Drivers access via:
+     *
+     *   `this.state.battery.sleeping = true`        // patches the battery slice
+     *   `const pct = this.state.battery.percentage` // reads the battery slice
+     *   `this.state.deviceStatus.online = true`     // mirrors `markOnline(true)`
+     *
+     * Adding a new cap with `runtimeState:` automatically extends this
+     * namespace — drivers don't have to declare proxies. Reads return
+     * `undefined` when the slice hasn't been seeded; writes patch via
+     * `runtimeState.patchCapState` and validate against the cap's schema
+     * (so partial writes need the slice to be seeded with the required
+     * fields first — drivers do this on cap registration).
+     *
+     * For caps not exposed in `DeviceLocalState`, drivers can build their
+     * own typed proxy via `this.sliceProxy(cap)`.
+     */
+    get state(): DeviceLocalState;
+    private _stateProxyCache?;
+    abstract readonly features: readonly DeviceFeature[];
+    readonly config: DeviceConfig<T>;
+    /**
+     * Per-device runtime state, cap-keyed. Always installed — slices
+     * for individual caps materialise as those caps register their
+     * native providers (`ctx.registerNativeCap`). The cap's own
+     * `runtimeState` schema is the source of truth for the slice
+     * shape; drivers don't redeclare it, they just write through.
+     *
+     * Read: `this.runtimeState.getCapState('battery')` →
+     *   `{percentage, charging, sleeping, lastUpdated}` for any
+     *   provider that registers `batteryCapability`.
+     * Write: `this.runtimeState.setCapState('battery', { … })`.
+     *
+     * Cross-process consumers reach this state through the
+     * `deviceState` cap router (or via cap-specific events the driver
+     * emits — e.g. `battery.onStatusChanged`). The local handle is
+     * accessed in-process by the driver to avoid roundtrips.
+     */
+    readonly runtimeState: IDeviceRuntimeState;
+    readonly ctx: DeviceContext;
+    /**
+     * Operator-organisational location label (room / area / zone).
+     * Read from `ctx.deviceMeta.location`; mutated via
+     * `kernel.devices.setLocation(id, value)`. Free-text — providers
+     * don't interpret it; the UI groups devices by this for filters
+     * like "show me all cameras in Kitchen". `null` when unset.
+     */
+    readonly location: string | null;
+    /**
+     * Soft-disabled flag. When `true`, the device class is still
+     * instantiated and visible in the UI (so the operator can flip
+     * back on without re-adding) but lifecycle hooks (publishToBroker,
+     * alarm-stream subscribe, …) MUST be gated by the driver to skip
+     * work. The `BaseDevice` enforces this by exposing the flag here;
+     * it does NOT mutate cap behaviour automatically — drivers consult
+     * `this.disabled` at the top of their lifecycle methods. Read from
+     * `ctx.deviceMeta.disabled`; mutated via
+     * `kernel.devices.setDisabled(id, value)`.
+     */
+    readonly disabled: boolean;
+    constructor(ctx: DeviceContext, schema: T, options: {
+        type: DeviceType;
+        /** Optional semantic role within parent — see `DeviceRole`. */
+        role?: DeviceRole;
+    });
+    removeDevice(): Promise<void>;
+    /**
+     * Set the device's online flag. Called by `BaseDeviceProvider` after
+     * aggregating per-profile stream-broker health, or directly by drivers
+     * that have provider-side liveness signals (e.g. ONVIF heartbeats,
+     * Reolink Baichuan firmware push events). Mirrors the new value into
+     * the `device-status` runtime-state slice so cross-process consumers
+     * pick it up via the standard cap-state channel. Subclasses can
+     * override to gate side effects on the transition.
+     */
+    markOnline(online: boolean): void;
+    /**
+     * Re-publish the device's current `features` array to the persisted
+     * meta blob. Drivers call this after a probe finishes when the live
+     * `features` getter has gained new flags (e.g. `hasIntercom` flips
+     * to true → `DeviceFeature.TwoWayAudio` joins the list).
+     *
+     * Without this, only the construction-time snapshot is written —
+     * `deviceManager.registerDevice` is invoked once per boot, so probe-
+     * driven additions don't reach the persisted index until the next
+     * server restart, and `getDevice` / `listAll` keep returning the
+     * stale list for forked-worker devices (whose live IDevice instance
+     * is invisible to the hub registry).
+     *
+     * Idempotent: re-calling with the same features just no-ops on the
+     * persisted meta. Best-effort: lookup or write failures are logged
+     * at debug and swallowed — the live `device.features` getter is
+     * still authoritative within this process, so callers never block
+     * device boot on a meta refresh.
+     */
+    protected refreshFeatures(): Promise<void>;
+    /**
+     * Typed read-through to a cap-keyed runtime-state slice. Drivers
+     * call `this.getCapSlice(batteryCapability)` and the return type
+     * is inferred from the cap's `runtimeState` Zod schema — no string
+     * key, no manual generic. Returns `null` when the slice hasn't
+     * been written yet (e.g. driver hasn't seeded battery yet).
+     */
+    protected getCapSlice<TCap extends CapabilityDefinition>(cap: TCap): InferRuntimeState<TCap> | null;
+    /**
+     * Typed writer to a cap-keyed runtime-state slice. Routes through
+     * the runtime-state writer (validate → persist → emit cap event).
+     * Equivalent to `this.runtimeState.setCapState(cap.name, value)`
+     * but with the cap's `runtimeState` schema enforcing the value
+     * shape at compile time. Mirrors the symmetry of
+     * `getCapSlice` / `setCapSlice` for cross-cap consistency.
+     */
+    protected setCapSlice<TCap extends CapabilityDefinition>(cap: TCap, value: InferRuntimeState<TCap> & Record<string, unknown>): void;
+    /**
+     * Field-level read/write proxy over a cap's runtime-state slice.
+     * Drivers that want ergonomic per-field access declare:
+     *
+     * ```ts
+     * protected battery = this.sliceProxy(batteryCapability)
+     * // …
+     * this.battery.sleeping = true        // patches the slice
+     * const charging = this.battery.charging  // reads the slice
+     * ```
+     *
+     * Reads return `undefined` when the slice hasn't been seeded yet
+     * (cap not registered, or seeded but the field is absent). Writes
+     * route through `runtimeState.patchCapState` so the cap's `runtimeState`
+     * schema validates the merged result and the cap event fires.
+     *
+     * Pattern is generic — same shape works for `battery`, `device-status`,
+     * `motion`, `doorbell`, anything with a `runtimeState:` schema. Drivers
+     * declare one proxy per cap they read/write directly.
+     */
+    protected sliceProxy<TCap extends CapabilityDefinition>(cap: TCap): InferRuntimeState<TCap>;
+    /**
+     * Default empty settings UI. Drivers override this to expose an
+     * editable form in the device-details page. Returning an empty sections
+     * array signals "nothing to contribute" — the aggregator drops the
+     * contribution entirely rather than rendering a blank panel.
+     */
+    getSettingsUISchema(): ConfigUISchemaWithValues;
+    /**
+     * Default write path: forward the flat patch directly to storage.
+     * Drivers that project a UI shape different from storage (e.g. `RtspCamera`
+     * exposing `mainStreamUrl`/`subStreamUrl` over `streams[]`) override this
+     * to reshape before `config.setAll`.
+     */
+    applySettingsPatch(patch: Record<string, unknown>): Promise<void>;
+    /**
+     * Phase 3 — populate device-scoped state needed by downstream phases
+     * (accessory reconciliation, public `features` array, optional cap
+     * registration). Called ONCE per construction, after register but
+     * before `getAccessoryChildren()`.
+     *
+     * Drivers write the `feature-probe` runtime-state slice via
+     * `this.runtimeState.setCapState('feature-probe', {...})` — flag bag
+     * is open (Reolink writes `hasPtz/hasIntercom`, Hikvision writes
+     * `hasSupplementalLight/hasAlarmIo`, etc).
+     *
+     * Default: no-op (driver had no probe to run).
+     */
+    onProbe(): Promise<void>;
+    /**
+     * Phase 5 — fired after the device + its accessories are registered.
+     * Drivers publish streams to the broker, kick off background tasks,
+     * or subscribe to lib events that need a fully-registered device id.
+     *
+     * Default: no-op.
+     *
+     * RENAMED FROM `onCreated` (which still exists for back-compat in this
+     * pass). The new name reflects the post-probe, post-accessory contract.
+     */
+    onActivate(): Promise<void>;
+    /**
+     * Re-run the probe + reconcile accessories + refresh features meta.
+     * Drivers call this when device-side state changes (battery cam wakes,
+     * firmware update, manual operator trigger).
+     *
+     * The kernel injects `_kernelReprobe` on registration so this method
+     * delegates to the same orchestrator that runs the boot-time phase
+     * 3 + 4 sequence. Drivers should NOT override this — they override
+     * `onProbe()` instead.
+     */
+    reprobe(): Promise<void>;
+    /**
+     * Kernel-injected callback that runs the full post-probe orchestration
+     * (onProbe → registerDevice meta refresh → accessory reconciliation).
+     * Set by `device-cap-proxy.register()`. Drivers should not touch this
+     * directly — call `reprobe()` instead.
+     */
+    _kernelReprobe?: () => Promise<void>;
+    /**
+     * Declare accessory child devices the kernel should auto-spawn
+     * after `onProbe()` resolves. Each spec fully describes one child
+     * — stableId suffix (deterministic per kind for restore-safety),
+     * meta (type / name / location), config (initial blob the child
+     * self-hydrates), and a factory that constructs the concrete
+     * class with whatever closure-captured refs it needs (typically
+     * `this` for the parent reference).
+     *
+     * The kernel handles the rest: allocateDeviceId, persistInitialConfig
+     * (skipped on restore when the row already exists),
+     * persistInitialMeta, createContext, factory invocation, register,
+     * and recursive lifecycle (probe + accessories + activate).
+     *
+     * Implementations should derive children from
+     * `this.runtimeState.getCapState('feature-probe')` (post-probe truth).
+     * Drivers can use the `getProbeFlags()` helper to read the flag bag
+     * with a typed cast.
+     *
+     * Default: no children.
+     */
+    getAccessoryChildren(): readonly AccessoryChildSpec[];
+    /**
+     * Read the current feature-probe flag bag with a typed cast. Helper
+     * for `getAccessoryChildren()` and `features` getters that derive
+     * outputs from the probe results.
+     */
+    protected getProbeFlags<F extends Record<string, unknown> = Record<string, unknown>>(): F;
+    /**
+     * Returns true once `onProbe` has completed at least once
+     * (`lastProbedAt > 0`). Drivers gate `getAccessoryChildren()` on this
+     * to avoid spawning stale accessories on a fresh device whose probe
+     * hasn't landed yet.
+     */
+    protected hasProbed(): boolean;
+}
+/**
+ * Specification for one accessory child a parent device wants the
+ * kernel to auto-spawn. Returned from `BaseDevice.getAccessoryChildren()`.
+ */
+export interface AccessoryChildSpec {
+    /**
+     * Stable suffix appended to the parent's stableId to derive the
+     * child's stableId (e.g. `siren` → `${parent.stableId}-siren`).
+     * Must be deterministic per (parent, accessory kind) so restore
+     * resolves the same numeric id and re-instantiates without
+     * orphaning the persisted config.
+     */
+    readonly stableIdSuffix: string;
+    /** Operator-organisational meta passed to `kernel.devices.create()`'s
+     *  `initialMeta` arg. The kernel pre-writes the meta row before
+     *  the child class constructor runs. */
+    readonly meta: import('./device-management.js').InitialDeviceMeta;
+    /** Initial config blob the child self-hydrates from on first
+     *  create. Empty `{}` on restore (DB row carries the canonical
+     *  values) — the kernel detects the existing row and skips the
+     *  pre-persist step. */
+    readonly config: Record<string, unknown>;
+    /**
+     * Constructor closure — invoked with the kernel-built context
+     * after meta + config are persisted. Closures over the parent
+     * reference for child classes that need `parent` as a constructor
+     * arg (e.g. accessories that share the parent's connection). The
+     * returned IDevice is registered + `onCreated`-fired by the
+     * kernel.
+     */
+    readonly factory: (ctx: DeviceContext) => IDevice;
+}
+//# sourceMappingURL=base-device.d.ts.map

package/dist/device/base-device.d.ts.map

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

package/dist/device/camera-device.d.ts

@@ -0,0 +1,49 @@
+import type { StreamQuality } from '../interfaces/device-capabilities/camera.js';
+import type { IDevice } from './device.js';
+import type { DeviceType } from './device-type.js';
+export interface StreamSourceEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly protocol: 'rtsp' | 'rtmp' | 'annexb' | 'http-mjpeg' | 'webrtc' | 'custom';
+    /** Stream URL — required for rtsp, rtmp, http-mjpeg. Not used for annexb/custom. */
+    readonly url?: string;
+    /**
+     * Stream metadata — optional. If omitted, the stream-broker will probe
+     * the stream (via ffprobe) on first registration to discover resolution/fps/codec.
+     * Providers that already know the metadata (e.g. ONVIF profiles) should provide it
+     * to avoid the probe delay.
+     */
+    readonly resolution?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly fps?: number;
+    readonly bitrate?: number;
+    readonly codec?: string;
+    /** Hint: suggested quality profile. Stream-broker may override after probing. */
+    readonly profileHint?: StreamQuality;
+    /**
+     * Pre-built SDP. Drivers that publish a `pull-rfc4571` source can
+     * derive a synthetic SDP from device-side metadata (e.g. Reolink
+     * `getStreamMetadata` cmd_id 56 — `videoEncType` + audio config) so
+     * the broker's `metadata.sdp` is populated WITHOUT first opening an
+     * upstream streaming session. SPS/PPS are intentionally omitted —
+     * the lib's `Rfc4571Muxer.sendCachedVideoConfigToClient` primes
+     * downstream consumers from in-band keyframe NAL units.
+     *
+     * Drivers that need full SDP (with parameter sets) still open a real
+     * streaming session at publish time — the field stays optional.
+     */
+    readonly sdp?: string;
+}
+/**
+ * Camera device interface — extends IDevice with stream source exposure.
+ * Every camera MUST implement getStreamSources() to tell the stream-broker
+ * how to consume its video feeds. The broker will probe streams that lack
+ * metadata (resolution/fps) and assign quality profiles automatically.
+ */
+export interface ICameraDevice extends IDevice {
+    readonly type: typeof DeviceType.Camera;
+    getStreamSources(): Promise<readonly StreamSourceEntry[]>;
+}
+//# sourceMappingURL=camera-device.d.ts.map

package/dist/device/camera-device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-device.d.ts","sourceRoot":"","sources":["../../src/device/camera-device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAClF,oFAAoF;IACpF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAA;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C,QAAQ,CAAC,IAAI,EAAE,OAAO,UAAU,CAAC,MAAM,CAAA;IACvC,gBAAgB,IAAI,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAA;CAC1D"}

package/dist/device/device-binding.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-device capability binding record. For each capability a device supports,
+ * one entry tells consumers which addon+node currently serves it (native or
+ * wrapper) and which addon provides the underlying native in case a wrapper is
+ * active.
+ */
+export interface DeviceBindingEntry {
+    capName: string;
+    kind: 'native' | 'wrapped';
+    /** Currently-active provider. For kind='native', equal to `nativeAddonId`.
+     *  For kind='wrapped', the wrapper addon id. */
+    providerAddonId: string;
+    /** Node where the active provider runs. 'hub' for native; may vary for wrappers. */
+    providerNodeId: string;
+    /** Always the addon id of the underlying native provider for the device. */
+    nativeAddonId: string;
+}
+export interface DeviceBinding {
+    /** Numeric device id — matches `IDevice.id`. */
+    deviceId: number;
+    entries: DeviceBindingEntry[];
+}
+//# sourceMappingURL=device-binding.d.ts.map

package/dist/device/device-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-binding.d.ts","sourceRoot":"","sources":["../../src/device/device-binding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC1B;oDACgD;IAChD,eAAe,EAAE,MAAM,CAAA;IACvB,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,kBAAkB,EAAE,CAAA;CAC9B"}

package/dist/device/device-config.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+/**
+ * Optional callback invoked when `fromSchema` had to drop one or
+ * more persisted fields to recover from a Zod validation failure.
+ * Used by `BaseDevice` to surface the action via the device logger.
+ */
+export type ConfigRecoveryListener = (info: {
+    droppedKeys: readonly string[];
+    issues: readonly z.core.$ZodIssue[];
+}) => void;
+export declare class DeviceConfig<T extends z.ZodObject<z.core.$ZodLooseShape>> {
+    readonly schema: T;
+    private data;
+    private readonly persistFn;
+    private constructor();
+    /**
+     * Build a `DeviceConfig` from a persisted blob, with automatic
+     * recovery from schema-validation failures. Boot must never be
+     * blocked by stale persisted values: if Zod rejects the blob,
+     * we drop every offending top-level field, retry, and persist
+     * the cleaned blob so the bad value is healed in the DB on next
+     * write. The most common trigger is a tightened range constraint
+     * (e.g. `max(100) → max(50)`) on a field that already has an
+     * out-of-range value persisted from the previous schema. Without
+     * this safety net, the device would fail to instantiate and end
+     * up with no caps registered — exactly the failure mode that
+     * stranded device 15 when `motionSensitivity: 90` no longer fit
+     * the new `1..50` schema.
+     *
+     * Recovery rules:
+     *  1. Try `safeParse(initialData)`. If it succeeds, done.
+     *  2. On failure, walk `error.issues`, collect the top-level path
+     *     of each issue, and drop those keys from `initialData`.
+     *  3. Re-run `safeParse`. If the cleaned blob now passes (Zod
+     *     fills the missing keys with schema defaults / undefined for
+     *     `.optional()`), persist it via `persist()` so the bad
+     *     values disappear from the DB, and return the device.
+     *  4. If the cleaned blob STILL fails (very rare — would require
+     *     a non-recoverable required field), fall back to
+     *     `schema.parse({})` so the device still boots with pure
+     *     schema defaults. Persist nothing in that path so the next
+     *     successful `setAll` still writes a coherent blob.
+     */
+    static fromSchema<T extends z.ZodObject<z.core.$ZodLooseShape>>(schema: T, persist: (data: z.infer<T>) => Promise<void>, initialData?: Record<string, unknown>, onRecover?: ConfigRecoveryListener): DeviceConfig<T>;
+    get values(): z.infer<T>;
+    get<K extends keyof z.infer<T>>(key: K): z.infer<T>[K];
+    set<K extends keyof z.infer<T>>(key: K, value: z.infer<T>[K]): Promise<void>;
+    /**
+     * Merge an untyped patch onto the current config and persist. Accepts
+     * `Record<string, unknown>` because the patch typically comes from the
+     * UI form layer (a `ConfigField.key → value` map) where the caller
+     * doesn't hold the Zod schema's static type. Runtime validation is
+     * authoritative: `this.schema.parse` rejects unknown keys or invalid
+     * shapes before touching storage.
+     */
+    setAll(partial: Record<string, unknown>): Promise<void>;
+    deleteKey<K extends keyof z.infer<T>>(key: K): Promise<void>;
+    entries(): Array<{
+        key: string;
+        schema: z.ZodType;
+        value: unknown;
+        description?: string;
+    }>;
+}
+//# sourceMappingURL=device-config.d.ts.map

package/dist/device/device-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-config.d.ts","sourceRoot":"","sources":["../../src/device/device-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,IAAI,EAAE;IAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAA;CACpC,KAAK,IAAI,CAAA;AAEV,qBAAa,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;IACpE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAClB,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAE/D,OAAO;IAUP;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,EAC5D,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAC5C,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACzC,SAAS,CAAC,EAAE,sBAAsB,GACjC,YAAY,CAAC,CAAC,CAAC;IAuClB,IAAI,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAEvB;IAED,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAIhD,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlF;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlE,OAAO,IAAI,KAAK,CAAC;QACf,GAAG,EAAE,MAAM,CAAA;QACX,MAAM,EAAE,CAAC,CAAC,OAAO,CAAA;QACjB,KAAK,EAAE,OAAO,CAAA;QACd,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CAAC;CASH"}