@abyss-project/commons-front-core 2.6.2 → 3.0.1

package/dist/components/Inputs/DatePeriodPicker/date-period-presets.util.d.ts

@@ -2,6 +2,14 @@ export type DatePeriodPreset = {
     label: string;
     getRange: () => [Date, Date];
 };
+/** Translation keys backing the default presets. Both locale files define them. */
 export declare const DEFAULT_PRESET_KEYS: readonly ["inputs.period-picker.labels.presets.7d", "inputs.period-picker.labels.presets.30d", "inputs.period-picker.labels.presets.90d", "inputs.period-picker.labels.presets.month", "inputs.period-picker.labels.presets.year"];
 export type DefaultPresetKey = (typeof DEFAULT_PRESET_KEYS)[number];
+/**
+ * Default presets, labelled from the active translations.
+ *
+ * These labels used to be hardcoded English literals, so every screen that did
+ * not pass its own `presets` rendered "Month" and "Year" next to a French UI.
+ * The keys already existed in both locale files; only the wiring was missing.
+ */
 export declare const buildDefaultPresets: (translate: (id: DefaultPresetKey) => string) => DatePeriodPreset[];

package/dist/components/Inputs/LanguageFlagLabel/LanguageFlagLabel.component.d.ts

@@ -1,9 +1,22 @@
 import { default as React } from 'react';
 type Props = {
+    /** Language/locale code (e.g. ProjectLanguage.FRENCH) used to resolve the flag. */
     code: string;
+    /** Human-readable, already-translated language name (e.g. "Français"). */
     label: string;
+    /** Font size of the language name. Defaults to MUI body2. */
     variant?: 'body1' | 'body2' | 'caption';
+    /** Gap between the flag and the label (MUI spacing units). */
     gap?: number;
 };
+/**
+ * Reusable flag + language-name row. The flag is purely decorative
+ * (`aria-hidden`) and the readable label carries the accessible text, so screen
+ * readers announce the language name without the flag noise.
+ *
+ * Renders e.g. "🇫🇷 Français" instead of a bare code or "FR - France". Use it in
+ * any language picker (`Autocomplete` option, list item, selected value) so every
+ * abyss front renders language options the same way. See the README in this folder.
+ */
 export declare const LanguageFlagLabel: React.FC<Props>;
 export default LanguageFlagLabel;

package/dist/components/Inputs/LanguageFlagLabel/language-flags.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Single source of truth that maps a language/locale code to its country flag
+ * emoji. Flags are stored as escaped regional-indicator code points so the file
+ * stays ASCII-safe and unambiguous in review.
+ *
+ * Codes match the `ProjectLanguage` enum used across the ecosystem (spotlight,
+ * forms, etc.) so any app can render a language option as a flag + readable name
+ * instead of a bare code or a "FR - France" style label.
+ */
 export declare const LANGUAGE_FLAGS: Record<string, string>;
+/** Returns the flag emoji for a language/locale code, or '' when unknown. */
 export declare const getLanguageFlag: (language: string) => string;

package/dist/components/Inputs/PasswordInput/PasswordInput.component.d.ts

@@ -11,15 +11,31 @@ type Props = {
     size?: 'small' | 'medium';
     sx?: SxProps;
     disabled?: boolean;
+    /**
+     * Password-manager hint. ALWAYS set it on real auth forms — `current-password`
+     * on sign-in, `new-password` on sign-up / reset / change. Without it browsers
+     * both fail to offer the saved credential and fail to offer to save the new
+     * one, which pushes people toward weaker, memorable passwords.
+     */
     autoComplete?: string;
+    /** Helper or error text shown under the field. */
     helperText?: ReactNode;
     required?: boolean;
     autoFocus?: boolean;
     id?: string;
+    /**
+     * Raw props forwarded to the underlying `input`. Use for a11y wiring
+     * (`aria-describedby`, `aria-invalid`) that has no dedicated prop here.
+     */
     inputProps?: Record<string, unknown>;
     onKeyDown?: (e: KeyboardEvent<HTMLDivElement>) => void;
     onKeyUp?: (e: KeyboardEvent<HTMLDivElement>) => void;
     onBlur?: () => void;
 };
+/**
+ * Text field for a password, with a show/hide toggle.
+ *
+ * See README.md in this folder for the full surface and usage notes.
+ */
 declare const PasswordInput: FC<Props>;
 export default PasswordInput;

package/dist/components/Inputs/ProjectLinkSelector/index.d.ts

@@ -1,2 +1,2 @@
 export { default as ProjectLinkSelector } from './ProjectLinkSelector.component';
-export type { OrganizationOption, ProjectOption, ApplicationOption, LinkType } from './ProjectLinkSelector.component';
+export type { OrganizationOption, ProjectOption, ApplicationOption, LinkType, } from './ProjectLinkSelector.component';

package/dist/components/Layouts/AbyssBillingPlan/AbyssBillingPlan.component.d.ts

@@ -1,6 +1,8 @@
 import { default as React } from 'react';
 import { IPlanTemplate } from '@abyss-project/main';
 type Props = {
+    /** Omitted/null when the user has no explicit billing account → shown as the
+     *  free plan, so the "current plan" badge never silently disappears. */
     planTemplate?: IPlanTemplate | null;
     label?: string;
     abyssUrl?: string;

package/dist/components/Layouts/AbyssFamilyBanner/AbyssFamilyBanner.component.d.ts

@@ -12,8 +12,20 @@ type Props = {
     abyssUrl?: string;
     variant: FamilyBannerVariant;
 };
+/** Pure resolver — exported for unit testing (no JSX, no hooks). */
 export declare function resolveBannerState(currentFamily: CurrentFamilyInfo | null | undefined): FamilyBannerStatus;
+/**
+ * Pure CTA href resolver — exported for unit testing.
+ *
+ * When the user has no family (none state), returns the create-family onboarding
+ * URL (with `?intent=family` so the onboarding flow can pre-select the FAMILY
+ * user-type). When the user has a family, returns the org management URL.
+ */
 export declare function resolveCTAHref(currentFamily: CurrentFamilyInfo | null | undefined, abyssUrl: string | undefined): string;
+/**
+ * Pure layout descriptor — exported for unit testing.
+ * Returns structural properties that differ between footer and settings variants.
+ */
 export declare function resolveVariantLayout(variant: FamilyBannerVariant): {
     isCompact: boolean;
     showDescription: boolean;

package/dist/components/Layouts/AbyssLayoutProvider/index.d.ts

@@ -1,3 +1,3 @@
-export { AbyssLayoutProvider, useAbyssLayoutStore } from './AbyssLayoutProvider.component';
+export { AbyssLayoutProvider, useAbyssLayoutStore, } from './AbyssLayoutProvider.component';
 export { createAbyssLayoutStore } from './abyss-layout.store';
 export type { AbyssLayoutState, AbyssLayoutStore } from './abyss-layout.store';

package/dist/components/Layouts/AbyssSidebar/index.d.ts

@@ -1,3 +1,3 @@
 export { default as AbyssSidebar } from './AbyssSidebar.component';
-export type { AbyssSidebarItem, AbyssSidebarSection } from './AbyssSidebar.component';
-export { ABYSS_SIDEBAR_WIDTH, ABYSS_SIDEBAR_WIDTH_COLLAPSED } from './AbyssSidebar.component';
+export type { AbyssSidebarItem, AbyssSidebarSection, } from './AbyssSidebar.component';
+export { ABYSS_SIDEBAR_WIDTH, ABYSS_SIDEBAR_WIDTH_COLLAPSED, } from './AbyssSidebar.component';

package/dist/components/Modals/AbyssModal/AbyssModal.component.d.ts

@@ -1,7 +1,13 @@
 import { default as React } from 'react';
 import { DialogProps, SxProps } from '@mui/material';
 type Props = {
+    /**
+     * Opt out of the built-in close button. AbyssModal owns the single close
+     * button for every modal — consumers must NOT render their own. Set this only
+     * when the modal provides its own custom close affordance.
+     */
     hideCloseButton?: boolean;
+    /** @deprecated Use `hideCloseButton` instead. Kept as an alias for back-compat. */
     disableCloseButton?: boolean;
     sxCloseButton?: SxProps;
     onClose?: () => void;

package/dist/components/Modals/QRCodeModal/QRCodeModal.component.d.ts

@@ -5,6 +5,7 @@ type Props = {
     url: string;
     maskShareButton?: boolean;
     maskCopyButton?: boolean;
+    /** Called when the reset button is clicked */
     handleResetButton?: () => Promise<void>;
 };
 declare const QRCodeModal: React.FC<Props>;

package/dist/components/Modals/UserSettingsModal/UserSettingsModal.component.d.ts

@@ -17,6 +17,11 @@ export type UserSettingsValues = {
     name: string;
     familyName: string;
 };
+/**
+ * Exported for unit testing — no React deps.
+ * `overrideFamily` is the standalone `currentFamily` prop from the component;
+ * when provided it takes precedence, otherwise falls back to `user.currentFamily`.
+ */
 export declare function shouldRenderFamilyBanner(user: UserSettingsUser, overrideFamily?: UserSettingsUser['currentFamily']): boolean;
 type Props = {
     isOpen: boolean;

package/dist/components/Modals/UserSettingsModal/index.d.ts

@@ -1,2 +1,2 @@
 export { default as UserSettingsModal } from './UserSettingsModal.component';
-export type { UserSettingsUser, UserSettingsValues } from './UserSettingsModal.component';
+export type { UserSettingsUser, UserSettingsValues, } from './UserSettingsModal.component';

package/dist/components/PdfEditor/hooks/use-pdf-document.d.ts

@@ -1,5 +1,6 @@
 import { PDFDocumentProxy } from 'pdfjs-dist';
 import { PdfSource } from '../types';
+/** Decrypts password-protected bytes (e.g. via qpdf-WASM). */
 type Decryptor = (bytes: Uint8Array, password: string) => Promise<Uint8Array>;
 interface UsePdfDocumentResult {
     pdfDoc: PDFDocumentProxy | null;
@@ -7,10 +8,21 @@ interface UsePdfDocumentResult {
     pageCount: number;
     loading: boolean;
     error: Error | null;
+    /** True when the source is encrypted and a decryptor is available — the host
+     *  should prompt for a password and call `unlock`. */
     needsPassword: boolean;
+    /** True while a submitted password is being verified/applied. */
     unlocking: boolean;
+    /** True after the last `unlock` attempt failed (wrong password). */
     unlockFailed: boolean;
+    /** Decrypt the source with the given password and load it on success. */
     unlock: (password: string) => void;
 }
+/**
+ * Loads a PDF from a PdfSource and returns a PDFDocumentProxy and raw bytes.
+ *
+ * IMPORTANT: `source` must be a stable reference (useState, useMemo, or module-level constant).
+ * Passing an inline object literal will cause an infinite reload loop.
+ */
 export declare const usePdfDocument: (source: PdfSource | null, decryptor?: Decryptor) => UsePdfDocumentResult;
 export {};

package/dist/components/PdfEditor/hooks/use-uploaded-docs.d.ts

@@ -1,3 +1,12 @@
 import { PDFDocumentProxy } from 'pdfjs-dist';
 import { PdfOperation } from '../types';
+/**
+ * Loads each unique `uploadKey` referenced by PAGE_INSERT_FROM_UPLOAD ops
+ * into a PDFDocumentProxy. Returns a map keyed by uploadKey.
+ *
+ * Re-runs only when the set of uploadKeys changes. Keeps previously-committed
+ * docs alive across re-runs so that the renderer never sees a destroyed proxy
+ * mid-transition; old docs are released only after the new map is committed
+ * (or on unmount).
+ */
 export declare const useUploadedDocs: (operations: PdfOperation[]) => Map<string, PDFDocumentProxy>;

package/dist/components/PdfEditor/operations/actions.d.ts

@@ -1,9 +1,23 @@
 import { AcroFormField, EditorAction, PdfOperation, ToolKind } from '../types';
+/**
+ * Typed action creators for the editor reducer.
+ *
+ * Call sites read as intent (`dispatch(deleteOperation(id))`) instead of raw
+ * `dispatch({ type: 'DELETE_OPERATION', payload: { opId: id } })`, and the
+ * action shapes live in exactly one place so the reducer, the creators and the
+ * `EditorAction` union can never drift apart.
+ */
+/** Append a new operation (records an undo step). */
 export declare const addOperation: (operation: PdfOperation) => EditorAction;
+/** Append several operations as a single undo step. */
 export declare const addOperations: (operations: PdfOperation[]) => EditorAction;
+/** Fan a text/image op out to the given pages (records a single undo step). */
 export declare const addOperationAllPages: (operation: PdfOperation, pageIndices: number[]) => EditorAction;
+/** Replace an operation in place (records an undo step). */
 export declare const updateOperation: (opId: string, operation: PdfOperation) => EditorAction;
+/** Replace an operation in place WITHOUT recording history (drag frames). */
 export declare const moveOperation: (opId: string, operation: PdfOperation) => EditorAction;
+/** Remove an operation (records an undo step). */
 export declare const deleteOperation: (opId: string) => EditorAction;
 export declare const undo: () => EditorAction;
 export declare const redo: () => EditorAction;

package/dist/components/PdfEditor/operations/compute-page-order.d.ts

@@ -4,7 +4,18 @@ export interface InsertedPageRef {
     uploadKey: string;
     uploadPageIndex: number;
 }
+/**
+ * Maps each synthetic virtual index (>= numPages) to the uploaded page it represents.
+ * Allocation order: walk operations in array order; for each PAGE_INSERT_FROM_UPLOAD,
+ * allocate uploadPages.length consecutive synthetic indices starting at the next
+ * available counter (initial = numPages). The K-th allocated index corresponds to
+ * op.uploadPages[K].
+ */
 export declare function computeInsertionTable(numPages: number, operations: PdfOperation[]): Map<number, InsertedPageRef>;
+/**
+ * Maps each synthetic virtual index that represents an inserted BLANK page to its
+ * size. Allocation order matches computeInsertionTable / computePageOrder.
+ */
 export declare function computeBlankPages(numPages: number, operations: PdfOperation[]): Map<number, {
     widthPt: number;
     heightPt: number;

package/dist/components/PdfEditor/operations/extract.d.ts

@@ -1,2 +1,7 @@
 import { PdfOperation } from '../types';
+/**
+ * Bake the current edits, then produce a NEW PDF containing only the selected
+ * output pages (by display index, 0-based, in the order given). Used by
+ * extract / split.
+ */
 export declare const extractPages: (sourceBytes: Uint8Array, operations: PdfOperation[], keepDisplayIndices: number[]) => Promise<Uint8Array>;

package/dist/components/PdfEditor/operations/pdf-data-url.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Decode a `data:application/pdf;base64,...` URL into raw bytes.
+ * Works in Node (via Buffer) and in the browser (via atob).
+ */
 export declare const dataUrlToBytes: (dataUrl: string) => Uint8Array;
 export declare const isPdfDataUrl: (key: string) => boolean;

package/dist/components/PdfEditor/operations/rasterize.d.ts

@@ -1,3 +1,20 @@
 import { PDFDocumentProxy } from 'pdfjs-dist';
 import { PdfOperation } from '../types';
+/**
+ * Browser-only pre-bake step for TRUE redaction.
+ *
+ * For every page carrying ANNOTATE_REDACT regions, render the original page to a
+ * canvas (in unrotated content space), paint opaque black boxes over the redacted
+ * rectangles, and replace the page with that flattened image. The page's text and
+ * vector content underneath is destroyed — not merely hidden — so the redacted
+ * data cannot be recovered with copy/paste or a PDF text extractor.
+ *
+ * Pages without redaction are copied through untouched (vector, selectable text
+ * preserved). The original page count and order are kept, so downstream
+ * annotation ops (which key off the source page index) still map correctly.
+ *
+ * Caller must strip the ANNOTATE_REDACT ops before the main bake — they are
+ * already baked into the raster here. Returns the source bytes unchanged when
+ * there is nothing to redact.
+ */
 export declare const rasterizeRedactedPages: (sourceBytes: Uint8Array, pdfProxy: PDFDocumentProxy, operations: PdfOperation[]) => Promise<Uint8Array>;

package/dist/components/PdfEditor/operations/redact.d.ts

@@ -1,9 +1,17 @@
 import { PdfOperation } from '../types';
+/** A single rectangle to black out, in PDF points (top-left origin, content space). */
 export interface RedactRect {
     x: number;
     y: number;
     widthPt: number;
     heightPt: number;
 }
+/** True when at least one redaction op is present (cheap export-time check). */
 export declare const hasRedactions: (operations: PdfOperation[]) => boolean;
+/**
+ * Group every redaction region by its (virtual) source page index. Pages absent
+ * from the returned map carry no redaction and must NOT be rasterized — keeping
+ * them vector preserves quality and selectable text everywhere except the pages
+ * the user explicitly redacted.
+ */
 export declare const collectRedactions: (operations: PdfOperation[]) => Map<number, RedactRect[]>;

package/dist/components/PdfEditor/operations/rotate-coords.d.ts

@@ -1,19 +1,44 @@
+/**
+ * Pure geometry helpers for mapping points between a page's UNROTATED content
+ * space (top-left origin, y-down, PDF points) and the ROTATED view space the
+ * user actually sees and clicks on.
+ *
+ * The bake (`apply.ts`) always draws annotations in content space and then sets
+ * the page rotation, so the page content + annotations rotate together. To keep
+ * the on-screen preview identical to the baked output, the editor stores every
+ * annotation in content space and uses these helpers to (a) convert pointer
+ * input from view space back to content space on creation/drag, and (b) place
+ * the (content-space) annotations inside a single inner layer that is rotated as
+ * a whole to match the page (`innerLayerTransform`).
+ *
+ * All rotations are CLOCKWISE and assumed to be multiples of 90.
+ */
 export type Rotation = 0 | 90 | 180 | 270;
+/** Clamp any (possibly negative, possibly >360) multiple of 90 into 0/90/180/270. */
 export declare const normalizeRotation: (deg: number) => Rotation;
+/** Rendered (view) size of a content box once rotated. 90/270 swap w/h. */
 export declare const viewSize: (cw: number, ch: number, rotation: Rotation) => {
     w: number;
     h: number;
 };
+/** Content size from a rendered (view) size. Inverse of {@link viewSize}. */
 export declare const contentSize: (vw: number, vh: number, rotation: Rotation) => {
     w: number;
     h: number;
 };
+/** Map a point from unrotated content space to rotated view space (clockwise). */
 export declare const contentToView: (x: number, y: number, rotation: Rotation, cw: number, ch: number) => {
     x: number;
     y: number;
 };
+/** Map a point from rotated view space back to content space. Inverse of {@link contentToView}. */
 export declare const viewToContent: (x: number, y: number, rotation: Rotation, cw: number, ch: number) => {
     x: number;
     y: number;
 };
+/**
+ * CSS `transform` for an inner layer sized to the content box (CW x CH pixels,
+ * already scaled) so that, after a clockwise rotation about its top-left corner,
+ * it lands exactly over the rotated page canvas in the positive quadrant.
+ */
 export declare const innerLayerTransform: (rotation: Rotation, contentWidthPx: number, contentHeightPx: number) => string;

package/dist/components/PdfEditor/signature/SignaturePicker.d.ts

@@ -5,11 +5,14 @@ interface SignaturePickerProps {
     open: boolean;
     onClose: () => void;
     onCapture: (dataUrl: string) => void;
+    /** Called when the user picks a TEXT_BLOCK asset — receives raw text so the
+     *  host can switch to text-placement mode rather than image insertion. */
     onCaptureText?: (text: string) => void;
     assetPalette?: AssetPalette;
     onSaveSignature?: SaveSignatureFn;
     resolveAssetBytes?: ResolveAssetBytes;
     onAssetError?: (message: string) => void;
+    /** Optional URL to the host's "manage assets" page (Account → Assets). */
     manageAssetsUrl?: string;
 }
 export declare const SignaturePicker: React.FC<SignaturePickerProps>;

package/dist/components/PdfEditor/signature/SignatureSaveButton.d.ts

@@ -3,6 +3,9 @@ import { AssetPalette, SaveSignatureFn } from '../types';
 interface SignatureSaveButtonProps {
     dataUrl: string | null;
     onSave: SaveSignatureFn;
+    /** When provided and it contains at least one org bucket, a scope picker
+     *  appears in the save dialog so the user can target a personal OR an
+     *  organization asset. */
     assetPalette?: AssetPalette;
 }
 export declare const SignatureSaveButton: React.FC<SignatureSaveButtonProps>;

package/dist/components/PdfEditor/signature/resolve-asset.d.ts

@@ -1,3 +1,20 @@
 import { AssetPaletteItem } from '../types';
+/**
+ * Host-provided resolver that returns a usable data URL for a server-stored
+ * asset. Authenticated hosts implement this via a presigned download so it works
+ * cross-origin (a bare `fetch` of the storage public-access URL is CORS-blocked
+ * even though an `<img>` of the same URL renders fine).
+ */
 export type ResolveAssetBytes = (item: AssetPaletteItem) => Promise<string>;
+/**
+ * Resolve an asset palette item to a data URL ready to embed.
+ *
+ * - Prefers the host `resolver` (authenticated, cross-origin safe).
+ * - Falls back to a direct `fetch` of `downloadUrl` — correct for same-origin or
+ *   `data:` URLs (e.g. anonymous local signatures), which is why anonymous mode
+ *   works without a resolver.
+ *
+ * Throws on failure so callers can surface a visible error instead of silently
+ * doing nothing.
+ */
 export declare const resolveAssetDataUrl: (item: AssetPaletteItem, resolver?: ResolveAssetBytes) => Promise<string>;

package/dist/components/PdfEditor/tools/RedactTool.d.ts

@@ -1,2 +1,8 @@
 import { default as React } from 'react';
+/**
+ * Redaction is destructive: on export the affected pages are flattened to an
+ * image with opaque black boxes, so the underlying text/content is gone for
+ * good. The popover makes that consequence explicit before the user draws —
+ * there is no styling to configure, only the warning + how-to.
+ */
 export declare const RedactTool: React.FC;

package/dist/components/PdfEditor/tools/Toolbar.d.ts

@@ -16,6 +16,7 @@ interface ToolbarProps {
     resolveAssetBytes?: ResolveAssetBytes;
     onAssetError?: (message: string) => void;
     pendingApplyAllPages?: boolean;
+    /** Compact (narrow viewport): drop labels/filename so the bar never overflows. */
     compact?: boolean;
     sidebarOpen?: boolean;
     onToggleSidebar?: () => void;
@@ -23,12 +24,20 @@ interface ToolbarProps {
     onAddPageNumbers?: () => void;
     onWatermark?: () => void;
     onInsertImage?: () => void;
+    /** Insert an image picked from AbyssCloud (host-wired). */
     onInsertCloudImage?: () => void;
     onExtractPages?: () => void;
+    /** Host-provided (qpdf-WASM) actions — shown only when wired. */
     onProtect?: () => void;
     onCompress?: () => void;
+    /** True while a password/compress operation runs (disables those items). */
     securing?: boolean;
+    /** Options panel for the active tool (null when the tool has none). Rendered
+     *  in a popover anchored to the active tool button (bottom sheet on mobile). */
     toolOptions?: React.ReactNode;
+    /** True while a signature/image/text is armed for placement. The anchored
+     *  options popover is suppressed so it never covers the page the user must
+     *  click to drop it (a non-blocking placement banner takes over instead). */
     placementActive?: boolean;
 }
 export declare const Toolbar: React.FC<ToolbarProps>;

package/dist/components/PdfEditor/tools/tool-options-ui.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+/** Section label inside a tool-options popover (consistent across every tool). */
 export declare const OptionLabel: React.FC<{
     children: React.ReactNode;
 }>;

package/dist/components/PdfEditor/types.d.ts

@@ -2,7 +2,13 @@ import { ReactNode } from 'react';
 import { AssetKind } from '@abyss-project/main';
 import { ISpace, IFile } from '@abyss-project/cloud';
 import { SupportCloudImportProps } from '../Support/types';
+/**
+ * Wiring for cloud-backed insertions inside the editor (currently only the
+ * "Insert pages" button). Includes the standard cloud picker props plus a
+ * helper to materialize bytes from the picked file.
+ */
 export interface PdfEditorCloudImportProps extends SupportCloudImportProps {
+    /** Resolve the raw bytes for a picked cloud file (e.g. via presigned URL). */
     downloadCloudFile: (cloud: ISpace, file: IFile) => Promise<ArrayBuffer>;
 }
 export declare enum PdfOperationType {
@@ -38,8 +44,11 @@ export type PdfOperation = {
     text: string;
     fontSize: number;
     color: string;
+    /** Font family; default 'sans' (Helvetica). */
     fontFamily?: TextFontFamily;
+    /** 0..1; default 1. Used by watermarks. */
     opacity?: number;
+    /** Counter-clockwise degrees around the text anchor; default 0 (watermark). */
     rotationDeg?: number;
 } | {
     opId: string;
@@ -68,6 +77,7 @@ export type PdfOperation = {
     y2: number;
     color: string;
     strokeWidth: number;
+    /** Fill color for rect/ellipse (hex). null = no fill (outline only). */
     fill?: string | null;
 } | {
     opId: string;
@@ -120,6 +130,21 @@ export type PdfOperation = {
     opId: string;
     type: PdfOperationType.FLATTEN;
 };
+/**
+ * One variant of the operation union, addressed by its discriminant.
+ *
+ * `PdfOperation` is an anonymous union, so a value annotated with it is the WHOLE union: a
+ * spread like `{ ...op, x }` then fails, because most members carry no `x`. Callers that
+ * genuinely hold one variant (a test builder, a tool that only emits text) say so with this
+ * helper instead of widening and casting back.
+ */
+export type PdfOperationOf<T extends PdfOperationType> = Extract<PdfOperation, {
+    type: T;
+}>;
+/** The subset of operations that carry per-page coordinates. */
+export type PdfPageScopedOperation = Extract<PdfOperation, {
+    pageIndex: number;
+}>;
 export type ExportOption = 'DOWNLOAD' | 'CLOUD_NEW_FILE' | 'CLOUD_REPLACE';
 export type ExportRequest = {
     kind: 'DOWNLOAD';
@@ -219,14 +244,21 @@ export interface AssetPaletteItem {
     id: string;
     kind: AssetKind;
     name: string;
+    /** Full-resolution download URL for image-mode assets; null for text-mode
+     *  (TEXT_BLOCK or typed INITIALS). Used when placing the asset on the PDF. */
     downloadUrl: string | null;
+    /** Small (256x256) thumbnail URL — preferred for grid previews so the
+     *  picker stays light. Falls back to downloadUrl when null. */
     thumbnailUrl?: string | null;
+    /** Raw text payload — set for TEXT_BLOCK and typed-mode INITIALS. */
     textContent?: string | null;
 }
 export interface AssetPaletteOrgBucket {
     id: string;
     name: string;
     items: AssetPaletteItem[];
+    /** Optional pre-rendered avatar node (host-injected, e.g. OrganizationAvatar)
+     *  used by the scope selector inside the picker. */
     avatar?: ReactNode;
 }
 export interface AssetPaletteProjectBucket {
@@ -237,11 +269,23 @@ export interface AssetPaletteProjectBucket {
     avatar?: ReactNode;
 }
 export interface AssetPalette {
+    /** Personal assets (the current user's). */
     personal: AssetPaletteItem[];
+    /** Optional pre-rendered avatar for the personal bucket — used by the
+     *  picker's scope selector to keep visuals consistent with the host app. */
     personalAvatar?: ReactNode;
+    /** Optional org-scoped assets, one bucket per organization the user is a
+     *  member of. */
     organizations?: AssetPaletteOrgBucket[];
+    /** Optional project-scoped assets, one bucket per project the user has
+     *  access to. */
     projects?: AssetPaletteProjectBucket[];
 }
+/** Called when the user clicks "Save signature" in the picker.
+ *  The implementation uploads the dataUrl as a SIGNATURE/INITIALS/STAMP asset.
+ *  - `projectId` set → PROJECT scope (organizationId required too).
+ *  - `organizationId` set (no projectId) → ORG scope.
+ *  - neither set → personal (USER) scope. */
 export type SaveSignatureFn = (params: {
     dataUrl: string;
     kind: AssetKind;
@@ -249,29 +293,70 @@ export type SaveSignatureFn = (params: {
     organizationId?: string | null;
     projectId?: string | null;
 }) => Promise<void>;
+/**
+ * Optional callback invoked debounced (800ms) after operations change,
+ * carrying the FULL list of current operations since the last successful flush.
+ * Hosts wiring a custom persistence backend should dedupe by op.opId
+ * (idempotent). Leave undefined for pure client-side editing.
+ */
 export type OperationsAdapter = (params: {
     operations: PdfOperation[];
 }) => Promise<void>;
+/**
+ * Optional host-provided PDF post-processors. pdf-lib cannot write/strip
+ * encryption nor truly recompress, so these heavy operations are delegated to
+ * the host (which wires a WASM engine like qpdf). Keeping the engine in the host
+ * means the multi-MB WASM never bloats the shared bundle: only apps that opt in
+ * pay for it, and it loads lazily when the user actually runs the action. The
+ * editor surfaces each action only when its callback is provided.
+ */
 export interface PdfSecurity {
+    /** Encrypt the baked PDF with a user password; resolves to encrypted bytes. */
     setPassword?: (bytes: Uint8Array, password: string) => Promise<Uint8Array>;
+    /** Decrypt a password-protected PDF; resolves to plain bytes. */
     removePassword?: (bytes: Uint8Array, password: string) => Promise<Uint8Array>;
+    /** Recompress / optimize the baked PDF; resolves to the smaller bytes. */
     compress?: (bytes: Uint8Array) => Promise<Uint8Array>;
 }
 export interface PdfEditorProps {
     source: PdfSource;
     mode: PdfEditorMode;
+    /** Initial server-loaded operations (replayed on mount). */
     initialOperations?: PdfOperation[];
+    /** Persist new operations server-side (debounced 800ms). */
     operationsAdapter?: OperationsAdapter;
+    /** Authenticated-mode asset palette — enables Saved tab and Save button in SignaturePicker.
+     *  When omitted, the editor runs in anonymous mode (2-tab picker, no save action). */
     assetPalette?: AssetPalette;
+    /** Resolve a saved (server-stored) asset to a data URL ready to embed.
+     *  Authenticated hosts implement this via a presigned download so it works
+     *  cross-origin — a bare fetch of the storage public-access URL is CORS-blocked
+     *  even though an <img> of the same URL renders. When omitted, the editor falls
+     *  back to fetching `item.downloadUrl` (correct for anonymous local `data:` URLs). */
     resolveAssetBytes?: (item: AssetPaletteItem) => Promise<string>;
+    /** Surface a user-facing error (e.g. a toast) — used when an asset fails to
+     *  resolve so the failure is visible instead of silently doing nothing. */
     onAssetError?: (message: string) => void;
+    /** Callback to upload a new signature asset. Wire alongside assetPalette in authenticated mode. */
     onSaveSignature?: SaveSignatureFn;
     onExport: (request: ExportRequest) => Promise<void>;
     exportOptions: ExportOption[];
     readOnly?: boolean;
+    /** Optional: full cloud-import wiring. When provided, the page sidebar's
+     *  "Insert pages" button uses `ImportButton` (file + cloud picker). */
     cloudImport?: PdfEditorCloudImportProps;
+    /** Optional: deep-link to the host's asset management page (Account →
+     *  Assets). When set, the signature picker shows a "Manage" button. */
     manageAssetsUrl?: string;
+    /** Optional: when provided, the toolbar shows a "Change file" button that
+     *  invokes this callback. Hosts typically reset their PdfSource state so
+     *  the dropzone reappears. */
     onChangeSource?: () => void;
+    /** Optional: host-provided encryption/compression engine (e.g. qpdf-WASM).
+     *  Each provided callback adds its matching action to the document menu. */
     pdfSecurity?: PdfSecurity;
+    /** Optional: let the user pick an image from AbyssCloud to insert. Resolves to
+     *  a `data:` URL ready to place, or null if cancelled. When provided, the
+     *  Insert panel shows an "AbyssCloud" image source. */
     pickCloudImage?: () => Promise<string | null>;
 }