pdfcedar 0.1.0-beta.0 → 0.1.1-beta.0

package/dist/types/core/annotation-geometry.d.cts

@@ -0,0 +1,36 @@
+import type { Annotation, AnnotationPatch, Point, Quad } from './annotations.cjs';
+import type { Rect } from './types.cjs';
+export declare function rectFromPoints(a: Point, b: Point): Rect;
+/** The patch that moves `a` by (dx, dy). */
+export declare function translateAnnotation(a: Annotation, dx: number, dy: number): AnnotationPatch;
+/** Whether the UI offers resize handles. Notes are fixed-size icons; markup follows its text. */
+export declare function isResizable(a: Annotation): boolean;
+/** Signatures scale from their corners only, keeping their proportions (a stretched signature looks forged). */
+export declare function resizeHandles(a: Annotation): Handle[];
+/**
+ * `resized` (from dragHandle on a corner) scaled back to `original`'s proportions: both sides grow or shrink by
+ * the larger of the two changes, anchored at the corner opposite `handle`. Works in any space with y up.
+ */
+export declare function keepAspect(original: Rect, resized: Rect, handle: Handle): Rect;
+export declare function isMovable(a: Annotation): boolean;
+/** The patch that fits `a` into `rect` (shapes take it as-is; ink paths are scaled into it). */
+export declare function resizeAnnotation(a: Annotation, rect: Rect): AnnotationPatch;
+export type Handle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+/**
+ * The rect after dragging `handle` by (dx, dy) in PDF space (y up). Never flips inside out and never
+ * shrinks below `min` points.
+ */
+export declare function dragHandle(rect: Rect, handle: Handle, dx: number, dy: number, min?: number): Rect;
+/** A rect as a QuadPoints quad: top-left, top-right, bottom-left, bottom-right. */
+export declare function quadFromRect(r: Rect): Quad;
+/**
+ * Merges per-word/per-span rects into one rect per line, so a highlight is one smooth band per line
+ * instead of a row of overlapping boxes. Two rects are on the same line when they overlap vertically
+ * by at least half the smaller height and the horizontal gap is under one line height.
+ */
+export declare function mergeLineRects(rects: Rect[]): Rect[];
+/**
+ * The two wing tips of an open arrowhead at `end`. Shared by the on-screen renderer and the PDF writer so
+ * an arrow looks the same everywhere; its reach (3 × stroke width) matches the bounds padding in validate.ts.
+ */
+export declare function arrowHeadPoints(start: Point, end: Point, strokeWidth: number): [Point, Point];

package/dist/types/core/annotation-manager.d.cts

@@ -0,0 +1,97 @@
+import type { Annotation, AnnotationInput, AnnotationPatch, AnnotationType } from './annotations.cjs';
+import type { User } from './types.cjs';
+import type { UndoManager } from './undo.cjs';
+/**
+ * Who caused a change. `document`: loaded from the PDF file itself. `remote` is reserved for
+ * collaboration (Milestone 13).
+ */
+export type ChangeSource = 'api' | 'user' | 'undo' | 'redo' | 'remote' | 'document';
+export type AnnotationEvents = {
+    annotationAdded: {
+        annotation: Annotation;
+        source: ChangeSource;
+    };
+    annotationChanged: {
+        annotation: Annotation;
+        previous: Annotation;
+        source: ChangeSource;
+    };
+    annotationRemoved: {
+        annotation: Annotation;
+        source: ChangeSource;
+    };
+};
+export interface AnnotationManagerOptions {
+    undo: UndoManager;
+    emit<K extends keyof AnnotationEvents>(event: K, payload: AnnotationEvents[K]): void;
+    user?: () => User | undefined;
+    pageCount?: () => number;
+    now?: () => string;
+    newId?: () => string;
+}
+export interface ListFilter {
+    page?: number;
+    type?: AnnotationType;
+}
+export interface ImportOptions {
+    /** Remove every existing annotation first. Default false: imported ids replace matching ones, others are added. */
+    replace?: boolean;
+}
+/**
+ * The single source of truth for annotations. Every change is validated, recorded for undo and announced
+ * through `emit`. Callers always get copies, so nothing outside can mutate the store.
+ */
+export declare class AnnotationManager {
+    private readonly options;
+    /** Insertion order is z-order (later = on top), and undo restores removed annotations to their slot. */
+    private items;
+    private readonly byId;
+    constructor(options: AnnotationManagerOptions);
+    get(id: string): Annotation | undefined;
+    list(filter?: ListFilter): Annotation[];
+    /** Replies to `id`, oldest first. */
+    replies(id: string): Annotation[];
+    add(input: AnnotationInput, source?: ChangeSource): Annotation;
+    update(id: string, patch: AnnotationPatch, source?: ChangeSource): Annotation;
+    /** Removes the annotation and its whole reply thread as one undo step. */
+    /** `withPage`: the annotation's page is being deleted, which also takes applied redactions. */
+    remove(id: string, source?: ChangeSource, { withPage }?: {
+        withPage?: boolean;
+    }): void;
+    /**
+     * Marks redactions as applied (`redaction.apply()`). Not an undoable edit: applying is final, and the
+     * caller clears the undo history so earlier steps can't bring the marks or what's under them back.
+     */
+    markApplied(ids: readonly string[], source?: ChangeSource): void;
+    /**
+     * Applies changes made by other people (collaboration). Not undoable locally, events carry `source: 'remote'`,
+     * and the rules for local edits (applied redactions are final…) don't block them: the shared state is the
+     * authority. Remote data is validated; entries that aren't valid annotations are skipped and returned.
+     */
+    applyRemote(changes: {
+        upsert?: readonly unknown[];
+        remove?: readonly string[];
+    }): {
+        rejected: unknown[];
+    };
+    export(): Annotation[];
+    /**
+     * Validates everything first, so a bad entry changes nothing; then applies the whole import as one undo step.
+     * Ids, authors and timestamps from the JSON are kept.
+     */
+    import(json: unknown, options?: ImportOptions, source?: ChangeSource): Annotation[];
+    private prepare;
+    private requireParent;
+    private require;
+    private insert;
+    private detach;
+    private replace;
+    /** During undo/redo, events report that instead of the original source. */
+    private sourceOf;
+    /**
+     * Whole seconds: PDF dates can't store milliseconds, so this keeps timestamps identical after a
+     * save → reload round trip (change detection by modifiedAt stays reliable).
+     */
+    private now;
+    private context;
+}

package/dist/types/core/annotations.d.cts

@@ -0,0 +1,106 @@
+import type { Rect } from './types.cjs';
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * One quadrilateral of marked-up text, as in a PDF /QuadPoints entry:
+ * [x1, y1, x2, y2, x3, y3, x4, y4] = top-left, top-right, bottom-left, bottom-right (Acrobat's order).
+ */
+export type Quad = [number, number, number, number, number, number, number, number];
+interface AnnotationBase {
+    id: string;
+    /** 1-based page number. */
+    page: number;
+    /** Bounding box. Derived automatically for markup, ink, line and arrow annotations. */
+    rect: Rect;
+    /** `#rrggbb`. Stroke/markup color; the text color for freeText. */
+    color: string;
+    /** 0..1 */
+    opacity: number;
+    /** Comment text shown in the note popup / comment thread. */
+    contents: string;
+    author: string;
+    authorId: string;
+    /** ISO 8601 */
+    createdAt: string;
+    /** ISO 8601 */
+    modifiedAt: string;
+    /** Locked annotations can't be moved, resized or deleted from the UI (the API still can). */
+    locked: boolean;
+}
+export interface TextMarkupAnnotation extends AnnotationBase {
+    type: 'highlight' | 'underline' | 'strikeout';
+    quads: Quad[];
+}
+export interface NoteAnnotation extends AnnotationBase {
+    type: 'note';
+}
+/** A reply in a comment thread. Maps to a PDF annotation with /IRT pointing at the parent. */
+export interface ReplyAnnotation extends AnnotationBase {
+    type: 'reply';
+    inReplyTo: string;
+}
+export interface InkAnnotation extends AnnotationBase {
+    type: 'ink';
+    paths: Point[][];
+    strokeWidth: number;
+}
+export interface ShapeAnnotation extends AnnotationBase {
+    type: 'rectangle' | 'ellipse';
+    strokeWidth: number;
+    /** `#rrggbb`, or null for no fill. */
+    fillColor: string | null;
+}
+export interface LineAnnotation extends AnnotationBase {
+    type: 'line' | 'arrow';
+    start: Point;
+    end: Point;
+    strokeWidth: number;
+}
+export interface FreeTextAnnotation extends AnnotationBase {
+    type: 'freeText';
+    /** The text itself lives in `contents`, as in PDF FreeText annotations. */
+    fontSize: number;
+    backgroundColor: string | null;
+    borderColor: string | null;
+}
+/**
+ * A signature image placed on the page. Saved by drawing it into the page content (flattened), so in the saved
+ * file it is part of the page, not an annotation.
+ */
+export interface SignatureAnnotation extends AnnotationBase {
+    type: 'signature';
+    /** A PNG or JPEG data URL (`signatures.add` converts other formats). */
+    image: string;
+}
+/**
+ * An area marked for redaction. Until applied it's an ordinary editable mark (saved as a /Redact annotation that
+ * Acrobat can also apply). `redaction.apply()` sets `applied`: the area turns black and, on save, everything under
+ * it is removed from the page. Applied redactions can't be changed or removed.
+ */
+export interface RedactionAnnotation extends AnnotationBase {
+    type: 'redaction';
+    applied: boolean;
+}
+export type Annotation = TextMarkupAnnotation | NoteAnnotation | ReplyAnnotation | InkAnnotation | ShapeAnnotation | LineAnnotation | FreeTextAnnotation | SignatureAnnotation | RedactionAnnotation;
+/** The serializable form; identical to `Annotation` (kept as a name because the public API uses it). */
+export type AnnotationJSON = Annotation;
+export type AnnotationType = Annotation['type'];
+type Defaulted = 'id' | 'rect' | 'color' | 'opacity' | 'contents' | 'author' | 'authorId' | 'createdAt' | 'modifiedAt' | 'locked';
+type Optionalize<T> = T extends Annotation ? Omit<T, Defaulted | OptionalFields<T>> & Partial<Pick<T, Extract<keyof T, Defaulted | OptionalFields<T>>>> : never;
+type OptionalFields<T> = T extends ReplyAnnotation ? 'page' : T extends ShapeAnnotation ? 'strokeWidth' | 'fillColor' : T extends InkAnnotation | LineAnnotation ? 'strokeWidth' : T extends FreeTextAnnotation ? 'fontSize' | 'backgroundColor' | 'borderColor' : T extends RedactionAnnotation ? 'applied' : never;
+/** What `annotations.add()` accepts: the annotation with every defaulted field optional. */
+export type AnnotationInput = Optionalize<Annotation>;
+/** What `annotations.update()` accepts: any fields of the annotation's own type. `id` and `type` can't change. */
+export type AnnotationPatch = Annotation extends infer T ? T extends Annotation ? Partial<Omit<T, 'id' | 'type'>> & {
+    id?: string;
+    type?: T['type'];
+} : never : never;
+export declare const ANNOTATION_TYPES: readonly AnnotationType[];
+export declare const DEFAULT_COLORS: Record<AnnotationType, string>;
+export declare const DEFAULT_STROKE_WIDTH = 2;
+export declare const DEFAULT_FONT_SIZE = 14;
+/** PDF annotation subtypes PDFCedar reads, edits and writes. Others in a file are left untouched. */
+export declare const PDF_ANNOTATION_SUBTYPES: ReadonlySet<string>;
+export {};

package/dist/types/core/errors.d.cts

@@ -0,0 +1,11 @@
+/** Thrown by API methods whose feature belongs to a later milestone. */
+export declare class NotImplementedError extends Error {
+    constructor(feature: string, milestone: number);
+}
+/**
+ * A password-protected PDF: opened without the right password, or saved (`save()`/`download()` can't write
+ * encrypted files yet). Lives here (not in the writer) so the public entry can export it without loading pdf-lib.
+ */
+export declare class EncryptedDocumentError extends Error {
+    constructor(message?: string);
+}

package/dist/types/core/errors.d.ts

@@ -2,7 +2,10 @@
 export declare class NotImplementedError extends Error {
     constructor(feature: string, milestone: number);
 }
-/** `save()`/`download()` on a password-protected PDF. Lives here (not in the writer) so the public entry can export it without loading pdf-lib. */
+/**
+ * A password-protected PDF: opened without the right password, or saved (`save()`/`download()` can't write
+ * encrypted files yet). Lives here (not in the writer) so the public entry can export it without loading pdf-lib.
+ */
 export declare class EncryptedDocumentError extends Error {
-    constructor();
+    constructor(message?: string);
 }

package/dist/types/core/events.d.cts

@@ -0,0 +1,10 @@
+export type EventMap = Record<string, unknown>;
+export type Handler<T> = (payload: T) => void;
+/** Small typed event emitter. Handler errors are isolated so one bad listener can't break the viewer. */
+export declare class Emitter<Events extends EventMap> {
+    private readonly handlers;
+    on<K extends keyof Events>(event: K, handler: Handler<Events[K]>): void;
+    off<K extends keyof Events>(event: K, handler: Handler<Events[K]>): void;
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    clear(): void;
+}

package/dist/types/core/forms.d.cts

@@ -0,0 +1,109 @@
+import type { ChangeSource } from './annotation-manager.cjs';
+import type { FormValues, Rect } from './types.cjs';
+import type { UndoManager } from './undo.cjs';
+export type FormFieldType = 'text' | 'checkbox' | 'radio' | 'dropdown' | 'listbox';
+export type FormValue = FormValues[string];
+export interface FormOption {
+    /** What is stored in the PDF and returned by getValues (the export value). */
+    value: string;
+    /** What the user sees. */
+    label: string;
+}
+/** One place a field appears. A radio group has one widget per button; a text field can repeat across pages. */
+export interface FormWidget {
+    /** pdf.js annotation id ("12R"): the widget's object number, used to find it again when saving. */
+    id: string;
+    /** 0-based page in the original file. */
+    pageIndex: number;
+    rect: Rect;
+    /** Checkbox / radio: the value this widget stands for when it is on. */
+    exportValue?: string;
+    /** Points; 0 means "auto" (fit the box). */
+    fontSize: number;
+    /** `#rrggbb` */
+    color: string;
+    align: 'left' | 'center' | 'right';
+    background: string | null;
+    border: string | null;
+    /** Hidden widgets keep their field's value but aren't drawn. */
+    hidden: boolean;
+    /** The widget's own rotation (/MK /R), on top of the page's. */
+    rotation: 0 | 90 | 180 | 270;
+}
+export interface FormField {
+    /** Fully qualified name ("address.city"); the key in getValues/setValues. */
+    name: string;
+    type: FormFieldType;
+    readOnly: boolean;
+    required: boolean;
+    multiline?: boolean;
+    password?: boolean;
+    /** Text: maximum characters (0 = none). */
+    maxLength?: number;
+    /** Text: one character per cell. */
+    comb?: boolean;
+    /** Dropdown / listbox. */
+    options?: FormOption[];
+    /** Listbox: several values. */
+    multiSelect?: boolean;
+    /** Dropdown: also accepts typed text that isn't an option. */
+    editable?: boolean;
+    widgets: FormWidget[];
+    /** The value in the file as loaded. */
+    value: FormValue;
+}
+/** Thrown by `forms.setValues` for an unknown field or a value the field can't hold. Nothing is changed. */
+export declare class FormValueError extends TypeError {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+export interface FormManagerOptions {
+    undo: UndoManager;
+    emit(payload: {
+        name: string;
+        value: FormValue;
+        source: ChangeSource;
+    }): void;
+    /** False for fields that are gone from the document (every page they appear on was deleted). */
+    available?: (field: FormField) => boolean;
+}
+/**
+ * Form field values with undo and change events. The field structure comes from the PDF and never changes;
+ * only values (and whether the form has been flattened) do.
+ */
+export declare class FormManager {
+    private readonly o;
+    private readonly byName;
+    private readonly current;
+    private flattenedState;
+    private readonly listeners;
+    constructor(o: FormManagerOptions);
+    /** Sets the fields read from the file. Not an edit: no undo step, no events. */
+    load(fields: readonly FormField[]): void;
+    /** Fields currently in the document. */
+    get fields(): readonly FormField[];
+    field(name: string): FormField | undefined;
+    private isAvailable;
+    get flattened(): boolean;
+    value(name: string): FormValue | undefined;
+    /** Every field's value; empty once the form is flattened (the fields no longer exist). */
+    values(): FormValues;
+    /** Fields whose value differs from the file's, for saving. */
+    changed(): FormValues;
+    /** Validates every entry first, then applies them as one undo step. */
+    setValues(values: FormValues, source?: ChangeSource): void;
+    /**
+     * Values set by other people (collaboration): validated like setValues, applied without undo, events with
+     * `source: 'remote'`. Unknown fields and invalid values are skipped (the sender may have another file).
+     */
+    applyRemote(values: FormValues): void;
+    /** Marks the form for flattening: on save the fields become part of the page. Undoable. */
+    flatten(): void;
+    /** Called with the names whose value changed (all names for load/flatten). */
+    onChange(listener: (names: readonly string[]) => void): () => void;
+    private setFlattened;
+    private apply;
+    private notify;
+}
+/** The canonical value for `field`, or a FormValueError explaining why `raw` doesn't fit. */
+export declare function normalizeValue(field: FormField, raw: unknown): FormValue;

package/dist/types/core/index.d.cts

@@ -0,0 +1,9 @@
+export { Emitter, type EventMap, type Handler } from './events.cjs';
+export type * from './types.cjs';
+export * from './annotations.cjs';
+export { AnnotationManager, type AnnotationEvents, type AnnotationManagerOptions, type ChangeSource, type ImportOptions, type ListFilter, } from './annotation-manager.cjs';
+export * from './annotation-geometry.cjs';
+export { UndoManager, type Command, type UndoState } from './undo.cjs';
+export { AnnotationValidationError, newId, normalizeAnnotation, normalizeColor, type NormalizeContext } from './validate.cjs';
+export { NotImplementedError, EncryptedDocumentError } from './errors.cjs';
+export { FormManager, FormValueError, normalizeValue, type FormField, type FormFieldType, type FormOption, type FormValue, type FormWidget, type FormManagerOptions } from './forms.cjs';

package/dist/types/core/types.d.cts

@@ -0,0 +1,103 @@
+import type { AnnotationEvents, ChangeSource } from './annotation-manager.cjs';
+import type { AnnotationJSON } from './annotations.cjs';
+export type DocumentSource = string | File | Blob | ArrayBuffer;
+export type ToolName = 'pan' | 'select' | 'zoom' | 'search' | 'highlight' | 'underline' | 'strikeout' | 'note' | 'ink' | 'rectangle' | 'ellipse' | 'line' | 'arrow' | 'freeText' | 'signature' | 'redaction' | 'pages' | 'download' | 'print';
+export interface ThemeObject {
+    /** CSS custom properties applied to the viewer root, e.g. `{ '--pl-accent': '#2563eb' }`. */
+    [cssVariable: `--${string}`]: string;
+}
+export interface User {
+    id: string;
+    name: string;
+}
+export interface CollaborationOptions {
+    serverUrl: string;
+    roomId: string;
+}
+export interface ViewerOptions {
+    container: HTMLElement;
+    document: DocumentSource;
+    /**
+     * Your PDFCedar licence key (`PL1.…`). Checked offline against the page's domain; without a valid key the
+     * viewer runs in trial mode, with a watermark on the pages. Any valid key also works on localhost.
+     */
+    licenseKey?: string;
+    theme?: 'light' | 'dark' | ThemeObject;
+    toolbar?: ToolName[];
+    readOnly?: boolean;
+    user?: User;
+    collaboration?: CollaborationOptions;
+    /**
+     * URL of the folder holding PDFCedar's PDF engine files (a copy of `pdfcedar/dist/pdfjs/`).
+     * Only needed when your bundler doesn't serve them next to the PDFCedar bundle; by default they're
+     * found automatically. Applies to every viewer on the page.
+     */
+    assetBaseUrl?: string;
+    /**
+     * Where the user's saved signatures persist. Without it they're kept in memory for this page session
+     * (per user id); PDFCedar itself never writes them to browser storage.
+     */
+    signatureStore?: SignatureStore;
+    /**
+     * Password of a password-protected PDF. If it's missing or wrong, the viewer asks the user for it;
+     * `createViewer` rejects with `EncryptedDocumentError` if they cancel.
+     */
+    password?: string;
+    /** Headers sent when `document` is a URL, e.g. `{ Authorization: 'Bearer …' }` for files behind a login. */
+    httpHeaders?: Record<string, string>;
+    /** Send cookies when `document` is a URL on another origin (the server must allow credentials). */
+    withCredentials?: boolean;
+}
+/** A signature the user chose to reuse. */
+export interface SavedSignature {
+    id: string;
+    /** PNG or JPEG data URL. */
+    image: string;
+    /** ISO 8601 */
+    createdAt: string;
+}
+/** Persistence for saved signatures, provided by the app (e.g. its backend, per signed-in user). */
+export interface SignatureStore {
+    /** Called once, the first time the user opens the signature dialog. */
+    load(): SavedSignature[] | Promise<SavedSignature[]>;
+    /** Called with the full list after every change (a signature saved or removed). */
+    save(signatures: SavedSignature[]): void | Promise<void>;
+}
+/** A rectangle in PDF user space (points, origin bottom-left). */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface SearchResult {
+    page: number;
+    /** Index of the match within the page's text. */
+    index: number;
+    text: string;
+    rects: Rect[];
+}
+export type FitMode = 'width' | 'page';
+export type Rotation = 90 | 180 | 270;
+export type FormValues = Record<string, string | boolean | string[]>;
+export type ViewerEvents = AnnotationEvents & {
+    documentLoaded: {
+        pageCount: number;
+    };
+    pageChanged: {
+        page: number;
+        previousPage: number;
+    };
+    formFieldChanged: {
+        name: string;
+        value: FormValues[string];
+        source: ChangeSource;
+    };
+    signatureAdded: {
+        annotation: AnnotationJSON;
+    };
+    saved: {
+        bytes: Uint8Array;
+    };
+};
+export type ViewerEventName = keyof ViewerEvents;

package/dist/types/core/types.d.ts

@@ -38,6 +38,15 @@ export interface ViewerOptions {
      * (per user id); PDFCedar itself never writes them to browser storage.
      */
     signatureStore?: SignatureStore;
+    /**
+     * Password of a password-protected PDF. If it's missing or wrong, the viewer asks the user for it;
+     * `createViewer` rejects with `EncryptedDocumentError` if they cancel.
+     */
+    password?: string;
+    /** Headers sent when `document` is a URL, e.g. `{ Authorization: 'Bearer …' }` for files behind a login. */
+    httpHeaders?: Record<string, string>;
+    /** Send cookies when `document` is a URL on another origin (the server must allow credentials). */
+    withCredentials?: boolean;
 }
 /** A signature the user chose to reuse. */
 export interface SavedSignature {

package/dist/types/core/undo.d.cts

@@ -0,0 +1,47 @@
+/** A change that has already been applied and knows how to revert and re-apply itself. */
+export interface Command {
+    /** Shown in UIs, e.g. "Add highlight". */
+    label: string;
+    undo(): void;
+    redo(): void;
+}
+export interface UndoState {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string | null;
+    redoLabel: string | null;
+}
+/**
+ * Linear undo history shared by every kind of edit (annotations, pages, forms, signatures).
+ * Edits record a Command after applying themselves; `transaction` folds several into one step.
+ */
+export declare class UndoManager {
+    private readonly limit;
+    private readonly undoStack;
+    private redoStack;
+    /** Commands collected by the open transaction(s); null when none is open. */
+    private pending;
+    private depth;
+    /** Set while undoing/redoing, so the edits a replay triggers aren't recorded again. */
+    private replaying;
+    private untrackedDepth;
+    private readonly listeners;
+    constructor(limit?: number);
+    /** Which replay is running, if any. Lets edits report `source: 'undo' | 'redo'` in their events. */
+    get replayKind(): 'undo' | 'redo' | null;
+    get state(): UndoState;
+    record(command: Command): void;
+    /**
+     * Runs `fn`, recording everything it does as a single undo step. If `fn` throws, the changes it already
+     * made are rolled back and the error is rethrown, so a failed batch never leaves half an edit behind.
+     */
+    transaction<T>(label: string, fn: () => T): T;
+    /** Runs `fn` without recording anything, e.g. when loading a document's own annotations. */
+    untracked<T>(fn: () => T): T;
+    undo(): boolean;
+    redo(): boolean;
+    clear(): void;
+    onChange(listener: (state: UndoState) => void): () => void;
+    private replay;
+    private notify;
+}

package/dist/types/core/validate.d.cts

@@ -0,0 +1,22 @@
+import { type Annotation } from './annotations.cjs';
+import type { User } from './types.cjs';
+export declare class AnnotationValidationError extends TypeError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export interface NormalizeContext {
+    now(): string;
+    newId(): string;
+    user?: User | undefined;
+    /** When known, pages outside 1..pageCount are rejected. */
+    pageCount?: number | undefined;
+}
+/** Accepts #rgb or #rrggbb in any case; always returns lowercase #rrggbb. */
+export declare function normalizeColor(path: string, v: unknown): string;
+/**
+ * Validates `input` and fills defaults, returning a complete annotation. Throws AnnotationValidationError
+ * naming the offending field. `prefix` labels paths, e.g. "annotations[3]" during import.
+ */
+export declare function normalizeAnnotation(input: unknown, ctx: NormalizeContext, prefix?: string): Annotation;
+/** RFC 4122 v4. crypto.randomUUID only exists in secure contexts, so fall back to getRandomValues. */
+export declare function newId(): string;