@osmix/core 0.0.2 → 0.1.1

package/dist/src/stringtable.d.ts

@@ -1,37 +1,101 @@
-import type { OsmPbfBlock, OsmPbfStringTable } from "@osmix/pbf";
-import { type BufferType } from "./typed-arrays";
-export interface StringTableTransferables {
-    bytes: BufferType;
-    start: BufferType;
-    count: BufferType;
+/**
+ * Deduplicated UTF-8 string storage.
+ *
+ * Strings are stored in a flat buffer and referenced by index.
+ * Supports fast deduplication (string→index) and lazy reconstruction (index→string).
+ *
+ * @module
+ */
+import type { OsmPbfStringTable } from "@osmix/pbf";
+import { type BufferType, ResizeableTypedArray as RTA } from "./typed-arrays";
+import type { ContentHasher } from "./utils";
+/**
+ * Serializable state for worker transfer.
+ */
+export interface StringTableTransferables<T extends BufferType = BufferType> {
+    /** Concatenated UTF-8 bytes. */
+    bytes: T;
+    /** Maps string index → byte offset. */
+    start: T;
+    /** Maps string index → byte length. */
+    count: T;
 }
 /**
- * StringTable that can be used to store and retrieve strings as bytes.
+ * Append-only deduplicated string table.
+ *
+ * Limits: Max string length 65,535 bytes.
+ * Rebuilds reverse index lazily after transfer.
  */
 export default class StringTable {
+    /** UTF-8 encoder for string→bytes conversion */
     private enc;
+    /** UTF-8 decoder for bytes→string conversion */
     private dec;
-    private bytes;
-    private start;
-    private count;
+    /** Concatenated UTF-8 bytes of all strings */
+    bytes: RTA<Uint8Array>;
+    /** Maps string index → byte offset in bytes array */
+    start: RTA<Uint32Array>;
+    /** Maps string index → byte length */
+    count: RTA<Uint16Array>;
+    /** Forward lookup: string → index (populated during add) */
     private stringToIndex;
+    /** Whether the reverse index has been built (lazy after transfer) */
+    private reverseIndexBuilt;
+    /** Cache of decoded strings to avoid repeated UTF-8 decoding */
     private indexToString;
-    static from({ bytes, start, count }: StringTableTransferables): StringTable;
-    constructor();
+    /**
+     * Create a new StringTable.
+     */
+    constructor(opts?: StringTableTransferables);
+    /**
+     * Get transferable objects for passing to another thread.
+     */
     transferables(): StringTableTransferables;
+    /**
+     * Add a string to the table and return its index.
+     */
     add(str: string): number;
     /**
      * Decode all the strings in a primitive block and add them to the string table.
      * Return a mapping of block index -> string table index
      */
-    createBlockIndexMap(block: OsmPbfBlock): Map<number, number>;
+    createBlockIndexMap(blockStringtable: OsmPbfStringTable): Uint32Array<ArrayBuffer>;
     /**
-     * TextDecoder.decode() does not support SharedArrayBuffer, so we need to first copy to a normal ArrayBuffer before decoding.
+     * Get a string by its index.
+     * Caches results to avoid repeated UTF-8 decoding.
      */
     get(index: number): string;
+    /**
+     * Get the raw UTF-8 bytes of a string.
+     * Returns a subarray view (not a copy).
+     */
     getBytes(index: number): Uint8Array;
+    /** Number of strings in the table. */
     get length(): number;
+    /**
+     * Finalize the string table by compacting internal arrays.
+     *
+     * This releases unused buffer capacity and marks the reverse index as built
+     * (since all strings were added before this call).
+     */
     buildIndex(): void;
+    /**
+     * Convert the string table to an OSM PBF string table.
+     */
     toOsmPbfStringTable(): OsmPbfStringTable;
+    /**
+     * Lazily build the reverse index (string → index).
+     * Decodes all strings once to populate the lookup map.
+     */
+    private ensureReverseIndex;
+    /**
+     * Find the index of a string.
+     */
+    find(str: string): number;
+    /**
+     * Update a ContentHasher with the string table's data.
+     * Hashes the bytes, start offsets, and counts.
+     */
+    updateHash(hasher: ContentHasher): ContentHasher;
 }
 //# sourceMappingURL=stringtable.d.ts.map

package/dist/src/stringtable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stringtable.d.ts","sourceRoot":"","sources":["../../src/stringtable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,gBAAgB,CAAA;AAEtE,MAAM,WAAW,wBAAwB;IACxC,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,UAAU,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;IAC/B,OAAO,CAAC,GAAG,CAAoB;IAC/B,OAAO,CAAC,GAAG,CAAoB;IAG/B,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,KAAK,CAAmC;IAGhD,OAAO,CAAC,aAAa,CAA4B;IAGjD,OAAO,CAAC,aAAa,CAA4B;IAEjD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,wBAAwB,GAAG,WAAW;;IAc3E,aAAa,IAAI,wBAAwB;IAQzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAYxB;;;OAGG;IACH,mBAAmB,CAAC,KAAK,EAAE,WAAW;IAWtC;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAY1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IASnC,IAAI,MAAM,WAET;IAED,UAAU;IAQV,mBAAmB,IAAI,iBAAiB;CAOxC"}
+{"version":3,"file":"stringtable.d.ts","sourceRoot":"","sources":["../../src/stringtable.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,KAAK,UAAU,EAAE,oBAAoB,IAAI,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAC1E,gCAAgC;IAChC,KAAK,EAAE,CAAC,CAAA;IACR,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAA;IACR,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAA;CACR;AAED;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;IAC/B,gDAAgD;IAChD,OAAO,CAAC,GAAG,CAAoB;IAC/B,gDAAgD;IAChD,OAAO,CAAC,GAAG,CAAoB;IAG/B,8CAA8C;IAC9C,KAAK,EAAE,GAAG,CAAC,UAAU,CAAC,CAAA;IACtB,qDAAqD;IACrD,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,CAAA;IACvB,sCAAsC;IACtC,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,CAAA;IAGvB,4DAA4D;IAC5D,OAAO,CAAC,aAAa,CAA4B;IAEjD,qEAAqE;IACrE,OAAO,CAAC,iBAAiB,CAAQ;IAGjC,gEAAgE;IAChE,OAAO,CAAC,aAAa,CAA4B;IAEjD;;OAEG;gBACS,IAAI,CAAC,EAAE,wBAAwB;IAY3C;;OAEG;IACH,aAAa,IAAI,wBAAwB;IAQzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAYxB;;;OAGG;IACH,mBAAmB,CAAC,gBAAgB,EAAE,iBAAiB;IAevD;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAY1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAQnC,sCAAsC;IACtC,IAAI,MAAM,WAET;IAED;;;;;OAKG;IACH,UAAU;IAOV;;OAEG;IACH,mBAAmB,IAAI,iBAAiB;IAQxC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAOzB;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAMhD"}

package/dist/src/stringtable.js

@@ -1,30 +1,55 @@
-import { ResizeableTypedArray } from "./typed-arrays";
 /**
- * StringTable that can be used to store and retrieve strings as bytes.
+ * Deduplicated UTF-8 string storage.
+ *
+ * Strings are stored in a flat buffer and referenced by index.
+ * Supports fast deduplication (string→index) and lazy reconstruction (index→string).
+ *
+ * @module
+ */
+import { ResizeableTypedArray as RTA } from "./typed-arrays";
+/**
+ * Append-only deduplicated string table.
+ *
+ * Limits: Max string length 65,535 bytes.
+ * Rebuilds reverse index lazily after transfer.
  */
 export default class StringTable {
+    /** UTF-8 encoder for string→bytes conversion */
     enc = new TextEncoder();
+    /** UTF-8 decoder for bytes→string conversion */
     dec = new TextDecoder(); // UTF-8
-    // Serializable state
+    // ─── Serializable State ────────────────────────────────────────────────────
+    /** Concatenated UTF-8 bytes of all strings */
     bytes;
+    /** Maps string index → byte offset in bytes array */
     start;
+    /** Maps string index → byte length */
     count;
-    // Builder state
+    // ─── Builder State (string → index) ────────────────────────────────────────
+    /** Forward lookup: string → index (populated during add) */
     stringToIndex = new Map();
-    // Retrieval state
+    /** Whether the reverse index has been built (lazy after transfer) */
+    reverseIndexBuilt = false;
+    // ─── Retrieval Cache (index → string) ──────────────────────────────────────
+    /** Cache of decoded strings to avoid repeated UTF-8 decoding */
     indexToString = new Map();
-    static from({ bytes, start, count }) {
-        const builder = new StringTable();
-        builder.bytes = ResizeableTypedArray.from(Uint8Array, bytes);
-        builder.start = ResizeableTypedArray.from(Uint32Array, start);
-        builder.count = ResizeableTypedArray.from(Uint16Array, count);
-        return builder;
-    }
-    constructor() {
-        this.bytes = new ResizeableTypedArray(Uint8Array);
-        this.start = new ResizeableTypedArray(Uint32Array);
-        this.count = new ResizeableTypedArray(Uint16Array);
+    /**
+     * Create a new StringTable.
+     */
+    constructor(opts) {
+        this.bytes = opts?.bytes
+            ? RTA.from(Uint8Array, opts.bytes)
+            : new RTA(Uint8Array);
+        this.start = opts?.start
+            ? RTA.from(Uint32Array, opts.start)
+            : new RTA(Uint32Array);
+        this.count = opts?.count
+            ? RTA.from(Uint16Array, opts.count)
+            : new RTA(Uint16Array);
     }
+    /**
+     * Get transferable objects for passing to another thread.
+     */
     transferables() {
         return {
             bytes: this.bytes.array.buffer,
@@ -32,6 +57,9 @@ export default class StringTable {
             count: this.count.array.buffer,
         };
     }
+    /**
+     * Add a string to the table and return its index.
+     */
     add(str) {
         const existingIndex = this.stringToIndex.get(str);
         if (existingIndex !== undefined)
@@ -48,18 +76,23 @@ export default class StringTable {
      * Decode all the strings in a primitive block and add them to the string table.
      * Return a mapping of block index -> string table index
      */
-    createBlockIndexMap(block) {
-        const map = new Map();
-        for (let i = 0; i < block.stringtable.length; i++) {
-            const bytesString = block.stringtable[i];
+    createBlockIndexMap(blockStringtable) {
+        const index = new Uint32Array(blockStringtable.length);
+        for (let i = 0; i < blockStringtable.length; i++) {
+            const bytesString = blockStringtable[i];
             const str = this.dec.decode(bytesString);
-            const index = this.add(str);
-            map.set(i, index);
+            const existingIndex = this.stringToIndex.get(str);
+            if (existingIndex !== undefined) {
+                index[i] = existingIndex;
+                continue;
+            }
+            index[i] = this.add(str);
         }
-        return map;
+        return index;
     }
     /**
-     * TextDecoder.decode() does not support SharedArrayBuffer, so we need to first copy to a normal ArrayBuffer before decoding.
+     * Get a string by its index.
+     * Caches results to avoid repeated UTF-8 decoding.
      */
     get(index) {
         const string = this.indexToString.get(index);
@@ -73,23 +106,36 @@ export default class StringTable {
         this.indexToString.set(index, decoded);
         return decoded;
     }
+    /**
+     * Get the raw UTF-8 bytes of a string.
+     * Returns a subarray view (not a copy).
+     */
     getBytes(index) {
         if (index < 0 || index >= this.length)
             throw Error(`String index out of range: ${index}`);
         const start = this.start.at(index);
         const count = this.count.at(index);
-        // Important: subarray creates a *view*, not a copy; TextDecoder cannot read from it directly.
         return this.bytes.array.subarray(start, start + count);
     }
+    /** Number of strings in the table. */
     get length() {
         return this.start.length;
     }
+    /**
+     * Finalize the string table by compacting internal arrays.
+     *
+     * This releases unused buffer capacity and marks the reverse index as built
+     * (since all strings were added before this call).
+     */
     buildIndex() {
         this.bytes.compact();
         this.start.compact();
         this.count.compact();
-        this.stringToIndex.clear();
+        this.reverseIndexBuilt = true;
     }
+    /**
+     * Convert the string table to an OSM PBF string table.
+     */
     toOsmPbfStringTable() {
         const stringTable = [];
         for (let i = 0; i < this.length; i++) {
@@ -97,5 +143,38 @@ export default class StringTable {
         }
         return stringTable;
     }
+    /**
+     * Lazily build the reverse index (string → index).
+     * Decodes all strings once to populate the lookup map.
+     */
+    ensureReverseIndex() {
+        if (this.reverseIndexBuilt)
+            return;
+        // Decode all strings and populate the forward lookup map
+        for (let i = 0; i < this.length; i++) {
+            this.stringToIndex.set(this.get(i), i);
+        }
+        this.reverseIndexBuilt = true;
+    }
+    /**
+     * Find the index of a string.
+     */
+    find(str) {
+        const existing = this.stringToIndex.get(str);
+        if (existing !== undefined)
+            return existing;
+        this.ensureReverseIndex();
+        return this.stringToIndex.get(str) ?? -1;
+    }
+    /**
+     * Update a ContentHasher with the string table's data.
+     * Hashes the bytes, start offsets, and counts.
+     */
+    updateHash(hasher) {
+        return hasher
+            .update(this.bytes.array)
+            .update(this.start.array)
+            .update(this.count.array);
+    }
 }
 //# sourceMappingURL=stringtable.js.map

package/dist/src/stringtable.js.map

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

package/dist/src/tags.d.ts

@@ -1,33 +1,132 @@
-import type { OsmTags } from "@osmix/json";
-import type StringTable from "./stringtable";
+/**
+ * Tag storage and lookup.
+ *
+ * Stores key=value pairs using string table indices. Supports:
+ * 1. **Entity → Tags**: Retrieve tags for a given entity.
+ * 2. **Key → Entities**: Find entities with a specific tag key.
+ *
+ * @module
+ */
+import type { OsmTags } from "@osmix/shared/types";
+import StringTable from "./stringtable";
 import { type BufferType } from "./typed-arrays";
-export interface TagsTransferables {
-    tagStart: BufferType;
-    tagCount: BufferType;
-    tagKeys: BufferType;
-    tagVals: BufferType;
+import type { ContentHasher } from "./utils";
+/**
+ * Serializable state for worker transfer.
+ */
+export interface TagsTransferables<T extends BufferType = BufferType> {
+    /** Maps entity index → start position in tagKeys/tagVals. */
+    tagStart: T;
+    /** Maps entity index → number of tags. */
+    tagCount: T;
+    /** Flattened tag key indices. */
+    tagKeys: T;
+    /** Flattened tag value indices. */
+    tagVals: T;
+    /** Flattened entity indices for reverse key lookup. */
+    keyEntities: T;
+    /** Maps key index → start position in keyEntities. */
+    keyIndexStart: T;
+    /** Maps key index → count of entities with that key. */
+    keyIndexCount: T;
 }
+/**
+ * Bidirectional tag storage.
+ *
+ * Limits: Max 255 tags per entity.
+ * Note: String indices reference a shared `StringTable`.
+ */
 export declare class Tags {
+    /** Reference to the shared string table for key/value storage */
     private stringTable;
+    /** Maps entity index → start position in tagKeys/tagVals */
     private tagStart;
+    /** Maps entity index → number of tags (max 255) */
     private tagCount;
+    /** All tag key string indices, concatenated */
     private tagKeys;
+    /** All tag value string indices, concatenated (parallel to tagKeys) */
     private tagVals;
+    /**
+     * Flattened array of entity indices that have each tag key.
+     * Indexed via keyIndexStart and keyIndexCount.
+     */
+    private keyEntities;
+    /** Maps key string index → start position in keyEntities */
+    private keyIndexStart;
+    /** Maps key string index → count of entities with that key */
+    private keyIndexCount;
+    /**
+     * Temporary map used during ingestion to collect entity indices per key.
+     * Converted to flat arrays during buildIndex() and then cleared.
+     */
+    private keyEntityIndexBuilder;
+    /** Whether buildIndex() has been called */
     private indexBuilt;
-    static from(stringTable: StringTable, { tagStart, tagCount, tagKeys, tagVals }: TagsTransferables): Tags;
-    constructor(stringTable: StringTable);
-    transferables(): {
-        tagStart: ArrayBufferLike;
-        tagCount: ArrayBufferLike;
-        tagKeys: ArrayBufferLike;
-        tagVals: ArrayBufferLike;
-    };
-    addTags(tags?: OsmTags): void;
-    addTagKeysAndValues(keys: number[], values: number[]): void;
+    /**
+     * Create a new Tags index.
+     */
+    constructor(stringTable: StringTable, transferables?: TagsTransferables);
+    /**
+     * Add tags to an entity.
+     */
+    addTags(index: number, tags?: OsmTags): [number[], number[]];
+    /**
+     * Add tags to an entity using key and value indexes.
+     */
+    addTagKeysAndValues(index: number, keys: number[], values: number[]): void;
+    /**
+     * Finalize the tag index.
+     *
+     * Compacts arrays and builds the reverse key→entity index.
+     * Must be called before `hasKey()`.
+     */
     buildIndex(): void;
-    get isReady(): boolean;
+    /**
+     * Check if the index is built and ready for use.
+     */
+    isReady(): boolean;
+    /**
+     * Get the number of tags for an entity.
+     */
     cardinality(index: number): number;
+    /**
+     * Get the tags for an entity.
+     */
     getTags(index: number): OsmTags | undefined;
+    /**
+     * Get tags from key and value indexes.
+     */
     getTagsFromIndices(keys: number[], values: number[]): OsmTags;
+    /**
+     * Find the index of a tag key.
+     */
+    find(key: string): number;
+    /**
+     * Get all entity indexes that have a specific tag key.
+     */
+    hasKey(keyIndex: number): number[];
+    /**
+     * Create a unique composite index for a key=value pair.
+     * Uses row-major indexing: `key * width + val`.
+     */
+    kvToIndex(key: number, val: number): number;
+    /**
+     * Get transferable objects for passing to another thread.
+     */
+    transferables(): TagsTransferables;
+    /**
+     * Get the approximate memory requirements for a given number of tags in bytes.
+     */
+    static getBytesRequired(count: number): number;
+    /**
+     * Reconstruct a Tags index from transferable objects.
+     */
+    static fromTransferables(stringTable: StringTable, transferables: TagsTransferables): Tags;
+    /**
+     * Update a ContentHasher with the tags data.
+     * Hashes tag keys and values for each entity.
+     */
+    updateHash(hasher: ContentHasher): ContentHasher;
 }
 //# sourceMappingURL=tags.d.ts.map

package/dist/src/tags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../src/tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,WAAW,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,gBAAgB,CAAA;AAEtE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,UAAU,CAAA;IACpB,QAAQ,EAAE,UAAU,CAAA;IACpB,OAAO,EAAE,UAAU,CAAA;IACnB,OAAO,EAAE,UAAU,CAAA;CACnB;AAED,qBAAa,IAAI;IAChB,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,OAAO,CAAmC;IAElD,OAAO,CAAC,UAAU,CAAQ;IAE1B,MAAM,CAAC,IAAI,CACV,WAAW,EAAE,WAAW,EACxB,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,iBAAiB;gBAWhD,WAAW,EAAE,WAAW;IAQpC,aAAa;;;;;;IASb,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO;IActB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;IAOpD,UAAU;IAQV,IAAI,OAAO,YAEV;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIlC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAuB3C,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;CAW7D"}
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,WAAW,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,KAAK,UAAU,EAA+B,MAAM,gBAAgB,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IACnE,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,CAAA;IACX,0CAA0C;IAC1C,QAAQ,EAAE,CAAC,CAAA;IACX,iCAAiC;IACjC,OAAO,EAAE,CAAC,CAAA;IACV,mCAAmC;IACnC,OAAO,EAAE,CAAC,CAAA;IAEV,uDAAuD;IACvD,WAAW,EAAE,CAAC,CAAA;IACd,sDAAsD;IACtD,aAAa,EAAE,CAAC,CAAA;IAChB,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAA;CAChB;AAED;;;;;GAKG;AACH,qBAAa,IAAI;IAChB,iEAAiE;IACjE,OAAO,CAAC,WAAW,CAAiC;IAGpD,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAkB;IAClC,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAiB;IACjC,+CAA+C;IAC/C,OAAO,CAAC,OAAO,CAAkB;IACjC,uEAAuE;IACvE,OAAO,CAAC,OAAO,CAAkB;IAGjC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAkB;IAErC,4DAA4D;IAC5D,OAAO,CAAC,aAAa,CAAkB;IACvC,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAAkB;IAEvC;;;OAGG;IACH,OAAO,CAAC,qBAAqB,CAA8B;IAE3D,2CAA2C;IAC3C,OAAO,CAAC,UAAU,CAAQ;IAE1B;;OAEG;gBACS,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,iBAAiB;IAsBvE;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC;IAgB5D;;OAEG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;IAgBnE;;;;;OAKG;IACH,UAAU;IAoBV;;OAEG;IACH,OAAO;IAIP;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIlC;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAuB3C;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;IAY7D;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIzB;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAOlC;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAKlC;;OAEG;IACH,aAAa,IAAI,iBAAiB;IAYlC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM;IAOrC;;OAEG;IACH,MAAM,CAAC,iBAAiB,CACvB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,iBAAiB;IAOjC;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAOhD"}