@osm-editor-kit/osm-way-chain 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,39 @@
+# `@osm-editor-kit/osm-way-chain`
+
+**Status:** First npm **alpha** (`0.1.0-alpha.0`). Publish with `bun run packages:release -- --publish-only` after `npm login`.
+
+## What it does
+
+Bidirectional OSM way-chain traversal for lane editors: walk connected highway ways from a center segment, score neighbor candidates (same kind, name, ref), surface ambiguous junctions, and orient geometry plus directional tags when a way is reversed.
+
+Includes `mirrorTags` for flipping digitization direction (left/right, forward/backward, oneway, lane pipes, placement), road-like highway predicates (`public` vs `inclusive` inclusion style, Overpass selectors), and a session adapter over in-memory `ParsedOsmData` from `@osm-editor-kit/osm-data`.
+
+## Usage
+
+```ts
+import type { ParsedOsmData } from '@osm-editor-kit/osm-data'
+import {
+  buildChain,
+  createSessionGraphAdapter,
+  isEditableRoadLikeSegment,
+  overpassRoadLikeSelector,
+} from '@osm-editor-kit/osm-way-chain'
+
+const graph: ParsedOsmData = /* loaded viewport data */
+const adapter = createSessionGraphAdapter(graph)
+
+const { chain, pendingJunctions } = await buildChain(adapter, {
+  centerWayId: 123456,
+  maxPerSide: 5,
+  candidateFilter: (candidate, from) =>
+    isEditableRoadLikeSegment(candidate) && isEditableRoadLikeSegment(from),
+})
+
+// chain.segments: predecessors, center, successors (ordered)
+// pendingJunctions: nodes where multiple equally good neighbors need a user pick
+
+// Overpass fragment for lane-mode downloads:
+overpassRoadLikeSelector('public')
+```
+
+Implement `OsmDataAdapter` (`getWay`, `getWaysForNode`) for other data sources. Use `extendChainAtJunction` and `recenterChain` to continue after resolving a junction choice.

package/dist/domain/types.d.ts

@@ -0,0 +1,23 @@
+import type { LineString } from 'geojson';
+export type OsmTags = Record<string, string>;
+export type Segment = {
+    id: number;
+    version: number;
+    nodeIds: number[];
+    tags: OsmTags;
+    geometry: LineString;
+    /** True when geometry direction was flipped relative to chain traversal */
+    reversed?: boolean;
+};
+export type SegmentChain = {
+    /** Ordered segments: predecessors (left), center, successors (right) */
+    segments: Segment[];
+    /** Index of the reference/center segment */
+    centerIndex: number;
+};
+export type JunctionChoice = {
+    nodeId: number;
+    direction: 'backward' | 'forward';
+    candidates: Segment[];
+};
+export type NeighborDirection = 'backward' | 'forward';

package/dist/highway-filter.d.ts

@@ -0,0 +1,30 @@
+import type { OsmTags } from '@osm-editor-kit/osm-data';
+import type { Segment } from './domain/types';
+/**
+ * Base highway values used for lane-mode street chain traversal.
+ * Link variants (`*_link`) and `highway=busway` are handled separately.
+ */
+export declare const ROAD_LIKE_HIGHWAY_BASE_REGEX: RegExp;
+/**
+ * How broadly the editor includes low-priority access roads in the map.
+ *
+ * - `public` (default): skip private access, driveways, emergency access, and parking aisles
+ * - `inclusive`: include those ways (previous editor behavior)
+ */
+export type HighwayInclusionStyle = 'public' | 'inclusive';
+export declare const DEFAULT_HIGHWAY_INCLUSION_STYLE: HighwayInclusionStyle;
+export declare const OVERPASS_PUBLIC_ROAD_FILTERS = "[service!=emergency_access][service!=parking_aisle][service!=driveway][access!=private]";
+/** Overpass selector for road-like ways under the given inclusion style. */
+export declare function overpassRoadLikeSelector(style?: HighwayInclusionStyle): string;
+/** Ways that are usually noise in street-space editing (private driveways, etc.). */
+export declare function isClutterAccessWay(tags: OsmTags): boolean;
+/** Whether a way should be shown/edited under the chosen inclusion style. */
+export declare function matchesHighwayInclusionStyle(tags: OsmTags, style?: HighwayInclusionStyle): boolean;
+/** Whether OSM tags describe a road-like highway suitable for lane-mode chaining. */
+export declare function isRoadLikeHighway(tags: OsmTags): boolean;
+/** Road-like highways that pass the active inclusion style. */
+export declare function isEditableRoadLikeHighway(tags: OsmTags, style?: HighwayInclusionStyle): boolean;
+/** Segment-level predicate for `buildChain` / `filterNeighborCandidates`. */
+export declare function isRoadLikeSegment(segment: Segment): boolean;
+/** Segment-level predicate that also applies the editor inclusion style. */
+export declare function isEditableRoadLikeSegment(segment: Segment, style?: HighwayInclusionStyle): boolean;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { JunctionChoice, NeighborDirection, OsmTags, Segment, SegmentChain, } from './domain/types';
+export { DEFAULT_HIGHWAY_INCLUSION_STYLE, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, overpassRoadLikeSelector, ROAD_LIKE_HIGHWAY_BASE_REGEX, OVERPASS_PUBLIC_ROAD_FILTERS, type HighwayInclusionStyle, } from './highway-filter';
+export type { OsmDataAdapter } from './ports/OsmDataAdapter';
+export { createSessionGraphAdapter, osmWayToSegment } from './session-graph-adapter';
+export { buildChain, extendChainAtJunction, getOtherEndpointNodeId, getSharedNodeBetween, recenterChain, type BuildChainOptions, type BuildChainResult, } from './traversal/buildChain';
+export { isReversedAtNode, normalizeTagsForDirection, orientNeighbor, swapLeftRightKey, } from './traversal/direction';
+export { mirrorTags } from './traversal/mirror-tags';
+export { type CandidateFilter, filterNeighborCandidates, getEndpointNodeId, getKindKey, pickBestNeighbor, sameKind, scoreNeighborCandidate, } from './traversal/neighborMatch';

package/dist/index.js

@@ -0,0 +1,399 @@
+// src/highway-filter.ts
+var ROAD_LIKE_HIGHWAY_BASE_REGEX = /^motorway|trunk|primary|secondary|tertiary|unclassified|residential|living_street|service/;
+var DEFAULT_HIGHWAY_INCLUSION_STYLE = "public";
+var CLUTTER_SERVICE_VALUES = /* @__PURE__ */ new Set(["driveway", "emergency_access", "parking_aisle"]);
+var OVERPASS_PUBLIC_ROAD_FILTERS = "[service!=emergency_access][service!=parking_aisle][service!=driveway][access!=private]";
+function overpassRoadLikeSelector(style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
+  const base = 'highway~"^motorway|trunk|primary|secondary|tertiary|unclassified|residential|service|living_street"';
+  if (style === "inclusive") return base;
+  return base + OVERPASS_PUBLIC_ROAD_FILTERS;
+}
+function isClutterAccessWay(tags) {
+  if (tags.access === "private") return true;
+  const service = tags.service;
+  return service != null && CLUTTER_SERVICE_VALUES.has(service);
+}
+function matchesHighwayInclusionStyle(tags, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
+  if (style === "inclusive") return true;
+  return !isClutterAccessWay(tags);
+}
+function isRoadLikeHighway(tags) {
+  const highway = tags.highway;
+  if (!highway) return false;
+  if (highway === "busway") return true;
+  const base = highway.endsWith("_link") ? highway.slice(0, -"_link".length) : highway;
+  return ROAD_LIKE_HIGHWAY_BASE_REGEX.test(base);
+}
+function isEditableRoadLikeHighway(tags, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
+  return isRoadLikeHighway(tags) && matchesHighwayInclusionStyle(tags, style);
+}
+function isRoadLikeSegment(segment) {
+  return isRoadLikeHighway(segment.tags);
+}
+function isEditableRoadLikeSegment(segment, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
+  return isEditableRoadLikeHighway(segment.tags, style);
+}
+
+// src/session-graph-adapter.ts
+function wayCoordinates(way, nodeCoords) {
+  return way.nodes.map((nodeId) => {
+    const coord = nodeCoords[nodeId];
+    if (!coord) return null;
+    return [coord[1], coord[0]];
+  }).filter((coord) => coord != null);
+}
+function osmWayToSegment(way, nodeCoords) {
+  return {
+    id: way.id,
+    version: way.version,
+    nodeIds: way.nodes,
+    tags: way.tags,
+    geometry: {
+      type: "LineString",
+      coordinates: wayCoordinates(way, nodeCoords)
+    }
+  };
+}
+function buildNodeWayIndex(graph) {
+  const index = /* @__PURE__ */ new Map();
+  for (const way of Object.values(graph.ways)) {
+    for (const nodeId of way.nodes) {
+      const existing = index.get(nodeId);
+      if (existing) {
+        existing.push(way.id);
+      } else {
+        index.set(nodeId, [way.id]);
+      }
+    }
+  }
+  return index;
+}
+function createSessionGraphAdapter(graph) {
+  const nodeWayIndex = buildNodeWayIndex(graph);
+  const segmentCache = /* @__PURE__ */ new Map();
+  function getSegment(wayId) {
+    const cached = segmentCache.get(wayId);
+    if (cached) return cached;
+    const way = graph.ways[wayId];
+    if (!way) throw new Error(`Way ${wayId} not found in session graph`);
+    const segment = osmWayToSegment(way, graph.nodeCoords);
+    segmentCache.set(wayId, segment);
+    return segment;
+  }
+  return {
+    getWay: (wayId) => Promise.resolve(getSegment(wayId)),
+    getWaysForNode: (nodeId) => {
+      const wayIds = nodeWayIndex.get(nodeId) ?? [];
+      return Promise.resolve(wayIds.map(getSegment));
+    }
+  };
+}
+
+// src/traversal/mirror-tags.ts
+var LEFT_RIGHT_RE = /:(left|right)(:|$)/g;
+var FORWARD_BACKWARD_RE = /:(forward|backward)(:|$)/g;
+var START_END_RE = /:(start|end)(:|$)/g;
+var ONEWAY_FORWARD = /* @__PURE__ */ new Set(["yes", "true", "1"]);
+var ONEWAY_REVERSE = /* @__PURE__ */ new Set(["-1", "reverse"]);
+var TURN_SWAP = {
+  left: "right",
+  right: "left",
+  slight_left: "slight_right",
+  slight_right: "slight_left",
+  sharp_left: "sharp_right",
+  sharp_right: "sharp_left",
+  merge_to_left: "merge_to_right",
+  merge_to_right: "merge_to_left"
+};
+var PLACEMENT_RE = /^(left_of|right_of|middle_of):(\d+)$/i;
+function mirrorDirectionalKey(key) {
+  return key.replace(LEFT_RIGHT_RE, (_match, side, suffix) => {
+    const swapped = side === "left" ? "right" : "left";
+    return `:${swapped}${suffix}`;
+  }).replace(FORWARD_BACKWARD_RE, (_match, dir, suffix) => {
+    const swapped = dir === "forward" ? "backward" : "forward";
+    return `:${swapped}${suffix}`;
+  }).replace(START_END_RE, (_match, pos, suffix) => {
+    const swapped = pos === "start" ? "end" : "start";
+    return `:${swapped}${suffix}`;
+  });
+}
+function isOnewayKey(key) {
+  const lower = key.toLowerCase();
+  return lower === "oneway" || lower.startsWith("oneway:");
+}
+function mirrorOnewayValue(value) {
+  const lower = value.trim().toLowerCase();
+  if (ONEWAY_FORWARD.has(lower)) return "-1";
+  if (ONEWAY_REVERSE.has(lower)) return "yes";
+  return value;
+}
+function isLanesPipeKey(key) {
+  return key.toLowerCase().includes(":lanes");
+}
+function mirrorTurnPart(part) {
+  const lower = part.trim().toLowerCase();
+  return TURN_SWAP[lower] ?? part;
+}
+function mirrorTurnToken(token) {
+  return token.split(";").map((part) => mirrorTurnPart(part)).join(";");
+}
+function mirrorChangeToken(token) {
+  const lower = token.trim().toLowerCase();
+  if (lower === "not_left") return "not_right";
+  if (lower === "not_right") return "not_left";
+  return token;
+}
+function mirrorLanesPipeValue(key, value) {
+  const lowerKey = key.toLowerCase();
+  const tokens = value.split("|");
+  const reversed = [...tokens].reverse();
+  if (lowerKey.includes("turn:lanes")) {
+    return reversed.map(mirrorTurnToken).join("|");
+  }
+  if (lowerKey.includes("change:lanes")) {
+    return reversed.map(mirrorChangeToken).join("|");
+  }
+  return reversed.join("|");
+}
+function mirrorBareSideValue(value) {
+  const lower = value.trim().toLowerCase();
+  if (lower === "left") return "right";
+  if (lower === "right") return "left";
+  return value;
+}
+function parsePositiveInt(value) {
+  if (value == null || value === "") return void 0;
+  const n = Number.parseInt(value.trim(), 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+function laneCountForPlacement(tags) {
+  const lanes = parsePositiveInt(tags.lanes);
+  if (lanes != null) return lanes;
+  const fwd = parsePositiveInt(tags["lanes:forward"]) ?? 0;
+  const back = parsePositiveInt(tags["lanes:backward"]) ?? 0;
+  const both = parsePositiveInt(tags["lanes:both_ways"]) ?? 0;
+  const sum = fwd + back + both;
+  return sum > 0 ? sum : 0;
+}
+function mirrorPlacementValue(value, laneCount) {
+  const trimmed = value.trim().toLowerCase();
+  if (trimmed === "transition") return value;
+  const match = PLACEMENT_RE.exec(trimmed);
+  if (!match) return value;
+  const kind = match[1].toLowerCase();
+  const lane = Number.parseInt(match[2], 10);
+  if (!Number.isInteger(lane) || lane < 1) return value;
+  const total = laneCount > 0 ? laneCount : lane;
+  const mirroredLane = total + 1 - lane;
+  if (kind === "left_of") return `right_of:${mirroredLane}`;
+  if (kind === "right_of") return `left_of:${mirroredLane}`;
+  if (kind === "middle_of") return `middle_of:${mirroredLane}`;
+  return value;
+}
+function isPlacementKey(key) {
+  const lower = key.toLowerCase();
+  return lower === "placement" || lower.startsWith("placement:");
+}
+function isBareSideKey(key) {
+  const lower = key.toLowerCase();
+  return lower === "sidewalk" || lower === "cycleway" || lower === "busway";
+}
+function mirrorTagValue(key, value, tags, laneCount) {
+  if (isOnewayKey(key)) return mirrorOnewayValue(value);
+  if (isPlacementKey(key)) return mirrorPlacementValue(value, laneCount);
+  if (isBareSideKey(key)) return mirrorBareSideValue(value);
+  if (isLanesPipeKey(key)) return mirrorLanesPipeValue(key, value);
+  return value;
+}
+function mirrorTags(tags) {
+  const laneCount = laneCountForPlacement(tags);
+  const mirrored = {};
+  for (const [key, value] of Object.entries(tags)) {
+    const mirroredKey = mirrorDirectionalKey(key);
+    mirrored[mirroredKey] = mirrorTagValue(key, value, tags, laneCount);
+  }
+  return mirrored;
+}
+
+// src/traversal/direction.ts
+var LEFT_RIGHT_RE2 = /:(left|right)(:|$)/;
+function isReversedAtNode(current, neighbor, sharedNodeId) {
+  const currentEnd = current.nodeIds[current.nodeIds.length - 1] === sharedNodeId ? "end" : "start";
+  const neighborEnd = neighbor.nodeIds[neighbor.nodeIds.length - 1] === sharedNodeId ? "end" : "start";
+  return currentEnd === neighborEnd;
+}
+function swapLeftRightKey(key) {
+  return key.replace(LEFT_RIGHT_RE2, (_match, side, suffix) => {
+    const swapped = side === "left" ? "right" : "left";
+    return `:${swapped}${suffix}`;
+  });
+}
+function normalizeTagsForDirection(tags, reversed) {
+  if (!reversed) return tags;
+  return mirrorTags(tags);
+}
+function orientNeighbor(neighbor, sharedNodeId, fromSegment) {
+  const reversed = isReversedAtNode(fromSegment, neighbor, sharedNodeId);
+  if (!reversed) return { ...neighbor, reversed: false };
+  const reversedNodeIds = [...neighbor.nodeIds].reverse();
+  const reversedCoords = [...neighbor.geometry.coordinates].reverse();
+  return {
+    ...neighbor,
+    nodeIds: reversedNodeIds,
+    geometry: {
+      type: "LineString",
+      coordinates: reversedCoords
+    },
+    tags: normalizeTagsForDirection(neighbor.tags, true),
+    reversed: true
+  };
+}
+
+// src/traversal/neighborMatch.ts
+var KIND_KEYS = ["highway", "cycleway", "footway", "path", "railway", "waterway"];
+function getKindKey(tags) {
+  for (const key of KIND_KEYS) {
+    if (tags[key]) return { key, value: tags[key] };
+  }
+  return void 0;
+}
+function sameKind(a, b) {
+  const kindA = getKindKey(a.tags);
+  const kindB = getKindKey(b.tags);
+  if (!kindA || !kindB) return false;
+  return kindA.key === kindB.key && kindA.value === kindB.value;
+}
+function getEndpointNodeId(segment, direction) {
+  const { nodeIds } = segment;
+  return direction === "forward" ? nodeIds[nodeIds.length - 1] : nodeIds[0];
+}
+function getOtherEndpointNodeId(segment, sharedNodeId) {
+  const first = segment.nodeIds[0];
+  const last = segment.nodeIds[segment.nodeIds.length - 1];
+  if (first === sharedNodeId) return last;
+  if (last === sharedNodeId) return first;
+  return void 0;
+}
+function filterNeighborCandidates(from, candidates, direction, candidateFilter) {
+  const endpoint = getEndpointNodeId(from, direction);
+  const touching = candidates.filter((c) => {
+    if (c.id === from.id) return false;
+    if (candidateFilter && !candidateFilter(c)) return false;
+    const first = c.nodeIds[0];
+    const last = c.nodeIds[c.nodeIds.length - 1];
+    return first === endpoint || last === endpoint;
+  });
+  const sameKindMatches = touching.filter((c) => sameKind(from, c));
+  if (sameKindMatches.length > 0) return sameKindMatches;
+  return touching;
+}
+function scoreNeighborCandidate(from, candidate) {
+  let score = 0;
+  if (sameKind(from, candidate)) score += 100;
+  if (candidate.tags.name && candidate.tags.name === from.tags.name) score += 50;
+  if (candidate.tags.ref && candidate.tags.ref === from.tags.ref) score += 30;
+  return score;
+}
+function pickBestNeighbor(from, candidates) {
+  if (candidates.length === 0) return void 0;
+  if (candidates.length === 1) return candidates[0];
+  const scored = candidates.map((c) => ({ segment: c, score: scoreNeighborCandidate(from, c) })).sort((a, b) => b.score - a.score);
+  const top = scored[0];
+  const second = scored[1];
+  if (top.score === second.score && top.score < 100) return void 0;
+  return top.segment;
+}
+
+// src/traversal/buildChain.ts
+var DEFAULT_MAX_PER_SIDE = 5;
+async function loadSegment(adapter, id, cache) {
+  const cached = cache.get(id);
+  if (cached) return cached;
+  const segment = await adapter.getWay(id);
+  cache.set(id, segment);
+  return segment;
+}
+async function extendChain(adapter, cache, start, direction, maxCount, candidateFilter) {
+  const extension = [];
+  const pendingJunctions = [];
+  let current = start;
+  for (let i = 0; i < maxCount; i++) {
+    const endpoint = getEndpointNodeId(current, direction);
+    const rawNeighbors = await adapter.getWaysForNode(endpoint);
+    const candidates = filterNeighborCandidates(current, rawNeighbors, direction, candidateFilter);
+    const best = pickBestNeighbor(current, candidates);
+    if (!best) {
+      if (candidates.length > 1) {
+        pendingJunctions.push({ nodeId: endpoint, direction, candidates });
+      }
+      break;
+    }
+    const fullBest = await loadSegment(adapter, best.id, cache);
+    const oriented = orientNeighbor(fullBest, endpoint, current);
+    extension.push(oriented);
+    current = oriented;
+  }
+  return { extension, pendingJunctions };
+}
+async function buildChain(adapter, options) {
+  const cache = new Map(options.knownSegments ?? []);
+  const maxPerSide = options.maxPerSide ?? DEFAULT_MAX_PER_SIDE;
+  const { candidateFilter } = options;
+  const center = await loadSegment(adapter, options.centerWayId, cache);
+  const [backwardResult, forwardResult] = await Promise.all([
+    extendChain(adapter, cache, center, "backward", maxPerSide, candidateFilter),
+    extendChain(adapter, cache, center, "forward", maxPerSide, candidateFilter)
+  ]);
+  const segments = [...backwardResult.extension.reverse(), center, ...forwardResult.extension];
+  return {
+    chain: {
+      segments,
+      centerIndex: backwardResult.extension.length
+    },
+    pendingJunctions: [...backwardResult.pendingJunctions, ...forwardResult.pendingJunctions]
+  };
+}
+async function extendChainAtJunction(adapter, chain, choice, selectedWayId, maxCount = DEFAULT_MAX_PER_SIDE, candidateFilter) {
+  const cache = new Map(chain.segments.map((s) => [s.id, s]));
+  const selected = cache.get(selectedWayId) ?? await adapter.getWay(selectedWayId);
+  cache.set(selected.id, selected);
+  const anchorIndex = choice.direction === "forward" ? chain.segments.length - 1 : 0;
+  const anchor = chain.segments[anchorIndex];
+  const oriented = orientNeighbor(selected, choice.nodeId, anchor);
+  const { extension, pendingJunctions } = await extendChain(
+    adapter,
+    cache,
+    oriented,
+    choice.direction,
+    maxCount,
+    candidateFilter
+  );
+  let segments;
+  if (choice.direction === "forward") {
+    segments = [...chain.segments, oriented, ...extension];
+  } else {
+    segments = [...extension.reverse(), oriented, ...chain.segments];
+  }
+  return {
+    chain: {
+      segments,
+      centerIndex: chain.centerIndex + (choice.direction === "backward" ? extension.length + 1 : 0)
+    },
+    pendingJunctions
+  };
+}
+function recenterChain(chain, newCenterWayId) {
+  const index = chain.segments.findIndex((s) => s.id === newCenterWayId);
+  if (index === -1) return chain;
+  return { segments: chain.segments, centerIndex: index };
+}
+function getSharedNodeBetween(a, b) {
+  const aEnds = /* @__PURE__ */ new Set([a.nodeIds[0], a.nodeIds[a.nodeIds.length - 1]]);
+  for (const nodeId of [b.nodeIds[0], b.nodeIds[b.nodeIds.length - 1]]) {
+    if (aEnds.has(nodeId)) return nodeId;
+  }
+  return void 0;
+}
+
+export { DEFAULT_HIGHWAY_INCLUSION_STYLE, OVERPASS_PUBLIC_ROAD_FILTERS, ROAD_LIKE_HIGHWAY_BASE_REGEX, buildChain, createSessionGraphAdapter, extendChainAtJunction, filterNeighborCandidates, getEndpointNodeId, getKindKey, getOtherEndpointNodeId, getSharedNodeBetween, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isReversedAtNode, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, mirrorTags, normalizeTagsForDirection, orientNeighbor, osmWayToSegment, overpassRoadLikeSelector, pickBestNeighbor, recenterChain, sameKind, scoreNeighborCandidate, swapLeftRightKey };

package/dist/ports/OsmDataAdapter.d.ts

@@ -0,0 +1,5 @@
+import type { Segment } from '../domain/types';
+export type OsmDataAdapter = {
+    getWay: (wayId: number) => Promise<Segment>;
+    getWaysForNode: (nodeId: number) => Promise<Segment[]>;
+};

package/dist/session-graph-adapter.d.ts

@@ -0,0 +1,9 @@
+import type { OsmWay, ParsedOsmData } from '@osm-editor-kit/osm-data';
+import type { Segment } from './domain/types';
+import type { OsmDataAdapter } from './ports/OsmDataAdapter';
+export declare function osmWayToSegment(way: OsmWay, nodeCoords: ParsedOsmData['nodeCoords']): Segment;
+/**
+ * Adapter backed by an already-loaded session graph (bbox coverage data).
+ * Lookups are synchronous but wrapped in Promises to satisfy `OsmDataAdapter`.
+ */
+export declare function createSessionGraphAdapter(graph: ParsedOsmData): OsmDataAdapter;

package/dist/traversal/buildChain.d.ts

@@ -0,0 +1,20 @@
+import type { JunctionChoice, Segment, SegmentChain } from '../domain/types';
+import type { OsmDataAdapter } from '../ports/OsmDataAdapter';
+import { type CandidateFilter, getOtherEndpointNodeId } from './neighborMatch';
+export type BuildChainOptions = {
+    centerWayId: number;
+    maxPerSide?: number;
+    /** Already loaded segments keyed by id */
+    knownSegments?: Map<number, Segment>;
+    /** Optional predicate to restrict neighbor candidates (e.g. road-like highways) */
+    candidateFilter?: CandidateFilter;
+};
+export type BuildChainResult = {
+    chain: SegmentChain;
+    pendingJunctions: JunctionChoice[];
+};
+export declare function buildChain(adapter: OsmDataAdapter, options: BuildChainOptions): Promise<BuildChainResult>;
+export declare function extendChainAtJunction(adapter: OsmDataAdapter, chain: SegmentChain, choice: JunctionChoice, selectedWayId: number, maxCount?: number, candidateFilter?: CandidateFilter): Promise<BuildChainResult>;
+export declare function recenterChain(chain: SegmentChain, newCenterWayId: number): SegmentChain;
+export declare function getSharedNodeBetween(a: Segment, b: Segment): number | undefined;
+export { getOtherEndpointNodeId };

package/dist/traversal/direction.d.ts

@@ -0,0 +1,5 @@
+import type { Segment } from '../domain/types';
+export declare function isReversedAtNode(current: Segment, neighbor: Segment, sharedNodeId: number): boolean;
+export declare function swapLeftRightKey(key: string): string;
+export declare function normalizeTagsForDirection(tags: Segment['tags'], reversed: boolean): import("..").OsmTags;
+export declare function orientNeighbor(neighbor: Segment, sharedNodeId: number, fromSegment: Segment): Segment;

package/dist/traversal/mirror-tags.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Mirror OSM tags as if the way were digitised in the opposite direction.
+ * Applying twice returns the original tags (deep equality).
+ */
+export declare function mirrorTags(tags: Record<string, string>): Record<string, string>;

package/dist/traversal/neighborMatch.d.ts

@@ -0,0 +1,14 @@
+import type { NeighborDirection, Segment } from '../domain/types';
+export type CandidateFilter = (segment: Segment) => boolean;
+export declare function getKindKey(tags: Segment['tags']): {
+    key: "cycleway" | "footway" | "highway" | "path" | "railway" | "waterway";
+    value: string;
+} | undefined;
+export declare function sameKind(a: Segment, b: Segment): boolean;
+export declare function getEndpointNodeId(segment: Segment, direction: NeighborDirection): number;
+export declare function getOtherEndpointNodeId(segment: Segment, sharedNodeId: number): number | undefined;
+/** Filter candidates at a junction: exclude self, prefer same kind */
+export declare function filterNeighborCandidates(from: Segment, candidates: Segment[], direction: NeighborDirection, candidateFilter?: CandidateFilter): Segment[];
+/** Score candidate for auto-follow (higher = better) */
+export declare function scoreNeighborCandidate(from: Segment, candidate: Segment): number;
+export declare function pickBestNeighbor(from: Segment, candidates: Segment[]): Segment | undefined;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@osm-editor-kit/osm-way-chain",
+  "version": "0.1.0-alpha.0",
+  "description": "Traverse and orient connected OSM highway ways for multi-segment editing sessions.",
+  "license": "MIT",
+  "author": "Tobias Jordans",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osmberlin/street-space-editor.git",
+    "directory": "packages/osm-way-chain"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsup && rm -f .tsbuildinfo && tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "test-run": "bun test src/test",
+    "prepublishOnly": "bun run build && bun ../../scripts/package-exports-for-publish.ts",
+    "postpublish": "bun ../../scripts/package-exports-restore.ts",
+    "prepack": "bun ../../scripts/package-exports-for-publish.ts",
+    "postpack": "bun ../../scripts/package-exports-restore.ts"
+  },
+  "dependencies": {
+    "@osm-editor-kit/osm-data": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/geojson": "^7946.0.16",
+    "bun-types": "^1.2.20",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.0"
+  },
+  "publishExports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}