@rudra-js/core 0.5.0 → 0.7.0

package/README.md

@@ -6,20 +6,21 @@ component specification.
 ## Install
 
 ```sh
-npm install @rudra-js/core @rudra-js/attested zod@^4
+npm install @rudra-js/core @rudra-js/attested
 ```
 
-Two peer dependencies, for two different reasons.
-
-`zod` is a peer because the public API of this package _is_ zod schemas, so your
-app and the package have to resolve the same copy of zod. **zod 4.5 or later is
-required**, which is what the peer range asks for. The schemas use zod 4 APIs,
-and installing into a zod 3 app fails with `ERESOLVE`, which isn't the most
-helpful error you'll ever read. The floor is 4.5 rather than 4.0 because 4.5
-changed how a nullable field is written into the tool schema we send the model.
-
-`@rudra-js/attested` is a peer for the opposite reason: none of its types cross
-this package's public surface, and you never have to import it. It's a peer so
+`zod` is a dependency, so you don't need it yourself. The public API of this
+package _is_ zod schemas, and an app on any zod 4 shares one copy with it. An
+app on zod 3 gets its own copy alongside ours, and the two don't mix: build on
+the exported schemas with their own methods (`productSchema.array()`) rather
+than your zod's (`z.array(productSchema)`), and read `error.issues` rather than
+checking `instanceof ZodError`. Whichever copy core ends up with writes the tool
+schema we send the model, so its wording shifts a little between releases:
+before 4.5, a nullable field is written as `anyOf` rather than a type array. It
+means the same thing either way.
+
+`@rudra-js/attested` is a peer dependency, even though none of its types cross
+this package's public surface and you never have to import it. It's a peer so
 there is exactly one denylist in your tree. As a real dependency, an app that
 pins its own copy gets two — we checked, and npm 10.9.4 installs the app's
 version at the top and quietly nests ours under `@rudra-js/core` — and the two
@@ -120,10 +121,23 @@ before anything renders. A product you left out doesn't reach the page.
 `bundles` is optional. These are the sets you sell together, each with your own
 price for the set, the currency that price is in, and, if you want one, your own
 name for it. Every product in a set has to be a candidate as well. That's what
-lets the same checks that pass a single product pass a whole set, and what lets
+lets the checks that pass a single product run over a whole set, and what lets
 the renderer look the members up in the catalog it already has. Ids must be
 unique, and one set must not name the same product twice.
 
+A set is placed whole, so one check runs differently: a set may hold something
+the shopper already bought or has in the basket, where a grid or a carousel
+would drop it. A thumbs-down on a member still blocks the whole set, and so does
+a member that is out of stock, already on the page, or the product being looked
+at right now.
+
+That last one has a cost. A "frequently bought together, including this item"
+set names the product whose page it sits on, so it is refused on exactly the
+page you wrote it for. Leave the item out and sell the companions as the set —
+that rejection goes away, and the rest of the checks still apply. And when a
+bundle block is the only block the model asked for, refusing the set leaves
+nothing to render, so the deterministic component takes over.
+
 The model _never_ picks a set and is never told a price. All it does is ask for a
 bundle block and write the words around it. We pick which set when the page is
 served, going on what the shopper has in their basket, has looked at, or is
@@ -244,6 +258,30 @@ everyone looking at it shares them. If you pick candidates per shopper you'll ge
 smaller cohorts. That's the honest outcome, because your prompt really is
 personal.
 
+What goes in the key is the _set_ of candidate SKUs. Not the order you sent them
+in, not which ones were in stock, and not where the 60-product cut fell. So two
+requests carrying the same SKUs in a different order share one component, and the
+one generated first is the one both get. If your ranking is personal, order your
+candidates and the products in the copy won't be the ones you put at the top.
+Prices, titles and stock are always read from your catalog at render time, so
+nothing stale is ever shown — a product that sold out is dropped as the page is
+served, and any sentence written about it stays.
+
+#### Who can create a cohort
+
+Every field above is one you supply, and each distinct value is a cohort of its
+own — a fresh model call, and a slot in the cache. If a visitor can choose one of
+them, a visitor can choose how many calls you pay for. A `locale` copied straight
+out of `Accept-Language`, a `currentCategory` read off a URL slug and a `segment`
+built from a query parameter are the three that go wrong. The shipped cache holds
+10,000 entries and drops the oldest, so enough made-up values also evict the
+cohorts your real shoppers were being served from.
+
+Draw those fields from sets you control: your own locale list, your own category
+ids, your own segment labels. Nothing leaks either way — a cohort prompt carries
+no shopper text at all — the cost is the bill and the model round trip on a page
+that was being served from cache.
+
 Pass `generation: 'per-shopper'` to generate for the individual instead. The
 model then chooses the products too, and every shopper pays for their own call.
 
@@ -311,9 +349,19 @@ const generator = createComponentGenerator({ provider, rank: 'given' });
 
 You keep the rest either way. We still drop anything the shopper shouldn't be
 shown, whether it's out of stock, already bought, in the basket, disliked, or
-the product they're looking at right now. Every product still carries a basis
-we check against their real signals, and everything the model writes is still
-screened.
+the product they're looking at right now — read from the payload you sent, not
+from the shortened history the model was shown, so a shopper with a long order
+book is covered too. Every product still carries a basis we check against their
+real signals, and everything the model writes is still screened.
+
+How much each basis proves is worth knowing, because two of the six prove less
+than they read. `most_viewed` is checked against the SKUs they viewed,
+`similar_to_current` against the category being browsed, `liked_category`
+against the categories they bought, liked, carted or viewed in — standing on a
+category page is not one of those — and `popular` claims nothing.
+`complements_cart` and `complements_purchase` check only that the basket, or the
+order history, isn't empty: nothing here can know that one product goes with
+another. A basis that fails takes the sentence and the badge stating it with it.
 
 Each candidate can carry its own `reason`, the phrase shown under the product.
 Reach for it when your ranking knows something the signals don't:

package/dist/claim-screening.d.ts

@@ -0,0 +1,10 @@
+import type { Product, TrackingInput } from './tracking-input.js';
+export declare const ALLOWED_PHRASES: string[];
+export declare function productFacts(product: Product): string[];
+export interface HostFacts {
+    pooled: string[];
+    bySku: Map<string, string[]>;
+}
+export declare function hostFacts(input: TrackingInput): HostFacts;
+export declare function claimIn(text: string): string | null;
+//# sourceMappingURL=claim-screening.d.ts.map

package/dist/claim-screening.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-screening.d.ts","sourceRoot":"","sources":["../src/claim-screening.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA2IlE,eAAO,MAAM,eAAe,UAAkE,CAAC;AAc/F,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAOvD;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9B;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAWzD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQnD"}

package/dist/claim-screening.js

@@ -0,0 +1,157 @@
+import { offeredCandidates } from './model-prompt.js';
+const CLAIM_PATTERNS = [
+    {
+        kind: 'rating',
+        patterns: [
+            /\breviews?\b|\breviewed\b/,
+            /\b(?:\d+(?:\.\d+)?|three|four|five)[\s-]?stars?\b/,
+            /\bstars?[\s-]?ratings?\b/,
+            /\b(?:customer|shopper|buyer|user|average|overall)[\s-]ratings?\b/,
+            /\bratings?\s+of\s+[0-5]\.\d\b/,
+            /\b[0-5](?:\.\d)?\s+out of\s+(?:5|five)\b/,
+            /\b(?:highly|top|best|well|poorly|five|four)[\s-]rated\b/,
+            /\brated\s+(?:[0-5]\.\d|(?:[0-5]|three|four|five)\s+(?:stars?|out of))\b/,
+            /\bbest[\s-]?sell(?:er|ers|ing)\b/,
+            /(?:\bnumber one|\bno\.? ?1|#\s?1)[\s-]?sell(?:er|ers|ing)\b/,
+            /\bloved by (?:thousands|hundreds|millions|\d)/,
+        ],
+    },
+    {
+        kind: 'price',
+        patterns: [
+            /[$£€¥₹]/,
+            /\b\d+(?:\.\d+)?\s?(?:usd|eur|gbp|dollars?|pounds?|euros?)\b/,
+            /\bdollars?\b|\beuros?\b/,
+            /\b(?:usd|eur|gbp)\s?\d/,
+            /\bkr\s?\d|\d\s?kr\b/,
+            /\bpric(?:e|es|ed|ing)\b/,
+            /\bwas\s+[$£€¥]?\s?\d[\d,.]*\s*[,;–—-]?\s*now\s+[$£€¥]?\s?\d/,
+            /\bcheap(?:er|est)\b/,
+            /\baffordable\b|\bbargain\b/,
+            /\bcosts?\s+(?:less|more|only|just|about|around|[$£€¥]?\d)/,
+            /\blow(?:er)?[\s-]cost\b/,
+            /\bsaves?\s+(?:you\s+)?(?:money|cash|[$£€¥]\s?\d)/,
+        ],
+    },
+    {
+        kind: 'discount',
+        patterns: [
+            /\d+(?:\.\d+)?\s?(?:%|percent)\s*(?:off\b|discount|reduction|less\b)/,
+            /\b(?:save|saving|savings|off|discount|extra|up to)\s+(?:up to\s+)?\d+(?:\.\d+)?\s?(?:%|percent)/,
+            /\bdiscount(?:s|ed)?\b/,
+            /\bsale\b|\bmarked down\b|\bdeal of\b/,
+            /\bhalf[\s-]?(?:price|off)\b/,
+            /\bsaves?\s+\d[\d.,]*\s+off\b/,
+            /\bclearance\s+(?:sale|price|event|deal)\b|\bon clearance\b/,
+            /\bprice reduced\b|\breduced price\b|\breduced by \d+\s?(?:%|percent)|\breduced\s+(?:this|next|last)\s+week\b/,
+        ],
+    },
+    {
+        kind: 'delivery',
+        patterns: [
+            /\bdelivery\b|\bshipping\b/,
+            /\bnext[\s-]day\b|\bsame[\s-]day\b|\bovernight\b/,
+            /\b(?:ships?|arrives?|arriving|delivered|by|before|in time for)\s+(?:on\s+)?(?:today|tomorrow|tonight|this week|next week|the weekend|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/,
+            /\b(?:ships?|arrives?|arriving)\s+(?:in|within)\s+\d/,
+            /\bin time for\b/,
+        ],
+    },
+    {
+        kind: 'stock',
+        patterns: [
+            /\b(?:in|out of|low on) stock\b/,
+            /\blimited stock\b/,
+            /\brestocked?\b|\bsold out\b/,
+            /\b(?:only\s+)?(?:\d+|a few|a handful|a couple|one|few)\s+(?:left|remain(?:s|ing)?)\b/,
+            /\bselling fast\b|\b(?:almost|nearly) gone\b|\bwhile stocks last\b/,
+        ],
+    },
+];
+const CONFUSABLES = {
+    а: 'a',
+    в: 'b',
+    е: 'e',
+    к: 'k',
+    м: 'm',
+    н: 'h',
+    о: 'o',
+    р: 'p',
+    с: 'c',
+    т: 't',
+    х: 'x',
+    у: 'y',
+    ѕ: 's',
+    і: 'i',
+    ј: 'j',
+    ԁ: 'd',
+    һ: 'h',
+    ӏ: 'l',
+    α: 'a',
+    ε: 'e',
+    ι: 'i',
+    κ: 'k',
+    ν: 'v',
+    ο: 'o',
+    ρ: 'p',
+    τ: 't',
+    υ: 'u',
+    χ: 'x',
+    ϲ: 'c',
+};
+const INVISIBLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}\p{Cc}]/gu;
+const SPACING = /[\t\n\v\f\r\u0085]/;
+const MARKS = /[\p{Mn}\p{Me}]/gu;
+function normaliseForClaims(text) {
+    const lowered = text
+        .replace(INVISIBLE, (char) => (SPACING.test(char) ? char : ''))
+        .normalize('NFKC')
+        .toLowerCase()
+        .normalize('NFC')
+        .replace(MARKS, '');
+    let folded = '';
+    for (const char of lowered)
+        folded += CONFUSABLES[char] ?? char;
+    return folded;
+}
+export const ALLOWED_PHRASES = ['does not feel cheap', "doesn't feel cheap", 'last few miles'];
+const DIGIT = /\p{Nd}/u;
+const BARE_EXPONENT = /^[+-]?\d+(?:\.\d+)?[eE]([+-]?\d+)$/;
+const MAX_EXPONENT = 1000;
+function canLayOut(fact) {
+    const match = BARE_EXPONENT.exec(fact.trim());
+    if (match === null)
+        return true;
+    return Math.abs(Number(match[1] ?? '')) <= MAX_EXPONENT;
+}
+export function productFacts(product) {
+    const facts = [];
+    if (DIGIT.test(product.category) && canLayOut(product.category))
+        facts.push(product.category);
+    for (const tag of product.tags) {
+        if (DIGIT.test(tag) && canLayOut(tag))
+            facts.push(tag);
+    }
+    return facts;
+}
+export function hostFacts(input) {
+    const pooled = new Set();
+    const bySku = new Map();
+    for (const product of offeredCandidates(input)) {
+        const own = productFacts(product);
+        bySku.set(product.sku, own);
+        for (const fact of own)
+            pooled.add(fact);
+    }
+    return { pooled: [...pooled], bySku };
+}
+export function claimIn(text) {
+    const normalised = normaliseForClaims(text);
+    for (const claim of CLAIM_PATTERNS) {
+        for (const pattern of claim.patterns) {
+            if (pattern.test(normalised))
+                return claim.kind;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=claim-screening.js.map

package/dist/claim-screening.js.map

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

package/dist/component-generator.d.ts

@@ -3,51 +3,11 @@ import type { ComponentProvider, TokenUsage } from './provider.js';
 import { type RankOrder } from './product-selection.js';
 import { type SpecCache } from './spec-cache.js';
 import { type TrackingInputDraft } from './tracking-input.js';
-/**
- * Turns one tracking payload into one renderable component.
- *
- * Everything else in this package is a piece of that sentence; this module is
- * the order they go in. It is deliberately the only place that knows the whole
- * sequence, and it is written as a straight line so the sequence is readable:
- *
- *   validate → digest → cache → generate → reconcile → render
- *
- * The single promise it makes to a caller is that `generate` always returns
- * something renderable. A model that is slow, refusing, erroring, rate-limited
- * or simply not configured produces the deterministic component instead. The
- * only way it rejects is a malformed payload, which is a caller bug and should
- * be loud.
- */
-/**
- * Reported exactly once per call to `generate`, whatever happened.
- *
- * One flat shape rather than a variant per outcome, because the numbers the
- * evaluation needs are ratios over all calls — hit rate, fallback share, model
- * calls and cost per thousand views. A variant that some callers do not emit
- * makes every one of those ratios wrong by however many it skipped, which is
- * what happened when requests that joined an in-flight generation reported
- * nothing at all.
- */
 export interface GenerationEvent {
-    /** Null when no key was computed, which means no provider was configured. */
     key: string | null;
     source: SpecSource;
-    /** Wall-clock milliseconds for the whole call. */
     elapsedMs: number;
-    /**
-     * True for the caller that sent the request, on every outcome — including a
-     * call that timed out, errored or came back unparseable. Requests that joined
-     * an in-flight generation share its answer and its usage figures, so cost
-     * must be summed over this flag rather than over every event.
-     *
-     * It counts requests sent, which is an upper bound on requests billed: an
-     * adapter that throws before it reaches the vendor looks the same from here
-     * as one that throws after. An upper bound is the useful direction — the
-     * calls that produce nothing are the ones worth seeing, and reporting them as
-     * no call at all hides them completely.
-     */
     calledModel: boolean;
-    /** What reconciliation removed. Absent when no spec was reconciled. */
     violations?: string[];
     usage?: TokenUsage;
     degradedReason?: DegradedReason;
@@ -55,46 +15,16 @@ export interface GenerationEvent {
     cache?: 'hit' | 'miss' | 'error' | 'timeout';
 }
 export interface ComponentGeneratorOptions {
-    /**
-     * Omit to run without a model. That is a supported configuration rather than
-     * a stub: it is the control arm of the benchmark, and the right setting for
-     * anyone who has not yet decided on a provider.
-     */
     provider?: ComponentProvider | null;
-    /** Defaults to an in-process cache. Pass `createNullSpecCache()` to disable. */
     cache?: SpecCache;
-    /**
-     * How long the model gets. Past this the deterministic component renders and
-     * the request is aborted. Defaults to 1500ms.
-     */
     modelTimeoutMs?: number;
-    /**
-     * How long the cache gets. The shipped caches cannot exceed it, but the store
-     * is a port a host implements — a hung Redis read on the render path would
-     * hold the page open, which is exactly what this module exists to prevent.
-     */
     cacheTimeoutMs?: number;
-    /**
-     * 'cohort' shares one generated component between shoppers who look alike and
-     * fills in each shopper's own products. 'per-shopper' generates for the
-     * individual, which is what the benchmark compares against. Defaults to
-     * 'cohort'.
-     */
     generation?: 'cohort' | 'per-shopper';
-    /**
-     * How the products are ordered. 'signals' scores each candidate from this
-     * shopper's signals. 'given' keeps the order you sent, for a shop whose own
-     * ranking is better than four weights. Either way the exclusions and the
-     * stock check still apply, and each product still carries a basis
-     * reconciliation can verify. Defaults to 'signals'.
-     */
     rank?: RankOrder;
-    /** Observability. Never allowed to break a render. */
     onEvent?: (event: GenerationEvent) => void;
 }
 export interface ComponentGenerator {
     generate(input: TrackingInputDraft): Promise<ComponentSpec>;
-    /** The deterministic component, without consulting a model or a cache. */
     generateDeterministic(input: TrackingInputDraft): ComponentSpec;
 }
 export declare class TimeoutError extends Error {

package/dist/component-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-generator.d.ts","sourceRoot":"","sources":["../src/component-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOnE,OAAO,EAAkB,KAAK,SAAS,EAAoB,MAAM,wBAAwB,CAAC;AAG1F,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACtC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAAC;CACjE;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAG9C;CACF;AAgKD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA8PpB"}
+{"version":3,"file":"component-generator.d.ts","sourceRoot":"","sources":["../src/component-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EAAkB,KAAK,SAAS,EAAoB,MAAM,wBAAwB,CAAC;AAG1F,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IAEnB,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,EAAE,OAAO,CAAC;IAErB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEpC,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,UAAU,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IAEtC,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE5D,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAAC;CACjE;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAG9C;CACF;AAkGD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA2LpB"}