@welldot/render 0.1.0-next.20260509.039db95 → 0.2.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Units, Well, DiameterUnits, LengthUnits } from '@welldot/core';
+import { Well, Lithology, Fracture, Cave, BoreHole, WellCase, WellScreen, HoleFill, SurfaceCase, Reduction, Units, DiameterUnits, LengthUnits } from '@welldot/core';
 
 type PadTextureConfig = {
     background: string;
@@ -71,6 +71,7 @@ type Highlights = {
     hole_fill?: HighlightItem[];
     well_case?: HighlightItem[];
     well_screen?: HighlightItem[];
+    reduction?: HighlightItem[];
 };
 type LithologyTheme = {
     stroke: string;
@@ -129,6 +130,11 @@ type ConstructionTheme = {
         stroke: string;
         strokeWidth: number;
     };
+    reduction: {
+        fill: string;
+        stroke: string;
+        strokeWidth: number;
+    };
     conflict: {
         stroke: string;
         strokeWidth: number;
@@ -256,6 +262,10 @@ type ComponentsClassNames = {
         group: string;
         rect: string;
     };
+    reduction: {
+        group: string;
+        item: string;
+    };
     conflict: {
         group: string;
         rect: string;
@@ -286,15 +296,113 @@ type ComponentsClassNames = {
     };
 };
 /** Keys identifying which tooltip types are active. Pass to `RenderConfig.tooltips` to control visibility. */
-type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
+type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'reduction' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
+/**
+ * A paired-locale string for renderer-drawn text, or a bare string when the
+ * value doesn't vary by locale. `pt` is the required fallback locale in the
+ * object form; `en` is optional. Resolve via `resolveRenderLabel()` — never
+ * read `.pt`/`.en` directly, since the value may be a plain string.
+ */
+type RenderLocalizedText = {
+    pt: string;
+    en?: string;
+} | string;
+/**
+ * Shape shared by `RenderConfig.tooltipLabels` (resolved, `T = string`) and
+ * `RenderLabelPack.tooltipLabels` (authoring, `T = RenderLocalizedText`) —
+ * defined once via the generic so the two shapes can't drift apart.
+ */
+type TooltipLabels<T = string> = {
+    common: {
+        from: T;
+        to: T;
+        description: T;
+        diameter: T;
+        type: T;
+    };
+    geology: {
+        title: T;
+        geologicUnit: T;
+        aquiferUnit: T;
+    };
+    hole: {
+        title: T;
+    };
+    surfaceCase: {
+        title: T;
+    };
+    holeFill: {
+        title: T;
+    };
+    wellCase: {
+        title: T;
+    };
+    wellScreen: {
+        title: T;
+        slot: T;
+    };
+    reduction: {
+        title: T;
+    };
+    conflict: {
+        title: T;
+    };
+    fracture: {
+        title: T;
+        titleSwarm: T;
+        depth: T;
+        waterIntake: T;
+        dip: T;
+        azimuth: T;
+    };
+    cementPad: {
+        title: T;
+        thickness: T;
+        width: T;
+        length: T;
+    };
+    cave: {
+        title: T;
+        waterIntake: T;
+    };
+};
+/**
+ * Canonical, paired-locale source for every string `@welldot/render` draws.
+ * `RENDER_LABELS` (in `configs/render.configs.ts`) is the sole instance;
+ * `applyRenderLocale()` resolves it down to a plain-string `DeepPartial<RenderConfig>`.
+ */
+type RenderLabelPack = {
+    constructionLabels: {
+        wellCasePrefix: RenderLocalizedText;
+        wellScreenPrefix: RenderLocalizedText;
+        wellScreenSlotPrefix: RenderLocalizedText;
+    };
+    legend: {
+        title: RenderLocalizedText;
+        labels: Record<keyof LegendRenderConfig['labels'], RenderLocalizedText>;
+    };
+    tooltipLabels: TooltipLabels<RenderLocalizedText>;
+    typeLabels: {
+        fracture: RenderLocalizedText;
+        fractureWater: RenderLocalizedText;
+        cave: RenderLocalizedText;
+        caveWater: RenderLocalizedText;
+    };
+};
 /** Full rendering behaviour configuration. Use `INTERACTIVE_RENDER_CONFIG` or `STATIC_RENDER_CONFIG` as a starting point. */
 type RenderConfig = {
     zoom: boolean;
     pan: boolean;
     /** Initial zoom scale applied on first render (1 = fit all, 2 = start 2× zoomed in). */
     zoomLevel?: number;
+    /** Upper bound for zoom scale, enforced for wheel/drag and `zoomBy`/`resetZoom` alike (default 150 = 15000%). */
+    maxZoomScale?: number;
+    /** Lower bound for zoom scale, enforced for wheel/drag and `zoomBy`/`resetZoom` alike (default 0 = 0%). */
+    minZoomScale?: number;
     /** undefined = show all; false or [] = show none; array = show only listed keys */
     tooltips?: TooltipKey[] | false;
+    /** Resolved (plain-string) tooltip titles/field labels — see `TooltipLabels`. */
+    tooltipLabels: TooltipLabels;
     animation: {
         duration: number;
         ease: (t: number) => number;
@@ -355,7 +463,9 @@ type RenderConfig = {
         lithology?: boolean | ('depth' | 'description' | 'dividers')[];
         typeLabels?: {
             fracture?: string;
+            fractureWater?: string;
             cave?: string;
+            caveWater?: string;
         };
         depthTipHeight: number;
         depthTipPadX: number;
@@ -415,6 +525,7 @@ type LegendRenderConfig = {
         holeFillSeal: string;
         wellCase: string;
         wellScreen: string;
+        reduction: string;
         cementPad: string;
         conflict: string;
     };
@@ -437,7 +548,54 @@ type SvgInstance = {
         bottom: number;
     };
 };
+/**
+ * Attaches an optional stable render identity to any feature type.
+ *
+ * **`key` is runtime-only.** It exists solely in memory while the renderer is
+ * running and must never be written to a `.well` file. It is not part of the
+ * `.well` v2 spec — persisting it would produce a non-conformant file.
+ */
+type WithKey<T> = T & {
+    key?: string | number;
+};
+/**
+ * A `Well` profile where every feature array element may carry an optional `key`.
+ *
+ * When `key` is present the renderer uses it as the D3 data-join key,
+ * giving fully stable DOM identity regardless of depth edits or array reordering.
+ * When absent the renderer falls back to coordinate-based keys (`from:to` or
+ * `depth:index`).
+ *
+ * **`key` is runtime-only** — generate it once per feature (e.g.
+ * `crypto.randomUUID()`) and keep it in memory across edits, but always strip
+ * it before serializing to a `.well` file.
+ */
+type RenderableWell = Omit<Well, 'lithology' | 'fractures' | 'caves' | 'bore_hole' | 'well_case' | 'well_screen' | 'hole_fill' | 'surface_case' | 'reduction'> & {
+    lithology: WithKey<Lithology>[];
+    fractures: WithKey<Fracture>[];
+    caves: WithKey<Cave>[];
+    bore_hole: WithKey<BoreHole>[];
+    well_case: WithKey<WellCase>[];
+    well_screen: WithKey<WellScreen>[];
+    hole_fill: WithKey<HoleFill>[];
+    surface_case: WithKey<SurfaceCase>[];
+    reduction: WithKey<Reduction>[];
+};
 
+/**
+ * Canonical, paired-locale source for every string `@welldot/render` draws
+ * (construction-label prefixes, legend entries, tooltip titles/fields,
+ * fracture/cave type words). `pt` values must match the literals historically
+ * hardcoded in `tooltips.utils.ts`/`annotation-labels.renderer.ts` exactly —
+ * this is the single source of truth `applyRenderLocale()` resolves from.
+ */
+declare const RENDER_LABELS: RenderLabelPack;
+/**
+ * Returns a copy of `config` with `constructionLabels.labels`, `legend.labels`,
+ * `tooltipLabels`, and `labels.typeLabels` resolved from `RENDER_LABELS` for
+ * `locale`. Every other field of `config` is preserved unchanged.
+ */
+declare function applyRenderLocale(config: RenderConfig, locale: 'en' | 'pt'): RenderConfig;
 declare const DEFAULT_WELL_THEME: WellTheme;
 declare const STATIC_RENDER_CONFIG: RenderConfig;
 declare const INTERACTIVE_RENDER_CONFIG: RenderConfig;
@@ -472,28 +630,50 @@ declare class WellRenderer {
     private instanceStates;
     private textures;
     private onError?;
+    private onZoom?;
     classes: ComponentsClassNames;
     private renderConfig;
     private theme;
     private units;
+    private locale;
     /**
      * @param svgs - One entry per SVG panel; multi-entry for split-panel layouts.
      * @param options.classNames - Override default BEM CSS class names.
      * @param options.units - Active measurement units (`length` and `diameter`).
+     * @param options.locale - Locale for renderer-drawn text (diameter symbol, and any `RenderConfig` fields resolved via `applyRenderLocale`). Defaults to `'pt'`, matching the package's historical output.
      * @param options.renderConfig - Rendering behaviour (zoom, pan, animation, layout). Defaults to `INTERACTIVE_RENDER_CONFIG`.
      * @param options.theme - Visual theme overrides. Merged on top of `DEFAULT_WELL_THEME`.
      * @param options.onError - Called when a draw error occurs (e.g., a renderer throws). Falls back to `console.error` if omitted.
+     * @param options.onZoom - Called with the current zoom scale (`1` = initial/fit) whenever the user zooms or pans, and whenever `zoomBy`/`resetZoom` are called. No-op if `renderConfig.zoom`/`pan` are both disabled.
      */
     constructor(svgs: SvgInstance[], options?: {
         classNames?: DeepPartial<ComponentsClassNames>;
         units?: Units;
+        locale?: 'en' | 'pt';
         renderConfig?: DeepPartial<RenderConfig>;
         theme?: DeepPartial<WellTheme>;
         onError?: (err: Error) => void;
+        onZoom?: (scale: number) => void;
     });
     private initInstanceSvg;
     /** Renders a standalone legend into the element matched by `selector`. */
     renderLegend(selector: string, profile: Well): void;
+    /**
+     * Multiplies the current zoom scale by `factor` (e.g. `1.25` to zoom in,
+     * `1 / 1.25` to zoom out) on every panel. No-op if both `renderConfig.zoom`
+     * and `renderConfig.pan` are disabled (no zoom behavior was attached).
+     */
+    zoomBy(factor: number): void;
+    /**
+     * Resets zoom/pan on every panel back to `renderConfig.zoomLevel`
+     * (defaults to `1`, i.e. the initial fit-to-container view).
+     */
+    resetZoom(): void;
+    /**
+     * Current zoom scale factor of the first panel (`1` = initial/fit).
+     * Returns `1` if zoom/pan is disabled or `prepareSvg()` hasn't run yet.
+     */
+    getZoomScale(): number;
     /**
      * Initialises the SVG DOM structure and preloads FGDC textures.
      * Must be called once before the first `draw()`.
@@ -503,10 +683,12 @@ declare class WellRenderer {
      * Renders the well profile into all configured SVG panels.
      * @param profile - The well data to render.
      * @param options.units - Override the instance-level measurement units for this render.
+     * @param options.locale - Override the instance-level locale for this render.
      * @param options.highlights - Highlight overlays to display on top of the profile.
      */
-    draw(profile: Well, options?: {
+    draw(profile: RenderableWell, options?: {
         units?: Units;
+        locale?: 'en' | 'pt';
         highlights?: Highlights;
     }): void;
     private drawLogToInstance;
@@ -519,13 +701,30 @@ declare function drawWellLegend(selector: string, profile: Well, options?: {
     textures?: TexturesConfig;
 }): void;
 
-/** Formats a depth value in metres to the active length unit string. */
-declare function formatLength(m: number, units: LengthUnits): string;
-/** Formats a diameter value in millimetres to the active diameter unit string. */
-declare function formatDiameter(mm: number, units: DiameterUnits): string;
+/**
+ * Formats a depth value in metres to the active length unit string, rounded
+ * (never raw floating-point) and using the target locale's decimal separator.
+ */
+declare function formatLength(m: number, units: LengthUnits, locale: 'en' | 'pt'): string;
+/**
+ * Formats a diameter value in millimetres to the active diameter unit
+ * string, rounded (never raw floating-point) and using the target locale's
+ * decimal separator.
+ */
+declare function formatDiameter(mm: number, units: DiameterUnits, locale: 'en' | 'pt'): string;
 /** Returns the display label for the active length unit (e.g. `"m"` or `"ft"`). */
 declare function getLengthUnit(units: LengthUnits): string;
-/** Returns the display label for the active diameter unit (e.g. `"mm"` or `'"'`). */
-declare function getDiameterUnit(units: DiameterUnits): string;
+/**
+ * Returns the display symbol for the active diameter unit. `mm` is
+ * locale-invariant; `inches` is `'"'` unless `locale` is `'en'`, in which
+ * case it's `'in.'`. Omitting `locale` preserves the historical `'"'` default.
+ */
+declare function getDiameterUnit(units: DiameterUnits, locale?: 'en' | 'pt'): string;
+/**
+ * Resolves a paired-locale render label to a plain string. A bare string is
+ * returned as-is (locale-invariant); for the `{ pt, en }` object form, `pt`
+ * is always the fallback — mirrors the org-wide `resolveLanguageText()` contract.
+ */
+declare function resolveRenderLabel(value: RenderLocalizedText, locale: 'en' | 'pt'): string;
 
-export { type CaveTheme, type ComponentsClassNames, type ConstructionTheme, DEFAULT_WELL_THEME, type DeepPartial, type FractureTheme, type HighlightItem, type Highlights, INTERACTIVE_RENDER_CONFIG, type LabelsTheme, type LegendRenderConfig, type LegendTheme, type LithologyTextureTheme, type LithologyTheme, type RenderConfig, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, WellRenderer, type WellTheme, drawWellLegend, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, importFgdcTextures };
+export { type CaveTheme, type ComponentsClassNames, type ConstructionTheme, DEFAULT_WELL_THEME, type DeepPartial, type FractureTheme, type HighlightItem, type Highlights, INTERACTIVE_RENDER_CONFIG, type LabelsTheme, type LegendRenderConfig, type LegendTheme, type LithologyTextureTheme, type LithologyTheme, RENDER_LABELS, type RenderConfig, type RenderLabelPack, type RenderLocalizedText, type RenderableWell, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, type TooltipLabels, WellRenderer, type WellTheme, type WithKey, applyRenderLocale, drawWellLegend, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, importFgdcTextures, resolveRenderLabel };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Units, Well, DiameterUnits, LengthUnits } from '@welldot/core';
+import { Well, Lithology, Fracture, Cave, BoreHole, WellCase, WellScreen, HoleFill, SurfaceCase, Reduction, Units, DiameterUnits, LengthUnits } from '@welldot/core';
 
 type PadTextureConfig = {
     background: string;
@@ -71,6 +71,7 @@ type Highlights = {
     hole_fill?: HighlightItem[];
     well_case?: HighlightItem[];
     well_screen?: HighlightItem[];
+    reduction?: HighlightItem[];
 };
 type LithologyTheme = {
     stroke: string;
@@ -129,6 +130,11 @@ type ConstructionTheme = {
         stroke: string;
         strokeWidth: number;
     };
+    reduction: {
+        fill: string;
+        stroke: string;
+        strokeWidth: number;
+    };
     conflict: {
         stroke: string;
         strokeWidth: number;
@@ -256,6 +262,10 @@ type ComponentsClassNames = {
         group: string;
         rect: string;
     };
+    reduction: {
+        group: string;
+        item: string;
+    };
     conflict: {
         group: string;
         rect: string;
@@ -286,15 +296,113 @@ type ComponentsClassNames = {
     };
 };
 /** Keys identifying which tooltip types are active. Pass to `RenderConfig.tooltips` to control visibility. */
-type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
+type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'reduction' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
+/**
+ * A paired-locale string for renderer-drawn text, or a bare string when the
+ * value doesn't vary by locale. `pt` is the required fallback locale in the
+ * object form; `en` is optional. Resolve via `resolveRenderLabel()` — never
+ * read `.pt`/`.en` directly, since the value may be a plain string.
+ */
+type RenderLocalizedText = {
+    pt: string;
+    en?: string;
+} | string;
+/**
+ * Shape shared by `RenderConfig.tooltipLabels` (resolved, `T = string`) and
+ * `RenderLabelPack.tooltipLabels` (authoring, `T = RenderLocalizedText`) —
+ * defined once via the generic so the two shapes can't drift apart.
+ */
+type TooltipLabels<T = string> = {
+    common: {
+        from: T;
+        to: T;
+        description: T;
+        diameter: T;
+        type: T;
+    };
+    geology: {
+        title: T;
+        geologicUnit: T;
+        aquiferUnit: T;
+    };
+    hole: {
+        title: T;
+    };
+    surfaceCase: {
+        title: T;
+    };
+    holeFill: {
+        title: T;
+    };
+    wellCase: {
+        title: T;
+    };
+    wellScreen: {
+        title: T;
+        slot: T;
+    };
+    reduction: {
+        title: T;
+    };
+    conflict: {
+        title: T;
+    };
+    fracture: {
+        title: T;
+        titleSwarm: T;
+        depth: T;
+        waterIntake: T;
+        dip: T;
+        azimuth: T;
+    };
+    cementPad: {
+        title: T;
+        thickness: T;
+        width: T;
+        length: T;
+    };
+    cave: {
+        title: T;
+        waterIntake: T;
+    };
+};
+/**
+ * Canonical, paired-locale source for every string `@welldot/render` draws.
+ * `RENDER_LABELS` (in `configs/render.configs.ts`) is the sole instance;
+ * `applyRenderLocale()` resolves it down to a plain-string `DeepPartial<RenderConfig>`.
+ */
+type RenderLabelPack = {
+    constructionLabels: {
+        wellCasePrefix: RenderLocalizedText;
+        wellScreenPrefix: RenderLocalizedText;
+        wellScreenSlotPrefix: RenderLocalizedText;
+    };
+    legend: {
+        title: RenderLocalizedText;
+        labels: Record<keyof LegendRenderConfig['labels'], RenderLocalizedText>;
+    };
+    tooltipLabels: TooltipLabels<RenderLocalizedText>;
+    typeLabels: {
+        fracture: RenderLocalizedText;
+        fractureWater: RenderLocalizedText;
+        cave: RenderLocalizedText;
+        caveWater: RenderLocalizedText;
+    };
+};
 /** Full rendering behaviour configuration. Use `INTERACTIVE_RENDER_CONFIG` or `STATIC_RENDER_CONFIG` as a starting point. */
 type RenderConfig = {
     zoom: boolean;
     pan: boolean;
     /** Initial zoom scale applied on first render (1 = fit all, 2 = start 2× zoomed in). */
     zoomLevel?: number;
+    /** Upper bound for zoom scale, enforced for wheel/drag and `zoomBy`/`resetZoom` alike (default 150 = 15000%). */
+    maxZoomScale?: number;
+    /** Lower bound for zoom scale, enforced for wheel/drag and `zoomBy`/`resetZoom` alike (default 0 = 0%). */
+    minZoomScale?: number;
     /** undefined = show all; false or [] = show none; array = show only listed keys */
     tooltips?: TooltipKey[] | false;
+    /** Resolved (plain-string) tooltip titles/field labels — see `TooltipLabels`. */
+    tooltipLabels: TooltipLabels;
     animation: {
         duration: number;
         ease: (t: number) => number;
@@ -355,7 +463,9 @@ type RenderConfig = {
         lithology?: boolean | ('depth' | 'description' | 'dividers')[];
         typeLabels?: {
             fracture?: string;
+            fractureWater?: string;
             cave?: string;
+            caveWater?: string;
         };
         depthTipHeight: number;
         depthTipPadX: number;
@@ -415,6 +525,7 @@ type LegendRenderConfig = {
         holeFillSeal: string;
         wellCase: string;
         wellScreen: string;
+        reduction: string;
         cementPad: string;
         conflict: string;
     };
@@ -437,7 +548,54 @@ type SvgInstance = {
         bottom: number;
     };
 };
+/**
+ * Attaches an optional stable render identity to any feature type.
+ *
+ * **`key` is runtime-only.** It exists solely in memory while the renderer is
+ * running and must never be written to a `.well` file. It is not part of the
+ * `.well` v2 spec — persisting it would produce a non-conformant file.
+ */
+type WithKey<T> = T & {
+    key?: string | number;
+};
+/**
+ * A `Well` profile where every feature array element may carry an optional `key`.
+ *
+ * When `key` is present the renderer uses it as the D3 data-join key,
+ * giving fully stable DOM identity regardless of depth edits or array reordering.
+ * When absent the renderer falls back to coordinate-based keys (`from:to` or
+ * `depth:index`).
+ *
+ * **`key` is runtime-only** — generate it once per feature (e.g.
+ * `crypto.randomUUID()`) and keep it in memory across edits, but always strip
+ * it before serializing to a `.well` file.
+ */
+type RenderableWell = Omit<Well, 'lithology' | 'fractures' | 'caves' | 'bore_hole' | 'well_case' | 'well_screen' | 'hole_fill' | 'surface_case' | 'reduction'> & {
+    lithology: WithKey<Lithology>[];
+    fractures: WithKey<Fracture>[];
+    caves: WithKey<Cave>[];
+    bore_hole: WithKey<BoreHole>[];
+    well_case: WithKey<WellCase>[];
+    well_screen: WithKey<WellScreen>[];
+    hole_fill: WithKey<HoleFill>[];
+    surface_case: WithKey<SurfaceCase>[];
+    reduction: WithKey<Reduction>[];
+};
 
+/**
+ * Canonical, paired-locale source for every string `@welldot/render` draws
+ * (construction-label prefixes, legend entries, tooltip titles/fields,
+ * fracture/cave type words). `pt` values must match the literals historically
+ * hardcoded in `tooltips.utils.ts`/`annotation-labels.renderer.ts` exactly —
+ * this is the single source of truth `applyRenderLocale()` resolves from.
+ */
+declare const RENDER_LABELS: RenderLabelPack;
+/**
+ * Returns a copy of `config` with `constructionLabels.labels`, `legend.labels`,
+ * `tooltipLabels`, and `labels.typeLabels` resolved from `RENDER_LABELS` for
+ * `locale`. Every other field of `config` is preserved unchanged.
+ */
+declare function applyRenderLocale(config: RenderConfig, locale: 'en' | 'pt'): RenderConfig;
 declare const DEFAULT_WELL_THEME: WellTheme;
 declare const STATIC_RENDER_CONFIG: RenderConfig;
 declare const INTERACTIVE_RENDER_CONFIG: RenderConfig;
@@ -472,28 +630,50 @@ declare class WellRenderer {
     private instanceStates;
     private textures;
     private onError?;
+    private onZoom?;
     classes: ComponentsClassNames;
     private renderConfig;
     private theme;
     private units;
+    private locale;
     /**
      * @param svgs - One entry per SVG panel; multi-entry for split-panel layouts.
      * @param options.classNames - Override default BEM CSS class names.
      * @param options.units - Active measurement units (`length` and `diameter`).
+     * @param options.locale - Locale for renderer-drawn text (diameter symbol, and any `RenderConfig` fields resolved via `applyRenderLocale`). Defaults to `'pt'`, matching the package's historical output.
      * @param options.renderConfig - Rendering behaviour (zoom, pan, animation, layout). Defaults to `INTERACTIVE_RENDER_CONFIG`.
      * @param options.theme - Visual theme overrides. Merged on top of `DEFAULT_WELL_THEME`.
      * @param options.onError - Called when a draw error occurs (e.g., a renderer throws). Falls back to `console.error` if omitted.
+     * @param options.onZoom - Called with the current zoom scale (`1` = initial/fit) whenever the user zooms or pans, and whenever `zoomBy`/`resetZoom` are called. No-op if `renderConfig.zoom`/`pan` are both disabled.
      */
     constructor(svgs: SvgInstance[], options?: {
         classNames?: DeepPartial<ComponentsClassNames>;
         units?: Units;
+        locale?: 'en' | 'pt';
         renderConfig?: DeepPartial<RenderConfig>;
         theme?: DeepPartial<WellTheme>;
         onError?: (err: Error) => void;
+        onZoom?: (scale: number) => void;
     });
     private initInstanceSvg;
     /** Renders a standalone legend into the element matched by `selector`. */
     renderLegend(selector: string, profile: Well): void;
+    /**
+     * Multiplies the current zoom scale by `factor` (e.g. `1.25` to zoom in,
+     * `1 / 1.25` to zoom out) on every panel. No-op if both `renderConfig.zoom`
+     * and `renderConfig.pan` are disabled (no zoom behavior was attached).
+     */
+    zoomBy(factor: number): void;
+    /**
+     * Resets zoom/pan on every panel back to `renderConfig.zoomLevel`
+     * (defaults to `1`, i.e. the initial fit-to-container view).
+     */
+    resetZoom(): void;
+    /**
+     * Current zoom scale factor of the first panel (`1` = initial/fit).
+     * Returns `1` if zoom/pan is disabled or `prepareSvg()` hasn't run yet.
+     */
+    getZoomScale(): number;
     /**
      * Initialises the SVG DOM structure and preloads FGDC textures.
      * Must be called once before the first `draw()`.
@@ -503,10 +683,12 @@ declare class WellRenderer {
      * Renders the well profile into all configured SVG panels.
      * @param profile - The well data to render.
      * @param options.units - Override the instance-level measurement units for this render.
+     * @param options.locale - Override the instance-level locale for this render.
      * @param options.highlights - Highlight overlays to display on top of the profile.
      */
-    draw(profile: Well, options?: {
+    draw(profile: RenderableWell, options?: {
         units?: Units;
+        locale?: 'en' | 'pt';
         highlights?: Highlights;
     }): void;
     private drawLogToInstance;
@@ -519,13 +701,30 @@ declare function drawWellLegend(selector: string, profile: Well, options?: {
     textures?: TexturesConfig;
 }): void;
 
-/** Formats a depth value in metres to the active length unit string. */
-declare function formatLength(m: number, units: LengthUnits): string;
-/** Formats a diameter value in millimetres to the active diameter unit string. */
-declare function formatDiameter(mm: number, units: DiameterUnits): string;
+/**
+ * Formats a depth value in metres to the active length unit string, rounded
+ * (never raw floating-point) and using the target locale's decimal separator.
+ */
+declare function formatLength(m: number, units: LengthUnits, locale: 'en' | 'pt'): string;
+/**
+ * Formats a diameter value in millimetres to the active diameter unit
+ * string, rounded (never raw floating-point) and using the target locale's
+ * decimal separator.
+ */
+declare function formatDiameter(mm: number, units: DiameterUnits, locale: 'en' | 'pt'): string;
 /** Returns the display label for the active length unit (e.g. `"m"` or `"ft"`). */
 declare function getLengthUnit(units: LengthUnits): string;
-/** Returns the display label for the active diameter unit (e.g. `"mm"` or `'"'`). */
-declare function getDiameterUnit(units: DiameterUnits): string;
+/**
+ * Returns the display symbol for the active diameter unit. `mm` is
+ * locale-invariant; `inches` is `'"'` unless `locale` is `'en'`, in which
+ * case it's `'in.'`. Omitting `locale` preserves the historical `'"'` default.
+ */
+declare function getDiameterUnit(units: DiameterUnits, locale?: 'en' | 'pt'): string;
+/**
+ * Resolves a paired-locale render label to a plain string. A bare string is
+ * returned as-is (locale-invariant); for the `{ pt, en }` object form, `pt`
+ * is always the fallback — mirrors the org-wide `resolveLanguageText()` contract.
+ */
+declare function resolveRenderLabel(value: RenderLocalizedText, locale: 'en' | 'pt'): string;
 
-export { type CaveTheme, type ComponentsClassNames, type ConstructionTheme, DEFAULT_WELL_THEME, type DeepPartial, type FractureTheme, type HighlightItem, type Highlights, INTERACTIVE_RENDER_CONFIG, type LabelsTheme, type LegendRenderConfig, type LegendTheme, type LithologyTextureTheme, type LithologyTheme, type RenderConfig, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, WellRenderer, type WellTheme, drawWellLegend, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, importFgdcTextures };
+export { type CaveTheme, type ComponentsClassNames, type ConstructionTheme, DEFAULT_WELL_THEME, type DeepPartial, type FractureTheme, type HighlightItem, type Highlights, INTERACTIVE_RENDER_CONFIG, type LabelsTheme, type LegendRenderConfig, type LegendTheme, type LithologyTextureTheme, type LithologyTheme, RENDER_LABELS, type RenderConfig, type RenderLabelPack, type RenderLocalizedText, type RenderableWell, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, type TooltipLabels, WellRenderer, type WellTheme, type WithKey, applyRenderLocale, drawWellLegend, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, importFgdcTextures, resolveRenderLabel };