@alfadocs/ui-kit 0.72.2 → 0.75.0

package/dist/components/data-table/data-table.d.ts

@@ -77,10 +77,7 @@ export declare const DataTable: (<TData = unknown>(props: DataTableProps<TData>
         Print: import("react").ForwardRefExoticComponent<Omit<import("..").IconButtonProps, "aria-label" | "onClick" | "tooltip" | "icon"> & {
             label?: string;
         } & import("react").RefAttributes<HTMLButtonElement>>;
-        ColumnToggle: {
-            ({ label, icon, footer, header }: import("./toolbar").ColumnToggleProps): import("react/jsx-runtime").JSX.Element;
-            displayName: string;
-        };
+        ColumnToggle: import("react").ForwardRefExoticComponent<import("./toolbar").ColumnToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
         BulkAction: import("react").ForwardRefExoticComponent<import("./toolbar").BulkActionProps & import("react").RefAttributes<HTMLButtonElement>>;
         QuickSearch: {
             ({ placeholder, debounceMs }: import("./toolbar").QuickSearchProps): import("react/jsx-runtime").JSX.Element;
@@ -92,10 +89,7 @@ export declare const DataTable: (<TData = unknown>(props: DataTableProps<TData>
             displayName: string;
         };
         FacetFilter: <TValue extends string | number | boolean = string>({ field, options, label, }: import("./toolbar").FacetFilterProps<TValue>) => import("react/jsx-runtime").JSX.Element;
-        ExportMenu: {
-            ({ children, label }: import("./toolbar").ExportMenuProps): import("react/jsx-runtime").JSX.Element;
-            displayName: string;
-        } & {
+        ExportMenu: import("react").ForwardRefExoticComponent<import("./toolbar").ExportMenuProps & import("react").RefAttributes<HTMLButtonElement>> & {
             Item: {
                 ({ format, label, onClick, fileName, }: import("./toolbar").ExportMenuItemProps): import("react/jsx-runtime").JSX.Element;
                 displayName: string;

package/dist/components/data-table/index.js

@@ -1,38 +1,39 @@
-import { A as r, C as l, D as t, a as s, b as n, c as o, I as d, L as i, N as C, d as R, S as F, e as T, f as g, T as b, g as u, h as c, i as m, j as h, k as x, l as D, U as f, m as p, n as y, o as E } from "../../_chunks/link-cell-renderer-BCppbMec.js";
-import { B as A, C as L, E as N, a as k, R as B, T as I, b as P, r as U, u as W } from "../../_chunks/editable-currency-cell-renderer-z9fJFw6Z.js";
+import { A as r, D as l, T as t, a as s, b as n, c as o, d, e as i, f as C } from "../../_chunks/actions-cell-renderer-DLrcSTK_.js";
+import { B as T, C as F, E as g, a as b, R as u, T as c, b as m, r as f, u as x } from "../../_chunks/editable-currency-cell-renderer-GwfA9tTR.js";
+import { C as p, D as h, a as y, b as E, I as S, L as A, N as L, c as N, S as B, d as I, e as P, T as U, f as W, g as k, U as v } from "../../_chunks/link-cell-renderer-BQGUs45d.js";
 export {
   r as ActionsCellRenderer,
-  A as BalanceCellRenderer,
-  L as ColorDotCellRenderer,
-  l as CurrencyCellRenderer,
-  t as DataTable,
-  s as DateCellRenderer,
-  n as DateRangeFilter,
-  o as DateRangeFloatingFilter,
-  N as EditableCurrencyCellRenderer,
-  k as EditableTextCellRenderer,
-  d as ImageCellRenderer,
-  i as LinkCellRenderer,
-  C as NumberFilter,
-  R as NumberFloatingFilter,
-  B as ReorderCellRenderer,
-  F as SelectFilter,
-  T as SelectFloatingFilter,
-  g as StatusCellRenderer,
-  b as TagListCellRenderer,
-  u as TextFilter,
-  c as TextFloatingFilter,
-  I as ToggleCellRenderer,
-  m as Toolbar,
-  h as ToolbarProvider,
-  P as ToothCellRenderer,
-  x as TypeaheadFilter,
-  D as TypeaheadFloatingFilter,
-  f as UserCellRenderer,
-  p as actionsColumnWidth,
-  y as dataTableAgent,
-  E as defaultExportPdf,
-  U as reorderColumnWidth,
-  W as useTotalRow
+  T as BalanceCellRenderer,
+  F as ColorDotCellRenderer,
+  p as CurrencyCellRenderer,
+  l as DataTable,
+  h as DateCellRenderer,
+  y as DateRangeFilter,
+  E as DateRangeFloatingFilter,
+  g as EditableCurrencyCellRenderer,
+  b as EditableTextCellRenderer,
+  S as ImageCellRenderer,
+  A as LinkCellRenderer,
+  L as NumberFilter,
+  N as NumberFloatingFilter,
+  u as ReorderCellRenderer,
+  B as SelectFilter,
+  I as SelectFloatingFilter,
+  P as StatusCellRenderer,
+  U as TagListCellRenderer,
+  t as TextFilter,
+  s as TextFloatingFilter,
+  c as ToggleCellRenderer,
+  n as Toolbar,
+  o as ToolbarProvider,
+  m as ToothCellRenderer,
+  W as TypeaheadFilter,
+  k as TypeaheadFloatingFilter,
+  v as UserCellRenderer,
+  d as actionsColumnWidth,
+  i as dataTableAgent,
+  C as defaultExportPdf,
+  f as reorderColumnWidth,
+  x as useTotalRow
 };
 //# sourceMappingURL=index.js.map

package/dist/components/data-table/toolbar.d.ts

@@ -74,15 +74,15 @@ export interface ExportMenuItemProps {
     /** File-name override (only used by built-in formats). */
     fileName?: string;
 }
-export interface ExportMenuProps {
+export interface ExportMenuProps extends Omit<IconButtonProps, 'icon' | 'aria-label' | 'tooltip' | 'onClick' | 'children'> {
     /** Custom menu items. When omitted, renders the default CSV+Excel+PDF trio. */
     children?: ReactNode;
     /** Accessible label for the trigger. */
     label?: string;
 }
-export interface ColumnToggleProps {
+export interface ColumnToggleProps extends Omit<IconButtonProps, 'icon' | 'aria-label' | 'tooltip' | 'onClick' | 'children'> {
     label?: string;
-    /** Override the trigger glyph (defaults to the Columns icon). */
+    /** Override the trigger glyph (defaults to the Columns3Cog icon). */
     icon?: ReactNode;
     /** Extra content rendered below the column list (e.g. a settings switch). */
     footer?: ReactNode;
@@ -107,10 +107,7 @@ export declare const Toolbar: import("react").ForwardRefExoticComponent<ToolbarR
         /** Accessible label — becomes the tooltip text and `aria-label`. */
         label?: string;
     } & import("react").RefAttributes<HTMLButtonElement>>;
-    ColumnToggle: {
-        ({ label, icon, footer, header }: ColumnToggleProps): import("react/jsx-runtime").JSX.Element;
-        displayName: string;
-    };
+    ColumnToggle: import("react").ForwardRefExoticComponent<ColumnToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
     BulkAction: import("react").ForwardRefExoticComponent<BulkActionProps & import("react").RefAttributes<HTMLButtonElement>>;
     QuickSearch: {
         ({ placeholder, debounceMs }: QuickSearchProps): import("react/jsx-runtime").JSX.Element;
@@ -122,10 +119,7 @@ export declare const Toolbar: import("react").ForwardRefExoticComponent<ToolbarR
         displayName: string;
     };
     FacetFilter: <TValue extends string | number | boolean = string>({ field, options, label, }: FacetFilterProps<TValue>) => import("react/jsx-runtime").JSX.Element;
-    ExportMenu: {
-        ({ children, label }: ExportMenuProps): import("react/jsx-runtime").JSX.Element;
-        displayName: string;
-    } & {
+    ExportMenu: import("react").ForwardRefExoticComponent<ExportMenuProps & import("react").RefAttributes<HTMLButtonElement>> & {
         Item: {
             ({ format, label, onClick, fileName, }: ExportMenuItemProps): import("react/jsx-runtime").JSX.Element;
             displayName: string;

package/dist/components/data-table-tabs/data-table-tabs.agent.d.ts

@@ -0,0 +1,4 @@
+import type { AgentAdapter } from '../../agent/types';
+import type { DataTableTabsHandle } from './data-table-tabs';
+export declare const dataTableTabsAgent: AgentAdapter<DataTableTabsHandle>;
+//# sourceMappingURL=data-table-tabs.agent.d.ts.map

package/dist/components/data-table-tabs/data-table-tabs.d.ts

@@ -0,0 +1,93 @@
+/**
+ * DataTableTabs — saved-filter folder tabs for any kit DataTable.
+ * ----------------------------------------------------------------------------
+ * A folder-tab strip attached above a table region. Each tab captures and
+ * restores its own AG Grid filter model (tabs are LIVE views — any filter
+ * edit rewrites the active tab); a "+" button saves the current filter as a
+ * new tab; tabs rename via double-click / F2 and remove via Delete/Backspace
+ * or the pointer-only ✕.
+ *
+ * ARIA: a real APG tablist built on Radix Tabs primitives with
+ * `activationMode="manual"` (arrow keys rove without applying filter models;
+ * Enter/Space activates). Every trigger points at ONE stable hand-rolled
+ * tabpanel that wraps `children` — the grid never remounts on tab switch and
+ * no dangling ARIA refs exist. The "+" button and the rename editor are
+ * SIBLINGS of the tablist (tablist purity).
+ *
+ * Grid wiring rides the narrow `DataTableTabsGridSeam` resolved at call time
+ * (`getTable={() => tableRef.current}`) — see use-data-table-filter-tabs.ts
+ * for the sync engine. Works against any `DataTableHandle`-shaped ref,
+ * including `PatientTableHandle`.
+ */
+import { type ReactNode } from 'react';
+import { type VariantProps } from 'class-variance-authority';
+import { type DataTableTabsGridSeam, type SavedTab } from './use-data-table-filter-tabs';
+export declare const dataTableTabsListVariants: (props?: ({
+    size?: "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const dataTableTabsTriggerVariants: (props?: ({
+    size?: "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Curated imperative handle — also the agent-adapter surface. */
+export interface DataTableTabsHandle {
+    getTabs: () => SavedTab[];
+    getActiveTabId: () => string | null;
+    /** Snapshots the outgoing tab, applies the incoming tab's filter model. */
+    selectTab: (id: string) => void;
+    /** Default model = a copy of the current live model (grid view unchanged). */
+    addTab: (label?: string, filterModel?: Record<string, unknown>) => string;
+    /** No-op on locked tabs and empty/whitespace labels. */
+    renameTab: (id: string, label: string) => void;
+    /** No-op on locked tabs and the last remaining tab. */
+    removeTab: (id: string) => void;
+}
+export interface DataTableTabsProps extends VariantProps<typeof dataTableTabsTriggerVariants> {
+    /**
+     * Resolve the grid seam at call time — `undefined` until the grid is ready
+     * (same convention as `ToolbarProvider.getApi`). Any `DataTableHandle`
+     * satisfies it: `getTable={() => tableRef.current}`.
+     */
+    getTable: () => DataTableTabsGridSeam | null | undefined;
+    /** Controlled tabs — pair with `onTabsChange`. */
+    tabs?: SavedTab[];
+    /** Uncontrolled seed. Default: one unfiltered tab. */
+    defaultTabs?: SavedTab[];
+    onTabsChange?: (tabs: SavedTab[]) => void;
+    activeTabId?: string;
+    defaultActiveTabId?: string;
+    onActiveTabChange?: (id: string) => void;
+    /**
+     * Opt-in localStorage persistence under `data-table-tabs:<persistKey>`.
+     * Ignored (with a DEV warning) while `tabs` is controlled. The active tab
+     * id is deliberately not persisted.
+     */
+    persistKey?: string;
+    /** Capture/restore the quick-filter text alongside the model. Default false. */
+    captureQuickFilter?: boolean;
+    /** Apply the active tab's model on mount + switch. Default true. */
+    applyOnActivate?: boolean;
+    /** Show the "+" button. Default true. */
+    allowAdd?: boolean;
+    /** Allow rename (double-click / F2 / popover editor). Default true. */
+    allowRename?: boolean;
+    /** Allow removal (Delete/Backspace / ✕). Default true. */
+    allowRemove?: boolean;
+    /** Tab cap — "+" disables at the cap. Default 8. */
+    maxTabs?: number;
+    /** Factory for new tabs; `index` is 1-based. */
+    createTab?: (index: number) => SavedTab;
+    /** Id factory — default `crypto.randomUUID()`. */
+    makeTabId?: () => string;
+    /** Open the rename editor on a freshly-added tab. Default true. */
+    renameOnAdd?: boolean;
+    /** `data-component-id` + agent instance id. */
+    id?: string;
+    className?: string;
+    /** Accessible tablist name — defaults to the localised "Saved views". */
+    'aria-label'?: string;
+    /** The table region — rendered inside the single stable tabpanel. */
+    children: ReactNode;
+}
+export declare const DataTableTabs: import("react").ForwardRefExoticComponent<DataTableTabsProps & import("react").RefAttributes<DataTableTabsHandle>>;
+export type { SavedTab, DataTableTabsGridSeam };
+//# sourceMappingURL=data-table-tabs.d.ts.map

package/dist/components/data-table-tabs/index.d.ts

@@ -0,0 +1,5 @@
+export { DataTableTabs, dataTableTabsListVariants, dataTableTabsTriggerVariants, } from './data-table-tabs';
+export type { DataTableTabsHandle, DataTableTabsProps, } from './data-table-tabs';
+export type { SavedTab, DataTableTabsGridSeam, } from './use-data-table-filter-tabs';
+export { dataTableTabsAgent } from './data-table-tabs.agent';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/data-table-tabs/index.js

@@ -0,0 +1,8 @@
+import { D as b, d as t, a as T, b as e } from "../../_chunks/data-table-tabs-BEUXiRlu.js";
+export {
+  b as DataTableTabs,
+  t as dataTableTabsAgent,
+  T as dataTableTabsListVariants,
+  e as dataTableTabsTriggerVariants
+};
+//# sourceMappingURL=index.js.map

package/dist/components/data-table-tabs/use-data-table-filter-tabs.d.ts

@@ -0,0 +1,63 @@
+import type { GridApi } from 'ag-grid-community';
+/** One saved-filter tab. */
+export interface SavedTab {
+    /** Opaque machine-generated id — emitted as `data-tab-id`, never the label. */
+    id: string;
+    /** User-typed name; rendered text only — never used in DOM hooks or keys. */
+    label: string;
+    /** AG Grid filter model (`DataTableHandle.getFilter()` shape); `{}` = none. */
+    filterModel: Record<string, unknown>;
+    /** Captured quick-filter text — only present when `captureQuickFilter`. */
+    quickFilter?: string;
+    /** Locked tabs cannot be renamed or removed (e.g. an "All" tab). */
+    locked?: boolean;
+}
+/**
+ * The narrow grid seam the tabs ride on. Structural, and `getRawApi` is
+ * deliberately typed against the un-parameterised `GridApi` so any
+ * `DataTableHandle<TData>` (incl. `PatientTableHandle`) satisfies it —
+ * `GridApi<TData>` is invariant, so pinning a row type here would reject
+ * every concretely-typed handle.
+ */
+export interface DataTableTabsGridSeam {
+    getFilter: () => Record<string, unknown>;
+    setFilter: (model: Record<string, unknown>) => void;
+    getRawApi: () => GridApi | undefined;
+}
+export interface UseDataTableFilterTabsOptions {
+    /** Resolve the grid seam at call time — `undefined` until grid-ready. */
+    getTable: () => DataTableTabsGridSeam | null | undefined;
+    tabs?: SavedTab[];
+    defaultTabs?: SavedTab[];
+    onTabsChange?: (tabs: SavedTab[]) => void;
+    activeTabId?: string;
+    defaultActiveTabId?: string;
+    onActiveTabChange?: (id: string) => void;
+    /** Opt-in localStorage persistence — disabled while `tabs` is controlled. */
+    persistKey?: string;
+    /** Capture/restore `quickFilterText` alongside the model. Default false. */
+    captureQuickFilter?: boolean;
+    /** Apply the active tab's model on mount + tab switch. Default true. */
+    applyOnActivate?: boolean;
+    /** Cap on the number of tabs. Default 8. */
+    maxTabs?: number;
+    /** Factory for a new tab; `index` is 1-based (used for the default name). */
+    createTab?: (index: number) => SavedTab;
+    /** Id factory — default `crypto.randomUUID()` with a counter fallback. */
+    makeTabId?: () => string;
+}
+export interface UseDataTableFilterTabsResult {
+    tabs: SavedTab[];
+    activeTabId: string;
+    selectTab: (id: string) => void;
+    addTab: (label?: string, filterModel?: Record<string, unknown>) => string;
+    renameTab: (id: string, label: string) => void;
+    removeTab: (id: string) => void;
+    atCapacity: boolean;
+    /** Synchronous snapshots for the imperative handle / agent adapter —
+     *  fresh immediately after a mutation, before React re-renders. */
+    getTabsSnapshot: () => SavedTab[];
+    getActiveTabIdSnapshot: () => string;
+}
+export declare function useDataTableFilterTabs(options: UseDataTableFilterTabsOptions): UseDataTableFilterTabsResult;
+//# sourceMappingURL=use-data-table-filter-tabs.d.ts.map

package/dist/components/date-picker/index.js

@@ -1,4 +1,4 @@
-import { D as r, d as t } from "../../_chunks/date-picker-CVkD_lOi.js";
+import { D as r, d as t } from "../../_chunks/date-picker-DzQS8mvt.js";
 export {
   r as DatePicker,
   t as datePickerAgent

package/dist/components/date-range-picker/index.js

@@ -1,4 +1,4 @@
-import { D as r, d as t } from "../../_chunks/date-range-picker-Dw12DgV8.js";
+import { D as r, d as t } from "../../_chunks/date-range-picker-Cbz1SKhm.js";
 export {
   r as DateRangePicker,
   t as dateRangePickerAgent

package/dist/components/date-time-picker/index.js

@@ -1,4 +1,4 @@
-import { D as i, d as r } from "../../_chunks/date-time-picker-Cd_OJtOy.js";
+import { D as i, d as r } from "../../_chunks/date-time-picker-B5IpU-nd.js";
 export {
   i as DateTimePicker,
   r as dateTimePickerAgent

package/dist/components/description-list/index.js

@@ -1,4 +1,4 @@
-import { D as r } from "../../_chunks/description-list-CmBVxIF5.js";
+import { D as r } from "../../_chunks/description-list-ClNLdRMy.js";
 export {
   r as DescriptionList
 };

package/dist/components/document-preview/document-preview.agent.d.ts

@@ -0,0 +1,4 @@
+import type { AgentAdapter } from '../../agent/types';
+import type { DocumentPreviewHandle } from './document-preview';
+export declare const documentPreviewAgent: AgentAdapter<DocumentPreviewHandle>;
+//# sourceMappingURL=document-preview.agent.d.ts.map

package/dist/components/document-preview/document-preview.d.ts

@@ -0,0 +1,41 @@
+import { type VariantProps } from 'class-variance-authority';
+export type DocumentPreviewSignatureStatus = 'none' | 'pending' | 'signed';
+/** Which render branch DocumentPreview is showing — structural, never PHI. */
+export type DocumentPreviewKind = 'pdf' | 'image' | 'metadata' | 'empty';
+export interface DocumentPreviewMetadata {
+    /** Size in bytes. */
+    size?: number;
+    /** ISO 8601 timestamp of the last modification. */
+    updatedAt?: string;
+    /** Open document-type category (non-identifying), e.g. `'xray'`. */
+    documentType?: string;
+    /** Signature workflow state. */
+    signatureStatus?: DocumentPreviewSignatureStatus;
+    /** Clinical-document flag (host-defined semantics). */
+    clinical?: boolean;
+    /** ISO 8601 expiry (e.g. identification documents). */
+    expiresAt?: string;
+}
+export interface DocumentPreviewProps extends VariantProps<typeof documentPreviewVariants> {
+    /** Opaque instance id — emitted as `data-component-id` for the agent registry. */
+    id?: string;
+    /** Display name. Absent → empty state. Treated as PHI by the agent contract. */
+    name?: string;
+    /** MIME type — drives the render branch and the fallback icon. */
+    mimeType?: string;
+    /** Resolved URL / data URI for the PDF or image viewer. The host owns auth. */
+    src?: string;
+    /** Structural metadata rendered by the metadata-card branch. */
+    metadata?: DocumentPreviewMetadata;
+    className?: string;
+}
+export interface DocumentPreviewHandle {
+    /** Which render branch is active — structural, safe for always-on reads. */
+    getKind: () => DocumentPreviewKind;
+    /** The document display name (PHI). Surfaced by the adapter as a `phi` action. */
+    getName: () => string | undefined;
+}
+declare const documentPreviewVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const DocumentPreview: import("react").ForwardRefExoticComponent<DocumentPreviewProps & import("react").RefAttributes<DocumentPreviewHandle>>;
+export {};
+//# sourceMappingURL=document-preview.d.ts.map

package/dist/components/document-preview/index.d.ts

@@ -0,0 +1,4 @@
+export { DocumentPreview } from './document-preview';
+export type { DocumentPreviewProps, DocumentPreviewHandle, DocumentPreviewKind, DocumentPreviewMetadata, DocumentPreviewSignatureStatus, } from './document-preview';
+export { documentPreviewAgent } from './document-preview.agent';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/document-preview/index.js

@@ -0,0 +1,6 @@
+import { D as r, d as t } from "../../_chunks/document-preview-CGSM_au9.js";
+export {
+  r as DocumentPreview,
+  t as documentPreviewAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/components/document-scanner/index.js

@@ -1,4 +1,4 @@
-import { D as a, d as c } from "../../_chunks/document-scanner-B23j4w7X.js";
+import { D as a, d as c } from "../../_chunks/document-scanner-B6h1Ir56.js";
 export {
   a as DocumentScanner,
   c as documentScannerAgent

package/dist/components/due-date-calculator/index.js

@@ -1,5 +1,5 @@
-import { D as e } from "../../_chunks/due-date-calculator-CmdAl_JO.js";
-import { C as r, a as o, D, G as _, M as T, T as M, c as E, b as l, g as C, p as A, r as N, d as i, t as n } from "../../_chunks/antenatal-schedule-timeline-CY-VsLok.js";
+import { D as e } from "../../_chunks/due-date-calculator-DASNRgnH.js";
+import { C as r, a as o, D, G as _, M as T, T as M, c as E, b as l, g as C, p as A, r as N, d as i, t as n } from "../../_chunks/antenatal-schedule-timeline-BzJZqS-8.js";
 export {
   r as CRL_DATING_MAX_MM,
   o as CRL_DATING_MIN_MM,

package/dist/components/editor-overlay/index.js

@@ -1,4 +1,4 @@
-import { E as a } from "../../_chunks/editor-overlay-BIOzr8v7.js";
+import { E as a } from "../../_chunks/editor-overlay-DE3esyio.js";
 export {
   a as EditorOverlay
 };

package/dist/components/empty-state/index.js

@@ -1,4 +1,4 @@
-import { E as e } from "../../_chunks/empty-state-BLy7tigq.js";
+import { E as e } from "../../_chunks/empty-state-CrLsi0XI.js";
 export {
   e as EmptyState
 };

package/dist/components/entity-summary/index.js

@@ -1,4 +1,4 @@
-import { E as t } from "../../_chunks/entity-summary-DpGziDv5.js";
+import { E as t } from "../../_chunks/entity-summary--vP698Jn.js";
 export {
   t as EntitySummary
 };

package/dist/components/face-scheme/face-scheme-data.d.ts

@@ -42,11 +42,24 @@ export interface FaceLandmark {
     x: number;
     y: number;
 }
+/** Axis-aligned box in view user units. */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface FaceView {
     id: FaceViewId;
     /** `faceScheme.view.<labelKey>` translation key. */
     labelKey: string;
     viewBox: string;
+    /** Photoless window: measured identity-affine mesh bbox + 24-unit pad,
+        pre-mirrored for the right profile. Re-measure if the mesh changes. */
+    schematicViewBox: string;
+    /** Raw identity-affine mesh bbox in LOCAL (un-mirrored) coords — the
+        auto-framing anchor. Same measurement as schematicViewBox, no pad. */
+    meshContentBox: Box;
     /** Pivot for the registration controls (the face centre). */
     pivot: Point;
     /** The face outline, drawn as a non-interactive guide. */
@@ -76,6 +89,109 @@ export interface FaceFinding {
 }
 /** Findings keyed by zone id. */
 export type FaceChart = Record<string, FaceFinding[]>;
+/** The drawing tools the annotation layer exposes. */
+export type FaceAnnotationTool = 'marker' | 'pen' | 'highlighter' | 'arrow' | 'line' | 'rect' | 'ellipse' | 'text';
+/** Toolbar order. */
+export declare const FACE_ANNOTATION_TOOLS: FaceAnnotationTool[];
+/** Shared fields on every annotation. `tone` is decorative reinforcement of the
+ *  KIND (shape / stroke style is the accessible channel), never colour alone. */
+interface FaceAnnotationBase {
+    /** Stable id — the kit generates one when the consumer doesn't supply it. */
+    id: string;
+    tone?: MarkerTone;
+    /** Linked clinical zone — a zone id, `null` = assessed outside every zone,
+     *  `undefined` = never assessed. Sticky: not re-assessed on mesh re-fit. */
+    zoneId?: string | null;
+}
+/** A shape glyph dropped at an arbitrary point (NOT snapped to a zone). */
+export interface MarkerAnnotation extends FaceAnnotationBase {
+    kind: 'marker';
+    x: number;
+    y: number;
+    shape: MarkerShape;
+}
+/** A freehand stroke — `pen` (opaque, thin) or `highlighter` (translucent, wide). */
+export interface InkAnnotation extends FaceAnnotationBase {
+    kind: 'pen' | 'highlighter';
+    points: Point[];
+}
+/** A two-point vector primitive drawn by dragging. */
+export interface ShapeAnnotation extends FaceAnnotationBase {
+    kind: 'arrow' | 'line' | 'rect' | 'ellipse';
+    from: Point;
+    to: Point;
+}
+/** A typed callout pinned to a point. `text` is PHI — never surfaced in the
+ *  agent snapshot, never persisted/logged/transmitted by the kit. */
+export interface TextAnnotation extends FaceAnnotationBase {
+    kind: 'text';
+    x: number;
+    y: number;
+    text: string;
+}
+export type FaceAnnotation = MarkerAnnotation | InkAnnotation | ShapeAnnotation | TextAnnotation;
+/** The distinct annotation kinds — the agent snapshot reports counts per kind. */
+export type FaceAnnotationKind = FaceAnnotation['kind'];
+/** An annotation as passed to `addAnnotation` — the `id` is optional (the kit
+ *  generates a stable one when omitted). */
+export type FaceAnnotationInput = (Omit<MarkerAnnotation, 'id'> & {
+    id?: string;
+}) | (Omit<InkAnnotation, 'id'> & {
+    id?: string;
+}) | (Omit<ShapeAnnotation, 'id'> & {
+    id?: string;
+}) | (Omit<TextAnnotation, 'id'> & {
+    id?: string;
+});
+/** Annotations keyed by view — each view draws over its own photo. */
+export type FaceAnnotations = Partial<Record<FaceViewId, FaceAnnotation[]>>;
+/** The annotation kind each tool produces. */
+export declare const ANNOTATION_TOOL_KIND: Record<FaceAnnotationTool, FaceAnnotationKind>;
+/** True when the tool draws by dragging between two points. */
+export declare function isShapeTool(tool: FaceAnnotationTool): boolean;
+/** True when the tool captures a freehand point stream. */
+export declare function isInkTool(tool: FaceAnnotationTool): boolean;
+/** True when the tool places a single-click annotation (marker / text). */
+export declare function isPointTool(tool: FaceAnnotationTool): boolean;
+/** SVG path `d` for a freehand point list (a polyline). Pure — no React/DOM. */
+export declare function inkPath(points: Point[]): string;
+/** SVG path `d` for a two-point shape (arrowhead drawn separately). Pure. */
+export declare function shapePath(kind: ShapeAnnotation['kind'], from: Point, to: Point): string;
+/** SVG path `d` for a two-barb arrowhead at `to`, pointing along from→to. Pure. */
+export declare function arrowHeadPath(from: Point, to: Point, size?: number): string;
+/** Axis-aligned bounding box of an annotation, in viewBox units. Pure. */
+export declare function annotationBBox(a: FaceAnnotation): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Bounding-box centre of an annotation — anchors its focus outline / label. */
+export declare function annotationAnchor(a: FaceAnnotation): Point;
+/** Stroke width of an annotation's invisible pointer hit clone, in viewBox units. */
+export declare const ANN_HIT_STROKE = 28;
+/** Pointer hit radius around a point annotation (marker), in viewBox units. */
+export declare const ANN_HIT_RADIUS = 26;
+export type AnnotationHitGeometry = {
+    type: 'stroke';
+    d: string;
+} | {
+    type: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    type: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Geometry for an annotation's transparent pointer hit target. Stroke kinds
+ * get a fat clone of their own path (hit on the stroke only — a hollow rect /
+ * ellipse interior stays click-through to the zones); marker gets a hit
+ * circle, text an estimated glyph box. Pure. */
+export declare function annotationHitGeometry(a: FaceAnnotation, textSize?: number): AnnotationHitGeometry;
 export type FaceAffine = readonly [
     number,
     number,
@@ -89,6 +205,56 @@ export declare const IDENTITY_AFFINE: FaceAffine;
 export type FaceRegistration = Partial<Record<FaceViewId, FaceAffine>>;
 export declare function affineToString(m: FaceAffine): string;
 export declare function applyAffine(m: FaceAffine, p: Point): Point;
+/** Inverse of a (non-degenerate) affine: photo space → mesh space. Pure. */
+export declare function invertAffine(m: FaceAffine): FaceAffine;
+/** Share of an auto-framed window the registered mesh occupies. 0.84 is the
+ *  front mesh's natural canvas fill, so the front keeps its full frame and
+ *  the profiles (smaller canvas share) zoom in to match it. */
+export declare const AUTO_FRAME_FRACTION = 0.84;
+/**
+ * Photo window that frames the registered mesh at a consistent size — the
+ * three-up "equal heads in equal cards" window. Transforms `meshBox` through
+ * `affine` (reflecting for the mirrored right profile), then returns a
+ * canvas-aspect window centred on the mesh, sized so the mesh fills
+ * `fraction` of it, shifted (never shrunk) to stay inside the canvas.
+ * Falls back to the full canvas when the window cannot fit or the input is
+ * degenerate. Pure; a window only — never a transform, so mesh, photo and
+ * annotation geometry are untouched.
+ */
+export declare function autoFrameViewBox(meshBox: Box, affine: FaceAffine, canvas: {
+    width: number;
+    height: number;
+}, opts?: {
+    mirror?: boolean;
+    fraction?: number;
+}): string;
+/** User zoom state: magnification `k` (1 = base window) plus the window
+ *  origin as fractions of the pannable range, so it survives base-window
+ *  changes (auto-frame recomputes, registration commits). */
+export interface FaceZoomState {
+    k: number;
+    fx: number;
+    fy: number;
+}
+export declare const FACE_ZOOM_MIN = 1;
+export declare const FACE_ZOOM_MAX = 8;
+export declare const FACE_ZOOM_RESET: FaceZoomState;
+/** Parse a `"x y w h"` viewBox string into a Box. */
+export declare function parseViewBox(vb: string): Box;
+/** Stringify a Box as a rounded viewBox value. */
+export declare function boxToViewBox(b: Box): string;
+/** The visible window for a zoom state: the base window shrunk by `k`,
+ *  positioned by the fractional origin. `k <= 1` returns the base. */
+export declare function composeZoomWindow(base: Box, z: FaceZoomState): Box;
+/** Zoom by `factor` keeping the user-space point `p` fixed in the window.
+ *  Clamped to [FACE_ZOOM_MIN, FACE_ZOOM_MAX] and to the base bounds. */
+export declare function zoomWindowAround(base: Box, z: FaceZoomState, p: {
+    x: number;
+    y: number;
+}, factor: number): FaceZoomState;
+/** Pan the zoom window by a user-space delta (drag the content by `dx,dy`
+ *  moves the window the opposite way), clamped to the base bounds. */
+export declare function panZoomWindow(base: Box, z: FaceZoomState, dx: number, dy: number): FaceZoomState;
 /** Editable decomposition of an affine about a pivot — what the numeric
  *  registration panel exposes. Angles are degrees. */
 export interface AffineParts {
@@ -110,4 +276,5 @@ export declare function decomposeAffine(m: FaceAffine, pivot: Point): AffinePart
  * Returns the identity if the system is degenerate.
  */
 export declare function solveAffine(src: Point[], dst: Point[]): FaceAffine;
+export {};
 //# sourceMappingURL=face-scheme-data.d.ts.map