@abyss-project/commons-front-core 3.0.0 → 3.1.0

package/dist/components/Inputs/DatePeriodPicker/date-period-picker.logic.d.ts

@@ -1,25 +1,79 @@
 import { Locale } from 'date-fns';
 export type EditingBound = 'start' | 'end';
+/**
+ * Time granularity of the resolved range.
+ *
+ * - `day` (default): bounds snap to start-of-day (start) / end-of-day (end). The
+ *   picker behaves as a day-only range picker — fully backward-compatible.
+ * - `minute`: bounds keep an explicit hour/minute and resolve to the exact
+ *   selected instant (no start/end-of-day snapping).
+ */
 export type DatePeriodGranularity = 'day' | 'minute';
 export type RangeUpdateInput = {
+    /** Which bound the user is currently editing. */
     editing: EditingBound;
+    /** The day the user just picked in the calendar. */
     picked: Date;
+    /** Current start bound (may be null/invalid). */
     startDate: Date | null;
+    /** Current end bound (may be null/invalid). */
     endDate: Date | null;
+    /**
+     * Time granularity. Defaults to `day` (snap to start/end of day). In `minute`
+     * mode the previously entered time is preserved when only the calendar day
+     * changes.
+     */
     granularity?: DatePeriodGranularity;
 };
 export type RangeUpdateResult = {
+    /** New start bound, or the previous reference when unchanged. */
     start: Date | null;
+    /** New end bound, or the previous reference when unchanged. */
     end: Date | null;
+    /** Whether the start reference changed. */
     startChanged: boolean;
+    /** Whether the end reference changed. */
     endChanged: boolean;
 };
 export type TimeChangeInput = {
+    /** Which bound the user is currently editing. */
     editing: EditingBound;
+    /** The value emitted by the time field (carries the new hour/minute). */
     time: Date;
+    /** Current start bound (may be null/invalid). */
     startDate: Date | null;
+    /** Current end bound (may be null/invalid). */
     endDate: Date | null;
 };
+/**
+ * Pure, independent range-bound update for a calendar day pick.
+ *
+ * Each bound is edited independently: editing the END never moves the START and
+ * vice-versa (fixes the "changing end also moves start" regression). The only
+ * coupling is a validation clamp guaranteeing `end >= start`:
+ * - editing `start` past `end` clamps the start down to `end` (end untouched);
+ * - editing `end` before `start` clamps the end up to `start` (start untouched).
+ *
+ * In `day` granularity (default) bounds are normalized to start-of-day (start) /
+ * end-of-day (end). In `minute` granularity the previously entered time is kept
+ * and only the calendar day changes; the range resolves to the exact instant.
+ */
 export declare const computeRangeUpdate: (input: RangeUpdateInput) => RangeUpdateResult;
+/**
+ * Pure time-of-day update (minute granularity only).
+ *
+ * Applies the hour/minute emitted by a time field to the edited bound while
+ * keeping that bound's calendar day. When the edited bound has no value yet, the
+ * time field's own day is used as the base. The same `end >= start` clamp as
+ * {@link computeRangeUpdate} keeps the range valid without moving the other bound.
+ */
 export declare const applyTimeChange: (input: TimeChangeInput) => RangeUpdateResult;
+/**
+ * Resolve a date-fns `Locale` from an app language code (e.g. the react-intl
+ * `intl.locale`). Defaults to English for unknown / missing codes.
+ *
+ * The specific locales are imported directly so they survive tree-shaking inside
+ * the commons bundle — the host's global `setDefaultOptions` never reaches the
+ * bundle's own date-fns copy, so locale must always be passed explicitly.
+ */
 export declare const resolveDateFnsLocale: (language?: string | null) => Locale;

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;
 }>;