Skip to content

Latest commit

 

History

History
875 lines (688 loc) · 66.8 KB

FEATURES.md

File metadata and controls

875 lines (688 loc) · 66.8 KB

Feature Reference

This reference describes the current local-first workflow. Implemented features are not a claim of release, physical-device or accessibility qualification. See the release gate ledger.

Your maps to the table

Start in Your maps to create, import, search, duplicate or reopen a project. Create map offers a sample, generation, blank map or image-tracing starting point with a preview before Use this map. It opens on Start blank; Explore a sample and Open a sample open on the sample list. Imports and samples create separate projects, keeping the current saved project. Library names, tags, Archive and Trash are local to this browser and origin, not an online account. Permanent deletion is explicit and cannot be undone.

In Edit, use Build, Decorate and Look, with Levels, Fog & sight, Notes, Encounter and Map info alongside them. Inspect object and Add or select by coordinates provide alternatives to canvas dragging. Apply commits a property draft as one undo step; Cancel or Escape discards it.

Wait for Saved on this device, review Player preview, then choose Prepare session. Session actions and backups have different scope from authored projects; see sessions and player display and saving and recovery.

Everything you can do

If you want the full tour in one place, this is it. Dungeon Mapper starts fast, then keeps unfolding as your map gets more ambitious. Every tool below is here to help you go from rough sketch to table-ready encounter without bouncing between five different apps.

  • Consistent interface icons - 32 original SVG line icons accompany navigation, project actions, save/offline status, export choices and player-display controls. Icons scale with interface text, inherit control colors and do not replace accessible names. Map symbols and token artwork are separate.
  • First-use illustrations - small original Folio scenes accompany the empty map collection, private backup guidance, session preparation and blank local player display. These are decorative drawings, not project previews, storage status or interactive controls.
  • Grid editor - guided creation accepts 10-100 tiles per axis; Project settings offers geometry sizes from 8 to 128 and preserves a loaded map's current dimensions. These controls are not a measured performance support limit.
  • Tile size - selectable tile size (12, 16, 20, 24, 32 px), default 20 px
  • 20 paintable tile types - Floor, Wall, Door (H/V), Secret Door, Locked Door (H/V), Trapped Door (H/V), Portcullis, Archway, Barricade, Stairs Up/Down, Water, Pillar, Trap, Treasure, Start, plus project-scoped custom tiles (use the Erase tool to clear a tile back to empty)
  • Themes - Dungeon Folio plus 13 legacy modes: Castle, Dungeon, Starship, Alien World, Lost Civilization, Old West, Steampunk, Wilderness, Cyberpunk, Post-Apocalypse, Modern City, Pirate and Desert (see Preset Modes below)
  • Custom themes - project-scoped custom theme builder with editable tile colors, labels, grid color, and optional uploaded tile graphics (see Custom Themes below)
  • Multi-level dungeons - create multi-floor projects with level tabs, stair links between levels, per-level undo history, and double-click stair navigation (see Multi-Level Dungeons below)
  • Sample maps - bundled encounters across all 13 themes, Folio art references and three authored launch maps: The Lantern Crypt, Alder Crossing and Kestrel Docking Bay. Launch previews are player-safe; opening a sample creates a fresh editable project (see Sample Maps below)
  • Themed canvas - per-theme grid colors, deterministic tile color jitter, and wall depth/shadow effects for a rich, organic look; warm parchment background with pixel-sharp rendering
  • Print mode - monochrome material patterns, connected wall contours, drawn doors/stairs and shape-coded token affiliations; includes A4/Letter planning and a quarter-inch overview scale
  • Shared navigation - Build, Decorate, Look and task-specific destinations replace the former Rail/Tabs layout choice
  • Command palette - fuzzy-search overlay (Ctrl/Cmd+K) for quick access to tools, themes, file actions, view toggles, and canvas commands
  • Selection inspector - contextual properties for tokens, notes, stamps, rooms, rivers and tile regions; Map info is a separate destination rather than an always-open empty inspector
  • Generate Hub - unified generation window (G shortcut) with tabbed Generate and Samples panels, archetype filtering, and all generation controls in one place
  • Stamps - the original 196-stamp catalog plus 24 versioned Dungeon Folio furnishings and custom stamp upload (PNG/SVG/JPEG/WebP, 2 MB limit); place, move, rotate, flip, scale, adjust opacity, lock, and z-order stamps on the canvas (see Stamps below)
  • Wall, path & river drawing - free-form wall segments snapped to grid edges (W), smooth path/road lines (Shift+W), and editable flowing river vectors (U) with erase modes; independent of tile grid until rivers rasterize to water (see Wall, Path & River Tools below)
  • Scene/room templates - save a selection of tiles, notes, and stamps as a reusable template; apply templates to stamp pre-built rooms onto any map (see Scene Templates below)
  • Drawing tools - Paint P, Erase E, Flood Fill F, Add Note N, Line L, Rectangle R, Select S, Line-of-Sight / FOV O, Measure M, Light Source I, GM Draw D, Wall W, Path Shift+W
  • GM drawing tools - private freehand annotations with dashed rendering; excluded from player projections and player-audience exports (D shortcut)
  • Copy / Paste / Cut - drag a region with the Select tool (a drag always selects tiles, even across rooms, tokens and stamps; a click picks the object under the pointer), then Ctrl+C to copy, Ctrl+X to cut, Ctrl+V to paste tiles and notes at the selection origin with a live preview overlay
  • Procedural map generation - the Generate Hub (G) opens a unified window with four algorithms (Rooms & Corridors, Open Terrain, Cavern, Village), a deterministic seed, a density slider, per-generator tile-mix sliders, corridor strategy and shape controls, optional theme room labels with procedural names, and an opt-in Generate into selection mode that stamps a generated map into an active selection rectangle without disturbing the rest of the map (see Map Generation below)
  • Prepare / Run / player display - separately saved play progress and a read-only second window in the same browser. Fog setup (formerly DM view) is where you set a map's starting fog; it is not a player-safe surface (see sessions and player display)
  • Fog of war - per-cell hidden / revealed flags with a Defog brush, Reveal V / Hide H drag-rectangles, Reset Fog (re-cover the map), Clear Fog (reveal everything), an optional GM 🌫 Show Fog preview overlay, fog edge feathering, and Dynamic Fog mode that auto-reveals cells visible from player tokens with 3-state rendering (hidden / explored / visible)
  • Tokens with icon library - drop Player, NPC, and Monster tokens (small 1×1, medium 2×2, large 3×3) onto the map with a searchable icon picker (legacy icons plus twelve opt-in Folio silhouettes); Move Token to drag, Remove Token to delete
  • Initiative panel - a turn-order list with selectable entries, visible Up/Down controls, Alt+Arrow and drag reordering, inline renaming and Clear (see Initiative below)
  • Shape / area markers - place colored shape overlays (circle, square, diamond) on the map for marking spell areas, hazard zones, and tactical effects; 8 color options with adjustable radius (see Markers below)
  • Measure tool - measure distances between cells in four shapes (ruler, circle, cone, line) with configurable feet-per-cell scale (default 5 ft); overlays are drawn in cyan with a distance readout pill (see Measure below)
  • Light sources - place light sources on the map from preset profiles (torch, lantern, magical, custom) with adjustable radius and color; integrates with dynamic fog to illuminate cells within range (see Light Sources below)
  • Background image import - import a PNG/JPG as a background layer behind the tile grid for tracing existing battlemaps; adjustable opacity, scale, and position (see Background Image below)
  • Player annotations - freehand pen with eight color swatches and Thin / Medium / Thick brush widths; per-stroke eraser and a Clear All button
  • Zoom & pan - + / - / Reset / Fit controls along the bottom of the map; right-click drag (or long-press on touch) to pan; mouse-wheel zoom while holding Shift (or with Caps Lock on); pinch-to-zoom and two-finger pan on touch devices; on-canvas HUD displays current zoom level and cursor coordinates
  • Undo / Redo - up to 50 steps per level (Ctrl+Z / Ctrl+Y or Ctrl+Shift+Z)
  • Room notes - numbered annotations with keyboard-editable labels and multiline descriptions. Player preview uses explicitly published public fields in known geography, not the DM's private text.
  • Device saving - debounced project writes to IndexedDB, visible save health, previous-save recovery and retained legacy migration originals. Failed or pending writes are not saved work.
  • Line-of-Sight / FOV - click any cell to visualize which cells are visible from that point, with walls blocking the view; click the same cell again to clear (O shortcut)
  • Export / Import - one intent-first dialog for private project backups, player-safe PNG/SVG images, bounded print pages and grid-aligned images for other tools
  • Interface text size - Project menu > Project settings offers 75%, 100%, 125%, 150% and 200%; this changes controls, not geometry, export resolution or native browser zoom
  • Preserve-tiles toggle - when enabled (toolbar 🎨 Preserve), switching themes keeps already-painted tiles in their original style so you can mix terrain styles from multiple themes on a single map
  • Art style presets - 5 built-in visual presets (Classic, Hand-Drawn, Painted, Minimal, Print) that configure all four art layers in one click; tweak individual layers to create a Custom style (see Art System below)
  • Paper texture - procedural background texture with 5 patterns (parchment, linen, canvas, watercolor, marble), per-theme tints, adjustable opacity/grain/vignette
  • Edge blending - softens tile boundaries with 3 styles (dither, smooth, stipple) for organic terrain transitions
  • Hand-drawn mode - 3 rendering styles (sketchy, pencil, ink) that add wobbly grid lines, cross-hatch shading, and bold boundary strokes for a hand-crafted look
  • Lighting & atmosphere - ambient occlusion in wall corners, drop-shadows under stamps, and day/night/dusk color grading for mood and depth
  • Responsive controls - smaller-screen tool menus and contextual sheets, with touch gestures implemented; physical mobile/touch/pen qualification remains open
  • Progressive Web App - installable app with visible offline cache readiness and explicit, save-aware updates

Preset Modes

Preset modes are where the map starts feeling alive. The idea is simple: keep the structure of your dungeon, then let you change the mood in seconds. You can audition settings, swap aesthetics for a new campaign, or make a print-friendly version without repainting the whole thing.

Theme modes

Every theme keeps the same underlying tile logic, but gives it a different visual language. That means your layout stays stable while the story around it changes: stone halls become neon corridors, wilderness trails become pirate decks, and so on. If you want to mix styles on purpose, the Preserve toggle lets already-painted tiles hang onto their original look while the rest of the map updates around them.

Theme Setting Tile flavor (Floor / Wall / Door / Secret Door / Locked Door / Trapped Door / Portcullis / Archway / Barricade / Water / Pillar / Trap / Treasure / Start)
Alien World Otherworldly biological landscape Spore Bed / Fungal Wall / Membrane / Hidden Burrow / Locked Membrane / Trapped Membrane / Chitin Gate / Nerve Arch / Growth Barricade / Acid Pool / Crystal Spire / Spore Burst / Crystal Cluster / Landing Site
Castle Aboveground stone keep Stone Tile / Battlement / Oak Door / Hidden Passage / Locked Oak Door / Trapped Oak Door / Castle Portcullis / Stone Archway / Wooden Barricade / Moat / Column / Murder Hole / Royal Hoard / Great Hall
Cyberpunk Neon-lit street grids Street / Barrier / Shutter / Cloaked Panel / Locked Shutter / Trapped Shutter / Security Gate / Neon Arch / Debris Barrier / Acid Pool / Terminal / Turret / Chip Cache / Spawn
Desert Sun-baked sands and tombs Sand / Sandstone / Tomb Door / Hidden Chamber / Locked Tomb Door / Trapped Tomb Door / Sand Gate / Desert Arch / Sand Barricade / Oasis / Cactus / Quicksand / Relic / Caravan
Dungeon (default) Subterranean crawl Flagstone / Stone Wall / Iron Door / Secret Door / Locked Iron Door / Trapped Iron Door / Iron Portcullis / Stone Archway / Wooden Barricade / Underground Pool / Pillar / Trap / Treasure / Entrance
Lost Civilization Ancient temple complex Flagstone / Carved Wall / Stone Slab / Hidden Glyph / Locked Carved Door / Trapped Carved Door / Stone Portcullis / Temple Arch / Stone Barricade / Reflecting Pool / Pillar / Cursed Glyph / Sarcophagus / Obelisk
Modern City Contemporary urban streets Sidewalk / Building / Doorway / Hidden Door / Locked Doorway / Trapped Doorway / Security Gate / Open Entry / Road Barrier / Fountain / Lamp Post / Manhole / ATM / Bus Stop
Old West Frontier towns and saloons Dirt / Plank Wall / Saloon Door / Hidden Passage / Locked Plank Door / Trapped Plank Door / Jail Gate / Open Doorway / Wooden Barricade / Water Trough / Post / Bear Trap / Gold / Entrance
Pirate Tall ships and hidden coves Deck / Hull / Hatch / Smuggler Hatch / Locked Hatch / Trapped Hatch / Chain Gate / Open Port / Cargo Barricade / Bilge / Mast / Cannon / Booty / Anchor
Post-Apocalypse Ruined wastelands Rubble / Ruins / Barricade / Hidden Stash / Locked Barricade / Trapped Barricade / Chain Gate / Ruined Arch / Scrap Barricade / Toxic Pool / Rubble Pile / Landmine / Supplies / Shelter
Starship Deep-space vessel interiors Deck / Bulkhead / Blast Door / Hidden Hatch / Locked Blast Door / Trapped Blast Door / Blast Shield / Open Bulkhead / Emergency Barrier / Coolant / Support / Laser Grid / Data Core / Airlock
Steampunk Industrial gear-and-steam works Iron Plate / Gear Wall / Valve Door / Concealed Hatch / Locked Valve Door / Trapped Valve Door / Steam Gate / Pipe Archway / Gear Barricade / Steam Pipe / Piston / Pressure Plate / Contraption / Engine
Wilderness Outdoor overland maps Grass / Trees / Gate / Hidden Path / Locked Gate / Trapped Gate / Fence Gate / Natural Arch / Log Barricade / River / Boulder / Snare / Cache / Camp

Print mode

Print mode uses white paper, black map symbols and neutral charcoal furnishings. Flagstone, wood, earth, rock and water have distinct patterns; wall contours join without internal outlines. Plain doors use drawn H/V labels; lock/trap symbols keep clean outer orientation posts. Stairs use drawn arrows. Party, NPC and hostile tokens have different frames even without color, including legacy tokens. Emoji-only markers use a label initial in print.

Choose Export > Print for the table > Ink-friendly map styling. The 0.25-inch cell option fits each 24 x 24 launch sample onto one A4 or Letter sheet as a six-inch square overview. Choose one-inch cells for miniatures and download the overlapping pages. Use 100% / actual-size printing, not fit to page. Player output still applies fog, discovery and publication rules before drawing. User-supplied images and annotations should always be reviewed before sharing; map styling cannot remove secrets baked into artwork.

Custom Themes

If the built-in themes get you 90 percent of the way there, custom themes handle the last 10 percent that makes a map feel like yours. You can start from an existing style, tweak the palette, rename the tile language, and even bring in your own graphics without giving up the editor's built-in behavior.

  • Base theme - custom themes inherit from one of the 13 built-in themes, getting its tile rendering and grid color as defaults.
  • Editable properties - change the theme name, grid line color, and per-tile colors and labels for all built-in tile types.
  • Custom tile palette - add user-defined tile entries with a label, semantic base behavior (floor, wall, door, etc.), color fallback, and optional uploaded PNG/JPEG/WebP graphic stored as a data URL.
  • Base behavior - custom tiles inherit line-of-sight blocking, dynamic fog interaction, light visibility, and print-mode fallback from their assigned base behavior.
  • Persistence - custom themes round-trip through JSON export/import and IndexedDB auto-save. They are project-scoped, so each project can have its own theme customizations.

Multi-Level Dungeons

Some maps want to sprawl. Multi-level support keeps those bigger projects manageable, so stairs actually connect places, each floor keeps its own history, and hopping between levels feels natural instead of fiddly.

  • Level tabs - a tab bar below the header with controls to add, rename (double-click), duplicate, delete, and drag-to-reorder levels.
  • Per-level undo - each level maintains its own 50-step undo/redo history.
  • Stair links - use the Stair Link tool (K) to connect stairs-up and stairs-down tiles between levels. Click a stairs tile to set the source, switch levels, then click the destination stairs to create a link.
  • Link badges - linked stairs show blue "L#" badges on the canvas indicating the destination level. Level tabs show a 🔗 badge with the link count.
  • Stair navigation - double-click a linked stairs tile to jump to the destination level and auto-center the viewport on the arrival cell.
  • Link management - the STAIR LINKS toolbar section provides the Link tool, a Clear Links button, and a link count display. Links auto-reindex when levels are deleted, duplicated, or reordered.
  • Keyboard shortcuts - PageUp / PageDown to cycle between levels; K to activate the Stair Link tool.
  • Full round-trip - multi-level projects export/import as JSON with all stair links preserved. IndexedDB auto-save handles legacy single-map migration automatically.

Sample Maps

Choose Your maps > Open a sample to preview an encounter before creating a fresh editable project. The launch trio is The Lantern Crypt, Alder Crossing and Kestrel Docking Bay. Each has a clear arrival, focal point, traversable encounter space, public scene notes and separate DM instructions. Their creation previews show only player-safe content; the editable copy includes the private encounter. Existing generated samples and Folio art references remain available, including through Generate Hub.

Every one of the 35 bundled samples states its role, purpose and usage in both the guided Choose a sample path and Generate Hub's Sample Maps gallery. The 26 generated examples are adaptable starting points, not completed adventures. Six art references demonstrate materials, furnishings or tokens, not encounter balance. The three launch encounters have authored goals and approaches. Read that distinction before choosing a sample.

New copies retain the guide at the start of the first note's DM-private description on each level, followed by the original note text. It travels with project saves and private JSON backups, but is not added to public note fields or player exports. Existing saved copies are not rewritten.

The Lantern Crypt asks the party to recover the memorial's brass key and return to the lantern stair; the watch and concealed cache offer optional interaction. Alder Crossing asks the party to reach the eastern trail together, dealing with the keeper and avoiding escalation with the lookout wolf.

Kestrel Docking Bay is a rules-neutral rescue: release a stranded engineer from sealed crew quarters and escort them to the aft airlock. DM notes offer a quiet port-control release or a cargo-tool bypass with an optional security complication. The coolant core is not a countdown. Door symbols and notes do not automate locks, movement restrictions, alarms or combat.

Sessions and player display

Prepare session reads the saved source project. Review public content, starting visibility and sight sources, acknowledge the readiness checklist, then choose Start session. Manual-fog play remains possible without sight sources; do not assume a newly created or imported map starts hidden. New maps start with fog off. When fog is off, Prepare says the whole level is visible, shows a warning and offers Turn on fog in Edit, which opens Fog & sight. The acknowledgement then confirms that players will see the whole level.

Run has reveal/hide, a defog brush, token movement, measurement, line of sight, area markers, pings, a dynamic fog switch, encounter turns and session checkpoints. With Reveal or Hide, click one cell or drag across an area to change it in one undoable action; the cell fields apply one cell from the keyboard. Defog brush wipes fog off cell by cell along a drag, as one undoable action. The private Run map shades cells that players cannot see, using the same projection as the player display.

Measure takes a start and an end cell (two clicks, a drag, or the cell fields). Distance reports the straight-line length and the count in squares and feet; Circle, Cone and Line draw a spell or ability template sized by that count, with a 90 degree cone and a one-cell-wide line. Line of sight highlights the cells visible from a chosen cell; walls, pillars and secret doors block it. Measurements and line of sight are drawn on the private Run map only. They are never saved or sent to the player display.

Place marker and Remove marker add and remove circle, square or diamond area markers as undoable session actions. Players see a marker on the shown level once its whole area is known to them. Dynamic fog switches party sight on or off for the inspected level during play, and Forget explored areas clears what the party has already explored. Both need fog to be on for the level. Changes save in a separate session record; the authored source map stays unchanged. Inspect DM level does not change the published level. Show this level does. Pause / blank now blanks the local display.

Open player display opens a read-only second window in the same browser using local communication. Allow site popups if blocked, or use Player preview. The display starts blank and must be explicitly shown again after reconnection. It is not an authenticated remote player service or a URL another device can use to join.

Leave and resume later keeps the saved session. End session > Save session progress keeps play progress separately. Discard changes since session start restores the session's source checkpoint, not the authored project. Both end choices retain the pre-end state in a last recovery slot.

Player preview and player-audience images filter geography, discovery, hidden tokens and explicitly published public note fields. DM note labels and descriptions are private even when a note is published. Review custom artwork for secrets baked into images. The editor, Library thumbnails and Fog setup are trusted DM surfaces; do not share their whole browser window.

Fog of war

Prepare fog and sight in Edit, then inspect Player preview before showing the map. Starting fog depends on the creation path or imported project, not a universal hidden default.

  • Defog - freehand brush; drag across the map to wipe fog away cell-by-cell.
  • Reveal V / Hide H - drag a rectangle of cells to expose or re-cover them.
  • Reset Fog - re-fog the entire map (hide every cell).
  • Clear Fog - reveal the entire map (clear all fog).
  • Dynamic - toggle auto-reveal mode. When enabled, cells visible from any player token are automatically revealed using line-of-sight. The fog uses 3-state rendering: hidden (opaque, never seen), explored (dimmed, previously visible but no longer in line-of-sight), and visible (clear, currently in line-of-sight of a player token). The explored grid persists with the map.
  • Reset Explored - (appears when Dynamic is enabled) clears all explored memory so previously seen cells return to fully fogged.

Player outputs remove unknown geography and private content before rendering. The editor's Show Fog option is a DM inspection aid, not the publication boundary. Revealing geography alone does not publish a note's private text.

Drawing pen

Fog setup includes a player-annotation pen operated by the DM. The separate player display is read-only and does not expose drawing controls.

  • Draw / Erase - sketch over the map with the pen, or click an individual stroke to remove it.
  • Pen colors - eight preset swatches (red, orange, yellow, green, blue, purple, near-black, white).
  • Brush widths - Thin, Medium, and Thick.
  • Clear All - remove every player-drawn stroke from the map at once.

Tokens

Tokens are meant to be fast to place, easy to read, and flexible enough for a real encounter. Drop in heroes, NPCs, and monsters, give them icons, then move them around without breaking the flow of the session.

  • Player, NPC, and Monster tokens. Monster tokens come in three footprints - Monster S (1×1), Monster M (2×2), and Monster L (3×3) - for varying creature sizes.
  • Icon picker - when placing a token, a searchable icon picker opens with legacy categories (Characters, Weapons, Magic, Creatures, Items, Environment) and an opt-in Folio tokens category. Choose an icon, choose No Icon for the letter fallback, or Cancel to abandon placement.
  • Folio tokens - twelve tiny troublemakers, one very unlucky dungeon. Warden, Wayfinder, Drake, Ranger, Duelist, Arcanist, Sunkeeper, Brute, Wolf, Owl, Spider and Ooze each work with all three affiliation frames. Kind selects the party shield, NPC round seal or hostile hexagon; shapes and marks remain distinct in print. Open The Crooked Company for the full furnished catalog, or The Lantern Watch for the original small scene. Legacy icons stay unchanged. The complete v1 catalog and one-line copy received owner approval on September 14, 2026.
  • Move Token - click and drag a token to relocate it.
  • Remove - click a token to delete it.

Authored tokens, fog and annotations are included in project saves and backups. Token/fog changes made in Run belong to the separate session, not the source project's JSON backup.

Initiative

The initiative panel keeps the tactical state tied to the map instead of floating off in a separate app or notebook. Place tokens, keep turn order nearby, and jump from list to canvas without losing your place.

In Edit mode the panel is fully editable:

  • Reorder with the visible Up/Down buttons, drag an entry, or focus its selection button and use Alt+Up / Alt+Down.
  • Rename an entry inline. Enter saves, Escape cancels, and focus returns to Rename. Leaving the field also saves a nonblank name.
  • Clear wipes the initiative list (tokens themselves stay on the map).

The Fog setup list is read-only, but that local fog-aware view is not a player-safe display. Use Player preview or the separate local player display for audience-filtered information.

The initiative order is persisted with the map (auto-save and JSON export). During Run, Next/Previous turn operates on separately saved session progress. The current round and turn are exposed in a polite live region.

Markers

Markers are the quick visual language for everything temporary: spell areas, danger zones, objectives, and all the other things players ask about five times in a round. They stay readable without covering up the map underneath.

  • Place - click on the map to drop a colored shape marker at the cursor position.
  • Remove - click an existing marker to delete it.
  • Clear All - remove every marker from the map.
  • Shape - choose between Circle, Square, and Diamond shapes.
  • Color - pick from 8 preset colors (red, orange, yellow, green, blue, purple, pink, dark grey).
  • Radius - adjust the marker size from 1 to 10 tiles using the slider.

Markers are rendered with transparency so the underlying map remains visible. They appear above annotations but below tokens in the rendering order. A ghost preview follows the cursor when the Place tool is active. Markers are persisted with the map and included in PNG and SVG exports.

Measure

The measure tool is built for the constant, tiny rules questions that happen during play. Drag, check the distance, answer the question, and move on. No menus, no math detour.

  • Measure tool (M) - click and drag on the map to measure the distance between two cells.
  • Shape - choose between four measurement shapes:
  • Ruler - straight-line point-to-point distance.
  • Circle - radial area from the origin point.
  • Cone - conical projection from the origin.
  • Line - linear path from the origin.
  • Scale - set the feet-per-cell value (default 5 ft, range 1–100) to match your game system's grid scale.

Measurements are drawn as cyan overlays with a pill-shaped distance readout. Distances use Chebyshev (king-move) distance, matching the D&D 5e diagonal movement convention. Measurements are ephemeral - they aren't saved with the map.

Light Sources

Lighting isn't just decoration here. Light sources feed directly into dynamic fog, which means torches, lanterns, and magical glows can actively shape what the table sees. It's a small detail that makes exploration feel much more alive.

  • Place (I) - click a cell to drop a light source at that position.
  • Remove - click an existing light source to delete it.
  • Presets - choose from four profiles: Torch (warm orange, 4-cell radius), Lantern (amber, 6-cell radius), Magical (violet, 8-cell radius), or Custom.
  • Radius - adjust the light radius from 1 to 20 cells.
  • Color - pick from 8 preset colors (torch orange, lantern amber, pale yellow, white, magical violet, arcane green, ice blue, infernal red).

Light sources emit a soft glow overlay on the canvas and integrate with dynamic fog of war - cells illuminated by a light source are treated as visible when computing fog visibility. Light sources are persisted with the map (auto-save and JSON export).

Copy, Cut & Paste

When a room layout works, you should be able to reuse it. The Select tool's clipboard actions make it easy to duplicate wings, shift encounter areas around, or save yourself from repainting the same geometry by hand.

  • Copy (Ctrl+C) - copies all tiles and notes within the selection rectangle to an internal clipboard.
  • Cut (Ctrl+X) - copies the selection and then erases the original tiles.
  • Paste (Ctrl+V) - stamps the clipboard contents onto the map at the selection's top-left corner (or the map origin if no selection is active). A translucent dashed preview outline follows the cursor while the clipboard has content.

Notes within the selection are remapped to fresh IDs on paste to avoid collisions. Per-tile theme overrides (from the "Preserve" toggle) are preserved through copy/paste.

Background Image

Background images are there for the moments when you want to trace over an existing battlemap, line up a sketch, or use outside art as a guide. It's a practical bridge between freehand planning and the structured tile grid.

  • Import - opens a file picker for PNG, JPEG, or WebP images. The image is loaded as a data URL and stored with the map.
  • Remove - clears the background image.
  • Opacity - controls the image transparency (0%–100%) so the grid and tiles remain visible on top.
  • Scale - resizes the image (10%–500%) relative to its natural size.
  • Offset X / Y - repositions the image in tile units (–50 to +50) to align it with the grid.

The background image is hidden by print styling. Other image exports use the export renderer, not a capture of the editor canvas. Player exports omit raw backgrounds while any geography remains unknown. Embedded image data is retained in private project saves and JSON backups.

Stamps

Stamps are how you add flavor without turning every detail into tile work. Furniture, hazards, props, creatures, clutter, little bits of scene dressing, they all sit on top of the map so you can make spaces feel inhabited without sacrificing clean layout control.

Placing & managing stamps

  • Place - select a stamp from the stamp picker, then click on the canvas to place it. Stamps are tile-aligned.
  • Move - drag a placed stamp to reposition it.
  • Select - click a placed stamp on the canvas to select it; a yellow dashed highlight appears.
  • Transform controls - the Selection inspector exposes rotation, flips, scale, opacity, lock, layer ordering and deletion. Apply unlocking before changing a locked stamp's transform.
  • Keyboard shortcuts - Shift+R rotate 90 degrees clockwise, Shift+H flip horizontal, Shift+Y flip vertical, Delete remove.

Per-theme filtering

The stamp picker can stay focused on the current theme or open up the whole library. That keeps browsing quick when you're in the zone, but still lets you break the rules whenever the map wants something weird.

Dungeon Folio furnishings

Choose Dungeon Folio v1, then Decorate > Theme for 24 original furnishings: tables and seating, beds and storage, chapel and dungeon props, vegetation and camping gear. The new The Wayfarer's Refuge sample combines the full set in a 24 x 24 hall, chapel and campsite. The Keeper's Hall retains the original eight-piece composition.

Each piece has an authored starting scale, editable rotation/flips/opacity, consistent shadows and a print companion. Existing artwork and saved IDs are unchanged. Furnishings are decoration: campfires and braziers do not emit light, and tents, plants or furniture do not block movement or sight. Add actual light sources or map geometry separately when needed.

Custom stamp upload

If the built-in library doesn't have the exact prop you want, bring your own. Custom stamps live with the project, so the weird altar, custom logo, or hand-drawn boss marker stays attached to the map when you export and re-import it later.

Wall, Path & River Tools

These tools sit in a sweet spot between strict grid editing and freeform drawing. Use them when you want cleaner structure than a paint brush gives you, but more expressive shapes than a tile-by-tile workflow would allow.

  • Wall tool (W) - draw wall segments that snap to grid-edge intersections. Click to add vertices; the segment completes when you press Escape or start a new segment. Walls render as solid lines on top of the tile layer.
  • Wall Erase - click near a wall segment to remove it.
  • Path tool (Shift+W) - draw smooth freeform path/road lines using fractional coordinates for organic curves. Paths render with rounded caps and joins.
  • Path Erase - click near a path segment to remove it.
  • River tool (U) - drag across the canvas to draw a flowing vector river. Rivers stay editable via their control points, then rasterize to water tiles with flow direction metadata.
  • River settings - choose stroke color, width (stream/river/wide/broad), and semantic type (water, lava, or underground stream). River polish adds theme-aware bank tiles plus source and mouth markers.
  • River editing - drag control points to reshape a river, right-click a control point to remove it, use Erase Rivers to delete a whole river vector, or Clear All to remove every river from the level.
  • Contextual settings - Build provides wall, path and river controls; the Selection inspector edits placed room/river geometry.
  • Clear all - buttons clear wall segments, path segments, or river vectors from the current level.

Walls, paths, and rivers are persisted with the map and included in all exports. They coexist with floor/wall tiles and are rendered above the tile layer but below stamps and tokens. Rivers also contribute rasterized water, bank, flow-direction, and endpoint metadata used by the canvas and export renderers.

Scene Templates

Scene templates are the payoff for building reusable encounter pieces. Save a room once, drop it into future maps whenever you need it, and slowly build your own library of reliable dungeon chunks.

  • Save template - select a region, then open Project menu > Scene templates or find it in Commands. Templates capture tiles, notes and stamps within the selection.
  • Apply template - choose a saved template from the dialog and stamp it onto the map at the current selection position.
  • Manage - rename or delete templates from the dialog.
  • Persistence - templates are project-scoped and round-trip through JSON export/import and IndexedDB auto-save.

Navigation Rail & Layout

One shared navigation serves Build, Decorate, Look, Levels, Fog & sight, Notes, Encounter and Map info. Commands and Project menu expose the same actions, including reasons when an action is unavailable. The former LAYOUT selector and Draw/Tactical/Advanced tabs are no longer the navigation model. On narrow screens, Tools expands the sidebar and All actions opens the action menu. A selection opens its contextual sheet rather than a permanent inspector column.

Art System

The art system is one of the nicest parts of the app because it treats presentation as layers, not a one-way commitment. You can dial the map toward crisp, sketchy, painterly, moody, or printer-friendly looks, then keep tweaking without touching the actual tile data underneath.

Art style presets

If you want a fast mood shift, presets do the heavy lifting. They bundle the four art layers into ready-made looks, then step aside so you can keep fine-tuning once a preset gets you close.

Preset Paper Edges Hand-Drawn Lighting Description
Classic Parchment Dither - AO Subtle parchment texture, dithered edges, ambient occlusion - the default look
Hand-Drawn Canvas - Sketchy AO Canvas texture, wobbly sketchy lines, cross-hatch shading
Painted Watercolor Smooth Ink Dusk grading Watercolor washes, smooth blending, bold ink outlines, warm dusk tint
Minimal - - - - Clean digital look - all art layers disabled
Print Linen Stipple Pencil AO Linen texture, stipple edges, pencil lines - optimised for B&W print output

Selecting a preset instantly applies its settings. If you manually adjust any individual layer afterward, the preset changes to Custom so you know it's been tweaked. All presets work with every theme - the art layers composite on top of the theme's base tile art.

Paper texture

Paper texture gives the whole map a surface to live on. It's subtle, but it does a lot of work in making a digital grid feel more like something you could have unfolded on the table.

  • Pattern - choose from 5 textures: parchment, linen, canvas, watercolor, marble.
  • Opacity - blend strength of the texture layer (0–1).
  • Grain - amount of fine noise added to the texture.
  • Vignette - darkening at the edges of the map for a framed look.
  • Theme tint - each theme applies its own color tint to the paper (e.g., warm amber for Castle, cool grey for Starship, olive for Wilderness).

Edge blending

Edge blending softens that hard cut between terrain types, which matters more than you might think. A little blur, dither, or stipple goes a long way toward making the map feel organic instead of assembled from obvious blocks.

  • Style - dither (scattered pixels), smooth (gradient fade), or stipple (dot pattern).
  • Intensity - how far the blend extends from the tile edge.
  • Opacity - overall strength of the blend layer.

Hand-drawn mode

Hand-drawn mode is for when you want the map to feel made, not rendered. It introduces just enough wobble and texture to fake that penciled, inked, sketched-at-midnight energy.

  • Style - sketchy (wobbly offset lines), pencil (fine textured strokes), or ink (bold confident outlines).
  • Wobble - amplitude of line waviness.
  • Line width - stroke thickness.
  • Opacity - overall strength of the hand-drawn overlay.
  • Honors print mode - renders in black & white when print mode is active.

Lighting & atmosphere

Lighting and atmosphere are the finishing touches that give the map depth. They're also fully optional, which is the point: add mood when you want it, keep things clean when you don't.

  • Ambient occlusion - darkens inner corners where wall tiles meet, simulating realistic shadow gathering. Adjustable intensity and radius.
  • Stamp shadows - soft drop-shadows beneath placed stamps for visual lift. Adjustable opacity and offset.
  • Color grading - a scene-wide tint overlay in four modes: day (warm daylight), night (cool blue), dusk (golden amber), or none. Adjustable intensity.
  • Overall opacity - master control for the entire lighting layer.
  • Disabled in print mode by default.

Export integration

Exports use the current map's art settings. The unified Export dialog provides audience, format, resolution and print styling choices with a preview; it does not expose the former independent per-layer export toggles.

Map Generation

For first use, choose Your maps > Create map > Generate a map and preview before committing. Inside the editor, Build > Generate or G opens Generate Hub for advanced options and generation into a selected region.

  • Generate - procedural map generation with four algorithms and full parameter controls.
  • Samples - bundled sample projects and Folio references with archetype filtering, plus three authored launch encounters.

Generated maps use the standard tile types (Floor, Wall, Door, Secret Door, Locked Door, Trapped Door, Portcullis, Archway, Barricade, Stairs, Water, Pillar, Trap, Treasure, Start) so the result is rendered in whatever theme the map currently uses - switching the theme afterwards restyles the generated map without losing any tile data.

Algorithms

Each generator has a different personality. Some are great for structured spaces, some are better for organic terrain, and some are there for the moments when you need a believable settlement in a hurry.

Algorithm What it produces Default for themes
Rooms & Corridors Rectangular rooms connected by corridors with configurable routing strategy. Best for dungeons, castles, ships, and other built spaces. Dungeon, Castle, Starship, Alien World, Steampunk, Cyberpunk, Modern City, Pirate, Old West, Lost Civilization
Open Terrain Open ground scattered with obstacles, water, and standing stones. Best for outdoor / overland maps. Wilderness, Desert, Post-Apocalypse
Cavern Organic cave system carved out via cellular-automata smoothing, guaranteed to be a single connected region. (No theme defaults to this - pick it manually for any theme.)
Village A settlement with buildings, streets, and optional walls. Uses BSP partitioning for organic district layout. (No theme defaults to this - pick it manually for any theme.)

Dialog controls

  • Width / Height - advanced Generate Hub dimensions use 8-128 tiles; guided creation uses 10-100. Geometry dimensions are different from canvas zoom.
  • Generate into selection - available for eligible selection rectangles of at least 6 x 6 tiles. Preview the affected region before applying. Outside content, tokens and fog are retained; generated tiles/notes/rivers are applied in the region. Without a selection target, generation creates a separate project and keeps the saved source.
  • Density - global "how full should the map feel" multiplier (range: 0.1–1.5, default 1.0). Higher values pack in more rooms / obstacles / features; lower values produce sparser layouts.
  • Corridor style (Rooms & Corridors only) - selects the corridor routing strategy:
  • Classic L-bends - connect rooms in sequence with right-angled corridors (default).
  • Spanning tree - connect each room to its nearest neighbors via a minimum spanning tree.
  • Looping passages - spanning tree plus extra short edges to create cycles.
  • Winding passages - spanning tree with Z-shaped corridors.
  • Corridor bend (Rooms & Corridors only) - a slider controlling how straight corridors are, from winding (0) to straight (1), with the legacy default at 0.5.
  • Dungeon shape (Rooms & Corridors only) - constrains room placement to a non-rectangular mask. Eight shapes available: Rectangle (default), Circle, Diamond, Cross, L-Shape, T-Shape, Hexagon, Octagon.
  • Dead-end pruning (Rooms & Corridors only) - slider (0–100%) that iteratively removes dead-end corridor tiles. At 0% (default) dead ends are kept; at 100% all dead-end stubs are removed.
  • Tile mix (collapsible section) - per-generator sliders for fine-tuning what gets sprinkled in. Each generator exposes its own set, e.g. Rooms & Corridors offers Treasure share, Trap / Hazard share, and Door fraction; Open Terrain and Cavern have their own. The dialog remembers the values you set per algorithm as you flip between them, and a Reset button restores the active algorithm's theme defaults.
  • Add river (supported terrain/cavern/village themes) - opt-in river generation with controls for count, width, meander, and source edge. Generated rivers are editable vector layers; high-meander rivers can spawn tributaries, underground themes use underground-stream semantics, and village roads crossing generated rivers become bridge archways.
  • Label rooms with theme archetypes - Rooms & Corridors only, and only when the active theme has a room-archetype palette (built spaces such as Castle "Great Hall", Starship "Bridge", Modern City rooms, etc.). When checked, generated rooms are auto-labeled with theme-appropriate names dropped into the side notes panel.
  • Add procedural names - visible when room labels are enabled. Appends flavor-text suffixes (e.g. "Crypt of the Crimson Veil") to room labels using per-theme word tables.
  • Seed - text seed used to make generation deterministic; the same seed + algorithm + parameters always produces the same map. Accepts decimal digits, hex (with or without an 0x prefix), or any free-form string (which is hashed). Use the 🎲 button next to the field to roll a new random seed; leaving the field blank also picks a fresh random seed at generate time.

Confirmation and undo

  • Review the preview, then choose Use this map; Cancel leaves the source unchanged.
  • Full-map generation and sample loading create separate projects, not an undoable replacement of the old project.
  • Selection generation is one undoable regional change. It can replace notes inside the region; it does not replace the whole project.

Keyboard Shortcuts

Once you spend a few minutes with Dungeon Mapper, shortcuts start doing a lot of the heavy lifting. The in-app overlay is generated from the same registry as the bindings themselves, so the reference stays honest and up to date.

Tools

Shortcut Action
P Paint tool
E Erase tool
F Flood Fill tool
N Add Note tool
L Line tool
R Rectangle tool
S Select tool
V Reveal fog (drag-rectangle, fog must be enabled)
H Hide fog (drag-rectangle, fog must be enabled)
O Line-of-Sight / FOV tool - click a cell to see what is visible from it
M Measure / Distance tool - click and drag to measure distances
I Light Source tool - click a cell to place a light source (Illuminate)
D GM Draw tool - private freehand annotations, excluded from player outputs
Q / Shift+C / Shift+P Rectangle / ellipse / polygon room tools. A plain drag always draws a new room, even when it starts on an existing room; Alt (Option) + drag moves a room, and handles resize the selected room. Touching or overlapping rooms merge and keep their outer walls closed; a wall, door or empty material falls back to floor for the room fill.
Door tool (Build > Tool) Click a wall, or the line where two rooms meet, to place one door. Where rooms meet, that room edge becomes a wall again around the door. The selected door material sets locked, trapped or secret styles; orientation follows the wall.
W Wall drawing tool - draw walls along grid edges
Shift+W Path/road drawing tool - draw free-form paths
U River tool - drag to draw flowing water
K Stair Link tool - click stairs to link between levels
Shift+R Rotate selected stamp 90° clockwise
Shift+H Flip selected stamp horizontally
Delete Delete selected placed stamp

View

Shortcut Action
Ctrl+B Toggle Print / B&W map styling
Shift+V Toggle Edit / Fog setup (a trusted DM screen, not the player display)
T / Shift+T Cycle to next / previous theme (Edit mode)
[ / ] Cycle to previous / next tile in the palette (Edit mode)
Ctrl+= or Ctrl++ Increase UI scale
Ctrl+- Decrease UI scale

Canvas

Shortcut Action
+ / - Zoom in / out
0 Reset zoom to 100%
1 Fit map to screen
Arrow keys Pan the canvas (focus the canvas first by clicking it or via the Skip to map canvas link)
Shift + mouse wheel Zoom in / out (Caps Lock also enables wheel zoom without Shift)
Right-click drag Pan the canvas
PageUp / PageDown Switch to previous / next level (multi-level projects)

Edit

Shortcut Action
Ctrl+Z Undo (up to 50 steps)
Ctrl+Y or Ctrl+Shift+Z Redo
Ctrl+C Copy selection to clipboard (Select tool)
Ctrl+X Cut selection to clipboard (Select tool)
Ctrl+V Paste clipboard at selection origin (Select tool)
Delete or Backspace Clear tiles inside the active selection (Select tool)
Esc Clear the active selection or close the open dialog

File

Shortcut Action
G Open the Generate Hub (Edit mode)
Ctrl+Alt+N or Ctrl+N Open creation for a separate project
Ctrl+O Import project JSON into a separate project
Ctrl+S Open private project backup export
Ctrl+Shift+S Export map as PNG
Ctrl+Alt+S Export map as SVG
Ctrl+Shift+P Print-optimized export (high-DPI PNG with page tiling)

Help

Shortcut Action
? Show the keyboard-shortcuts overlay
Ctrl+K or Cmd+K Open command palette (fuzzy-search actions)

Some browsers reserve Ctrl+N, Ctrl+O, and Ctrl+S for their own "new window", "open file", and "save page" actions and won't deliver them to the page. Use Project menu > Create map / Import project JSON, Export > Back up project, or the listed alternate instead. These are editor shortcuts, not the entry path from an empty Library.

Accessibility

Keyboard controls cover creation, notes, initiative, export/recovery and routine session actions. Full screen-reader task review and WCAG 2.2 AA qualification remain open; automated checks are not conformance certification. On macOS Safari/WebKit, use Option+Tab to reach all controls if ordinary Tab visits only text fields, or enable the browser's full keyboard navigation setting.

  • Single-listener keyboard registry. Every global shortcut listed above is owned by useGlobalShortcuts, which automatically suppresses shortcuts while you're typing in a text field, drop-down, or modal dialog so single-letter tool keys never fire from the wrong context.
  • Skip link. A "Skip to map canvas" link is the first focusable element on the page, so keyboard users don't have to tab through the header on every visit.
  • Landmarks. The header (<header>), tool sidebar (<nav>), map area (<main>), and side panels (<aside>) are real landmark elements with accessible names so screen-reader rotors can jump between regions.
  • Toggle state. Every toggle button (Print, GM/Player view, Show Fog, Preserve theme, the active tool, the active palette tile, the pen color and brush size) carries aria-pressed so assistive technology reports its on/off state.
  • Shortcut hints. Buttons with a hotkey advertise it via aria-keyshortcuts, and tooltips show the same key in [brackets] for sighted users.
  • Polite live region. Undo / redo, theme switch, view-mode swap, print-mode toggle, zoom level changes, and "Map generated" announcements are surfaced via an aria-live="polite" status region so the actions are audible without checking the canvas.
  • Focus visibility. All interactive controls (header buttons, tool buttons, palette tiles, drop-downs, zoom controls, the canvas, note and initiative panel items, form inputs, and edit/delete buttons) expose a high-contrast :focus-visible ring that is shown only for keyboard users.
  • Keyboard-navigable panels. Native selection buttons use Enter/Space without intercepting editing keys. Initiative has visible Up/Down buttons and Alt+Up/Alt+Down reordering. Note descriptions accept newlines; Save/Cancel returns to Edit, and Escape cancels the draft before closing a mobile sheet. Actions remain scrollable in short landscape layouts.
  • Descriptive labels. Note edit/delete buttons and initiative rename buttons carry aria-label attributes that include the item name for clear screen-reader identification. Form inputs in note editing have explicit aria-label values. All range sliders and color pickers in the toolbar include descriptive aria-label text.
  • Modal dialogs. Creation, Export, Generate Hub, Icon Picker, Shortcuts Help, Scene Templates and Command Palette use named dialog semantics and shared focus containment. Tab cycling skips unavailable controls and closed advanced sections. Escape dismisses the active dialog or editing draft, and focus returns to the opener when it still exists. A resized mobile sheet does not take focus from an already-open dialog.
  • Print mode. Monochrome map styling is available through Commands or Ctrl+B, and through Export > Print for the table > Ink-friendly map styling.

Saving, Exporting & Importing

The save indicator reports device storage, not cloud sync or a separate backup. Writes are debounced and can fail. Wait for Saved on this device before closing or updating. Undo history is in memory and does not survive reload.

Save health and recovery

Open Save health & recovery if saving fails or a stale tab conflicts with newer work. Download an Export backup of current in-memory work before reloading; retry a storage failure when its cause is resolved. Do not erase site data or overwrite another tab's work as a recovery shortcut.

Recovery copies can preview a previous save, retained migration original, checkpoint or recovery file. Restore whole project restores all levels into the current project, not just the visible level; inspect the preview before confirming. A failed startup retains the original source and offers recovery or retry instead of treating a blank editor as a successful restore.

Recovery copies live in the same browser storage and can be lost with it. Export an external project backup regularly. The checkpoint limit is 20; cleanup is explicit, not automatic deletion. Library Archive and Trash are organization tools, not off-device backups.

Session records are separate. Run provides Download session recovery, named checkpoint downloads and the last recovery checkpoint. These files are DM-private recovery material; there is no dedicated session-file importer, and the project import dialog is not a session restore path. Keep the local session for normal resumption through Prepare session > Continue a session.

Export

Open Export and choose the purpose. Existing file shortcuts open the same dialog with the matching purpose selected. PNG/SVG shortcuts select Use in another map tool and initially use the current DM/player view; from Edit, that can include private content. For player sharing, choose Share with players rather than assuming every image export is public.

Purpose Output and scope
Share with players PNG or SVG of the current level using Player preview publication and fog rules, with a public filename and audience preview.
Back up project Editable JSON of every level and project asset. Includes DM-only content. Separate session records and device checkpoint history are not included.
Print for the table Current-level PNG pages with player (default) or DM audience, 72/150/300 DPI, physical grid scale, Letter/A4, configurable margins and overlap, page preview, and optional scale bar. Download one page or all pages with progress and cancellation.
Use in another map tool Current-level PNG/SVG with player (default) or DM audience, and grid dimensions and pixels per cell shown. No claim of native VTT integration.

PNG uses a dedicated export renderer, never the editor canvas or selection handles. Single images are limited to 16 megapixels and 8192 pixels per side. Larger maps must use lower resolution or tiled printing. Pages are rendered directly rather than cropped from an enormous full-map canvas. PNG files carry physical DPI metadata; print at 100% / actual size, not fit to page. Browser permission may be required for multiple downloads.

Once Cancel export is handled, the dialog shows that cancellation is pending. The current render or PNG encoding operation may still need to finish; output settings and new exports stay locked until its cleanup completes. Completed downloads are kept and the project remains unchanged.

Ink-friendly PNG styling uses monochrome map companions, Folio furnishings, Folio token frames/silhouettes and legacy token affiliations. Embedded artwork and annotations can remain colored. SVG retains the map's color art treatment. Missing or undecodable optional artwork is explained in the preview and uses a base color or placeholder. External images are not fetched. Review embedded images for secrets before sharing. Cancelling or failing an export does not change the project; already completed downloads remain.

Import

For a preview before import, choose Your maps > Import project, review the summary, then choose Import as new project. The editor's Project menu > Import project JSON reads the chosen file directly into a separate project without that Library preview step. Both allocate a new local identity, even when the file came from this Library, and retain the current saved project.

Private project-backup JSON, legacy project JSON and legacy single-map JSON are supported. A single map becomes a one-level project. Invalid or unsupported data produces an error without replacing the source; preserve the original file. PNG/SVG exports, third-party VTT formats and separate session recovery records are not project imports. Use Trace an image or background-image tools for raster artwork rather than expecting editable geometry from a PNG.

Creator-sharing packages

Choose Share a creator copy on a saved Library card or inside the editor's Export dialog. This is a separate author-to-author flow, not Share with players or Back up project. Both profiles expose the selected full layout, including secret geometry. Map layout omits notes, tokens and encounter annotations; DM encounter lets you include specific notes, tokens, hidden furnishings, annotations and markers. No encounter items are automatically selected. Publication titles/level names are reviewed separately from private source names. Play progress, separate sessions, recovery data and unknown fields are not published.

Choose a contribution license explicitly: CC BY 4.0 or CC BY-SA 4.0 for original content, with an inherited-license path for existing AGPL material. Existing map/asset notices are preserved, not relicensed. Newly created sample copies carry notices; older saved copies may lack provenance and need manual source declarations. The app cannot prove ownership or legal compatibility.

Review custom asset rights, the exact package previews/files and image metadata, then acknowledge the sharing copy before Download creator ZIP. Accepted image bytes are preserved. Raster files may contain private metadata not shown in the preview. Static PNG/JPEG/WebP and a restricted SVG path/shape subset are supported; unsupported effects, animation or active/external SVG content fail explicitly. No original map or image is rewritten to make a package pass.

The ZIP contains ordinary files under maps/<package-id>/: editable map data, previews, manifest/checksums and attribution/license notes. In Your maps, choose Import creator package for the ZIP or Import creator folder for the extracted map directory. Both validate before preview, then create a new local identity only after Import as new project. Rejected or cancelled imports leave existing records unchanged. Imported copies start with fresh visibility state; they are still author-facing, not player-safe.

Sharing limits are 32 MiB ZIP, 64 MiB expanded members, 16 MiB map JSON, 256 members and 32 levels totaling 262,144 cells. Each image is limited to 10 MiB encoded source and 24 million pixels; distinct images for one level share a 24-million-pixel decoding budget. Levels render sequentially. These limits do not restrict private backups or certify total browser/GPU memory.

No GitHub login, connection or upload is implemented. Manual upload is a separate action requiring deliberate repository visibility, rights review and any workflow/budget approvals. Creator sharing is implemented locally with bounded browser evidence, not hosted release qualification. See the contract and evidence.

Compare a creator package without connecting an account

For a map imported from a creator package, choose Manage > Compare creator package in Your maps and select another creator ZIP. The preview compares the original imported member hashes with the selected package, not with your current edits. It shows added, removed and changed files, declared versions, creator/license changes and different package IDs. A changed file is still flagged when its byte count or version label is unchanged.

Matching IDs, author names and version labels do not verify a publisher or establish which file is newer. The saved receipt is private, editable metadata, not a signature. Comparison never replaces a map: Import as new project creates a separate copy, and cancelling leaves existing records unchanged. There is no GitHub request, polling or automatic merge.

New creator imports retain the original package receipt in private backups; creator exports exclude it. Older imports may have no receipt, and unsupported future/damaged receipts remain preserved but cannot be used for comparison. Import the original creator ZIP as a separate project to establish a baseline instead of reconstructing it from an edited map.

Mobile & Touch Support

The initial release scope is desktop-first. Responsive layouts and touch gestures are implemented, but real mobile devices, keyboards, touch/pen and native zoom remain unqualified. Emulated dimensions and interface text scaling do not establish those support claims.

Responsive layout

The layout shifts with the screen instead of pretending one arrangement fits everything. That keeps the important tools reachable whether you're on a big monitor, a tablet in portrait, or a phone you handed across the table.

  • Wide editor - task navigation, map canvas and a contextual panel only when needed.
  • At 1100px or narrower - the contextual panel overlays the map rather than reserving a third column.
  • At 768px or narrower - compact primary actions, an expandable Tools panel and a focus-contained contextual sheet. The sheet tracks available viewport height, including reduced-height layouts.

Touch gestures

Touch support is built around the gestures people already expect. Zooming, panning, and quick undo or redo actions are meant to feel natural, not like a desktop shortcut awkwardly translated to glass.

  • Pinch-to-zoom - two-finger pinch to scale the canvas (0.25×–4×).
  • Two-finger pan - drag with two fingers to pan the canvas.
  • Long-press pan - long-press (400ms) starts pan mode, replacing right-click for touch devices.
  • Two-finger tap - undo. Three-finger tap - redo.

Mobile toolbar

On smaller screens, the toolbar changes shape so the app stays usable with thumbs. The essentials stay close, and the deeper tools are still there when you need them.

  • Edit - Paint, Select, Undo and All actions.
  • Fog setup - Draw, Defog, Undo and All actions.
  • Tools - expands the shared navigation and coordinate/object controls.
  • Run/player display - separate workspaces, not the editor's bottom toolbar.

Progressive Web App (PWA)

If you want Dungeon Mapper to behave more like an installed tool than a browser tab, the PWA support is there for that. Install it, keep it offline, and treat it like part of your regular session kit.

  • Install prompt - browsers offer an "Add to Home Screen" or "Install" option for the app.
  • Offline readiness - open Offline & updates in the Library or editor. Wait for App and built-in art cached while online. All bundled art is included; no third-party fonts or remote images are needed. Browser storage eviction can remove caches or projects, so retain JSON backups.
  • App updates - updates wait without automatically reloading. Update saved workspace requires a saved project, closed dialogs, and no other Dungeon Mapper windows or player displays. Save/end a live session and return to the editor first. Failed, conflicted or pending saves block reload.
  • Standalone mode - installable where the browser provides it. Safe-area styling exists; physical notched-device and mobile interruption behavior remain unqualified.

See UX-08 export and offline contract for browser limits, production qualification and the update policy.

If an update or recovery goes wrong

Keep the current tab open while saving is pending or failed. Export a private project backup of current work where available, and retain session recovery downloads separately before leaving Run. Do not clear browser/site storage: that can remove the Library, sessions, recovery copies and offline cache.

Use the visible retry/recovery controls and preserve the original download when reporting a failure. An older deployed app is not automatically a safe reader for newer data. There is no user-facing version picker or general downgrade guarantee. A locally rehearsed version pair is evidence for that pair only, not permission to restore arbitrary application or storage versions.