@sharpee/if-domain 0.9.60-beta

package/dist/grammar/grammar-builder.d.ts

@@ -0,0 +1,507 @@
+/**
+ * @file Grammar Builder Interfaces
+ * @description Language-agnostic interfaces for defining grammar rules
+ */
+import { IEntity } from '@sharpee/core';
+/**
+ * Slot types for grammar patterns
+ * Controls how the parser handles slot matching
+ */
+export declare enum SlotType {
+    /** Default: resolve slot text to an entity via vocabulary lookup */
+    ENTITY = "entity",
+    /** Capture raw text without entity resolution (single token) */
+    TEXT = "text",
+    /** Capture raw text until next pattern element or end (greedy) */
+    TEXT_GREEDY = "text_greedy",
+    /** Resolve entity but mark as instrument for the action */
+    INSTRUMENT = "instrument",
+    /** Match cardinal/ordinal direction (n, s, e, w, ne, up, down, etc.) */
+    DIRECTION = "direction",
+    /** Match integer (digits or words: 1, 29, one, twenty) */
+    NUMBER = "number",
+    /** Match ordinal (1st, first, 2nd, second, etc.) */
+    ORDINAL = "ordinal",
+    /** Match time expression (10:40, 6:00) */
+    TIME = "time",
+    /** Match manner adverb (carefully, quickly, forcefully) - feeds intention.manner */
+    MANNER = "manner",
+    /** Match text enclosed in double quotes */
+    QUOTED_TEXT = "quoted_text",
+    /** Match conversation topic (one or more words) */
+    TOPIC = "topic",
+    /** Match word from a story-defined vocabulary category */
+    VOCABULARY = "vocabulary",
+    /** @deprecated Use VOCABULARY with .fromVocabulary() instead */
+    ADJECTIVE = "adjective",
+    /** @deprecated Use VOCABULARY with .fromVocabulary() instead */
+    NOUN = "noun"
+}
+/**
+ * Constraint types for slot matching
+ */
+export type PropertyConstraint = Record<string, any>;
+export type FunctionConstraint = (entity: IEntity, context: GrammarContext) => boolean;
+export type ScopeConstraintBuilder = (scope: ScopeBuilder) => ScopeBuilder;
+export type Constraint = PropertyConstraint | FunctionConstraint | ScopeConstraintBuilder;
+/**
+ * Context provided to constraint functions
+ */
+export interface GrammarContext {
+    world: any;
+    actorId: string;
+    actionId?: string;
+    currentLocation: string;
+    slots: Map<string, IEntity[]>;
+}
+/**
+ * Scope builder for constraint definitions
+ */
+export interface ScopeBuilder {
+    visible(): ScopeBuilder;
+    touchable(): ScopeBuilder;
+    carried(): ScopeBuilder;
+    nearby(): ScopeBuilder;
+    matching(constraint: PropertyConstraint | FunctionConstraint): ScopeBuilder;
+    kind(kind: string): ScopeBuilder;
+    orExplicitly(entityIds: string[]): ScopeBuilder;
+    orRule(ruleId: string): ScopeBuilder;
+    /**
+     * Require the entity to have a specific trait
+     * @param traitType The trait type constant (e.g., TraitType.PORTABLE)
+     */
+    hasTrait(traitType: string): ScopeBuilder;
+    build(): ScopeConstraint;
+}
+/**
+ * Internal scope constraint representation
+ */
+export interface ScopeConstraint {
+    base: 'visible' | 'touchable' | 'carried' | 'nearby' | 'all';
+    filters: Array<PropertyConstraint | FunctionConstraint>;
+    /** Required trait types the entity must have */
+    traitFilters: string[];
+    explicitEntities: string[];
+    includeRules: string[];
+}
+/**
+ * ADR-082: Typed slot value for non-entity slots
+ * Each variant carries the parsed/typed value from the input
+ */
+export type TypedSlotValue = {
+    type: 'direction';
+    direction: string;
+    canonical: string;
+} | {
+    type: 'number';
+    value: number;
+    word: string;
+} | {
+    type: 'ordinal';
+    value: number;
+    word: string;
+} | {
+    type: 'time';
+    hours: number;
+    minutes: number;
+    text: string;
+} | {
+    type: 'manner';
+    word: string;
+} | {
+    type: 'quoted_text';
+    text: string;
+} | {
+    type: 'topic';
+    words: string[];
+} | {
+    type: 'vocabulary';
+    word: string;
+    category: string;
+} | {
+    type: 'adjective';
+    word: string;
+} | {
+    type: 'noun';
+    word: string;
+};
+/**
+ * Pattern builder for defining grammar rules
+ */
+export interface PatternBuilder {
+    /**
+     * Require a slot's entity to have a specific trait
+     * This is the primary method for semantic constraints in grammar.
+     * @param slot The slot name from the pattern
+     * @param traitType The trait type constant (e.g., TraitType.CONTAINER)
+     *
+     * @example
+     * ```typescript
+     * grammar.define('board :target')
+     *   .hasTrait('target', TraitType.ENTERABLE)
+     *   .mapsTo('if.action.entering')
+     *   .build();
+     * ```
+     */
+    hasTrait(slot: string, traitType: string): PatternBuilder;
+    /**
+     * Define a constraint for a slot (advanced use)
+     * Prefer .hasTrait() for trait-based constraints.
+     * @param slot The slot name from the pattern
+     * @param constraint The constraint to apply
+     */
+    where(slot: string, constraint: Constraint): PatternBuilder;
+    /**
+     * Mark a slot as capturing raw text (single token) instead of resolving to entity
+     * For greedy text capture, use :slot... syntax in the pattern
+     * @param slot The slot name from the pattern
+     */
+    text(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as an instrument for the action
+     * The slot will still resolve to an entity, but be stored in command.instrument
+     * @param slot The slot name from the pattern
+     */
+    instrument(slot: string): PatternBuilder;
+    /**
+     * Map this pattern to an action
+     * @param action The action identifier
+     */
+    mapsTo(action: string): PatternBuilder;
+    /**
+     * Set the priority for this pattern (higher = preferred)
+     * @param priority The priority value
+     */
+    withPriority(priority: number): PatternBuilder;
+    /**
+     * Add semantic mappings for verbs
+     * @param verbs Map of verb text to semantic properties
+     */
+    withSemanticVerbs(verbs: Record<string, Partial<SemanticProperties>>): PatternBuilder;
+    /**
+     * Add semantic mappings for prepositions
+     * @param prepositions Map of preposition text to spatial relations
+     */
+    withSemanticPrepositions(prepositions: Record<string, string>): PatternBuilder;
+    /**
+     * Add semantic mappings for directions
+     * @param directions Map of direction text to normalized directions
+     */
+    withSemanticDirections(directions: Record<string, string>): PatternBuilder;
+    /**
+     * Set default semantic properties
+     * @param defaults Default semantic properties
+     */
+    withDefaultSemantics(defaults: Partial<SemanticProperties>): PatternBuilder;
+    /**
+     * Mark a slot as a number (integer)
+     * Matches digits (1, 29, 100) or words (one, twenty)
+     * @param slot The slot name from the pattern
+     */
+    number(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as an ordinal
+     * Matches ordinal words (first, second) or suffixed numbers (1st, 2nd)
+     * @param slot The slot name from the pattern
+     */
+    ordinal(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as a time expression
+     * Matches HH:MM format (10:40, 6:00)
+     * @param slot The slot name from the pattern
+     */
+    time(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as a direction
+     * Matches built-in direction vocabulary (n, north, up, etc.)
+     * @param slot The slot name from the pattern
+     */
+    direction(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as a manner adverb
+     * Matches built-in manner vocabulary (carefully, quickly, forcefully, etc.)
+     * The matched word is stored in command.intention.manner
+     * @param slot The slot name from the pattern
+     */
+    manner(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as matching a story-defined vocabulary category
+     * The category must be registered via world.getVocabularyProvider().define()
+     *
+     * @param slot The slot name from the pattern
+     * @param category The vocabulary category name
+     *
+     * @example
+     * ```typescript
+     * // Register vocabulary
+     * vocab.define('panel-colors', {
+     *   words: ['red', 'yellow', 'mahogany', 'pine'],
+     *   when: (ctx) => ctx.currentLocation === insideMirrorId
+     * });
+     *
+     * // Use in grammar
+     * grammar
+     *   .define('push :color panel')
+     *   .fromVocabulary('color', 'panel-colors')
+     *   .mapsTo('push_panel')
+     *   .build();
+     * ```
+     */
+    fromVocabulary(slot: string, category: string): PatternBuilder;
+    /**
+     * @deprecated Use fromVocabulary() with a named category instead
+     * Mark a slot as an adjective from story vocabulary
+     */
+    adjective(slot: string): PatternBuilder;
+    /**
+     * @deprecated Use fromVocabulary() with a named category instead
+     * Mark a slot as a noun from story vocabulary
+     */
+    noun(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as quoted text
+     * Matches text enclosed in double quotes
+     * @param slot The slot name from the pattern
+     */
+    quotedText(slot: string): PatternBuilder;
+    /**
+     * Mark a slot as a conversation topic
+     * Consumes one or more words as a topic
+     * @param slot The slot name from the pattern
+     */
+    topic(slot: string): PatternBuilder;
+    /**
+     * Build the final grammar rule
+     */
+    build(): GrammarRule;
+}
+/**
+ * Main grammar builder interface
+ */
+export interface GrammarBuilder {
+    /**
+     * Define a new grammar pattern
+     * @param pattern The pattern string (e.g., "put :item in|into :container")
+     */
+    define(pattern: string): PatternBuilder;
+    /**
+     * ADR-087: Define grammar patterns for an action with verb aliases
+     * @param actionId The action identifier to map patterns to
+     * @returns An ActionGrammarBuilder for fluent configuration
+     *
+     * @example
+     * ```typescript
+     * grammar
+     *   .forAction('if.action.pushing')
+     *   .verbs(['push', 'press', 'shove', 'move'])
+     *   .pattern(':target')
+     *   .where('target', scope => scope.touchable())
+     *   .build();
+     * ```
+     */
+    forAction(actionId: string): ActionGrammarBuilder;
+    /**
+     * Get all defined rules
+     */
+    getRules(): GrammarRule[];
+    /**
+     * Clear all rules
+     */
+    clear(): void;
+}
+/**
+ * ADR-087: Action-centric grammar builder
+ * Allows defining multiple patterns for an action with verb aliases
+ */
+export interface ActionGrammarBuilder {
+    /**
+     * Define verb aliases for this action
+     * Each verb will generate a separate pattern
+     * @param verbs Array of verb strings (e.g., ['push', 'press', 'shove'])
+     */
+    verbs(verbs: string[]): ActionGrammarBuilder;
+    /**
+     * Define a pattern template (without verb)
+     * Will be combined with each verb to create full patterns
+     * @param pattern Pattern template (e.g., ':target' becomes 'push :target', 'press :target', etc.)
+     */
+    pattern(pattern: string): ActionGrammarBuilder;
+    /**
+     * Define multiple pattern templates
+     * Each pattern will be combined with each verb
+     * @param patterns Array of pattern templates
+     *
+     * @example
+     * ```typescript
+     * grammar
+     *   .forAction('if.action.pushing')
+     *   .verbs(['push', 'press'])
+     *   .patterns([':target', ':target :direction'])
+     *   .build();
+     * // Generates: push :target, press :target, push :target :direction, press :target :direction
+     * ```
+     */
+    patterns(patterns: string[]): ActionGrammarBuilder;
+    /**
+     * Define direction patterns with aliases
+     * Creates standalone direction patterns (no verb prefix)
+     * @param directionMap Map of canonical direction to aliases
+     *
+     * @example
+     * ```typescript
+     * grammar
+     *   .forAction('if.action.going')
+     *   .directions({
+     *     'north': ['north', 'n'],
+     *     'south': ['south', 's'],
+     *   })
+     *   .build();
+     * // Generates patterns 'north', 'n', 'south', 's' each with direction semantics
+     * ```
+     */
+    directions(directionMap: Record<string, string[]>): ActionGrammarBuilder;
+    /**
+     * Require a slot's entity to have a specific trait (applies to all generated patterns)
+     * This is the primary method for semantic constraints in grammar.
+     * @param slot The slot name from the pattern
+     * @param traitType The trait type constant (e.g., TraitType.CONTAINER)
+     */
+    hasTrait(slot: string, traitType: string): ActionGrammarBuilder;
+    /**
+     * Define a constraint for a slot (applies to all generated patterns)
+     * Prefer .hasTrait() for trait-based constraints.
+     * @param slot The slot name from the pattern
+     * @param constraint The constraint to apply
+     */
+    where(slot: string, constraint: Constraint): ActionGrammarBuilder;
+    /**
+     * Set priority for all generated patterns
+     * @param priority The priority value (higher = preferred)
+     */
+    withPriority(priority: number): ActionGrammarBuilder;
+    /**
+     * Set default semantic properties for all generated patterns
+     * @param defaults Default semantic properties
+     */
+    withDefaultSemantics(defaults: Partial<SemanticProperties>): ActionGrammarBuilder;
+    /**
+     * Mark a slot as a specific type (applies to all generated patterns)
+     * @param slot The slot name
+     * @param slotType The slot type
+     */
+    slotType(slot: string, slotType: SlotType): ActionGrammarBuilder;
+    /**
+     * Build all patterns and add them to the grammar
+     * Generates patterns from: verbs × patterns combinations
+     */
+    build(): void;
+}
+/**
+ * A compiled grammar rule
+ */
+export interface GrammarRule {
+    id: string;
+    pattern: string;
+    compiledPattern?: CompiledPattern;
+    slots: Map<string, SlotConstraint>;
+    action: string;
+    priority: number;
+    semantics?: SemanticMapping;
+    defaultSemantics?: Partial<SemanticProperties>;
+}
+/**
+ * Semantic properties that can be derived from grammar
+ */
+export interface SemanticProperties {
+    /** How an action is performed */
+    manner?: 'normal' | 'careful' | 'careless' | 'forceful' | 'stealthy' | 'quick';
+    /** Spatial relationship for placement actions */
+    spatialRelation?: 'in' | 'on' | 'under' | 'behind' | 'beside' | 'above' | 'below';
+    /** Direction for movement */
+    direction?: 'north' | 'south' | 'east' | 'west' | 'up' | 'down' | 'northeast' | 'northwest' | 'southeast' | 'southwest' | 'in' | 'out';
+    /** Whether the preposition was implicit */
+    implicitPreposition?: boolean;
+    /** Whether a direction was implicit */
+    implicitDirection?: boolean;
+    /** Custom properties for specific actions */
+    [key: string]: any;
+}
+/**
+ * Mapping from text variations to semantic properties
+ */
+export interface SemanticMapping {
+    /** Map verb variations to properties */
+    verbs?: Record<string, Partial<SemanticProperties>>;
+    /** Map preposition variations to spatial relations */
+    prepositions?: Record<string, string>;
+    /** Map direction variations to normalized directions */
+    directions?: Record<string, string>;
+    /** Function to compute dynamic semantics based on match */
+    compute?: (match: any) => Partial<SemanticProperties>;
+}
+/**
+ * Slot constraint definition
+ */
+export interface SlotConstraint {
+    name: string;
+    constraints: Constraint[];
+    /** Required trait types the entity must have (from .hasTrait()) */
+    traitFilters?: string[];
+    /** How the parser should handle this slot (default: ENTITY) */
+    slotType?: SlotType;
+    /** For VOCABULARY slots: the category name to match against */
+    vocabularyCategory?: string;
+}
+/**
+ * Token in a pattern
+ */
+export interface PatternToken {
+    type: 'literal' | 'slot' | 'alternates';
+    value: string;
+    alternates?: string[];
+    optional?: boolean;
+    slotType?: SlotType;
+    greedy?: boolean;
+    vocabularyCategory?: string;
+}
+/**
+ * Compiled pattern for efficient matching
+ */
+export interface CompiledPattern {
+    tokens: PatternToken[];
+    slots: Map<string, number>;
+    minTokens: number;
+    maxTokens: number;
+}
+/**
+ * Slot match data with multi-object support
+ */
+export interface SlotMatch {
+    tokens: number[];
+    text: string;
+    slotType?: SlotType;
+    confidence?: number;
+    isAll?: boolean;
+    isList?: boolean;
+    items?: SlotMatch[];
+    excluded?: SlotMatch[];
+    category?: string;
+    matchedWord?: string;
+    manner?: string;
+}
+/**
+ * Result of pattern matching
+ */
+export interface PatternMatch {
+    rule: GrammarRule;
+    confidence: number;
+    slots: Map<string, SlotMatch>;
+    consumed: number;
+    semantics?: SemanticProperties;
+    matchedTokens?: {
+        verb?: string;
+        preposition?: string;
+        direction?: string;
+    };
+}
+//# sourceMappingURL=grammar-builder.d.ts.map

package/dist/grammar/grammar-builder.d.ts.map

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

package/dist/grammar/grammar-builder.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * @file Grammar Builder Interfaces
+ * @description Language-agnostic interfaces for defining grammar rules
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlotType = void 0;
+/**
+ * Slot types for grammar patterns
+ * Controls how the parser handles slot matching
+ */
+var SlotType;
+(function (SlotType) {
+    /** Default: resolve slot text to an entity via vocabulary lookup */
+    SlotType["ENTITY"] = "entity";
+    /** Capture raw text without entity resolution (single token) */
+    SlotType["TEXT"] = "text";
+    /** Capture raw text until next pattern element or end (greedy) */
+    SlotType["TEXT_GREEDY"] = "text_greedy";
+    /** Resolve entity but mark as instrument for the action */
+    SlotType["INSTRUMENT"] = "instrument";
+    // ADR-082: Built-in typed value slots
+    /** Match cardinal/ordinal direction (n, s, e, w, ne, up, down, etc.) */
+    SlotType["DIRECTION"] = "direction";
+    /** Match integer (digits or words: 1, 29, one, twenty) */
+    SlotType["NUMBER"] = "number";
+    /** Match ordinal (1st, first, 2nd, second, etc.) */
+    SlotType["ORDINAL"] = "ordinal";
+    /** Match time expression (10:40, 6:00) */
+    SlotType["TIME"] = "time";
+    /** Match manner adverb (carefully, quickly, forcefully) - feeds intention.manner */
+    SlotType["MANNER"] = "manner";
+    // ADR-082: Text variant slots
+    /** Match text enclosed in double quotes */
+    SlotType["QUOTED_TEXT"] = "quoted_text";
+    /** Match conversation topic (one or more words) */
+    SlotType["TOPIC"] = "topic";
+    // ADR-082: Category-based vocabulary slots
+    /** Match word from a story-defined vocabulary category */
+    SlotType["VOCABULARY"] = "vocabulary";
+    // Deprecated: Use VOCABULARY with named categories instead
+    /** @deprecated Use VOCABULARY with .fromVocabulary() instead */
+    SlotType["ADJECTIVE"] = "adjective";
+    /** @deprecated Use VOCABULARY with .fromVocabulary() instead */
+    SlotType["NOUN"] = "noun";
+})(SlotType || (exports.SlotType = SlotType = {}));
+//# sourceMappingURL=grammar-builder.js.map

package/dist/grammar/grammar-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-builder.js","sourceRoot":"","sources":["../../src/grammar/grammar-builder.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH;;;GAGG;AACH,IAAY,QAqCX;AArCD,WAAY,QAAQ;IAClB,oEAAoE;IACpE,6BAAiB,CAAA;IACjB,gEAAgE;IAChE,yBAAa,CAAA;IACb,kEAAkE;IAClE,uCAA2B,CAAA;IAC3B,2DAA2D;IAC3D,qCAAyB,CAAA;IAEzB,sCAAsC;IACtC,wEAAwE;IACxE,mCAAuB,CAAA;IACvB,0DAA0D;IAC1D,6BAAiB,CAAA;IACjB,oDAAoD;IACpD,+BAAmB,CAAA;IACnB,0CAA0C;IAC1C,yBAAa,CAAA;IACb,oFAAoF;IACpF,6BAAiB,CAAA;IAEjB,8BAA8B;IAC9B,2CAA2C;IAC3C,uCAA2B,CAAA;IAC3B,mDAAmD;IACnD,2BAAe,CAAA;IAEf,2CAA2C;IAC3C,0DAA0D;IAC1D,qCAAyB,CAAA;IAEzB,2DAA2D;IAC3D,gEAAgE;IAChE,mCAAuB,CAAA;IACvB,gEAAgE;IAChE,yBAAa,CAAA;AACf,CAAC,EArCW,QAAQ,wBAAR,QAAQ,QAqCnB"}

package/dist/grammar/grammar-engine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Grammar Engine Base
+ * @description Abstract base class for grammar matching engines
+ */
+import { Token } from '../parser-contracts/parser-types';
+import { GrammarRule, PatternMatch, GrammarContext, GrammarBuilder } from './grammar-builder';
+import { PatternCompiler } from './pattern-compiler';
+/**
+ * Grammar matching options
+ */
+export interface GrammarMatchOptions {
+    /** Minimum confidence threshold */
+    minConfidence?: number;
+    /** Maximum number of matches to return */
+    maxMatches?: number;
+    /** Whether to allow partial matches */
+    allowPartial?: boolean;
+}
+/**
+ * Abstract base class for grammar engines
+ * Language-specific implementations provide concrete matching logic
+ */
+export declare abstract class GrammarEngine {
+    protected rules: GrammarRule[];
+    protected rulesByAction: Map<string, GrammarRule[]>;
+    protected compiler: PatternCompiler;
+    constructor(compiler: PatternCompiler);
+    /**
+     * Add a grammar rule
+     */
+    addRule(rule: GrammarRule): void;
+    /**
+     * Add multiple rules
+     */
+    addRules(rules: GrammarRule[]): void;
+    /**
+     * Find matching grammar rules for tokens
+     */
+    abstract findMatches(tokens: Token[], context: GrammarContext, options?: GrammarMatchOptions): PatternMatch[];
+    /**
+     * Get the best match from a set of tokens
+     */
+    getBestMatch(tokens: Token[], context: GrammarContext, options?: GrammarMatchOptions): PatternMatch | null;
+    /**
+     * Clear all rules
+     */
+    clear(): void;
+    /**
+     * Get all rules
+     */
+    getRules(): GrammarRule[];
+    /**
+     * Get rules for a specific action
+     */
+    getRulesForAction(action: string): GrammarRule[];
+    /**
+     * Sort rules by priority (descending)
+     */
+    protected sortRules(): void;
+    /**
+     * Create a grammar builder connected to this engine
+     */
+    createBuilder(): GrammarBuilder;
+}
+//# sourceMappingURL=grammar-engine.d.ts.map

package/dist/grammar/grammar-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-engine.d.ts","sourceRoot":"","sources":["../../src/grammar/grammar-engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AACzD,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EAEd,cAAc,EAOf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,8BAAsB,aAAa;IACjC,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,CAAM;IACpC,SAAS,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAa;IAChE,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC;gBAExB,QAAQ,EAAE,eAAe;IAIrC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAiBhC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI;IAIpC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAClB,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,EAAE;IAEjB;;OAEG;IACH,YAAY,CACV,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,GAAG,IAAI;IAKtB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,QAAQ,IAAI,WAAW,EAAE;IAIzB;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE;IAIhD;;OAEG;IACH,SAAS,CAAC,SAAS,IAAI,IAAI;IAS3B;;OAEG;IACH,aAAa,IAAI,cAAc;CA+UhC"}