@thinkingos/vsl-sdk 0.1.1 → 0.3.0

package/dist/index.d.mts

@@ -60,6 +60,18 @@ interface ElementCss {
     pointerEvents?: string;
     overflow?: string;
     height?: string;
+    /** Background color (computed) — для sty.bg в VslObject. */
+    backgroundColor?: string;
+    /** Text/foreground color (computed) — для sty.fg в VslObject. */
+    color?: string;
+    /** Border shorthand (computed) — для sty.border в VslObject. */
+    border?: string;
+    /** Border radius (computed) — для sty.radius в VslObject. */
+    borderRadius?: string;
+    /** Box shadow (computed) — для sty.shadow в VslObject. */
+    boxShadow?: string;
+    /** Font family (computed) — для sty.font.family в VslObject. */
+    fontFamily?: string;
 }
 /** Собственный текст элемента: только прямые текстовые узлы, whitespace-нормализация. */
 declare function ownText(el: Element): string;
@@ -76,7 +88,7 @@ declare function extractDomTree(root?: Element): ExtractedElement[];
  * Семантический тип объекта 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';
+type VslType = 'button' | 'input' | 'file_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). */
@@ -89,6 +101,29 @@ interface VslFragmentMeta$1 {
     hash?: string;
     cached_at?: string;
 }
+/**
+ * Визуальные стили объекта VSL (DESIGN_SYSTEM.md §4.3).
+ * Optional: только для визуально значимых элементов.
+ * Все значения — computed styles в момент snapshot.
+ */
+interface VslStyle {
+    /** Background color (computed). */
+    bg?: string;
+    /** Text/foreground color (computed). */
+    fg?: string;
+    /** Border shorthand (computed). */
+    border?: string;
+    /** Border radius (computed). */
+    radius?: string;
+    /** Box shadow (computed). */
+    shadow?: string;
+    /** Font properties. */
+    font?: {
+        family?: string;
+        size?: string;
+        weight?: string;
+    };
+}
 /**
  * Запись реестра visual_fragments документа (§2.2.2, ARCHITECTURE.md:L265-284).
  * ТОЛЬКО метаданные: base64-данные изображений живут в VisualFragmentStore
@@ -148,6 +183,12 @@ interface VslObject {
     vf?: string;
     /** Метаданные фрагмента (§4.4). */
     vf_meta?: VslFragmentMeta$1;
+    /** Визуальные стили (DESIGN_SYSTEM.md §4.3). Optional: только для визуально значимых элементов. */
+    sty?: VslStyle;
+    /** Accept attribute для file_input (например, '.pdf,.docx'). */
+    accept?: string;
+    /** Multiple attribute для file_input — разрешена загрузка нескольких файлов. */
+    multiple?: boolean;
 }
 interface VslDocument {
     vsl_version: string;
@@ -250,6 +291,8 @@ interface SegmentedElement {
     txt: string | null;
     /** Состояние из ARIA (checked/expanded/disabled) или null. */
     st: VslState | null;
+    /** CSS-подмножество для визуальных стилей (передаётся в Builder для sty). */
+    css?: ElementCss;
     ch: SegmentedElement[];
     /** Ссылка на визуальный фрагмент (заполняется enrichWithVision, T1.5.4). */
     vf?: string;
@@ -802,32 +845,6 @@ interface EnrichWithVisionDeps {
     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). */
@@ -866,11 +883,26 @@ declare class VslSnapshotSession {
     private lastDocument;
     private version;
     constructor(store?: CacheStore);
+    /**
+     * Сбрасывает состояние сессии (URL, viewport, документ, версия).
+     * Следующий вызов snapshot() вернёт полный документ (как первый вызов).
+     */
+    clear(): void;
+    /** Возвращает последний полный документ (не diff). */
+    getLastDocument(): VslDocument | null;
+    /** Текущая версия документа (инкрементируется при каждом diff). */
+    getVersion(): number;
     /**
      * Строит VSL из DOM поддерева root (extractDomTree → segmentTree →
      * buildVslDocument) и возвращает полный документ либо дифф (см. шапку).
      */
     snapshot(root: Element, input: SnapshotInput): SnapshotResult;
+    /**
+     * Вариант snapshot() для pre-extracted elements (MCP сервер, Node.js контекст).
+     * Принимает ExtractedElement[] напрямую (без DOM Element), проходит тот же
+     * pipeline: segmentTree → buildVslDocument → cache/diff.
+     */
+    snapshotFromElements(extractedElements: readonly ExtractedElement[], input: SnapshotInput): SnapshotResult;
     /**
      * Vision-вариант конвейера (T1.5.5): segmentTree → enrichWithVision (Level 5
      * fallback — аннотация t + vf/vf_meta на элементах ДО сборки) → buildVslDocument
@@ -879,8 +911,18 @@ declare class VslSnapshotSession {
      * (base64) возвращаются ОТДЕЛЬНО — в документе только метаданные (DEC-015).
      */
     snapshotWithVision(root: Element, input: SnapshotInput, vision: EnrichWithVisionDeps): Promise<VisionSnapshotResult>;
+    /**
+     * Vision-вариант для pre-extracted elements (MCP сервер, Node.js контекст).
+     * Полный pipeline: segmentTree → enrichWithVision → buildVslDocument → cache/diff.
+     */
+    snapshotWithVisionFromElements(extractedElements: readonly ExtractedElement[], input: SnapshotInput, vision: EnrichWithVisionDeps): Promise<VisionSnapshotResult>;
     /** BuildOptions из input + портативный title (логика бывшего snapshot()). */
     private buildOptions;
+    /**
+     * BuildOptions из input без DOM Element (для snapshotFromElements).
+     * Title берётся только из input (нет фолбэка на root.ownerDocument.title).
+     */
+    private buildOptionsFromInput;
     /** Сборка документа + кэш/дифф (логика бывшего snapshot(), см. шапку модуля). */
     private commit;
 }
@@ -1055,7 +1097,7 @@ declare const ACTION_TOOL_SCHEMA: {
         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")[];
+            enum: ("select" | "type" | "click" | "close" | "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;

package/dist/index.d.ts

@@ -60,6 +60,18 @@ interface ElementCss {
     pointerEvents?: string;
     overflow?: string;
     height?: string;
+    /** Background color (computed) — для sty.bg в VslObject. */
+    backgroundColor?: string;
+    /** Text/foreground color (computed) — для sty.fg в VslObject. */
+    color?: string;
+    /** Border shorthand (computed) — для sty.border в VslObject. */
+    border?: string;
+    /** Border radius (computed) — для sty.radius в VslObject. */
+    borderRadius?: string;
+    /** Box shadow (computed) — для sty.shadow в VslObject. */
+    boxShadow?: string;
+    /** Font family (computed) — для sty.font.family в VslObject. */
+    fontFamily?: string;
 }
 /** Собственный текст элемента: только прямые текстовые узлы, whitespace-нормализация. */
 declare function ownText(el: Element): string;
@@ -76,7 +88,7 @@ declare function extractDomTree(root?: Element): ExtractedElement[];
  * Семантический тип объекта 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';
+type VslType = 'button' | 'input' | 'file_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). */
@@ -89,6 +101,29 @@ interface VslFragmentMeta$1 {
     hash?: string;
     cached_at?: string;
 }
+/**
+ * Визуальные стили объекта VSL (DESIGN_SYSTEM.md §4.3).
+ * Optional: только для визуально значимых элементов.
+ * Все значения — computed styles в момент snapshot.
+ */
+interface VslStyle {
+    /** Background color (computed). */
+    bg?: string;
+    /** Text/foreground color (computed). */
+    fg?: string;
+    /** Border shorthand (computed). */
+    border?: string;
+    /** Border radius (computed). */
+    radius?: string;
+    /** Box shadow (computed). */
+    shadow?: string;
+    /** Font properties. */
+    font?: {
+        family?: string;
+        size?: string;
+        weight?: string;
+    };
+}
 /**
  * Запись реестра visual_fragments документа (§2.2.2, ARCHITECTURE.md:L265-284).
  * ТОЛЬКО метаданные: base64-данные изображений живут в VisualFragmentStore
@@ -148,6 +183,12 @@ interface VslObject {
     vf?: string;
     /** Метаданные фрагмента (§4.4). */
     vf_meta?: VslFragmentMeta$1;
+    /** Визуальные стили (DESIGN_SYSTEM.md §4.3). Optional: только для визуально значимых элементов. */
+    sty?: VslStyle;
+    /** Accept attribute для file_input (например, '.pdf,.docx'). */
+    accept?: string;
+    /** Multiple attribute для file_input — разрешена загрузка нескольких файлов. */
+    multiple?: boolean;
 }
 interface VslDocument {
     vsl_version: string;
@@ -250,6 +291,8 @@ interface SegmentedElement {
     txt: string | null;
     /** Состояние из ARIA (checked/expanded/disabled) или null. */
     st: VslState | null;
+    /** CSS-подмножество для визуальных стилей (передаётся в Builder для sty). */
+    css?: ElementCss;
     ch: SegmentedElement[];
     /** Ссылка на визуальный фрагмент (заполняется enrichWithVision, T1.5.4). */
     vf?: string;
@@ -802,32 +845,6 @@ interface EnrichWithVisionDeps {
     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). */
@@ -866,11 +883,26 @@ declare class VslSnapshotSession {
     private lastDocument;
     private version;
     constructor(store?: CacheStore);
+    /**
+     * Сбрасывает состояние сессии (URL, viewport, документ, версия).
+     * Следующий вызов snapshot() вернёт полный документ (как первый вызов).
+     */
+    clear(): void;
+    /** Возвращает последний полный документ (не diff). */
+    getLastDocument(): VslDocument | null;
+    /** Текущая версия документа (инкрементируется при каждом diff). */
+    getVersion(): number;
     /**
      * Строит VSL из DOM поддерева root (extractDomTree → segmentTree →
      * buildVslDocument) и возвращает полный документ либо дифф (см. шапку).
      */
     snapshot(root: Element, input: SnapshotInput): SnapshotResult;
+    /**
+     * Вариант snapshot() для pre-extracted elements (MCP сервер, Node.js контекст).
+     * Принимает ExtractedElement[] напрямую (без DOM Element), проходит тот же
+     * pipeline: segmentTree → buildVslDocument → cache/diff.
+     */
+    snapshotFromElements(extractedElements: readonly ExtractedElement[], input: SnapshotInput): SnapshotResult;
     /**
      * Vision-вариант конвейера (T1.5.5): segmentTree → enrichWithVision (Level 5
      * fallback — аннотация t + vf/vf_meta на элементах ДО сборки) → buildVslDocument
@@ -879,8 +911,18 @@ declare class VslSnapshotSession {
      * (base64) возвращаются ОТДЕЛЬНО — в документе только метаданные (DEC-015).
      */
     snapshotWithVision(root: Element, input: SnapshotInput, vision: EnrichWithVisionDeps): Promise<VisionSnapshotResult>;
+    /**
+     * Vision-вариант для pre-extracted elements (MCP сервер, Node.js контекст).
+     * Полный pipeline: segmentTree → enrichWithVision → buildVslDocument → cache/diff.
+     */
+    snapshotWithVisionFromElements(extractedElements: readonly ExtractedElement[], input: SnapshotInput, vision: EnrichWithVisionDeps): Promise<VisionSnapshotResult>;
     /** BuildOptions из input + портативный title (логика бывшего snapshot()). */
     private buildOptions;
+    /**
+     * BuildOptions из input без DOM Element (для snapshotFromElements).
+     * Title берётся только из input (нет фолбэка на root.ownerDocument.title).
+     */
+    private buildOptionsFromInput;
     /** Сборка документа + кэш/дифф (логика бывшего snapshot(), см. шапку модуля). */
     private commit;
 }
@@ -1055,7 +1097,7 @@ declare const ACTION_TOOL_SCHEMA: {
         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")[];
+            enum: ("select" | "type" | "click" | "close" | "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;

package/dist/index.js

@@ -109,7 +109,13 @@ var CSS_PROPERTIES = [
   ["opacity", "opacity"],
   ["pointerEvents", "pointer-events"],
   ["overflow", "overflow"],
-  ["height", "height"]
+  ["height", "height"],
+  ["backgroundColor", "background-color"],
+  ["color", "color"],
+  ["border", "border"],
+  ["borderRadius", "border-radius"],
+  ["boxShadow", "box-shadow"],
+  ["fontFamily", "font-family"]
 ];
 function captureCss(el) {
   const view = viewOf(el);
@@ -319,14 +325,16 @@ function isAriaHidden(attributes) {
 }
 function segmentOne(el) {
   const { attributes } = el;
+  const isFileInput = el.tag === "input" && attributes["type"] === "file";
   return {
     tag: el.tag,
     indexPath: el.indexPath,
     rect: el.rect,
     attributes,
-    t: resolveLevel1Type(el.tag) ?? resolveAriaRoleType(attributes["role"]) ?? resolveLevel3Type(el.css, attributes),
+    t: isFileInput ? "file_input" : resolveLevel1Type(el.tag) ?? resolveAriaRoleType(attributes["role"]) ?? resolveLevel3Type(el.css, attributes),
     txt: attributes["aria-label"] ?? el.text,
     st: resolveSt(attributes),
+    css: el.css,
     ch: []
   };
 }
@@ -379,6 +387,8 @@ function defaultActions(t, st, attributes) {
       return ["click", "select"];
     case "textarea":
       return ["click", "type", "clear"];
+    case "file_input":
+      return ["click", "upload"];
     default:
       return void 0;
   }
@@ -391,6 +401,39 @@ function baseSemanticScore(el) {
   if (el.txt) score += 1;
   return score;
 }
+function extractVisualStyles(css) {
+  if (!css) return void 0;
+  const style = {};
+  let hasContent = false;
+  if (css.backgroundColor && css.backgroundColor !== "transparent" && !css.backgroundColor.includes("rgba(0, 0, 0, 0)")) {
+    style.bg = css.backgroundColor;
+    hasContent = true;
+  }
+  if (css.color && css.color !== "rgb(0, 0, 0)") {
+    style.fg = css.color;
+    hasContent = true;
+  }
+  if (css.border && css.border !== "none" && !css.border.startsWith("0px")) {
+    style.border = css.border;
+    hasContent = true;
+  }
+  if (css.borderRadius && css.borderRadius !== "0px") {
+    style.radius = css.borderRadius;
+    hasContent = true;
+  }
+  if (css.boxShadow && css.boxShadow !== "none") {
+    style.shadow = css.boxShadow;
+    hasContent = true;
+  }
+  if (css.fontFamily || css.fontSize || css.fontWeight) {
+    style.font = {};
+    if (css.fontFamily) style.font.family = css.fontFamily;
+    if (css.fontSize) style.font.size = css.fontSize;
+    if (css.fontWeight) style.font.weight = css.fontWeight;
+    hasContent = true;
+  }
+  return hasContent ? style : void 0;
+}
 function toVslObject(el, viewport, includedChildren, textBlocks, counter) {
   const t = el.t ?? "container";
   const object = {
@@ -417,6 +460,12 @@ function toVslObject(el, viewport, includedChildren, textBlocks, counter) {
   if (includedChildren.length > 0) object.ch = includedChildren;
   if (el.vf !== void 0) object.vf = el.vf;
   if (el.vf_meta !== void 0) object.vf_meta = el.vf_meta;
+  const sty = extractVisualStyles(el.css);
+  if (sty !== void 0) object.sty = sty;
+  if (t === "file_input") {
+    if (el.attributes["accept"] !== void 0) object.accept = el.attributes["accept"];
+    if (el.attributes["multiple"] !== void 0) object.multiple = true;
+  }
   return object;
 }
 function convert(el, viewport, textBlocks, counter) {
@@ -603,6 +652,8 @@ function objectsEqual(a, b) {
   return computeContentHash(a) === computeContentHash(b) && computeCoordHash(a) === computeCoordHash(b);
 }
 function tuple2Equal(a, b) {
+  if (a === null || a === void 0) return b === null || b === void 0;
+  if (b === null || b === void 0) return false;
   return a[0] === b[0] && a[1] === b[1];
 }
 function stringArrayEqual(a, b) {
@@ -739,6 +790,25 @@ var VslSnapshotSession = class {
   constructor(store = createCacheStore()) {
     this.store = store;
   }
+  /**
+   * Сбрасывает состояние сессии (URL, viewport, документ, версия).
+   * Следующий вызов snapshot() вернёт полный документ (как первый вызов).
+   */
+  clear() {
+    this.store.clear();
+    this.lastUrl = null;
+    this.lastViewport = null;
+    this.lastDocument = null;
+    this.version = 0;
+  }
+  /** Возвращает последний полный документ (не diff). */
+  getLastDocument() {
+    return this.lastDocument;
+  }
+  /** Текущая версия документа (инкрементируется при каждом diff). */
+  getVersion() {
+    return this.version;
+  }
   /**
    * Строит VSL из DOM поддерева root (extractDomTree → segmentTree →
    * buildVslDocument) и возвращает полный документ либо дифф (см. шапку).
@@ -747,6 +817,15 @@ var VslSnapshotSession = class {
     const elements = segmentTree(extractDomTree(root));
     return this.commit(elements, this.buildOptions(root, input), input);
   }
+  /**
+   * Вариант snapshot() для pre-extracted elements (MCP сервер, Node.js контекст).
+   * Принимает ExtractedElement[] напрямую (без DOM Element), проходит тот же
+   * pipeline: segmentTree → buildVslDocument → cache/diff.
+   */
+  snapshotFromElements(extractedElements, input) {
+    const elements = segmentTree(extractedElements);
+    return this.commit(elements, this.buildOptionsFromInput(input), input);
+  }
   /**
    * Vision-вариант конвейера (T1.5.5): segmentTree → enrichWithVision (Level 5
    * fallback — аннотация t + vf/vf_meta на элементах ДО сборки) → buildVslDocument
@@ -760,6 +839,16 @@ var VslSnapshotSession = class {
     const snapshot = this.commit(elements, this.buildOptions(root, input), input);
     return { snapshot, fragments: visionResult.fragments };
   }
+  /**
+   * Vision-вариант для pre-extracted elements (MCP сервер, Node.js контекст).
+   * Полный pipeline: segmentTree → enrichWithVision → buildVslDocument → cache/diff.
+   */
+  async snapshotWithVisionFromElements(extractedElements, input, vision) {
+    const elements = segmentTree(extractedElements);
+    const visionResult = await enrichWithVision(elements, vision);
+    const snapshot = this.commit(elements, this.buildOptionsFromInput(input), input);
+    return { snapshot, fragments: visionResult.fragments };
+  }
   /** BuildOptions из input + портативный title (логика бывшего snapshot()). */
   buildOptions(root, input) {
     const options = {
@@ -771,6 +860,20 @@ var VslSnapshotSession = class {
     if (input.background !== void 0) options.background = input.background;
     return options;
   }
+  /**
+   * BuildOptions из input без DOM Element (для snapshotFromElements).
+   * Title берётся только из input (нет фолбэка на root.ownerDocument.title).
+   */
+  buildOptionsFromInput(input) {
+    const options = {
+      viewport: { width: input.viewport.width, height: input.viewport.height },
+      url: input.url
+    };
+    if (input.title !== void 0) options.title = input.title;
+    if (input.timestamp !== void 0) options.timestamp = input.timestamp;
+    if (input.background !== void 0) options.background = input.background;
+    return options;
+  }
   /** Сборка документа + кэш/дифф (логика бывшего snapshot(), см. шапку модуля). */
   commit(elements, options, input) {
     const nextDocument = buildVslDocument(elements, options);