@honua/app-platform 0.1.1-beta.0 → 0.1.4-beta.0

package/web-components/elements.js

@@ -1,6 +1,12 @@
 import { createHonuaWebComponentController } from "./controller.js";
+import { renderCspSafeShadowHtml } from "./csp-styles.js";
+import { redactHonuaExportText } from "./export-redaction.js";
+import { HONUA_EXPORT_KINDS, approximateHonuaScaleLabel, createBrowserPrintExportAdapter, runHonuaExport, } from "./export.js";
+import { HonuaFeatureEditorElement, } from "./feature-editor.js";
+import { featureTableFocusMoveForKey, featureTableGridHtml, featureTableGridStyles, featureTableViewModel, legacyFeatureTableViewModel, } from "./feature-table-view.js";
 import { HonuaMapLibreRenderer } from "./maplibre-renderer.js";
 import { HonuaMeasurementElement } from "./measurement.js";
+import { HonuaTimeSliderElement } from "./time-slider.js";
 const globalDom = globalThis;
 const HTMLElementBase = globalDom.HTMLElement ?? class {
 };
@@ -8,6 +14,7 @@ class HonuaElementBase extends HTMLElementBase {
     #controller;
     #unsubscribe;
     #controllerReadyListener;
+    #controllerReadyTarget;
     state;
     get controller() {
         return this.#controller;
@@ -39,8 +46,9 @@ class HonuaElementBase extends HTMLElementBase {
         this.#unsubscribe?.remove();
         this.#unsubscribe = undefined;
         if (this.#controllerReadyListener) {
-            this.getRootEventTarget()?.removeEventListener("honua-controller-ready", this.#controllerReadyListener);
+            this.#controllerReadyTarget?.removeEventListener("honua-controller-ready", this.#controllerReadyListener);
             this.#controllerReadyListener = undefined;
+            this.#controllerReadyTarget = undefined;
         }
     }
     controllerChanged(_controller) { }
@@ -54,7 +62,7 @@ class HonuaElementBase extends HTMLElementBase {
         this.ensureShadowRoot();
         const root = this.shadowRoot ?? this;
         const focus = captureFocus(root);
-        root.innerHTML = html;
+        renderCspSafeShadowHtml(root, html);
         restoreFocus(root, focus);
     }
     resolveControllerFromContext() {
@@ -77,6 +85,7 @@ class HonuaElementBase extends HTMLElementBase {
         const target = this.getRootEventTarget();
         if (!target)
             return;
+        this.#controllerReadyTarget = target;
         this.#controllerReadyListener = (event) => {
             const detail = event.detail;
             if (!detail?.controller)
@@ -113,6 +122,14 @@ export class HonuaMapElement extends HonuaElementBase {
     #packageLoadToken = 0;
     #packageLoading = false;
     #packageLoadError;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     get map() {
         return this.#renderer?.map;
     }
@@ -180,10 +197,11 @@ export class HonuaMapElement extends HonuaElementBase {
             }
             catch {
                 this.#packageLoading = false;
-                this.#packageLoadError = "Invalid map-package JSON.";
+                const message = this.#messages.invalidPackage ?? "Invalid map-package JSON.";
+                this.#packageLoadError = message;
                 this.dispatchTypedEvent("honua-map-error", {
-                    error: new Error("Invalid map-package JSON."),
-                    message: "Invalid map-package JSON.",
+                    error: new Error(message),
+                    message,
                 });
             }
         }
@@ -220,6 +238,7 @@ export class HonuaMapElement extends HonuaElementBase {
         const viewport = state?.viewport ?? {};
         const visibleLayers = layers.filter((layer) => layer.visible);
         const label = this.getAttribute("label") ?? state?.mapPackage?.mapPackageId ?? "Honua map";
+        const messages = this.#messages;
         const root = this.shadowRoot ?? this;
         if (!root.querySelector?.(".map")) {
             this.setShadowHtml(`
@@ -227,10 +246,10 @@ export class HonuaMapElement extends HonuaElementBase {
         <section part="map" class="map" role="region" aria-label="${escapeHtml(label)}" tabindex="0">
           <div class="map__chrome">
             <div class="map__title"></div>
-            <div class="map__controls" aria-label="Map controls">
-              <button type="button" class="icon-button" data-zoom="out" aria-label="Zoom out">-</button>
-              <output class="zoom" aria-label="Zoom">0</output>
-              <button type="button" class="icon-button" data-zoom="in" aria-label="Zoom in">+</button>
+            <div class="map__controls" aria-label="${escapeHtml(messages.controlsLabel ?? "Map controls")}">
+              <button type="button" class="icon-button" data-zoom="out" aria-label="${escapeHtml(messages.zoomOutLabel ?? "Zoom out")}">-</button>
+              <output class="zoom" aria-label="${escapeHtml(messages.zoomLabel ?? "Zoom")}">0</output>
+              <button type="button" class="icon-button" data-zoom="in" aria-label="${escapeHtml(messages.zoomInLabel ?? "Zoom in")}">+</button>
             </div>
           </div>
           <div class="map__canvas" part="canvas">
@@ -238,8 +257,8 @@ export class HonuaMapElement extends HonuaElementBase {
             <div class="map__status" aria-live="polite"></div>
           </div>
           <div class="map__footer">
-            <span data-visible-layers>0 visible</span>
-            <span data-center>No center</span>
+            <span data-visible-layers>${escapeHtml(formatMapVisibleLayers(messages.visibleLayers, 0))}</span>
+            <span data-center>${escapeHtml(messages.noCenter ?? "No center")}</span>
           </div>
         </section>
       `);
@@ -249,8 +268,8 @@ export class HonuaMapElement extends HonuaElementBase {
         nextRoot.querySelector(".map")?.setAttribute("aria-label", label);
         setText(nextRoot.querySelector(".map__title"), label);
         setText(nextRoot.querySelector(".zoom"), String(viewport.zoom?.toFixed?.(1) ?? viewport.zoom ?? 0));
-        setText(nextRoot.querySelector("[data-visible-layers]"), `${String(visibleLayers.length)} visible`);
-        setText(nextRoot.querySelector("[data-center]"), viewport.center ? viewport.center.join(", ") : "No center");
+        setText(nextRoot.querySelector("[data-visible-layers]"), formatMapVisibleLayers(messages.visibleLayers, visibleLayers.length));
+        setText(nextRoot.querySelector("[data-center]"), viewport.center ? viewport.center.join(", ") : (messages.noCenter ?? "No center"));
         setText(nextRoot.querySelector(".map__status"), this.mapStatusText(state));
         void this.syncRenderer();
     }
@@ -345,8 +364,8 @@ export class HonuaMapElement extends HonuaElementBase {
         if (state?.mapPackage)
             return "";
         if (this.#packageLoading || this.#packageUrl)
-            return "Loading map package";
-        return "No map package";
+            return this.#messages.loadingPackage ?? "Loading map package";
+        return this.#messages.noPackage ?? "No map package";
     }
 }
 /**
@@ -371,6 +390,14 @@ export class HonuaLayerListElement extends HonuaElementBase {
     }
     #dragLayerId;
     #layersOverride;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     /**
      * The layer rows currently rendered. Headless hosts (for example the
      * esri-compat LayerList shim delegating through `HonuaWidgetHost`) can
@@ -394,7 +421,7 @@ export class HonuaLayerListElement extends HonuaElementBase {
     }
     render() {
         const layers = this.layers;
-        const label = this.getAttribute("label") ?? "Layers";
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Layers";
         const supportsOpacity = typeof this.controller?.setLayerOpacity === "function";
         const supportsReorder = typeof this.controller?.moveLayer === "function";
         this.setShadowHtml(`
@@ -403,7 +430,7 @@ export class HonuaLayerListElement extends HonuaElementBase {
         <legend>${escapeHtml(label)}</legend>
         <div class="stack" role="list">
           ${layers.length === 0
-            ? `<p class="empty">No layers</p>`
+            ? `<p class="empty">${escapeHtml(this.#messages.noLayers ?? "No layers")}</p>`
             : layers
                 .map((layer, index) => this.renderRow(layer, index, layers.length, supportsOpacity, supportsReorder))
                 .join("")}
@@ -428,15 +455,15 @@ export class HonuaLayerListElement extends HonuaElementBase {
           max="100"
           step="1"
           value="${opacityPercent}"
-          aria-label="Opacity"
-          aria-valuetext="${opacityPercent}%"
+          aria-label="${escapeAttribute(this.#messages.opacityLabel ?? "Opacity")}"
+          aria-valuetext="${escapeAttribute(formatLayerOpacityValue(this.#messages.opacityValue, opacityPercent))}"
           data-layer-opacity="${id}"
         />`
             : "";
         const reorder = supportsReorder
             ? `
-        <button type="button" class="move" part="move-up" aria-label="Move up" data-move="up:${id}" ${index === 0 ? "disabled" : ""}>&#9650;</button>
-        <button type="button" class="move" part="move-down" aria-label="Move down" data-move="down:${id}" ${index === count - 1 ? "disabled" : ""}>&#9660;</button>`
+        <button type="button" class="move" part="move-up" aria-label="${escapeAttribute(this.#messages.moveUpLabel ?? "Move up")}" data-move="up:${id}" ${index === 0 ? "disabled" : ""}>&#9650;</button>
+        <button type="button" class="move" part="move-down" aria-label="${escapeAttribute(this.#messages.moveDownLabel ?? "Move down")}" data-move="down:${id}" ${index === count - 1 ? "disabled" : ""}>&#9660;</button>`
             : "";
         return `
       <div class="layer-row" role="listitem" part="row" data-layer-row="${id}"${supportsReorder ? ` draggable="true"` : ""}>
@@ -563,6 +590,14 @@ export class HonuaLegendElement extends HonuaElementBase {
         return ["for", "label", "include-hidden"];
     }
     #itemsOverride;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     /**
      * Explicit legend items. When set, these render instead of the controller
      * state's legend (visibility coupling still applies when the controller is
@@ -598,20 +633,23 @@ export class HonuaLegendElement extends HonuaElementBase {
     }
     render() {
         const legend = this.visibleItems;
-        const label = this.getAttribute("label") ?? "Legend";
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Legend";
+        const swatchStyles = legend
+            .map((item, index) => `.swatch-${index} { --swatch: ${escapeAttribute(item.color ?? "#64748b")}; }`)
+            .join("\n");
         this.setShadowHtml(`
-      <style>${baseStyles()}${listStyles()}</style>
+      <style>${baseStyles()}${listStyles()}${legendStyles()}${swatchStyles}</style>
       <section class="panel" part="panel" aria-label="${escapeHtml(label)}">
         <h2>${escapeHtml(label)}</h2>
         <ul class="legend" role="list">
           ${legend.length === 0
-            ? `<li class="empty">No legend</li>`
+            ? `<li class="empty">${escapeHtml(this.#messages.noLegend ?? "No legend")}</li>`
             : legend
-                .map((item) => `
+                .map((item, index) => `
             <li role="listitem" data-legend-item="${escapeAttribute(item.id)}">
               ${item.iconUrl
                 ? `<img class="swatch" alt="" aria-hidden="true" src="${escapeAttribute(item.iconUrl)}" />`
-                : `<span class="swatch" aria-hidden="true" style="--swatch:${escapeAttribute(item.color ?? "#64748b")}"></span>`}
+                : `<span class="swatch swatch-${index}" aria-hidden="true"></span>`}
               <span>${escapeHtml(item.label)}</span>
             </li>
           `)
@@ -621,12 +659,86 @@ export class HonuaLegendElement extends HonuaElementBase {
     `);
     }
 }
+/**
+ * `<honua-feature-table>` — the production feature grid (issue #681).
+ *
+ * Two lanes, both rendering the same accessible WAI-ARIA `grid`:
+ *
+ * - **Bounded lane** (recommended for operational apps) — assign the `table`
+ *   property a {@link HonuaFeatureTable} from
+ *   {@link createHonuaFeatureTable}. The element then renders the engine's
+ *   virtualized window, drives remote paging from real scroll geometry, pushes
+ *   header clicks into multi-column sort, exposes total-known / estimated /
+ *   partial / stale / loading / cancelled / unsupported / error truth, and
+ *   announces realtime reconciliation conflicts in a polite live region.
+ * - **Controller lane** (unchanged, backwards compatible) — with no engine
+ *   attached the element queries the shared controller for a single bounded
+ *   page, exactly as before, and renders it through the same grid markup so the
+ *   keyboard and screen-reader contract does not depend on which lane is in use.
+ *
+ * Keyboard: arrow keys move the focused cell, `Home`/`End` jump within the row
+ * (`Ctrl`/`Cmd` to the grid), `PageUp`/`PageDown` move a window at a time —
+ * loading the page the focus lands on in the bounded lane — and
+ * `Enter`/`Space` selects the focused row. Exactly one cell is tabbable
+ * (roving `tabindex`).
+ */
 export class HonuaFeatureTableElement extends HonuaElementBase {
     static get observedAttributes() {
-        return ["for", "source", "fields", "page-size", "filter-text", "label"];
+        return ["for", "source", "fields", "page-size", "filter-text", "label", "row-height"];
     }
     #model;
     #refreshToken = 0;
+    #table;
+    #tableUnsubscribe;
+    #tableSnapshot;
+    #announcedConflicts = "";
+    #tableConnected = false;
+    #restoringScroll = false;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
+    /**
+     * The bounded query engine backing this grid. Assigning one switches the
+     * element to the bounded lane; assigning `undefined` restores the
+     * controller-driven single-page lane.
+     */
+    get table() {
+        return this.#table;
+    }
+    set table(table) {
+        if (this.#table === table) {
+            // Re-assigning the same engine must still be able to re-take a
+            // subscription that `disconnectedCallback()` dropped.
+            this.#subscribeTable();
+            return;
+        }
+        this.#tableUnsubscribe?.();
+        this.#tableUnsubscribe = undefined;
+        this.#table = table;
+        this.#tableSnapshot = table?.snapshot;
+        // Only hold a subscription while connected; `connectedCallback()` re-takes
+        // it so a detached-then-reinserted grid resumes updating.
+        this.#subscribeTable();
+        this.render();
+    }
+    /** Takes the engine subscription, unless one is already held or we are detached. */
+    #subscribeTable() {
+        const table = this.#table;
+        if (!table || this.#tableUnsubscribe || !this.#tableConnected)
+            return;
+        // The engine may have moved on while detached; re-read before listening.
+        this.#tableSnapshot = table.snapshot;
+        this.#tableUnsubscribe = table.subscribe((snapshot) => {
+            this.#tableSnapshot = snapshot;
+            this.render();
+            this.#announceConflicts(snapshot);
+        });
+    }
     attributeChangedCallback(name, _oldValue, newValue) {
         this.resolveControllerFromContext();
         if (name === "filter-text") {
@@ -640,13 +752,40 @@ export class HonuaFeatureTableElement extends HonuaElementBase {
         void this.refresh();
     }
     connectedCallback() {
+        this.#tableConnected = true;
         super.connectedCallback();
+        this.#subscribeTable();
+        if (this.#table) {
+            // Reconnect must not re-query: the engine already holds bounded pages, and
+            // re-taking the subscription plus a render is enough to resume.
+            this.render();
+            return;
+        }
         void this.refresh();
     }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.#tableConnected = false;
+        this.#tableUnsubscribe?.();
+        this.#tableUnsubscribe = undefined;
+    }
     stateChanged() {
+        if (this.#table) {
+            // Selection is owned by the engine (and, through it, shared exploration
+            // state) in the bounded lane — a controller state change must not trigger
+            // an unbounded re-query.
+            this.render();
+            return;
+        }
         void this.refresh();
     }
     async refresh() {
+        if (this.#table) {
+            const snapshot = await this.#table.refresh();
+            this.#tableSnapshot = snapshot;
+            this.render();
+            return featureTableModelFromSnapshot(snapshot);
+        }
         const controller = this.controller;
         if (!controller)
             return undefined;
@@ -662,53 +801,202 @@ export class HonuaFeatureTableElement extends HonuaElementBase {
         return model;
     }
     render() {
-        const state = this.state;
-        const model = this.#model ?? tableModelFromState(state, this.sourceId(), this.fields(), this.pageSize());
-        const selectedId = state?.selection?.featureId;
-        const label = this.getAttribute("label") ?? "Features";
-        this.setShadowHtml(`
-      <style>${baseStyles()}${tableStyles()}</style>
-      <section class="table-panel" part="panel" aria-label="${escapeHtml(label)}">
-        <div class="table-panel__bar">
-          <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(String(model.totalCount))}</span>
-        </div>
-        <div class="table-wrap">
-          <table role="grid" aria-rowcount="${escapeHtml(String(model.rows.length))}">
-            <thead>
-              <tr>${model.fields.map((field) => `<th scope="col">${escapeHtml(field)}</th>`).join("")}</tr>
-            </thead>
-            <tbody>
-              ${model.rows.length === 0
-            ? `<tr><td colspan="${Math.max(1, model.fields.length)}" class="empty">No rows</td></tr>`
-            : model.rows
-                .map((row) => `
-                <tr tabindex="0" data-source-id="${escapeHtml(row.sourceId)}" data-feature-id="${escapeHtml(String(row.id))}" aria-selected="${String(String(selectedId ?? "") === String(row.id))}">
-                  ${model.fields.map((field) => `<td>${escapeHtml(formatCell(row.attributes[field]))}</td>`).join("")}
-                </tr>
-              `)
-                .join("")}
-            </tbody>
-          </table>
-        </div>
-      </section>
-    `);
-        this.shadowRoot?.querySelectorAll("tbody tr[data-feature-id]").forEach((row) => {
-            const select = () => this.selectRow(row);
-            row.addEventListener("click", select);
-            row.addEventListener("keydown", (event) => {
-                if (event.key !== "Enter" && event.key !== " ")
-                    return;
-                event.preventDefault();
-                select();
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Features";
+        const rowHeight = this.rowHeight();
+        const snapshot = this.#tableSnapshot;
+        const viewModel = snapshot
+            ? featureTableViewModel(snapshot, { label, rowHeight, messages: this.#messages })
+            : legacyFeatureTableViewModel(this.#model ?? tableModelFromState(this.state, this.sourceId(), this.fields(), this.pageSize()), {
+                label,
+                rowHeight,
+                messages: this.#messages,
+                ...(this.state?.selection?.featureId !== undefined
+                    ? { selectedFeatureId: String(this.state.selection.featureId) }
+                    : {}),
             });
+        // `setShadowHtml` replaces the whole shadow tree, including the scroll
+        // container. A fresh container starts at `scrollTop = 0`, which would snap a
+        // virtualized grid back to the top (and strand a full-height leading spacer)
+        // on every publish — including the synchronous loading snapshot that
+        // `setScroll` itself publishes. Carry the offset across the swap.
+        const previousScrollTop = this.#scroller()?.scrollTop ?? 0;
+        this.setShadowHtml(`<style>${baseStyles()}${tableStyles()}${featureTableGridStyles()}</style>${featureTableGridHtml(viewModel)}`);
+        this.#bindGrid();
+        this.#restoreScrollTop(previousScrollTop);
+    }
+    #scroller() {
+        return this.shadowRoot?.querySelector("[data-scroller]") ?? null;
+    }
+    #restoreScrollTop(scrollTop) {
+        if (scrollTop <= 0)
+            return;
+        const scroller = this.#scroller();
+        if (!scroller || scroller.scrollTop === scrollTop)
+            return;
+        // Restoring the offset fires `scroll`; that echo must not be mistaken for a
+        // user gesture and fed back into the engine as a new window.
+        this.#restoringScroll = true;
+        scroller.scrollTop = scrollTop;
+        queueMicrotask(() => {
+            this.#restoringScroll = false;
         });
     }
+    #bindGrid() {
+        const root = this.shadowRoot;
+        if (!root)
+            return;
+        for (const button of root.querySelectorAll("[data-sort-field]")) {
+            button.addEventListener("click", (event) => {
+                const field = button.dataset.sortField;
+                if (!field)
+                    return;
+                void this.#table?.toggleSort(field, { additive: event.shiftKey });
+            });
+        }
+        for (const row of root.querySelectorAll("tbody tr[data-feature-id]")) {
+            row.addEventListener("click", () => this.selectRow(row));
+            row.addEventListener("keydown", (event) => this.#onRowKeydown(event, row));
+        }
+        for (const cell of root.querySelectorAll('tbody [role="gridcell"]')) {
+            cell.addEventListener("focus", () => this.#focusCell(cell));
+            cell.addEventListener("keydown", (event) => this.#onGridKeydown(event, cell));
+        }
+        const scroller = root.querySelector("[data-scroller]");
+        if (scroller && this.#table) {
+            scroller.addEventListener("scroll", () => {
+                if (this.#restoringScroll)
+                    return;
+                void this.#table?.setScroll({
+                    scrollTop: scroller.scrollTop,
+                    rowHeight: this.rowHeight(),
+                    viewportHeight: scroller.clientHeight || this.rowHeight() * 10,
+                });
+            });
+        }
+    }
+    /**
+     * Keys pressed while the **row** itself holds focus, rather than one of its
+     * cells. Cells handle their own keys and their events bubble through the row,
+     * so this bails unless the row is the actual target — no double handling.
+     *
+     * Enter/Space selects, matching the row-level activation the grid has always
+     * offered. Any navigation key hands focus to the row's first cell, which is
+     * where the roving-tabindex model takes over.
+     */
+    #onRowKeydown(event, row) {
+        if (event.target !== row)
+            return;
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            this.selectRow(row);
+            return;
+        }
+        if (!featureTableFocusMoveForKey(event.key, { ctrl: event.ctrlKey, meta: event.metaKey }))
+            return;
+        const cell = row.querySelector('[role="gridcell"]');
+        if (!cell)
+            return;
+        event.preventDefault();
+        cell.focus();
+    }
+    #focusCell(cell) {
+        const rowKey = cell.closest("tr")?.dataset.rowKey;
+        const field = cell.dataset.field;
+        if (!rowKey || !field || !this.#table)
+            return;
+        if (this.#tableSnapshot?.focus?.rowKey === rowKey && this.#tableSnapshot.focus.field === field)
+            return;
+        this.#table.setFocus({ rowKey, field });
+    }
+    #onGridKeydown(event, cell) {
+        const row = cell.closest("tr");
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            if (row)
+                this.selectRow(row);
+            return;
+        }
+        const move = featureTableFocusMoveForKey(event.key, { ctrl: event.ctrlKey, meta: event.metaKey });
+        if (!move)
+            return;
+        event.preventDefault();
+        const table = this.#table;
+        if (!table) {
+            this.#moveDomFocus(move, cell, row);
+            return;
+        }
+        if (!this.#tableSnapshot?.focus)
+            this.#focusCell(cell);
+        void table.moveFocus(move).then(() => this.#restoreFocusedCell());
+    }
+    /** Controller lane: move focus within the rendered rows only — no paging. */
+    #moveDomFocus(move, cell, row) {
+        const root = this.shadowRoot;
+        if (!root || !row)
+            return;
+        const rows = [...root.querySelectorAll("tbody tr")];
+        const cells = [...row.querySelectorAll('[role="gridcell"]')];
+        const rowIndex = rows.indexOf(row);
+        const cellIndex = cells.indexOf(cell);
+        const clamp = (value, max) => Math.max(0, Math.min(value, max));
+        let nextRow = rowIndex;
+        let nextCell = cellIndex;
+        if (move === "up")
+            nextRow -= 1;
+        else if (move === "down")
+            nextRow += 1;
+        else if (move === "left")
+            nextCell -= 1;
+        else if (move === "right")
+            nextCell += 1;
+        else if (move === "row-start")
+            nextCell = 0;
+        else if (move === "row-end")
+            nextCell = cells.length - 1;
+        else if (move === "page-up")
+            nextRow = 0;
+        else if (move === "page-down")
+            nextRow = rows.length - 1;
+        else if (move === "grid-start") {
+            nextRow = 0;
+            nextCell = 0;
+        }
+        else if (move === "grid-end") {
+            nextRow = rows.length - 1;
+            nextCell = cells.length - 1;
+        }
+        const target = rows[clamp(nextRow, rows.length - 1)]?.querySelectorAll('[role="gridcell"]')[clamp(nextCell, cells.length - 1)];
+        target?.focus();
+    }
+    #restoreFocusedCell() {
+        const focus = this.#tableSnapshot?.focus;
+        const root = this.shadowRoot;
+        if (!focus || !root)
+            return;
+        const selector = `tbody tr[data-row-key="${cssEscape(focus.rowKey)}"] [data-field="${cssEscape(focus.field)}"]`;
+        root.querySelector(selector)?.focus();
+    }
+    #announceConflicts(snapshot) {
+        const digest = snapshot.conflicts.map((conflict) => `${conflict.code}:${conflict.rowKeys.join(",")}`).join("|");
+        if (digest === this.#announcedConflicts)
+            return;
+        this.#announcedConflicts = digest;
+        for (const conflict of snapshot.conflicts) {
+            this.dispatchTypedEvent("honua-table-conflict", {
+                code: conflict.code,
+                message: conflict.message,
+                rowKeys: conflict.rowKeys,
+            });
+        }
+    }
     selectRow(row) {
         const sourceId = row.dataset.sourceId;
         const featureId = row.dataset.featureId;
         if (!sourceId || featureId === undefined)
             return;
+        const rowKey = row.dataset.rowKey;
+        if (this.#table && rowKey)
+            this.#table.select([rowKey]);
         const feature = (this.#model?.rows ?? []).find((candidate) => String(candidate.id) === featureId);
         this.controller?.selectFeature({ sourceId, featureId, ...(feature ? { feature } : {}) });
         this.dispatchTypedEvent("honua-selection-change", {
@@ -731,6 +1019,53 @@ export class HonuaFeatureTableElement extends HonuaElementBase {
         const parsed = Number(this.getAttribute("page-size"));
         return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
     }
+    rowHeight() {
+        const parsed = Number(this.getAttribute("row-height"));
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : 32;
+    }
+}
+/**
+ * Project a bounded snapshot onto the legacy {@link HonuaFeatureTableModel} so
+ * existing `refresh()` callers keep compiling. `totalCount` is only the
+ * engine's count when the engine actually knows one; a partial or unknown count
+ * reports the resident row count, which the `exceededTransferLimit` flag marks
+ * as incomplete rather than presenting it as a total.
+ */
+function featureTableModelFromSnapshot(snapshot) {
+    const rows = snapshot.rows.filter((row) => row !== undefined);
+    const known = snapshot.count.kind === "known" || snapshot.count.kind === "estimated";
+    return {
+        sourceId: snapshot.sourceId,
+        status: legacyStatusForState(snapshot.state),
+        fields: snapshot.visibleColumns.map((column) => column.field),
+        rows: rows.map((row) => ({
+            id: row.id,
+            sourceId: row.sourceId,
+            attributes: row.attributes,
+            ...(row.geometry !== undefined ? { geometry: row.geometry } : {}),
+        })),
+        totalCount: known ? (snapshot.count.value ?? snapshot.count.loaded) : snapshot.count.loaded,
+        ...(known ? {} : { exceededTransferLimit: true }),
+        ...(snapshot.error !== undefined ? { error: snapshot.error } : {}),
+    };
+}
+function legacyStatusForState(state) {
+    switch (state) {
+        case "idle":
+            return "idle";
+        case "loading":
+            return "loading";
+        case "error":
+            return "error";
+        case "unsupported":
+            return "unsupported";
+        default:
+            return "ready";
+    }
+}
+/** Minimal `CSS.escape` for the attribute selectors this element builds. */
+function cssEscape(value) {
+    return value.split("\\").join("\\\\").split('"').join('\\"');
 }
 /**
  * `<honua-search>` — the survival-tier search box (issue #493).
@@ -752,7 +1087,7 @@ export class HonuaFeatureTableElement extends HonuaElementBase {
  */
 export class HonuaSearchElement extends HonuaElementBase {
     static get observedAttributes() {
-        return ["for", "source", "placeholder", "label", "debounce", "zoom"];
+        return ["for", "source", "placeholder", "label", "submit-label", "debounce", "zoom"];
     }
     #query = "";
     #results = [];
@@ -763,6 +1098,14 @@ export class HonuaSearchElement extends HonuaElementBase {
     #suggestTimer;
     #suggestToken = 0;
     #geocodeToken = 0;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     /** The geocoding provider powering typeahead + geocode-on-submit. */
     get geocoder() {
         return this.#geocoder;
@@ -775,6 +1118,20 @@ export class HonuaSearchElement extends HonuaElementBase {
         this.#status = "";
         this.render();
     }
+    /**
+     * Text rendered in the form's submit button. Defaults to `"Search"` for
+     * compatibility with the original markup. The property reflects the
+     * `submit-label` attribute so either caller API can supply localized text.
+     */
+    get submitLabel() {
+        return this.getAttribute("submit-label") ?? "Search";
+    }
+    set submitLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("submit-label");
+        else
+            this.setAttribute("submit-label", value);
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
@@ -784,8 +1141,9 @@ export class HonuaSearchElement extends HonuaElementBase {
         super.disconnectedCallback();
     }
     render() {
-        const label = this.getAttribute("label") ?? "Search";
-        const placeholder = this.getAttribute("placeholder") ?? "Search";
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Search";
+        const placeholder = this.#messages.placeholder ?? this.getAttribute("placeholder") ?? "Search";
+        const submitLabel = this.#messages.submitLabel ?? this.submitLabel;
         const geocoding = this.#geocoder !== undefined;
         const expanded = geocoding && this.#suggestions.length > 0;
         const comboboxAttributes = geocoding
@@ -797,10 +1155,12 @@ export class HonuaSearchElement extends HonuaElementBase {
         <form>
           <label class="sr-only" for="honua-search-input">${escapeHtml(label)}</label>
           <input id="honua-search-input" name="q" value="${escapeAttribute(this.#query)}" placeholder="${escapeAttribute(placeholder)}" autocomplete="off"${comboboxAttributes} />
-          <button type="submit">Search</button>
+          <button type="submit">${escapeHtml(submitLabel)}</button>
         </form>
         ${geocoding
-            ? `<ul class="suggestions" id="honua-search-listbox" role="listbox" aria-label="${escapeAttribute(`${label} suggestions`)}"${expanded ? "" : " hidden"}>
+            ? `<ul class="suggestions" id="honua-search-listbox" role="listbox" aria-label="${escapeAttribute(typeof this.#messages.suggestionsLabel === "function"
+                ? this.#messages.suggestionsLabel(label)
+                : (this.#messages.suggestionsLabel ?? `${label} suggestions`))}"${expanded ? "" : " hidden"}>
           ${this.#suggestions
                 .map((suggestion, index) => `<li id="honua-search-option-${index}" role="option" aria-selected="${String(index === this.#activeIndex)}" data-suggestion-index="${index}">${escapeHtml(suggestion.text)}</li>`)
                 .join("")}
@@ -821,11 +1181,18 @@ export class HonuaSearchElement extends HonuaElementBase {
             else
                 void this.runSearch(query);
         });
-        if (this.#geocoder) {
-            input?.addEventListener("input", () => {
-                this.#query = input.value;
+        // The typed query is tracked unconditionally, not only when a geocoder is
+        // assigned. `render()` re-creates the input from `#query`, so without this
+        // any controller-driven re-render (a viewport change, a layer toggle, a
+        // realtime refresh) silently wiped whatever the user had typed — the
+        // focus-restoration gate this is measured against (issue #683, REQ-004)
+        // found exactly that. Suggestion scheduling stays geocoder-gated.
+        input?.addEventListener("input", () => {
+            this.#query = input.value;
+            if (this.#geocoder)
                 this.scheduleSuggest();
-            });
+        });
+        if (this.#geocoder) {
             input?.addEventListener("keydown", (event) => this.onComboboxKeydown(event));
             this.shadowRoot?.querySelectorAll("li[data-suggestion-index]").forEach((option) => {
                 option.addEventListener("click", () => {
@@ -912,7 +1279,8 @@ export class HonuaSearchElement extends HonuaElementBase {
                 return;
             this.#suggestions = [];
             this.#activeIndex = -1;
-            this.#status = error instanceof Error ? error.message : "Suggestions unavailable.";
+            this.#status =
+                error instanceof Error ? error.message : (this.#messages.suggestionsUnavailable ?? "Suggestions unavailable.");
             this.render();
         }
     }
@@ -949,7 +1317,7 @@ export class HonuaSearchElement extends HonuaElementBase {
                 return;
             const candidate = candidates[0];
             if (!candidate) {
-                this.#status = `No results for "${trimmed}".`;
+                this.#status = this.#messages.noResults?.(trimmed) ?? `No results for "${trimmed}".`;
                 this.render();
                 return;
             }
@@ -969,7 +1337,12 @@ export class HonuaSearchElement extends HonuaElementBase {
         catch (error) {
             if (token !== this.#geocodeToken)
                 return;
-            this.#status = error instanceof Error ? error.message : "Geocoding failed.";
+            this.#status =
+                error instanceof Error
+                    ? error.message
+                    : typeof this.#messages.geocodingFailed === "function"
+                        ? this.#messages.geocodingFailed(error)
+                        : (this.#messages.geocodingFailed ?? "Geocoding failed.");
             this.render();
         }
     }
@@ -997,9 +1370,20 @@ export class HonuaSearchElement extends HonuaElementBase {
 }
 export class HonuaEditorElement extends HonuaElementBase {
     static get observedAttributes() {
-        return ["for", "source", "label"];
+        return [
+            "for",
+            "source",
+            "label",
+            "new-label",
+            "save-label",
+            "delete-label",
+            "no-selection-label",
+            "read-only-label",
+            "editable-label",
+        ];
     }
     #model;
+    #messages = {};
     get editorModel() {
         return this.#model ?? this.state?.editor;
     }
@@ -1007,6 +1391,74 @@ export class HonuaEditorElement extends HonuaElementBase {
         this.#model = model;
         this.render();
     }
+    /** Caller-supplied localized status and read-only messages. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
+    /** Text rendered by the create action. Defaults to `"New"`. */
+    get newLabel() {
+        return this.getAttribute("new-label") ?? "New";
+    }
+    set newLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("new-label");
+        else
+            this.setAttribute("new-label", value);
+    }
+    /** Text rendered by the save action. Defaults to `"Save"`. */
+    get saveLabel() {
+        return this.getAttribute("save-label") ?? "Save";
+    }
+    set saveLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("save-label");
+        else
+            this.setAttribute("save-label", value);
+    }
+    /** Text rendered by the delete action. Defaults to `"Delete"`. */
+    get deleteLabel() {
+        return this.getAttribute("delete-label") ?? "Delete";
+    }
+    set deleteLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("delete-label");
+        else
+            this.setAttribute("delete-label", value);
+    }
+    /** Text rendered when no feature is selected. Defaults to `"No selection"`. */
+    get noSelectionLabel() {
+        return this.getAttribute("no-selection-label") ?? "No selection";
+    }
+    set noSelectionLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("no-selection-label");
+        else
+            this.setAttribute("no-selection-label", value);
+    }
+    /** Text rendered for a read-only editor without a model-supplied reason. Defaults to `"Read-only"`. */
+    get readOnlyLabel() {
+        return this.getAttribute("read-only-label") ?? "Read-only";
+    }
+    set readOnlyLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("read-only-label");
+        else
+            this.setAttribute("read-only-label", value);
+    }
+    /** Text rendered for an editable editor. Defaults to `"Editable"`. */
+    get editableLabel() {
+        return this.getAttribute("editable-label") ?? "Editable";
+    }
+    set editableLabel(value) {
+        if (value === undefined)
+            this.removeAttribute("editable-label");
+        else
+            this.setAttribute("editable-label", value);
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
@@ -1017,19 +1469,30 @@ export class HonuaEditorElement extends HonuaElementBase {
         const selected = state?.selection?.feature;
         const canUpdate = model.capabilities.canUpdate && !model.capabilities.readOnly;
         const label = this.getAttribute("label") ?? "Editor";
+        const newLabel = this.newLabel;
+        const saveLabel = this.saveLabel;
+        const deleteLabel = this.deleteLabel;
+        const noSelectionLabel = this.noSelectionLabel;
+        const readOnlyLabel = this.readOnlyLabel;
+        const editableLabel = this.editableLabel;
+        const statusLabel = this.#messages.status?.[model.status] ?? model.status;
+        const readOnlyReason = this.#messages.readOnlyReason;
+        const readOnlyMessage = typeof readOnlyReason === "function"
+            ? readOnlyReason(model.capabilities.reason)
+            : (readOnlyReason ?? model.capabilities.reason ?? readOnlyLabel);
         this.setShadowHtml(`
       <style>${baseStyles()}${editorStyles()}</style>
       <section class="editor" part="panel" aria-label="${escapeHtml(label)}">
         <div class="editor__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span data-status>${escapeHtml(model.status)}</span>
+          <span data-status>${escapeHtml(statusLabel)}</span>
         </div>
-        <p class="selection">${escapeHtml(selected?.title ?? "No selection")}</p>
-        <p class="muted">${escapeHtml(model.capabilities.readOnly ? (model.capabilities.reason ?? "Read-only") : "Editable")}</p>
+        <p class="selection">${escapeHtml(selected?.title ?? noSelectionLabel)}</p>
+        <p class="muted">${escapeHtml(model.capabilities.readOnly ? readOnlyMessage : editableLabel)}</p>
         <div class="editor__actions">
-          <button type="button" data-action="new" ${model.capabilities.canCreate && !model.capabilities.readOnly ? "" : "disabled"}>New</button>
-          <button type="button" data-action="save" ${canUpdate ? "" : "disabled"}>Save</button>
-          <button type="button" data-action="delete" ${model.capabilities.canDelete && !model.capabilities.readOnly ? "" : "disabled"}>Delete</button>
+          <button type="button" data-action="new" ${model.capabilities.canCreate && !model.capabilities.readOnly ? "" : "disabled"}>${escapeHtml(newLabel)}</button>
+          <button type="button" data-action="save" ${canUpdate ? "" : "disabled"}>${escapeHtml(saveLabel)}</button>
+          <button type="button" data-action="delete" ${model.capabilities.canDelete && !model.capabilities.readOnly ? "" : "disabled"}>${escapeHtml(deleteLabel)}</button>
         </div>
       </section>
     `);
@@ -1062,6 +1525,14 @@ export class HonuaChartElement extends HonuaElementBase {
         return ["for", "label"];
     }
     #model;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     get chartModel() {
         return this.#model ?? this.state?.chart;
     }
@@ -1074,24 +1545,28 @@ export class HonuaChartElement extends HonuaElementBase {
         this.render();
     }
     render() {
-        const model = this.chartModel ?? defaultChartModel(this.getAttribute("label") ?? "Chart");
+        const model = this.chartModel ?? defaultChartModel(this.#messages.label ?? this.getAttribute("label") ?? "Chart");
+        const title = this.#messages.label ?? model.title;
         const max = Math.max(1, ...(model.data ?? []).map((datum) => datum.value));
+        const barStyles = (model.data ?? [])
+            .map((datum, index) => `.bar-${index} { --bar: ${(datum.value / max) * 100}%; --bar-color: ${escapeAttribute(datum.color ?? "#2563eb")}; }`)
+            .join("\n");
         this.setShadowHtml(`
-      <style>${baseStyles()}${chartStyles()}</style>
-      <section class="chart" part="panel" aria-label="${escapeHtml(model.title)}">
-        <h2>${escapeHtml(model.title)}</h2>
+      <style>${baseStyles()}${chartStyles()}${barStyles}</style>
+      <section class="chart" part="panel" aria-label="${escapeHtml(title)}">
+        <h2>${escapeHtml(title)}</h2>
         <div class="bars">
           ${model.data?.length
             ? model.data
-                .map((datum) => `
+                .map((datum, index) => `
             <div class="bar-row">
               <span>${escapeHtml(datum.label)}</span>
-              <span class="bar" style="--bar:${(datum.value / max) * 100}%;--bar-color:${escapeAttribute(datum.color ?? "#2563eb")}"></span>
+              <span class="bar bar-${index}"></span>
               <strong>${escapeHtml(String(datum.value))}</strong>
             </div>
           `)
                 .join("")
-            : `<p class="empty">${escapeHtml(model.message ?? "No chart data")}</p>`}
+            : `<p class="empty">${escapeHtml(this.#messages.noData ?? model.message ?? "No chart data")}</p>`}
         </div>
       </section>
     `);
@@ -1102,24 +1577,32 @@ export class HonuaBasemapControlElement extends HonuaElementBase {
         return ["for", "label"];
     }
     #activeBasemapId;
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
     }
     render() {
-        const label = this.getAttribute("label") ?? "Basemaps";
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Basemaps";
         const basemaps = basemapsFromState(this.state);
         const active = this.#activeBasemapId ?? basemaps.find((basemap) => basemap.visible)?.id ?? basemaps[0]?.id;
         this.setShadowHtml(`
-      <style>${baseStyles()}${controlPanelStyles()}</style>
+      <style>${baseStyles()}${controlPanelStyles()}${basemapControlStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(basemaps.length >= 2 ? "ready" : "unsupported")}</span>
+          <span>${escapeHtml(this.#messages.status?.[basemaps.length >= 2 ? "ready" : "unsupported"] ?? (basemaps.length >= 2 ? "ready" : "unsupported"))}</span>
         </div>
         ${basemaps.length < 2
-            ? `<p class="empty" role="status">At least two basemap layers are required.</p>`
-            : `<div class="segmented" role="group" aria-label="${escapeAttribute(label)}">
+            ? `<p class="empty" role="status">${escapeHtml(this.#messages.unavailable ?? this.#messages.unsupported ?? "At least two basemap layers are required.")}</p>`
+            : `<div class="segmented" role="group" aria-label="${escapeAttribute(this.#messages.groupLabel ?? label)}">
               ${basemaps
                 .map((basemap) => `
                 <button type="button" data-basemap-id="${escapeAttribute(basemap.id)}" aria-pressed="${String(basemap.id === active)}">${escapeHtml(basemap.title)}</button>
@@ -1152,6 +1635,14 @@ export class HonuaBookmarksElement extends HonuaElementBase {
     static get observedAttributes() {
         return ["for", "label", "bookmarks"];
     }
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
@@ -1159,15 +1650,17 @@ export class HonuaBookmarksElement extends HonuaElementBase {
     render() {
         const label = this.getAttribute("label") ?? "Bookmarks";
         const bookmarks = this.bookmarks();
+        const statusLabel = this.#messages.status?.[bookmarks.length > 0 ? "ready" : "unsupported"] ??
+            (bookmarks.length > 0 ? "ready" : "unsupported");
         this.setShadowHtml(`
       <style>${baseStyles()}${controlPanelStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(bookmarks.length > 0 ? "ready" : "unsupported")}</span>
+          <span>${escapeHtml(statusLabel)}</span>
         </div>
         ${bookmarks.length === 0
-            ? `<p class="empty" role="status">No initial view or bookmarks are available.</p>`
+            ? `<p class="empty" role="status">${escapeHtml(this.#messages.empty ?? "No initial view or bookmarks are available.")}</p>`
             : `<div class="button-stack">
               ${bookmarks
                 .map((bookmark) => `
@@ -1188,7 +1681,12 @@ export class HonuaBookmarksElement extends HonuaElementBase {
     bookmarks() {
         const configured = parseBookmarks(this.getAttribute("bookmarks"));
         const home = this.state?.mapPackage?.initialView;
-        return [...(home ? [{ id: "home", label: "Home", viewport: home }] : []), ...configured];
+        return [
+            ...(home
+                ? [{ id: "home", label: this.#messages.homeLabel ?? "Home", viewport: home }]
+                : []),
+            ...configured,
+        ];
     }
     goToBookmark(bookmark) {
         this.controller?.setViewport(bookmark.viewport);
@@ -1205,6 +1703,15 @@ export class HonuaLocateControlElement extends HonuaElementBase {
     }
     #status = "idle";
     #message = "";
+    #messages = {};
+    /** Caller-supplied localized labels and state messages. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
@@ -1213,15 +1720,20 @@ export class HonuaLocateControlElement extends HonuaElementBase {
         const label = this.getAttribute("label") ?? "Locate";
         const supported = this.hasConfiguredLocation() || Boolean(globalThis.navigator?.geolocation);
         const status = supported ? this.#status : "unsupported";
+        const statusLabel = this.#messages.status?.[status] ?? status;
+        const message = this.#message ||
+            (supported
+                ? (this.#messages.initial ?? "Centers the shared map controller.")
+                : (this.#messages.unavailable ?? "Geolocation is unavailable."));
         this.setShadowHtml(`
       <style>${baseStyles()}${controlPanelStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(status)}</span>
+          <span>${escapeHtml(statusLabel)}</span>
         </div>
-        <button type="button" data-locate ${supported ? "" : "disabled"}>Use location</button>
-        <p class="empty" role="status">${escapeHtml(supported ? this.#message || "Centers the shared map controller." : "Geolocation is unavailable.")}</p>
+        <button type="button" data-locate="action" ${supported ? "" : "disabled"}>${escapeHtml(this.#messages.actionLabel ?? "Use location")}</button>
+        <p class="empty" role="status">${escapeHtml(message)}</p>
       </section>
     `);
         this.shadowRoot?.querySelector("button[data-locate]")?.addEventListener("click", () => {
@@ -1237,7 +1749,7 @@ export class HonuaLocateControlElement extends HonuaElementBase {
         const geolocation = globalThis.navigator?.geolocation;
         if (!geolocation) {
             this.#status = "unsupported";
-            this.#message = "Geolocation is unavailable.";
+            this.#message = this.#messages.unavailable ?? "Geolocation is unavailable.";
             this.dispatchTypedEvent("honua-locate-change", {
                 status: "unsupported",
                 message: this.#message,
@@ -1246,7 +1758,7 @@ export class HonuaLocateControlElement extends HonuaElementBase {
             return;
         }
         this.#status = "loading";
-        this.#message = "Requesting location.";
+        this.#message = this.#messages.requesting ?? "Requesting location.";
         this.render();
         geolocation.getCurrentPosition((position) => {
             this.applyLocation({
@@ -1255,7 +1767,7 @@ export class HonuaLocateControlElement extends HonuaElementBase {
             });
         }, (error) => {
             this.#status = "error";
-            this.#message = error.message;
+            this.#message = this.#messages.error?.(error) ?? error.message;
             this.dispatchTypedEvent("honua-locate-change", {
                 status: "error",
                 error,
@@ -1266,7 +1778,7 @@ export class HonuaLocateControlElement extends HonuaElementBase {
     }
     applyLocation(viewport) {
         this.#status = "ready";
-        this.#message = "Location applied.";
+        this.#message = this.#messages.applied ?? "Location applied.";
         this.controller?.setViewport(viewport);
         this.dispatchTypedEvent("honua-locate-change", { status: "ready", viewport });
         this.dispatchTypedEvent("honua-viewport-change", viewport);
@@ -1301,6 +1813,15 @@ export class HonuaMeasureControlElement extends HonuaElementBase {
         return ["for", "label"];
     }
     #mode = "off";
+    #messages = {};
+    /** Caller-supplied localized status, action, and empty-state messages. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
@@ -1311,23 +1832,25 @@ export class HonuaMeasureControlElement extends HonuaElementBase {
     render() {
         const label = this.getAttribute("label") ?? "Measure";
         const enabled = this.controller?.canMeasure() ?? false;
+        const status = enabled ? "ready" : "unsupported";
         this.setShadowHtml(`
       <style>${baseStyles()}${controlPanelStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(enabled ? "ready" : "unsupported")}</span>
+          <span>${escapeHtml(this.#messages.status?.[status] ?? status)}</span>
         </div>
         <div class="segmented" role="group" aria-label="${escapeAttribute(label)}">
           ${["off", "distance", "area"]
             .map((mode) => `
-            <button type="button" data-measure-mode="${mode}" aria-pressed="${String(this.#mode === mode)}"${enabled ? "" : ' aria-disabled="true" disabled'}>${escapeHtml(modeLabel(mode))}</button>
+            <button type="button" data-measure-mode="${mode}" aria-pressed="${String(this.#mode === mode)}"${enabled ? "" : ' aria-disabled="true" disabled'}>${escapeHtml(this.#messages.actionLabels?.[mode] ?? modeLabel(mode))}</button>
           `)
             .join("")}
         </div>
         ${enabled
             ? ""
-            : `<p class="empty" role="status">Measurement is disabled because no geometry provider is configured. Pass a \`measurementGeometry\` provider to the controller to enable distance and area measuring.</p>`}
+            : `<p class="empty" role="status">${escapeHtml(this.#messages.empty ??
+                "Measurement is disabled because no geometry provider is configured. Pass a `measurementGeometry` provider to the controller to enable distance and area measuring.")}</p>`}
       </section>
     `);
         if (!enabled)
@@ -1345,7 +1868,8 @@ export class HonuaMeasureControlElement extends HonuaElementBase {
             : {
                 mode,
                 status: "unsupported",
-                message: "Measurement requires a geometry provider. Configure `measurementGeometry` on the controller to enable measuring.",
+                message: this.#messages.unsupportedMessage ??
+                    "Measurement requires a geometry provider. Configure `measurementGeometry` on the controller to enable measuring.",
             };
         this.dispatchTypedEvent("honua-measure-change", detail);
         this.render();
@@ -1364,6 +1888,15 @@ export class HonuaSketchControlElement extends HonuaElementBase {
         return ["for", "label"];
     }
     #mode = "off";
+    #messages = {};
+    /** Caller-supplied localized status, action, and empty-state messages. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
@@ -1374,23 +1907,25 @@ export class HonuaSketchControlElement extends HonuaElementBase {
     render() {
         const label = this.getAttribute("label") ?? "Sketch";
         const enabled = this.controller?.canSketch() ?? false;
+        const status = enabled ? "ready" : "unsupported";
         this.setShadowHtml(`
       <style>${baseStyles()}${controlPanelStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(enabled ? "ready" : "unsupported")}</span>
+          <span>${escapeHtml(this.#messages.status?.[status] ?? status)}</span>
         </div>
         <div class="segmented" role="group" aria-label="${escapeAttribute(label)}">
           ${["off", "point", "line", "polygon"]
             .map((mode) => `
-            <button type="button" data-sketch-mode="${mode}" aria-pressed="${String(this.#mode === mode)}"${enabled ? "" : ' aria-disabled="true" disabled'}>${escapeHtml(modeLabel(mode))}</button>
+            <button type="button" data-sketch-mode="${mode}" aria-pressed="${String(this.#mode === mode)}"${enabled ? "" : ' aria-disabled="true" disabled'}>${escapeHtml(this.#messages.actionLabels?.[mode] ?? modeLabel(mode))}</button>
           `)
             .join("")}
         </div>
         ${enabled
             ? ""
-            : `<p class="empty" role="status">Sketching is disabled because no geometry provider is configured. Pass a \`sketchGeometry\` provider to the controller to enable point, line, and polygon drawing.</p>`}
+            : `<p class="empty" role="status">${escapeHtml(this.#messages.empty ??
+                "Sketching is disabled because no geometry provider is configured. Pass a `sketchGeometry` provider to the controller to enable point, line, and polygon drawing.")}</p>`}
       </section>
     `);
         if (!enabled)
@@ -1408,79 +1943,283 @@ export class HonuaSketchControlElement extends HonuaElementBase {
             : {
                 mode,
                 status: "unsupported",
-                message: "Sketching requires a geometry provider. Configure `sketchGeometry` on the controller to enable drawing.",
+                message: this.#messages.unsupportedMessage ??
+                    "Sketching requires a geometry provider. Configure `sketchGeometry` on the controller to enable drawing.",
             };
         this.dispatchTypedEvent("honua-sketch-change", detail);
         this.render();
     }
 }
+/** Legacy `honua-export` event `format` label for each export kind. */
+const EXPORT_FORMAT_BY_KIND = {
+    print: "print",
+    snapshot: "png",
+    state: "json",
+};
+const EXPORT_KIND_BY_FORMAT = {
+    print: "print",
+    png: "snapshot",
+    json: "state",
+};
+/** Maps an export outcome onto the shared component-status vocabulary. */
+const EXPORT_COMPONENT_STATUS = {
+    ready: "ready",
+    unsupported: "unsupported",
+    cancelled: "idle",
+    error: "error",
+};
+/**
+ * `<honua-print-export>` — print, snapshot, and sanitized state export.
+ *
+ * Assign {@link HonuaPrintExportElement.exportAdapter} to enable snapshot and
+ * state export. Without an adapter both **fail closed** (issue #683): the
+ * buttons render disabled with an explanation, and a programmatic
+ * `requestExport()` resolves to an `unsupported` result carrying a
+ * `HonuaCapabilityNotSupportedError` — never a blank image or a
+ * partially-credentialed JSON document. Browser print keeps working with no
+ * adapter, because `window.print()` reads no pixels and serializes no state.
+ */
 export class HonuaPrintExportElement extends HonuaElementBase {
+    #exportAdapter;
+    #lastResult;
+    #inFlight;
+    #messages = {};
+    /** Monotonic request generation; only the newest export may publish. */
+    #exportGeneration = 0;
     static get observedAttributes() {
         return ["for", "label", "title"];
     }
+    /**
+     * The application-supplied export adapter. Setting it re-renders so the
+     * snapshot/state affordances become enabled; clearing it re-disables them.
+     */
+    get exportAdapter() {
+        return this.#exportAdapter;
+    }
+    set exportAdapter(adapter) {
+        if (this.#exportAdapter === adapter)
+            return;
+        this.#exportAdapter = adapter;
+        this.render();
+    }
+    /** Caller-supplied localized status, action, and unsupported messages. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
+    /** The most recent export result, for callers that prefer polling to events. */
+    get lastExportResult() {
+        return this.#lastResult;
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
     }
+    disconnectedCallback() {
+        // An in-flight export outlives nothing: disconnecting cancels it so a
+        // detached element cannot keep an adapter (or a server-side render job)
+        // alive (REQ-005 deterministic disposal).
+        this.#inFlight?.abort();
+        this.#inFlight = undefined;
+        // Bump the generation too: an abort-ignoring adapter's continuation must
+        // not publish onto a detached element either.
+        this.#exportGeneration += 1;
+        super.disconnectedCallback();
+    }
+    /** Kinds that are actually available right now, given the assigned adapter. */
+    availableExportKinds() {
+        const adapter = this.#resolveAdapter();
+        if (!adapter)
+            return [];
+        try {
+            return adapter.describeCapabilities().kinds.filter((kind) => HONUA_EXPORT_KINDS.includes(kind));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Runs one export. Resolves with the full result envelope (never throws) and
+     * dispatches `honua-export` with a redacted projection of it.
+     */
+    async requestExport(kind) {
+        this.#inFlight?.abort();
+        const controller = typeof AbortController === "function" ? new AbortController() : undefined;
+        this.#inFlight = controller;
+        // An AbortSignal is advisory: an adapter is free to ignore it and settle
+        // later, so aborting the previous export does not guarantee it stays quiet.
+        // Ownership of the element's visible state therefore belongs to a
+        // generation, not to a controller — a completion that no longer owns the
+        // element neither publishes a result nor dispatches an event, so a slow
+        // first export cannot overwrite a newer one that already finished.
+        this.#exportGeneration += 1;
+        const generation = this.#exportGeneration;
+        const title = this.getAttribute("title") ?? this.state?.packageId ?? undefined;
+        const result = await runHonuaExport({
+            kind,
+            adapter: this.#resolveAdapter(kind),
+            state: this.state,
+            ...(title ? { title } : {}),
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+        if (this.#inFlight === controller)
+            this.#inFlight = undefined;
+        if (generation !== this.#exportGeneration) {
+            // Superseded. The caller still gets its own result — it asked for this
+            // export and is entitled to the outcome — but the element does not adopt
+            // it, and any resource the adapter handed back is released here, since
+            // nothing else now holds a reference to release it.
+            void result.release();
+            return result;
+        }
+        this.#lastResult = result;
+        this.dispatchTypedEvent("honua-export", exportDetailFromResult(result, title));
+        this.render();
+        return result;
+    }
+    /**
+     * Resolves the adapter for `kind`. The built-in browser-print adapter is used
+     * for `print` only when the application supplied nothing — snapshot and state
+     * have no built-in fallback by design.
+     */
+    #resolveAdapter(kind) {
+        if (this.#exportAdapter)
+            return this.#exportAdapter;
+        if (kind !== undefined && kind !== "print")
+            return undefined;
+        const printAdapter = createBrowserPrintExportAdapter();
+        return printAdapter.describeCapabilities().kinds.length > 0 ? printAdapter : undefined;
+    }
     render() {
         const label = this.getAttribute("label") ?? "Print and export";
+        const available = new Set(this.availableExportKinds());
+        const status = available.size === 0 ? "unsupported" : "ready";
+        const last = this.#lastResult;
+        const buttons = ["print", "snapshot", "state"]
+            .map((kind) => {
+            const enabled = available.has(kind);
+            const actionLabel = this.#messages.actionLabels?.[kind] ?? EXPORT_LABELS[kind];
+            const title = enabled
+                ? `${actionLabel} export`
+                : (this.#messages.unavailable?.[kind] ??
+                    `${actionLabel} export requires an application-supplied export adapter.`);
+            // Deliberately neither `disabled` nor `aria-disabled`, even when no
+            // adapter is assigned. Both suppress activation — assistive technology
+            // skips a disabled control, and Playwright treats either as
+            // non-actionable — which would silence the `honua-export` event that is
+            // how an application *discovers* it must supply an adapter. The
+            // unavailability is conveyed where it can still be read and acted on:
+            // an explanatory `title` on the control and the live-region readout
+            // below. Fail-closed is unaffected — activating it runs the export,
+            // which returns `unsupported` with no bytes.
+            return `<button type="button" data-export-format="${EXPORT_FORMAT_BY_KIND[kind]}" data-export-kind="${kind}"${enabled ? "" : ' data-export-unavailable="true"'} title="${escapeHtml(title)}">${escapeHtml(actionLabel)}</button>`;
+        })
+            .join("");
         this.setShadowHtml(`
       <style>${baseStyles()}${controlPanelStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(typeof window !== "undefined" && typeof window.print === "function" ? "ready" : "unsupported")}</span>
-        </div>
-        <div class="button-stack">
-          <button type="button" data-export-format="print">Print</button>
-          <button type="button" data-export-format="png">Snapshot</button>
-          <button type="button" data-export-format="json">State JSON</button>
+          <span>${escapeHtml(this.#messages.status?.[status] ?? status)}</span>
         </div>
+        <div class="button-stack">${buttons}</div>
+        <p part="status" role="status" aria-live="polite">${escapeHtml(exportStatusText(last, available, this.#messages))}</p>
       </section>
     `);
-        this.shadowRoot?.querySelectorAll("button[data-export-format]").forEach((button) => {
-            button.addEventListener("click", () => this.export(button.dataset.exportFormat));
-        });
-    }
-    export(format) {
-        const title = this.getAttribute("title") ?? this.state?.packageId ?? undefined;
-        if (format === "print" && typeof window !== "undefined" && typeof window.print === "function") {
-            this.dispatchTypedEvent("honua-export", {
-                format,
-                status: "ready",
-                ...(title ? { title } : {}),
+        this.shadowRoot?.querySelectorAll("button[data-export-kind]").forEach((button) => {
+            button.addEventListener("click", () => {
+                void this.requestExport(button.dataset.exportKind);
             });
-            window.print();
-            return;
-        }
-        const message = format === "print"
-            ? "Window printing is unavailable."
-            : "Snapshot export requires an application adapter to avoid leaking private map credentials.";
-        this.dispatchTypedEvent("honua-export", {
-            format,
-            status: "unsupported",
-            ...(title ? { title } : {}),
-            message,
         });
     }
 }
+const EXPORT_LABELS = {
+    print: "Print",
+    snapshot: "Snapshot",
+    state: "State JSON",
+};
+/**
+ * Redacted, displayable summary of the last export attempt — or, before any
+ * attempt, an honest statement of what is actually available. The
+ * adapter-required message is keyed on snapshot/state specifically, not on
+ * "nothing is available": browser print is available with no adapter, and
+ * reporting "ready to export" while two of the three buttons are inert would be
+ * exactly the kind of quiet degradation issue #683 exists to remove.
+ */
+function exportStatusText(result, available, messages = {}) {
+    if (!result) {
+        if (available.has("snapshot") && available.has("state"))
+            return messages.ready ?? "Ready to export.";
+        return available.size === 0
+            ? (messages.adapterRequired ?? "Assign an export adapter to enable export.")
+            : (messages.adapterRequiredForSnapshotState ?? "Assign an export adapter to enable snapshot and state export.");
+    }
+    if (result.status === "ready") {
+        const redacted = result.redactions.length > 0 ? ` ${result.redactions.length} value(s) were withheld as non-exportable.` : "";
+        return result.sideEffectOnly
+            ? `Print layout sent to the browser.${redacted}`
+            : `Exported ${result.filename ?? "artifact"}.${redacted}`;
+    }
+    return result.message ?? `Export ${result.status}.`;
+}
+/** Projects a result onto the event detail, carrying only redacted fields. */
+function exportDetailFromResult(result, title) {
+    const detail = {
+        format: EXPORT_FORMAT_BY_KIND[result.kind],
+        kind: result.kind,
+        status: EXPORT_COMPONENT_STATUS[result.status],
+        exportStatus: result.status,
+        redactionCount: result.redactions.length,
+    };
+    const mutable = detail;
+    if (title)
+        mutable.title = redactHonuaExportText(title);
+    if (result.message)
+        mutable.message = result.message;
+    if (result.adapterId)
+        mutable.adapterId = redactHonuaExportText(result.adapterId);
+    if (result.filename)
+        mutable.filename = result.filename;
+    if (result.mediaType)
+        mutable.mediaType = result.mediaType;
+    if (result.bytes)
+        mutable.byteLength = result.bytes.byteLength;
+    if (result.error)
+        mutable.errorCode = result.error.sdkCode;
+    return detail;
+}
+/** The `format` → export-kind mapping, exported for callers on the legacy event shape. */
+export function honuaExportKindFromFormat(format) {
+    return EXPORT_KIND_BY_FORMAT[format];
+}
 export class HonuaMapStatusElement extends HonuaElementBase {
     static get observedAttributes() {
         return ["for", "label", "attribution"];
     }
+    #messages = {};
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
     }
     render() {
-        const label = this.getAttribute("label") ?? "Map status";
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Map status";
         const attribution = this.getAttribute("attribution") ?? this.state?.mapPackage?.mapPackageId ?? "Honua";
         this.setShadowHtml(`
       <style>${baseStyles()}${mapStatusStyles()}</style>
       <section class="map-status" part="panel" aria-label="${escapeHtml(label)}">
-        <span aria-label="Approximate scale">${escapeHtml(approximateScale(this.state?.viewport))}</span>
-        <span aria-label="Attribution">${escapeHtml(attribution)}</span>
-        <button type="button" data-fullscreen>Fullscreen</button>
+        <span aria-label="${escapeAttribute(this.#messages.scaleLabel ?? "Approximate scale")}">${escapeHtml(approximateScale(this.state?.viewport))}</span>
+        <span aria-label="${escapeAttribute(this.#messages.attributionLabel ?? "Attribution")}">${escapeHtml(attribution)}</span>
+        <button type="button" data-fullscreen="action">${escapeHtml(this.#messages.fullscreenLabel ?? "Fullscreen")}</button>
       </section>
     `);
         this.shadowRoot?.querySelector("button[data-fullscreen]")?.addEventListener("click", () => {
@@ -1496,7 +2235,7 @@ export class HonuaMapStatusElement extends HonuaElementBase {
             this.dispatchTypedEvent("honua-fullscreen-change", {
                 fullscreen: false,
                 status: "unsupported",
-                message: "Fullscreen is unavailable.",
+                message: this.#messages.fullscreenUnavailable ?? "Fullscreen is unavailable.",
             });
             return;
         }
@@ -1511,22 +2250,32 @@ export class HonuaActionPanelElement extends HonuaElementBase {
     static get observedAttributes() {
         return ["for", "label", "actions"];
     }
+    #messages = {};
+    /** Caller-supplied localized panel label, status, and empty-state text. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.render();
+    }
     attributeChangedCallback() {
         this.resolveControllerFromContext();
         this.render();
     }
     render() {
-        const label = this.getAttribute("label") ?? "Actions";
+        const label = this.#messages.label ?? this.getAttribute("label") ?? "Actions";
         const actions = parseActions(this.getAttribute("actions"));
+        const status = actions.length > 0 ? "ready" : "unsupported";
         this.setShadowHtml(`
-      <style>${baseStyles()}${controlPanelStyles()}</style>
+      <style>${baseStyles()}${controlPanelStyles()}${actionPanelStyles()}</style>
       <section class="control-panel" part="panel" aria-label="${escapeHtml(label)}">
         <div class="control-panel__bar">
           <h2>${escapeHtml(label)}</h2>
-          <span>${escapeHtml(actions.length > 0 ? "ready" : "unsupported")}</span>
+          <span>${escapeHtml(this.#messages.status?.[status] ?? status)}</span>
         </div>
         ${actions.length === 0
-            ? `<p class="empty" role="status">No actions are configured.</p>`
+            ? `<p class="empty" role="status">${escapeHtml(this.#messages.empty ?? "No actions are configured.")}</p>`
             : `<div class="button-stack">
               ${actions
                 .map((action) => `
@@ -1549,33 +2298,71 @@ export class HonuaActionPanelElement extends HonuaElementBase {
         });
     }
 }
+/**
+ * Every tag this kit owns, keyed for both the blanket
+ * {@link defineHonuaWebComponents} registration and per-tag
+ * {@link defineHonuaWebComponent} lookups (and, transitively, the catalog id
+ * → constructor resolution `../controls/registry.js` uses for cross-kit
+ * registration). Order here is the kit's auto-registration order.
+ */
+const WEB_COMPONENT_ELEMENTS = new Map([
+    ["honua-map", HonuaMapElement],
+    ["honua-layer-list", HonuaLayerListElement],
+    ["honua-legend", HonuaLegendElement],
+    ["honua-feature-table", HonuaFeatureTableElement],
+    ["honua-search", HonuaSearchElement],
+    ["honua-editor", HonuaEditorElement],
+    ["honua-feature-editor", HonuaFeatureEditorElement],
+    ["honua-chart", HonuaChartElement],
+    ["honua-basemap-control", HonuaBasemapControlElement],
+    ["honua-bookmarks", HonuaBookmarksElement],
+    ["honua-locate-control", HonuaLocateControlElement],
+    ["honua-measure-control", HonuaMeasureControlElement],
+    ["honua-measurement", HonuaMeasurementElement],
+    ["honua-time-slider", HonuaTimeSliderElement],
+    ["honua-sketch-control", HonuaSketchControlElement],
+    ["honua-print-export", HonuaPrintExportElement],
+    ["honua-map-status", HonuaMapStatusElement],
+    ["honua-action-panel", HonuaActionPanelElement],
+]);
+/**
+ * Registers every custom element this kit owns. Skips tags already defined.
+ * Called automatically on import of `./index.js` (`@honua/sdk-js/web-components`)
+ * — NOT on import of this module, which stays side-effect-free (issue #679).
+ */
 export function defineHonuaWebComponents(registry = globalDom.customElements) {
     if (!registry)
         return;
-    defineIfMissing(registry, "honua-map", HonuaMapElement);
-    defineIfMissing(registry, "honua-layer-list", HonuaLayerListElement);
-    defineIfMissing(registry, "honua-legend", HonuaLegendElement);
-    defineIfMissing(registry, "honua-feature-table", HonuaFeatureTableElement);
-    defineIfMissing(registry, "honua-search", HonuaSearchElement);
-    defineIfMissing(registry, "honua-editor", HonuaEditorElement);
-    defineIfMissing(registry, "honua-chart", HonuaChartElement);
-    defineIfMissing(registry, "honua-basemap-control", HonuaBasemapControlElement);
-    defineIfMissing(registry, "honua-bookmarks", HonuaBookmarksElement);
-    defineIfMissing(registry, "honua-locate-control", HonuaLocateControlElement);
-    defineIfMissing(registry, "honua-measure-control", HonuaMeasureControlElement);
-    defineIfMissing(registry, "honua-measurement", HonuaMeasurementElement);
-    defineIfMissing(registry, "honua-sketch-control", HonuaSketchControlElement);
-    defineIfMissing(registry, "honua-print-export", HonuaPrintExportElement);
-    defineIfMissing(registry, "honua-map-status", HonuaMapStatusElement);
-    defineIfMissing(registry, "honua-action-panel", HonuaActionPanelElement);
+    for (const [tagName, ctor] of WEB_COMPONENT_ELEMENTS) {
+        defineIfMissing(registry, tagName, ctor);
+    }
+}
+/**
+ * Registers a single web-components tag by name (e.g. `"honua-feature-table"`).
+ * Unknown tags are a no-op. Skips the registration when the tag is already
+ * defined. This is the primitive the catalog-driven `registerComponent` /
+ * `registerComponents` APIs in `../controls/registry.js` call for
+ * `web-components`-sourced catalog entries, so a consumer can register one
+ * tag from this kit without the blanket {@link defineHonuaWebComponents} call.
+ */
+export function defineHonuaWebComponent(tagName, registry = globalDom.customElements) {
+    if (!registry)
+        return;
+    const ctor = WEB_COMPONENT_ELEMENTS.get(tagName);
+    if (ctor)
+        defineIfMissing(registry, tagName, ctor);
 }
 function defineIfMissing(registry, tagName, ctor) {
     if (!registry.get(tagName))
         registry.define(tagName, ctor);
 }
-if (globalDom.customElements) {
-    defineHonuaWebComponents(globalDom.customElements);
-}
+// Deliberately no module-load auto-registration here (issue #679 PR review):
+// this module must stay side-effect-free on import so `../controls/registry.js`
+// can dynamically `import()` it for single-tag registration without that
+// import silently claiming every tag the kit owns. The blanket
+// auto-registration importing `@honua/sdk-js/web-components` triggers lives
+// in `./index.js`, which is every existing consumer's actual entry point —
+// see that module for the `defineHonuaWebComponents()` call.
 function tableModelFromState(state, sourceId, fields, pageSize) {
     const resolvedSourceId = sourceId ?? Object.keys(state?.featuresBySource ?? {})[0];
     const rows = resolvedSourceId ? [...(state?.featuresBySource[resolvedSourceId] ?? [])] : [];
@@ -1674,24 +2461,16 @@ function getElementById(root, id) {
         return root.getElementById(id);
     return typeof document !== "undefined" ? document.getElementById(id) : null;
 }
-function formatCell(value) {
-    if (value === null || value === undefined)
-        return "";
-    if (typeof value === "object")
-        return JSON.stringify(value);
-    return String(value);
-}
 function modeLabel(mode) {
     return mode.charAt(0).toUpperCase() + mode.slice(1);
 }
+/**
+ * `<honua-map-status>`'s scale readout. Shares the single scale implementation
+ * with the export pipeline's provenance block (issue #683) so a printed or
+ * snapshotted map can never disagree with the scale the user saw on screen.
+ */
 function approximateScale(viewport) {
-    const zoom = viewport?.zoom;
-    if (!Number.isFinite(zoom))
-        return "Scale unavailable";
-    const latitude = viewport?.center?.[1] ?? 0;
-    const metersPerPixel = (156543.03392 * Math.cos((latitude * Math.PI) / 180)) / 2 ** Number(zoom);
-    const scale = Math.max(1, Math.round(metersPerPixel * 96 * 39.37));
-    return `1:${scale.toLocaleString("en-US")}`;
+    return approximateHonuaScaleLabel(viewport) ?? "Scale unavailable";
 }
 function setText(element, value) {
     if (element)
@@ -1765,6 +2544,13 @@ function escapeHtml(value) {
 function escapeAttribute(value) {
     return escapeHtml(value).replace(/'/g, "&#39;");
 }
+function formatLayerOpacityValue(format, percent) {
+    if (typeof format === "function")
+        return format(percent);
+    if (format !== undefined)
+        return format.replace("{percent}", String(percent));
+    return `${percent}%`;
+}
 function baseStyles() {
     return `
     :host {
@@ -1806,8 +2592,17 @@ function baseStyles() {
     }
   `;
 }
+function formatMapVisibleLayers(format, count) {
+    return typeof format === "function"
+        ? format(count)
+        : format
+            ? format.replace("{count}", String(count))
+            : `${count} visible`;
+}
 function mapStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .map {
       background: #dbeafe;
       border: 1px solid var(--honua-ui-border);
@@ -1823,7 +2618,8 @@ function mapStyles() {
       display: flex;
       gap: 8px;
       justify-content: space-between;
-      padding: 8px 10px;
+      padding-block: 8px;
+      padding-inline: 10px;
     }
     .map__controls { align-items: center; display: flex; gap: 6px; }
     .icon-button { min-width: 32px; padding: 0; }
@@ -1857,18 +2653,19 @@ function mapStyles() {
       position: absolute;
     }
     .map__renderer .maplibregl-canvas {
-      left: 0;
+      inset-block-start: 0;
+      inset-inline-start: 0;
       position: absolute;
-      top: 0;
     }
     .map__status {
       background: rgba(255,255,255,0.86);
       border-radius: 6px;
       color: var(--honua-ui-muted);
-      left: 10px;
-      padding: 4px 7px;
+      inset-block-start: 10px;
+      inset-inline-start: 10px;
+      padding-block: 4px;
+      padding-inline: 7px;
       position: absolute;
-      top: 10px;
       z-index: 1;
     }
     .map__status:empty { display: none; }
@@ -1876,21 +2673,52 @@ function mapStyles() {
     .maplibregl-control-container {
       display: none;
     }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .map {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .map__chrome, .map__footer, .map__status {
+        background: Canvas;
+        color: CanvasText;
+      }
+      .map__canvas { background: Canvas; }
+      .map__controls button { border-color: ButtonText; color: ButtonText; }
+    }
+    @media (max-width: 320px) {
+      .map { min-width: 0; }
+      .map__chrome, .map__footer {
+        align-items: stretch;
+        flex-direction: column;
+      }
+      .map__controls { justify-content: space-between; width: 100%; }
+    }
   `;
 }
 function listStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .panel {
       background: var(--honua-ui-bg);
       border: 1px solid var(--honua-ui-border);
       border-radius: 8px;
       margin: 0;
-      padding: 10px;
+      padding-block: 10px;
+      padding-inline: 10px;
     }
-    legend { font-weight: 650; padding: 0 4px; }
+    legend { font-weight: 650; padding-block: 0; padding-inline: 4px; }
     .stack { display: grid; gap: 8px; }
     .check-row { align-items: center; display: flex; gap: 8px; min-height: 28px; }
-    .legend { display: grid; gap: 8px; list-style: none; margin: 10px 0 0; padding: 0; }
+    .legend {
+      display: grid;
+      gap: 8px;
+      list-style: none;
+      margin-block-start: 10px;
+      margin-inline: 0;
+      padding: 0;
+    }
     .legend li { align-items: center; display: flex; gap: 8px; min-height: 24px; }
     .swatch {
       background: var(--swatch);
@@ -1903,6 +2731,23 @@ function listStyles() {
     img.swatch { object-fit: cover; }
   `;
 }
+function legendStyles() {
+    return `
+    @media (max-width: 320px) {
+      .panel { min-width: 0; }
+      .legend li { align-items: flex-start; min-width: 0; }
+      .legend li > span:last-child { min-width: 0; overflow-wrap: anywhere; }
+    }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .legend li { color: CanvasText; }
+      .legend .swatch {
+        background: Canvas;
+        border: 2px solid CanvasText;
+        forced-color-adjust: none;
+      }
+    }
+  `;
+}
 function layerListStyles() {
     return `
     .layer-row {
@@ -1915,14 +2760,33 @@ function layerListStyles() {
       align-items: center;
       display: flex;
       gap: 6px;
-      padding-left: 24px;
+      padding-inline-start: 24px;
     }
     .opacity { flex: 1; min-width: 60px; }
     .move { min-width: 32px; padding: 0; }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .layer-row {
+        border-top-color: CanvasText;
+      }
+      .layer-row input[type="checkbox"]:checked + span {
+        color: Highlight;
+      }
+      .layer-row__tools button {
+        border-color: ButtonText;
+      }
+    }
+    @media (max-width: 320px) {
+      .panel { min-width: 0; }
+      .layer-row__tools { flex-wrap: wrap; padding-left: 0; }
+      .opacity { min-width: 0; width: 100%; }
+      .move { flex: 1 1 32px; }
+    }
   `;
 }
 function tableStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .table-panel {
       border: 1px solid var(--honua-ui-border);
       border-radius: 8px;
@@ -1933,15 +2797,17 @@ function tableStyles() {
       background: var(--honua-ui-surface);
       display: flex;
       justify-content: space-between;
-      padding: 8px 10px;
+      padding-block: 8px;
+      padding-inline: 10px;
     }
     .table-wrap { max-height: 300px; overflow: auto; }
     table { border-collapse: collapse; min-width: 100%; table-layout: fixed; }
     th, td {
       border-top: 1px solid var(--honua-ui-border);
       overflow: hidden;
-      padding: 7px 9px;
-      text-align: left;
+      padding-block: 7px;
+      padding-inline: 9px;
+      text-align: start;
       text-overflow: ellipsis;
       white-space: nowrap;
     }
@@ -1949,63 +2815,133 @@ function tableStyles() {
     tr[aria-selected="true"] td { background: #dbeafe; }
     tbody tr[data-feature-id] { cursor: pointer; }
     tbody tr[data-feature-id]:focus { outline: 2px solid var(--honua-ui-accent); outline-offset: -2px; }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .table-panel {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .table-panel__bar, th { background: Canvas; color: CanvasText; }
+      th, td { border-top-color: CanvasText; }
+      tr[aria-selected="true"] td { background: Highlight; color: HighlightText; }
+      tbody tr[data-feature-id]:focus { outline-color: Highlight; }
+    }
   `;
 }
 function searchStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .search {
       border: 1px solid var(--honua-ui-border);
       border-radius: 8px;
-      padding: 10px;
+      min-width: 0;
+      padding-block: 10px;
+      padding-inline: 10px;
+      width: 100%;
     }
-    form { display: grid; gap: 8px; grid-template-columns: minmax(120px, 1fr) auto; }
+    form button { padding-block: 0; padding-inline: 10px; }
+    form { display: grid; gap: 8px; grid-template-columns: minmax(0, 1fr) auto; min-width: 0; }
     input {
       border: 1px solid var(--honua-ui-border);
       border-radius: 6px;
       min-height: 32px;
       min-width: 0;
-      padding: 0 9px;
+      padding-block: 0;
+      padding-inline: 9px;
+    }
+    .results {
+      display: grid;
+      gap: 6px;
+      list-style: none;
+      margin-block-start: 10px;
+      margin-inline: 0;
+      padding: 0;
     }
-    .results { display: grid; gap: 6px; list-style: none; margin: 10px 0 0; padding: 0; }
-    .results button { text-align: left; width: 100%; }
+    .results button { text-align: start; width: 100%; }
     .suggestions {
       border: 1px solid var(--honua-ui-border);
       border-radius: 6px;
       display: grid;
       list-style: none;
-      margin: 6px 0 0;
+      margin-block-start: 6px;
+      margin-inline: 0;
       overflow: hidden;
       padding: 0;
     }
     .suggestions[hidden] { display: none; }
-    .suggestions [role="option"] { cursor: pointer; padding: 6px 9px; }
+    .suggestions [role="option"] {
+      cursor: pointer;
+      padding-block: 6px;
+      padding-inline: 9px;
+    }
     .suggestions [role="option"][aria-selected="true"] {
       background: var(--honua-ui-accent);
       color: var(--honua-ui-accent-fg);
     }
-    .status { color: var(--honua-ui-muted); margin: 6px 0 0; }
+    .status { color: var(--honua-ui-muted); margin-block-start: 6px; margin-inline: 0; }
     .status:empty { display: none; }
+    @media (max-width: 320px) {
+      form { grid-template-columns: minmax(0, 1fr); }
+      form button { width: 100%; }
+    }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .search, input, button, .suggestions { border-color: CanvasText; }
+      .suggestions [role="option"][aria-selected="true"] {
+        background: Highlight;
+        color: HighlightText;
+      }
+    }
   `;
 }
 function editorStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .editor {
       border: 1px solid var(--honua-ui-border);
       border-radius: 8px;
-      padding: 10px;
+      padding-block: 10px;
+      padding-inline: 10px;
     }
+    button { padding-block: 0; padding-inline: 10px; }
     .editor__bar, .editor__actions { align-items: center; display: flex; gap: 8px; justify-content: space-between; }
     .editor__actions { justify-content: flex-start; }
-    .selection { margin: 10px 0 4px; }
-    .muted { margin: 0 0 10px; }
+    .selection { margin-block: 10px 4px; margin-inline: 0; }
+    .muted { margin-block: 0 10px; margin-inline: 0; }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .editor {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .editor__actions button {
+        border-color: ButtonText;
+        color: ButtonText;
+      }
+    }
+    @media (max-width: 320px) {
+      .editor { min-width: 0; }
+      .editor__bar { align-items: flex-start; flex-direction: column; }
+      .editor__actions { flex-wrap: wrap; }
+      .editor__actions button {
+        flex: 1 1 120px;
+        min-width: 0;
+        overflow-wrap: anywhere;
+        white-space: normal;
+      }
+    }
   `;
 }
 function chartStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .chart {
       border: 1px solid var(--honua-ui-border);
       border-radius: 8px;
-      padding: 10px;
+      padding-block: 10px;
+      padding-inline: 10px;
     }
     .bars { display: grid; gap: 8px; margin-top: 10px; }
     .bar-row { align-items: center; display: grid; gap: 8px; grid-template-columns: minmax(70px, 1fr) 3fr auto; }
@@ -2014,14 +2950,32 @@ function chartStyles() {
       background: var(--bar-color);
       border-radius: inherit;
       content: "";
-      inset: 0 auto 0 0;
+      inset-block: 0;
+      inset-inline-end: auto;
+      inset-inline-start: 0;
       position: absolute;
       width: var(--bar);
     }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .chart {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .bar { background: ButtonFace; outline: 1px solid ButtonText; }
+      .bar::before { background: Highlight; }
+    }
+    @media (max-width: 320px) {
+      .chart { min-width: 0; }
+      .bar-row { grid-template-columns: minmax(0, 1fr); }
+      .bar { min-width: 0; width: 100%; }
+    }
   `;
 }
 function controlPanelStyles() {
     return `
+    :host { direction: inherit; }
+    :host([dir="rtl"]) { direction: rtl; }
     .control-panel {
       background: var(--honua-ui-bg);
       border: 1px solid var(--honua-ui-border);
@@ -2029,13 +2983,24 @@ function controlPanelStyles() {
       display: grid;
       gap: 10px;
       min-width: 180px;
-      padding: 10px;
+      max-width: 100%;
+      min-inline-size: 0;
+      padding-block: 10px;
+      padding-inline: 10px;
     }
+    .control-panel > * { min-width: 0; max-width: 100%; }
+    button { padding-block: 0; padding-inline: 10px; }
     .control-panel__bar {
       align-items: center;
       display: flex;
       gap: 8px;
       justify-content: space-between;
+      min-width: 0;
+    }
+    .control-panel__bar h2,
+    .control-panel__bar span {
+      min-width: 0;
+      overflow-wrap: anywhere;
     }
     .control-panel__bar span {
       color: var(--honua-ui-muted);
@@ -2047,7 +3012,7 @@ function controlPanelStyles() {
     }
     .button-stack button {
       justify-content: flex-start;
-      text-align: left;
+      text-align: start;
     }
     .segmented {
       display: grid;
@@ -2056,7 +3021,10 @@ function controlPanelStyles() {
     }
     .segmented button {
       min-width: 0;
-      padding: 0 8px;
+      overflow-wrap: anywhere;
+      padding-block: 0;
+      padding-inline: 8px;
+      white-space: normal;
     }
     button[aria-pressed="true"] {
       background: var(--honua-ui-accent);
@@ -2065,6 +3033,93 @@ function controlPanelStyles() {
     }
     p {
       margin: 0;
+      overflow-wrap: anywhere;
+    }
+    @media (max-width: 240px) {
+      .control-panel {
+        min-width: 0;
+      }
+      .control-panel__bar {
+        align-items: flex-start;
+        flex-direction: column;
+      }
+      .control-panel__bar h2 {
+        min-width: 0;
+        overflow-wrap: anywhere;
+      }
+      .segmented {
+        grid-template-columns: 1fr;
+      }
+      .button-stack button,
+      .segmented button,
+      .control-panel > button {
+        width: 100%;
+      }
+    }
+    @media (min-width: 241px) and (max-width: 320px) {
+      .segmented { grid-template-columns: repeat(auto-fit, minmax(0, 1fr)); }
+    }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .control-panel {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .control-panel__bar span { color: CanvasText; }
+      .button-stack button {
+        background: ButtonFace;
+        border-color: ButtonText;
+        color: ButtonText;
+      }
+    }
+  `;
+}
+function basemapControlStyles() {
+    return `
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .control-panel {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .control-panel__bar span, .empty { color: CanvasText; }
+      .segmented button {
+        background: ButtonFace;
+        border: 2px solid ButtonText;
+        color: ButtonText;
+        forced-color-adjust: none;
+      }
+      .segmented button[aria-pressed="true"] {
+        background: Highlight;
+        border-color: Highlight;
+        color: HighlightText;
+      }
+      .segmented button:focus-visible {
+        outline: 2px solid Highlight;
+        outline-offset: 2px;
+      }
+    }
+  `;
+}
+function actionPanelStyles() {
+    return `
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .control-panel {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .control-panel__bar span, .empty { color: CanvasText; }
+      .button-stack button {
+        background: ButtonFace;
+        border: 2px solid ButtonText;
+        color: ButtonText;
+        forced-color-adjust: none;
+      }
+      .button-stack button:disabled {
+        border-color: GrayText;
+        color: GrayText;
+      }
     }
   `;
 }
@@ -2076,15 +3131,47 @@ function mapStatusStyles() {
       border: 1px solid var(--honua-ui-border);
       border-radius: 8px;
       display: flex;
+      direction: inherit;
       flex-wrap: wrap;
       gap: 8px;
       justify-content: space-between;
       min-height: 42px;
-      padding: 6px 8px;
+      padding-block: 6px;
+      padding-inline: 8px;
     }
     span {
       color: var(--honua-ui-muted);
       min-width: 0;
+      text-align: start;
+    }
+    .map-status button { text-align: start; }
+    @media (forced-colors: active), (prefers-contrast: more) {
+      .map-status {
+        background: Canvas;
+        border-color: CanvasText;
+        color: CanvasText;
+      }
+      .map-status span { color: CanvasText; }
+      .map-status button {
+        background: ButtonFace;
+        border: 2px solid ButtonText;
+        color: ButtonText;
+        forced-color-adjust: none;
+      }
+      :host([data-status="unsupported"]) .map-status {
+        border-color: GrayText;
+        color: GrayText;
+      }
+      :host([data-status="unsupported"]) .map-status span { color: GrayText; }
+      :host([data-status="error"]) .map-status {
+        border-color: Mark;
+        color: MarkText;
+      }
+      :host([data-status="error"]) .map-status span { color: MarkText; }
+    }
+    @media (max-width: 240px) {
+      .map-status { align-items: flex-start; flex-direction: column; }
+      .map-status button { inline-size: 100%; }
     }
   `;
 }