Changelog

Isometric Projection

A new projection mode transforms top-down images into a 2.5D isometric perspective:

• 45° rotation — rotates the image to create the classic isometric diamond view
• Vertical foreshortening — compresses the Y axis by 50% for proper isometric proportions
• Bilinear sampling — smooth interpolation for high-quality output

Use isometric projection to convert floor plans, game maps, or top-down artwork into an isometric view. Select "Isometric" from the Projection dropdown in the main form.

Scale Metadata for Measurements

Define how pixels relate to real-world units for accurate measurements on your tilesets:

• Pixels per unit — specify how many pixels represent one unit (e.g., "10 pixels = 1 meter")
• Units per tile — specify how many units one tile covers (e.g., "1 tile = 100 feet")
• Unit options — meters, feet, kilometers, miles, yards, or inches

Scale metadata is stored in the tileset and can be used by mapping applications to display accurate distance measurements. Find these options in the Advanced Options section.

Other Changes

• PMTiles for local processing — WASM processing now generates both ZIP and PMTiles output
• Pre-scaling — scale images before tiling (0.25x, 0.5x, 2x, or 4x)
• Background color — fill transparent areas with a solid color
• Proxy file convention — migrated from deprecated middleware.ts to proxy.ts for Next.js 16

API Changes

The /api/tiles endpoint now accepts an optional projection parameter with three values:

| Value | Description | |---|---| | flat | Standard flat projection (default) | | mercator | Web Mercator for geographic maps | | isometric | 2.5D isometric transformation |

Batch Processing

Process multiple images at once with the new batch queue:

• Multi-file upload — drag and drop multiple images or use the file picker with multi-select
• Queue display — see all queued files with their status (queued, processing, done, error)
• Per-file progress — individual progress bars showing zoom level and tile count
• Sequential processing — files process one at a time via server mode
• Individual downloads — download each completed tileset directly from the queue

Single file uploads continue to work as before with the existing flow.

Rate Limit Feedback

The API now returns rate limit headers on all responses, and the frontend displays warnings when you're approaching limits:

• X-RateLimit-Limit — maximum requests allowed in the window
• X-RateLimit-Remaining — requests remaining before limit
• X-RateLimit-Reset — Unix timestamp when the window resets

A warning banner appears when you have 3 or fewer requests remaining, showing the reset countdown.

API Changes

All rate-limited endpoints now include these headers in responses:

| Header | Description | |---|---| | X-RateLimit-Limit | Max requests per window | | X-RateLimit-Remaining | Requests left | | X-RateLimit-Reset | Window reset timestamp |

Skeleton Loading States

Loading states now show animated skeleton placeholders that match the actual UI layout, providing a smoother experience while content loads:

• Gallery & My Tilesets — skeleton card grids instead of "Loading..." text
• Tileset Detail — full page skeleton with metadata placeholders
• Compare Page — skeleton selectors and map placeholders
• Homepage — drop area skeleton while WASM initializes

Tileset Comparison View

New /compare page lets you view two tilesets side by side with synchronized pan and zoom. Useful for comparing different processing settings or versions of the same source image.

Keyboard Shortcuts

• Ctrl/Cmd + Enter — process the current image
• Escape — reset the form

Export Presets

Save your favorite tile settings (tile size, zoom range, projection) as named presets. Presets persist in localStorage and can be loaded or deleted from the dropdown.

Drag-and-Drop Improvements

The drop zone now validates file types during drag:

• Green border — valid image file, drop to upload
• Red border — invalid file type, shows "Only image files allowed"

Additional Improvements

• Service Worker — WASM assets are now cached for offline processing
• Error Boundary — graceful error handling with retry option
• Copy-to-Clipboard — toast notifications when copying URLs and code snippets
• Lazy Loading — tileset thumbnails load on scroll
• E2E Testing — Playwright test suite for critical paths

NATS JetStream Job Queue

The async tile-processing pipeline now uses NATS JetStream instead of Redis LPUSH/BRPOP for job dispatch. This brings proper delivery guarantees that were missing before:

• Durable publish — the API awaits a PubAck from NATS before returning 202, so no job is silently lost.
• Explicit ack — the worker acknowledges each message only after successful processing and S3 upload.
• Crash recovery — if the worker crashes mid-job, the unacked message redelivers automatically after a 10-minute ack_wait timeout. The S3 upload is preserved because cleanup only runs post-ack.
• Retry with backoff — transient failures trigger redelivery with escalating delays (30 s, 2 min, 5 min, 10 min), up to 5 attempts.
• Dead-letter queue — messages that exhaust all retries are terminated and captured in a TILEFORGE_DLQ stream for inspection.

Redis remains in use for rate limiting and real-time progress tracking — only the job queue moved to NATS.

New Environment Variable

| Variable | Default | Description | |---|---|---| | NATS_URL | nats://127.0.0.1:4222 | NATS server connection URL |

Docker Compose

A new nats service (nats:2-alpine with JetStream enabled) is included in docker-compose.yml. Monitoring is available on port 8222.

PMTiles Range-Request Preview

Tile sets with PMTiles output can now be previewed directly in the browser using range requests against presigned S3 URLs. No need to download the full file — the map viewer streams tiles on demand via the PMTiles protocol.

jsonwebtoken v10

Upgraded the Rust API to jsonwebtoken v10 with the new Validation builder API. Required spec claims (sub, exp) are now explicitly declared for stricter token verification.

Select & Tooltip UX

• Projection and tile-size selects now use Radix Select with proper keyboard navigation and a visible chevron indicator.
• Tooltips on download and visibility-toggle buttons provide clearer affordances.

API Key Authentication

Bearer tokens starting with tf_ are now recognized as API keys in addition to JWTs. You can also pass your API key as a ?key=tf_... query parameter for simple integrations.

TeeWriter & Image Dimensions

• The worker now writes ZIP and PMTiles output in a single pass using TeeTileWriter, halving I/O for every job.
• Original image width and height are stored alongside each tile set for future layout features.

Min Zoom Control

Users can now set a minimum zoom level when processing tiles, reducing output size for large images where low zoom levels aren't needed.