@aiscene/core 9.0.6 → 9.0.8

package/dist/es/agent/run-gherkin-scenario.mjs

@@ -0,0 +1,114 @@
+const stepKeywordPattern = /^(Given|When|Then|And|But)\s+(.+)$/i;
+const headerPattern = /^(Scenario):\s*(.*)$/i;
+const unsupportedHeaderPattern = /^(Feature|Background|Scenario Outline|Scenario Template|Examples|Rule):/i;
+const normalizeStepKeyword = (keyword)=>{
+    const lowerKeyword = keyword.toLowerCase();
+    if ('given' === lowerKeyword) return 'Given';
+    if ('when' === lowerKeyword) return 'When';
+    if ('then' === lowerKeyword) return 'Then';
+    if ('and' === lowerKeyword) return 'And';
+    return 'But';
+};
+const isPrimaryKeyword = (keyword)=>'Given' === keyword || 'When' === keyword || 'Then' === keyword;
+const resolveSteps = (steps)=>{
+    let previousPrimaryKeyword;
+    return steps.map((step)=>{
+        const effectiveKeyword = isPrimaryKeyword(step.keyword) ? step.keyword : previousPrimaryKeyword;
+        if (!effectiveKeyword) throw new Error(`runGherkinScenario cannot resolve "${step.keyword}" at line ${step.lineNumber}; use Given, When, or Then before ${step.keyword}.`);
+        previousPrimaryKeyword = effectiveKeyword;
+        return {
+            ...step,
+            effectiveKeyword
+        };
+    });
+};
+const throwIfAborted = (abortSignal)=>{
+    if (!abortSignal?.aborted) return;
+    if ('function' == typeof abortSignal.throwIfAborted) abortSignal.throwIfAborted();
+    throw new Error(`runGherkinScenario aborted: ${abortSignal.reason || 'signal already aborted'}`);
+};
+const parseGherkinScenario = (scenarioText)=>{
+    const lines = scenarioText.split(/\r?\n/);
+    const scenarioSteps = [];
+    const anonymousSteps = [];
+    let scenario;
+    let scenarioCount = 0;
+    let section = 'prelude';
+    for (const [lineIndex, rawLine] of lines.entries()){
+        const lineNumber = lineIndex + 1;
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#') || line.startsWith('@')) continue;
+        if ('"""' === line || "'''" === line) throw new Error(`runGherkinScenario does not support doc strings; found one at line ${lineNumber}.`);
+        if (line.startsWith('|')) throw new Error(`runGherkinScenario does not support data tables; found one at line ${lineNumber}.`);
+        if (unsupportedHeaderPattern.test(line)) throw new Error(`runGherkinScenario does not support "${line}" at line ${lineNumber}.`);
+        const headerMatch = line.match(headerPattern);
+        if (headerMatch) {
+            scenarioCount += 1;
+            scenario = headerMatch[2].trim() || void 0;
+            section = 'scenario';
+            continue;
+        }
+        const stepMatch = line.match(stepKeywordPattern);
+        if (stepMatch) {
+            const step = {
+                keyword: normalizeStepKeyword(stepMatch[1]),
+                text: stepMatch[2].trim(),
+                lineNumber
+            };
+            if ('scenario' === section) scenarioSteps.push(step);
+            else anonymousSteps.push(step);
+            continue;
+        }
+        throw new Error(`runGherkinScenario does not support content at line ${lineNumber}: ${line}`);
+    }
+    if (scenarioCount > 1) throw new Error(`runGherkinScenario expects exactly one Scenario, but found ${scenarioCount}.`);
+    if (1 === scenarioCount && anonymousSteps.length > 0) throw new Error('runGherkinScenario cannot mix anonymous steps with a Scenario block.');
+    const rawSteps = 1 === scenarioCount ? scenarioSteps : anonymousSteps;
+    if (0 === rawSteps.length) throw new Error('runGherkinScenario requires at least one Gherkin step.');
+    return {
+        scenario,
+        steps: resolveSteps(rawSteps)
+    };
+};
+const buildStepPrompt = (step)=>{
+    if ('Given' === step.effectiveKeyword) return `Set up this precondition: ${step.text}`;
+    if ('When' === step.effectiveKeyword) return `Perform this user action: ${step.text}`;
+    return `Verify that ${step.text}`;
+};
+const describeStepExecution = (step, action)=>{
+    const keywordMapping = step.keyword === step.effectiveKeyword ? step.keyword : `${step.keyword} as ${step.effectiveKeyword}`;
+    if ('Given' === step.effectiveKeyword) return `setting up the precondition (${keywordMapping} -> ${action})`;
+    if ('When' === step.effectiveKeyword) return `performing the user action (${keywordMapping} -> ${action})`;
+    return `verifying the expected result (${keywordMapping} -> ${action})`;
+};
+const describeErrorCause = (error)=>{
+    if (error instanceof Error && error.message) return ` Original error: ${error.message}`;
+    return '';
+};
+const runGherkinScenario = async (agent, scenarioText, opt)=>{
+    const parsedScenario = parseGherkinScenario(scenarioText);
+    const aiActOptions = {
+        ...opt,
+        cacheable: false
+    };
+    for (const step of parsedScenario.steps){
+        throwIfAborted(opt?.abortSignal);
+        const action = 'Then' === step.effectiveKeyword ? 'aiAssert' : 'aiAct';
+        const prompt = buildStepPrompt(step);
+        try {
+            if ('aiAct' === action) await agent.aiAct(prompt, aiActOptions);
+            else if (opt?.context || opt?.abortSignal) await agent.aiAssert(prompt, void 0, {
+                context: opt.context,
+                abortSignal: opt.abortSignal
+            });
+            else await agent.aiAssert(prompt);
+        } catch (error) {
+            throw new Error(`runGherkinScenario failed while ${describeStepExecution(step, action)} at line ${step.lineNumber}: ${step.keyword} ${step.text}.${describeErrorCause(error)}`, {
+                cause: error
+            });
+        }
+    }
+};
+export { parseGherkinScenario, runGherkinScenario };
+
+//# sourceMappingURL=run-gherkin-scenario.mjs.map

package/dist/es/agent/run-gherkin-scenario.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent/run-gherkin-scenario.mjs","sources":["../../../src/agent/run-gherkin-scenario.ts"],"sourcesContent":["import type { AiActOptions } from './agent';\n\nexport type GherkinStepKeyword = 'Given' | 'When' | 'Then' | 'And' | 'But';\n\ntype RunGherkinScenarioStepAction = 'aiAct' | 'aiAssert';\n\nexport type RunGherkinScenarioOptions = AiActOptions & {\n  context?: string;\n};\n\ntype GherkinPrimaryKeyword = 'Given' | 'When' | 'Then';\n\ntype ParsedGherkinStep = {\n  keyword: GherkinStepKeyword;\n  effectiveKeyword: GherkinPrimaryKeyword;\n  text: string;\n  lineNumber: number;\n};\n\ntype RawGherkinStep = {\n  keyword: GherkinStepKeyword;\n  text: string;\n  lineNumber: number;\n};\n\ntype ParsedGherkinScenario = {\n  scenario?: string;\n  steps: ParsedGherkinStep[];\n};\n\ntype GherkinScenarioAgent = {\n  aiAct: (taskPrompt: string, opt?: AiActOptions) => Promise<unknown>;\n  aiAssert: (\n    assertion: string,\n    msg?: string,\n    opt?: { context?: string; abortSignal?: AbortSignal },\n  ) => Promise<unknown>;\n};\n\nconst stepKeywordPattern = /^(Given|When|Then|And|But)\\s+(.+)$/i;\nconst headerPattern = /^(Scenario):\\s*(.*)$/i;\nconst unsupportedHeaderPattern =\n  /^(Feature|Background|Scenario Outline|Scenario Template|Examples|Rule):/i;\n\nconst normalizeStepKeyword = (keyword: string): GherkinStepKeyword => {\n  const lowerKeyword = keyword.toLowerCase();\n  if (lowerKeyword === 'given') return 'Given';\n  if (lowerKeyword === 'when') return 'When';\n  if (lowerKeyword === 'then') return 'Then';\n  if (lowerKeyword === 'and') return 'And';\n  return 'But';\n};\n\nconst isPrimaryKeyword = (\n  keyword: GherkinStepKeyword,\n): keyword is GherkinPrimaryKeyword => {\n  return keyword === 'Given' || keyword === 'When' || keyword === 'Then';\n};\n\nconst resolveSteps = (steps: RawGherkinStep[]): ParsedGherkinStep[] => {\n  let previousPrimaryKeyword: GherkinPrimaryKeyword | undefined;\n\n  return steps.map((step) => {\n    const effectiveKeyword = isPrimaryKeyword(step.keyword)\n      ? step.keyword\n      : previousPrimaryKeyword;\n\n    if (!effectiveKeyword) {\n      throw new Error(\n        `runGherkinScenario cannot resolve \"${step.keyword}\" at line ${step.lineNumber}; use Given, When, or Then before ${step.keyword}.`,\n      );\n    }\n\n    previousPrimaryKeyword = effectiveKeyword;\n\n    return {\n      ...step,\n      effectiveKeyword,\n    };\n  });\n};\n\nconst throwIfAborted = (abortSignal: AbortSignal | undefined) => {\n  if (!abortSignal?.aborted) {\n    return;\n  }\n\n  if (typeof abortSignal.throwIfAborted === 'function') {\n    abortSignal.throwIfAborted();\n  }\n\n  throw new Error(\n    `runGherkinScenario aborted: ${abortSignal.reason || 'signal already aborted'}`,\n  );\n};\n\nexport const parseGherkinScenario = (\n  scenarioText: string,\n): ParsedGherkinScenario => {\n  const lines = scenarioText.split(/\\r?\\n/);\n  const scenarioSteps: RawGherkinStep[] = [];\n  const anonymousSteps: RawGherkinStep[] = [];\n  let scenario: string | undefined;\n  let scenarioCount = 0;\n  let section: 'prelude' | 'scenario' = 'prelude';\n\n  for (const [lineIndex, rawLine] of lines.entries()) {\n    const lineNumber = lineIndex + 1;\n    const line = rawLine.trim();\n\n    if (!line || line.startsWith('#') || line.startsWith('@')) {\n      continue;\n    }\n\n    if (line === '\"\"\"' || line === \"'''\") {\n      throw new Error(\n        `runGherkinScenario does not support doc strings; found one at line ${lineNumber}.`,\n      );\n    }\n\n    if (line.startsWith('|')) {\n      throw new Error(\n        `runGherkinScenario does not support data tables; found one at line ${lineNumber}.`,\n      );\n    }\n\n    if (unsupportedHeaderPattern.test(line)) {\n      throw new Error(\n        `runGherkinScenario does not support \"${line}\" at line ${lineNumber}.`,\n      );\n    }\n\n    const headerMatch = line.match(headerPattern);\n    if (headerMatch) {\n      scenarioCount += 1;\n      scenario = headerMatch[2].trim() || undefined;\n      section = 'scenario';\n      continue;\n    }\n\n    const stepMatch = line.match(stepKeywordPattern);\n    if (stepMatch) {\n      const step = {\n        keyword: normalizeStepKeyword(stepMatch[1]),\n        text: stepMatch[2].trim(),\n        lineNumber,\n      };\n\n      if (section === 'scenario') {\n        scenarioSteps.push(step);\n      } else {\n        anonymousSteps.push(step);\n      }\n\n      continue;\n    }\n\n    throw new Error(\n      `runGherkinScenario does not support content at line ${lineNumber}: ${line}`,\n    );\n  }\n\n  if (scenarioCount > 1) {\n    throw new Error(\n      `runGherkinScenario expects exactly one Scenario, but found ${scenarioCount}.`,\n    );\n  }\n\n  if (scenarioCount === 1 && anonymousSteps.length > 0) {\n    throw new Error(\n      'runGherkinScenario cannot mix anonymous steps with a Scenario block.',\n    );\n  }\n\n  const rawSteps = scenarioCount === 1 ? scenarioSteps : anonymousSteps;\n\n  if (rawSteps.length === 0) {\n    throw new Error('runGherkinScenario requires at least one Gherkin step.');\n  }\n\n  return {\n    scenario,\n    steps: resolveSteps(rawSteps),\n  };\n};\n\nconst buildStepPrompt = (step: ParsedGherkinStep) => {\n  if (step.effectiveKeyword === 'Given') {\n    return `Set up this precondition: ${step.text}`;\n  }\n\n  if (step.effectiveKeyword === 'When') {\n    return `Perform this user action: ${step.text}`;\n  }\n\n  return `Verify that ${step.text}`;\n};\n\nconst describeStepExecution = (\n  step: ParsedGherkinStep,\n  action: RunGherkinScenarioStepAction,\n) => {\n  const keywordMapping =\n    step.keyword === step.effectiveKeyword\n      ? step.keyword\n      : `${step.keyword} as ${step.effectiveKeyword}`;\n\n  if (step.effectiveKeyword === 'Given') {\n    return `setting up the precondition (${keywordMapping} -> ${action})`;\n  }\n\n  if (step.effectiveKeyword === 'When') {\n    return `performing the user action (${keywordMapping} -> ${action})`;\n  }\n\n  return `verifying the expected result (${keywordMapping} -> ${action})`;\n};\n\nconst describeErrorCause = (error: unknown) => {\n  if (error instanceof Error && error.message) {\n    return ` Original error: ${error.message}`;\n  }\n\n  return '';\n};\n\nexport const runGherkinScenario = async (\n  agent: GherkinScenarioAgent,\n  scenarioText: string,\n  opt?: RunGherkinScenarioOptions,\n): Promise<void> => {\n  const parsedScenario = parseGherkinScenario(scenarioText);\n  const aiActOptions: AiActOptions = {\n    ...opt,\n    cacheable: false,\n  };\n\n  for (const step of parsedScenario.steps) {\n    throwIfAborted(opt?.abortSignal);\n\n    const action: RunGherkinScenarioStepAction =\n      step.effectiveKeyword === 'Then' ? 'aiAssert' : 'aiAct';\n    const prompt = buildStepPrompt(step);\n\n    try {\n      if (action === 'aiAct') {\n        await agent.aiAct(prompt, aiActOptions);\n      } else if (opt?.context || opt?.abortSignal) {\n        await agent.aiAssert(prompt, undefined, {\n          context: opt.context,\n          abortSignal: opt.abortSignal,\n        });\n      } else {\n        await agent.aiAssert(prompt);\n      }\n    } catch (error) {\n      throw new Error(\n        `runGherkinScenario failed while ${describeStepExecution(\n          step,\n          action,\n        )} at line ${step.lineNumber}: ${step.keyword} ${step.text}.${describeErrorCause(\n          error,\n        )}`,\n        {\n          cause: error,\n        },\n      );\n    }\n  }\n};\n"],"names":["stepKeywordPattern","headerPattern","unsupportedHeaderPattern","normalizeStepKeyword","keyword","lowerKeyword","isPrimaryKeyword","resolveSteps","steps","previousPrimaryKeyword","step","effectiveKeyword","Error","throwIfAborted","abortSignal","parseGherkinScenario","scenarioText","lines","scenarioSteps","anonymousSteps","scenario","scenarioCount","section","lineIndex","rawLine","lineNumber","line","headerMatch","undefined","stepMatch","rawSteps","buildStepPrompt","describeStepExecution","action","keywordMapping","describeErrorCause","error","runGherkinScenario","agent","opt","parsedScenario","aiActOptions","prompt"],"mappings":"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"}

package/dist/es/agent/run-markdown.mjs

@@ -0,0 +1,62 @@
+import { dirname, isAbsolute, resolve } from "node:path";
+const MAX_MARKDOWN_IMAGES = 20;
+const REFERENCE_IMAGE_PREFIX = '参考图片';
+const imageNameForIndex = (index)=>`${REFERENCE_IMAGE_PREFIX}-${String(index + 1).padStart(3, '0')}`;
+const formatSource = (sourcePath)=>sourcePath ? ` in ${sourcePath}` : '';
+const hasUrlScheme = (url)=>/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(url);
+const resolveMarkdownImageUrl = (url, sourcePath)=>{
+    if (!sourcePath || hasUrlScheme(url) || isAbsolute(url)) return url;
+    return resolve(dirname(sourcePath), url);
+};
+const replaceMarkdownImages = (tree, sourcePath)=>{
+    const images = [];
+    const visitChildren = (node)=>{
+        if (!Array.isArray(node.children)) return;
+        node.children = node.children.map((child)=>{
+            if ('imageReference' === child.type) {
+                const identifier = child.identifier || child.label || 'unknown';
+                throw new Error(`runMarkdown does not support reference-style image "${identifier}"${formatSource(sourcePath)}. Use direct image syntax instead.`);
+            }
+            if ('image' === child.type) {
+                const name = imageNameForIndex(images.length);
+                if (!child.url) throw new Error(`Markdown image ${name}${formatSource(sourcePath)} is missing a URL.`);
+                images.push({
+                    name,
+                    url: resolveMarkdownImageUrl(child.url, sourcePath)
+                });
+                if (images.length > MAX_MARKDOWN_IMAGES) throw new Error(`runMarkdown supports at most ${MAX_MARKDOWN_IMAGES} images, but found ${images.length} images${formatSource(sourcePath)}.`);
+                return {
+                    type: 'text',
+                    value: name
+                };
+            }
+            visitChildren(child);
+            return child;
+        });
+    };
+    visitChildren(tree);
+    return images;
+};
+const markdownToAiActPrompt = async (markdown, sourcePath)=>{
+    const fromMarkdownModuleName = 'mdast-util-from-markdown';
+    const toMarkdownModuleName = 'mdast-util-to-markdown';
+    const { fromMarkdown } = await import(fromMarkdownModuleName);
+    const { toMarkdown } = await import(toMarkdownModuleName);
+    const tree = fromMarkdown(markdown);
+    const images = replaceMarkdownImages(tree, sourcePath);
+    if (0 === images.length) return {
+        prompt: markdown,
+        imageCount: 0
+    };
+    return {
+        prompt: {
+            prompt: toMarkdown(tree),
+            images,
+            convertHttpImage2Base64: true
+        },
+        imageCount: images.length
+    };
+};
+export { markdownToAiActPrompt };
+
+//# sourceMappingURL=run-markdown.mjs.map

package/dist/es/agent/run-markdown.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent/run-markdown.mjs","sources":["../../../src/agent/run-markdown.ts"],"sourcesContent":["import { dirname, isAbsolute, resolve } from 'node:path';\nimport type { TUserPrompt } from '@/common';\n\nconst MAX_MARKDOWN_IMAGES = 20;\nconst REFERENCE_IMAGE_PREFIX = '参考图片';\n\ntype MdastNode = {\n  type: string;\n  children?: MdastNode[];\n  url?: string;\n  identifier?: string;\n  label?: string;\n};\n\ntype MdastRoot = MdastNode & {\n  children: MdastNode[];\n};\n\ntype MdastFromMarkdownModule = {\n  fromMarkdown: (value: string) => MdastRoot;\n};\n\ntype MdastToMarkdownModule = {\n  toMarkdown: (tree: MdastRoot) => string;\n};\n\nexport type RunMarkdownTransformResult = {\n  prompt: TUserPrompt;\n  imageCount: number;\n};\n\nconst imageNameForIndex = (index: number) =>\n  `${REFERENCE_IMAGE_PREFIX}-${String(index + 1).padStart(3, '0')}`;\n\nconst formatSource = (sourcePath?: string) =>\n  sourcePath ? ` in ${sourcePath}` : '';\n\nconst hasUrlScheme = (url: string) => /^[a-zA-Z][a-zA-Z\\d+.-]*:/.test(url);\n\nconst resolveMarkdownImageUrl = (url: string, sourcePath?: string) => {\n  if (!sourcePath || hasUrlScheme(url) || isAbsolute(url)) {\n    return url;\n  }\n  return resolve(dirname(sourcePath), url);\n};\n\nconst replaceMarkdownImages = (tree: MdastRoot, sourcePath?: string) => {\n  const images: Array<{ name: string; url: string }> = [];\n\n  const visitChildren = (node: MdastNode) => {\n    if (!Array.isArray(node.children)) {\n      return;\n    }\n\n    node.children = node.children.map((child) => {\n      if (child.type === 'imageReference') {\n        const identifier = child.identifier || child.label || 'unknown';\n        throw new Error(\n          `runMarkdown does not support reference-style image \"${identifier}\"${formatSource(sourcePath)}. Use direct image syntax instead.`,\n        );\n      }\n\n      if (child.type === 'image') {\n        const name = imageNameForIndex(images.length);\n        if (!child.url) {\n          throw new Error(\n            `Markdown image ${name}${formatSource(sourcePath)} is missing a URL.`,\n          );\n        }\n\n        images.push({\n          name,\n          url: resolveMarkdownImageUrl(child.url, sourcePath),\n        });\n        if (images.length > MAX_MARKDOWN_IMAGES) {\n          throw new Error(\n            `runMarkdown supports at most ${MAX_MARKDOWN_IMAGES} images, but found ${images.length} images${formatSource(sourcePath)}.`,\n          );\n        }\n\n        return {\n          type: 'text',\n          value: name,\n        } as MdastNode;\n      }\n\n      visitChildren(child);\n      return child;\n    });\n  };\n\n  visitChildren(tree);\n  return images;\n};\n\nexport const markdownToAiActPrompt = async (\n  markdown: string,\n  sourcePath?: string,\n): Promise<RunMarkdownTransformResult> => {\n  const fromMarkdownModuleName = 'mdast-util-from-markdown';\n  const toMarkdownModuleName = 'mdast-util-to-markdown';\n  const { fromMarkdown } = (await import(\n    fromMarkdownModuleName\n  )) as MdastFromMarkdownModule;\n  const { toMarkdown } = (await import(\n    toMarkdownModuleName\n  )) as MdastToMarkdownModule;\n\n  const tree = fromMarkdown(markdown);\n  const images = replaceMarkdownImages(tree, sourcePath);\n\n  if (images.length === 0) {\n    return {\n      prompt: markdown,\n      imageCount: 0,\n    };\n  }\n\n  return {\n    prompt: {\n      prompt: toMarkdown(tree),\n      images,\n      convertHttpImage2Base64: true,\n    },\n    imageCount: images.length,\n  };\n};\n"],"names":["MAX_MARKDOWN_IMAGES","REFERENCE_IMAGE_PREFIX","imageNameForIndex","index","String","formatSource","sourcePath","hasUrlScheme","url","resolveMarkdownImageUrl","isAbsolute","resolve","dirname","replaceMarkdownImages","tree","images","visitChildren","node","Array","child","identifier","Error","name","markdownToAiActPrompt","markdown","fromMarkdownModuleName","toMarkdownModuleName","fromMarkdown","toMarkdown"],"mappings":";AAGA,MAAMA,sBAAsB;AAC5B,MAAMC,yBAAyB;AA2B/B,MAAMC,oBAAoB,CAACC,QACzB,GAAGF,uBAAuB,CAAC,EAAEG,OAAOD,QAAQ,GAAG,QAAQ,CAAC,GAAG,MAAM;AAEnE,MAAME,eAAe,CAACC,aACpBA,aAAa,CAAC,IAAI,EAAEA,YAAY,GAAG;AAErC,MAAMC,eAAe,CAACC,MAAgB,2BAA2B,IAAI,CAACA;AAEtE,MAAMC,0BAA0B,CAACD,KAAaF;IAC5C,IAAI,CAACA,cAAcC,aAAaC,QAAQE,WAAWF,MACjD,OAAOA;IAET,OAAOG,QAAQC,QAAQN,aAAaE;AACtC;AAEA,MAAMK,wBAAwB,CAACC,MAAiBR;IAC9C,MAAMS,SAA+C,EAAE;IAEvD,MAAMC,gBAAgB,CAACC;QACrB,IAAI,CAACC,MAAM,OAAO,CAACD,KAAK,QAAQ,GAC9B;QAGFA,KAAK,QAAQ,GAAGA,KAAK,QAAQ,CAAC,GAAG,CAAC,CAACE;YACjC,IAAIA,AAAe,qBAAfA,MAAM,IAAI,EAAuB;gBACnC,MAAMC,aAAaD,MAAM,UAAU,IAAIA,MAAM,KAAK,IAAI;gBACtD,MAAM,IAAIE,MACR,CAAC,oDAAoD,EAAED,WAAW,CAAC,EAAEf,aAAaC,YAAY,kCAAkC,CAAC;YAErI;YAEA,IAAIa,AAAe,YAAfA,MAAM,IAAI,EAAc;gBAC1B,MAAMG,OAAOpB,kBAAkBa,OAAO,MAAM;gBAC5C,IAAI,CAACI,MAAM,GAAG,EACZ,MAAM,IAAIE,MACR,CAAC,eAAe,EAAEC,OAAOjB,aAAaC,YAAY,kBAAkB,CAAC;gBAIzES,OAAO,IAAI,CAAC;oBACVO;oBACA,KAAKb,wBAAwBU,MAAM,GAAG,EAAEb;gBAC1C;gBACA,IAAIS,OAAO,MAAM,GAAGf,qBAClB,MAAM,IAAIqB,MACR,CAAC,6BAA6B,EAAErB,oBAAoB,mBAAmB,EAAEe,OAAO,MAAM,CAAC,OAAO,EAAEV,aAAaC,YAAY,CAAC,CAAC;gBAI/H,OAAO;oBACL,MAAM;oBACN,OAAOgB;gBACT;YACF;YAEAN,cAAcG;YACd,OAAOA;QACT;IACF;IAEAH,cAAcF;IACd,OAAOC;AACT;AAEO,MAAMQ,wBAAwB,OACnCC,UACAlB;IAEA,MAAMmB,yBAAyB;IAC/B,MAAMC,uBAAuB;IAC7B,MAAM,EAAEC,YAAY,EAAE,GAAI,MAAM,MAAM,CACpCF;IAEF,MAAM,EAAEG,UAAU,EAAE,GAAI,MAAM,MAAM,CAClCF;IAGF,MAAMZ,OAAOa,aAAaH;IAC1B,MAAMT,SAASF,sBAAsBC,MAAMR;IAE3C,IAAIS,AAAkB,MAAlBA,OAAO,MAAM,EACf,OAAO;QACL,QAAQS;QACR,YAAY;IACd;IAGF,OAAO;QACL,QAAQ;YACN,QAAQI,WAAWd;YACnBC;YACA,yBAAyB;QAC3B;QACA,YAAYA,OAAO,MAAM;IAC3B;AACF"}

package/dist/es/agent/screenshot-preparation.mjs

@@ -0,0 +1,37 @@
+import { convertBase64ImageToJpeg, imageInfoOfBase64, resizeBase64ImageToJpeg } from "@aiscene/shared/img";
+const SCREENSHOT_JPEG_QUALITY = 90;
+function assertValidSize(size, label) {
+    if (!Number.isFinite(size.width) || !Number.isFinite(size.height)) throw new Error(`Invalid ${label}: width and height must be finite numbers. Received width: ${size.width}, height: ${size.height}`);
+    if (size.width <= 0 || size.height <= 0) throw new Error(`Invalid ${label}: width and height must be positive numbers. Received width: ${size.width}, height: ${size.height}`);
+}
+async function prepareRawScreenshot(screenshotBase64, options) {
+    const shrinkFactor = options?.shrinkFactor ?? 1;
+    if (!Number.isFinite(shrinkFactor) || shrinkFactor < 1) throw new Error(`Invalid screenshotShrinkFactor: must be a finite number >= 1. Received: ${shrinkFactor}`);
+    const originalSize = await imageInfoOfBase64(screenshotBase64);
+    assertValidSize(originalSize, 'screenshot dimensions');
+    const shotSize = shrinkFactor > 1 ? {
+        width: Math.round(originalSize.width / shrinkFactor),
+        height: Math.round(originalSize.height / shrinkFactor)
+    } : {
+        ...originalSize
+    };
+    assertValidSize(shotSize, 'prepared screenshot dimensions');
+    const base64 = await resizeBase64ImageToJpeg(screenshotBase64, {
+        sourceSize: originalSize,
+        targetSize: shotSize,
+        jpegQuality: SCREENSHOT_JPEG_QUALITY
+    });
+    return {
+        base64,
+        originalSize,
+        shotSize
+    };
+}
+async function prepareScreenshotForPersistence(screenshotBase64, options) {
+    const shrinkFactor = options?.shrinkFactor ?? 1;
+    if (1 === shrinkFactor) return convertBase64ImageToJpeg(screenshotBase64, SCREENSHOT_JPEG_QUALITY);
+    return (await prepareRawScreenshot(screenshotBase64, options)).base64;
+}
+export { prepareRawScreenshot, prepareScreenshotForPersistence };
+
+//# sourceMappingURL=screenshot-preparation.mjs.map

package/dist/es/agent/screenshot-preparation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent/screenshot-preparation.mjs","sources":["../../../src/agent/screenshot-preparation.ts"],"sourcesContent":["import {\n  type JpegBase64DataUrl,\n  convertBase64ImageToJpeg,\n  imageInfoOfBase64,\n  resizeBase64ImageToJpeg,\n} from '@aiscene/shared/img';\nimport type { Size } from '../types';\n\nconst SCREENSHOT_JPEG_QUALITY = 90;\n\nexport interface PrepareRawScreenshotOptions {\n  shrinkFactor?: number;\n}\n\nexport interface PreparedScreenshot {\n  base64: JpegBase64DataUrl;\n  originalSize: Size;\n  shotSize: Size;\n}\n\nfunction assertValidSize(size: Size, label: string): void {\n  if (!Number.isFinite(size.width) || !Number.isFinite(size.height)) {\n    throw new Error(\n      `Invalid ${label}: width and height must be finite numbers. Received width: ${size.width}, height: ${size.height}`,\n    );\n  }\n  if (size.width <= 0 || size.height <= 0) {\n    throw new Error(\n      `Invalid ${label}: width and height must be positive numbers. Received width: ${size.width}, height: ${size.height}`,\n    );\n  }\n}\n\n/**\n * Prepare one raw screenshot for model context or observation persistence.\n * Each raw screenshot must pass through this pipeline at most once.\n */\nexport async function prepareRawScreenshot(\n  screenshotBase64: string,\n  options?: PrepareRawScreenshotOptions,\n): Promise<PreparedScreenshot> {\n  const shrinkFactor = options?.shrinkFactor ?? 1;\n  if (!Number.isFinite(shrinkFactor) || shrinkFactor < 1) {\n    throw new Error(\n      `Invalid screenshotShrinkFactor: must be a finite number >= 1. Received: ${shrinkFactor}`,\n    );\n  }\n\n  const originalSize = await imageInfoOfBase64(screenshotBase64);\n  assertValidSize(originalSize, 'screenshot dimensions');\n\n  const shotSize =\n    shrinkFactor > 1\n      ? {\n          width: Math.round(originalSize.width / shrinkFactor),\n          height: Math.round(originalSize.height / shrinkFactor),\n        }\n      : { ...originalSize };\n  assertValidSize(shotSize, 'prepared screenshot dimensions');\n\n  const base64 = await resizeBase64ImageToJpeg(screenshotBase64, {\n    sourceSize: originalSize,\n    targetSize: shotSize,\n    jpegQuality: SCREENSHOT_JPEG_QUALITY,\n  });\n\n  return {\n    base64,\n    originalSize,\n    shotSize,\n  };\n}\n\n/**\n * Prepare a screenshot for persistence when only JPEG output is required.\n * Unscaled frames avoid dimension reads; scaled frames use the full pipeline.\n */\nexport async function prepareScreenshotForPersistence(\n  screenshotBase64: string,\n  options?: PrepareRawScreenshotOptions,\n): Promise<JpegBase64DataUrl> {\n  const shrinkFactor = options?.shrinkFactor ?? 1;\n  if (shrinkFactor === 1) {\n    return convertBase64ImageToJpeg(screenshotBase64, SCREENSHOT_JPEG_QUALITY);\n  }\n  return (await prepareRawScreenshot(screenshotBase64, options)).base64;\n}\n"],"names":["SCREENSHOT_JPEG_QUALITY","assertValidSize","size","label","Number","Error","prepareRawScreenshot","screenshotBase64","options","shrinkFactor","originalSize","imageInfoOfBase64","shotSize","Math","base64","resizeBase64ImageToJpeg","prepareScreenshotForPersistence","convertBase64ImageToJpeg"],"mappings":";AAQA,MAAMA,0BAA0B;AAYhC,SAASC,gBAAgBC,IAAU,EAAEC,KAAa;IAChD,IAAI,CAACC,OAAO,QAAQ,CAACF,KAAK,KAAK,KAAK,CAACE,OAAO,QAAQ,CAACF,KAAK,MAAM,GAC9D,MAAM,IAAIG,MACR,CAAC,QAAQ,EAAEF,MAAM,2DAA2D,EAAED,KAAK,KAAK,CAAC,UAAU,EAAEA,KAAK,MAAM,EAAE;IAGtH,IAAIA,KAAK,KAAK,IAAI,KAAKA,KAAK,MAAM,IAAI,GACpC,MAAM,IAAIG,MACR,CAAC,QAAQ,EAAEF,MAAM,6DAA6D,EAAED,KAAK,KAAK,CAAC,UAAU,EAAEA,KAAK,MAAM,EAAE;AAG1H;AAMO,eAAeI,qBACpBC,gBAAwB,EACxBC,OAAqC;IAErC,MAAMC,eAAeD,SAAS,gBAAgB;IAC9C,IAAI,CAACJ,OAAO,QAAQ,CAACK,iBAAiBA,eAAe,GACnD,MAAM,IAAIJ,MACR,CAAC,wEAAwE,EAAEI,cAAc;IAI7F,MAAMC,eAAe,MAAMC,kBAAkBJ;IAC7CN,gBAAgBS,cAAc;IAE9B,MAAME,WACJH,eAAe,IACX;QACE,OAAOI,KAAK,KAAK,CAACH,aAAa,KAAK,GAAGD;QACvC,QAAQI,KAAK,KAAK,CAACH,aAAa,MAAM,GAAGD;IAC3C,IACA;QAAE,GAAGC,YAAY;IAAC;IACxBT,gBAAgBW,UAAU;IAE1B,MAAME,SAAS,MAAMC,wBAAwBR,kBAAkB;QAC7D,YAAYG;QACZ,YAAYE;QACZ,aAAaZ;IACf;IAEA,OAAO;QACLc;QACAJ;QACAE;IACF;AACF;AAMO,eAAeI,gCACpBT,gBAAwB,EACxBC,OAAqC;IAErC,MAAMC,eAAeD,SAAS,gBAAgB;IAC9C,IAAIC,AAAiB,MAAjBA,cACF,OAAOQ,yBAAyBV,kBAAkBP;IAEpD,OAAQ,OAAMM,qBAAqBC,kBAAkBC,QAAO,EAAG,MAAM;AACvE"}

package/dist/es/agent/ui-observer.mjs

@@ -0,0 +1,385 @@
+import { UIObservationRecordWriter, cloneUIObservationRecord } from "@aiscene/shared/agent-tools/observation-record";
+import { getDebug } from "@aiscene/shared/logger";
+import { assert } from "@aiscene/shared/utils";
+import { ScreenshotItem } from "../screenshot-item.mjs";
+import { prepareScreenshotForPersistence } from "./screenshot-preparation.mjs";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const debug = getDebug('ui-observer');
+const warnObserver = getDebug('ui-observer', {
+    console: true
+});
+const DEFAULT_INTERVAL_MS = 1000;
+const MIN_INTERVAL_MS = 200;
+const DEFAULT_MAX_FRAMES = 30;
+const FIRST_FRAME_TIMEOUT_MS = 3000;
+const DEFAULT_WATCHDOG_MS = 300000;
+const MAX_FRAMES_PER_RECORD = 50;
+const DECODE_BATCH_SIZE = 4;
+class UIObservationImpl {
+    get frameCount() {
+        return this.record.frames.length;
+    }
+    get startedAt() {
+        return this.record.startedAt;
+    }
+    get endedAt() {
+        return this.record.endedAt;
+    }
+    ensureUsable() {
+        assert(!this.disposed, 'UI observation has been disposed');
+    }
+    ensureFixedWindowOptions(options) {
+        assert(options?.domIncluded === void 0, 'UIObservation does not support domIncluded because it only evaluates recorded screenshots');
+    }
+    async aiQuery(demand, options) {
+        this.ensureUsable();
+        this.ensureFixedWindowOptions(options);
+        return this.insight.aiQuery(demand, options);
+    }
+    async aiBoolean(prompt, options) {
+        this.ensureUsable();
+        this.ensureFixedWindowOptions(options);
+        return this.insight.aiBoolean(prompt, options);
+    }
+    async aiNumber(prompt, options) {
+        this.ensureUsable();
+        this.ensureFixedWindowOptions(options);
+        return this.insight.aiNumber(prompt, options);
+    }
+    async aiString(prompt, options) {
+        this.ensureUsable();
+        this.ensureFixedWindowOptions(options);
+        return this.insight.aiString(prompt, options);
+    }
+    async aiAsk(prompt, options) {
+        this.ensureUsable();
+        this.ensureFixedWindowOptions(options);
+        return this.insight.aiAsk(prompt, options);
+    }
+    async aiAssert(assertion, message, options) {
+        this.ensureUsable();
+        this.ensureFixedWindowOptions(options);
+        return this.insight.aiAssert(assertion, message, options);
+    }
+    async exportRecord() {
+        this.ensureUsable();
+        return cloneUIObservationRecord(this.record);
+    }
+    async dispose() {
+        if (this.disposed) return;
+        this.disposeRecord?.();
+        this.disposed = true;
+        this.onDisposed?.();
+    }
+    constructor(record, insight, disposeRecord, onDisposed){
+        _define_property(this, "insight", void 0);
+        _define_property(this, "disposeRecord", void 0);
+        _define_property(this, "onDisposed", void 0);
+        _define_property(this, "disposed", void 0);
+        _define_property(this, "record", void 0);
+        this.insight = insight;
+        this.disposeRecord = disposeRecord;
+        this.onDisposed = onDisposed;
+        this.disposed = false;
+        this.record = cloneUIObservationRecord(record);
+    }
+}
+function isImageDataUrl(value) {
+    return 'string' == typeof value && /^data:image\/(?:png|jpe?g);base64,/i.test(value);
+}
+class UIObserverImpl {
+    get bufferedFrameCount() {
+        return this.frames.length;
+    }
+    async start() {
+        assert(!this.loopPromise && !this.stopped, 'observer has already started');
+        this.startedAt = Date.now();
+        try {
+            this.source = await this.deps.openFrameSource() ?? null;
+        } catch (error) {
+            debug(`frame source unavailable, using screenshot fallback: ${error}`);
+            this.source = null;
+        }
+        this.usingFallback = !this.source;
+        if (this.usingFallback) debug('no continuous frame source; sampling via plain screenshots');
+        else {
+            const waitStart = Date.now();
+            while(!this.source.latest() && Date.now() - waitStart < FIRST_FRAME_TIMEOUT_MS)await new Promise((resolve)=>setTimeout(resolve, 50));
+            if (!this.source.latest()) debug(`no first frame within ${FIRST_FRAME_TIMEOUT_MS}ms; starting anyway`);
+        }
+        await this.captureOnce();
+        this.loopPromise = this.runLoop();
+        if (this.watchdogMs > 0) {
+            this.watchdogTimer = setTimeout(()=>{
+                warnObserver(`UIObserver auto-stopped after ${this.watchdogMs}ms. Call observer.stop() explicitly to avoid this.`);
+                this.stop().catch(()=>{});
+            }, this.watchdogMs);
+            if ('function' == typeof this.watchdogTimer.unref) this.watchdogTimer.unref();
+        }
+    }
+    stop() {
+        if (!this.stopPromise) this.stopPromise = this.finalizeStop();
+        return this.stopPromise;
+    }
+    async finalizeStop() {
+        this.stopped = true;
+        if (this.watchdogTimer) {
+            clearTimeout(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+        await this.loopPromise;
+        try {
+            if (this.frames.length > 0) this.persistPromise = this.persistUnstoredFrames().catch((error)=>{
+                debug(`frame persistence failed, will retry during export: ${error}`);
+            });
+            const representativePromise = this.deps.capturePreparedRepresentative();
+            const [, representative] = await Promise.all([
+                this.persistPromise,
+                representativePromise
+            ]);
+            const lastFrame = this.frames.at(-1);
+            if (this.source && lastFrame?.persisted) {
+                this.representativeFrame = {
+                    ...lastFrame.persisted,
+                    capturedAt: lastFrame.capturedAt
+                };
+                representative.screenshot = ScreenshotItem.fromFile(this.writer.resolveFramePath(lastFrame.persisted), lastFrame.persisted.mimeType, lastFrame.capturedAt);
+                debug('representative screenshot aligned with last sampled frame');
+            }
+            this.representative = representative;
+            const endedAt = Date.now();
+            const record = await this.finalizeRecord(endedAt);
+            this.observation = new UIObservationImpl(record, this.deps.createInsight(record), ()=>this.writer.dispose(), this.deps.onDisposed);
+            return this.observation;
+        } finally{
+            if (this.source) try {
+                await this.source.stop();
+            } catch (error) {
+                debug(`error stopping frame source: ${error}`);
+            }
+            debug(`observation stopped with ${this.frames.length} buffered frames (+1 representative)`);
+            this.deps.onStopped?.();
+        }
+    }
+    async finalizeRecord(endedAt) {
+        assert(this.stopped && this.representative, 'observation must be stopped before finalizing the observed window');
+        if (this.persistPromise) {
+            await this.persistPromise;
+            this.persistPromise = null;
+        }
+        await this.persistUnstoredFrames();
+        const sampledFrames = this.frames.map((frame)=>{
+            assert(frame.persisted, 'observation frame was not persisted');
+            return {
+                ...frame.persisted,
+                capturedAt: frame.capturedAt
+            };
+        });
+        if (!this.representativeFrame) {
+            const representative = this.representative;
+            this.representativeFrame = this.writer.persistFrame(representative.screenshot.base64, representative.screenshot.capturedAt);
+            representative.screenshot = ScreenshotItem.fromFile(this.writer.resolveFramePath(this.representativeFrame), this.representativeFrame.mimeType, this.representativeFrame.capturedAt);
+        }
+        const frames = [
+            ...sampledFrames,
+            this.representativeFrame
+        ];
+        if (frames.length > MAX_FRAMES_PER_RECORD) warnObserver(`WARNING: exporting ${frames.length} frames (soft limit ${MAX_FRAMES_PER_RECORD}). Running insight against this observation sends every frame to the model; consider increasing intervalMs or decreasing maxFrames to reduce token cost.`);
+        debug(`exporting ${frames.length} file-backed observation frames (${this.persistedByRef.size} decoded source refs)`);
+        const metadata = {
+            startedAt: this.startedAt,
+            endedAt,
+            shotSize: {
+                ...this.representative.shotSize
+            },
+            shrunkShotToLogicalRatio: this.representative.shrunkShotToLogicalRatio
+        };
+        return this.writer.finalize(frames, metadata);
+    }
+    async dispose() {
+        if (this.disposed) return;
+        try {
+            if (this.stopPromise) await this.stopPromise;
+            else if (!this.stopped) await this.stop();
+        } finally{
+            if (this.observation) await this.observation.dispose();
+            else {
+                this.writer.dispose();
+                this.deps.onDisposed?.();
+            }
+            this.frames = [];
+            this.persistedByRef.clear();
+            this.observation = null;
+            this.disposed = true;
+        }
+    }
+    async persistUnstoredFrames() {
+        const uniqueFrames = this.dedupeRefs(this.frames.filter((frame)=>!frame.persisted));
+        const uncachedFrames = uniqueFrames.filter((frame)=>!this.persistedByRef.has(frame.ref));
+        for(let start = 0; start < uncachedFrames.length; start += DECODE_BATCH_SIZE){
+            const batch = uncachedFrames.slice(start, start + DECODE_BATCH_SIZE);
+            const decoded = this.source ? await this.source.decode(batch) : batch.map((frame)=>{
+                assert(isImageDataUrl(frame.ref), 'fallback observation frame must be an image data URL');
+                return frame.ref;
+            });
+            assert(decoded.length === batch.length, 'frame source decode() must return one image per frame handle');
+            const preparedDataUrls = await Promise.all(decoded.map((dataUrl)=>prepareScreenshotForPersistence(dataUrl, {
+                    shrinkFactor: this.screenshotShrinkFactor
+                })));
+            for(let index = 0; index < batch.length; index++)this.persistedByRef.set(batch[index].ref, this.writer.persistFrame(preparedDataUrls[index], batch[index].capturedAt));
+        }
+        for (const frame of this.frames)frame.persisted ??= this.persistedByRef.get(frame.ref);
+        if (uncachedFrames.length > 0) debug(`decoded and persisted ${uncachedFrames.length} source frames`);
+    }
+    async captureOnce() {
+        try {
+            if (this.source) {
+                const frame = this.source.latest();
+                if (!frame) return;
+                if (isImageDataUrl(frame.ref)) {
+                    const preparedDataUrl = await prepareScreenshotForPersistence(frame.ref, {
+                        shrinkFactor: this.screenshotShrinkFactor
+                    });
+                    const persisted = this.writer.persistFrame(preparedDataUrl, frame.capturedAt);
+                    this.pushFrame({
+                        ref: persisted.path,
+                        capturedAt: frame.capturedAt,
+                        persisted
+                    });
+                } else this.pushFrame(frame);
+                return;
+            }
+            const preparedDataUrl = await prepareScreenshotForPersistence(await this.deps.captureRawScreenshot(), {
+                shrinkFactor: this.screenshotShrinkFactor
+            });
+            const persisted = this.writer.persistFrame(preparedDataUrl, Date.now());
+            this.pushFrame({
+                ref: persisted.path,
+                capturedAt: persisted.capturedAt,
+                persisted
+            });
+        } catch (error) {
+            debug(`frame capture failed, skipping tick: ${error}`);
+        }
+    }
+    async runLoop() {
+        while(!this.stopped){
+            const tickStart = Date.now();
+            await this.captureOnce();
+            while(!this.stopped && Date.now() - tickStart < this.intervalMs)await new Promise((resolve)=>setTimeout(resolve, 50));
+        }
+    }
+    pushFrame(frame) {
+        this.frames.push(frame);
+        if (this.frames.length > this.maxFrames) {
+            this.frames = this.thinBuffer(this.frames);
+            this.writer.pruneFrames(this.frames.flatMap((retainedFrame)=>retainedFrame.persisted ? [
+                    retainedFrame.persisted
+                ] : []));
+            debug(`frame buffer thinned to ${this.frames.length} frames`);
+        }
+    }
+    thinBuffer(frames) {
+        if (frames.length <= 1) return frames;
+        const isChangePoint = new Array(frames.length).fill(false);
+        isChangePoint[0] = true;
+        for(let index = 1; index < frames.length; index++)if (frames[index].ref !== frames[index - 1].ref) isChangePoint[index] = true;
+        isChangePoint[frames.length - 1] = true;
+        let result = [];
+        let staticCounter = 0;
+        for(let index = 0; index < frames.length; index++)if (isChangePoint[index]) {
+            result.push(frames[index]);
+            staticCounter = 0;
+        } else if (staticCounter % 2 === 0) {
+            result.push(frames[index]);
+            staticCounter++;
+        } else staticCounter++;
+        if (result.length > this.maxFrames) {
+            const step = result.length / this.maxFrames;
+            const sampled = [];
+            for(let index = 0; index < this.maxFrames; index++)sampled.push(result[Math.floor(index * step)]);
+            sampled[this.maxFrames - 1] = result[result.length - 1];
+            result = sampled;
+        }
+        return result;
+    }
+    dedupeRefs(frames) {
+        const seen = new Set();
+        const result = [];
+        for (const frame of frames)if (!seen.has(frame.ref)) {
+            seen.add(frame.ref);
+            result.push(frame);
+        }
+        return result;
+    }
+    constructor(deps, opt){
+        _define_property(this, "deps", void 0);
+        _define_property(this, "frames", void 0);
+        _define_property(this, "source", void 0);
+        _define_property(this, "usingFallback", void 0);
+        _define_property(this, "stopped", void 0);
+        _define_property(this, "disposed", void 0);
+        _define_property(this, "loopPromise", void 0);
+        _define_property(this, "stopPromise", void 0);
+        _define_property(this, "representative", void 0);
+        _define_property(this, "representativeFrame", void 0);
+        _define_property(this, "watchdogTimer", void 0);
+        _define_property(this, "persistPromise", void 0);
+        _define_property(this, "persistedByRef", void 0);
+        _define_property(this, "observation", void 0);
+        _define_property(this, "startedAt", void 0);
+        _define_property(this, "intervalMs", void 0);
+        _define_property(this, "maxFrames", void 0);
+        _define_property(this, "watchdogMs", void 0);
+        _define_property(this, "screenshotShrinkFactor", void 0);
+        _define_property(this, "writer", void 0);
+        this.deps = deps;
+        this.frames = [];
+        this.source = null;
+        this.usingFallback = false;
+        this.stopped = false;
+        this.disposed = false;
+        this.loopPromise = null;
+        this.stopPromise = null;
+        this.representative = null;
+        this.representativeFrame = null;
+        this.watchdogTimer = null;
+        this.persistPromise = null;
+        this.persistedByRef = new Map();
+        this.observation = null;
+        this.startedAt = 0;
+        this.intervalMs = Math.max(MIN_INTERVAL_MS, opt?.intervalMs ?? DEFAULT_INTERVAL_MS);
+        this.maxFrames = Math.max(2, opt?.maxFrames ?? DEFAULT_MAX_FRAMES);
+        this.watchdogMs = opt?.watchdogMs ?? DEFAULT_WATCHDOG_MS;
+        this.screenshotShrinkFactor = deps.screenshotShrinkFactor ?? 1;
+        this.writer = deps.observationRecordWriter ?? new UIObservationRecordWriter();
+    }
+}
+function uiContextFromObservationRecord(record) {
+    assert('midscene_ui_observation' === record.type && 1 === record.version, 'invalid UI observation record type or version');
+    assert(record.frames.length > 0, 'UI observation record contains no frames');
+    assert(Number.isFinite(record.shotSize.width) && record.shotSize.width > 0, 'UI observation record shot width must be positive');
+    assert(Number.isFinite(record.shotSize.height) && record.shotSize.height > 0, 'UI observation record shot height must be positive');
+    assert(Number.isFinite(record.shrunkShotToLogicalRatio) && record.shrunkShotToLogicalRatio > 0, 'UI observation record screenshot ratio must be positive');
+    const screenshotSequence = record.frames.map((frame)=>ScreenshotItem.fromFile(frame.path, frame.mimeType, frame.capturedAt));
+    return {
+        screenshot: screenshotSequence[screenshotSequence.length - 1],
+        screenshotSequence,
+        shotSize: {
+            ...record.shotSize
+        },
+        shrunkShotToLogicalRatio: record.shrunkShotToLogicalRatio
+    };
+}
+export { UIObservationImpl, UIObserverImpl, uiContextFromObservationRecord };
+
+//# sourceMappingURL=ui-observer.mjs.map