rewritable 0.15.0 → 0.16.0

package/README.md

@@ -79,6 +79,8 @@ Embeds the input file's content as the document's initial state. Supported forma
 
 Output defaults to `<input-basename>.html` in the input's directory. Conversion is deterministic and offline — no API key, no network.
 
+**Import fidelity loop (PDF).** After a PDF import, `rwa` runs an offline **structural fidelity check** (text-coverage + extraction-quality). If it's low *and* a model is reachable (`RWA_OPENROUTER_KEY` set), it **auto-escalates** to `--vision` and keeps the higher-fidelity result — announced on stderr. **Offline-first is preserved:** with no key, a low-fidelity import stays offline, succeeds, and just warns (suggesting `--vision`/`--claude`). Controls: `--no-escalate` (disable the loop), `--target-fidelity <0..1>` (set the bar, default 0.85). *(The deterministic geometry import is unchanged; the loop only measures and, when authorized, escalates. The full picture-level visual judge is a browser-side follow-up.)*
+
 ### `rwa clone <url> [path]`
 
 Clone a public webpage into a self-contained rewritable: fetch the page, extract its main article and title, and bake the content into a fresh container. First-class for **WordPress / ikangai posts** — a blog post becomes an editable, shareable single-file `.html` you can rewrite with `⌘K`.

package/bin/rwa.mjs

@@ -1217,6 +1217,16 @@ function detectProductKind(fileText) {
     const vision = rest.includes('--vision');
     const claude = rest.includes('--claude');
     const trustInput = rest.includes('--trust-input');
+    // Import fidelity loop (PDF): measure the deterministic import + auto-escalate to --vision when
+    // low AND a model is reachable. --no-escalate opts out; --target-fidelity <0..1> sets the bar.
+    const escalate = !rest.includes('--no-escalate');
+    const tfIdx = rest.indexOf('--target-fidelity');
+    const targetFidelity = tfIdx >= 0 ? Number(rest[tfIdx + 1]) : undefined;
+    if (tfIdx >= 0 && (!Number.isFinite(targetFidelity) || targetFidelity < 0 || targetFidelity > 1)) {
+      console.error('rwa import: --target-fidelity must be a number between 0 and 1');
+      process.exitCode = 2;
+      return;
+    }
     // --model and --timeout take a value: find the index, then take the next arg.
     const modelIdx = rest.indexOf('--model');
     const model = modelIdx >= 0 ? rest[modelIdx + 1] : undefined;
@@ -1249,7 +1259,7 @@ function detectProductKind(fileText) {
       process.exitCode = 2;
       return;
     }
-    const positional = rest.filter((a, i) => !a.startsWith('-') && rest[i - 1] !== '--model' && rest[i - 1] !== '--timeout' && rest[i - 1] !== '--kind' && rest[i - 1] !== '--skin');
+    const positional = rest.filter((a, i) => !a.startsWith('-') && rest[i - 1] !== '--model' && rest[i - 1] !== '--timeout' && rest[i - 1] !== '--kind' && rest[i - 1] !== '--skin' && rest[i - 1] !== '--target-fidelity');
     if (verb === 'new') {
       // `rwa new --kind <starter>` selects a built-in starter. Otherwise a bare-word
       // first positional is a TEMPLATE name (clone a data-rwa-template-labeled file
@@ -1268,7 +1278,7 @@ function detectProductKind(fileText) {
         process.exitCode = 2;
         return;
       }
-      await importCmd({ inputPath: positional[0], outPath: positional[1], force, open, vision, claude, trustInput, model, timeoutSec });
+      await importCmd({ inputPath: positional[0], outPath: positional[1], force, open, vision, claude, trustInput, model, timeoutSec, escalate, targetFidelity });
     } else {
       console.error(`rwa: unknown verb "${verb}". Try --help.`);
       process.exitCode = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rewritable",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "CLI for re-writeable: emit and import single-file rwa documents.",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -228,7 +228,7 @@ export async function newCmd({ outPath, force, open, kind, templateName, skin })
 
 export { KNOWN_KINDS };
 
-export async function importCmd({ inputPath, outPath, force, open, vision, claude, trustInput, model, timeoutSec }) {
+export async function importCmd({ inputPath, outPath, force, open, vision, claude, trustInput, model, timeoutSec, escalate, targetFidelity }) {
   if (vision && claude) {
     const e = new Error('--vision and --claude are mutually exclusive');
     e.exitCode = 2;
@@ -265,7 +265,31 @@ export async function importCmd({ inputPath, outPath, force, open, vision, claud
     // Buffer (not utf8 string) — docx and pdf are binary, and text formats
     // decode internally inside convert().
     const contents = await fs.readFile(input);
-    ({ html, warnings } = await convert(ext, contents));
+    const conv = await convert(ext, contents);
+    ({ html, warnings } = conv);
+    // Import fidelity loop (PDF) — measure the deterministic import; on a low structural score,
+    // auto-escalate to --vision, but ONLY when a model is reachable (offline-first: a keyless
+    // import stays offline and warns). `--no-escalate` opts out. Design: docs/plans/2026-06-30-…
+    if (ext === 'pdf' && conv.fidelityInput && escalate !== false) {
+      const { measureAndEscalate } = await import('./import-fidelity.mjs');
+      // Resolve the OpenRouter key ONCE so the reachability probe and the actual escalation target
+      // agree (both honor RWA_OPENROUTER_KEY, the project-preferred var, AND OPENROUTER_API_KEY).
+      // convertPdfViaVision otherwise only reads OPENROUTER_API_KEY, so a probe that said "reachable"
+      // on RWA_OPENROUTER_KEY alone would escalate into a guaranteed "key required" throw.
+      const orKey = process.env.RWA_OPENROUTER_KEY || process.env.OPENROUTER_API_KEY;
+      const r = await measureAndEscalate(
+        { structuralInput: conv.fidelityInput, importResult: conv },
+        {
+          threshold: targetFidelity,
+          escalate: escalate !== false,
+          modelReachable: () => !!orKey,
+          visionImport: async () => { console.error('note: import fidelity low — escalating to --vision (openrouter)…'); return convertPdfViaVision(contents, { model, apiKey: orKey }); },
+        },
+      );
+      if (r.note) console.error('note: ' + r.note);
+      html = r.result.html;
+      warnings = r.result.warnings || warnings;
+    }
   }
   for (const w of warnings) console.error(`note: ${w}`);
 

package/src/import-fidelity.mjs

@@ -0,0 +1,131 @@
+// Import fidelity loop — increment 1 (docs/plans/2026-06-30-import-fidelity-loop-design.md).
+// An OFFLINE structural check on a PDF import + auto-escalate UP the ladder (default → --vision)
+// when fidelity is low — gated on offline-first: escalation fires only when a model is reachable;
+// a keyless low-fidelity import stays offline and warns, never touching the network.
+//
+// Increment 1 measures two false-positive-free signals:
+//   - coverage: fraction of source word-tokens present in the imported text (transform fidelity —
+//               catches dropped/mangled content; ~1 for a faithful geometry import).
+//   - garble:   1 − share of replacement (U+FFFD) / control chars in the source (extraction
+//               quality — a PDF with broken font encoding extracts to garbage; the geometry import
+//               is then unfaithful and should escalate to --vision, which reads the rendered glyphs).
+// The graphics/visual signal ("this page is a chart/scan the text import can't reproduce") needs a
+// renderer; it is the browser-side VISUAL JUDGE, a later increment. `density` is returned for
+// callers/future use but deliberately NOT scored here (char-count alone false-positives on short
+// docs) and is not yet surfaced in CLI output.
+//
+// Sensitivity, stated honestly: this is a FLOOR, biased to never over-escalate a good import.
+// coverage uses substring `includes`, so reordered/duplicated text scores ~1.0; garble only counts
+// U+FFFD + control chars, so wrong-encoding glyphs that aren't U+FFFD score ~1.0. The offline
+// trigger therefore reliably fires only on DROPPED text or replacement-char garble — visual/glyph
+// faithfulness is the VLM judge's job, not this metric's.
+
+const DEFAULT_THRESHOLD = 0.85;
+const MIN_CHARS_PER_PAGE = 200; // informational density floor only (not part of the score in inc. 1)
+
+const norm = (s) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().toLowerCase();
+const stripTags = (h) => String(h == null ? '' : h).replace(/<[^>]*>/g, ' ');
+
+// Count replacement (U+FFFD) + control chars (excluding tab/LF/CR) without embedding literal
+// control bytes in source — a char-code scan, so the file stays clean ASCII.
+function badChars(src) {
+  let bad = 0;
+  for (let i = 0; i < src.length; i++) {
+    const c = src.charCodeAt(i);
+    if (c === 0xFFFD || (c < 0x20 && c !== 9 && c !== 10 && c !== 13)) bad++;
+  }
+  return bad;
+}
+
+/** Pure offline structural score in [0,1] = min(coverage, garble). Returns the components + reasons. */
+export function structuralScore({ sourceText, pages } = {}, importedHtml) {
+  const src = String(sourceText == null ? '' : sourceText);
+  const importText = norm(stripTags(importedHtml));
+
+  // coverage — unique source word-tokens (len>1) present in the imported text
+  const tokens = [...new Set(norm(src).split(' ').filter(t => t.length > 1))];
+  let coverage = 1;
+  if (tokens.length) {
+    let hit = 0;
+    for (const t of tokens) if (importText.includes(t)) hit++;
+    coverage = hit / tokens.length;
+  }
+
+  // garble — replacement + control char share of the source
+  const garble = src.length ? Math.max(0, 1 - badChars(src) / src.length) : 1;
+
+  // density — reported only (graphics-heaviness detection is the deferred visual judge)
+  const pageN = Math.max(1, pages | 0);
+  const density = Math.min(1, src.replace(/\s+/g, '').length / (pageN * MIN_CHARS_PER_PAGE));
+
+  const score = Math.min(coverage, garble);
+  const reasons = [];
+  if (coverage < 0.9) reasons.push('low-coverage');
+  if (garble < 0.9) reasons.push('garbled-text');
+  return { score, coverage, garble, density, reasons };
+}
+
+/**
+ * Per-page structural fidelity for a multipage import. `perPage`: [{ sourceText, html }], where
+ * imported page i aligns 1:1 with source page i (the geometry import preserves page order). Returns
+ * { pages:[{page, score, coverage, garble, reasons}], overall (mean), worst (the lowest page) }.
+ * The per-page strip is what the browser visual judge surfaces so you jump to the bad pages.
+ */
+export function structuralScoreByPage(perPage = []) {
+  const pages = perPage.map((p, i) => ({ page: i + 1, ...structuralScore({ sourceText: p.sourceText, pages: 1 }, p.html) }));
+  const overall = pages.length ? pages.reduce((a, p) => a + p.score, 0) / pages.length : 1;
+  const worst = pages.length ? pages.reduce((w, p) => (p.score < w.score ? p : w)) : null;
+  return { pages, overall, worst };
+}
+
+// The escalate-trigger fidelity: the WORST page when per-page data is present (so one bad page in an
+// otherwise-good doc still escalates — averaging would hide it), else the whole-doc score.
+function measureStructural(structuralInput, importHtml) {
+  if (structuralInput && Array.isArray(structuralInput.perPage) && structuralInput.perPage.length) {
+    const bp = structuralScoreByPage(structuralInput.perPage);
+    return { score: bp.worst.score, coverage: bp.worst.coverage, garble: bp.worst.garble, reasons: bp.worst.reasons, overall: bp.overall, worst: bp.worst, pages: bp.pages };
+  }
+  return structuralScore(structuralInput, importHtml);
+}
+
+/**
+ * Measure the geometry import; if its score is below `threshold` AND escalation is enabled AND a
+ * model is reachable, re-import via the injected `visionImport` and keep the higher-rung result.
+ * Offline-first: with no reachable model, never call the network — keep the deterministic import and
+ * surface a warning `note`. A failed escalation falls back to the deterministic import (loud).
+ *
+ * deps: { threshold=0.85, escalate=true, modelReachable():boolean, visionImport():Promise<importResult> }
+ */
+export async function measureAndEscalate({ structuralInput, importResult }, deps = {}) {
+  const threshold = deps.threshold == null ? DEFAULT_THRESHOLD : deps.threshold;
+  const escalate = deps.escalate !== false; // default on
+  const fidelity = measureStructural(structuralInput, importResult.html);
+
+  if (fidelity.score >= threshold || !escalate) {
+    return { result: importResult, fidelity, escalated: false };
+  }
+
+  const reachable = typeof deps.modelReachable === 'function' ? deps.modelReachable() : false;
+  if (!reachable) {
+    return {
+      result: importResult, fidelity, escalated: false,
+      note: 'low import fidelity (' + fidelity.score.toFixed(2) + (fidelity.reasons.length ? ': ' + fidelity.reasons.join(', ') : '') +
+        ') — set RWA_OPENROUTER_KEY or use --vision/--claude for a higher-fidelity import',
+    };
+  }
+
+  try {
+    const vResult = await deps.visionImport();
+    // Escalation succeeded: keep the higher rung. We do NOT re-score with the same text-only metric
+    // — its blind spot (graphics/garbled glyphs) is exactly why we escalated; the model addresses it.
+    return {
+      result: vResult, escalated: true, baselineFidelity: fidelity,
+      note: 'import fidelity ' + fidelity.score.toFixed(2) + ' — escalated to --vision',
+    };
+  } catch (e) {
+    return {
+      result: importResult, fidelity, escalated: false,
+      note: 'low import fidelity (' + fidelity.score.toFixed(2) + ') — escalation to --vision failed: ' + ((e && e.message) || e),
+    };
+  }
+}

package/src/import.mjs

@@ -264,13 +264,18 @@ async function convertPdf(bytes) {
     throw e;
   }
   const pages = [];
+  const perPage = [];
   let totalText = 0;
+  let sourceText = '';
   for (let p = 1; p <= doc.numPages; p++) {
     const page = await doc.getPage(p);
     const rendered = await renderPdfPage(page, pdfjs.Util, pdfjs.OPS);
     pages.push(rendered.html);
     totalText += rendered.textCount;
+    sourceText += (rendered.text || '') + '\n';
+    perPage.push({ sourceText: rendered.text || '', html: rendered.html }); // for per-page fidelity
   }
+  const pageCount = doc.numPages;
   await doc.destroy().catch(() => {});
 
   if (totalText === 0) {
@@ -281,6 +286,7 @@ async function convertPdf(bytes) {
   return {
     html: `<article class="rwa-pdf">\n${PDF_PAGE_STYLE}\n<div class="rwa-pdf-doc">\n${pages.join('\n')}\n</div>\n</article>`,
     warnings: ['pdf: imported as a geometry-faithful reconstruction (positioned text + rules) — text stays editable but is absolutely positioned'],
+    fidelityInput: { sourceText, pages: pageCount, perPage }, // for the import fidelity loop (import-fidelity.mjs); perPage drives per-page/worst-page scoring
   };
 }
 
@@ -489,5 +495,7 @@ async function renderPdfPage(page, Util, OPS) {
   }
 
   const html = `<div class="rwa-pdf-page" style="width:${pdfNum(vp.width)}px;height:${pdfNum(vp.height)}px">\n${parts.join('\n')}\n</div>`;
-  return { html, textCount };
+  // text: the raw pdf.js-extracted source text (for the import fidelity check — coverage + garble).
+  const text = tc.items.map(i => i.str || '').join(' ');
+  return { html, textCount, text };
 }