@oddkin/analyzer 0.0.0-stage → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Brady
+
+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

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @oddkin/analyzer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node-only static analysis for Oddkin component libraries. Produces a standard Custom Elements Manifest (`custom-elements.json`, schema 2.1.0) and the Oddkin enrichment manifest (`oddkin.metadata.json`) **without importing or executing** the analyzed code. Development tooling: it depends on the TypeScript 5.9 compiler and is never part of a browser bundle.
+
+```sh
+oddkin-analyze tsconfig.json --out . [--name my-lib --version 1.0.0] [--strict] [--json]
+```
+
+```ts
+import { analyze, writeOutputs } from '@oddkin/analyzer';
+
+const result = analyze({ project: 'tsconfig.json' });
+await writeOutputs(result, '.');
+```
+
+Module paths in the outputs are the published paths (`rootDir` → `outDir`). Dynamic definitions are reported as `analyzer.dynamic.*` diagnostics with source locations instead of being guessed.
+
+Contract and limits: [metadata-and-analyzer.md](../../docs/architecture/metadata-and-analyzer.md) §8; front-end decision: ADR 0018.
+
+## Agent kits
+
+`oddkin-kit` writes agent kits from the metadata the analyzer publishes ([agent-tooling.md](../../docs/architecture/agent-tooling.md) §4–5): an entry guide (`GUIDE.md`, within 8 KiB), a reference for each component, token category, recipe, stylesheet, and model, `kit.json` with a fingerprint of its inputs, and `llms.txt`. Run it in the workspace root:
+
+```sh
+# The kit each component package ships, in <package>/agent/ (list "agent" in the package's "files").
+oddkin-kit package
+# Check every shipped kit against the installed package's metadata: the packages named, or the workspace's own.
+oddkin-kit package --check --package @oddkin/components
+# A kit for the repository itself, in .oddkin/agent-kit/<name>/; --check names the inputs that changed.
+oddkin-kit [--package <name>]... [--out <dir>] [--theme-config <file>] [--check]
+# The managed section of AGENTS.md; text outside its markers is kept.
+oddkin-kit agents-md [--write | --check]
+# A documentation site's llms.txt (llmstxt.org) and the kit files it links, in <dir>/agent/<name>/.
+oddkin-kit llms --base https://docs.example/ --out <dir> [--title <text>] [--summary <text>]
+```
+
+Exit codes: 0 success; 1 a stale, missing, or over-budget kit, or a stale `AGENTS.md` section; 2 usage error. The same functions are exported from `@oddkin/analyzer/kit` (`resolveProjectContext`, `generateKit`, `checkKit`, `packageKit`, `siteLlmsText`, `renderSection`, `updateAgentsMd`, and `main`). A kit a package ships depends only on what the package publishes, so a project that installs it regenerates the same files.
+
+## Stability
+
+The analyzer is versioned `1.0.0` with the other Oddkin packages, but only its outputs follow candidate v1 contracts: Custom Elements Manifest 2.1.0, `oddkin-metadata.v1`, `diagnostic.v1`, and the agent kits' `agent-kit.v1` and `project-context.v1`. Its own contracts are **not frozen by 1.0.0** ([ADR 0047](../../docs/architecture/decisions/0047-m8-checkpoint-candidate-v1-contracts.md)): the impact snapshot and report (`comparison-snapshot.v1`, `impact-report.v1`) and the `product.v1` input `oddkin-impact` reads. Until they are frozen they can change in a minor release; only frozen contracts wait for a major ([release-process.md](../../docs/release-process.md) §1).

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * oddkin-analyze <tsconfig> [--out dir] [--name n --version v] [--no-history] [--strict] [--json]
+ * Exit codes: 0 success, 1 errors (or warnings with --strict), 2 usage error.
+ */
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { analyze, gitHistory, writeOutputs } from './index.js';
+const USAGE = 'Usage: oddkin-analyze <tsconfig.json> [--out <dir>] [--name <library> --version <version>] [--no-history] [--strict] [--json]\n' +
+    '  Updated dates come from git history unless --no-history; without full history (no git, a shallow clone) pages carry only authored @updated dates.';
+let parsed;
+try {
+    parsed = parseArgs({
+        allowPositionals: true,
+        allowNegative: true,
+        options: {
+            out: { type: 'string', default: '.' },
+            name: { type: 'string' },
+            version: { type: 'string' },
+            history: { type: 'boolean', default: true },
+            strict: { type: 'boolean', default: false },
+            json: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+}
+catch (error) {
+    console.error(`${error instanceof Error ? error.message : String(error)}\n${USAGE}`);
+    process.exit(2);
+}
+const { values, positionals } = parsed;
+if (values.help) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const [project] = positionals;
+if (!project || (values.name === undefined) !== (values.version === undefined)) {
+    console.error(USAGE);
+    process.exit(2);
+}
+const history = values.history ? gitHistory(dirname(resolve(project))) : undefined;
+const result = analyze({
+    project,
+    ...(values.name && values.version
+        ? { library: { name: values.name, version: values.version } }
+        : {}),
+    ...(history ? { history } : {}),
+});
+const files = await writeOutputs(result, values.out);
+if (values.json)
+    console.log(JSON.stringify(result.diagnostics, null, 2));
+else {
+    if (values.history && !history)
+        console.error('note: no full git history (no repository, or a shallow clone); pages carry only authored @updated dates.');
+    for (const d of result.diagnostics) {
+        const at = d.source ? ` ${d.source.file}:${d.source.line}:${d.source.column}` : '';
+        console.error(`${d.severity} ${d.code}${at}: ${d.message}${d.suggestion ? `\n  → ${d.suggestion}` : ''}`);
+    }
+    for (const file of files)
+        console.log(`wrote ${file}`);
+}
+process.exitCode = result.diagnostics.some((d) => d.severity === 'error' || (values.strict && d.severity === 'warning'))
+    ? 1
+    : 0;
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

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

package/dist/contracts.d.ts

@@ -0,0 +1,29 @@
+export interface ContractEntry {
+    readonly title: string;
+    readonly anchor: string;
+    /** SHA-256 of the section text, for change detection. */
+    readonly sha256: string;
+}
+export interface ContractIndex {
+    readonly package: string;
+    /** Version of the installed package the index was read from. */
+    readonly version: string;
+    /** Absolute path of the installed `CONTRACTS.md`. */
+    readonly path: string;
+    readonly contracts: Readonly<Record<string, ContractEntry>>;
+}
+export interface ResolvedContract extends ContractEntry {
+    readonly id: string;
+    readonly package: string;
+    readonly version: string;
+    readonly path: string;
+    /** The section of `CONTRACTS.md`, from its anchor to the next one. */
+    readonly text: string;
+}
+/** The package that publishes `id` (`contract:core/scope` → `@oddkin/core`), if `id` is well formed. */
+export declare const contractPackage: (id: string) => string | undefined;
+/** The contract index of `packageName` as installed for code in `from` (default: the working directory). */
+export declare function contractIndex(packageName: string, from?: string): ContractIndex | undefined;
+/** Resolve a contract id to its text in the installed package, or `undefined` when it does not exist. */
+export declare function resolveContract(id: string, from?: string): ResolvedContract | undefined;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID,wGAAwG;AACxG,eAAO,MAAM,eAAe,OAAQ,MAAM,KAAG,MAAM,GAAG,SAGrD,CAAC;AAEF,4GAA4G;AAC5G,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,IAAI,SAAgB,GACnB,aAAa,GAAG,SAAS,CAqB3B;AAED,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,gBAAgB,GAAG,SAAS,CAiB9F"}

package/dist/contracts.js

@@ -0,0 +1,57 @@
+/**
+ * Contract references (`contract:core/<name>`) resolved offline against the installed package:
+ * `@oddkin/core/contracts.json` maps each id to an anchor in the packaged `CONTRACTS.md`, both
+ * generated from `docs/architecture/core-contracts.md`.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const ID = /^contract:([a-z][a-z0-9-]*)\/([a-z0-9-]+)$/;
+/** The package that publishes `id` (`contract:core/scope` → `@oddkin/core`), if `id` is well formed. */
+export const contractPackage = (id) => {
+    const owner = ID.exec(id)?.[1];
+    return owner ? `@oddkin/${owner}` : undefined;
+};
+/** The contract index of `packageName` as installed for code in `from` (default: the working directory). */
+export function contractIndex(packageName, from = process.cwd()) {
+    const require = createRequire(join(from, 'package.json'));
+    let indexPath;
+    let manifestPath;
+    try {
+        indexPath = require.resolve(`${packageName}/contracts.json`);
+        manifestPath = require.resolve(`${packageName}/package.json`);
+    }
+    catch {
+        return undefined;
+    }
+    const index = JSON.parse(readFileSync(indexPath, 'utf8'));
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    return {
+        package: packageName,
+        version: manifest.version,
+        path: join(dirname(indexPath), index.file),
+        contracts: index.contracts,
+    };
+}
+/** Resolve a contract id to its text in the installed package, or `undefined` when it does not exist. */
+export function resolveContract(id, from = process.cwd()) {
+    const packageName = contractPackage(id);
+    const index = packageName ? contractIndex(packageName, from) : undefined;
+    const entry = index?.contracts[id];
+    if (!index || !entry)
+        return undefined;
+    const markdown = readFileSync(index.path, 'utf8');
+    const start = markdown.indexOf(`<a id="${entry.anchor}"></a>`);
+    if (start < 0)
+        return undefined;
+    const next = markdown.indexOf('<a id="', start + 1);
+    return {
+        id,
+        ...entry,
+        package: index.package,
+        version: index.version,
+        path: index.path,
+        text: markdown.slice(start, next < 0 ? undefined : next).trim(),
+    };
+}
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

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

package/dist/docs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `docs[*].updated` (metadata-and-analyzer.md §3, "Updated dates"): an authored `@updated` date,
+ * or the last commit touching the page's declared source files. Never build time; pages with
+ * neither are omitted. Page ids are shared with the Workbench page registry.
+ */
+import type { ExampleInfo } from './examples.js';
+import type { Extraction, SourceLocation } from './extract.js';
+import type { SourceHistory } from './history.js';
+export interface DatedPage {
+    /** Stable page id: `components/<tag>`, `foundations/<id>`. */
+    readonly page: string;
+    /** Library-relative files the page's facts come from. */
+    readonly files: readonly string[];
+    readonly authored?: {
+        readonly value: string;
+        readonly source: SourceLocation;
+    };
+}
+export interface UpdatedFact {
+    readonly value: string;
+    readonly provenance: 'authored' | 'extracted';
+    readonly source?: SourceLocation;
+}
+/**
+ * Each registered element's page and its declared sources in this library: the class and its base
+ * classes, the definition and the definitions it recomposes, template, styles, registration
+ * module, explicit metadata, and examples.
+ */
+export declare function componentPages(extraction: Extraction, examples: readonly ExampleInfo[]): DatedPage[];
+/** `docs` entries with an `updated` fact, keyed by page id in sorted order. */
+export declare function updatedDocs(pages: readonly DatedPage[], history: SourceHistory | undefined): Record<string, {
+    updated: UpdatedFact;
+}>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAiB,UAAU,EAAE,cAAc,EAAa,MAAM,cAAc,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;KAAE,CAAC;CACjF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAKD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,WAAW,EAAE,GAC/B,SAAS,EAAE,CAoCb;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,aAAa,GAAG,SAAS,GACjC,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,CAoB1C"}

package/dist/docs.js

@@ -0,0 +1,63 @@
+const local = (ref) => ref && !ref.external && !ref.package ? [ref.file] : [];
+/**
+ * Each registered element's page and its declared sources in this library: the class and its base
+ * classes, the definition and the definitions it recomposes, template, styles, registration
+ * module, explicit metadata, and examples.
+ */
+export function componentPages(extraction, examples) {
+    const classes = new Map(extraction.components.map((c) => [`${c.file}#${c.name}`, c]));
+    const definitions = new Map(extraction.definitions.map((d) => [d.tag, d]));
+    return extraction.registrations.map((registration) => {
+        const files = new Set([registration.file]);
+        let component = classes.get(`${registration.classFile}#${registration.className}`);
+        const authored = component?.tags['updated']?.[0];
+        // `classes` holds only this library's classes: the chain ends at another package's base.
+        while (component) {
+            files.add(component.file);
+            if (component.authored)
+                files.add(component.authored.file);
+            const base = component.superclass;
+            component = base.file ? classes.get(`${base.file}#${base.name}`) : undefined;
+        }
+        for (let definition = registration.definition; definition; definition = definition.extends ? definitions.get(definition.extends) : undefined) {
+            for (const file of [
+                ...local(definition.ref),
+                ...local(definition.template),
+                ...definition.styles.flatMap(local),
+            ])
+                files.add(file);
+        }
+        for (const example of examples)
+            if (example.component === registration.tag)
+                files.add(example.file);
+        return {
+            page: `components/${registration.tag}`,
+            files: [...files].sort(),
+            ...(authored ? { authored: { value: authored.value, source: authored.location } } : {}),
+        };
+    });
+}
+/** `docs` entries with an `updated` fact, keyed by page id in sorted order. */
+export function updatedDocs(pages, history) {
+    const dates = history?.lastChanged([...new Set(pages.flatMap((p) => p.files))]);
+    const docs = {};
+    for (const page of [...pages].sort((a, b) => (a.page < b.page ? -1 : 1))) {
+        if (page.authored) {
+            docs[page.page] = {
+                updated: {
+                    value: page.authored.value,
+                    provenance: 'authored',
+                    source: page.authored.source,
+                },
+            };
+            continue;
+        }
+        const latest = page.files
+            .map((file) => dates?.get(file) ?? '')
+            .reduce((a, b) => (b > a ? b : a), '');
+        if (latest)
+            docs[page.page] = { updated: { value: latest, provenance: 'extracted' } };
+    }
+    return docs;
+}
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

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

package/dist/emit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Outputs: a standard Custom Elements Manifest (custom-elements-manifest@2.1.0) and the
+ * Oddkin enrichment manifest (`oddkin.metadata.json`, schema v1) that references CEM
+ * declarations by module path and name. Deterministic: no timestamps, stable ordering.
+ */
+import type { AnalyzerDiagnostic, Extraction } from './extract.js';
+export interface ModulePaths {
+    /** Map a source path (relative to the package root) to its published module path. */
+    readonly moduleOf: (sourceFile: string) => string;
+    /** Map a published module path to a package export specifier, when one exists. */
+    readonly specifierOf: (modulePath: string) => string | undefined;
+}
+export interface LibraryInfo {
+    readonly name: string;
+    readonly version: string;
+    readonly prefix?: string;
+    readonly packages: ReadonlyArray<{
+        readonly name: string;
+        readonly version: string;
+        readonly customElements?: string;
+    }>;
+}
+/**
+ * Category records from the `@category` tags of registered components: the label is the first
+ * spelling in tag order, and a different spelling of the same id is reported, not merged.
+ */
+export declare function categoryRecords(extraction: Extraction): {
+    readonly categories: Record<string, {
+        label: string;
+    }>;
+    readonly diagnostics: AnalyzerDiagnostic[];
+};
+export declare function buildManifest(extraction: Extraction, paths: ModulePaths): Record<string, unknown>;
+export declare function buildMetadata(extraction: Extraction, paths: ModulePaths, library: LibraryInfo, oddkinVersion: string): Record<string, unknown>;
+export declare function sortDiagnostics(diagnostics: readonly AnalyzerDiagnostic[]): AnalyzerDiagnostic[];
+/** Stable JSON text: two-space indentation and a trailing newline. */
+export declare const stableJson: (value: unknown) => string;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACV,kBAAkB,EAIlB,UAAU,EAIX,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAClE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;KAClC,CAAC,CAAC;CACJ;AAgBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,EAAE,kBAAkB,EAAE,CAAC;CAC5C,CA8BA;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwIjG;AAuGD,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwKzB;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAIhG;AAED,sEAAsE;AACtE,eAAO,MAAM,UAAU,UAAW,OAAO,WAA0C,CAAC"}