@namzu/sandbox 23.0.1 → 25.0.0

package/dist/local-virtual-computer/setup/contract.d.ts

@@ -0,0 +1,360 @@
+/**
+ * The contract of the Windows Pal computer setup: what a readiness inspection
+ * reports, the plan a person consents to, and how running that plan reports
+ * progress and ends. The provider never installs, updates, loads or starts
+ * anything; everything here is a separate operation an application runs after
+ * the person agrees.
+ */
+import type { LocalComputerCommandRunner } from '../engine.js';
+/**
+ * One state per machine, checked in this order: the first that applies wins.
+ * - `unsupported`: not Windows, not x64, or a Windows build below 19041.
+ * - `blocked-by-policy`: `AllowWSL` or `AllowWSLContainer` is 0 under
+ *   `HKLM\Software\Policies\WSL`.
+ * - `restart-pending`: setup recorded that Windows needs a restart, and the PC
+ *   has not restarted since; or Virtual Machine Platform is on, no hypervisor
+ *   runs yet, and Windows itself reports a restart pending (no marker then).
+ *   A marker that cannot be read, or a boot time that cannot be fetched while
+ *   a marker exists, also reads `restart-pending`: the steps still to run
+ *   after the restart are then unknown and treated as none. So does a marker
+ *   that can be neither read nor dated (no file date): `restart` is then
+ *   absent, since there is no record time to report.
+ * - `platform-off`: Virtual Machine Platform is off, or (Windows 10 only) the
+ *   Windows Subsystem for Linux optional component is.
+ * - `wsl-missing`: no WSL package with wslc.
+ * - `wsl-outdated`: WSL is present, but wslc is missing or below the floor.
+ * - `sdk-mismatch`: the installed WSL refuses this client (`0x8004060B`).
+ * - `virtualization-off`: the session's virtual machine cannot start
+ *   (`0x80370102`), or (without a session probe) no hypervisor runs although
+ *   the platform is on and Windows reports no restart pending.
+ * - `image-missing`: wslc works, but the Pal computer image is not loaded.
+ * - `ready`: wslc works and the image is loaded and matches its manifest.
+ */
+export type WslcReadinessState = 'unsupported' | 'blocked-by-policy' | 'restart-pending' | 'platform-off' | 'wsl-missing' | 'wsl-outdated' | 'sdk-mismatch' | 'virtualization-off' | 'image-missing' | 'ready';
+/** Why a machine is `unsupported`. */
+export type WslcUnsupportedReason = 'platform' | 'architecture' | 'windows-build';
+/** What a readiness inspection found. Plain data; safe to print as JSON. */
+export interface WslcReadiness {
+    readonly state: WslcReadinessState;
+    /** Set only when `state` is `unsupported`. */
+    readonly unsupportedReason?: WslcUnsupportedReason;
+    readonly windows?: {
+        readonly build: number;
+        readonly architecture: 'x64' | 'arm64' | 'other';
+        readonly isWindows11: boolean;
+    };
+    readonly policy: {
+        readonly allowWsl: boolean;
+        readonly allowWslContainer: boolean;
+    };
+    readonly components: {
+        readonly virtualMachinePlatform: boolean | 'unknown';
+        /** Windows 11 does not need the optional component. */
+        readonly wslOptionalComponent: boolean | 'unknown' | 'not-needed';
+        readonly hypervisorPresent: boolean | 'unknown';
+    };
+    readonly wsl: {
+        /** `x.y.z.w` from `wsl.exe --version`, when a WSL package answers. */
+        readonly version?: string;
+        /** The wslc binary found, if any. */
+        readonly wslcBinary?: string;
+        /** `x.y.z` from `wslc version`. */
+        readonly wslcVersion?: string;
+    };
+    readonly image: {
+        /** The reference the inspection looked for, e.g. `namzu-local-computer:2`. */
+        readonly ref: string;
+        readonly loaded: boolean;
+        /** A manifest and archive the application carries, if it has them. */
+        readonly bundled?: {
+            readonly manifestPath: string;
+            readonly archivePath: string;
+        };
+    };
+    /** Set when setup recorded a required restart (see {@link WslcRestartMarker}). */
+    readonly restart?: {
+        readonly recordedAt: string;
+        readonly bootTime?: string;
+    };
+    /** ISO time of the inspection. */
+    readonly checkedAt: string;
+}
+/**
+ * The image manifest `local-computer/build-image.mjs` writes and the Windows
+ * installer carries in `resources/pal-computer/manifest.json`.
+ */
+export interface WslcImageManifest {
+    readonly revision: number;
+    readonly stage: 'base' | 'creative';
+    /** `namzu-local-computer:<revision>`; a test tag is never bundled. */
+    readonly imageRef: string;
+    readonly imageId: string;
+    /** The image's `org.namzu.local-computer.protocol` label. */
+    readonly protocol: string;
+    /** The archive's file name, beside the manifest. */
+    readonly file: string;
+    /** SHA-256 of the archive as shipped. */
+    readonly sha256: string;
+    /** SHA-256 of the uncompressed tar. */
+    readonly tarSha256: string;
+    /** Size of the uncompressed tar. */
+    readonly sizeBytes: number;
+    /** Size of the archive. */
+    readonly compressedBytes: number;
+    readonly format: 'zst' | 'xz' | 'gz' | 'tar';
+}
+/** The WSL release setup installs when WSL is missing or too old. */
+export interface PinnedWslPackage {
+    /** `x.y.z.w`, for example `3.0.1.0`. */
+    readonly version: string;
+    readonly architecture: 'x64';
+    /** An `https://github.com/microsoft/WSL/releases/download/...` URL. */
+    readonly url: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+}
+/**
+ * One step of a plan, in the order it runs.
+ * - `download-wsl`: fetch the pinned WSL package into the setup directory and
+ *   check its size and SHA-256. Not elevated.
+ * - `enable-windows-features`: turn on Virtual Machine Platform (and on
+ *   Windows 10 the WSL optional component). Elevated.
+ * - `install-wsl`: install the downloaded WSL package. Elevated.
+ * - `restart`: the person restarts the PC; setup continues after sign-in.
+ * - `load-image`: check the bundled archive against its manifest and load it
+ *   with `wslc load -i`. Not elevated.
+ *
+ * Every elevated step of one plan runs in ONE elevated process, so a plan
+ * causes at most one Windows permission prompt.
+ */
+export type WslcSetupStepKind = 'download-wsl' | 'enable-windows-features' | 'install-wsl' | 'restart' | 'load-image';
+export interface WslcSetupStep {
+    readonly kind: WslcSetupStepKind;
+    readonly elevated: boolean;
+    /** Bytes this step downloads, if any. */
+    readonly downloadBytes?: number;
+    /** Bytes this step adds on disk, if known. */
+    readonly diskBytes?: number;
+    /** A rough duration for the sentence the person reads. */
+    readonly estimatedSeconds: number;
+    readonly mayRequireRestart: boolean;
+}
+/** Why a plan has nothing Namzu can do. */
+export type WslcSetupBlock = 'unsupported' | 'blocked-by-policy' | 'virtualization-off' | 'sdk-mismatch'
+/** No bundled image and no other way to get one. */
+ | 'image-unavailable';
+export interface WslcSetupPlan {
+    /**
+     * A digest of the readiness state and the steps. Consent names it, and
+     * running refuses a plan whose id no longer matches a fresh inspection.
+     */
+    readonly id: string;
+    readonly state: WslcReadinessState;
+    readonly steps: readonly WslcSetupStep[];
+    /** 0 or 1: all elevated steps share one elevated process. */
+    readonly elevationPrompts: 0 | 1;
+    readonly mayRequireRestart: boolean;
+    /** Set when setup cannot proceed; `steps` is then empty. */
+    readonly blocked?: WslcSetupBlock;
+}
+/** The person's agreement to one specific plan. */
+export interface WslcSetupConsent {
+    readonly planId: string;
+    /** ISO time of the click or the typed answer. */
+    readonly approvedAt: string;
+}
+/** Progress, emitted in order. Byte counts are raw; the caller humanises them. */
+export type WslcSetupProgress = {
+    readonly step: WslcSetupStepKind;
+    readonly phase: 'started';
+} | {
+    readonly step: WslcSetupStepKind;
+    readonly phase: 'progress';
+    readonly done: number;
+    readonly total?: number;
+    readonly unit: 'bytes' | 'percent';
+} | {
+    readonly step: WslcSetupStepKind;
+    readonly phase: 'finished';
+    readonly result: 'ok' | 'restart-required';
+};
+/** Stable reasons a failed setup step carries. */
+export type WslcSetupFailureCode = 'download-failed' | 'download-corrupt' | 'elevation-failed' | 'feature-enable-failed' | 'wsl-install-failed' | 'image-corrupt' | 'image-load-failed' | 'image-mismatch' | 'engine-failed';
+/** How running a plan ended. */
+export type WslcSetupResult = {
+    readonly outcome: 'ready';
+} | {
+    readonly outcome: 'restart-required';
+}
+/** The person declined the Windows permission prompt. */
+ | {
+    readonly outcome: 'cancelled';
+}
+/** The account cannot elevate and no administrator approved. */
+ | {
+    readonly outcome: 'needs-administrator';
+}
+/** The consent names a plan that no longer matches the machine. */
+ | {
+    readonly outcome: 'plan-changed';
+    readonly plan: WslcSetupPlan;
+} | {
+    readonly outcome: 'blocked';
+    readonly blocked: WslcSetupBlock;
+} | {
+    readonly outcome: 'failed';
+    readonly step: WslcSetupStepKind;
+    readonly code: WslcSetupFailureCode;
+    /** Plain words for a Details fold. Never engine output or paths with user names. */
+    readonly detail?: string;
+    /** The Windows exit code of the failed step, when Windows gave one. */
+    readonly exitCode?: number;
+};
+/**
+ * Written to `<stateDirectory>/restart.json` when an elevated step reports
+ * that Windows needs a restart; cleared once readiness sees a boot later than
+ * `recordedAt`.
+ */
+export interface WslcRestartMarker {
+    readonly recordedAt: string;
+    readonly planId: string;
+    /** Steps still to run after the restart. */
+    readonly remaining: readonly WslcSetupStepKind[];
+}
+/** Exit status of the elevated process, before it is mapped to a result. */
+export type WslcElevatedOutcome = {
+    readonly outcome: 'ok';
+} | {
+    readonly outcome: 'restart-required';
+} | {
+    readonly outcome: 'cancelled';
+} | {
+    readonly outcome: 'needs-administrator';
+} | {
+    readonly outcome: 'failed';
+    readonly step: 'enable-windows-features' | 'install-wsl';
+    readonly code: 'feature-enable-failed' | 'wsl-install-failed' | 'elevation-failed';
+    /** The Windows exit code, for a Details fold. */
+    readonly exitCode?: number;
+};
+/**
+ * Everything the setup touches on the machine, injected so tests can stand in
+ * for Windows. Implementations for a real Windows host live beside the
+ * functions that use them.
+ */
+export interface WslcSetupHost {
+    readonly platform: NodeJS.Platform;
+    readonly arch: string;
+    /** Windows build number, e.g. 19045; undefined off Windows. */
+    readonly windowsBuild: number | undefined;
+    readonly env: NodeJS.ProcessEnv;
+    readonly runner: LocalComputerCommandRunner;
+    /** A DWORD from the registry; undefined when the value or key is absent. */
+    readDword(key: string, name: string): Promise<number | undefined>;
+    /** Whether a registry key exists; `unknown` when the check failed or timed out. */
+    keyExists(key: string): Promise<boolean | 'unknown'>;
+    /** The last boot time of Windows. */
+    bootTime(): Promise<Date>;
+    now(): Date;
+    /** `%LOCALAPPDATA%\Namzu\setup` unless the caller chooses otherwise. */
+    readonly stateDirectory: string;
+    /**
+     * The registry key the resume command is written under. Defaults to
+     * {@link RESUME_AT_SIGN_IN_KEY}; a trial run on a real PC points it at a
+     * scratch key so nothing runs at the next sign-in.
+     */
+    readonly resumeRegistryKey: string;
+}
+/** Where Windows keeps the command it runs once at the next sign-in. */
+export declare const RESUME_AT_SIGN_IN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\RunOnce";
+/** Options every setup entry point takes. */
+export interface WslcSetupOptions {
+    /** The image the application runs, e.g. `namzu-local-computer:2`. */
+    readonly imageRef: string;
+    /** The manifest the application carries, with its archive beside it. */
+    readonly bundledManifestPath?: string;
+    /** Defaults to the release pinned in this package. */
+    readonly wslPackage?: PinnedWslPackage;
+    readonly host?: Partial<WslcSetupHost>;
+    readonly signal?: AbortSignal;
+    /**
+     * Start the wslc session to check the loaded image and the virtual machine
+     * itself. Off by default, so opening a panel never starts a virtual machine
+     * of about 2 GB; without it, `image.loaded` comes from the record setup
+     * writes after a successful load (`<stateDirectory>/image.json`).
+     * `runWslcSetup` always probes.
+     */
+    readonly probeSession?: boolean;
+}
+/** Run the one elevated process for the elevated steps of a plan. */
+export type RunElevatedWslcSteps = (request: {
+    readonly steps: readonly ('enable-windows-features' | 'install-wsl')[];
+    /** Required when `install-wsl` is among the steps; re-verified while elevated. */
+    readonly wslPackage?: {
+        readonly path: string;
+        readonly sha256: string;
+    };
+    readonly host: WslcSetupHost;
+    readonly onProgress?: (progress: WslcSetupProgress) => void;
+    readonly signal?: AbortSignal;
+}) => Promise<WslcElevatedOutcome>;
+/** The entry points, as the CLI and Desktop call them. */
+export type InspectWslcReadiness = (options: WslcSetupOptions) => Promise<WslcReadiness>;
+export type PlanWslcSetup = (readiness: WslcReadiness, options: Pick<WslcSetupOptions, 'wslPackage'> & {
+    readonly manifest?: WslcImageManifest;
+}) => WslcSetupPlan;
+export type RunWslcSetup = (consent: WslcSetupConsent, options: WslcSetupOptions & {
+    readonly onProgress?: (progress: WslcSetupProgress) => void;
+    /** Defaults to the real elevated runner; tests pass a stand-in. */
+    readonly runElevated?: RunElevatedWslcSteps;
+    /** The command Windows runs once at the next sign-in to continue setup. */
+    readonly resumeCommand?: string;
+}) => Promise<WslcSetupResult>;
+/**
+ * Stop the wslc session's virtual machine when nothing runs in it. Answers
+ * `busy` and does nothing while any container runs, Namzu's or not.
+ */
+export type StopIdleWslcSession = (options: Pick<WslcSetupOptions, 'host' | 'signal'>) => Promise<{
+    readonly outcome: 'stopped' | 'busy' | 'not-running';
+}>;
+/** Check the bundled archive against its manifest, load it, and check what loaded. */
+export type LoadWslcImage = (options: {
+    readonly manifestPath: string;
+    readonly host?: Partial<WslcSetupHost>;
+    readonly onProgress?: (progress: WslcSetupProgress) => void;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly outcome: 'loaded' | 'already-loaded';
+} | {
+    readonly outcome: 'failed';
+    readonly code: 'image-corrupt' | 'image-load-failed' | 'image-mismatch';
+    readonly detail?: string;
+}>;
+/**
+ * Fetch the pinned WSL package into `directory`, resuming a partial file, and
+ * check its size and SHA-256. A file that fails the check is deleted.
+ */
+export type DownloadWslPackage = (options: {
+    readonly pinned: PinnedWslPackage;
+    readonly directory: string;
+    readonly fetch?: typeof fetch;
+    readonly onProgress?: (progress: WslcSetupProgress) => void;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly outcome: 'ok';
+    readonly path: string;
+} | {
+    readonly outcome: 'failed';
+    readonly code: 'download-failed' | 'download-corrupt';
+    readonly detail?: string;
+}>;
+/** The restart marker in `<stateDirectory>/restart.json`. */
+export type ReadRestartMarker = (host: WslcSetupHost) => Promise<WslcRestartMarker | undefined>;
+export type WriteRestartMarker = (host: WslcSetupHost, marker: WslcRestartMarker) => Promise<void>;
+export type ClearRestartMarker = (host: WslcSetupHost) => Promise<void>;
+/** Ask Windows to run `command` once at the next sign-in, and take that back. */
+export type RegisterResumeAtSignIn = (host: WslcSetupHost, command: string) => Promise<void>;
+export type ClearResumeAtSignIn = (host: WslcSetupHost) => Promise<void>;
+/** The real Windows host, with `overrides` applied. */
+export type CreateWslcSetupHost = (overrides?: Partial<WslcSetupHost>) => WslcSetupHost;
+//# sourceMappingURL=contract.d.ts.map

package/dist/local-virtual-computer/setup/contract.d.ts.map

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

package/dist/local-virtual-computer/setup/contract.js

@@ -0,0 +1,3 @@
+/** Where Windows keeps the command it runs once at the next sign-in. */
+export const RESUME_AT_SIGN_IN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\RunOnce';
+//# sourceMappingURL=contract.js.map

package/dist/local-virtual-computer/setup/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/local-virtual-computer/setup/contract.ts"],"names":[],"mappings":"AAqSA,wEAAwE;AACxE,MAAM,CAAC,MAAM,qBAAqB,GAAG,6DAA6D,CAAA"}

package/dist/local-virtual-computer/setup/elevated.d.ts

@@ -0,0 +1,78 @@
+import type { RunElevatedWslcSteps, WslcElevatedOutcome } from './contract.js';
+/**
+ * The one elevated process of a setup plan.
+ *
+ * Windows PowerShell (a Microsoft-signed program, so the Windows prompt names
+ * Microsoft rather than an unknown publisher) is started with
+ * `Start-Process -Verb RunAs` and runs a FIXED script handed over with
+ * `-EncodedCommand`. There is no script file anyone could edit between the
+ * prompt and the run. Values reach the script only as single-quoted PowerShell
+ * literals, after being validated here. Inside, only Microsoft tools run:
+ * dism.exe, msiexec.exe and Get-FileHash.
+ *
+ * Exit codes of the elevated script: 0 ok, 3010 restart required,
+ * 20 enabling Windows features failed, 21 installing the WSL package failed,
+ * 22 the package did not match the pinned digest. The launcher (a second,
+ * non-elevated PowerShell) prints `NAMZU_EXIT=<code>` with the child's exit
+ * code, 1223 when the person declined the prompt, or `NAMZU_LAUNCH_FAILED`,
+ * and exits 0 itself: the command runner keeps no output from a process that
+ * exits nonzero, so the code travels on stdout.
+ *
+ * The elevated child cannot be stopped from here. Aborting the signal stops
+ * waiting and stops reading progress; if the person already approved, the
+ * elevated steps run to the end.
+ */
+export declare const ELEVATED_EXIT: {
+    readonly ok: 0;
+    readonly restartRequired: 3010;
+    readonly enableFeaturesFailed: 20;
+    readonly installWslFailed: 21;
+    readonly packageMismatch: 22;
+    readonly folderFailed: 23;
+    readonly cancelled: 1223;
+};
+type ElevatedStep = 'enable-windows-features' | 'install-wsl';
+type Request = Parameters<RunElevatedWslcSteps>[0];
+export interface ElevatedScripts {
+    /** The script that runs elevated (the user's SID is filled in by the launcher). */
+    readonly inner: string;
+    /** The script the non-elevated launcher runs; it starts `inner`. */
+    readonly launcher: string;
+    /** `powershell.exe` arguments that run the launcher. */
+    readonly launcherArgs: readonly string[];
+    /** Where the elevated process writes progress, under the protected folder. */
+    readonly progressFile: string;
+    readonly isWindows11: boolean;
+}
+export interface ElevatedBuildOptions {
+    /** 32 hex characters naming the protected folder; random per run. */
+    readonly runId?: string;
+    /** The Windows folder as the host reports it, used only to locate the progress file. */
+    readonly windowsDirectory?: string;
+}
+/**
+ * Validate a request and build both scripts. Exported for tests; the public
+ * entry point is {@link runElevatedWslcSteps}. Throws on any request that
+ * could put a foreign value into a script.
+ */
+export declare function buildElevatedScripts(request: Request, options?: ElevatedBuildOptions): ElevatedScripts;
+export declare function encodeCommand(script: string): string;
+/** What `whoami /groups` lists for an account: an administrator, even with a filtered token, has the group. */
+export declare function isAdministratorAccount(whoamiGroupsOutput: string): boolean;
+interface ProgressLine {
+    readonly step: ElevatedStep;
+    readonly phase: 'started' | 'finished' | 'failed';
+    readonly result?: 'ok' | 'restart-required';
+    readonly exitCode?: number;
+}
+export declare function parseProgressLine(line: string): ProgressLine | undefined;
+/** Map the launcher's answer to an outcome. `standardUser` is only consulted when needed. */
+export declare function mapElevatedExit(code: number, steps: readonly ElevatedStep[], failure: {
+    readonly step?: ElevatedStep;
+    readonly exitCode?: number;
+}): WslcElevatedOutcome | 'cancelled';
+export declare const runElevatedWslcSteps: RunElevatedWslcSteps;
+/** {@link runElevatedWslcSteps} with the run id and Windows folder a test pins. */
+export declare function runElevatedWith(request: Request, options: ElevatedBuildOptions): Promise<WslcElevatedOutcome>;
+export {};
+//# sourceMappingURL=elevated.d.ts.map

package/dist/local-virtual-computer/setup/elevated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevated.d.ts","sourceRoot":"","sources":["../../../src/local-virtual-computer/setup/elevated.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,oBAAoB,EACpB,mBAAmB,EAGnB,MAAM,eAAe,CAAA;AAGtB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,aAAa;;;;;;;;CAQhB,CAAA;AAEV,KAAK,YAAY,GAAG,yBAAyB,GAAG,aAAa,CAAA;AAY7D,KAAK,OAAO,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAA;AAkClD,MAAM,WAAW,eAAe;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACpC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,wFAAwF;IACxF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAClC;AAWD;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,oBAAyB,GAChC,eAAe,CA8EjB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAgMD,+GAA+G;AAC/G,wBAAgB,sBAAsB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAM1E;AAMD,UAAU,YAAY;IACrB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAA;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,kBAAkB,CAAA;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAiBxE;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnE,mBAAmB,GAAG,WAAW,CA+BnC;AA0FD,eAAO,MAAM,oBAAoB,EAAE,oBAAgE,CAAA;AAEnG,mFAAmF;AACnF,wBAAsB,eAAe,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CA8D9B"}