@xeonr/telemetry-web 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @xeonr/telemetry-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser telemetry for Xeonr consoles, sent to Lantern's client ingest
+(`telemetry.xeonr.io`). It replaces Sentry: uncaught errors, failed and
+timed-out requests, web vitals and one span per RPC, as OTLP/HTTP JSON, with
+an offline buffer so a console that cannot reach us still reports once it
+can. No runtime dependencies; the browser entry is ~9 KiB min+gzip.
+
+Every console that mounts `@xeonr/console-shell` ≥ 0.7 already has it — the
+shell's `ConsoleProvider` starts it. Use this package directly on a page
+without the shell, or for the extra pieces below (your own Connect clients,
+the Vite plugin).
+
+Design: fleet observability plan §10.2; wire contract:
+`lantern/docs/WAVE4-client-ingest.md` §7 (both in platform-docs).
+
+## Install
+
+```bash
+pnpm add @xeonr/telemetry-web
+```
+
+## Start it
+
+```ts
+import { init } from "@xeonr/telemetry-web";
+
+init({
+  service: "functions-ui",   // the Lantern client project; default <meta name="lantern-service">
+  product: "functions",      // service.namespace
+  // release:     default <meta name="lantern-release">, else "dev"
+  // endpoint:    default https://telemetry.xeonr.io
+  // sampleRate:  0..1 for RPC spans and web vitals; errors and reachability always go
+  // enabled:     default on, except on localhost/*.localhost/*.test and under
+  //              <meta name="lantern-telemetry" content="off">
+});
+```
+
+Once per page: a second `init` returns the first client. Nothing the SDK does
+ever throws into the page, and it never reports its own sends.
+
+Authentication is the public-origin model: every request goes to
+`<endpoint>/v1/logs?service=<service>` (or `/v1/traces`), `credentials: "omit"`,
+as `text/plain` so no request needs a preflight. The ingest accepts it only
+from an origin on the project's allow-list.
+
+## What it sends
+
+| Record | When | Key attributes |
+|---|---|---|
+| `exception` (ERROR) | `window` error, unhandled rejection, the React boundary, `captureException`, a kit error toast | `exception.type/message/stacktrace` (raw stack — Lantern symbolicates), `exception.mechanism`, `code.filepath/lineno/column`, `url.path`, `http.response.header.x-trace-id`, `app.breadcrumbs` |
+| `client.request.failed` (WARN) | a request through `wrapFetch` or the interceptor that got no answer, timed out, or failed server-side | `server.address`, `rpc.method`, `error.type` = `timeout\|http_5xx\|cors\|network\|aborted`, `client.online`, `client.since_last_success_ms` |
+| `web_vital` (INFO, sampled) | LCP, INP, CLS (on hide), FCP, TTFB | `web_vital.name/value/rating` |
+| `page_view`, `route_change` (INFO) | load; `trackRoute(path)` | `url.path`, `document_load.*` |
+| CLIENT span (sampled) | every RPC / wrapped fetch | named by the procedure; `rpc.method`, `server.address`, `rpc.response.status_code` |
+
+Every record carries `session.id` (per tab session); the resource carries
+`service.instance.id` (per browser install), `telemetry.sdk.*` and `browser.*`.
+Breadcrumbs are the last 20 route changes and request outcomes — procedure and
+code, never a payload. Messages lose URL query strings, email addresses and
+bearer-looking secrets before they leave; stack frames are sent untouched.
+
+A browser cannot tell DNS from TLS from a refused connection: `fetch` rejects
+with the same `TypeError` for all of them. Offline is `network`; a same-origin
+failure is `network`; a cross-origin one is `cors` if a `no-cors` probe of the
+same URL gets an answer, else `network`. `dns` and `tls` are never sent from a
+browser.
+
+Delivery: batches every 5 s or at 50 records. A send that gets no answer, a
+408, a 429 or a 5xx moves its records to `localStorage` (at most 200 records /
+256 KiB, oldest non-errors dropped first) and waits for `Retry-After` or a
+backoff; the next page load replays them. On `pagehide` / hidden, whatever is
+left goes by `navigator.sendBeacon`.
+
+## Errors
+
+```ts
+import { captureException, traceIdFrom } from "@xeonr/telemetry-web";
+
+try { await save(); } catch (err) {
+  captureException(err, { extra: { "app.form": "schedule" } });   // route and X-Trace-Id are filled in
+  showError(err, traceIdFrom(err));   // "trace 1a2b3c4d… [copy]"
+}
+```
+
+`traceIdFrom(errOrResponse)` reads `X-Trace-Id` from a ConnectError's
+metadata, a fetch `Response`'s headers, or a `traceId` (and from their
+`cause`). The kit's `TraceRef` renders it.
+
+### React
+
+```tsx
+import { TelemetryErrorBoundary } from "@xeonr/telemetry-web/react";
+
+<TelemetryErrorBoundary resetKeys={[pathname]} fallback={({ error, traceId, reset }) => <Oops traceId={traceId} onRetry={reset} />}>
+  <App />
+</TelemetryErrorBoundary>
+```
+
+## Requests
+
+```ts
+// ConnectRPC: first in the list, so it times what the others do.
+import { telemetryInterceptor } from "@xeonr/telemetry-web/connect";
+createConnectTransport({ baseUrl, interceptors: [telemetryInterceptor(), ...yours] });
+
+// fetch
+import { wrapFetch } from "@xeonr/telemetry-web";
+const api = wrapFetch();            // wraps the global fetch; or wrapFetch(myFetch)
+```
+
+A same-origin call carries a W3C `traceparent`, so the browser span parents the
+server's trace at the edge. A cross-origin API gets none unless you say so —
+its CORS policy has to allow the header first:
+
+```ts
+init({ service: "x-ui", getTraceHeaders: (url, { traceparent }) => url.hostname === "api.x.xeonr.io" ? { traceparent } : undefined });
+```
+
+## Releases and source maps (Vite)
+
+```ts
+// vite.config.ts
+import { lanternTelemetry } from "@xeonr/telemetry-web/vite";
+
+export default defineConfig({
+  plugins: [react(), lanternTelemetry({ service: "functions-ui" })],
+});
+```
+
+The plugin:
+
+1. writes `<meta name="lantern-service">` and `<meta name="lantern-release">`
+   into `index.html` — the release is `VERSION`, else `VITE_APP_VERSION`, else
+   `dev` — so the SDK needs no configuration for either;
+2. forces `build.sourcemap = "hidden"` (maps are written, no bundle links them);
+3. after the build, with `CI_JOB_TOKEN` (or `LANTERN_RELEASE_KEY`) set,
+   registers the release (`POST /v1/releases`) and uploads every
+   `dist/**/*.map` (gzipped) to `/v1/sourcemaps?service=&release=&path=` keyed
+   by the `.js` it belongs to. `LANTERN_INGEST_URL` moves the endpoint. A
+   failed upload warns; it never fails the build;
+4. deletes the `.map` files from `dist`, so they are never served.
+
+The k8s pipeline already passes `CI_JOB_TOKEN` and `VERSION` to every image
+build; declare them in the builder stage, before `vite build`:
+
+```dockerfile
+FROM node:24-slim AS builder
+WORKDIR /src
+RUN corepack enable
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+ARG CI_JOB_TOKEN
+ARG VERSION
+RUN pnpm run build          # vite build: meta tags, hidden maps, upload, maps deleted
+
+FROM nginx:alpine
+COPY --from=builder /src/dist /usr/share/nginx/html
+```
+
+The `ARG`s sit after the install so a new version or token does not bust the
+dependency layer, and they never reach the final stage.
+
+## Testing against it
+
+`createClient(options, env)` builds a client against an injected environment
+(fetch, storage, timers, events) instead of the page's, without touching the
+page-wide singleton.

package/dist/classify.d.ts

@@ -0,0 +1,48 @@
+export type ErrorClass = "dns" | "tls" | "timeout" | "http_5xx" | "cors" | "network" | "aborted";
+/** Connect's numeric codes, so this package carries no runtime import of @connectrpc/connect. */
+export declare const CODE: {
+    readonly Canceled: 1;
+    readonly Unknown: 2;
+    readonly DeadlineExceeded: 4;
+    readonly ResourceExhausted: 8;
+    readonly Internal: 13;
+    readonly Unavailable: 14;
+    readonly DataLoss: 15;
+};
+/** Connect's code as its wire name ("permission_denied"); "unknown" for anything out of range. */
+export declare function codeName(code: number): string;
+export interface ConnectErrorLike {
+    name: string;
+    code: number;
+    message: string;
+    rawMessage?: string;
+    metadata?: {
+        get(k: string): string | null;
+    };
+    cause?: unknown;
+}
+export declare function isConnectError(e: unknown): e is ConnectErrorLike;
+/** fetch's "could not get an answer at all": a TypeError (or, in old Safari, a bare "Load failed"). */
+export declare function isNetworkTypeError(e: unknown): boolean;
+export interface ClassifyInput {
+    /** What fetch rejected with, or what the Connect call threw. */
+    error?: unknown;
+    /** The HTTP status, when there was an answer. */
+    status?: number | undefined;
+    online: boolean;
+    sameOrigin: boolean;
+}
+/**
+ * The class of a failure, or "maybe-cors" when only a probe can decide,
+ * or null when this was not a reachability failure at all (a 4xx, a
+ * Connect PermissionDenied — the server answered, and answered no).
+ */
+export declare function classify(i: ClassifyInput): ErrorClass | "maybe-cors" | null;
+/**
+ * Settles "maybe-cors": a `no-cors` request to the same URL resolves (with an
+ * opaque response) when the server answered, and rejects when nothing did.
+ * Uses the SDK's own unwrapped fetch, so it is never itself reported. Bounded
+ * by a short timeout; an undecidable probe says "network".
+ */
+export declare function probeCors(fetchImpl: typeof fetch | undefined, url: string, timeoutMs?: number): Promise<ErrorClass>;
+//# sourceMappingURL=classify.d.ts.map

package/dist/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjG,iGAAiG;AACjG,eAAO,MAAM,IAAI;;;;;;;;CAQP,CAAC;AAQX,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CAOhE;AAMD,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,IAAI,CA+B3E;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,OAAO,KAAK,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAcvH"}

package/dist/classify.js

@@ -0,0 +1,117 @@
+// Why a request failed, from what a browser is willing to say — which is not
+// much. fetch rejects with the same opaque TypeError for a DNS failure, a TLS
+// failure, a refused connection and a CORS refusal, by design. What can be
+// told apart:
+//
+//   offline (navigator.onLine false)          → network
+//   AbortSignal.timeout / Connect deadline    → timeout
+//   an abort the caller asked for             → aborted
+//   an answer with status ≥ 500               → http_5xx
+//   an opaque TypeError, same-origin          → network (CORS cannot apply)
+//   an opaque TypeError, cross-origin         → cors if a no-cors probe of the
+//                                               same URL gets an answer (the
+//                                               server is up, the browser hid
+//                                               it), otherwise network
+//
+// `dns` and `tls` are in the vocabulary for clients that can tell (device
+// apps); a browser never can, so this module never returns them.
+/** Connect's numeric codes, so this package carries no runtime import of @connectrpc/connect. */
+export const CODE = {
+    Canceled: 1,
+    Unknown: 2,
+    DeadlineExceeded: 4,
+    ResourceExhausted: 8,
+    Internal: 13,
+    Unavailable: 14,
+    DataLoss: 15,
+};
+const CODE_NAMES = [
+    "ok", "canceled", "unknown", "invalid_argument", "deadline_exceeded", "not_found", "already_exists",
+    "permission_denied", "resource_exhausted", "failed_precondition", "aborted", "out_of_range",
+    "unimplemented", "internal", "unavailable", "data_loss", "unauthenticated",
+];
+/** Connect's code as its wire name ("permission_denied"); "unknown" for anything out of range. */
+export function codeName(code) {
+    return CODE_NAMES[code] ?? "unknown";
+}
+export function isConnectError(e) {
+    return (typeof e === "object" &&
+        e !== null &&
+        e.name === "ConnectError" &&
+        typeof e.code === "number");
+}
+function errName(e) {
+    return typeof e === "object" && e !== null && typeof e.name === "string" ? e.name : undefined;
+}
+/** fetch's "could not get an answer at all": a TypeError (or, in old Safari, a bare "Load failed"). */
+export function isNetworkTypeError(e) {
+    return errName(e) === "TypeError" || (e instanceof Error && /load failed|failed to fetch|networkerror/i.test(e.message));
+}
+/**
+ * The class of a failure, or "maybe-cors" when only a probe can decide,
+ * or null when this was not a reachability failure at all (a 4xx, a
+ * Connect PermissionDenied — the server answered, and answered no).
+ */
+export function classify(i) {
+    if (i.status !== undefined && i.status >= 500)
+        return "http_5xx";
+    const e = i.error;
+    if (e === undefined || e === null)
+        return null;
+    const name = errName(e);
+    if (name === "TimeoutError")
+        return "timeout";
+    if (name === "AbortError")
+        return "aborted";
+    if (isConnectError(e)) {
+        switch (e.code) {
+            case CODE.DeadlineExceeded:
+                return "timeout";
+            case CODE.Canceled:
+                // connect-web maps AbortSignal.timeout() to Canceled as well; the cause says which.
+                return /timed out|timeout/i.test(e.message) ? "timeout" : "aborted";
+            case CODE.Unknown:
+                // A fetch that never got an answer arrives as Unknown with the TypeError as its cause.
+                if (isNetworkTypeError(e.cause))
+                    return !i.online ? "network" : i.sameOrigin ? "network" : "maybe-cors";
+                return "http_5xx";
+            case CODE.Internal:
+            case CODE.Unavailable:
+            case CODE.DataLoss:
+                return "http_5xx";
+            default:
+                return null;
+        }
+    }
+    if (isNetworkTypeError(e)) {
+        if (!i.online)
+            return "network";
+        return i.sameOrigin ? "network" : "maybe-cors";
+    }
+    return null;
+}
+/**
+ * Settles "maybe-cors": a `no-cors` request to the same URL resolves (with an
+ * opaque response) when the server answered, and rejects when nothing did.
+ * Uses the SDK's own unwrapped fetch, so it is never itself reported. Bounded
+ * by a short timeout; an undecidable probe says "network".
+ */
+export async function probeCors(fetchImpl, url, timeoutMs = 3000) {
+    if (!fetchImpl)
+        return "network";
+    try {
+        const ctrl = typeof AbortController === "function" ? new AbortController() : undefined;
+        const t = setTimeout(() => ctrl?.abort(), timeoutMs);
+        try {
+            await fetchImpl(url, { method: "HEAD", mode: "no-cors", credentials: "omit", cache: "no-store", ...(ctrl ? { signal: ctrl.signal } : {}) });
+            return "cors";
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    catch {
+        return "network";
+    }
+}
+//# sourceMappingURL=classify.js.map

package/dist/classify.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,135 @@
+import { type Env } from "./env.ts";
+import { type Attrs, type SeverityName } from "./otlp.ts";
+export declare const SDK_NAME = "@xeonr/telemetry-web";
+export declare const SDK_VERSION = "0.1.0";
+export declare const DEFAULT_ENDPOINT = "https://telemetry.xeonr.io";
+/** The record attribute carrying breadcrumbs (a JSON string). */
+export declare const BREADCRUMBS_KEY = "app.breadcrumbs";
+export interface TelemetryOptions {
+    /**
+     * The client project's service name in Lantern, `<product>-ui`. Default:
+     * `<meta name="lantern-service">` (the Vite plugin writes it). With neither,
+     * the client is disabled: there is nowhere to send to.
+     */
+    service?: string | undefined;
+    /** The ingest. Default `https://telemetry.xeonr.io`. */
+    endpoint?: string | undefined;
+    /** service.version. Default `<meta name="lantern-release">`, else "dev". */
+    release?: string | undefined;
+    /** deployment.environment. The ingest stamps the project's own; this is a hint. */
+    environment?: string | undefined;
+    /** The console's product key (`service.namespace`). */
+    product?: string | undefined;
+    /**
+     * The propagation headers for an outgoing request, or undefined for none.
+     * Default: `{ traceparent }` for a same-origin request only — a
+     * cross-origin API has to allow the header in its CORS policy first, and a
+     * request it refuses is worse than an unparented trace.
+     */
+    getTraceHeaders?: ((url: URL, ctx: {
+        traceparent: string;
+        sameOrigin: boolean;
+    }) => Record<string, string> | undefined) | undefined;
+    /** Share of RPC spans, page loads' web vitals that are sent, 0..1. Errors and reachability are always sent. Default 1. */
+    sampleRate?: number | undefined;
+    /**
+     * Default: on, except on a local development host (localhost, 127.0.0.1,
+     * [::1], *.localhost, *.test) and on a page with
+     * `<meta name="lantern-telemetry" content="off">`. An explicit value wins.
+     */
+    enabled?: boolean | undefined;
+    /** Window error/unhandledrejection handlers. Default true. */
+    captureGlobalErrors?: boolean | undefined;
+    /** Web vitals and the page_view record. Default true. */
+    capturePerformance?: boolean | undefined;
+    /** Advanced: flush cadence and buffer bounds. */
+    flushIntervalMs?: number | undefined;
+    maxBatch?: number | undefined;
+    maxStored?: number | undefined;
+    maxStoredBytes?: number | undefined;
+}
+export interface CaptureContext {
+    /** The route (url.path) — default the last trackRoute, else location.pathname. Query strings are stripped. */
+    route?: string | undefined;
+    /** The X-Trace-Id of the failed call, when there was one. Default: read from the error itself. */
+    traceId?: string | undefined;
+    /** More record attributes. Keys the ingest has not declared are dropped there. */
+    extra?: Attrs | undefined;
+    /** How it was caught: onerror, unhandledrejection, react, toast, manual (default). */
+    mechanism?: string | undefined;
+    /** Default ERROR. A handled, expected refusal (a toast for a 4xx) can go as WARN. */
+    severity?: Extract<SeverityName, "ERROR" | "WARN"> | undefined;
+    /** React's component stack, from an error boundary. */
+    componentStack?: string | undefined;
+}
+export type Breadcrumb = {
+    type: "route";
+    path: string;
+} | {
+    type: "rpc";
+    procedure: string;
+    code: string;
+} | {
+    type: "fetch";
+    method: string;
+    host: string;
+    status: string;
+};
+export interface RequestStart {
+    /** The full request URL. */
+    url: string;
+    /** Connect procedure (`pkg.Service/Method`), for an RPC. */
+    procedure?: string | undefined;
+    /** HTTP method. Default POST for an RPC, GET otherwise. */
+    method?: string | undefined;
+}
+export interface RequestEnd {
+    /** HTTP status, when there was an answer (fetch). */
+    status?: number | undefined;
+    /** What the call threw. */
+    error?: unknown;
+    /** The response's X-Trace-Id, when there was one. */
+    traceId?: string | null | undefined;
+}
+export interface RequestHandle {
+    /** Headers to add to the request (traceparent, when propagating). */
+    readonly headers: Record<string, string>;
+    end(r: RequestEnd): void;
+}
+export interface TelemetryClient {
+    readonly enabled: boolean;
+    readonly service: string;
+    readonly release: string;
+    readonly endpoint: string;
+    /** service.instance.id: one per browser install (localStorage). */
+    readonly instanceId: string;
+    /** session.id: one per tab session (sessionStorage). */
+    readonly sessionId: string;
+    captureException(err: unknown, ctx?: CaptureContext): void;
+    /** A route change: a breadcrumb, a route_change record, and the url.path of later records. */
+    trackRoute(path: string): void;
+    /** A record of your own: `event.name` = name. */
+    event(name: string, attrs?: Attrs, opts?: {
+        severity?: SeverityName | undefined;
+        body?: string | undefined;
+    }): void;
+    breadcrumb(b: Breadcrumb): void;
+    /** Attributes added to every later record (`xeonr.subject`, say). undefined removes one. */
+    setAttributes(attrs: Attrs): void;
+    /** Instrument one request: the fetch wrapper and the Connect interceptor are built on this. */
+    beginRequest(r: RequestStart): RequestHandle;
+    /** Whether a URL is the ingest's own (never instrumented: no recursion). */
+    isOwnUrl(url: string): boolean;
+    flush(): Promise<void>;
+    shutdown(): void;
+}
+/** A client that does nothing, for a disabled or unconfigured page. Same shape, so callers never null-check. */
+export declare function noopClient(service?: string, release?: string, endpoint?: string): TelemetryClient;
+/** Whether this page is a local development server, where telemetry is off by default. */
+export declare function isLocalDevHost(hostname: string | undefined): boolean;
+/**
+ * Build a client against an explicit environment. `init` is this over the
+ * real browser, plus the page-wide singleton; tests call it directly.
+ */
+export declare function createClient(opts?: TelemetryOptions, env?: Env): TelemetryClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgD,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,EAAuE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAO/H,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAC/C,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAE7D,iEAAiE;AACjE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IACpI,0HAA0H;IAC1H,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,kGAAkG;IAClG,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kFAAkF;IAClF,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAC/D,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC3D,8FAA8F;IAC9F,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iDAAiD;IACjD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,IAAI,CAAC;IACpH,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4FAA4F;IAC5F,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAClC,+FAA+F;IAC/F,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC;IAC7C,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAID,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,OAAO,SAAK,EAAE,OAAO,SAAQ,EAAE,QAAQ,SAAmB,GAAG,eAAe,CAkBtG;AAID,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEpE;AAgcD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,gBAAqB,EAAE,GAAG,GAAE,GAAkB,GAAG,eAAe,CAoBlG"}