@osmix/vt 0.0.2 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @osmix/vt
 
+## 0.0.7
+
+### Patch Changes
+
+- 68d6bd8: Fix publishing for packages.
+- Updated dependencies [68d6bd8]
+  - @osmix/shared@0.0.7
+
+## 0.0.6
+
+### Patch Changes
+
+- 2c03b6c: Add shortbread vector tile generation option
+- 0cd8a2e: Explore patterns for extending Osmix worker
+- Updated dependencies [0cd8a2e]
+  - @osmix/shared@0.0.6
+
+## 0.0.5
+
+### Patch Changes
+
+- bb629cf: Simplify raster drawing when geometry is smaller than a pixel
+- edbb26b: Handle more Relation types
+- Updated dependencies [bb629cf]
+- Updated dependencies [edbb26b]
+- Updated dependencies [69a36bd]
+  - @osmix/shared@0.0.5
+
+## 0.0.4
+
+### Patch Changes
+
+- d001d9a: Refactor to align around new main external API
+- Updated dependencies [572cbd8]
+- Updated dependencies [d001d9a]
+  - @osmix/shared@0.0.4
+
+## 0.0.3
+
+### Patch Changes
+
+- b4a3ff2: Improve Relation handling and display
+- Updated dependencies [b4a3ff2]
+  - @osmix/shared@0.0.3
+  - @osmix/json@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -1,23 +1,23 @@
 # @osmix/vt
 
-`@osmix/vt` converts Osmix binary overlays (typed-array node and way payloads) into Mapbox Vector Tiles. It also ships a lightweight tile index with LRU caching so workers or web apps can request tiles on demand without re-projecting data for every request.
+`@osmix/vt` converts `@osmix/core` OSM into Mapbox Vector Tiles.
 
 ## Installation
 
 ```sh
-npm install @osmix/vt
+bun install @osmix/vt
 ```
 
 ## Usage
 
-### Encode a single vector tile from an Osmix dataset
+### Encode a single vector tile from an Osm dataset
 
 ```ts
-import { Osmix } from "@osmix/core"
+import { Osm } from "@osmix/core"
 import { OsmixVtEncoder } from "@osmix/vt"
 
-// Load or build an Osmix dataset (indexed nodes/ways/relations)
-const osm = await Osmix.fromPbf(fetch("/fixtures/monaco.pbf").then((r) => r.arrayBuffer()))
+// Load your Osm dataset
+const osm = await Osmix.fromPbf(Bun.file('./monaco.pbf').stream())
 
 // Create an encoder. Defaults: extent=4096, buffer=64px
 const encoder = new OsmixVtEncoder(osm)
@@ -25,71 +25,68 @@ const encoder = new OsmixVtEncoder(osm)
 // XYZ tile tuple: [x, y, z]
 const tile: [number, number, number] = [9372, 12535, 15]
 
-// Returns an ArrayBuffer containing an MVT PBF for two layers:
-// "@osmix:<id>:ways" and "@osmix:<id>:nodes"
+// Returns an ArrayBuffer containing up to three layers:
+// "@osmix:<id>:ways", "@osmix:<id>:nodes", "@osmix:<id>:relations"
 const pbfBuffer = encoder.getTile(tile)
-
-// Persist or send somewhere
-await Deno.writeFile("tile.mvt", new Uint8Array(pbfBuffer))
 ```
 
-### Custom bounding box and projection
+### Displaying in a browser (manual Blob URL)
 
-If you already have a WGS84 bbox and a lon/lat → tile-pixel projection, you can render directly:
+Most viewers expect tile URLs. To see a Maplibre implementation in the [example merge app](/apps/merge/src/lib/osmix-vector-protocol.ts).
 
-```ts
-import { OsmixVtEncoder, projectToTile } from "@osmix/vt"
+## What gets encoded
 
-const encoder = new OsmixVtEncoder(osm, 4096, 64)
-const bbox: [number, number, number, number] = [-73.99, 40.73, -73.98, 40.74]
-const proj = projectToTile([9372, 12535, 15], 4096)
+- Ways become LINE features; AREA-like ways (per `wayIsArea`) become POLYGON features.
+- Multipolygon relations render as POLYGON features in a dedicated layer so holes and shared ways stay intact.
+- Nodes with tags become POINT features. Untagged nodes are skipped.
+- Each feature includes properties `{ type: "node" | "way" | "relation", ...tags }` and `id`.
+- Three layers are emitted per tile: `@osmix:<datasetId>:ways`, `@osmix:<datasetId>:nodes`, and `@osmix:<datasetId>:relations` (empty layers are omitted automatically).
 
-const pbf = encoder.getTileForBbox(bbox, proj)
-```
+## API
 
-### Displaying in a browser (manual Blob URL)
+### `OsmixVtEncoder`
 
-Most viewers expect tile URLs. For quick inspection, you can create a Blob URL for a single tile:
+The main class for encoding vector tiles.
 
 ```ts
-const buf = encoder.getTile([9372, 12535, 15])
-const url = URL.createObjectURL(new Blob([buf], { type: "application/x-protobuf" }))
-// Use `url` anywhere a single MVT URL is accepted (debug tooling, downloads, etc.)
+constructor(osm: Osm, extent = 4096, buffer = 64)
 ```
 
-For full map integration, serve tiles from a handler that calls `getTile([x,y,z])` and returns the bytes. MapLibre/Mapbox GL can then point a `vector` source at `https://your-host/tiles/{z}/{x}/{y}.mvt`.
+- `osm`: The `@osmix/core` dataset to encode.
+- `extent`: Tile extent (default 4096). Higher values offer more precision.
+- `buffer`: Buffer around the tile in extent units (default 64).
 
-## What gets encoded
+#### `getTile(tile: [x, y, z]): ArrayBuffer`
 
-- Ways become LINE features; AREA-like ways (per `wayIsArea`) become POLYGON features.
-- Nodes with tags become POINT features. Untagged nodes are skipped.
-- Each feature includes properties `{ type: "node" | "way", ...tags }` and `id`.
-- Two layers are emitted per tile: `@osmix:<datasetId>:ways` and `@osmix:<datasetId>:nodes`.
+Encodes a single tile identified by its XYZ coordinates. Returns a PBF `ArrayBuffer`.
 
-## API overview
+#### `getTileForBbox(bbox: [w, s, e, n], proj: (ll) => [x, y]): ArrayBuffer`
 
-- `class OsmixVtEncoder(osmix: Osmix, extent=4096, buffer=64)`
-  - `getTile(tile: [x, y, z]): ArrayBuffer` – Encodes a tile using internal bbox/projection.
-  - `getTileForBbox(bbox, proj): ArrayBuffer` – Encode for a WGS84 bbox with a lon/lat → tile-pixel projector.
-  - Internals expose generators for `nodeFeatures` and `wayFeatures` if you need to post-process.
-- `projectToTile(tile: [x, y, z], extent=4096): (lonLat) => [x, y]` – Helper to build a projector matching the encoder.
-- Types (from `src/types.ts`):
-  - `VtSimpleFeature` – `{ id, type, properties, geometry }`
-  - `VtPbfLayer` – `{ name, version, extent, features }`
+Lower-level method to encode a specific bounding box with a custom projection function. Useful if you are projecting to non-Mercator tiles or need custom bounds.
 
 ## Environment and limitations
 
 - Designed for modern runtimes (Node 20+, Bun, browser workers). Uses typed arrays throughout.
-- Polygon handling currently assumes a single outer ring; holes/multi-polygons (relations) are not encoded in v0.0.1.
+- Multipolygon relations are supported, but other relation types are skipped.
 - Ways are clipped to tile bounds; nodes outside the tile are omitted.
 - Extent defaults to 4096; set a larger extent if you need higher precision.
 
 ### Tags and metadata
 
 - Feature properties include the OSM tags available in the source dataset. Styling keys can be derived at ingestion time; for very large tag sets consider pre-filtering to a stable subset to keep tile size reasonable.
+- Way features normalize `color`/`colour` tags into a single `color` property formatted as `#RRGGBB` (or `#RRGGBBAA` when provided).
+
+## Related Packages
+
+- [`@osmix/core`](../core/README.md) – In-memory index used to source node/way geometry.
+- [`@osmix/shared`](../shared/README.md) – Supplies `wayIsArea` heuristics and entity types.
+- [`@osmix/raster`](../raster/README.md) – Raster tile rendering if you prefer PNG/WebP output.
+- [`osmix`](../osmix/README.md) – High-level API with `getVectorTile()` helper.
+
+## Development
 
-## See also
+- `bun run test packages/vt`
+- `bun run lint packages/vt`
+- `bun run typecheck packages/vt`
 
-- `@osmix/core` – In-memory index used to source node/way geometry.
-- `@osmix/json` – Supplies `wayIsArea` heuristics and entity types used by the encoder.
-- `@osmix/raster` – If you prefer raster previews or a protocol helper for MapLibre.
+Run `bun run check` at the repo root before publishing to ensure formatting, lint, and type coverage.

package/dist/encode.d.ts

@@ -1,21 +1,57 @@
-import type { Osmix } from "@osmix/core";
+/**
+ * Vector tile encoding for OSM data.
+ *
+ * The OsmixVtEncoder class converts Osmix datasets into Mapbox Vector Tiles,
+ * handling geometry projection, clipping, area detection, and proper
+ * MVT encoding for nodes, ways, and relations.
+ *
+ * @module
+ */
+import type { Osm } from "@osmix/core";
 import type { GeoBbox2D, LonLat, Tile, XY } from "@osmix/shared/types";
 import type { VtSimpleFeature } from "./types";
+/**
+ * Returns a projection function that converts [lon, lat] to [x, y] pixel coordinates
+ * relative to the given tile. The extent determines the resolution of the tile
+ * (e.g. 4096 means coordinates range from 0 to 4096).
+ */
 export declare function projectToTile(tile: Tile, extent?: number): (ll: LonLat) => XY;
+/**
+ * Encode an Osm instance into a Mapbox Vector Tile PBF.
+ */
 export declare class OsmixVtEncoder {
     readonly nodeLayerName: string;
     readonly wayLayerName: string;
-    private readonly osmix;
+    readonly relationLayerName: string;
+    private readonly osm;
     private readonly extent;
     private readonly extentBbox;
-    constructor(osmix: Osmix, extent?: number, buffer?: number);
+    static layerNames(id: string): {
+        nodeLayerName: string;
+        wayLayerName: string;
+        relationLayerName: string;
+    };
+    constructor(osm: Osm, extent?: number, buffer?: number);
+    /**
+     * Get a vector tile PBF for a specific tile coordinate.
+     * Returns an empty buffer if the tile does not intersect with the OSM dataset.
+     */
     getTile(tile: Tile): ArrayBuffer;
+    /**
+     * Get a vector tile PBF for a specific geographic bounding box.
+     * @param bbox The bounding box to include features from.
+     * @param proj A function to project [lon, lat] to [x, y] within the tile extent.
+     */
     getTileForBbox(bbox: GeoBbox2D, proj: (ll: LonLat) => XY): ArrayBuffer;
     nodeFeatures(bbox: GeoBbox2D, proj: (ll: LonLat) => XY): Generator<VtSimpleFeature>;
-    wayFeatures(bbox: GeoBbox2D, proj: (ll: LonLat) => XY): Generator<VtSimpleFeature>;
+    wayFeatures(bbox: GeoBbox2D, proj: (ll: LonLat) => XY, relationWayIds?: Set<number>): Generator<VtSimpleFeature>;
     clipProjectedPolyline(points: XY[]): XY[][];
-    clipProjectedPolygon(points: XY[]): XY[];
-    processClippedPolygonRing(rawRing: XY[]): XY[];
+    clipProjectedPolygon(points: XY[]): XY[][];
+    processClippedPolygonRing(rawRing: XY[], isOuter: boolean): XY[];
+    /**
+     * Super relations and logical relations are not directly rendered; they would need recursive expansion.
+     */
+    relationFeatures(bbox: GeoBbox2D, proj: (ll: LonLat) => XY): Generator<VtSimpleFeature>;
     clampAndRoundPoint(xy: XY): XY;
 }
 //# sourceMappingURL=encode.d.ts.map

package/dist/encode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAIxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,KAAK,EACX,eAAe,EAGf,MAAM,SAAS,CAAA;AA2BhB,wBAAgB,aAAa,CAC5B,IAAI,EAAE,IAAI,EACV,MAAM,SAAiB,GACrB,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,CAGpB;AAED,qBAAa,cAAc;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;gBAEjD,KAAK,EAAE,KAAK,EAAE,MAAM,SAAiB,EAAE,MAAM,SAAiB;IAa1E,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW;IAMhC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,GAAG,WAAW;IAkBrE,YAAY,CACZ,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,GACtB,SAAS,CAAC,eAAe,CAAC;IAkB5B,WAAW,CACX,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,GACtB,SAAS,CAAC,eAAe,CAAC;IAmD7B,qBAAqB,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAI3C,oBAAoB,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;IAIxC,yBAAyB,CAAC,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;IAc9C,kBAAkB,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE;CAS9B"}
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAKtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAA;AAEtE,OAAO,KAAK,EACX,eAAe,EAGf,MAAM,SAAS,CAAA;AA6BhB;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,IAAI,EACV,MAAM,SAAiB,GACrB,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,CAEpB;AAED;;GAEG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAE7D,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM;;;;;gBAQhB,GAAG,EAAE,GAAG,EAAE,MAAM,SAAiB,EAAE,MAAM,SAAiB;IActE;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW;IAShC;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,GAAG,WAAW;IA2BrE,YAAY,CACZ,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,GACtB,SAAS,CAAC,eAAe,CAAC;IAkB5B,WAAW,CACX,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,EACxB,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,SAAS,CAAC,eAAe,CAAC;IAmE7B,qBAAqB,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAI3C,oBAAoB,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAO1C,yBAAyB,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,EAAE;IAkBhE;;OAEG;IACF,gBAAgB,CAChB,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,EAAE,GACtB,SAAS,CAAC,eAAe,CAAC;IA4G7B,kBAAkB,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE;CAS9B"}

package/dist/encode.js

@@ -1,8 +1,21 @@
-import { wayIsArea } from "@osmix/json";
+/**
+ * Vector tile encoding for OSM data.
+ *
+ * The OsmixVtEncoder class converts Osmix datasets into Mapbox Vector Tiles,
+ * handling geometry projection, clipping, area detection, and proper
+ * MVT encoding for nodes, ways, and relations.
+ *
+ * @module
+ */
+import { bboxContainsOrIntersects } from "@osmix/shared/bbox-intersects";
+import { normalizeHexColor } from "@osmix/shared/color";
 import { clipPolygon, clipPolyline } from "@osmix/shared/lineclip";
-import SphericalMercatorTile from "@osmix/shared/spherical-mercator";
+import { llToTilePx, tileToBbox } from "@osmix/shared/tile";
+import { wayIsArea } from "@osmix/shared/way-is-area";
 import writeVtPbf from "./write-vt-pbf";
+/** Default tile extent (coordinate resolution). */
 const DEFAULT_EXTENT = 4096;
+/** Default buffer around tile in extent units. */
 const DEFAULT_BUFFER = 64;
 const SF_TYPE = {
     POINT: 1,
@@ -23,38 +36,68 @@ function dedupePoints(points) {
     }
     return result;
 }
+/**
+ * Returns a projection function that converts [lon, lat] to [x, y] pixel coordinates
+ * relative to the given tile. The extent determines the resolution of the tile
+ * (e.g. 4096 means coordinates range from 0 to 4096).
+ */
 export function projectToTile(tile, extent = DEFAULT_EXTENT) {
-    const sm = new SphericalMercatorTile({ size: extent, tile });
-    return (lonLat) => sm.llToTilePx(lonLat);
+    return (lonLat) => llToTilePx(lonLat, tile, extent);
 }
+/**
+ * Encode an Osm instance into a Mapbox Vector Tile PBF.
+ */
 export class OsmixVtEncoder {
     nodeLayerName;
     wayLayerName;
-    osmix;
+    relationLayerName;
+    osm;
     extent;
     extentBbox;
-    constructor(osmix, extent = DEFAULT_EXTENT, buffer = DEFAULT_BUFFER) {
-        this.osmix = osmix;
+    static layerNames(id) {
+        return {
+            nodeLayerName: `@osmix:${id}:nodes`,
+            wayLayerName: `@osmix:${id}:ways`,
+            relationLayerName: `@osmix:${id}:relations`,
+        };
+    }
+    constructor(osm, extent = DEFAULT_EXTENT, buffer = DEFAULT_BUFFER) {
+        this.osm = osm;
         const min = -buffer;
         const max = extent + buffer;
         this.extent = extent;
         this.extentBbox = [min, min, max, max];
-        const layerName = `@osmix:${osmix.id}`;
+        const layerName = `@osmix:${osm.id}`;
         this.nodeLayerName = `${layerName}:nodes`;
         this.wayLayerName = `${layerName}:ways`;
+        this.relationLayerName = `${layerName}:relations`;
     }
+    /**
+     * Get a vector tile PBF for a specific tile coordinate.
+     * Returns an empty buffer if the tile does not intersect with the OSM dataset.
+     */
     getTile(tile) {
-        const sm = new SphericalMercatorTile({ size: this.extent, tile });
-        const bbox = sm.bbox(tile[0], tile[1], tile[2]);
-        return this.getTileForBbox(bbox, (ll) => sm.llToTilePx(ll));
+        const bbox = tileToBbox(tile);
+        const osmBbox = this.osm.bbox();
+        if (!bboxContainsOrIntersects(bbox, osmBbox)) {
+            return new ArrayBuffer(0);
+        }
+        return this.getTileForBbox(bbox, (ll) => llToTilePx(ll, tile, this.extent));
     }
+    /**
+     * Get a vector tile PBF for a specific geographic bounding box.
+     * @param bbox The bounding box to include features from.
+     * @param proj A function to project [lon, lat] to [x, y] within the tile extent.
+     */
     getTileForBbox(bbox, proj) {
-        const layer = writeVtPbf([
+        // Get way IDs that are part of relations (to exclude from individual rendering)
+        const relationWayIds = this.osm.relations.getWayMemberIds();
+        const layers = [
             {
                 name: this.wayLayerName,
                 version: 2,
                 extent: this.extent,
-                features: this.wayFeatures(bbox, proj),
+                features: this.wayFeatures(bbox, proj, relationWayIds),
             },
             {
                 name: this.nodeLayerName,
@@ -62,56 +105,73 @@ export class OsmixVtEncoder {
                 extent: this.extent,
                 features: this.nodeFeatures(bbox, proj),
             },
-        ]);
-        return layer;
+            {
+                name: this.relationLayerName,
+                version: 2,
+                extent: this.extent,
+                features: this.relationFeatures(bbox, proj),
+            },
+        ];
+        return writeVtPbf(layers);
     }
     *nodeFeatures(bbox, proj) {
-        const nodeIndexes = this.osmix.nodes.withinBbox(bbox);
+        const nodeIndexes = this.osm.nodes.findIndexesWithinBbox(bbox);
         for (let i = 0; i < nodeIndexes.length; i++) {
             const nodeIndex = nodeIndexes[i];
             if (nodeIndex === undefined)
                 continue;
-            const tags = this.osmix.nodes.tags.getTags(nodeIndex);
+            const tags = this.osm.nodes.tags.getTags(nodeIndex);
             if (!tags || Object.keys(tags).length === 0)
                 continue;
-            const id = this.osmix.nodes.ids.at(nodeIndex);
-            const ll = this.osmix.nodes.getNodeLonLat({ index: nodeIndex });
+            const id = this.osm.nodes.ids.at(nodeIndex);
+            const ll = this.osm.nodes.getNodeLonLat({ index: nodeIndex });
             yield {
                 id,
                 type: SF_TYPE.POINT,
-                properties: { type: "node", ...tags },
+                properties: { ...tags, type: "node" },
                 geometry: [[proj(ll)]],
             };
         }
     }
-    *wayFeatures(bbox, proj) {
-        const wayIndexes = this.osmix.ways.intersects(bbox);
+    *wayFeatures(bbox, proj, relationWayIds) {
+        const wayIndexes = this.osm.ways.intersects(bbox);
         for (let i = 0; i < wayIndexes.length; i++) {
             const wayIndex = wayIndexes[i];
             if (wayIndex === undefined)
                 continue;
-            const id = this.osmix.ways.ids.at(wayIndex);
-            const tags = this.osmix.ways.tags.getTags(wayIndex);
-            const count = this.osmix.ways.refCount.at(wayIndex);
-            const start = this.osmix.ways.refStart.at(wayIndex);
-            const points = new Array(count);
-            for (let i = 0; i < count; i++) {
-                const ref = this.osmix.ways.refs.at(start + i);
-                const ll = this.osmix.nodes.getNodeLonLat({ id: ref });
-                points[i] = proj(ll);
-            }
-            const isArea = wayIsArea({ id, refs: new Array(count).fill(0), tags });
+            const id = this.osm.ways.ids.at(wayIndex);
+            // Skip ways that are part of relations (they will be rendered via relations)
+            if (id !== undefined && relationWayIds?.has(id))
+                continue;
+            const tags = this.osm.ways.tags.getTags(wayIndex);
+            // Skip ways without tags (they are likely only for relations)
+            if (!tags || Object.keys(tags).length === 0)
+                continue;
+            const normalizedColor = normalizeHexColor(tags["color"] ?? tags["colour"]);
+            const wayLine = this.osm.ways.getCoordinates(wayIndex);
+            const points = wayLine.map((ll) => proj(ll));
+            const isArea = wayIsArea({
+                id,
+                refs: this.osm.ways.getRefIds(wayIndex),
+                tags,
+            });
             const geometry = [];
             if (isArea) {
-                // 1. clip polygon in tile coords
-                const clippedPoly = this.clipProjectedPolygon(points);
-                // clipProjectedPolygon currently returns XY[], not XY[][]
-                // i.e. assumes single ring. We'll treat it as one ring.
-                // 2. round/clamp, dedupe, close, orient
-                const processedRing = this.processClippedPolygonRing(clippedPoly);
-                // TODO handle MultiPolygons with holes
-                if (processedRing.length > 0) {
-                    geometry.push(processedRing);
+                // 1. clip polygon in tile coords (returns array of rings)
+                const clippedRings = this.clipProjectedPolygon(points);
+                // 2. process each ring (first is outer, rest would be holes if from relations)
+                for (let ringIndex = 0; ringIndex < clippedRings.length; ringIndex++) {
+                    const clippedRing = clippedRings[ringIndex];
+                    if (!clippedRing)
+                        continue;
+                    // Normalize winding order using rewind before processing
+                    // GeoJSON: outer counterclockwise, inner clockwise
+                    // MVT: outer clockwise, inner counterclockwise
+                    const isOuter = ringIndex === 0;
+                    const processedRing = this.processClippedPolygonRing(clippedRing, isOuter);
+                    if (processedRing.length > 0) {
+                        geometry.push(processedRing);
+                    }
                 }
             }
             else {
@@ -129,7 +189,11 @@ export class OsmixVtEncoder {
             yield {
                 id,
                 type: isArea ? SF_TYPE.POLYGON : SF_TYPE.LINE,
-                properties: { type: "way", ...tags },
+                properties: {
+                    ...tags,
+                    ...(normalizedColor ? { color: normalizedColor } : {}),
+                    type: "way",
+                },
                 geometry,
             };
         }
@@ -138,25 +202,135 @@ export class OsmixVtEncoder {
         return clipPolyline(points, this.extentBbox);
     }
     clipProjectedPolygon(points) {
-        return clipPolygon(points, this.extentBbox);
+        // clipPolygon returns a single ring, but we return as array for consistency
+        // with multi-ring support (e.g., from relations)
+        const clipped = clipPolygon(points, this.extentBbox);
+        return [clipped];
     }
-    processClippedPolygonRing(rawRing) {
+    processClippedPolygonRing(rawRing, isOuter) {
         // 1. round & clamp EVERY point
         const snapped = rawRing.map((xy) => this.clampAndRoundPoint(xy));
         // 2. clean (dedupe + close + min length)
         const cleaned = cleanRing(snapped);
         if (cleaned.length === 0)
             return [];
-        // 3. enforce clockwise for outer ring
-        const oriented = ensureClockwise(cleaned);
+        // 3. enforce winding order per MVT spec:
+        //    - Outer rings: clockwise
+        //    - Inner rings (holes): counterclockwise
+        const oriented = isOuter
+            ? ensureClockwise(cleaned)
+            : ensureCounterclockwise(cleaned);
         return oriented;
     }
+    /**
+     * Super relations and logical relations are not directly rendered; they would need recursive expansion.
+     */
+    *relationFeatures(bbox, proj) {
+        const relationIndexes = this.osm.relations.intersects(bbox);
+        for (const relIndex of relationIndexes) {
+            const relation = this.osm.relations.getByIndex(relIndex);
+            const relationGeometry = this.osm.relations.getRelationGeometry(relIndex);
+            if (!relation ||
+                (!relationGeometry.lineStrings &&
+                    !relationGeometry.rings &&
+                    !relationGeometry.points))
+                continue;
+            const id = this.osm.relations.ids.at(relIndex);
+            const tags = this.osm.relations.tags.getTags(relIndex);
+            if (relationGeometry.rings) {
+                // Area relations (multipolygon, boundary)
+                const { rings } = relationGeometry;
+                if (rings.length === 0)
+                    continue;
+                // Process each polygon in the relation
+                for (const polygon of rings) {
+                    const geometry = [];
+                    // Process outer ring and inner rings (holes)
+                    for (let ringIndex = 0; ringIndex < polygon.length; ringIndex++) {
+                        const ring = polygon[ringIndex];
+                        if (!ring || ring.length < 3)
+                            continue;
+                        // Project ring to tile coordinates
+                        const projectedRing = ring.map((ll) => proj(ll));
+                        // Clip polygon ring
+                        const clipped = clipPolygon(projectedRing, this.extentBbox);
+                        if (clipped.length < 3)
+                            continue;
+                        // Process ring (round/clamp, dedupe, close, orient)
+                        const isOuter = ringIndex === 0;
+                        const processedRing = this.processClippedPolygonRing(clipped, isOuter);
+                        if (processedRing.length > 0) {
+                            geometry.push(processedRing);
+                        }
+                    }
+                    if (geometry.length === 0)
+                        continue;
+                    yield {
+                        id: id ?? 0,
+                        type: SF_TYPE.POLYGON,
+                        properties: { ...tags, type: "relation" },
+                        geometry,
+                    };
+                }
+            }
+            else if (relationGeometry.lineStrings) {
+                // Line relations (route, multilinestring)
+                const { lineStrings } = relationGeometry;
+                if (lineStrings.length === 0)
+                    continue;
+                for (const lineString of lineStrings) {
+                    const geometry = [];
+                    const points = lineString.map((ll) => proj(ll));
+                    const clippedSegmentsRaw = this.clipProjectedPolyline(points);
+                    for (const segment of clippedSegmentsRaw) {
+                        const rounded = segment.map((xy) => this.clampAndRoundPoint(xy));
+                        const deduped = dedupePoints(rounded);
+                        if (deduped.length >= 2) {
+                            geometry.push(deduped);
+                        }
+                    }
+                    if (geometry.length === 0)
+                        continue;
+                    yield {
+                        id: id ?? 0,
+                        type: SF_TYPE.LINE,
+                        properties: { ...tags, type: "relation" },
+                        geometry,
+                    };
+                }
+            }
+            else if (relationGeometry.points) {
+                // Point relations (multipoint)
+                const { points } = relationGeometry;
+                if (points.length === 0)
+                    continue;
+                const geometry = [];
+                for (const point of points) {
+                    const projected = proj(point);
+                    const clamped = this.clampAndRoundPoint(projected);
+                    geometry.push([clamped]);
+                }
+                if (geometry.length === 0)
+                    continue;
+                yield {
+                    id: id ?? 0,
+                    type: SF_TYPE.POINT,
+                    properties: { ...tags, type: "relation" },
+                    geometry,
+                };
+            }
+        }
+    }
     clampAndRoundPoint(xy) {
         const clampedX = Math.round(clamp(xy[0], this.extentBbox[0], this.extentBbox[2]));
         const clampedY = Math.round(clamp(xy[1], this.extentBbox[1], this.extentBbox[3]));
         return [clampedX, clampedY];
     }
 }
+/**
+ * Ensures the ring is closed (first and last points are identical).
+ * If not, appends the first point to the end.
+ */
 function closeRing(ring) {
     const first = ring[0];
     const last = ring[ring.length - 1];
@@ -167,8 +341,10 @@ function closeRing(ring) {
     }
     return ring;
 }
-// Signed area via shoelace formula.
-// Positive area => CCW, Negative => CW.
+/**
+ * Signed area via shoelace formula.
+ * Positive area => CCW, Negative => CW.
+ */
 function ringArea(ring) {
     let sum = 0;
     for (let i = 0; i < ring.length - 1; i++) {
@@ -181,14 +357,13 @@ function ringArea(ring) {
 function ensureClockwise(ring) {
     return ringArea(ring) < 0 ? ring : [...ring].reverse();
 }
-/**
- * TODO handle MultiPolygons with holes
- *
-function _ensureCounterClockwise(ring: XY[]): XY[] {
-    return ringArea(ring) > 0 ? ring : [...ring].reverse()
+function ensureCounterclockwise(ring) {
+    return ringArea(ring) > 0 ? ring : [...ring].reverse();
 }
-*/
-// Remove consecutive duplicates *after* rounding
+/**
+ * Clean a polygon ring by removing consecutive duplicates, ensuring it's closed,
+ * and checking that it has at least 4 coordinates (3 unique points).
+ */
 function cleanRing(ring) {
     const deduped = dedupePoints(ring);
     // After dedupe, we still must ensure closure, and a polygon