@expofp/floorplan 0.0.0-experimental.2d6c681

package/dist/esm/components/Maplibre/utils/venue-contour.js

@@ -0,0 +1,188 @@
+import { Box } from '@expofp/geometry';
+function meshPositions(mesh) {
+    if (!mesh || !Array.isArray(mesh.positions) || mesh.positions.length < 3)
+        return null;
+    const points = [];
+    for (const position of mesh.positions) {
+        if (!Array.isArray(position) ||
+            !Number.isFinite(position[0]) ||
+            !Number.isFinite(position[1])) {
+            return null;
+        }
+        points.push({ x: position[0], y: position[1] });
+    }
+    return points;
+}
+/**
+ * Walks the boundary of a triangulated mesh back into a single ring. Returns
+ * null unless the boundary is exactly one closed, manifold loop — a mesh with a
+ * hole, several disjoint parts, or a non-manifold edge has no single outline.
+ */
+function ringFromMesh(mesh) {
+    if (!mesh || !Array.isArray(mesh.positions) || !Array.isArray(mesh.cells))
+        return null;
+    const vertices = [];
+    const vertexByCoordinate = new Map();
+    const sourceToVertex = mesh.positions.map((position) => {
+        if (!Array.isArray(position) ||
+            !Number.isFinite(position[0]) ||
+            !Number.isFinite(position[1])) {
+            return -1;
+        }
+        const key = `${position[0]},${position[1]}`;
+        const known = vertexByCoordinate.get(key);
+        if (known !== undefined)
+            return known;
+        const index = vertices.length;
+        vertices.push({ x: position[0], y: position[1] });
+        vertexByCoordinate.set(key, index);
+        return index;
+    });
+    const edgeCounts = new Map();
+    for (const cell of mesh.cells) {
+        if (!Array.isArray(cell) || cell.length !== 3)
+            return null;
+        const triangle = cell.map((index) => sourceToVertex[index]);
+        if (triangle.some((index) => index === undefined || index < 0) ||
+            new Set(triangle).size !== 3) {
+            return null;
+        }
+        for (let index = 0; index < 3; index++) {
+            const first = triangle[index];
+            const second = triangle[(index + 1) % 3];
+            const a = Math.min(first, second);
+            const b = Math.max(first, second);
+            const key = `${a}:${b}`;
+            const edge = edgeCounts.get(key);
+            if (edge) {
+                edge.count++;
+                if (edge.count > 2)
+                    return null;
+            }
+            else {
+                edgeCounts.set(key, { a, b, count: 1 });
+            }
+        }
+    }
+    const adjacency = new Map();
+    for (const edge of edgeCounts.values()) {
+        if (edge.count !== 1)
+            continue;
+        const from = adjacency.get(edge.a) ?? [];
+        const to = adjacency.get(edge.b) ?? [];
+        from.push(edge.b);
+        to.push(edge.a);
+        adjacency.set(edge.a, from);
+        adjacency.set(edge.b, to);
+    }
+    if (adjacency.size < 3 ||
+        Array.from(adjacency.values()).some((neighbors) => neighbors.length !== 2)) {
+        return null;
+    }
+    let start = Number.POSITIVE_INFINITY;
+    adjacency.forEach((_neighbors, vertex) => {
+        start = Math.min(start, vertex);
+    });
+    const ordered = [];
+    const visited = new Set();
+    let previous = -1;
+    let current = start;
+    do {
+        if (visited.has(current))
+            return null;
+        visited.add(current);
+        ordered.push(current);
+        const neighbors = adjacency.get(current);
+        const next = neighbors[0] === previous ? neighbors[1] : neighbors[0];
+        previous = current;
+        current = next;
+    } while (current !== start && ordered.length <= adjacency.size);
+    if (current !== start || ordered.length !== adjacency.size)
+        return null;
+    return ordered.map((index) => vertices[index]);
+}
+/**
+ * True when the shape (or an ancestor) carries an effect whose painted extent
+ * can exceed its geometry — a genuine reason to fall back to the bounding
+ * box. A stroke is deliberately NOT one of these: a single stroked closed
+ * path is the natural way to author a contour outline (§6 tells authors to
+ * do exactly that), so treating a stroke as disqualifying pushed idiomatic
+ * artwork straight into the fallback it was meant to avoid.
+ */
+function hasPaintExtendingEffect(shape, root) {
+    let current = shape;
+    while (current) {
+        if (['filter', 'mask', 'clip-path', 'marker-start', 'marker-mid', 'marker-end'].some((name) => current.hasAttribute(name))) {
+            return true;
+        }
+        if (current === root)
+            break;
+        current = current.parentElement;
+    }
+    return false;
+}
+function boundsRing(pointSets) {
+    const box = Box.fromPoints(pointSets.flat());
+    const { min, max } = box;
+    if (!Number.isFinite(min.x) || !Number.isFinite(min.y))
+        return null;
+    return [
+        { x: min.x, y: min.y },
+        { x: max.x, y: min.y },
+        { x: max.x, y: max.y },
+        { x: min.x, y: max.y },
+    ];
+}
+/**
+ * Every SVG shape element that can appear on a plan layer. Only `<path>` is a
+ * footprint source — both drawing implementations select paths and dispatch on
+ * their mesh index, so nothing else on an ordinary layer is ever rendered (§6).
+ * The rest are matched anyway, so an author who drew one can be told which.
+ */
+const SHAPE_SELECTOR = 'path, rect, polygon, circle, ellipse, polyline, line';
+/**
+ * Extracts one plan-local ring from a venue's scene layer.
+ *
+ * Geometry comes from the same source the renderer draws from: a `<path>` is
+ * read through its `data-index` mesh (`window.__fpPaths`), never by parsing `d`,
+ * and coordinates are taken verbatim — no SVG transform or viewBox scaling is
+ * applied, matching `Box.fromSvg` and `meshToShapeDef`. A path the renderer
+ * cannot draw therefore yields no contour, and the caller falls back per §6 of
+ * the data contract.
+ *
+ * The returned ring is a candidate only; `parseVenues` validates it.
+ */
+export function extractVenueContour(root, getMesh) {
+    const shapes = Array.from(root.querySelectorAll(SHAPE_SELECTOR)).filter((shape) => !shape.closest('defs'));
+    const paths = shapes.filter((shape) => shape.tagName.toLowerCase() === 'path');
+    const noRing = (unusableElementKinds = []) => ({
+        ring: null,
+        unusableElementKinds,
+    });
+    // Kinds are named only here, where the shapes drawn instead of a path are the
+    // whole reason there is no footprint. Below, a path was drawn and the answer
+    // is missing geometry, not the wrong element — naming the decoration standing
+    // beside it would send the author to redraw artwork that was never at fault.
+    if (paths.length === 0) {
+        return noRing([...new Set(shapes.map((shape) => shape.tagName.toLowerCase()))]);
+    }
+    const meshes = paths.map((path) => {
+        const dataIndex = path.getAttribute('data-index');
+        if (dataIndex === null || !/^\d+$/.test(dataIndex) || !getMesh)
+            return null;
+        return getMesh(Number(dataIndex)) ?? null;
+    });
+    const pointSets = meshes.map((mesh) => meshPositions(mesh));
+    if (pointSets.some((points) => !points))
+        return noRing();
+    const validPointSets = pointSets;
+    const bounds = () => {
+        const ring = boundsRing(validPointSets);
+        return ring ? { ring, boundsFallback: true } : noRing();
+    };
+    if (paths.length > 1 || hasPaintExtendingEffect(paths[0], root))
+        return bounds();
+    // Only reached for a lone path, so the boundary walk runs at most once.
+    const ring = ringFromMesh(meshes[0]);
+    return ring ? { ring, boundsFallback: false } : noRing();
+}

package/dist/esm/components/Maplibre/utils/venue-focus.d.ts

@@ -0,0 +1,26 @@
+import { type Box } from '@expofp/geometry';
+export interface VenueFocusCandidate {
+    name: string;
+    floorIndex?: number;
+    indoorDetail?: boolean;
+    rect?: Box | null;
+    viewbox?: Box | null;
+}
+export type VenueFocusState = {
+    kind: 'focus';
+    name: string;
+} | {
+    kind: 'none';
+};
+/**
+ * Resolves the viewport's context venue from weighted spatial confidence.
+ *
+ * The score combines center proximity, visible screen area, visible venue
+ * fraction, and center containment. A cold campus view needs both absolute
+ * and relative confidence. An incumbent is retained until a challenger earns
+ * the larger handoff margin. Indoor detail always receives a context: an
+ * ambiguous view retains its visible indoor incumbent or chooses the nearest
+ * visible indoor venue on a cold start.
+ */
+export declare function resolveVenueFocusState(viewport: Box, candidates: readonly VenueFocusCandidate[], focusedName?: string | null): VenueFocusState;
+//# sourceMappingURL=venue-focus.d.ts.map

package/dist/esm/components/Maplibre/utils/venue-focus.js

@@ -0,0 +1,106 @@
+import { pointDistance } from '@expofp/geometry';
+// SDK-owned policy values. They are intentionally centralized here rather
+// than exposed through venue authoring data.
+const CENTER_PROXIMITY_WEIGHT = 0.35;
+const VISIBLE_VENUE_FRACTION_WEIGHT = 0.3;
+const VISIBLE_VIEWPORT_AREA_WEIGHT = 0.15;
+const VIEWPORT_CENTER_INSIDE_WEIGHT = 0.2;
+const ABSOLUTE_CONFIDENCE = 0.45;
+const RELATIVE_CONFIDENCE_MARGIN = 0.08;
+const CONTEXT_HANDOFF_MARGIN = 0.12;
+function boundsOf(candidate) {
+    const bounds = candidate.viewbox ?? candidate.rect ?? null;
+    return bounds && bounds.area > 0 ? bounds : null;
+}
+function scoreCandidates(viewport, candidates) {
+    const viewportArea = viewport.area;
+    const viewportDiagonal = Math.hypot(viewport.size.x, viewport.size.y);
+    if (viewportArea <= 0 || viewportDiagonal <= 0)
+        return [];
+    return candidates.flatMap((candidate, index) => {
+        const bounds = boundsOf(candidate);
+        if (!bounds)
+            return [];
+        const overlap = bounds.intersection(viewport)?.area ?? 0;
+        if (overlap <= 0)
+            return [];
+        const centerDistance = pointDistance(bounds.center, viewport.center);
+        const centerProximity = Math.max(0, 1 - centerDistance / viewportDiagonal);
+        const visibleVenueFraction = Math.min(1, overlap / bounds.area);
+        const visibleViewportArea = Math.min(1, overlap / viewportArea);
+        const viewportCenterInside = bounds.containsPoint(viewport.center) ? 1 : 0;
+        return [
+            {
+                candidate,
+                centerDistance,
+                indoorDetail: candidate.indoorDetail === true,
+                order: candidate.floorIndex ?? index,
+                score: centerProximity * CENTER_PROXIMITY_WEIGHT +
+                    visibleVenueFraction * VISIBLE_VENUE_FRACTION_WEIGHT +
+                    visibleViewportArea * VISIBLE_VIEWPORT_AREA_WEIGHT +
+                    viewportCenterInside * VIEWPORT_CENTER_INSIDE_WEIGHT,
+            },
+        ];
+    });
+}
+function compareCandidates(a, b) {
+    return b.score - a.score || a.centerDistance - b.centerDistance || a.order - b.order;
+}
+function nearestIndoorCandidate(scored) {
+    return (scored
+        .filter(({ indoorDetail }) => indoorDetail)
+        .sort((a, b) => a.centerDistance - b.centerDistance || a.order - b.order)[0] ?? null);
+}
+/**
+ * Resolves the viewport's context venue from weighted spatial confidence.
+ *
+ * The score combines center proximity, visible screen area, visible venue
+ * fraction, and center containment. A cold campus view needs both absolute
+ * and relative confidence. An incumbent is retained until a challenger earns
+ * the larger handoff margin. Indoor detail always receives a context: an
+ * ambiguous view retains its visible indoor incumbent or chooses the nearest
+ * visible indoor venue on a cold start.
+ */
+export function resolveVenueFocusState(viewport, candidates, focusedName = null) {
+    const ordered = candidates
+        .map((candidate, index) => ({ candidate, order: candidate.floorIndex ?? index }))
+        .sort((a, b) => a.order - b.order);
+    // A zero-area viewport is the camera hook's point fallback. It cannot
+    // support area scoring, but containment still gives a deterministic result.
+    if (viewport.area <= 0) {
+        const containing = ordered.find(({ candidate }) => boundsOf(candidate)?.containsPoint(viewport.center));
+        return containing ? { kind: 'focus', name: containing.candidate.name } : { kind: 'none' };
+    }
+    const scored = scoreCandidates(viewport, ordered.map(({ candidate }) => candidate)).sort(compareCandidates);
+    if (!scored.length)
+        return { kind: 'none' };
+    const indoorScored = scored.filter(({ indoorDetail }) => indoorDetail);
+    const eligible = indoorScored.length > 0 ? indoorScored : scored;
+    const best = eligible[0];
+    const incumbent = focusedName
+        ? eligible.find(({ candidate }) => candidate.name === focusedName)
+        : undefined;
+    if (incumbent) {
+        if (best.candidate.name === incumbent.candidate.name) {
+            if (incumbent.score >= ABSOLUTE_CONFIDENCE || incumbent.indoorDetail) {
+                return { kind: 'focus', name: incumbent.candidate.name };
+            }
+            return { kind: 'none' };
+        }
+        if (best.score >= ABSOLUTE_CONFIDENCE &&
+            best.score - incumbent.score >= CONTEXT_HANDOFF_MARGIN) {
+            return { kind: 'focus', name: best.candidate.name };
+        }
+        if (incumbent.score >= ABSOLUTE_CONFIDENCE || incumbent.indoorDetail) {
+            return { kind: 'focus', name: incumbent.candidate.name };
+        }
+        return { kind: 'none' };
+    }
+    const runnerUp = eligible[1];
+    const hasRelativeConfidence = !runnerUp || best.score - runnerUp.score >= RELATIVE_CONFIDENCE_MARGIN;
+    if (best.score >= ABSOLUTE_CONFIDENCE && hasRelativeConfidence) {
+        return { kind: 'focus', name: best.candidate.name };
+    }
+    const nearestIndoor = nearestIndoorCandidate(eligible);
+    return nearestIndoor ? { kind: 'focus', name: nearestIndoor.candidate.name } : { kind: 'none' };
+}

package/dist/esm/components/Maplibre/utils/venue-legibility.d.ts

@@ -0,0 +1,30 @@
+export { DEFAULT_DETAIL_MIN_SIZE_PX, DEFAULT_MARKER_MAX_SIZE_PX } from '../../../data/venues';
+export declare const SIZE_HYSTERESIS_RATIO = 0.1;
+/**
+ * The venue's detail cutoff. `parseVenues` already rejects non-positive values
+ * and clamps authored ones into the legal band, so an absent value is the only
+ * case left to resolve — every size-axis module resolves it through here.
+ */
+export declare function resolveDetailThreshold(detailMinSizePx: number | undefined): number;
+/**
+ * The venue's marker ⇄ scene edge (§4, Revision 5). Like the detail cutoff,
+ * `parseVenues` has already replaced an unusable or inverted value with the
+ * default, so an absent value is the only case left.
+ */
+export declare function resolveMarkerThreshold(markerMaxSizePx: number | undefined): number;
+/** The size at which a below-threshold edge flips above it (the sticky enter edge). */
+export declare function stickyEnterSizePx(threshold: number): number;
+/**
+ * The detail cutoff on the current screen. A venue whose floors fit the
+ * viewport only below its authored cutoff (a wide hall on a phone) would
+ * otherwise show its contour wherever its whole floor is visible, so the
+ * cutoff drops until the sticky enter edge sits at `fitSizePx` — the venue's
+ * size where its floors fit. Never below `floor` — the venue's own detail
+ * floor (`detailMinSizeFloor` of its marker edge; the contract's 66 by
+ * default) — which keeps the scene band between the marker and detail edges.
+ */
+export declare function resolveViewportDetailThreshold(threshold: number, fitSizePx: number | null, floor?: number): number;
+export type StickySizeEdgeState = 'below' | 'above';
+/** Resolves one default size edge while retaining its incumbent side inside the ±10% band. */
+export declare function resolveStickySizeEdge(sizePx: number | null, threshold: number, previous: StickySizeEdgeState | null): StickySizeEdgeState;
+//# sourceMappingURL=venue-legibility.d.ts.map

package/dist/esm/components/Maplibre/utils/venue-legibility.js

@@ -0,0 +1,52 @@
+import { DEFAULT_DETAIL_MIN_SIZE_PX, DEFAULT_MARKER_MAX_SIZE_PX, MIN_DETAIL_MIN_SIZE_PX, } from '../../../data/venues';
+// The contract owns these defaults; re-exported so the size-axis modules keep
+// importing them from one place.
+export { DEFAULT_DETAIL_MIN_SIZE_PX, DEFAULT_MARKER_MAX_SIZE_PX } from '../../../data/venues';
+export const SIZE_HYSTERESIS_RATIO = 0.1;
+/**
+ * The venue's detail cutoff. `parseVenues` already rejects non-positive values
+ * and clamps authored ones into the legal band, so an absent value is the only
+ * case left to resolve — every size-axis module resolves it through here.
+ */
+export function resolveDetailThreshold(detailMinSizePx) {
+    return detailMinSizePx ?? DEFAULT_DETAIL_MIN_SIZE_PX;
+}
+/**
+ * The venue's marker ⇄ scene edge (§4, Revision 5). Like the detail cutoff,
+ * `parseVenues` has already replaced an unusable or inverted value with the
+ * default, so an absent value is the only case left.
+ */
+export function resolveMarkerThreshold(markerMaxSizePx) {
+    return markerMaxSizePx ?? DEFAULT_MARKER_MAX_SIZE_PX;
+}
+/** The size at which a below-threshold edge flips above it (the sticky enter edge). */
+export function stickyEnterSizePx(threshold) {
+    return threshold + threshold * SIZE_HYSTERESIS_RATIO;
+}
+/**
+ * The detail cutoff on the current screen. A venue whose floors fit the
+ * viewport only below its authored cutoff (a wide hall on a phone) would
+ * otherwise show its contour wherever its whole floor is visible, so the
+ * cutoff drops until the sticky enter edge sits at `fitSizePx` — the venue's
+ * size where its floors fit. Never below `floor` — the venue's own detail
+ * floor (`detailMinSizeFloor` of its marker edge; the contract's 66 by
+ * default) — which keeps the scene band between the marker and detail edges.
+ */
+export function resolveViewportDetailThreshold(threshold, fitSizePx, floor = MIN_DETAIL_MIN_SIZE_PX) {
+    if (fitSizePx === null || !Number.isFinite(fitSizePx) || fitSizePx <= 0)
+        return threshold;
+    const fitThreshold = fitSizePx / (1 + SIZE_HYSTERESIS_RATIO);
+    return Math.min(threshold, Math.max(floor, fitThreshold));
+}
+/** Resolves one default size edge while retaining its incumbent side inside the ±10% band. */
+export function resolveStickySizeEdge(sizePx, threshold, previous) {
+    if (!Number.isFinite(sizePx) || sizePx === null || sizePx < 0)
+        return 'below';
+    if (previous === 'below') {
+        return sizePx >= stickyEnterSizePx(threshold) ? 'above' : 'below';
+    }
+    if (previous === 'above') {
+        return sizePx <= threshold - threshold * SIZE_HYSTERESIS_RATIO ? 'below' : 'above';
+    }
+    return sizePx >= threshold ? 'above' : 'below';
+}

package/dist/esm/components/Maplibre/utils/venue-pin-rasterize.d.ts

@@ -0,0 +1,88 @@
+import { Box } from '@expofp/geometry';
+import type { FpPathMesh, GetFpPathMesh } from './venue-contour';
+/**
+ * Rasterization of an authored venue pin layer (KTD-5): the designer's plan
+ * layer artwork is serialized to a standalone SVG, rasterized through an
+ * `<img>` (the outdoor-POI `loadImage` → canvas → `map.addImage` pipeline),
+ * and rendered as a screen-fixed MapLibre symbol at the artwork's resolved
+ * bottom-center anchor. Pure helpers and the DOM/canvas path are unit-tested.
+ *
+ * The layer's SVG is fpsync2's compiled output, not the authored drawing: a
+ * vector shape survives only as a `<path data-index>` stub carrying its fill,
+ * with the geometry moved to the layer's mesh table (strokes already outlined
+ * into meshes of their own). The rasterizer rebuilds each stub's `d` from its
+ * mesh before decoding, and leaves everything else — `<image>` children in
+ * particular — to the `<img>` pipeline as authored.
+ */
+/** CSS width of a rasterized venue pin icon (the POI markers use 42). */
+export declare const VENUE_PIN_WIDTH_PX = 42;
+/**
+ * Icon pixel size for artwork with the given plan-local bounds, scaled to the
+ * target width with the aspect ratio preserved. Null for degenerate bounds.
+ */
+export declare function venuePinIconSize(bounds: Box, targetWidthPx: number): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * SVG path data tracing a triangulated mesh's outline: its triangles are wound
+ * one way, every edge two of them share cancels, and what is left — the
+ * boundary — is chained into closed loops. Under the default nonzero fill the
+ * loops paint exactly the triangles' union (the winding number is a sum over
+ * edges, so a hole's loop runs the other way and stays empty), but with no
+ * interior edge for anti-aliasing to leave a hairline seam along — which
+ * painting triangles one at a time does, visibly so at 42 px. Null when the
+ * mesh draws nothing.
+ */
+export declare function meshPathData(mesh: FpPathMesh | undefined): string | null;
+/**
+ * A copy of a compiled layer group whose `<path data-index>` stubs carry their
+ * mesh geometry again, plus the plan-space extent of those meshes (null when
+ * the layer has none — an image-only layer). Rebuilt paths paint their fill
+ * only: the mesh is already the shape's whole appearance, outlined strokes
+ * included, and its coordinates are final plan coordinates, so a leftover
+ * stroke or transform on the stub would draw it twice or move it. Paths
+ * without a mesh, and every other element, are kept as they are.
+ */
+export declare function restoreMeshPaths(group: Element, getMesh: GetFpPathMesh): {
+    group: Element;
+    meshBounds: Box | null;
+};
+/**
+ * The plan-space frame to rasterize: the layer rect grown to the meshes'
+ * extent. The rect is computed without stroke, so an outlined stroke pokes
+ * past it; the meshes alone are never the frame, because an image-only layer
+ * has none.
+ */
+export declare function venuePinFrame(bounds: Box, meshBounds: Box | null): Box;
+/** Whether a bitmap draws anything: at least one pixel with non-zero alpha. */
+export declare function hasOpaquePixel(rgba: Uint8ClampedArray): boolean;
+/** A rasterized pin and where the symbol must shift it to stay anchored. */
+export interface VenuePinRaster {
+    canvas: HTMLCanvasElement;
+    /**
+     * `icon-offset` (CSS px, for `icon-anchor: bottom`) that puts the rect's
+     * bottom-center — the venue anchor (§6) — back on the map point once the
+     * frame grew past the rect. `[0, 0]` when the frame is the rect.
+     */
+    iconOffset: [number, number];
+}
+/**
+ * Wraps serialized plan-layer markup in a standalone SVG document whose
+ * viewBox is the artwork's plan-local bounds, so the group's own coordinates
+ * render unchanged. Class-driven fills are already inlined as style attributes
+ * by the plan SVG parser (data/svg.ts), so no stylesheet needs embedding.
+ */
+export declare function buildStandaloneSvg(groupMarkup: string, bounds: Box, width: number, height: number): string;
+/**
+ * Rasterizes an authored pin layer's SVG group to a canvas sized for a
+ * screen-fixed marker icon (at `pixelRatio` density; register with
+ * `map.addImage(..., { pixelRatio })` to restore the CSS size). The rect sets
+ * the scale — its width maps to `targetWidthPx` — and the frame grows past it
+ * where meshes do (see {@link venuePinFrame}). Resolves null when the bounds
+ * are degenerate or the browser fails to decode the SVG — the caller keeps
+ * the procedural pin rather than throwing. A successful decode can still be
+ * blank; checking the pixels is the caller's job, since it reads them anyway.
+ */
+export declare function rasterizeVenuePinLayer(group: Element, bounds: Box, targetWidthPx: number, pixelRatio: number, getMesh: GetFpPathMesh): Promise<VenuePinRaster | null>;
+//# sourceMappingURL=venue-pin-rasterize.d.ts.map