@osm-editor-kit/osm-way-chain 0.1.0-alpha.3 → 1.0.0

package/README.md

@@ -1,16 +1,26 @@
 # `@osm-editor-kit/osm-way-chain`
 
+Walk connected OSM ways from a center way and orient them into one chain, for editors that change several segments of a street at once.
+
 > [!NOTE]
-> This package is an **alpha** release and still under active development. APIs may change; install with the npm `alpha` dist-tag.
+> Claude Opus 5.5 wrote and reviewed the code of this package. [@tordans](https://github.com/tordans) specified what it should do and tested and verified its user-facing behavior.
+
+## Install
+
+```bash
+npm install @osm-editor-kit/osm-way-chain
+```
+
+It depends on `@osm-editor-kit/osm-data`, which npm installs for you.
 
 ## What it does
 
-- Walk connected highway ways left and right from a center segment
-- Rank neighbor candidates (same road kind, name, ref)
-- Flag junctions where more than one neighbor is equally good
-- Flip geometry and directional tags when a way is digitized the “wrong” way
-- Compile and match **app-owned** way-selection policies (Overpass + in-memory tags)
-- Adapter for in-memory session data from `@osm-editor-kit/osm-data`
+- Walks connected ways left and right from a center way
+- Ranks neighbor candidates (same kind of road, name, ref)
+- Reports junctions where more than one neighbor is equally good, so the user can choose
+- Flips geometry and directional tags when a way is digitized the "wrong" way (`mirrorTags`)
+- Compiles app-owned way-selection policies to Overpass queries and matches them against in-memory tags
+- Reads from an in-memory `ParsedOsmData` session (`createSessionGraphAdapter`) or any data source that implements `OsmDataAdapter`
 
 ## Usage
 
@@ -25,7 +35,7 @@ import {
   type OsmWaySelectionPolicy,
 } from '@osm-editor-kit/osm-way-chain'
 
-/** App-owned contract — which ways to download / chain. Not package defaults. */
+// App-owned contract: which ways to download and chain. The package has no defaults.
 const wayPolicy: OsmWaySelectionPolicy = {
   include: [
     { all: [tag.oneOf('highway', ['residential', 'cycleway', 'path', 'footway', 'steps'])] },
@@ -39,15 +49,53 @@ const adapter = createSessionGraphAdapter(graph)
 const { chain, pendingJunctions } = await buildChain(adapter, {
   centerWayId: 123456,
   maxPerSide: 5,
-  candidateFilter: (candidate, from) =>
-    matchesOsmWaySelectionSegment(candidate, wayPolicy) &&
-    matchesOsmWaySelectionSegment(from, wayPolicy),
+  candidateFilter: (candidate) => matchesOsmWaySelectionSegment(candidate, wayPolicy),
 })
 
-// Overpass download for the same policy:
-buildWaysOverpassQuery(wayPolicy, '52.5,13.4,52.51,13.41')
+// Overpass query that downloads the same ways for a bbox (south,west,north,east):
+const query = buildWaysOverpassQuery(wayPolicy, '52.5,13.4,52.51,13.41')
+```
+
+`buildChain` returns the ordered `chain.segments`, the index of the center way in `chain.centerIndex`, and `pendingJunctions` for places where it could not pick a neighbor.
+
+## Junctions
+
+When a junction has several equally good neighbors, `buildChain` stops there and lists them in `pendingJunctions`. Let the user pick one, then continue with `extendChainAtJunction(adapter, chain, choice, selectedWayId, { maxPerSide, candidateFilter })`. Use `recenterChain(chain, wayId)` to move the center to another way in the chain without reloading; it returns the chain unchanged when the way is not part of it.
+
+## Way-selection policies
+
+A policy is a list of `include` clauses (OR), each a list of tag predicates (AND), plus optional `globalAll` predicates added to every clause. Build predicates with `tag.eq`, `tag.neq`, `tag.oneOf`, `tag.noneOf`, `tag.regex`, `tag.nregex`, `tag.present` and `tag.absent`. `compileOverpassWaySelectors` returns one Overpass filter per clause, `matchesOsmWaySelection` tests in-memory tags. A missing tag matches `neq`, `noneOf`, `nregex` and `absent`, as in Overpass.
+
+`tag.regex` and `tag.nregex` patterns run as JavaScript `RegExp` in memory but go to Overpass unchanged, where they are POSIX extended regular expressions. Use only syntax both understand: anchors, groups, `|`, `[...]`, `*`, `+`, `?`, `{n,m}`. `\d`, `(?:...)`, lookarounds and lazy quantifiers behave differently or fail in Overpass.
+
+## Helpers
+
+- `mirrorTags(tags)` returns the tags as if the way were digitized the other way round (left/right, forward/backward, `oneway`, `*:lanes`, `placement`). `normalizeTagsForDirection(tags, reversed)` applies it only when `reversed`; `swapLeftRightKey(key)` swaps one key.
+- `orientNeighbor(neighbor, sharedNodeId, from)` flips a neighbor so it runs in the direction of `from`.
+- `getSharedNodeBetween(a, b)`, `getEndpointNodeId(segment, direction)` and `getOtherEndpointNodeId(segment, nodeId)` read way endpoints.
+- `osmWayToSegment(way, nodeCoords)` turns an `OsmWay` from `@osm-editor-kit/osm-data` into a `Segment`.
+
+## Other data sources
+
+Implement `OsmDataAdapter` to chain ways from somewhere other than a loaded session:
+
+```ts
+import type { OsmDataAdapter, Segment } from '@osm-editor-kit/osm-way-chain'
+
+const waysById = new Map<number, Segment>() // fill from your own source
+
+const adapter: OsmDataAdapter = {
+  getWay: async (wayId) => {
+    const way = waysById.get(wayId)
+    if (!way) throw new Error(`Way ${wayId} not found`)
+    return way
+  },
+  // All ways that use this node
+  getWaysForNode: async (nodeId) =>
+    [...waysById.values()].filter((way) => way.nodeIds.includes(nodeId)),
+}
 ```
 
-Implement `OsmDataAdapter` (`getWay`, `getWaysForNode`) for other data sources. Use `extendChainAtJunction` and `recenterChain` to continue after resolving a junction choice.
+## License
 
-Legacy `overpassRoadLikeSelector` / `HighwayInclusionStyle` helpers remain as deprecated shims for street-space-editor.
+MIT

package/dist/domain/types.d.ts

@@ -1,23 +1,26 @@
+import type { OsmTags } from '@osm-editor-kit/osm-data';
 import type { LineString } from 'geojson';
-export type OsmTags = Record<string, string>;
+/** Walking direction along a way: `forward` follows its node order, `backward` goes against it. */
+export type NeighborDirection = 'backward' | 'forward';
+/** One OSM way as a chain member. */
 export type Segment = {
     id: number;
     version: number;
     nodeIds: number[];
     tags: OsmTags;
     geometry: LineString;
-    /** True when geometry direction was flipped relative to chain traversal */
+    /** True when node order, geometry and directional tags were flipped to match the chain direction */
     reversed?: boolean;
 };
 export type SegmentChain = {
     /** Ordered segments: predecessors (left), center, successors (right) */
     segments: Segment[];
-    /** Index of the reference/center segment */
+    /** Index of the center segment in `segments` */
     centerIndex: number;
 };
+/** A junction where several neighbors are equally good; the user picks one of `candidates`. */
 export type JunctionChoice = {
     nodeId: number;
-    direction: 'backward' | 'forward';
+    direction: NeighborDirection;
     candidates: Segment[];
 };
-export type NeighborDirection = 'backward' | 'forward';

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export type { JunctionChoice, NeighborDirection, OsmTags, Segment, SegmentChain, } from './domain/types';
-export { createLegacyStreetRoadWayPolicy, 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 { buildWaysOverpassQuery, compileOverpassWaySelector, compileOverpassWaySelectors, matchesOsmWaySelection, matchesOsmWaySelectionSegment, tag, type OsmTagPredicate, type OsmWayFilterClause, type OsmWaySelectionPolicy, } from './way-selection-policy';
+export type { JunctionChoice, NeighborDirection, Segment, SegmentChain } from './domain/types';
 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 { buildChain, extendChainAtJunction, recenterChain, type BuildChainOptions, type BuildChainResult, type ExtendChainAtJunctionOptions, } from './traversal/buildChain';
+export type { CandidateFilter } from './traversal/neighborMatch';
+export { getEndpointNodeId, getOtherEndpointNodeId, getSharedNodeBetween, } from './traversal/endpoints';
+export { normalizeTagsForDirection, orientNeighbor, swapLeftRightKey } from './traversal/direction';
 export { mirrorTags } from './traversal/mirror-tags';
-export { type CandidateFilter, filterNeighborCandidates, getEndpointNodeId, getKindKey, pickBestNeighbor, sameKind, scoreNeighborCandidate, } from './traversal/neighborMatch';
+export { buildWaysOverpassQuery, compileOverpassWaySelector, compileOverpassWaySelectors, matchesOsmWaySelection, matchesOsmWaySelectionSegment, tag, type OsmTagPredicate, type OsmWayFilterClause, type OsmWaySelectionPolicy, } from './way-selection-policy';

package/dist/index.js

@@ -1,155 +1,3 @@
-// src/way-selection-policy.ts
-var tag = {
-  eq: (key, value) => ({ key, op: "eq", value }),
-  neq: (key, value) => ({ key, op: "neq", value }),
-  oneOf: (key, values) => ({
-    key,
-    op: "in",
-    values
-  }),
-  noneOf: (key, values) => ({
-    key,
-    op: "nin",
-    values
-  }),
-  regex: (key, pattern) => ({ key, op: "regex", pattern }),
-  nregex: (key, pattern) => ({ key, op: "nregex", pattern }),
-  present: (key) => ({ key, op: "present" }),
-  absent: (key) => ({ key, op: "absent" })
-};
-function escapeRegexAlternation(values) {
-  return values.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
-}
-function quoteOverpassValue(value) {
-  if (/^[A-Za-z0-9_:-]+$/.test(value)) return value;
-  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-function escapeOverpassRegex(pattern) {
-  return pattern.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-function compileTagPredicate(predicate) {
-  switch (predicate.op) {
-    case "eq":
-      return `[${predicate.key}=${quoteOverpassValue(predicate.value)}]`;
-    case "neq":
-      return `[${predicate.key}!=${quoteOverpassValue(predicate.value)}]`;
-    case "in":
-      return `[${predicate.key}~"^(${escapeRegexAlternation(predicate.values)})$"]`;
-    case "nin":
-      return `[${predicate.key}!~"^(${escapeRegexAlternation(predicate.values)})$"]`;
-    case "regex":
-      return `[${predicate.key}~"${escapeOverpassRegex(predicate.pattern)}"]`;
-    case "nregex":
-      return `[${predicate.key}!~"${escapeOverpassRegex(predicate.pattern)}"]`;
-    case "present":
-      return `[${predicate.key}]`;
-    case "absent":
-      return `[!${predicate.key}]`;
-  }
-}
-function clausePredicates(policy, clause) {
-  return [...clause.all, ...policy.globalAll ?? []];
-}
-function compileOverpassWaySelectors(policy) {
-  if (policy.include.length === 0) {
-    throw new Error("OsmWaySelectionPolicy.include must contain at least one clause");
-  }
-  return policy.include.map(
-    (clause) => clausePredicates(policy, clause).map(compileTagPredicate).join("")
-  );
-}
-function compileOverpassWaySelector(policy) {
-  const selectors = compileOverpassWaySelectors(policy);
-  if (selectors.length !== 1) {
-    throw new Error(
-      `compileOverpassWaySelector expects exactly one include clause, got ${selectors.length}`
-    );
-  }
-  return selectors[0];
-}
-function matchesTagPredicate(tags, predicate) {
-  const raw = tags[predicate.key];
-  switch (predicate.op) {
-    case "eq":
-      return raw === predicate.value;
-    case "neq":
-      return raw !== predicate.value;
-    case "in":
-      return raw != null && predicate.values.includes(raw);
-    case "nin":
-      return raw == null || !predicate.values.includes(raw);
-    case "regex":
-      return raw != null && new RegExp(predicate.pattern).test(raw);
-    case "nregex":
-      return raw == null || !new RegExp(predicate.pattern).test(raw);
-    case "present":
-      return raw != null && raw !== "";
-    case "absent":
-      return raw == null || raw === "";
-  }
-}
-function matchesClause(tags, predicates) {
-  return predicates.every((predicate) => matchesTagPredicate(tags, predicate));
-}
-function matchesOsmWaySelection(tags, policy) {
-  return policy.include.some((clause) => matchesClause(tags, clausePredicates(policy, clause)));
-}
-function matchesOsmWaySelectionSegment(segment, policy) {
-  return matchesOsmWaySelection(segment.tags, policy);
-}
-function buildWaysOverpassQuery(policy, bbox, options) {
-  const selectors = compileOverpassWaySelectors(policy);
-  const timeout = options?.timeoutSeconds ?? 60;
-  const out = options?.out ?? "meta";
-  const union = selectors.map((selector) => `way${selector}(${bbox});`).join("");
-  return `[out:xml][timeout:${timeout}];(${union});(._;>;);out ${out};`;
-}
-
-// src/highway-filter.ts
-var DEFAULT_HIGHWAY_INCLUSION_STYLE = "public";
-function createLegacyStreetRoadWayPolicy(style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
-  const highway = tag.regex(
-    "highway",
-    "^(motorway|trunk|primary|secondary|tertiary|unclassified|residential|living_street|service)(_link)?$|^busway$"
-  );
-  if (style === "inclusive") {
-    return { include: [{ all: [highway] }] };
-  }
-  return {
-    include: [{ all: [highway] }],
-    globalAll: [
-      tag.neq("access", "private"),
-      tag.noneOf("service", ["emergency_access", "parking_aisle", "driveway"])
-    ]
-  };
-}
-var ROAD_LIKE_HIGHWAY_BASE_REGEX = /^motorway|trunk|primary|secondary|tertiary|unclassified|residential|living_street|service/;
-var OVERPASS_PUBLIC_ROAD_FILTERS = "[service!=emergency_access][service!=parking_aisle][service!=driveway][access!=private]";
-function overpassRoadLikeSelector(style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
-  return compileOverpassWaySelector(createLegacyStreetRoadWayPolicy(style)).slice(1);
-}
-function isClutterAccessWay(tags) {
-  if (tags.access === "private") return true;
-  const service = tags.service;
-  return service === "driveway" || service === "emergency_access" || service === "parking_aisle";
-}
-function matchesHighwayInclusionStyle(tags, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
-  if (style === "inclusive") return true;
-  return !isClutterAccessWay(tags);
-}
-function isRoadLikeHighway(tags) {
-  return matchesOsmWaySelection(tags, createLegacyStreetRoadWayPolicy("inclusive"));
-}
-function isEditableRoadLikeHighway(tags, style = DEFAULT_HIGHWAY_INCLUSION_STYLE) {
-  return matchesOsmWaySelection(tags, createLegacyStreetRoadWayPolicy(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) => {
@@ -315,7 +163,7 @@ function isBareSideKey(key) {
   const lower = key.toLowerCase();
   return lower === "sidewalk" || lower === "cycleway" || lower === "busway";
 }
-function mirrorTagValue(key, value, tags, laneCount) {
+function mirrorTagValue(key, value, laneCount) {
   if (isOnewayKey(key)) return mirrorOnewayValue(value);
   if (isPlacementKey(key)) return mirrorPlacementValue(value, laneCount);
   if (isBareSideKey(key)) return mirrorBareSideValue(value);
@@ -327,7 +175,7 @@ function mirrorTags(tags) {
   const mirrored = {};
   for (const [key, value] of Object.entries(tags)) {
     const mirroredKey = mirrorDirectionalKey(key);
-    mirrored[mirroredKey] = mirrorTagValue(key, value, tags, laneCount);
+    mirrored[mirroredKey] = mirrorTagValue(key, value, laneCount);
   }
   return mirrored;
 }
@@ -352,25 +200,44 @@ function normalizeTagsForDirection(tags, reversed) {
 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,
+    nodeIds: [...neighbor.nodeIds].reverse(),
     geometry: {
       type: "LineString",
-      coordinates: reversedCoords
+      coordinates: [...neighbor.geometry.coordinates].reverse()
     },
-    tags: normalizeTagsForDirection(neighbor.tags, true),
+    tags: mirrorTags(neighbor.tags),
     reversed: true
   };
 }
 
+// src/traversal/endpoints.ts
+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 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 (nodeId != null && aEnds.has(nodeId)) return nodeId;
+  }
+  return void 0;
+}
+
 // 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] };
+    const value = tags[key];
+    if (value) return { key, value };
   }
   return void 0;
 }
@@ -380,17 +247,6 @@ function sameKind(a, b) {
   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) => {
@@ -470,10 +326,10 @@ async function buildChain(adapter, options) {
     pendingJunctions: [...backwardResult.pendingJunctions, ...forwardResult.pendingJunctions]
   };
 }
-async function extendChainAtJunction(adapter, chain, choice, selectedWayId, maxCount = DEFAULT_MAX_PER_SIDE, candidateFilter) {
+async function extendChainAtJunction(adapter, chain, choice, selectedWayId, options = {}) {
+  const maxPerSide = options.maxPerSide ?? DEFAULT_MAX_PER_SIDE;
   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 selected = await loadSegment(adapter, selectedWayId, cache);
   const anchorIndex = choice.direction === "forward" ? chain.segments.length - 1 : 0;
   const anchor = chain.segments[anchorIndex];
   const oriented = orientNeighbor(selected, choice.nodeId, anchor);
@@ -482,15 +338,10 @@ async function extendChainAtJunction(adapter, chain, choice, selectedWayId, maxC
     cache,
     oriented,
     choice.direction,
-    maxCount,
-    candidateFilter
+    maxPerSide,
+    options.candidateFilter
   );
-  let segments;
-  if (choice.direction === "forward") {
-    segments = [...chain.segments, oriented, ...extension];
-  } else {
-    segments = [...extension.reverse(), oriented, ...chain.segments];
-  }
+  const segments = choice.direction === "forward" ? [...chain.segments, oriented, ...extension] : [...extension.reverse(), oriented, ...chain.segments];
   return {
     chain: {
       segments,
@@ -504,12 +355,121 @@ function recenterChain(chain, 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;
+
+// src/way-selection-policy.ts
+var tag = {
+  eq: (key, value) => ({ key, op: "eq", value }),
+  neq: (key, value) => ({ key, op: "neq", value }),
+  oneOf: (key, values) => ({
+    key,
+    op: "in",
+    values
+  }),
+  noneOf: (key, values) => ({
+    key,
+    op: "nin",
+    values
+  }),
+  regex: (key, pattern) => ({ key, op: "regex", pattern }),
+  nregex: (key, pattern) => ({ key, op: "nregex", pattern }),
+  present: (key) => ({ key, op: "present" }),
+  absent: (key) => ({ key, op: "absent" })
+};
+function escapeRegexAlternation(values) {
+  return values.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+}
+function quoteOverpassValue(value) {
+  if (/^[A-Za-z0-9_:-]+$/.test(value)) return value;
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function escapeOverpassRegex(pattern) {
+  return pattern.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function compileTagPredicate(predicate) {
+  switch (predicate.op) {
+    case "eq":
+      return `[${predicate.key}=${quoteOverpassValue(predicate.value)}]`;
+    case "neq":
+      return `[${predicate.key}!=${quoteOverpassValue(predicate.value)}]`;
+    case "in":
+      return `[${predicate.key}~"^(${escapeRegexAlternation(predicate.values)})$"]`;
+    case "nin":
+      return `[${predicate.key}!~"^(${escapeRegexAlternation(predicate.values)})$"]`;
+    case "regex":
+      return `[${predicate.key}~"${escapeOverpassRegex(predicate.pattern)}"]`;
+    case "nregex":
+      return `[${predicate.key}!~"${escapeOverpassRegex(predicate.pattern)}"]`;
+    case "present":
+      return `[${predicate.key}]`;
+    case "absent":
+      return `[!${predicate.key}]`;
   }
-  return void 0;
+}
+function clausePredicates(policy, clause) {
+  return [...clause.all, ...policy.globalAll ?? []];
+}
+function compileOverpassWaySelectors(policy) {
+  if (policy.include.length === 0) {
+    throw new Error("OsmWaySelectionPolicy.include must contain at least one clause");
+  }
+  return policy.include.map(
+    (clause) => clausePredicates(policy, clause).map(compileTagPredicate).join("")
+  );
+}
+function compileOverpassWaySelector(policy) {
+  const selectors = compileOverpassWaySelectors(policy);
+  if (selectors.length !== 1) {
+    throw new Error(
+      `compileOverpassWaySelector expects exactly one include clause, got ${selectors.length}`
+    );
+  }
+  return selectors[0];
+}
+var regexCache = /* @__PURE__ */ new Map();
+function cachedRegex(pattern) {
+  let regex = regexCache.get(pattern);
+  if (!regex) {
+    regex = new RegExp(pattern);
+    regexCache.set(pattern, regex);
+  }
+  return regex;
+}
+function matchesTagPredicate(tags, predicate) {
+  const raw = tags[predicate.key];
+  switch (predicate.op) {
+    case "eq":
+      return raw === predicate.value;
+    case "neq":
+      return raw !== predicate.value;
+    case "in":
+      return raw != null && predicate.values.includes(raw);
+    case "nin":
+      return raw == null || !predicate.values.includes(raw);
+    case "regex":
+      return raw != null && cachedRegex(predicate.pattern).test(raw);
+    case "nregex":
+      return raw == null || !cachedRegex(predicate.pattern).test(raw);
+    case "present":
+      return raw != null && raw !== "";
+    case "absent":
+      return raw == null || raw === "";
+  }
+}
+function matchesClause(tags, predicates) {
+  return predicates.every((predicate) => matchesTagPredicate(tags, predicate));
+}
+function matchesOsmWaySelection(tags, policy) {
+  return policy.include.some((clause) => matchesClause(tags, clausePredicates(policy, clause)));
+}
+function matchesOsmWaySelectionSegment(segment, policy) {
+  return matchesOsmWaySelection(segment.tags, policy);
+}
+function buildWaysOverpassQuery(policy, bbox, options) {
+  const selectors = compileOverpassWaySelectors(policy);
+  const timeout = options?.timeoutSeconds ?? 60;
+  const out = options?.out ?? "meta";
+  const union = selectors.map((selector) => `way${selector}(${bbox});`).join("");
+  return `[out:xml][timeout:${timeout}];(${union});(._;>;);out ${out};`;
 }
 
-export { DEFAULT_HIGHWAY_INCLUSION_STYLE, OVERPASS_PUBLIC_ROAD_FILTERS, ROAD_LIKE_HIGHWAY_BASE_REGEX, buildChain, buildWaysOverpassQuery, compileOverpassWaySelector, compileOverpassWaySelectors, createLegacyStreetRoadWayPolicy, createSessionGraphAdapter, extendChainAtJunction, filterNeighborCandidates, getEndpointNodeId, getKindKey, getOtherEndpointNodeId, getSharedNodeBetween, isClutterAccessWay, isEditableRoadLikeHighway, isEditableRoadLikeSegment, isReversedAtNode, isRoadLikeHighway, isRoadLikeSegment, matchesHighwayInclusionStyle, matchesOsmWaySelection, matchesOsmWaySelectionSegment, mirrorTags, normalizeTagsForDirection, orientNeighbor, osmWayToSegment, overpassRoadLikeSelector, pickBestNeighbor, recenterChain, sameKind, scoreNeighborCandidate, swapLeftRightKey, tag };
+export { buildChain, buildWaysOverpassQuery, compileOverpassWaySelector, compileOverpassWaySelectors, createSessionGraphAdapter, extendChainAtJunction, getEndpointNodeId, getOtherEndpointNodeId, getSharedNodeBetween, matchesOsmWaySelection, matchesOsmWaySelectionSegment, mirrorTags, normalizeTagsForDirection, orientNeighbor, osmWayToSegment, recenterChain, swapLeftRightKey, tag };

package/dist/ports/OsmDataAdapter.d.ts

@@ -1,5 +1,8 @@
 import type { Segment } from '../domain/types';
+/** Data source for chain building. */
 export type OsmDataAdapter = {
+    /** Rejects when the way is unknown. */
     getWay: (wayId: number) => Promise<Segment>;
+    /** All ways that use this node, at any position. */
     getWaysForNode: (nodeId: number) => Promise<Segment[]>;
 };

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

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

package/dist/traversal/buildChain.d.ts

@@ -1,20 +1,38 @@
 import type { JunctionChoice, Segment, SegmentChain } from '../domain/types';
 import type { OsmDataAdapter } from '../ports/OsmDataAdapter';
-import { type CandidateFilter, getOtherEndpointNodeId } from './neighborMatch';
+import { type CandidateFilter } from './neighborMatch';
 export type BuildChainOptions = {
     centerWayId: number;
+    /** Maximum number of ways to add on each side of the center. Default 5. */
     maxPerSide?: number;
-    /** Already loaded segments keyed by id */
+    /** Already loaded segments keyed by id; skips `adapter.getWay` for these. */
     knownSegments?: Map<number, Segment>;
-    /** Optional predicate to restrict neighbor candidates (e.g. road-like highways) */
+    /** Restricts which ways may join the chain. */
+    candidateFilter?: CandidateFilter;
+};
+export type ExtendChainAtJunctionOptions = {
+    /** Maximum number of ways to add after the selected way. Default 5. */
+    maxPerSide?: number;
+    /** Restricts which ways may join the chain. */
     candidateFilter?: CandidateFilter;
 };
 export type BuildChainResult = {
     chain: SegmentChain;
     pendingJunctions: JunctionChoice[];
 };
+/**
+ * Walks connected ways backward and forward from `centerWayId` and orients them into one chain.
+ * Stops on each side at `maxPerSide`, at a dead end, or at a junction it cannot decide
+ * (reported in `pendingJunctions`).
+ */
 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>;
+/**
+ * Continues `chain` at a pending junction with the way the user picked, then keeps walking
+ * in the junction's direction. The center way stays the same.
+ */
+export declare function extendChainAtJunction(adapter: OsmDataAdapter, chain: SegmentChain, choice: JunctionChoice, selectedWayId: number, options?: ExtendChainAtJunctionOptions): Promise<BuildChainResult>;
+/**
+ * Moves the center to `newCenterWayId` without reloading.
+ * Returns `chain` itself, unchanged, when the way is not part of the chain.
+ */
 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

@@ -1,5 +1,13 @@
+import type { OsmTags } from '@osm-editor-kit/osm-data';
 import type { Segment } from '../domain/types';
+/** True when both segments start (or both end) at `sharedNodeId`, so one runs against the other. */
 export declare function isReversedAtNode(current: Segment, neighbor: Segment, sharedNodeId: number): boolean;
+/** Swaps the first `:left` / `:right` part of a tag key, e.g. `cycleway:left:surface`. */
 export declare function swapLeftRightKey(key: string): string;
-export declare function normalizeTagsForDirection(tags: Segment['tags'], reversed: boolean): import("..").OsmTags;
+/** `mirrorTags(tags)` when `reversed`, otherwise `tags` itself. */
+export declare function normalizeTagsForDirection(tags: OsmTags, reversed: boolean): OsmTags;
+/**
+ * Re-expresses `neighbor` in the direction of `fromSegment`: when they run against each other
+ * at `sharedNodeId`, node order, geometry and directional tags are flipped and `reversed` is set.
+ */
 export declare function orientNeighbor(neighbor: Segment, sharedNodeId: number, fromSegment: Segment): Segment;

package/dist/traversal/endpoints.d.ts

@@ -0,0 +1,7 @@
+import type { NeighborDirection, Segment } from '../domain/types';
+/** Last node for `forward`, first node for `backward`. */
+export declare function getEndpointNodeId(segment: Segment, direction: NeighborDirection): number;
+/** The endpoint opposite `sharedNodeId`, or `undefined` when `sharedNodeId` is not an endpoint. */
+export declare function getOtherEndpointNodeId(segment: Segment, sharedNodeId: number): number | undefined;
+/** The node where the endpoints of `a` and `b` meet, or `undefined` when they do not touch. */
+export declare function getSharedNodeBetween(a: Segment, b: Segment): number | undefined;

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

@@ -1,5 +1,6 @@
+import type { OsmTags } from '@osm-editor-kit/osm-data';
 /**
  * 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>;
+export declare function mirrorTags(tags: OsmTags): OsmTags;

package/dist/traversal/neighborMatch.d.ts

@@ -1,14 +1,14 @@
 import type { NeighborDirection, Segment } from '../domain/types';
+/** Restricts which ways may join a chain. */
 export type CandidateFilter = (segment: Segment) => boolean;
 export declare function getKindKey(tags: Segment['tags']): {
-    key: "cycleway" | "footway" | "highway" | "path" | "railway" | "waterway";
+    key: string;
     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 */
+/** Ways that start or end at `from`'s endpoint in `direction`; same-kind ways win if there are any. */
 export declare function filterNeighborCandidates(from: Segment, candidates: Segment[], direction: NeighborDirection, candidateFilter?: CandidateFilter): Segment[];
-/** Score candidate for auto-follow (higher = better) */
+/** Score for auto-follow (higher = better) */
 export declare function scoreNeighborCandidate(from: Segment, candidate: Segment): number;
+/** The neighbor to follow, or `undefined` when there is none or the top two tie below same kind. */
 export declare function pickBestNeighbor(from: Segment, candidates: Segment[]): Segment | undefined;

package/dist/way-selection-policy.d.ts

@@ -1,9 +1,13 @@
 import type { OsmTags } from '@osm-editor-kit/osm-data';
 import type { Segment } from './domain/types';
 /**
- * Atomic tag predicate. Compiles 1:1 to Overpass filter syntax and the same
- * semantics when matching in-memory `OsmTags` (missing tag matches `neq` / `nin`
- * / `absent`, same as Overpass).
+ * Atomic tag predicate. Compiles 1:1 to an Overpass tag filter and matches in-memory `OsmTags`
+ * the same way: a missing tag matches `neq`, `nin`, `nregex` and `absent`.
+ *
+ * `regex` / `nregex` patterns run as JavaScript `RegExp` in memory but go to Overpass unchanged,
+ * where they are POSIX extended regular expressions. Use only syntax both understand (anchors,
+ * groups, `|`, `[...]`, `*`, `+`, `?`, `{n,m}`); `\d`, `(?:...)`, lookarounds or lazy quantifiers
+ * will differ or fail in Overpass.
  */
 export type OsmTagPredicate = {
     readonly key: string;
@@ -56,6 +60,7 @@ export declare function compileOverpassWaySelectors(policy: OsmWaySelectionPolic
 export declare function compileOverpassWaySelector(policy: OsmWaySelectionPolicy): string;
 /** Whether OSM tags match the policy (OR of include clauses, each with globalAll). */
 export declare function matchesOsmWaySelection(tags: OsmTags, policy: OsmWaySelectionPolicy): boolean;
+/** {@link matchesOsmWaySelection} for a segment's tags, e.g. as a `candidateFilter`. */
 export declare function matchesOsmWaySelectionSegment(segment: Segment, policy: OsmWaySelectionPolicy): boolean;
 /** Builds Overpass QL that downloads matching ways (+ their nodes) for a bbox string. */
 export declare function buildWaysOverpassQuery(policy: OsmWaySelectionPolicy, bbox: string, options?: {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@osm-editor-kit/osm-way-chain",
-  "version": "0.1.0-alpha.3",
+  "version": "1.0.0",
   "description": "Traverse and orient connected OSM highway ways for multi-segment editing sessions.",
-  "homepage": "https://github.com/osmberlin/street-space-editor/tree/main/packages/osm-way-chain",
+  "homepage": "https://github.com/osm-editor-kit/street-space-editor/tree/main/packages/osm-way-chain",
   "license": "MIT",
   "author": "Tobias Jordans",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/osmberlin/street-space-editor.git",
+    "url": "git+https://github.com/osm-editor-kit/street-space-editor.git",
     "directory": "packages/osm-way-chain"
   },
   "files": [
@@ -23,8 +23,7 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   },
   "scripts": {
     "build": "tsup && rm -f .tsbuildinfo && tsc -p tsconfig.build.json",
@@ -36,10 +35,10 @@
     "postpack": "bun ../../scripts/package-exports-restore.ts"
   },
   "dependencies": {
-    "@osm-editor-kit/osm-data": "^0.1.0-alpha.1"
+    "@osm-editor-kit/osm-data": "^1.0.0",
+    "@types/geojson": "^7946.0.16"
   },
   "devDependencies": {
-    "@types/geojson": "^7946.0.16",
     "bun-types": "^1.2.20",
     "tsup": "^8.5.1",
     "typescript": "^7.0.0"

package/dist/highway-filter.d.ts

@@ -1,36 +0,0 @@
-import type { OsmTags } from '@osm-editor-kit/osm-data';
-import type { Segment } from './domain/types';
-import { type OsmWaySelectionPolicy } from './way-selection-policy';
-/**
- * @deprecated App-owned concept. Prefer {@link OsmWaySelectionPolicy} defined in the app.
- * Kept temporarily for street-space-editor call sites.
- */
-export type HighwayInclusionStyle = 'public' | 'inclusive';
-/** @deprecated Prefer app-owned policies. */
-export declare const DEFAULT_HIGHWAY_INCLUSION_STYLE: HighwayInclusionStyle;
-/**
- * @deprecated Prefer app-owned {@link OsmWaySelectionPolicy}.
- * Legacy lane-mode car/road selection (incl. `*_link` and `busway`).
- */
-export declare function createLegacyStreetRoadWayPolicy(style?: HighwayInclusionStyle): OsmWaySelectionPolicy;
-/** @deprecated Prefer matching against an app policy. */
-export declare const ROAD_LIKE_HIGHWAY_BASE_REGEX: RegExp;
-/** @deprecated Prefer policy `globalAll`. */
-export declare const OVERPASS_PUBLIC_ROAD_FILTERS = "[service!=emergency_access][service!=parking_aisle][service!=driveway][access!=private]";
-/**
- * @deprecated Prefer {@link compileOverpassWaySelector} with an app policy.
- * Returns the legacy fragment expected by `way[${tag}]` callers (no leading `[`).
- */
-export declare function overpassRoadLikeSelector(style?: HighwayInclusionStyle): string;
-/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
-export declare function isClutterAccessWay(tags: OsmTags): boolean;
-/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
-export declare function matchesHighwayInclusionStyle(tags: OsmTags, style?: HighwayInclusionStyle): boolean;
-/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
-export declare function isRoadLikeHighway(tags: OsmTags): boolean;
-/** @deprecated Prefer app policy + {@link matchesOsmWaySelection}. */
-export declare function isEditableRoadLikeHighway(tags: OsmTags, style?: HighwayInclusionStyle): boolean;
-/** @deprecated Prefer app policy + {@link matchesOsmWaySelectionSegment}. */
-export declare function isRoadLikeSegment(segment: Segment): boolean;
-/** @deprecated Prefer app policy + {@link matchesOsmWaySelectionSegment}. */
-export declare function isEditableRoadLikeSegment(segment: Segment, style?: HighwayInclusionStyle): boolean;