@vendoai/apps 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/** @vendoai/apps — the app artifact and engine (docs/contracts/06-apps.md).
+ *
+ * The sandbox seam is the execution-v2 shape (sandbox.ts); the v1 seam and
+ * its compat bridge are deleted (execution-v2 Wave 1.5).
+ * The package root otherwise exports exactly the 06 §1 public API plus the
+ * block-plan's flagged additions (AppsConfig.pinBaselines), the ENG-288 M4
+ * in-client trust-axis surface (06 §9): AppsRuntime.inClient and
+ * appVersionHash, and the ENG-288 M5 drift→rebase surface (06 §8):
+ * AppsRuntime.pins and detectPinDrift.
+ * Everything else — the generation engine, interchange plumbing — is internal
+ * and reachable only through AppsRuntime.
+ */
+export { createApps, type AppsConfig, type AppsRuntime, type BoxRequest, type BoxResponse, type EditFailure, type EditResult, type MachineEditResult, type OpenSurface, type PinForkInput, type PinForkResult, type PinRebaseResult, type SecretExposureState, type SetExposureResult, type VersionEntry, } from "./runtime.js";
+export type { SandboxAdapter, SandboxMachine, SandboxResumePolicy } from "./sandbox.js";
+export { parseVendoManifest, vendoManifestSchema, type VendoManifest, type VendoManifestSchedule, } from "./manifest.js";
+export { createAppTokens, type AppTokens, } from "./app-token.js";
+export { buildEnv, type BuildEnvContext, type BuiltBoxEnv, type InferenceResolver, } from "./box-env.js";
+export { SCHEDULE_STATE_COLLECTION } from "./schedules.js";
+export { shareSnapshotSchema, publishRecordSchema, type CloudAppsClient, type PublishRecord, type ShareSnapshot, } from "./cloud.js";
+export { detectPinDrift, inClientApprovalSchema, pinBaselineSchema, pinComponentName, type InClientApproval, type PinBaseline, type PinDrift, } from "./pins.js";
+export { appVersionHash } from "./version-hash.js";
+export { type InClientVenueState, type InClientVerdict, } from "./inclient.js";
+export { type ShipDiff, type ShipDiffGenerated, type ShipDiffPin, } from "./ship-diff.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,UAAU,EACV,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,KAAK,SAAS,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,QAAQ,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/** @vendoai/apps — the app artifact and engine (docs/contracts/06-apps.md).
+ *
+ * The sandbox seam is the execution-v2 shape (sandbox.ts); the v1 seam and
+ * its compat bridge are deleted (execution-v2 Wave 1.5).
+ * The package root otherwise exports exactly the 06 §1 public API plus the
+ * block-plan's flagged additions (AppsConfig.pinBaselines), the ENG-288 M4
+ * in-client trust-axis surface (06 §9): AppsRuntime.inClient and
+ * appVersionHash, and the ENG-288 M5 drift→rebase surface (06 §8):
+ * AppsRuntime.pins and detectPinDrift.
+ * Everything else — the generation engine, interchange plumbing — is internal
+ * and reachable only through AppsRuntime.
+ */
+export { createApps, } from "./runtime.js";
+// execution-v2 skin contract (Lane C): the manifest gate, the per-app box
+// token, and the box env assembly Lane B consumes at provision.
+export { parseVendoManifest, vendoManifestSchema, } from "./manifest.js";
+export { createAppTokens, } from "./app-token.js";
+export { buildEnv, } from "./box-env.js";
+// execution-v2 Lane D — the BYO schedule engine's state collection (the wire
+// tests pin its name).
+export { SCHEDULE_STATE_COLLECTION } from "./schedules.js";
+export { shareSnapshotSchema, publishRecordSchema, } from "./cloud.js";
+export { detectPinDrift, inClientApprovalSchema, pinBaselineSchema, pinComponentName, } from "./pins.js";
+export { appVersionHash } from "./version-hash.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,UAAU,GAeX,MAAM,cAAc,CAAC;AAEtB,0EAA0E;AAC1E,gEAAgE;AAChE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAGpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,GAEhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,QAAQ,GAIT,MAAM,cAAc,CAAC;AACtB,6EAA6E;AAC7E,uBAAuB;AACvB,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GAIpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/interchange.d.ts

@@ -0,0 +1,17 @@
+import { type AppDocument, type AppId, type Guard, type RunContext, type StoreAdapter } from "@vendoai/core";
+import { type PinBaseline } from "./pins.js";
+/** Dependencies for the 06-apps §7 interchange boundary. */
+export interface AppInterchangeDependencies {
+    store: StoreAdapter;
+    guard: Guard;
+    pinBaselines?: readonly PinBaseline[];
+    requireOwned(appId: AppId, subject: string): Promise<AppDocument>;
+}
+/** Public interchange methods wired into AppsRuntime. */
+export interface AppInterchange {
+    exportApp(appId: AppId, ctx: RunContext): Promise<Uint8Array>;
+    importApp(source: Uint8Array | AppDocument, ctx: RunContext): Promise<AppDocument>;
+}
+/** 06-apps §7 — build the copy-only .vendoapp import/export boundary. */
+export declare const createAppInterchange: (dependencies: AppInterchangeDependencies) => AppInterchange;
+//# sourceMappingURL=interchange.d.ts.map

package/dist/interchange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interchange.d.ts","sourceRoot":"","sources":["../src/interchange.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,KAAK,EAEV,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AA+GnE,4DAA4D;AAC5D,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACnE;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9D,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACpF;AAED,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,GAC/B,cAAc,0BAA0B,KACvC,cA0CF,CAAC"}

package/dist/interchange.js

@@ -0,0 +1,133 @@
+import { VendoError, validateAppDocument, } from "@vendoai/core";
+import { unzipSync, zipSync } from "fflate";
+import { appLifecycleEvent } from "./audit.js";
+import { appRecordInput } from "./persistence.js";
+import { assertPinsExportable } from "./pins.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const ARCHIVE_MAX_ENTRIES = 4_096;
+const ARCHIVE_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const ARCHIVE_MAX_ENTRY_BYTES = 16 * 1024 * 1024;
+const APP_DOCUMENT_FIELDS = [
+    "format",
+    "id",
+    "name",
+    "description",
+    "ui",
+    "tree",
+    "components",
+    "storage",
+    "server",
+    "machine",
+    "trigger",
+    "egress",
+    "secrets",
+    "pins",
+    "forkedFrom",
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const validationError = (message, detail) => new VendoError("validation", message, detail);
+const validateImportedDocument = (input) => {
+    const result = validateAppDocument(input);
+    if (!result.ok) {
+        throw validationError(`invalid imported app document: ${result.error.message}`, {
+            reason: result.error.message,
+            validationCode: result.error.code,
+        });
+    }
+    return structuredClone(result.app);
+};
+const allowedDocumentFields = (input, omitted) => {
+    if (!isRecord(input))
+        return {};
+    const copy = {};
+    for (const field of APP_DOCUMENT_FIELDS) {
+        if (!omitted.has(field) && Object.prototype.hasOwnProperty.call(input, field)) {
+            copy[field] = structuredClone(input[field]);
+        }
+    }
+    return copy;
+};
+// execution-v2 — interchange is document-only, a copy boundary: a machine (or
+// retired v1 server) ref never crosses it. Export never writes one, import
+// strips one a document tries to smuggle in, and the box's disk is scratch by
+// the data rule — an imported app re-graduates on its own.
+const withoutExportIdentity = (app) => allowedDocumentFields(app, new Set(["id", "server", "machine", "forkedFrom"]));
+const withFreshIdentity = (input, id) => {
+    const copy = allowedDocumentFields(input, new Set(["id", "server", "machine", "forkedFrom"]));
+    copy.id = id;
+    return copy;
+};
+const parseArchive = (source) => {
+    try {
+        let entryCount = 0;
+        let declaredBytes = 0;
+        const archive = unzipSync(source, {
+            filter(entry) {
+                entryCount += 1;
+                declaredBytes += entry.originalSize;
+                if (entryCount > ARCHIVE_MAX_ENTRIES
+                    || entry.originalSize > ARCHIVE_MAX_ENTRY_BYTES
+                    || declaredBytes > ARCHIVE_MAX_TOTAL_BYTES) {
+                    throw validationError("app archive exceeds size limits");
+                }
+                return true;
+            },
+        });
+        let inflatedBytes = 0;
+        for (const bytes of Object.values(archive)) {
+            inflatedBytes += bytes.byteLength;
+            if (bytes.byteLength > ARCHIVE_MAX_ENTRY_BYTES || inflatedBytes > ARCHIVE_MAX_TOTAL_BYTES) {
+                throw validationError("app archive exceeds size limits");
+            }
+        }
+        const appJson = archive["app.json"];
+        if (appJson === undefined)
+            throw validationError("invalid .vendoapp: app.json is missing");
+        return {
+            document: JSON.parse(decoder.decode(appJson)),
+            hasAppDirectory: Object.keys(archive).some((entry) => entry.startsWith("app/")),
+        };
+    }
+    catch (error) {
+        if (error instanceof VendoError)
+            throw error;
+        throw validationError("invalid .vendoapp archive", {
+            reason: error instanceof Error ? error.message : "archive parse failed",
+        });
+    }
+};
+/** 06-apps §7 — build the copy-only .vendoapp import/export boundary. */
+export const createAppInterchange = (dependencies) => {
+    const report = async (operation, appId, ctx, extra = {}) => {
+        await dependencies.guard.report(appLifecycleEvent(ctx.principal, ctx, appId, { operation, ...extra }));
+    };
+    return {
+        async exportApp(appId, ctx) {
+            const app = await dependencies.requireOwned(appId, ctx.principal.subject);
+            assertPinsExportable(app.pins ?? [], dependencies.pinBaselines ?? []);
+            const archive = {
+                "app.json": encoder.encode(JSON.stringify(withoutExportIdentity(app))),
+            };
+            const bytes = zipSync(archive, { level: 6 });
+            await report("export", app.id, ctx);
+            return bytes;
+        },
+        async importApp(source, ctx) {
+            // Mint before document validation; an artifact id is never trusted (01-core §10).
+            const appId = `app_${globalThis.crypto.randomUUID()}`;
+            const parsed = source instanceof Uint8Array
+                ? parseArchive(source)
+                : { document: source, hasAppDirectory: false };
+            const imported = validateImportedDocument(withFreshIdentity(parsed.document, appId));
+            await dependencies.store.records("vendo_apps").put(appRecordInput(imported, ctx.principal.subject));
+            // An app/ directory in the archive is machine scratch from an older
+            // export; it is ignored — the imported copy re-graduates on its own.
+            await report("import", imported.id, ctx, {
+                appDirectory: parsed.hasAppDirectory ? "ignored" : "absent",
+            });
+            return structuredClone(imported);
+        },
+    };
+};
+//# sourceMappingURL=interchange.js.map

package/dist/interchange.js.map

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

package/dist/machine-lifecycle.d.ts

@@ -0,0 +1,102 @@
+import { type AppDocument, type AppId, type StoreAdapter } from "@vendoai/core";
+import type { SandboxAdapter, SandboxMachine } from "./sandbox.js";
+/** Injectable timer seam so idle auto-sleep is testable without real time. */
+export interface LifecycleClock {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/**
+ * Lane C's env-assembly seam (PORT, secrets, store URL, callback URL,
+ * inference endpoint). Injected here so the lanes do not collide; the default
+ * assembles nothing.
+ *
+ * Lane E adds `grants`: the runtime resolves the app's active secret grants
+ * and hands them to the host's assembler, so ONLY declared ∩ granted secrets
+ * inject real values (the assembler never reads grant state itself). The
+ * lifecycle calls the seam with the document only; the runtime composes the
+ * grant-carrying closure.
+ */
+export type BuildMachineEnv = (app: AppDocument, grants?: MachineEnvGrants) => Promise<Record<string, string>> | Record<string, string>;
+/** Lane E — grant state resolved by the runtime for the env assembler. */
+export interface MachineEnvGrants {
+    /** Names of declared secrets the owner granted to THIS app. */
+    grantedSecrets: ReadonlySet<string>;
+}
+/**
+ * Lane E's egress-policy seam: resolves the CURRENT allowlist a machine must
+ * boot or wake with (approved declaration + implicit skin domains — see
+ * boxAllowlist in egress-approval.ts, where the list is assembled). Consulted
+ * on every provision AND every wake, so a grant decided while the machine
+ * slept applies at the next resume; it throws to refuse the operation (an
+ * unapproved declared domain must never reach the provider). `undefined`
+ * result means unrestricted egress (no policy for this app). No callback →
+ * pre-Lane-E behavior: create unrestricted, resume with the snapshot ref's
+ * stored policy.
+ */
+export type BuildMachineAllowlist = (app: AppDocument) => Promise<string[] | undefined> | string[] | undefined;
+export interface MachineLifecycleConfig {
+    store: StoreAdapter;
+    sandbox?: SandboxAdapter;
+    buildEnv?: BuildMachineEnv;
+    allowedDomains?: BuildMachineAllowlist;
+    /**
+     * Wave 7 — push a freshly assembled boundary env into a LIVE machine (the
+     * runtime wires the box control port's env door, which restarts the app).
+     * A wake of a machine whose document carries `machine.envStaleAt` (a secret
+     * grant changed while it slept — resumes restore the SNAPSHOT's env on
+     * every provider) rebuilds the env through this seam and clears the marker.
+     * Fail-closed: an injection failure destroys the resumed machine and fails
+     * the wake (a box we cannot re-police must not serve — a revoked secret
+     * would stay usable inside it); the marker and ref survive for the retry.
+     */
+    injectEnv?: (machine: SandboxMachine, env: Record<string, string>) => Promise<void>;
+    /** Provider base template every provisioned machine boots from. */
+    template?: string;
+    idleMs?: number;
+    clock?: LifecycleClock;
+}
+/**
+ * Execution-v2 machine lifecycle: provision on graduation, wake on demand,
+ * sleep on idle, destroy with the app. Wake single-flight and the idle timer
+ * are in-process state — multi-instance hosts can wake one app twice (known
+ * v2 limit; last sleep's CAS wins).
+ */
+export interface MachineLifecycle {
+    available(): boolean;
+    /** The live machine for an app, when one is awake in this process. */
+    peek(appId: AppId): SandboxMachine | undefined;
+    /** Create the machine from the base template, snapshot it, store the ref. Idempotent. */
+    provision(app: AppDocument): Promise<AppDocument>;
+    /** Resume the stored snapshot; concurrent wakes of one app share one machine. */
+    wake(app: AppDocument): Promise<SandboxMachine>;
+    /** Snapshot the live machine, store the new ref, stop it. No-op when not awake. */
+    sleep(app: AppDocument): Promise<AppDocument>;
+    /**
+     * execution-v2 Wave 3 — drop the live machine WITHOUT snapshotting it,
+     * leaving the document's `machine.snapshotRef` untouched: the app rolls back
+     * to its pre-edit snapshot (the next wake re-provisions from the prior ref).
+     * This is the failed-edit rollback — no new fork machinery, just "don't keep
+     * what the box just did". No-op when the app is not awake.
+     */
+    discard(app: AppDocument): Promise<void>;
+    /** Destroy the sandbox and clear the document's machine field. */
+    destroyMachine(app: AppDocument): Promise<AppDocument>;
+    /**
+     * execution-v2 Wave 3 — reap ALL provider resources for an app (live machine
+     * + stored snapshot) WITHOUT rewriting the document. The delete path uses
+     * this: the row is about to be removed, so re-validating a machine-cleared
+     * document (which a graduated tree's `fn:` refs would fail) must never block
+     * the provider cleanup. Best-effort and idempotent.
+     */
+    destroyResources(app: AppDocument): Promise<void>;
+    /**
+     * execution-v2 Wave 3 — the CURRENT boundary env for an app (PORT, granted
+     * secrets, skin URLs, inference), assembled by the injected buildEnv seam.
+     * The Wave-3 edit flow pushes this to the box's control port before an edit
+     * so a grant flipped while the machine slept lands via the in-box restart
+     * loop (Lane E's env-baked-at-provision gap).
+     */
+    buildAppEnv(app: AppDocument): Promise<Record<string, string>>;
+}
+export declare const createMachineLifecycle: (config: MachineLifecycleConfig) => MachineLifecycle;
+//# sourceMappingURL=machine-lifecycle.d.ts.map

package/dist/machine-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-lifecycle.d.ts","sourceRoot":"","sources":["../src/machine-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnE,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAChD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,WAAW,EAChB,MAAM,CAAC,EAAE,gBAAgB,KACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE9D,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,IAAI,OAAO,CAAC;IACrB,sEAAsE;IACtE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,cAAc,GAAG,SAAS,CAAC;IAC/C,yFAAyF;IACzF,SAAS,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClD,iFAAiF;IACjF,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAChD,mFAAmF;IACnF,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,kEAAkE;IAClE,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChE;AAUD,eAAO,MAAM,sBAAsB,GAAI,QAAQ,sBAAsB,KAAG,gBAuWvE,CAAC"}