kaloko 0.12.0 → 0.12.1

package/src/lib/pii.mjs

@@ -1,19 +1,23 @@
 // Personal data in captures (#64): one mask for every output of a step. The mask is applied to the page itself for the
-// moment of the capture (maskInPage): the screenshot, the stored HTML, the page outline for the evaluators, the
-// keyboard shots and the HTML view all see placeholders ("[hidden]") or consistent fake values (pseudonymize), and the
-// page gets its own text back right after. Recordings get an overlay that covers the same places while the walk runs
-// (maskPainter). Every value masked is remembered for the run (rememberPii), so traces, console lines, capture records
-// and later steps replace it too. `kaloko share` scans what it is about to upload (piiFindings) and refuses unmasked
-// e-mails, phone numbers, birth numbers and IBANs unless told --allow-pii.
+// moment of the capture (maskInPage): the screenshot, the stored HTML, the page outline for the evaluators and the HTML
+// view all see placeholders ("[hidden]") or consistent fake values (pseudonymize), and the page gets its own text back
+// right after. Attributes nobody sees (data-*, content, links) are not touched in the live page: their masked values
+// are applied to the stored HTML (maskHtml). Recordings get an overlay that covers the same places while the walk runs
+// (maskPainter). Every value masked is remembered for the run (rememberPii, kept in the run folder for the next
+// process), so traces, console lines, capture records and later steps replace it too. `kaloko share` scans what it is
+// about to upload (piiFindings): a run that asked for hiding personal data is refused with unmasked e-mails, phone
+// numbers, birth numbers or IBANs in it (unless --allow-pii); any other run gets a warning.
 //
 // piiKit, maskInPage and maskPainter run inside the browser: keep them self-contained (no outer references).
-import { readFile } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { UserError } from './util.mjs'
 
 /**
  * Detection, placeholders and fake values. Self-contained: Node calls it directly, the page gets it serialised.
- * find(text, { kinds, allow }) → [{ kind, start, end, value }] in text order, without overlaps.
+ * find(text, { kinds, allow, context }) → [{ kind, start, end, value, plain? }] in text order, without overlaps.
+ * `context` is the text just before (a label in the previous element); `plain` is the decoded value of a hit in
+ * percent-encoded text (?email=jan%40firma.cz).
  */
 export function piiKit () {
   const KINDS = ['email', 'phone', 'birth_number', 'account', 'iban', 'birth_date', 'address', 'name']
@@ -22,10 +26,12 @@ export function piiKit () {
   const digits = (s) => String(s).replace(/\D/g, '')
   const wild = (p) => new RegExp('^' + String(p).trim().split('*').map((x) => x.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', 'i')
   const allowed = (value, allow) => (allow || []).some((p) => wild(p).test(value.trim()) || (digits(p).length >= 6 && !String(p).includes('*') && digits(p) === digits(value)))
+  const DAYS = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
   const birthNumberOk = (yy, mm, dd, tail) => {
     let m = Number(mm); const d = Number(dd)
-    if (m > 70) m -= 70; else if (m > 50) m -= 50; else if (m > 20 && tail.length === 4) m -= 20
-    if (m < 1 || m > 12 || d < 1 || d > 31) return false
+    // women +50; since 2004 also +20 (men) and +70 (women), only in the ten-digit form
+    if (m > 70 && tail.length === 4) m -= 70; else if (m > 50) m -= 50; else if (m > 20 && tail.length === 4) m -= 20
+    if (m < 1 || m > 12 || d < 1 || d > DAYS[m - 1]) return false
     if (tail.length === 3) return Number(yy) < 54
     const n = Number(`${yy}${mm}${dd}${tail}`)
     return n % 11 === 0 || (Math.floor(n / 10) % 11 === 10 && n % 10 === 0)
@@ -42,29 +48,48 @@ export function piiKit () {
     for (const c of r) m = (m * 10 + Number(c)) % 97
     return m === 1
   }
-  const CURRENCY = /^\s?(Kč|Kc|CZK|EUR|€|\$|USD|,-)/
+  // an amount, not a phone number: a currency or decimals right after it, a currency right before it
+  const CURRENCY = /^\s?(Kč|Kc|CZK|EUR|€|\$|USD|£|GBP|,-|[.,]\d)/i
+  const CURRENCY_BEFORE = /(Kč|CZK|EUR|€|\$|USD|£|GBP)\s?$/i
+  // a phone number written 603 123 456 counts only next to a word that says so (or another phone number)
+  const TEL = /(?:^|[^\p{L}])(?:tel|telefon|telephone|phone|mobil|mobile|mob|gsm|fax|volejte|zavolejte|call|kontakt|contact|sms|whatsapp|hotline|linka)\p{L}*\.?(?![\p{L}])|[☎📞]|\+\d{2,3}[  ]?\d{3}/iu
+  // a birth number without the slash, or in the old nine-digit form, only next to its label
+  const BIRTH = /(?:^|[^\p{L}])(?:rodn\p{L}*|r\.\s?č\.?|rč|birth\s?number|personal\s?(?:id|number|identification))(?![\p{L}])/iu
+  const before = (text, at, ctx, n = 60) => (String(ctx || '') + ' ' + text.slice(Math.max(0, at - n), at)).slice(-n)
   const finders = {
     email (text, out) {
-      for (const m of text.matchAll(/[\p{L}\p{N}._%+-]+@([\p{L}\p{N}-]+(?:\.[\p{L}\p{N}-]+)*\.(\p{L}{2,24}))(?![\p{L}\p{N}])/gu)) {
+      if (!text.includes('@')) return
+      // the local part at most 64 characters and from its start (a lookbehind): no quadratic search in long words
+      for (const m of text.matchAll(/(?<![\p{L}\p{N}._%+-])[\p{L}\p{N}._%+-]{1,64}@([\p{L}\p{N}-]{1,63}(?:\.[\p{L}\p{N}-]{1,63}){0,8}\.(\p{L}{2,24}))(?![\p{L}\p{N}])/gu)) {
         if (RESERVED.test(m[1]) || FILE_TLD.test(m[2]) || m[0].startsWith('.')) continue
         out.push({ kind: 'email', start: m.index, end: m.index + m[0].length })
       }
     },
-    phone (text, out) {
-      // international (+420 603 123 456, 00420…) and Czech grouped 3-3-3 (603 123 456); a fake keeps 000 after the code
-      for (const m of text.matchAll(/(?<![\p{L}\p{N}+])(?:\+|00)\d{1,3}[ \u00a0.-]?(?:\(\d{1,4}\)[ \u00a0.-]?)?\d{1,4}(?:[ \u00a0.-]?\d{2,4}){1,4}(?![\p{N}])/gu)) {
+    phone (text, out, ctx) {
+      // international (+420 603 123 456, 00420 603 123 456); a fake keeps 000 after the code
+      for (const m of text.matchAll(/(?<![\p{L}\p{N}+\-./_#])(?:\+|00)\d{1,3}[  .-]?(?:\(\d{1,4}\)[  .-]?)?\d{1,4}(?:[  .-]?\d{2,4}){1,4}(?![\p{N}])/gu)) {
         const n = digits(m[0]).replace(/^00/, '')
-        if (n.length < 9 || n.length > 15 || /^\+?(00)?\d{1,3}[ \u00a0.-]?0{3}/.test(m[0])) continue
-        out.push({ kind: 'phone', start: m.index, end: m.index + m[0].length })
+        if (n.length < 9 || n.length > 15 || /^\+?(00)?\d{1,3}[  .-]?0{3}/.test(m[0])) continue
+        // order numbers and EANs start with 00 too: 00 only with a space after the country code
+        if (m[0].startsWith('00') && !/^00\d{1,3}[  ]\d/.test(m[0])) continue
+        const end = m.index + m[0].length
+        if (CURRENCY.test(text.slice(end, end + 6)) || CURRENCY_BEFORE.test(text.slice(Math.max(0, m.index - 6), m.index))) continue
+        out.push({ kind: 'phone', start: m.index, end })
       }
-      for (const m of text.matchAll(/(?<![\p{N}+][ \u00a0]?)(?<![.,/-])[2-7]\d{2}[ \u00a0]\d{3}[ \u00a0]\d{3}(?![\p{N}])/gu)) {
-        if (CURRENCY.test(text.slice(m.index + m[0].length, m.index + m[0].length + 5))) continue
-        out.push({ kind: 'phone', start: m.index, end: m.index + m[0].length })
+      // Czech grouped 3-3-3 (603 123 456), with a label nearby; amounts (250 000 000 Kč, 349 990 000,00) are not
+      for (const m of text.matchAll(/(?<![\p{N}+][  ]?)(?<![\p{L}\p{N}.,/:#-])[2-7]\d{2}([  ])\d{3}\1\d{3}(?![\p{N}])/gu)) {
+        const end = m.index + m[0].length
+        if (CURRENCY.test(text.slice(end, end + 6)) || CURRENCY_BEFORE.test(text.slice(Math.max(0, m.index - 6), m.index))) continue
+        if (!TEL.test(before(text, m.index, ctx))) continue
+        out.push({ kind: 'phone', start: m.index, end })
       }
     },
-    birth_number (text, out) {
-      for (const m of text.matchAll(/(?<![\p{N}/])(\d{2})(\d{2})(\d{2}) ?\/ ?(\d{3,4})(?![\p{N}/])/gu)) {
-        if (birthNumberOk(m[1], m[2], m[3], m[4])) out.push({ kind: 'birth_number', start: m.index, end: m.index + m[0].length })
+    birth_number (text, out, ctx) {
+      for (const m of text.matchAll(/(?<![\p{N}/.,-])(\d{2})(\d{2})(\d{2})( ?\/ ?)?(\d{3,4})(?![\p{N}/])/gu)) {
+        const slash = !!m[4]; const tail = m[5]
+        if (tail.length === 3 && !slash) continue
+        if ((tail.length === 3 || !slash) && !BIRTH.test(before(text, m.index, ctx, 40))) continue
+        if (birthNumberOk(m[1], m[2], m[3], tail)) out.push({ kind: 'birth_number', start: m.index, end: m.index + m[0].length })
       }
     },
     account (text, out) {
@@ -73,13 +98,13 @@ export function piiKit () {
       }
     },
     iban (text, out) {
-      for (const m of text.matchAll(/(?<![\p{L}\p{N}])[A-Z]{2}\d{2}[ \u00a0]?[A-Z0-9]{4}/g)) {
+      for (const m of text.matchAll(/(?<![\p{L}\p{N}])[A-Z]{2}\d{2}[  ]?[A-Z0-9]{4}/g)) {
         // the longest run of groups that is a valid IBAN (the next word in capitals is not part of it)
-        const tail = text.slice(m.index, m.index + 50).match(/^[A-Z0-9]+(?:[ \u00a0][A-Z0-9]{1,4})*/)?.[0] || m[0]
+        const tail = text.slice(m.index, m.index + 50).match(/^[A-Z0-9]+(?:[  ][A-Z0-9]{1,4})*/)?.[0] || m[0]
         for (let end = tail.length; end >= 15; end--) {
           const cand = tail.slice(0, end)
-          if (/[ \u00a0]$/.test(cand) || /[A-Z0-9]/.test(tail[end] || '') && !/[ \u00a0]/.test(tail[end] || '')) continue
-          if (ibanOk(cand.replace(/[ \u00a0]/g, ''))) { out.push({ kind: 'iban', start: m.index, end: m.index + end }); break }
+          if (/[  ]$/.test(cand) || /[A-Z0-9]/.test(tail[end] || '') && !/[  ]/.test(tail[end] || '')) continue
+          if (ibanOk(cand.replace(/[  ]/g, ''))) { out.push({ kind: 'iban', start: m.index, end: m.index + end }); break }
         }
       }
     },
@@ -92,8 +117,8 @@ export function piiKit () {
     address (text, out) {
       // Czech: street and number, postcode and town (one line or two); English: number and street
       for (const m of text.matchAll(/[\p{Lu}][\p{L}.'’ -]{1,40}? \d{1,5}(?:\/\d{1,5})?[a-zA-Z]?,?\s+\d{3} ?\d{2}\s+[\p{Lu}][\p{L}-]+(?: (?:[\p{Lu}][\p{L}-]+|\d{1,2}))*/gu)) out.push({ kind: 'address', start: m.index, end: m.index + m[0].length })
-      for (const m of text.matchAll(/(?<![\p{N}])[1-9]\d{2}[ \u00a0]\d{2}[ \u00a0]+[\p{Lu}][\p{Ll}]+(?:[ -](?:[\p{Lu}][\p{Ll}]+|\d{1,2}))*(?![\p{L}])/gu)) {
-        if (/^\d{3}[ \u00a0]\d{2}[ \u00a0]+(Kč|Kc|Eur|Ks|Kusů|Kus)/.test(m[0])) continue
+      for (const m of text.matchAll(/(?<![\p{N}])[1-9]\d{2}[  ]\d{2}[  ]+[\p{Lu}][\p{Ll}]+(?:[ -](?:[\p{Lu}][\p{Ll}]+|\d{1,2}))*(?![\p{L}])/gu)) {
+        if (/^\d{3}[  ]\d{2}[  ]+(Kč|Kc|Eur|Ks|Kusů|Kus)/.test(m[0])) continue
         out.push({ kind: 'address', start: m.index, end: m.index + m[0].length })
       }
       for (const m of text.matchAll(/(?<![\p{N}])\d{1,5} (?:[\p{Lu}][\p{Ll}]+ ){1,3}(?:Street|St\.?|Avenue|Ave\.?|Road|Rd\.?|Lane|Ln\.?|Boulevard|Blvd\.?|Drive|Dr\.?|Court|Ct\.?|Way|Place|Pl\.?|Square)(?![\p{L}])/gu)) out.push({ kind: 'address', start: m.index, end: m.index + m[0].length })
@@ -106,19 +131,54 @@ export function piiKit () {
       }
     }
   }
-  /** Personal data in a text: [{ kind, start, end, value }], sorted, the longer of two overlapping matches kept. */
-  function find (text, { kinds = KINDS, allow = [] } = {}) {
+  /**
+   * Percent-encoded text decoded, with each character's place in the original ({ text, from, to }), or null. UTF-8
+   * sequences decode together; a broken one stays as it is.
+   */
+  function decodePct (text) {
+    if (!/%[0-9A-Fa-f]{2}/.test(text)) return null
+    let out = ''; const from = []; const to = []
+    const keep = (s, at) => { for (let i = 0; i < s.length; i++) { out += s[i]; from.push(at + i); to.push(at + i + 1) } }
+    let at = 0
+    for (const m of text.matchAll(/(?:%[0-9A-Fa-f]{2})+/g)) {
+      keep(text.slice(at, m.index), at)
+      const bytes = m[0].length / 3
+      for (let b = 0; b < bytes;) {
+        const first = parseInt(m[0].substr(b * 3 + 1, 2), 16)
+        const n = first < 0x80 ? 1 : first >= 0xf0 ? 4 : first >= 0xe0 ? 3 : first >= 0xc0 ? 2 : 1
+        let ch = null
+        if (n <= bytes - b) { try { ch = decodeURIComponent(m[0].substr(b * 3, n * 3)) } catch {} }
+        if (ch == null) { keep(m[0].substr(b * 3, 3), m.index + b * 3); b++; continue }
+        const s = m.index + b * 3; const e = s + n * 3
+        for (let k = 0; k < ch.length; k++) { out += ch[k]; from.push(s); to.push(e) }
+        b += n
+      }
+      at = m.index + m[0].length
+    }
+    keep(text.slice(at), at)
+    return out === text ? null : { text: out, from, to }
+  }
+  const scan = (text, kinds, ctx) => {
     const all = []
-    if (!text || !/[\p{N}@]/u.test(text) && !kinds.includes('name')) return all
-    for (const k of kinds) finders[k]?.(String(text), all)
+    if (!/[\p{N}@]/u.test(text) && !kinds.includes('name')) return all
+    for (const k of kinds) finders[k]?.(text, all, ctx)
+    return all
+  }
+  /** Personal data in a text: [{ kind, start, end, value, plain? }], sorted, the longer of two overlapping matches kept. */
+  function find (text, { kinds = KINDS, allow = [], context = '' } = {}) {
+    text = text == null ? '' : String(text)
+    if (!text) return []
+    const all = scan(text, kinds, context)
+    const dec = text.length < 500000 ? decodePct(text) : null
+    if (dec) for (const r of scan(dec.text, kinds, context)) all.push({ kind: r.kind, start: dec.from[r.start], end: dec.to[r.end - 1], plain: dec.text.slice(r.start, r.end) })
     all.sort((a, b) => a.start - b.start || (b.end - b.start) - (a.end - a.start))
     const out = []
     let end = -1
     for (const r of all) {
       if (r.start < end) continue
       const value = text.slice(r.start, r.end)
-      if (allowed(value, allow)) continue
-      out.push({ ...r, value }); end = r.end
+      if (allowed(value, allow) || (r.plain && allowed(r.plain, allow))) continue
+      out.push({ kind: r.kind, start: r.start, end: r.end, value, ...(r.plain && r.plain !== value ? { plain: r.plain } : {}) }); end = r.end
     }
     return out
   }
@@ -149,7 +209,7 @@ export function piiKit () {
   /** The kind of a whole value (an element the scenario masks, a form field). */
   function kindOf (value) {
     const v = String(value || '').trim()
-    const hit = find(v, { kinds: KINDS.filter((k) => k !== 'name') })
+    const hit = find(v, { kinds: KINDS.filter((k) => k !== 'name'), context: 'tel rč' })
     if (hit.length === 1 && hit[0].start === 0 && hit[0].end === v.length) return hit[0].kind
     return NAME.test(v) ? 'name' : 'text'
   }
@@ -168,31 +228,32 @@ export function piiKit () {
     if (/(^|\s)(name|given-name|family-name|additional-name)\b/.test(ac) || /^(name|full_?name|first_?name|last_?name|surname|given_?name|family_?name|jmeno|prijmeni)$/.test(key)) return 'name'
     return null
   }
-  // fake values: a hash of the run's salt and the value picks them, so one value gets one fake in the whole run
+  // fake values: a hash of the salt (scenario and project) and the value picks them, so one value gets one fake in
+  // every run of the scenario; the hash keeps a few bits of the value at most, so a fake does not lead back to it
   const hash = (s) => { let x = 0x811c9dc5; for (const ch of String(s)) { x ^= ch.codePointAt(0); x = Math.imul(x, 0x01000193) >>> 0 } return x }
   const rng = (seed) => { let s = seed || 1; return () => { s ^= s << 13; s >>>= 0; s ^= s >>> 17; s ^= s << 5; s >>>= 0; return s / 4294967296 } }
   const pick = (r, list) => list[Math.floor(r() * list.length)]
   const dd = (r, n) => Array.from({ length: n }, () => Math.floor(r() * 10)).join('')
   const ascii = (s) => s.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase()
-  const WOMEN = [['Jana', 'Nováková'], ['Eva', 'Svobodová'], ['Lucie', 'Dvořáková'], ['Tereza', 'Černá'], ['Klára', 'Procházková'], ['Anna', 'Kučerová']]
-  const MEN = [['Petr', 'Novák'], ['Tomáš', 'Svoboda'], ['Martin', 'Dvořák'], ['Jakub', 'Černý'], ['David', 'Procházka'], ['Ondřej', 'Kučera']]
+  const WOMEN = [['Jana', 'Eva', 'Lucie', 'Tereza', 'Klára', 'Anna', 'Petra', 'Hana', 'Marie', 'Lenka'], ['Nováková', 'Svobodová', 'Dvořáková', 'Černá', 'Procházková', 'Kučerová', 'Veselá', 'Horáková', 'Němcová', 'Marková']]
+  const MEN = [['Petr', 'Tomáš', 'Martin', 'Jakub', 'David', 'Ondřej', 'Pavel', 'Karel', 'Lukáš', 'Filip'], ['Novák', 'Svoboda', 'Dvořák', 'Černý', 'Procházka', 'Kučera', 'Veselý', 'Horák', 'Němec', 'Marek']]
   const STREETS = ['Lipová', 'Krátká', 'Polní', 'Školní', 'Zahradní', 'Luční']
   const TOWNS = ['Vzorov', 'Ukázkov', 'Testov']
-  function pseudonym (kind, value, salt = '') {
+  function pseudonym (kind, value, salt = '', attempt = 0) {
     const v = String(value || '').trim()
     const norm = kind === 'email' ? v.toLowerCase() : kind === 'phone' || kind === 'birth_number' || kind === 'account' ? digits(v) : v.replace(/\s+/g, ' ')
-    const r = rng(hash(`${salt}|${kind === 'known' ? kindOf(v) : kind}|${norm}`))
-    const person = () => { const p = pick(r, r() < 0.5 ? WOMEN : MEN); return p }
+    const r = rng(hash(`${salt}|${kind === 'known' ? kindOf(v) : kind}|${norm}${attempt ? `|${attempt}` : ''}`))
+    const person = () => { const [first, last] = r() < 0.5 ? WOMEN : MEN; return [pick(r, first), pick(r, last)] }
     const k = kind === 'known' || kind === 'text' ? kindOf(v) : kind
     if (k === 'email') { const [f, l] = person(); return `${ascii(f)}.${ascii(l)}${10 + Math.floor(r() * 90)}@example.com` }
     if (k === 'phone') {
-      const cc = v.match(/^(?:\+|00)(\d{1,3})(?=[ \u00a0.(-])/)?.[1] || (/^(?:\+|00)/.test(v) ? '420' : '')
+      const cc = v.match(/^(?:\+|00)(\d{1,3})(?=[  .(-])/)?.[1] || (/^(?:\+|00)/.test(v) ? '420' : '')
       return `${cc ? `+${cc} ` : ''}000 ${dd(r, 3)} ${dd(r, 3)}`
     }
     // month 00 does not exist: a fake birth number never passes as a real one
     if (k === 'birth_number') return `${dd(r, 2)}00${String(1 + Math.floor(r() * 28)).padStart(2, '0')}/${dd(r, 4)}`
     if (k === 'account') return `${dd(r, 10).replace(/^0/, '1')}/0000`
-    if (k === 'iban') { const n = v.replace(/[ \u00a0]/g, '').length; return (v.slice(0, 2) + '00' + dd(r, n - 4)).replace(/(.{4})(?=.)/g, '$1 ') }
+    if (k === 'iban') { const n = v.replace(/[  ]/g, '').length; return (v.slice(0, 2) + '00' + dd(r, n - 4)).replace(/(.{4})(?=.)/g, '$1 ') }
     if (k === 'birth_date') {
       const d = String(1 + Math.floor(r() * 28)); const m = String(1 + Math.floor(r() * 12)); const y = String(1950 + Math.floor(r() * 50))
       if (/^\d{4}-/.test(v)) return `${y}-${m.padStart(2, '0')}-${d.padStart(2, '0')}`
@@ -211,14 +272,63 @@ export function piiKit () {
   }
   /** "[hidden]" padded with dots to the length of the value it stands for (shorter values: dots only). */
   const placeholder = (value, label = '[hidden]') => { const n = [...String(value)].length; return n >= label.length ? label + '•'.repeat(n - label.length) : '•'.repeat(Math.max(1, n)) }
-  const replacement = (kind, value, ctx) => ctx.mode === 'pseudonymize' ? pseudonym(kind, value, ctx.salt) : placeholder(value, ctx.label)
-  return { KINDS, find, findKnown, merge, kindOf, fieldKind, pseudonym, placeholder, replacement }
+  /**
+   * The stand-in for a value: a placeholder, or a fake that is not in `taken` (fakes and real values already used),
+   * so two people never share one fake and a fake never equals a real value.
+   */
+  const replacement = (kind, value, ctx, taken = null) => {
+    if (ctx.mode !== 'pseudonymize') return placeholder(value, ctx.label)
+    let v = pseudonym(kind, value, ctx.salt)
+    for (let i = 1; taken && taken.has(v) && i < 40; i++) v = pseudonym(kind, value, ctx.salt, i)
+    const base = v
+    for (let n = 2; taken && taken.has(v); n++) v = base.includes('@') ? base.replace('@', `-${n}@`) : `${base} ${n}`
+    return v
+  }
+  // --- in the page only ---
+  /** This document and its same-origin frames: [{ doc, ox, oy }], ox/oy turn a frame's viewport point into a page point. */
+  function pageFrames () {
+    const out = []
+    const add = (doc, ox, oy, depth) => {
+      out.push({ doc, ox, oy })
+      if (depth >= 3) return
+      for (const f of doc.querySelectorAll('iframe, frame')) {
+        let d = null
+        try { d = f.contentDocument } catch {}
+        if (!d || !d.documentElement) continue
+        const r = f.getBoundingClientRect()
+        add(d, ox + r.left + f.clientLeft, oy + r.top + f.clientTop, depth + 1)
+      }
+    }
+    add(document, scrollX, scrollY, 0)
+    return out
+  }
+  /** A document and every open shadow root in it. */
+  function rootsOf (doc) {
+    const out = [doc]
+    for (let i = 0; i < out.length; i++) for (const el of out[i].querySelectorAll('*')) if (el.shadowRoot && el.tagName !== 'KALOKO-MASK') out.push(el.shadowRoot)
+    return out
+  }
+  /** The text nodes of a document or shadow root, in order. */
+  function textsOf (root) {
+    const start = root.nodeType === 9 ? root.documentElement : root
+    if (!start) return []
+    const w = (root.ownerDocument || root).createTreeWalker(start, 4)
+    const out = []
+    for (let n = w.nextNode(); n; n = w.nextNode()) out.push(n)
+    return out
+  }
+  /** The element above, also across a shadow boundary. */
+  const up = (node) => node.parentElement || (node.parentNode && node.parentNode.nodeType === 11 ? node.parentNode.host : null)
+  return { KINDS, find, findKnown, merge, kindOf, fieldKind, pseudonym, placeholder, replacement, decodePct, pageFrames, rootsOf, textsOf, up }
 }
 
 /**
- * Runs in the page (self-contained, `kit` is piiKit()): replaces masked text, form values and attributes in the live
- * document and keeps window.__kalokoMaskUndo to put them back. Returns the masked places in page coordinates
- * ({ x, y, w, h, kind, box }: box = drawn as a box on the screenshot) and the values masked ([original, replacement]).
+ * Runs in the page (self-contained, `kit` is piiKit()): replaces masked text, form values and the attributes a reader
+ * or the outline sees (title, alt, aria-label, placeholder, value) in the live document, in open shadow roots and in
+ * same-origin frames, and keeps window.__kalokoMaskUndo to put them back (in place from the first change, so a failure
+ * half-way leaves nothing masked). Attributes nobody sees (data-*, content, href, src) are left alone and returned as
+ * `attrs` ([original, masked]) for the stored HTML. Returns the masked places in page coordinates ({ x, y, w, h, kind,
+ * box }: box = drawn as a box on the screenshot) and the values masked ([original, replacement, kind]).
  */
 export function maskInPage (args, kit) {
   const { selectors = [], auto = false, mode = 'redact', salt = '', label = '[hidden]', allow = [], known = [] } = args
@@ -226,167 +336,207 @@ export function maskInPage (args, kit) {
   if (window.__kalokoMaskUndo) window.__kalokoMaskUndo()
   window.__kalokoMask?.pause()
   const undo = []
-  const pairs = new Map(known.map(([v, r]) => [v, r]))
-  const fresh = new Map()
-  const rects = []
-  const counts = {}
-  const masked = new Set()
-  for (const sel of selectors) { try { document.querySelectorAll(sel).forEach((el) => masked.add(el)) } catch {} }
-  const inMasked = (node) => { for (let el = node.nodeType === 1 ? node : node.parentElement; el; el = el.parentElement) if (masked.has(el)) return true; return false }
-  const CODE = ['email', 'birth_number', 'iban']
-  const made = new Set(known.map(([, r]) => r))
-  const repl = (r) => {
-    if (r.repl != null) { counts.known = (counts.known || 0) + 1; return r.repl }
-    if (made.has(r.value)) return r.value
-    let v = pairs.get(r.value)
-    if (v == null) { v = kit.replacement(r.kind, r.value, ctx); pairs.set(r.value, v) }
-    fresh.set(r.value, v); made.add(v)
-    counts[r.kind] = (counts[r.kind] || 0) + 1
-    return v
-  }
-  // every word-ish part of a masked value is masked: found data with its own kind, the rest as a whole
-  const whole = (text) => {
-    const lead = text.length - text.trimStart().length; const core = text.trim()
-    if (!core) return []
-    const found = kit.merge(kit.find(core, { allow: [] }), kit.findKnown(core, known))
-    const out = []; let at = 0
-    const rest = (s, e) => { const seg = core.slice(s, e); const t = seg.trim(); if (!/[\p{L}\p{N}]/u.test(t)) return; const off = s + seg.indexOf(t); out.push({ kind: kit.kindOf(t), start: lead + off, end: lead + off + t.length, value: t }) }
-    for (const r of found) { rest(at, r.start); out.push({ ...r, start: lead + r.start, end: lead + r.end }); at = r.end }
-    rest(at, core.length)
-    return out
-  }
-  const ranges = (text, isMasked, code = false) => isMasked ? whole(text) : kit.merge(auto ? kit.find(text, { allow, kinds: code ? CODE : undefined }) : [], kit.findKnown(text, known))
-  const rendered = (el) => el && !el.closest('head, script, style, noscript, template, title') && el.getClientRects().length > 0
-  const push = (r, kind, box) => { if (rects.length < 500 && r.width > 0 && r.height > 0) rects.push({ x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.ceil(r.width), h: Math.ceil(r.height), kind, box }) }
-  // whole elements the scenario masks: one box each (drawn in both modes when they hold no text, e.g. a photo)
-  for (const el of masked) { if (rendered(el) && !masked.has(el.parentElement)) push(el.getBoundingClientRect(), 'mask', mode === 'redact' || !el.textContent.trim()) }
-  // text
-  const walker = document.createTreeWalker(document.documentElement, NodeFilter.SHOW_TEXT)
-  const nodes = []
-  for (let n = walker.nextNode(); n; n = walker.nextNode()) nodes.push(n)
-  for (const node of nodes) {
-    const parent = node.parentElement
-    if (!parent || parent.closest('style, kaloko-mask')) continue
-    const text = node.nodeValue
-    if (!text || !text.trim()) continue
-    const isMasked = inMasked(node)
-    const list = ranges(text, isMasked, !!parent.closest('script'))
-    if (!list.length) continue
-    let out = ''; let at = 0; const spans = []
-    for (const r of list) { const v = repl(r); out += text.slice(at, r.start); spans.push([out.length, out.length + v.length, r.kind === 'known' ? 'known' : r.kind]); out += v; at = r.end }
-    out += text.slice(at)
-    node.nodeValue = out
-    undo.push(() => { node.nodeValue = text })
-    if (!isMasked && rendered(parent)) {
-      for (const [s, e, kind] of spans) { const range = document.createRange(); range.setStart(node, s); range.setEnd(node, e); for (const r of range.getClientRects()) push(r, kind, mode === 'redact') }
+  window.__kalokoMaskUndo = () => { for (const f of undo.splice(0).reverse()) { try { f() } catch {} } delete window.__kalokoMaskUndo; window.__kalokoMask?.resume() }
+  try {
+    const pairs = new Map(known.map(([v, r]) => [v, r]))
+    const taken = new Set(known.flatMap(([v, r]) => [v, r]))
+    const fresh = new Map()
+    const rects = []
+    const counts = {}
+    const attrs = new Map()
+    const roots = kit.pageFrames().flatMap((f) => kit.rootsOf(f.doc).map((root) => ({ root, f })))
+    const masked = new Set()
+    for (const { root } of roots) for (const sel of selectors) { try { root.querySelectorAll(sel).forEach((el) => masked.add(el)) } catch {} }
+    const inMasked = (node) => { for (let el = node.nodeType === 1 ? node : kit.up(node); el; el = kit.up(el)) if (masked.has(el)) return true; return false }
+    const CODE = ['email', 'birth_number', 'iban']
+    const repl = (r) => {
+      if (r.repl != null) { counts.known = (counts.known || 0) + 1; return r.repl }
+      const real = r.plain ?? r.value
+      let v = pairs.get(real) ?? pairs.get(r.value)
+      if (v == null) { taken.add(real); v = kit.replacement(r.kind, real, ctx, taken); taken.add(v) }
+      pairs.set(r.value, v); pairs.set(real, v)
+      // a part of a masked element that is no kind of its own is plain text (remembered only when it is long)
+      const kind = r.guess ? 'text' : r.kind
+      fresh.set(r.value, [v, kind]); if (real !== r.value) fresh.set(real, [v, kind])
+      counts[r.kind] = (counts[r.kind] || 0) + 1
+      return v
     }
-  }
-  // form fields as they are filled in (the value property, not only the attribute)
-  const SKIP = /^(password|hidden|submit|button|checkbox|radio|file|image|reset|range|color)$/
-  for (const el of document.querySelectorAll('input, textarea')) {
-    if (SKIP.test(el.type || '')) continue
-    const value = el.value
-    if (!value || !value.trim()) continue
-    const isMasked = inMasked(el)
-    const kind = !isMasked && auto ? kit.fieldKind(el) : null
-    const list = kind ? [{ kind, start: value.length - value.trimStart().length, end: value.trimEnd().length, value: value.trim() }] : ranges(value, isMasked)
-    if (!list.length) continue
-    let out = ''; let at = 0
-    for (const r of list) { out += value.slice(at, r.start) + repl(r); at = r.end }
-    out += value.slice(at)
-    const attr = el.getAttribute('value')
-    el.value = out
-    if (attr != null) el.setAttribute('value', out)
-    undo.push(() => { el.value = value; if (attr != null) el.setAttribute('value', attr) })
-    if (!isMasked && rendered(el)) push(el.getBoundingClientRect(), kind || list[0].kind, mode === 'redact')
-  }
-  // attributes that show or carry text: title, alt, aria-label, placeholder, value, content, mailto:/tel: links, data-*
-  const ATTR = /^(title|alt|aria-label|aria-description|placeholder|value|content|href|data-[\w-]+)$/i
-  for (const el of document.querySelectorAll('*')) {
-    if (el.closest('kaloko-mask')) continue
-    const isMasked = inMasked(el)
-    for (const a of [...el.attributes]) {
-      if (!ATTR.test(a.name) || !a.value.trim()) continue
-      if (a.name === 'href' && !/^\s*(mailto|tel):/i.test(a.value)) continue
-      if (a.name === 'value' && /^(INPUT|TEXTAREA)$/.test(el.tagName)) continue // the fields above
-      const list = isMasked && a.name !== 'href' ? whole(a.value) : ranges(a.value, false)
-      const hits = isMasked && a.name === 'href' ? [{ kind: 'text', start: a.value.indexOf(':') + 1, end: a.value.length, value: a.value.slice(a.value.indexOf(':') + 1) }] : list
-      if (!hits.length) continue
-      let out = ''; let at = 0
-      for (const r of hits) { out += a.value.slice(at, r.start) + repl(r); at = r.end }
-      out += a.value.slice(at)
-      const name = a.name; const before = a.value
-      el.setAttribute(name, out)
-      undo.push(() => el.setAttribute(name, before))
+    // every word-ish part of a masked value is masked: found data with its own kind, the rest as a whole
+    const whole = (text) => {
+      const lead = text.length - text.trimStart().length; const core = text.trim()
+      if (!core) return []
+      const found = kit.merge(kit.find(core, { allow: [] }), kit.findKnown(core, known))
+      const out = []; let at = 0
+      const rest = (s, e) => { const seg = core.slice(s, e); const t = seg.trim(); if (!/[\p{L}\p{N}]/u.test(t)) return; const off = s + seg.indexOf(t); out.push({ kind: kit.kindOf(t), guess: true, start: lead + off, end: lead + off + t.length, value: t }) }
+      for (const r of found) { rest(at, r.start); out.push({ ...r, start: lead + r.start, end: lead + r.end }); at = r.end }
+      rest(at, core.length)
+      return out
+    }
+    const ranges = (text, isMasked, kinds, context = '') => isMasked ? whole(text) : kit.merge(auto ? kit.find(text, { allow, kinds, context }) : [], kit.findKnown(text, known))
+    const rendered = (el) => el && !el.closest('head, script, style, noscript, template, title') && el.getClientRects().length > 0
+    const push = (r, kind, box, f) => { if (rects.length < 500 && r.width > 0 && r.height > 0) rects.push({ x: Math.round(r.left + f.ox), y: Math.round(r.top + f.oy), w: Math.ceil(r.width), h: Math.ceil(r.height), kind, box }) }
+    const spliceIn = (text, list) => { let out = ''; let at = 0; const spans = []; for (const r of list) { const v = repl(r); out += text.slice(at, r.start); spans.push([out.length, out.length + v.length, r.kind === 'known' ? 'known' : r.kind]); out += v; at = r.end } return { out: out + text.slice(at), spans } }
+    // whole elements the scenario masks: one box each (drawn in both modes when they hold no text, e.g. a photo)
+    for (const { root, f } of roots) for (const el of masked) if (el.getRootNode() === root && rendered(el) && !masked.has(kit.up(el))) push(el.getBoundingClientRect(), 'mask', mode === 'redact' || !el.textContent.trim(), f)
+    // text; the text before a node is its context (a "Telefon" label in the cell before the number)
+    let prev = ''
+    for (const { root, f } of roots) {
+      for (const node of kit.textsOf(root)) {
+        const parent = kit.up(node)
+        if (!parent || parent.closest('style, kaloko-mask')) continue
+        const text = node.nodeValue
+        if (!text || !text.trim()) continue
+        const script = parent.closest('script')
+        // inline JSON (JSON-LD, state) gets every kind; script code only the kinds a checksum or an @ confirms
+        const kinds = script && !/json/i.test(script.type || '') ? CODE : undefined
+        const isMasked = inMasked(node)
+        const list = ranges(text, isMasked, kinds, prev)
+        if (!script) prev = (prev + ' ' + text).slice(-80)
+        if (!list.length) continue
+        const { out, spans } = spliceIn(text, list)
+        node.nodeValue = out
+        undo.push(() => { node.nodeValue = text })
+        if (!isMasked && rendered(parent)) {
+          for (const [s, e, kind] of spans) { const range = node.ownerDocument.createRange(); range.setStart(node, s); range.setEnd(node, e); for (const r of range.getClientRects()) push(r, kind, mode === 'redact', f) }
+        }
+      }
+    }
+    // form fields as they are filled in (the value property, not only the attribute), hidden ones included
+    const SKIP = /^(password|submit|button|checkbox|radio|file|image|reset|range|color)$/
+    const handled = new Set()
+    for (const { root, f } of roots) {
+      for (const el of root.querySelectorAll('input, textarea')) {
+        if (SKIP.test(el.type || '')) continue
+        const value = el.value
+        if (!value || !value.trim()) continue
+        const hidden = el.type === 'hidden'
+        const isMasked = inMasked(el)
+        let kind = !isMasked && auto ? kit.fieldKind(el) : null
+        if (hidden && kind === 'name') kind = null // name="name" on a hidden field is rarely a person
+        const list = kind ? [{ kind, start: value.length - value.trimStart().length, end: value.trimEnd().length, value: value.trim() }] : ranges(value, isMasked)
+        if (!list.length) continue
+        const { out } = spliceIn(value, list)
+        const attr = el.getAttribute('value')
+        el.value = out
+        if (attr != null) el.setAttribute('value', out)
+        handled.add(el)
+        undo.push(() => { el.value = value; if (attr != null) el.setAttribute('value', attr) })
+        if (!hidden && !isMasked && rendered(el)) push(el.getBoundingClientRect(), kind || list[0].kind, mode === 'redact', f)
+      }
+    }
+    // attributes: what a reader or the outline sees is masked in the page; the rest only in the stored HTML (no
+    // observer of the page sees a data-* attribute change)
+    const LIVE = /^(title|alt|aria-label|aria-description|aria-valuetext|placeholder|value|label)$/i
+    const STORED = /^(data-[\w-]+|content|href|src|action|formaction|poster|srcset)$/i
+    const LINK = /^(href|src|action|formaction|poster|srcset)$/i
+    for (const { root, f } of roots) {
+      const top = f.doc === document && root === document
+      for (const el of root.querySelectorAll('*')) {
+        if (el.tagName === 'KALOKO-MASK') continue
+        const isMasked = inMasked(el)
+        for (const a of [...el.attributes]) {
+          const live = LIVE.test(a.name)
+          if ((!live && !(top && STORED.test(a.name))) || !a.value.trim()) continue
+          if (a.name === 'value' && handled.has(el)) continue // the fields above
+          const link = LINK.test(a.name)
+          const scheme = link && /^\s*(mailto|tel|sms):/i.test(a.value)
+          const at = a.value.indexOf(':') + 1
+          const hits = isMasked && scheme ? [{ kind: 'text', guess: true, start: at, end: a.value.length, value: a.value.slice(at) }] : isMasked && !link ? whole(a.value) : ranges(a.value, false)
+          if (!hits.length) continue
+          const { out } = spliceIn(a.value, hits)
+          if (live) { const name = a.name; const before = a.value; el.setAttribute(name, out); undo.push(() => el.setAttribute(name, before)) } else attrs.set(a.value, out)
+        }
+      }
     }
+    return { rects, pairs: [...fresh].map(([v, [r, k]]) => [v, r, k]), counts, attrs: [...attrs], changed: undo.length + attrs.size }
+  } catch (error) {
+    window.__kalokoMaskUndo?.()
+    throw error
   }
-  window.__kalokoMaskUndo = () => { for (const f of undo.reverse()) { try { f() } catch {} } delete window.__kalokoMaskUndo; window.__kalokoMask?.resume() }
-  return { rects, pairs: [...fresh].filter(([v]) => v.length >= 3), counts }
 }
 
 /**
  * Runs in the page (self-contained, `kit` is piiKit()): an overlay that keeps every masked place covered while the page
- * changes, for recordings, focus shots and crops. window.__kalokoMask: update(args), pause(), resume().
+ * changes, for recordings. It reads open shadow roots and same-origin frames, and paints inside an open modal dialog
+ * or popover too (the top layer is above anything else in the page). window.__kalokoMask: update(args), pause(),
+ * resume().
  */
 export function maskPainter (args, kit) {
   if (window.__kalokoMask) { window.__kalokoMask.update(args); return }
   let cfg = { selectors: [], known: [], ...args }
-  let paused = false; let pending = false; let host = null; let root = null
-  const ensure = () => {
-    if (host?.isConnected || !document.documentElement) return
-    host = document.createElement('kaloko-mask')
-    host.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;overflow:visible;z-index:2147483647;pointer-events:none;display:block;margin:0;padding:0;border:0'
-    root = host.attachShadow({ mode: 'closed' })
-    document.documentElement.appendChild(host)
+  let paused = false; let pending = false
+  const hosts = new Map()
+  const hostIn = (container, fixed) => {
+    const had = hosts.get(container)
+    if (had?.host.isConnected) return had
+    const host = document.createElement('kaloko-mask')
+    host.style.cssText = `position:${fixed ? 'fixed' : 'absolute'};left:0;top:0;width:0;height:0;overflow:visible;z-index:2147483647;pointer-events:none;display:block;margin:0;padding:0;border:0`
+    const root = host.attachShadow({ mode: 'closed' })
+    container.appendChild(host)
+    const h = { host, root, fixed }
+    hosts.set(container, h)
+    return h
   }
+  const topLayer = () => { for (const q of ['dialog:modal, :popover-open', 'dialog[open]']) { try { return [...document.querySelectorAll(q)] } catch {} } return [] }
   const collect = () => {
     const out = []
-    const add = (r) => { if (out.length < 500 && r.width > 0 && r.height > 0) out.push([r.left + scrollX, r.top + scrollY, r.width, r.height]) }
-    const masked = []
-    for (const sel of cfg.selectors) { try { document.querySelectorAll(sel).forEach((el) => masked.push(el)) } catch {} }
-    for (const el of masked) add(el.getBoundingClientRect())
-    const inMasked = (el) => masked.some((m) => m.contains(el))
-    if (!document.body) return out
-    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
-    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
-      const p = n.parentElement
-      if (!p || p.closest('script, style, noscript, template, kaloko-mask') || !n.nodeValue.trim()) continue
-      const list = kit.merge(cfg.auto ? kit.find(n.nodeValue, { allow: cfg.allow }) : [], kit.findKnown(n.nodeValue, cfg.known))
-      if (!list.length || inMasked(p)) continue
-      for (const r of list) { const range = document.createRange(); range.setStart(n, r.start); range.setEnd(n, r.end); for (const c of range.getClientRects()) add(c) }
-    }
-    for (const el of document.querySelectorAll('input, textarea')) {
-      if (/^(password|hidden|submit|button|checkbox|radio|file|image|reset|range|color)$/.test(el.type || '') || !el.value.trim() || inMasked(el)) continue
-      if ((cfg.auto && (kit.fieldKind(el) || kit.find(el.value, { allow: cfg.allow }).length)) || kit.findKnown(el.value, cfg.known).length) add(el.getBoundingClientRect())
+    const add = (r, f) => { if (out.length < 500 && r.width > 0 && r.height > 0) out.push([r.left + f.ox, r.top + f.oy, r.width, r.height]) }
+    const roots = kit.pageFrames().flatMap((f) => kit.rootsOf(f.doc).map((root) => ({ root, f })))
+    const masked = new Set()
+    for (const { root, f } of roots) for (const sel of cfg.selectors) { try { root.querySelectorAll(sel).forEach((el) => { masked.add(el); add(el.getBoundingClientRect(), f) }) } catch {} }
+    const inMasked = (el) => { for (let e = el; e; e = kit.up(e)) if (masked.has(e)) return true; return false }
+    let prev = ''
+    for (const { root, f } of roots) {
+      for (const n of kit.textsOf(root)) {
+        const p = kit.up(n)
+        if (!p || p.closest('head, title, script, style, noscript, template, kaloko-mask') || !n.nodeValue.trim()) continue
+        const list = kit.merge(cfg.auto ? kit.find(n.nodeValue, { allow: cfg.allow, context: prev }) : [], kit.findKnown(n.nodeValue, cfg.known))
+        prev = (prev + ' ' + n.nodeValue).slice(-80)
+        if (!list.length || inMasked(p)) continue
+        for (const r of list) { const range = n.ownerDocument.createRange(); range.setStart(n, r.start); range.setEnd(n, r.end); for (const c of range.getClientRects()) add(c, f) }
+      }
+      for (const el of root.querySelectorAll('input, textarea')) {
+        if (/^(password|hidden|submit|button|checkbox|radio|file|image|reset|range|color)$/.test(el.type || '') || !el.value.trim() || inMasked(el)) continue
+        if ((cfg.auto && (kit.fieldKind(el) || kit.find(el.value, { allow: cfg.allow }).length)) || kit.findKnown(el.value, cfg.known).length) add(el.getBoundingClientRect(), f)
+      }
     }
     return out
   }
   const paint = () => {
     pending = false
-    if (paused) return
-    ensure()
-    if (!root) return
-    const boxes = collect().map(([x, y, w, h]) => { const d = document.createElement('div'); d.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px;background:repeating-linear-gradient(135deg,#1f1f1d 0 6px,#34342f 6px 12px)`; return d })
-    root.replaceChildren(...boxes)
+    if (paused || !document.documentElement) return
+    const boxes = collect()
+    const draw = (h) => {
+      // a host inside the top layer is fixed: viewport coordinates, from wherever it actually sits
+      const o = h.fixed ? h.host.getBoundingClientRect() : null
+      const dx = o ? -scrollX - o.left : 0; const dy = o ? -scrollY - o.top : 0
+      h.root.replaceChildren(...boxes.map(([x, y, w, hh]) => { const d = document.createElement('div'); d.style.cssText = `position:absolute;left:${x + dx}px;top:${y + dy}px;width:${w}px;height:${hh}px;background:repeating-linear-gradient(135deg,#1f1f1d 0 6px,#34342f 6px 12px)`; return d }))
+    }
+    draw(hostIn(document.documentElement, false))
+    const tops = new Set(topLayer())
+    for (const [c, h] of hosts) if (c !== document.documentElement && !tops.has(c)) { h.host.remove(); hosts.delete(c) }
+    for (const el of tops) draw(hostIn(el, true))
   }
   const schedule = () => { if (!pending && !paused) { pending = true; requestAnimationFrame(paint) } }
   const start = () => {
-    new MutationObserver(schedule).observe(document.documentElement, { subtree: true, childList: true, characterData: true })
-    for (const ev of ['scroll', 'input', 'resize', 'load']) addEventListener(ev, schedule, true)
+    new MutationObserver(schedule).observe(document.documentElement, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ['open', 'popover', 'value', 'style', 'class', 'hidden'] })
+    for (const ev of ['scroll', 'input', 'resize', 'load', 'toggle']) addEventListener(ev, schedule, true)
     setInterval(schedule, 400)
     schedule()
   }
   window.__kalokoMask = {
     update (a) { cfg = { ...cfg, ...a, selectors: [...new Set([...cfg.selectors, ...(a.selectors || [])])], known: [...new Map([...cfg.known, ...(a.known || [])]).entries()] }; schedule() },
-    pause () { paused = true; host?.remove() },
+    pause () { paused = true; for (const h of hosts.values()) h.host.remove(); hosts.clear() },
     resume () { paused = false; schedule() }
   }
-  if (document.documentElement) start(); else document.addEventListener('DOMContentLoaded', start, { once: true })
+  // an init script runs before the document has an element: start with the first one, not at DOMContentLoaded
+  if (document.documentElement) start()
+  else new MutationObserver((_, o) => { if (document.documentElement) { o.disconnect(); start() } }).observe(document, { childList: true })
 }
 
 const kit = piiKit()
 export const findPii = (text, opts) => kit.find(text, opts)
-export const pseudonym = (kind, value, salt) => kit.pseudonym(kind, value, salt)
+export const pseudonym = (kind, value, salt, attempt) => kit.pseudonym(kind, value, salt, attempt)
 export const placeholder = (value, label) => kit.placeholder(value, label)
 
 /** The text of the masked placeholder in a locale. */
@@ -414,6 +564,11 @@ export function piiSettings ({ config = {}, env = {}, scenario = {}, args = {} }
   return { mode, allow: [...(config.pii?.allow || [])].map(String) }
 }
 
+/** Whether a run asked for hiding personal data (its own setting, the environment, the scenario or a mask: auto). */
+export function piiRequested ({ run = null, env = {}, scenario = {} }) {
+  return !!(run?.meta?.pii || ['required', ...PII_MODES].includes(env?.pii) || PII_MODES.includes(scenario?.pii) || scenarioMasks(scenario).auto)
+}
+
 /** capture.mask as given (a list of selectors, `auto`, or a list with `auto` in it): { selectors, auto }. */
 export function maskList (mask) {
   const list = mask == null ? [] : Array.isArray(mask) ? mask : [mask]
@@ -421,9 +576,19 @@ export function maskList (mask) {
   return { selectors: items.filter((s) => s !== 'auto'), auto: items.includes('auto') }
 }
 
+/**
+ * The salt of fake values: the scenario and the project, so one value gets the same fake in every run of the scenario
+ * (pixel diffs and approvals carry over). KALOKO_PII_SALT adds a secret of your own.
+ */
+export function piiSalt (meta = {}) {
+  const p = meta?.project
+  const project = typeof p === 'string' ? p : p?.id || p?.slug || p?.name || ''
+  return [process.env.KALOKO_PII_SALT || '', project, meta?.scenario?.id || meta?.id || ''].join('|')
+}
+
 /**
  * What one capture masks: the selectors of the scenario and the step, automatic detection (the run's pii setting or
- * `mask: auto`), the mode and the run's salt for fake values. `active` is false when there is nothing to mask.
+ * `mask: auto`), the mode and the salt for fake values. `active` is false when there is nothing to mask.
  */
 export function maskSpec ({ run = null, selectors = [], auto = false, locale = null }) {
   const pii = run?.meta?.pii || null
@@ -431,7 +596,7 @@ export function maskSpec ({ run = null, selectors = [], auto = false, locale = n
     selectors: [...new Set(selectors)],
     auto: !!(auto || pii),
     mode: pii?.mode || 'redact',
-    salt: run?.meta?.id || '',
+    salt: piiSalt(run?.meta),
     label: maskLabel(locale),
     allow: pii?.allow || []
   }
@@ -445,23 +610,55 @@ export function scenarioMasks (scenario) {
   return { selectors: [...new Set(all.flatMap((m) => m.selectors))], auto: all.some((m) => m.auto) }
 }
 
-// --- the values masked in this process ---------------------------------------------------------------------------
+// --- the values masked in this run ---------------------------------------------------------------------------------
 
 const remembered = new Map()
+const kindsOf = new Map()
+const loaded = new Set()
 let pattern = null
 
-/** Remembers masked values ([original, replacement]) so every later output of the run replaces them too. */
+const digitsOf = (s) => String(s).replace(/\D/g, '')
+const NUMERIC = /^[\d\s.,:/+%-]+$/
+/**
+ * Whether a masked value is replaced everywhere else: values of a detected kind, other text from 6 characters on,
+ * numbers only from 6 digits on (2024, 100 or Praha are not worth replacing across pages and markup).
+ */
+function worthRemembering (v, kind) {
+  if (v.length < 3) return false
+  if (NUMERIC.test(v) && digitsOf(v).length < 6) return false
+  if (!kind || kind === 'text' || kind === 'known' || kind === 'mask') return v.length >= 6
+  return true
+}
+
+/** Remembers masked values ([original, replacement, kind?]) so every later output of the run replaces them too. */
 export function rememberPii (pairs) {
-  for (const [value, repl] of pairs || []) {
+  for (const [value, repl, kind] of pairs || []) {
     const v = String(value || '').trim()
-    if (v.length >= 3 && !remembered.has(v)) { remembered.set(v, String(repl)); pattern = null }
+    if (worthRemembering(v, kind) && !remembered.has(v)) { remembered.set(v, String(repl)); kindsOf.set(v, kind || 'text'); pattern = null }
   }
 }
 
 /** The values remembered so far, as [[original, replacement]] (for the page and the overlay). */
 export const knownPii = () => [...remembered]
 
-export const _forgetPii = () => { remembered.clear(); pattern = null } // tests
+export const _forgetPii = () => { remembered.clear(); kindsOf.clear(); loaded.clear(); pattern = null } // tests
+
+// The values travel to the next `kaloko` process of the run in the run folder. The file stays on this computer:
+// share uploads only the files the manifest names.
+export const KNOWN_FILE = '.pii-known.json'
+
+/** Reads the values an earlier process of this run masked (once per run and process). */
+export async function loadKnownPii (dir) {
+  if (!dir || loaded.has(dir)) return
+  loaded.add(dir)
+  try { rememberPii(JSON.parse(await readFile(join(dir, KNOWN_FILE), 'utf8'))) } catch {}
+}
+
+/** Keeps the values masked so far for the next process of this run. */
+export async function saveKnownPii (dir) {
+  if (!dir || !remembered.size) return
+  await writeFile(join(dir, KNOWN_FILE), JSON.stringify([...remembered].map(([v, r]) => [v, r, kindsOf.get(v)])), { mode: 0o600 }).catch(() => {})
+}
 
 /** Replaces every remembered value (and its URL-encoded form) where it stands as a whole word. */
 export function redactPii (text) {
@@ -472,39 +669,68 @@ export function redactPii (text) {
     const keys = [...forms.keys()].sort((a, b) => b.length - a.length).map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
     pattern = { re: new RegExp(`(?<![\\p{L}\\p{N}])(?:${keys.join('|')})(?![\\p{L}\\p{N}])`, 'gu'), forms }
   }
-  return text.replace(pattern.re, (m) => pattern.forms.get(m) ?? m)
+  return text.replace(pattern.re, (m, at, all) => {
+    // a number in markup stays: a colour (#123456), a percentage
+    if (NUMERIC.test(m) && (all[at - 1] === '#' || all[at + m.length] === '%')) return m
+    return pattern.forms.get(m) ?? m
+  })
 }
 
+const takenNow = () => new Set([...remembered.keys(), ...remembered.values()])
+
 /** A text from outside the page (trace, console, mail headers): remembered values, then detection when it is on. */
 export function scrubText (text, spec) {
   let out = redactPii(text)
   if (typeof out !== 'string' || !spec?.auto) return out
   const hits = kit.find(out, { allow: spec.allow })
+  const taken = takenNow()
   for (const r of hits.reverse()) {
-    const repl = kit.replacement(r.kind, r.value, spec)
-    rememberPii([[r.value, repl]])
+    const real = r.plain ?? r.value
+    let repl = remembered.get(real)
+    if (repl == null) { taken.add(real); repl = kit.replacement(r.kind, real, spec, taken); taken.add(repl) }
+    rememberPii([[real, repl, r.kind], ...(r.plain ? [[r.value, repl, r.kind]] : [])])
     out = out.slice(0, r.start) + repl + out.slice(r.end)
   }
   return out
 }
 
-/** Deep copy with every string scrubbed (scrubText). */
-export function scrubDeep (value, spec) {
+/** Deep copy with every string scrubbed (scrubText); keys in `skip` are copied as they are. */
+export function scrubDeep (value, spec, skip = null) {
   if (typeof value === 'string') return scrubText(value, spec)
-  if (Array.isArray(value)) return value.map((v) => scrubDeep(v, spec))
-  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrubDeep(v, spec)]))
+  if (Array.isArray(value)) return value.map((v) => scrubDeep(v, spec, skip))
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, skip?.has(k) ? v : scrubDeep(v, spec, skip)]))
   return value
 }
 
+/** Keys of a capture record that hold no page text (paths, hashes, coordinates). */
+export const RECORD_PLAIN_KEYS = new Set(['schema', 'files', 'criteria_hash', 'captured_at', 'boxes', 'rects', 'ignore', 'unstable', 'capture', 'pii', 'node', 'locale', 'viewport', 'view'])
+
+/**
+ * The stored HTML of a masked page: attributes masked in the page only as values (maskInPage's `attrs`: data-*,
+ * content, links) replaced, as the browser serialises them.
+ */
+export function maskHtml (html, attrs = []) {
+  if (typeof html !== 'string' || !attrs?.length) return html
+  const esc = (s, lt) => { let v = s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/ /g, '&nbsp;'); if (lt) v = v.replace(/</g, '&lt;').replace(/>/g, '&gt;'); return v }
+  let out = html
+  for (const [from, to] of [...attrs].sort((a, b) => b[0].length - a[0].length)) {
+    for (const lt of [false, true]) out = out.split(`="${esc(from, lt)}"`).join(`="${esc(to, lt)}"`)
+  }
+  return out
+}
+
 /** The e-mail headers of a captured message with recipients replaced (To and Cc are always personal data). */
 export function maskMailHeaders (mail, spec) {
   if (!mail || !spec?.active) return mail
+  const taken = takenNow()
+  const stand = (kind, v) => { const had = remembered.get(v); if (had != null) return had; taken.add(v); const r = kit.replacement(kind, v, spec, taken); taken.add(r); return r }
   const one = (addr) => {
     const a = String(addr || '').trim()
     if (!a) return a
     const email = a.match(/<([^>]+)>/)?.[1] || a
-    const repl = kit.replacement('email', email, spec)
-    rememberPii([[email, repl], ...(a !== email ? [[a.replace(/<[^>]+>/, '').trim().replace(/^"|"$/g, ''), kit.replacement('name', a.replace(/<[^>]+>/, '').trim(), spec)]] : [])])
+    const repl = stand('email', email)
+    const name = a !== email ? a.replace(/<[^>]+>/, '').trim().replace(/^"|"$/g, '') : ''
+    rememberPii([[email, repl, 'email'], ...(name ? [[name, stand('name', name), 'name']] : [])])
     return repl
   }
   const list = (v) => String(v || '').split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map(one).filter(Boolean).join(', ')
@@ -514,17 +740,29 @@ export function maskMailHeaders (mail, spec) {
 /** Page argument for maskInPage / maskPainter: the kit travels as source with the call. */
 export const inPage = (fn, args) => `(${fn})(${JSON.stringify(args)}, (${piiKit})())`
 
-/** Installs (or extends) the overlay on a page and on its next documents; resolves false where it cannot. */
+/**
+ * Installs (or extends) the overlay on a page and on its next documents; resolves false where it cannot. An init
+ * script cannot be changed, so a new one is added whenever the values to cover have grown: a later document starts
+ * with everything masked so far.
+ */
 export async function paintMasks (page, spec) {
   if (!spec?.active) return false
   const args = { selectors: spec.selectors, auto: spec.auto, allow: spec.allow, known: knownPii() }
   try {
-    if (!PAINTED.has(page)) { PAINTED.add(page); await page.addInitScript(inPage(maskPainter, args)) }
-    await page.evaluate(inPage(maskPainter, args))
+    const script = inPage(maskPainter, args)
+    SPECS.set(page, spec)
+    if (SCRIPTS.get(page) !== script) { await page.addInitScript(script); SCRIPTS.set(page, script) }
+    await page.evaluate(script)
     return true
   } catch { return false }
 }
-const PAINTED = new WeakSet()
+const SCRIPTS = new WeakMap()
+const SPECS = new WeakMap()
+
+/** After a capture: an overlay drawn on the page learns the values masked since (nothing when none is drawn). */
+export async function updateMasks (page) {
+  if (SPECS.has(page)) await paintMasks(page, SPECS.get(page))
+}
 
 // --- the guard before upload ---------------------------------------------------------------------------------------
 
@@ -551,43 +789,122 @@ function elementAt (html, at) {
   return `<${m[1].toLowerCase()}${id ? `#${id}` : ''}${cls ? `.${cls}` : ''}>`
 }
 
-/** Personal data in one text: [{ kind, value, where }]. */
+// sample addresses of forms and docs (you@company.com): never anyone's
+const SAMPLE = /^(you|your[._-]?(name|email|mail)?|name|user(name)?|e-?mail|jmeno|jmeno\.prijmeni|vas[._-]?email|vase[._-]?jmeno|john[._-]?doe|jane[._-]?doe)@|@(your)?(company|domain)\.(com|cz)$|@(vase|moje)firma\.cz$/i
+// text in a placeholder (an attribute in evidence, a key in JSON) is a hint, not data
+const HINT_BEFORE = /placeholder\s*[=:]\s*["'“\\]*[^"'\n]{0,80}$/i
+// HTML values that never hold personal data: SVG geometry, styles, placeholders, responsive image lists
+const GEOMETRY = /\s(d|points|viewBox|transform|x|y|x1|x2|y1|y2|cx|cy|r|rx|ry|dx|dy|width|height|offset|stroke-dasharray|stroke-dashoffset|stroke-width|style|placeholder|srcset|sizes|integrity|nonce)\s*=\s*("[^"]*"|'[^']*')/gi
+/** HTML for the guard: values that are never personal data blanked (offsets stay, so elements are still named). */
+function blankHtml (html) {
+  return html
+    .replace(GEOMETRY, (m, name, val) => m.slice(0, m.length - val.length) + val[0] + ' '.repeat(val.length - 2) + val.at(-1))
+    .replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (m, a, b, c) => a + ' '.repeat(b.length) + c)
+}
+
+/** Personal data in one text: [{ kind, value, plain?, where }]. */
 export function scanText (text, { allow = [], where = null } = {}) {
-  return kit.find(String(text || ''), { kinds: GUARD_KINDS, allow }).map((r) => ({ kind: r.kind, value: r.value, where: typeof where === 'function' ? where(r.start) : where }))
+  const s = String(text || '')
+  return kit.find(s, { kinds: GUARD_KINDS, allow })
+    .filter((r) => !HINT_BEFORE.test(s.slice(Math.max(0, r.start - 100), r.start)))
+    .map((r) => ({ kind: r.kind, value: r.value, ...(r.plain ? { plain: r.plain } : {}), where: typeof where === 'function' ? where(r.start) : where }))
 }
 
+const PLAIN_KEYS = new Set(['files', 'criteria_hash', 'boxes', 'rects', 'ignore', 'unstable'])
 /** Personal data in a JSON value: hits with the field path. */
 export function scanJson (value, { allow = [], path = '' } = {}) {
   if (typeof value === 'string') return scanText(value, { allow, where: path || 'value' })
   if (Array.isArray(value)) return value.flatMap((v, i) => scanJson(v, { allow, path: `${path}[${i}]` }))
-  if (value && typeof value === 'object') return Object.entries(value).flatMap(([k, v]) => (k === 'files' || k === 'criteria_hash' ? [] : scanJson(v, { allow, path: path ? `${path}.${k}` : k })))
+  if (value && typeof value === 'object') return Object.entries(value).flatMap(([k, v]) => (PLAIN_KEYS.has(k) ? [] : scanJson(v, { allow, path: path ? `${path}.${k}` : k })))
   return []
 }
 
+/** A contact as compared: an e-mail in lower case, a phone number as its digits without 00. */
+const contactKey = (v) => { const s = String(v || '').trim().replace(/^(mailto|tel):/i, ''); return s.includes('@') ? s.toLowerCase() : digitsOf(s).replace(/^00/, '') }
+const ORG = /Organi[sz]ation|Corporation|Business|Store|ContactPoint|WebSite|WebPage|Brand|Place|Restaurant|Hotel|NGO|School|College|University|Library|Museum|Shop/i
+const PEOPLE = /^(employees?|founders?|members?|authors?|customers?|persons?|people|contactPersons?|creators?|editors?|reviews?)$/i
+/** The e-mails and phone numbers an organisation publishes about itself in JSON-LD (Organization, ContactPoint). */
+function ldContacts (value, out, org = false) {
+  if (Array.isArray(value)) { for (const v of value) ldContacts(v, out, org); return }
+  if (!value || typeof value !== 'object') return
+  const types = [].concat(value['@type'] || []).map(String)
+  const isOrg = types.length ? types.some((t) => ORG.test(t)) && !types.some((t) => /Person|Patient/i.test(t)) : org
+  if (isOrg) for (const k of ['email', 'telephone', 'faxNumber']) for (const x of [].concat(value[k] || [])) if (typeof x === 'string') out.add(contactKey(x))
+  for (const [k, v] of Object.entries(value)) if (v && typeof v === 'object') ldContacts(v, out, isOrg && !PEOPLE.test(k))
+}
+
+/** [start, end] ranges of the page footer (<footer>, role=contentinfo) in an HTML text. */
+function footerRanges (html) {
+  const out = []
+  for (const m of html.matchAll(/<(footer)\b[^>]*>|<([a-z][\w-]*)\b[^>]*\brole=["']?contentinfo\b[^>]*>/gi)) {
+    const tag = (m[1] || m[2]).toLowerCase()
+    const re = new RegExp(`<${tag}\\b|</${tag}\\s*>`, 'gi')
+    re.lastIndex = m.index + m[0].length
+    let depth = 1; let end = html.length
+    for (let t = re.exec(html); t; t = re.exec(html)) { if (t[0][1] === '/') { if (!--depth) { end = t.index; break } } else depth++ }
+    out.push([m.index, end])
+  }
+  return out
+}
+
+/** The registrable part of a host name (shop.acme.cz → acme.cz, www.acme.co.uk → acme.co.uk). */
+function baseDomain (host) {
+  const parts = String(host || '').toLowerCase().replace(/\.$/, '').split('.')
+  const n = parts.length >= 3 && /^(co|com|org|net|gov|ac|edu)$/.test(parts.at(-2)) ? 3 : 2
+  return parts.slice(-n).join('.')
+}
+
+const TEXT_FILES = /\.(json|html?|xml|svg|txt|eml|csv|md|log)$/i
+
 /**
  * What `kaloko share` would upload, scanned for unmasked e-mails, phone numbers, birth numbers and IBANs:
- * the manifest's steps (captures, mail headers, console lines, evidence) and the files that travel with it:
+ * the manifest's steps (captures, mail headers, console lines, evidence) and the text files that travel with it:
  * [{ kind, value, node, locale, viewport, file, where }]. Images and recordings are not read (masks cover them).
+ * The site's own contacts are not personal data (site.contacts, on unless pii.site_contacts: false): e-mails on the
+ * domain of the environment, e-mails and phone numbers in the page footer, and those of an Organization or
+ * ContactPoint in JSON-LD. Sample addresses (you@company.com) and placeholder text never count.
  */
-export async function piiFindings ({ dir, files, allow = [], manifest = null }) {
-  const out = []
+export async function piiFindings ({ dir, files, allow = [], manifest = null, site = null }) {
+  const hits = []
+  const contacts = new Set()
+  const siteContacts = site?.contacts !== false
+  let own = null
+  try { own = site?.url ? baseDomain(new URL(site.url).hostname) : null } catch {}
   for (const n of manifest?.nodes || []) {
     const { captures, ...rest } = n
-    for (const h of scanJson(rest, { allow })) out.push({ ...h, node: n.id, file: 'run.json' })
+    for (const h of scanJson(rest, { allow })) hits.push({ ...h, node: n.id, file: 'run.json' })
     for (const [locale, byVp] of Object.entries(captures || {})) {
-      for (const [viewport, c] of Object.entries(byVp || {})) for (const h of scanJson(c, { allow })) out.push({ ...h, node: n.id, locale, viewport, file: 'run.json' })
+      for (const [viewport, c] of Object.entries(byVp || {})) for (const h of scanJson(c, { allow })) hits.push({ ...h, node: n.id, locale, viewport, file: 'run.json' })
     }
   }
+  if (manifest) ldContacts(manifest, contacts)
   for (const file of files) {
-    if (!/\.(json|html?)$/i.test(file)) continue
+    if (!TEXT_FILES.test(file)) continue
     let text
     try { text = await readFile(join(dir, file), 'utf8') } catch { continue }
     const at = stepOfPath(file)
-    let hits
-    if (/\.json$/i.test(file)) { let data; try { data = JSON.parse(text) } catch { data = text } hits = scanJson(data, { allow }) } else hits = scanText(text, { allow, where: (i) => elementAt(text, i) })
-    for (const h of hits) out.push({ ...h, ...at, file })
+    if (/\.json$/i.test(file)) {
+      let data
+      try { data = JSON.parse(text) } catch { data = text }
+      ldContacts(data, contacts)
+      for (const h of scanJson(data, { allow })) hits.push({ ...h, ...at, file })
+    } else if (/\.(html?|xml|svg)$/i.test(file)) {
+      for (const m of text.matchAll(/<script\b[^>]*type=["']?application\/ld\+json[^>]*>([\s\S]*?)<\/script>/gi)) { try { ldContacts(JSON.parse(m[1]), contacts) } catch {} }
+      const footers = footerRanges(text)
+      for (const h of scanText(blankHtml(text), { allow, where: (i) => ({ i, el: elementAt(text, i) }) })) {
+        if (siteContacts && footers.some(([s, e]) => h.where.i >= s && h.where.i < e)) { contacts.add(contactKey(h.plain ?? h.value)); continue }
+        hits.push({ ...h, where: h.where.el, ...at, file })
+      }
+    } else for (const h of scanText(text, { allow, where: 'text' })) hits.push({ ...h, ...at, file })
   }
-  return out
+  return hits.filter((h) => {
+    const v = String(h.plain ?? h.value).trim()
+    if (SAMPLE.test(v)) return false
+    if (!siteContacts) return true
+    if (contacts.has(contactKey(v))) return false
+    if (own && h.kind === 'email' && baseDomain(v.split('@')[1]) === own) return false
+    return true
+  })
 }
 
 /** The values a project says are not personal data, plus the run's own test mailboxes ({run} = any run). */
@@ -596,11 +913,11 @@ export function guardAllow ({ config = {}, env = {}, scenario = {}, run = null }
   return [...(config.pii?.allow || []), ...(run?.meta?.pii?.allow || []), ...boxes.filter(Boolean).map((b) => String(b).replace('{run}', '*'))].map(String)
 }
 
-/** The refusal (or the warning with --allow-pii) for findings: one line per hit, step and element first. */
+/** The refusal (or the warning) for findings: one line per hit, step and element first. */
 export function formatFindings (findings, max = 12) {
   const lines = findings.slice(0, max).map((f) => {
     const where = f.node ? `${f.node}${f.locale ? ` (${f.locale}, ${f.viewport})` : ''}` : f.file
-    return `  ${where}  ${f.where || ''}  ${f.kind.replace('_', ' ')} ${hint(f.value)}`.replace(/ {3,}/g, '  ')
+    return `  ${where}  ${f.where || ''}  ${f.kind.replace('_', ' ')} ${hint(f.plain ?? f.value)}`.replace(/ {3,}/g, '  ')
   })
   if (findings.length > max) lines.push(`  … ${findings.length - max} more`)
   return lines.join('\n')