@skmtc/core 0.0.984 → 0.16.1

package/esm/dsl/model/toModelProjectionBase.d.ts

@@ -0,0 +1,125 @@
+import type { GenerateContextType } from '../../context/generateTypes.js';
+import type { InsertModelOptions, InsertNormalizedModelArgs, InsertNormalizedModelReturn } from '../../context/generateTypes.js';
+import type { RefName } from '../../types/RefName.js';
+import type { ContentSettings } from '../ContentSettings.js';
+import type { Lang, LangSnippetConstructor } from '../Lang.js';
+import type { IdentifierType } from '../IdentifierType.js';
+import type { GeneratedValue } from '../GeneratedValue.js';
+import type { Inserted } from '../Inserted.js';
+import type { OasSchema } from '../../oas/schema/Schema.js';
+import type { OasRef } from '../../oas/ref/Ref.js';
+import type { OasVoid } from '../../oas/void/Void.js';
+import type { ModelProjection, ToModelIdentifierNameArgs, ToModelExportPathArgs } from './types.js';
+import * as v from 'valibot';
+/**
+ * Arguments accepted by classes generated via {@link toModelProjectionBase}.
+ *
+ * The factory injects `generatorKey` before delegating to the language
+ * snippet base, so user code only supplies these three fields.
+ */
+export type ModelProjectionArgs<EnrichmentType = undefined> = {
+    context: GenerateContextType;
+    settings: ContentSettings<EnrichmentType>;
+    refName: RefName;
+};
+type ToEnrichmentsArgs = {
+    refName: RefName;
+    context: GenerateContextType;
+    /** Model variant whose enrichment should be resolved (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * Configuration for {@link toModelProjectionBase}.
+ *
+ * Generic over the language `L`: a language veneer parameterizes this config
+ * (`ModelProjectionBaseConfig<E, KtLang>`) so `toIdentifierType`'s return
+ * tightens to that language's `IdentifierType<L>` — no recast. A bare
+ * config (`L = Lang`) keeps the loose `kind: string` boundary.
+ */
+export type ModelProjectionBaseConfig<EnrichmentType = undefined, L extends Lang = Lang> = {
+    id: string;
+    /** Pure: the cache-key name (the cache-check path runs this). */
+    toIdentifierName: (args: ToModelIdentifierNameArgs<EnrichmentType>) => string;
+    /**
+     * Context-aware, overridable: the non-`name` parts of the identifier
+     * (`kind` / `typeName` / `exported`), derived from the schema. Runs only
+     * on cache-miss. Returns this language's `IdentifierType<L>` — the `kind`
+     * is bound to `L`'s `EntityKind` vocabulary (the loose `string` when
+     * `L = Lang`). The tightening rides the type argument, replacing the old
+     * veneer recast.
+     */
+    toIdentifierType: (refName: RefName, context: GenerateContextType) => IdentifierType<L>;
+    toExportPath: (args: ToModelExportPathArgs<EnrichmentType>) => string;
+    /**
+     * Required composite schema for the `{ subject, generator, stack }`
+     * enrichment umbrella. Required (not optional) is load-bearing: it is what
+     * lets `static toEnrichments` parse cast-free. A no-enrichment generator
+     * passes `emptyEnrichmentSchema`.
+     */
+    toEnrichmentSchema: () => v.GenericSchema<EnrichmentType>;
+    /**
+     * Optional: compute the DEFAULT enrichment values for a model from its schema
+     * — the seed the CMS persists and the user then edits (vs {@link toEnrichments},
+     * which READS already-authored values). Returns the `{ subject, generator,
+     * stack }` umbrella; a generator typically fills only `subject` and leaves the
+     * run-constant `generator` / `stack` scopes `undefined`. Omitted → the derived
+     * static returns `undefined`.
+     */
+    toEnrichmentDefaults?: (args: ToEnrichmentsArgs) => EnrichmentType | undefined;
+};
+/**
+ * Build a model projection base class from a per-generator config.
+ *
+ * The returned class extends `base` — the generator's language
+ * snippet base — so the projection hierarchy is language-bound at its root
+ * while core stays language-blind (the base arrives as an opaque
+ * constructor; core never names a concrete language class). The class
+ * exposes the generator's `id`, `toIdentifierName`, `toIdentifierType`,
+ * `toExportPath`, and `toEnrichments` statics, inherits the static `lang`
+ * from the base, and
+ * injects `generatorKey` so subclasses don't have to.
+ *
+ * Defines NO `register` / `registerInto` — register ergonomics are typed by
+ * each language's concise vocabulary, which core can't name, so they live
+ * in the language package's projection-base veneer over this factory.
+ *
+ * The projection machinery previously hosted on `ModelProjectionBase` lives
+ * here now, because the base class is no longer statically known.
+ */
+export declare const toModelProjectionBase: <EnrichmentType = undefined, L extends Lang = Lang>(base: LangSnippetConstructor<L>, config: ModelProjectionBaseConfig<EnrichmentType, L>) => {
+    new (args: ModelProjectionArgs<EnrichmentType>): {
+        settings: ContentSettings<EnrichmentType>;
+        refName: RefName;
+        /**
+         * Insert a related model and return its `Inserted` reference. The
+         * inserted model is exported to this projection's own `exportPath`
+         * unless `noExport` is set.
+         */
+        insertModel<V extends GeneratedValue, PeerEnrichmentType = undefined>(projection: ModelProjection<V, PeerEnrichmentType>, refName: RefName, options?: Pick<InsertModelOptions, "noExport" | "variant">): Inserted<V, PeerEnrichmentType>;
+        /**
+         * Insert a related model with reference normalization. If `schema` is a
+         * `$ref`, the referenced name is used; otherwise `fallbackName` applies.
+         */
+        insertNormalizedModel<V extends GeneratedValue, Schema extends OasSchema | OasRef<"schema"> | OasVoid, PeerEnrichmentType_1 = undefined>(projection: ModelProjection<V, PeerEnrichmentType_1>, { schema, fallbackName }: Omit<InsertNormalizedModelArgs<Schema>, "destinationPath">, options?: Pick<InsertModelOptions, "noExport" | "variant">): InsertNormalizedModelReturn<V, Schema>;
+        context: GenerateContextType;
+        skipped: boolean;
+        generatorKey: import("../GeneratorKeys.js").GeneratorKey | undefined;
+        stackTrail: import("../../mod.js").StackTrail;
+    };
+    id: string;
+    type: "model";
+    toIdentifierName: (args: ToModelIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierType: (refName: RefName, context: GenerateContextType) => IdentifierType<L>;
+    toExportPath: (args: ToModelExportPathArgs<EnrichmentType>) => string;
+    toEnrichments: ({ refName, context, variant }: ToEnrichmentsArgs) => EnrichmentType;
+    /**
+     * Derive the seed enrichment values for a model from its schema (the CMS
+     * persists these, then the user edits). Returns `undefined` when the
+     * generator declares no `toEnrichmentDefaults` — the common case.
+     */
+    toEnrichmentDefaults: (args: ToEnrichmentsArgs) => EnrichmentType | undefined;
+    isSupported: () => boolean;
+    lang: L;
+};
+export {};
+//# sourceMappingURL=toModelProjectionBase.d.ts.map

package/esm/dsl/model/toModelProjectionBase.d.ts.map

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

package/esm/dsl/model/toModelProjectionBase.js

@@ -0,0 +1,146 @@
+import { toModelGeneratorKey } from '../GeneratorKeys.js';
+import * as v from 'valibot';
+import { DEFAULT_VARIANT } from '../../types/Variant.js';
+import { GENERATOR_ENRICHMENT_KEY, STACK_ENRICHMENT_KEY } from '../../types/Enrichments.js';
+import get from 'lodash-es/get.js';
+/**
+ * Build a model projection base class from a per-generator config.
+ *
+ * The returned class extends `base` — the generator's language
+ * snippet base — so the projection hierarchy is language-bound at its root
+ * while core stays language-blind (the base arrives as an opaque
+ * constructor; core never names a concrete language class). The class
+ * exposes the generator's `id`, `toIdentifierName`, `toIdentifierType`,
+ * `toExportPath`, and `toEnrichments` statics, inherits the static `lang`
+ * from the base, and
+ * injects `generatorKey` so subclasses don't have to.
+ *
+ * Defines NO `register` / `registerInto` — register ergonomics are typed by
+ * each language's concise vocabulary, which core can't name, so they live
+ * in the language package's projection-base veneer over this factory.
+ *
+ * The projection machinery previously hosted on `ModelProjectionBase` lives
+ * here now, because the base class is no longer statically known.
+ */
+export const toModelProjectionBase = (base, config) => {
+    var _a;
+    return _a = class extends base {
+            constructor(args) {
+                super({
+                    context: args.context,
+                    generatorKey: toModelGeneratorKey({
+                        generatorId: config.id,
+                        refName: args.refName,
+                        variant: args.settings.variant ?? DEFAULT_VARIANT
+                    })
+                });
+                Object.defineProperty(this, "settings", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
+                Object.defineProperty(this, "refName", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
+                this.refName = args.refName;
+                this.settings = args.settings;
+            }
+            /**
+             * Insert a related model and return its `Inserted` reference. The
+             * inserted model is exported to this projection's own `exportPath`
+             * unless `noExport` is set.
+             */
+            insertModel(projection, refName, options = {}) {
+                return this.context.insertModel(projection, refName, {
+                    destinationPath: this.settings.exportPath,
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+            /**
+             * Insert a related model with reference normalization. If `schema` is a
+             * `$ref`, the referenced name is used; otherwise `fallbackName` applies.
+             */
+            insertNormalizedModel(projection, { schema, fallbackName }, options = {}) {
+                return this.context.insertNormalizedModel(projection, {
+                    schema,
+                    fallbackName,
+                    destinationPath: this.settings.exportPath
+                }, {
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+        },
+        Object.defineProperty(_a, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.id
+        }),
+        Object.defineProperty(_a, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'model'
+        }),
+        Object.defineProperty(_a, "toIdentifierName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toIdentifierName.bind(config)
+        }),
+        Object.defineProperty(_a, "toIdentifierType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toIdentifierType.bind(config)
+        }),
+        Object.defineProperty(_a, "toExportPath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toExportPath.bind(config)
+        }),
+        Object.defineProperty(_a, "toEnrichments", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ({ refName, context, variant }) => {
+                // The three enrichment scopes assembled into the umbrella a generator
+                // reads off `this.settings.enrichments`. Subject is per-item
+                // (`[id][refName][variant]`) — the variant axis is core-owned, and the
+                // engine has already asserted `'main'` exists; generator and stack are
+                // run-constants (`[id][_generator]`, `[_stack]`). The required composite
+                // schema parses the raw umbrella once — typed, cast-free.
+                const raw = {
+                    subject: get(context.settings, ['enrichments', config.id, refName, variant]),
+                    generator: get(context.settings, ['enrichments', config.id, GENERATOR_ENRICHMENT_KEY]),
+                    stack: get(context.settings, ['enrichments', STACK_ENRICHMENT_KEY])
+                };
+                return v.parse(config.toEnrichmentSchema(), raw);
+            }
+        }),
+        /**
+         * Derive the seed enrichment values for a model from its schema (the CMS
+         * persists these, then the user edits). Returns `undefined` when the
+         * generator declares no `toEnrichmentDefaults` — the common case.
+         */
+        Object.defineProperty(_a, "toEnrichmentDefaults", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (args) => config.toEnrichmentDefaults?.call(config, args)
+        }),
+        Object.defineProperty(_a, "isSupported", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => true
+        }),
+        _a;
+};

package/esm/dsl/model/types.d.ts

@@ -1,105 +1,138 @@
 import type { GenerateContextType } from '../../context/generateTypes.js';
+import type { Lang } from '../Lang.js';
 import type { ContentSettings } from '../ContentSettings.js';
 import type { RefName } from '../../types/RefName.js';
-import type { Identifier } from '../Identifier.js';
+import type { IdentifierType } from '../IdentifierType.js';
+import type { IdentifierBase } from '../IdentifierBase.js';
+import type { GeneratedValue } from '../GeneratedValue.js';
 import type { EnrichmentRequest } from '../../types/EnrichmentRequest.js';
 import type * as v from 'valibot';
 import type { MappingModule, PreviewModule } from '../../types/Preview.js';
 import type { SchemaToValueFn } from '../../types/TypeSystem.js';
 /**
- * Constructor arguments for model insertable instances.
+ * External constructor signature for a model projection class.
  *
- * @template EnrichmentType - Optional enrichment data type for additional metadata
+ * The pipeline calls `new SomeProjection(args)` with this shape; the
+ * runtime base class ({@link ModelProjectionBase}) injects `generatorKey`
+ * before calling `super()`.
  */
-export type ModelInsertableConstructorArgs<EnrichmentType = undefined> = {
+export type ModelProjectionConstructorArgs<EnrichmentType = undefined> = {
     context: GenerateContextType;
     refName: RefName;
     settings: ContentSettings<EnrichmentType>;
     destinationPath: string;
     rootRef?: RefName;
 };
-/**
- * Interface for objects that provide model transformation capabilities.
- *
- * Used by generator configurations to transform model definitions
- * during the code generation process.
- */
 export type WithTransformModel = {
     transformModel: (refName: RefName) => void;
 };
-/**
- * Arguments for generating enrichment data for models.
- */
 export type ToModelEnrichmentsArgs = {
     refName: RefName;
     context: GenerateContextType;
+    /** Model variant whose enrichment should be resolved (see {@link Variant}) */
+    variant: string;
 };
-/**
- * Arguments passed to model transformation functions.
- *
- * @template Acc - Accumulator type for collecting transformation results
- */
-export type TransformModelArgs<Acc> = {
+export type TransformModelArgs = {
     context: GenerateContextType;
     refName: RefName;
-    acc: Acc | undefined;
+    /**
+     * The model variant the engine is dispatching for this call. The
+     * engine fans out one `transform` call per variant declared in the
+     * consumer's `enrichments[id][refName]` block (or just `'main'`
+     * when no enrichments are configured). See {@link Variant}.
+     */
+    variant: string;
 };
-/**
- * Arguments for generating model preview modules.
- *
- * Preview modules provide quick insights into generated models
- * without full code generation.
- */
 export type ToModelPreviewModuleArgs = {
     context: GenerateContextType;
     refName: RefName;
+    /** Model variant the preview module describes (see {@link Variant}) */
+    variant: string;
 };
-/**
- * Arguments for generating model mapping information.
- *
- * Mappings track relationships between OAS schemas and generated models,
- * enabling cross-references and dependency analysis.
- */
 export type ToModelMappingArgs = {
     context: GenerateContextType;
     refName: RefName;
+    /** Model variant the mapping module describes (see {@link Variant}) */
+    variant: string;
 };
 /**
- * Configuration object for insertable model generators.
- *
- * Defines the contract for model generator classes that can be inserted
- * into the generation context to produce type-safe model definitions.
+ * Arguments for a model projection's `toIdentifierName` — the pure,
+ * cache-key-source half of the old `toIdentifier`.
+ */
+export type ToModelIdentifierNameArgs<EnrichmentType = undefined> = {
+    refName: RefName;
+    enrichments: EnrichmentType;
+    /** Model variant the identifier should disambiguate (see {@link Variant}) */
+    variant: string;
+};
+export type ToModelExportPathArgs<EnrichmentType = undefined> = {
+    refName: RefName;
+    enrichments: EnrichmentType;
+    /** Model variant the export path should disambiguate (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * Static structural type of a model projection class.
  *
- * @template V - Generated value type produced by the model generator
- * @template EnrichmentType - Optional enrichment data type for additional metadata
+ * Captures both the instance side (`new(...) => V`) and the static side
+ * (`id`, `toIdentifierName`, `toIdentifierType`, `toExportPath`,
+ * `toEnrichments`, `schemaToValueFn`). Passed as a type parameter to
+ * `context.insertModel(...)`.
  */
-export type ModelInsertable<V, EnrichmentType = undefined> = {
+export type ModelProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
     prototype: V;
 } & {
-    new ({ context, refName, settings, destinationPath, rootRef }: ModelInsertableConstructorArgs<EnrichmentType>): V;
+    new ({ context, refName, settings, destinationPath, rootRef }: ModelProjectionConstructorArgs<EnrichmentType>): V;
     id: string;
     type: 'model';
-    toIdentifier: (refName: RefName) => Identifier;
-    toExportPath: (refName: RefName) => string;
-    toEnrichments: ({ refName, context }: ToModelEnrichmentsArgs) => EnrichmentType;
+    /**
+     * The projection's language — the static inherited from the language
+     * snippet base the projection class is built on
+     * (`toModelProjectionBase(TsSnippet, …)`). Drivers read it
+     * pre-construction (cache-hit path). SPIKE (option 2 — see `notes/lang/14`).
+     */
+    lang: Lang;
+    /** Pure: the cache-key name. */
+    toIdentifierName: (args: ToModelIdentifierNameArgs<EnrichmentType>) => string;
+    /**
+     * Context-aware, overridable: the non-`name` parts of the identifier
+     * (`kind` / `typeName` / `exported`), derived from the schema. The engine
+     * assembles `lang.toIdentifier({ name: toIdentifierName(args),
+     * ...toIdentifierType(refName, context) })`.
+     */
+    toIdentifierType: (refName: RefName, context: GenerateContextType) => IdentifierType;
+    toExportPath: (args: ToModelExportPathArgs<EnrichmentType>) => string;
+    toEnrichments: ({ refName, context, variant }: ToModelEnrichmentsArgs) => EnrichmentType;
     schemaToValueFn: SchemaToValueFn;
-    createIdentifier: (name: string) => Identifier;
+    /**
+     * The inline-schema fallback seam used by `insertNormalizedModel` when a
+     * schema is not a `$ref`: builds the Definition's identifier from a bare
+     * `fallbackName`. A generator static; returns the neutral `IdentifierBase`
+     * (the engine reads only `.name`).
+     */
+    createIdentifier: (name: string) => IdentifierBase;
 } & Function;
 /**
- * Configuration object for model generators.
- *
- * Defines the behavior and capabilities of model generators including
- * transformation logic, preview generation, and enrichment handling.
- *
- * @template EnrichmentType - Optional enrichment data type for additional metadata
+ * Pipeline-side configuration for a model projection (built by
+ * `toModelEntry`). Carries the iteration callback (`transform`) and
+ * optional preview/mapping/enrichment hooks.
  */
 export type ModelConfig<EnrichmentType = undefined> = {
     id: string;
     type: 'model';
-    transform: <Acc = void>({ context, refName, acc }: TransformModelArgs<Acc>) => Acc;
-    toPreviewModule?: ({ context, refName }: ToModelPreviewModuleArgs) => PreviewModule;
-    toMappingModule?: ({ context, refName }: ToModelMappingArgs) => MappingModule;
-    toEnrichmentSchema?: () => v.BaseSchema<EnrichmentType, EnrichmentType, v.BaseIssue<unknown>>;
+    transform: ({ context, refName, variant }: TransformModelArgs) => void;
+    toPreviewModule?: ({ context, refName, variant }: ToModelPreviewModuleArgs) => PreviewModule;
+    toMappingModule?: ({ context, refName, variant }: ToModelMappingArgs) => MappingModule;
+    toEnrichmentSchema: () => v.GenericSchema<EnrichmentType>;
     toEnrichmentRequest?: <RequestedEnrichment extends EnrichmentType>(refName: RefName) => EnrichmentRequest<RequestedEnrichment> | undefined;
+    /**
+     * Optional: compute the DEFAULT enrichment values for a model from its schema
+     * — the seed the CMS persists and the user then edits. The pipeline
+     * counterpart of the projection base's static of the same name; a generator
+     * forwards `MyProjection.toEnrichmentDefaults` here so the seeding pass can
+     * reach it via the generator-config map. Returns the `{ subject, generator,
+     * stack }` umbrella, or `undefined` when no defaults are advertised.
+     */
+    toEnrichmentDefaults?: ({ refName, context, variant }: ToModelEnrichmentsArgs) => EnrichmentType | undefined;
 };
 //# sourceMappingURL=types.d.ts.map

package/esm/dsl/model/types.d.ts.map

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

package/esm/dsl/operation/gql/GqlOperationDriver.d.ts

@@ -0,0 +1,52 @@
+import type { GqlOperationProjection } from './types.js';
+import type { GqlOperation } from '../../../gql/operation/GqlOperation.js';
+import type { ContentSettings } from '../../ContentSettings.js';
+import type { GeneratedDefinition } from '../../GeneratedValue.js';
+import type { GeneratedValue } from '../../GeneratedValue.js';
+import type { GenerateContextType } from '../../../context/generateTypes.js';
+type CreateGqlOperationArgs<V extends GeneratedValue, EnrichmentType = undefined> = {
+    context: GenerateContextType;
+    projection: GqlOperationProjection<V, EnrichmentType>;
+    operation: GqlOperation;
+    destinationPath?: string;
+    noExport?: boolean;
+    /**
+     * Target variant of the projection. The Driver resolves the
+     * peer's enrichment for this variant, asserts the variant exists
+     * (or is the default `'main'` which is always permitted), and
+     * threads it into the projection's `ContentSettings`.
+     */
+    variant: string;
+};
+/**
+ * Driver for the GraphQL operation insertion lifecycle.
+ *
+ * GraphQL counterpart to {@link OasOperationDriver}: resolves the
+ * projection's identifier and export path, looks up an existing
+ * `Definition` in the target file, instantiates the projection when no
+ * cache hit exists, registers the new definition, and stitches an import
+ * into `destinationPath` if it differs from the projection's `exportPath`.
+ */
+export declare class GqlOperationDriver<V extends GeneratedValue, EnrichmentType = undefined> {
+    context: GenerateContextType;
+    projection: GqlOperationProjection<V, EnrichmentType>;
+    operation: GqlOperation;
+    settings: ContentSettings<EnrichmentType>;
+    destinationPath?: string;
+    definition: GeneratedDefinition<V>;
+    noExport?: boolean;
+    variant: string;
+    constructor({ context, projection, operation, destinationPath, noExport, variant }: CreateGqlOperationArgs<V, EnrichmentType>);
+    private apply;
+    /**
+     * Ensure the file at `path` exists, creating it on first write through
+     * the projection's language — the static read off the projection class
+     * at the use site, never persisted (works pre-construction on the
+     * cache-hit path). Returns the normalized path.
+     */
+    private ensureFile;
+    private getDefinition;
+    private affirmDefinition;
+}
+export {};
+//# sourceMappingURL=GqlOperationDriver.d.ts.map

package/esm/dsl/operation/gql/GqlOperationDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GqlOperationDriver.d.ts","sourceRoot":"","sources":["../../../../src/dsl/operation/gql/GqlOperationDriver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAI/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAM5E,KAAK,sBAAsB,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,IAAI;IAClF,OAAO,EAAE,mBAAmB,CAAA;IAC5B,UAAU,EAAE,sBAAsB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IACrD,SAAS,EAAE,YAAY,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAWD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS;IAClF,OAAO,EAAE,mBAAmB,CAAA;IAC5B,UAAU,EAAE,sBAAsB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IACrD,SAAS,EAAE,YAAY,CAAA;IACvB,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAA;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;gBAEH,EACV,OAAO,EACP,UAAU,EACV,SAAS,EACT,eAAe,EACf,QAAQ,EACR,OAAO,EACR,EAAE,sBAAsB,CAAC,CAAC,EAAE,cAAc,CAAC;IA0B5C,OAAO,CAAC,KAAK;IAsBb;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,aAAa;IAgCrB,OAAO,CAAC,gBAAgB;CAsBzB"}