@sheetpane/grid 0.1.0 → 0.4.0

package/dist/pane/store.js

@@ -2,14 +2,22 @@
 // SR-LAW-7, SR-LAW-9). Framework-free: subscribe / getSnapshot, and mutators.
 // Every mutation goes through commit(): undo (W-23), derive and validate
 // (W-14), "matches suggestion" (B-022) and one notification.
-import { cellRef, detailOf, parseRange, parseRef, patchXlsx, rangesIntersect, spError, spMessage, toCsv, toXlsx } from '@sheetpane/export';
-import { formatCode, general, ImportError, read, subsetCode } from '@sheetpane/import';
+import { cellRef, detailOf, inverseOp, isRowOp, parseRange, parseRef, patchXlsx, rangesIntersect, spError, spMessage, toCsv, toXlsx } from '@sheetpane/export';
+import { formatCode, general, ImportError, read, restructureWorkbook, sha256, subsetCode } from '@sheetpane/import';
 import { checkPlugins, mergeDecorations } from '../plugins/host.js';
+import { STYLE_PROPS } from '../plugins/types.js';
+import { formulaHiddenIn, lockedIn, protectionModeOf, sheetProtectionIn, structureLockedIn, structureProtectionIn } from './protection.js';
 import { HostRules } from './rules.js';
-import { machineAuthored } from './types.js';
+import { DEFAULT_LAYER, ERROR_META_MAX, RESULTS_LEVELS, SEVERITY_ORDER, copyError, isLayerName, isResult, layerOf, machineAuthored } from './types.js';
+import { STRUCTURE_REF, shiftChanges, shiftComposing, shiftDerived, shiftErrors, shiftPluginErrors, shiftSelection, structureRefusal } from './structure.js';
 /** The undo stack's depth per pane; the oldest entry goes first (W-23, SR-GRID decision 7). */
 export const HISTORY_CAP = 500;
 const BLANK = '(blank)';
+/** The CSS a run's span may carry (W-53): the `decorate` allow-list. */
+const ALLOWED_PROPS = new Set(STYLE_PROPS);
+/** The cells a range covers. */
+const areaOf = (r) => (r.bottom - r.top + 1) * (r.right - r.left + 1);
+const inBox = (r, row, col) => row >= r.top && row <= r.bottom && col >= r.left && col <= r.right;
 /**
  * The change-map key of a cell: `Sheet1!B3` (exported as `cellKey`).
  * @param sheet - The sheet name.
@@ -55,8 +63,103 @@ export function parseInput(text, original, source) {
     }
     return text;
 }
+/**
+ * The cell or range a change-map ref is about (W-64): `B3` → `B3`, `#style:B3` → `B3`, `#merge:A1:C1` → `A1:C1`,
+ * and `''` for a ref about the whole sheet (`#freeze`, `#hiddenRows`, `#sheetState`).
+ * @param ref - A change-map ref (the part of the key after `sheet!`).
+ * @returns The A1 cell or range, or `''`.
+ */
+export function editRef(ref) {
+    if (!ref.startsWith('#'))
+        return ref;
+    const m = /^#[A-Za-z]+:(.+)$/.exec(ref);
+    return m ? m[1] : '';
+}
+/** An edit's range at most this many cells is looked up cell by cell; a larger one scans the sheet's problems. */
+const EDIT_LOOKUP_CELLS = 4096;
 /** A sheet's state as read: `state` (W-49), else the older `hidden` flag. */
 export const sheetStateOf = (s) => (s.state ?? (s.hidden ? 'hidden' : 'visible'));
+/** An error's `meta` as kept (W-68): its JSON round trip, or `undefined` — logged as SP-3016 — when it is not JSON or weighs over ERROR_META_MAX. */
+function cleanMeta(id, meta) {
+    let json;
+    try {
+        json = JSON.stringify(meta);
+    }
+    catch {
+        json = undefined;
+    } // a cycle or a BigInt
+    if (json === undefined) {
+        console.warn(spMessage('SP-3016', `${id || 'a new error'}: its meta is not JSON, so it was not kept`));
+        return undefined;
+    }
+    // UTF-8 weighs one to three bytes per UTF-16 unit: encode only when the length cannot tell
+    const bytes = json.length * 3 <= ERROR_META_MAX ? json.length : new TextEncoder().encode(json).length;
+    if (bytes > ERROR_META_MAX) {
+        console.warn(spMessage('SP-3016', `${id || 'a new error'}: its meta is ${bytes} bytes of JSON, over the ${ERROR_META_MAX}-byte cap, so it was not kept`));
+        return undefined;
+    }
+    return JSON.parse(json);
+}
+/** The error with `meta` set to what may be kept, or without it. */
+function withMeta(e, meta) {
+    const { meta: _was, ...rest } = e;
+    const m = meta === undefined ? undefined : cleanMeta(e.id, meta);
+    return m === undefined ? rest : { ...rest, meta: m };
+}
+/** The error without who, when and why (W-69): only an `accepted` error carries them. */
+function withoutAcceptance(e) {
+    if (!('acceptedBy' in e || 'acceptedAt' in e || 'reason' in e))
+        return e;
+    const { acceptedBy: _by, acceptedAt: _at, reason: _why, ...rest } = e;
+    return rest;
+}
+/** Why an error may not stand as `accepted` (W-69), or `undefined` when it may: it needs a reason, and the workbook's own errors are B-029's. */
+function acceptRefusal(e) {
+    if (e.author === 'workbook' || e.author === 'file')
+        return `${e.id}: it is the workbook's own (author "${e.author}"), which is not accepted here`;
+    if (typeof e.reason !== 'string' || !e.reason.trim())
+        return `${e.id || 'an error'}: no reason was given`;
+    return undefined;
+}
+/** An error as a restore keeps it (W-69): `accepted` with who, when and why — without a reason it comes back `open`, logged as SP-3018; any other status, without them. */
+function restoredStatus(e) {
+    if (e.status !== 'accepted')
+        return withoutAcceptance(e);
+    const why = acceptRefusal(e);
+    if (why) {
+        console.warn(spMessage('SP-3018', `${why}, so it was restored as open`));
+        return { ...withoutAcceptance(e), status: 'open' };
+    }
+    return { ...e, acceptedBy: typeof e.acceptedBy === 'string' ? e.acceptedBy : '', acceptedAt: typeof e.acceptedAt === 'string' ? e.acceptedAt : '' };
+}
+/** An error's layer as a restore keeps it (W-51): its own name, or `review` — an unusable one logged as SP-3021. */
+function keptLayer(e) {
+    if (e.layer === undefined)
+        return DEFAULT_LAYER;
+    if (isLayerName(e.layer))
+        return e.layer;
+    console.warn(spMessage('SP-3021', `${e.id || 'an error'}: its layer ${JSON.stringify(e.layer)} is not a layer name, so it went into "${DEFAULT_LAYER}"`));
+    return DEFAULT_LAYER;
+}
+/** The layers whose errors differ between two lists of the pane's errors (W-51): an error added, removed or changed. */
+function changedLayers(a, b) {
+    const out = new Set();
+    if (a === b)
+        return out;
+    const was = new Map(a.map((e) => [e.id, e]));
+    for (const e of b) {
+        const w = was.get(e.id);
+        if (w !== e) {
+            out.add(layerOf(e));
+            if (w)
+                out.add(layerOf(w));
+        }
+        was.delete(e.id);
+    }
+    for (const e of was.values())
+        out.add(layerOf(e));
+    return out;
+}
 const same = (a, b) => a === b || (typeof a === 'number' && typeof b === 'number' && Object.is(a, b)) || JSON.stringify(a) === JSON.stringify(b);
 /**
  * The in-memory workbook one pane shares (SR-GRID decisions 1–8): the uploaded file, every
@@ -95,6 +198,27 @@ export class WorkbookStore {
     /** Plugin errors by `plugin|sheet|range|type` → error id. */
     pluginErrors = new Map();
     errorsViews = 0;
+    // results (W-50): the pane's level, the range Show ▸ marks, and the index the grid reads per cell
+    resultsLevel = 'summary';
+    focus;
+    resultIdx;
+    /** The pane's layers in the order first named (W-51); `shown` the visible ones, `null` for every layer. */
+    known = [];
+    shown = null;
+    layersDirty = false;
+    /** Plugins already told their draft's layer is no name (SP-3021, once each). */
+    badLayerWarned = new Set();
+    // the edits list (W-64): when each change-map entry was written (a commit's sequence and time) and the problems on its
+    // cells before the cell first changed — keyed by the entry object, so undo and redo bring both back with the entry
+    editMeta = new WeakMap();
+    effects = new WeakMap();
+    editSeq = 0;
+    /** The workbook as read, before any insert or delete (W-52); undefined before a load. */
+    baseBook;
+    /** A moved or rewritten change-map entry keeps its edit's time and baseline (W-52 × W-64). */
+    carryEdit = (from, to) => { const m = this.editMeta.get(from); if (m && !this.editMeta.has(to))
+        this.editMeta.set(to, m); };
+    problemIdx;
     /** The host's column rules (W-27): a built-in `validate` provider, never part of the frozen plugin set. */
     rules = new HostRules({
         bookSheets: () => this.snap.book?.sheets,
@@ -112,9 +236,9 @@ export class WorkbookStore {
         this.plugins = checkPlugins(o.plugins ?? []);
         this.snap = {
             load: { status: 'empty' }, source: undefined, book: undefined,
-            changes: new Map(), derived: new Map(), errors: [],
+            changes: new Map(), derived: new Map(), errors: [], layers: [], visibleLayers: [], visibleErrors: [],
             selection: { sheet: '', ref: 'A1' }, mode: 'view', composing: null,
-            canUndo: false, canRedo: false, version: 0,
+            canUndo: false, canRedo: false, protection: 'honour', version: 0,
         };
     }
     // ── subscription (useSyncExternalStore-shaped) ───────────────────────────
@@ -125,7 +249,29 @@ export class WorkbookStore {
     /** Store events, for the elements to turn into DOM events. */
     on(fn) { this.eventListeners.add(fn); return () => this.eventListeners.delete(fn); }
     set(patch, events = []) {
-        this.snap = { ...this.snap, ...patch, canUndo: this.undoStack.length > 0, canRedo: this.redoStack.length > 0, version: this.snap.version + 1 };
+        const prev = this.snap;
+        const next = { ...prev, ...patch, canUndo: this.undoStack.length > 0, canRedo: this.redoStack.length > 0, version: prev.version + 1 };
+        if (next.errors !== prev.errors || this.layersDirty) { // W-51: the layers named so far, the visible ones and their errors
+            const seen = new Set(this.known);
+            for (const l of [...next.errors.map(layerOf), ...(this.shown ?? [])])
+                if (!seen.has(l)) {
+                    seen.add(l);
+                    this.known.push(l);
+                }
+            if (this.layersDirty || this.known.length !== prev.layers.length) {
+                next.layers = [...this.known];
+                next.visibleLayers = this.shown ? [...this.shown] : next.layers;
+            }
+            const vis = this.shown && new Set(this.shown);
+            next.visibleErrors = vis ? next.errors.filter((e) => vis.has(layerOf(e))) : next.errors;
+            this.layersDirty = false;
+        }
+        for (const e of events)
+            if (e.type === 'errors' && !e.layers) {
+                const c = changedLayers(prev.errors, next.errors);
+                e.layers = next.layers.filter((l) => c.has(l));
+            }
+        this.snap = next;
         for (const fn of [...this.listeners])
             fn();
         for (const e of events)
@@ -161,12 +307,16 @@ export class WorkbookStore {
         }
         if (seq !== this.loadSeq)
             return;
-        const source = { name, kind: book.source, size: bytes.length, bytes, readMs: Math.round(performance.now() - t0) };
+        const source = { name, kind: book.source, size: bytes.length, bytes, readMs: Math.round(performance.now() - t0), ...(book.sha256 ? { sha256: book.sha256 } : {}) };
         this.undoStack = [];
         this.redoStack = [];
         this.textCache.clear();
         this.pluginErrors.clear();
+        this.focus = undefined;
+        this.known = [];
+        this.layersDirty = true; // W-51: a new workbook starts with the visible layers named, and no others
         const first = book.sheets[book.activeSheet] ?? book.sheets[0];
+        this.baseBook = book; // the workbook as read: a reverted `structure` edit replays what still stands on it (W-52 × W-64)
         this.set({ load: { status: 'ready' }, source, book, changes: new Map(), derived: new Map(), errors: [], composing: null, selection: { sheet: first.name, ref: 'A1' } }, [{ type: 'load', origin }]);
         this.rules.reset(); // column rules: the `load` phase (time-sliced; it re-runs validate when done)
         this.runValidate(book.sheets.map((s) => s.name), origin);
@@ -211,7 +361,8 @@ export class WorkbookStore {
     }
     /** What the cell bar edits: the formula when a `derive` provider (a formula engine) is installed, else the raw value. */
     input(sheet, ref) {
-        const f = this.plugins.some((x) => x.provides.includes('derive')) ? this.formula(sheet, ref) : undefined;
+        // a hidden formula on a protected sheet shows its value only (W-62)
+        const f = this.plugins.some((x) => x.provides.includes('derive')) && !this.isFormulaHidden(sheet, ref) ? this.formula(sheet, ref) : undefined;
         if (f !== undefined)
             return f;
         const v = this.value(sheet, ref);
@@ -280,7 +431,49 @@ export class WorkbookStore {
         const book = this.snap.book, s = this.sheet(sheet), p = parseRef(ref);
         if (!book || !s || !p)
             return undefined;
-        return { store: this, book, sheet: s, ref, row: p.row, col: p.col, value: value === undefined ? this.value(sheet, ref) : value, styleIndex: s.styleIndex[ref] };
+        const runs = this.runs(sheet, ref);
+        return { store: this, book, sheet: s, ref, row: p.row, col: p.col, value: value === undefined ? this.value(sheet, ref) : value, styleIndex: s.styleIndex[ref], ...(runs ? { runs } : {}) };
+    }
+    /**
+     * A rich-text cell's runs from the file (W-53, SR-IMPORT decision 12) while it still holds the file's value — no
+     * value or formula change, no derived value; `undefined` otherwise. An edit writes plain text, so its runs go.
+     */
+    runs(sheet, ref) {
+        const r = this.sheet(sheet)?.runs?.[ref];
+        if (!r)
+            return undefined;
+        const k = key(sheet, ref), c = this.snap.changes.get(k);
+        if ((c && (c.kind === 'value' || c.kind === 'formula')) || this.snap.derived.has(k))
+            return undefined;
+        return r;
+    }
+    /**
+     * A rich-text cell as styled pieces (W-53): the last `decorate` provider's `decorateRuns` that answers, its CSS
+     * allow-listed to `STYLE_PROPS`; a `font-family` throws (SP-3010). `undefined` — draw the text plain — when the
+     * cell has no runs, no provider answers, or the pieces' text is not the display text.
+     */
+    decorateRuns(sheet, ref) {
+        if (!this.runs(sheet, ref))
+            return undefined;
+        const ctx = this.cellContext(sheet, ref);
+        if (!ctx)
+            return undefined;
+        let out;
+        for (const p of this.plugins) {
+            if (!p.provides.includes('decorate') || !p.decorateRuns)
+                continue;
+            const pieces = p.decorateRuns(ctx);
+            if (!pieces)
+                continue;
+            out = pieces.map((x) => {
+                const style = mergeDecorations([{ id: p.id, style: x.style }]);
+                for (const k of Object.keys(style))
+                    if (!ALLOWED_PROPS.has(k))
+                        delete style[k];
+                return Object.keys(style).length ? { text: x.text, style } : { text: x.text };
+            });
+        }
+        return out && out.map((x) => x.text).join('') === this.text(sheet, ref) ? out : undefined;
     }
     /** The merged `decorate` result for a cell; `{}` with no decorate plugin. */
     decorate(sheet, ref) {
@@ -307,6 +500,7 @@ export class WorkbookStore {
             this.textCache.delete(key(sheet, baseRef(ref)));
         }
         const errors = this.withMatches(next.errors, next.changes);
+        this.stampEdits(before, next.changes, keys);
         if (o.record !== false) {
             const last = this.undoStack[this.undoStack.length - 1];
             if (o.coalesce && last && last.coalesce === o.coalesce) {
@@ -373,6 +567,8 @@ export class WorkbookStore {
         if (!book || !p || !this.sheet(sheet))
             return undefined;
         const a1 = cellRef(p.row, p.col);
+        if (this.isLocked(sheet, a1))
+            return undefined; // W-62: a locked cell of a protected sheet refuses every write
         const orig = this.original(sheet, a1);
         const now = typeof input === 'string' && o.parse !== false ? parseInput(input, orig.value, book.source) : input;
         const k = key(sheet, a1);
@@ -443,6 +639,168 @@ export class WorkbookStore {
         if (keys.length)
             this.commit({ changes, errors: this.snap.errors }, keys, origin, events);
     }
+    // ── the edits list (W-64): the change map read as a list, newest first ──
+    /** Stamps the entries a commit wrote with its sequence and time, and the problems on their cells before they first changed. */
+    stampEdits(before, changes, keys) {
+        const seq = ++this.editSeq, at = Date.now();
+        for (const k of keys) {
+            const entry = changes.get(k), prev = before.changes.get(k);
+            if (!entry || entry === prev || this.editMeta.has(entry))
+                continue;
+            this.editMeta.set(entry, { seq, at, base: prev ? this.editMeta.get(prev)?.base : this.baselineOf(before.errors, k) });
+        }
+    }
+    /**
+     * Every edit in the pane — the change map as a list, newest first (W-64): one entry per change-map key, whatever its
+     * kind, so a paste lists each cell and a change a plugin keeps as one entry is one. Derived cells are not edits.
+     * @returns The edits, newest first; the edits one step made keep the change map's order.
+     * @example
+     * ```ts
+     * import { createWorkbook } from '@sheetpane/grid';
+     * const wb = createWorkbook();
+     * await wb.load(bytes, 'q3.xlsx');
+     * wb.setCell('Holdings', 'G7', '6.5');
+     * wb.edits(); // [{ key: 'Holdings!G7', sheet: 'Holdings', ref: 'G7', kind: 'value', was: 6.63, now: 6.5, at: '2026-10-19T…' }]
+     * ```
+     */
+    edits() {
+        const out = [];
+        for (const [k, c] of this.snap.changes) {
+            const { sheet, ref } = splitKey(k), m = this.editMeta.get(c);
+            out.push({ seq: m?.seq ?? 0, e: { key: k, sheet, ref: editRef(ref), kind: c.kind, was: c.was, now: c.now, at: new Date(m?.at ?? 0).toISOString() } });
+        }
+        return out.sort((a, b) => b.seq - a.seq).map((x) => x.e); // stable: one step's edits stay in map order
+    }
+    /**
+     * What one edit did to the problems on its cells (W-64), compared with before its cell first changed: workbook, file
+     * and rule errors `cleared` (now resolved or gone) and `raised` (open now, not before), and a person's errors whose
+     * suggestion the cell now `matched`. An edit about a whole sheet has none.
+     * @param k - The edit's change-map key (`Edit.key`).
+     * @returns Error ids, each list in the errors' order.
+     */
+    editEffects(k) {
+        const c = this.snap.changes.get(k);
+        const none = { cleared: [], raised: [], matched: [] };
+        const base = c && this.editMeta.get(c)?.base;
+        if (!c || !base)
+            return none;
+        const errors = this.snap.errors, hit = this.effects.get(c);
+        if (hit?.errors === errors)
+            return hit.fx;
+        const now = this.problemsOn(errors, k) ?? new Map();
+        const byId = this.indexProblems(errors).byId;
+        const fx = { cleared: [], raised: [], matched: [] };
+        for (const [id, b] of base) {
+            if (!b.open || !b.machine)
+                continue;
+            const e = byId.get(id);
+            if (!e || e.status === 'resolved')
+                fx.cleared.push(id);
+        }
+        for (const e of now.values()) {
+            const b = base.get(e.id);
+            if (machineAuthored(e.author)) {
+                if (e.status === 'open' && !b?.open)
+                    fx.raised.push(e.id);
+            }
+            else if (e.matchesExpected && !b?.matches)
+                fx.matched.push(e.id);
+        }
+        this.effects.set(c, { errors, fx });
+        return fx;
+    }
+    /**
+     * Reverts edits to the file as one undo step (W-64): each key's change-map entry goes, whatever its kind. A sheet's
+     * `structure` entry (W-52) takes every insert and delete on that sheet back with it — the workbook as read, the other
+     * edits moved back. Undo brings them back, each with its time.
+     * @param keys - Change-map keys (`Edit.key`); omitted, every edit in the pane (*Revert all*).
+     * @param origin - The element that asked.
+     * @returns How many edits were reverted.
+     */
+    revertEdits(keys, origin) {
+        const all = keys ?? [...this.snap.changes.keys()];
+        if (all.some((k) => this.snap.changes.get(k)?.kind === 'structure'))
+            return this.revertStructure(all, origin);
+        const changes = new Map(this.snap.changes);
+        const done = [], events = [];
+        for (const k of all) {
+            const prev = changes.get(k);
+            if (!prev)
+                continue;
+            changes.delete(k);
+            done.push(k);
+            const { sheet, ref } = splitKey(k);
+            events.push({ type: 'change', origin, sheet, ref: baseRef(ref), kind: prev.kind, was: prev.now, now: prev.was });
+        }
+        if (done.length)
+            this.commit({ changes, errors: this.snap.errors }, done, origin, events);
+        return done.length;
+    }
+    /** The problems an edit's key covers before its cell first changed, or undefined for an edit about a whole sheet. */
+    baselineOf(errors, k) {
+        const on = this.problemsOn(errors, k);
+        if (!on)
+            return undefined;
+        const out = new Map();
+        for (const e of on.values())
+            out.set(e.id, { open: e.status === 'open', matches: e.matchesExpected, machine: machineAuthored(e.author) });
+        return out;
+    }
+    /** The problems (not results) whose range meets an edit key's cells, by id; undefined when the key is about no cell. */
+    problemsOn(errors, k) {
+        const { sheet, ref } = splitKey(k), r = parseRange(editRef(ref));
+        if (!r)
+            return undefined;
+        const out = new Map();
+        const x = this.indexProblems(errors).sheets.get(sheet);
+        if (!x)
+            return out;
+        if (areaOf(r) <= EDIT_LOOKUP_CELLS) {
+            for (let row = r.top; row <= r.bottom; row++)
+                for (let col = r.left; col <= r.right; col++)
+                    for (const e of x.cells.get(`${row},${col}`) ?? [])
+                        out.set(e.id, e);
+        }
+        else {
+            for (const [c, list] of x.cells) {
+                const [row, col] = c.split(',').map(Number);
+                if (inBox(r, row, col))
+                    for (const e of list)
+                        out.set(e.id, e);
+            }
+        }
+        for (const y of x.ranges)
+            if (rangesIntersect(y.r, r))
+                out.set(y.e.id, y.e);
+        return out;
+    }
+    indexProblems(errors) {
+        if (this.problemIdx?.errors === errors)
+            return this.problemIdx;
+        const sheets = new Map(), byId = new Map();
+        for (const e of errors) {
+            byId.set(e.id, e);
+            if (isResult(e))
+                continue;
+            const r = parseRange(e.range);
+            if (!r)
+                continue;
+            let x = sheets.get(e.sheet);
+            if (!x)
+                sheets.set(e.sheet, (x = { cells: new Map(), ranges: [] }));
+            if (r.top === r.bottom && r.left === r.right) {
+                const c = `${r.top},${r.left}`, l = x.cells.get(c);
+                if (l)
+                    l.push(e);
+                else
+                    x.cells.set(c, [e]);
+            }
+            else
+                x.ranges.push({ r, e });
+        }
+        this.problemIdx = { errors, sheets, byId };
+        return this.problemIdx;
+    }
     // ── merged ranges: core, changed by plugins as kind `merge` (key `sheet!#merge:A1:C1`, now true | false) ──
     /** The sheet's merged ranges: the file's with `merge` changes applied. */
     merges(sheet) {
@@ -510,8 +868,8 @@ export class WorkbookStore {
      */
     setSheetState(sheet, state, origin) {
         const s = this.sheet(sheet), book = this.snap.book;
-        if (!s || !book)
-            return false;
+        if (!s || !book || this.structureLocked())
+            return false; // W-62: a protected structure keeps its sheets as they are
         if (state !== 'visible' && !book.sheets.some((x) => x.name !== sheet && this.hidden(x.name).state === 'visible'))
             return false;
         this.setChange(sheet, '#sheetState', 'sheetState', state, sheetStateOf(s), origin);
@@ -610,8 +968,10 @@ export class WorkbookStore {
             return m === e.matchesExpected ? e : { ...e, matchesExpected: m };
         });
     }
-    /** The uploaded display text of a range's first cell, as `found` freezes it. */
+    /** The uploaded display text of a range's first cell, as `found` freezes it; `""` for a sheet- or workbook-level error (no cell, W-55). */
     foundFor(sheet, range) {
+        if (range === '')
+            return '';
         const r = parseRange(range);
         if (!r)
             return BLANK;
@@ -628,18 +988,27 @@ export class WorkbookStore {
             return false;
         return (this.original(e.sheet, cellRef(r.top, r.left)).text || BLANK) !== e.found;
     }
-    /** Adds a person's error with a new id; `cellChanged` also writes `expected` into the cell in the same undo step. */
+    /** Adds a person's error with a new id; `cellChanged` also writes `expected` into the cell in the same undo step. `range: ''` is the whole sheet, and with `sheet: ''` the workbook (W-55): no cell, so `found` is `''` and nothing is written. `meta` is the host's data (W-68): kept as JSON, or dropped with SP-3016. */
     addError(d, origin) {
-        const e = {
+        let layer = this.defaultLayer;
+        if (d.layer !== undefined) {
+            if (isLayerName(d.layer))
+                layer = d.layer;
+            else
+                console.warn(spMessage('SP-3021', `addError: ${JSON.stringify(d.layer)} is not a layer name, so the error went into "${layer}"`));
+        }
+        const e = withMeta({
             v: 1, id: this.newId(), sheet: d.sheet, range: d.range, type: d.type, severity: d.severity,
             found: this.foundFor(d.sheet, d.range), expected: d.expected ?? '', message: d.message ?? '',
-            cellChanged: !!d.cellChanged, status: 'open', matchesExpected: false, author: d.author ?? '', createdAt: new Date().toISOString(),
-        };
+            cellChanged: !!d.cellChanged, status: 'open', matchesExpected: false, author: d.author ?? '', createdAt: new Date().toISOString(), layer,
+        }, d.meta);
+        if (this.resultsLevel === 'off' && isResult(e))
+            return e; // `results="off"`: a result is dropped on arrival (W-50)
         let changes = this.snap.changes;
         const keys = [];
         const events = [{ type: 'errors', origin }];
         const r = parseRange(d.range);
-        if (d.cellChanged && r && e.expected !== '') {
+        if (d.cellChanged && r && e.expected !== '' && !this.isLocked(d.sheet, cellRef(r.top, r.left))) { // W-62: a locked cell is not written
             const ref = cellRef(r.top, r.left), k = key(d.sheet, ref), orig = this.original(d.sheet, ref);
             const now = parseInput(e.expected, orig.value, this.snap.book?.source ?? 'xlsx');
             const m = new Map(changes);
@@ -654,11 +1023,64 @@ export class WorkbookStore {
         this.commit({ changes, errors: [...this.snap.errors, e] }, keys, origin, events, { extra: { composing: null } });
         return this.snap.errors.find((x) => x.id === e.id);
     }
-    /** Changes an error's status, severity, expected value, message or type; undoable. */
+    /**
+     * Changes an error's status, severity, expected value, message, type or `meta` (W-68: `meta: undefined` removes it; a
+     * `meta` that may not be kept is dropped with SP-3016 and the error keeps its own); undoable. `status: 'accepted'`
+     * (W-69) needs a `reason` and stamps `acceptedAt`; any other status drops `acceptedBy`, `acceptedAt` and `reason`.
+     * @returns `false` when nothing changed: no such error, or an acceptance refused (SP-3018).
+     */
     updateError(id, patch, origin) {
-        if (!this.snap.errors.some((e) => e.id === id))
-            return;
-        this.commit({ changes: this.snap.changes, errors: this.snap.errors.map((e) => (e.id === id ? { ...e, ...patch } : e)) }, [], origin, [{ type: 'errors', origin }]);
+        const cur = this.snap.errors.find((e) => e.id === id);
+        if (!cur)
+            return false;
+        const { meta, reason, acceptedBy, layer: _layer, ...rest } = patch; // an edit never moves an error to another layer (W-51)
+        let out = { ...cur, ...rest };
+        if (out.status === 'accepted') {
+            if (reason !== undefined)
+                out.reason = typeof reason === 'string' ? reason.trim() : reason;
+            if (acceptedBy !== undefined || cur.status !== 'accepted')
+                out.acceptedBy = acceptedBy ?? '';
+            if (patch.status === 'accepted' || cur.status !== 'accepted')
+                out.acceptedAt = new Date().toISOString();
+            const why = acceptRefusal(out);
+            if (why) {
+                console.warn(spMessage('SP-3018', why));
+                return false;
+            }
+            out = { ...withoutAcceptance(out), acceptedBy: out.acceptedBy, acceptedAt: out.acceptedAt, reason: out.reason }; // keep the key order stable
+        }
+        else
+            out = withoutAcceptance(out);
+        if ('meta' in patch) {
+            if (meta === undefined)
+                out = withMeta(out, undefined);
+            else {
+                const m = cleanMeta(id, meta);
+                if (m !== undefined)
+                    out = { ...out, meta: m };
+            }
+        }
+        this.commit({ changes: this.snap.changes, errors: this.snap.errors.map((e) => (e.id === id ? out : e)) }, [], origin, [{ type: 'errors', origin }]);
+        return true;
+    }
+    /**
+     * Accepts an error as a known deviation (W-69): it stays in the review and the download, recorded with who, when and
+     * why, and is no longer counted as open. One undo step; Reopen (`updateError(id, { status: 'open' })`) takes it back.
+     * The workbook's own errors (author `workbook` or `file`) are not accepted here.
+     * @param id - The error's id.
+     * @param reason - Why the deviation is accepted — required; blank is refused with SP-3018.
+     * @param o - `by`: who accepted it (the errors element passes its `author`).
+     * @returns `false` when nothing changed.
+     * @example
+     * ```ts
+     * import { createWorkbook } from '@sheetpane/grid';
+     * const wb = createWorkbook();
+     * const e = wb.addError({ sheet: '', range: '', type: 'other', severity: 'warning', message: 'Page 4 is 2 mm wider than the spec' });
+     * wb.acceptError(e.id, 'Approved by the customer on 18 Oct', { by: 'Ravi' }); // true
+     * ```
+     */
+    acceptError(id, reason, o = {}, origin) {
+        return this.updateError(id, { status: 'accepted', reason, acceptedBy: o.by ?? '' }, origin);
     }
     /** Deletes an error; a cell it changed keeps the change (contract decision 6). */
     deleteError(id, origin) {
@@ -666,22 +1088,128 @@ export class WorkbookStore {
             return;
         this.commit({ changes: this.snap.changes, errors: this.snap.errors.filter((e) => e.id !== id) }, [], origin, [{ type: 'errors', origin }]);
     }
-    /** A copy of every error in the pane. */
-    getErrors() { return this.snap.errors.map((e) => ({ ...e })); }
-    /** The host restores a saved review. Not a user action: the undo stack is cleared (W-23). */
-    setErrors(list, origin) {
-        const errors = list.map((e) => ({ ...e, v: 1, matchesExpected: false }));
-        for (const e of errors) {
-            const n = /^ERR-(\d+)$/.exec(e.id);
-            if (n)
-                this.nextError = Math.max(this.nextError, Number(n[1]) + 1);
+    /**
+     * A copy of the pane's errors, `meta` included (W-68): every layer's, or with `layer` that layer's only (W-51).
+     * @param o - `layer`: one layer's name; an unusable one is logged as SP-3021 and gives `[]`.
+     * @returns The errors, each with its `layer`.
+     */
+    getErrors(o = {}) {
+        if (o.layer === undefined)
+            return this.snap.errors.map(copyError);
+        if (!isLayerName(o.layer)) {
+            console.warn(spMessage('SP-3021', `getErrors: ${JSON.stringify(o.layer)} is not a layer name`));
+            return [];
+        }
+        return this.snap.errors.filter((e) => layerOf(e) === o.layer).map(copyError);
+    }
+    /** Bumps the id counter past an `ERR-n` id, so a new error never reuses it. */
+    reserve(id) { const n = /^ERR-(\d+)$/.exec(id); if (n)
+        this.nextError = Math.max(this.nextError, Number(n[1]) + 1); }
+    /**
+     * The host restores a saved review, or replaces one layer (W-51). Each `meta` is kept as JSON, or dropped with SP-3016 (W-68).
+     *
+     * - **The whole review** (no `layer`): a list, or the `sheetpane-errors` envelope — each error in its own `layer`, one
+     *   without it in `review`; the envelope's `layers` come back too, an empty one included. Not a user action: the undo
+     *   stack is cleared (W-23).
+     * - **One layer** (`layer`): the list becomes that layer's errors, each stamped with it; every other layer is left as it
+     *   is. An id another layer holds (or a blank one) gets a new one. The undo stack is kept, and every step in it sees the
+     *   new layer, so undo neither brings back the replaced errors nor takes away the new ones.
+     *
+     * @param review - The errors, or a saved envelope (`{ v?, errors, plugins?, layers? }`; one saved before W-51 has no `v`).
+     * @param o - `layer`: the one layer to replace; an unusable name is logged as SP-3021 and nothing changes.
+     * @param origin - The element that asked.
+     * @example
+     * ```ts
+     * import { createWorkbook } from '@sheetpane/grid';
+     * const wb = createWorkbook();
+     * wb.setErrors(validationResults, { layer: 'validation' });
+     * wb.setErrors(pdfResults, { layer: 'pdf' }); // the validation layer is untouched
+     * wb.setVisibleLayers(['pdf']);
+     * ```
+     */
+    setErrors(review, o = {}, origin) {
+        const env = Array.isArray(review) ? undefined : review;
+        const list = env ? (Array.isArray(env.errors) ? env.errors : []) : review;
+        if (o.layer !== undefined) {
+            if (!isLayerName(o.layer)) {
+                console.warn(spMessage('SP-3021', `setErrors: ${JSON.stringify(o.layer)} is not a layer name, so nothing changed`));
+                return;
+            }
+            this.replaceLayer(list, o.layer, origin);
+            return;
         }
+        const errors = this.arriving(list).map((e) => restoredStatus(withMeta({ ...e, v: 1, matchesExpected: false, layer: keptLayer(e) }, e.meta)));
+        for (const e of errors)
+            this.reserve(e.id);
         this.undoStack = [];
         this.redoStack = [];
         this.pluginErrors.clear(); // ids now name the restored list's errors; validate re-adopts its own by what they say, never by id
+        this.known = (env && Array.isArray(env.layers) ? env.layers : []).filter((l, i, a) => keptLayer({ layer: l }) === l && a.indexOf(l) === i);
+        this.layersDirty = true;
         this.set({ errors: this.withMatches(errors, this.snap.changes) }, [{ type: 'errors', origin }, { type: 'history', origin, reason: 'cleared' }]);
         this.runValidate(this.allSheets(), origin);
     }
+    /** `setErrors(list, { layer })` (W-51): one layer replaced; the other layers, and the undo stack rebased onto the new layer, kept. */
+    replaceLayer(list, layer, origin) {
+        const mine = (e) => layerOf(e) === layer;
+        const history = [...this.undoStack, ...this.redoStack];
+        const taken = new Set(this.snap.errors.filter((e) => !mine(e)).map((e) => e.id));
+        for (const h of history)
+            for (const e of [...h.before.errors, ...h.after.errors])
+                if (!mine(e))
+                    taken.add(e.id);
+        const incoming = this.arriving(list).map((e) => restoredStatus(withMeta({ ...e, v: 1, matchesExpected: false, layer }, e.meta)));
+        for (const e of incoming)
+            this.reserve(e.id);
+        const fresh = incoming.map((e) => { const ok = typeof e.id === 'string' && e.id !== '' && !taken.has(e.id); const x = ok ? e : { ...e, id: this.newId() }; taken.add(x.id); return x; });
+        const swap = (errors) => [...errors.filter((e) => !mine(e)), ...fresh];
+        for (const h of history) {
+            h.before = { changes: h.before.changes, errors: swap(h.before.errors) };
+            h.after = { changes: h.after.changes, errors: swap(h.after.errors) };
+        }
+        const gone = new Set(this.snap.errors.filter(mine).map((e) => e.id));
+        for (const [k, id] of this.pluginErrors)
+            if (gone.has(id))
+                this.pluginErrors.delete(k); // a provider re-adopts its own by what they say
+        if (!this.known.includes(layer))
+            this.known.push(layer); // a check that found nothing is still a layer
+        this.layersDirty = true;
+        this.set({ errors: this.withMatches(swap(this.snap.errors), this.snap.changes) }, [{ type: 'errors', origin }]);
+        this.runValidate(this.allSheets(), origin);
+    }
+    /**
+     * Shows the errors of some layers only (W-51): the sheet's marks, pins and counts, the tab counts, the error list and
+     * the comments an export writes all follow. `null` or `[]` shows every layer. Naming a layer that has no errors yet
+     * adds it to the pane's layers. Not undone; it is view state, like the mode.
+     * @param names - The layers to show, or `null` for every layer.
+     * @param origin - The element that asked.
+     * @returns `false` when a name is unusable (logged as SP-3021) — nothing changes.
+     */
+    setVisibleLayers(names, origin) {
+        const list = names && names.length ? [...new Set(names)] : null;
+        const bad = list?.find((l) => !isLayerName(l));
+        if (list && bad !== undefined) {
+            console.warn(spMessage('SP-3021', `layers: ${JSON.stringify(bad)} is not a layer name, so the visible layers did not change`));
+            return false;
+        }
+        if ((list ?? []).join(' ') === (this.shown ?? []).join(' '))
+            return true;
+        this.shown = list;
+        this.layersDirty = true;
+        this.set({}, [{ type: 'layers', origin }]);
+        return true;
+    }
+    /** The layer a new error goes into when none is named (W-51): `review` while it is visible, else the first visible layer — so what a person adds stays in sight. */
+    get defaultLayer() { const v = this.shown; return !v || v.includes(DEFAULT_LAYER) ? DEFAULT_LAYER : v[0]; }
+    /**
+     * What `sheetpane-errors` carries (W-51, `v: 2`): every error, the plugin ids and the pane's layers — what a host saves
+     * and gives back to `setErrors()`.
+     * @param changed - The layers whose errors changed in this event.
+     * @returns A new envelope; its errors are copies.
+     */
+    envelope(changed = []) {
+        return { v: 2, errors: this.getErrors(), plugins: this.pluginIds, layers: [...this.snap.layers], changed: [...changed] };
+    }
     // ── undo / redo (W-23): one stack per pane ──────────────────────────────
     /** Undoes the pane's last step (changes and errors; never selection or mode). */
     undo(origin) { this.travel(this.undoStack, this.redoStack, 'before', origin, 'undo'); }
@@ -694,6 +1222,10 @@ export class WorkbookStore {
         h.coalesce = undefined;
         to.push(h);
         const state = h[side];
+        if (h.structure) {
+            this.travelStructure(h, side, origin, reason);
+            return;
+        }
         const events = [{ type: 'history', origin, reason }];
         const cur = this.snap.changes;
         for (const k of new Set([...h.keys, ...[...cur.keys()].filter((x) => cur.get(x) !== state.changes.get(x))])) {
@@ -706,7 +1238,7 @@ export class WorkbookStore {
         }
         if (this.snap.errors !== state.errors)
             events.push({ type: 'errors', origin });
-        this.set({ changes: state.changes, errors: this.withMatches(state.errors, state.changes) }, events);
+        this.set({ changes: state.changes, errors: this.withMatches(this.arriving(state.errors), state.changes) }, events);
         const sheets = [...new Set(h.keys.map((k) => splitKey(k).sheet))];
         if (sheets.length) {
             this.rules.touch(h.keys.map(splitKey).filter((c) => !c.ref.startsWith('#')));
@@ -716,6 +1248,162 @@ export class WorkbookStore {
                 void this.runDerive({ kind: 'change', cells });
         }
     }
+    // ── rows and columns (W-52): one change of kind `structure` per operation ──
+    /**
+     * Inserts rows above row `at` (0-based): everything at and below it moves down — cells, changes,
+     * errors, merges, rules, notes, drawings, sizes, hidden and outline state, and every formula that
+     * points there. One undo step; written into the download.
+     * @param sheet - The sheet's name.
+     * @param at - The first new row, 0-based.
+     * @param count - How many rows (default 1).
+     * @param origin - The element that asked.
+     * @returns False when refused (see {@link WorkbookStore.structureRefusal}) or nothing is loaded.
+     */
+    insertRows(sheet, at, count = 1, origin) { return this.restructure({ sheet, op: 'insertRows', at, count }, origin); }
+    /**
+     * Deletes rows `at` … `at + count − 1` (0-based) and what sits on them; references to them become `#REF!`.
+     * @param sheet - The sheet's name.
+     * @param at - The first row to delete, 0-based.
+     * @param count - How many rows (default 1).
+     * @param origin - The element that asked.
+     * @returns False when refused or nothing is loaded.
+     */
+    deleteRows(sheet, at, count = 1, origin) { return this.restructure({ sheet, op: 'deleteRows', at, count }, origin); }
+    /**
+     * Inserts columns left of column `at` (0-based: A is 0); everything at and right of it moves right.
+     * @param sheet - The sheet's name.
+     * @param at - The first new column, 0-based.
+     * @param count - How many columns (default 1).
+     * @param origin - The element that asked.
+     * @returns False when refused or nothing is loaded.
+     */
+    insertCols(sheet, at, count = 1, origin) { return this.restructure({ sheet, op: 'insertCols', at, count }, origin); }
+    /**
+     * Deletes columns `at` … `at + count − 1` (0-based) and what sits on them.
+     * @param sheet - The sheet's name.
+     * @param at - The first column to delete, 0-based.
+     * @param count - How many columns (default 1).
+     * @param origin - The element that asked.
+     * @returns False when refused or nothing is loaded.
+     */
+    deleteCols(sheet, at, count = 1, origin) { return this.restructure({ sheet, op: 'deleteCols', at, count }, origin); }
+    /**
+     * Why an insert or delete would be refused — the file's protection first (SP-3026, W-62: the workbook's structure
+     * is protected, or the sheet is protected without the matching permission), then a merge cut (SP-3022), a pivot
+     * moved (SP-3023), cells pushed off the sheet (SP-3024), a table cut (SP-3025) — or `undefined` when it may go ahead.
+     * @param o - The operation.
+     * @returns The SP code and a sentence for the person, or `undefined`.
+     */
+    structureRefusal(o) {
+        const book = this.snap.book;
+        return book ? structureProtectionIn(this.snap, o) ?? structureRefusal(book, this.merges(o.sheet), o) : undefined;
+    }
+    /** Every insert and delete made since the file was read, in order per sheet — what the download replays first. */
+    structureOps() {
+        return [...this.snap.changes].filter(([, c]) => c.kind === 'structure').flatMap(([, c]) => c.now);
+    }
+    /** The one structural path: check, move every table, one undo step, one `structure` change event. */
+    restructure(o, origin) {
+        const book = this.snap.book;
+        if (!book || !this.sheet(o.sheet) || !Number.isInteger(o.at) || o.at < 0 || !Number.isInteger(o.count) || o.count < 1)
+            return false;
+        const no = this.structureRefusal(o);
+        if (no) {
+            console.warn(spMessage(no.code, `sheetpane: ${no.message}`));
+            return false;
+        }
+        const before = { book, derived: this.snap.derived, pluginErrors: new Map(this.pluginErrors) };
+        const moved = shiftErrors(this.snap.errors, o);
+        const after = { book: restructureWorkbook(book, o), derived: shiftDerived(this.snap.derived, o), pluginErrors: shiftPluginErrors(this.pluginErrors, this.snap.errors, moved.errors, moved.gone) };
+        const changes = shiftChanges(this.snap.changes, o, this.carryEdit);
+        const k = key(o.sheet, STRUCTURE_REF);
+        this.editMeta.set(changes.get(k), { seq: ++this.editSeq, at: Date.now(), base: undefined }); // the sheet's one Edits row, newest (W-64)
+        this.undoStack.push({ before: { changes: this.snap.changes, errors: this.snap.errors }, after: { changes, errors: moved.errors }, keys: [k], coalesce: undefined, structure: { ops: [o], before, after } });
+        if (this.undoStack.length > HISTORY_CAP)
+            this.undoStack.shift();
+        this.redoStack = [];
+        this.applyStructure([o], after, changes, moved.errors, origin, [{ type: 'errors', origin }]);
+        return true;
+    }
+    /**
+     * Reverts edits that include a sheet's `structure` entry (W-52 × W-64) as one undo step: the other edits named go,
+     * then each named sheet's inserts and deletes are undone, newest first — the changes, errors, derived values and
+     * selection moved back — and the workbook is the one as read with every operation still standing replayed on it, so
+     * deleted rows come back as the file had them. An edit made inside a deleted row was dropped with it and stays gone.
+     */
+    revertStructure(all, origin) {
+        const book0 = this.snap.book;
+        if (!book0 || !this.baseBook)
+            return 0;
+        let changes = new Map(this.snap.changes);
+        const struct = [], done = [], events = [];
+        for (const k of all) {
+            const prev = changes.get(k);
+            if (!prev)
+                continue;
+            if (prev.kind === 'structure') {
+                struct.push(k);
+                continue;
+            }
+            changes.delete(k);
+            done.push(k);
+            const { sheet, ref } = splitKey(k);
+            events.push({ type: 'change', origin, sheet, ref: baseRef(ref), kind: prev.kind, was: prev.now, now: prev.was });
+        }
+        const opsOf = (c) => (Array.isArray(c?.now) ? c.now : []);
+        const ops = struct.flatMap((k) => [...opsOf(this.snap.changes.get(k))].reverse().map(inverseOp));
+        let errors = this.snap.errors, derived = this.snap.derived, plugin = new Map(this.pluginErrors);
+        for (const o of ops) {
+            const moved = shiftErrors(errors, o);
+            plugin = shiftPluginErrors(plugin, errors, moved.errors, moved.gone);
+            errors = moved.errors;
+            changes = shiftChanges(changes, o, this.carryEdit);
+            derived = shiftDerived(derived, o);
+        }
+        for (const k of struct)
+            changes.delete(k); // the undoing operations were appended to the entry: it goes whole
+        let book = this.baseBook;
+        for (const [, c] of changes)
+            if (c.kind === 'structure')
+                for (const o of opsOf(c))
+                    book = restructureWorkbook(book, o);
+        const before = { book: book0, derived: this.snap.derived, pluginErrors: new Map(this.pluginErrors) };
+        const after = { book, derived, pluginErrors: plugin };
+        this.undoStack.push({ before: { changes: this.snap.changes, errors: this.snap.errors }, after: { changes, errors }, keys: [...done, ...struct], coalesce: undefined, structure: { ops, before, after } });
+        if (this.undoStack.length > HISTORY_CAP)
+            this.undoStack.shift();
+        this.redoStack = [];
+        this.applyStructure(ops, after, changes, errors, origin, [{ type: 'errors', origin }], events);
+        return done.length + struct.length;
+    }
+    travelStructure(h, side, origin, reason) {
+        const s = h.structure, ops = side === 'before' ? [...s.ops].reverse().map(inverseOp) : s.ops;
+        this.applyStructure(ops, s[side], h[side].changes, h[side].errors, origin, [{ type: 'history', origin, reason }, { type: 'errors', origin }]);
+    }
+    /**
+     * Puts a structural state in place: the moved book first (formatting reads it), then one notification — a `structure`
+     * change event per operation, after `events[0]`, then `extra` — then validate and derive.
+     */
+    applyStructure(ops, st, changes, errors, origin, events, extra = []) {
+        this.textCache.clear();
+        this.pluginErrors.clear();
+        this.focus = undefined; // W-50: Show ▸'s range named cells that have moved
+        for (const [k, v] of st.pluginErrors)
+            this.pluginErrors.set(k, v);
+        this.snap = { ...this.snap, book: st.book, changes, derived: st.derived };
+        const moves = ops.map((o) => {
+            const last = o.at + o.count - 1;
+            const ref = isRowOp(o) ? `${o.at + 1}:${last + 1}` : `${cellRef(0, o.at).replace(/\d+$/, '')}:${cellRef(0, last).replace(/\d+$/, '')}`;
+            return { type: 'change', origin, sheet: o.sheet, ref, kind: 'structure', was: null, now: null, op: o.op, at: o.at, count: o.count };
+        });
+        const selection = ops.reduce(shiftSelection, this.snap.selection), composing = ops.reduce(shiftComposing, this.snap.composing);
+        this.set({ book: st.book, changes, derived: st.derived, errors: this.withMatches(errors, changes), selection, composing }, [events[0], ...moves, ...extra, ...events.slice(1)]);
+        this.rules.reset();
+        this.runValidate(this.allSheets(), origin);
+        const o = ops[ops.length - 1];
+        if (o)
+            void this.runDerive({ kind: 'restructure', sheet: o.sheet, op: o.op, at: o.at, count: o.count }); // the whole derived set comes back
+    }
     // ── plugin hooks: derive, validate ───────────────────────────────────────
     async runDerive(input) {
         const p = this.plugins.find((x) => x.provides.includes('derive'));
@@ -732,7 +1420,7 @@ export class WorkbookStore {
         }
         if (load !== this.loadSeq)
             return; // a newer workbook replaced this one
-        const derived = new Map(input.kind === 'load' ? [] : this.snap.derived);
+        const derived = new Map(input.kind === 'load' || input.kind === 'restructure' ? [] : this.snap.derived); // a load or a restructure returns the whole set
         for (const d of out) {
             const k = key(d.sheet, d.ref);
             if (d.clear)
@@ -754,10 +1442,11 @@ export class WorkbookStore {
             return;
         let errors = [...this.snap.errors];
         let changed = false;
+        const gone = new Set();
         const at = new Map(errors.map((e, i) => [e.id, i]));
         // restored errors a provider may adopt (setErrors): by what they say, built once
         let adoptable;
-        const contentKey = (e) => `${e.sheet}|${e.range}|${e.type}|${e.author}`;
+        const contentKey = (e) => `${e.sheet}|${e.range}|${e.type}|${e.author}|${layerOf(e)}`;
         const adopt = (d) => {
             if (!adoptable) {
                 adoptable = new Map();
@@ -784,11 +1473,22 @@ export class WorkbookStore {
                     continue;
                 }
                 const seen = new Set();
-                for (const d of drafts) {
-                    const k = `${p.id}|${d.sheet}|${d.range}|${d.type}${d.key ? `|${d.key}` : ''}`;
+                for (const raw of drafts) {
+                    if (this.resultsLevel === 'off' && isResult(raw))
+                        continue; // `results="off"` (W-50)
+                    // W-51: a draft lands in `review` unless its plugin names a layer
+                    let layer = DEFAULT_LAYER;
+                    if (raw.layer !== undefined && isLayerName(raw.layer))
+                        layer = raw.layer;
+                    else if (raw.layer !== undefined && !this.badLayerWarned.has(p.id)) {
+                        this.badLayerWarned.add(p.id);
+                        console.warn(spMessage('SP-3021', `plugin "${p.id}": ${JSON.stringify(raw.layer)} is not a layer name, so its errors went into "${DEFAULT_LAYER}"`));
+                    }
+                    const d = { ...raw, layer };
+                    const k = `${p.id}|${d.sheet}|${d.range}|${d.type}${d.key ? `|${d.key}` : ''}${layer === DEFAULT_LAYER ? '' : `|@${layer}`}`;
                     seen.add(k);
                     const id = this.pluginErrors.get(k);
-                    const mine = (e) => !!e && e.sheet === d.sheet && e.range === d.range && e.type === d.type && e.author === d.author;
+                    const mine = (e) => !!e && e.sheet === d.sheet && e.range === d.range && e.type === d.type && e.author === d.author && layerOf(e) === layer;
                     let i = id !== undefined ? at.get(id) ?? -1 : -1;
                     if (i >= 0 && !mine(errors[i]))
                         i = -1;
@@ -798,7 +1498,7 @@ export class WorkbookStore {
                             this.pluginErrors.set(k, errors[i].id);
                     }
                     if (i < 0) {
-                        const e = { v: 1, id: this.newId(), sheet: d.sheet, range: d.range, type: d.type, severity: d.severity, found: d.found, expected: d.expected, message: d.message, cellChanged: !!d.cellChanged, status: d.status ?? 'open', matchesExpected: false, author: d.author, createdAt: new Date().toISOString() }; // `key` stays out of the error
+                        const e = { v: 1, id: this.newId(), sheet: d.sheet, range: d.range, type: d.type, severity: d.severity, found: d.found, expected: d.expected, message: d.message, cellChanged: !!d.cellChanged, status: d.status ?? 'open', matchesExpected: false, author: d.author, createdAt: new Date().toISOString(), layer }; // `key` stays out of the error
                         if (d.code)
                             e.code = d.code;
                         this.pluginErrors.set(k, e.id);
@@ -806,9 +1506,9 @@ export class WorkbookStore {
                         errors.push(e);
                         changed = true;
                     }
-                    else if (errors[i].author !== 'file' && (errors[i].status === 'resolved' || errors[i].found !== d.found || errors[i].message !== d.message || errors[i].severity !== d.severity || errors[i].code !== d.code)) {
-                        // a machine-authored error follows the cell: reopened, and its found / message refreshed
-                        const { code: _was, ...rest } = errors[i];
+                    else if (errors[i].author !== 'file' && (errors[i].status === 'resolved' || errors[i].found !== d.found || errors[i].expected !== d.expected || errors[i].message !== d.message || errors[i].severity !== d.severity || errors[i].code !== d.code)) {
+                        // a machine-authored error follows the cell: reopened, and its found / expected / message refreshed (W-60: a dependent list's choices change with its parent)
+                        const { code: _was, ...rest } = withoutAcceptance(errors[i]); // an acceptance was for what it found then (W-69)
                         errors[i] = { ...rest, status: d.status ?? 'open', message: d.message, expected: d.expected, found: d.found, severity: d.severity, ...(d.code ? { code: d.code } : {}) };
                         changed = true;
                     }
@@ -818,16 +1518,117 @@ export class WorkbookStore {
                     if (!k.startsWith(`${p.id}|${sheet}|`) || seen.has(k))
                         continue;
                     const i = at.get(id) ?? -1;
-                    if (i >= 0 && (errors[i].author === 'workbook' || errors[i].author === 'host') && errors[i].status === 'open') {
-                        errors[i] = { ...errors[i], status: 'resolved' };
+                    // a result the provider no longer reports is no longer true: it goes, it never resolves (W-50)
+                    if (i >= 0 && isResult(errors[i])) {
+                        gone.add(id);
+                        this.pluginErrors.delete(k);
+                        changed = true;
+                    }
+                    else if (i >= 0 && (errors[i].author === 'workbook' || errors[i].author === 'host') && (errors[i].status === 'open' || errors[i].status === 'accepted')) {
+                        errors[i] = { ...withoutAcceptance(errors[i]), status: 'resolved' };
                         changed = true;
                     }
                 }
             }
         }
+        if (gone.size)
+            errors = errors.filter((e) => !gone.has(e.id));
         if (changed)
             this.set({ errors: this.withMatches(errors, this.snap.changes) }, [{ type: 'errors', origin }]);
     }
+    // ── results (W-50): `pass` and `skipped` entries — counted apart, marked only when asked ──
+    /** How much of the results the pane shows: `off`, `summary` (the default) or `marks`. */
+    get results() { return this.resultsLevel; }
+    /**
+     * Sets the pane's results level — a view setting, never a change or an undo step. `off` drops
+     * the results the pane holds and every one that arrives after.
+     * @param level - `off`, `summary` or `marks`; anything else is ignored.
+     */
+    setResults(level) {
+        if (!RESULTS_LEVELS.includes(level) || level === this.resultsLevel)
+            return;
+        this.resultsLevel = level;
+        this.focus = undefined;
+        if (level === 'off' && this.snap.errors.some(isResult))
+            this.set({ errors: this.snap.errors.filter((e) => !isResult(e)) }, [{ type: 'errors', origin: undefined }]);
+        else
+            this.set({});
+    }
+    /** The range whose results are marked on the sheet below `marks` (Show ▸ in the errors panel), or undefined. */
+    get resultFocus() { return this.focus; }
+    /**
+     * Marks one range's results on the sheet even at `summary` (Show ▸); `undefined` clears it. A view setting.
+     * @param sheet - The sheet's name.
+     * @param range - An A1 range, or undefined to clear.
+     */
+    focusResults(sheet, range) {
+        const next = range && parseRange(range) ? { sheet, range } : undefined;
+        if (next?.sheet === this.focus?.sheet && next?.range === this.focus?.range)
+            return;
+        this.focus = next;
+        this.set({});
+    }
+    /**
+     * The result a cell shows — `pass` or `skipped` — or undefined. A problem always wins: a cell any
+     * problem covers has no result. Indexed once per errors list, so the grid asks per cell.
+     * @param sheet - The sheet's name.
+     * @param row - The 0-based row.
+     * @param col - The 0-based column.
+     * @returns The result entry, or undefined.
+     */
+    resultAt(sheet, row, col) {
+        const x = this.indexResults().sheets.get(sheet);
+        if (!x)
+            return undefined;
+        const k = `${row},${col}`;
+        if (x.problemCells.has(k) || x.problemRanges.some((r) => inBox(r, row, col)))
+            return undefined;
+        return x.cells.get(k) ?? x.ranges.find((y) => inBox(y.r, row, col))?.e;
+    }
+    /** Problems (entries) and results (cells) in the pane — what the summary line and the status line say. */
+    resultCounts() { return this.indexResults().counts; }
+    indexResults() {
+        const errors = this.snap.visibleErrors; // W-51: what the visible layers hold
+        if (this.resultIdx?.errors === errors)
+            return this.resultIdx;
+        const sheets = new Map(), counts = { problems: 0, open: 0, pass: 0, skipped: 0 };
+        for (const e of errors) {
+            const r = parseRange(e.range);
+            const result = isResult(e);
+            if (!result) {
+                counts.problems++;
+                if (e.status === 'open')
+                    counts.open++;
+            }
+            if (!r)
+                continue;
+            if (result)
+                counts[e.severity] += areaOf(r);
+            let x = sheets.get(e.sheet);
+            if (!x)
+                sheets.set(e.sheet, (x = { cells: new Map(), ranges: [], problemCells: new Set(), problemRanges: [] }));
+            const one = r.top === r.bottom && r.left === r.right, k = `${r.top},${r.left}`;
+            if (!result) {
+                if (one)
+                    x.problemCells.add(k);
+                else
+                    x.problemRanges.push(r);
+            }
+            else if (!one)
+                x.ranges.push({ r, e });
+            else {
+                const was = x.cells.get(k);
+                if (!was || SEVERITY_ORDER[e.severity] > SEVERITY_ORDER[was.severity])
+                    x.cells.set(k, e);
+            }
+        }
+        this.resultIdx = { errors, sheets, counts };
+        return this.resultIdx;
+    }
+    /** A list as it arrives in the pane: at `off`, without its results. */
+    arriving(list) {
+        return this.resultsLevel === 'off' ? list.filter((e) => !isResult(e)) : list;
+    }
     // ── column rules (W-27) ──────────────────────────────────────────────────
     /** The host's column rules for this pane. Setting them checks every row again; host errors no longer produced go. */
     setColumnRules(c) { this.rules.configure(c); }
@@ -837,6 +1638,44 @@ export class WorkbookStore {
     get ruleProgress() { return this.rules.progress; }
     /** Whether a rules file (W-33) is in force for this pane. */
     get hasRulesDocument() { return this.rules.hasDocument; }
+    // ── protection (W-62, SR-GRID decision 21e): what the file locks, kept unless the host rules otherwise ──
+    /** `honour` (the default) keeps the file's sheet and workbook protection; `ignore` is the host's decision. */
+    get protection() { return this.snap.protection; }
+    /**
+     * Keeps (`honour`) or sets aside (`ignore`) the file's protection for this pane — a view setting, never a change or
+     * an undo step. The `protection` attribute of `<sheetpane-excel>` sets it.
+     * @param mode - `honour` or `ignore`; anything else is `honour`.
+     */
+    setProtection(mode) { const m = protectionModeOf(mode); if (m !== this.snap.protection)
+        this.set({ protection: m }); }
+    /**
+     * A sheet's protection while it is honoured: the file's switches (`true` = refused while protected) and whether a
+     * password is stored — never the password.
+     * @param sheet - The sheet's name.
+     * @returns The switches, or undefined when the sheet is not protected or protection is ignored.
+     */
+    sheetProtection(sheet) { return sheetProtectionIn(this.snap, sheet); }
+    /**
+     * Whether a cell refuses edits: a protected sheet, and the cell's format locked (Excel's default). `setCell`,
+     * `setCells` and an error's "Also change the cell" leave it as it is.
+     * @param sheet - The sheet's name.
+     * @param ref - The cell, `A1`.
+     * @returns True when the cell is locked.
+     */
+    isLocked(sheet, ref) { return lockedIn(this.snap, sheet, ref); }
+    /**
+     * Whether a cell's formula is hidden: a protected sheet, and the cell's format `hidden`. It shows its value only.
+     * @param sheet - The sheet's name.
+     * @param ref - The cell, `A1`.
+     * @returns True when the formula is not shown.
+     */
+    isFormulaHidden(sheet, ref) { return formulaHiddenIn(this.snap, sheet, ref); }
+    /**
+     * Whether the workbook's structure is protected (`lockStructure`, honoured): hiding or unhiding a sheet is
+     * refused, and inserting or deleting rows and columns. The one predicate a structural control asks.
+     * @returns True while structural edits are refused.
+     */
+    structureLocked() { return structureLockedIn(this.snap); }
     // ── flagging (W-33): `off` leaves the errors panel as the one place errors are read ──
     flaggingOn = true;
     /** Whether Flag issue is on for this pane (SR-GRID decision 22e). */
@@ -912,8 +1751,15 @@ export class WorkbookStore {
         }
         return Array.from(rows, (r) => Array.from(r ?? [], (v) => v ?? null));
     }
-    /** Every change applied; the upload never modified (SR-LAW-6). */
+    /**
+     * Every change applied; the upload never modified (SR-LAW-6). `sha256` is the hash of the
+     * blob's bytes, taken once per export (W-65) — `undefined` where Web Crypto is missing (SP-1009).
+     */
     async exportFile(o = {}) {
+        const r = await this.buildExport(o);
+        return { ...r, sha256: await sha256(r.blob) };
+    }
+    async buildExport(o) {
         const src = this.snap.source, book = this.snap.book;
         if (!src || !book)
             throw spError('SP-3001', 'sheetpane: nothing is loaded to export');
@@ -948,7 +1794,8 @@ export class WorkbookStore {
             const outline = has('#outlineRows') || has('#outlineCols') ? { outline: { ...(has('#outlineRows') ? { rows: o.rows } : {}), ...(has('#outlineCols') ? { cols: o.cols } : {}) } } : {};
             return { sheet, ...(has('#hiddenRows') ? { rows: h.rows } : {}), ...(has('#hiddenCols') ? { cols: h.cols } : {}), ...(has('#sheetState') ? { state: h.state } : {}), ...outline };
         });
-        const bytes = await patchXlsx(src.bytes, this.exportChanges(), { exportPatch: hooks, ...(freeze.length ? { freeze } : {}), ...(merges.length ? { merges } : {}), ...(hidden.length ? { hidden } : {}) });
+        const structure = this.structureOps(); // replayed on the upload first; everything below is in the sheet as it stands now
+        const bytes = await patchXlsx(src.bytes, this.exportChanges(), { exportPatch: hooks, ...(structure.length ? { structure } : {}), ...(freeze.length ? { freeze } : {}), ...(merges.length ? { merges } : {}), ...(hidden.length ? { hidden } : {}) });
         return { blob: new Blob([bytes], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }), kind: 'xlsx', name: src.name, guarded: [], converted: false };
     }
     // ── stale formula marks (W-01 DoD 15) ───────────────────────────────────