@thinkingos/vsl-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1280 @@
+/**
+ * DOM extraction (T1.1.2, ROADMAP.md M1.1).
+ *
+ * Обходит дерево от корня (по умолчанию document.body) и извлекает все видимые
+ * элементы с координатами (getBoundingClientRect), собственным текстом, атрибутами и CSS-подмножеством (Level 3, T1.5.1).
+ * Покрывает тот же набор элементов, что и root.querySelectorAll('*'), минус отфильтрованные.
+ *
+ * Фильтр невидимых (семантика ARCHITECTURE.md; CSS-уровень 3 вне scope M1.1):
+ *  - непрендеримые теги (script/style/link/meta/noscript/template/head/title/base) —
+ *    никогда не отрисовываются → пропуск поддерева;
+ *  - display: none → элемент и всё поддерево не отрисованы → пропуск поддерева;
+ *  - visibility: hidden → сам элемент невидим, но дети могут быть видимы
+ *    (visibility: visible) → элемент не включается, поддерево обходится;
+ *  - нулевой прямоугольник (width <= 0 || height <= 0) → нет видимого бокса, но дети
+ *    (например, overflow) могут быть видимы → элемент не включается, поддерево обходится.
+ *
+ * indexPath — индексы среди ЭЛЕМЕНТНЫХ детей на каждом уровне, вычисляются по
+ * структуре DOM ДО фильтрации: позиция стабильна независимо от фильтров — основа
+ * детерминированных ID VSL (решение note_1789916091535: без Date.now()/Math.random(),
+ * база для diffing в M1.2).
+ */
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ExtractedElement {
+    /** Имя тега в нижнем регистре (например, 'button'). */
+    tag: string;
+    /** Путь от корня обхода: индексы среди элементных детей каждого уровня (до фильтрации). */
+    indexPath: number[];
+    /** Координаты и размеры из getBoundingClientRect (px, viewport). */
+    rect: Rect;
+    /** Собственный текст (только прямые текстовые узлы), нормализованный; null если пуст. */
+    text: string | null;
+    /** Все атрибуты элемента (verbatim). */
+    attributes: Record<string, string>;
+    /** CSS-подмножество для Level 3 (computed styles в момент extraction, T1.5.1). */
+    css?: ElementCss;
+    /** Видимые дочерние элементы. */
+    children: ExtractedElement[];
+}
+/**
+ * CSS-подмножество для Segmentation Level 3 (T1.5.1): computed styles,
+ * захваченные в момент extraction (viewOf/getComputedStyle). Все поля
+ * optional: отсутствие значения или поддержки свойства средой → поле
+ * просто не задано.
+ */
+interface ElementCss {
+    cursor?: string;
+    position?: string;
+    top?: string;
+    bottom?: string;
+    display?: string;
+    gap?: string;
+    fontWeight?: string;
+    fontSize?: string;
+    opacity?: string;
+    pointerEvents?: string;
+    overflow?: string;
+    height?: string;
+}
+/** Собственный текст элемента: только прямые текстовые узлы, whitespace-нормализация. */
+declare function ownText(el: Element): string;
+/**
+ * Извлекает видимое поддерево DOM, начиная с root (по умолчанию document.body).
+ * Сам root не включается — возвращается лес его видимых потомков.
+ */
+declare function extractDomTree(root?: Element): ExtractedElement[];
+
+/**
+ * Типы VSL JSON (DESIGN_SYSTEM.md §4, ARCHITECTURE.md §2.3).
+ */
+/**
+ * Семантический тип объекта VSL (поле `t`): L1-теги + L2-роли (T1.1.3/T1.1.4),
+ * L3-CSS (T1.5.1), L4-структурные (T1.5.2), L5-vision (T1.5.4).
+ */
+type VslType = 'button' | 'input' | 'link' | 'nav' | 'header' | 'main' | 'container' | 'image' | 'select' | 'textarea' | 'modal' | 'tab' | 'heading' | 'footer' | 'scrollable_container' | 'toolbar' | 'list' | 'grid' | 'form_field' | 'tab_bar' | 'layout' | 'icon' | 'chart' | 'custom_widget' | 'unknown';
+/** Состояние объекта VSL (поле `st`) — из ARIA-атрибутов (T1.1.4). */
+type VslState = 'checked' | 'expanded' | 'disabled';
+/** Тип визуального фрагмента — выход классификации vision (§2.2.2 Шаг 2). */
+type VisualFragmentType = 'image' | 'icon' | 'chart' | 'custom_widget' | 'unknown';
+/** Метаданные visual fragment (DESIGN_SYSTEM.md §4.4). */
+interface VslFragmentMeta$1 {
+    type?: string;
+    format?: string;
+    size?: [number, number];
+    hash?: string;
+    cached_at?: string;
+}
+/**
+ * Запись реестра visual_fragments документа (§2.2.2, ARCHITECTURE.md:L265-284).
+ * ТОЛЬКО метаданные: base64-данные изображений живут в VisualFragmentStore
+ * (src/llm/types.ts, DEC-015) и подаются по запросу (lazy loading §4.4) —
+ * документ остаётся в бюджете 10-100 KB (ARCHITECTURE.md:L16-18).
+ */
+interface VisualFragment {
+    /** Тип фрагмента (§2.2.2 Шаг 2). */
+    type: VisualFragmentType;
+    /** Формат закодированных данных (например, 'webp'). */
+    format: string;
+    /** Размер [ширина, высота] в px. */
+    size: [number, number];
+    /** Хэш кэша hash(bounding_box + pixel_content) — ключ инвалидации (§5.2). */
+    hash?: string;
+    /** ISO 8601 — время кэширования. */
+    cached_at?: string;
+    /** Эмбеддинг (512-dim CLIP) — контракт §2.2.2; в M1.5 не заполняется. */
+    embedding?: number[];
+}
+/** Версия формата VSL (DESIGN_SYSTEM.md §4.1). */
+declare const VSL_VERSION: "1.0.0";
+interface VslViewport {
+    width: number;
+    height: number;
+    unit: 'px';
+}
+interface VslCanvas {
+    viewport: VslViewport;
+    background: string;
+    scale: number;
+    orientation: 'landscape' | 'portrait';
+    /** ISO 8601; для детерминизма тестов фиксируется через BuildOptions. */
+    timestamp: string;
+    url?: string;
+    title?: string;
+}
+interface VslObject {
+    /** Детерминированный ID из DOM-пути (note_1789916091535, база M1.2 diff). */
+    id: string;
+    t: VslType;
+    /** Роль (атрибут role), уточняет семантику. */
+    r?: string;
+    /** Позиция [x, y] — относительные координаты 0.0–1.0 от viewport. */
+    p: [number, number];
+    /** Размер [width, height] в px. */
+    s: [number, number];
+    st?: VslState;
+    txt?: string;
+    /** Preview длинного текста (первые ~50 символов) — lazy text loading (M1.7, DEC-026). */
+    txt_preview?: string;
+    /** Ссылка на полный текст в text_blocks документа — lazy text loading (M1.7, DEC-026). */
+    txt_ref?: string;
+    act?: string[];
+    ch?: VslObject[];
+    /** Ссылка на визуальный фрагмент (§2.2.2) — ключ в visual_fragments документа. */
+    vf?: string;
+    /** Метаданные фрагмента (§4.4). */
+    vf_meta?: VslFragmentMeta$1;
+}
+interface VslDocument {
+    vsl_version: string;
+    canvas: VslCanvas;
+    objects: VslObject[];
+    /**
+     * Реестр визуальных фрагментов (§2.2.2): ключ — vf-ссылка объекта
+     * (инвариант: каждый vf объекта — ключ этой map). Только метаданные:
+     * base64-данные изображений живут в VisualFragmentStore (src/llm/types.ts,
+     * DEC-015) и подаются по запросу (lazy loading §4.4) — документ остаётся
+     * в бюджете 10-100 KB (ARCHITECTURE.md:L16-18). Optional: документы
+     * без фрагментов валидны (обратно-совместимость).
+     */
+    visual_fragments?: Record<string, VisualFragment>;
+    /**
+     * Кэш полных текстов для lazy text loading (M1.7, DEC-026): ключ — txt_ref
+     * объекта (формат tb_xxx, инкрементный счётчик). Значение — полный текст.
+     * Только для элементов с txt > 200 символов. Optional: документы без
+     * текстовых блоков валидны (обратно-совместимость).
+     */
+    text_blocks?: Record<string, string>;
+}
+
+/**
+ * Segmentation Level 1: семантические теги (T1.1.3, ROADMAP.md M1.1).
+ *
+ * Контракт — таблица «Уровень 1: Семантические теги» из ARCHITECTURE.md:
+ * ровно 10 тегов, покрывающих ~40% элементов типичной страницы. Теги вне
+ * таблицы (div/span/p/footer/…) НЕ классифицируются на этом уровне —
+ * их семантика, если есть, добавляется Level 2 (ARIA) в T1.1.4.
+ *
+ * Функция чистая и детерминированная: (тег) → тип VSL | null.
+ */
+
+/** Таблица маппинга HTML-тегов (нижний регистр) → семантические типы VSL. */
+declare const LEVEL1_TAG_MAP: Readonly<Record<string, VslType>>;
+/**
+ * Возвращает семантический тип VSL для HTML-тега по таблице Level 1
+ * или null, если тег на этом уровне не классифицируется.
+ * Регистр тега не учитывается (защита от tagName в любом регистре).
+ */
+declare function resolveLevel1Type(tag: string): VslType | null;
+
+/**
+ * Segmentation Level 2: ARIA-атрибуты (T1.1.4, ROADMAP.md M1.1).
+ *
+ * Контракт — таблица «Уровень 2: ARIA-атрибуты» из ARCHITECTURE.md:
+ *  - role → тип VSL (button / dialog→modal / tab / tabpanel→container);
+ *  - aria-label → txt (доступное имя элемента);
+ *  - aria-pressed / aria-expanded / aria-disabled = "true" → st
+ *    (checked / expanded / disabled);
+ *  - aria-hidden="true" → элемент декоративный (обрезается в segmenter.ts).
+ *
+ * L2 дополняет L1: тип из ARIA-роли применяется только если тег не дал типа.
+ */
+
+/** Таблица маппинга ARIA-ролей (нижний регистр) → типы VSL. */
+declare const ARIA_ROLE_TYPE_MAP: Readonly<Record<string, VslType>>;
+/**
+ * Возвращает тип VSL по ARIA-роли или null, если роль не из контракта
+ * (или роли нет). Регистр не учитывается.
+ */
+declare function resolveAriaRoleType(role: string | undefined): VslType | null;
+/**
+ * Состояние VSL из ARIA-атрибутов. По контракту маппируется только точное
+ * значение "true" ("false"/"mixed"/прочее → null). При нескольких состояниях
+ * приоритет — порядок таблицы контракта: checked → expanded → disabled.
+ */
+declare function resolveSt(attributes: Record<string, string>): VslState | null;
+
+/**
+ * Segmentation Engine: объединение уровней 1-4 (T1.1.3/T1.1.4/T1.5.1/T1.5.2).
+ *
+ * Обходит ExtractedElement-дерево (domExtractor) и аннотирует каждый элемент:
+ *  - t: приоритет L1 (тег) → L2 (ARIA-роль) → L3 (CSS-паттерны) → L4
+ *    (структурные паттерны по геометрии уже аннотированных детей); null —
+ *    не классифицирован (включение и типизация контейнеров — решение
+ *    VSL Builder, T1.1.5);
+ *  - txt: aria-label (приоритет по семантике доступного имени) ?? собственный текст;
+ *  - st: состояние из aria-pressed/expanded/disabled ("true" only).
+ *
+ * Skip-поддеревья (элемент не попадает в VSL вместе с поддеревом):
+ *  - aria-hidden="true" — декоративный по семантике accessibility-дерева;
+ *  - opacity:0 + pointer-events:none — визуально невидимый (L3,
+ *    isPointerInvisible).
+ *
+ * L4 применяется после рекурсивной обработки детей: структурные паттерны
+ * (toolbar/list/grid/form_field/tab_bar/layout) анализируют t детей.
+ */
+
+interface SegmentedElement {
+    tag: string;
+    indexPath: number[];
+    rect: Rect;
+    /** Атрибуты verbatim (нужны Builder для умных дефолтов act и валидации). */
+    attributes: Record<string, string>;
+    /** Тип VSL: приоритет L1 > L2 > L3 > L4; null — не классифицирован. */
+    t: VslType | null;
+    /** Текст: aria-label ?? собственный текст; null, если нет ни того, ни другого. */
+    txt: string | null;
+    /** Состояние из ARIA (checked/expanded/disabled) или null. */
+    st: VslState | null;
+    ch: SegmentedElement[];
+    /** Ссылка на визуальный фрагмент (заполняется enrichWithVision, T1.5.4). */
+    vf?: string;
+    /** Метаданные фрагмента (§4.4). */
+    vf_meta?: VslFragmentMeta$1;
+}
+/** Элемент декоративен (aria-hidden="true") → в VSL не включается. */
+declare function isAriaHidden(attributes: Record<string, string>): boolean;
+/**
+ * Аннотирует видимое дерево (результат extractDomTree) семантикой L1-L4,
+ * обрезая skip-поддеревья (aria-hidden, isPointerInvisible). Порядок
+ * элементов сохраняется. L4 анализирует геометрию детей ПОСЛЕ их
+ * аннотирования (post-order по t).
+ */
+declare function segmentTree(elements: readonly ExtractedElement[]): SegmentedElement[];
+
+/**
+ * VSL Builder (T1.1.5, ROADMAP.md M1.1; контракт ARCHITECTURE.md §2.3).
+ *
+ * Вход: семантическое дерево от Segmentation Engine (segmentTree).
+ * Выход: VSL JSON по DESIGN_SYSTEM.md §4 (vsl_version, canvas, objects tree).
+ *
+ * Отбор элементов — эвристика Semantic Density (ARCHITECTURE.md) в адаптации
+ * к L1/L2-сегментации:
+ *  - t !== null (типизирован L1/L2) → семантический объект, включается;
+ *  - t === null → score = role(3) + aria-label(2) + interactive-атрибуты(2) +
+ *    txt(1) + включённые дети(1); score >= 3 → контейнер;
+ *  - t === null и есть включённые потомки → контейнер-обёртка (обобщение
+ *    контракта «== 0 с семантическими детьми → grouping» на зазор 1–2);
+ *  - иначе — декоративный, пропускается вместе с поддеревом.
+ *
+ * Детерминизм (решение для M1.2 Cache/Diff): id = tag_indexPath из DOM-пути,
+ * без Date.now()/Math.random(); timestamp/url/title фиксируются через
+ * BuildOptions (в тестах — обязательно).
+ */
+
+/** Опции сборки: для детерминированных тестов фиксируйте timestamp/url/title. */
+interface BuildOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    background?: string;
+    timestamp?: string;
+    url?: string;
+    title?: string;
+}
+/**
+ * Строит VSL JSON из семантического дерева (segmentTree) по DESIGN_SYSTEM §4.
+ * Viewport фиксируется один раз на всю сборку — p-нормализация консистентна.
+ */
+declare function buildVslDocument(elements: readonly SegmentedElement[], options?: BuildOptions): VslDocument;
+
+/**
+ * Cache Store (T1.2.1, ROADMAP.md M1.2; контракт ARCHITECTURE.md §2.4/§5).
+ *
+ * In-memory Map id → CacheEntry. Запись кэша содержит VslObject и два
+ * детерминированных хэша (решение dc_4):
+ *  - contentHash — содержимое {t, r?, st?, txt?, act?} в порядке канона §4;
+ *  - coordHash   — координаты {p, s}.
+ * id в хэш не входит (он ключ Map), ch не входит (дети отслеживаются
+ * собственными записями). Хэш — sha256 (node:crypto) поверх JSON.stringify
+ * объекта с фиксированным порядком ключей.
+ *
+ * Invalidation (ARCHITECTURE.md §5.2, решение dc_5):
+ *  - invalidate(id) — точечная инвалидация записи;
+ *  - invalidateBySelector — MVP-семантика: '*' → полный сброс; точный id;
+ *    иначе селектор трактуется как тег id ('button' → все 'button_*'), т.к.
+ *    CSS-селекторы к кэшированным VslObject неприменимы (id = tag_indexPath);
+ *  - invalidateCoordinates() — «сброс координат» при viewport resize:
+ *    coordHash всех записей обнуляется, содержимое сохраняется.
+ */
+
+/** Запись кэша: объект VSL + хэши содержимого и координат. */
+interface CacheEntry {
+    /** Кэшированный VslObject (поддерево ch не хранится — дети в своих записях). */
+    object: VslObject;
+    /** sha256 от {t, r?, st?, txt?, act?} в фиксированном порядке ключей. */
+    contentHash: string;
+    /** sha256 от {p, s}; пустая строка — координаты инвалидированы (resize). */
+    coordHash: string;
+}
+/**
+ * contentHash: только смысловые поля, фиксированный порядок t→r→st→txt→act.
+ * Опциональные поля включаются только при наличии — сериализация детерминирована.
+ */
+declare function computeContentHash(object: VslObject): string;
+/** coordHash: только координаты {p, s}. */
+declare function computeCoordHash(object: VslObject): string;
+/** Публичный контракт Cache Store (ROADMAP T1.2.1). */
+interface CacheStore {
+    /** Сохранить объект под явным id (ROADMAP T1.2.1: cache.set(id, element)). */
+    set(id: string, object: VslObject): void;
+    /** Запись по id или undefined. */
+    get(id: string): CacheEntry | undefined;
+    /** Наличие записи. */
+    has(id: string): boolean;
+    /** Точечная инвалидация (§5.2 cache.invalidate). */
+    invalidate(id: string): void;
+    /** MVP-семантика (решение dc_5): '*' | точный id | 'tag' → префикс 'tag_'. */
+    invalidateBySelector(selector: string): void;
+    /** Viewport resize (§5.2 «сброс координат»): обнулить coordHash, объекты сохранить. */
+    invalidateCoordinates(): void;
+    /** Полный сброс (§5.2 cache.clear). */
+    clear(): void;
+    /** Все id в порядке вставки. */
+    keys(): string[];
+    /** Число записей. */
+    readonly size: number;
+}
+declare function createCacheStore(): CacheStore;
+
+/**
+ * Cache invalidation через MutationObserver (T1.2.2, ROADMAP.md M1.2; ARCHITECTURE.md §5.2).
+ *
+ * attachMutationObserver(root, store) подписывается на мутации поддерева root
+ * и точечно инвалидирует записи Cache Store:
+ *  - childList (изменился состав детей) → родительский элемент (его поле ch);
+ *  - attributes → сам целевой элемент;
+ *  - characterData → owner-элемент текстового узла.
+ *
+ * Маппинг element → id воспроизводит арифметику domExtractor + vslBuilder
+ * (id = tag_indexPath): подъём от элемента до root, на каждом уровне — индекс
+ * среди ЭЛЕМЕНТНЫХ детей (Array.from(parent.children)); domExtractor считает
+ * indexPath по живому DOM ДО фильтрации, поэтому индексы совпадают 1:1.
+ * Контракт: root наблюдателя === корень extraction (document.body по умолчанию).
+ *
+ * Если id элемента мутации нет в store — инвалидируется ближайший предок из
+ * store (подъём вверх до root). Root сам не имеет VSL-записи (extractDomTree
+ * не включает корень) → childList на прямых детях root — no-op в MVP.
+ *
+ * Известное MVP-ограничение (соответствует дизайну фикстур dc_6: добавления/
+ * удаления только в конец списков детей): вставка/удаление в середину сдвигает
+ * indexPath последующих сиблингов — их id меняются; точечная инвалидация
+ * «переехавших» записей вне MVP, итоговую консистентность гарантирует diff
+ * по полному переизвлечению (T1.2.4).
+ */
+
+/** Результат attachMutationObserver: наблюдатель + ручная отписка. */
+interface MutationObserverHandle {
+    /** Живой MutationObserver (для тестов и расширенного контроля). */
+    observer: MutationObserver;
+    /** Отписаться от мутаций. */
+    disconnect(): void;
+}
+/**
+ * Подписывает store на мутации поддерева root (§5.2 «DOM mutation observer →
+ * invalidation изменённых элементов»). Возвращает handle с disconnect().
+ */
+declare function attachMutationObserver(root: Element, store: CacheStore): MutationObserverHandle;
+
+/**
+ * Diff Engine (T1.2.3, ROADMAP.md M1.2; формат ARCHITECTURE.md §6.2).
+ *
+ * diffVslDocuments(prev, next, options) сравнивает два VslDocument по ПЛОСКОМУ
+ * индексу id (id = tag_indexPath глобально уникальны — база M1.1) и выдаёт
+ * дифф строго в формате §6.2:
+ *  - added    — новые объекты полными поддеревьями (tree order next);
+ *  - modified — id + только изменившиеся поля в порядке канона §4
+ *    (t→r→p→s→st→txt→act); УДАЛЁННОЕ опциональное поле передаётся явным null
+ *    (r/st/txt/act; решение dc_5: отсутствие в Partial амбивалентно —
+ *    «не изменилось» vs «удалено»); t/p/s/id никогда не null;
+ *  - removed  — {id} в tree order prev;
+ *  - unchanged_refs — id неизменённых объектов (tree order next).
+ *
+ * Равенство объектов — по паре хэшей Cache Store (решение dc_4):
+ * contentHash {t,r?,st?,txt?,act?} + coordHash {p,s}, sha256 по фиксированному
+ * порядку ключей. Поле ch в сравнении НЕ участвует — diff плоский, дети
+ * отслеживаются собственными id: изменение состава/содержимого детей проявляется
+ * их собственными added/removed/modified записями. Canvas не диффуется —
+ * сравнивается только дерево objects.
+ *
+ * Пустой дифф валиден: идентичные документы → все id в unchanged_refs,
+ * остальные списки пусты.
+ *
+ * Предусловие: id уникальны в пределах каждого документа (гарантия M1.1).
+ */
+
+/** Изменившийся объект: id + только изменившиеся поля (порядок канона §4). */
+interface VslModifiedObject {
+    id: string;
+    t?: VslType;
+    /** null = опциональное поле r удалено в next. */
+    r?: string | null;
+    p?: [number, number];
+    s?: [number, number];
+    /** null = состояние st удалено в next. */
+    st?: VslState | null;
+    /** null = текст txt удалён в next. */
+    txt?: string | null;
+    /** null = список действий act удалён в next. */
+    act?: string[] | null;
+}
+/** Удалённый объект: только ссылка на id (§6.2). */
+interface VslRemovedObject {
+    id: string;
+}
+/** Блок changes формата §6.2. */
+interface VslDiffChanges {
+    /** Новые объекты — полные поддеревья, tree order next. */
+    added: VslObject[];
+    /** Изменившиеся объекты, tree order next. */
+    modified: VslModifiedObject[];
+    /** Удалённые объекты, tree order prev. */
+    removed: VslRemovedObject[];
+    /** id неизменённых объектов, tree order next. */
+    unchanged_refs: string[];
+}
+/** Дифф двух VslDocument (формат ARCHITECTURE.md §6.2). */
+interface VslDiff {
+    /** Версия нового состояния (счётчик session). */
+    diff_version: number;
+    /** Версия базового (предыдущего) состояния. */
+    base_version: number;
+    /** ISO 8601. */
+    timestamp: string;
+    changes: VslDiffChanges;
+}
+/** Опции diffVslDocuments: версии заголовка обязательны (явный контракт session). */
+interface DiffOptions {
+    diffVersion: number;
+    baseVersion: number;
+    /** ISO 8601; по умолчанию — текущее время (недетерминированно; в тестах фиксировать). */
+    timestamp?: string;
+}
+/** Сравнивает два VSL-документа и возвращает дифф формата §6.2 (см. шапку модуля). */
+declare function diffVslDocuments(prev: VslDocument, next: VslDocument, options: DiffOptions): VslDiff;
+
+/**
+ * Типы LLM Integration (M1.3, ROADMAP.md T1.3.1–T1.3.5).
+ *
+ * Архитектурная база:
+ *  - ARCHITECTURE.md §2.5 — LLM Integration Layer, промпт-шаблон {vsl_json}+{goal};
+ *  - ARCHITECTURE.md §7 — Action Model, формат ответа LLM (§7.4);
+ *  - ARCHITECTURE.md §9.4 — API адаптеров: decide({vslJson, goal});
+ *  - ARCHITECTURE.md §10.3 — retry 3× exponential backoff;
+ *  - DESIGN_SYSTEM.md §4.4 — visual fragments (vf/vf_meta, forward-compatible);
+ *  - DEC-002 — model-agnostic: адаптеры провайдеров без SDK-зависимостей.
+ *
+ * Транспорт (нативный fetch, node>=18) инъецируется через LlmTransport —
+ * тесты работают на моках без сети (решение пользователя, clarification M1.3).
+ * Ноль runtime-зависимостей: официальные SDK провайдеров НЕ используются.
+ */
+
+/** Вход LLM-адаптера: полный документ или дифф (§2.5, §11.2 — diff-first). */
+type VslInput = VslDocument | VslDiff;
+/** Действие LLM — формат ответа модели (ARCHITECTURE.md §7.4). */
+interface LlmAction {
+    /** Имя действия из Action Model (§7.1–7.3; см. VALID_ACTIONS в llm/actions). */
+    action: string;
+    /** ID элемента-цели в VSL JSON — обязателен для действий с целью. */
+    target_id?: string;
+    /** Значение: текст ввода для type, option для select и т.п. */
+    value?: string | null;
+    /** Объяснение выбора модели (свободный текст). */
+    reasoning?: string;
+}
+/** Нормализованное использование токенов (маппинг из usage провайдера). */
+interface LlmUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/** Ответ провайдера на sendPrompt (T1.3.1): raw-данные БЕЗ валидации. */
+interface LlmResponse {
+    /** Текстовое содержимое ответа (если провайдер его вернул). */
+    text: string | null;
+    /** Raw-объект действия из tool call (валидацию выполняет decide). */
+    action?: unknown;
+    /** Идентификатор модели, сформировавшей ответ. */
+    model: string;
+    usage?: LlmUsage;
+}
+/** Метаданные visual fragment (DESIGN_SYSTEM.md §4.4). */
+interface VslFragmentMeta {
+    type?: string;
+    format?: string;
+    size?: [number, number];
+    hash?: string;
+    cached_at?: string;
+}
+/** Объект VSL с forward-compatible полями visual fragments (§4.4). */
+type VslObjectWithVf = VslObject & {
+    /** Ссылка на визуальный фрагмент (например, «emb_abc123»). */
+    vf?: string;
+    /** Метаданные фрагмента. */
+    vf_meta?: VslFragmentMeta;
+};
+/** Данные изображения фрагмента для мультимодальной подачи (DEC-015). */
+interface VisualFragmentData {
+    /** MIME-тип изображения, например «image/webp». */
+    mediaType: string;
+    /** Base64-данные изображения (без data:-префикса). */
+    data: string;
+}
+/** Стор данных фрагментов: ключ — vf-ссылка объекта («emb_abc123»). */
+type VisualFragmentStore = ReadonlyMap<string, VisualFragmentData>;
+/**
+ * Провайдер-независимая content-часть user-сообщения (T1.5.4, вариант C):
+ * адаптеры маппят её в формат провайдера (OpenAI image_url / Anthropic image
+ * base64-блок); форма image-части совпадает с VisualFragmentData (DEC-015).
+ */
+type LlmContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+};
+/**
+ * Провайдер-независимое определение tool: одна JSON Schema на оба провайдера
+ * (паттерн schema.ts: OpenAI function.parameters / Anthropic input_schema).
+ */
+interface LlmToolDef {
+    /** Имя tool (execute_action / classify_fragment). */
+    name: string;
+    /** Описание для модели. */
+    description: string;
+    /** JSON Schema аргументов. */
+    schema: Record<string, unknown>;
+}
+/** Опции sendPrompt сверх базовых аргументов. */
+interface SendPromptOptions {
+    /**
+     * Данные изображений для vf-ссылок входа: image-блоки включаются
+     * только для ссылок, присутствующих в сторе (lazy loading, §4.4);
+     * без стора подача остаётся текстовой.
+     */
+    visualFragments?: VisualFragmentStore;
+}
+/** Вход decide (ARCHITECTURE.md §9.4). */
+interface DecideInput {
+    /** VSL JSON: VslDocument или VslDiff от VslSnapshotSession. */
+    vslJson: VslInput;
+    /** Цель пользователя на естественном языке. */
+    goal: string;
+    /** Данные изображений для vf-ссылок (см. SendPromptOptions). */
+    visualFragments?: VisualFragmentStore;
+}
+/**
+ * Инъекция HTTP-транспорта: подмножество сигнатуры fetch.
+ * Прод — нативный fetch; тесты — мок (ноль runtime-зависимостей).
+ */
+type LlmTransport = (url: string, init: RequestInit) => Promise<Response>;
+/** Функция задержки (инъекция для детерминированных тестов retry). */
+type Sleep = (ms: number) => Promise<void>;
+/** Конфиг адаптера провайдера (§9.4: new OpenAIAdapter({apiKey, model})). */
+interface LlmAdapterConfig {
+    /** API-ключ провайдера. */
+    apiKey: string;
+    /** Модель; дефолт задаёт адаптер (gpt-4o / claude-sonnet-4-20250514). */
+    model?: string;
+    /** База API; по умолчанию — официальный endpoint провайдера. */
+    baseUrl?: string;
+    /** Попыток при сбоях API (§10.3); по умолчанию 3. */
+    maxRetries?: number;
+    /** Транспорт; по умолчанию — нативный fetch. */
+    transport?: LlmTransport;
+    /** Задержка между retry-попытками (инъекция для детерминированных тестов; §10.3). */
+    sleep?: Sleep;
+}
+/** Абстрактный интерфейс LLM Adapter (ROADMAP.md T1.3.1). */
+interface LlmAdapter {
+    /** Низкий уровень: VSL JSON + задача → ответ провайдера (raw action). */
+    sendPrompt(vslJson: VslInput, task: string, options?: SendPromptOptions): Promise<LlmResponse>;
+    /** Convenience (§9.4): решение для цели с валидацией действия (§7.4). */
+    decide(input: DecideInput): Promise<LlmAction>;
+}
+/** Базовая ошибка LLM-слоя (транспорт/HTTP/формат ответа провайдера). */
+declare class LlmError extends Error {
+    /** HTTP-статус, если ошибка пришла от API (для классификации retry). */
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** Ответ модели не прошёл валидацию: неизвестное действие, невалидный target_id. */
+declare class LlmValidationError extends LlmError {
+    constructor(message: string);
+}
+
+/**
+ * Vision-подсистема (T1.5.3/T1.5.4): порты и типы (§2.2.2).
+ *
+ * Порты (Dependency Inversion) — SDK не зависит от платформы:
+ *  - ViewportCapture: скриншот текущего viewport (chrome.tabs.captureVisibleTab
+ *    в extension background, Playwright screenshot в e2e; jsdom не рендерит —
+ *    в unit-тестах инъекция фейка);
+ *  - FragmentCropper: кроп скриншота по прямоугольнику → WebP base64
+ *    (дефолтная реализация — Image + offscreen canvas в браузере;
+ *    getContext('2d') в jsdom возвращает null — в unit-тестах инъекция фейка);
+ *  - VisionClassifier: классификация визуального фрагмента — реализация M1.5 —
+ *    LlmVisionClassifier через LLM vision API (решение пользователя 24.09.2026);
+ *    CLIP-эмбеддинги — будущие реализации порта (контракт §2.2.2 Шаг 3).
+ *
+ * Кэш фрагментов — по hash(bounding_box + pixel_content) (§2.2.2 Шаг 4):
+ * sync sha256 через createHash (node:crypto / nodeCryptoShim в браузере),
+ * как в cacheStore — переиспользование готового механизма.
+ */
+
+/** Результат классификации фрагмента vision-моделью (§2.2.2 Шаг 2). */
+interface VisionClassification {
+    /** Тип фрагмента: image | icon | chart | custom_widget | unknown. */
+    type: VisualFragmentType;
+    /** Уверенность модели 0..1. */
+    confidence: number;
+    /** Опциональное описание, например «blue submit button with white text». */
+    description?: string;
+}
+/**
+ * Порт классификатора визуальных фрагментов (§2.2.2 Шаг 2).
+ * Реализация M1.5 — LlmVisionClassifier (LLM vision API); unit-тесты — моки.
+ */
+interface VisionClassifier {
+    /**
+     * Классифицирует изображение фрагмента.
+     * @param image Данные изображения (mediaType + base64 без data:-префикса).
+     * @param hint  Контекст элемента (тег/атрибуты) — подсказка модели.
+     */
+    classify(image: VisualFragmentData, hint?: string): Promise<VisionClassification>;
+}
+/**
+ * Порт скриншота текущего viewport (§2.2.2 Шаг 1). Возвращает полный скриншот
+ * как data-URL (например, 'data:image/png;base64,...').
+ * Extension — chrome.tabs.captureVisibleTab; unit-тесты — инъекция фейка.
+ */
+type ViewportCapture = () => Promise<string>;
+/** Результат кропа: данные фрагмента + фактический размер (после клампинга). */
+interface CroppedFragment {
+    /** MIME-тип фактически закодированных данных, например 'image/webp'. */
+    mediaType: string;
+    /** Base64-данные (без data:-префикса). */
+    data: string;
+    /** Фактический размер кропа в px [width, height] — после клампинга к границам скриншота. */
+    size: [number, number];
+}
+/**
+ * Кроп скриншота по прямоугольнику (§2.2.2 Шаг 1: +2px margin применяется
+ * вызывающей стороной; здесь — вырезание области и кодирование WebP q~0.6).
+ * Дефолтная реализация — Image + offscreen canvas (браузер).
+ */
+type FragmentCropper = (screenshot: string, rect: Rect) => Promise<CroppedFragment>;
+
+/**
+ * FragmentExtractor (T1.5.3): извлечение визуальных фрагментов по bounding box.
+ *
+ * Конвейер §2.2.2 Шаг 1 + Шаг 4:
+ *  1. Расширить rect на 2px с каждой стороны (захват border) — expandRect;
+ *  2. capture() — полный скриншот viewport (порт, chrome.tabs.captureVisibleTab);
+ *  3. crop(screenshot, rect) — вырезание области → WebP base64 (порт/дефолт);
+ *  4. hash = sha256('x,y,w,h|data') — hash(bounding_box + pixel_content);
+ *  5. Кэш: hit → та же запись (vfId/cached_at исходные, cached=true —
+ *     классификатор не вызывается повторно, AC[3]); miss → новая запись.
+ *
+ * vfId детерминированный: 'emb_' + первые 12 hex-символов hash — одинаковые
+ * фрагменты (позиция+пиксели) получают один vfId (стабильность в diff-режиме).
+ *
+ * Инъекции (Dependency Inversion): capture обязателен; crop опционален
+ * (дефолт — Image + offscreen canvas браузера; в jsdom getContext('2d')
+ * возвращает null → в unit-тестах инъекция фейка); now опционален
+ * (детерминизм cached_at в тестах). createHash — прямой импорт node:crypto
+ * как в cacheStore (esbuild alias → nodeCryptoShim в extension-сборке).
+ */
+
+/** Метаданные фрагмента в кэше (заполняются полностью при extract). */
+interface FragmentMeta {
+    /** Формат закодированных данных без префикса 'image/' (например, 'webp'). */
+    format: string;
+    /** Фактический размер кропа в px [width, height] (после клампинга). */
+    size: [number, number];
+    /** sha256(expanded_rect + '|' + base64-данные) — ключ кэша (§2.2.2 Шаг 4). */
+    hash: string;
+    /** ISO 8601 — время первого кэширования (сохраняется при cache hit). */
+    cached_at: string;
+}
+/** Запись кэша фрагментов: данные + метаданные + классификация (после enrich). */
+interface FragmentCacheEntry {
+    vfId: string;
+    meta: FragmentMeta;
+    data: VisualFragmentData;
+    /** Классификация — дозаполняется enrichWithVision после classify. */
+    classification?: VisionClassification;
+}
+/** Результат extract: запись кэша + признак «уже была в кэше». */
+interface FragmentExtraction {
+    entry: FragmentCacheEntry;
+    /** true — фрагмент уже был в кэше: классификатор вызывать не нужно (AC[3]). */
+    cached: boolean;
+}
+/** Опции конструктора FragmentExtractor. */
+interface FragmentExtractorOptions {
+    /** Порт скриншота viewport (data-URL), например chrome.tabs.captureVisibleTab. */
+    capture: ViewportCapture;
+    /** Кроп скриншота; дефолт — Image + offscreen canvas (браузер). */
+    crop?: FragmentCropper;
+    /** Часы для cached_at (инъекция для детерминированных тестов). */
+    now?: () => string;
+}
+/**
+ * Извлекатель визуальных фрагментов (T1.5.3). Stateful: держит кэш
+ * hash → запись (§2.2.2 Шаг 4). Экземпляр живёт столько же, сколько сессия
+ * снапшотов (кэш переживает повторные snapshot() той же страницы).
+ */
+declare class FragmentExtractor {
+    private readonly capture;
+    private readonly crop;
+    private readonly now;
+    private readonly cache;
+    constructor(options: FragmentExtractorOptions);
+    /** Число записей в кэше (для тестов и диагностики). */
+    get size(): number;
+    /**
+     * Извлекает визуальный фрагмент по прямоугольнику: capture → crop(+2px
+     * margin) → hash → кэш. Возвращает null для пустой геометрии (нулевые
+     * размеры или кроп полностью вне скриншота). Ошибки capture/crop не
+     * глушатся — их обрабатывает enrichWithVision (vision — best-effort).
+     */
+    extract(rect: Rect): Promise<FragmentExtraction | null>;
+}
+
+/**
+ * enrichWithVision (T1.5.4, dev_8): async-шаг конвейера ДО buildVslDocument —
+ * Level 5 vision fallback (§2.2.1, ARCHITECTURE.md:L174-202).
+ *
+ * Отбор кандидатов: элементы, которые builder ОТБРОСИТ (t === null и
+ * !isIncludedInVsl — нетипизированный, score < 3, без включённых детей).
+ * Для каждого: extract (bounding box → WebP base64, кэш по hash) → classify
+ * (порт VisionClassifier) → аннотация t + vf/vf_meta НА МЕСТЕ (мутирует
+ * дерево, как segmentTree) — после этого builder включает элемент в VSL
+ * (типизирован), а convert переносит vf/vf_meta в объект (AC[5]).
+ *
+ * Best-effort (vision не должен ломать снапшот): ошибки extract/classify
+ * одного элемента не роняют обогащение — элемент остаётся отброшенным
+ * (поведение как до vision), ошибка учитывается в failedCount.
+ *
+ * Кэш и AC[3]: запись FragmentCacheEntry возвращается extract по ссылке и
+ * хранит classification — повторный extract того же hash даёт тот же entry,
+ * поэтому классификатор вызывается один раз на фрагмент. Обход СТРОГО
+ * последовательный: параллельный запуск классифицировал бы одинаковые
+ * фрагменты дважды (оба extract завершились бы до первой записи classification).
+ *
+ * Данные изображений НЕ попадают в VslDocument (бюджет 10-100 KB) —
+ * возвращаются в VisualFragmentStore (DEC-015, lazy loading §4.4) для
+ * DecideInput.visualFragments.
+ */
+
+/** Зависимости enrichWithVision (Dependency Inversion — фейки в unit-тестах). */
+interface EnrichWithVisionDeps {
+    /** Классификатор фрагментов (LlmVisionClassifier; в тестах — фейк). */
+    classifier: VisionClassifier;
+    /** Извлекатель фрагментов с кэшем по hash (AC[3]). */
+    extractor: FragmentExtractor;
+}
+
+/**
+ * VSL Snapshot Session (T1.2.4, ROADMAP.md M1.2; ARCHITECTURE.md §2.4/§5.2/§6.3).
+ *
+ * Stateful-фасад над пайплайном capture→segment→build→cache→diff:
+ *  - первый вызов или смена URL → полный VslDocument; кэш очищается и
+ *    заполняется объектами документа; счётчик версий сбрасывается в 1;
+ *  - тот же URL → VslDiff последнего документа против нового (формат §6.2):
+ *    diff_version = version + 1, base_version = version;
+ *  - viewport изменился при том же URL → дополнительно
+ *    store.invalidateCoordinates() — «сброс координат» §5.2, НЕ полный сброс.
+ *
+ * Состояние {lastUrl, lastViewport, lastDocument, version} — в памяти
+ * экземпляра; VslDocument (канон §4) версиями НЕ расширяется.
+ *
+ * Политика кэша — store отражает текущий документ: full → clear + заполнение;
+ * diff → удалённые invalidate, добавленные (поддеревья) и изменённые set из
+ * нового документа; неизменённые остаются кэшированными (после resize — с
+ * обнулённым coordHash: наблюдаемый эффект invalidateCoordinates).
+ *
+ * input.url/viewport/timestamp/background передаются в BuildOptions ЯВНО —
+ * дефолты builder (window.innerWidth/innerHeight/location.href/document.title)
+ * вычислялись бы от глобалов: недетерминированны в тестах и недоступны в Node;
+ * title — из input, иначе root.ownerDocument.title (портативный фолбэк — фикс
+ * packaging-smoke demo:cache-diff).
+ */
+
+/** Результат snapshot(): полный документ (1-й вызов / URL change) или дифф. */
+type SnapshotResult = VslDocument | VslDiff;
+/** Type guard: различение диффа и полного документа (контракт T1.2.4). */
+declare function isVslDiff(result: SnapshotResult): result is VslDiff;
+/**
+ * Результат snapshotWithVision (T1.5.5): снапшот (документ/дифф) + ДАННЫЕ
+ * фрагментов (base64) — стора в документе нет по контракту (DEC-015):
+ * документ несёт только vf/vf_meta, данные идут в decide({visualFragments}).
+ */
+interface VisionSnapshotResult {
+    snapshot: SnapshotResult;
+    fragments: VisualFragmentStore;
+}
+/** Входные параметры снапшота; url/viewport обязательны (инвалидация §5.2). */
+interface SnapshotInput {
+    /** URL страницы: изменение → полный сброс кэша и новый полный документ. */
+    url: string;
+    /** Текущий viewport: изменение при том же URL → сброс координат кэша. */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    title?: string;
+    /** ISO 8601; фиксировать в тестах (детерминизм canvas.timestamp и диффа). */
+    timestamp?: string;
+    background?: string;
+}
+/**
+ * Session-фасад (§2.4 «первый вызов → полный JSON, последующие → дифф»).
+ * Store инъекцией — тесты наблюдают coordHash-инвалидацию напрямую.
+ */
+declare class VslSnapshotSession {
+    private readonly store;
+    private lastUrl;
+    private lastViewport;
+    private lastDocument;
+    private version;
+    constructor(store?: CacheStore);
+    /**
+     * Строит VSL из DOM поддерева root (extractDomTree → segmentTree →
+     * buildVslDocument) и возвращает полный документ либо дифф (см. шапку).
+     */
+    snapshot(root: Element, input: SnapshotInput): SnapshotResult;
+    /**
+     * Vision-вариант конвейера (T1.5.5): segmentTree → enrichWithVision (Level 5
+     * fallback — аннотация t + vf/vf_meta на элементах ДО сборки) → buildVslDocument
+     * → cache/diff — та же логика состояния, что snapshot(). Синхронный snapshot()
+     * сохранён (существующие контракты/тесты не ломаются); данные фрагментов
+     * (base64) возвращаются ОТДЕЛЬНО — в документе только метаданные (DEC-015).
+     */
+    snapshotWithVision(root: Element, input: SnapshotInput, vision: EnrichWithVisionDeps): Promise<VisionSnapshotResult>;
+    /** BuildOptions из input + портативный title (логика бывшего snapshot()). */
+    private buildOptions;
+    /** Сборка документа + кэш/дифф (логика бывшего snapshot(), см. шапку модуля). */
+    private commit;
+}
+
+/**
+ * OpenAI adapter (T1.3.2): Chat Completions API + function calling
+ * (tools/tool_choice «execute_action») без официального SDK — нативный fetch
+ * через инъекцию транспорта (ноль runtime-зависимостей, DEC-002).
+ *
+ * Retry (AC[8], §10.3): executeJsonWithRetry — до 3 попыток, только
+ * сеть/429/5xx. Мультимодальность (AC[7], §4.4): vf-ссылки из входа при
+ * наличии данных в сторе превращаются в content-части
+ * {type: 'image_url', image_url: {url: 'data:<mediaType>;base64,<data>'}}.
+ */
+
+/**
+ * Адаптер OpenAI (gpt-4o / gpt-4o-mini): system prompt + VSL JSON (§2.5)
+ * → tool call «execute_action» с действием §7.4.
+ */
+declare class OpenAIAdapter implements LlmAdapter {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly transport;
+    private readonly sleep;
+    constructor(config: LlmAdapterConfig);
+    sendPrompt(vslJson: VslInput, task: string, options?: SendPromptOptions): Promise<LlmResponse>;
+    /**
+     * Низкоуровневый вызов (T1.5.4, вариант C): провайдер-независимые аргументы
+     * → Chat Completions → LlmResponse. Потребители: sendPrompt (tool
+     * «execute_action») и LlmVisionClassifier (tool «classify_fragment»).
+     * Retry (§10.3) и парсинг tool_calls живут здесь в одном месте.
+     */
+    sendRaw(system: string, userContent: readonly LlmContentPart[], tool: LlmToolDef): Promise<LlmResponse>;
+    /** Convenience §9.4: решение для цели + валидация (whitelist + target_id). */
+    decide(input: DecideInput): Promise<LlmAction>;
+}
+
+/**
+ * Anthropic adapter (T1.3.3): Messages API (/v1/messages) + tool use
+ * (tools/tool_choice «execute_action») без официального SDK — нативный fetch
+ * через инъекцию транспорта (ноль runtime-зависимостей, DEC-002).
+ *
+ * Retry (AC[8], §10.3): executeJsonWithRetry — до 3 попыток, только
+ * сеть/429/5xx. Мультимодальность (AC[7], §4.4): vf-ссылки из входа при
+ * наличии данных в сторе превращаются в content-блоки
+ * {type: 'image', source: {type: 'base64', media_type, data}}.
+ */
+
+/**
+ * Адаптер Anthropic (claude-sonnet-4-20250514): system prompt + VSL JSON (§2.5)
+ * → tool_use «execute_action» с действием §7.4.
+ */
+declare class AnthropicAdapter implements LlmAdapter {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly maxTokens;
+    private readonly maxRetries;
+    private readonly transport;
+    private readonly sleep;
+    constructor(config: LlmAdapterConfig);
+    sendPrompt(vslJson: VslInput, task: string, options?: SendPromptOptions): Promise<LlmResponse>;
+    /**
+     * Низкоуровневый вызов (T1.5.4, вариант C): провайдер-независимые аргументы
+     * → Messages API → LlmResponse. Потребители: sendPrompt (tool
+     * «execute_action») и LlmVisionClassifier (tool «classify_fragment»).
+     * tool_use-блоки фильтруются по tool.name (ранее — константа ACTION_TOOL_NAME):
+     * параметризация безопасна, sendPrompt передаёт ACTION_TOOL_NAME.
+     */
+    sendRaw(system: string, userContent: readonly LlmContentPart[], tool: LlmToolDef): Promise<LlmResponse>;
+    /** Convenience §9.4: решение для цели + валидация (whitelist + target_id). */
+    decide(input: DecideInput): Promise<LlmAction>;
+}
+
+/**
+ * Alibaba/Qwen adapter (DashScope API, OpenAI-compatible): Chat Completions API
+ * + function calling (tools/tool_choice «execute_action») без официального SDK —
+ * нативный fetch через инъекцию транспорта (ноль runtime-зависимостей, DEC-002).
+ *
+ * DashScope compatible-mode endpoint: https://dashscope.aliyuncs.com/compatible-mode/v1
+ * Формат запроса/ответа идентичен OpenAI (chat/completions, tool_calls).
+ *
+ * Модель по умолчанию: qwen3.8-flash — самая быстрая и дешёвая модель Qwen (09.2026).
+ * Используется для vision-backend (классификация visual fragments).
+ *
+ * Retry (AC[8], §10.3): executeJsonWithRetry — до 3 попыток, только
+ * сеть/429/5xx. Мультимодальность (AC[7], §4.4): vf-ссылки из входа при
+ * наличии данных в сторе превращаются в content-части
+ * {type: 'image_url', image_url: {url: 'data:<mediaType>;base64,<data>'}}.
+ */
+
+/**
+ * Адаптер Alibaba/Qwen (qwen3.8-flash): system prompt + VSL JSON (§2.5)
+ * → tool call «execute_action» с действием §7.4.
+ *
+ * DashScope compatible-mode — OpenAI-compatible API, формат запроса/ответа
+ * идентичен OpenAI (chat/completions, tools, tool_choice, tool_calls).
+ */
+declare class AlibabaAdapter implements LlmAdapter {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly transport;
+    private readonly sleep;
+    constructor(config: LlmAdapterConfig);
+    sendPrompt(vslJson: VslInput, task: string, options?: SendPromptOptions): Promise<LlmResponse>;
+    /**
+     * Низкоуровневый вызов (T1.5.4, вариант C): провайдер-независимые аргументы
+     * → DashScope Chat Completions → LlmResponse. Потребители: sendPrompt (tool
+     * «execute_action») и LlmVisionClassifier (tool «classify_fragment»).
+     * Retry (§10.3) и парсинг tool_calls живут здесь в одном месте.
+     */
+    sendRaw(system: string, userContent: readonly LlmContentPart[], tool: LlmToolDef): Promise<LlmResponse>;
+    /** Convenience §9.4: решение для цели + валидация (whitelist + target_id). */
+    decide(input: DecideInput): Promise<LlmAction>;
+}
+
+/**
+ * Action Model (ARCHITECTURE.md §7) для M1.3: канонический список действий,
+ * классификация по цели и валидация ответа LLM (§7.4, T1.3.5).
+ *
+ * Валидация (§7.4 «Action Executor», п.1): action — валидное действие,
+ * target_id существует в поданном VSL JSON. Поля value/reasoning проходят
+ * сквозь с мягкой нормализацией типов (string | null).
+ */
+
+/**
+ * Канонический список действий Action Model (§7.1–7.3) — 24 действия:
+ * базовые (10) + расширенные (9) + навигационные (4) + download (1).
+ */
+declare const VALID_ACTIONS: readonly ["click", "type", "clear", "scroll", "hover", "focus", "blur", "select", "check", "uncheck", "drag", "drop", "submit", "reset", "open", "close", "expand", "collapse", "wait", "navigate", "go_back", "go_forward", "refresh", "download"];
+/** Имя валидного действия Action Model. */
+type ValidAction = (typeof VALID_ACTIONS)[number];
+/**
+ * Собирает множество валидных target_id из входа LLM (§7.4 валидация):
+ *  - VslDocument — все id рекурсивно;
+ *  - VslDiff — added (рекурсивно) + modified + unchanged_refs;
+ *    removed НЕ включаются: элементы удалены и не могут быть целью.
+ */
+declare function collectIds(vslJson: VslInput): ReadonlySet<string>;
+/**
+ * Валидирует raw-объект действия из tool call модели (§7.4):
+ *  - action — строка из VALID_ACTIONS;
+ *  - для TARGET_ACTIONS target_id обязателен и должен присутствовать в validIds;
+ *  - value/reasoning — passthrough с мягкой нормализацией (string | null);
+ *    target_id у действий без цели игнорируется.
+ * Бросает LlmValidationError при нарушении любого условия.
+ */
+declare function validateAction(raw: unknown, validIds: ReadonlySet<string>): LlmAction;
+
+/**
+ * JSON Schema tool «execute_action» (T1.3.4) — одна схема для обоих провайдеров:
+ *  - OpenAI function calling: tools[0].function.parameters;
+ *  - Anthropic tool use: tools[0].input_schema.
+ * Список действий — enum из VALID_ACTIONS (actions.ts): единый источник правды
+ * с system prompt. Формат аргументов — §7.4 {action, target_id, value, reasoning}.
+ */
+/** Имя tool, через которое модель возвращает действие. */
+declare const ACTION_TOOL_NAME: "execute_action";
+/** Описание tool для моделей. */
+declare const ACTION_TOOL_DESCRIPTION = "Execute exactly one next browser action toward the user goal.";
+/**
+ * JSON Schema аргументов tool (подмножество Draft 2020-12, совместимое
+ * с OpenAI function calling и Anthropic tool use).
+ */
+declare const ACTION_TOOL_SCHEMA: {
+    type: string;
+    properties: {
+        action: {
+            type: string;
+            description: string;
+            enum: ("select" | "click" | "close" | "type" | "check" | "uncheck" | "clear" | "scroll" | "hover" | "focus" | "blur" | "drag" | "drop" | "submit" | "reset" | "open" | "expand" | "collapse" | "wait" | "navigate" | "go_back" | "go_forward" | "refresh" | "download")[];
+        };
+        target_id: {
+            type: string;
+            description: string;
+        };
+        value: {
+            type: string[];
+            description: string;
+        };
+        reasoning: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+
+/**
+ * Промпты LLM (T1.3.4): system prompt (VSL-формат + Action Model + 3 few-shot)
+ * и user-промпт по каноническому шаблону ARCHITECTURE.md §2.5.
+ *
+ * Промпты провайдер-независимы: few-shot включены ТЕКСТОМ в system prompt,
+ * поэтому OpenAI (function calling) и Anthropic (tool use) получают идентичную
+ * инструкцию; само действие модель возвращает через tool «execute_action»
+ * (см. schema.ts). Список действий рендерится из VALID_ACTIONS (actions.ts) —
+ * единый источник правды для промпта и enum в JSON Schema.
+ *
+ * Примечание (neg note f48a9bda4bd5): llm_prompts_examples.md из корня —
+ * примеры домена scene editing (Phase 4), НЕ заготовка для этого промпта;
+ * текст построен с нуля из ARCHITECTURE §2.5 + §7.
+ */
+
+/** Few-shot пример: заголовок, компактный VSL-фрагмент, цель, действие. */
+interface FewShotExample {
+    title: string;
+    /** Компактный VSL JSON (иллюстративный фрагмент). */
+    vsl: string;
+    goal: string;
+    /** Ожидаемый ответ модели — JSON действия (формат §7.4). */
+    action: string;
+}
+/**
+ * Строит system prompt: описание VSL-формата (включая семантику диффа §6.2),
+ * правила ответа через tool «execute_action», Action Model и 3 few-shot.
+ */
+declare function buildSystemPrompt(): string;
+/** Строит user-промпт по шаблону §2.5: Current screen (VSL JSON) + User goal. */
+declare function buildUserPrompt(vslJson: VslInput, goal: string): string;
+
+/**
+ * HTTP-транспорт и retry для LLM-адаптеров (T1.3.2/T1.3.3, ARCHITECTURE §10.1/§10.3):
+ *  - defaultTransport — нативный fetch (node>=18, ноль runtime-зависимостей);
+ *  - retryWithBackoff — до 3 попыток с exponential backoff (§10.3, 2^attempt секунд);
+ *  - executeJsonWithRetry — запрос + статус-проверка + парс JSON, с retry.
+ *
+ * Retry-политика (уточнение §10.1/§10.3): повторяются ТОЛЬКО сетевые ошибки,
+ * HTTP 429 и 5xx; прочие 4xx — fast-fail (401/403 повтором не чинятся).
+ * Паузы: 1s, 2s перед 2-й и 3-й попыткой (форма 2^attempt секунд из §10.3).
+ * sleep инъецируется (RetryOptions.sleep / LlmAdapterConfig.sleep) —
+ * тесты идут без реальных задержек.
+ */
+
+interface RetryOptions {
+    /** Всего попыток, включая первую (§10.3: 3). Значения <1 приводятся к 1. */
+    maxRetries?: number;
+    /** Задержка между попытками (инъекция для тестов). */
+    sleep?: Sleep;
+}
+/**
+ * Исполняет operation с retry до maxRetries попыток и exponential backoff
+ * 1s/2s/… (§10.3). После исчерпания попыток (или на неремрабатой ошибке)
+ * исключение уходит наружу.
+ */
+declare function retryWithBackoff<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Типы Action Executor (ARCHITECTURE.md §7.4 «Action Executor»,
+ * ROADMAP.md M1.4: T1.4.1–T1.4.3).
+ *
+ * Executor исполняет действия Action Model M1.3 (VALID_ACTIONS, 24 действия)
+ * на живом DOM. Контракты:
+ *  - вход — LlmAction (llm/types.ts): {action, target_id?, value?, reasoning?};
+ *  - value-кодирование — строго по PARAMETER_CONVENTIONS (llm/prompt.ts),
+ *    единый источник правды с LLM (prompt/schema согласованы в M1.3);
+ *  - резолв target_id — чисто вычислительный, executor не аннотирует DOM;
+ *  - executeAction — soft-fail: сбои возвращаются в ActionResult (error), а не
+ *    бросаются, чтобы шаг агента не прерывал агентный цикл (extension background).
+ */
+/** Информация о загруженном файле (заполняется при download действии). */
+interface DownloadInfo {
+    /** Уникальный идентификатор загрузки. */
+    downloadId: string;
+    /** Имя файла. */
+    filename: string;
+    /** URL источника. */
+    url: string;
+    /** Статус загрузки: pending | completed | cancelled | failed. */
+    status: 'pending' | 'completed' | 'cancelled' | 'failed';
+}
+/** Результат исполнения одного действия (возврат executeAction агенту). */
+interface ActionResult {
+    /** true — действие исполнено; false — отклонено (детали в error). */
+    success: boolean;
+    /** Имя исполненного действия (эхо LlmAction.action). */
+    action: string;
+    /** target_id, если действие было с целью (эхо из входа). */
+    targetId?: string;
+    /** Машиночитаемое описание сбоя при success=false; обратная связь агенту. */
+    error?: string;
+    /** Информация о загрузке (заполняется при action='download' и success=true). */
+    download?: DownloadInfo;
+}
+/**
+ * Ошибка исполнения действия: невалидные параметры, целевой элемент не найден
+ * (DOM изменился с момента снапшота) или расхождение tag при резолве id.
+ * Бросается resolveTarget и внутренними шагами executeAction; снаружи
+ * executeAction конвертирует её в ActionResult{success:false, error}.
+ */
+declare class ActionExecutionError extends Error {
+    constructor(message: string);
+}
+/** Опции исполнения; все опциональны (дефолты рассчитаны на прод в браузере). */
+interface ExecutorOptions {
+    /**
+     * Корень обхода DOM при резолве target_id; по умолчанию document.body.
+     * Обязан совпадать с root, переданным в extractDomTree/VslSnapshotSession:
+     * indexPath в VSL id считается от корня обхода (domExtractor, §5.1).
+     */
+    root?: Element;
+    /** Таймаут wait (мс) — для селектора или "idle"; по умолчанию 5000. */
+    waitTimeout?: number;
+    /**
+     * Амплитуда скролла (px) для bare-направления ("down" без amount);
+     * по умолчанию 300. Явный "down:300" перекрывает дефолт.
+     */
+    defaultScrollAmount?: number;
+}
+
+/**
+ * Action Executor — исполнение действий Action Model M1.3 на живом DOM
+ * (ARCHITECTURE.md §7.4 «Action Executor», ROADMAP.md M1.4: T1.4.1–T1.4.3).
+ *
+ * Контракт (spec M1.4; value-кодирование — строго по PARAMETER_CONVENTIONS
+ * llm/prompt.ts, единый источник правды с LLM — решение dc_4/dc_7):
+ *  - вход — LlmAction (llm/types.ts): {action, target_id?, value?, reasoning?};
+ *  - target_id резолвится resolveTarget (tag_indexPath → обход DOM от корня
+ *    снапшота: ExecutorOptions.root ?? document.body) — executor не аннотирует
+ *    DOM и не хранит ссылок на элементы между действиями;
+ *  - executeAction — soft-fail: всегда возвращает Promise<ActionResult>, не
+ *    бросает; ActionExecutionError (и любой неожиданный error) перехватывается
+ *    и отражается в result.error — сбой шага не роняет агентный цикл
+ *    (extension background);
+ *  - значения input/select/checkbox выставляются программно + dispatch
+ *    input/change с bubbles — React-совместимость (AC[2]): React обновляет
+ *    controlled-компоненты только по событиям, а не от прямой смены .value;
+ *  - type ЗАМЕНЯЕТ значение поля (не дополняет) — детерминизм: повторный type
+ *    даёт то же состояние; очистка поля — отдельным действием clear;
+ *  - сообщения ошибок — на английском (публичный API @thinkingos/vsl-sdk и вход для
+ *    LLM-агента, решение 22.09.2026).
+ */
+
+/**
+ * Исполняет одно действие LLM на живом DOM (§7.4, T1.4.1–T1.4.3).
+ *
+ * Soft-fail (решение dev_1): любые сбои — невалидные параметры, целевой
+ * элемент не найден, DOM изменился с момента снапшота — возвращаются в
+ * ActionResult.error, исключение агентному циклу не бросается.
+ *
+ * @param action — действие от LLM (после validateAction в M1.3; состав VSL
+ *   здесь повторно не валидируется — executor проверяет только то, что нужно
+ *   для исполнения).
+ * @param options — ExecutorOptions; root обязан совпадать с корнем снапшота.
+ * @returns ActionResult с эхом action/targetId.
+ */
+declare function executeAction(action: LlmAction, options?: ExecutorOptions): Promise<ActionResult>;
+
+/**
+ * Резолв target_id → DOM-элемент (ARCHITECTURE.md §7.4 «Action Executor»,
+ * ROADMAP.md M1.4, T1.4.1).
+ *
+ * Контракт (spec M1.4 п.4; формат id — vslBuilder.ts:100):
+ *  - target_id = `tag_index1_index2_...`: tag — имя тега в нижнем регистре,
+ *    индексы — indexPath элемента (id = `${el.tag}_${el.indexPath.join('_')}`);
+ *  - indexPath — индексы среди ЭЛЕМЕНТНЫХ детей каждого уровня, вычисляются по
+ *    структуре DOM ДО фильтрации (domExtractor.collectVisibleChildren) — позиция
+ *    стабильна независимо от фильтров видимости/сегментации;
+ *  - extractDomTree возвращает ЛЕС потомков root (сам root не включается), поэтому
+ *    каждый VSL id содержит ≥1 индекс, а обход стартует с root.children[index];
+ *  - обход от корня снапшота: ExecutorOptions.root ?? document.body. Root обязан
+ *    совпадать с root, переданным в extractDomTree/VslSnapshotSession, иначе
+ *    indexPath укажет не на тот элемент;
+ *  - резолв чисто вычислительный: executor не аннотирует DOM и не хранит ссылок;
+ *  - при невалидном формате id, отсутствии элемента по indexPath или несовпадении
+ *    tag бросается ActionExecutionError (DOM изменился с момента снапшота).
+ *    Сообщения ошибок — на английском: runtime-строки — публичный API @thinkingos/vsl-sdk и
+ *    вход для LLM-агента (решение 22.09.2026).
+ */
+
+/**
+ * Резолвит target_id в DOM-элемент обходом от корня снапшота (§7.4, T1.4.1).
+ *
+ * @param targetId — id элемента из VSL JSON, формат "tag_index1_index2_...".
+ * @param options — ExecutorOptions; root обязан совпадать с корнем снапшота
+ *   (extractDomTree/§5.1), по умолчанию document.body.
+ * @returns найденный DOM-элемент.
+ * @throws ActionExecutionError — невалидный формат id, элемент по indexPath не
+ *   найден или tag не совпал (DOM изменился с момента снапшота).
+ */
+declare function resolveTarget(targetId: string, options?: ExecutorOptions): Element;
+
+/**
+ * VSL SDK — публичное API. Точка входа:
+ *  - Snapshot generation (M1.1): capture → segment → build;
+ *  - Cache & Diff (M1.2): Cache Store, invalidation, Diff Engine (§6.2),
+ *    Snapshot Session (первый вызов → VslDocument, далее → VslDiff).
+ *  - LLM Integration (M1.3): LLM Adapter (OpenAI/Anthropic), Action Model, промпты и retry.
+ */
+
+declare const VSL_SDK_VERSION = "0.1.0";
+
+export { ACTION_TOOL_DESCRIPTION, ACTION_TOOL_NAME, ACTION_TOOL_SCHEMA, ARIA_ROLE_TYPE_MAP, ActionExecutionError, type ActionResult, AlibabaAdapter, AnthropicAdapter, type BuildOptions, type CacheEntry, type CacheStore, type DecideInput, type DiffOptions, type ExecutorOptions, type ExtractedElement, type FewShotExample, LEVEL1_TAG_MAP, type LlmAction, type LlmAdapter, type LlmAdapterConfig, LlmError, type LlmResponse, type LlmTransport, type LlmUsage, LlmValidationError, type MutationObserverHandle, OpenAIAdapter, type Rect, type RetryOptions, type SegmentedElement, type SendPromptOptions, type Sleep, type SnapshotInput, type SnapshotResult, VALID_ACTIONS, VSL_SDK_VERSION, VSL_VERSION, type ValidAction, type VisualFragment, type VisualFragmentData, type VisualFragmentStore, type VisualFragmentType, type VslCanvas, type VslDiff, type VslDiffChanges, type VslDocument, type VslFragmentMeta, type VslInput, type VslModifiedObject, type VslObject, type VslObjectWithVf, type VslRemovedObject, VslSnapshotSession, type VslState, type VslType, type VslViewport, attachMutationObserver, buildSystemPrompt, buildUserPrompt, buildVslDocument, collectIds, computeContentHash, computeCoordHash, createCacheStore, diffVslDocuments, executeAction, extractDomTree, isAriaHidden, isVslDiff, ownText, resolveAriaRoleType, resolveLevel1Type, resolveSt, resolveTarget, retryWithBackoff, segmentTree, validateAction };