@alfadocs/ui-kit 1.4.16 → 1.5.0

package/dist/components/index.d.ts

@@ -196,6 +196,7 @@ export * from './sign-document';
 export * from './slot-grid';
 export * from './face-scheme';
 export * from './tooth-scheme';
+export * from './tooth-finding-palette';
 export * from './transaction-chip';
 export * from './whatsapp-button';
 export * from './workflow';

package/dist/components/periodontal-chart/index.js

@@ -1,4 +1,4 @@
-import { B as t, M as s, P as e, a as i, b as E, c as r, d as P, S as _, e as n, f as A, g as d, h as l, p as T, i as p, j as C, k as L, s as N, t as O, l as R } from "../../_chunks/periodontal-chart-brakjj0s.js";
+import { B as t, M as s, P as e, a as i, b as E, c as r, d as P, S as _, e as n, f as A, g as d, h as l, p as T, i as p, j as C, k as L, s as N, t as O, l as R } from "../../_chunks/periodontal-chart-C0nNQKKK.js";
 export {
   t as BLEEDING_WARN_PERCENT,
   s as MODERATE_POCKET_MM,

package/dist/components/tooth-finding-palette/index.d.ts

@@ -0,0 +1,4 @@
+export { ToothFindingPalette, toothFindingPaletteVariants, DEFAULT_FINDING_GROUPS, CUSTOM_FINDING_GROUP_ID, } from './tooth-finding-palette';
+export type { ToothFindingPaletteProps, ToothFindingPaletteHandle, ToothFindingPaletteGroup, } from './tooth-finding-palette';
+export { toothFindingPaletteAgent } from './tooth-finding-palette.agent';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/tooth-finding-palette/index.js

@@ -0,0 +1,9 @@
+import { C as e, D as n, T as o, t as i, a as s } from "../../_chunks/tooth-finding-palette-vqC-D2Ye.js";
+export {
+  e as CUSTOM_FINDING_GROUP_ID,
+  n as DEFAULT_FINDING_GROUPS,
+  o as ToothFindingPalette,
+  i as toothFindingPaletteAgent,
+  s as toothFindingPaletteVariants
+};
+//# sourceMappingURL=index.js.map

package/dist/components/tooth-finding-palette/tooth-finding-palette.agent.d.ts

@@ -0,0 +1,4 @@
+import type { AgentAdapter } from '../../agent/types';
+import type { ToothFindingPaletteHandle } from './tooth-finding-palette';
+export declare const toothFindingPaletteAgent: AgentAdapter<ToothFindingPaletteHandle>;
+//# sourceMappingURL=tooth-finding-palette.agent.d.ts.map

package/dist/components/tooth-finding-palette/tooth-finding-palette.d.ts

@@ -0,0 +1,89 @@
+import { type HTMLAttributes } from 'react';
+import { type ConditionDefinition, type ConditionId, type SymbolStatus } from '../tooth-scheme/tooth-data';
+/** One clinically-meaningful run of tools inside the palette. */
+export interface ToothFindingPaletteGroup {
+    /** Stable id — emitted as `data-group` and used for the default heading key. */
+    id: string;
+    /**
+     * Already-translated heading. Omit for a built-in group and the palette
+     * resolves `toothFindingPalette.group.<id>` instead; a custom group with no
+     * label and no matching key falls back to its own id.
+     */
+    label?: string;
+    /** Findings in this group, in render order. */
+    conditions: ConditionId[];
+}
+/**
+ * Curated imperative handle. Exposed as the `forwardRef` target so a future
+ * agent / MCP UI bridge can arm a tool without touching the DOM — see
+ * `tooth-finding-palette.agent.ts`. Everything here is transient tool state;
+ * no patient record is reachable through it.
+ */
+export interface ToothFindingPaletteHandle {
+    /** The armed finding id, or null when the palette is disarmed. */
+    getValue: () => ConditionId | null;
+    /** Arm a finding tool (or pass null to disarm). */
+    setValue: (condition: ConditionId | null) => void;
+    /** Disarm the palette. Charted findings are untouched. */
+    clear: () => void;
+    /** The status the next charted finding takes. */
+    getStatus: () => SymbolStatus;
+    setStatus: (status: SymbolStatus) => void;
+    /** Every finding id the palette currently offers, in render order. */
+    getTools: () => ConditionId[];
+    /** Move the roving tab stop (and focus) to a tool without arming it. */
+    focusTool: (condition: ConditionId) => void;
+}
+export interface ToothFindingPaletteProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'role' | 'color'> {
+    /** Controlled armed finding. `null` means "no tool armed". */
+    value?: ConditionId | null;
+    /** Initial armed finding when uncontrolled. */
+    defaultValue?: ConditionId | null;
+    /** Fires on every arm / disarm, including the toggle-off to `null`. */
+    onChange?: (condition: ConditionId | null) => void;
+    /**
+     * Which tools to show. Ignored when `groups` is supplied (order the groups
+     * instead). Omit both and the palette ships the default grouping of all
+     * built-in findings.
+     */
+    conditions?: ConditionId[];
+    /** Explicit grouping. Wins over `conditions`. */
+    groups?: ToothFindingPaletteGroup[];
+    /**
+     * Practice-defined findings. They resolve exactly as they do on the chart
+     * (registry → built-in → glyph fallback) and, under the default grouping,
+     * any id that is not a built-in is appended as a "Practice findings" group.
+     */
+    conditionRegistry?: ConditionDefinition[];
+    /** Show the planned / executed selector. Default `false`. */
+    showStatus?: boolean;
+    /** Controlled execution status. */
+    status?: SymbolStatus;
+    /** Initial execution status when uncontrolled. Default `'planned'`. */
+    defaultStatus?: SymbolStatus;
+    onStatusChange?: (status: SymbolStatus) => void;
+    /** Tile scale. Default `'md'`. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Wide bar (`'horizontal'`, default) or sidebar rail (`'vertical'`). */
+    orientation?: 'horizontal' | 'vertical';
+    /** Root the tooth renders are served from. Matches `ToothScheme`. */
+    assetBaseUrl?: string;
+    /** Disable every tool. */
+    disabled?: boolean;
+    /** Disable individual tools (e.g. findings this practice cannot chart). */
+    disabledConditions?: ConditionId[];
+    /** Accessible name for the toolbar. Falls back to a translated default. */
+    ariaLabel?: string;
+    /** Render the group headings. Default `true`. */
+    showGroupLabels?: boolean;
+    className?: string;
+}
+export declare const DEFAULT_FINDING_GROUPS: ToothFindingPaletteGroup[];
+/** Group id used for registry findings under the default grouping. */
+export declare const CUSTOM_FINDING_GROUP_ID = "custom";
+export declare const toothFindingPaletteVariants: (props?: ({
+    orientation?: "vertical" | "horizontal" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const ToothFindingPalette: import("react").ForwardRefExoticComponent<ToothFindingPaletteProps & import("react").RefAttributes<ToothFindingPaletteHandle>>;
+//# sourceMappingURL=tooth-finding-palette.d.ts.map

package/dist/components/tooth-scheme/index.d.ts

@@ -1,5 +1,5 @@
 export * from './tooth-scheme';
-export { FDI_TO_META, FDI_TO_UNIVERSAL, FDI_TO_PALMER, CONDITION_COLORS, CONDITION_TOKENS, CONDITION_SIDE_SYMBOL, CONDITION_PLAN_FOLDER, SURFACE_ASSET_NAME, toothImageUrl, conditionSymbolUrl, surfaceSymbolUrl, zonesForTooth, zoneSurface, zonePath, chartFromConditions, emptyChart, labelFor, layoutTeeth, layoutSpecials, specialsForRow, specialIconUrl, generalElement, isSpecialElement, SPECIAL_ELEMENTS, SPECIAL_BY_ID, } from './tooth-data';
-export type { Anatomy, Arch, Quadrant, Side, Surface, SurfaceZone, Projection, Radiograph, RadiographKind, SideSymbolSpec, SpecialElement, SpecialElementKind, PositionedSpecial, ToothMeta, PositionedTooth, } from './tooth-data';
+export { FDI_TO_META, FDI_TO_UNIVERSAL, FDI_TO_PALMER, CONDITION_COLORS, CONDITION_TOKENS, CONDITION_PART, CONDITION_SIDE_SYMBOL, CONDITION_PLAN_SYMBOL, CONDITION_PLAN_FOLDER, SURFACE_ASSET_NAME, TOOTH_CONDITIONS, INTRINSIC_CONDITIONS, STATUS_TOKENS, STATUS_COLORS, STATUS_OPACITY, FALLBACK_CONDITION_TOKEN, isBuiltInCondition, statusLabelKey, conditionLabelKey, conditionDefinition, conditionLabel, conditionColor, conditionPart, conditionGlyph, conditionHasArtwork, conditionSideSymbol, conditionPlanSymbol, conditionPlanFolder, symbolColor, symbolsForTooth, rootsForTooth, rootScreenSide, rootFileStem, toothImageUrl, conditionSymbolUrl, planSymbolUrl, surfaceSymbolUrl, zonesForTooth, zoneSurface, zonePath, chartFromConditions, chartFromSymbols, emptyChart, labelFor, layoutTeeth, layoutSpecials, specialsForRow, specialIconUrl, generalElement, isSpecialElement, SPECIAL_ELEMENTS, SPECIAL_BY_ID, } from './tooth-data';
+export type { Anatomy, Arch, Quadrant, Side, Surface, SurfaceZone, Projection, ViewMode, Radiograph, RadiographKind, SideSymbolSpec, SymbolTarget, SymbolRegion, SymbolLetter, SymbolPart, SymbolStatus, Root, RootFileStem, ConditionId, ConditionDefinition, ConditionRegistry, ConditionLabel, ToothSymbol, SpecialElement, SpecialElementKind, PositionedSpecial, ToothMeta, PositionedTooth, } from './tooth-data';
 export { toothSchemeAgent } from './tooth-scheme.agent';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/tooth-scheme/index.js

@@ -1,35 +1,62 @@
-import { T as o, t as e, r as t } from "../../_chunks/tooth-scheme-s0ipC0-Z.js";
-import { C as r, a as S, b as T, c as I, F as _, d as l, e as O, P as N, f as n, S as c, g as h, h as m, i as A, j as i, k as C, l as D, m as F, n as L, o as R, p, s as P, q as M, r as U, t as f, z as u, u as y, v as b } from "../../_chunks/tooth-data-BwuoKFf4.js";
+import { T as s, t, r as e } from "../../_chunks/tooth-scheme-BPXE1_3N.js";
+import { C as i, a as T, b as S, c as l, d as r, e as I, F as O, f as N, g as _, h as c, I as E, P as C, i as A, S as m, j as L, k as d, l as h, m as D, n as F, T as y, o as P, p as b, q as R, r as U, s as p, t as M, u, v as K, w as f, x as B, y as Y, z as H, A as g, B as z, D as w, E as x, G as V, H as k, J as G, K as j, L as q, M as v, N as J, O as Q, Q as W, R as X, U as Z, V as $, W as aa, X as oa, Y as sa, Z as ta, _ as ea, $ as na } from "../../_chunks/tooth-data-DR8Kdnup.js";
 export {
-  r as CONDITION_COLORS,
+  i as CONDITION_COLORS,
+  T as CONDITION_PART,
   S as CONDITION_PLAN_FOLDER,
-  T as CONDITION_SIDE_SYMBOL,
+  l as CONDITION_PLAN_SYMBOL,
+  r as CONDITION_SIDE_SYMBOL,
   I as CONDITION_TOKENS,
-  _ as FDI_TO_META,
-  l as FDI_TO_PALMER,
-  O as FDI_TO_UNIVERSAL,
-  N as PERMANENT_TEETH,
-  n as PRIMARY_TEETH,
-  c as SPECIAL_BY_ID,
-  h as SPECIAL_ELEMENTS,
-  m as SURFACE_ASSET_NAME,
-  o as ToothScheme,
-  A as chartFromConditions,
-  i as conditionSymbolUrl,
-  C as emptyChart,
-  D as generalElement,
-  F as isSpecialElement,
-  L as labelFor,
-  R as layoutSpecials,
-  p as layoutTeeth,
-  P as specialIconUrl,
-  M as specialsForRow,
-  U as surfaceSymbolUrl,
-  f as toothImageUrl,
-  e as toothSchemeAgent,
-  t as toothSchemeVariants,
-  u as zonePath,
-  y as zoneSurface,
-  b as zonesForTooth
+  O as FALLBACK_CONDITION_TOKEN,
+  N as FDI_TO_META,
+  _ as FDI_TO_PALMER,
+  c as FDI_TO_UNIVERSAL,
+  E as INTRINSIC_CONDITIONS,
+  C as PERMANENT_TEETH,
+  A as PRIMARY_TEETH,
+  m as SPECIAL_BY_ID,
+  L as SPECIAL_ELEMENTS,
+  d as STATUS_COLORS,
+  h as STATUS_OPACITY,
+  D as STATUS_TOKENS,
+  F as SURFACE_ASSET_NAME,
+  y as TOOTH_CONDITIONS,
+  s as ToothScheme,
+  P as chartFromConditions,
+  b as chartFromSymbols,
+  R as conditionColor,
+  U as conditionDefinition,
+  p as conditionGlyph,
+  M as conditionHasArtwork,
+  u as conditionLabel,
+  K as conditionLabelKey,
+  f as conditionPart,
+  B as conditionPlanFolder,
+  Y as conditionPlanSymbol,
+  H as conditionSideSymbol,
+  g as conditionSymbolUrl,
+  z as emptyChart,
+  w as generalElement,
+  x as isBuiltInCondition,
+  V as isSpecialElement,
+  k as labelFor,
+  G as layoutSpecials,
+  j as layoutTeeth,
+  q as planSymbolUrl,
+  v as rootFileStem,
+  J as rootScreenSide,
+  Q as rootsForTooth,
+  W as specialIconUrl,
+  X as specialsForRow,
+  Z as statusLabelKey,
+  $ as surfaceSymbolUrl,
+  aa as symbolColor,
+  oa as symbolsForTooth,
+  sa as toothImageUrl,
+  t as toothSchemeAgent,
+  e as toothSchemeVariants,
+  ta as zonePath,
+  ea as zoneSurface,
+  na as zonesForTooth
 };
 //# sourceMappingURL=index.js.map

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

@@ -3,10 +3,67 @@ export type Dentition = 'permanent' | 'primary' | 'mixed';
 export type Numbering = 'fdi' | 'universal' | 'palmer';
 export type ToothMode = 'interactive' | 'display';
 export type Surface = 'mesial' | 'distal' | 'occlusal' | 'buccal' | 'lingual';
-export type ToothCondition = 'caries' | 'filled' | 'crowned' | 'temporaryCrown' | 'bridge' | 'missing' | 'implant' | 'implantExtraction' | 'stub' | 'destroyed' | 'rootCanal';
+/**
+ * Built-in findings. `destroyed` is the platform's *radice persistente*
+ * (retained root); the id is frozen for backward compatibility but the label
+ * and docs read "Retained root" so the two systems describe the same thing.
+ * `xray` is the chartable radiograph SYMBOL — distinct from the `radiographs`
+ * image archive a tooth can also carry.
+ */
+export type ToothCondition = 'caries' | 'filled' | 'crowned' | 'temporaryCrown' | 'bridge' | 'missing' | 'implant' | 'implantExtraction' | 'stub' | 'destroyed' | 'rootCanal' | 'pin' | 'rootAmputation' | 'anchorage' | 'hook' | 'attachment' | 'mucogingivalSurgery' | 'periodontalSurgery' | 'curettage' | 'medication' | 'xray';
+/**
+ * Open condition id: a built-in, or an id from a consumer's condition registry.
+ * The `(string & {})` keeps editor autocomplete on the built-ins while still
+ * accepting a practice-defined finding.
+ */
+export type ConditionId = ToothCondition | (string & {});
+/** Which anatomical layer a symbol marks — mirrors the platform's `part`. */
+export type SymbolPart = 'element' | 'surface' | 'root';
+/** Planned vs already executed. Matches the Care Plan's blue/green convention. */
+export type SymbolStatus = 'planned' | 'executed';
+/**
+ * A tooth's roots, named anatomically; `'single'` covers every one-rooted
+ * tooth. For flank-mounted markers (anchorage, hook) `mesial` / `distal` select
+ * which SIDE of the tooth the marker sits on rather than a root proper.
+ */
+export type Root = 'mesial' | 'distal' | 'palatal' | 'buccal' | 'single';
+/**
+ * One charted finding. Unlike the legacy `conditions` + `surfaces` pair — where
+ * a single flat surface list is shared by every condition on the tooth — a
+ * symbol scopes its own surfaces and roots, so two fillings on one tooth (one
+ * mesial, one distal) are finally representable.
+ */
+export interface ToothSymbol {
+    /**
+     * Provenance — the platform's carePlanEntryId / findingEntryId. Lets a
+     * consumer route a click on the symbol back to the record that produced it.
+     */
+    id?: string;
+    condition: ConditionId;
+    /** Defaults to the condition's natural part (see `conditionPart`). */
+    part?: SymbolPart;
+    surfaces?: Surface[];
+    roots?: Root[];
+    /**
+     * Where a flank-mounted marker sits — the gingival surgeries ship
+     * `left` / `right` / `total` / `repeat` renders rather than per-root ones.
+     * Omitted, they fall back to `repeat`.
+     */
+    region?: SymbolRegion;
+    status?: SymbolStatus;
+    /** Per-practice colour override (a CSS colour or `var(--token)`). */
+    color?: string;
+    note?: string;
+}
 export interface ToothState {
     conditions: ToothCondition[];
     surfaces: Surface[];
+    /**
+     * Per-symbol findings. When present these WIN over `conditions`/`surfaces`;
+     * when absent `symbolsForTooth()` derives the equivalent list from them, so
+     * the renderer only ever walks one shape.
+     */
+    symbols?: ToothSymbol[];
     notes?: string;
 }
 export type ToothChart = Record<FdiId, ToothState>;
@@ -81,24 +138,150 @@ export declare const FDI_TO_PALMER: Record<FdiId, string>;
 export declare function assetFdi(meta: ToothMeta): FdiId;
 /** Render scale applied to a tooth image (primary teeth are smaller). */
 export declare const PRIMARY_TOOTH_SCALE = 0.72;
+/** Positional file stem used by the per-root `rootTreatment` renders. */
+export type RootFileStem = 'full' | 'left' | 'right' | 'center';
+/**
+ * The roots a tooth's artwork distinguishes: upper molars are three-rooted
+ * (mesial, distal, palatal), lower molars two-rooted, everything else renders
+ * as one root. Derived from `assetFdi` rather than `meta.anatomy` because a
+ * primary molar reuses PREMOLAR art (54 draws 14) and so has one root's worth
+ * of renders. The upper first premolars 14/24 are treated as single-rooted for
+ * the same reason — clinically they are often bifurcated, but no second render
+ * ships, and a wrong answer here resolves to a file that does not exist.
+ */
+export declare function rootsForTooth(meta: ToothMeta): Root[];
+/**
+ * Which SCREEN side a tooth's mesial or distal root faces. The chart is FIXED
+ * to clinical orientation — the patient's right sits on the viewer's left in
+ * BOTH arches — so the midline falls on the viewer's RIGHT for the patient's
+ * right quadrants (1 & 4) and on the viewer's LEFT for the patient's left
+ * quadrants (2 & 3). Mesial means "toward the midline", so it flips with it;
+ * distal is always its opposite. This is the same flip `zoneSurface` applies
+ * to the plan view's left/right zones. Primary quadrants normalise (5-8 → 1-4).
+ */
+export declare function rootScreenSide(meta: ToothMeta, root: 'mesial' | 'distal'): 'left' | 'right';
+/**
+ * Map an anatomical root to the `rootTreatment` file stem. `center` is the
+ * palatal root and ships for upper molars only; a root the tooth does not
+ * distinguish falls back to the whole-tooth render rather than a dead URL.
+ */
+export declare function rootFileStem(meta: ToothMeta, root: Root): RootFileStem;
 /** CSS variable name (without the leading `var(...)`) that drives a condition's colour. */
 export declare const CONDITION_TOKENS: Record<ToothCondition, string>;
 /**
  * Convenience: the `fill="var(--destructive)"` string ready to paste onto
- * an SVG attribute. Kept in sync with `CONDITION_TOKENS`. Used for the legend
- * swatch + the surface-condition ring; whole-tooth conditions render a
- * distinct symbol image (the glyph is the colour-independent channel).
+ * an SVG attribute. DERIVED from `CONDITION_TOKENS` so the two can never drift.
+ * Used for the legend swatch + the surface-condition ring; whole-tooth
+ * conditions render a distinct symbol image (the glyph is the
+ * colour-independent channel).
  */
 export declare const CONDITION_COLORS: Record<ToothCondition, string>;
-export interface SideSymbolSpec {
-    /** Asset folder under `side/`. */
+/**
+ * Every built-in condition id, in declaration order. Derived from
+ * `CONDITION_TOKENS`, which the compiler forces to be exhaustive — so a new
+ * condition can never silently fall out of a hand-maintained list.
+ */
+export declare const TOOTH_CONDITIONS: ToothCondition[];
+/** True when an id names a built-in condition rather than a registry entry. */
+export declare function isBuiltInCondition(id: ConditionId): id is ToothCondition;
+/** The layer each built-in finding marks, used when a symbol omits `part`. */
+export declare const CONDITION_PART: Record<ToothCondition, SymbolPart>;
+/**
+ * Built-ins the chart draws ITSELF rather than from artwork — `missing` is an
+ * SVG cross, `caries` / `filled` fall back to the surface ring in the side
+ * view. They must never take the registry's glyph badge.
+ */
+export declare const INTRINSIC_CONDITIONS: ToothCondition[];
+export declare const STATUS_TOKENS: Record<SymbolStatus, string>;
+/** The `var(...)` form of `STATUS_TOKENS`, ready for an SVG attribute. */
+export declare const STATUS_COLORS: Record<SymbolStatus, string>;
+/** The second, non-colour channel: a planned symbol renders lighter. */
+export declare const STATUS_OPACITY: Record<SymbolStatus, number>;
+/** i18n key for a status label (`ui.toothScheme.status.*`). */
+export declare function statusLabelKey(status: SymbolStatus): string;
+/**
+ * Screen-relative marker slot. `repeat` is what the BARE gingival-surgery type
+ * resolves to — it is the default marker, not a "repeat treatment" variant.
+ */
+export type SymbolRegion = 'left' | 'right' | 'total' | 'repeat';
+/** Corner glyph stem in `side/other/` — curettage, medication, x-ray. */
+export type SymbolLetter = 'c' | 'm' | 'x';
+/**
+ * How a symbol's file resolves inside `{folder}/{view}/`. A discriminated union
+ * rather than a bare enum because two shapes carry their own data: `per-fdi-root`
+ * has to know whether a multi-rooted tooth also ships a whole-tooth render, and
+ * `letter` pins the single glyph its condition owns.
+ */
+export type SideSymbolSpec = 
+/** `{fdi}.webp` — one render per tooth. */
+{
     folder: string;
-    /** How the file resolves inside `{folder}/{view}/`. */
-    resolve: 'per-fdi' | 'general' | 'rct';
+    resolve: 'per-fdi';
+}
+/** `general.webp` — one render per arch. */
+ | {
+    folder: string;
+    resolve: 'general';
+}
+/** `{fdi}/{full|left|right|center}.webp` — per-FDI subdirectory. */
+ | {
+    folder: string;
+    resolve: 'rct';
+}
+/**
+ * `{fdi}[-{mesial|distal|palatal}].webp`. `wholeTooth` distinguishes two
+ * folders that look symmetric and are not: `pin` ships a bare file for every
+ * FDI, `rootAmputation` only for single-rooted teeth.
+ */
+ | {
+    folder: string;
+    resolve: 'per-fdi-root';
+    wholeTooth: 'always' | 'single-rooted-only';
+}
+/** `{fdi}-{mesial|distal}.webp` — always suffixed, no bare file. */
+ | {
+    folder: string;
+    resolve: 'per-fdi-side';
+}
+/** `{fdi}_{left|right}.webp` — the only folder using an UNDERSCORE. */
+ | {
+    folder: string;
+    resolve: 'per-fdi-lr';
+}
+/** `{left|right|total|repeat}.webp` — no FDI in the name. */
+ | {
+    folder: string;
+    resolve: 'region';
+}
+/** `{left|right}.webp` — no FDI, and only the two sides ship. */
+ | {
+    folder: string;
+    resolve: 'screen-side';
+}
+/** `{c|m|x}.webp`. */
+ | {
+    folder: string;
+    resolve: 'letter';
+    letter: SymbolLetter;
+};
+/**
+ * Which instance of a symbol to resolve. The two fields are independent
+ * discriminators read by different `resolve` strategies (roots by the per-root
+ * shapes, regions by the screen-side ones) — passed in, never module state.
+ */
+export interface SymbolTarget {
+    /** Root, or tooth side for a flank-mounted marker. */
+    root?: Root;
+    /** Explicit screen-relative slot; wins over `root` where both apply. */
+    region?: SymbolRegion;
 }
 export declare const CONDITION_SIDE_SYMBOL: Partial<Record<ToothCondition, SideSymbolSpec>>;
-/** Resolve the side-view symbol overlay URL for a condition on a tooth. */
-export declare function conditionSymbolUrl(meta: ToothMeta, assetBaseUrl: string, spec: SideSymbolSpec): string;
+/**
+ * Resolve the side-view symbol overlay URL for a condition on a tooth. `target`
+ * picks a specific root / side; omitted, every strategy resolves to the
+ * whole-tooth or default marker, which is what the legacy call sites want.
+ */
+export declare function conditionSymbolUrl(meta: ToothMeta, assetBaseUrl: string, spec: SideSymbolSpec, target?: SymbolTarget): string;
 export type Projection = 'side' | 'plan';
 /** The user-selectable view: a single projection, or both stacked together. */
 export type ViewMode = Projection | 'both';
@@ -108,6 +291,84 @@ export declare const SURFACE_ASSET_NAME: Record<Surface, string>;
 export declare const CONDITION_PLAN_FOLDER: Partial<Record<ToothCondition, string>>;
 /** Resolve a per-surface plan-view overlay URL (e.g. caries on the distal). */
 export declare function surfaceSymbolUrl(meta: ToothMeta, assetBaseUrl: string, folder: string, surface: Surface): string;
+/**
+ * Whole-tooth symbols in the PLAN projection. Without these a crowned tooth
+ * reads as a plain tooth in the occlusal view, which also made `projection`
+ * `'both'` disagree with itself between its own rows.
+ *
+ * `anchorage` is the odd one: the plan art is two generic screen-side markers
+ * (no FDI in the name) composited over the default render, so its mesial/distal
+ * root has to be flipped through the quadrant — `symbolUrl` does that.
+ */
+export declare const CONDITION_PLAN_SYMBOL: Partial<Record<ToothCondition, SideSymbolSpec>>;
+/** Resolve the plan-view whole-tooth symbol overlay URL for a condition. */
+export declare function planSymbolUrl(meta: ToothMeta, assetBaseUrl: string, spec: SideSymbolSpec, target?: SymbolTarget): string;
+/**
+ * How much to scale a plan overlay so its tooth registers with the base render.
+ * `1` for everything on the standard canvas.
+ */
+export declare function planOverlayScale(url: string): number;
+export interface ConditionDefinition {
+    id: string;
+    /** Already-translated label — the CONSUMER owns custom-condition copy. */
+    label: string;
+    color?: string;
+    part?: SymbolPart;
+    sideSymbol?: SideSymbolSpec;
+    planSymbol?: SideSymbolSpec;
+    planFolder?: string;
+    /** 1–3 char mark rendered when the condition has no artwork. */
+    glyph?: string;
+}
+export type ConditionRegistry = readonly ConditionDefinition[];
+/**
+ * A condition's display name. Built-ins resolve to an i18n key; registry
+ * entries carry literal text, because their copy lives in the consuming app.
+ */
+export type ConditionLabel = {
+    kind: 'key';
+    key: string;
+} | {
+    kind: 'text';
+    text: string;
+};
+/** Colour used when a condition is neither registered nor built in. */
+export declare const FALLBACK_CONDITION_TOKEN = "--muted-foreground";
+/** i18n key for a built-in condition label (`ui.toothScheme.condition.*`). */
+export declare function conditionLabelKey(condition: ToothCondition): string;
+/**
+ * Look up a registry entry. Registry ids shadow built-ins field by field, so a
+ * practice can re-tint or re-label a shipped finding without losing its art.
+ */
+export declare function conditionDefinition(condition: ConditionId, registry?: ConditionRegistry): ConditionDefinition | undefined;
+export declare function conditionLabel(condition: ConditionId, registry?: ConditionRegistry): ConditionLabel;
+/** Paintable colour for a condition — never empty, so nothing renders unseen. */
+export declare function conditionColor(condition: ConditionId, registry?: ConditionRegistry): string;
+/** Paint colour for ONE charted symbol — its own override wins. */
+export declare function symbolColor(symbol: ToothSymbol, registry?: ConditionRegistry): string;
+export declare function conditionSideSymbol(condition: ConditionId, registry?: ConditionRegistry): SideSymbolSpec | undefined;
+export declare function conditionPlanSymbol(condition: ConditionId, registry?: ConditionRegistry): SideSymbolSpec | undefined;
+export declare function conditionPlanFolder(condition: ConditionId, registry?: ConditionRegistry): string | undefined;
+export declare function conditionPart(condition: ConditionId, registry?: ConditionRegistry): SymbolPart;
+/**
+ * The 1–3 character mark that stands in when a condition ships no artwork.
+ * Falls back to the id's initials so a practice-defined finding can be charted
+ * the day it is registered, rather than rendering as a silent blank.
+ */
+export declare function conditionGlyph(condition: ConditionId, registry?: ConditionRegistry): string;
+/**
+ * Whether a condition has artwork in a projection. When false the renderer
+ * must fall back to the glyph badge — that seam is what lets a practice chart
+ * a finding before a designer draws it.
+ */
+export declare function conditionHasArtwork(condition: ConditionId, projection: Projection, registry?: ConditionRegistry): boolean;
+/**
+ * The findings on a tooth as a symbol list. `state.symbols` wins outright when
+ * present (an explicit empty array therefore means "no findings"); otherwise
+ * the legacy pair is derived faithfully — the shared `surfaces` list attaches
+ * only to surface-part conditions, exactly as the flat renderer treated it.
+ */
+export declare function symbolsForTooth(state: ToothState | undefined, registry?: ConditionRegistry): ToothSymbol[];
 /**
  * Clickable surface regions of a plan-view tooth, named by SCREEN position.
  * `zoneSurface()` resolves each to the anatomical `Surface` per quadrant.
@@ -260,4 +521,12 @@ export declare function layoutSpecials(specials: SpecialElement[], teethWidth: n
 export declare function labelFor(id: FdiId, numbering: Numbering): string;
 export declare function emptyChart(): ToothChart;
 export declare function chartFromConditions(conditions: Partial<Record<FdiId, ToothCondition[]>>): ToothChart;
+/**
+ * Build a chart from the richer per-symbol shape. Each entry also projects its
+ * built-in conditions and surfaces back onto the legacy pair so readers that
+ * predate `symbols` (the first-condition `data-condition`, the periodontal
+ * chart, the care-plan card) still see the tooth. Registry ids are omitted from
+ * that projection — a legacy reader does not know the custom vocabulary.
+ */
+export declare function chartFromSymbols(symbols: Partial<Record<FdiId, ToothSymbol[]>>): ToothChart;
 //# sourceMappingURL=tooth-data.d.ts.map

package/dist/components/tooth-scheme/tooth-scheme.agent.d.ts

@@ -1,6 +1,6 @@
 import type { AgentAdapter } from '../../agent/types';
 import type { ToothSchemeHandle } from './tooth-scheme';
-import type { Radiograph, Surface, ToothCondition } from './tooth-data';
+import type { ConditionId, Radiograph, RadiographKind, Root, Surface, SymbolPart, SymbolStatus, ToothCondition, ToothSymbol } from './tooth-data';
 export declare const toothSchemeAgent: AgentAdapter<ToothSchemeHandle>;
-export type { Radiograph, Surface, ToothCondition };
+export type { ConditionId, Radiograph, RadiographKind, Root, Surface, SymbolPart, SymbolStatus, ToothCondition, ToothSymbol, };
 //# sourceMappingURL=tooth-scheme.agent.d.ts.map

package/dist/components/tooth-scheme/tooth-scheme.d.ts

@@ -1,4 +1,4 @@
-import { PERMANENT_TEETH, PRIMARY_TEETH, type Arch, type ViewMode, type Dentition, type FdiId, type Numbering, type Radiograph, type Surface, type ToothChart, type ToothCondition, type ToothMode } from './tooth-data';
+import { PERMANENT_TEETH, PRIMARY_TEETH, type Arch, type ConditionDefinition, type ConditionId, type ToothSymbol, type ViewMode, type Dentition, type FdiId, type Numbering, type Radiograph, type Surface, type ToothChart, type ToothCondition, type ToothMode } from './tooth-data';
 export interface ToothSchemeProps {
     /** Opaque instance id — emitted as `data-component-id` for the agent registry. */
     id?: string;
@@ -67,8 +67,22 @@ export interface ToothSchemeProps {
      * The finding a tooth-click applies in interactive mode (the selected
      * tool in a Findings / "Stato dentale" panel). Clicking a tooth toggles
      * this condition. When unset, clicking cycles caries on/off.
+     *
+     * A surface-part tool (caries / filled) drills into the tooth's surfaces in
+     * the occlusal view; a root-part tool (root canal, post, apicectomy) drills
+     * into the roots of a multi-rooted tooth in the facial view. Accepts a
+     * `conditionRegistry` id as well as a built-in.
+     */
+    activeCondition?: ConditionId;
+    /**
+     * Practice-defined findings, resolved AHEAD of the built-in vocabulary field
+     * by field — so an entry may re-tint or re-label a shipped finding without
+     * losing its artwork, or add a wholly new one. An entry with no artwork
+     * renders its `glyph` badge, which is the seam that lets a practice chart a
+     * finding before a designer draws it. Labels are already-translated text:
+     * the consuming app owns custom-condition copy, not the kit.
      */
-    activeCondition?: ToothCondition;
+    conditionRegistry?: ConditionDefinition[];
     /**
      * Base URL the photoreal tooth renders are served from. Resolves to
      * `${assetBaseUrl}/{side|plan}/{symbol}/{top|bottom}/{fdi}.webp`. Defaults
@@ -132,12 +146,25 @@ export interface ToothSchemeHandle {
     focusTooth: (id: FdiId) => void;
     /** Read the current chart state. */
     getChart: () => ToothChart;
-    /** Read the findings recorded on one tooth (empty array if none). */
+    /**
+     * Read the built-in findings recorded on one tooth (empty array if none).
+     * Registry ids are omitted — use `getSymbols` for the full list.
+     */
     getTooth: (id: FdiId) => ToothCondition[];
+    /** Read the findings on one tooth as symbols, with surfaces, roots and status. */
+    getSymbols: (id: FdiId) => ToothSymbol[];
     /** Read the FDI ids of every tooth carrying a given finding. */
     teethWith: (condition: ToothCondition) => FdiId[];
+    /** As `teethWith`, but open to a `conditionRegistry` id. */
+    teethWithSymbol: (condition: ConditionId) => FdiId[];
     /** Add a finding to a tooth (no-op if already present). Optionally mark surfaces. */
     setFinding: (id: FdiId, condition: ToothCondition, surfaces?: Surface[]) => void;
+    /**
+     * Add or replace one symbol on a tooth — the surface-, root- and
+     * status-aware form of `setFinding`. Matched by `symbol.id` when the symbol
+     * carries provenance, else by its condition.
+     */
+    setSymbol: (id: FdiId, symbol: ToothSymbol) => void;
     /** Remove a finding from a tooth (no-op if absent). */
     removeFinding: (id: FdiId, condition: ToothCondition) => void;
     /** Clear every finding from a tooth. */