tosijs-styled-editor 0.4.4 → 0.5.0

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security
+
+## Reporting
+
+- **A sanitizer bypass** — pasted or dropped content that reaches the document
+  still able to execute — belongs to
+  [`tosijs-kilpi`](https://github.com/tonioloewald/kilpi/issues). That is where
+  the filtering code lives; this package only calls it.
+- **Anything else** — [this repository's
+  issues](https://github.com/tonioloewald/tosijs-editor/issues).
+
+If you would rather not disclose publicly first, open an issue with no details
+and we will find a private channel.
+
+## What this package is responsible for
+
+- applying sanitization at the **paste and drop choke point**, before any node
+  enters the document (`insertTransfer`)
+- the `editor.sanitize` hook, so a host can substitute its own sanitizer
+- the two URL guards this package owns: `setLink`, and following a link on
+  Ctrl/Cmd-click
+
+## What it is NOT responsible for
+
+- **the sanitization policy itself** — that is kilpi's, and
+  [kilpi's SECURITY.md](https://github.com/tonioloewald/kilpi/blob/main/SECURITY.md)
+  is authoritative. It is deliberately not restated here, because a copy of a
+  policy drifts from the policy.
+- **content the host supplies**: `editor.value = html` and initial light-DOM
+  content are inside your trust boundary and are not filtered.
+- **documents stored before 0.4.4**, which may already contain a pasted payload.
+  Setting `value` does not filter, so sanitize your corpus as part of upgrading.

package/dist/changes.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Tracked changes — insertions and deletions as CONTENT, with attribution.
+ *
+ * The alternative was an operation log alongside the undo snapshots.
+ * EXTENSIBILITY.md weighs both: an operation log is the only thing that gets you
+ * a merge story, and it is the most expensive decision in this codebase.
+ * Changes-as-content gets everything except merge, for a fraction of the work,
+ * and it fits the web-component substrate that footnotes and spelling already
+ * proved.
+ *
+ * WHAT THIS BUYS THAT AN OPERATION LOG DOES NOT: a tracked document is still a
+ * document. It serializes, round-trips, pastes into another editor, and can be
+ * read by something that has never heard of this component.
+ *
+ * ONE ASYMMETRY TO KNOW ABOUT. A footnote plugin that fails to load is benign —
+ * you see a stray marker. A `<tosi-del>` that fails to load renders deleted text
+ * as ordinary prose, which reads as the opposite of what the document means. So
+ * the strikethrough is load-bearing for CORRECTNESS, not decoration, and those
+ * styles belong in the core stylesheet even though the behaviour is a plugin.
+ */
+/** Who made a change, and when. */
+export interface ChangeAuthor {
+    /** Stable id — a user id, or a model name for an LLM pass. */
+    id: string;
+    /** What to show a reviewer. */
+    name?: string;
+}
+export interface TrackedChange {
+    id: string;
+    kind: 'insert' | 'delete';
+    author: string;
+    authorName: string;
+    time: string;
+    text: string;
+    element: HTMLElement;
+}
+export declare const INS_TAG = "tosi-ins";
+export declare const DEL_TAG = "tosi-del";
+/**
+ * A new change id.
+ *
+ * The sequence counter is not decoration. `Date.now()` alone collides whenever
+ * two marks are produced in one synchronous handler, which is the NORMAL case:
+ * typing over a selection and pasting over one both delete and then insert
+ * inside a single keydown. Measured at 29% collision without the counter — and
+ * a collision means `acceptChanges(deletionId)` silently also accepts the
+ * replacement insertion, so a reviewer cannot accept a deletion and reject
+ * what replaced it. Exported so there is ONE producer; there used to be three,
+ * and only this one had the guard.
+ */
+export declare const changeId: () => string;
+/**
+ * Insertion and deletion marks.
+ *
+ * Both are CONTAINERS — the text inside stays ordinary editable text, because a
+ * reviewer needs to be able to put the caret in a proposed sentence and adjust
+ * it before accepting. They hold no state beyond their attributes: what a change
+ * is, and who made it, is written in the document, not remembered by an
+ * instance that would not survive a round trip.
+ */
+export declare class TosiIns extends HTMLElement {
+}
+export declare class TosiDel extends HTMLElement {
+}
+export declare function defineChanges(): void;
+/** Every tracked change in a root, in document order. */
+export declare function changesIn(root: Element): TrackedChange[];
+/**
+ * Accept a change: the insertion becomes ordinary text, the deletion goes.
+ *
+ * Accept and reject are deliberately symmetric and deliberately *dumb* — each
+ * one resolves exactly one mark. Anything cleverer (accept all by this author,
+ * accept this paragraph) is a filter over `changesIn` plus a loop, which is the
+ * caller's policy rather than ours.
+ */
+export declare function acceptChange(el: Element): void;
+/** Reject a change: the insertion goes, the deletion becomes ordinary text. */
+export declare function rejectChange(el: Element): void;
+/**
+ * A word-level diff.
+ *
+ * Word-level, not character-level, because the unit has to be something a
+ * reviewer can meaningfully accept or reject. A character diff turns
+ * `teh -> the` into three separate changes and a rewritten sentence into
+ * confetti.
+ *
+ * Longest-common-subsequence over word tokens. Whitespace rides along with the
+ * word that follows it so that rejoining is lossless — the output of a diff with
+ * no changes is byte-identical to its input.
+ */
+export declare function tokenize(text: string): string[];
+export type DiffOp = {
+    op: 'same';
+    text: string;
+} | {
+    op: 'insert';
+    text: string;
+} | {
+    op: 'delete';
+    text: string;
+};
+/**
+ * Above this many tokens on either side, fall back to replace-the-whole-thing.
+ *
+ * The LCS table is (n+1)x(m+1) numbers, and one side of this diff is a REMOTE
+ * RESPONSE — whatever the proofreader returned. Measured: 8k tokens is 429 ms
+ * and +366 MB; 16k (a 78 kB text node) is 1.7 s and +1.2 GB, synchronously on
+ * the main thread. The asymmetric case is worse and cheaper to trigger: a
+ * 200-word paragraph against a 200k-word response is +226 MB PER TEXT NODE.
+ * 4000 tokens is a very long paragraph and costs about 128 MB worst case.
+ *
+ * Past the cap the change is still correct, just coarser: one deletion and one
+ * insertion rather than a word-level diff. Degrading the review experience
+ * beats freezing the tab.
+ */
+export declare const MAX_DIFF_TOKENS = 4000;
+export declare function diffWords(before: string, after: string): DiffOp[];
+/**
+ * Replace a text node's contents with the tracked result of revising it.
+ *
+ * Returns the number of changes introduced. Zero means the revision was
+ * identical and the document was not touched at all — which matters, because a
+ * proofreading pass that changes nothing should not dirty the document or
+ * produce an undo step.
+ */
+export declare function applyRevision(node: Text, revised: string, author: ChangeAuthor): number;

package/dist/commands.d.ts

@@ -26,6 +26,51 @@ export interface EditableContext {
     normalize(): void;
     focus(): void;
     updateUndo(command?: string, reason?: string): void;
+    /**
+     * Delete a node — or, under change tracking, mark it deleted in place.
+     *
+     * **This is how a command deletes anything.** A bare `node.remove()` is
+     * correct only when you know tracking is off, and a command cannot know
+     * that. The fix for tracked deletion originally landed on the component's
+     * private helper and stopped at the keydown handlers, so the two table
+     * commands — and every host-authored command added through
+     * `editor.commands.x = fn` — removed content with no `<tosi-del>`, no entry
+     * in `changes`, and nothing for `rejectChanges()` to restore.
+     */
+    removeNode(node: Node): void;
+    /**
+     * Decline a structural edit, audibly.
+     *
+     * Returns true when the caller should go ahead and refuse; a host that calls
+     * `preventDefault()` on the `structural-edit-refused` event gets false back
+     * and the edit proceeds. Pair it with `tracksChanges()`:
+     *
+     * ```typescript
+     * if (ctx.tracksChanges() && ctx.refuseStructural('delete-table-row')) return
+     * ```
+     *
+     * A bare `return` is not good enough: `preventDefault()` has already run by
+     * the time a command executes, so a silent refusal is a dead menu item with
+     * no signal at any layer. Both table commands shipped that way for one
+     * commit while the README promised the event.
+     *
+     * **An override means the edit happens UNTRACKED.** If tracking could have
+     * represented it, the command would not have been refusing. So a command
+     * whose refusal was overridden should delete raw rather than through
+     * `removeNode` — half-tracking a structural edit is worse than either
+     * choice made cleanly.
+     */
+    refuseStructural(reason: string): boolean;
+    /**
+     * Whether edits are being recorded as tracked changes.
+     *
+     * A command that RESTRUCTURES rather than deletes text — removing a table
+     * row, merging blocks — should check this and decline, because a change mark
+     * wraps content and structure is not content. Declining is the house rule:
+     * silently restructuring with nothing in `changes` to show for it is the
+     * failure this whole mechanism exists to prevent.
+     */
+    tracksChanges(): boolean;
 }
 /** Parse a "key value key value" argument list into a CSS object */
 export declare function makeCSS(args: string[]): Record<string, string> | null;

package/dist/dom-utils.d.ts

@@ -84,26 +84,25 @@ export declare function caretGeometryAt(marker: Element, root: Element): {
     height: number;
 } | null;
 /**
- * Strip executable content from a subtree, IN PLACE.
+ * Sanitization lives in `tosijs-kilpi` — the same code, extracted so it is not
+ * maintained in two places.
  *
- * The editor replaced `contentEditable` but not the sanitization the browser
- * was doing on its behalf: pasted and dropped HTML is written into the live
- * document, and from there into `value`, `internals.setFormValue` and every
- * undo snapshot — so an unsanitized payload is stored, re-served, and re-fired
- * on undo. Must run BEFORE any node enters the document.
+ * It was duplicated briefly, and that is exactly the shape that produced review
+ * finding M1 of the 0.4.4 cycle: one URL-normalization defect fixed in one of
+ * two copies, silently leaving the other. Across two repositories that drift
+ * would not even be visible in a diff.
  *
- * This is deliberately a denylist for elements and an allowlist for URL
- * schemes: unknown ELEMENTS are content (including a plugin's custom elements,
- * which must survive — see EXTENSIBILITY.md), whereas unknown SCHEMES are not.
+ * Re-exported here so the editor's public API is unchanged and every call site
+ * keeps importing from `./dom-utils`.
  */
-export declare function sanitizeInPlace(root: Element | DocumentFragment): void;
+export { sanitizeInPlace, isSafeNavigationUrl } from 'tosijs-kilpi';
 /**
- * Is this URL safe to NAVIGATE to, or to write into an href?
+ * A block with nothing left in it worth keeping.
  *
- * Stricter than `isSafeUrl`: that one allows raster `data:image/*` because an
- * `<img src>` may legitimately carry one, while a link must never — so this
- * rejects every `data:` URL. Both must normalize identically, or the stricter
- * check is the one that gets bypassed: `da&#9;ta:image/png;…` passed here while
- * `data:image/png;…` was correctly rejected.
+ * "No text" is not enough on its own: an image, a rule, a line break or a
+ * table is content with no text content, and a `<tosi-del>` is text somebody
+ * has proposed to remove and a reviewer still has to see. Two copies of this
+ * test existed and had already drifted in opposite directions — one checked
+ * the replaced elements and not the change mark, the other the reverse.
  */
-export declare function isSafeNavigationUrl(value: string): boolean;
+export declare function blockIsEmpty(block: Element): boolean;

package/dist/footnote.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `<tosi-footnote>` — a footnote reference that maintains its own entry.
+ *
+ * This is the first feature converted to the web-component substrate described
+ * in EXTENSIBILITY.md, and it exists because of a shipped bug: `insertFootnote`
+ * called `renumberFootnotes` at insertion time and nothing called it again, so
+ * deleting a reference with Backspace left its text orphaned in the list and
+ * the survivors mis-numbered.
+ *
+ * `renumberFootnotes` was never wrong — it already removes orphans and derives
+ * numbers from document order. What was missing was anything to *call* it when
+ * the document changed. Custom element lifecycle is that caller, and it is a
+ * better one than a global "document changed" hook would have been: it fires
+ * per node, only for the nodes that actually moved, and it fires for edits
+ * nobody wrote code for — a deletion, a drag, a paste, an undo.
+ */
+export declare class TosiFootnote extends HTMLElement {
+    /**
+     * Captured on connect, because `disconnectedCallback` runs when this element
+     * is ALREADY detached — `closest()` would find nothing at the only moment we
+     * most need the document.
+     */
+    private editorRoot;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+/** The tag name, so callers do not hard-code a string that could drift. */
+export declare const FOOTNOTE_TAG = "tosi-footnote";
+/**
+ * Register the element.
+ *
+ * Idempotent, and safe to call in a non-browser environment — the editor's
+ * tests run under happy-dom, and a plugin should never be the reason an import
+ * throws somewhere it was not designed for.
+ */
+export declare function defineFootnote(): void;

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export * from './dom-utils';
 export * from './selection';
 export * from './commands';
 export * from './tosijs-styled-editor';
+export * from './changes';
+export * from './spelling';
+export * from './footnote';
 export * from './toolbar';
 export * from './table-utils';
 export { version } from './version';