@tilda-geo/bicycle-infrastructure 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,15 @@
1
+ # ISC License
2
+
3
+ Copyright (c) 2026 FixMyCity GmbH
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
package/NOTICE.md ADDED
@@ -0,0 +1,13 @@
1
+ # Notice: where the code comes from
2
+
3
+ The bicycle infrastructure logic of `@tilda-geo/bicycle-infrastructure` is a TypeScript port of the
4
+ LUA processing of [tilda-geo](https://github.com/FixMyBerlin/tilda-geo)
5
+ (`processing/topics/roads_bikelanes`). tilda-geo is licensed under the
6
+ [AGPL-3.0](https://github.com/FixMyBerlin/tilda-geo/blob/develop/LICENSE).
7
+
8
+ FixMyCity GmbH holds the rights to tilda-geo and to this repository. As the rights holder it
9
+ publishes the ported logic here under the ISC license. tilda-geo itself stays under the AGPL-3.0;
10
+ this notice does not change its license.
11
+
12
+ The tagging logic of `@tilda-geo/bicycle-infrastructure-tagging` comes from the iD Radnetz editor of
13
+ FixMyCity GmbH (ISC), and its German labels from the topic docs of tilda-geo.
package/README.md CHANGED
@@ -19,6 +19,8 @@ npm install @tilda-geo/bicycle-infrastructure
19
19
  3. Returns **1..N features** (centerline `self` plus transformed `left`/`right` sides), each with:
20
20
  - **`category`** — `Radinfrastrukturkategorie` (primary focus; see [`schemas/bicycle-infrastructure-category`](../../schemas/bicycle-infrastructure-category/))
21
21
  - plus surface, smoothness, oneway, separation / buffer / marking, traffic_mode, traffic_sign, surface_color, width
22
+ - `_lineReversed` and `offset` (riding direction of the published line, follows tilda-geo-private#34, not merged yet)
23
+ - `todos` (what is missing or wrong in the tagging) and `todoTagFixes`
22
24
 
23
25
  Disallowed sanitizer values become `null`, matching TILDA’s GeoJSON export.
24
26
 
@@ -39,11 +41,11 @@ const features = processBikelanes({
39
41
 
40
42
  ## How it relates to the rest of the monorepo
41
43
 
42
- | Piece | Relationship |
43
- | --- | --- |
44
- | [`schemas/bicycle-infrastructure-category`](../../schemas/bicycle-infrastructure-category/) | Source of truth for allowed `category` values + fixtures |
45
- | [`schemas/bicycle-infrastructure-attributes`](../../schemas/bicycle-infrastructure-attributes/) | Draft vocabularies for non-category fields (fixtures used in tests) |
46
- | [`bicycle-infrastructure-reconciliation`](../bicycle-infrastructure-reconciliation/) | **Internal** tooling that proves this library ≡ TILDA LUA on a Berlin corpus |
44
+ | Piece | Relationship |
45
+ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
46
+ | [`schemas/bicycle-infrastructure-category`](../../schemas/bicycle-infrastructure-category/) | Source of truth for allowed `category` values + fixtures |
47
+ | [`schemas/bicycle-infrastructure-attributes`](../../schemas/bicycle-infrastructure-attributes/) | Draft vocabularies for non-category fields (fixtures used in tests) |
48
+ | [`bicycle-infrastructure-reconciliation`](../bicycle-infrastructure-reconciliation/) | **Internal** tooling that proves this library ≡ TILDA LUA on a Berlin corpus |
47
49
 
48
50
  ---
49
51
 
@@ -51,13 +53,14 @@ const features = processBikelanes({
51
53
 
52
54
  Ported module-for-module from `tilda-geo` → `processing/topics/roads_bikelanes`:
53
55
 
54
- | This package | LUA |
55
- | --- | --- |
56
- | `transform/prepare-tags.ts` | `helper/transform_tags/*` |
57
- | `transform/transformations.ts` | `bikelanes/transformations.lua` |
58
- | `categories/*` | `bikelanes/bikelane_categories.lua` (+ decision view, sidepath) |
59
- | `sanitize/*`, `derive/*` | `helper/sanitize_*`, `derive_*` |
60
- | `index.ts` → `processBikelanes` | `bikelanes/bikelanes.lua` |
56
+ | This package | LUA |
57
+ | ------------------------------- | --------------------------------------------------------------- |
58
+ | `transform/prepare-tags.ts` | `helper/transform_tags/*` |
59
+ | `transform/transformations.ts` | `bikelanes/transformations.lua` |
60
+ | `categories/*` | `bikelanes/bikelane_categories.lua` (+ decision view, sidepath) |
61
+ | `sanitize/*`, `derive/*` | `helper/sanitize_*`, `derive_*`, `bikelane_todo_categories.lua` |
62
+ | `helpers/parse-length.ts` | `helper/parse_length.lua`, `helper/parse_width.lua` |
63
+ | `index.ts` → `processBikelanes` | `bikelanes/bikelanes.lua` |
61
64
 
62
65
  ---
63
66
 
@@ -68,16 +71,18 @@ From the monorepo root:
68
71
  ```bash
69
72
  bun install
70
73
  bun run build
71
- bun run --filter '@tilda-geo/bicycle-infrastructure' test
74
+ bun run test-run
72
75
  bun run check-exports
73
76
  ```
74
77
 
75
78
  - `test/spec.test.ts` — conformance against `schemas/**/fixtures` (via `test/load-spec.ts`)
76
79
  - `test/categories.smoke.test.ts` — cases ported from LUA `__tests__`
77
80
 
81
+ Editor helpers (planner wrapper, required attributes, widths, extract and merge paths) are in [`@tilda-geo/bicycle-infrastructure-tagging`](../bicycle-infrastructure-tagging/). `planTagsForCategory` stays here because it needs the category specs; the tagging package depends on this one.
82
+
78
83
  Berlin corpus check (category agreement ~100%): see the **internal** [reconciliation](../bicycle-infrastructure-reconciliation/) package.
79
84
 
80
- Releases use [changesets](https://github.com/changesets/changesets) — see the root README **Release** section (manual publish, same as the smoothness packages).
85
+ Releases use [changesets](https://github.com/changesets/changesets), see [`.changeset/README.md`](../../.changeset/README.md) and the root README **Release** section.
81
86
 
82
87
  ---
83
88
 
@@ -85,3 +90,7 @@ Releases use [changesets](https://github.com/changesets/changesets) — see the
85
90
 
86
91
  - `_adjoining` / `_isolated` / `_adjoiningOrIsolated` use the raw OSM `is_sidepath` tag (same as LUA categorization). TILDA’s `_is_sidepath` CSV estimate is export-only and does not affect category.
87
92
  - `highway=construction` lifecycle is handled; the geometry crossing-length filter (>100 m) is skipped when `_length` is absent (typical for live Overpass tags).
93
+
94
+ ## License
95
+
96
+ [ISC](LICENSE.md), FixMyCity GmbH. The logic is ported from the LUA processing of tilda-geo (AGPL-3.0) by its rights holder, see [NOTICE.md](NOTICE.md).
package/dist/index.d.ts CHANGED
@@ -14,12 +14,19 @@ interface OsmTags {
14
14
  _length?: any;
15
15
  }
16
16
  type ImplicitOneWayConfidence = 'high' | 'medium' | 'low' | 'not_applicable';
17
+ /**
18
+ * How a bikelane category reads `surface:bicycle` (`BikelaneCategory.bicycleSurface` in LUA):
19
+ * `strip`: bicycles use a strip of a wide shared area; `whole_way`: the bikelane is a way of its own.
20
+ */
21
+ type BicycleSurface = 'strip' | 'whole_way';
17
22
  interface BikelaneCategory {
18
23
  id: string;
19
24
  infrastructureExists: boolean;
20
25
  implicitOneWay: boolean;
21
26
  implicitOneWayConfidence: ImplicitOneWayConfidence;
22
27
  copySurfaceSmoothnessFromParent: boolean;
28
+ /** How `surface:bicycle` applies, see `deriveBikelaneSurfaceTags`; undefined ignores it. */
29
+ bicycleSurface?: BicycleSurface;
23
30
  /** Receives a decision-view of the tags; returns truthy when the category matches. */
24
31
  condition: (tags: OsmTags) => boolean | undefined;
25
32
  /** Optional post-match mutation of the tags (mirrors LUA `process`). */
@@ -31,7 +38,19 @@ interface BikelaneResult {
31
38
  _prefix: string | null;
32
39
  _infrastructureExists: boolean;
33
40
  category: string;
41
+ /**
42
+ * `construction`, `construction_no_access`, `blocked` or `temporary`: the side's own lifecycle,
43
+ * else the one of its road. Only for features with infrastructure.
44
+ */
45
+ lifecycle?: string | null;
34
46
  oneway?: string;
47
+ /**
48
+ * Whether the published line runs against the OSM way (`_line_reversed` in LUA).
49
+ * follows tilda-geo-private#34 (not merged yet).
50
+ */
51
+ _lineReversed?: boolean;
52
+ /** Sideways offset in meters of left|right lanes, signed relative to the published line. */
53
+ offset?: number;
35
54
  surface?: string | null;
36
55
  surface_source?: string | null;
37
56
  surface_confidence?: string | null;
@@ -49,7 +68,134 @@ interface BikelaneResult {
49
68
  surface_color?: string | null;
50
69
  traffic_sign?: string | null;
51
70
  width?: number | null;
71
+ /**
72
+ * Ids of the todos that apply to the feature (`_todo_list` in LUA), see `BIKELANE_TODOS`.
73
+ * Only for features with infrastructure. Without the Mapillary, age and sidepath-CSV todos.
74
+ */
75
+ todos?: string[];
76
+ /** Proposed tag changes per todo id (`unset`: tags to remove), when a todo proposes one. */
77
+ todoTagFixes?: Record<string, {
78
+ unset: string[];
79
+ }>;
80
+ }
81
+
82
+ /** What the todo conditions read besides the transformed tags (LUA `result_tags`). */
83
+ interface BikelaneTodoResult {
84
+ category: string;
85
+ width?: number | null;
86
+ surface?: string | null;
87
+ surface_source?: string | null;
88
+ oneway?: string;
89
+ implicitOneWayConfidence: ImplicitOneWayConfidence;
90
+ }
91
+ /** Proposed tag change of a todo, for editors and MapRoulette Tag Fix tasks. */
92
+ interface TodoTagFix {
93
+ unset: string[];
94
+ }
95
+ interface BikelaneTodoDefinition {
96
+ id: string;
97
+ desc: string;
98
+ /** `true`: hidden from the inspector, only in the todo table. */
99
+ todoTableOnly: boolean;
100
+ condition: (tags: OsmTags, result: BikelaneTodoResult) => boolean;
101
+ tagFix?: (tags: OsmTags, result: BikelaneTodoResult) => TodoTagFix | undefined;
102
+ }
103
+ /**
104
+ * Port of is_unusual_width.lua: a `width` a human should look at. Not readable by `parseWidth`
105
+ * (`narrow`, `1-2`, `-1`, `0`), or above 50 m (published, but probably a typo). A check date on the
106
+ * way, on the road of a lane, or on the width itself closes the todo.
107
+ */
108
+ declare function isUnusualWidth(tags: OsmTags, result: Pick<BikelaneTodoResult, 'width'>): boolean;
109
+ /** In the order of `bikelane_todo_categories` in LUA. */
110
+ declare const BIKELANE_TODOS: readonly BikelaneTodoDefinition[];
111
+ interface BikelaneTodos {
112
+ /** Ids of the todos that apply, in the order of `BIKELANE_TODOS`. */
113
+ todos: string[];
114
+ /** Proposed tag changes per todo id; only set when a todo proposes one. */
115
+ todoTagFixes?: Record<string, TodoTagFix>;
52
116
  }
117
+ /**
118
+ * `tags` are the transformed tags after categorization (the category's `process` may have changed
119
+ * them), `result` what was derived for the feature.
120
+ */
121
+ declare function deriveBikelaneTodos(tags: OsmTags, result: BikelaneTodoResult): BikelaneTodos;
122
+
123
+ /** What the road todo conditions read besides the tags (LUA `result_tags`). */
124
+ interface RoadTodoResult {
125
+ /** `width` of the road, read by `parseWidth` */
126
+ width?: number | null;
127
+ /**
128
+ * `true` when the `self` bikelane row of the way has the todo `unusual_width` already
129
+ * (`_self_bikelane_has_unusual_width` in LUA): one todo per way.
130
+ */
131
+ selfBikelaneHasUnusualWidth?: boolean;
132
+ }
133
+ interface RoadTodoDefinition {
134
+ id: string;
135
+ desc: string;
136
+ /** `true`: hidden from the inspector, only in the todo table. */
137
+ todoTableOnly: boolean;
138
+ condition: (tags: OsmTags, result: RoadTodoResult) => boolean;
139
+ }
140
+ /** In the order of `road_todo_categories` in LUA (without `adjoining_of_vs_csv`). */
141
+ declare const ROAD_TODOS: readonly RoadTodoDefinition[];
142
+ /**
143
+ * The todos of a road (the way itself). `result.width` defaults to what `parseWidth` reads from
144
+ * `tags.width`, like the roads table does.
145
+ */
146
+ declare function deriveRoadTodos(tags: OsmTags, result?: RoadTodoResult): string[];
147
+
148
+ /**
149
+ * Port of osm2pgsql.split_unit + topics/helper/parse_length.lua + topics/helper/parse_width.lua
150
+ * (tilda-geo, state of 2026-11-04). One parser for every `width`, `buffer` and other length value.
151
+ */
152
+ /**
153
+ * Normalize a length to meters. Units `cm`, `m` and `km` are converted, every other unit
154
+ * (`mm`, `ft`, `in`, `mi`, ...) is `undefined`, like in LUA. A negative length is `undefined`;
155
+ * `0` is kept (`buffer=0` means no buffer). Use `parseWidth` when `0` makes no sense.
156
+ */
157
+ declare function parseLength(length: string | number | undefined | null): number | undefined;
158
+ /** Like `parseLength` for the width of a road or lane, where `0` can only be a mapping error. */
159
+ declare function parseWidth(width: string | number | undefined | null): number | undefined;
160
+
161
+ /** Port of topics/roads_bikelanes/helper/sanitize_road_tags.lua */
162
+
163
+ /**
164
+ * `separation` values that make a lane "protected" (`cyclewayOnHighwayProtected`), as in
165
+ * `bikelane_categories.lua`. Other allowed values (`kerb`, `greenery`, ...) do not.
166
+ */
167
+ declare const PROTECTIVE_SEPARATION: readonly ["bollard", "flex_post", "vertical_panel", "studs", "bump", "planter", "fence", "jersey_barrier", "guard_rail"];
168
+ declare const SEPARATION_ALLOWED: readonly ["no", "bollard", "flex_post", "vertical_panel", "studs", "bump", "planter", "kerb", "fence", "jersey_barrier", "guard_rail", "structure", "ditch", "greenery", "hedge", "tree_row", "cone", "kerb;parking_lane", "kerb;bollard", "yes"];
169
+ declare const MARKING_ALLOWED: readonly ["solid_line", "dashed_line", "double_solid_line", "barred_area", "pictogram", "surface"];
170
+ declare const TRAFFIC_MODE_ALLOWED: readonly ["no", "motor_vehicle", "parking", "psv", "bicycle", "foot"];
171
+ declare const SURFACE_COLOR_ALLOWED: readonly ["red", "green", "red;green", "no"];
172
+
173
+ /** Port of topics/helper/sanitize_tags.lua > `surface` */
174
+
175
+ declare const SURFACE_ALLOWED: readonly ["asphalt", "paved", "unpaved", "concrete", "concrete:plates", "concrete:lanes", "paving_stones", "paving_stones:lanes", "sett", "bricks", "stone", "ground", "grass", "sand", "compacted", "fine_gravel", "gravel", "pebblestone", "wood", "woodchips", "metal", "metal_grid", "plastic", "rubber", "grass_paver"];
176
+
177
+ /** Port of topics/roads_bikelanes/bikelanes/helper/derive_traffic_mode.lua */
178
+
179
+ /** Categories where `traffic_mode` is inferred from the road's `parking:<side>`, besides bicycle roads. */
180
+ declare const DIRECTIONAL_PARKING_INFERENCE_CATEGORIES: Set<string>;
181
+ declare const PARKING_ALLOWED: readonly ["no", "yes", "lane", "street_side", "on_kerb", "half_on_kerb", "shoulder", "separate"];
182
+
183
+ /**
184
+ * Port of topics/roads_bikelanes/bikelanes/derive_oneway.lua as in the tilda-geo branch
185
+ * `claude/tilda-oneway-processing-81b448` (follows tilda-geo-private#34, not merged yet).
186
+ * It replaces the `develop` version, which has no `-1`, no line direction and no side defaults.
187
+ *
188
+ * OSM `oneway` values are relative to the drawing direction of the way:
189
+ * `yes` (or `1`) flows with the way, `-1` against it, `no` in both directions.
190
+ * https://wiki.openstreetmap.org/wiki/Key:oneway
191
+ */
192
+
193
+ /**
194
+ * Whether bicycles ride against the drawing direction of the road on the `left`|`right` lane of
195
+ * `road` when the lane has no `cycleway:<side>:oneway` (the rules above, right-hand traffic).
196
+ * Exported so editors suggest the same direction the processing derives.
197
+ */
198
+ declare function defaultSideRunsAgainstWay(road: OsmTags, side: 'left' | 'right'): boolean;
53
199
 
54
200
  /** Port of topics/roads_bikelanes/bikelanes/bikelane_categories.lua — compiled from declarative specs. */
55
201
 
@@ -80,23 +226,36 @@ declare function analyzeCategoryGaps(wayTags: OsmTags, results: BikelaneResult[]
80
226
  * Plan OSM tag adds/changes to reach a target bikelane category.
81
227
  * Works in transformed tag space internally; returns nested OSM keys for left/right
82
228
  * cycleway (and sidewalk) sides, bare keys for self.
229
+ *
230
+ * The planner reads the same category specs the classifier uses. The match predicate of the
231
+ * target (and of its refining child, e.g. `_adjoining`) is expanded into alternatives: each
232
+ * alternative is a set of tags that is enough on its own (`segregated=yes` + `bicycle` + `foot`,
233
+ * or `traffic_sign=DE:241`). Every alternative becomes a candidate plan; the planner classifies the
234
+ * planned tags and keeps the cheapest candidate that gives the target.
83
235
  */
84
236
 
85
- interface TagPlanEntry {
237
+ /**
238
+ * Why a tag is planned: `reason` is an English sentence, `reasonCode` a stable code for apps that
239
+ * write their own text (for example `required_for_category`), `reasonParams` fills its placeholders.
240
+ * The codes are listed in `TAG_REASON_CODES`.
241
+ */
242
+ interface TagReason {
243
+ reason: string;
244
+ reasonCode: TagReasonCode;
245
+ reasonParams?: Record<string, string>;
246
+ }
247
+ interface TagPlanEntry extends TagReason {
86
248
  key: string;
87
249
  value: string;
88
- reason: string;
89
250
  }
90
- interface TagChangeEntry {
251
+ interface TagChangeEntry extends TagReason {
91
252
  key: string;
92
253
  from: string;
93
254
  to: string;
94
- reason: string;
95
255
  }
96
- interface TagConflictEntry {
256
+ interface TagConflictEntry extends TagReason {
97
257
  key: string;
98
258
  value: string;
99
- reason: string;
100
259
  }
101
260
  interface CategoryTagPlan {
102
261
  targetCategoryId: string;
@@ -104,23 +263,66 @@ interface CategoryTagPlan {
104
263
  aligned: boolean;
105
264
  add: TagPlanEntry[];
106
265
  change: TagChangeEntry[];
266
+ /** Keys to delete: `cycleway:both` (or `cycleway`) when a road side is split from the other */
267
+ remove: string[];
107
268
  conflicts: TagConflictEntry[];
108
269
  }
270
+ /**
271
+ * `default`: the cheapest plan, the one `planTagsForCategory` returns.
272
+ * `with_sign`: reaches the target with the traffic sign of the category (DE:240, DE:241, ...).
273
+ * `without_sign`: reaches the target with `traffic_sign=none` and the tags that say the same.
274
+ */
275
+ type CategoryTagPlanVariantId = 'default' | 'with_sign' | 'without_sign';
276
+ interface CategoryTagPlanVariant extends CategoryTagPlan {
277
+ variantId: CategoryTagPlanVariantId;
278
+ }
109
279
  interface ListTargetCategoriesOptions {
110
280
  /** Current category id — unlock candidates from its gapDiscriminators are listed first. */
111
281
  fromCategory?: string;
112
282
  /** When true with `fromCategory`, treat it as incomplete even if the id looks complete. */
113
283
  fromIncomplete?: boolean;
114
284
  }
285
+ /** The codes of `TagReason.reasonCode`; `{x}` names a parameter. */
286
+ declare const TAG_REASON_CODES: readonly ["required_for_category", "discriminator_for_category", "fixed_by_mapping_target", "bicycle_road", "bicycle_road_sign", "vehicle_destination", "bicycle_road_sign_vehicle_destination", "unsigned_cycleway", "unsigned_cycleway_no_sign", "footway_bicycles_allowed", "bicycle_allowed_on_footway", "footway_sign_bicycles_allowed", "on_highway_cycle_lane", "bus_lane_with_bicycles", "cycle_lane_shared_with_buses", "protected_lane_separation", "protected_lane_parking", "protected_lane_sidepath", "cycleway_crossing", "split_both_sides", "side_presence", "lifecycle", "lifecycle_not_reached", "plan_not_enough", "plan_no_edits"];
287
+ type TagReasonCode = (typeof TAG_REASON_CODES)[number];
288
+ /**
289
+ * The prefix of the road side object a category lives on: `sidewalk` for a footway with bicycles
290
+ * allowed (`sidewalk:right:bicycle=yes`), `cycleway` for the rest.
291
+ */
292
+ declare function categorySidePrefix(categoryId: string): 'cycleway' | 'sidewalk';
115
293
  /**
116
294
  * Map a transformed tag key back to OSM way tags for writing.
117
- * Left/right cycleway (and sidewalk) sub-objects use nested keys (`cycleway:right:lane`).
295
+ * Left/right cycleway (and sidewalk) sub-objects use nested keys (`cycleway:right:lane`); the key
296
+ * that names the side itself (`cycleway`) is `cycleway:right`.
118
297
  */
119
298
  declare function writeKeyForSide(transformedKey: string, side: BikelaneResult['_side'], prefix: string | null): string;
299
+ /** The traffic signs that settle `categoryId` on their own, and whether it works without a sign. */
300
+ interface CategorySignOptions {
301
+ /** Signs the planner writes for the category (`DE:240`); never `none` */
302
+ signs: string[];
303
+ /** Some alternative of the category needs no traffic sign (or `traffic_sign=none`) */
304
+ unsignedPossible: boolean;
305
+ }
306
+ /** Which traffic signs settle `categoryId`, read from the category specs. */
307
+ declare function categorySignOptions(categoryId: string): CategorySignOptions;
120
308
  declare function listTargetCategories(options?: ListTargetCategoriesOptions): string[];
121
309
  interface PlanTagsForCategoryOptions {
122
310
  side?: BikelaneResult['_side'];
311
+ /**
312
+ * Tags the plan must contain, in transformed (bare) keys: `{ traffic_sign: 'DE:240' }`. They are
313
+ * written for the side (`cycleway:right:traffic_sign`) and may overwrite `traffic_sign=none`: a
314
+ * fixed tag is an explicit choice of the mapper (a mapping target).
315
+ */
316
+ fixed?: Record<string, string>;
317
+ /**
318
+ * The lifecycle the side must get. `temporary` writes `temporary=yes` for the side
319
+ * (`cycleway:right:temporary=yes`). `construction` writes a way of its own as
320
+ * `highway=construction` + `construction=<highway>` and a road side under the prefix
321
+ * (`construction:cycleway:right=lane`).
322
+ */
323
+ lifecycle?: PlanLifecycle;
123
324
  }
325
+ type PlanLifecycle = 'construction' | 'temporary';
124
326
  declare class UnknownTargetCategoryError extends Error {
125
327
  readonly targetCategoryId: string;
126
328
  constructor(targetCategoryId: string);
@@ -131,10 +333,21 @@ declare class UnknownTargetCategoryError extends Error {
131
333
  * Returned keys use nested OSM form for left/right cycleway (and sidewalk) sides
132
334
  * (`cycleway:right:lane`); bare keys for self-side objects.
133
335
  *
134
- * Predicate macros (`cycleway_on_highway_*`, `needs_clarification`, etc.) are not
135
- * inverted — plans rely on simple eq/in atoms and gap discriminators.
336
+ * - Tags that settle a category are alternatives: `segregated=yes` (with `bicycle` and `foot`) or
337
+ * `traffic_sign=DE:241` is enough, the plan never asks for both. Plans that add no traffic sign
338
+ * come first.
339
+ * - `traffic_sign=none` is never overwritten (unless `options.fixed` says so).
340
+ * - Macros the classifier evaluates imperatively have preferred tags (`MACRO_PLAN_ALTERNATIVES`);
341
+ * the rest (e.g. `cyclewayOnHighwayProtected`) may still yield a `_category` conflict.
136
342
  */
137
343
  declare function planTagsForCategory(wayTags: OsmTags, targetCategoryId: string, options?: PlanTagsForCategoryOptions): CategoryTagPlan;
344
+ /**
345
+ * The ways to reach `targetCategoryId`, the plan of `planTagsForCategory` first (`default`).
346
+ * For categories a traffic sign can settle, further variants: `with_sign` (the sign of the
347
+ * category) and `without_sign` (`traffic_sign=none` plus the tags that say the same). Variants that
348
+ * do not reach the target or repeat an earlier one are left out.
349
+ */
350
+ declare function planTagVariantsForCategory(wayTags: OsmTags, targetCategoryId: string, options?: PlanTagsForCategoryOptions): CategoryTagPlanVariant[];
138
351
 
139
352
  /** Small predicate AST for declarative category specs (OSMnexus-inspired). */
140
353
 
@@ -214,6 +427,8 @@ interface CategorySpec {
214
427
  implicitOneWay: boolean;
215
428
  implicitOneWayConfidence: ImplicitOneWayConfidence;
216
429
  copySurfaceSmoothnessFromParent: boolean;
430
+ /** How `surface:bicycle` applies, see `deriveBikelaneSurfaceTags`; undefined ignores it. */
431
+ bicycleSurface?: BicycleSurface;
217
432
  match?: TagPredicate;
218
433
  excludes?: TagPredicate[];
219
434
  refining?: RefiningChild[];
@@ -271,4 +486,4 @@ declare const ALLOWED_HIGHWAYS: Set<string>;
271
486
 
272
487
  declare function processBikelanes(objectTags: OsmTags): BikelaneResult[];
273
488
 
274
- export { ALLOWED_HIGHWAYS, BIKELANE_TRANSFORMATIONS, type BikelaneResult, CATEGORY_DEFINITIONS, CATEGORY_SPECS, type CategoryGap, type CategoryGapResult, type CategorySpec, type CategoryTagPlan, type GapDiscriminator, type ListTargetCategoriesOptions, MAJOR_ROAD_CLASSES, MINOR_ROAD_CLASSES, type OsmTags, PATH_CLASSES, type PlanTagsForCategoryOptions, SIDEPATH_HIGHWAY_CLASSES, TRUNK_MOTORWAY_CLASSES, type TagChangeEntry, type TagConflictEntry, type TagPlanEntry, UnknownTargetCategoryError, analyzeCategoryGaps, categorizeBikelane, getTransformedObjects, isIncompleteCategoryId, listTargetCategories, planTagsForCategory, prepareTags, processBikelanes, specsWithGapDiscriminators, writeKeyForSide };
489
+ export { ALLOWED_HIGHWAYS, BIKELANE_TODOS, BIKELANE_TRANSFORMATIONS, type BikelaneResult, type BikelaneTodoDefinition, type BikelaneTodoResult, type BikelaneTodos, CATEGORY_DEFINITIONS, CATEGORY_SPECS, type CategoryGap, type CategoryGapResult, type CategorySignOptions, type CategorySpec, type CategoryTagPlan, type CategoryTagPlanVariant, type CategoryTagPlanVariantId, DIRECTIONAL_PARKING_INFERENCE_CATEGORIES, type GapDiscriminator, type ListTargetCategoriesOptions, MAJOR_ROAD_CLASSES, MARKING_ALLOWED, MINOR_ROAD_CLASSES, type OsmTags, PARKING_ALLOWED, PATH_CLASSES, PROTECTIVE_SEPARATION, type PlanLifecycle, type PlanTagsForCategoryOptions, ROAD_TODOS, type RoadTodoDefinition, type RoadTodoResult, SEPARATION_ALLOWED, SIDEPATH_HIGHWAY_CLASSES, SURFACE_ALLOWED, SURFACE_COLOR_ALLOWED, TAG_REASON_CODES, TRAFFIC_MODE_ALLOWED, TRUNK_MOTORWAY_CLASSES, type TagChangeEntry, type TagConflictEntry, type TagPlanEntry, type TagReason, type TagReasonCode, type TodoTagFix, UnknownTargetCategoryError, analyzeCategoryGaps, categorizeBikelane, categorySidePrefix, categorySignOptions, defaultSideRunsAgainstWay, deriveBikelaneTodos, deriveRoadTodos, getTransformedObjects, isIncompleteCategoryId, isUnusualWidth, listTargetCategories, parseLength, parseWidth, planTagVariantsForCategory, planTagsForCategory, prepareTags, processBikelanes, specsWithGapDiscriminators, writeKeyForSide };