@sharpee/stdlib 0.9.60-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Cornelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @sharpee/stdlib
+
+Standard library for the Sharpee IF Platform - 43 standard IF actions with four-phase pattern (validate/execute/report/blocked).
+
+## Overview
+
+The `@sharpee/stdlib` package provides the core IF functionality:
+- **Parser** - Converts user input to ParsedCommand structures (syntax only)
+- **Validator** - Resolves entities and validates commands against world state
+- **Actions** - Standard IF actions (take, drop, examine, go, etc.)
+- **Language System** - Message keys and formatting
+- **Vocabulary** - Standard English vocabulary for IF
+
+## Architecture
+
+The stdlib implements Sharpee's three-phase command processing:
+
+```
+Input Text
+    ↓
+[Parser] - Grammar analysis only
+    ↓
+ParsedCommand - Structured but unresolved
+    ↓
+[Validator] - Entity resolution & validation
+    ↓
+ValidatedCommand - Ready for execution
+    ↓
+[Actions] - Business logic
+    ↓
+SemanticEvents - What happened
+```
+
+## Parser
+
+The parser performs purely grammatical analysis without world knowledge:
+
+```typescript
+import { BasicParser } from '@sharpee/stdlib/parser';
+
+const parser = new BasicParser();
+parser.registerVocabulary(standardVocabulary);
+
+const result = parser.parse("take the red ball");
+// Returns ParsedCommand with:
+// - action: "TAKE"
+// - directObject: { text: "red ball", candidates: ["ball", "red"] }
+// - pattern: "VERB_OBJ"
+```
+
+## Validator
+
+The validator resolves entities and checks preconditions:
+
+```typescript
+import { CommandValidator } from '@sharpee/stdlib/validation';
+
+const validator = new CommandValidator(world, actionRegistry);
+
+const validated = validator.validate(parsedCommand, {
+  world,
+  player,
+  location: currentRoom,
+  scopeService
+});
+
+// Returns ValidatedCommand with:
+// - Resolved entities
+// - Action handler reference
+// - Validation score
+```
+
+### Entity Resolution Features
+
+- Adjective matching ("red ball" vs "blue ball")
+- Scope checking (visible, reachable, touchable)
+- Pronoun resolution ("it", "them") 
+- Synonym matching
+- Container contents ("ball in box")
+- Recent interaction bonus
+- Ambiguity resolution
+
+## Actions
+
+Standard IF actions are included:
+
+```typescript
+import { 
+  takingAction,
+  droppingAction,
+  examiningAction,
+  goingAction,
+  openingAction 
+} from '@sharpee/stdlib/actions';
+
+// Actions implement the Action interface:
+interface Action {
+  id: string;
+  execute(command: ValidatedCommand, context: ActionContext): SemanticEvent[];
+}
+```
+
+### Available Actions (43 Total)
+
+**Movement**: going, entering, exiting
+**Manipulation**: taking, dropping, putting, inserting, removing, giving, throwing
+**Containers/Doors**: opening, closing, locking, unlocking
+**Examination**: looking, examining, searching, reading
+**Interaction**: talking, showing, attacking
+**Devices**: switching on/off, pushing, pulling, raising, lowering
+**Wearables**: wearing, taking off
+**Consumables**: eating, drinking
+**Senses**: touching, smelling, listening
+**Meta**: inventory, score, help, save, restore, restart, quit, undo, wait, about, sleep
+
+## Language System
+
+Message formatting and resolution:
+
+```typescript
+import { IFMessageResolver } from '@sharpee/stdlib/messages';
+
+const resolver = new IFMessageResolver();
+resolver.registerBundle('en-US', enUSBundle);
+
+// Format messages with parameters
+const message = resolver.resolve('item_taken', {
+  item: 'golden key'
+});
+// "You take the golden key."
+```
+
+## Vocabulary
+
+Standard English vocabulary for IF:
+
+```typescript
+import { standardVocabulary } from '@sharpee/stdlib/vocabulary';
+
+// Includes common IF words:
+// - Verbs: take, drop, examine, go, etc.
+// - Prepositions: in, on, under, with, etc.
+// - Articles: the, a, an
+// - Common nouns and adjectives
+```
+
+## Integration Example
+
+```typescript
+import { 
+  BasicParser,
+  CommandValidator,
+  ActionRegistry,
+  standardActions,
+  standardVocabulary 
+} from '@sharpee/stdlib';
+
+// Set up parser
+const parser = new BasicParser();
+parser.registerVocabulary(standardVocabulary);
+
+// Set up actions
+const actionRegistry = new ActionRegistry();
+standardActions.forEach(action => actionRegistry.register(action));
+
+// Set up validator
+const validator = new CommandValidator(world, actionRegistry);
+
+// Process a command
+const parsed = parser.parse("take brass key");
+if (parsed.success) {
+  const validated = validator.validate(parsed.value, validationContext);
+  if (validated.success) {
+    const events = validated.value.actionHandler.execute(
+      validated.value,
+      actionContext
+    );
+    // Process events...
+  }
+}
+```
+
+## Design Philosophy
+
+The stdlib follows Sharpee's core principles:
+
+1. **Separation of Concerns** - Parser doesn't know about world, validator doesn't execute
+2. **Pure Functions** - Actions return events, don't mutate state
+3. **Extensible** - Easy to add new actions, vocabulary, messages
+4. **Type-Safe** - Full TypeScript support with proper types
+5. **Event-Driven** - All changes happen through semantic events
+
+## Testing
+
+The stdlib package has comprehensive test coverage:
+
+```bash
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+
+# Watch mode
+pnpm test:watch
+
+# View coverage report
+pnpm coverage:view
+
+# Update coverage badge
+pnpm coverage:badge
+```
+
+### Test Structure
+
+```
+tests/
+├── unit/           # Unit tests for individual components
+│   ├── actions/    # Action tests
+│   ├── parser/     # Parser tests
+│   ├── validation/ # Validator tests
+│   └── language/   # Language system tests
+└── integration/    # Integration tests
+```
+
+### Coverage Goals
+
+- Unit tests: >90% coverage
+- Integration tests: >80% coverage
+- All public APIs tested
+- All error paths tested
+- Debug events verified
+
+## License
+
+MIT

package/dist/actions/author/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Author commands for debugging and development
+ */
+export { TraceAction } from './trace';
+//# sourceMappingURL=index.d.ts.map

package/dist/actions/author/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/actions/author/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/actions/author/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Author commands for debugging and development
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceAction = void 0;
+var trace_1 = require("./trace");
+Object.defineProperty(exports, "TraceAction", { enumerable: true, get: function () { return trace_1.TraceAction; } });
+//# sourceMappingURL=index.js.map

package/dist/actions/author/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/actions/author/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iCAAsC;AAA7B,oGAAA,WAAW,OAAA"}

package/dist/actions/author/trace.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Trace Command
+ *
+ * Enables/disables tracing of internal engine events for debugging
+ *
+ * Usage:
+ *   trace - Show current trace status
+ *   trace on - Enable all tracing
+ *   trace off - Disable all tracing
+ *   trace parser on/off - Control parser event tracing
+ *   trace validation on/off - Control validation event tracing
+ *   trace system on/off - Control system event tracing
+ *   trace all on/off - Control all tracing
+ */
+import { ActionContext } from '../enhanced-types';
+import { MetaAction } from '../meta-action';
+import { ValidationResult } from '../enhanced-types';
+import { ISemanticEvent } from '@sharpee/core';
+export declare class TraceAction extends MetaAction {
+    id: string;
+    verbs: string[];
+    constructor();
+    validate(context: ActionContext): ValidationResult;
+    execute(context: ActionContext): ISemanticEvent[];
+}
+//# sourceMappingURL=trace.d.ts.map

package/dist/actions/author/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../../src/actions/author/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,qBAAa,WAAY,SAAQ,UAAU;IACzC,EAAE,SAAkB;IACpB,KAAK,WAAa;;IAOlB,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB;IAuClD,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,EAAE;CA4ElD"}

package/dist/actions/author/trace.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Trace Command
+ *
+ * Enables/disables tracing of internal engine events for debugging
+ *
+ * Usage:
+ *   trace - Show current trace status
+ *   trace on - Enable all tracing
+ *   trace off - Disable all tracing
+ *   trace parser on/off - Control parser event tracing
+ *   trace validation on/off - Control validation event tracing
+ *   trace system on/off - Control system event tracing
+ *   trace all on/off - Control all tracing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceAction = void 0;
+const meta_action_1 = require("../meta-action");
+class TraceAction extends meta_action_1.MetaAction {
+    id = 'author.trace';
+    verbs = ['trace'];
+    constructor() {
+        super();
+        this.ensureRegistered();
+    }
+    validate(context) {
+        const { command } = context;
+        const tokens = command.parsed?.tokens || [];
+        // Must have at least "trace"
+        if (tokens.length === 0)
+            return { valid: false, error: 'no_tokens' };
+        // Check first token is "trace"
+        const verb = tokens[0]?.normalized?.toLowerCase();
+        if (verb !== 'trace')
+            return { valid: false, error: 'not_trace' };
+        // Valid patterns:
+        // "trace" - length 1
+        // "trace on/off" - length 2
+        // "trace [target] on/off" - length 3
+        if (tokens.length === 1) {
+            return { valid: true }; // Just "trace"
+        }
+        if (tokens.length === 2) {
+            const second = tokens[1]?.normalized?.toLowerCase();
+            return (second === 'on' || second === 'off') ? { valid: true } : { valid: false, error: 'invalid_state' };
+        }
+        if (tokens.length === 3) {
+            const target = tokens[1]?.normalized?.toLowerCase();
+            const state = tokens[2]?.normalized?.toLowerCase();
+            const validTargets = ['parser', 'validation', 'system', 'all'];
+            const validStates = ['on', 'off'];
+            return (validTargets.includes(target) && validStates.includes(state)) ?
+                { valid: true } : { valid: false, error: 'invalid_target_or_state' };
+        }
+        return { valid: false, error: 'invalid_pattern' };
+    }
+    execute(context) {
+        const { command, world } = context;
+        const tokens = command.parsed?.tokens || [];
+        const events = [];
+        // Get or create debug capability data
+        let debugData = world.getCapability('debug') || {
+            debugParserEvents: false,
+            debugValidationEvents: false,
+            debugSystemEvents: false
+        };
+        if (tokens.length === 1) {
+            // Just "trace" - show status
+            events.push(context.event('trace.status', {
+                parser: debugData.debugParserEvents || false,
+                validation: debugData.debugValidationEvents || false,
+                system: debugData.debugSystemEvents || false
+            }));
+            return events;
+        }
+        if (tokens.length === 2) {
+            // "trace on/off" - affect all
+            const state = tokens[1]?.normalized?.toLowerCase() === 'on';
+            debugData.debugParserEvents = state;
+            debugData.debugValidationEvents = state;
+            debugData.debugSystemEvents = state;
+            world.updateCapability('debug', debugData);
+            events.push(context.event('trace.changed', {
+                target: 'all',
+                enabled: state
+            }));
+            return events;
+        }
+        if (tokens.length === 3) {
+            // "trace [target] on/off"
+            const target = tokens[1]?.normalized?.toLowerCase();
+            const state = tokens[2]?.normalized?.toLowerCase() === 'on';
+            switch (target) {
+                case 'parser':
+                    debugData.debugParserEvents = state;
+                    break;
+                case 'validation':
+                    debugData.debugValidationEvents = state;
+                    break;
+                case 'system':
+                    debugData.debugSystemEvents = state;
+                    break;
+                case 'all':
+                    debugData.debugParserEvents = state;
+                    debugData.debugValidationEvents = state;
+                    debugData.debugSystemEvents = state;
+                    break;
+                default:
+                    // Shouldn't happen due to validation, but be safe
+                    events.push(context.event('action.error', {
+                        reason: `Unknown trace target: ${target}`
+                    }));
+                    return events;
+            }
+            world.updateCapability('debug', debugData);
+            events.push(context.event('trace.changed', {
+                target,
+                enabled: state
+            }));
+        }
+        return events;
+    }
+}
+exports.TraceAction = TraceAction;
+//# sourceMappingURL=trace.js.map

package/dist/actions/author/trace.js.map

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

package/dist/actions/base/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Base utilities for actions
+ *
+ * Provides snapshot utilities and migration helpers for the
+ * three-phase action pattern (validate, execute, report).
+ */
+export * from './snapshot-utils';
+export * from './migration-shim';
+//# sourceMappingURL=index.d.ts.map

package/dist/actions/base/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/actions/base/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/actions/base/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Base utilities for actions
+ *
+ * Provides snapshot utilities and migration helpers for the
+ * three-phase action pattern (validate, execute, report).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./snapshot-utils"), exports);
+__exportStar(require("./migration-shim"), exports);
+//# sourceMappingURL=index.js.map

package/dist/actions/base/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/actions/base/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;AAEH,mDAAiC;AACjC,mDAAiC"}

package/dist/actions/base/migration-shim.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Migration shim for transitioning actions to the three-phase pattern
+ *
+ * This provides utilities to help migrate existing actions from the
+ * two-phase pattern (validate + execute) to the three-phase pattern
+ * (validate + execute + report).
+ */
+import { ISemanticEvent } from '@sharpee/core';
+import { Action, ActionContext, ValidationResult } from '../enhanced-types';
+/**
+ * Base class for migrating actions to three-phase pattern
+ *
+ * Subclasses can override executeWithMutation() and generateReport()
+ * to implement the new pattern while maintaining compatibility.
+ */
+export declare abstract class ThreePhaseAction implements Action {
+    abstract id: string;
+    requiredMessages?: string[];
+    descriptionMessageId?: string;
+    examplesMessageId?: string;
+    group?: string;
+    priority?: number;
+    /**
+     * Validate phase - check if action can proceed
+     */
+    abstract validate(context: ActionContext): ValidationResult;
+    /**
+     * Execute phase - handles both old and new patterns
+     *
+     * This method checks if the subclass has implemented the new pattern.
+     * If so, it calls executeWithMutation() and returns void.
+     * Otherwise, it falls back to the old pattern.
+     */
+    execute(context: ActionContext): ISemanticEvent[] | void;
+    /**
+     * Report phase - generate events after mutations
+     *
+     * This is automatically used when executeWithMutation is implemented.
+     */
+    report(context: ActionContext): ISemanticEvent[];
+    /**
+     * New pattern: perform mutations only (optional override)
+     *
+     * Subclasses implementing the three-phase pattern should override this.
+     */
+    protected executeWithMutation?(context: ActionContext): void;
+    /**
+     * New pattern: generate events with captured state (optional override)
+     *
+     * Subclasses implementing the three-phase pattern should override this.
+     */
+    protected generateReport?(context: ActionContext): ISemanticEvent[];
+}
+/**
+ * Helper to create a three-phase action from functions
+ *
+ * This is useful for quickly converting existing actions without
+ * creating a full class.
+ */
+export declare function createThreePhaseAction(config: {
+    id: string;
+    validate: (context: ActionContext) => ValidationResult;
+    execute: (context: ActionContext) => void;
+    report: (context: ActionContext) => ISemanticEvent[];
+    requiredMessages?: string[];
+    descriptionMessageId?: string;
+    examplesMessageId?: string;
+    group?: string;
+    priority?: number;
+}): Action;
+/**
+ * Adapter to wrap old-style actions in the new interface
+ *
+ * This allows old actions to work with the new CommandExecutor
+ * without modification.
+ */
+export declare function adaptOldAction(oldAction: {
+    id: string;
+    validate: (context: ActionContext) => ValidationResult;
+    execute: (context: ActionContext) => ISemanticEvent[];
+    requiredMessages?: string[];
+    descriptionMessageId?: string;
+    examplesMessageId?: string;
+    group?: string;
+    priority?: number;
+}): Action;
+/**
+ * Helper to split an old execute method into execute + report
+ *
+ * This helps when migrating actions that mix mutations and event generation.
+ *
+ * @param executeOld The old execute method that does both
+ * @returns Object with separate execute and report methods
+ */
+export declare function splitExecuteMethod(executeOld: (context: ActionContext) => ISemanticEvent[]): {
+    execute: (context: ActionContext) => void;
+    report: (context: ActionContext) => ISemanticEvent[];
+};
+/**
+ * Create a migration wrapper that logs when old patterns are used
+ *
+ * This helps identify which actions still need migration.
+ */
+export declare function createMigrationLogger(action: Action, logger?: (message: string) => void): Action;
+//# sourceMappingURL=migration-shim.d.ts.map

package/dist/actions/base/migration-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-shim.d.ts","sourceRoot":"","sources":["../../../src/actions/base/migration-shim.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;;;GAKG;AACH,8BAAsB,gBAAiB,YAAW,MAAM;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB;IAE3D;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,EAAE,GAAG,IAAI;IAexD;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,EAAE;IAShD;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAE5D;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,EAAE;CACpE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,gBAAgB,CAAC;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,EAAE,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAkBT;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,gBAAgB,CAAC;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,EAAE,CAAC;IACtD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAOT;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,EAAE,GACvD;IACD,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,EAAE,CAAC;CACtD,CAqBA;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAmB,GAC/C,MAAM,CAsBR"}