@thinkingos/vsl-sdk 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -845,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). */
@@ -909,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
@@ -922,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;
 }

package/dist/index.d.ts

@@ -845,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). */
@@ -909,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
@@ -922,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;
 }

package/dist/index.js

@@ -652,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) {
@@ -788,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) и возвращает полный документ либо дифф (см. шапку).
@@ -796,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
@@ -809,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 = {
@@ -820,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);