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

package/web-components/feature-inspection.js

@@ -0,0 +1,1464 @@
+/**
+ * Capability-aware feature inspection workflow.
+ *
+ * The controller in this module is the supported join between map hits,
+ * server search, table rows, source-qualified selection, popup/details
+ * presentation, attachments, relationships, and realtime freshness. It never
+ * evaluates Arcade or inserts source HTML into the document.
+ *
+ * @module
+ */
+import { queryFilter } from "../contract/query-filter.js";
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { featureSelectionKey, sourceFeatureSelectionTarget } from "../exploration/selection.js";
+import { renderCspSafeShadowHtml } from "./csp-styles.js";
+const DEFAULT_PAGE_SIZE = 10;
+const DEFAULT_MAX_PAGES = 5;
+const DEFAULT_MAX_OVERLAPPING = 25;
+const DEFAULT_MAX_FIELDS = 24;
+const DEFAULT_MAX_RELATIONSHIPS = 8;
+const DEFAULT_DETAILS_TTL_MS = 30_000;
+const DEFAULT_SEARCH_TTL_MS = 5_000;
+const DEFAULT_CACHE_ENTRIES = 100;
+class BoundedTtlCache {
+    maxEntries;
+    now;
+    #entries = new Map();
+    constructor(maxEntries, now) {
+        this.maxEntries = maxEntries;
+        this.now = now;
+    }
+    get(key) {
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.#entries.delete(key);
+            return undefined;
+        }
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        this.#entries.delete(key);
+        this.#entries.set(key, { value, expiresAt: this.now() + Math.max(0, ttlMs) });
+        while (this.#entries.size > this.maxEntries) {
+            const oldest = this.#entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#entries.delete(oldest);
+        }
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}
+/** Create a bounded, cancellable inspection workflow. */
+export function createHonuaFeatureInspection(options) {
+    return new FeatureInspectionController(options);
+}
+/**
+ * Bind inspection to the supported application shell without introducing a
+ * second selection identity or authorization cache scope.
+ */
+export function createHonuaFeatureInspectionFromApplicationContext(context, options = {}) {
+    const boundSource = () => context.snapshot.binding.source;
+    const sourceIdentity = () => context.snapshot.binding.sourceIdentity ?? context.snapshot.binding.source?.descriptor.id;
+    return createHonuaFeatureInspection({
+        ...options,
+        resolveSource: (sourceId) => {
+            const source = boundSource();
+            if (source && (sourceIdentity() === sourceId || source.descriptor.id === sourceId))
+                return source;
+            return options.resolveSource?.(sourceId);
+        },
+        sourceIds: options.sourceIds ?? (sourceIdentity() ? [sourceIdentity()] : []),
+        selection: {
+            setSelection(targets) {
+                context.update({ selection: targets });
+            },
+        },
+        authScope: () => {
+            const authorization = context.snapshot.authorization;
+            return [authorization.status, authorization.principalId ?? "", ...authorization.scopes].join(":");
+        },
+        version: () => [
+            context.snapshot.binding.sourceIdentity ?? "",
+            context.snapshot.binding.planIdentity ?? "",
+            context.snapshot.invalidationGeneration,
+            context.snapshot.freshness.generation,
+        ].join(":"),
+    });
+}
+class FeatureInspectionController {
+    options;
+    #listeners = new Set();
+    #now;
+    #detailsCache;
+    #searchCache;
+    #pageSize;
+    #maxStoredItems;
+    #maxOverlapping;
+    #maxFields;
+    #maxRelationships;
+    #maxSearchSources;
+    #detailsTtlMs;
+    #searchTtlMs;
+    #detailsAbort;
+    #searchAbort;
+    #generation = 0;
+    #disposed = false;
+    #cachedDetails;
+    #attachmentPage = 0;
+    #relationshipPages = new Map();
+    #state = {
+        status: "idle",
+        candidates: [],
+        activeIndex: 0,
+        relationships: [],
+        diagnostics: [],
+        search: { status: "idle", query: "", results: [], diagnostics: [] },
+    };
+    constructor(options) {
+        this.options = options;
+        this.#now = options.now ?? Date.now;
+        const budgets = options.budgets ?? {};
+        this.#pageSize = positiveInteger(budgets.pageSize, DEFAULT_PAGE_SIZE);
+        const maxPages = positiveInteger(budgets.maxPages, DEFAULT_MAX_PAGES);
+        this.#maxStoredItems = this.#pageSize * maxPages;
+        this.#maxOverlapping = positiveInteger(budgets.maxOverlappingResults, DEFAULT_MAX_OVERLAPPING);
+        this.#maxFields = positiveInteger(budgets.maxFields, DEFAULT_MAX_FIELDS);
+        this.#maxRelationships = positiveInteger(budgets.maxRelationships, DEFAULT_MAX_RELATIONSHIPS);
+        this.#maxSearchSources = positiveInteger(budgets.maxSearchSources, 10);
+        const cacheEntries = positiveInteger(budgets.cacheEntries, DEFAULT_CACHE_ENTRIES);
+        this.#detailsCache = new BoundedTtlCache(cacheEntries, this.#now);
+        this.#searchCache = new BoundedTtlCache(cacheEntries, this.#now);
+        this.#detailsTtlMs = nonNegativeNumber(options.detailsTtlMs, DEFAULT_DETAILS_TTL_MS);
+        this.#searchTtlMs = nonNegativeNumber(options.searchTtlMs, DEFAULT_SEARCH_TTL_MS);
+    }
+    snapshot() {
+        return this.#state;
+    }
+    subscribe(listener) {
+        this.#assertLive();
+        this.#listeners.add(listener);
+        listener(this.#state);
+        return { remove: () => this.#listeners.delete(listener) };
+    }
+    openFromMapClick(candidates) {
+        return this.open(candidates, { origin: "map" });
+    }
+    openFromTableRow(candidate) {
+        return this.open(candidate, { origin: "table" });
+    }
+    openSearchResult(index) {
+        const result = this.#state.search.results[index];
+        if (!result)
+            return Promise.resolve(this.#state);
+        return this.open({ target: result.target, feature: result.feature, authoritative: true }, { origin: "search" });
+    }
+    async open(input, options = {}) {
+        this.#assertLive();
+        const supplied = (Array.isArray(input) ? input : [input]);
+        const deduped = dedupeCandidates(supplied).slice(0, this.#maxOverlapping);
+        if (deduped.length === 0) {
+            this.close();
+            return this.#state;
+        }
+        const diagnostics = [];
+        if (supplied.length > deduped.length) {
+            diagnostics.push({
+                code: "result-limit",
+                message: `Inspection is limited to ${this.#maxOverlapping} overlapping results. Refine the map hit or search to inspect more.`,
+            });
+        }
+        const activeIndex = clamp(options.activeIndex ?? 0, 0, deduped.length - 1);
+        const candidate = deduped[activeIndex];
+        if (!candidate)
+            return this.#state;
+        const origin = options.origin ?? "programmatic";
+        this.#detailsAbort?.abort();
+        this.#detailsAbort = new AbortController();
+        this.#generation += 1;
+        const generation = this.#generation;
+        this.#cachedDetails = undefined;
+        this.#attachmentPage = 0;
+        this.#relationshipPages.clear();
+        this.#state = {
+            ...this.#state,
+            status: "loading",
+            origin,
+            candidates: deduped,
+            activeIndex,
+            feature: undefined,
+            attachments: undefined,
+            relationships: [],
+            diagnostics,
+            staleReason: undefined,
+        };
+        this.options.selection?.setSelection([candidate.target], { origin });
+        this.#notify();
+        const source = this.options.resolveSource(candidate.target.sourceId);
+        if (!source || !source.capabilities.has("query")) {
+            if (generation !== this.#generation)
+                return this.#state;
+            const diagnostic = capabilityDiagnostic("query", candidate.target.sourceId, source?.descriptor.protocol);
+            this.#state = { ...this.#state, status: "unsupported", diagnostics: [...diagnostics, diagnostic] };
+            this.#notify();
+            return this.#state;
+        }
+        const presentation = this.#presentation(source);
+        const fields = requiredFields(source, presentation, this.#maxFields);
+        const key = this.#detailsKey(source, candidate.target, fields);
+        const cached = options.force ? undefined : this.#detailsCache.get(key);
+        try {
+            const details = cached ??
+                (await this.#loadDetails(source, candidate, presentation, fields, this.#detailsAbort.signal, diagnostics));
+            if (generation !== this.#generation || this.#detailsAbort.signal.aborted)
+                return this.#state;
+            if (!cached)
+                this.#detailsCache.set(key, details, this.#detailsTtlMs);
+            this.#cachedDetails = details;
+            this.#state = this.#projectDetails("ready", details);
+            this.#notify();
+            return this.#state;
+        }
+        catch (error) {
+            if (generation !== this.#generation || isAbortError(error))
+                return this.#state;
+            const diagnostic = diagnosticForError(error, "query-failed", candidate.target.sourceId);
+            this.#state = {
+                ...this.#state,
+                status: error instanceof HonuaCapabilityNotSupportedError ? "unsupported" : "error",
+                diagnostics: [...diagnostics, diagnostic],
+            };
+            this.#notify();
+            return this.#state;
+        }
+    }
+    async search(query, options = {}) {
+        this.#assertLive();
+        const normalized = query.trim();
+        this.#searchAbort?.abort();
+        if (!normalized) {
+            this.#setSearch({ status: "idle", query: "", results: [], diagnostics: [] });
+            return this.#state.search;
+        }
+        const controller = new AbortController();
+        this.#searchAbort = controller;
+        const sourceIds = [...new Set(options.sourceIds ?? this.options.sourceIds ?? [])].slice(0, this.#maxSearchSources);
+        this.#setSearch({ status: "loading", query: normalized, results: [], diagnostics: [] });
+        const diagnostics = [];
+        const results = [];
+        await Promise.all(sourceIds.map(async (sourceId) => {
+            const source = this.options.resolveSource(sourceId);
+            if (!source || !source.capabilities.has("query")) {
+                diagnostics.push({
+                    code: "search-unsupported",
+                    capability: "query",
+                    sourceId,
+                    message: `Server search is unavailable for source "${sourceId}" because it does not advertise query.`,
+                });
+                return;
+            }
+            const fields = this.#searchFields(source);
+            if (fields.length === 0) {
+                diagnostics.push({
+                    code: "search-unsupported",
+                    capability: "query",
+                    sourceId,
+                    message: `Server search is unavailable for source "${sourceId}" because it has no searchable fields.`,
+                });
+                return;
+            }
+            const cacheKey = this.#searchKey(source, normalized, fields);
+            const cached = this.#searchCache.get(cacheKey);
+            if (cached) {
+                results.push(...cached);
+                return;
+            }
+            try {
+                const pk = primaryKey(source);
+                const outFields = uniqueStrings([pk, ...fields]).slice(0, this.#maxFields);
+                const result = await source.query({
+                    filter: queryFilter.or(...fields.map((field) => queryFilter.like(field, `%${normalized}%`))),
+                    outFields,
+                    returnGeometry: false,
+                    pagination: { limit: this.#maxStoredItems },
+                    signal: controller.signal,
+                });
+                const sourceResults = result.features.slice(0, this.#maxStoredItems).map((feature, index) => {
+                    const id = featureId(feature.attributes, pk, index);
+                    const target = sourceFeatureSelectionTarget(sourceId, id);
+                    const presentation = this.#presentation(source);
+                    return {
+                        id: featureSelectionKey(target),
+                        target,
+                        title: featureTitle(feature.attributes, presentation.titleField, id),
+                        subtitle: source.descriptor.id,
+                        feature,
+                    };
+                });
+                this.#searchCache.set(cacheKey, sourceResults, this.#searchTtlMs);
+                results.push(...sourceResults);
+                if (result.exceededTransferLimit || result.features.length > this.#maxStoredItems) {
+                    diagnostics.push({
+                        code: "result-limit",
+                        sourceId,
+                        message: `Search results for source "${sourceId}" were limited to ${this.#maxStoredItems}. Refine the search text for more specific results.`,
+                    });
+                }
+            }
+            catch (error) {
+                if (isAbortError(error))
+                    return;
+                diagnostics.push(diagnosticForError(error, "search-failed", sourceId));
+            }
+        }));
+        if (controller.signal.aborted || this.#searchAbort !== controller)
+            return this.#state.search;
+        const bounded = dedupeSearchResults(results).slice(0, this.#maxStoredItems);
+        const status = bounded.length > 0 || diagnostics.length === 0
+            ? "ready"
+            : diagnostics.every(isUnsupportedDiagnostic)
+                ? "unsupported"
+                : "error";
+        this.#setSearch({ status, query: normalized, results: bounded, diagnostics });
+        return this.#state.search;
+    }
+    navigate(index) {
+        if (this.#state.candidates.length === 0)
+            return Promise.resolve(this.#state);
+        return this.open(this.#state.candidates, {
+            origin: this.#state.origin ?? "programmatic",
+            activeIndex: clamp(index, 0, this.#state.candidates.length - 1),
+        });
+    }
+    next() {
+        return this.navigate(this.#state.activeIndex + 1);
+    }
+    previous() {
+        return this.navigate(this.#state.activeIndex - 1);
+    }
+    setAttachmentPage(page) {
+        if (!this.#cachedDetails)
+            return this.#state;
+        this.#attachmentPage = boundedPage(page, this.#cachedDetails.attachmentTotal, this.#pageSize);
+        this.#state = this.#projectDetails(this.#state.status, this.#cachedDetails);
+        this.#notify();
+        return this.#state;
+    }
+    setRelationshipPage(relationshipId, page) {
+        if (!this.#cachedDetails)
+            return this.#state;
+        const relationship = this.#cachedDetails.relationships.find((candidate) => candidate.id === relationshipId);
+        if (!relationship)
+            return this.#state;
+        this.#relationshipPages.set(relationshipId, boundedPage(page, relationship.total, this.#pageSize));
+        this.#state = this.#projectDetails(this.#state.status, this.#cachedDetails);
+        this.#notify();
+        return this.#state;
+    }
+    refresh() {
+        if (this.#state.candidates.length === 0)
+            return Promise.resolve(this.#state);
+        return this.open(this.#state.candidates, {
+            activeIndex: this.#state.activeIndex,
+            origin: "refresh",
+            force: true,
+        });
+    }
+    applyRealtime(update) {
+        const current = this.#state.feature;
+        if (!current || featureSelectionKey(current.target) !== featureSelectionKey(update.target))
+            return this.#state;
+        if (update.kind === "delete") {
+            this.#detailsAbort?.abort();
+            this.#cachedDetails = undefined;
+            this.#state = {
+                ...this.#state,
+                status: "deleted",
+                feature: undefined,
+                attachments: undefined,
+                relationships: [],
+                staleReason: "The selected feature was deleted by a realtime update.",
+            };
+            this.#notify();
+            return this.#state;
+        }
+        const changedFields = update.changedFields ?? [];
+        const loadedFields = new Set(current.fields.map((field) => field.name));
+        const safePatch = update.completeness === "full" ||
+            (update.completeness === "patch" &&
+                changedFields.length > 0 &&
+                changedFields.every((field) => loadedFields.has(field)));
+        if (!safePatch || !update.attributes) {
+            this.#state = {
+                ...this.#state,
+                status: "stale",
+                staleReason: "A realtime update changed fields that were not safely patchable. Refresh to load the authoritative feature.",
+            };
+            this.#notify();
+            return this.#state;
+        }
+        const attributes = update.completeness === "full"
+            ? update.attributes
+            : { ...current.attributes, ...update.attributes };
+        const source = this.options.resolveSource(current.target.sourceId);
+        if (!source)
+            return this.#state;
+        const feature = projectFeature(current.target, { attributes, ...(update.geometry !== undefined ? { geometry: update.geometry } : {}) }, source, this.#presentation(source), this.options, [], current.fields.map((field) => field.name));
+        this.#state = { ...this.#state, status: "ready", feature, staleReason: undefined };
+        this.#notify();
+        return this.#state;
+    }
+    close() {
+        if (this.#disposed)
+            return;
+        this.#detailsAbort?.abort();
+        this.#detailsAbort = undefined;
+        this.#generation += 1;
+        this.#cachedDetails = undefined;
+        this.#state = {
+            ...this.#state,
+            status: "idle",
+            origin: undefined,
+            candidates: [],
+            activeIndex: 0,
+            feature: undefined,
+            attachments: undefined,
+            relationships: [],
+            diagnostics: [],
+            staleReason: undefined,
+        };
+        this.options.selection?.setSelection([], { origin: "programmatic" });
+        this.#notify();
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#detailsAbort?.abort();
+        this.#searchAbort?.abort();
+        this.#detailsCache.clear();
+        this.#searchCache.clear();
+        this.#listeners.clear();
+    }
+    async #loadDetails(source, candidate, presentation, fields, signal, initialDiagnostics) {
+        const pk = primaryKey(source);
+        const feature = candidate.authoritative && candidate.feature
+            ? candidate.feature
+            : (await source.query({
+                filter: queryFilter.eq(pk, scalarFeatureId(candidate.target.id)),
+                outFields: fields,
+                returnGeometry: false,
+                pagination: { limit: 1 },
+                signal,
+            })).features[0];
+        if (!feature) {
+            throw new FeatureNotFoundError(candidate.target.sourceId, candidate.target.id);
+        }
+        const diagnostics = [...initialDiagnostics];
+        if ((presentation.arcadeExpressions?.length ?? 0) > 0) {
+            diagnostics.push({
+                code: "popup-arcade-unsupported",
+                sourceId: candidate.target.sourceId,
+                message: "Arcade popup expressions are not executed. Replace them with server-computed fields or application-owned presentation logic.",
+            });
+        }
+        const projected = projectFeature(candidate.target, feature, source, presentation, this.options, diagnostics, fields);
+        const [attachmentResult, relationshipResult] = await Promise.all([
+            this.#loadAttachments(source, candidate.target, signal),
+            this.#loadRelationships(source, candidate.target, signal),
+        ]);
+        diagnostics.push(...attachmentResult.diagnostics, ...relationshipResult.diagnostics);
+        return {
+            feature: projected,
+            attachments: attachmentResult.items,
+            attachmentTotal: attachmentResult.total,
+            attachmentTruncated: attachmentResult.truncated,
+            relationships: relationshipResult.items,
+            diagnostics,
+        };
+    }
+    async #loadAttachments(source, target, signal) {
+        if (!source.capabilities.has("attachments")) {
+            return {
+                items: [],
+                total: 0,
+                truncated: false,
+                diagnostics: [capabilityDiagnostic("attachments", target.sourceId, source.descriptor.protocol)],
+            };
+        }
+        if (!this.options.loadAttachmentPage) {
+            return {
+                items: [],
+                total: 0,
+                truncated: false,
+                diagnostics: [
+                    {
+                        code: "attachments-unbounded",
+                        capability: "attachments",
+                        sourceId: target.sourceId,
+                        message: "Attachments were not requested because the canonical source API cannot bound the response. Configure loadAttachmentPage with a protocol-aware offset/limit implementation.",
+                    },
+                ],
+            };
+        }
+        try {
+            const result = await this.options.loadAttachmentPage({
+                source,
+                target,
+                offset: 0,
+                limit: this.#maxStoredItems,
+                signal,
+            });
+            signal.throwIfAborted();
+            const bounded = result.items.slice(0, this.#maxStoredItems);
+            const items = bounded.map((attachment) => {
+                const rawHref = this.options.attachmentHref?.(attachment, target);
+                const href = rawHref
+                    ? sanitizeHonuaInspectionHref(rawHref, {
+                        baseHref: this.options.baseHref,
+                        allowedOrigins: this.options.allowedLinkOrigins,
+                    })
+                    : undefined;
+                return { ...attachment, ...(href ? { href } : {}) };
+            });
+            return {
+                items,
+                total: Math.max(items.length, result.total),
+                truncated: result.truncated === true || result.total > items.length || result.items.length > items.length,
+                diagnostics: result.items.length > this.#maxStoredItems
+                    ? [
+                        {
+                            code: "result-limit",
+                            sourceId: target.sourceId,
+                            message: `The attachment loader returned more than its ${this.#maxStoredItems}-item limit. Extra entries were discarded.`,
+                        },
+                    ]
+                    : [],
+            };
+        }
+        catch (error) {
+            if (isAbortError(error))
+                throw error;
+            return {
+                items: [],
+                total: 0,
+                truncated: false,
+                diagnostics: [diagnosticForError(error, "attachments-failed", target.sourceId)],
+            };
+        }
+    }
+    async #loadRelationships(source, target, signal) {
+        const definitions = this.#relationships(source).slice(0, this.#maxRelationships);
+        if (definitions.length === 0)
+            return { items: [], diagnostics: [] };
+        if (!source.capabilities.has("queryRelated")) {
+            return {
+                items: [],
+                diagnostics: [capabilityDiagnostic("queryRelated", target.sourceId, source.descriptor.protocol)],
+            };
+        }
+        if (!this.options.loadRelationshipPage) {
+            return {
+                items: [],
+                diagnostics: [
+                    {
+                        code: "relationships-unbounded",
+                        capability: "queryRelated",
+                        sourceId: target.sourceId,
+                        message: "Related records were not requested because the canonical source API cannot bound the response. Configure loadRelationshipPage with a protocol-aware offset/limit implementation.",
+                    },
+                ],
+            };
+        }
+        const loadRelationshipPage = this.options.loadRelationshipPage;
+        const diagnostics = [];
+        const items = await Promise.all(definitions.map(async (definition) => {
+            try {
+                const result = await loadRelationshipPage({
+                    source,
+                    target,
+                    relationship: {
+                        ...definition,
+                        ...(definition.outFields ? { outFields: definition.outFields.slice(0, this.#maxFields) } : {}),
+                    },
+                    offset: 0,
+                    limit: this.#maxStoredItems,
+                    signal,
+                });
+                signal.throwIfAborted();
+                const features = result.items.slice(0, this.#maxStoredItems);
+                const total = Math.max(features.length, result.total);
+                if (result.items.length > this.#maxStoredItems) {
+                    diagnostics.push({
+                        code: "result-limit",
+                        sourceId: target.sourceId,
+                        relationshipId: definition.id,
+                        message: `The related-record loader returned more than its ${this.#maxStoredItems}-item limit. Extra entries were discarded.`,
+                    });
+                }
+                return {
+                    id: definition.id,
+                    label: definition.label ?? `Related records ${definition.id}`,
+                    fields: result.fields ?? [],
+                    features,
+                    total,
+                    truncated: result.truncated === true || total > features.length || result.items.length > features.length,
+                };
+            }
+            catch (error) {
+                if (isAbortError(error))
+                    throw error;
+                diagnostics.push({
+                    ...diagnosticForError(error, "relationships-failed", target.sourceId),
+                    relationshipId: definition.id,
+                });
+                return undefined;
+            }
+        }));
+        return { items: items.filter((item) => item !== undefined), diagnostics };
+    }
+    #projectDetails(status, details) {
+        return {
+            ...this.#state,
+            status,
+            feature: details.feature,
+            attachments: pageOf(details.attachments, details.attachmentTotal, this.#attachmentPage, this.#pageSize, details.attachmentTruncated),
+            relationships: details.relationships.map((relationship) => ({
+                id: relationship.id,
+                label: relationship.label,
+                fields: relationship.fields,
+                page: pageOf(relationship.features, relationship.total, this.#relationshipPages.get(relationship.id) ?? 0, this.#pageSize, relationship.truncated),
+            })),
+            diagnostics: details.diagnostics,
+        };
+    }
+    #presentation(source) {
+        const configured = this.options.presentation;
+        return (typeof configured === "function" ? configured(source) : configured) ?? {};
+    }
+    #relationships(source) {
+        const configured = this.options.relationships;
+        return (typeof configured === "function" ? configured(source) : configured) ?? [];
+    }
+    #searchFields(source) {
+        const configured = this.options.searchFields;
+        const fields = typeof configured === "function" ? configured(source) : configured;
+        if (fields)
+            return uniqueStrings(fields).slice(0, this.#maxFields);
+        return searchableFields(source.descriptor.schema?.fields ?? []).slice(0, this.#maxFields);
+    }
+    #detailsKey(source, target, fields) {
+        const relationships = this.#relationships(source)
+            .slice(0, this.#maxRelationships)
+            .map((relationship) => `${relationship.id}:${relationship.outFields?.join(",") ?? "*"}`)
+            .join("|");
+        return [
+            featureSelectionKey(target),
+            fields.join(","),
+            relationships,
+            this.options.authScope?.() ?? "",
+            this.options.version?.(source) ?? "",
+        ].join("\u0001");
+    }
+    #searchKey(source, query, fields) {
+        return [
+            source.descriptor.id,
+            query.toLocaleLowerCase(),
+            fields.join(","),
+            this.options.authScope?.() ?? "",
+            this.options.version?.(source) ?? "",
+        ].join("\u0001");
+    }
+    #setSearch(search) {
+        this.#state = { ...this.#state, search };
+        this.#notify();
+    }
+    #notify() {
+        for (const listener of this.#listeners)
+            listener(this.#state);
+    }
+    #assertLive() {
+        if (this.#disposed)
+            throw new Error("HonuaFeatureInspectionController has been disposed");
+    }
+}
+class FeatureNotFoundError extends Error {
+    sourceId;
+    featureId;
+    constructor(sourceId, featureId) {
+        super(`Feature ${String(featureId)} was not found in source ${sourceId}`);
+        this.sourceId = sourceId;
+        this.featureId = featureId;
+        this.name = "FeatureNotFoundError";
+    }
+}
+function projectFeature(target, feature, source, presentation, options, diagnostics, requestedFields = requiredFields(source, presentation, DEFAULT_MAX_FIELDS)) {
+    const attributes = feature.attributes;
+    const schemaFields = new Map((source.descriptor.schema?.fields ?? []).map((field) => [field.name, field]));
+    const names = requestedFields.filter((name) => name in attributes);
+    const fields = names.map((name) => ({
+        name,
+        label: schemaFields.get(name)?.alias ?? name,
+        value: attributes[name],
+        text: formatHonuaInspectionValue(attributes[name]),
+    }));
+    const links = [];
+    for (const link of presentation.links ?? []) {
+        const raw = attributes[link.hrefField];
+        if (typeof raw !== "string" || !raw.trim())
+            continue;
+        const href = sanitizeHonuaInspectionHref(raw, {
+            baseHref: options.baseHref,
+            allowedOrigins: options.allowedLinkOrigins,
+        });
+        if (!href) {
+            diagnostics.push({
+                code: "unsafe-link",
+                sourceId: target.sourceId,
+                message: `The external link in field "${link.hrefField}" was withheld because its URL is unsafe or outside the configured origins.`,
+            });
+            continue;
+        }
+        const baseOrigin = safeOrigin(options.baseHref);
+        links.push({ label: link.label, href, external: safeOrigin(href) !== baseOrigin });
+    }
+    const description = presentation.description
+        ? sanitizeHonuaInspectionRichText(interpolateInspectionTemplate(presentation.description, attributes))
+        : undefined;
+    return {
+        target,
+        title: featureTitle(feature.attributes, presentation.titleField, target.id),
+        ...(description ? { description } : {}),
+        fields,
+        links,
+        attributes: feature.attributes,
+        ...(feature.geometry !== undefined ? { geometry: feature.geometry } : {}),
+    };
+}
+function requiredFields(source, presentation, maxFields) {
+    const pk = primaryKey(source);
+    const requested = presentation.fields ?? source.descriptor.schema?.fields?.map((field) => field.name) ?? [pk];
+    const linkFields = presentation.links?.map((link) => link.hrefField) ?? [];
+    return uniqueStrings([
+        pk,
+        ...(presentation.titleField ? [presentation.titleField] : []),
+        ...requested,
+        ...linkFields,
+    ]).slice(0, maxFields);
+}
+function primaryKey(source) {
+    return (source.descriptor.schema?.primaryKey ??
+        source.descriptor.schema?.fields?.find((field) => /^(objectid|fid|id)$/i.test(field.name))?.name ??
+        "OBJECTID");
+}
+function searchableFields(fields) {
+    const strings = fields.filter((field) => /string|guid/i.test(field.type)).map((field) => field.name);
+    return strings.length > 0 ? strings : fields.map((field) => field.name);
+}
+function scalarFeatureId(id) {
+    return id;
+}
+function featureId(attributes, pk, fallbackIndex) {
+    const record = asRecord(attributes);
+    const value = record[pk];
+    if (typeof value === "string" || typeof value === "number")
+        return value;
+    for (const name of ["OBJECTID", "objectid", "id", "ID", "fid", "FID"]) {
+        const candidate = record[name];
+        if (typeof candidate === "string" || typeof candidate === "number")
+            return candidate;
+    }
+    return `result:${fallbackIndex}`;
+}
+function featureTitle(attributes, titleField, id) {
+    const record = asRecord(attributes);
+    const named = titleField ? record[titleField] : undefined;
+    if (typeof named === "string" && named.trim())
+        return named;
+    for (const key of ["name", "Name", "NAME", "title", "Title", "TITLE", "label", "Label", "LABEL"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim())
+            return value;
+    }
+    return String(id);
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" ? value : {};
+}
+function dedupeCandidates(candidates) {
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        const key = featureSelectionKey(candidate.target);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function dedupeSearchResults(results) {
+    const seen = new Set();
+    return results.filter((result) => {
+        if (seen.has(result.id))
+            return false;
+        seen.add(result.id);
+        return true;
+    });
+}
+function pageOf(values, total, page, limit, truncated) {
+    const resolvedPage = boundedPage(page, total, limit);
+    const offset = resolvedPage * limit;
+    return {
+        items: values.slice(offset, offset + limit),
+        offset,
+        limit,
+        total,
+        hasPrevious: resolvedPage > 0,
+        hasNext: offset + limit < total && offset + limit < values.length,
+        truncated,
+    };
+}
+function boundedPage(page, total, limit) {
+    return clamp(Math.trunc(page), 0, Math.max(0, Math.ceil(total / limit) - 1));
+}
+function capabilityDiagnostic(capability, sourceId, protocol = "unknown") {
+    const error = new HonuaCapabilityNotSupportedError(capability, protocol, sourceId);
+    const labels = { query: "Feature details", attachments: "Attachments", queryRelated: "Related records" };
+    const codes = {
+        query: "query-unsupported",
+        attachments: "attachments-unsupported",
+        queryRelated: "relationships-unsupported",
+    };
+    return {
+        code: codes[capability],
+        capability,
+        sourceId,
+        message: `${labels[capability]} are unavailable: ${error.message}. Choose a source that advertises "${capability}" or hide this presentation.`,
+    };
+}
+function diagnosticForError(error, fallback, sourceId) {
+    if (error instanceof FeatureNotFoundError) {
+        return {
+            code: "feature-not-found",
+            sourceId,
+            message: `Feature "${String(error.featureId)}" is no longer available in source "${sourceId}". Clear the selection or refresh its origin.`,
+        };
+    }
+    if (error instanceof HonuaCapabilityNotSupportedError) {
+        const capability = error.capability === "attachments" || error.capability === "queryRelated" ? error.capability : "query";
+        return capabilityDiagnostic(capability, sourceId, error.protocol);
+    }
+    const labels = {
+        "query-failed": "Feature details could not be loaded. Retry or verify access to the source.",
+        "search-failed": "Server search failed. Refine the query, retry, or verify access to the source.",
+        "attachments-failed": "Attachments could not be loaded. Retry or verify attachment access.",
+        "relationships-failed": "Related records could not be loaded. Retry or verify relationship access.",
+    };
+    return { code: fallback, sourceId, message: labels[fallback] };
+}
+function isUnsupportedDiagnostic(diagnostic) {
+    return diagnostic.code.endsWith("-unsupported");
+}
+function isAbortError(error) {
+    return ((typeof DOMException === "function" && error instanceof DOMException && error.name === "AbortError") ||
+        (error instanceof Error && error.name === "AbortError"));
+}
+function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function nonNegativeNumber(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => value.trim().length > 0))];
+}
+function safeOrigin(value) {
+    if (!value)
+        return undefined;
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Convert source-owned popup text to plain text. Tags, script/style blocks,
+ * event handlers, and control characters never reach a DOM interpretation.
+ */
+export function sanitizeHonuaInspectionRichText(value) {
+    const plainText = decodeHonuaInspectionEntities(stripHonuaInspectionMarkup(value));
+    return [...plainText]
+        .filter((character) => {
+        const code = character.charCodeAt(0);
+        return code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127);
+    })
+        .join("")
+        .replace(/[ \t]+/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+const WITHHELD_INSPECTION_ELEMENTS = new Set(["script", "style", "iframe", "object", "embed"]);
+function stripHonuaInspectionMarkup(value) {
+    let result = "";
+    let offset = 0;
+    let withheldElement;
+    while (offset < value.length) {
+        const open = value.indexOf("<", offset);
+        if (open < 0) {
+            if (!withheldElement)
+                result += value.slice(offset);
+            break;
+        }
+        if (!withheldElement)
+            result += value.slice(offset, open);
+        const close = value.indexOf(">", open + 1);
+        if (close < 0) {
+            if (!withheldElement)
+                result += value.slice(open);
+            break;
+        }
+        const tag = value.slice(open + 1, close).trim();
+        const closing = tag.startsWith("/");
+        const name = (closing ? tag.slice(1) : tag).split(/[\s/]/, 1)[0]?.toLocaleLowerCase() ?? "";
+        if (withheldElement) {
+            if (closing && name === withheldElement)
+                withheldElement = undefined;
+        }
+        else if (!closing && WITHHELD_INSPECTION_ELEMENTS.has(name)) {
+            withheldElement = name;
+            result += " ";
+        }
+        else if (name === "br" || (closing && name === "p")) {
+            result += "\n";
+        }
+        else {
+            result += " ";
+        }
+        offset = close + 1;
+    }
+    return result;
+}
+function decodeHonuaInspectionEntities(value) {
+    const entities = {
+        nbsp: " ",
+        lt: "<",
+        gt: ">",
+        amp: "&",
+        quot: '"',
+        "#39": "'",
+        "#x27": "'",
+    };
+    return value.replace(/&(nbsp|lt|gt|amp|quot|#39|#x27);/gi, (entity, name) => entities[name.toLocaleLowerCase()] ?? entity);
+}
+/** Resolve a display link without carrying credentials or unsafe schemes. */
+export function sanitizeHonuaInspectionHref(value, options = {}) {
+    try {
+        const url = options.baseHref ? new URL(value, options.baseHref) : new URL(value);
+        if (url.protocol !== "https:" && url.protocol !== "http:")
+            return undefined;
+        if (url.username || url.password)
+            return undefined;
+        const allowed = options.allowedOrigins;
+        if (allowed && allowed.length > 0 && !allowed.includes(url.origin))
+            return undefined;
+        url.hash = "";
+        return url.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Format a scalar popup/detail value without interpreting it as markup. */
+export function formatHonuaInspectionValue(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "object") {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return "[unavailable]";
+        }
+    }
+    return String(value);
+}
+function interpolateInspectionTemplate(template, attributes) {
+    return template.replace(/\{([A-Za-z_][A-Za-z0-9_.:]*)\}/g, (_match, field) => formatHonuaInspectionValue(attributes[field]));
+}
+const globalDom = globalThis;
+const HTMLElementBase = globalDom.HTMLElement ?? class {
+};
+/** Accessible search + popup/details presentation for a feature inspection controller. */
+export class HonuaFeatureInspectionElement extends HTMLElementBase {
+    #controller;
+    #subscription;
+    #applicationContext;
+    #ownsController = false;
+    #state;
+    #restoreFocus;
+    #messages = {};
+    /** Caller-injected labels, status text, range formatters, and diagnostics. */
+    get messages() {
+        return this.#messages;
+    }
+    set messages(messages) {
+        this.#messages = messages ?? {};
+        this.#render();
+    }
+    get inspection() {
+        return this.#controller;
+    }
+    set inspection(controller) {
+        this.#bindInspection(controller, false);
+    }
+    /** Application shell context assigned by `mountHonuaApplication()`. */
+    get applicationContext() {
+        return this.#applicationContext;
+    }
+    set applicationContext(context) {
+        if (context === this.#applicationContext)
+            return;
+        this.#applicationContext = context;
+        if (!context) {
+            if (this.#ownsController)
+                this.#bindInspection(undefined, false);
+            return;
+        }
+        this.#bindApplicationContext(context);
+    }
+    honuaApplicationContextConnected(context) {
+        this.applicationContext = context;
+    }
+    honuaApplicationContextChanged(event) {
+        if (event.current !== this.#applicationContext?.snapshot)
+            return;
+        if (event.changed.includes("binding") || event.changed.includes("authorization")) {
+            this.#bindApplicationContext(this.#applicationContext);
+            return;
+        }
+        if (event.changed.includes("selection"))
+            this.#applyContextSelection(event.current.selection);
+        this.#applyContextPresentation();
+    }
+    honuaApplicationContextDisconnected(context) {
+        if (this.#applicationContext === context)
+            this.applicationContext = undefined;
+    }
+    #bindInspection(controller, owned) {
+        if (controller === this.#controller)
+            return;
+        this.#subscription?.remove();
+        if (this.#ownsController)
+            this.#controller?.dispose();
+        this.#controller = controller;
+        this.#ownsController = owned;
+        this.#state = controller?.snapshot();
+        if (controller)
+            this.#subscribeInspection(controller);
+        this.#render();
+    }
+    #subscribeInspection(controller) {
+        this.#subscription = controller.subscribe((state) => {
+            const wasOpen = this.#state?.status !== "idle" && this.#state !== undefined;
+            const isOpen = state.status !== "idle";
+            if (!wasOpen && isOpen)
+                this.#captureFocus();
+            this.#state = state;
+            this.#render();
+            if (wasOpen && !isOpen)
+                this.#restoreFocus?.focus();
+        });
+    }
+    #bindApplicationContext(context) {
+        if (!context.snapshot.binding.source) {
+            if (this.#ownsController)
+                this.#bindInspection(undefined, false);
+            this.#applyContextPresentation();
+            return;
+        }
+        this.#bindInspection(createHonuaFeatureInspectionFromApplicationContext(context), true);
+        this.#applyContextSelection(context.snapshot.selection);
+        this.#applyContextPresentation();
+    }
+    #applyContextSelection(selection) {
+        if (!this.#controller)
+            return;
+        const target = selection.find(isSourceQualifiedTarget);
+        const current = this.#controller.snapshot().candidates[this.#controller.snapshot().activeIndex]?.target;
+        if (!target) {
+            if (current)
+                this.#controller.close();
+            return;
+        }
+        if (!current || featureSelectionKey(current) !== featureSelectionKey(target)) {
+            void this.#controller.open({ target }, { origin: "programmatic" });
+        }
+    }
+    #applyContextPresentation() {
+        const snapshot = this.#applicationContext?.snapshot;
+        if (!snapshot)
+            return;
+        this.setAttribute("lang", snapshot.locale.locale);
+        this.setAttribute("dir", snapshot.locale.direction ?? "auto");
+        this.style.colorScheme = snapshot.theme.colorScheme ?? "";
+    }
+    connectedCallback() {
+        if (!this.shadowRoot && typeof this.attachShadow === "function")
+            this.attachShadow({ mode: "open" });
+        this.shadowRoot?.addEventListener("click", this.#onClick);
+        this.shadowRoot?.addEventListener("keydown", this.#onKeyDown);
+        this.shadowRoot?.addEventListener("submit", this.#onSubmit);
+        if (this.#controller && !this.#subscription)
+            this.#subscribeInspection(this.#controller);
+        if (this.#applicationContext && !this.#controller)
+            this.#bindApplicationContext(this.#applicationContext);
+        this.#render();
+    }
+    disconnectedCallback() {
+        this.shadowRoot?.removeEventListener("click", this.#onClick);
+        this.shadowRoot?.removeEventListener("keydown", this.#onKeyDown);
+        this.shadowRoot?.removeEventListener("submit", this.#onSubmit);
+        this.#subscription?.remove();
+        this.#subscription = undefined;
+        if (this.#ownsController)
+            this.#bindInspection(undefined, false);
+    }
+    #captureFocus() {
+        const active = this.ownerDocument?.activeElement;
+        this.#restoreFocus = active instanceof HTMLElement ? active : undefined;
+    }
+    #render() {
+        const root = this.shadowRoot;
+        if (!root)
+            return;
+        const focus = captureInspectionFocus(root);
+        const state = this.#state;
+        const messages = resolveInspectionMessages(this.#messages, this.#applicationContext);
+        const label = this.getAttribute("label") ?? messages.panelLabel;
+        const search = state?.search ?? { status: "idle", query: "", results: [], diagnostics: [] };
+        const feature = state?.feature;
+        const role = this.getAttribute("presentation") === "popup" ? "dialog" : "region";
+        const details = feature
+            ? `<article class="details" part="details" role="${role}"${role === "dialog" ? ' aria-modal="false"' : ""} aria-labelledby="honua-inspection-title">
+          <header><h2 id="honua-inspection-title" tabindex="-1">${escapeHtml(feature.title)}</h2>
+            <button type="button" data-focus-id="close" data-action="close" aria-label="${escapeAttribute(messages.closeDetailsLabel)}">&times;</button></header>
+          ${feature.description ? `<p>${escapeHtml(feature.description)}</p>` : ""}
+          ${renderNavigation(state, messages)}
+          <dl>${feature.fields
+                .map((field) => `<div><dt>${escapeHtml(field.label)}</dt><dd>${escapeHtml(field.text)}</dd></div>`)
+                .join("")}</dl>
+          ${renderLinks(feature.links, messages)}
+          ${renderAttachments(state?.attachments, messages)}
+          ${renderRelationships(state?.relationships ?? [], messages)}
+        </article>`
+            : "";
+        renderCspSafeShadowHtml(root, `<style>${inspectionStyles()}</style>
+       <section class="inspection" part="panel" aria-label="${escapeAttribute(label)}" aria-busy="${String(state?.status === "loading" || search.status === "loading")}">
+        <form role="search"><label for="honua-inspection-search">${escapeHtml(messages.searchLabel)}</label>
+          <div class="search-row"><input id="honua-inspection-search" name="q" type="search" value="${escapeAttribute(search.query)}" data-focus-id="search" autocomplete="off" role="combobox" aria-autocomplete="list" aria-expanded="${String(search.results.length > 0)}" aria-controls="honua-inspection-results" />
+          <button type="submit" data-focus-id="search-submit">${escapeHtml(messages.searchButtonLabel)}</button></div></form>
+        <ol id="honua-inspection-results" class="results" role="listbox" aria-label="${escapeAttribute(messages.searchResultsLabel)}">${search.results
+            .map((result, index) => `<li role="option" aria-selected="${String(featureSelectionKey(result.target) ===
+            (state?.feature ? featureSelectionKey(state.feature.target) : undefined))}"><button type="button" data-focus-id="search-${index}" data-search-index="${index}">${escapeHtml(result.title)}<small>${escapeHtml(result.subtitle ?? result.target.sourceId)}</small></button></li>`)
+            .join("")}</ol>
+        <p class="status" role="status" aria-live="polite">${escapeHtml(statusText(state, messages))}</p>
+        ${renderDiagnostics(state?.diagnostics ?? [], search.diagnostics, messages)}
+        ${details}
+       </section>`);
+        restoreInspectionFocus(root, focus);
+    }
+    #onClick = (event) => {
+        const button = event.composedPath().find((entry) => entry instanceof HTMLButtonElement);
+        if (button)
+            this.#activate(button);
+    };
+    #onSubmit = (event) => {
+        event.preventDefault();
+        this.#search();
+    };
+    #onKeyDown = (event) => {
+        const keyboardEvent = event;
+        const target = keyboardEvent.composedPath()[0];
+        if (target instanceof HTMLButtonElement && (keyboardEvent.key === "Enter" || keyboardEvent.key === " ")) {
+            keyboardEvent.preventDefault();
+            this.#activate(target);
+            return;
+        }
+        if (target instanceof HTMLInputElement && keyboardEvent.key === "Enter") {
+            keyboardEvent.preventDefault();
+            this.#search();
+            return;
+        }
+        if (keyboardEvent.key === "/" && !(target instanceof HTMLInputElement)) {
+            keyboardEvent.preventDefault();
+            this.shadowRoot?.querySelector("input[name='q']")?.focus();
+            return;
+        }
+        if (keyboardEvent.key === "Escape" && this.#state?.status !== "idle") {
+            event.preventDefault();
+            this.#controller?.close();
+            return;
+        }
+        if (target instanceof HTMLInputElement)
+            return;
+        if (keyboardEvent.key === "ArrowLeft") {
+            keyboardEvent.preventDefault();
+            void this.#controller?.previous();
+        }
+        else if (keyboardEvent.key === "ArrowRight") {
+            keyboardEvent.preventDefault();
+            void this.#controller?.next();
+        }
+        else if (keyboardEvent.key === "Home") {
+            keyboardEvent.preventDefault();
+            void this.#controller?.navigate(0);
+        }
+        else if (keyboardEvent.key === "End") {
+            keyboardEvent.preventDefault();
+            void this.#controller?.navigate(Number.MAX_SAFE_INTEGER);
+        }
+    };
+    #search() {
+        const value = this.shadowRoot?.querySelector("input[name='q']")?.value ?? "";
+        void this.#controller?.search(value);
+    }
+    #activate(button) {
+        if (button.disabled)
+            return;
+        if (button.dataset.searchIndex !== undefined) {
+            void this.#controller?.openSearchResult(Number(button.dataset.searchIndex));
+            return;
+        }
+        switch (button.dataset.action) {
+            case "close":
+                this.#controller?.close();
+                return;
+            case "previous":
+                void this.#controller?.previous();
+                return;
+            case "next":
+                void this.#controller?.next();
+                return;
+            case "refresh":
+                void this.#controller?.refresh();
+                return;
+            case "attachments-previous":
+                this.#moveAttachmentPage(-1);
+                return;
+            case "attachments-next":
+                this.#moveAttachmentPage(1);
+                return;
+        }
+        if (button.dataset.relationshipId === undefined)
+            return;
+        const relationshipId = Number(button.dataset.relationshipId);
+        const relationship = this.#state?.relationships.find((candidate) => candidate.id === relationshipId);
+        if (!relationship)
+            return;
+        const direction = button.dataset.relationshipPage === "previous" ? -1 : 1;
+        this.#controller?.setRelationshipPage(relationshipId, relationship.page.offset / relationship.page.limit + direction);
+    }
+    #moveAttachmentPage(direction) {
+        const page = this.#state?.attachments;
+        if (page)
+            this.#controller?.setAttachmentPage(page.offset / page.limit + direction);
+    }
+}
+/** Define `<honua-feature-inspection>` in a registry, if it is not already defined. */
+export function defineHonuaFeatureInspection(registry = globalDom.customElements) {
+    if (!registry?.get("honua-feature-inspection"))
+        registry?.define("honua-feature-inspection", HonuaFeatureInspectionElement);
+}
+const DEFAULT_INSPECTION_MESSAGES = Object.freeze({
+    panelLabel: "Feature inspection",
+    searchLabel: "Search features",
+    searchButtonLabel: "Search",
+    searchResultsLabel: "Feature search results",
+    closeDetailsLabel: "Close feature details",
+    overlappingResultsLabel: "Overlapping feature results",
+    previousResultLabel: "Previous",
+    nextResultLabel: "Next",
+    resultPosition: (index, total) => `${index} of ${total}`,
+    refreshLabel: "Refresh",
+    featureLinksLabel: "Feature links",
+    attachmentsLabel: "Attachments",
+    attachmentLabel: (id) => `Attachment ${String(id)}`,
+    attachmentSize: (bytes) => `${bytes} bytes`,
+    attachmentPagesLabel: "Attachment pages",
+    previousAttachmentsLabel: "Previous attachments",
+    nextAttachmentsLabel: "Next attachments",
+    relationshipPagesLabel: (relationship) => `${relationship} pages`,
+    previousRelatedLabel: "Previous related records",
+    nextRelatedLabel: "Next related records",
+    diagnosticsLabel: "Inspection diagnostics",
+    diagnostic: (diagnostic) => diagnostic.message,
+    range: (offset, count, total) => `${offset + Math.min(1, count)}-${offset + count} of ${total}`,
+    disconnectedStatus: "Connect an inspection controller to search and inspect features.",
+    searchingStatus: "Searching features.",
+    loadingStatus: "Loading feature details.",
+    deletedStatus: "The selected feature was deleted.",
+    staleStatus: "Feature details are stale. Refresh to continue.",
+    showingStatus: (title) => `Showing ${title}.`,
+    searchResultsStatus: (count) => `${count} feature search result(s).`,
+    emptyStatus: "No feature selected.",
+});
+function resolveInspectionMessages(messages, context) {
+    const statuses = context?.snapshot.locale.status;
+    return {
+        ...DEFAULT_INSPECTION_MESSAGES,
+        ...(statuses?.loading ? { loadingStatus: statuses.loading, searchingStatus: statuses.loading } : {}),
+        ...(statuses?.stale ? { staleStatus: statuses.stale } : {}),
+        ...(statuses?.empty ? { emptyStatus: statuses.empty } : {}),
+        ...(statuses?.unsupported ? { disconnectedStatus: statuses.unsupported } : {}),
+        ...messages,
+    };
+}
+function renderNavigation(state, messages) {
+    if (state.candidates.length <= 1)
+        return state.status === "stale" ? refreshButton(messages) : "";
+    return `<nav aria-label="${escapeAttribute(messages.overlappingResultsLabel)}">
+    <button type="button" data-focus-id="result-previous" data-action="previous"${state.activeIndex === 0 ? " disabled" : ""}>${escapeHtml(messages.previousResultLabel)}</button>
+    <span>${escapeHtml(messages.resultPosition(state.activeIndex + 1, state.candidates.length))}</span>
+    <button type="button" data-focus-id="result-next" data-action="next"${state.activeIndex + 1 >= state.candidates.length ? " disabled" : ""}>${escapeHtml(messages.nextResultLabel)}</button>
+    ${state.status === "stale" ? refreshButton(messages) : ""}
+  </nav>`;
+}
+function refreshButton(messages) {
+    return `<button type="button" data-focus-id="refresh" data-action="refresh">${escapeHtml(messages.refreshLabel)}</button>`;
+}
+function renderLinks(links, messages) {
+    if (links.length === 0)
+        return "";
+    return `<ul class="links" aria-label="${escapeAttribute(messages.featureLinksLabel)}">${links
+        .map((link) => `<li><a href="${escapeAttribute(link.href)}" target="_blank" rel="noopener noreferrer">${escapeHtml(link.label)}</a></li>`)
+        .join("")}</ul>`;
+}
+function renderAttachments(page, messages) {
+    if (!page || page.total === 0)
+        return "";
+    return `<section aria-labelledby="honua-inspection-attachments"><h3 id="honua-inspection-attachments">${escapeHtml(messages.attachmentsLabel)}</h3>
+    <ul>${page.items
+        .map((attachment) => {
+        const label = attachment.name ?? messages.attachmentLabel(attachment.id);
+        return `<li>${attachment.href
+            ? `<a href="${escapeAttribute(attachment.href)}" target="_blank" rel="noopener noreferrer">${escapeHtml(label)}</a>`
+            : escapeHtml(label)}${attachment.size === undefined ? "" : ` (${escapeHtml(messages.attachmentSize(attachment.size))})`}</li>`;
+    })
+        .join("")}</ul><p>${escapeHtml(messages.range(page.offset, page.items.length, page.total))}</p>
+      <nav aria-label="${escapeAttribute(messages.attachmentPagesLabel)}"><button type="button" data-focus-id="attachments-previous" data-action="attachments-previous"${page.hasPrevious ? "" : " disabled"}>${escapeHtml(messages.previousAttachmentsLabel)}</button><button type="button" data-focus-id="attachments-next" data-action="attachments-next"${page.hasNext ? "" : " disabled"}>${escapeHtml(messages.nextAttachmentsLabel)}</button></nav></section>`;
+}
+function renderRelationships(relationships, messages) {
+    return relationships
+        .map((relationship) => `<section aria-labelledby="honua-relationship-${relationship.id}">
+        <h3 id="honua-relationship-${relationship.id}">${escapeHtml(relationship.label)}</h3>
+        <ol>${relationship.page.items
+        .map((feature) => `<li>${escapeHtml(featureTitle(feature.attributes, undefined, "related"))}</li>`)
+        .join("")}</ol>
+        <p>${escapeHtml(messages.range(relationship.page.offset, relationship.page.items.length, relationship.page.total))}</p>
+        <nav aria-label="${escapeAttribute(messages.relationshipPagesLabel(relationship.label))}">
+          <button type="button" data-focus-id="relationship-${relationship.id}-previous" data-relationship-id="${relationship.id}" data-relationship-page="previous"${relationship.page.hasPrevious ? "" : " disabled"}>${escapeHtml(messages.previousRelatedLabel)}</button>
+          <button type="button" data-focus-id="relationship-${relationship.id}-next" data-relationship-id="${relationship.id}" data-relationship-page="next"${relationship.page.hasNext ? "" : " disabled"}>${escapeHtml(messages.nextRelatedLabel)}</button>
+        </nav>
+      </section>`)
+        .join("");
+}
+function renderDiagnostics(details, search, messages) {
+    const diagnostics = [...details, ...search];
+    if (diagnostics.length === 0)
+        return "";
+    return `<ul class="diagnostics" role="alert" aria-label="${escapeAttribute(messages.diagnosticsLabel)}">${diagnostics
+        .map((diagnostic) => `<li>${escapeHtml(messages.diagnostic(diagnostic))}</li>`)
+        .join("")}</ul>`;
+}
+function statusText(state, messages) {
+    if (!state)
+        return messages.disconnectedStatus;
+    if (state.search.status === "loading")
+        return messages.searchingStatus;
+    if (state.status === "loading")
+        return messages.loadingStatus;
+    if (state.status === "deleted")
+        return state.staleReason ?? messages.deletedStatus;
+    if (state.status === "stale")
+        return state.staleReason ?? messages.staleStatus;
+    if (state.feature)
+        return messages.showingStatus(state.feature.title);
+    if (state.search.status === "ready")
+        return messages.searchResultsStatus(state.search.results.length);
+    return messages.emptyStatus;
+}
+function escapeHtml(value) {
+    return String(value)
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function isSourceQualifiedTarget(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const target = value;
+    return (typeof target.sourceId === "string" &&
+        (typeof target.id === "string" || (typeof target.id === "number" && Number.isFinite(target.id))));
+}
+function escapeAttribute(value) {
+    return escapeHtml(value).replaceAll("`", "&#96;");
+}
+function captureInspectionFocus(root) {
+    const active = root.activeElement;
+    if (!(active instanceof HTMLElement))
+        return undefined;
+    const id = active.dataset.focusId;
+    if (!id)
+        return undefined;
+    if (!(active instanceof HTMLInputElement))
+        return { id };
+    return {
+        id,
+        value: active.value,
+        ...(active.selectionStart !== null ? { selectionStart: active.selectionStart } : {}),
+        ...(active.selectionEnd !== null ? { selectionEnd: active.selectionEnd } : {}),
+        ...(active.selectionDirection ? { selectionDirection: active.selectionDirection } : {}),
+    };
+}
+function restoreInspectionFocus(root, snapshot) {
+    if (!snapshot)
+        return;
+    const target = [...root.querySelectorAll("[data-focus-id]")].find((candidate) => candidate.dataset.focusId === snapshot.id);
+    if (!target)
+        return;
+    if (target instanceof HTMLInputElement && snapshot.value !== undefined) {
+        target.value = snapshot.value;
+    }
+    target.focus();
+    if (target instanceof HTMLInputElement &&
+        snapshot.selectionStart !== undefined &&
+        snapshot.selectionEnd !== undefined) {
+        target.setSelectionRange(snapshot.selectionStart, snapshot.selectionEnd, snapshot.selectionDirection);
+    }
+}
+function inspectionStyles() {
+    return `:host{display:block;min-inline-size:0;max-inline-size:100%;container-type:inline-size;color:var(--honua-color-text,#17202a);font:var(--honua-font,normal 400 1rem/1.5 system-ui,sans-serif)}
+  *{box-sizing:border-box}.inspection{display:grid;min-inline-size:0;gap:.75rem}.search-row{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:.5rem}
+  label,h2,h3{font-weight:600}input,button,a{font:inherit}input{min-inline-size:0;max-inline-size:100%;padding:.5rem;border:1px solid var(--honua-color-border,#777);border-radius:.25rem}
+  button{max-inline-size:100%;padding:.45rem .7rem;overflow-wrap:anywhere}.results,.links,.diagnostics{margin:0;padding-inline-start:1.25rem}.results:empty{display:none}.results button{inline-size:100%;text-align:start}.results small{display:block}
+  .details{min-inline-size:0;border:1px solid var(--honua-color-border,#aaa);border-radius:.375rem;padding:1rem;overflow-wrap:anywhere}.details header{display:flex;justify-content:space-between;gap:1rem}.details h2{margin:0}
+  dl{display:grid;gap:.25rem}dl div{display:grid;grid-template-columns:minmax(8rem,1fr) 2fr;gap:.5rem}dt{font-weight:600}dd{margin:0;overflow-wrap:anywhere}
+  nav{display:flex;align-items:center;gap:.5rem;flex-wrap:wrap}.status{min-height:1.5em}.diagnostics{color:var(--honua-color-danger,#8b1a1a)}
+  :focus-visible{outline:3px solid var(--honua-color-focus,#1565c0);outline-offset:2px}
+  @container(max-width:320px){.search-row,dl div{grid-template-columns:minmax(0,1fr)}.search-row button,nav button{inline-size:100%}.details header{align-items:stretch;flex-direction:column}}
+  @media(max-width:320px){.search-row,dl div{grid-template-columns:minmax(0,1fr)}.search-row button,nav button{inline-size:100%}}
+  @media(prefers-reduced-motion:reduce){*{scroll-behavior:auto!important;transition:none!important;animation:none!important}}
+  @media(forced-colors:active),(prefers-contrast:more){:host{color:CanvasText;background:Canvas}.inspection,.details,input{color:CanvasText;background:Canvas;border-color:CanvasText}button{color:ButtonText;background:ButtonFace;border:1px solid ButtonText}a{color:LinkText}.diagnostics{color:CanvasText;border-inline-start:3px solid MarkText}:focus-visible{outline-color:Highlight}}`;
+}