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

package/web-components/feature-table-engine.js

@@ -29,6 +29,7 @@
  *
  * @module
  */
+import { envelope } from "../core/spatial-filter.js";
 import { isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget } from "../exploration/selection.js";
 import { projectFilterRegistryToQuery } from "../filter-registry/index.js";
 import { reconcileRealtimeKeyedState, reconcileRealtimeViewport } from "../realtime/reconciliation.js";
@@ -43,12 +44,26 @@ export const DEFAULT_FEATURE_TABLE_BUDGETS = Object.freeze({
     maxCachedBytes: 4 * 1024 * 1024,
     maxRequests: 64,
     maxExportRows: 10_000,
+    maxFields: 64,
+    maxRenderedColumns: 12,
+    maxExportBytes: 16 * 1024 * 1024,
     windowOverscan: 20,
 });
 /** Select the work items attributed to one execution tier. */
 export function featureTableWorkByTier(evidence, tier) {
     return Object.freeze(evidence.work.filter((item) => item.tier === tier));
 }
+/** Horizontal counterpart of {@link featureTableWindow}. */
+export function featureTableColumnWindow(metrics, options) {
+    const width = metrics.columnWidth > 0 ? metrics.columnWidth : 1;
+    const overscan = Math.max(0, options.overscan ?? 1);
+    const total = Math.max(0, options.totalColumns);
+    const first = Math.max(0, Math.floor(Math.max(0, metrics.scrollLeft) / width) - overscan);
+    const visible = Math.max(1, Math.ceil(Math.max(0, metrics.viewportWidth) / width));
+    const span = Math.min(options.maxRenderedColumns, visible + overscan * 2);
+    const startIndex = Math.min(first, Math.max(0, total - span));
+    return Object.freeze({ startIndex, endIndex: Math.min(total, startIndex + span) });
+}
 /**
  * Pure window computation: which absolute row indices a renderer must paint
  * for the given scroll geometry, widened by `overscan` and clamped to
@@ -117,11 +132,17 @@ export function createHonuaFeatureTable(options) {
     const selectionTargetIndex = new Map();
     const misconfiguredPageSize = budgets.pageSize > budgets.maxCachedRows;
     let columns = resolveColumns(options.columns ?? []);
+    let viewportMode = options.viewportMode ?? "independent";
+    let viewportExtent = options.viewportExtent ? Object.freeze({ ...options.viewportExtent }) : undefined;
     let sort = Object.freeze([...(options.sort ?? [])]);
     let filters = normalizeFilters(options.filters);
     let selection = Object.freeze([]);
     let focus;
     let window = Object.freeze({ startIndex: 0, endIndex: 0 });
+    let columnWindow = Object.freeze({
+        startIndex: 0,
+        endIndex: Math.min(columns.filter((column) => column.visible).length, budgets.maxRenderedColumns),
+    });
     let state = identityField && !misconfiguredPageSize && queryCapabilityAdvertised !== false ? "idle" : "unsupported";
     let stale = false;
     let message = !identityField
@@ -132,18 +153,21 @@ export function createHonuaFeatureTable(options) {
                 ? `\`budgets.pageSize\` (${budgets.pageSize}) exceeds \`budgets.maxCachedRows\` (${budgets.maxCachedRows}), so ${PAGE_SIZE_HINT}`
                 : undefined;
     /** Set when a bounded operation had to give something up; survives a successful run. */
-    let budgetNotice;
+    let budgetNotice = columns.filter((column) => column.visible).length > budgets.maxFields
+        ? `Only the first ${budgets.maxFields} visible fields are projected and rendered.`
+        : undefined;
     let error;
     let conflicts = Object.freeze([]);
     let evidence = EMPTY_EVIDENCE;
     let count = Object.freeze({ kind: "unknown", loaded: 0, evidence: "none" });
+    const initialExhausted = columns.filter((column) => column.visible).length > budgets.maxFields ? ["fields"] : [];
     let ledger = Object.freeze({
         requests: 0,
         lifetimeRequests: 0,
         rows: 0,
         bytes: 0,
         evictedRows: 0,
-        exhausted: Object.freeze([]),
+        exhausted: Object.freeze(initialExhausted),
     });
     let totalKnown;
     /** Which evidence produced `totalKnown`. Never inferred after the fact. */
@@ -159,11 +183,16 @@ export function createHonuaFeatureTable(options) {
     let inFlight;
     // ── Snapshot assembly ───────────────────────────────────────
     function buildSnapshot() {
+        const visibleColumns = columns.filter((column) => column.visible).slice(0, budgets.maxFields);
+        const boundedColumnWindow = clampColumnWindow(columnWindow, visibleColumns.length, budgets.maxRenderedColumns);
+        columnWindow = boundedColumnWindow;
         return Object.freeze({
             sourceId: options.sourceId,
             state,
             columns,
-            visibleColumns: Object.freeze(columns.filter((column) => column.visible)),
+            visibleColumns: Object.freeze(visibleColumns),
+            renderedColumns: Object.freeze(visibleColumns.slice(boundedColumnWindow.startIndex, boundedColumnWindow.endIndex)),
+            columnWindow: boundedColumnWindow,
             rows: Object.freeze(rowsInWindow()),
             window,
             count,
@@ -177,6 +206,8 @@ export function createHonuaFeatureTable(options) {
             evidence,
             conflicts,
             stale,
+            viewportMode,
+            ...(viewportExtent ? { viewportExtent } : {}),
             ...(message !== undefined ? { message } : {}),
             ...(error !== undefined ? { error } : {}),
             revision,
@@ -229,14 +260,20 @@ export function createHonuaFeatureTable(options) {
     }
     // ── Query composition ───────────────────────────────────────
     function projection() {
-        const fields = columns.filter((column) => column.visible).map((column) => column.field);
+        const fields = columns
+            .filter((column) => column.visible)
+            .slice(0, budgets.maxFields)
+            .map((column) => column.field);
         if (fields.length === 0)
             return undefined;
         return identityField && !fields.includes(identityField) ? [...fields, identityField] : fields;
     }
     function orderedFields() {
-        const visible = columns.filter((column) => column.visible).map((column) => column.field);
-        return visible.length > 0 ? visible : columns.map((column) => column.field);
+        const visible = columns
+            .filter((column) => column.visible)
+            .slice(0, budgets.maxFields)
+            .map((column) => column.field);
+        return visible.length > 0 ? visible : columns.slice(0, budgets.maxFields).map((column) => column.field);
     }
     function composeQuery(page) {
         const descriptor = options.source.descriptor;
@@ -247,15 +284,29 @@ export function createHonuaFeatureTable(options) {
                 : {}),
         });
         const outFields = projection();
+        const extentFilter = viewportMode === "linked" && viewportExtent
+            ? envelope(viewportExtent.xmin, viewportExtent.ymin, viewportExtent.xmax, viewportExtent.ymax, viewportExtent.spatialReference)
+            : undefined;
+        const combined = combineFeatureTableSpatialFilters(extentFilter, projected.query.spatialFilter);
+        const spatialFilter = combined.filter;
         const query = {
             ...(projected.where !== undefined ? { where: projected.where } : {}),
-            ...(projected.query.spatialFilter ? { spatialFilter: projected.query.spatialFilter } : {}),
+            ...(spatialFilter ? { spatialFilter } : {}),
             ...(outFields ? { outFields } : {}),
             ...(sort.length > 0 ? { orderBy: [...sort] } : {}),
             pagination: { ...(page.offset === undefined ? {} : { offset: page.offset }), limit: page.limit },
             returnGeometry,
         };
-        return { query, degraded: projected.degraded ?? [], filterKey: projected.cacheKey };
+        const extentKey = extentFilter ? JSON.stringify(extentFilter.geometry) : "independent";
+        // The disjoint case is part of the cache identity: panning back into the
+        // filtered area must not be served the empty page cached while outside it.
+        const disjointKey = combined.disjoint ? "|disjoint" : "";
+        return {
+            query,
+            degraded: projected.degraded ?? [],
+            filterKey: `${projected.cacheKey}|viewport=${extentKey}${disjointKey}`,
+            empty: combined.disjoint,
+        };
     }
     function identity(filterKey, planFingerprint) {
         const descriptor = options.source.descriptor;
@@ -408,6 +459,19 @@ export function createHonuaFeatureTable(options) {
             evidence = buildEvidence(plan, composed.degraded, cacheKey);
             return cached;
         }
+        if (composed.empty) {
+            // No request: the intersection is empty by construction. The page is
+            // cached under the disjoint filter key so re-entering the filtered area
+            // rebuilds a real query rather than reusing this one.
+            sequence += 1;
+            const emptyPage = { offset, rows: Object.freeze([]), bytes: 0, cacheKey, sequence };
+            pages.set(offset, emptyPage);
+            exhausted = true;
+            totalKnown = 0;
+            totalEvidence = "exhausted-pages";
+            evidence = buildEvidence(plan, composed.degraded, cacheKey);
+            return emptyPage;
+        }
         if (ledger.requests >= budgets.maxRequests) {
             markExhausted("requests");
             return undefined;
@@ -615,7 +679,12 @@ export function createHonuaFeatureTable(options) {
         // refuse to load a brand-new question forever, so the per-identity counter
         // and its exhaustion flags reset while the lifetime totals stay intact.
         ledger = Object.freeze({ ...ledger, requests: 0, exhausted: Object.freeze([]) });
-        budgetNotice = undefined;
+        budgetNotice =
+            columns.filter((column) => column.visible).length > budgets.maxFields
+                ? `Only the first ${budgets.maxFields} visible fields are projected and rendered.`
+                : undefined;
+        if (budgetNotice)
+            markExhausted("fields");
         conflicts = Object.freeze([]);
         if (state !== "unsupported")
             state = "idle";
@@ -722,6 +791,7 @@ export function createHonuaFeatureTable(options) {
         const nextField = fields[field];
         if (!row || nextField === undefined)
             return publish();
+        revealColumn(field, fields.length);
         focus = Object.freeze({ rowKey: row.key, field: nextField });
         return publish();
     }
@@ -733,6 +803,13 @@ export function createHonuaFeatureTable(options) {
         }
         return max;
     }
+    function revealColumn(index, totalColumns) {
+        if (index >= columnWindow.startIndex && index < columnWindow.endIndex)
+            return;
+        const span = Math.min(budgets.maxRenderedColumns, totalColumns);
+        const startIndex = index < columnWindow.startIndex ? index : index - span + 1;
+        columnWindow = clampColumnWindow({ startIndex, endIndex: startIndex + span }, totalColumns, span);
+    }
     // ── Realtime reconciliation (REQ-005) ───────────────────────
     function reconcile(diff) {
         const keyed = {
@@ -779,6 +856,18 @@ export function createHonuaFeatureTable(options) {
                 const attributes = change.record?.feature.attributes;
                 if (!attributes)
                     continue;
+                if (filters.length > 0) {
+                    stale = true;
+                    if (state === "ready" || state === "partial")
+                        state = "stale";
+                    message = "A live update may have changed filtered membership; refresh the bounded page.";
+                    nextConflicts.push({
+                        code: "filter-membership-unknown",
+                        message,
+                        rowKeys: Object.freeze([change.key]),
+                    });
+                    continue;
+                }
                 if (changesSortKey(existing.attributes, attributes, sortFields)) {
                     nextConflicts.push({
                         code: "sort-key-changed",
@@ -876,20 +965,59 @@ export function createHonuaFeatureTable(options) {
     async function setColumns(nextColumns) {
         const before = (projection() ?? []).join(",");
         columns = resolveColumns(nextColumns);
-        if ((projection() ?? []).join(",") === before)
+        const fieldsExceeded = columns.filter((column) => column.visible).length > budgets.maxFields;
+        if ((projection() ?? []).join(",") === before) {
+            if (fieldsExceeded) {
+                markExhausted("fields");
+                budgetNotice = `Only the first ${budgets.maxFields} visible fields are projected and rendered.`;
+            }
             return publish();
+        }
         invalidate();
+        if (fieldsExceeded) {
+            markExhausted("fields");
+            budgetNotice = `Only the first ${budgets.maxFields} visible fields are projected and rendered.`;
+        }
         ensureWindow();
         return run(undefined);
     }
+    async function runAggregation(aggregation, aggregateOptions = {}) {
+        throwIfAborted(aggregateOptions.signal);
+        const composed = composeQuery({ limit: budgets.pageSize });
+        if (composed.empty) {
+            return Object.freeze({
+                rows: Object.freeze([]),
+                truncated: false,
+                evidence: buildEvidence(options.planner?.(composed.query), composed.degraded, composed.filterKey),
+            });
+        }
+        const query = {
+            ...composed.query,
+            aggregation,
+            returnGeometry: false,
+            pagination: { limit: budgets.pageSize },
+            ...(aggregateOptions.signal ? { signal: aggregateOptions.signal } : {}),
+        };
+        const plan = options.planner?.(query);
+        const result = await options.source.query(query);
+        throwIfAborted(aggregateOptions.signal);
+        const aggregateEvidence = buildEvidence(plan, [...composed.degraded, ...(result.degraded ?? [])], composed.filterKey);
+        return Object.freeze({
+            rows: Object.freeze(result.features.slice(0, budgets.pageSize).map((feature) => feature.attributes)),
+            truncated: result.features.length > budgets.pageSize || result.exceededTransferLimit === true,
+            evidence: aggregateEvidence,
+        });
+    }
     async function runExport(request) {
         const fields = orderedFields();
         if (currentState() === "unsupported") {
+            const serialized = serializeBoundedExport(request.format, [], fields, columns, budgets.maxExportBytes);
             return Object.freeze({
                 format: request.format,
-                content: request.format === "csv" ? toCsv([], fields, columns) : toJson([], fields, columns),
+                content: serialized.content,
                 rowCount: 0,
-                truncated: false,
+                truncated: serialized.truncated,
+                ...(serialized.truncated ? { limit: "export-bytes" } : {}),
                 columns: Object.freeze([...fields]),
                 evidence,
             });
@@ -928,16 +1056,100 @@ export function createHonuaFeatureTable(options) {
         }
         recomputeCount();
         publish();
+        const serialized = serializeBoundedExport(request.format, rows, fields, columns, budgets.maxExportBytes);
+        if (serialized.truncated)
+            limit = "export-bytes";
         return Object.freeze({
             format: request.format,
-            content: request.format === "csv" ? toCsv(rows, fields, columns) : toJson(rows, fields, columns),
-            rowCount: rows.length,
+            content: serialized.content,
+            rowCount: serialized.rowCount,
             truncated: limit !== undefined,
             ...(limit ? { limit } : {}),
             columns: Object.freeze([...fields]),
             evidence,
         });
     }
+    async function runSecureExport(request) {
+        throwIfAborted(request.signal);
+        const fields = orderedFields();
+        const maxRows = Math.max(0, Math.min(request.maxRows ?? budgets.maxExportRows, budgets.maxExportRows));
+        const first = composeQuery({ offset: 0, limit: Math.min(budgets.pageSize, Math.max(1, maxRows)) });
+        const plan = options.planner?.(first.query);
+        const authorization = await request.adapter.authorize({
+            sourceId: options.sourceId,
+            format: request.format,
+            selectionOnly: request.selectionOnly === true,
+            maxRows,
+            maxBytes: budgets.maxExportBytes,
+            authorizationScope,
+            ...(plan ? { planId: plan.id, planFingerprint: plan.fingerprint } : {}),
+            ...(request.signal ? { signal: request.signal } : {}),
+        });
+        throwIfAborted(request.signal);
+        if (!authorization.authorized) {
+            throw new Error(authorization.reason ?? "The host denied the table export under the current authorization.");
+        }
+        const selected = request.selectionOnly ? new Set(selection) : undefined;
+        const rows = [];
+        let offset = 0;
+        let requests = 0;
+        let degraded = first.degraded;
+        let sourceExhausted = false;
+        while (rows.length < maxRows && requests < budgets.maxRequests && !sourceExhausted) {
+            throwIfAborted(request.signal);
+            const composed = composeQuery({ offset, limit: budgets.pageSize });
+            if (composed.empty) {
+                degraded = composed.degraded;
+                sourceExhausted = true;
+                break;
+            }
+            const result = await options.source.query({
+                ...composed.query,
+                ...(request.signal ? { signal: request.signal } : {}),
+            });
+            requests += 1;
+            degraded = [...composed.degraded, ...(result.degraded ?? [])];
+            for (const [index, feature] of result.features.entries()) {
+                const row = toRow(feature, offset + index);
+                if (!row)
+                    continue;
+                if ((!selected || selected.has(row.key)) && rows.length < maxRows)
+                    rows.push(row);
+            }
+            sourceExhausted = result.features.length < budgets.pageSize && result.exceededTransferLimit !== true;
+            offset += budgets.pageSize;
+        }
+        throwIfAborted(request.signal);
+        const exportEvidence = buildEvidence(plan, degraded, first.filterKey);
+        const serialized = serializeBoundedExport(request.format, rows, fields, columns, budgets.maxExportBytes);
+        const truncated = serialized.truncated ||
+            rows.length >= maxRows ||
+            (!sourceExhausted && requests >= budgets.maxRequests) ||
+            (selected !== undefined && rows.length < selected.size);
+        const provenance = Object.freeze({
+            sourceId: options.sourceId,
+            adapterId: request.adapter.id,
+            authorizationId: authorization.authorizationId,
+            exportedAt: new Date().toISOString(),
+            format: request.format,
+            rowCount: serialized.rowCount,
+            truncated,
+            authorizationScope,
+            ...(plan ? { planId: plan.id, planFingerprint: plan.fingerprint } : {}),
+        });
+        await request.adapter.record(provenance);
+        throwIfAborted(request.signal);
+        return Object.freeze({
+            format: request.format,
+            content: serialized.content,
+            rowCount: serialized.rowCount,
+            truncated,
+            ...(serialized.truncated ? { limit: "export-bytes" } : {}),
+            columns: Object.freeze([...fields]),
+            evidence: exportEvidence,
+            provenance,
+        });
+    }
     return {
         get snapshot() {
             return snapshot;
@@ -960,6 +1172,17 @@ export function createHonuaFeatureTable(options) {
             window = next;
             return run(undefined);
         },
+        setColumnScroll(metrics) {
+            const totalColumns = Math.min(budgets.maxFields, columns.filter((column) => column.visible).length);
+            const next = featureTableColumnWindow(metrics, {
+                totalColumns,
+                maxRenderedColumns: budgets.maxRenderedColumns,
+            });
+            if (next.startIndex === columnWindow.startIndex && next.endIndex === columnWindow.endIndex)
+                return snapshot;
+            columnWindow = next;
+            return publish();
+        },
         setSort,
         async toggleSort(field, toggleOptions = {}) {
             const existing = sort.find((entry) => entry.field === field);
@@ -980,6 +1203,23 @@ export function createHonuaFeatureTable(options) {
         async setColumnVisibility(field, visible) {
             return setColumns(columns.map((column) => (column.field === field ? { ...column, visible } : { ...column })));
         },
+        async setViewportMode(mode) {
+            if (mode === viewportMode)
+                return snapshot;
+            viewportMode = mode;
+            invalidate();
+            ensureWindow();
+            return run(undefined);
+        },
+        async setViewportExtent(extent) {
+            viewportExtent = extent ? Object.freeze({ ...extent }) : undefined;
+            if (viewportMode === "independent")
+                return publish();
+            invalidate();
+            ensureWindow();
+            return run(undefined);
+        },
+        aggregate: runAggregation,
         select(keys, selectOptions = {}) {
             setSelection(selectOptions.replace === false ? [...selection, ...keys] : keys);
         },
@@ -1014,6 +1254,12 @@ export function createHonuaFeatureTable(options) {
             return Object.freeze(out);
         },
         setFocus(nextFocus) {
+            if (nextFocus) {
+                const fields = orderedFields();
+                const index = fields.indexOf(nextFocus.field);
+                if (index >= 0)
+                    revealColumn(index, fields.length);
+            }
             focus = nextFocus ? Object.freeze({ ...nextFocus }) : undefined;
             publish();
         },
@@ -1031,6 +1277,7 @@ export function createHonuaFeatureTable(options) {
             publish();
         },
         export: runExport,
+        secureExport: runSecureExport,
         cancel() {
             const controller = inFlight;
             inFlight = undefined;
@@ -1073,6 +1320,10 @@ export function linkFeatureTableToExploration(table, view, options = {}) {
     const syncFilters = options.filters ?? true;
     const syncSelection = options.selection ?? true;
     const syncPage = options.page ?? true;
+    const syncExtent = options.extent ?? false;
+    if (syncExtent) {
+        void table.setViewportMode("linked").then(() => table.setViewportExtent(view.state.extent));
+    }
     let applying = false;
     let suppressFilterPublish = 0;
     /** Filter snapshots requested by inbound assignments; these are suppressed. */
@@ -1096,7 +1347,7 @@ export function linkFeatureTableToExploration(table, view, options = {}) {
             }
         }
     }
-    const unsubscribeContext = view.subscribe(["selection", "sort", "visibleFields", "filters"], (event) => {
+    const unsubscribeContext = view.subscribe(["selection", "sort", "visibleFields", "filters", "extent"], (event) => {
         if (applying)
             return;
         applying = true;
@@ -1130,6 +1381,8 @@ export function linkFeatureTableToExploration(table, view, options = {}) {
                     }
                 });
             }
+            if (syncExtent && event.changedSlices.has("extent"))
+                void table.setViewportExtent(event.state.extent);
         }
         finally {
             applying = false;
@@ -1343,10 +1596,104 @@ function toCsv(rows, fields, columns) {
     }
     return lines.join("\n");
 }
+/**
+ * Largest row prefix that fits `maxBytes`, found by binary search.
+ *
+ * Trimming one row at a time re-encoded the whole export on every step, so a
+ * 10,000-row export of wide attributes could run thousands of full CSV/JSON
+ * encodings on the main thread -- a bounded export that freezes the page is
+ * not bounded. Both encoders are prefix-monotonic (a longer prefix is never
+ * fewer bytes: CSV appends whole lines, JSON appends whole elements), so the
+ * fitting prefixes form a contiguous range and bisection finds its edge in
+ * O(log n) encodings.
+ */
+function serializeBoundedExport(format, rows, fields, columns, maxBytes) {
+    const encoder = new TextEncoder();
+    const encode = (kept) => format === "csv" ? toCsv(rows.slice(0, kept), fields, columns) : toJson(rows.slice(0, kept), fields, columns);
+    const fits = (content) => encoder.encode(content).byteLength <= maxBytes;
+    const whole = encode(rows.length);
+    if (fits(whole))
+        return { content: whole, rowCount: rows.length, truncated: false };
+    // Invariant: `best` always fits, `high` never does. The header-only export
+    // is the floor; when even that overflows the budget nothing can be emitted.
+    let best;
+    let low = 0;
+    let high = rows.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        const content = encode(middle);
+        if (fits(content)) {
+            best = { content, rowCount: middle };
+            low = middle + 1;
+        }
+        else {
+            high = middle;
+        }
+    }
+    if (best)
+        return { content: best.content, rowCount: best.rowCount, truncated: best.rowCount < rows.length };
+    return { content: "", rowCount: 0, truncated: true };
+}
 function csvCell(value) {
-    if (!value.includes(",") && !value.includes('"') && !value.includes("\n"))
-        return value;
-    return `"${value.split('"').join('""')}"`;
+    // Spreadsheet programs treat leading =, +, -, @, tab, and carriage return
+    // as formula/control syntax even in a CSV cell. Prefixing an apostrophe
+    // forces literal display and prevents a server-returned value from becoming
+    // executable spreadsheet content when a user opens the bounded export.
+    const safe = /^[\t\r]|^\s*[=+\-@]/.test(value) ? `'${value}` : value;
+    if (!safe.includes(",") && !safe.includes('"') && !safe.includes("\n"))
+        return safe;
+    return `"${safe.split('"').join('""')}"`;
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    if (typeof signal.throwIfAborted === "function")
+        signal.throwIfAborted();
+    const error = new Error("The table operation was cancelled.");
+    error.name = "AbortError";
+    throw error;
+}
+function sameSpatialReference(left, right) {
+    if (left === undefined || right === undefined)
+        return true;
+    if (left === right)
+        return true;
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function combineFeatureTableSpatialFilters(extent, existing) {
+    if (!extent)
+        return { disjoint: false, filter: existing };
+    if (!existing)
+        return { disjoint: false, filter: extent };
+    if (extent.geometryType !== "esriGeometryEnvelope" || existing.geometryType !== "esriGeometryEnvelope") {
+        throw new Error("A linked table extent cannot be combined exactly with a non-envelope spatial filter; use independent viewport mode or an envelope filter.");
+    }
+    const left = extent.geometry;
+    const right = existing.geometry;
+    const values = [left.xmin, left.ymin, left.xmax, left.ymax, right.xmin, right.ymin, right.xmax, right.ymax];
+    if (!values.every((value) => typeof value === "number" && Number.isFinite(value))) {
+        throw new Error("A linked table extent and spatial filter must contain finite envelope coordinates.");
+    }
+    const leftReference = left.spatialReference;
+    const rightReference = right.spatialReference;
+    if (!sameSpatialReference(leftReference, rightReference)) {
+        throw new Error("A linked table extent and spatial filter must share one spatial reference; reproject the filter or use independent viewport mode.");
+    }
+    const xmin = Math.max(left.xmin, right.xmin);
+    const ymin = Math.max(left.ymin, right.ymin);
+    const xmax = Math.min(left.xmax, right.xmax);
+    const ymax = Math.min(left.ymax, right.ymax);
+    if (xmin > xmax || ymin > ymax)
+        return { disjoint: true };
+    return {
+        disjoint: false,
+        filter: envelope(xmin, ymin, xmax, ymax, (leftReference ?? rightReference)),
+    };
+}
+function clampColumnWindow(value, totalColumns, maxRenderedColumns) {
+    const span = Math.min(maxRenderedColumns, totalColumns);
+    const startIndex = Math.min(Math.max(0, value.startIndex), Math.max(0, totalColumns - span));
+    return Object.freeze({ startIndex, endIndex: Math.min(totalColumns, startIndex + span) });
 }
 function toJson(rows, fields, columns) {
     const byField = new Map(columns.map((column) => [column.field, column]));

package/web-components/feature-table-view.d.ts

@@ -16,7 +16,7 @@
  * @module
  */
 import type { SortSpec } from "../contract/types.js";
-import { type HonuaFeatureTableConflict, type HonuaFeatureTableCount, type HonuaFeatureTableFocus, type HonuaFeatureTableFocusMove, type HonuaFeatureTableResolvedColumn, type HonuaFeatureTableSnapshot, type HonuaFeatureTableState, type HonuaFeatureTableWindow } from "./feature-table-engine.js";
+import { type HonuaFeatureTableConflict, type HonuaFeatureTableCount, type HonuaFeatureTableFocus, type HonuaFeatureTableFocusMove, type HonuaFeatureTableQueryEvidence, type HonuaFeatureTableResolvedColumn, type HonuaFeatureTableSnapshot, type HonuaFeatureTableState, type HonuaFeatureTableWindow } from "./feature-table-engine.js";
 import type { HonuaFeatureTableModel } from "./types.js";
 /** One rendered row. `placeholder` rows sit inside the window but are not resident. */
 export interface HonuaFeatureTableViewRow {
@@ -29,11 +29,26 @@ export interface HonuaFeatureTableViewRow {
     readonly cells: readonly string[];
     readonly placeholder: boolean;
 }
+/** One visible diagnostic describing where accepted query-plan work ran. */
+export interface HonuaFeatureTableWorkBadge {
+    readonly tier: "server" | "worker" | "client";
+    readonly label: string;
+    readonly detail: string;
+}
+export interface HonuaFeatureTableColumnControl {
+    readonly field: string;
+    readonly label: string;
+    readonly visible: boolean;
+}
 /** Everything the renderer needs. Derived from an engine snapshot. */
 export interface HonuaFeatureTableViewModel {
     readonly label: string;
     readonly state: HonuaFeatureTableState;
     readonly columns: readonly HonuaFeatureTableResolvedColumn[];
+    readonly totalColumnCount: number;
+    readonly columnWindow: HonuaFeatureTableWindow;
+    readonly columnWidth: number;
+    readonly columnControls: readonly HonuaFeatureTableColumnControl[];
     readonly rows: readonly HonuaFeatureTableViewRow[];
     readonly window: HonuaFeatureTableWindow;
     readonly ariaRowCount: number;
@@ -42,9 +57,19 @@ export interface HonuaFeatureTableViewModel {
     readonly sort: readonly SortSpec[];
     readonly focus?: HonuaFeatureTableFocus;
     readonly conflicts: readonly HonuaFeatureTableConflict[];
+    /** Compact server/worker/client diagnostics projected from accepted-plan evidence. */
+    readonly workBadges: readonly HonuaFeatureTableWorkBadge[];
     /** Row height in CSS pixels; drives the virtualization spacers. */
     readonly rowHeight: number;
     readonly busy: boolean;
+    /**
+     * The user unchecked every column. Distinct from a merely empty horizontal
+     * window: the grid renders an explicit no-column state instead of a column
+     * the controls report as hidden.
+     */
+    readonly columnsHidden: boolean;
+    /** Announced in place of the grid when {@link columnsHidden} is set. */
+    readonly columnsHiddenLabel?: string;
 }
 /** Caller-supplied labels and announcements for `<honua-feature-table>`. */
 export interface HonuaFeatureTableMessages {
@@ -52,6 +77,8 @@ export interface HonuaFeatureTableMessages {
     readonly count?: (count: HonuaFeatureTableCount) => string;
     readonly status?: Partial<Readonly<Record<HonuaFeatureTableState, string>>>;
     readonly state?: (state: HonuaFeatureTableState, count: HonuaFeatureTableCount, message?: string) => string;
+    /** Shown in place of the grid when every column has been hidden. */
+    readonly columnsHidden?: string;
 }
 /** Human/screen-reader summary of the table's lifecycle state. */
 export declare function describeFeatureTableState(state: HonuaFeatureTableState, count: HonuaFeatureTableCount, message: string | undefined, messages?: HonuaFeatureTableMessages): string;
@@ -59,6 +86,7 @@ export declare function describeFeatureTableState(state: HonuaFeatureTableState,
 export declare function featureTableViewModel<T>(snapshot: HonuaFeatureTableSnapshot<T>, options?: {
     readonly label?: string;
     readonly rowHeight?: number;
+    readonly columnWidth?: number;
     readonly messages?: HonuaFeatureTableMessages;
 }): HonuaFeatureTableViewModel;
 /**
@@ -74,6 +102,12 @@ export declare function legacyFeatureTableViewModel<T>(model: HonuaFeatureTableM
     readonly selectedFeatureId?: string;
     readonly messages?: HonuaFeatureTableMessages;
 }): HonuaFeatureTableViewModel;
+/**
+ * Collapse accepted-plan work into compact, accessible execution diagnostics.
+ * The labels never infer pushdown: a tier appears only when the engine's
+ * evidence names work that actually ran there.
+ */
+export declare function featureTableWorkBadges(evidence: HonuaFeatureTableQueryEvidence): readonly HonuaFeatureTableWorkBadge[];
 /**
  * Map a `KeyboardEvent.key` (plus modifiers) onto a grid navigation move.
  * Returns `undefined` for keys the grid must not swallow.