@expofp/floorplan 0.0.0-experimental.2d6c681

package/dist/esm/data/venues.js

@@ -0,0 +1,955 @@
+import { Box, convexHull, polygonCentroid, rectCorners } from '@expofp/geometry';
+const ID_PATTERN = /^[a-z0-9_-]+$/;
+const RENDER_MODES = ['scene', 'marker'];
+/** Contract defaults for the size axis (§4). Re-exported by `venue-legibility`. */
+export const DEFAULT_MARKER_MAX_SIZE_PX = 60;
+export const DEFAULT_DETAIL_MIN_SIZE_PX = 240;
+/**
+ * Floor for an authored `detailMinSizePx`, and the reason it is not simply 60:
+ *
+ * 66 is the **marker/scene sticky enter edge** for the contract's defaults —
+ * `stickyEnterSizePx(60)`, where the `× 1.1` is the ±10% size hysteresis
+ * (`SIZE_HYSTERESIS_RATIO` in `venue-legibility.ts`) — the size at which a
+ * venue climbing out of the marker band actually enters the scene band.
+ * Clamping here keeps floor detail from beginning before the scene band has
+ * been entered.
+ *
+ * **A literal, never derived** (contract §4, App. C). The contract states the
+ * floor to authors as the number 66, and every implementation must hold that
+ * number exactly: an author who writes `detailMinSizePx: 66` clears the
+ * producer's export gate and must not then be clamped at runtime. Derived, the
+ * floor is a float expression the contract cannot promise equals 66 — it does
+ * for these two operands, and would stop the moment either the ceiling or the
+ * ratio moved, silently invalidating the documented value. So it is written as
+ * 66 here and in every other implementation, with the relationship above
+ * documented rather than computed.
+ *
+ * Nor can the relationship be expressed in code: `venue-legibility.ts` imports
+ * the band defaults from this module, so the dependency is one-way and
+ * `stickyEnterSizePx` is not importable here.
+ *
+ * It is deliberately NOT "the smallest value above 60" (that would be 61):
+ * 61 clears the impossible-range guard below — which needs only
+ * `resolvedDetailMinSizePx > resolvedMin`, and a defaulted scene aux resolves
+ * `minSizePx` to 60 — but leaves a ~1px-wide scene band wedged between the
+ * two sticky edges, which flickers rather than hands off. Do not "simplify"
+ * this to `DEFAULT_MARKER_MAX_SIZE_PX + 1`; it silently breaks the handoff.
+ *
+ * This is the floor for the **default** ceiling. A venue that authors its own
+ * `markerMaxSizePx` (Revision 5) gets its floor from {@link detailMinSizeFloor}.
+ */
+export const MIN_DETAIL_MIN_SIZE_PX = 66;
+/** `detailMinSizePx × 10 ≥ markerMaxSizePx × 11` (§4, Revision 5), as its two integer factors. */
+const DETAIL_FLOOR_NUMERATOR = 11;
+const DETAIL_FLOOR_DENOMINATOR = 10;
+/**
+ * Whether a detail edge leaves room above a marker edge for the hysteresis
+ * band (§4, Revision 5). Stated as the contract's integer comparison rather
+ * than `× 1.1`, so every implementation agrees on the boundary exactly.
+ */
+export function detailEdgeClearsMarkerEdge(detailMinSizePx, markerMaxSizePx) {
+    return detailMinSizePx * DETAIL_FLOOR_DENOMINATOR >= markerMaxSizePx * DETAIL_FLOOR_NUMERATOR;
+}
+/**
+ * The smallest `detailMinSizePx` a venue with this marker edge may carry: the
+ * least value satisfying {@link detailEdgeClearsMarkerEdge}. For the default
+ * ceiling it is the literal {@link MIN_DETAIL_MIN_SIZE_PX}, so the number §4
+ * has always stated to authors cannot drift.
+ */
+export function detailMinSizeFloor(markerMaxSizePx) {
+    if (markerMaxSizePx === DEFAULT_MARKER_MAX_SIZE_PX)
+        return MIN_DETAIL_MIN_SIZE_PX;
+    return Math.ceil((markerMaxSizePx * DETAIL_FLOOR_NUMERATOR) / DETAIL_FLOOR_DENOMINATOR);
+}
+const VENUE_KEYS = new Set([
+    'id',
+    'name',
+    'order',
+    'levels',
+    'contour',
+    'markerPoint',
+    'detailMinSizePx',
+    'markerMaxSizePx',
+    'layers',
+    'entrances',
+    'campusViewbox',
+]);
+const LEVEL_KEYS = new Set(['layer', 'ordinal', 'name', 'initial']);
+const ENTRANCE_KEYS = new Set(['layer', 'point', 'name']);
+const AUX_KEYS = new Set([
+    'layer',
+    'render',
+    'replacesDefault',
+    'suppressesLabel',
+    'minSizePx',
+    'maxSizePx',
+]);
+/**
+ * Codepoint order for venue `id`s — the contract's "alphabetically by `id`"
+ * (§9), pinned to one answer every implementation of this contract can
+ * reproduce. `localeCompare` cannot: it is ICU-collated, so `hall-1`, `hall_a`
+ * and `halla` sort differently across runtimes, and a layer-ownership winner
+ * that depends on the reader is exactly what §10 keys off `id` to avoid.
+ */
+export const compareIds = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+const isFinitePoint = (value) => isObject(value) && isFiniteNumber(value.x) && isFiniteNumber(value.y);
+const isCampusViewbox = (value) => isObject(value) &&
+    isFiniteNumber(value.x) &&
+    isFiniteNumber(value.y) &&
+    isFiniteNumber(value.width) &&
+    isFiniteNumber(value.height) &&
+    value.width > 0 &&
+    value.height > 0;
+function describe(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? String(value) : serialized;
+    }
+    catch {
+        return String(value);
+    }
+}
+function emitDiagnostics(diagnostics) {
+    for (const diagnostic of diagnostics) {
+        try {
+            console.warn('parseVenues:', `${diagnostic.code} (${diagnostic.effect}) ${diagnostic.path || '(root)'}: ${diagnostic.message}; ${diagnostic.consequence}`);
+        }
+        catch {
+            // Diagnostics remain available in the result even if a host console is broken.
+        }
+    }
+}
+function complete(venues, diagnostics, quarantinedLayerNames, campusViewbox = null) {
+    emitDiagnostics(diagnostics);
+    return { venues, diagnostics, quarantinedLayerNames, campusViewbox };
+}
+function segmentsIntersect(p1, p2, p3, p4) {
+    const direction = (a, b, c) => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+    const d1 = direction(p3, p4, p1);
+    const d2 = direction(p3, p4, p2);
+    const d3 = direction(p1, p2, p3);
+    const d4 = direction(p1, p2, p4);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0))) {
+        return true;
+    }
+    const onSegment = (a, b, c) => Math.min(a.x, b.x) <= c.x &&
+        c.x <= Math.max(a.x, b.x) &&
+        Math.min(a.y, b.y) <= c.y &&
+        c.y <= Math.max(a.y, b.y);
+    return ((d1 === 0 && onSegment(p3, p4, p1)) ||
+        (d2 === 0 && onSegment(p3, p4, p2)) ||
+        (d3 === 0 && onSegment(p1, p2, p3)) ||
+        (d4 === 0 && onSegment(p1, p2, p4)));
+}
+function validateRing(value) {
+    if (!Array.isArray(value))
+        return { issue: 'is not an array' };
+    if (value.length < 3) {
+        return { issue: `has ${value.length} point(s); a ring needs at least 3` };
+    }
+    if (!value.every(isFinitePoint)) {
+        return { issue: 'contains a non-finite or malformed point' };
+    }
+    const ring = value.map((point) => ({ x: point.x, y: point.y }));
+    const first = ring[0];
+    const last = ring[ring.length - 1];
+    if (first.x === last.x && first.y === last.y)
+        ring.pop();
+    if (ring.length < 3)
+        return { issue: `has ${ring.length} point(s); a ring needs at least 3` };
+    const { width, height } = Box.fromPoints(ring).size;
+    if (width === 0 || height === 0) {
+        return { issue: 'is degenerate (zero width or height)' };
+    }
+    for (let i = 0; i < ring.length; i++) {
+        const a1 = ring[i];
+        const a2 = ring[(i + 1) % ring.length];
+        for (let j = i + 1; j < ring.length; j++) {
+            if (j === i || (j + 1) % ring.length === i || (i + 1) % ring.length === j)
+                continue;
+            if (segmentsIntersect(a1, a2, ring[j], ring[(j + 1) % ring.length])) {
+                return {
+                    issue: 'is self-intersecting; v1 accepts one simple ring only (no holes, no multi-part)',
+                };
+            }
+        }
+    }
+    let twiceArea = 0;
+    for (let i = 0; i < ring.length; i++) {
+        const current = ring[i];
+        const next = ring[(i + 1) % ring.length];
+        twiceArea += current.x * next.y - next.x * current.y;
+    }
+    return twiceArea === 0 ? { issue: 'is degenerate (zero area)' } : { ring };
+}
+function deriveLevelHull(levels, geometries) {
+    const corners = [];
+    for (const candidate of levels) {
+        if (!candidate.surviving)
+            continue;
+        const geometry = geometries.get(candidate.value.layer);
+        const bounds = geometry?.rect ?? geometry?.viewbox;
+        if (!bounds || bounds.area <= 0)
+            continue;
+        corners.push(...rectCorners(bounds).map((corner) => ({ x: corner.x, y: corner.y })));
+    }
+    return convexHull(corners);
+}
+/**
+ * Parses a complete venue payload. Candidate entries are validated before any
+ * ownership is committed; all surviving levels claim globally before aux refs.
+ */
+export function parseVenues(payload, geometries, sceneCandidates = []) {
+    try {
+        return parseVenuesInternal(payload, geometries, sceneCandidates);
+    }
+    catch {
+        const diagnostics = [
+            {
+                code: 'venues-payload-invalid',
+                path: 'venues',
+                message: 'could not be parsed',
+                consequence: 'plan loads as single-venue',
+                effect: 'dropped',
+            },
+        ];
+        return complete([], diagnostics, []);
+    }
+}
+function parseVenuesInternal(payload, geometries, sceneCandidates) {
+    const diagnostics = [];
+    // One emitter per `effect` (§11), so every site states what the SDK did with
+    // the authored value. `code` is the parity key against
+    // `docs/specs/validate-venues.mjs`; `message` and `consequence` are prose and
+    // are deliberately not compared across implementations.
+    const emit = (effect) => (code, path, message, consequence) => diagnostics.push({ code, path, message, consequence, effect });
+    const dropped = emit('dropped');
+    const fallback = emit('fallback');
+    const clamped = emit('clamped');
+    const advisory = emit('advisory');
+    const reportUnknownKeys = (at, value, knownKeys) => {
+        for (const key of Object.keys(value)) {
+            if (!knownKeys.has(key)) {
+                advisory('unknown-key', `${at}.${key}`, 'is not a contract field', 'ignored by the SDK');
+            }
+        }
+    };
+    /** Runs a probe pass, discarding whatever diagnostics it emitted. */
+    const speculative = (probe) => {
+        const mark = diagnostics.length;
+        try {
+            return probe();
+        }
+        finally {
+            diagnostics.length = mark;
+        }
+    };
+    const sceneCandidateLayerNames = new Set();
+    for (const candidates of sceneCandidates) {
+        for (const candidate of candidates)
+            sceneCandidateLayerNames.add(candidate.layer);
+    }
+    if (payload === undefined || payload === null)
+        return complete([], diagnostics, []);
+    if (!isObject(payload)) {
+        dropped('venues-payload-invalid', '', 'payload is not an object', 'nothing to parse');
+        return complete([], diagnostics, []);
+    }
+    const venuesValue = payload.venues;
+    if (venuesValue === undefined)
+        return complete([], diagnostics, []);
+    // An absent `venuesVersion` is read as v1 and reported by nothing here: the
+    // config layer supplies `venuesVersion: 1` as a default before venue parsing
+    // runs, so absence is indistinguishable from an authored 1 by this point.
+    // The field is contractually required (§15) — the requirement lives on the
+    // producer's export gate, which the reference validator implements.
+    if (payload.venuesVersion !== undefined && payload.venuesVersion !== 1) {
+        dropped('venues-version-unsupported', 'venuesVersion', `payload version ${describe(payload.venuesVersion)} is unsupported; SDK supports version 1`, 'whole venues array ignored; plan loads as single-venue');
+        return complete([], diagnostics, []);
+    }
+    if (!Array.isArray(venuesValue)) {
+        dropped('venues-payload-invalid', 'venues', 'is not an array', 'plan loads as single-venue');
+        return complete([], diagnostics, []);
+    }
+    const seenIds = new Map();
+    const nameOwners = new Map();
+    const duplicateNames = new Map();
+    venuesValue.forEach((value, index) => {
+        if (!isObject(value) || !isNonEmptyString(value.name))
+            return;
+        const at = `venues[${index}]`;
+        const normalized = value.name.toLowerCase();
+        const owner = nameOwners.get(normalized);
+        if (owner)
+            duplicateNames.set(at, owner);
+        else
+            nameOwners.set(normalized, at);
+    });
+    const states = venuesValue.map((value, index) => {
+        const at = `venues[${index}]`;
+        if (!isObject(value)) {
+            dropped('venue-identity-invalid', at, 'is not an object', 'venue dropped');
+            return {
+                at,
+                label: at,
+                claimable: false,
+                order: index,
+                levels: [],
+                aux: [],
+                entrances: [],
+                expectedSceneLayers: [],
+                referencedLayers: [],
+            };
+        }
+        reportUnknownKeys(at, value, VENUE_KEYS);
+        let claimable = true;
+        const id = value.id;
+        if (!isNonEmptyString(id)) {
+            dropped('venue-identity-invalid', `${at}.id`, 'is missing or not a non-empty string', 'venue dropped');
+            claimable = false;
+        }
+        else {
+            if (!ID_PATTERN.test(id)) {
+                dropped('venue-identity-invalid', `${at}.id`, `"${id}" must match ${ID_PATTERN} (lowercase alphanumerics, hyphen, underscore)`, 'id is used as a MapLibre feature id, a style-image id and a ?camera[venue]= deep-link value');
+                claimable = false;
+            }
+            if (seenIds.has(id)) {
+                dropped('venue-id-duplicate', `${at}.id`, `"${id}" duplicates ${seenIds.get(id)}`, 'this venue dropped');
+                claimable = false;
+            }
+            else {
+                seenIds.set(id, at);
+            }
+        }
+        const label = isNonEmptyString(id) ? `"${id}"` : at;
+        const name = value.name;
+        if (!isNonEmptyString(name)) {
+            dropped('venue-identity-invalid', `${at}.name`, 'is missing or not a non-empty string', 'venue dropped');
+            claimable = false;
+        }
+        else if (duplicateNames.has(at)) {
+            // Advisory since Revision 4 (§9): lookup resolves an `id` only, so a
+            // shared display name is an authoring smell — two identical rows in the
+            // venue switch — never a reason to delete a building.
+            advisory('venue-name-duplicate', `${at}.name`, `"${name}" duplicates the name of ${duplicateNames.get(at)} (case-insensitive)`, 'nothing dropped — two identical rows in the venue switch, ambiguous search results');
+        }
+        // `order` is contractually required (§9): the venue is never dropped for
+        // it, but the fallback to array position is reported so a producer's gate
+        // — and Guard 4's preview — can see that the export should have failed.
+        let order = index;
+        if (Number.isInteger(value.order)) {
+            order = value.order;
+        }
+        else {
+            fallback('venue-order-invalid', `${at}.order`, value.order === undefined ? 'is missing' : 'is not an integer', 'falls back to array position; order is contractually required (§9)');
+        }
+        const referencedLayers = [];
+        const rememberReference = (layer, exists = false) => {
+            if (isNonEmptyString(layer) &&
+                !layer.startsWith('WF') &&
+                exists &&
+                !referencedLayers.includes(layer)) {
+                referencedLayers.push(layer);
+            }
+        };
+        const levelCandidates = [];
+        if (!Array.isArray(value.levels) || value.levels.length === 0) {
+            dropped('venue-levels-missing', `${at}.levels`, 'is missing or empty', 'venue dropped');
+            claimable = false;
+        }
+        else {
+            value.levels.forEach((level, levelIndex) => {
+                const levelAt = `${at}.levels[${levelIndex}]`;
+                if (!isObject(level)) {
+                    dropped('level-entry-invalid', levelAt, 'is not an object', 'level dropped');
+                    return;
+                }
+                reportUnknownKeys(levelAt, level, LEVEL_KEYS);
+                rememberReference(level.layer, geometries.has(level.layer));
+                let ok = true;
+                if (!isNonEmptyString(level.layer)) {
+                    dropped('level-layer-invalid', `${levelAt}.layer`, 'is missing or not a non-empty string', 'level dropped');
+                    ok = false;
+                }
+                else {
+                    if (!geometries.has(level.layer)) {
+                        dropped('level-layer-unknown', `${levelAt}.layer`, `"${level.layer}" does not exist in the plan`, `level dropped; venue ${label} loses this floor (check for a rename or typo)`);
+                        ok = false;
+                    }
+                    if (level.layer.startsWith('WF')) {
+                        dropped('level-layer-wayfinding', `${levelAt}.layer`, `"${level.layer}" is a wayfinding layer`, 'WF* layers are excluded before the venue model sees them — level dropped');
+                        ok = false;
+                    }
+                }
+                if (!Number.isInteger(level.ordinal)) {
+                    dropped('level-ordinal-invalid', `${levelAt}.ordinal`, 'is missing or not an integer', 'level dropped; ordinal is required (0 = ground, -1 = basement)');
+                    ok = false;
+                }
+                if (level.name !== undefined && !isNonEmptyString(level.name)) {
+                    fallback('level-field-invalid', `${levelAt}.name`, 'is not a non-empty string', "falls back to the layer's description");
+                }
+                if (level.initial !== undefined && typeof level.initial !== 'boolean') {
+                    fallback('level-field-invalid', `${levelAt}.initial`, 'is not a boolean', 'ignored');
+                }
+                levelCandidates.push({
+                    value: {
+                        layer: isNonEmptyString(level.layer) ? level.layer : '',
+                        ordinal: Number.isInteger(level.ordinal) ? level.ordinal : 0,
+                        name: isNonEmptyString(level.name) ? level.name : undefined,
+                        initial: typeof level.initial === 'boolean' ? level.initial : undefined,
+                    },
+                    at: levelAt,
+                    ok,
+                    surviving: false,
+                });
+            });
+            const ordinals = new Map();
+            for (const candidate of levelCandidates) {
+                if (!candidate.ok)
+                    continue;
+                const ordinal = candidate.value.ordinal;
+                const owner = ordinals.get(ordinal);
+                if (owner) {
+                    dropped('level-ordinal-duplicate', `${candidate.at}.ordinal`, `${ordinal} duplicates ${owner}`, 'level dropped; ordinals are unique within a venue');
+                    candidate.ok = false;
+                }
+                else {
+                    ordinals.set(ordinal, candidate.at);
+                }
+            }
+        }
+        let contour;
+        if (value.contour !== undefined) {
+            const result = validateRing(value.contour);
+            if (result.issue) {
+                fallback('contour-invalid', `${at}.contour`, result.issue, "falls back to the scene layer's geometry, then to the hull of level rects");
+            }
+            else {
+                contour = result.ring;
+            }
+        }
+        let markerPoint;
+        if (value.markerPoint !== undefined) {
+            if (isFinitePoint(value.markerPoint)) {
+                markerPoint = { x: value.markerPoint.x, y: value.markerPoint.y };
+            }
+            else {
+                fallback('venue-marker-point-invalid', `${at}.markerPoint`, 'is not a finite {x, y} point', 'falls back to the contour centroid');
+            }
+        }
+        // The two edges of the size band resolve together (§4): the detail edge is
+        // checked for usability first, the marker edge is then judged against it,
+        // and only then is the detail edge clamped above whichever marker edge won.
+        let detailMinSizePx;
+        if (value.detailMinSizePx !== undefined) {
+            if (!isFiniteNumber(value.detailMinSizePx) || value.detailMinSizePx <= 0) {
+                fallback('detail-min-size-invalid', `${at}.detailMinSizePx`, 'is not a positive finite number', 'default 240 used');
+            }
+            else {
+                detailMinSizePx = value.detailMinSizePx;
+            }
+        }
+        let markerMaxSizePx;
+        if (value.markerMaxSizePx !== undefined) {
+            // Judged against the detail edge as the default ceiling would leave it:
+            // the marker edge is what is in question, so it cannot be its own yardstick.
+            const detailBeforeClamp = detailMinSizePx === undefined
+                ? DEFAULT_DETAIL_MIN_SIZE_PX
+                : Math.max(MIN_DETAIL_MIN_SIZE_PX, detailMinSizePx);
+            if (!isFiniteNumber(value.markerMaxSizePx) || value.markerMaxSizePx <= 0) {
+                fallback('marker-max-size-invalid', `${at}.markerMaxSizePx`, 'is not a positive finite number', `default ${DEFAULT_MARKER_MAX_SIZE_PX} used`);
+            }
+            else if (value.markerMaxSizePx >= detailBeforeClamp) {
+                fallback('marker-max-size-inverted', `${at}.markerMaxSizePx`, `${value.markerMaxSizePx} is at or above the venue's resolved detailMinSizePx of ${detailBeforeClamp}`, `default ${DEFAULT_MARKER_MAX_SIZE_PX} used, then the detail-edge clamp applies`);
+            }
+            else {
+                markerMaxSizePx = value.markerMaxSizePx;
+            }
+        }
+        const resolvedMarkerMaxSizePx = markerMaxSizePx ?? DEFAULT_MARKER_MAX_SIZE_PX;
+        if (detailMinSizePx !== undefined &&
+            !detailEdgeClearsMarkerEdge(detailMinSizePx, resolvedMarkerMaxSizePx)) {
+            const floor = detailMinSizeFloor(resolvedMarkerMaxSizePx);
+            clamped('detail-min-size-clamped', `${at}.detailMinSizePx`, `${detailMinSizePx} is below the ${floor}px marker/scene sticky enter edge`, `clamped to ${floor}`);
+            detailMinSizePx = floor;
+        }
+        const resolvedDetailMinSizePx = detailMinSizePx ?? DEFAULT_DETAIL_MIN_SIZE_PX;
+        const auxCandidates = [];
+        const expectedSceneLayers = [];
+        if (value.layers !== undefined) {
+            if (!Array.isArray(value.layers)) {
+                fallback('aux-layers-invalid', `${at}.layers`, 'is not an array', 'ignored; procedural appearance used');
+            }
+            else {
+                value.layers.forEach((aux, auxIndex) => {
+                    const auxAt = `${at}.layers[${auxIndex}]`;
+                    if (!isObject(aux)) {
+                        dropped('aux-entry-invalid', auxAt, 'is not an object', 'entry dropped');
+                        return;
+                    }
+                    reportUnknownKeys(auxAt, aux, AUX_KEYS);
+                    if (isNonEmptyString(aux.layer) &&
+                        aux.render === 'scene' &&
+                        (aux.replacesDefault === undefined || aux.replacesDefault === true)) {
+                        expectedSceneLayers.push(aux.layer);
+                    }
+                    const layerExists = isNonEmptyString(aux.layer) &&
+                        (geometries.has(aux.layer) || sceneCandidateLayerNames.has(aux.layer));
+                    rememberReference(aux.layer, layerExists);
+                    let ok = true;
+                    if (!isNonEmptyString(aux.layer)) {
+                        dropped('aux-layer-invalid', `${auxAt}.layer`, 'is missing or not a non-empty string', 'entry dropped');
+                        ok = false;
+                    }
+                    else {
+                        if (!layerExists) {
+                            dropped('aux-layer-unknown', `${auxAt}.layer`, `"${aux.layer}" does not exist in the plan`, 'entry dropped; venue falls back to the procedural appearance');
+                            ok = false;
+                        }
+                        if (aux.layer.startsWith('WF')) {
+                            dropped('aux-layer-wayfinding', `${auxAt}.layer`, `"${aux.layer}" is a wayfinding layer`, 'WF* layers are excluded before the venue model sees them — entry dropped');
+                            ok = false;
+                        }
+                    }
+                    const renderValid = RENDER_MODES.includes(aux.render);
+                    if (!renderValid) {
+                        dropped('aux-entry-invalid', `${auxAt}.render`, `is ${describe(aux.render)}, expected "scene" or "marker"`, 'entry dropped');
+                        ok = false;
+                    }
+                    if (aux.replacesDefault !== undefined && typeof aux.replacesDefault !== 'boolean') {
+                        dropped('aux-entry-invalid', `${auxAt}.replacesDefault`, 'is not a boolean', 'entry dropped');
+                        ok = false;
+                    }
+                    if (aux.suppressesLabel !== undefined && typeof aux.suppressesLabel !== 'boolean') {
+                        dropped('aux-entry-invalid', `${auxAt}.suppressesLabel`, 'is not a boolean', 'entry dropped');
+                        ok = false;
+                    }
+                    if (aux.minSizePx !== undefined &&
+                        (!isFiniteNumber(aux.minSizePx) || aux.minSizePx < 0)) {
+                        dropped('aux-entry-invalid', `${auxAt}.minSizePx`, 'is not a non-negative finite number', 'entry dropped');
+                        ok = false;
+                    }
+                    if (aux.maxSizePx !== undefined &&
+                        aux.maxSizePx !== 'detail' &&
+                        (!isFiniteNumber(aux.maxSizePx) || aux.maxSizePx < 0)) {
+                        dropped('aux-entry-invalid', `${auxAt}.maxSizePx`, 'is not a non-negative finite number or the literal "detail"', 'entry dropped');
+                        ok = false;
+                    }
+                    if (isFiniteNumber(aux.minSizePx) &&
+                        isFiniteNumber(aux.maxSizePx) &&
+                        aux.minSizePx >= 0 &&
+                        aux.maxSizePx >= 0 &&
+                        aux.minSizePx > aux.maxSizePx) {
+                        dropped('aux-range-inverted', auxAt, `minSizePx ${aux.minSizePx} exceeds maxSizePx ${aux.maxSizePx}`, 'entry dropped');
+                        ok = false;
+                    }
+                    const render = renderValid ? aux.render : 'scene';
+                    const resolvedMin = isFiniteNumber(aux.minSizePx) && aux.minSizePx >= 0
+                        ? aux.minSizePx
+                        : render === 'marker'
+                            ? 0
+                            : resolvedMarkerMaxSizePx;
+                    // Resolved the same way as the minimum: §7's default maxSizePx is
+                    // "detail" for scene layers and the venue's marker edge for markers
+                    // (Revision 5; 60 unless authored), so an entry that
+                    // only authors one bound (the most idiomatic shape) must still be
+                    // checked against its defaulted other bound — not the authored
+                    // value alone, which the un-resolved check below used to do.
+                    const resolvedMax = aux.maxSizePx !== undefined &&
+                        (aux.maxSizePx === 'detail' || isFiniteNumber(aux.maxSizePx))
+                        ? aux.maxSizePx
+                        : render === 'scene'
+                            ? 'detail'
+                            : resolvedMarkerMaxSizePx;
+                    const impossibleRange = resolvedMax === 'detail'
+                        ? resolvedMin >= resolvedDetailMinSizePx
+                        : resolvedMin > resolvedMax;
+                    if (renderValid && impossibleRange) {
+                        dropped('aux-range-never-visible', auxAt, `resolved range ${resolvedMin}..${resolvedMax} can never render`, 'entry dropped; the procedural fallback for this render mode is restored');
+                        ok = false;
+                    }
+                    if (renderValid && render === 'scene' && isFiniteNumber(aux.maxSizePx)) {
+                        advisory('aux-max-size-numeric', `${auxAt}.maxSizePx`, `is the hard edge ${aux.maxSizePx} rather than "detail"`, 'a static edge cannot follow the ±10% detail hysteresis — expect flicker and brief overlap with the floor plan');
+                    }
+                    auxCandidates.push({
+                        value: {
+                            layer: isNonEmptyString(aux.layer) ? aux.layer : '',
+                            render,
+                            replacesDefault: typeof aux.replacesDefault === 'boolean' ? aux.replacesDefault : undefined,
+                            suppressesLabel: typeof aux.suppressesLabel === 'boolean' ? aux.suppressesLabel : undefined,
+                            minSizePx: isFiniteNumber(aux.minSizePx) ? aux.minSizePx : undefined,
+                            maxSizePx: aux.maxSizePx === 'detail' || isFiniteNumber(aux.maxSizePx)
+                                ? aux.maxSizePx
+                                : undefined,
+                        },
+                        at: auxAt,
+                        ok,
+                        surviving: false,
+                    });
+                });
+            }
+        }
+        // An entrance stands on a level of its own venue (§6.1), so it is checked
+        // against the levels this venue *authored* — not against the plan's layers,
+        // and not against the levels that survive. That keeps the answer identical
+        // in the export-time validator, which sees no geometry and no claims; a
+        // door orphaned by a level that later drops is reported below instead.
+        const authoredLevelLayers = new Set((Array.isArray(value.levels) ? value.levels : [])
+            .filter(isObject)
+            .map((level) => level.layer)
+            .filter(isNonEmptyString));
+        const entranceCandidates = [];
+        if (value.entrances !== undefined) {
+            if (!Array.isArray(value.entrances)) {
+                fallback('entrances-invalid', `${at}.entrances`, 'is not an array', 'ignored; the venue keeps marker-point targeting');
+            }
+            else {
+                value.entrances.forEach((entrance, entranceIndex) => {
+                    const entranceAt = `${at}.entrances[${entranceIndex}]`;
+                    if (!isObject(entrance)) {
+                        dropped('entrance-entry-invalid', entranceAt, 'is not an object', 'entrance dropped');
+                        return;
+                    }
+                    reportUnknownKeys(entranceAt, entrance, ENTRANCE_KEYS);
+                    // Unlike a level or an aux entry, a rejected door claims nothing and
+                    // is never reconsidered, so it is dropped here rather than carried on
+                    // as a candidate with placeholder geometry.
+                    let ok = true;
+                    if (!isNonEmptyString(entrance.layer)) {
+                        dropped('entrance-layer-invalid', `${entranceAt}.layer`, 'is missing or not a non-empty string', 'entrance dropped');
+                        ok = false;
+                    }
+                    else if (!authoredLevelLayers.has(entrance.layer)) {
+                        dropped('entrance-layer-foreign', `${entranceAt}.layer`, `"${entrance.layer}" is not a level of venue ${label}`, 'entrance dropped; an entrance stands on one of its own venue’s levels');
+                        ok = false;
+                    }
+                    if (!isFinitePoint(entrance.point)) {
+                        dropped('entrance-entry-invalid', `${entranceAt}.point`, 'is missing or not a finite {x, y} point', 'entrance dropped; an entrance is a point before it is anything else');
+                        ok = false;
+                    }
+                    if (entrance.name !== undefined && !isNonEmptyString(entrance.name)) {
+                        fallback('entrance-field-invalid', `${entranceAt}.name`, 'is not a non-empty string', 'falls back to the venue’s own name');
+                    }
+                    if (!ok || !isNonEmptyString(entrance.layer) || !isFinitePoint(entrance.point))
+                        return;
+                    entranceCandidates.push({
+                        value: {
+                            layer: entrance.layer,
+                            point: { x: entrance.point.x, y: entrance.point.y },
+                            name: isNonEmptyString(entrance.name) ? entrance.name : undefined,
+                        },
+                        at: entranceAt,
+                    });
+                });
+            }
+        }
+        return {
+            at,
+            id: isNonEmptyString(id) ? id : undefined,
+            name: isNonEmptyString(name) ? name : undefined,
+            label,
+            claimable,
+            order,
+            levels: levelCandidates,
+            aux: auxCandidates,
+            entrances: entranceCandidates,
+            expectedSceneLayers,
+            contour,
+            markerPoint,
+            detailMinSizePx,
+            markerMaxSizePx,
+            referencedLayers,
+            campusViewbox: value.campusViewbox,
+        };
+    });
+    const geometryDropped = new Set();
+    /**
+     * The order competing claims are resolved in (§10): resolved `order`, then
+     * `id`. Deliberately NOT array position — a contested layer is a broken
+     * authoring state either way, so the property worth having is that the
+     * winner survives a re-export that reorders `venues[]`. `sort` is stable, so
+     * venues that tie on both keys (only unidentified ones, which never claim)
+     * keep their array position.
+     *
+     * Codepoint comparison, not `localeCompare`: the same payload must resolve
+     * identically in this parser, in the reference validator and in whatever
+     * runs a producer's export gate, and `localeCompare` orders `-`, `_` and
+     * digits by ICU collation rules that vary between runtimes.
+     */
+    const claimOrder = [...states].sort((a, b) => a.order - b.order || compareIds(a.id ?? '', b.id ?? ''));
+    // The campus viewbox belongs to the plan, not to the venue carrying it (§3):
+    // the first carrier in the same order as claims holds it — usable or not —
+    // and every later carrier is ignored. It is read from the authored record,
+    // so a carrier that is dropped as a venue still frames the campus.
+    let campusViewbox = null;
+    let campusCarrier;
+    for (const state of claimOrder) {
+        if (state.campusViewbox === undefined)
+            continue;
+        const at = `${state.at}.campusViewbox`;
+        if (campusCarrier) {
+            dropped('campus-viewbox-duplicate', at, `${campusCarrier.at} already carries the campus viewbox`, "this venue's value is ignored; the first carrier by order wins");
+            continue;
+        }
+        campusCarrier = state;
+        const value = state.campusViewbox;
+        if (isCampusViewbox(value)) {
+            campusViewbox = new Box(value.x, value.y, value.width, value.height);
+        }
+        else {
+            fallback('campus-viewbox-invalid', at, 'is not an {x, y, width, height} of finite numbers with a positive width and height', 'the campus is framed by the union of the venue footprints');
+        }
+    }
+    const assignClaims = () => {
+        const claims = new Map();
+        for (const state of states) {
+            state.parsed = undefined;
+            for (const candidate of state.levels)
+                candidate.surviving = false;
+            for (const candidate of state.aux)
+                candidate.surviving = false;
+        }
+        // KTD3: every valid level receives its claim opportunity before any aux entry.
+        for (const state of claimOrder) {
+            if (!state.claimable || !state.id || !state.name || geometryDropped.has(state))
+                continue;
+            for (const candidate of state.levels) {
+                if (!candidate.ok)
+                    continue;
+                const layer = candidate.value.layer;
+                const claimedBy = claims.get(layer);
+                if (claimedBy) {
+                    dropped('level-layer-claimed', `${candidate.at}.layer`, `"${layer}" is already used by ${claimedBy.label} (${claimedBy.role})`, 'level dropped; a layer belongs to at most one venue and one role');
+                    continue;
+                }
+                claims.set(layer, { label: state.label, role: 'level' });
+                candidate.surviving = true;
+            }
+        }
+        for (const state of claimOrder) {
+            if (!state.claimable ||
+                !state.id ||
+                !state.name ||
+                geometryDropped.has(state) ||
+                !state.levels.some((candidate) => candidate.surviving)) {
+                continue;
+            }
+            let markerCount = 0;
+            for (const candidate of state.aux) {
+                if (!candidate.ok)
+                    continue;
+                const aux = candidate.value;
+                const claimedBy = claims.get(aux.layer);
+                if (claimedBy) {
+                    dropped('aux-layer-claimed', `${candidate.at}.layer`, `"${aux.layer}" is already used by ${claimedBy.label} (${claimedBy.role})`, 'entry dropped; a layer is a level, an aux layer, or neither — never two');
+                    continue;
+                }
+                if (aux.render === 'marker' && markerCount > 0) {
+                    dropped('aux-marker-duplicate', `${candidate.at}.render`, 'is a second marker layer for this venue', 'at most one per venue; extras dropped, the first wins');
+                    continue;
+                }
+                claims.set(aux.layer, { label: state.label, role: 'aux' });
+                candidate.surviving = true;
+                if (aux.render === 'marker')
+                    markerCount++;
+            }
+        }
+        return claims;
+    };
+    const resolveContour = (state) => {
+        if (state.contour)
+            return state.contour;
+        const venueIndex = states.indexOf(state);
+        const replacingScenes = state.aux.filter((candidate) => candidate.ok &&
+            candidate.value.render === 'scene' &&
+            candidate.value.replacesDefault !== false);
+        const candidateByLayer = new Map(replacingScenes
+            .filter((candidate) => candidate.surviving)
+            .map((candidate) => [candidate.value.layer, candidate]));
+        const validScenes = [];
+        for (const scene of sceneCandidates[venueIndex] ?? []) {
+            const candidate = candidateByLayer.get(scene.layer);
+            if (!candidate?.surviving)
+                continue;
+            const unusable = (issue) => fallback('footprint-source-unusable', `${candidate.at}.layer`, `scene layer "${scene.layer}" ${issue}`, 'the next valid replacing scene is tried, then the level-rect hull');
+            const { extraction } = scene;
+            if (!extraction.ring) {
+                // Naming the shapes is the whole point: on an ordinary plan layer only
+                // paths are drawn (§6), so an author who outlined the building with a
+                // rect sees artwork on screen and cannot otherwise tell why the venue
+                // took its footprint from somewhere else.
+                unusable(extraction.unusableElementKinds.length > 0
+                    ? `draws no usable <path>; only paths are footprint sources, and it draws ${extraction.unusableElementKinds
+                        .map((kind) => `<${kind}>`)
+                        .join(', ')}`
+                    : 'could not supply a valid contour');
+                continue;
+            }
+            const validation = validateRing(extraction.ring);
+            if (!validation.ring) {
+                unusable(validation.issue ?? 'could not supply a valid contour');
+                continue;
+            }
+            validScenes.push({
+                candidate,
+                layer: scene.layer,
+                ring: validation.ring,
+                boundsFallback: extraction.boundsFallback,
+            });
+        }
+        if (validScenes.length > 1) {
+            advisory('footprint-source-ambiguous', `${state.at}.layers`, `multiple replacing scene layers provide contours: ${validScenes
+                .map(({ layer }) => `"${layer}"`)
+                .join(', ')}`, `the first in plan-layer order, "${validScenes[0].layer}", wins`);
+        }
+        const selected = validScenes[0];
+        if (selected) {
+            if (selected.boundsFallback) {
+                fallback('footprint-bounding-box', `${selected.candidate.at}.layer`, `scene layer "${selected.layer}" uses its bounding box for the venue contour`, 'camera, tap target, and size bounds may extend beyond the artwork');
+            }
+            return selected.ring;
+        }
+        const hull = deriveLevelHull(state.levels, geometries);
+        if (hull.length >= 3 && state.expectedSceneLayers.length > 0) {
+            fallback('footprint-source-fallthrough', `${state.at}.contour`, 'replacing scene contour unavailable; using the level-rect hull', 'bounds, camera target, tap target, and the size axis changed source');
+        }
+        return hull;
+    };
+    // A geometry-invalid earlier venue must release its claims before later venues
+    // are evaluated. Drop one at a time so each retry sees the newly available roles.
+    while (true) {
+        // Claim assignment and contour resolution are the same code whether or not
+        // the pass is final; only their diagnostics differ. Run the probe with the
+        // buffer rewound afterwards rather than threading a "stay quiet" flag
+        // through every emit site — the claim/survivor mutations still stand.
+        const failed = speculative(() => {
+            assignClaims();
+            // Claim order again, not array position: dropping a venue releases its
+            // claims to the others, so which one is examined first is part of the
+            // outcome (§10).
+            return claimOrder.find((state) => state.claimable &&
+                !geometryDropped.has(state) &&
+                state.levels.some((candidate) => candidate.surviving) &&
+                resolveContour(state).length < 3);
+        });
+        if (!failed)
+            break;
+        resolveContour(failed);
+        dropped('footprint-underivable', `${failed.at}.contour`, 'no valid polygon can be derived', `venue ${failed.label} dropped entirely`);
+        geometryDropped.add(failed);
+    }
+    const claimedLayers = assignClaims();
+    for (const state of states) {
+        if (!state.claimable || !state.id || !state.name || geometryDropped.has(state))
+            continue;
+        const survivingLevels = state.levels.filter((candidate) => candidate.surviving);
+        if (survivingLevels.length === 0) {
+            dropped('venue-levels-all-dropped', `${state.at}.levels`, 'no level survives validation', `venue ${state.label} dropped entirely`);
+            continue;
+        }
+        const contour = resolveContour(state);
+        const authoredInitial = state.levels.filter((candidate) => candidate.value.initial === true);
+        const survivingInitial = survivingLevels.filter((candidate) => candidate.value.initial === true);
+        if (authoredInitial.some((candidate) => !candidate.surviving)) {
+            const lostInitial = authoredInitial.find((candidate) => !candidate.surviving);
+            fallback('level-initial-dropped', `${lostInitial.at}.initial`, 'initial level was dropped', 'the lowest surviving ordinal is initial');
+        }
+        // A dropped ordinal-0 (ground) level is usually both the default
+        // `initial` level and the floor carrying the venue↔pathway virtual
+        // connection — §11's "drop the level, not the venue" design otherwise
+        // leaves the hall booting on an upper floor with cross-venue routing
+        // silently broken (§13, undetectable from data.js alone).
+        const authoredGround = state.levels.filter((candidate) => candidate.value.ordinal === 0);
+        if (authoredGround.length > 0 &&
+            !survivingLevels.some((candidate) => candidate.value.ordinal === 0)) {
+            advisory('level-ground-dropped', `${state.at}.levels`, 'the ordinal 0 (ground) level was dropped', 'cross-venue routing into this venue is likely broken (§13); the venue also boots on an upper floor');
+        }
+        if (survivingInitial.length > 1) {
+            advisory('level-initial-duplicate', `${state.at}.levels`, `${survivingInitial.length} levels are marked initial`, 'at most one per venue; the SDK takes the first');
+        }
+        const initial = survivingInitial[0] ??
+            survivingLevels.reduce((lowest, candidate) => candidate.value.ordinal < lowest.value.ordinal ? candidate : lowest);
+        // A door on a level the venue just lost leads nowhere the SDK can draw or
+        // route to, so it goes with the level — and says so, because the venue may
+        // be left with fewer doors, or with none and back on its marker point.
+        const survivingLevelLayers = new Set(survivingLevels.map((candidate) => candidate.value.layer));
+        const entrances = [];
+        for (const candidate of state.entrances) {
+            if (!survivingLevelLayers.has(candidate.value.layer)) {
+                // `dropped`, not `fallback` (ADR-0009): the entrance leaves the model.
+                // What the venue does afterwards — its other doors, then its marker
+                // point — is the consequence, which is what that field is for.
+                dropped('entrance-level-dropped', `${candidate.at}.layer`, `level "${candidate.value.layer}" did not survive validation`, 'entrance dropped; the venue falls back to its remaining doors, then to marker-point targeting');
+                continue;
+            }
+            entrances.push({ ...candidate.value });
+        }
+        const copiedContour = contour.map((point) => ({ x: point.x, y: point.y }));
+        state.parsed = {
+            id: state.id,
+            name: state.name,
+            order: state.order,
+            levels: survivingLevels.map((candidate) => ({
+                layer: candidate.value.layer,
+                ordinal: candidate.value.ordinal,
+                name: candidate.value.name,
+                initial: candidate === initial,
+            })),
+            contour: copiedContour,
+            markerPoint: state.markerPoint ?? polygonCentroid(copiedContour),
+            bounds: Box.fromPoints(copiedContour),
+            detailMinSizePx: state.detailMinSizePx,
+            markerMaxSizePx: state.markerMaxSizePx,
+            entrances,
+            auxLayers: state.aux
+                .filter((candidate) => candidate.surviving)
+                .map(({ value: aux }) => {
+                const replacesDefault = aux.replacesDefault ?? true;
+                return {
+                    layer: aux.layer,
+                    render: aux.render,
+                    replacesDefault,
+                    // Artwork that replaces the procedural scene also carries the venue's
+                    // name, so the SDK's label would double it (§7); a marker never
+                    // suppresses the label unless the author says so (§4, R14).
+                    suppressesLabel: aux.suppressesLabel ?? (aux.render === 'scene' && replacesDefault),
+                    minSizePx: aux.minSizePx,
+                    maxSizePx: aux.maxSizePx,
+                };
+            }),
+        };
+    }
+    const quarantineCandidates = [];
+    for (const state of states) {
+        if (state.parsed)
+            continue;
+        for (const layer of state.referencedLayers) {
+            if (!quarantineCandidates.includes(layer))
+                quarantineCandidates.push(layer);
+        }
+    }
+    const parsedVenues = [];
+    for (const state of states) {
+        if (state.parsed)
+            parsedVenues.push(state.parsed);
+    }
+    // Every venue failed validation: nothing claims a layer, so every
+    // referenced layer would otherwise become a quarantine candidate and the
+    // whole plan would render blank — inverting §11's "a broken venue must not
+    // take an event offline" promise. Degrade to single-venue instead, the
+    // same precedent already used for an unsupported venuesVersion above.
+    if (venuesValue.length > 0 && parsedVenues.length === 0) {
+        dropped('venues-all-dropped', 'venues', 'no venue survived validation', 'plan loads as single-venue');
+        return complete([], diagnostics, []);
+    }
+    const quarantinedLayerNames = quarantineCandidates.filter((layer) => !claimedLayers.has(layer));
+    if (quarantinedLayerNames.length > 0) {
+        dropped('plan-layers-quarantined', 'venues', `quarantined unclaimed layer${quarantinedLayerNames.length === 1 ? '' : 's'}: ${quarantinedLayerNames
+            .map((layer) => `"${layer}"`)
+            .join(', ')}`, 'hidden from venue and ordinary layer rendering');
+    }
+    return complete(parsedVenues, diagnostics, quarantinedLayerNames, campusViewbox);
+}