@e2edev/mobile 0.8.0-canary-20260921180210

package/dist/support.d.ts

@@ -0,0 +1,58 @@
+/** Shared helpers for the agent-device engine: error constructors, filenames, PNG headers, gestures, the screen location and size. */
+import { EngineError, type Momentum, type ScrollDirection, type ViewportSize } from 'e2e/engine';
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export declare function cancelled(text: string): EngineError;
+export declare function invalidState(text: string): EngineError;
+export declare function notActionable(text: string): EngineError;
+export declare function unsupported(text: string): EngineError;
+/** Constrains a caller-supplied artifact label to a safe filename. */
+export declare function sanitizeFilename(name: string): string;
+/** Reads the dimensions out of a PNG's IHDR chunk; undefined for anything else. */
+export declare function readPngSize(data: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * The finger gesture that scrolls one rect's content in `direction`. Scrolling
+ * down reveals what is below, so the finger travels up; the travel is a share
+ * of the rect's extent scaled by momentum, and never leaves the rect.
+ */
+export declare function swipeWithin(rect: Rect, direction: ScrollDirection, momentum: Momentum | undefined): {
+    from: Point;
+    to: Point;
+};
+/**
+ * The location a device surface reports in a snapshot: the foreground app
+ * and the screen shown, `<app> / <screen title>`. A simulator has no address
+ * bar, so this is an opaque address the harness shows to the model and the
+ * report and anchors trace replay on; it changes exactly when the app or its
+ * screen changes. It is deliberately not a URL: no scheme, no colon, so the
+ * harness never mistakes it for one and applies an origin policy to it.
+ * Undefined when neither the app nor a title is known.
+ */
+export declare function screenLocation(app: string | undefined, title: string | undefined): string | undefined;
+/** The screenshot fields a viewport probe reads off agent-device's response. */
+export interface RawScreenshotResult {
+    readonly path?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly logicalWidth?: number;
+    readonly logicalHeight?: number;
+    readonly pixelDensity?: number;
+}
+/**
+ * The device's logical screen size as its screenshot reports it, in points:
+ * the logical dimensions when given, else the pixel dimensions over the
+ * density. Undefined when the response carries neither.
+ */
+export declare function logicalScreenSize(result: RawScreenshotResult): ViewportSize | undefined;
+//# sourceMappingURL=support.d.ts.map

package/dist/support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../src/support.ts"],"names":[],"mappings":"AAAA,sIAAsI;AAEtI,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEnD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEvD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAErD;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAID,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAe5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKrG;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,mBAAmB,GAC1B,YAAY,GAAG,SAAS,CAS1B"}

package/dist/support.js

@@ -0,0 +1,82 @@
+/** Shared helpers for the agent-device engine: error constructors, filenames, PNG headers, gestures, the screen location and size. */
+import { EngineError } from 'e2e/engine';
+export function cancelled(text) {
+    return new EngineError('CANCELLED', text, { retryable: false });
+}
+export function invalidState(text) {
+    return new EngineError('INVALID_STATE', text, { retryable: false });
+}
+export function notActionable(text) {
+    return new EngineError('NOT_ACTIONABLE', text, { retryable: false });
+}
+export function unsupported(text) {
+    return new EngineError('UNSUPPORTED_CAPABILITY', text, { retryable: false });
+}
+/** Constrains a caller-supplied artifact label to a safe filename. */
+export function sanitizeFilename(name) {
+    return name.replaceAll(/[^A-Za-z0-9._-]/g, '_').slice(0, 64) || 'artifact';
+}
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Reads the dimensions out of a PNG's IHDR chunk; undefined for anything else. */
+export function readPngSize(data) {
+    if (data.byteLength < 24)
+        return undefined;
+    for (const [offset, byte] of PNG_SIGNATURE.entries()) {
+        if (data[offset] !== byte)
+            return undefined;
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+/**
+ * The finger gesture that scrolls one rect's content in `direction`. Scrolling
+ * down reveals what is below, so the finger travels up; the travel is a share
+ * of the rect's extent scaled by momentum, and never leaves the rect.
+ */
+export function swipeWithin(rect, direction, momentum) {
+    const ratio = momentum === 'fast' ? 0.8 : momentum === 'slow' ? 0.25 : 0.5;
+    const centre = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+    const dx = (rect.width * ratio) / 2;
+    const dy = (rect.height * ratio) / 2;
+    switch (direction) {
+        case 'down':
+            return { from: { x: centre.x, y: centre.y + dy }, to: { x: centre.x, y: centre.y - dy } };
+        case 'up':
+            return { from: { x: centre.x, y: centre.y - dy }, to: { x: centre.x, y: centre.y + dy } };
+        case 'right':
+            return { from: { x: centre.x + dx, y: centre.y }, to: { x: centre.x - dx, y: centre.y } };
+        case 'left':
+            return { from: { x: centre.x - dx, y: centre.y }, to: { x: centre.x + dx, y: centre.y } };
+    }
+}
+/**
+ * The location a device surface reports in a snapshot: the foreground app
+ * and the screen shown, `<app> / <screen title>`. A simulator has no address
+ * bar, so this is an opaque address the harness shows to the model and the
+ * report and anchors trace replay on; it changes exactly when the app or its
+ * screen changes. It is deliberately not a URL: no scheme, no colon, so the
+ * harness never mistakes it for one and applies an origin policy to it.
+ * Undefined when neither the app nor a title is known.
+ */
+export function screenLocation(app, title) {
+    const parts = [app, title]
+        .map((part) => (part === undefined ? '' : part.replaceAll(/\s+/g, ' ').trim()))
+        .filter((part) => part !== '');
+    return parts.length === 0 ? undefined : parts.join(' / ');
+}
+/**
+ * The device's logical screen size as its screenshot reports it, in points:
+ * the logical dimensions when given, else the pixel dimensions over the
+ * density. Undefined when the response carries neither.
+ */
+export function logicalScreenSize(result) {
+    const logical = result.logicalWidth !== undefined && result.logicalHeight !== undefined
+        ? { width: result.logicalWidth, height: result.logicalHeight }
+        : result.width !== undefined && result.height !== undefined && result.pixelDensity !== undefined && result.pixelDensity > 0
+            ? { width: result.width / result.pixelDensity, height: result.height / result.pixelDensity }
+            : undefined;
+    if (logical === undefined || logical.width <= 0 || logical.height <= 0)
+        return undefined;
+    return logical;
+}
+//# sourceMappingURL=support.js.map

package/dist/support.js.map

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

package/dist/surface.d.ts

@@ -0,0 +1,243 @@
+/**
+ * The agent-device surface: one simulator or emulator session, driven through
+ * agent-device's typed client, exposed to the runner as the contract's
+ * observe/locate/perform members. It owns the id space (one fresh generation
+ * per observation), the attempt state (artifact directory, screenshot
+ * counter), and every translation between the contract's vocabulary and
+ * agent-device's commands. Its device and session come from the target's
+ * `DevicePool`, by worker slot. The runner owns everything else.
+ *
+ * Every observation is reported under one root of a stable id (`ROOT_ID`)
+ * wrapping the device's top-level elements; a `swipe` performed on that root
+ * scrolls the whole screen.
+ */
+import { type EngineAttemptContext, type EngineCleanupContext, type EngineInitInfo, type EngineObserveOptions, type EngineSnapshot, type LocatorAction, type LocatorExpression, type NodeRef, type OperationContext, type PointerAction, type VideoSegment, type SemanticNode, type ViewportPoint } from 'e2e/engine';
+import type { AgentDeviceClient, MobileOptions, ClientFactory } from './options.ts';
+import { DevicePool } from './pool.ts';
+/** How `installApp` puts a build on the device. */
+export interface InstallAppOptions {
+    /**
+     * Bundle id or package of the build. `reinstall` needs one: agent-device
+     * removes that app before installing. Defaults to the pinned app.
+     */
+    readonly app?: string;
+    /** Remove the installed app first so the build starts with no data. */
+    readonly reinstall?: boolean;
+}
+/** What an install put on the device, as agent-device identified it. */
+export interface InstalledApp {
+    /** The bundle id or package to open the app by. */
+    readonly app: string;
+    readonly bundleId?: string;
+}
+/** What agent-device is told about settling after an action. */
+type SettleOptions = {
+    readonly settle: true;
+    readonly settleQuietMs: number;
+} | Record<never, never>;
+export declare class AgentDeviceSurface {
+    readonly options: MobileOptions;
+    private readonly createClient;
+    private client;
+    private attempt;
+    /** The device this worker drives, the pool's entry for its slot; undefined leaves the choice to agent-device. */
+    private device;
+    private generation;
+    private readonly located;
+    private idCounter;
+    private appIdentity;
+    /** The app the build `appPath` installed, once `init` has, itself or through a lease. */
+    private installedApp;
+    /** Where relative build paths resolve; the run's project root once init has told us. */
+    private projectRoot;
+    /**
+     * Commands still running on the device. agent-device takes no abort
+     * signal, so a cancelled or timed-out call is only abandoned by its
+     * caller; it keeps executing. The next attempt waits for these to settle
+     * before it opens anything, so a ghost tap can never land in a retry.
+     */
+    private readonly inflight;
+    /** The target's devices, one per worker slot; `init` takes this worker's from it. */
+    readonly pool: DevicePool;
+    /** The settle wait every action carries: quiet window from the `settle` option, or nothing when it is `false`. */
+    readonly settleOptions: SettleOptions;
+    /** When this surface last acted on the device (an input or an app launch); the screen may be in transition for a while after. */
+    private lastActionAt;
+    /** The screen as last projected before that action, to tell controls that were already there from ones that came with it. */
+    private indexBeforeAction;
+    /** The most recent projection of the screen, from any observe or locate. */
+    private latestIndex;
+    /** Budget a control that came with the last action gets to finish arriving; see DEFAULT_TRANSITION_MS. */
+    private readonly transitionMs;
+    /**
+     * The screen's logical size as last learned from a snapshot with geometry
+     * or from the device itself, so a snapshot without geometry (an empty
+     * screen before any app is open, a sparse tree) still reports the viewport
+     * every observation must carry.
+     */
+    private knownViewport;
+    constructor(options: MobileOptions, createClient: ClientFactory);
+    /** Whether the manifest declares app restart and state clearing. */
+    get managesApp(): boolean;
+    /** The app opened fresh per attempt: the `app` option, else the build `appPath` installed. */
+    get pinnedApp(): string | undefined;
+    /** Whether an attempt is running on this surface right now. */
+    get attemptRunning(): boolean;
+    /** The live client; INVALID_STATE before init or after dispose. */
+    requireClient(): AgentDeviceClient;
+    /**
+     * Runs one agent-device command under an operation budget and translates
+     * its failure. Contributed-fixture methods route through here too, so the
+     * device fixture never carries its own error mapping.
+     */
+    command<T>(label: string, run: (client: AgentDeviceClient) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Registers one device command as in flight until it settles. */
+    private track;
+    /**
+     * Waits for every abandoned command to settle, within the caller's
+     * budget. A command that never settles fails the attempt launch instead of
+     * racing it: the launch timeout is the honest bound on a stuck device.
+     */
+    private settleInflight;
+    /** The device selection this worker's commands take. */
+    private selection;
+    init(info: EngineInitInfo): Promise<void>;
+    startAttempt(context: EngineAttemptContext): Promise<void>;
+    endAttempt(context: EngineCleanupContext): Promise<void>;
+    /**
+     * Asks the device to record its screen into the attempt directory. Taps stay
+     * visible in the recording (agent-device's touch indicator), which is the
+     * closest a phone comes to a cursor.
+     */
+    startVideo(operation: OperationContext): Promise<void>;
+    /** Stops the recording and returns its one segment, or none when the device wrote nothing. */
+    stopVideo(operation: OperationContext): Promise<readonly VideoSegment[]>;
+    dispose(context: EngineCleanupContext): Promise<void>;
+    /** Opens an app in the session, remembering its identity for the path anchor. */
+    openApp(app: string, relaunch: boolean, signal: AbortSignal): Promise<void>;
+    /**
+     * Installs a build on the session's device. `reinstall` removes the app
+     * named by `options.app` (else the pinned app) first, so the build starts
+     * with no data; a plain install replaces the binary and keeps its data.
+     */
+    installApp(appPath: string, options: InstallAppOptions, signal: AbortSignal): Promise<InstalledApp>;
+    private snapshot;
+    /**
+     * Snapshot for an observation. Without a pinned app, an observation before
+     * anything is open is an empty screen rather than a fault: the model's next
+     * move is the open tool, and failing the step would take that move away.
+     */
+    private snapshotOrEmpty;
+    private project;
+    /**
+     * The viewport of a snapshot: its own geometry, else the last one this
+     * session learned, else the device's logical screen size read off one
+     * screenshot. A device whose size cannot be learned fails the observation:
+     * the harness measures every rect and point against the viewport, so an
+     * invented one would misplace every tap.
+     */
+    private viewportFor;
+    /** The device's logical screen size as its screenshot reports it; undefined when it reports none. */
+    private probeViewport;
+    observe(operation: OperationContext, options?: EngineObserveOptions): Promise<EngineSnapshot>;
+    /** Retains only action bindings for matches, independently of the observation generation. */
+    locate(expression: LocatorExpression, operation: OperationContext): Promise<readonly SemanticNode[]>;
+    private resolveRef;
+    private actionTarget;
+    /**
+     * The node a toggle press must land on. UIKit reports a settings row as a
+     * labelled `Switch` spanning the whole row with the real control as an
+     * unlabelled `Switch` child at its trailing edge; a press at the row's
+     * centre hits the label and changes nothing. The innermost same-role
+     * descendant with a ref is the control; a node without one is its own.
+     */
+    private controlOf;
+    /** Copies the fields actions use and pre-resolves a toggle's inner control. */
+    private bind;
+    /**
+     * The node a binding stands for, in a fresh snapshot: same role, same test
+     * id, same name and text, and of those the one closest to where it was.
+     */
+    private refind;
+    /**
+     * Lets a control that came with the last action finish arriving before a
+     * test acts on it. A control already present at the same place in the
+     * snapshot the last action was resolved from is not in transition and is
+     * acted on at once; anything else waits out the remainder of the
+     * transition budget since that action. Nothing is observed here: the
+     * budget is the only signal, because the tree reports final frames.
+     */
+    private awaitTransition;
+    /**
+     * Records an action the device received: the screen as it was projected
+     * before it, and when it returned. The transition budget counts from the
+     * return, since the input lands late in the command's own round trip.
+     */
+    private markAction;
+    perform(ref: NodeRef, action: LocatorAction, operation: OperationContext): Promise<void>;
+    /**
+     * Keys on a touch surface, in the contract's key grammar: `Enter` submits
+     * through the soft keyboard, `Space` and any single character are typed
+     * into the focused field. agent-device exposes no key event bus, so
+     * modifiers and the other named keys (`Escape`, `Tab`, `Backspace`, the
+     * arrows) have nothing to land on and are refused.
+     */
+    private pressKey;
+    /**
+     * One pointer action at a screen point in logical pixels, the space every
+     * node's bounds are in, with no element resolved behind it. `settle` waits
+     * for the UI to go quiet, as the node taps do.
+     */
+    performAt(point: ViewportPoint, action: PointerAction, operation: OperationContext): Promise<void>;
+    /**
+     * Types into whatever holds focus through the device's text-input path;
+     * agent-device's `type` lands on the focused field. `replace` is not a
+     * device primitive without a target, so it is refused rather than faked:
+     * the model clears a listed field by filling it by id.
+     */
+    typeText(text: string, options: {
+        readonly replace: boolean;
+    }, operation: OperationContext): Promise<void>;
+    /**
+     * One key to the focused field, with the same reach as a node press: Enter
+     * submits through the soft keyboard, Space and single characters are typed.
+     * Modifiers and the other named keys have no event bus to land on.
+     */
+    pressFocusedKey(key: string, operation: OperationContext): Promise<void>;
+    /** Hides the soft keyboard, so a control it covered can be reached. */
+    dismissKeyboard(operation: OperationContext): Promise<void>;
+    back(operation: OperationContext): Promise<void>;
+    restart(operation: OperationContext): Promise<void>;
+    /** Clears the pinned app's persisted state and relaunches it: the device equivalent of a fresh context. */
+    reset(operation: OperationContext): Promise<void>;
+    /**
+     * A redacted screenshot artifact. The device paints secure fields as dots,
+     * but the last typed character shows in clear, so every secure node's
+     * bounds are painted over before the file is kept. A secure node without
+     * bounds cannot be masked, and an image that cannot be redacted is not
+     * written at all.
+     */
+    screenshot(label: string | undefined, operation: OperationContext): Promise<string>;
+    /** Raw device pixels; cleanup follows the capture even when its caller abandons it. */
+    private rawScreenshot;
+    /**
+     * One screenshot into a temp directory that is removed once `read` has
+     * taken what it needs from the response or the file, even when the caller
+     * abandons the capture.
+     */
+    private captureScreenshot;
+    /**
+     * Screenshot with every secure node on the current screen painted over.
+     * Observes first so the regions describe the screen the pixels show;
+     * throws when a secure field cannot be covered, because an image that may
+     * hold a credential must not leave the engine.
+     */
+    private maskedScreenshot;
+    /**
+     * Viewport pixels for an observation. Best-effort: a screenshot that cannot
+     * be produced or redacted costs the observation its image, not the step.
+     */
+    private capturePixels;
+}
+export {};
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAML,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAEZ,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAcpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAkB,aAAa,EAAE,MAAM,cAAc,CAAC;AAGpG,OAAO,EAAE,UAAU,EAAmB,MAAM,WAAW,CAAC;AAcxD,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAmGD,gEAAgE;AAChE,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAuBtG,qBAAa,kBAAkB;IA0C3B,QAAQ,CAAC,OAAO,EAAE,aAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IA1C/B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAsB;IACrC,iHAAiH;IACjH,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAqB;IACxC,yFAAyF;IACzF,OAAO,CAAC,YAAY,CAAqB;IACzC,wFAAwF;IACxF,OAAO,CAAC,WAAW,CAAiB;IACpC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IAExD,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,kHAAkH;IAClH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,iIAAiI;IACjI,OAAO,CAAC,YAAY,CAAK;IACzB,6HAA6H;IAC7H,OAAO,CAAC,iBAAiB,CAAuC;IAChE,4EAA4E;IAC5E,OAAO,CAAC,WAAW,CAAuC;IAC1D,0GAA0G;IAC1G,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAA2B;IAEhD,YACW,OAAO,EAAE,aAAa,EACd,YAAY,EAAE,aAAa,EAK7C;IAED,oEAAoE;IACpE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,8FAA8F;IAC9F,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,+DAA+D;IAC/D,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,mEAAmE;IACnE,aAAa,IAAI,iBAAiB,CAGjC;IAED;;;;OAIG;IACG,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhH;IAED,kEAAkE;IAClE,OAAO,CAAC,KAAK;IASb;;;;OAIG;YACW,cAAc;IAM5B,wDAAwD;IACxD,OAAO,CAAC,SAAS;IAIX,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAW9C;IAEK,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/D;IAEK,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7D;IAID;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3D;IAED,8FAA8F;IACxF,SAAS,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAkB7E;IAEK,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1D;IAED,iFAAiF;IAC3E,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhF;IAED;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAiBxG;YAEa,QAAQ;IAkBtB;;;;OAIG;YACW,eAAe;IAS7B,OAAO,CAAC,OAAO;IAYf;;;;;;OAMG;YACW,WAAW;IAezB,qGAAqG;YACvF,aAAa;IAKrB,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAalG;IAED,6FAA6F;IACvF,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAUzG;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAMpB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAgBjB,+EAA+E;IAC/E,OAAO,CAAC,IAAI;IAMZ;;;OAGG;IACH,OAAO,CAAC,MAAM;IAwBd;;;;;;;OAOG;YACW,eAAe;IAiB7B;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAKZ,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4F7F;IAED;;;;;;OAMG;YACW,QAAQ;IAuBtB;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvG;IAED;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB7E;IAED,uEAAuE;IACjE,eAAe,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhE;IAEK,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrD;IAEK,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxD;IAED,2GAA2G;IACrG,KAAK,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAStD;IAED;;;;;;OAMG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUxF;IAED,uFAAuF;IACvF,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;OAKG;YACW,gBAAgB;IAmB9B;;;OAGG;YACW,aAAa;CAqB5B"}