@nebulacomponents/citable 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -90,14 +90,27 @@
     "ajv-formats": "^3.0.1",
     "csv-parse": "^7.0.1",
     "js-yaml": "^5.2.1",
-    "node-html-parser": "^9.0.0"
+    "node-html-parser": "^9.0.0",
+    "pdfjs-dist": "^6.1.200"
   },
   "peerDependencies": {
-    "playwright": ">=1.50.0"
+    "chrome-launcher": ">=1.2.1",
+    "lighthouse": ">=13.4.0",
+    "playwright": ">=1.50.0",
+    "tesseract.js": ">=7.0.0"
   },
   "peerDependenciesMeta": {
+    "chrome-launcher": {
+      "optional": true
+    },
+    "lighthouse": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
+    },
+    "tesseract.js": {
+      "optional": true
     }
   }
 }

package/schemas/media-manifest.schema.json

@@ -0,0 +1,2 @@
+{
+  "$id":"citable://schemas/media-manifest.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Media evidence import manifest","type":"object","additionalProperties":false,"required":["version","items"],"properties":{"version":{"const":1},"items":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["media_id","type","path","source_url","page_url","claim_ids","permission_status"],"properties":{"media_id":{"type":"string","pattern":"^MEDIA-[A-Z0-9][A-Z0-9_-]*$"},"type":{"type":"string","enum":["pdf","transcript","image"]},"path":{"type":"string","minLength":1},"source_url":{"type":["string","null"]},"page_url":{"type":["string","null"]},"claim_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"}},"permission_status":{"type":"string","enum":["owner_authorized","licensed","public_unknown","internal"]},"image_src":{"type":"string"},"language":{"type":"string"},"published_at":{"type":"string","format":"date-time"}}}}}}

package/schemas/observation.schema.json

@@ -7,7 +7,7 @@
   "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
   "properties": {
     "observation_id": { "type": "string", "minLength": 1 },
-    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
+    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image"] },
     "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
     "collected_at": { "type": "string", "format": "date-time" },
     "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.10.0
+version: 1.12.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -96,6 +96,8 @@ citable compare-snapshots [runA runB]
 citable action-plan [run-id]          # ordered actions, blockers, semantic gates, verification
 citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
 citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
+citable observe render --target <url> [--interactions] [--resume-run <run-id>]
+citable observe performance --target <url> --lighthouse [--repeat 1..5]
 citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
 citable monitor [runA runB]           # observation regression alerts
 citable metrics import --provider <name> --input <csv|json>
@@ -117,6 +119,7 @@ citable reviews sample <sampling-plan-id> [--write]
 citable reviews evaluate
 citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
 citable project github <run-id>
+citable observe media --input <manifest.json> [--ocr]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema

package/skill/commands/README.md

@@ -30,10 +30,11 @@ intent, not executability, so statuses are strict:
 | /citable governance validate / evaluate | implemented — validates reviewer and exception authority and emits immutable dispositions without changing failed findings |
 | /citable reviews queue / prioritize / plan / sample / evaluate | implemented — materiality queues, reproducible sampling, stale-decision checks, and independent disagreement adjudication |
 | /citable schedules run / project github | implemented — canonical scheduled audits and hash-bound non-authoritative GitHub projections |
+| /citable observe media | implemented — bounded PDF, transcript, image-context, optional OCR, and declared claim-link evidence |
 | /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
 | /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
 | /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |
-| /citable validate-render | partially implemented by `observe render`; mobile/cross-browser and interaction exploration remain |
+| /citable validate-render | partially implemented by `observe render`; desktop/mobile/JavaScript-disabled profiles and bounded interaction exploration are implemented, while cross-browser and application-specific journeys remain |
 | /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
 
 Shared refusal conditions (all commands): any action that would fabricate

package/skill/commands/media-evidence.md

@@ -0,0 +1,17 @@
+# Media evidence collection
+
+Use `citable observe media --input <manifest.json>` for bounded local-media
+evidence. The manifest declares source URL, owning page, permission status, and
+linked claim IDs for each PDF, transcript, or image-context source.
+
+PDF collection extracts native text, basic metadata, and stable page anchors.
+It does not establish reading order, table structure, footnote linkage,
+signatures, revisions, scan accuracy, accessibility, or claim support.
+Transcript collection preserves cues but does not verify speakers, timing,
+accuracy, or source-media parity. Image collection records alt text, captions,
+and nearby figure text without inferring visual entailment.
+
+OCR is off by default. `--ocr` explicitly requests the optional `tesseract.js`
+path; an unavailable engine or image produces incomplete evidence, never guessed
+text. Every media-to-claim relationship is declarative and still requires
+human-authoritative semantic review.

package/skill/commands/observe-and-act.md

@@ -9,7 +9,11 @@ failure_behaviour: unavailable dependency, credential, source run, reviewer, exa
 ## Collection modes
 
 - `observe render --target <URL>` uses optional Playwright. Browser evidence is
-  not search-index evidence.
+  not search-index evidence. It captures independent desktop, mobile, and
+  JavaScript-disabled profiles. `--interactions` exercises at most 20 visible
+  disclosure, inactive-tab, and load-more-like controls; it does not prove an
+  application-specific journey. `--resume-run` reuses only successful profile
+  observations from the named immutable run and recollects failed/absent ones.
 - `observe index --input <JSON>` imports owner exports. With `--target`,
   `--site-url`, and `GSC_ACCESS_TOKEN`, it calls Google URL Inspection, which
   reports the indexed version rather than performing a live indexability test.
@@ -21,6 +25,9 @@ failure_behaviour: unavailable dependency, credential, source run, reviewer, exa
   without IP verification remain low confidence.
 - `observe passages|consensus --target <dir|URL>` performs static extraction.
 - `observe performance` imports evidence or calls CrUX with `CRUX_API_KEY`.
+  `--lighthouse` instead performs 1-5 local lab runs (default 3) using optional
+  `lighthouse` and `chrome-launcher` peers, preserving each result and a median
+  summary. Lab evidence remains separate from CrUX field evidence.
 - `observe corroboration --input <JSON>` records observable external mentions;
   controlled or unverified sources do not become authority claims.
 

package/skill/references/aeo-geo-validation.md

@@ -9,7 +9,7 @@ not a prediction of citation or recommendation. Report every row as
 | State | Current evidence boundary |
 | --- | --- |
 | Retrieval eligibility | Static policy plus captured synthetic HTTP response; crawler identity remains simulated unless verified logs/IP evidence are supplied |
-| Source extraction and support suitability | Initial-HTML extraction plus registries/detectors/rubrics; rendered-DOM parity remains not established without a renderer |
+| Source extraction and support suitability | Initial HTML plus registries/detectors/rubrics; optional Chromium profiles can establish bounded raw/desktop/mobile/JavaScript-disabled parity, while cross-browser and application-specific journeys remain unproven |
 | Observed citation behavior | Operator-supplied prompt-result observations only; report cohort size and property citation presence, never infer from readiness |
 
 ## AEO checks

package/skill/references/capability-boundaries.md

@@ -9,6 +9,8 @@ Use the narrowest supported state. Never promote evidence across rows.
 | Verified crawler reached edge | Imported evidence | `observe logs` record plus provider-published IP verification where supported |
 | Observed in production logs | Imported evidence | Timestamped `observe logs` artifact with URL, status, bytes, latency, cache result, UA, and verification result |
 | Indexed | Google API or imported evidence | `observe index`; Google inspection covers the indexed version, other engines require owner exports |
+| Rendered profile observed | Optional local browser evidence | Successful profile-specific Chromium DOM, text, screenshot, failed requests, interactions, viewport, and configuration; failed profiles remain independent |
+| Render parity compared | Bounded local comparison | Raw/desktop and mobile/desktop word ratios from the same run or explicitly resumed immutable profiles; not semantic equivalence |
 | Returned by retrieval | Operator supplied | Provider observation containing retrieved source URL |
 | Cited | Import or disclosed adapter | Complete `observe citations` answer with citation URL and product/adapter mode |
 | Materially supports answer | Human review required | `citation_review` maps answer claim to source passage and names the reviewer |

package/src/cli/index.js

@@ -43,7 +43,7 @@ Commands
   compare-snapshots [a b]   Regression diff between two audit runs
   action-plan [run]         Turn audit findings into ordered remediation work
   observe <mode>            Collect render, index, citation, log, Bing, passage,
-                            consensus, performance, or corroboration evidence
+                            consensus, performance, corroboration, or media evidence
   apply                     Apply a reviewed, hash-locked remediation spec
   monitor [runA runB]       Compare observation runs and emit regression alerts
   metrics import            Import declared metric observations from CSV/JSON
@@ -84,6 +84,10 @@ Options
   --access-token <token>    OAuth token (prefer provider environment variables)
   --endpoint <url>          Controlled citation adapter endpoint
   --repeat <count>          Repetitions per prompt for citation experiments
+  --interactions            Exercise bounded disclosure, tab, and load-more controls
+  --resume-run <run-id>     Reuse successful immutable render profiles
+  --lighthouse              Run local, repeated Lighthouse lab observations
+  --ocr                     Explicitly request optional OCR for media images
   --write                   Persist registry changes (map-claims, substantiate)
   --json                    Machine-readable output only
 
@@ -96,6 +100,9 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === '--write') args.write = true;
     else if (a === '--json') args.json = true;
+    else if (a === '--ocr') args.ocr = true;
+    else if (a === '--interactions') args.interactions = true;
+    else if (a === '--lighthouse') args.lighthouse = true;
     else if (a === '--target') args.target = argv[++i];
     else if (a === '--base-url') args.baseUrl = argv[++i];
     else if (a === '--ref-date') args.refDate = argv[++i];
@@ -112,6 +119,7 @@ function parseArgs(argv) {
     else if (a === '--access-token') args.accessToken = argv[++i];
     else if (a === '--endpoint') args.endpoint = argv[++i];
     else if (a === '--repeat') args.repeat = Number(argv[++i]);
+    else if (a === '--resume-run') args.resumeRun = argv[++i];
     else if (a === '--timeout') args.timeout = Number(argv[++i]);
     else if (a === '--force') args.force = true;
     else args._.push(a);

package/src/commands/observe.js

@@ -7,6 +7,7 @@ import path from 'node:path';
 import { parse as parseCsv } from 'csv-parse/sync';
 import { crawlerIdentity } from '../observations/crawlerIdentity.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { observeMedia } from '../observations/media.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
@@ -31,37 +32,59 @@ function canonicalReview(raw, targetOrigin) {
 
 async function observeRender(root, options) {
   if (!options.target || !/^https?:\/\//.test(options.target)) throw new Error('render requires --target <http(s) URL>');
-  let playwright;
-  try { playwright = await import('playwright'); } catch {
-    const item = envelope('render', { url: options.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
-    return observationRun(root, 'observe render', options.target, [item], { incomplete: ['Rendered DOM capture unavailable: install Playwright and a Chromium browser.'] });
+  const profileNames = ['desktop', 'mobile', 'javascript_disabled'];
+  let reused = [], previousRaw = null;
+  if (options.resumeRun) {
+    const previousDir = path.join(root, '.citable', 'runs', options.resumeRun);
+    const observationsDir = path.join(previousDir, 'observations');
+    if (!fs.existsSync(observationsDir)) throw new Error(`resume run ${options.resumeRun} has no observations`);
+    reused = fs.readdirSync(observationsDir).filter((name) => name.endsWith('-render.json')).map((name) => JSON.parse(fs.readFileSync(path.join(observationsDir, name)))).filter((item) => item.state === 'observed' && profileNames.includes(item.data.profile) && item.data.url === options.target && Boolean(item.data.interaction_execution_requested) === Boolean(options.interactions));
+    previousRaw = fs.readFileSync(path.join(previousDir, 'manifest.json'), 'utf8');
+  }
+  let browser = null;
+  let capture = options.captureProfile;
+  if (!capture) {
+    let playwright;
+    try { playwright = await import('playwright'); } catch {
+      const item = envelope('render', { url: options.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
+      return observationRun(root, 'observe render', options.target, [item], { incomplete: ['Rendered DOM capture unavailable: install Playwright and a Chromium browser.'] });
+    }
+    browser = await playwright.chromium.launch({ headless: true });
   }
-  const initial = await fetchUrl(options.target, { timeoutMs: options.timeout || 30000, maxRetries: 1 });
-  const browser = await playwright.chromium.launch({ headless: true });
   try {
-    const capture = async (name, viewport, isMobile = false) => {
-      const context = await browser.newContext({ viewport, isMobile });
-      const page = await context.newPage();
-      const failures = [];
-      page.on('requestfailed', (request) => failures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
-      const response = await page.goto(options.target, { waitUntil: 'networkidle', timeout: options.timeout || 30000 });
-      const html = await page.content(), text = await page.locator('body').innerText(), screenshot = await page.screenshot({ fullPage: true });
-      const result = { name, final_url: page.url(), status: response?.status() ?? null, viewport, html, text, screenshot, failed_requests: failures };
-      await context.close();
-      return result;
-    };
-    const desktop = await capture('desktop', { width: 1280, height: 900 });
-    const mobile = await capture('mobile', { width: 390, height: 844 }, true);
+    if (!capture) {
+      capture = async (name, viewport, { isMobile = false, javaScriptEnabled = true } = {}) => {
+      const context = await browser.newContext({ viewport, isMobile, javaScriptEnabled });
+      try {
+        const page = await context.newPage();
+        const failures = [];
+        page.on('requestfailed', (request) => failures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
+        const response = await page.goto(options.target, { waitUntil: 'networkidle', timeout: options.timeout || 30000 });
+        const discovered = await page.locator('details > summary,[aria-expanded=false],[role=tab][aria-selected=false],button').evaluateAll((nodes) => nodes.map((node) => ({ tag: node.tagName.toLowerCase(), text: (node.textContent || '').trim().slice(0, 120), role: node.getAttribute('role'), expanded: node.getAttribute('aria-expanded') })).filter((item) => item.tag !== 'button' || /load more|show more|view more/i.test(item.text)));
+        const executed = [];
+        if (options.interactions) {
+          const controls = page.locator('details:not([open]) > summary,[aria-expanded=false],[role=tab][aria-selected=false],button');
+          for (let i = 0; i < Math.min(await controls.count(), 20); i++) { const control = controls.nth(i); const label = ((await control.textContent()) || '').trim(); if ((await control.evaluate((node) => node.tagName.toLowerCase())) === 'button' && !/load more|show more|view more/i.test(label)) continue; try { await control.click({ timeout: 2000 }); executed.push(label.slice(0, 120) || `control-${i + 1}`); } catch { executed.push(`failed:${label.slice(0, 100) || i + 1}`); } }
+        }
+        const html = await page.content(), text = await page.locator('body').innerText(), screenshot = await page.screenshot({ fullPage: true });
+        return { name, final_url: page.url(), status: response?.status() ?? null, viewport, javaScriptEnabled, html, text, screenshot, failed_requests: failures, interactions: { discovered, executed } };
+      } finally {
+        await context.close();
+      }
+      };
+    }
+    const initial = await (options.fetchUrl || fetchUrl)(options.target, { timeoutMs: options.timeout || 30000, maxRetries: 1 });
     const initialText = initial.body.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ').replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
-    const data = {
-      url: options.target, initial: { final_url: initial.url, status: initial.status, html_hash: sha256(initial.body), text_hash: sha256(initialText), word_count: words(initialText).length, redirect_chain: initial.redirectChain },
-      desktop: { final_url: desktop.final_url, status: desktop.status, html_hash: sha256(desktop.html), text_hash: sha256(desktop.text), word_count: words(desktop.text).length, failed_requests: desktop.failed_requests },
-      mobile: { final_url: mobile.final_url, status: mobile.status, html_hash: sha256(mobile.html), text_hash: sha256(mobile.text), word_count: words(mobile.text).length, failed_requests: mobile.failed_requests },
-      parity: { initial_to_desktop_word_ratio: words(desktop.text).length ? Number((words(initialText).length / words(desktop.text).length).toFixed(3)) : null, mobile_to_desktop_word_ratio: words(desktop.text).length ? Number((words(mobile.text).length / words(desktop.text).length).toFixed(3)) : null },
-    };
-    const item = envelope('render', data, { method: 'browser', source: 'playwright/chromium', raw: `${initial.body}\n${desktop.html}\n${mobile.html}` });
-    return observationRun(root, 'observe render', options.target, [item], { artifacts: { 'initial/response.html': initial.body, 'rendered/desktop-dom.html': desktop.html, 'rendered/desktop-text.txt': desktop.text, 'rendered/mobile-dom.html': mobile.html, 'rendered/mobile-text.txt': mobile.text, 'screenshots/desktop.png': desktop.screenshot, 'screenshots/mobile.png': mobile.screenshot } });
-  } finally { await browser.close(); }
+    const observations = [...reused], artifacts = { 'initial/response.html': initial.body }, incomplete = [];
+    const profiles = [{ name: 'desktop', viewport: { width: 1280, height: 900 } }, { name: 'mobile', viewport: { width: 390, height: 844 }, settings: { isMobile: true } }, { name: 'javascript_disabled', viewport: { width: 1280, height: 900 }, settings: { javaScriptEnabled: false } }];
+    for (const profile of profiles.filter((item) => !reused.some((old) => old.data.profile === item.name))) {
+      try { const result = await capture(profile.name, profile.viewport, profile.settings); const count = words(result.text).length; const data = { url: options.target, profile: profile.name, final_url: result.final_url, status: result.status, viewport: result.viewport, javascript_enabled: result.javaScriptEnabled, interaction_execution_requested: Boolean(options.interactions), html_hash: sha256(result.html), text_hash: sha256(result.text), word_count: count, raw_http_word_ratio: count ? Number((words(initialText).length / count).toFixed(3)) : null, failed_requests: result.failed_requests, interactions: result.interactions }; observations.push(envelope('render', data, { method: 'browser', source: 'playwright/chromium', raw: result.html, limitations: result.interactions.executed.length ? ['Interactions were bounded to disclosure, tab, and load-more-like controls; application-specific journeys remain untested.'] : [] })); artifacts[`rendered/${profile.name}-dom.html`] = result.html; artifacts[`rendered/${profile.name}-text.txt`] = result.text; artifacts[`screenshots/${profile.name}.png`] = result.screenshot; }
+      catch (error) { incomplete.push(`${profile.name} render failed: ${error.message}`); observations.push(envelope('render', { url: options.target, profile: profile.name }, { method: 'browser', source: 'playwright/chromium', state: 'failed', confidence: 'confirmed', raw: `${profile.name}:${error.message}`, limitations: [error.message] })); }
+    }
+    const desktop = observations.find((item) => item.data.profile === 'desktop' && item.state === 'observed'), mobile = observations.find((item) => item.data.profile === 'mobile' && item.state === 'observed');
+    observations.push(envelope('render', { url: options.target, profile: 'parity', raw_http_to_desktop_word_ratio: desktop?.data.raw_http_word_ratio ?? null, mobile_to_desktop_word_ratio: desktop?.data.word_count && mobile?.data.word_count ? Number((mobile.data.word_count / desktop.data.word_count).toFixed(3)) : null, resumed_from_run_id: options.resumeRun || null }, { method: 'static_analysis', source: options.target, state: desktop && mobile ? 'observed' : 'incomplete', confidence: 'high', limitations: desktop && mobile ? [] : ['Desktop/mobile parity is incomplete because one or more profiles failed.'] }));
+    return observationRun(root, 'observe render', options.target, observations, { rawInputs: previousRaw ? { resumed_manifest: previousRaw } : {}, incomplete, warnings: reused.length ? [`${reused.length} successful profile(s) reused from immutable run ${options.resumeRun}; failed, absent, or configuration-mismatched profiles were recollected.`] : options.resumeRun ? [`No compatible successful profiles were reusable from immutable run ${options.resumeRun}; all profiles were recollected.`] : [], artifacts });
+  } finally { if (browser) await browser.close(); }
 }
 
 async function observeIndex(root, options) {
@@ -247,7 +270,75 @@ async function observeConsensus(root, options) {
   return observationRun(root, 'observe consensus', options.target, observations);
 }
 
+const median = (values) => {
+  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+};
+
+function lighthouseMetrics(lhr) {
+  const audits = lhr.audits || {};
+  const value = (id) => Number.isFinite(audits[id]?.numericValue) ? audits[id].numericValue : null;
+  return {
+    performance_score: Number.isFinite(lhr.categories?.performance?.score) ? lhr.categories.performance.score : null,
+    first_contentful_paint_ms: value('first-contentful-paint'),
+    largest_contentful_paint_ms: value('largest-contentful-paint'),
+    cumulative_layout_shift: value('cumulative-layout-shift'),
+    total_blocking_time_ms: value('total-blocking-time'),
+    speed_index_ms: value('speed-index'),
+  };
+}
+
+async function localLighthouseRunner(target, runIndex, options) {
+  let lighthouse, launcher;
+  try {
+    ({ default: lighthouse } = await import('lighthouse'));
+    launcher = await import('chrome-launcher');
+  } catch {
+    throw new Error('optional lighthouse and chrome-launcher dependencies are not installed');
+  }
+  const chrome = await launcher.launch({ chromeFlags: ['--headless', '--no-sandbox', '--disable-gpu'] });
+  try {
+    const result = await lighthouse(target, { port: chrome.port, output: 'json', logLevel: 'error', formFactor: options.deviceProfile || 'mobile' });
+    return result.lhr;
+  } finally {
+    await chrome.kill();
+  }
+}
+
+async function observeLighthouse(root, options) {
+  if (!/^https?:\/\//.test(options.target || '')) throw new Error('Lighthouse requires --target <http(s) URL>');
+  const repeat = Number.isInteger(options.repeat) && options.repeat >= 1 && options.repeat <= 5 ? options.repeat : 3;
+  const runner = options.lighthouseRunner || localLighthouseRunner;
+  const observations = [], artifacts = {}, incomplete = [];
+  for (let runIndex = 1; runIndex <= repeat; runIndex++) {
+    try {
+      const lhr = await runner(options.target, runIndex, options);
+      const metrics = lighthouseMetrics(lhr);
+      const data = {
+        url: options.target, provider: 'Lighthouse', evidence_type: 'lab', run_index: runIndex, runs_in_series: repeat,
+        lighthouse_version: lhr.lighthouseVersion || null, chrome_user_agent: lhr.userAgent || null, fetched_at: lhr.fetchTime || null,
+        final_url: lhr.finalDisplayedUrl || lhr.finalUrl || options.target,
+        configuration: { form_factor: lhr.configSettings?.formFactor || null, throttling_method: lhr.configSettings?.throttlingMethod || null, screen_emulation: lhr.configSettings?.screenEmulation || null, throttling: lhr.configSettings?.throttling || null },
+        metrics,
+      };
+      observations.push(envelope('performance', data, { method: 'browser', source: 'lighthouse/local', raw: JSON.stringify(lhr), limitations: ['This is controlled lab evidence, not field performance or a guarantee of user experience.'] }));
+      artifacts[`lighthouse/run-${String(runIndex).padStart(2, '0')}.json`] = JSON.stringify(lhr, null, 2);
+    } catch (error) {
+      incomplete.push(`Lighthouse run ${runIndex} failed: ${error.message}`);
+      observations.push(envelope('performance', { url: options.target, provider: 'Lighthouse', evidence_type: 'lab', run_index: runIndex, runs_in_series: repeat }, { method: 'browser', source: 'lighthouse/local', state: 'failed', confidence: 'confirmed', raw: `run-${runIndex}:${error.message}`, limitations: [error.message] }));
+    }
+  }
+  const successful = observations.filter((item) => item.state === 'observed');
+  const metricNames = ['performance_score', 'first_contentful_paint_ms', 'largest_contentful_paint_ms', 'cumulative_layout_shift', 'total_blocking_time_ms', 'speed_index_ms'];
+  const medians = Object.fromEntries(metricNames.map((name) => [name, median(successful.map((item) => item.data.metrics[name]))]));
+  observations.push(envelope('performance', { url: options.target, provider: 'Lighthouse', evidence_type: 'lab_summary', requested_runs: repeat, successful_runs: successful.length, median_metrics: medians }, { method: 'static_analysis', source: 'lighthouse/local', state: successful.length ? 'observed' : 'not_evidenced', confidence: successful.length === repeat ? 'high' : 'low', limitations: ['Medians summarize only successful controlled lab runs; failed runs remain separate evidence.'] }));
+  return observationRun(root, 'observe performance --lighthouse', options.target, observations, { incomplete, artifacts });
+}
+
 async function observePerformance(root, options) {
+  if (options.lighthouse) return observeLighthouse(root, options);
   if (options.input) {
     const input = readInput(options.input);
     const rows = Array.isArray(input.value) ? input.value : [input.value];
@@ -289,6 +380,7 @@ export async function observe(root, mode, options = {}) {
     case 'consensus': return observeConsensus(root, options);
     case 'performance': return observePerformance(root, options);
     case 'corroboration': return observeCorroboration(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, or corroboration');
+    case 'media': return observeMedia(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, or media');
   }
 }

package/src/observations/media.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'node-html-parser';
+import { envelope, observationRun, readInput } from './common.js';
+import { loadRegistries } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function resolveMediaPath(manifestFile, value) {
+  const file = path.resolve(path.dirname(manifestFile), value);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`media file not found: ${value}`);
+  return file;
+}
+
+async function pdfEvidence(item, file, artifacts) {
+  const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+  const bytes = new Uint8Array(fs.readFileSync(file));
+  const document = await pdfjs.getDocument({ data: bytes, disableWorker: true, useSystemFonts: true }).promise;
+  const metadata = await document.getMetadata().catch(() => ({ info: {}, metadata: null }));
+  const pages = [];
+  for (let number = 1; number <= document.numPages; number++) {
+    const page = await document.getPage(number);
+    const content = await page.getTextContent();
+    const text = content.items.map((entry) => entry.str).join(' ').replace(/\s+/g, ' ').trim();
+    pages.push({ page: number, text, word_count: text ? text.split(/\s+/).length : 0, anchor: `${item.source_url || file}#page=${number}` });
+  }
+  artifacts[`media/${item.media_id}/extracted.txt`] = pages.map((page) => `--- page ${page.page} ---\n${page.text}`).join('\n');
+  return envelope('media_pdf', { 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, page_count: document.numPages, pages, metadata: metadata.info || {}, tagged: Boolean(metadata.info?.IsTagged) }, { method: 'static_analysis', source: file, raw: bytes, confidence: 'high', limitations: ['Reading order, tables, footnotes, signatures, revisions, accessibility tags, and scanned text are not fully validated.', 'Page text extraction does not establish that linked claims are supported.'] });
+}
+
+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 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.'] });
+}
+
+async function imageEvidence(item, file, options) {
+  const html = fs.readFileSync(file, 'utf8');
+  const root = parse(html);
+  const images = root.querySelectorAll('img');
+  const image = item.image_src ? images.find((node) => node.getAttribute('src') === item.image_src) : images[0];
+  if (!image) return envelope('media_image', { media_id: item.media_id, image_src: item.image_src || null, page_url: item.page_url, claim_ids: item.claim_ids }, { method: 'static_analysis', source: file, raw: html, state: 'not_observed', limitations: ['No matching image was found in the supplied HTML.'] });
+  const figure = image.closest('figure');
+  const caption = figure?.querySelector('figcaption')?.text.replace(/\s+/g, ' ').trim() || null;
+  const alt = image.getAttribute('alt');
+  const nearby_text = (figure || image.parentNode)?.text?.replace(/\s+/g, ' ').trim() || null;
+  let ocr = { state: 'not_requested', text: null };
+  if (options.ocr) {
+    try { const tesseract = await import('tesseract.js'); const result = await tesseract.recognize(path.resolve(path.dirname(file), image.getAttribute('src')), item.language || 'eng'); ocr = { state: 'observed', text: result.data.text }; }
+    catch { ocr = { state: 'not_evidenced', text: null }; }
+  }
+  return envelope('media_image', { media_id: item.media_id, image_src: image.getAttribute('src'), source_url: item.source_url, page_url: item.page_url, claim_ids: item.claim_ids, permission_status: item.permission_status, alt: alt ?? null, caption, nearby_text, ocr }, { method: 'static_analysis', source: file, raw: html, state: options.ocr && ocr.state === 'not_evidenced' ? 'incomplete' : 'observed', confidence: 'high', limitations: [...(!alt && !caption ? ['Neither alt text nor a figure caption supplies textual context.'] : []), ...(ocr.state === 'not_evidenced' ? ['OCR was explicitly requested but the optional tesseract.js dependency or image resource was unavailable.'] : []), 'Alt text, captions, nearby text, and OCR do not establish semantic equivalence or claim support.'] });
+}
+
+export async function observeMedia(root, options) {
+  const input = readInput(options.input);
+  const check = validateAgainst('media-manifest.schema.json', input.value);
+  if (!check.valid) throw new Error(`media manifest violates contract: ${check.errors.join('; ')}`);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const claimIds = new Set(registries.claims.entries.map((claim) => claim.claim_id));
+  const observations = [], artifacts = {}, rawInputs = { media_manifest: input.raw };
+  for (const item of input.value.items) {
+    const unknown = item.claim_ids.filter((id) => !claimIds.has(id));
+    if (unknown.length) throw new Error(`${item.media_id} references unknown claim ids: ${unknown.join(', ')}`);
+    const file = resolveMediaPath(input.file, item.path);
+    rawInputs[`media_${item.media_id}`] = fs.readFileSync(file);
+    if (item.type === 'pdf') observations.push(await pdfEvidence(item, file, artifacts));
+    else if (item.type === 'transcript') observations.push(transcriptEvidence(item, file, artifacts));
+    else observations.push(await imageEvidence(item, file, options));
+  }
+  const incomplete = observations.filter((item) => item.state === 'incomplete').map((item) => `${item.data.media_id}: requested extraction is incomplete`);
+  return observationRun(root, 'observe media', input.file, observations, { rawInputs, artifacts, incomplete });
+}