@frmwrkd/snag-anchor 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Snag contributors
+
+   Full text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,305 @@
+# @frmwrkd/snag-anchor
+
+An [unplugin](https://github.com/unjs/unplugin) that stamps
+`data-snag="path:line:col"` onto DOM elements at build time.
+
+```html
+<button data-snag="src/checkout/PromoField.tsx:42:7" data-snag-cmp="PromoField">
+```
+
+Two attributes, self-contained — **no global registry, no indirection**.
+LocatorJS's default `data-locatorjs-id` mode needs a `window.__LOCATOR_DATA__`
+lookup table; this deliberately does not, because only `data-*` attributes cross
+the ISOLATED-world boundary. Expando properties the page attaches to DOM nodes
+(`__reactFiber$*`, `__svelte_meta`) are invisible to an ISOLATED content script,
+so tier 0 is the only resolution path that needs no round trip into the page:
+one `getAttribute` and you're done.
+
+**Licence:** Apache-2.0.
+**Spec:** `docs/02-BACKEND-SPEC.md` §2. Locked decisions live in
+`docs/00-MASTER-BUILD-PLAN.md` §7 — don't relitigate them.
+
+---
+
+## Install and wire up
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import snagAnchor from '@frmwrkd/snag-anchor/vite';
+
+export default defineConfig({ plugins: [snagAnchor()] });
+```
+
+```js
+// webpack.config.js
+const snagAnchor = require('@frmwrkd/snag-anchor/webpack').default;
+module.exports = { plugins: [snagAnchor()] };
+```
+
+Also available: `@frmwrkd/snag-anchor/rollup`, `/rspack`, `/esbuild`, `/nuxt`,
+`/babel` (a plain Babel plugin) and `/loader` (a webpack-shaped loader, see
+[Next.js and Turbopack](#nextjs-and-turbopack)).
+
+---
+
+## Options
+
+Every default below is the one in `docs/02-BACKEND-SPEC.md` §2.3.
+
+| Option | Type | Default | |
+|---|---|---|---|
+| `enabled` | `boolean` | `process.env.NODE_ENV !== 'production'` | Master switch. |
+| `attribute` | `string` | `'data-snag'` | |
+| `componentAttribute` | `string` | `'data-snag-cmp'` | |
+| `root` | `string` | git root | Every emitted path is relative to this. |
+| `include` | `string[]` | `['**/*.{jsx,tsx,vue}']` | |
+| `exclude` | `string[]` | `['**/node_modules/**','**/*.test.*','**/*.stories.*']` | Beats `include`. |
+| `intrinsicOnly` | `boolean` | `true` | Stamp DOM elements, not component tags. |
+| `emitRepoMap` | `boolean` | `true` | Reserved — see [Not yet wired](#not-yet-wired). |
+| `devtoolsJson` | `boolean` | `true` | Serve the well-known project-root file. |
+| `production` | `false \| 'minimal'` | `false` | `'minimal'` = component name only, no path. |
+
+---
+
+## The information-disclosure tradeoff — read before turning production on
+
+`data-snag` publishes a source path into the DOM. In development that is the
+entire point. In a **public production build** it publishes your directory
+layout, your internal component names, and — for anyone willing to read a few
+hundred of them — a decent sketch of your architecture, to anyone with DevTools
+open.
+
+So the gate is two-layered and fails closed:
+
+- `enabled` defaults to `process.env.NODE_ENV !== 'production'`, which switches
+  the plugin off entirely in a production build.
+- Even with `enabled: true` forced on, a production build can only ever reach
+  `'minimal'`. The `production` option's type is `false | 'minimal'` — **there
+  is no value that means "full paths in production"**, by design.
+- The Vite integration additionally re-reads `config.isProduction` in
+  `configResolved` and downgrades on its own if Vite says "production" while
+  `NODE_ENV` says nothing.
+
+`production: 'minimal'` emits **only** `data-snag-cmp="PromoField"` — a
+component name, never a path, never a line number. That is a real but much
+smaller disclosure: it leaks your component vocabulary. It exists because a
+staging screenshot with a component name still beats nothing, which is how
+FullStory ships theirs. Use it on internal staging; think twice before shipping
+it to the open internet.
+
+If an element has no resolvable component name, `'minimal'` emits nothing at all
+for it. A missing attribute is honest; a made-up one is not.
+
+---
+
+## What gets stamped, and what deliberately does not
+
+### Intrinsic elements only
+
+`data-snag` goes on **lowercase JSX elements** — `<div>`, `<button>`,
+`<my-widget>` — and never on `<PromoField />`. A `data-snag` prop on a component
+element is silently swallowed unless that component happens to spread its props
+onto a DOM node, and an attribute that lands nowhere is worse than no attribute:
+the resolver cannot tell "not stamped" from "stamped and dropped".
+
+The intrinsic test is Babel's own `isCompatTag` — the tag name starts with a
+lowercase ASCII letter. `<Foo.Bar>` (a member expression) and `<svg:circle>` (a
+namespaced name) are never stamped.
+
+`intrinsicOnly: false` additionally stamps component elements. That is only
+useful for frameworks that forward unknown props onto a DOM node by default;
+leave it off unless you have measured that it helps.
+
+### Fragments
+
+`<>…</>` parses to a different AST node entirely and is never visited.
+`<React.Fragment>` is a member expression, so it is not intrinsic. Neither is
+ever stamped.
+
+### An existing `data-snag`
+
+User override wins. An element that already carries `data-snag` (or
+`data-snag-cmp`) is left exactly as written.
+
+### Vue
+
+The SFC template is transformed at `enforce: 'pre'`, before
+`@vitejs/plugin-vue` compiles it. Host elements are stamped; `<MyChild/>`,
+`<template>` and `<slot>` are not — the last two are compiler constructs that
+never reach the DOM. `@vue/compiler-sfc` reports template positions **absolute
+within the whole `.vue` file**, so the emitted line counts from the top of the
+file including the `<script setup>` block. The component name is the SFC's file
+name.
+
+### Svelte — nothing, on purpose
+
+`.svelte` is **absent from the default `include`, deliberately**. Svelte 5
+already attaches
+
+```js
+element.__svelte_meta = { loc: { file: 'src/App.svelte', line: 12, column: 5 } }
+```
+
+to every element in dev, with zero setup, and `@frmwrkd/snag-resolver` reads it directly
+at **tier 1**. Injecting an attribute there would duplicate framework metadata
+that can only ever disagree with it. See `docs/02-BACKEND-SPEC.md` §2.2 and
+`docs/03-RESEARCH-APPENDIX.md` §2.2, technique #3.
+
+### Plain HTML with no build step
+
+Not supported at tier 0, by design. It falls to tier 4, where the resolver
+reports a route and a selector, zero candidates, and **no fabricated path**.
+
+---
+
+## Line and column semantics
+
+- `line` is **1-based** and points at the `<` of the element's **opening tag**.
+- `col` is **1-based**. Babel reports columns 0-based; this package adds one,
+  because the consumer is `vscode://file/{path}:{line}:{col}` and every editor's
+  "go to line:column" is 1-based. Vue's parser already reports 1-based columns,
+  so both languages emit the same convention.
+
+The invariant, which `packages/anchor/test/` asserts against every fixture by
+reading the file back off disk:
+
+```
+sourceLines[line - 1].charAt(col - 1) === '<'
+```
+
+Paths are **repo-relative and POSIX-normalised**, so the same attribute works
+locally, in a container, and on a preview deploy — and so a capture filed on
+Windows still matches a repo map built on Linux. The absolute root is published
+separately, below.
+
+---
+
+## The absolute project root
+
+With `devtoolsJson: true` (the default) the Vite dev server also serves:
+
+```
+GET /.well-known/appspecific/com.chrome.devtools.json
+{ "workspace": { "root": "/Users/theo/dev/myapp", "uuid": "…" } }
+```
+
+The extension fetches this from the page origin and joins it to the
+repo-relative half, so `src/App.tsx:42:7` becomes a path Claude Code can open.
+It only works on localhost, which is exactly the case that matters.
+
+The uuid is a **UUID v5 derived from the absolute root**, not a random one:
+Chrome DevTools binds a workspace folder to it, and a fresh uuid on every
+restart would silently unbind the folder each time the dev server restarts.
+
+For bundlers other than Vite, mount the middleware yourself — register it
+**unmounted**, or connect will rewrite `req.url` to `/` and it will swallow the
+index route:
+
+```ts
+import { createDevtoolsJsonMiddleware } from '@frmwrkd/snag-anchor';
+server.middlewares.use(createDevtoolsJsonMiddleware('/abs/project/root'));
+```
+
+---
+
+## Next.js and Turbopack
+
+`create-next-app` on Next 15 defaults `next dev` to Turbopack, and
+`turbopack.rules` maps file extensions to **webpack-shaped loaders**, not to
+unplugin plugins. So the transform also ships as a plain CommonJS loader:
+
+```js
+// next.config.js
+module.exports = {
+  turbopack: {
+    rules: {
+      '*.{jsx,tsx}': { loaders: ['@frmwrkd/snag-anchor/loader'], as: '*.{jsx,tsx}' },
+    },
+  },
+};
+```
+
+**This integration is unverified.** `docs/03-RESEARCH-APPENDIX.md` §2.7 marks it
+`[U]`, and no primary source confirms an unplugin-based transform can be
+registered through `turbopack.rules`. It has not been run against a real
+Turbopack dev server here. If Turbopack rejects the loader,
+`docs/02-BACKEND-SPEC.md` §2.6 criterion 6 explicitly permits `next dev
+--no-turbo` — which runs the webpack pipeline, where both
+`@frmwrkd/snag-anchor/webpack` and this loader work — with the gap recorded as a known
+limitation.
+
+There is no native SWC plugin. A real one would have to be a Rust-compiled
+binary; the loader covers the same ground at the bundler level, for both the
+Turbopack and the webpack pipelines.
+
+---
+
+## What this is NOT built on
+
+React 19 **removed** `fiber._debugSource`. `jsxDEV`'s `source` argument was
+dropped in 19.0/19.1 and removed from the signature entirely in 19.2;
+`createElement` explicitly strips `__source`/`__self`; `@babel/preset-react` now
+defaults `developmentSourceSelf` to `false` for exactly that reason.
+
+That break took out `click-to-component`,
+`vite-plugin-react-click-to-component`, `react-dev-inspector`, `code-inspector`,
+`radon-ide` and LocatorJS's React path **simultaneously**. This package depends
+on none of them and reads none of those fields. The Babel visitor is written
+from scratch and is about forty lines. See `docs/03-RESEARCH-APPENDIX.md` §2.1
+(marked `[V]` — verified against React's source).
+
+---
+
+## How the transform works
+
+Parse, then **splice** — never re-print. `@babel/parser` produces the AST, the
+insertion offsets are computed from it, and the attribute text is inserted into
+the original source with `magic-string`. The file is never handed to a code
+generator.
+
+That matters three times over:
+
+1. **Correctness.** Re-printing a `.tsx` file round-trips syntax this plugin has
+   no business touching. A splice cannot corrupt what it does not read.
+2. **Line accuracy.** An insertion that never contains a newline cannot move a
+   line — the emitted line number stays true to the original file.
+3. **Build overhead.** `docs/02-BACKEND-SPEC.md` §2.6 criterion 4 caps overhead
+   at 8%. Parse + splice is a fraction of parse + generate.
+
+The attribute is inserted **after the last existing attribute**, so a
+`{...props}` spread cannot overwrite the stamp with a value forwarded from a
+parent.
+
+A transform that throws breaks the developer's dev server, so every failure path
+here returns the source untouched instead: unparseable file, unsupported
+template language, no filename to derive a path from. The cost of a missed
+anchor is a tier-3 fallback. The cost of a thrown error is somebody's afternoon.
+
+`@frmwrkd/snag-anchor/babel` is the same logic as a real Babel `PluginObj`, for wiring
+into a `babel.config.js` (React Native, Storybook, Next's Babel path). Both
+paths share one decision core, and `test/parity.test.ts` asserts they emit
+identical attributes for the same input.
+
+---
+
+## Not yet wired
+
+`emitRepoMap` is accepted and carried on the resolved options, but nothing runs
+yet — `@frmwrkd/snag-repomap` is milestone M3 and is not a dependency of this package.
+The option exists so that a user's config does not need to change when it lands.
+
+---
+
+## Tests
+
+```bash
+pnpm --filter @frmwrkd/snag-anchor test
+```
+
+Fixtures live in `fixtures/` (see `fixtures/README.md`). The assertion that
+matters is in `packages/anchor/test/helpers/anchors.ts`: every emitted
+`data-snag` is read back out of the transformed output, the file it names is
+opened at the line and column it names, and the element's opening tag has to
+really be there. A snapshot can lock in an off-by-one for ever; reading the file
+back cannot.

package/dist/babel/component-name.d.ts

@@ -0,0 +1,42 @@
+/**
+ * "Set `data-snag-cmp` to the **nearest enclosing function/component name**"
+ * — doc 02 §2.2, rule 2.
+ *
+ * This is the second of the two rules, kept deliberately separate from the
+ * `data-snag` path rule: the path says *where the tag is written*, the
+ * component name says *what owns it*. They answer different questions and one
+ * can be present without the other (`production: 'minimal'` emits only the
+ * name).
+ *
+ * ## Why the *nearest named* scope and not the nearest scope
+ *
+ * The common React shape is an anonymous callback inside a component:
+ *
+ * ```tsx
+ * function PricingGrid({ plans }) {
+ *   return <ul>{plans.map((plan) => <li key={plan.id}>{plan.name}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * The `<li>`'s nearest enclosing function is the anonymous arrow passed to
+ * `.map()`. Reporting `""` there would be useless, so an unnameable scope is
+ * skipped and the walk continues outward — `<li>` reports `PricingGrid`.
+ *
+ * ## Why this takes an ancestor array rather than a Babel `NodePath`
+ *
+ * There are two call sites — the string-splicing transform (which walks the AST
+ * itself and keeps its own stack) and the real Babel plugin (which has
+ * `path.parentPath`). Both can produce a plain array of ancestor nodes, so the
+ * naming logic lives here once and cannot drift between the two paths.
+ */
+import type { Node } from '@babel/types';
+/**
+ * @param ancestors Ancestors of the JSX element, **outermost first** — index 0
+ *   is `File`, the last entry is the element's direct parent. Scanned from the
+ *   end, so "nearest" means "highest index".
+ * @returns The nearest enclosing nameable function/class scope, or `undefined`
+ *   when there genuinely isn't one. `undefined` means *no attribute is
+ *   emitted*: a missing name is honest, an invented one is not (doc 00 §3).
+ */
+export declare function resolveComponentName(ancestors: readonly Node[]): string | undefined;
+//# sourceMappingURL=component-name.d.ts.map

package/dist/babel/component-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-name.d.ts","sourceRoot":"","sources":["../../src/babel/component-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,GAAG,SAAS,CAQnF"}

package/dist/babel/component-name.js

@@ -0,0 +1,107 @@
+/**
+ * @param ancestors Ancestors of the JSX element, **outermost first** — index 0
+ *   is `File`, the last entry is the element's direct parent. Scanned from the
+ *   end, so "nearest" means "highest index".
+ * @returns The nearest enclosing nameable function/class scope, or `undefined`
+ *   when there genuinely isn't one. `undefined` means *no attribute is
+ *   emitted*: a missing name is honest, an invented one is not (doc 00 §3).
+ */
+export function resolveComponentName(ancestors) {
+    for (let i = ancestors.length - 1; i >= 0; i -= 1) {
+        const node = ancestors[i];
+        if (node === undefined)
+            continue;
+        const name = nameOfScope(node, ancestors, i);
+        if (name !== undefined && name !== '')
+            return name;
+    }
+    return undefined;
+}
+function nameOfScope(node, ancestors, index) {
+    switch (node.type) {
+        // `function App() {}`, `const App = function App() {}`
+        case 'FunctionDeclaration':
+        case 'FunctionExpression':
+            return node.id?.name ?? nameFromHost(ancestors, index);
+        // `const App = () => <div/>`, `memo(() => <div/>)`
+        case 'ArrowFunctionExpression':
+            return nameFromHost(ancestors, index);
+        // A class component. Reached after `ClassMethod` declines to name itself.
+        case 'ClassDeclaration':
+        case 'ClassExpression':
+            return node.id?.name ?? nameFromHost(ancestors, index);
+        // `{ renderRow() { return <tr/> } }`
+        case 'ObjectMethod':
+            return keyName(node.key, node.computed);
+        // `render() { return <div/> }` inside a class — the *class* is the
+        // component, not the method, so decline and let the walk continue outward.
+        case 'ClassMethod':
+        case 'ClassPrivateMethod':
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Derive a name for an anonymous function from whatever it is attached to,
+ * transparently stepping over higher-order wrappers.
+ *
+ * `const PromoField = memo(forwardRef((props, ref) => <input/>))` must resolve
+ * to `PromoField`: the arrow's parent is a `CallExpression`, whose parent is
+ * another `CallExpression`, whose parent is the `VariableDeclarator` that
+ * actually carries the name. Anything that is not a recognised wrapper stops
+ * the search rather than guessing.
+ */
+function nameFromHost(ancestors, index) {
+    for (let i = index - 1; i >= 0; i -= 1) {
+        const parent = ancestors[i];
+        if (parent === undefined)
+            return undefined;
+        switch (parent.type) {
+            case 'VariableDeclarator':
+                return parent.id.type === 'Identifier' ? parent.id.name : undefined;
+            case 'ObjectProperty':
+                return keyName(parent.key, parent.computed);
+            case 'ClassProperty':
+                return keyName(parent.key, parent.computed);
+            case 'ClassPrivateProperty':
+                return parent.key.id.name;
+            case 'AssignmentExpression':
+                return assignmentTargetName(parent.left);
+            // Higher-order wrappers and type-only nodes: keep walking outward.
+            case 'CallExpression':
+            case 'NewExpression':
+            case 'ParenthesizedExpression':
+            case 'TSAsExpression':
+            case 'TSSatisfiesExpression':
+            case 'TSNonNullExpression':
+            case 'TSTypeAssertion':
+            case 'TSInstantiationExpression':
+            case 'TypeCastExpression':
+                continue;
+            default:
+                return undefined;
+        }
+    }
+    return undefined;
+}
+function keyName(key, computed) {
+    if (computed)
+        return undefined;
+    if (key.type === 'Identifier')
+        return key.name;
+    if (key.type === 'StringLiteral')
+        return key.value;
+    if (key.type === 'PrivateName')
+        return key.id.name;
+    return undefined;
+}
+function assignmentTargetName(left) {
+    if (left.type === 'Identifier')
+        return left.name;
+    if (left.type === 'MemberExpression' && !left.computed && left.property.type === 'Identifier') {
+        return left.property.name;
+    }
+    return undefined;
+}
+//# sourceMappingURL=component-name.js.map

package/dist/babel/component-name.js.map

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

package/dist/babel/plugin.d.ts

@@ -0,0 +1,69 @@
+import type { ParserPlugin } from '@babel/parser';
+import type { JSXOpeningElement, Node } from '@babel/types';
+import type { PluginObj, PluginPass } from '@babel/core';
+import type { AnchorMode } from '../options.js';
+import type { AnchorSourceMap, StampContext, StampSite } from '../stamp.js';
+export type { AnchorAttribute, AnchorSourceMap, StampContext, StampSite } from '../stamp.js';
+export { buildAttributes, escapeAttributeValue } from '../stamp.js';
+/**
+ * Babel's own `isCompatTag`: a JSX identifier is an intrinsic host element iff
+ * it starts with a lowercase ASCII letter. `<div>` and `<my-widget>` are
+ * intrinsic; `<Foo>`, `<_Foo>`, `<Foo.Bar>` and `<svg:circle>` are not.
+ */
+export declare function isIntrinsicTagName(name: string): boolean;
+export interface TagInfo {
+    tag: string;
+    intrinsic: boolean;
+}
+export declare function tagInfo(name: JSXOpeningElement['name']): TagInfo | null;
+export declare function hasAttribute(node: JSXOpeningElement, attribute: string): boolean;
+/**
+ * doc 02 §2.2: "Skip if a `data-snag` attribute already exists (user override
+ * wins)." Extended to the component attribute too, so `production: 'minimal'`
+ * — where `data-snag` is never emitted — respects an override just the same.
+ */
+export declare function shouldStamp(node: JSXOpeningElement, ctx: StampContext): boolean;
+export declare function parserPluginsFor(filename: string): ParserPlugin[];
+/**
+ * Collect every stamp site in an already-parsed file, in source order.
+ *
+ * The insertion offset is the end of the **last existing attribute**, or the
+ * end of the tag name when there are none. That places the injected attribute
+ * last, after any `{...props}` spread, so the stamp always wins: an element
+ * that receives a forwarded `data-snag` from a parent still reports the line it
+ * is actually written on. It also sidesteps arithmetic on `/>` vs `>`.
+ */
+export declare function collectStampSites(ast: Node, ctx: StampContext): StampSite[];
+export interface StampResult {
+    code: string;
+    map: AnchorSourceMap;
+    sites: StampSite[];
+}
+/**
+ * Transform a JSX/TSX source string.
+ *
+ * Returns `null` when nothing was stamped **and** when the file could not be
+ * parsed. A source transform that throws breaks the user's dev server; this one
+ * fails open and leaves the file exactly as it found it. The cost of a missed
+ * anchor is a tier-3 fallback; the cost of a thrown error is a broken build.
+ */
+export declare function stampJsx(code: string, ctx: StampContext, filename?: string): StampResult | null;
+export interface SnagBabelPluginOptions {
+    attribute?: string;
+    componentAttribute?: string;
+    intrinsicOnly?: boolean;
+    mode?: AnchorMode;
+    /** Repo-relative path override. Derived from the filename + `root` when absent. */
+    file?: string;
+    /** Absolute project root. Defaults to git-root detection from `process.cwd()`. */
+    root?: string;
+}
+/**
+ * `@frmwrkd/snag-anchor/babel` — usable directly in a `babel.config.js`:
+ *
+ * ```js
+ * plugins: [['@frmwrkd/snag-anchor/babel', { mode: 'full' }]]
+ * ```
+ */
+export default function snagAnchorBabelPlugin(): PluginObj<PluginPass>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/babel/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/babel/plugin.ts"],"names":[],"mappings":"AAuDA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI5E,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIpE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,OAAO,GAAG,IAAI,CAsBvE;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAW/E;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAajE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,GAAG,SAAS,EAAE,CA2B3E;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA6B/F;AAID,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAeD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,IAAI,SAAS,CAAC,UAAU,CAAC,CAiDrE"}