@nebulacomponents/citable 1.11.0 → 1.13.0

package/src/commands/scenario.js

@@ -0,0 +1,98 @@
+/**
+ * scenario command — Scenario War Room
+ *
+ * Models compound risks with cascade analysis and early-warning triggers.
+ * Maximum 3 variables per scenario. Requires explicit hedges with cost,
+ * impact, owner, and deadline — not just worst-case narratives.
+ *
+ * Usage:
+ *   citable scenario list
+ *   citable scenario show <scenario_id>
+ *   citable scenario validate
+ *   citable scenario triggers   — early-warning trigger summary
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+export async function scenarioCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'scenarios.yaml');
+
+  switch (subcommand) {
+    case 'show':     return scenarioShow(file, rest[0]);
+    case 'validate': return scenarioValidate(file);
+    case 'triggers': return scenarioTriggers(file);
+    default:         return scenarioList(file);
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'scenarios');
+}
+
+function scenarioList(file) {
+  const data = load(file);
+  return {
+    scenarios: data.entries.map(s => ({
+      scenario_id: s.scenario_id,
+      title: s.title,
+      variables: (s.variables ?? []).length,
+      cascade_steps: (s.cascade_analysis ?? []).length,
+      hedges: (s.hedges ?? []).length,
+      early_warnings: (s.early_warning_triggers ?? []).length,
+      owner: s.owner,
+    })),
+    total: data.entries.length,
+  };
+}
+
+function scenarioShow(file, id) {
+  if (!id) return { error: 'scenario_id required' };
+  const data = load(file);
+  const s = data.entries.find(e => e.scenario_id === id);
+  if (!s) return { error: `Scenario not found: ${id}` };
+  return { scenario: s };
+}
+
+function scenarioTriggers(file) {
+  const data = load(file);
+  return {
+    triggers: data.entries.flatMap(s =>
+      (s.early_warning_triggers ?? []).map(t => ({
+        scenario_id: s.scenario_id, title: s.title, trigger: t,
+      }))
+    ),
+    total_scenarios: data.entries.length,
+  };
+}
+
+function scenarioValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('scenario.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const s of data.entries) {
+    // Variables capped at 3
+    if ((s.variables ?? []).length > 3)
+      problems.push(`${s.scenario_id}: maximum 3 variables per scenario — combine compound drivers into a single variable`);
+    // Cascade analysis required (not just isolated risk statements)
+    if (!s.cascade_analysis || s.cascade_analysis.length === 0)
+      problems.push(`${s.scenario_id}: cascade_analysis required — scenarios must show cascading effects, not isolated risks`);
+    // All three states required
+    if (!s.states?.base || !s.states?.stress || !s.states?.severe)
+      problems.push(`${s.scenario_id}: all three states (base, stress, severe) required`);
+    // Hedges must have all required fields
+    for (const h of s.hedges ?? []) {
+      if (!h.cost || !h.impact || !h.owner || !h.deadline)
+        problems.push(`${s.scenario_id} hedge "${h.action}": cost, impact, owner, and deadline all required`);
+    }
+    // Early-warning triggers required
+    if (!s.early_warning_triggers || s.early_warning_triggers.length === 0)
+      problems.push(`${s.scenario_id}: early_warning_triggers required — scenario without triggers is a narrative, not a management tool`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/commands/variance.js

@@ -0,0 +1,102 @@
+/**
+ * variance command — Variance analysis registry
+ *
+ * Rejects non-causes (market conditions, timing, customer behaviour)
+ * unless decomposed into specific observed mechanisms.
+ *
+ * Usage:
+ *   citable variance list [--period <period>]
+ *   citable variance show <variance_id>
+ *   citable variance validate
+ *   citable variance material   — list material/critical variances only
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+// Vague causes that must be decomposed before acceptance
+const REJECTED_CAUSE_PATTERNS = [
+  /^market conditions?$/i,
+  /^timing$/i,
+  /^customer behaviour?$/i,
+  /^execution issues?$/i,
+  /^macro(economic)?$/i,
+  /^seasonality$/i,
+];
+
+export async function varianceCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'variances.yaml');
+
+  switch (subcommand) {
+    case 'show':     return varianceShow(file, rest[0]);
+    case 'validate': return varianceValidate(file);
+    case 'material': return varianceList(file, { materialOnly: true });
+    default: {
+      const i = rest.indexOf('--period');
+      return varianceList(file, { period: i >= 0 ? rest[i + 1] : null });
+    }
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'variances');
+}
+
+function varianceList(file, { materialOnly = false, period = null } = {}) {
+  const data = load(file);
+  let entries = data.entries;
+  if (materialOnly) entries = entries.filter(v => ['material','critical'].includes(v.materiality));
+  if (period) entries = entries.filter(v => v.period === period);
+  return {
+    variances: entries.map(v => ({
+      variance_id:    v.variance_id,
+      metric_id:      v.metric_id,
+      period:         v.period,
+      variance_pct:   v.variance_pct,
+      materiality:    v.materiality,
+      primary_driver: v.primary_driver,
+      controllable:   v.controllable,
+      confidence:     v.confidence,
+    })),
+    total: entries.length,
+  };
+}
+
+function varianceShow(file, id) {
+  if (!id) return { error: 'variance_id required' };
+  const data = load(file);
+  const v = data.entries.find(e => e.variance_id === id);
+  if (!v) return { error: `Variance not found: ${id}` };
+  return { variance: v };
+}
+
+function varianceValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('variance.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const v of data.entries) {
+    // Reject vague causes
+    for (const pattern of REJECTED_CAUSE_PATTERNS) {
+      if (pattern.test((v.primary_driver ?? '').trim())) {
+        problems.push(`${v.variance_id}: primary_driver "${v.primary_driver}" is a non-cause — decompose into a specific observed mechanism`);
+      }
+      for (const d of v.secondary_drivers ?? []) {
+        if (pattern.test(d.trim())) {
+          problems.push(`${v.variance_id}: secondary_driver "${d}" is a non-cause — decompose into a specific observed mechanism`);
+        }
+      }
+    }
+    // Material variances need management response
+    if (['material','critical'].includes(v.materiality) && !v.management_response)
+      problems.push(`${v.variance_id}: material variance requires management_response`);
+    // Evidence required
+    if (!v.evidence || v.evidence.length === 0)
+      problems.push(`${v.variance_id}: evidence array must not be empty`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/detectors/framework.js

@@ -100,12 +100,49 @@ export function runDetectors(detectors, ctx) {
 /** Pages whose declared or default intent is to be indexed. */
 export function indexTargets(ctx) {
   return ctx.site.pages.filter((p) => {
+    if (isProviderUtilityUrl(p.url)) return false;
     const reg = registryPageFor(ctx, p);
     if (reg?.indexing_intent === 'noindex') return false;
     return true;
   });
 }
 
+/** Index targets whose response is an HTML document. */
+export function htmlIndexTargets(ctx) {
+  return indexTargets(ctx).filter(isHtmlDocument);
+}
+
+export function isHtmlDocument(page) {
+  const type = String(page?.contentType || '').toLowerCase();
+  return !type || type.includes('text/html') || type.includes('application/xhtml+xml');
+}
+
+/** URLs that conventionally identify HTML documents rather than media/data resources. */
+export function isHtmlDocumentUrl(url) {
+  try {
+    const pathname = new URL(url).pathname;
+    const name = pathname.split('/').pop() || '';
+    const match = name.match(/\.([a-z0-9]+)$/i);
+    return Boolean(match) && ['html', 'htm', 'xhtml'].includes(match[1].toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function hasHtmlDocumentMarkup(page) {
+  return /^\s*(?:<!doctype\s+html\b|<html\b)/i.test(String(page?.rawHtml || ''));
+}
+
+/** Provider-owned utility routes are link evidence, not default content pages. */
+export function isProviderUtilityUrl(url) {
+  try {
+    const { pathname } = new URL(url);
+    return pathname === '/cdn-cgi' || pathname.startsWith('/cdn-cgi/');
+  } catch {
+    return false;
+  }
+}
+
 /** Match a live page to its registry entry by URL path. */
 export function registryPageFor(ctx, page) {
   const entries = ctx.registries?.pages?.entries || [];

package/src/detectors/page.js

@@ -1,4 +1,4 @@
-import { defineDetector, indexTargets, pageSubject } from './framework.js';
+import { defineDetector, htmlIndexTargets, pageSubject } from './framework.js';
 
 const D = [];
 
@@ -11,7 +11,7 @@ D.push(defineDetector({
   remediation: 'Add a concise title identifying the page subject and distinguishing it from other pages.',
   verification: 'Confirm a non-empty <title> in rendered HTML.',
   check(ctx) {
-    return indexTargets(ctx).filter((p) => p.status === 200 && !p.title).map((p) => ({
+    return htmlIndexTargets(ctx).filter((p) => p.status === 200 && !p.title).map((p) => ({
       subject: pageSubject(p), summary: 'Page has no title element', evidence: ['<title> absent or empty'],
     }));
   },
@@ -27,7 +27,7 @@ D.push(defineDetector({
   verification: 'Confirm title uniqueness across index targets.',
   check(ctx) {
     const byTitle = new Map();
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (!p.title || p.status !== 200) continue;
       if (!byTitle.has(p.title)) byTitle.set(p.title, []);
       byTitle.get(p.title).push(p);
@@ -49,7 +49,7 @@ D.push(defineDetector({
   remediation: 'Add an accurate, page-specific description stating the expected value.',
   verification: 'Confirm meta[name=description] present and non-empty.',
   check(ctx) {
-    return indexTargets(ctx).filter((p) => p.status === 200 && !p.metaDescription).map((p) => ({
+    return htmlIndexTargets(ctx).filter((p) => p.status === 200 && !p.metaDescription).map((p) => ({
       subject: pageSubject(p), summary: 'Page has no meta description', evidence: ['meta[name=description] absent'],
     }));
   },
@@ -65,7 +65,7 @@ D.push(defineDetector({
   verification: 'Confirm description uniqueness.',
   check(ctx) {
     const byDesc = new Map();
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (!p.metaDescription || p.status !== 200) continue;
       if (!byDesc.has(p.metaDescription)) byDesc.set(p.metaDescription, []);
       byDesc.get(p.metaDescription).push(p);
@@ -87,7 +87,7 @@ D.push(defineDetector({
   remediation: 'Use exactly one H1 that identifies the page purpose.',
   verification: 'Count H1 elements.',
   check(ctx) {
-    return indexTargets(ctx).filter((p) => p.status === 200 && p.h1s.length !== 1).map((p) => ({
+    return htmlIndexTargets(ctx).filter((p) => p.status === 200 && p.h1s.length !== 1).map((p) => ({
       subject: pageSubject(p),
       summary: p.h1s.length === 0 ? 'Page has no H1' : `Page has ${p.h1s.length} H1 elements`,
       evidence: p.h1s.length ? p.h1s.map((h) => `H1: ${h.text}`) : ['no <h1> found'],
@@ -106,7 +106,7 @@ D.push(defineDetector({
   verification: 'Walk heading sequence and confirm no level is skipped.',
   check(ctx) {
     const hits = [];
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (p.status !== 200) continue;
       let prev = 0;
       for (const h of p.headings) {
@@ -134,7 +134,7 @@ D.push(defineDetector({
   remediation: 'Add descriptive alt text (or empty alt for purely decorative images, reviewed case by case).',
   verification: 'Confirm every <img> has an alt attribute.',
   check(ctx) {
-    return indexTargets(ctx)
+    return htmlIndexTargets(ctx)
       .map((p) => ({ p, missing: p.images.filter((i) => i.alt === undefined || i.alt === null) }))
       .filter(({ p, missing }) => p.status === 200 && missing.length > 0)
       .map(({ p, missing }) => ({
@@ -156,7 +156,7 @@ D.push(defineDetector({
   verification: 'Re-measure extracted word count after revision.',
   check(ctx) {
     const min = ctx.config?.audit?.thin_content_words ?? 120;
-    return indexTargets(ctx)
+    return htmlIndexTargets(ctx)
       .filter((p) => p.status === 200 && p.wordCount > 0 && p.wordCount < min)
       .map((p) => ({
         subject: pageSubject(p),
@@ -178,7 +178,7 @@ D.push(defineDetector({
   verification: 'Re-measure dominant-term density.',
   check(ctx) {
     const hits = [];
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (p.status !== 200 || p.wordCount < 80) continue;
       const words = p.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || [];
       const freq = new Map();

package/src/detectors/tech.js

@@ -1,4 +1,4 @@
-import { defineDetector, indexTargets, registryPageFor, pageSubject, safePath } from './framework.js';
+import { defineDetector, hasHtmlDocumentMarkup, indexTargets, isHtmlDocument, isHtmlDocumentUrl, registryPageFor, pageSubject, safePath } from './framework.js';
 import { isAllowed } from '../crawler/robots.js';
 
 const D = [];
@@ -177,7 +177,9 @@ D.push(defineDetector({
     for (const sm of ctx.site.sitemaps) {
       for (const u of sm.parsed.urls) {
         const page = ctx.site.byUrl.get(ctx.site.normalize(u.loc));
-        if (!page) {
+        if (!page && ctx.site.mode === 'url' && ctx.site.crawl?.truncated) {
+          continue;
+        } else if (!page) {
           hits.push({
             subject: { type: 'url', identifier: u.loc, url: u.loc, source_location: sm.source },
             summary: 'Sitemap URL not present in audited output',
@@ -227,7 +229,7 @@ D.push(defineDetector({
   verification: 'Inspect the Content-Type response header.',
   check(ctx) {
     return indexTargets(ctx)
-      .filter((p) => p.status === 200 && p.contentType && !p.contentType.includes('text/html'))
+      .filter((p) => p.status === 200 && p.contentType && (isHtmlDocumentUrl(p.url) || hasHtmlDocumentMarkup(p)) && !isHtmlDocument(p))
       .map((p) => ({
         subject: pageSubject(p),
         summary: `HTML page served with Content-Type "${p.contentType}"`,

package/src/extractor/site.js

@@ -59,6 +59,7 @@ export function buildSiteFromDir(dir, { baseUrl = 'https://example.test' } = {})
 export async function buildSiteFromUrl(startUrl, {
   maxPages = 50, userAgent, pageMaxBytes = 5 * 1024 * 1024,
   robotsMaxBytes = 512 * 1024, sitemapMaxBytes = 5 * 1024 * 1024,
+  fetcher = fetchUrl,
 } = {}) {
   const origin = new URL(startUrl).origin;
   const seen = new Set();
@@ -71,7 +72,7 @@ export async function buildSiteFromUrl(startUrl, {
     if (seen.has(key)) continue;
     seen.add(key);
     try {
-      const res = await fetchUrl(url, { userAgent, maxBodyBytes: pageMaxBytes });
+      const res = await fetcher(url, { userAgent, maxBodyBytes: pageMaxBytes });
       const page = extractPage({
         url: res.url, html: res.body, status: res.status, headers: res.headers, redirectChain: res.redirectChain,
       });
@@ -81,7 +82,8 @@ export async function buildSiteFromUrl(startUrl, {
         for (const l of page.links) {
           try {
             const u = new URL(l.href, res.url);
-            if (u.origin === origin && !seen.has(u.href.replace(/#.*$/, ''))) queue.push(u.href);
+            u.hash = '';
+            if (u.origin === origin && !isProviderUtilityPath(u.pathname) && !seen.has(u.href)) queue.push(u.href);
           } catch { /* unresolvable href — surfaced by LINK detectors */ }
         }
       }
@@ -92,7 +94,7 @@ export async function buildSiteFromUrl(startUrl, {
   let robotsText = null;
   const sitemaps = [];
   try {
-    const r = await fetchUrl(new URL('/robots.txt', origin).href, { userAgent, maxBodyBytes: robotsMaxBytes });
+    const r = await fetcher(new URL('/robots.txt', origin).href, { userAgent, maxBodyBytes: robotsMaxBytes });
     if (r.status === 200) robotsText = r.body;
   } catch { /* recorded as missing robots */ }
   const smUrls = robotsText ? parseRobots(robotsText).sitemaps : [new URL('/sitemap.xml', origin).href];
@@ -103,16 +105,24 @@ export async function buildSiteFromUrl(startUrl, {
         errors.push(`${sitemapUrl.href}: sitemap URL leaves audited origin`);
         continue;
       }
-      const r = await fetchUrl(sitemapUrl.href, { userAgent, maxBodyBytes: sitemapMaxBytes });
+      const r = await fetcher(sitemapUrl.href, { userAgent, maxBodyBytes: sitemapMaxBytes });
       if (r.status === 200) sitemaps.push({ source: sm, parsed: parseSitemap(r.body) });
     } catch { /* absence handled by TECH detectors */ }
   }
-  const site = assembleSite({ baseUrl: origin, pages, robotsText, sitemaps, transport: {}, mode: 'url', location: startUrl });
+  const pendingUrls = [...new Set(queue.map((url) => url.replace(/#.*$/, '')).filter((url) => !seen.has(url)))];
+  const crawl = {
+    maxPages,
+    pagesFetched: pages.length,
+    truncated: pages.length >= maxPages && pendingUrls.length > 0,
+    pendingUrlCount: pendingUrls.length,
+    pendingUrls,
+  };
+  const site = assembleSite({ baseUrl: origin, pages, robotsText, sitemaps, transport: {}, mode: 'url', location: startUrl, crawl });
   site.fetchErrors = errors;
   return site;
 }
 
-function assembleSite({ baseUrl, pages, robotsText, sitemaps, transport, mode, location }) {
+function assembleSite({ baseUrl, pages, robotsText, sitemaps, transport, mode, location, crawl = null }) {
   const byUrl = new Map();
   for (const p of pages) byUrl.set(normalize(p.url), p);
 
@@ -168,9 +178,14 @@ function assembleSite({ baseUrl, pages, robotsText, sitemaps, transport, mode, l
     outbound,
     depth,
     normalize,
+    crawl,
   };
 }
 
+function isProviderUtilityPath(pathname) {
+  return pathname === '/cdn-cgi' || pathname.startsWith('/cdn-cgi/');
+}
+
 export function normalize(url) {
   try {
     const u = new URL(url);

package/src/observations/browserJourney.js

@@ -0,0 +1,167 @@
+import { envelope, observationRun, readInput } from './common.js';
+import { fetchUrl } from '../crawler/fetch.js';
+import { sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+async function executeStep(page, step) {
+  const locator = step.locator ? page.locator(step.locator).first() : null;
+  if (step.action === 'navigate') await page.goto(step.url, { waitUntil: 'networkidle' });
+  else if (step.action === 'click') await locator.click();
+  else if (step.action === 'fill') {
+    const value = process.env[step.value_env];
+    if (value == null) throw new Error(`environment input ${step.value_env} is unavailable`);
+    await locator.fill(value);
+  } else if (step.action === 'select_option') {
+    const value = process.env[step.value_env];
+    if (value == null) throw new Error(`environment input ${step.value_env} is unavailable`);
+    await locator.selectOption(value);
+  } else if (step.action === 'check') await locator.check();
+  else if (step.action === 'press') await locator.press(step.key);
+  else if (step.action === 'wait_for') await locator.waitFor({ state: 'visible' });
+  else if (step.action === 'assert_visible' && !(await locator.isVisible())) throw new Error(`locator is not visible: ${step.locator}`);
+  else if (step.action === 'scroll') await locator.scrollIntoViewIfNeeded();
+}
+
+async function playwrightCapture(profile, plan, playwright) {
+  if (profile.authentication_state !== 'anonymous') throw new Error(`authentication state ${profile.authentication_state} requires a disclosed custom adapter`);
+  const browserType = playwright[profile.browser.engine];
+  if (!browserType) throw new Error(`Playwright engine ${profile.browser.engine} is unavailable`);
+  const browser = await browserType.launch({ headless: true });
+  try {
+    const context = await browser.newContext({
+      viewport: profile.device.viewport,
+      isMobile: profile.device.is_mobile,
+      javaScriptEnabled: profile.javascript_enabled,
+      locale: profile.locale,
+    });
+    try {
+      const page = await context.newPage();
+      const consoleErrors = [], networkFailures = [], steps = [], stepScreenshots = {};
+      page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
+      page.on('requestfailed', (request) => networkFailures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
+      const response = await page.goto(plan.target, { waitUntil: 'networkidle' });
+      for (const step of profile.steps) {
+        const record = { step_id: step.step_id, action: step.action, status: 'completed', failure: null, screenshot_ref: null };
+        try {
+          await executeStep(page, step);
+          if (step.capture_screenshot) {
+            record.screenshot_ref = `journeys/${profile.profile_id}/steps/${step.step_id}.png`;
+            stepScreenshots[record.screenshot_ref] = await page.screenshot({ fullPage: true });
+          }
+        } catch (error) {
+          record.status = 'failed';
+          record.failure = error.message;
+          steps.push(record);
+          if (step.required) throw Object.assign(new Error(`required step ${step.step_id} failed: ${error.message}`), { steps, stepScreenshots });
+          continue;
+        }
+        steps.push(record);
+      }
+      const dom = await page.content();
+      const text = await page.locator('body').innerText();
+      const accessibilityTree = typeof page.locator('body').ariaSnapshot === 'function' ? await page.locator('body').ariaSnapshot() : null;
+      return {
+        final_url: page.url(), status: response?.status() ?? null, browser_version: browser.version(),
+        dom, text, accessibility_tree: accessibilityTree, screenshot: await page.screenshot({ fullPage: true }),
+        console_errors: consoleErrors, network_failures: networkFailures, steps, step_screenshots: stepScreenshots,
+      };
+    } finally {
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+export async function observeBrowserPlan(root, options) {
+  const input = readInput(options.input);
+  const plan = input.value;
+  const check = validateAgainst('browser-evidence-plan.schema.json', plan);
+  if (!check.valid) throw new Error(`browser evidence plan violates contract: ${check.errors.join('; ')}`);
+  if (options.target && options.target !== plan.target) throw new Error('browser evidence target differs from the plan target');
+  const profileIds = plan.profiles.map((item) => item.profile_id);
+  if (new Set(profileIds).size !== profileIds.length) throw new Error('browser evidence plan contains duplicate profile ids');
+  const targetOrigin = new URL(plan.target).origin;
+  for (const profile of plan.profiles) {
+    const stepIds = profile.steps.map((item) => item.step_id);
+    if (new Set(stepIds).size !== stepIds.length) throw new Error(`${profile.profile_id}: duplicate journey step ids`);
+    for (const step of profile.steps) {
+      if (step.action === 'navigate') {
+        if (!step.url) throw new Error(`${profile.profile_id}/${step.step_id}: navigate requires url`);
+        if (new URL(step.url).origin !== targetOrigin) throw new Error(`${profile.profile_id}/${step.step_id}: cross-origin navigation is not allowed`);
+      } else if (!step.locator) throw new Error(`${profile.profile_id}/${step.step_id}: ${step.action} requires locator`);
+      if (['fill', 'select_option'].includes(step.action) && !step.value_env) throw new Error(`${profile.profile_id}/${step.step_id}: ${step.action} requires value_env`);
+      if (step.action === 'press' && !step.key) throw new Error(`${profile.profile_id}/${step.step_id}: press requires key`);
+    }
+  }
+
+  let playwright = options.playwright;
+  if (!options.captureJourney && !playwright) {
+    try { playwright = await import('playwright'); } catch {
+      const item = envelope('browser_journey', { plan_id: plan.plan_id, target: plan.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
+      return observationRun(root, 'observe render', plan.target, [item], { rawInputs: { browser_evidence_plan: input.raw }, incomplete: ['Cross-browser journey collection unavailable: install Playwright and browser engines.'] });
+    }
+  }
+
+  const initial = await (options.fetchUrl || fetchUrl)(plan.target, { maxRetries: 1 });
+  const observations = [], incomplete = [], artifacts = {
+    'initial/response.html': initial.body,
+    'initial/headers.json': initial.headers || {},
+  };
+  for (const profile of plan.profiles) {
+    const prefix = `journeys/${profile.profile_id}`;
+    try {
+      const capture = options.captureJourney
+        ? await options.captureJourney(profile, plan)
+        : await playwrightCapture(profile, plan, playwright);
+      if (!capture || typeof capture.dom !== 'string' || typeof capture.text !== 'string' || typeof capture.browser_version !== 'string' || capture.screenshot == null) {
+        throw new Error('browser adapter returned an incomplete capture contract');
+      }
+      const refs = {
+        raw_response: 'initial/response.html',
+        rendered_dom: `${prefix}/dom.html`,
+        rendered_text: `${prefix}/text.txt`,
+        accessibility_tree: capture.accessibility_tree == null ? null : `${prefix}/accessibility-tree.txt`,
+        screenshot: `${prefix}/final.png`,
+        failures: `${prefix}/failures.json`,
+        interactions: `${prefix}/steps.json`,
+      };
+      artifacts[refs.rendered_dom] = capture.dom;
+      artifacts[refs.rendered_text] = capture.text;
+      if (refs.accessibility_tree) artifacts[refs.accessibility_tree] = capture.accessibility_tree;
+      artifacts[refs.screenshot] = capture.screenshot;
+      artifacts[refs.failures] = { console_errors: capture.console_errors || [], network_failures: capture.network_failures || [] };
+      artifacts[refs.interactions] = capture.steps || [];
+      for (const [name, value] of Object.entries(capture.step_screenshots || {})) {
+        if (!name.startsWith(`${prefix}/steps/`) || name.includes('..')) throw new Error(`browser adapter returned unsafe artifact path: ${name}`);
+        artifacts[name] = value;
+      }
+      const versionMatches = profile.browser.expected_version == null || profile.browser.expected_version === capture.browser_version;
+      const data = {
+        plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id,
+        browser: { ...profile.browser, observed_version: capture.browser_version, version_matches_expectation: versionMatches },
+        device: profile.device, javascript_enabled: profile.javascript_enabled, locale: profile.locale,
+        consent_state: profile.consent_state, authentication_state: profile.authentication_state,
+        final_url: capture.final_url, status: capture.status, dom_hash: sha256(capture.dom), text_hash: sha256(capture.text),
+        steps: capture.steps || [], artifact_refs: refs,
+        interpretation_boundary: 'Observed differences do not establish semantic, retrieval, citation, ranking, or business impact.',
+      };
+      const limitations = [...plan.limitations, ...profile.limitations];
+      if (!versionMatches) limitations.push('Observed browser version differs from the planned version.');
+      observations.push(envelope('browser_journey', data, { method: 'browser', source: `playwright/${profile.browser.engine}`, raw: capture.dom, limitations }));
+    } catch (error) {
+      incomplete.push(`${profile.profile_id}: ${error.message}`);
+      const failureRef = `${prefix}/failure.json`;
+      artifacts[failureRef] = { profile_id: profile.profile_id, error: error.message, completed_steps: error.steps || [] };
+      for (const [name, value] of Object.entries(error.stepScreenshots || {})) artifacts[name] = value;
+      observations.push(envelope('browser_journey', {
+        plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id, browser: profile.browser,
+        device: profile.device, javascript_enabled: profile.javascript_enabled, locale: profile.locale,
+        consent_state: profile.consent_state, authentication_state: profile.authentication_state,
+        steps: error.steps || [], artifact_refs: { failure: failureRef },
+        interpretation_boundary: 'Profile failure does not invalidate successful profiles or establish semantic impact.',
+      }, { method: 'browser', source: `playwright/${profile.browser.engine}`, state: 'failed', confidence: 'confirmed', raw: error.message, limitations: [...plan.limitations, ...profile.limitations, error.message] }));
+    }
+  }
+  return observationRun(root, 'observe render', plan.target, observations, { rawInputs: { browser_evidence_plan: input.raw }, incomplete, artifacts });
+}

package/src/observations/media.js

@@ -29,7 +29,14 @@ async function pdfEvidence(item, file, artifacts) {
 
 function transcriptEvidence(item, file, artifacts) {
   const raw = fs.readFileSync(file, 'utf8');
-  const cues = raw.split(/\r?\n\r?\n/).map((block) => { const lines = block.split(/\r?\n/).filter(Boolean); const timing = lines.find((line) => line.includes('-->')) || null; const text = lines.filter((line) => line !== 'WEBVTT' && line !== timing && !/^\d+$/.test(line)).join(' ').replace(/<[^>]+>/g, '').trim(); return text ? { timing, text } : null; }).filter(Boolean);
+  const cues = raw.split(/\r?\n\r?\n/).map((block) => {
+    const lines = block.split(/\r?\n/).filter(Boolean);
+    const timing = lines.find((line) => line.includes('-->')) || null;
+    const fragment = parse(lines.filter((line) => line !== 'WEBVTT' && line !== timing && !/^\d+$/.test(line)).join(' '));
+    for (const node of fragment.querySelectorAll('script,style')) node.remove();
+    const text = fragment.textContent.replace(/\s+/g, ' ').trim();
+    return text ? { timing, text } : null;
+  }).filter(Boolean);
   const text = cues.map((cue) => cue.text).join(' ');
   artifacts[`media/${item.media_id}/transcript.txt`] = text;
   return envelope('media_transcript', { media_id: item.media_id, source_url: item.source_url, page_url: item.page_url, claim_ids: item.claim_ids, permission_status: item.permission_status, language: item.language || null, published_at: item.published_at || null, cues, word_count: text ? text.split(/\s+/).length : 0 }, { method: 'owner_import', source: file, raw, limitations: ['Speaker identity, transcription accuracy, timing accuracy, and media parity require human verification.', 'Transcript ingestion does not establish that linked claims are supported.'] });