rewritable 0.3.0 → 0.6.0

package/src/host.mjs

@@ -0,0 +1,126 @@
+// `rwa host <file>` — ingest a local rewritable into a hosted runtime's `POST /r`
+// (service/server.js handleHostedCreate) and print the `{id, token, url}` the
+// server mints. The url carries the capability token in its `#k=` fragment — the
+// only way the user keeps editing the hosted copy — so it is printed verbatim.
+//
+// This is the network-bearing INGEST client (the round-trip-edit foundation),
+// the way `rwa publish` is the ephemeral-share client. Online by design (the
+// offline-first invariant of new/import does not apply to a host action), so —
+// like `clone`/`publish-site` — it is excluded from the offline-first rule.
+//
+// Design parity:
+//   - flags-over-env config (--url > $RWA_HOST_URL), nothing baked in — like
+//     publish-site's RWA_SITE_*.
+//   - injected transport ({transport, env}) so tests run offline — the same
+//     deps-seam shape publish-site uses for {execFile, env}. The default
+//     transport is a real node:http/node:https POST.
+//   - CliError exit codes: 2 file_error (not_found/read_error/not_a_rewritable),
+//     1 config_error (no url), 4 host_error (transport/HTTP failure, carrying the
+//     server's status/body verbatim). The bin labels exit 4 `host_error`.
+//
+// Security: only the file bytes are sent — a rewritable carries NO secret (the
+// API key is sessionStorage-only, never in the file). The returned token is
+// surfaced to stdout (the bin) and nowhere else.
+
+import { readFile } from 'node:fs/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { extractInlineDoc } from './seed.mjs';
+import { CliError } from './edit.mjs';
+
+// Default transport: a single POST over node:http / node:https. Returns the raw
+// status + body text; hostFile owns all status/JSON interpretation so the seam
+// stays dumb and the contract lives in one place. Network failures reject — the
+// caller maps them to host_error/network_error.
+//
+// @param {string} url — the full POST target (already includes the /r path)
+// @param {{method:string, headers:object, body:string}} opts
+// @returns {Promise<{status:number, body:string}>}
+function defaultTransport(url, { method, headers, body }) {
+  const u = new URL(url);
+  const request = u.protocol === 'https:' ? httpsRequest : httpRequest;
+  return new Promise((resolve, reject) => {
+    const req = request(u, { method, headers }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+    });
+    req.on('error', reject);
+    if (body != null) req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Read, locally validate, and POST a rewritable's bytes to `<baseUrl>/r`.
+ *
+ * @param {string} filePath
+ * @param {{url?:string, transport?:Function, env?:object}} [deps]
+ *   url      — base url override (flag); falls back to env.RWA_HOST_URL
+ *   transport— injection seam ((url, opts) => {status, body}); defaults to a
+ *              real node:http/https POST
+ *   env      — env source (tests inject); defaults to process.env
+ * @returns {Promise<{id:string, token:string, url:string}>} the server's 200 object
+ * @throws {CliError} 2 file_error · 1 config_error · 4 host_error
+ */
+export async function hostFile(filePath, deps = {}) {
+  const env = deps.env || process.env;
+  const transport = deps.transport || defaultTransport;
+
+  // 1. Read — identical CliError file_error surface to publish.mjs / publish-site.mjs.
+  let bytes;
+  try {
+    bytes = await readFile(filePath, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: filePath });
+    throw new CliError(2, 'read_error', { path: filePath, errno: e && e.code, message: e && e.message });
+  }
+
+  // 2. Local fail-fast: is this even a rewritable? Same gate as `rwa publish`.
+  // The server re-validates authoritatively (it returns 400 not_a_rewritable);
+  // this just avoids a wasted round trip and gives an offline-detectable error.
+  try {
+    extractInlineDoc(bytes);
+  } catch {
+    throw new CliError(2, 'not_a_rewritable', { path: filePath });
+  }
+
+  // 3. Config: flag url > $RWA_HOST_URL; nothing is baked into the package.
+  const urlBase = deps.url || env.RWA_HOST_URL;
+  if (!urlBase) throw new CliError(1, 'config_error', { missing: ['RWA_HOST_URL'] });
+
+  // 4. POST the raw bytes to <base>/r. text/html is the honest label for the
+  // payload (the server reads the body raw; service/server.js ignores
+  // content-type but is honest about what we send).
+  const endpoint = `${urlBase.replace(/\/+$/, '')}/r`;
+  let res;
+  try {
+    res = await transport(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'text/html; charset=utf-8' },
+      body: bytes,
+    });
+  } catch (e) {
+    throw new CliError(4, 'network_error', { url: endpoint, message: (e && e.message) || String(e) });
+  }
+
+  // Body may be empty or non-JSON on some error paths — parse defensively.
+  let payload = null;
+  if (res.body) { try { payload = JSON.parse(res.body); } catch { payload = null; } }
+
+  if (res.status === 200) {
+    if (!payload || typeof payload.id !== 'string' || typeof payload.token !== 'string' || typeof payload.url !== 'string') {
+      throw new CliError(4, 'malformed_success_response', { status: 200 });
+    }
+    return { id: payload.id, token: payload.token, url: payload.url };
+  }
+
+  // Map the server's error envelope to an honest subcode. Prefer the server's
+  // own `error` name when present; carry the status + maxBytes verbatim so the
+  // user sees WHY ingest failed.
+  const errName = payload && typeof payload.error === 'string' ? payload.error : null;
+  if (res.status === 413 || errName === 'body_too_large') {
+    throw new CliError(4, 'body_too_large', { maxBytes: payload && payload.maxBytes });
+  }
+  throw new CliError(4, 'server_error', { status: res.status, error: errName });
+}

package/src/identity.mjs

@@ -0,0 +1,257 @@
+// Consumer-side static self-description for `self-description/1` — the answer to
+// "what is this rewritable, and what can be done with it?" computed from the
+// file BYTES, without executing the container's JS.
+// Contract + reference: docs/specs/rwa-self-description-spec.md,
+// tools/self-description.mjs (computeSelfDescription / validateSelfDescription).
+//
+// This is a PUBLISH-SAFE MIRROR of the reference's static computer. The CLI is a
+// standalone npm package and cannot reach repo-root tools/ at runtime, so the
+// kind→provider table, the substrate baseline, the title/blocks extraction, and
+// the assembled object are duplicated here — the same pattern as
+// cli/src/apply-edits.mjs mirroring the seed. The mirror is pinned to the single
+// source by tests/identity.test.mjs (KIND_PROVIDERS / SUBSTRATE_BASELINE deep-equal
+// the reference; the full assembled object deep-equals computeSelfDescription in
+// doc.test.mjs). Drift fails loudly. KEEP IN STEP with tools/self-description.mjs.
+
+import { tagHasFrozenAttr } from './apply-edits.mjs';
+import { parseSkillZone } from './skill-manifest.mjs';
+
+export const SCHEMA_TAG = 'self-description/1';
+// Mirror of tools/self-description.mjs AFFORDANCE_KINDS / PROVENANCES — used by the
+// declared-projection conformance gate (declaredIsConforming). Keep in step.
+export const AFFORDANCE_KINDS = ['view', 'edit-surface', 'tool', 'compute', 'hook'];
+export const PROVENANCES = ['first-party', 'installed'];
+
+// kind -> registered provider bundle (spec §4). Each provider is {kind,name,label};
+// `provenance:'first-party'` is added per emit (bootstrap-resident providers).
+// The presentation entry mirrors the seed presentationProvider {name:'presentation',
+// label:'Present'} (seeds/rewritable.html:3542-3543) so static == live by construction.
+// ONLY kinds the runtime FIRST-PARTY-provides — custom kinds (datatable, …) are
+// consumer-built via provide()/the declaration, so their honest static answer is
+// [] (declared > static supplies the real affordances when a declaration exists).
+export const KIND_PROVIDERS = {
+  document: [],
+  presentation: [{ kind: 'view', name: 'presentation', label: 'Present' }],
+  workflow: [],
+  // skill-host: no first-party affordances; installed skills (provenance:'installed')
+  // come from parseSkillZone (§8), not this table. Explicit [] mirrors the oracle.
+  'skill-host': [],
+};
+
+// Substrate-universal ops — the SAME for every container regardless of kind. The
+// "what can be done with me" data that is NOT an affordance (affordances stay
+// kernel-pure: a base document is []). `history` is undo-only — there is no redo
+// (re-write-able-spec Invariant 7).
+export const SUBSTRATE_BASELINE = Object.freeze({
+  edit: ['lens'],
+  tools: ['apply_dsl_plan', 'apply_edits', 'replace_document'],
+  export: ['html', 'print'],
+  history: ['undo'],
+});
+
+/**
+ * The document's human-readable title: the text of its first <h1>, or null.
+ * Mirrors tools/self-description.mjs `staticTitle` exactly (so titles agree).
+ * @param {string} doc — the LF-canonical editable body
+ * @returns {string|null}
+ */
+export function extractTitle(doc) {
+  const m = (doc || '').match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
+  if (!m) return null;
+  const text = m[1].replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+  return text || null;
+}
+
+/**
+ * Count of data-rwa-id-addressable blocks — a coarse "how structured" signal.
+ * @param {string} doc — the LF-canonical editable body
+ * @returns {number}
+ */
+export function countBlocks(doc) {
+  return ((doc || '').match(/\bdata-rwa-id\b/g) || []).length;
+}
+
+/**
+ * Assemble the STATIC self-description projection from a container's already-
+ * extracted facts (so inspectDoc parses the file once). Equivalent to the
+ * reference `computeSelfDescription(fileText)`, minus the file parsing.
+ *
+ * @param {{doc:string, uuid:string|null, kind:string, frozenZones:string[]}} facts
+ * @returns {object} a `source:'static'` self-description/1 object (spec §2)
+ */
+export function buildSelfDescription({ doc, uuid, kind, frozenZones }) {
+  // First-party (kind-derived) + INSTALLED skills from the frozen #rwa-skills zone
+  // (§8). Mirrors tools/self-description.mjs computeSelfDescription exactly.
+  const affordances = [
+    ...(KIND_PROVIDERS[kind] || []).map((p) => ({ ...p, provenance: 'first-party' })),
+    ...parseSkillZone(doc),
+  ];
+  return {
+    rwa: SCHEMA_TAG,
+    source: 'static',
+    uuid,
+    kind,
+    title: extractTitle(doc),
+    blocks: countBlocks(doc),
+    affordances,
+    frozenZones,
+    baseline: { ...SUBSTRATE_BASELINE },
+  };
+}
+
+// ── The `declared` projection (v1.1, spec §3.1) ───────────────────────────────
+// A custom-affordance file (a datatable the kind table can only GUESS for) may
+// carry its own answer: an inert `<script id="rwa-affordances">` block with a
+// `source:"declared"` self-description. The reader prefers it (declared > static)
+// only if it is TRUSTWORTHY — edit-unreachable so the lens/agent can't have
+// drifted it. Mirror of tools/self-description.mjs DECL_RE / parseDeclaration /
+// declarationFacts (publish-safe; the CLI can't reach repo-root tools/ at runtime).
+// The oracle takes only fileText and extractInlineDoc's it; the CLI passes the
+// already-extracted `doc` (== extractInlineDoc(fileText)) so the two agree.
+// KEEP IN STEP with tools/self-description.mjs.
+const DECL_RE = /<script\b[^>]*\bid=["']rwa-affordances["'][^>]*>([\s\S]*?)<\/script\s*>/i;
+
+// A body declaration lives inside INLINE_DOC (its </script> escaped in raw bytes),
+// so it is found in `doc`; a chrome declaration (immutable, outside INLINE_DOC) is
+// found in the raw file text. Return which, so the reader can judge edit-reachability.
+function declarationLocus(fileText, doc) {
+  if (doc && DECL_RE.test(doc)) return { hay: doc, inEditableBody: true };
+  return { hay: fileText, inEditableBody: false };
+}
+
+/**
+ * Extract the embedded #rwa-affordances declaration, if any.
+ * @returns {{ declaration: object|null, raw: string|null, error: string|null }}
+ */
+export function parseDeclaration(fileText, doc) {
+  const m = declarationLocus(fileText, doc).hay.match(DECL_RE);
+  if (!m) return { declaration: null, raw: null, error: null };
+  try {
+    return { declaration: JSON.parse(m[1]), raw: m[1], error: null };
+  } catch (e) {
+    return { declaration: null, raw: m[1], error: 'invalid JSON: ' + (e && e.message) };
+  }
+}
+
+/**
+ * Edit-reachability facts for the declaration (spec §3.1). Trustworthy iff
+ * `!inEditableBody` (chrome) OR `frozenAttr` (data-rwa-frozen — enforced by the
+ * lens, and by the CLI as of attribute-form enforcement). `frozenZones` is NOT
+ * consulted (marker-form only, SD-04).
+ * @returns {{ found: boolean, inEditableBody: boolean, frozenAttr: boolean }}
+ */
+export function declarationFacts(fileText, doc) {
+  const { hay, inEditableBody } = declarationLocus(fileText, doc);
+  const m = hay.match(DECL_RE);
+  if (!m) return { found: false, inEditableBody: false, frozenAttr: false };
+  const openTag = m[0].slice(0, m[0].indexOf('>') + 1);
+  // DOM-accurate: data-rwa-frozen must be a real attribute NAME (not a value-
+  // mention / longer name), matching the seed's actual enforcement — else the
+  // CLI would over-trust a declaration the lens can still drift (euler #112).
+  return { found: true, inEditableBody, frozenAttr: tagHasFrozenAttr(openTag) };
+}
+
+export const SOURCES = ['static', 'live', 'declared'];
+const isStrArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+/**
+ * Validate a self-description/1 object against the §2/§3.1 schema — a publish-safe
+ * MIRROR of tools/self-description.mjs validateSelfDescription, so the reader can
+ * guarantee it never emits a non-conforming declared answer without importing
+ * repo-root tools/ at runtime. Pinned to the oracle by test (identity.test.mjs).
+ * KEEP IN STEP with tools/self-description.mjs.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateSelfDescription(obj) {
+  const errors = [];
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return { valid: false, errors: ['not an object'] };
+  if (obj.rwa !== SCHEMA_TAG) errors.push('rwa must be "' + SCHEMA_TAG + '"');
+  if (!SOURCES.includes(obj.source)) errors.push('source must be one of ' + SOURCES.join(' | '));
+  // uuid/frozenZones are container facts the reader fills, so optional in a declaration.
+  if (obj.source === 'declared') {
+    if ('uuid' in obj && obj.uuid !== null && typeof obj.uuid !== 'string') errors.push('uuid, if present, must be a string or null');
+  } else if (!('uuid' in obj) || (obj.uuid !== null && typeof obj.uuid !== 'string')) {
+    errors.push('uuid must be a string or null');
+  }
+  if (typeof obj.kind !== 'string' || obj.kind.length === 0) errors.push('kind must be a non-empty string');
+  if ('title' in obj && obj.title !== null && typeof obj.title !== 'string') errors.push('title must be a string or null');
+  if ('blocks' in obj && (typeof obj.blocks !== 'number' || !Number.isFinite(obj.blocks))) errors.push('blocks must be a number');
+  if (!Array.isArray(obj.affordances)) {
+    errors.push('affordances must be an array');
+  } else {
+    obj.affordances.forEach((a, i) => {
+      if (a === null || typeof a !== 'object' || Array.isArray(a)) { errors.push('affordances[' + i + '] must be an object'); return; }
+      if (!AFFORDANCE_KINDS.includes(a.kind)) errors.push('affordances[' + i + '].kind unknown');
+      if (typeof a.name !== 'string' || !a.name) errors.push('affordances[' + i + '].name must be a non-empty string');
+      if ('label' in a && typeof a.label !== 'string') errors.push('affordances[' + i + '].label must be a string');
+      if (!PROVENANCES.includes(a.provenance)) errors.push('affordances[' + i + '].provenance must be first-party | installed');
+      if ('surface' in a && typeof a.surface !== 'string') errors.push('affordances[' + i + '].surface must be a string');
+      if ('target' in a && typeof a.target !== 'string') errors.push('affordances[' + i + '].target must be a string');
+      if ('output' in a && typeof a.output !== 'string') errors.push('affordances[' + i + '].output must be a string');
+      if ('inputs' in a && !isStrArray(a.inputs)) errors.push('affordances[' + i + '].inputs must be an array of strings');
+      if ('verified' in a && typeof a.verified !== 'boolean') errors.push('affordances[' + i + '].verified must be a boolean');
+    });
+  }
+  if ('data' in obj && obj.data !== null && typeof obj.data !== 'string') errors.push('data must be a string or null');
+  if ('frozenZones' in obj) {
+    if (!isStrArray(obj.frozenZones)) errors.push('frozenZones must be an array of strings');
+  } else if (obj.source !== 'declared') {
+    errors.push('frozenZones must be an array of strings');
+  }
+  if ('baseline' in obj) {
+    const b = obj.baseline;
+    if (b === null || typeof b !== 'object' || Array.isArray(b)) {
+      errors.push('baseline must be an object');
+    } else {
+      for (const k of ['edit', 'tools', 'export', 'history', 'view']) {
+        if (k in b && !isStrArray(b[k])) errors.push('baseline.' + k + ', if present, must be an array of strings');
+      }
+      if (Array.isArray(b.history) && b.history.includes('redo')) errors.push('baseline.history must not claim "redo"');
+    }
+  }
+  if (obj.source === 'static' && 'activeView' in obj) errors.push('static projection must omit activeView');
+  if ('activeView' in obj && obj.activeView !== null && typeof obj.activeView !== 'string') errors.push('activeView must be a string or null');
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * The reader's one answer (spec §3.1 precedence: declared > static). If the file
+ * carries a TRUSTWORTHY (edit-unreachable) declaration that — once the reader
+ * fills container facts (uuid/frozenZones/blocks from the bytes, authoritative
+ * over any author claim) — VALIDATES, emit it as `source:'declared'`. Otherwise
+ * emit the static kind-derived projection. Validating the assembled object before
+ * trusting it guarantees the reader never emits a non-conforming answer (a subtly
+ * malformed trustworthy declaration safely falls back to static). No `live`
+ * registry on the static path, so there is no declared>live>static middle tier.
+ *
+ * @param {{fileText:string, doc:string, uuid:string|null, kind:string, frozenZones:string[]}} facts
+ * @returns {object} a self-description/1 object (`source:'declared'` or `'static'`)
+ */
+export function resolveSelfDescription({ fileText, doc, uuid, kind, frozenZones }) {
+  const f = declarationFacts(fileText, doc);
+  if (f.found && (!f.inEditableBody || f.frozenAttr)) {
+    const { declaration } = parseDeclaration(fileText, doc);
+    if (declaration && typeof declaration === 'object' && !Array.isArray(declaration)) {
+      // Fill ONLY container facts (uuid/frozenZones/blocks from the bytes —
+      // authoritative over any author claim). Do NOT force rwa/source: the
+      // discriminator and source are the author's claim and must already be
+      // correct, or the declaration is non-conforming and we must not "repair"
+      // it into a trusted answer (e.g. a `schema`-not-`rwa` pre-aligned block).
+      // Union installed skills (parseSkillZone) into the declared affordances —
+      // the static path does, so dropping them here made declared≠live (SD-04).
+      // Declared providers win a (kind,name) collision; mirrors the seed's
+      // runtimeDescribe registry→declared→installed precedence.
+      const declAff = Array.isArray(declaration.affordances) ? declaration.affordances : [];
+      const seen = new Set(declAff.map((a) => a.kind + '\0' + a.name));
+      const candidate = {
+        ...declaration,
+        affordances: [...declAff, ...parseSkillZone(doc).filter((s) => !seen.has(s.kind + '\0' + s.name))],
+        uuid,
+        frozenZones,
+        blocks: countBlocks(doc),
+      };
+      if (candidate.source === 'declared' && validateSelfDescription(candidate).valid) return candidate;
+    }
+  }
+  return buildSelfDescription({ doc, uuid, kind, frozenZones });
+}

package/src/import-claude.mjs

@@ -17,10 +17,19 @@ import * as pdfjs from 'pdfjs-dist/legacy/build/pdf.mjs';
 // strictly better fidelity than either the local pdfjs heuristic or the
 // raw-vision OpenRouter path, on documents where the skills apply.
 //
-// Trust model: this spawns a Claude Code subprocess with
-// `--permission-mode bypassPermissions`, which lets the agent run shell
-// commands and write files without prompting. The user already trusts
-// their input file (they're importing it). Document this in HELP.
+// Trust model: this spawns a Claude Code subprocess that reads the input file's
+// CONTENTS into an agent context (the pdf/docx skill needs Python — pypdf,
+// pdfplumber, mammoth — to extract them, so the agent genuinely needs tool
+// access). That makes the file attacker-controlled input: prompt-injection text
+// hidden in a third-party PDF/DOCX could hijack the agent. `import` is precisely
+// the command you point at files you received from someone else, so "the user
+// trusts their input file" is the WRONG threat model.
+//
+// Therefore `--claude` is gated behind an explicit `--trust-input` consent flag
+// (convertViaClaudeCli throws below if it is absent). Only when the user vouches
+// for the file do we add `--permission-mode bypassPermissions`. The default
+// import path (pdfjs/mammoth — parses bytes, never executes the file's content)
+// remains the safe, no-flag route. Documented in HELP.
 
 const SKILL_FOR_EXT = { pdf: 'pdf', docx: 'docx' };
 
@@ -103,6 +112,21 @@ export async function convertViaClaudeCli(filePath, ext, opts = {}) {
     throw e;
   }
 
+  // Consent gate (SECURITY). Refuse to point an autonomous agent at the file
+  // unless the user explicitly vouched for it. Must run BEFORE any file read or
+  // subprocess spawn, so an unconsented file is never touched by the agent.
+  if (!opts.trustInput) {
+    const e = new Error(
+      `refusing to run an autonomous agent on ${filePath} without consent.\n` +
+      `  --claude extraction reads the file's contents into a Claude Code agent, so a\n` +
+      `  malicious file could hijack it (prompt-injection -> code execution).\n` +
+      `  Re-run with --claude --trust-input only if you trust this file's source.\n` +
+      `  (The default import, without --claude, parses the file safely and never executes its contents.)`
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+
   // docx isn't naturally page-chunkable (no fixed page boundaries inside the
   // XML). Single call.
   if (ext !== 'pdf') {

package/src/import-vision.mjs

@@ -57,7 +57,7 @@ export async function convertPdfViaVision(bytes, { apiKey, model, signal } = {})
   const dataUri = `data:application/pdf;base64,${buf.toString('base64')}`;
 
   const body = {
-    model: model || 'google/gemini-3-flash-preview',
+    model: model || 'google/gemini-3.5-flash',
     messages: [
       { role: 'system', content: SYSTEM_PROMPT },
       {

package/src/import.mjs

@@ -38,8 +38,9 @@ function toText(bytes) {
 }
 
 function convertMd(md) {
-  const html = marked.parse(md, { gfm: true, breaks: false });
-  return { html: `<article>\n${html.trim()}\n</article>`, warnings: [] };
+  const raw = marked.parse(md, { gfm: true, breaks: false });
+  const { html, warnings } = sanitizeImportedHtml(raw);
+  return { html: `<article>\n${html.trim()}\n</article>`, warnings };
 }
 
 function convertHtml(input) {
@@ -149,16 +150,30 @@ async function convertDocx(bytes) {
 // escapes &, ", <, > inside values, so a regex match against `attr="..."` is
 // sufficient — no quote-escape ambiguity to worry about.
 const _SAFE_HREF_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
+// Two layers, both required:
+//   1) Strip invisibles before parsing — whitespace + C0/C1 controls (\x00-\x1f,
+//      \x7f-\xa0) + soft hyphen (\xad) + Cf-class format chars (ZWSP/ZWNJ/ZWJ,
+//      LRM/RLM, LRE/RLE/PDF/LRO/RLO, word joiner, BOM, etc.). The previous
+//      regex used JS \s which doesn't match these — they slipped through and
+//      let a docx with `​javascript:…` href bypass the scheme check.
+//   2) Parse via WHATWG URL — the same parser the browser uses to navigate.
+//      Resolve against a synthetic base so scheme-less inputs (relative URL,
+//      fragment, path) round-trip back to that base and pass.
+const _ATTR_STRIP_RE = /[\s\x00-\x1f\x7f-\xa0\xad؜᠎​-‏‪-‮⁠-]/g;
+const _SANITIZER_BASE = 'http://_rwa_sanitizer_base_/';
 function _attrIsSafe(attr, val) {
-  const m = val.match(/^\s*([a-z][a-z0-9+.\-]*):/i);
-  if (!m) return true; // no scheme: relative URL, fragment, or path
-  const proto = m[1].toLowerCase();
+  const normalized = String(val).replace(_ATTR_STRIP_RE, '');
+  let parsed;
+  try { parsed = new URL(normalized, _SANITIZER_BASE); }
+  catch { return true; } // unparseable → cannot be an active URL scheme
+  if (parsed.origin === 'http://_rwa_sanitizer_base_') return true; // resolved relative — no scheme
+  const proto = parsed.protocol.replace(/:$/, '').toLowerCase();
   if (_SAFE_HREF_SCHEMES.has(proto)) return true;
-  // Mammoth embeds images as data:image/...;base64,... — allow that one
-  // narrow shape on src only. A docx that lies about its image content-type
-  // could produce data:text/html in src; img doesn't execute scripts there,
-  // so it's a UX issue (broken image) not a security issue.
-  if (attr === 'src' && proto === 'data' && /^\s*data:image\//i.test(val)) return true;
+  // Mammoth embeds raster images as data:image/...;base64,... — allow on src.
+  // data:image/svg+xml passes here too, but <img src> renders SVG in image-
+  // loading mode with no script execution (HTML spec), so the narrow
+  // 'data:image/*' allowance is still safe for src. Keep scoped to src only.
+  if (attr === 'src' && proto === 'data' && /^data:image\//i.test(parsed.href)) return true;
   return false;
 }
 function sanitizeMammothUrls(html) {
@@ -178,6 +193,57 @@ function sanitizeMammothUrls(html) {
   };
 }
 
+// marked v14 explicitly does NOT sanitize HTML — its README points readers at
+// DOMPurify. The seed bootstrap injects INLINE_DOC via m.innerHTML AND
+// re-creates <script> tags so they execute (intended for documents that ship
+// JS), so any active content in the imported HTML runs on container open. An
+// imported .md must not be able to add active content.
+//
+// Regex-based strip (not a parser) for mirror-symmetry with the browser. The
+// rules below are deliberately conservative: when in doubt, strip. Marked's
+// output is well-formed and uses double-quoted attributes, so the regex shape
+// matches reliably. Edge cases (CDATA, malformed nesting) are over-stripped
+// rather than under-stripped — acceptable for an import path.
+const _ACTIVE_TAGS = ['script', 'iframe', 'object', 'embed', 'svg', 'math', 'link', 'meta', 'base'];
+export function sanitizeImportedHtml(html) {
+  const warnings = [];
+  let s = String(html);
+  // 1) Drop active-content tags (open+close blocks, then self-closing/unmatched).
+  for (const tag of _ACTIVE_TAGS) {
+    const block = new RegExp('<' + tag + '\\b[^>]*>[\\s\\S]*?<\\/' + tag + '\\s*>', 'gi');
+    const solo  = new RegExp('<\\/?' + tag + '\\b[^>]*\\/?>', 'gi');
+    if (block.test(s) || solo.test(s)) warnings.push('imported md: stripped <' + tag + '> elements');
+    s = s.replace(block, '').replace(solo, '');
+  }
+  // 2) Drop on*= event-handler attributes from surviving elements.
+  //    Match quoted (double/single) and unquoted-to-whitespace/> forms.
+  let onCount = 0;
+  s = s.replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, () => { onCount++; return ''; });
+  if (onCount) warnings.push('imported md: stripped ' + onCount + ' event-handler attribute(s)');
+  // 3) Apply scheme allow-list to surviving URL-bearing attributes. Marked's
+  //    output is double-quoted href/src only, but rwa clone feeds ARBITRARY web
+  //    HTML here — single-quoted, unquoted, and other URL attributes (action/
+  //    formaction/poster/xlink:href) are all common and must be checked too, or
+  //    a `href='javascript:…'` survives into the file:// container as a live,
+  //    clickable link. Match all three value forms (mirror of the on*= strip)
+  //    and the full reachable URL-attr set. data:image/* stays allowed on src.
+  let urlSkipped = 0;
+  s = s.replace(
+    /(\s)(xlink:href|formaction|href|src|action|poster)(\s*=\s*)("[^"]*"|'[^']*'|[^\s>]+)/gi,
+    (full, ws, name, eq, rawVal) => {
+      const lname = name.toLowerCase();
+      const attr = (lname === 'src' || lname === 'poster') ? 'src' : 'href';
+      const quoted = rawVal[0] === '"' || rawVal[0] === "'";
+      const val = quoted ? rawVal.slice(1, -1) : rawVal;
+      if (_attrIsSafe(attr, val)) return full;
+      urlSkipped++;
+      return ws + name + eq + '"#"';
+    }
+  );
+  if (urlSkipped) warnings.push('imported md: neutralised ' + urlSkipped + ' unsafe URL attribute(s)');
+  return { html: s, warnings };
+}
+
 async function convertPdf(bytes) {
   // pdfjs explicitly rejects Node's Buffer (despite Buffer extending Uint8Array)
   // and wants a plain Uint8Array view.

package/src/ls.mjs

@@ -0,0 +1,105 @@
+// `rwa ls` — collection-scale self-description. Where inspectDoc answers "what is
+// THIS file?", listRewritables answers "what are all these?": it resolves a set
+// of paths (files, directories, or — by default — the current directory) to
+// candidate .html files and reports each one's self-description/1 projection,
+// flagging non-rewritables. The scan is lenient: a missing path or a
+// non-rewritable is a row in the result, never a thrown error — so one bad entry
+// can't abort the inventory of a whole folder.
+
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspectDoc } from './doc.mjs';
+
+const HTML_RE = /\.html?$/i;
+
+/**
+ * Expand input paths to a flat, ordered list of candidate files. A directory
+ * contributes its (non-recursive) .html children; a file contributes itself; a
+ * path that cannot be stat'd is kept as a `missing` candidate so the caller can
+ * report it rather than silently drop it. No inputs ⇒ scan the current directory.
+ *
+ * @param {string[]} paths
+ * @returns {Promise<Array<{file:string, missing?:boolean}>>}
+ */
+export async function resolveTargets(paths) {
+  const inputs = (paths && paths.length) ? paths : ['.'];
+  const targets = [];
+  for (const p of inputs) {
+    let st;
+    try { st = await stat(p); } catch { targets.push({ file: p, missing: true }); continue; }
+    if (st.isDirectory()) {
+      let names;
+      try { names = await readdir(p); } catch { targets.push({ file: p, missing: true }); continue; }
+      for (const name of names.filter(n => HTML_RE.test(n)).sort()) {
+        targets.push({ file: join(p, name) });
+      }
+    } else {
+      targets.push({ file: p });
+    }
+  }
+  return targets;
+}
+
+/**
+ * Inspect each candidate and classify it. Each row is one of:
+ *   { file, status:'rewritable', self }            — self-description/1 object
+ *   { file, status:'not_a_rewritable' }            — a plain .html / other file
+ *   { file, status:'error', reason }               — not_found / read_error
+ *
+ * @param {string[]} paths
+ * @returns {Promise<Array<object>>}
+ */
+export async function listRewritables(paths) {
+  const targets = await resolveTargets(paths);
+  const rows = [];
+  for (const t of targets) {
+    if (t.missing) { rows.push({ file: t.file, status: 'error', reason: 'not_found' }); continue; }
+    try {
+      const info = await inspectDoc(t.file);
+      rows.push({ file: t.file, status: 'rewritable', self: info.self });
+    } catch (e) {
+      if (e && e.subcode === 'not_a_rewritable') {
+        rows.push({ file: t.file, status: 'not_a_rewritable' });
+      } else {
+        rows.push({ file: t.file, status: 'error', reason: (e && e.subcode) || 'read_error' });
+      }
+    }
+  }
+  return rows;
+}
+
+/**
+ * Render the rows as a human-readable, aligned inventory. Rewritables become a
+ * KIND/TITLE/AFFORDANCES/FILE table; a footer counts rewritables vs. other files
+ * and names any errors — nothing is silently dropped (Rule 12).
+ *
+ * @param {Array<object>} rows
+ * @returns {string}
+ */
+export function formatRows(rows) {
+  const rwa = rows.filter(r => r.status === 'rewritable');
+  const other = rows.filter(r => r.status === 'not_a_rewritable');
+  const errors = rows.filter(r => r.status === 'error');
+
+  const lines = [];
+  if (rwa.length) {
+    const cells = rwa.map(r => ({
+      kind: r.self.kind || '',
+      title: r.self.title || '—',
+      affordances: r.self.affordances.length ? r.self.affordances.map(a => a.kind).join(',') : '—',
+      file: r.file,
+    }));
+    const head = { kind: 'KIND', title: 'TITLE', affordances: 'AFFORDANCES', file: 'FILE' };
+    const w = (k) => Math.max(head[k].length, ...cells.map(c => c[k].length));
+    const wk = w('kind'), wt = w('title'), wa = w('affordances');
+    const row = (c) => `${c.kind.padEnd(wk)}  ${c.title.padEnd(wt)}  ${c.affordances.padEnd(wa)}  ${c.file}`;
+    lines.push(row(head));
+    for (const c of cells) lines.push(row(c));
+    lines.push('');
+  }
+  const parts = [`${rwa.length} rewritable${rwa.length === 1 ? '' : 's'}`];
+  if (other.length) parts.push(`${other.length} other (${other.map(r => r.file).join(', ')})`);
+  if (errors.length) parts.push(`${errors.length} error (${errors.map(r => `${r.file}: ${r.reason}`).join(', ')})`);
+  lines.push(parts.join(', '));
+  return lines.join('\n');
+}