@namemasker/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Bell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @namemasker/core
+
+The engine behind [NameMasker](https://namemasker.com): local PII detection,
+masking, and restore for student documents. Plain TypeScript, zero runtime
+dependencies, no network access of any kind. Runs in the browser and in Node.
+
+**The design stance:** the tool stages, the professional approves. Detection
+is deliberately layered and each layer is exported on its own, so callers
+decide what to trust and what to review.
+
+## Install
+
+```sh
+npm install @namemasker/core
+```
+
+## Quick start
+
+```ts
+import {
+  scanDocument,
+  createStudentMap,
+  addToMap,
+  applyMap,
+  unmaskText,
+} from '@namemasker/core';
+
+const text = 'It is my pleasure to recommend Maya Chen of Lakeside Prep.';
+
+// 1. Scan: returns flags (direct / name / contextual), each with a reason.
+const { flags, accumulation } = scanDocument(text);
+
+// 2. The caller (a human, in our UI) approves flags into a map.
+const map = createStudentMap();
+for (const flag of flags) {
+  addToMap(map, { text: flag.text, placeholderType: flag.placeholderType });
+}
+
+// 3. Mask: every occurrence, longest match first.
+const masked = applyMap(text, map);
+// -> 'It is my pleasure to recommend Student A of School 1.'
+
+// 4. Unmask AI output: placeholders restore to canonical names only.
+unmaskText('In short, Student A excels.', map.mapping);
+// -> 'In short, Maya Chen excels.'
+```
+
+## Detection layers
+
+1. **Direct** (`detectDirect`) — deterministic patterns: emails, phones,
+   SSN/ID numbers, dates, street addresses. No ML.
+2. **Names** — bring your own: pass `nameFlags` from any NER (the NameMasker
+   site runs a vendored distilbert-NER in-browser), or fall back to the
+   built-in, honestly-labeled naive capitalized-pair pattern
+   (`detectNamesNaive`).
+3. **Contextual** (`detectContextual`) — weighted heuristics with proximity
+   scoring for passages that may identify a student without naming them
+   (uniqueness claims, rare activities, school patterns, geographic
+   narrowing). These are flags for human judgment; the engine never masks
+   them on its own.
+4. **Accumulation** — six or more contextual flags in one document raises a
+   document-level warning that the combination may identify even after
+   masking.
+
+`scanDocument(text, options)` composes all layers. `options.knownTerms`
+stages caller-supplied terms (a watchlist, or names from a student record)
+with top priority; `options.nameFlags` replaces the naive name layer.
+
+## The map (format v2)
+
+A `StudentMap` is `{ mapping, aliases, watchlist }`:
+
+- `mapping` — canonical real → placeholder (`Student A`, `School 1`), unique
+  placeholders; the only section Unmask reads, so restoration is
+  deterministic.
+- `aliases` — alternate spellings that mask to an existing placeholder
+  (bare "Maya" → `Student A`) but never win at unmask.
+- `watchlist` — terms to always stage on future scans.
+
+`parseStudentMap` accepts v2 files and lifts v1 flat `{real: placeholder}`
+files forever. `serializeStudentMap` writes v2.
+
+## Honest scope
+
+This library does not guarantee anonymity, and neither does anything else.
+It catches what software can catch, flags what software can only suspect,
+and is built to keep a human in the approval seat. See the
+[threat model](https://namemasker.com/security.html).
+
+MIT © Chris Bell

package/dist/contextual.d.ts

@@ -0,0 +1,10 @@
+import type { ContextSignal, Flag, ScanOptions } from './types.js';
+/** Gather raw rule hits, deduplicating overlapping hits of the same category. */
+export declare function collectSignals(text: string): ContextSignal[];
+export interface ContextualResult {
+    /** All raw signals, including those below the flag threshold. */
+    signals: ContextSignal[];
+    flags: Flag[];
+}
+/** Score signals against their neighbors and return flags for those crossing the threshold. */
+export declare function detectContextual(text: string, options?: ScanOptions): ContextualResult;

package/dist/contextual.js

@@ -0,0 +1,246 @@
+import { DEFAULT_OPTIONS } from './types.js';
+const RULES = [
+    {
+        category: 'uniqueness-claim',
+        weight: 2,
+        reason: 'Uniqueness claim (first/only/sole + a role) can identify a student on its own',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:first|only|sole)\b(?:\s+\w+){0,4}?\s+(?:captain|co-captain|president|chair|chairperson|founder|editor|student|member|winner|recipient|player|performer|graduate|girl|boy|woman|man|person)\b/gi,
+        ],
+    },
+    {
+        category: 'rare-role',
+        weight: 3,
+        reason: 'Rare role held by very few students in any school',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:valedictorian|salutatorian|concertmaster|concertmistress|drum\s+major|student\s+body\s+president)\b/gi,
+        ],
+    },
+    {
+        category: 'award-reference',
+        weight: 2,
+        reason: 'Award reference narrows the field of possible students',
+        placeholderType: 'other',
+        patterns: [
+            /\baward[\s-]winning\b/gi,
+            /\b(?:won|received|earned)\s+(?:an?|the|several|multiple)\s+(?:\w+\s+){0,3}?awards?\b/gi,
+            /\brecipient\s+of\b/gi,
+        ],
+    },
+    {
+        category: 'named-award',
+        weight: 3,
+        reason: 'Named award is searchable and may identify the student directly',
+        placeholderType: 'other',
+        patterns: [/\b(?:[A-Z][\w'&.]*\s+){1,4}(?:Award|Prize|Scholarship|Fellowship|Medal|Cup|Trophy)\b/g],
+    },
+    {
+        category: 'rare-instrument',
+        weight: 2,
+        reason: 'Rare instrument or soloist role narrows the field sharply',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:tuba|oboe|bassoon|harp|french\s+horn|euphonium|piccolo|marimba|harpsichord|bagpipes)(?:\s+soloist)?\b/gi,
+            /\bsoloist\b/gi,
+        ],
+    },
+    {
+        category: 'named-ensemble',
+        weight: 3,
+        reason: 'Named ensemble ties the student to a specific school or region',
+        placeholderType: 'org',
+        patterns: [
+            /\b(?:[A-Z][\w']+\s+){1,4}(?:Band|Orchestra|Choir|Chorale|Ensemble|Symphony|Philharmonic|Quartet|Quintet)\b/g,
+        ],
+    },
+    {
+        category: 'school-name',
+        weight: 3,
+        reason: 'School-name pattern (capitalized words + High/Prep/Academy)',
+        placeholderType: 'school',
+        patterns: [
+            /\b(?:[A-Z][\w'.]+\s+){1,3}(?:High(?:\s+School)?|Prep(?:aratory)?(?:\s+School)?|Academy|Middle\s+School|Elementary(?:\s+School)?)\b/g,
+        ],
+    },
+    {
+        category: 'narrow-school-type',
+        weight: 2,
+        reason: 'Narrow school type sharply limits which schools this could be',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:Quaker|Jesuit|Montessori|Waldorf|charter|boarding|magnet|parochial|all-girls|all-boys|single-sex)\s+(?:\w+\s+){0,2}?school\b/gi,
+        ],
+    },
+    {
+        category: 'school-size',
+        weight: 1,
+        reason: 'School-size mention narrows the school',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:small|tiny|little)\s+(?:\w+\s+){0,2}?school\b/gi,
+            /\bschool\s+of\s+(?:about\s+|around\s+|only\s+)?\d+\b/gi,
+            /\bclass\s+of\s+(?:about\s+|around\s+|only\s+)?\d+\s+students\b/gi,
+        ],
+    },
+    {
+        category: 'geographic-narrowing',
+        weight: 2,
+        reason: 'Geographic narrowing (outside/near + a place) localizes the student',
+        placeholderType: 'place',
+        patterns: [
+            /\b(?:just\s+outside|on\s+the\s+outskirts\s+of|outside|near)\s+(?:of\s+)?[A-Z][\w']+(?:\s+[A-Z][\w']+){0,2}/g,
+        ],
+    },
+    {
+        category: 'specific-achievement',
+        weight: 2,
+        reason: 'Specific achievement (state/national title) is searchable',
+        placeholderType: 'other',
+        patterns: [
+            /\bstate\s+(?:\w+\s+){0,3}?(?:title|champion(?:ship)?s?|finalist)\b/gi,
+            /\bnational\s+(?:\w+\s+){0,2}?(?:champion|title|finalist)\b/gi,
+            /\ball-state\b/gi,
+            /\ball-american\b/gi,
+        ],
+    },
+    {
+        category: 'uncommon-sport',
+        weight: 2,
+        reason: 'Less common sport narrows the field of students',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:wrestling|fencing|alpine\s+skiing|nordic\s+skiing|water\s+polo|squash|rowing|crew\s+team|rugby|badminton|archery|equestrian|diving|sailing|curling|ultimate\s+frisbee|gymnastics)\b/gi,
+        ],
+    },
+    {
+        category: 'leadership-role',
+        weight: 1,
+        reason: 'Leadership role; identifying only when stacked with other signals',
+        placeholderType: 'other',
+        patterns: [
+            /\b(?:captain|co-captain|president|vice\s+president|treasurer|secretary|editor-in-chief|section\s+leader|founder)\b/gi,
+        ],
+    },
+    {
+        category: 'anchoring-year',
+        weight: 1,
+        reason: 'Anchoring year; identifying only when stacked with other signals',
+        placeholderType: 'other',
+        patterns: [/\b(?:19|20)\d{2}\b/g, /\b(?:freshman|sophomore|junior|senior)\s+year\b/gi],
+    },
+];
+const LIST_CONTINUATION = {
+    category: 'school-list-continuation',
+    weight: 2,
+    reason: 'Listed alongside a detected school name; likely another school (list continuation)',
+    placeholderType: 'school',
+};
+const REASON_BY_CATEGORY = new Map([
+    ...RULES.map((r) => [r.category, r.reason]),
+    [LIST_CONTINUATION.category, LIST_CONTINUATION.reason],
+]);
+const PLACEHOLDER_BY_CATEGORY = new Map([
+    ...RULES.map((r) => [r.category, r.placeholderType]),
+    [LIST_CONTINUATION.category, LIST_CONTINUATION.placeholderType],
+]);
+function collect(re, text) {
+    const out = [];
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        out.push({ start: m.index, end: m.index + m[0].length, text: m[0] });
+        if (m.index === re.lastIndex)
+            re.lastIndex++;
+    }
+    return out;
+}
+function spansOverlap(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+/**
+ * The Fairview rule: after a school-name match, capitalized tokens that
+ * continue the same comma/and list are probable schools too. The chain breaks
+ * at the first lowercase word, so it cannot wander into unrelated text.
+ */
+function findListContinuations(text, schoolSpans) {
+    const out = [];
+    const CHAIN = /^(?:\s*,\s*(?:and\s+|or\s+)?|\s+(?:and|or)\s+)([A-Z][\w']+(?:\s+[A-Z][\w']+)?)/;
+    for (const school of schoolSpans) {
+        let pos = school.end;
+        for (;;) {
+            const m = CHAIN.exec(text.slice(pos));
+            if (m === null || m[1] === undefined)
+                break;
+            const start = pos + m[0].length - m[1].length;
+            const span = { start, end: start + m[1].length, text: m[1] };
+            pos = span.end;
+            // Skip anything the school-name rule already caught.
+            if (!schoolSpans.some((s) => spansOverlap(s, span)))
+                out.push(span);
+        }
+    }
+    return out;
+}
+/** Gather raw rule hits, deduplicating overlapping hits of the same category. */
+export function collectSignals(text) {
+    const signals = [];
+    const push = (category, weight, span) => {
+        if (signals.some((s) => s.category === category && spansOverlap(s, span)))
+            return;
+        signals.push({ category, weight, start: span.start, end: span.end, text: span.text });
+    };
+    let schoolSpans = [];
+    for (const rule of RULES) {
+        const spans = rule.patterns.flatMap((p) => collect(p, text));
+        if (rule.category === 'school-name')
+            schoolSpans = spans;
+        for (const span of spans)
+            push(rule.category, rule.weight, span);
+    }
+    for (const span of findListContinuations(text, schoolSpans)) {
+        push(LIST_CONTINUATION.category, LIST_CONTINUATION.weight, span);
+    }
+    return signals.sort((a, b) => a.start - b.start);
+}
+function gap(a, b) {
+    if (spansOverlap(a, b))
+        return 0;
+    return a.start >= b.end ? a.start - b.end : b.start - a.end;
+}
+/** Score signals against their neighbors and return flags for those crossing the threshold. */
+export function detectContextual(text, options = {}) {
+    const { flagThreshold, proximityWindow } = { ...DEFAULT_OPTIONS, ...options };
+    const signals = collectSignals(text);
+    const flags = [];
+    for (const signal of signals) {
+        let score = signal.weight;
+        const supporters = [];
+        for (const other of signals) {
+            if (other === signal)
+                continue;
+            const d = gap(signal, other);
+            if (d > proximityWindow)
+                continue;
+            score += other.weight * (1 - d / proximityWindow);
+            supporters.push(other.category);
+        }
+        if (score < flagThreshold)
+            continue;
+        const support = supporters.length > 0
+            ? `; stacked with ${supporters.length} nearby signal${supporters.length === 1 ? '' : 's'}`
+            : '';
+        flags.push({
+            kind: 'contextual',
+            category: signal.category,
+            start: signal.start,
+            end: signal.end,
+            text: signal.text,
+            reason: `${REASON_BY_CATEGORY.get(signal.category) ?? signal.category} (score ${score.toFixed(1)}, threshold ${flagThreshold}${support})`,
+            placeholderType: PLACEHOLDER_BY_CATEGORY.get(signal.category) ?? 'other',
+            score,
+        });
+    }
+    return { signals, flags };
+}

package/dist/direct.d.ts

@@ -0,0 +1,9 @@
+import type { Flag } from './types.js';
+interface Span {
+    start: number;
+    end: number;
+}
+export declare function overlaps(a: Span, b: Span): boolean;
+/** Detect direct identifiers. Returned flags never overlap each other. */
+export declare function detectDirect(text: string): Flag[];
+export {};

package/dist/direct.js

@@ -0,0 +1,84 @@
+// Order matters: earlier categories win when spans overlap.
+const RULES = [
+    {
+        category: 'email',
+        placeholderType: 'email',
+        reason: 'Email address (deterministic pattern)',
+        patterns: [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g],
+    },
+    {
+        category: 'phone',
+        placeholderType: 'phone',
+        reason: 'Phone number (deterministic pattern)',
+        patterns: [/(?:\+1[\s.-]?)?(?:\(\d{3}\)[\s.-]?|\b\d{3}[\s.-])\d{3}[\s.-]\d{4}\b/g],
+    },
+    {
+        category: 'ssn',
+        placeholderType: 'id',
+        reason: 'SSN-format number (deterministic pattern)',
+        patterns: [/\b\d{3}-\d{2}-\d{4}\b/g],
+    },
+    {
+        category: 'id',
+        placeholderType: 'id',
+        reason: 'Labeled ID number (deterministic pattern)',
+        patterns: [
+            /\b(?:student\s+(?:id|number|no)|id(?:\s+(?:number|no))?|case\s+(?:number|no))\s*[#:.]?\s*\d{4,12}\b/gi,
+        ],
+    },
+    {
+        category: 'date',
+        placeholderType: 'date',
+        reason: 'Date (deterministic pattern)',
+        patterns: [
+            /\b\d{4}-\d{2}-\d{2}\b/g,
+            /\b(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)\.?\s+\d{1,2}(?:st|nd|rd|th)?,?\s+\d{4}\b/gi,
+            /\b\d{1,2}\s+(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}\b/gi,
+            /\b\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b/g,
+        ],
+    },
+    {
+        category: 'address',
+        placeholderType: 'address',
+        reason: 'Street address (deterministic pattern)',
+        patterns: [
+            /\b\d{1,5}\s+(?:[A-Z][\w']+\s+){1,3}(?:Street|St|Avenue|Ave|Road|Rd|Boulevard|Blvd|Lane|Ln|Drive|Dr|Court|Ct|Place|Pl|Way|Terrace|Ter|Circle|Cir)\b\.?/g,
+        ],
+    },
+];
+export function overlaps(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+function collect(re, text) {
+    const out = [];
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        out.push({ start: m.index, end: m.index + m[0].length, text: m[0] });
+        if (m.index === re.lastIndex)
+            re.lastIndex++;
+    }
+    return out;
+}
+/** Detect direct identifiers. Returned flags never overlap each other. */
+export function detectDirect(text) {
+    const flags = [];
+    for (const rule of RULES) {
+        for (const pattern of rule.patterns) {
+            for (const hit of collect(pattern, text)) {
+                if (flags.some((f) => overlaps(f, hit)))
+                    continue;
+                flags.push({
+                    kind: 'direct',
+                    category: rule.category,
+                    start: hit.start,
+                    end: hit.end,
+                    text: hit.text,
+                    reason: rule.reason,
+                    placeholderType: rule.placeholderType,
+                });
+            }
+        }
+    }
+    return flags.sort((a, b) => a.start - b.start);
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @namemasker/core — local PII detection, masking, and restore.
+ *
+ * Everything here runs entirely on the caller's device, browser or Node.
+ * No function in this library performs any network request, ever.
+ *
+ * Detection layers are exported independently; scanDocument composes them.
+ * The tool stages, the professional approves: nothing in this library
+ * auto-redacts a contextual flag or claims a document is "safe."
+ */
+export type { FlagKind, PlaceholderType, Flag, ContextSignal, ScanOptions, AccumulationResult, ScanResult, Mapping, StudentMap, KnownTerm, ApprovedItem, } from './types.js';
+export { DEFAULT_OPTIONS } from './types.js';
+export { detectDirect } from './direct.js';
+export { detectNamesNaive } from './names.js';
+export { detectContextual, collectSignals } from './contextual.js';
+export type { ContextualResult } from './contextual.js';
+export { scanDocument } from './scan.js';
+export { detectKnownTerms } from './scan.js';
+export { nextPlaceholder, maskText, unmaskText, serializeMapping, parseMapping, MAP_FORMAT, createStudentMap, liftV1, addToMap, applyMap, serializeStudentMap, parseStudentMap, } from './mapping.js';
+export type { MaskResult } from './mapping.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @namemasker/core — local PII detection, masking, and restore.
+ *
+ * Everything here runs entirely on the caller's device, browser or Node.
+ * No function in this library performs any network request, ever.
+ *
+ * Detection layers are exported independently; scanDocument composes them.
+ * The tool stages, the professional approves: nothing in this library
+ * auto-redacts a contextual flag or claims a document is "safe."
+ */
+export { DEFAULT_OPTIONS } from './types.js';
+export { detectDirect } from './direct.js';
+export { detectNamesNaive } from './names.js';
+export { detectContextual, collectSignals } from './contextual.js';
+export { scanDocument } from './scan.js';
+export { detectKnownTerms } from './scan.js';
+export { nextPlaceholder, maskText, unmaskText, serializeMapping, parseMapping, MAP_FORMAT, createStudentMap, liftV1, addToMap, applyMap, serializeStudentMap, parseStudentMap, } from './mapping.js';

package/dist/mapping.d.ts

@@ -0,0 +1,41 @@
+import type { ApprovedItem, Mapping, PlaceholderType, StudentMap } from './types.js';
+/** Next unused placeholder in the sequence for a type: Student A/B, School 1/2, ... */
+export declare function nextPlaceholder(type: PlaceholderType, mapping: Mapping): string;
+export interface MaskResult {
+    masked: string;
+    mapping: Mapping;
+}
+/**
+ * Mask a document. Pass order per spec: exact-match replacement from the
+ * loaded mapping first (a loaded mapping beats model misses), then approved
+ * new detections get the next placeholder in their type's sequence, assigned
+ * in detection order (position in the document).
+ */
+export declare function maskText(text: string, approved: ApprovedItem[], existing?: Mapping): MaskResult;
+/** Unmask: the mapping applied in reverse. Pure substitution, nothing else. */
+export declare function unmaskText(text: string, mapping: Mapping): string;
+export declare const MAP_FORMAT = "namemasker-map@2";
+export declare function createStudentMap(): StudentMap;
+/** Lift a v1 flat mapping into the v2 shape. v1 files import forever. */
+export declare function liftV1(mapping: Mapping): StudentMap;
+/**
+ * Add an approved item to the map. If the item is a person whose text is a
+ * word of an already-mapped person (bare "Maya" after "Maya Chen"), it
+ * becomes an alias of that placeholder instead of getting its own.
+ * Mutates the map; returns the placeholder used.
+ */
+export declare function addToMap(map: StudentMap, item: ApprovedItem): string;
+/**
+ * Apply the map to a document: canonical reals and aliases both mask to
+ * their placeholder. `exclude` skips specific reals for this document only
+ * (a dismissed watchlist hit) without touching the map.
+ */
+export declare function applyMap(text: string, map: StudentMap, exclude?: ReadonlySet<string>): string;
+/** Serialize the full v2 map for export as {student}.map.json. */
+export declare function serializeStudentMap(map: StudentMap): string;
+/** Parse an imported map file: v2, or a v1 flat mapping (lifted). */
+export declare function parseStudentMap(json: string): StudentMap;
+/** Serialize for export as {student}.map.json. (v1 shape; superseded by serializeStudentMap.) */
+export declare function serializeMapping(mapping: Mapping): string;
+/** Parse an imported mapping file, validating shape and placeholder uniqueness. */
+export declare function parseMapping(json: string): Mapping;

package/dist/mapping.js

@@ -0,0 +1,217 @@
+/**
+ * Mapping and restore. The mapping is a flat JSON object, real string ->
+ * placeholder. It is the only sensitive artifact the tool creates, it makes
+ * Unmask possible, and it never leaves the user's device.
+ */
+const TYPE_LABEL = {
+    student: 'Student',
+    parent: 'Parent',
+    school: 'School',
+    coach: 'Coach',
+    org: 'Organization',
+    place: 'Place',
+    email: 'Email',
+    phone: 'Phone',
+    id: 'ID',
+    date: 'Date',
+    address: 'Address',
+    other: 'Detail',
+};
+/** 0 -> A, 25 -> Z, 26 -> AA (bijective base 26). Students get letters. */
+function indexToLetters(index) {
+    let n = index + 1;
+    let s = '';
+    while (n > 0) {
+        const r = (n - 1) % 26;
+        s = String.fromCharCode(65 + r) + s;
+        n = Math.floor((n - 1) / 26);
+    }
+    return s;
+}
+/** Next unused placeholder in the sequence for a type: Student A/B, School 1/2, ... */
+export function nextPlaceholder(type, mapping) {
+    const label = TYPE_LABEL[type];
+    const used = new Set(Object.values(mapping));
+    for (let i = 0;; i++) {
+        const candidate = type === 'student' ? `${label} ${indexToLetters(i)}` : `${label} ${i + 1}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Build one alternation regex for exact, whole-token replacement. Longest first. */
+function buildPattern(keys) {
+    const sorted = [...keys].sort((a, b) => b.length - a.length).map(escapeRegExp);
+    return new RegExp(`(?<!\\w)(?:${sorted.join('|')})(?!\\w)`, 'g');
+}
+/**
+ * Mask a document. Pass order per spec: exact-match replacement from the
+ * loaded mapping first (a loaded mapping beats model misses), then approved
+ * new detections get the next placeholder in their type's sequence, assigned
+ * in detection order (position in the document).
+ */
+export function maskText(text, approved, existing = {}) {
+    const mapping = { ...existing };
+    const inOrder = [...approved].sort((a, b) => text.indexOf(a.text) - text.indexOf(b.text));
+    for (const item of inOrder) {
+        if (item.text.length === 0 || mapping[item.text] !== undefined)
+            continue;
+        mapping[item.text] = nextPlaceholder(item.placeholderType, mapping);
+    }
+    const keys = Object.keys(mapping);
+    if (keys.length === 0)
+        return { masked: text, mapping };
+    const masked = text.replace(buildPattern(keys), (m) => mapping[m] ?? m);
+    return { masked, mapping };
+}
+/** Unmask: the mapping applied in reverse. Pure substitution, nothing else. */
+export function unmaskText(text, mapping) {
+    const byPlaceholder = new Map();
+    for (const [real, placeholder] of Object.entries(mapping)) {
+        byPlaceholder.set(placeholder, real);
+    }
+    if (byPlaceholder.size === 0)
+        return text;
+    const pattern = buildPattern([...byPlaceholder.keys()]);
+    return text.replace(pattern, (m) => byPlaceholder.get(m) ?? m);
+}
+// ---------- map format v2 ----------
+export const MAP_FORMAT = 'namemasker-map@2';
+export function createStudentMap() {
+    return { mapping: {}, aliases: {}, watchlist: [] };
+}
+/** Lift a v1 flat mapping into the v2 shape. v1 files import forever. */
+export function liftV1(mapping) {
+    return { mapping: { ...mapping }, aliases: {}, watchlist: [] };
+}
+/**
+ * Add an approved item to the map. If the item is a person whose text is a
+ * word of an already-mapped person (bare "Maya" after "Maya Chen"), it
+ * becomes an alias of that placeholder instead of getting its own.
+ * Mutates the map; returns the placeholder used.
+ */
+export function addToMap(map, item) {
+    const existing = map.mapping[item.text] ?? map.aliases[item.text];
+    if (existing !== undefined)
+        return existing;
+    if (item.placeholderType === 'student') {
+        for (const [real, placeholder] of Object.entries(map.mapping)) {
+            if (placeholder.startsWith('Student ') && real.split(/\s+/).includes(item.text)) {
+                map.aliases[item.text] = placeholder;
+                return placeholder;
+            }
+        }
+    }
+    const placeholder = nextPlaceholder(item.placeholderType, map.mapping);
+    map.mapping[item.text] = placeholder;
+    return placeholder;
+}
+/**
+ * Apply the map to a document: canonical reals and aliases both mask to
+ * their placeholder. `exclude` skips specific reals for this document only
+ * (a dismissed watchlist hit) without touching the map.
+ */
+export function applyMap(text, map, exclude) {
+    const pairs = {};
+    for (const [real, ph] of Object.entries(map.mapping)) {
+        if (!exclude?.has(real))
+            pairs[real] = ph;
+    }
+    for (const [real, ph] of Object.entries(map.aliases)) {
+        if (!exclude?.has(real))
+            pairs[real] = ph;
+    }
+    const keys = Object.keys(pairs);
+    if (keys.length === 0)
+        return text;
+    return text.replace(buildPattern(keys), (m) => pairs[m] ?? m);
+}
+/** Serialize the full v2 map for export as {student}.map.json. */
+export function serializeStudentMap(map) {
+    return `${JSON.stringify({ format: MAP_FORMAT, mapping: map.mapping, aliases: map.aliases, watchlist: map.watchlist }, null, 2)}\n`;
+}
+function validateEntries(obj, what) {
+    for (const [real, ph] of Object.entries(obj)) {
+        if (typeof ph !== 'string' || ph.length === 0 || real.length === 0) {
+            throw new Error(`Map file ${what} must map non-empty strings to non-empty strings.`);
+        }
+    }
+}
+/** Parse an imported map file: v2, or a v1 flat mapping (lifted). */
+export function parseStudentMap(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error('Map file is not valid JSON.');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Map file must be a JSON object.');
+    }
+    const obj = parsed;
+    if (obj['format'] === undefined) {
+        // v1: flat real -> placeholder
+        return liftV1(parseMapping(json));
+    }
+    if (obj['format'] !== MAP_FORMAT) {
+        throw new Error(`Unrecognized map format "${String(obj['format'])}".`);
+    }
+    const mapping = (obj['mapping'] ?? {});
+    const aliases = (obj['aliases'] ?? {});
+    const watchlist = obj['watchlist'] ?? [];
+    if (typeof mapping !== 'object' || mapping === null || Array.isArray(mapping)) {
+        throw new Error('Map file "mapping" must be an object.');
+    }
+    if (typeof aliases !== 'object' || aliases === null || Array.isArray(aliases)) {
+        throw new Error('Map file "aliases" must be an object.');
+    }
+    if (!Array.isArray(watchlist) || watchlist.some((w) => typeof w !== 'string' || w.length === 0)) {
+        throw new Error('Map file "watchlist" must be an array of non-empty strings.');
+    }
+    validateEntries(mapping, '"mapping"');
+    validateEntries(aliases, '"aliases"');
+    const seen = new Set();
+    for (const ph of Object.values(mapping)) {
+        if (seen.has(ph))
+            throw new Error(`Map file reuses the placeholder "${ph}"; Unmask would be ambiguous.`);
+        seen.add(ph);
+    }
+    for (const [real, ph] of Object.entries(aliases)) {
+        if (!seen.has(ph)) {
+            throw new Error(`Alias "${real}" points at "${ph}", which is not in the mapping.`);
+        }
+    }
+    return { mapping, aliases, watchlist: [...new Set(watchlist)] };
+}
+/** Serialize for export as {student}.map.json. (v1 shape; superseded by serializeStudentMap.) */
+export function serializeMapping(mapping) {
+    return `${JSON.stringify(mapping, null, 2)}\n`;
+}
+/** Parse an imported mapping file, validating shape and placeholder uniqueness. */
+export function parseMapping(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error('Mapping file is not valid JSON.');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Mapping file must be a JSON object of real string -> placeholder.');
+    }
+    const entries = Object.entries(parsed);
+    const seen = new Set();
+    for (const [real, placeholder] of entries) {
+        if (typeof placeholder !== 'string' || placeholder.length === 0 || real.length === 0) {
+            throw new Error('Mapping file must map non-empty strings to non-empty strings.');
+        }
+        if (seen.has(placeholder)) {
+            throw new Error(`Mapping file reuses the placeholder "${placeholder}"; Unmask would be ambiguous.`);
+        }
+        seen.add(placeholder);
+    }
+    return parsed;
+}

package/dist/names.d.ts

@@ -0,0 +1,3 @@
+import type { Flag } from './types.js';
+/** Detect probable personal names with the naive capitalized-pair pattern. */
+export declare function detectNamesNaive(text: string): Flag[];

package/dist/names.js

@@ -0,0 +1,52 @@
+/**
+ * Layer 2, Phase 2 form: a deliberately naive capitalized-pair pattern.
+ * This is a stopgap with known false positives and misses; Phase 3 replaces
+ * it with a small on-device NER model. The reason string on every flag says
+ * so, honestly, and the UI surfaces that reason.
+ */
+const NAIVE_REASON = 'Looks like a personal name: two capitalized words (naive pattern; an on-device model replaces this in a later phase)';
+// Second words that indicate an institution or thing, not a person.
+// Schools and ensembles are handled by the contextual layer instead.
+const SECOND_WORD_STOPLIST = new Set([
+    'High', 'Prep', 'Academy', 'Preparatory', 'School', 'Elementary', 'Middle',
+    'Band', 'Orchestra', 'Choir', 'Chorale', 'Ensemble', 'Symphony', 'Philharmonic',
+    'Honors', 'University', 'College', 'Institute', 'Award', 'Prize', 'Scholarship',
+    'Fellowship', 'Medal', 'Committee', 'Department', 'Office', 'Center', 'Foundation',
+    'Association', 'Club', 'Team', 'League', 'County', 'City', 'State', 'Hall',
+    'Park', 'Library', 'Hospital', 'Church', 'Program', 'Project', 'Street',
+    'Avenue', 'Road', 'Boulevard', 'Lane', 'Drive', 'Court',
+]);
+// Common sentence-openers and function words that begin false pairs.
+const FIRST_WORD_STOPLIST = new Set([
+    'The', 'A', 'An', 'As', 'At', 'In', 'On', 'Of', 'My', 'Our', 'Your', 'His',
+    'Her', 'Their', 'This', 'That', 'These', 'Those', 'Dear', 'If', 'When',
+    'While', 'After', 'Before', 'She', 'He', 'They', 'It', 'We', 'You', 'But',
+    'And', 'Or', 'So', 'To', 'For', 'From', 'With', 'By', 'Please',
+]);
+const PAIR = /\b([A-Z][a-z]+)\s+(?:[A-Z]\.\s+)?([A-Z][a-z]+)\b/g;
+/** Detect probable personal names with the naive capitalized-pair pattern. */
+export function detectNamesNaive(text) {
+    const flags = [];
+    PAIR.lastIndex = 0;
+    let m;
+    while ((m = PAIR.exec(text)) !== null) {
+        const [whole, first, second] = m;
+        if (first === undefined || second === undefined)
+            continue;
+        if (FIRST_WORD_STOPLIST.has(first) || SECOND_WORD_STOPLIST.has(second)) {
+            // Rescan from the second word so "The Maya Chen" still finds "Maya Chen".
+            PAIR.lastIndex = m.index + first.length;
+            continue;
+        }
+        flags.push({
+            kind: 'name',
+            category: 'name-pair',
+            start: m.index,
+            end: m.index + whole.length,
+            text: whole,
+            reason: NAIVE_REASON,
+            placeholderType: 'student',
+        });
+    }
+    return flags;
+}

package/dist/scan.d.ts

@@ -0,0 +1,9 @@
+import type { Flag, KnownTerm, ScanOptions, ScanResult } from './types.js';
+/** Stage every whole-token occurrence of the caller's known terms. */
+export declare function detectKnownTerms(text: string, terms: KnownTerm[]): Flag[];
+/**
+ * Run all detection layers over a document and apply layer 4: document-level
+ * accumulation. The banner is a flag for the professional, never a redaction,
+ * and no result from this function ever means "this document is safe."
+ */
+export declare function scanDocument(text: string, options?: ScanOptions): ScanResult;

package/dist/scan.js

@@ -0,0 +1,62 @@
+import { DEFAULT_OPTIONS } from './types.js';
+import { detectDirect, overlaps } from './direct.js';
+import { detectNamesNaive } from './names.js';
+import { detectContextual } from './contextual.js';
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Stage every whole-token occurrence of the caller's known terms. */
+export function detectKnownTerms(text, terms) {
+    const flags = [];
+    for (const t of terms) {
+        if (t.term.trim().length === 0)
+            continue;
+        const re = new RegExp(`(?<!\\w)${escapeRegExp(t.term)}(?!\\w)`, 'g');
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            flags.push({
+                kind: 'name',
+                category: 'known-term',
+                start: m.index,
+                end: m.index + m[0].length,
+                text: m[0],
+                reason: t.label ?? 'On your always-flag list',
+                placeholderType: t.placeholderType ?? 'student',
+            });
+            if (m.index === re.lastIndex)
+                re.lastIndex++;
+        }
+    }
+    return flags;
+}
+/**
+ * Run all detection layers over a document and apply layer 4: document-level
+ * accumulation. The banner is a flag for the professional, never a redaction,
+ * and no result from this function ever means "this document is safe."
+ */
+export function scanDocument(text, options = {}) {
+    const { accumulationThreshold } = { ...DEFAULT_OPTIONS, ...options };
+    // Known terms are caller-supplied truth; they win every overlap.
+    const known = detectKnownTerms(text, options.knownTerms ?? []);
+    const direct = detectDirect(text).filter((d) => !known.some((k) => overlaps(k, d)));
+    // Direct hits win over the name layer and over contextual signals that
+    // fall entirely inside them (e.g. a year inside a full date).
+    const names = (options.nameFlags ?? detectNamesNaive(text)).filter((n) => !direct.some((d) => overlaps(d, n)) && !known.some((k) => overlaps(k, n)));
+    const contextual = detectContextual(text, options).flags.filter((c) => !direct.some((d) => d.start <= c.start && c.end <= d.end) &&
+        !known.some((k) => k.start <= c.start && c.end <= k.end));
+    const flags = [...known, ...direct, ...names, ...contextual].sort((a, b) => a.start - b.start || a.end - b.end);
+    const contextualCount = contextual.length;
+    const triggered = contextualCount >= accumulationThreshold;
+    return {
+        flags,
+        accumulation: {
+            triggered,
+            contextualCount,
+            ...(triggered
+                ? {
+                    message: `${contextualCount} contextual details flagged in this document. Even with each one masked, the combination may still identify the student. Review whether the pieces together narrow to one person.`,
+                }
+                : {}),
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/** The three flag kinds shown in the UI: red / name-colored / yellow. */
+export type FlagKind = 'direct' | 'name' | 'contextual';
+/** Placeholder sequences are assigned per type, in detection order. */
+export type PlaceholderType = 'student' | 'parent' | 'school' | 'coach' | 'org' | 'place' | 'email' | 'phone' | 'id' | 'date' | 'address' | 'other';
+/** A single staged detection. Every flag carries a human-readable reason. */
+export interface Flag {
+    kind: FlagKind;
+    /** Rule identifier, e.g. 'email', 'name-pair', 'school-list-continuation'. */
+    category: string;
+    start: number;
+    end: number;
+    text: string;
+    reason: string;
+    /** Suggested placeholder sequence if the professional approves this flag. */
+    placeholderType: PlaceholderType;
+    /** Contextual flags only: the score that crossed the threshold. */
+    score?: number;
+}
+/** A raw contextual rule hit, before proximity scoring. */
+export interface ContextSignal {
+    category: string;
+    weight: number;
+    start: number;
+    end: number;
+    text: string;
+}
+export interface ScanOptions {
+    /** Contextual score a signal must reach to become a flag. Default 3. */
+    flagThreshold?: number;
+    /** Contextual flag count that triggers the document-level banner. Default 6. */
+    accumulationThreshold?: number;
+    /** Distance (chars) within which neighboring signals contribute. Default 200. */
+    proximityWindow?: number;
+    /**
+     * Name-kind flags from an external detector (e.g. an on-device NER model).
+     * When provided, these replace the built-in naive capitalized-pair layer.
+     */
+    nameFlags?: Flag[];
+    /**
+     * Terms the caller already knows are identifying (the user's watchlist, or
+     * a student record on the caller's side). Staged with top priority; they
+     * win every overlap with detected flags.
+     */
+    knownTerms?: KnownTerm[];
+}
+export interface AccumulationResult {
+    triggered: boolean;
+    contextualCount: number;
+    /** Present when triggered. A flag for the professional, never a redaction. */
+    message?: string;
+}
+export interface ScanResult {
+    flags: Flag[];
+    accumulation: AccumulationResult;
+}
+/** Flat mapping: real string -> placeholder. The only sensitive artifact. */
+export type Mapping = Record<string, string>;
+/**
+ * Map format v2 (namemasker-map@2): the full sensitive artifact.
+ * - mapping: canonical real -> placeholder, placeholders unique. Unmask
+ *   restores ONLY these, so restoration is always deterministic.
+ * - aliases: alternate spellings -> an existing placeholder. They mask but
+ *   never win at unmask ("Maya" -> "Student A" alongside "Maya Chen").
+ * - watchlist: terms to always stage on scan. Deleting one only affects
+ *   future scans; deleting a mapping entry is the only destructive act.
+ */
+export interface StudentMap {
+    mapping: Mapping;
+    aliases: Mapping;
+    watchlist: string[];
+}
+/** A term the caller already knows is identifying (watchlist, student record). */
+export interface KnownTerm {
+    term: string;
+    placeholderType?: PlaceholderType;
+    /** Optional reason override shown on the flag. */
+    label?: string;
+}
+/** A flag the professional approved, possibly with an edited replacement type. */
+export interface ApprovedItem {
+    text: string;
+    placeholderType: PlaceholderType;
+}
+export declare const DEFAULT_OPTIONS: Required<Omit<ScanOptions, 'nameFlags' | 'knownTerms'>>;

package/dist/types.js

@@ -0,0 +1,5 @@
+export const DEFAULT_OPTIONS = {
+    flagThreshold: 3,
+    accumulationThreshold: 6,
+    proximityWindow: 200,
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@namemasker/core",
+  "version": "0.1.0",
+  "description": "Local PII detection, masking, and restore engine for NameMasker. Runs in browser and Node; no network, no telemetry.",
+  "license": "MIT",
+  "author": "Chris Bell",
+  "homepage": "https://namemasker.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisbellco2/namemasker.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/chrisbellco2/namemasker/issues",
+  "keywords": [
+    "pii",
+    "redaction",
+    "masking",
+    "privacy",
+    "student-privacy",
+    "local-first",
+    "ner"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run check && npm test && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  }
+}