@e2e-dev/web 0.11.0-canary-20260928184528

package/dist/locators.js

@@ -0,0 +1,289 @@
+/** LocatorExpression -> Playwright locator projection. */
+import { EngineError } from 'e2e/engine';
+import { SEARCH_ROOTS_SELECTOR_ENGINE } from './closed-shadow.js';
+import { exactLabelSelector } from './label-selector.js';
+import { SECURE_FIELD_SELECTOR } from './read-node.js';
+function patternToPw(pattern) {
+    if (pattern.kind === 'regexp')
+        return new RegExp(pattern.source, pattern.flags);
+    return pattern.value;
+}
+function patternExact(pattern) {
+    return pattern.kind === 'string' ? pattern.exact : false;
+}
+/**
+ * The selector `getByTestId` compiles to, with the project's attribute in
+ * place of Playwright's process-global one (`selectors.setTestIdAttribute`
+ * would leak one engine's attribute into every other engine of the process).
+ * The value is encoded as Playwright's `escapeForAttributeSelector` encodes it:
+ * a string is an exact, case-sensitive match; a RegExp is passed as written.
+ */
+function testIdSelector(attribute, pattern) {
+    const name = attribute.includes(',') ? JSON.stringify(attribute) : attribute;
+    const value = pattern.kind === 'regexp'
+        ? escapeRegexForSelector(new RegExp(pattern.source, pattern.flags))
+        : `"${pattern.value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"s`;
+    return `internal:testid=[${name}=${value}]`;
+}
+/** A RegExp written into a Playwright selector: quotes and `>>` escaped unless the flags forbid it. */
+function escapeRegexForSelector(re) {
+    if (/[uv]/.test(re.flags))
+        return String(re);
+    return String(re)
+        .replace(/(^|[^\\])(\\\\)*(["'`])/g, '$1$2\\$3')
+        .replace(/>>/g, '\\>\\>');
+}
+/**
+ * The contract's role vocabulary spelled as the ARIA role the role selector
+ * knows, where the two differ: the tree reports an `img` as `image`, so an
+ * `image` query has to go back to `img` to match it.
+ */
+const ARIA_ROLE_BY_CONTRACT_ROLE = { image: 'img' };
+/** Every control that carries a current value: the candidates of a display-value query. */
+const VALUED_SELECTOR = 'input, textarea, select';
+/**
+ * The one table of query kinds: each declares its Playwright getter or its
+ * CSS candidate set. An exact label query is the one kind whose candidates
+ * depend on the pattern: exact goes to the `e2e-label` engine, substring
+ * stays with Playwright's `getByLabel`.
+ */
+function candidatesOf(query, testIdAttribute) {
+    switch (query.kind) {
+        case 'role': {
+            if (query.value.kind !== 'string') {
+                throw new EngineError('ENGINE_FAILURE', 'role query value must be a string', {
+                    retryable: false,
+                });
+            }
+            const options = {};
+            if (query.name !== undefined) {
+                options.name = patternToPw(query.name);
+                if (query.name.kind === 'string')
+                    options.exact = query.name.exact;
+            }
+            const states = query.states ?? {};
+            if (states.checked !== undefined)
+                options.checked = states.checked;
+            if (states.disabled !== undefined)
+                options.disabled = states.disabled;
+            if (states.selected !== undefined)
+                options.selected = states.selected;
+            if (states.expanded !== undefined)
+                options.expanded = states.expanded;
+            if (states.pressed !== undefined)
+                options.pressed = states.pressed;
+            if (query.level !== undefined)
+                options.level = query.level;
+            const role = ARIA_ROLE_BY_CONTRACT_ROLE[query.value.value] ?? query.value.value;
+            return { kind: 'playwright', locate: (roots) => roots.getByRole(role, options) };
+        }
+        case 'label':
+            return query.value.kind === 'string' && query.value.exact
+                ? {
+                    kind: 'engine',
+                    selector: exactLabelSelector({ value: query.value.value, testIdAttribute, secureFieldSelector: SECURE_FIELD_SELECTOR }),
+                }
+                : { kind: 'playwright', locate: (roots) => roots.getByLabel(patternToPw(query.value), { exact: false }) };
+        case 'placeholder':
+            return { kind: 'playwright', locate: (roots) => roots.getByPlaceholder(patternToPw(query.value), { exact: patternExact(query.value) }) };
+        case 'text':
+            return { kind: 'playwright', locate: (roots) => roots.getByText(patternToPw(query.value), { exact: patternExact(query.value) }) };
+        case 'displayValue':
+            return { kind: 'css', selector: VALUED_SELECTOR };
+        case 'testId':
+            return { kind: 'playwright', locate: (roots) => roots.locator(testIdSelector(testIdAttribute, query.value)) };
+    }
+}
+/** Composes the candidates of one query onto `scope` and the closed shadow roots under it. */
+function queryToPw(scope, query, testIdAttribute) {
+    const candidates = candidatesOf(query, testIdAttribute);
+    switch (candidates.kind) {
+        case 'css':
+            return scope.locator(`${SEARCH_ROOTS_SELECTOR_ENGINE}=${candidates.selector}`);
+        case 'engine':
+            return scope.locator(candidates.selector);
+        case 'playwright':
+            return candidates.locate(scope.locator(`${SEARCH_ROOTS_SELECTOR_ENGINE}=`));
+    }
+}
+/**
+ * Self-selector for the part of the semantic `hidden` state Playwright's own
+ * visibility filter does not read: `aria-hidden` on the element itself.
+ */
+const NOT_ARIA_HIDDEN = ':scope:not([aria-hidden="true"])';
+/**
+ * A `visible` query narrows its candidates inside the selector, before any
+ * enclosing scope, filter, or index runs: Playwright's visibility predicate
+ * (layout box, `display`, `visibility`) plus the `aria-hidden` check the
+ * semantic `hidden` state also makes. An indexed, filtered, or scoping visible
+ * query therefore never selects or retains a node that state calls hidden.
+ * The surface additionally holds a terminal query to the batch-read `hidden`
+ * state, which reads the same box, style, and `details` facts Playwright's
+ * predicate does, so a direct query agrees with `toBeVisible()`.
+ */
+function visibleQueryToPw(scope, query, testIdAttribute) {
+    return narrowedToVisible(queryToPw(scope, query, testIdAttribute), query);
+}
+/** The visibility narrowing above, on a locator already built for `query`; identity unless the query is `visible`. */
+function narrowedToVisible(located, query) {
+    if (query.visible !== true)
+        return located;
+    return located.filter({ visible: true }).locator(NOT_ARIA_HIDDEN);
+}
+function positioned(locator, index) {
+    return index === 'first' ? locator.first() : index === 'last' ? locator.last() : locator.nth(index);
+}
+const DISPLAY_VALUE_COMPOSITION_MESSAGE = 'displayValue queries cannot scope child queries or serve as a has-filter in this engine';
+/**
+ * Projects a complete immutable expression onto a Playwright locator within
+ * one scope. Frame cardinality is validated separately by the surface.
+ *
+ * Every semantic query searches its scope and the closed shadow roots under
+ * it (see `Candidates`), so a scope, a `has` filter, and an index reach
+ * across a closed boundary. Two compositions stay Playwright's own and stop
+ * at one: a `selector` expression is the platform's CSS or XPath, and
+ * `filter({ hasText })` reads an element's text as Playwright does, light DOM
+ * and open roots, so text inside a closed root does not count toward an
+ * element outside it.
+ *
+ * A display-value query resolves to a candidate locator plus a value predicate
+ * the surface applies once the candidates are read. Per-element filters
+ * (`filter({ hasText, has })`) commute with that predicate, so they compose
+ * onto the candidate locator as for any other query. Positional selection does
+ * not commute (positions are relative to the value-filtered matches), so it is
+ * recorded as a step and applied after filtering; a filter that follows a
+ * position is recorded the same way and checked on the selected element. Two
+ * compositions need the predicate inside Playwright's own chain and stay
+ * unsupported: a display-value query as the scope of a child query, and as a
+ * `has` filter.
+ */
+function project(scope, expression, testIdAttribute) {
+    switch (expression.kind) {
+        case 'query': {
+            const inner = expression.scope === undefined
+                ? scope
+                : requireComposable(project(scope, expression.scope, testIdAttribute));
+            const { query } = expression;
+            const exactLabel = query.kind === 'label' && query.value.kind === 'string' && query.value.exact ? query.value : null;
+            const locator = visibleQueryToPw(inner, query, testIdAttribute);
+            return {
+                locator,
+                displayValue: query.kind === 'displayValue' ? query.value : null,
+                name: exactLabel,
+                composable: exactLabel === null ? null : locator,
+                steps: [],
+                visible: query.visible === true,
+            };
+        }
+        case 'filter': {
+            const source = project(scope, expression.source, testIdAttribute);
+            const options = {};
+            if (expression.hasText !== undefined)
+                options.hasText = patternToPw(expression.hasText);
+            if (expression.has !== undefined) {
+                options.has = requireComposable(project(scope, expression.has, testIdAttribute));
+            }
+            if (source.steps.length > 0) {
+                return { ...source, steps: [...source.steps, { kind: 'filter', options }] };
+            }
+            return {
+                ...source,
+                locator: source.locator.filter(options),
+                composable: source.composable === null ? null : source.composable.filter(options),
+                steps: [],
+            };
+        }
+        case 'index': {
+            const source = project(scope, expression.source, testIdAttribute);
+            if (source.displayValue !== null || source.name !== null) {
+                return {
+                    ...source,
+                    composable: source.composable === null ? null : positioned(source.composable, expression.index),
+                    steps: [...source.steps, { kind: 'index', index: expression.index }],
+                };
+            }
+            return {
+                locator: positioned(source.locator, expression.index),
+                displayValue: null,
+                name: null,
+                composable: null,
+                steps: [],
+                visible: false,
+            };
+        }
+        case 'selector':
+            return {
+                locator: scope.locator(expression.selector),
+                displayValue: null,
+                name: null,
+                composable: null,
+                steps: [],
+                visible: false,
+            };
+        case 'frame':
+            return project(scope.frameLocator(expression.selector), expression.source, testIdAttribute);
+    }
+}
+/** Projects an expression onto the page; `testIdAttribute` is what a `testId` query reads. */
+export function projectExpression(page, expression, testIdAttribute) {
+    return project(page, expression, testIdAttribute);
+}
+/**
+ * Returns the locator of a projection that must participate in Playwright's
+ * own locator chain: a scope for child queries or a `has` target. A
+ * display-value projection cannot, because its value predicate lives outside
+ * that chain.
+ */
+function requireComposable(projected) {
+    if (projected.composable !== null)
+        return projected.composable;
+    if (projected.displayValue !== null) {
+        throw new EngineError('UNSUPPORTED_CAPABILITY', DISPLAY_VALUE_COMPOSITION_MESSAGE, {
+            retryable: false,
+        });
+    }
+    return projected.locator;
+}
+/**
+ * Applies post steps, innermost first, to an ordered list of matches. `nth`
+ * past the end selects nothing, matching Playwright's `nth` on a locator with
+ * too few matches. A filter step keeps the matches `passesFilter` accepts;
+ * it runs only on the matches that survived the steps before it.
+ */
+export async function applyPostSteps(matches, steps, passesFilter) {
+    let selected = matches;
+    for (const step of steps) {
+        if (step.kind === 'index') {
+            const { index } = step;
+            if (index === 'first')
+                selected = selected.slice(0, 1);
+            else if (index === 'last')
+                selected = selected.slice(-1);
+            else
+                selected = index < selected.length ? [selected[index]] : [];
+            continue;
+        }
+        const kept = [];
+        for (const match of selected) {
+            if (await passesFilter(match, step.options))
+                kept.push(match);
+        }
+        selected = kept;
+    }
+    return selected;
+}
+/** Returns every frame selector along an expression, outermost first. */
+export function frameSelectors(expression) {
+    switch (expression.kind) {
+        case 'query':
+            return expression.scope === undefined ? [] : frameSelectors(expression.scope);
+        case 'filter':
+        case 'index':
+            return frameSelectors(expression.source);
+        case 'selector':
+            return [];
+        case 'frame':
+            return [expression.selector, ...frameSelectors(expression.source)];
+    }
+}
+//# sourceMappingURL=locators.js.map

package/dist/locators.js.map

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

package/dist/observation-capture.d.ts

@@ -0,0 +1,12 @@
+/** One observation transaction: settling, semantic capture, masked pixels, and staged refs. */
+import type { Page } from 'playwright';
+import { type EngineObserveOptions, type OperationContext } from 'e2e/engine';
+import { RefRegistry, type CapturedObservation } from './refs.ts';
+interface CaptureSettings {
+    readonly testIdAttribute: string;
+    readonly site: string | undefined;
+}
+/** Captures under one deadline, retaining no refs from a failed or abandoned document. */
+export declare function captureObservation(page: Page, refs: RefRegistry, settings: CaptureSettings, operation: OperationContext, options: EngineObserveOptions | undefined): Promise<CapturedObservation>;
+export {};
+//# sourceMappingURL=observation-capture.d.ts.map

package/dist/observation-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-capture.d.ts","sourceRoot":"","sources":["../src/observation-capture.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAe,KAAK,oBAAoB,EAAuB,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIhH,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAUlE,UAAU,eAAe;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,0FAA0F;AAC1F,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,OAAO,CAAC,mBAAmB,CAAC,CAqE9B"}

package/dist/observation-capture.js

@@ -0,0 +1,93 @@
+/** One observation transaction: settling, semantic capture, masked pixels, and staged refs. */
+import { EngineError } from 'e2e/engine';
+import { CaptureScope } from './capture-scope.js';
+import { captureDocument, ROOT_NODE_ID } from './observation.js';
+import { capturePixels } from './observe.js';
+import { RefRegistry } from './refs.js';
+import { cancelled, currentViewport } from './support.js';
+/** Shared node budget across the main document and its frames. */
+const MAX_OBSERVED_NODES = 3_000;
+/** Settling is best-effort and spends from the observation's total budget. */
+const SETTLE_TIMEOUT_MS = 5_000;
+/** Leave time for a fresh masked screenshot after semantic capture expires. */
+const PIXEL_FALLBACK_RESERVE_MS = 2_000;
+/** Captures under one deadline, retaining no refs from a failed or abandoned document. */
+export async function captureObservation(page, refs, settings, operation, options) {
+    const deadline = Date.now() + operation.timeoutMs;
+    let accepting = true;
+    const generation = new Map();
+    try {
+        const settleDeadline = Math.min(deadline, Date.now() + SETTLE_TIMEOUT_MS);
+        await new CaptureScope(settleDeadline, operation.signal).run(() => page.waitForLoadState('domcontentloaded', {
+            timeout: Math.max(1, settleDeadline - Date.now()),
+        })).catch(() => undefined);
+        if (operation.signal.aborted)
+            throw cancelled('observe cancelled');
+        const viewport = await currentViewport(page);
+        const semanticDeadline = options?.pixelFallback === true
+            ? deadline - Math.min(PIXEL_FALLBACK_RESERVE_MS, (deadline - Date.now()) / 4)
+            : deadline;
+        // The initial image is independent of the reader. A fallback always takes a fresh one.
+        const pixelCapture = options?.pixels === true
+            ? capturePixels(page, { ...operation, timeoutMs: semanticDeadline - Date.now() }, viewport).catch(() => undefined)
+            : Promise.resolve(undefined);
+        let snapshot;
+        try {
+            const [captured, pixels] = await Promise.all([
+                captureDocument({
+                    ...settings,
+                    reserveIds: (count) => refs.reserveIds(count),
+                    commit: (id, element) => {
+                        if (accepting && !operation.signal.aborted)
+                            generation.set(id, { kind: 'element', element });
+                        else
+                            void element.dispose().catch(() => undefined);
+                    },
+                }, page, {
+                    framePath: [], budget: MAX_OBSERVED_NODES,
+                    deadline: semanticDeadline, signal: operation.signal,
+                }),
+                pixelCapture,
+            ]);
+            snapshot = {
+                location: page.url(),
+                root: captured.tree,
+                viewport: { width: viewport.width, height: viewport.height },
+                ...(captured.truncated ? { truncated: true } : {}),
+                ...(pixels === undefined ? {} : { pixels: pixels.pixels, maskedRegionCount: pixels.maskedRegionCount }),
+            };
+        }
+        catch (cause) {
+            RefRegistry.dispose(generation);
+            generation.clear();
+            if (options?.pixelFallback !== true || !(cause instanceof EngineError) || cause.code !== 'OPERATION_TIMEOUT')
+                throw cause;
+            await pixelCapture;
+            const fallbackViewport = await currentViewport(page);
+            const pixels = await capturePixels(page, {
+                ...operation, timeoutMs: deadline - Date.now(),
+            }, fallbackViewport);
+            if (!pixels.maskingProven)
+                throw cause;
+            snapshot = {
+                location: page.url(),
+                root: { ref: { id: ROOT_NODE_ID, revision: '' } },
+                viewport: { width: fallbackViewport.width, height: fallbackViewport.height },
+                truncated: true,
+                treeUnavailable: true,
+                pixels: pixels.pixels,
+                maskedRegionCount: pixels.maskedRegionCount,
+            };
+        }
+        return { snapshot, generation };
+    }
+    catch (cause) {
+        RefRegistry.dispose(generation);
+        generation.clear();
+        throw cause;
+    }
+    finally {
+        accepting = false;
+    }
+}
+//# sourceMappingURL=observation-capture.js.map

package/dist/observation-capture.js.map

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

package/dist/observation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Semantic tree capture for one observation: the in-page walk, nested-document
+ * stitching, and element-handle bookkeeping the surface keeps per generation.
+ */
+import type { ElementHandle, Frame } from 'playwright';
+import { type NodeRef, type SemanticNode } from 'e2e/engine';
+import { type RawNodeData } from './read-node.ts';
+/**
+ * The id of every observation's root: the main document's element under one
+ * id the engine mints, stable across observations and navigations, so the
+ * harness can address the viewport (`perform(root, swipe)`) from an earlier
+ * observation. Outside the `n<number>` space stamped ids and located ids share.
+ */
+export declare const ROOT_NODE_ID = "root";
+/** A page or frame: anything one document's reader can be evaluated on. */
+export type DocumentHost = Pick<Frame, 'evaluateHandle'>;
+/** What one capture needs from the surface that owns the generation. */
+export interface CaptureDeps {
+    readonly testIdAttribute: string;
+    /** The app's site; a child frame off it stays a boundary node. Undefined admits no child frame. */
+    readonly site: string | undefined;
+    /** Reserves a disjoint range before the reader can stamp any element, including on timeout. */
+    reserveIds(count: number): number;
+    /** Publishes one element handle under its id in the generation being built. */
+    commit(id: string, element: ElementHandle<Element>): void;
+}
+export interface CaptureOptions {
+    /** Enclosing frame selectors, outermost first; empty for the main document. */
+    readonly framePath: readonly string[];
+    /** Remaining node budget shared across every document of the observation. */
+    readonly budget: number;
+    /**
+     * Absolute time (epoch ms) by which the whole observation must be done.
+     * Every document's budget is derived from what remains of it, so the
+     * documents of one observation can never sum past the operation's budget.
+     */
+    readonly deadline: number;
+    readonly signal: AbortSignal;
+}
+/** One document's tree with what the capture knows about its completeness. */
+export interface CapturedDocument {
+    readonly tree: SemanticNode;
+    /** Nodes captured across this document and every child document stitched in. */
+    readonly nodeCount: number;
+    /**
+     * True when nodes on screen are missing from `tree`: the node budget cut
+     * the walk short in this document or a child, or an on-site child frame's
+     * document was not read (no budget or time left, past the depth limit, or
+     * its capture failed). Off-site frames are left out by design and never
+     * count.
+     */
+    readonly truncated: boolean;
+}
+/**
+ * Captures one document's semantic tree, then descends into each observed
+ * iframe boundary node via its content frame and stitches the child
+ * document under it. Frame capture is best-effort: a detached or unloaded
+ * frame leaves its boundary node childless rather than failing the
+ * observation. The node budget is shared across all documents.
+ */
+export declare function captureDocument(deps: CaptureDeps, host: DocumentHost, options: CaptureOptions): Promise<CapturedDocument>;
+export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
+//# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAY,MAAM,YAAY,CAAC;AACjE,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,gBAAgB,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAcnC,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;AAEzD,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+FAA+F;IAC/F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAKD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAmND,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,GAAE,SAAS,YAAY,EAAO,EACtC,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,YAAY,CA0Bd"}