@thymian/plugin-sampler 0.3.0-canary.20261007-e6cb8dc → 0.3.0-canary.20261007-cdbe1d3

package/dist/generation/types/type-names.js

@@ -0,0 +1,213 @@
+/**
+ * Deterministic TypeScript identifiers for the declarations the type surface
+ * emits.
+ *
+ * Every name is a pure function of the transaction's selector plus the schema's
+ * role within that transaction. Naming by catalog position instead
+ * (`Transaction4Type2`) is stable under a document reorder but not under an
+ * *insertion*: a new endpoint that sorts first renumbers every declaration
+ * after it. The surface is committed and the diff against it **is** the
+ * staleness signal, so a positional name turns adding one endpoint into a
+ * whole-file diff — 282 changed lines on the demo description, for one added
+ * operation.
+ *
+ * SANITISATION IS NOT COSMETIC AND THE COLLISION SUFFIX IS NOT DEFENSIVE. A
+ * selector legitimately carries characters no identifier can: a method is an
+ * RFC 9110 section 5.6.2 token, paths carry `/`, `{`, `}` and percent-encoding,
+ * and media types carry `/`, `+`, `;` and `=`. Two distinct selectors therefore
+ * collapse onto one stem — methods `A-B` and `A.B` on the same path both
+ * sanitise to `AB` — so the suffix is reached by real input.
+ *
+ * THE NAME WE REFERENCE AND THE NAME THE LIBRARY DECLARES ARE ONE STRING.
+ * `json-schema-to-typescript` does not declare under the name it is handed: it
+ * declares under `toSafeString(name)`, which re-cases a lowercase letter that
+ * follows a digit (`V1beta` becomes `V1Beta`), collapses `_x` into `X` and
+ * upper-cases the first letter. A positional name is already a fixed point of
+ * that transform; a selector-derived one is not, and a name that changes on the
+ * way in is a dangling reference on the way out. {@link safeIdentifier} is the
+ * single boundary, and {@link NameRegistry} uniquifies AFTER it — so two
+ * candidates that sanitise onto one identifier get a suffix rather than one
+ * declaration emitted twice under two names.
+ */
+/**
+ * The fixed declarations `generate-type-surface.ts` emits around the
+ * generated ones. Shared by {@link NameRegistry} (so a generated declaration
+ * never shadows one of these) and by `DeclarationSet` (so a description
+ * component named after one of these — `Status`, say — is reserved out from
+ * under it rather than silently merged into it, which is what let a
+ * description declaring a `Status` component reach the committed surface as
+ * two conflicting `export type Status` and `export interface Status`
+ * declarations, `skipLibCheck` hiding the fault until a user's own hook
+ * compile — or, once the self-check gate is on, at generation time with an
+ * unattributed `TS2300`).
+ */
+export const FIXED_ROOT_NAMES = [
+    'Endpoints',
+    'Method',
+    'Path',
+    'RequestMediaType',
+    'ResponseMediaType',
+    'Responses',
+    'Selector',
+    'Status',
+    'StatusClass',
+    'TransactionResponse',
+    'WireMediaType',
+];
+/**
+ * Splits on every run of non-alphanumeric characters and upper-cases each
+ * remaining segment's first character, so `GET`, `astronauts`, `{id}` and
+ * `application/vnd.Example+JSON` become `Get`, `Astronauts`, `Id` and
+ * `ApplicationVndExampleJson`.
+ *
+ * The tail is lower-cased deliberately: a declaration NAME is not required to
+ * be byte-exact — only the emitted selector keys and union members are — and
+ * folding it keeps `JSON` and `json` from producing two visually
+ * indistinguishable identifiers.
+ */
+export function pascalSegments(value) {
+    return value
+        .split(/[^A-Za-z0-9]+/)
+        .filter((segment) => segment.length > 0)
+        .map((segment) => `${segment.charAt(0).toUpperCase()}${segment.slice(1).toLowerCase()}`)
+        .join('');
+}
+/**
+ * A valid identifier fragment for a parameter name. A parameter name may
+ * sanitise to nothing at all — `''` and `'-'` are both reachable header names
+ * in a description — and an empty fragment would silently merge `Header_` with
+ * the next one, so the empty case gets a name of its own rather than no name.
+ */
+function parameterSegment(name) {
+    const segment = pascalSegments(name);
+    return segment.length > 0 ? segment : 'Unnamed';
+}
+/** The role's contribution to a declaration name. */
+export function roleSuffix(role) {
+    switch (role.kind) {
+        case 'request-body':
+            return 'RequestBody';
+        case 'response-body':
+            return 'ResponseBody';
+        case 'query-parameter':
+            return `QueryParam_${parameterSegment(role.parameter)}`;
+        case 'path-parameter':
+            return `PathParam_${parameterSegment(role.parameter)}`;
+        case 'request-header':
+            return `Header_${parameterSegment(role.parameter)}`;
+        case 'cookie':
+            return `Cookie_${parameterSegment(role.parameter)}`;
+        case 'response-header':
+            return `ResponseHeader_${parameterSegment(role.parameter)}`;
+    }
+}
+/**
+ * The identifier a selector plus a role WANTS. Several sites may want the same
+ * one; {@link NameRegistry} is what turns wants into names.
+ *
+ * A method is an RFC 9110 token, so it may be all digits (`123 /x` is a legal
+ * selector), and a parameter name may start with one (`2fa`). Neither an
+ * identifier nor the library's own transform tolerates a leading digit, so the
+ * candidate leaves through {@link safeIdentifier} rather than through a local
+ * guard.
+ */
+export function candidateName(selector, role) {
+    const stem = pascalSegments(selector);
+    return safeIdentifier(`${stem.length > 0 ? stem : 'Schema'}${roleSuffix(role)}`);
+}
+const SAFE_CHARACTER = /[A-Za-z0-9_$]/;
+const LOWERCASE = /[a-z]/;
+const DIGIT = /[0-9]/;
+/**
+ * A character after which the library's `toSafeString` upper-cases a following
+ * lowercase letter: a digit or `$` (`([\d$]+[a-zA-Z])` upper-cases the whole
+ * match) and an underscore (`_[a-z]` is collapsed into the upper-cased letter).
+ */
+const UPPERCASES_WHAT_FOLLOWS = /[0-9$_]/;
+/**
+ * An identifier `json-schema-to-typescript`'s `toSafeString` leaves alone, for
+ * any input string.
+ *
+ * The contract is deliberately weaker than "reproduce `toSafeString`": the
+ * library never sees the original, only this function's output, so all that has
+ * to hold is that the output is a FIXED POINT of the library's transform. That
+ * is four conditions, and each is enforced by one branch below:
+ *
+ * - every character is in `[A-Za-z0-9_$]`, so nothing is replaced by whitespace;
+ * - the first character is never a digit, hence the `_` prefix;
+ * - no lowercase letter follows a digit, a `$` or an `_`;
+ * - the first character is never lowercase, so `upperFirst` is a no-op.
+ *
+ * A run of unusable characters is a word boundary rather than a deletion, so
+ * `foo bar` and `foo-bar` both become `FooBar` — the same convention
+ * {@link pascalSegments} uses, which is why applying both is harmless.
+ */
+export function safeIdentifier(value) {
+    let result = '';
+    let previous = '';
+    let atBoundary = true;
+    for (const character of value) {
+        if (!SAFE_CHARACTER.test(character)) {
+            atBoundary = true;
+            continue;
+        }
+        let next = character;
+        if (LOWERCASE.test(next) &&
+            (atBoundary ||
+                result.length === 0 ||
+                UPPERCASES_WHAT_FOLLOWS.test(previous))) {
+            next = next.toUpperCase();
+        }
+        if (result.length === 0 && DIGIT.test(next)) {
+            result = '_';
+        }
+        result += next;
+        previous = next;
+        atBoundary = false;
+    }
+    return result.length > 0 ? result : 'Schema';
+}
+/**
+ * Hands out unique identifiers, remembering what each site was given.
+ *
+ * The suffix order is a function of the description rather than of traversal
+ * order, because the catalog is sorted by selector and each transaction's
+ * schemas are visited in a fixed role order. Adding a transaction that collides
+ * with an existing stem can renumber the colliding group, and only that group;
+ * adding a non-colliding one — the overwhelmingly common case — renames
+ * nothing.
+ */
+export class NameRegistry {
+    used;
+    byKey = new Map();
+    /**
+     * @param reserved names nothing may be assigned, such as the fixed
+     * declarations the surface emits around the generated ones.
+     */
+    constructor(reserved = []) {
+        this.used = new Set(reserved);
+    }
+    /**
+     * The name for `selector` in `role`, minted the first time it is asked for
+     * and returned unchanged thereafter — so two references to one site cannot
+     * drift apart.
+     */
+    nameFor(selector, role) {
+        const key = `${selector} ${roleSuffix(role)}`;
+        const existing = this.byKey.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const candidate = candidateName(selector, role);
+        let name = candidate;
+        let suffix = 1;
+        while (this.used.has(name)) {
+            suffix += 1;
+            name = `${candidate}_${suffix}`;
+        }
+        this.used.add(name);
+        this.byKey.set(key, name);
+        return name;
+    }
+}
+//# sourceMappingURL=type-names.js.map

package/dist/generation/types/type-names.js.map

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

package/dist/generation/types/write-type-surface.d.ts

@@ -0,0 +1,58 @@
+import type { SamplerPaths } from '../../sampler-paths.js';
+import { type TypeSurface } from './generate-type-surface.js';
+/**
+ * The tsconfig `init` scaffolds, once.
+ *
+ * It is **user-owned from then on**: `sync` never rewrites it, because a user's
+ * edits here — a `types` entry, a stricter flag, an extra `include` — are
+ * legitimate and losing them silently would be worse than any convenience of
+ * keeping it current. A future plugin version needing a different tsconfig is a
+ * documented manual step, not an overwrite.
+ *
+ * The `paths` alias is what makes `@thymian/hooks` resolve in an editor. It is
+ * not what makes hooks *run*: the runtime resolves through a jiti alias, so a
+ * project with no tsconfig at all still executes its hooks.
+ *
+ * No `types` entry, deliberately. The generated surface needs no `@types/node`
+ * — `readFile` answers a `Uint8Array` and the encodings are spelled out — so a
+ * project without it still type-checks. A hook file that imports `node:fs`
+ * needs it and adds it here, which is a legitimate edit and the reason this
+ * file is scaffolded once rather than regenerated.
+ */
+export declare function scaffoldTsconfig(): string;
+/**
+ * The note `init` prints about the repository's own tsconfig.
+ *
+ * The root tsconfig is never modified — it is the project's, not the sampler's —
+ * so the one thing a user has to do by hand is say so.
+ */
+export declare function rootExcludeNote(paths: SamplerPaths, cwd: string): string[];
+/**
+ * Write the generated directory, wholesale.
+ *
+ * Wipe and rewrite rather than merge: a file left over from a description that
+ * no longer has that shape is exactly the stale artifact the virtual model
+ * exists to remove, and a merge cannot tell one from a file a user added.
+ * Everything outside `generated/` — the hooks, the tsconfig — is untouched.
+ */
+export declare function writeGenerated(paths: SamplerPaths, surface: TypeSurface): Promise<string[]>;
+/**
+ * What is currently committed under `generated/`, file name → contents.
+ *
+ * Reads only the files the surface itself ever writes — {@link
+ * REQUEST_TYPES_FILE} and {@link HOOKS_API_FILE} — rather than every
+ * directory entry. `writeGenerated` wipes and rewrites the whole directory on
+ * every write, so anything else in it was never put there by the sampler: a
+ * macOS `.DS_Store`, an editor swap file, a stray subdirectory. `readdir`
+ * would hand all of it back with no way to tell a file from a directory
+ * without a second syscall per entry, and blindly `readFile`-ing a
+ * subdirectory throws `EISDIR` — crashing `sync --check`, `validate` and
+ * `thymian test` alike, mid-command, on a file the user never asked the
+ * sampler to look at. Naming the two files instead of listing the directory
+ * sidesteps both failure modes: a stray entry is neither read nor compared,
+ * so it is silently ignored rather than reported as spurious drift.
+ */
+export declare function readGenerated(paths: SamplerPaths): Promise<Record<string, string>>;
+/** The surface as the file map it is written as, for comparison without I/O. */
+export declare function surfaceAsFiles(surface: TypeSurface): Record<string, string>;
+//# sourceMappingURL=write-type-surface.d.ts.map

package/dist/generation/types/write-type-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-type-surface.d.ts","sourceRoot":"","sources":["../../../src/generation/types/write-type-surface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAoBzC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAa1E;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgBjC;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK3E"}

package/dist/generation/types/write-type-surface.js

@@ -0,0 +1,119 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { toTypeScriptPath } from '../../ts-path.js';
+import { entryExists } from '../../utils.js';
+import { HOOKS_API_FILE, REQUEST_TYPES_FILE, } from './generate-type-surface.js';
+/**
+ * The tsconfig `init` scaffolds, once.
+ *
+ * It is **user-owned from then on**: `sync` never rewrites it, because a user's
+ * edits here — a `types` entry, a stricter flag, an extra `include` — are
+ * legitimate and losing them silently would be worse than any convenience of
+ * keeping it current. A future plugin version needing a different tsconfig is a
+ * documented manual step, not an overwrite.
+ *
+ * The `paths` alias is what makes `@thymian/hooks` resolve in an editor. It is
+ * not what makes hooks *run*: the runtime resolves through a jiti alias, so a
+ * project with no tsconfig at all still executes its hooks.
+ *
+ * No `types` entry, deliberately. The generated surface needs no `@types/node`
+ * — `readFile` answers a `Uint8Array` and the encodings are spelled out — so a
+ * project without it still type-checks. A hook file that imports `node:fs`
+ * needs it and adds it here, which is a legitimate edit and the reason this
+ * file is scaffolded once rather than regenerated.
+ */
+export function scaffoldTsconfig() {
+    return `${JSON.stringify({
+        compilerOptions: {
+            baseUrl: '.',
+            module: 'nodenext',
+            moduleResolution: 'nodenext',
+            target: 'es2023',
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            paths: {
+                '@thymian/hooks': [`./generated/${HOOKS_API_FILE}`],
+            },
+        },
+        include: ['./hooks/**/*.ts', './generated/**/*.d.ts'],
+    }, null, 2)}\n`;
+}
+/**
+ * The note `init` prints about the repository's own tsconfig.
+ *
+ * The root tsconfig is never modified — it is the project's, not the sampler's —
+ * so the one thing a user has to do by hand is say so.
+ */
+export function rootExcludeNote(paths, cwd) {
+    // A tsconfig `exclude` entry is a glob TypeScript matches against its own
+    // forward-slashed file names, so the hint has to be printed in that form on
+    // every platform — a Windows `\` here is a suggestion the user's own
+    // tsconfig would silently fail to honour.
+    const rootRelative = toTypeScriptPath(relative(cwd, paths.root) || paths.root);
+    return [
+        `Add ${JSON.stringify(rootRelative)} to the "exclude" list of your project's own tsconfig.json.`,
+        'Without it your project compiles the hooks with its own settings, and the sampler tsconfig — the one that knows where `@thymian/hooks` lives — never governs them.',
+    ];
+}
+/**
+ * Write the generated directory, wholesale.
+ *
+ * Wipe and rewrite rather than merge: a file left over from a description that
+ * no longer has that shape is exactly the stale artifact the virtual model
+ * exists to remove, and a merge cannot tell one from a file a user added.
+ * Everything outside `generated/` — the hooks, the tsconfig — is untouched.
+ */
+export async function writeGenerated(paths, surface) {
+    const before = await readGenerated(paths);
+    const fresh = surfaceAsFiles(surface);
+    await rm(paths.generatedDir, { recursive: true, force: true });
+    await mkdir(paths.generatedDir, { recursive: true });
+    for (const [name, contents] of Object.entries(fresh)) {
+        await writeFile(join(paths.generatedDir, name), contents, 'utf-8');
+    }
+    // Which files' *bytes* moved, which is not the same question as which types
+    // moved: the drift gate compares canonicalized, so a description edit is not
+    // drift — but it does change the file, and a user told "these match" while
+    // finding a diff in their working tree is owed the difference.
+    return [...new Set([...Object.keys(before), ...Object.keys(fresh)])]
+        .filter((name) => before[name] !== fresh[name])
+        .sort();
+}
+/**
+ * What is currently committed under `generated/`, file name → contents.
+ *
+ * Reads only the files the surface itself ever writes — {@link
+ * REQUEST_TYPES_FILE} and {@link HOOKS_API_FILE} — rather than every
+ * directory entry. `writeGenerated` wipes and rewrites the whole directory on
+ * every write, so anything else in it was never put there by the sampler: a
+ * macOS `.DS_Store`, an editor swap file, a stray subdirectory. `readdir`
+ * would hand all of it back with no way to tell a file from a directory
+ * without a second syscall per entry, and blindly `readFile`-ing a
+ * subdirectory throws `EISDIR` — crashing `sync --check`, `validate` and
+ * `thymian test` alike, mid-command, on a file the user never asked the
+ * sampler to look at. Naming the two files instead of listing the directory
+ * sidesteps both failure modes: a stray entry is neither read nor compared,
+ * so it is silently ignored rather than reported as spurious drift.
+ */
+export async function readGenerated(paths) {
+    if (!(await entryExists(paths.generatedDir))) {
+        return {};
+    }
+    const files = {};
+    for (const name of [HOOKS_API_FILE, REQUEST_TYPES_FILE].sort()) {
+        const path = join(paths.generatedDir, name);
+        if (await entryExists(path)) {
+            files[name] = await readFile(path, 'utf-8');
+        }
+    }
+    return files;
+}
+/** The surface as the file map it is written as, for comparison without I/O. */
+export function surfaceAsFiles(surface) {
+    return {
+        [HOOKS_API_FILE]: surface.hooksApi,
+        [REQUEST_TYPES_FILE]: surface.requestTypes,
+    };
+}
+//# sourceMappingURL=write-type-surface.js.map

package/dist/generation/types/write-type-surface.js.map

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

package/dist/hooks/create-hook-utils.d.ts

@@ -1,8 +1,24 @@
-import { type HttpRequest, type HttpRequestTemplate, type HttpResponse, type Logger, type ThymianFormat } from '@thymian/core';
-import { type HttpTestCaseResult } from '@thymian/core';
-import type { HookRunner } from './hook-runner.js';
-import type { EndpointRequest, Endpoints, HookUtils } from './hook-utils.js';
-export declare function toHttpRequestTemplate(methodAndUrl: string, req: EndpointRequest): HttpRequestTemplate;
-export declare function createHookUtils<E extends Endpoints>(format: ThymianFormat, runRequest: (req: HttpRequest) => Promise<HttpResponse>, hookRunner: HookRunner, urlToTransactionId: Record<string, string>, results: HttpTestCaseResult[], logger: Logger): HookUtils<E>;
+import { type HttpRequestTemplate, type HttpResponse, type HttpTestCaseResult } from '@thymian/core';
+import type { Selector } from '../selectors/selector.js';
+import type { EndpointRequest, EndpointResponse, Endpoints, HookUtils, RequestOptions } from './hook-utils.js';
+/** What one hook call needs to know about where it came from and what it shapes. */
+export type HookCallContext = {
+    /** Absolute directory of the hook file, for the file helpers. */
+    dir: string;
+    /** The request this hook is shaping, for the typed setters. */
+    request: HttpRequestTemplate | undefined;
+    /** Where a hook's assertions and messages land. */
+    results: HttpTestCaseResult[];
+    /**
+     * Runs a cross-endpoint request. Absent where there is no pipeline to run one
+     * through — a `defineSample` hook runs before any request exists.
+     */
+    requestOther?: (selector: Selector, args: EndpointRequest, options: RequestOptions) => Promise<EndpointResponse>;
+};
+export declare function createHookUtils<E extends Endpoints>(context: HookCallContext): HookUtils<E>;
+/**
+ * The body a hook sees, parsed when the response says it is JSON and left as
+ * the raw string when it does not.
+ */
 export declare function parseResponseBody(res: HttpResponse): unknown;
 //# sourceMappingURL=create-hook-utils.d.ts.map

package/dist/hooks/create-hook-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-hook-utils.d.ts","sourceRoot":"","sources":["../../src/hooks/create-hook-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,kBAAkB,EAAoB,MAAM,eAAe,CAAC;AAG1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK7E,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,eAAe,GACnB,mBAAmB,CAsBrB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EACjD,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,EACvD,UAAU,EAAE,UAAU,EACtB,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,OAAO,EAAE,kBAAkB,EAAE,EAC7B,MAAM,EAAE,MAAM,GACb,SAAS,CAAC,CAAC,CAAC,CAmId;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAW5D"}
+{"version":3,"file":"create-hook-utils.d.ts","sourceRoot":"","sources":["../../src/hooks/create-hook-utils.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,cAAc,EACf,MAAM,iBAAiB,CAAC;AAKzB,oFAAoF;AACpF,MAAM,MAAM,eAAe,GAAG;IAC5B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACzC,mDAAmD;IACnD,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,CACb,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChC,CAAC;AAEF,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EACjD,OAAO,EAAE,eAAe,GACvB,SAAS,CAAC,CAAC,CAAC,CA2Hd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAY5D"}