vinext 0.0.0 → 0.0.1

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vinext/cloudflare — Cloudflare Workers integration.
+ *
+ * Provides cache handlers and utilities for running vinext on Cloudflare Workers.
+ */
+export { KVCacheHandler } from "./kv-cache-handler.js";
+export { runTPR, type TPROptions, type TPRResult } from "./tpr.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cloudflare/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cloudflare/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/cloudflare/index.js

@@ -0,0 +1,8 @@
+/**
+ * vinext/cloudflare — Cloudflare Workers integration.
+ *
+ * Provides cache handlers and utilities for running vinext on Cloudflare Workers.
+ */
+export { KVCacheHandler } from "./kv-cache-handler.js";
+export { runTPR } from "./tpr.js";
+//# sourceMappingURL=index.js.map

package/dist/cloudflare/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cloudflare/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAmC,MAAM,UAAU,CAAC"}

package/dist/cloudflare/kv-cache-handler.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cloudflare KV-backed CacheHandler for vinext.
+ *
+ * Provides persistent ISR caching on Cloudflare Workers using KV as the
+ * storage backend. Supports time-based expiry (stale-while-revalidate)
+ * and tag-based invalidation.
+ *
+ * Usage in worker/index.ts:
+ *
+ *   import { KVCacheHandler } from "vinext/cloudflare";
+ *   import { setCacheHandler } from "vinext/shims/cache";
+ *
+ *   export default {
+ *     async fetch(request: Request, env: Env) {
+ *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));
+ *       // ... rest of worker handler
+ *     }
+ *   };
+ *
+ * Wrangler config (wrangler.jsonc):
+ *
+ *   {
+ *     "kv_namespaces": [
+ *       { "binding": "VINEXT_CACHE", "id": "<your-kv-namespace-id>" }
+ *     ]
+ *   }
+ */
+import type { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "../shims/cache.js";
+interface KVNamespace {
+    get(key: string, options?: {
+        type?: string;
+    }): Promise<string | null>;
+    get(key: string, options: {
+        type: "arrayBuffer";
+    }): Promise<ArrayBuffer | null>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: {
+        expirationTtl?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+            metadata?: Record<string, unknown>;
+        }>;
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+export declare class KVCacheHandler implements CacheHandler {
+    private kv;
+    private prefix;
+    constructor(kvNamespace: KVNamespace, options?: {
+        appPrefix?: string;
+    });
+    get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+    set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+    revalidateTag(tags: string | string[], _durations?: {
+        expire?: number;
+    }): Promise<void>;
+    resetRequestCache(): void;
+}
+export {};
+//# sourceMappingURL=kv-cache-handler.d.ts.map

package/dist/cloudflare/kv-cache-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-cache-handler.d.ts","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAG3B,UAAU,WAAW;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAChF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,cAAc,EAC5C,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACvE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QACV,IAAI,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC,CAAC;QAClE,aAAa,EAAE,OAAO,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAiCD,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKhE,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkE9B,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,GAAG,IAAI,EAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IA8DV,aAAa,CACjB,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,IAAI,CAAC;IAehB,iBAAiB,IAAI,IAAI;CAG1B"}

package/dist/cloudflare/kv-cache-handler.js

@@ -0,0 +1,304 @@
+/**
+ * Cloudflare KV-backed CacheHandler for vinext.
+ *
+ * Provides persistent ISR caching on Cloudflare Workers using KV as the
+ * storage backend. Supports time-based expiry (stale-while-revalidate)
+ * and tag-based invalidation.
+ *
+ * Usage in worker/index.ts:
+ *
+ *   import { KVCacheHandler } from "vinext/cloudflare";
+ *   import { setCacheHandler } from "vinext/shims/cache";
+ *
+ *   export default {
+ *     async fetch(request: Request, env: Env) {
+ *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));
+ *       // ... rest of worker handler
+ *     }
+ *   };
+ *
+ * Wrangler config (wrangler.jsonc):
+ *
+ *   {
+ *     "kv_namespaces": [
+ *       { "binding": "VINEXT_CACHE", "id": "<your-kv-namespace-id>" }
+ *     ]
+ *   }
+ */
+/** Key prefix for tag invalidation timestamps. */
+const TAG_PREFIX = "__tag:";
+/** Key prefix for cache entries. */
+const ENTRY_PREFIX = "cache:";
+/** Max tag length to prevent KV key abuse. */
+const MAX_TAG_LENGTH = 256;
+/**
+ * Validate a cache tag. Returns null if invalid.
+ * Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a
+ * separator — allowing `:` in user tags could cause ambiguous key lookups.
+ */
+function validateTag(tag) {
+    if (typeof tag !== "string" || tag.length === 0 || tag.length > MAX_TAG_LENGTH)
+        return null;
+    // Block control characters, path separators, and KV-special characters.
+    // eslint-disable-next-line no-control-regex -- intentional: reject control chars in tags
+    if (/[\x00-\x1f/\\:]/.test(tag))
+        return null;
+    return tag;
+}
+export class KVCacheHandler {
+    kv;
+    prefix;
+    constructor(kvNamespace, options) {
+        this.kv = kvNamespace;
+        this.prefix = options?.appPrefix ? `${options.appPrefix}:` : "";
+    }
+    async get(key, _ctx) {
+        const kvKey = this.prefix + ENTRY_PREFIX + key;
+        const raw = await this.kv.get(kvKey);
+        if (!raw)
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Corrupted JSON — delete and treat as miss
+            await this.kv.delete(kvKey);
+            return null;
+        }
+        // Validate deserialized shape before using
+        const entry = validateCacheEntry(parsed);
+        if (!entry) {
+            console.error("[vinext] Invalid cache entry shape for key:", key);
+            await this.kv.delete(kvKey);
+            return null;
+        }
+        // Restore ArrayBuffer fields that were base64-encoded for JSON storage
+        if (entry.value) {
+            const ok = restoreArrayBuffers(entry.value);
+            if (!ok) {
+                // base64 decode failed — corrupted entry, treat as miss
+                await this.kv.delete(kvKey);
+                return null;
+            }
+        }
+        // Check tag-based invalidation (parallel for lower latency)
+        if (entry.tags.length > 0) {
+            const tagResults = await Promise.all(entry.tags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)));
+            for (let i = 0; i < entry.tags.length; i++) {
+                const tagTime = tagResults[i];
+                if (tagTime) {
+                    const tagTimestamp = Number(tagTime);
+                    if (Number.isNaN(tagTimestamp) || tagTimestamp >= entry.lastModified) {
+                        // Tag was invalidated after this entry, or timestamp is corrupted
+                        // — treat as miss to force re-render
+                        await this.kv.delete(kvKey);
+                        return null;
+                    }
+                }
+            }
+        }
+        // Check time-based expiry — return stale with cacheState
+        if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) {
+            return {
+                lastModified: entry.lastModified,
+                value: entry.value,
+                cacheState: "stale",
+            };
+        }
+        return {
+            lastModified: entry.lastModified,
+            value: entry.value,
+        };
+    }
+    async set(key, data, ctx) {
+        // Collect, validate, and dedupe tags from data and context
+        const tagSet = new Set();
+        if (data && "tags" in data && Array.isArray(data.tags)) {
+            for (const t of data.tags) {
+                const validated = validateTag(t);
+                if (validated)
+                    tagSet.add(validated);
+            }
+        }
+        if (ctx && "tags" in ctx && Array.isArray(ctx.tags)) {
+            for (const t of ctx.tags) {
+                const validated = validateTag(t);
+                if (validated)
+                    tagSet.add(validated);
+            }
+        }
+        const tags = [...tagSet];
+        // Determine revalidation time
+        let revalidateAt = null;
+        if (ctx) {
+            const revalidate = ctx.cacheControl?.revalidate ?? ctx.revalidate;
+            if (typeof revalidate === "number" && revalidate > 0) {
+                revalidateAt = Date.now() + revalidate * 1000;
+            }
+        }
+        if (data &&
+            "revalidate" in data &&
+            typeof data.revalidate === "number" &&
+            data.revalidate > 0) {
+            revalidateAt = Date.now() + data.revalidate * 1000;
+        }
+        // Prepare entry — convert ArrayBuffers to base64 for JSON storage
+        const serializable = data ? serializeForJSON(data) : null;
+        const entry = {
+            value: serializable,
+            tags,
+            lastModified: Date.now(),
+            revalidateAt,
+        };
+        // Calculate KV TTL — keep entries well beyond their revalidate window
+        // (10x revalidate period, clamped to 60s–30d) so stale-while-revalidate
+        // can serve stale content while background regeneration happens.
+        let expirationTtl;
+        if (revalidateAt !== null) {
+            const revalidateSeconds = Math.ceil((revalidateAt - Date.now()) / 1000);
+            // Keep in KV for 10x the revalidation period, up to 30 days
+            expirationTtl = Math.min(revalidateSeconds * 10, 30 * 24 * 3600);
+            // KV minimum TTL is 60 seconds
+            expirationTtl = Math.max(expirationTtl, 60);
+        }
+        await this.kv.put(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {
+            expirationTtl,
+        });
+    }
+    async revalidateTag(tags, _durations) {
+        const tagList = Array.isArray(tags) ? tags : [tags];
+        const now = Date.now();
+        const validTags = tagList.filter((t) => validateTag(t) !== null);
+        // Store invalidation timestamp for each tag
+        // Use a long TTL (30 days) so recent invalidations are always found
+        await Promise.all(validTags.map((tag) => this.kv.put(this.prefix + TAG_PREFIX + tag, String(now), {
+            expirationTtl: 30 * 24 * 3600,
+        })));
+    }
+    resetRequestCache() {
+        // No-op — KV is stateless per request
+    }
+}
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+const VALID_KINDS = new Set([
+    "FETCH",
+    "APP_PAGE",
+    "PAGES",
+    "APP_ROUTE",
+    "REDIRECT",
+    "IMAGE",
+]);
+/**
+ * Validate that a parsed JSON value has the expected KVCacheEntry shape.
+ * Returns the validated entry or null if the shape is invalid.
+ */
+function validateCacheEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    // Required fields
+    if (typeof obj.lastModified !== "number")
+        return null;
+    if (!Array.isArray(obj.tags))
+        return null;
+    if (obj.revalidateAt !== null &&
+        typeof obj.revalidateAt !== "number")
+        return null;
+    // value must be null or a valid cache value object with a known kind
+    if (obj.value !== null) {
+        if (!obj.value || typeof obj.value !== "object")
+            return null;
+        const value = obj.value;
+        if (typeof value.kind !== "string" || !VALID_KINDS.has(value.kind))
+            return null;
+    }
+    return raw;
+}
+// ---------------------------------------------------------------------------
+// ArrayBuffer serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Deep-clone a cache value, converting ArrayBuffer fields to base64 strings
+ * so the entire structure can be JSON.stringify'd for KV storage.
+ */
+function serializeForJSON(value) {
+    if (value.kind === "APP_PAGE") {
+        return {
+            ...value,
+            rscData: value.rscData
+                ? arrayBufferToBase64(value.rscData)
+                : undefined,
+        };
+    }
+    if (value.kind === "APP_ROUTE") {
+        return {
+            ...value,
+            body: arrayBufferToBase64(value.body),
+        };
+    }
+    if (value.kind === "IMAGE") {
+        return {
+            ...value,
+            buffer: arrayBufferToBase64(value.buffer),
+        };
+    }
+    return value;
+}
+/**
+ * Restore base64 strings back to ArrayBuffers after JSON.parse.
+ * Returns false if any base64 decode fails (corrupted entry).
+ */
+function restoreArrayBuffers(value) {
+    if (value.kind === "APP_PAGE" && typeof value.rscData === "string") {
+        const decoded = safeBase64ToArrayBuffer(value.rscData);
+        if (!decoded)
+            return false;
+        value.rscData = decoded;
+    }
+    if (value.kind === "APP_ROUTE" && typeof value.body === "string") {
+        const decoded = safeBase64ToArrayBuffer(value.body);
+        if (!decoded)
+            return false;
+        value.body = decoded;
+    }
+    if (value.kind === "IMAGE" && typeof value.buffer === "string") {
+        const decoded = safeBase64ToArrayBuffer(value.buffer);
+        if (!decoded)
+            return false;
+        value.buffer = decoded;
+    }
+    return true;
+}
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function base64ToArrayBuffer(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}
+/**
+ * Safely decode base64 to ArrayBuffer. Returns null on invalid input
+ * instead of throwing a DOMException.
+ */
+function safeBase64ToArrayBuffer(base64) {
+    try {
+        return base64ToArrayBuffer(base64);
+    }
+    catch {
+        console.error("[vinext] Invalid base64 in cache entry");
+        return null;
+    }
+}
+//# sourceMappingURL=kv-cache-handler.js.map

package/dist/cloudflare/kv-cache-handler.js.map

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

package/dist/cloudflare/tpr.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TPR: Traffic-aware Pre-Rendering
+ *
+ * Uses Cloudflare zone analytics to determine which pages actually get
+ * traffic, and pre-renders only those during deploy. The pre-rendered
+ * HTML is uploaded to KV in the same format ISR uses at runtime — no
+ * runtime changes needed.
+ *
+ * Flow:
+ *   1. Parse wrangler config to find custom domain and KV namespace
+ *   2. Resolve the Cloudflare zone for the custom domain
+ *   3. Query zone analytics (GraphQL) for top pages by request count
+ *   4. Walk ranked list until coverage threshold is met
+ *   5. Start the built production server locally
+ *   6. Fetch each hot route to produce HTML
+ *   7. Upload pre-rendered HTML to KV (same KVCacheEntry format ISR reads)
+ *
+ * TPR is an experimental feature enabled via --experimental-tpr. It
+ * gracefully skips when no custom domain, no API token, no traffic data,
+ * or no KV namespace is configured.
+ */
+export interface TPROptions {
+    /** Project root directory. */
+    root: string;
+    /** Traffic coverage percentage (0–100). Default: 90. */
+    coverage: number;
+    /** Hard cap on number of pages to pre-render. Default: 1000. */
+    limit: number;
+    /** Analytics lookback window in hours. Default: 24. */
+    window: number;
+}
+export interface TPRResult {
+    /** Total unique page paths found in analytics. */
+    totalPaths: number;
+    /** Number of pages successfully pre-rendered and uploaded. */
+    prerenderedCount: number;
+    /** Actual traffic coverage achieved (percentage). */
+    coverageAchieved: number;
+    /** Wall-clock duration of the TPR step in milliseconds. */
+    durationMs: number;
+    /** If TPR was skipped, the reason. */
+    skipped?: string;
+}
+interface TrafficEntry {
+    path: string;
+    requests: number;
+}
+interface SelectedRoutes {
+    routes: TrafficEntry[];
+    totalRequests: number;
+    coveredRequests: number;
+    coveragePercent: number;
+}
+interface WranglerConfig {
+    accountId?: string;
+    kvNamespaceId?: string;
+    customDomain?: string;
+}
+/**
+ * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
+ * account_id, VINEXT_CACHE KV namespace ID, and custom domain.
+ */
+export declare function parseWranglerConfig(root: string): WranglerConfig | null;
+/**
+ * Walk the ranked traffic list, accumulating request counts until the
+ * coverage target is met or the hard cap is reached.
+ */
+export declare function selectRoutes(traffic: TrafficEntry[], coverageTarget: number, limit: number): SelectedRoutes;
+/**
+ * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
+ *
+ * Designed to be called between the build step and wrangler deploy in
+ * the `vinext deploy` pipeline. Gracefully skips (never errors) when
+ * the prerequisites aren't met.
+ */
+export declare function runTPR(options: TPROptions): Promise<TPRResult>;
+export {};
+//# sourceMappingURL=tpr.d.ts.map

package/dist/cloudflare/tpr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tpr.d.ts","sourceRoot":"","sources":["../../src/cloudflare/tpr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAQD,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAuBvE;AAkXD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,CAuBhB;AAyPD;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAmIpE"}