# Changelog — Baileywiki Better Levels

<!-- LAST-PUBLIC-STABLE: 2.0.0 -->

How this works: in-progress notes accumulate under **Unreleased**, grouped by Added / Changed / Fixed.
At publish time, **Unreleased** is renamed to the version being released (with the date) and the version
is bumped — so every *published* release carries ONE complete, user-facing summary. FoundryMods receives
only the released version's `## <version>` section, never the whole file.

**Release-channel workflow (as of 1.5.2 → testing).** Default publish target is the **testing** channel
(`publish-foundrymods.py --module baileywiki-better-levels --testing`), left **private**. Every "publish
it" cuts a new testing version; stable's `latest_version` stays put. Version numbers are **globally unique
per module across both channels**, so a version can't be pushed twice — promotion re-points the stable
channel at the artifact already sitting in testing (no rebuild, same bytes).

The per-version sections below stay detailed for OUR tracking. When promoting to stable, do NOT send the
raw pile of testing sections. Instead collate every `## <version>` newer than the `LAST-PUBLIC-STABLE`
marker above, then hand the promotion **one rationalized, user-facing changelog**: keep only what matters
to someone upgrading from the last public version, drop internal churn (harness/lint/verification fixes,
"assert too strict", bugs introduced and fixed within the same testing run), and merge related items into
single lines. After promoting, update the `LAST-PUBLIC-STABLE` marker to the promoted version.

## Unreleased
### Added
- _new features_
### Changed
- _behaviour changes_
### Fixed
- _bug fixes_

## 2.0.1 - 2026-08-25

### Fixed
- Helper panel remembers whether it was open, minimized, or closed, and no longer pops open just because a scene has levels.
- Audit no longer errors when a roof is missing its surface region (that used to spam the console every time the helper panel redrew).

### Added
- Set Defaults has a link that opens this module's Game Settings.

### Changed
- Show visible tokens only (keeps overhead tiles intact when a token is seen on another floor) now defaults to on. Worlds that already saved it off stay off.

## 2.0.0 - 2026-08-24

**Any battlemap can now have levels, not just the ones designed for them.**

Draw a region over artwork that is already painted into a map (a bridge, catwalk, awning, or cave mouth) and tokens traveling underneath vanish behind it, exactly as if an overhead tile covered them. No tile needed, and none is added. Anyone who can genuinely see under there still sees a ghost of the token; everyone else sees nothing. This turns a whole category of maps into levels maps with no art surgery.

### Edit region shapes point by point

Foundry has no built-in way to move, add, or delete an individual vertex of a region polygon. Select a polygon region with the Regions layer Select tool and every vertex gets a handle: drag a point to move it, right-click a point to delete it, drag an edge midpoint to insert a point, hold Shift to bypass grid snapping. On by default for GMs; toggle it under "Edit region points on the canvas".

### Faux Overhead

A region behavior that conceals tokens beneath painted-in overhead art.

- Per-client display of concealed tokens: hidden, faded ghost, hitbox only, or the token as normal. Each player and the GM pick their own.
- Per-region concealment override (solid stone vs slatted catwalk). Line of sight always wins: a token you can truly see ghosts rather than vanishing.
- Partial occlusion: a token on the edge is clipped there, not popped in or out.
- Concealed tokens hide their nameplate, bars, and elevation badge, and cannot be targeted by someone who cannot see them.
- Keep this area lit through fog of war, so a walled interior under an overhead reads at the map brightness instead of a black hole (holes stay dark).
- Make Surface gives an overhead a sight-blocking surface so tokens above and below cannot see through it.
- Occlude light like a roof (mutually exclusive with Keep Lit).
- Faux Overhead defaults: set draw-time options once; apply to selected for existing regions.
- Fill a walled area from the Create menu (click inside a tent, hut, or alcove, or select the walls). Draw is for bridges and anything walls do not enclose. Escape or right-click cancels.

### Native roofs (Better Roofs is no longer required)

- Fog-of-war reveal is native, with a Reveal fog of war checkbox on the tile Overhead tab.
- Occlusion linking is native: tiles that share an Occlusion Link Id fade together.
- Existing Better Roofs settings carry over. The old load warning is gone.

### Level Manager and audit

- Per-level backgrounds, with a BG column and a modal for image or color. Deliberate shared artwork is respected by the audit.
- Audit outlines on the canvas: red and amber outlines on the viewed floor when Build Mode is on or the helper panel is open. Click an outline to Fix or Ignore. GM only.

### Also in this release

- The toolbar is one Better Levels group. Clicking the Better Levels icon opens the helper panel.
- Lights dropped on a non-ground floor take that floor elevation (the Levels nav selection).
- v13-to-v14 migration no longer loops on scenes that already have v14 levels. Leftover light and sound flags.levels crumbs can be stripped like any other legacy-flag finding.
- Hardened the Placeables tile-thumbnail list against a Tiles-tab freeze.
- A failure building our toolbar buttons can no longer remove other modules tools.
- Concealment, targeting, and rendering refinements so hidden tokens stay hidden.

## 1.12.57 - 2026-08-13
### Added
- **Edit region points directly on the canvas.** Select a polygon region with the Regions layer's Select
  tool and every vertex gets a handle: drag a point to move it, right-click a point to delete it (its
  neighbors join with a straight line), and drag an edge midpoint to insert a new point. Hold Shift while
  dragging to bypass grid snapping. Foundry v14 has no built-in way to edit an individual region vertex, so
  the only way to reshape a drawn polygon used to be to delete it and draw it again. This makes it easy to
  tune a Faux Overhead, Define Surface, or stair region so its outline hugs the underlying map art. On by
  default (GM tool, hidden from players); turn it off under "Edit region points on the canvas" in settings.

## 1.12.56 - 2026-08-12
### Reverted (Faux Overhead)
- **Backed out the terrain-wall Keep-Lit experiment from 1.12.55.** It did not produce the intended result in
  practice, so Keep-Lit returns to its prior behavior for now. Reaching "see into the area at the scene's
  illumination level, like terrain walls" remains the open goal, to be revisited with a different approach.

## 1.12.54 - 2026-08-12
### Changed (Faux Overhead)
- **Keep-Lit and Occlude-Light are now mutually exclusive** (they can't both work on one region). In the Faux
  Defaults dialog they're a single radio group (Keep lit | Occlude light | Neither), and on the region
  behavior sheet checking one clears the other. Enforced on save so it holds from the sheet, the dialog, or
  the API - no more silent conflict.

## 1.12.53 - 2026-08-12
### Documented (Faux Overhead)
- **Light occlusion and "Keep lit through fog of war" cannot both work on one region in v14.** Source research
  confirmed the two are arbitrated by the SAME depth-mask channel: an occluder writes its elevation there,
  and the illumination gate reads that channel to zero out any brightness sourced below it - which is the
  keep-lit ground brightness. They only coexist while a token stands under the footprint. No occluder
  property changes this. The occluder itself is correct and works. Better Levels now warns once when a region
  has both enabled, and documents the mutual exclusivity in the hint. Use one or the other per region.

## 1.12.51 - 2026-08-12
### Fixed (Faux Overhead)
- **Light occluder no longer shadows the floor beneath it.** It was set to occlusionMode NONE, which makes
  the depth mask permanently block ALL light below the occluder plane - darkening the very under-bridge
  floor (and killing the region's Keep-Lit). Switched to occlusionMode FADE (verified against the v14 depth
  shader): when a token is under it, the occlusion state flips the depth write so the gate becomes "block
  light ABOVE the plane, pass it BELOW" - the under light lights the floor, but does not spill onto the
  deck. This is exactly how a roof tile avoids darkening the floor under it.

## 1.12.50 - 2026-08-12
### Fixed (Faux Overhead)
- **Light occluder is now invisible.** It occluded light correctly but rendered as a grey rectangle in the
  region. Set its display alpha to 0: the depth shader keys on the texture's per-pixel alpha, not the mesh's
  display alpha, so it still writes depth (still occludes) while drawing nothing to the colour buffer.

## 1.12.49 - 2026-08-12
### Added (Faux Overhead)
- **Light occlusion (per region), for real this time.** A Faux Overhead can now block light beneath it so a
  torch under a bridge does not spill onto its level, exactly like a roof tile. v14 research confirmed light
  occlusion is a DEPTH-MASK feature (regions/surfaces can't do it), and the depth pass is duck-typed over
  canvas.primary children - so Better Levels adds an invisible depth-writing occluder shaped to the region
  polygon: a PrimarySpriteMesh (restrictsLight, at the region's elevation) built from a polygon render
  texture, the exact mechanism the engine uses for level-background light occlusion. Opt-in via the region's
  Faux Overhead behavior and the Faux Defaults dialog; off by default.
  - Diagnostics: api.faux.lightOccluders() and api.faux.why() (occludesLight) report state.

## 1.12.47 - 2026-08-12
### Fixed (Roofs / Fog of War)
- **Roof fog reveal now holds through darkness.** Rebuilt on the same mechanism the faux-overhead region
  reveal uses (which already worked in the dark): a plain white fill of the tile footprint into the vision
  mask's brightness channel, which LIGHTS the footprint rather than merely marking it seen, so the roof
  stays visible at any scene-darkness level. Dropped the shader SpriteMesh (which wasn't rendering in that
  mask) and Better Roofs' token-below / line-of-sight gate (a same-elevation crypt lid never passed it).
  Reveal is now unconditional, matching the faux region reveal.
  - Trade-off: the lit footprint is the tile's rectangle, so a very irregular roof PNG also lights its
    transparent bbox margins. Shaping the fill to the texture silhouette is a future refinement.

## 1.12.46 - 2026-08-12
### Fixed (Roofs / Fog of War)
- **Roof fog reveal now survives scene darkness.** The revealed roof was painted into the vision mask ROOT
  (as Better Roofs does), which marks it seen but not lit - so raising scene darkness hid it again. It now
  paints into the mask's brightness channel (`fov`), the same channel the faux-overhead reveal uses, so the
  roof reads as lit and stays visible through fog at any darkness level. (Better than Better Roofs, whose
  own tooltip notes it does not work with lights.)

## 1.12.45 - 2026-08-12
### Fixed (Roofs / Fog of War)
- **Roof fog reveal now actually works.** The first native attempt used the wrong mechanism: it painted
  the roof footprint into the vision mask as a white-TINTED sprite, which multiplies the texture and so
  paints a dark roof's own dark colours - revealing almost nothing (the crypt-lid symptom). Rebuilt it
  from Better Roofs' actual approach: a custom sampler shader that outputs PURE WHITE shaped by the
  texture's alpha, drawing the roof through the fog in `canvas.masks.vision`.
  - Gating matches Better Roofs: a roof reveals only when the controlled token is BELOW it and its vision
    actually reaches the tile, so roofs across unexplored map aren't revealed. Driven on sight refresh.
  - Roof fog reveal moved to its own module (tile-fog-reveal.mjs); the faux-overhead painter is back to
    regions only (a painted-in bridge is lit through fog; a roof tile is re-drawn above fog - different
    problems, different mechanisms).

## 1.12.44 - 2026-08-12
### Added (Roofs / Occlusion)
- **Native occlusion linking** (Better Roofs' Occlusion Link Id / Source, rebuilt natively). Tiles that
  share an **Occlusion Link Id** fade together; a tile marked **Occlusion Link Source** broadcasts its
  occluded state to the rest, while non-sources only receive. Ideal for a multi-tile roof on a prefab
  that should fade as one piece. Done by wrapping core's `CanvasOcclusionMask#_identifyOccludedObjects`
  through libWrapper (never a raw patch), elevation-gated to the viewed level.
- **Tile config (Overhead tab):** the "Reveal fog of war", "Occlusion Link Id" and "Occlusion Link
  Source" controls now appear just above "Restricts Light", where Better Roofs' controls used to be.
  Each writes its flag immediately.
- **Migration** now also carries over Better Roofs' `occlusionLinkId` / `occlusionLinkSource` (not just
  the fog flag) onto the native flags on scene load.

## 1.12.43 - 2026-08-12
### Added (Roofs / Fog of War)
- **"Reveal fog of war" checkbox in the Tile config sheet**, bound to the native flag. It shows CHECKED on
  roofs (marking a tile as Roof sets it automatically) and can be toggled on any tile; the change takes
  effect immediately. This restores the UI Better Roofs used to provide, now native.
- **Migration:** roofs configured before the dependency was dropped (carrying the old
  `flags.betterroofs.brMode`) adopt the native reveal-fog flag on scene load, so they keep revealing fog
  and show the checkbox checked. The old flag is left untouched for anyone still running Better Roofs.

## 1.12.42 - 2026-08-12
### Changed (Roofs / Fog of War)
- **Dropped the Better Roofs dependency for fog-of-war reveal - it is native now.** Roof tiles no longer
  rely on Better Roofs' `flags.betterroofs.brMode`; Better Levels reveals the fog itself by painting the
  roof's footprint into the sight mask (the same vision-mask painter the Faux Overhead fog reveal already
  used). The reveal follows the roof art: a white sprite of the tile's own texture, so an irregular roof
  reveals only what it covers (falls back to the tile rectangle if its texture isn't reachable).
- A new native tile flag (`flags.baileywiki-better-levels.revealFog`) replaces brMode everywhere - tile
  configuration, the Audit "reveal fog" rule + fix, role inference, and Set Defaults. No external module
  is required or written to. Better Roofs can be uninstalled without losing roof fog reveal.

## 1.12.41 - 2026-08-12
### Added (Faux Overhead)
- **Faux Overhead defaults.** A new "Faux defaults" button in the Better Levels panel's Create menu opens a
  small dialog for the draw-time settings a Faux Overhead is born with: Keep lit through fog of war, Make
  Surface, and the token visibility override. Set them ONCE and every newly drawn (or toggled-on) faux
  region inherits them, instead of opening each region's Behaviors tab after the fact.
- **"Apply to selected"** in the same dialog stamps the shown settings onto the faux regions you have
  selected - the quick on/off path for existing regions, since v14 has no region HUD to hang toggles on.
- Light occlusion is intentionally not in this panel yet; it needs the depth-mask work tracked separately.

## 1.12.40 - 2026-08-12
### Changed (Faux Overhead)
- **Replaced the (non-working) light-occlusion toggle with "Make Surface".** v14 source research confirmed
  regions CANNOT occlude light in the rendered view - cross-elevation light blocking is a depth-mask
  feature written only by tiles, so the light-only Define Surface added in 1.12.37 never actually blocked
  any light. Removed it.
- **New per-region "Make Surface" toggle** gives a Faux Overhead a real, FULL Define Surface so token
  occlusion works properly: without one, two tokens can see each other straight through the bridge because
  sight is not blocked between levels. It applies core's surface via the same machinery a hand-made
  Define Surface uses (all restrictions on), tagged to EVERY level mutually visible with this one
  (so tokens on a level that can't see the overhead don't suddenly reveal each other), with the region's
  own band as the level (not whatever floor you happen to be viewing). Off by default; leave off for a
  see-through awning or rope bridge.
- Light occlusion for Faux Overheads is tracked separately - it needs a depth-mask occluder (emulating a
  tile), which regions cannot do natively.

## 1.12.39 - 2026-08-12
### Fixed (Faux Overhead)
- **Definitive white-screen fix.** Moving a token down a level triggers three full canvas redraws; during
  them PIXI could leave a partial-occlusion mask's `renderable` flag on while it sat in the primary group
  (which renders its children), so the mask's white fill painted the whole screen. All masks now live in a
  dedicated `renderable = false` holder: their transforms still update (so clipping still aligns and works)
  but they are skipped by the colour pass entirely and can never paint the screen. Combined with the
  bounded fill and per-mesh binding, the mask is now physically unable to white out the canvas.

## 1.12.38 - 2026-08-12
### Fixed (Faux Overhead)
- **The partial-occlusion mask can no longer white out the whole screen.** Its fill was scene-sized, so a
  single stray/orphaned mask painted white over the entire canvas (seen again when moving a token down a
  level). The fill is now bounded to the region's own bounding box plus a margin, so even if a mask ever
  leaks, the worst it can do is briefly flash the overhead's immediate footprint, never the whole scene.

## 1.12.37 - 2026-08-12
### Added (Faux Overhead)
- **Per-region "Occlude light (like a roof)" toggle.** A Faux Overhead can now block light at its own
  elevation, so a light beneath it does not spill onto the overhead's level (a torch under a stone bridge
  stops lighting the bridge deck). Off by default, for things you can see light through (a catwalk, a
  rope bridge).
  - Native, no tile and no module dependency: it uses core v14's own region light occlusion. Better
    Levels keeps a light-ONLY Define Surface on the region (move/sight/sound/occlusion all off), so only
    light is affected. The surface is flagged as ours - it is added and removed with the toggle and never
    touches a surface you built by hand.
  - Set it in the region's Faux Overhead behavior, per region, alongside the reveal override.

## 1.12.35 - 2026-08-12
### Changed (Faux Overhead)
- **Partial occlusion is now STANDARD in both concealing modes** - "Nothing at all" and "Hitbox only".
  A token straddling a Faux Overhead edge is clipped at that edge, so the part sticking out still shows;
  Hitbox additionally keeps its box. Ghost is unchanged. The separate opt-in setting has been removed.
- **Reveal-mode copy clarified** - the setting now says plainly it changes only how a token beneath an
  overhead is drawn ON YOUR OWN SCREEN, not what it can do and not anyone else's view (the old wording
  could be read as controlling other tokens in view).
### Fixed (Faux Overhead)
- **The scene no longer flashes white when dragging a token under an overhead.** A drag/refresh swaps in
  a new token mesh; the old partial-occlusion mask was left orphaned in the primary group, and PIXI can
  leave a spent mask's `renderable` flag on, so the orphan painted its white fill over the whole scene.
  The mask is now bound to the exact mesh it was built for (a mesh swap rebuilds it) and orphans are
  swept and destroyed every frame before they can render.

## 1.12.34 - 2026-08-12
### Diagnostics (Faux Overhead)
- **`api.faux.why()`** - reports the full reveal/partial decision for the controlled (or hovered) token:
  client setting, region found, region override, whether the token is seen by active vision, the final
  mode painted, whether partial occlusion would engage, and whether the region shape can be masked. Used
  to pin down why an edit appears to do nothing.

## 1.12.33 - 2026-08-12
### Added (Faux Overhead)
- **Partial occlusion (opt-in, client setting).** A hidden token standing HALF under a Faux Overhead now
  shows the half sticking out, clipped at the region's edge exactly as a real overhead tile would, instead
  of vanishing whole. Off by default (it changes the look of a feature people already rely on) and it only
  affects the fully-hidden reveal mode; ghost and hitbox-only are unchanged.
  - Done with a PIXI mask over the token's artwork, punched out by the region polygon. The mask geometry
    is static per region (rebuilt only when the region changes, not when the token moves) so it is cheap.
  - Name and health bars are still hidden when the token is under an overhead, since they aren't part of
    the artwork and can't be clipped by it.
  - Degrades safely: an unsupported region shape (ellipse/circle), a missing PIXI API, or any error falls
    back to the original whole-token hide, so it can never leave a token MORE visible than before.

## 1.12.32 - 2026-08-10
### Removed
- **Simple Elevation (the experimental elevation-drives-level mode) has been withdrawn.** It fought the
  v14 movement pipeline too hard (relative HUD field, elevation clamping, movement-id collisions, and a
  crash segmentizing through regions) and never became reliable. All of its code, settings, and the HUD
  readout are gone. Nothing shipped to stable.
### Fixed
- **The roof-infinity suggestion no longer applies to lower-level roofs.** `roof-infinity-region` set a
  roof surface's top to infinite, which is only valid on the TOP level (open sky above). Applied to a
  roof on a lower level it created a surface spanning [bottom, +Infinity) that overlaps every level
  above AND crashes core's movement path-sampling on any elevation change through it
  (`Cannot read properties of undefined (reading 'testPoint')`). The suggestion is now gated to the top
  level.
### Added
- **Audit rule: "Surface with infinite top below the top level"** (error) - finds surfaces already made
  infinite on a lower level and caps them at their own level's top, repairing scenes that hit the crash
  above.

## 1.12.31 - 2026-08-10
### Changed (Simple Elevation)
- **The elevation edit is now a single `TokenDocument#move()`** carrying the destination level and
  elevation together, replacing the two back-to-back updates that collided in core's movement tracking
  (`Cannot redefine property: <movementId>`). This is the modern API the deprecated `teleport` option
  pointed to, and it is one clean movement with no second update to collide. Dropped the deprecated
  `teleport` option entirely.
### Known limitation
- A scene with MALFORMED regions (e.g. duplicate surface regions, or surfaces with an infinite top)
  can still crash core's own elevation path-sampling
  (`Cannot read properties of undefined (reading 'testPoint')` inside segmentizeRegionMovementPath),
  independent of this feature. Run Better Levels' Audit & Fix / Repair on such a scene to clean the
  regions first.

## 1.12.30 — 2026-08-10
### Fixed (Simple Elevation)
- **Elevation edits no longer crash inside core's region movement code.** A non-teleport elevation
  change makes core SEGMENTIZE the vertical path through every region between the old and new position,
  and on a scene with a region whose polygon tree is unreadable that throws
  `Cannot read properties of undefined (reading 'testPoint')`. Both writes (level, then elevation) are
  now marked teleport, so core jumps straight to the destination and never samples the path. This is the
  same option the existing setElevationOnLevelChange handler uses, and removing it earlier was a mistake.

## 1.12.29 — 2026-08-10
### Fixed (Simple Elevation)
- **Rebuilt the elevation edit as two steps (Jerrod's design): change the level the normal way, then
  nudge the elevation once the token is there.** The single combined write changed the data but did not
  trigger the refresh a real level change does, so the canvas looked frozen ("totally unresponsive").
  Changing the level first goes through the proven, self-refreshing path; by the time the elevation is
  set the token is already on the destination level, so the typed value is inside the new band and core
  has nothing to clamp. Moving within one level is still a single elevation write.

## 1.12.28 — 2026-08-10
### Fixed (Simple Elevation)
- **Removed the full-canvas redraw on every elevation edit.** Deriving a lower level now works (the
  atomic level+elevation write from 1.12.27 landed correctly), but the follow-up view switch to render
  the new floor forced Foundry to redraw every canvas layer and reload all scene assets on each edit,
  the log spam and the setTimeout violations. It is also not wanted: as Jerrod noted earlier, the GM
  follows the token to its level via the Levels nav, which is the light built-in way to change the shown
  floor. The mode now just moves the token to the right level and stops there.

## 1.12.27 — 2026-08-10
### Fixed (Simple Elevation)
- **Dropping a token to a lower level now works.** Confirmed live: core clamps a token's elevation to
  its CURRENT level's band during the update, so writing elevation 15 to a token on a base-30 level
  landed at 30 (the floor). The mode wrote elevation first and derived the level after, which deadlocks
  going down: the elevation can't fall below the current floor, so the level never changes, so the
  elevation can't fall. The absolute field now writes the derived level AND the elevation in ONE update,
  giving core a consistent pair with no moment to clamp, then switches the viewed level so the new floor
  renders.
- The duplicate-event guard now dedupes by value, so two different elevations typed in quick succession
  both apply (the previous time-only guard could swallow the second).

## 1.12.26 — 2026-08-10
### Fixed (Simple Elevation)
- **The absolute-elevation field now writes ONCE per edit.** The stock field submits on Enter, on blur,
  and fires a `change`, and the override was listening to all three, so it wrote three times per edit
  (three preUpdate lines in the watcher). Everything now routes through a single `change` write, with
  Enter only committing-and-blurring and a short guard dropping stragglers.
- The watcher now logs a line when the field override actually writes, so it is possible to confirm the
  override is winning over core's relative handler rather than inferring it.

## 1.12.25 — 2026-08-10
### Fixed (Simple Elevation)
- **Simple Elevation now actually delivers "one scene zero," and the new floor renders.** The v1
  approach fought two core behaviors the watcher and the v14 source made plain:
  - **The HUD elevation field is relative to the VIEWED level** (reads `elevation - base`, writes
    `typed + base`) and never touches `level`. So typing "20" while viewing a base-20 level meant
    absolute 40, and once the level changed the base shifted and the same number meant something new,
    the chaotic wrong-floor drift. Simple Elevation now overrides that field in both directions so it
    shows and accepts ONE absolute number from the single scene zero, regardless of which level you are
    viewing. Only while the mode is on.
  - **Floors render from the viewed level, not the token's band.** A raw `level` write from a GM's own
    edit did not switch the view, so the new floor never drew. Deriving a level now also switches the
    viewed level to it (only for the controlled token, so it never yanks the view for a background
    update).
- Removed the deprecated `teleport: true` update option from the level write (v13-deprecated; it only
  aliased the `displace` movement action and did not suppress the vision refresh anyway).
### Diagnostics
- `api.simpleElevation.watch()` / `.unwatch()` retained for confirming behavior in a live scene.

## 1.12.24 — 2026-08-10
### Added (diagnostics)
- **`api.simpleElevation.watch()` / `.unwatch()`** — logs every token elevation/level update with the
  viewed-level frame, so the level-relative HUD anchoring can be observed directly. Writes nothing.
### Note
Investigating why Simple Elevation misbehaves when driven from the HUD elevation field. Verified against
the v14 client source: the HUD elevation field is level-RELATIVE (`typed + canvas.level.elevation.base`)
and never sets `level`, and floors render from the VIEWED level, not the token's band. The current
derive-level-from-elevation approach fights both. Fix pending real console data from the watcher.

## 1.12.23 — 2026-08-10
### Added
- **Simple Elevation** (world setting, off by default). Turn it on and elevation becomes the only number
  you touch: a token is assigned to whichever level its elevation falls in, measured from one scene zero,
  so there is no more "N feet above WHICH floor" arithmetic. A flyer is treated exactly like a walker at
  the same height, one point in space, one level. Levels stay fully alive underneath (vision, occlusion,
  per-level backgrounds); the mode only changes who assigns the level.
  - The level is derived on a token's every move AND the moment it is dropped, so a token is never left
    at `level: null` (the ambiguous state behind the earlier invisible-tokens scenes).
  - Out-of-range elevations clamp to the nearest real level: below the basement gives the basement, above
    the roof gives the roof.
  - Enabling it switches off "Set elevation on level change," which is its exact inverse and would
    otherwise form a feedback loop.
- **Optional token-HUD readout** (client setting, off by default, only shown while Simple Elevation is
  on): a compact "10 : L2" chip showing a token's absolute elevation and the level it lands on. No
  separate always-on badge, the level dropdown already shows the level; this just adds the number that
  drives it for anyone who wants the reassurance.
### Internal
- The stair `movementActions` write is unaffected; Simple Elevation derives `level` in `updateToken`
  after the move settles, teleport-flagged, with a re-entrancy guard, mirroring the existing
  level->elevation handler rather than fighting the v14 movement pipeline. Spec:
  `specs/better-levels-single-axis-elevation-spec.md`.

## 1.12.22 — 2026-08-09
### Fixed
- **Reverted 1.12.21's exclusion of `blink` from stairs.** That change rested on my own reasoning, not
  Foundry's: a teleporting move never passes through the intervening space, so I concluded it could not
  have climbed the stairs. Core disagrees. Its Change Level behavior offers `blink` in the field's own
  choices and hard-rejects only `displace` — before it consults the field at all. A player blinking onto
  a staircase changing floor is intended behavior, and 1.12.21 broke it. Stairs list `blink` again.
- The audit rule added in 1.12.21 ("Stair triggers on teleporting movement") is removed for the same
  reason: it was flagging correct scenes.
### Note
Stairs still get their movement actions written out explicitly rather than left empty, and that part was
right for a reason worth recording: **an empty set means ALL actions are allowed**, per core's own hint
— *"If no actions are selected, all movement actions are allowed."* A fresh Change Level behavior ships
empty, so an untouched stair accepts everything.
That said, writing the list is NOT protection against a module's custom movement action: core builds the
choices as every registered action minus `displace`, so a new action lands in the list like any other. A
vehicle stays off the stairs by moving with `displace`, which core hard-rejects. See
`specs/mass-edit-vehicle-token-spec.md`.

## 1.12.21 — 2026-08-09
### Fixed
- **Stairs no longer trigger on teleporting movement.** Core's Change Level behavior has exactly one
  field, `movementActions`, so a stair fires only for tokens moving with a listed action. We were writing
  every action we could find into it, which is wrong twice over: a teleporting move "goes from the origin
  immediately to the destination grid space", so blinking across a staircase should no more change your
  floor than blinking across a doorway should open the door; and a vehicle carrying its own prefab
  staircase, driven by a token using a teleporting movement action, would set off its own stairs while
  merely sailing. New stairs now exclude any action whose config has `teleport: true`.
### Added
- **Audit rule: "Stair triggers on teleporting movement"** — finds stairs created before the above and
  removes just the teleporting actions, leaving the walking ones alone.

## 1.12.20 — 2026-08-09
### Removed
- **"Lock Rotation Value" (added in 1.12.19) has been withdrawn.** It belongs in Mass Edit, not here:
  the problem it solves is a *linked-prefab* problem, and Mass Edit owns linking. Better Levels adding a
  token-config checkbox to fix Mass Edit's behaviour would have put the switch in one module and the
  thing it switches in another — exactly the kind of split that makes a bug impossible for a user to
  attribute. Specified for Aedif instead; nothing shipped to stable, so no user is affected.

## 1.12.19 — 2026-08-09
### Added
- **"Lock Rotation Value" — a new checkbox in the token config, directly beneath core's Lock Rotation.**
  Core's option is purely cosmetic; the v14 docs describe `lockRotation` as *"Prevent the Token image
  from visually rotating?"*, and the token's rotation VALUE still turns as it moves. That is fine for a
  character, whose art is all there is, but it breaks vehicles: a ship or wagon is a token plus a prefab
  of tiles pinned to it, so the art stays upright while everything attached to it swings. Ticking this
  behaves as though Automatic Token Rotation were switched off for that token alone, instead of turning
  it off world-wide and stopping every character from facing their movement.
  Deliberate rotation still works — the HUD, the rotate keys and the config sheet all turn the token as
  before. Only rotation applied automatically BY MOVEMENT is suppressed, so a ship stays steerable.
  Set it on a prototype token and every vehicle placed from that actor inherits it.

### Internal
- Implemented on `preMoveToken`, whose `autoRotate` field the v14 docs mark as one of only two writable
  properties on the movement operation — a supported extension point rather than something prised open.
  Explicitly NOT via `preUpdateToken`: v14 rejects movement mutations there and silently aborts the whole
  update, a trap this codebase has already paid for once (see token-hud.mjs). The hook never returns
  false and swallows its own errors, because cancelling a move would leave the token undraggable — a
  worse failure than the one being fixed.

## 1.12.18 — 2026-08-09
### Added
- **Per-region token concealment on Faux Overhead.** The behavior gains a "Token concealment" field:
  *Use each player's setting* (default), *Nothing at all*, *Hitbox only*, *A faded ghost*, or *The token
  as normal*. The client setting answers "how do I like to see concealed tokens"; this answers "what does
  this piece of scenery do", which belongs to whoever built the scene — so a region wins when it
  expresses an opinion. A solid stone bridge can hide a token outright even for a player who prefers
  ghosts; a slatted catwalk can show hitboxes even for one who prefers them hidden.
  Inherit is the default and stays the default: a region that silently imposed a look on every client
  would take the choice away from players who never asked for scenery to have an opinion.
  Line of sight still beats concealment — a token a viewer can genuinely see ghosts rather than
  vanishing, whatever the region says.
### Fixed
- Two things that the override would have quietly broken, found while wiring it: the per-token region
  test was skipped whenever a client had the effect switched off (which would have made "The token as
  normal" ignore every overriding region), and the targeting gate consulted the client setting rather
  than the outcome (which would have left a region-hidden token freely targetable).
### Internal
- `test/import-graph.mjs` — the import smoke test now lives with the module instead of in a scratch file
  that kept evaporating between runs. `node --check` only parses; this module has shipped two bugs that
  only appear when the graph is actually loaded.

## 1.12.17 — 2026-08-04
### Fixed
- **Ghost tokens are no longer the wrong size for tokens with dynamic rings** (reported by RedB). With
  Foundry's Dynamic Token Rings **Adjustment mode** set to *Grid*, a ghost drew smaller than the token it
  stands for: two concentric rings while both were on screen, and an apparent shrink the moment the real
  token hid.
  We were computing the ghost's size as `token.width x grid size` — the token's FOOTPRINT, which equals
  the drawn artwork only for a plain token at texture scale 1. A dynamic ring scales its subject by the
  world's Adjustment mode, so Grid and Standard fit differ (the same ~1.2 factor that shows up when
  scaling a copied sprite in Sequencer). The ghost now MEASURES what core actually drew, so it inherits
  every correction core applies rather than us racing to reimplement each one.
  This also fixes a case nobody had reported: **`texture.scaleX/scaleY` was ignored entirely**, so art
  deliberately drawn larger or smaller than its square ghosted at the wrong size too, rings or no rings.
  The measurement is cached per token, because core destroys the mesh of an invisible token — which is
  precisely when a ghost is wanted.

## 1.12.16 — 2026-08-04
### Added
- **Per-level backgrounds in the Level Manager.** A new BG column shows, at a glance, which of three
  states each level is in:
  - a **solid thumbnail** — the level paints its own image;
  - a **faded thumbnail** — it has no image of its own and is showing another level's, named in the
    tooltip ("Using the background from Level 01");
  - a **colour swatch** — no image anywhere visible below, so only the colour shows.
  Clicking any of them opens one modal offering both a file picker and a colour picker, because all
  three states are views of the same two fields. Edits are **staged like every other change in that
  window** and written on Commit, so Cancel genuinely undoes them; a pending edit is ringed in blue.
  A background-only change skips the backup prompt — it destroys nothing, and a prompt that cries wolf
  is one people learn to click through.
- **The audit now defers to a background you chose.** Setting an image through the modal marks that
  level, and the duplicate-background rule skips it — so two levels can deliberately share artwork
  without being told off. Generated duplicates are still caught. Same contract as the visibility matrix.

### Note
Foundry has no mechanism for one level to reference another's image: a level either has its own
`background.src` or it has none, and when it has none you see the level below because it is in that
level's Visible Levels. "Inherited" is therefore something we infer and display, never something we
store — and emphatically not something we implement by copying the image, which is the bug fixed in
1.8.9 / 1.12.8.

## 1.12.15 — 2026-08-04
### Fixed
- **Hardened the Placeables tile-thumbnail decorator against locking up the interface.** A user reported
  Foundry crashing whenever they opened the Tile Controls or the Placeables → Tiles tab, only with this
  module enabled. A tab that dies with no exception is a freeze or an out-of-memory, and this code had
  three ways to cause one:
  - The MutationObserver watched the same rows it then modified. On its own that settles, but against
    another module that also rebuilds those rows the two wake each other forever. It now ignores its own
    writes, coalesces bursts into a single pass per frame, and **stands down permanently** if it is still
    being woken 25 times in two seconds — logging why, rather than taking the interface with it.
  - The row scan was `querySelectorAll("*")` combined with a per-tile substring search, so one pass cost
    roughly elements × attributes × tiles, and the observer re-ran it on every DOM change. It now scans
    row-shaped elements only, and the substring fallback is bounded.
  - Every animated tile created its own `<video>` decoder. Capped, with a static icon beyond it, and the
    number of decorated rows is capped too.
- **A failure building our scene-control buttons can no longer damage the rest of the toolbar.** Every
  listener on `getSceneControlButtons` shares one object, so an exception from ours abandons the chain
  and removes other modules' tools — or core's. Wrapped: ours failing now costs only ours.

## 1.12.14 — 2026-08-03
### Added
- **Setting: "Show the Audit issue badge"** (on by default). Turn it off to make Audit & Fix purely
  on-demand — the button stays put and works as before, it just stops putting a red count on the helper
  panel. A permanent badge over a scene the GM built that way deliberately is nagging, not helping.
  Per-client, and hidden from players along with the other GM-only client settings.
  *Also shipped to stable as 1.8.10.*

## 1.12.13 — 2026-08-01
### Fixed
- **Each drawing in a Create mode now makes its own region.** Foundry's Regions layer adds a newly drawn
  shape to the *selected* region instead of creating a new one, and it selects each region as you create
  it — so in Create Stairs every stair after the first became another shape of the first stair. Change
  level between drawings and the new stair silently belonged to the old level, because no `createRegion`
  ever fired for it and none of our configuration ran. The selection is now released after each creation,
  so one drawing means one entity. Applies to Faux Overhead Draw as well, which had the same flaw.
  Only while a Create mode is armed — adding a shape to an existing region with the plain Regions tools
  is untouched.

## 1.12.12 — 2026-07-31
### Changed
- **Helper-panel tooltips dismiss the moment you click a button.** Foundry keeps a tooltip up while the
  pointer rests on the button, so pressing Create opened its menu directly underneath the tooltip still
  explaining the Create button. The tooltip has done its job the instant you commit to the click.
  Applies to every button on the panel, not just Create — several of them open menus or dialogs anchored
  near the cursor. Hovering again brings the tooltip back as normal.

## 1.12.11 — 2026-07-31
### Changed
- **Right-click no longer cancels a Create mode — it pans, as it always should have.** Foundry pans on
  right-drag, so binding cancel to a single right-click threw you out of the mode every time you moved
  around the map to find the next room, which is precisely the workflow Faux Overhead Fill exists for.
  Exiting is now **Escape** or a **double right-click** (within about half a second — a pan never
  produces the second press). Applies to all three Create modes: Stair, Faux Overhead Fill, Faux
  Overhead Draw.
- **A persistent on-screen hint** now sits above the hotbar for as long as a Create mode is armed,
  naming the mode and stating how to leave it. The panel's banner alone was not enough — the panel can
  be collapsed or dragged aside while you work the canvas, and a modal state needs a visible exit.
  Click-through (`pointer-events: none`), so it can never intercept a click meant for the map.

## 1.12.10 — 2026-07-31
### Fixed
- **No more "Better Levels and Better Roofs modify the same functionality" on every scene load.**
  Better Roofs has exactly one libWrapper registration —
  `CanvasOcclusionMask.prototype._identifyOccludedObjects` — and "Show visible tokens only" was
  assigning straight over that same prototype method. A raw assignment over a libWrapper-managed method
  is what produced the warning, and depending on load order it can discard Better Roofs' wrapper
  outright, silently breaking its occlusion links.
  That patch was redundant anyway: core reaches `_identifyOccludedObjects` with the list from
  `TokenLayer#_getOccludableTokens`, which we already filter one step upstream. Removed it. The two
  modules now touch disjoint surfaces — Better Roofs owns the occlusion mask, we decide which tokens are
  eligible to enter it.

## 1.12.9 — 2026-07-31
### Fixed
- **Faux Overhead Fill now encloses a room built from mixed wall types.** It swept each wall channel
  (move / sight / light / sound) separately and kept the smallest result, which assumed the whole
  boundary was made of one kind of wall. Real rooms aren't: two solid sides, a curtain that stops sight
  but not movement, a railing that stops movement but not sight. Every channel leaks through the walls
  it can't see, so an obviously enclosed room was rejected as "not enclosed". The fill now treats ANY
  wall as solid — doors included, open or shut — because the question it is really asking is what shape
  you drew, not what the walls are made of. The per-channel sweep remains as a fallback.

## 1.12.8 — 2026-07-31
### Fixed
- **Tokens invisible on a scene built from a flat map image.** Generating levels — or adding one in the
  Level Manager — copied the ground floor's background image onto every new level. In v14 the background
  belongs to the Level and is painted across the whole canvas at that level's elevation, so a five-level
  scene drew five opaque copies of the map stacked above the ground floor. Tokens standing there were
  buried: artwork gone, while the hitbox, selection border and elevation badge kept drawing — which reads
  as a broken token and cost a long hunt through every other module in the world. New levels now inherit
  the ground floor's background *colour* only; the floor below shows through via that level's Visible
  Levels list, which is what the field is for. Tile-built scenes were never affected, which is exactly
  why every scene we tested on looked fine.
  *Also shipped to stable as 1.8.9.*
### Added
- **Audit rule: "Duplicated level background"** — finds levels already damaged by the above and clears the
  repeated image. Only flags an upper level whose image is identical to the ground floor's, so deliberate
  artwork on an upper floor survives. Regenerating levels self-heals too.
- Regression test `test/level-background.mjs`, using BOTH a flat-map scene and a tile-built one — a
  tile-only fixture would have passed against the broken code, which is how this got missed.

## 1.12.7 — 2026-07-31
### Added
- **`api.faux.purgeFromWorld()`** — removes Better Levels' region behaviors from every scene at once.
  The per-scene version only cleans the scene you have open, so a world with Faux Overheads spread across
  several scenes kept throwing validation errors on load until each was visited individually.

## 1.12.6 — 2026-07-31
### Fixed
- **"Show visible tokens only" now installs nothing while it is switched off.** The experimental feature
  patched core rendering methods at every canvas load regardless of its setting, relying on its filters to
  do nothing — so an off-by-default feature was permanently altering core behaviour, and libWrapper
  reported it as a conflict. That made Better Levels impossible to distinguish from libWrapper when
  bisecting with Find The Culprit. Off now means absent.

## 1.12.5 — 2026-07-31
### Fixed
- **Concealment can no longer make a token MORE visible than Foundry intended.** It set the token's mesh
  visible before dimming it, so a token that something else had legitimately hidden reappeared when it
  walked under a Faux Overhead — the exact inverse of the feature — and the per-frame pass kept forcing
  it. Concealment now only ever reduces opacity, never restores visibility.

## 1.12.4 — 2026-07-31
### Added
- **A way to remove Better Levels data from a scene**, so the scene still works for someone without the
  module: `game.modules.get("baileywiki-better-levels").api.faux.purgeFromScene()`.
  - This matters more than it sounds. A Faux Overhead is a custom region behavior, and Foundry only
    accepts a custom behavior type while the module declaring it is installed and enabled. Without it,
    every region carrying one becomes an invalid document, which aborts the scene's initialization — the
    scene does not lose a feature, it stops working, and the cause appears only as a validation error.
  - Run it before publishing any scene not explicitly sold as requiring Better Levels. Define Surface
    regions are untouched, since those are core Foundry and valid on their own.

## 1.12.3 — 2026-07-31
### Fixed
- **Removed a console error that wrongly blamed Better Levels for being out of date.** The targeting block
  tried to wrap a Token method that does not exist in Foundry v14, which made libWrapper report a package
  error against this module. The method was already unnecessary — the targeting event does the work — so
  the attempt is simply skipped when the method is absent.

## 1.12.2 — 2026-07-30
### Fixed
- **Faux Overhead fill no longer buries you in notifications.** Engaging the mode posted two and each fill
  posted three — the mode announcing itself, a "click inside the space" prompt repeated on every re-arm,
  and one message each from the internal steps that add the surface and name the region. It is now one
  notification when you start the mode and one per area filled.

## 1.12.1 — 2026-07-30
### Fixed
- **Faux Overhead fill mode now survives changing level.** Switching level rebuilds the canvas, which took
  the armed click with it — so the mode looked active but did nothing. That is exactly the moment the mode
  is needed, since changing level is usually how you find the walls you meant to fill. It now re-arms
  itself whenever the canvas is rebuilt.
- **Right-clicking the canvas cancels any Create mode**, not just the fill. Right-clicking the panel does
  not, so you can still use its context menus.

## 1.12.0 — 2026-07-30
### Changed
- **Better Levels now adds exactly one entry to the scene toolbar**, its own group at the end, holding the
  panel button and Build Mode. Everything it used to scatter through Foundry's Tiles, Walls and Regions
  toolbars is gone.
  - The removed buttons — Mark Floor, Make Surface, Faux Overhead — were all "configure the thing I have
    selected", which is what **Fix / Configure the Selected Entity** already does by reading the selection.
    Three menus each carrying one type's version of one verb is worse than one button that works it out.
  - Build Mode keeps a toolbar home because it is flipped constantly while building and deserves to be one
    click from anywhere.
### Added
- **A "Create" menu on the helper panel**, holding the actions that make new things:
  - **Stair region** — switches to the Regions layer and rectangle tool, and every region you draw becomes
    a stair to the level above, so consecutive stairs are one drag each.
  - **Faux Overhead — fill from walls** — switches to the Walls layer and shows a crosshair; click inside
    an enclosed space to fill it, and keep clicking to fill more. The crosshair survives changing level,
    since that is usually when you discover you were looking at the wrong one.
  - **Faux Overhead — draw by hand** — switches to polygon drawing; the region you draw becomes a Faux
    Overhead.
- **An armed Create mode is always visible on the panel**, with a Cancel button, and Escape stops it. Modes
  that quietly persist have stranded people twice in this module; one that deliberately survives a level
  change needs to be impossible to forget about.

## 1.11.3 — 2026-07-30
### Fixed
- **Click-to-fill now recognises rooms enclosed by sight-blocking walls.** It only ever asked whether a
  point was enclosed by walls that block MOVEMENT, so a cloth tent, a curtain or a treeline — which block
  sight but let you walk through — sailed straight past it and the fill was refused. It now checks every
  wall channel and uses the tightest enclosure it finds, so the question is "is this enclosed by
  anything?" rather than "is it enclosed by the kind of wall I assumed?".
- `api.faux.fillDebug()` now reports every wall channel side by side, so a failed fill shows which kind of
  wall (if any) encloses the spot.

## 1.11.2 — 2026-07-30
### Fixed
- **Click-to-fill no longer rejects rooms that really are enclosed.** The check that decides whether a
  point is walled in measured the sweep's bounding box against the scene rectangle. A bounding box wildly
  overstates any room that isn't a neat rectangle — a diagonal or L-shaped space can have a box covering
  most of the map while enclosing very little — and the sweep is clipped to the canvas, which is larger
  than the scene rectangle, inflating the comparison further. It now measures the polygon's true area
  against the canvas.
- Added `game.modules.get("baileywiki-better-levels").api.faux.fillDebug({x, y})`, which reports what the
  wall sweep found at a point and why it was accepted or rejected.

## 1.11.1 — 2026-07-30
### Fixed
- **The Regions toolbar buttons are back** (Make Surface, Faux Overhead, Create Stairs). Better Levels was
  looking up the Regions control group by a key that did not match, and the guard around that lookup
  skipped the entire block without an error — so the buttons simply never appeared. Control groups are now
  located by their own name or layer rather than an assumed key, and a mismatch is reported in the console
  instead of failing silently.

## 1.11.0 — 2026-07-30
### Changed
- **The fill tool now works by clicking inside a space.** Press the paint bucket with nothing selected and
  click inside a tent, hut or alcove — Better Levels finds the walls enclosing that point and builds the
  Faux Overhead from them. No wall selection needed.
  - Selecting walls still works and takes priority, for cases where you want to say exactly which loop to
    use.
  - Clicking somewhere that isn't enclosed doesn't blanket the map: the fill is refused and you are told
    to close the gaps or select the walls instead.
  - Right-click cancels while waiting for your click.

## 1.10.2 — 2026-07-30
### Fixed
- **Filling a walled area now blocks line of sight as well as hiding artwork.** The fill created only the
  Faux Overhead behavior, which hides a token's art but does nothing to sight — so tokens above and below
  could still see each other, and the concealment was skin-deep. A Define Surface is now added alongside
  it, tagged across the levels that can see each other, exactly as Fix / Configure the Selected Entity
  would. (That is why running Fix on a filled region appeared to repair it: Fix was adding the behavior
  the fill had left out.)

## 1.10.1 — 2026-07-30
### Fixed
- **The Build Mode toolbar buttons are back.** A missing import in 1.10.0 threw partway through building
  the scene controls, so every tool registered after that point — Fill Walled Area, Mark Floor, Make
  Surface, Faux Overhead and Create Stairs — silently failed to appear.

## 1.10.0 — 2026-07-30
### Added
- **Fill a walled area with a Faux Overhead, in one click.** Select the walls enclosing a space — a tent,
  a hut, an alcove — and press the paint-bucket button in the **Walls** toolbar. Better Levels traces the
  wall loop, creates a Faux Overhead region matching it exactly, places it on the level ABOVE the walls
  (where it needs to be to hide anything beneath), and names and tags it.
  - This matters beyond convenience. Every concealment gap chased during testing came from a hand-drawn
    region not quite matching its walls, leaving a token inside the room but outside the polygon. A
    wall-traced region removes the discrepancy at source: the region *is* the room.
  - Foundry has a manual equivalent (Region Config → Shapes → "Create Shape from Controlled Walls"), but
    it produces a bare shape and leaves you to create the region, set its band, add the behavior and name
    it. This does all of it.
  - If the walls do not form a single closed loop it says which problem it found — a gap, a branch, extra
    walls beyond the enclosure — rather than just failing.
### Changed
- **The construction tools now appear only in Build Mode**, reducing toolbar clutter during play. The
  Build Mode toggle and the Better Levels panel button remain visible always.
- **Make Surface has a new icon**, freeing the paint bucket for the new fill tool.

## 1.9.19 — 2026-07-30
### Fixed
- **Removed the last per-frame cost from Faux Overhead.** Re-asserting concealment each frame was also
  re-running Foundry's full visibility calculation for every concealed token, sixty times a second — the
  remaining source of long animation-frame warnings in the console. The decision is now made only when
  something could have changed it (sight refresh, token movement, changing which token you control) and
  merely replayed each frame, which costs a few property writes.

## 1.9.18 — 2026-07-30
### Fixed
- **Concealed tokens really can no longer be targeted.** The previous attempt hooked a Token method that
  does not exist in Foundry v14, so it silently did nothing. Targeting is now released through the
  targeting event itself, which does fire.
- **Removed a per-frame drawing cost.** The marker drawn around a concealed token was having its geometry
  rebuilt on every frame once concealment moved to the renderer, which showed up in the console as long
  animation-frame handlers. It is now redrawn only when the token's size or the marker style changes.

## 1.9.17 — 2026-07-30
### Changed
- **Slightly wider footprint sampling for concealment** — a token's edge midpoints are now checked as
  well as its centre and corners, closing narrow gaps where a token inside a walled area fell between the
  sampled points and was drawn with a visible border around nothing. The reach is unchanged, so a token
  standing beside a bridge is still visible rather than vanishing.

## 1.9.16 — 2026-07-30
### Fixed
- **A concealed token no longer blinks in and out at all.** Concealment was applied in response to
  Foundry's refresh hooks, but Foundry also redraws tokens through paths that fire no hook, and can redraw
  again later in the same frame — so the effect was permanently racing the renderer, and the lost frames
  showed. It is now re-asserted each frame after rendering, so whatever Foundry has just drawn is
  overwritten before the frame reaches the screen. Only tokens already known to be concealed are touched,
  so a scene with nothing hidden costs nothing.

## 1.9.15 — 2026-07-30
### Fixed
- **A hand-drawn region that does not exactly trace its walls no longer leaves tokens exposed at the
  edges.** Concealment tested only the token's centre point, so a token standing fully inside a walled
  area could be drawn in plain view whenever the region stopped slightly short of the wall. It now samples
  the token's footprint, so partial overlap is enough — a token half under a bridge is hidden rather than
  revealed.

## 1.9.14 — 2026-07-30
### Fixed
- **The Hitbox-only marker no longer blinks.** It was Foundry's own selection border, which core shows and
  hides on its own schedule, so a concealed token flickered into view at random and announced itself.
  Better Levels now suppresses core's border while a token is concealed and draws its own steady marker.
- **"Keep this area lit" no longer reveals tokens standing in the lit area.** The vision mask carries both
  brightness and sight, so painting the region white marked it *seen* as well as lit — letting a token
  under the tent spot a token crossing the roof above. The brightness channel is now targeted specifically.

## 1.9.13 — 2026-07-30
### Fixed
- **A concealed token no longer gives itself away through its nameplate, hit-point bars, status icons or
  elevation badge.** Hiding the artwork while a floating "-10 ft" and a health bar hovered over an empty
  patch of map defeated the point. Those are hidden in every concealing mode now, including Hitbox only —
  where the selection border alone remains, since that is the hitbox.
- **A concealed token can no longer be targeted** by someone who cannot see it. Targeting handed out
  exactly the information the concealment exists to withhold, and let a player attack something they had
  no way of knowing was there. Selecting and dragging still work, so a GM can grab a token they have
  hidden; your own tokens are never affected.

## 1.9.12 — 2026-07-30
### Fixed
- **A concealed token no longer flickers into view from one exact spot.** The sight test that decides
  whether a hidden token is shown as a ghost was checking a ring of points around the token rather than
  the token itself, so a token standing just inside a wall counted as visible whenever one of those points
  happened to fall on the far side of it — true only from a particular viewer position, which is why the
  ghost appeared at a single place on the map and nowhere else. The test now uses the token's actual
  position.

## 1.9.11 — 2026-07-30
### Changed
- **Region behaviors are now labelled "Better Levels: ..."** — so the Add Behavior list groups everything
  this module contributes together instead of scattering it alphabetically. Faux Overhead now reads
  **Better Levels: Faux Overhead**.
- **The retired "phantomOverhead" entry is gone from the Add Behavior dropdown.** Its data model is still
  registered, so any region that has not yet been converted still loads and migrates rather than turning
  into an invalid document — it is simply no longer offered as something you can add.

## 1.9.10 — 2026-07-30
### Added
- **"Keep this area lit" on Faux Overhead regions.** A walled interior under a faux overhead had nothing
  with line of sight into it, so it read as unexplored fog — going darker still as scene darkness rose.
  The region's footprint is now marked as seen, so the area matches the brightness of the rest of the map.
  Holes in the region stay dark, so a gap in a bridge still reads as a gap. On by default; turn it off for
  something that SHOULD be dark, like a cave mouth.

## 1.9.9 — 2026-07-30
### Added
- **Better Levels now warns when a Faux Overhead lands on a floor-sized Surface region.** A Faux Overhead
  hides every token beneath it across its whole footprint — exactly what you want on a bridge, and
  catastrophic on a region big enough to be a floor, where it silently hides every token on every level
  below. That reads as a broken module rather than a mis-set region, so it is now called out twice:
  - a warning at the moment you switch it on, naming the consequence before your tokens vanish;
  - a new Audit rule, **"Faux Overhead on a floor-sized Surface"**, which finds it in scenes where it has
    already happened. Its fix removes the Faux Overhead and leaves the Surface untouched.
  Pairing the two on a small, bridge-sized region stays fully supported and is not flagged — footprint is
  what separates a bridge from a floor.

## 1.9.8 — 2026-07-30
### Added
- **A Faux Overhead button in the Regions toolbar**, directly below Make Surface. Select one or more
  regions and click it. This is the UI-native entry point — Foundry v14 has no Region HUD, so the toolbar
  and the region sheet were the only places it could live.
- **Faux Overhead regions are now named and flagged**, however you create them. A region marked from the
  toolbar, from Fix / Configure the Selected Entity, or by adding the behavior by hand in the region sheet
  all end up identical: named "Faux Overhead {level}" so it is findable in the Regions list, and flagged
  as Better Levels' own so the Audit treats it as deliberate rather than an unexplained region. A region
  you have already given a meaningful name of your own is never renamed.

## 1.9.7 — 2026-07-30
### Changed
- **Phantom Overhead is now called Faux Overhead.** The old name implied something semi-transparent,
  which is exactly what it is not — and it collided with the actual ghosting the feature does for
  observed tokens. Regions built under the old name keep working and are converted automatically the
  first time a GM loads the scene.

### Headline for the next public release
> **Any battlemap can now have levels — not just the ones designed for them.**
>
> Faux Overhead lets you draw a region over artwork that is already painted into the map — a bridge, a
> catwalk, an awning, a cave mouth — and have tokens travelling underneath disappear behind it, exactly
> as if an overhead tile were covering them. No tile is needed, and none is added. Whoever can genuinely
> see under there still sees a ghost of the token; everyone else sees nothing.
>
> That turns a whole category of maps into levels maps. Until now, multi-level play meant either a map
> built for it, with separate roof and floor tiles you could hide and reveal, or an evening spent cutting
> artwork apart to make them. Faux Overhead skips all of it: point at the part of the picture that should
> read as "above", and it behaves that way.

## 1.9.6 — 2026-07-30
### Fixed
- **Players no longer see the GM's Better Levels settings.** Six map-building preferences (Placeables tab
  thumbnails, tile drag-reordering, depth sorting, the Build Mode sync filter, the toolbar button and the
  auto-show panel) were per-user settings, which Foundry shows to everyone — so players got a settings
  page full of controls for tools they cannot open. The only Better Levels setting a player sees now is
  how their own token is drawn beneath a Phantom Overhead, which is genuinely theirs to choose.

## 1.9.5 — 2026-07-30
### Changed
- **A token ghosted beneath a Phantom Overhead now carries the same dashed outline as cross-level
  occlusion.** It is the identical outline, shared from one place in the code, so players learn a single
  convention: dashes mean "something is there that you can see, but cannot see properly". A token you can
  see under the bridge reads exactly like a token you can see through a floor.

## 1.9.4 — 2026-07-30
### Added
- **"Hitbox only" display option for Phantom Overhead** — the token's artwork disappears but its border
  and nameplate are left to Foundry, so you can still see where it is without seeing what it is.
### Fixed
- **Phantom Overhead no longer switches on token decorations that were meant to be hidden.** Restoring a
  token forced its nameplate, bars and elevation badge visible rather than putting back what was there,
  so an elevation badge appeared over tokens that never had one. It now records each token's original
  state before touching it and restores exactly that.

## 1.9.3 — 2026-07-30
### Fixed
- **A token hidden by a Phantom Overhead keeps its hitbox.** It was being made invisible outright, and
  PIXI skips invisible objects for hit-testing too, so the token could no longer be clicked or dragged.
  It is now drawn at zero opacity instead — nothing on screen, but still fully grabbable.
- **An observer with line of sight now sees a ghost of a hidden token**, instead of nothing at all. A
  viewer who can genuinely see under the bridge keeps that information, shown the same faded way as
  cross-level occlusion; a viewer with no line of sight still sees nothing. The token you are driving
  yourself still vanishes completely — it sees itself, so it would otherwise never disappear.

## 1.9.2 — 2026-07-30
### Added
- **Fix / Configure the Selected Entity now offers every region option in one dialog**: configure it as a
  Surface or a Stair (or leave the level configuration alone), switch **Phantom Overhead** on or off, and
  ignore it in the Audit. The role dropdown defaults to what Better Levels infers, so simply accepting the
  dialog does what it always did.
  - Phantom Overhead is a checkbox rather than a third role, because it is additive: a bridge painted into
    the map usually wants a Define Surface (blocking sight between levels) AND a Phantom Overhead (hiding
    the token's art from a GM whose vision is unconstrained). They are two halves of one illusion.
  - This is now the way to reach both region actions. The Region HUD they used to live on does not exist
    in Foundry v14, so those buttons were never reachable.

## 1.9.1 — 2026-07-30
### Fixed
- **Phantom Overhead now actually appears in the region's Behaviors dropdown.** Foundry only offers a
  document sub-type if the module manifest declares it, which ours did not — so the behavior was
  registered internally but unreachable from the UI. Requires a Foundry restart, not just a reload.

## 1.9.0 — 2026-07-30
### Added
- **Phantom Overhead — a region that hides tokens travelling beneath it.** For bridges, balconies,
  catwalks and cave mouths that are painted into the map art, where there is no tile to occlude with.
  Draw a region over the painted bridge, switch on Phantom Overhead, and tokens below it vanish exactly
  as if a never-occluding tile were covering them. Tokens standing on it, or above it, are untouched —
  it behaves like a floor. Holes in the region are respected, so a gap in a bridge shows through.
  - Available as a proper Region Behavior (region sheet → Behaviors → Phantom Overhead), so it can be
    enabled and disabled with core's own control and travels with the region through Mass Edit prefabs.
    There is also a one-click toggle on the Region HUD in Build Mode.
  - New client setting **"Under a Phantom Overhead, show"**: nothing (default), a faded ghost, or the
    token as normal. Each player and the GM choose their own, so a GM can keep track of a token their
    players cannot see.
  - This complements Define Surface rather than replacing it. A surface blocks line of sight between
    levels; Phantom Overhead handles the rendering, which is what hides a token from a GM with full
    vision. Use both on the same footprint for a complete illusion.

## 1.8.8 — 2026-07-30
### Fixed
- **Closing the helper panel now also leaves Create Stairs mode**, for the same reason it leaves Build
  Mode: the panel is the only place either mode is visible, and with it closed every region you draw
  would silently become a stair. Both modes switch off on every close path.

## 1.8.7 — 2026-07-30
### Fixed
- **Closing the helper panel now leaves Build Mode.** Build Mode hides every tile and region above the
  level you are working on, and the panel was the only thing on screen saying it was switched on — so
  closing the panel left the scene silently missing its roofs, with no visible control to explain or undo
  it. Build Mode now switches off on every close path (the panel's own button, the window header, ESC, and
  the automatic dismissal on scenes without multiple levels), restoring exactly the tiles and regions it
  had hidden.

## 1.8.6 — 2026-07-29
### Fixed
- **The level visibility grid no longer clips its labels.** The grid was being compressed to fit its
  container, so the row and column names overflowed and were cut off — widening the window freed up the
  first column but never the headers. The grid now keeps its natural size and scrolls sideways if it has
  to, and column headers read bottom-to-top so a long level name no longer needs a metre of width.
### Changed
- **Both axes of the visibility grid now show each level's elevation band** alongside its name, so levels
  whose names only differ near the end ("Level - Castle Deck" / "Level - Castle Keep") can be told apart.
  The full label is also available on hover.
- The Level Manager opens slightly wider, so a twelve-level building's grid fits without resizing.

## 1.8.5 — 2026-07-28
### Changed
- **The Floor / Roof / Basement / Balcony buttons on the Tile HUD are now toggles, and the active one
  lights up blue.** A tile is exactly one thing, so the four roles behave like radio buttons: the role a
  tile already carries is highlighted, and clicking a different one switches to it. You can now see what
  any tile was meant to be at a glance, without opening a dialog.
- **Clicking a tile's current role clears it**, the same way the Ignore toggle works. Clearing restores
  the occlusion, light/weather restrictions, level tags and elevation the tile had *before* Better Levels
  first configured it — captured once when the first role is applied, so switching roles never overwrites
  the original. The Surface region is removed too, but only if Better Levels created it and no other tile
  is still using it; hand-drawn and shared regions are unlinked and left alone.

## 1.8.4 — 2026-07-28
### Fixed
- **The Level Manager now scrolls.** On scenes with many levels the window grew past the bottom of the
  screen — a ten-storey tower put Add Level, Commit and Cancel out of reach with nothing to scroll. The
  window is now capped to the viewport, the level table and visibility matrix scroll, and the action bar
  stays pinned at the bottom where it is always clickable. The Backups, Status and Sample Scenes windows
  got the same ceiling, since their lists can grow without bound for the same reason.

## 1.8.3 — 2026-07-28
### Changed
- **The "tiles with no role assigned" notice now identifies each tile by id as well as name.** Scenes
  routinely contain several copies of the same art, so ignoring one copy left an identical-looking
  finding behind and made the ignore toggle appear broken when it had worked. Each tile is now listed as
  "name [id]", so duplicates are visibly distinct entities.

## 1.8.2 — 2026-07-28
### Fixed
- **"Floor openings carry through" findings no longer come back after being fixed.** The fix genuinely
  worked — the opening really was copied into the surface below — but the audit kept re-reporting it. The
  check asked "does the lower surface have a hole containing this point?", using the opening's average
  centre; for a CONCAVE opening (an L-shaped stairwell is the usual case) that centre lies outside the
  opening's own outline, so the answer was "no" even immediately after it had been copied. Detection is
  now structural — matching the opening's geometry, plus a record of what's already been carried down —
  so a fixed opening stays fixed.
- **Findings involving same-named regions are now distinguishable.** A scene often has several regions
  called e.g. "Surface Level 02 (10 | 20)", which produced findings that looked identical; each now
  carries a short id and the number of openings involved.

## 1.8.1 — 2026-07-28
### Fixed
- **Audit findings now name the tile the way the Placeables tab does.** Tile findings read
  "Tile a1b2c3" — an internal id you can't search for — because the label was reading a flag the module
  never writes. It now uses the tile's actual name, falling back to its texture filename, so a finding
  can be located immediately in the Placeables list. The "tiles with no role assigned" notice also lists
  the tiles by name instead of only naming the level.

## 1.8.0 — 2026-07-27
_Stable release — rolls up everything since 1.7.5._

### Added
- **Ignore a tile, region or light in the Audit.** An eye toggle on the Tile HUD, and an "Ignore this
  entity in the Audit" checkbox in the Fix / Configure dialog, remove that entity from every audit rule
  that inspects it — so deliberate decoration, backdrops and one-off art stop being reported without
  switching a whole rule off for the scene. It's reversible from either place, and the Fix dialog reaches
  entities the HUD can't (Build Mode hides overhead tiles — select them in the Placeables list instead).
  The default is unchanged and deliberate: an untouched tile is still audited **and** still reported as
  having no role assigned, because "untagged" usually means "forgot", not "deliberate".

### Changed
- **The sample Tudor scene now audits completely clean.** Its structural tiles are tagged and audited;
  its decoration and backdrop tiles are marked ignored. Importing it shows a finished scene rather than a
  list of notices, and demonstrates the tag-it / ignore-it decision on every tile.

### Fixed
- **"Show visible tokens only" (experimental): hovering a ghosted token no longer wipes the roof above
  it** on the GM view. Core's occlusion mask takes surfaces as well as tokens, and hovering a token
  nominates the surfaces above it — drawn across their whole footprint. Ghosted tokens are now kept out
  of hover entirely, and the ghost provides its own highlight and click-to-target. Player-side behaviour
  can still vary depending on your module set; the feature remains off by default.

## 1.7.12 — 2026-07-27
### Changed
- **The sample Tudor scene now audits completely clean (0 issues).** Its 10 decoration and backdrop
  tiles are marked "ignore" and its 6 structural tiles stay tagged and audited, so importing the sample
  shows a finished scene rather than a list of notices — and it doubles as a worked example of the
  tag-it / ignore-it decision on every tile in a scene.

## 1.7.11 — 2026-07-27
### Added
- **"Ignore this entity in the Audit" is now also on the Fix / Configure dialog** — and it covers
  regions and lights, not just tiles. Build Mode hides overhead tiles, which put the HUD's eye toggle
  out of reach exactly when you wanted it; the Fix dialog is reachable for anything you can select in
  the Placeables list, so it carries the same switch. It's also where you turn ignoring back OFF.
  Ticking it is a terminal choice — the entity is silenced and nothing else is reconfigured.
- Ignoring now silences **every** rule that inspects that entity, for tiles, regions and lights alike.

### Note
- The default is unchanged and deliberate: an untouched tile is still audited **and** still reported as
  having no role assigned, because "untagged" usually means "forgot", not "deliberate". Only an explicit
  ignore silences anything.
## 1.7.10 — 2026-07-27
### Added
- **"Ignore this tile" toggle on the Tile HUD.** Alongside the Floor / Roof / Basement / Balcony buttons
  there's now an eye toggle that removes a tile from the Audit's consideration entirely — every tile rule
  skips it, including the "no role assigned" notice. Use it for deliberate decoration, backdrops and
  one-off art so they stop being reported without switching a whole rule off for the scene. It's a
  toggle, so a tile can be put back under supervision at any time, and the button shows which state it's
  in. Tagging says "check this forever"; ignoring says "never check this" — between them, everything in a
  scene has a deliberate answer.
## 1.7.9 — 2026-07-27
### Fixed
- **Token-reveal: ghost hover block now registers through libWrapper.** On player clients the block
  installed and applied but the hover registered anyway — a silent load-order fight, which libWrapper had
  already warned about in the console ("Detected non-libWrapper wrapping ... by module
  baileywiki-better-levels"). The hover gates are now registered via libWrapper when it's present, so
  they sit in the composed wrapper chain regardless of which other module patches the same methods or
  when. Worlds without libWrapper keep the previous direct patch. `api.tokenReveal.debug()` now reports
  `hoverVia` so the install path is visible.
## 1.7.8 — 2026-07-27
### Fixed
- **Token-reveal: ghost hover now blocked on player clients too.** 1.7.7 fixed this for the GM but not
  for players — the block was installed and applicable, yet the layer still recorded the hover, so the
  roof still vanished. Refusing the hover from `_onHoverIn` turned out not to be enough. The block now
  also refuses at `_canHover`, which core consults *before* a hover is initiated, so the hover never
  starts and nothing downstream (layer hover state, surface nomination, perception refresh) can run.
## 1.7.7 — 2026-07-27
### Fixed
- **Token-reveal: hovering a ghost no longer wipes the roof — blocked at the source.** 1.7.6 tried to
  have the ghost capture the pointer; the sprite is interactive but the real token underneath still
  registered as hovered. Rather than keep chasing which core path consumes that hover, a ghosted token
  now never enters hover at all, so no hover-driven behaviour — including the surface nomination that
  draws a whole roof into the occlusion mask — can fire for it. Narrowly scoped: only tokens that
  currently have a ghost, and only while the feature is enabled. Your own tokens, same-level tokens and
  uncovered tokens hover normally. The ghost supplies its own highlight and click-to-target.
## 1.7.6 — 2026-07-27
### Fixed
- **Token-reveal: hovering a ghost no longer wipes the roof above it.** Root cause found in core's
  occlusion mask, which has TWO inputs — occludable tokens, and "occluded surfaces". Hovering a token
  nominates the surfaces above it, and a hovered surface is drawn into the mask across its ENTIRE
  footprint — so the whole roof vanished rather than a sightline-shaped patch. Every filter we had
  targeted the token half, so it could never touch this. The ghost sprite now captures the pointer
  instead of letting it fall through to the real token underneath, so nothing beneath it is ever
  hovered, no surface is nominated, and the cover stays drawn. The ghost also now provides its own
  hover highlight and can be clicked to target the real token (shift-click adds to existing targets).
## 1.7.5 — 2026-07-27
_Stable release — rolls up everything since 1.7.0._

### Added
- **New audit rule: "Tiles with no role assigned (unmonitored)."** Every floor/roof check — surface
  region, occlusion, light and weather, fog reveal — only inspects tiles you've marked as Floor, Roof,
  Basement or Balcony. That meant a half-configured scene could audit completely clean while unmarked
  tiles went unchecked. The audit now reports, per level, how many tiles are unmonitored and points you
  at the tile HUD buttons or "Mark selected tiles as Floor". It is deliberately informational with **no
  auto-fix**: Better Levels can't tell a floor plate from a rug or a shadow overlay, and guessing would
  create surface regions your tokens then stand on. It sits in the green (safe) category, and you can
  switch it off for scenes that are mostly props.

### Changed
- **Bulk fixes now post one summary instead of dozens of notifications.** Fix All, the per-category Fix
  All buttons, "Mark selected tiles as Floor" and multi-select Fix Entity previously fired a toast for
  every tile and region they touched, burying the result. They now report once, with a breakdown of what
  changed ("Fixed 23 issue(s) — Floor tile has no Define Surface region (8), Stair spans its connected
  levels (5), …"), and the full detail goes to the console. Warnings and errors are never suppressed.

## 1.7.4 — 2026-07-27
### Added
- **New audit rule: "Tiles with no role assigned (unmonitored)."** Every floor/roof check is gated on a
  tile's role, so a tile you've never marked was skipped by all of them — meaning a half-configured scene
  could audit completely clean. The audit now reports, per level, how many tiles are unmonitored and
  points at the tile HUD / "Mark selected tiles as Floor". It is deliberately informational with NO
  auto-fix: Better Levels can't tell a floor plate from a rug or a shadow overlay, and guessing would
  create surface regions your tokens then stand on. Green bucket; switch it off for prop-heavy scenes.
### Changed
- **Bulk fixes now post ONE summary notification instead of dozens.** Fix All, per-category Fix All,
  "Mark selected tiles as Floor" and multi-select Fix Entity previously fired a toast per tile and per
  region, burying the result. The per-entity notices are now suppressed for bulk runs and replaced by a
  single summary with a per-rule breakdown ("Fixed 23 issue(s) — Floor tile has no Define Surface region
  (8), Stair spans its connected levels (5), ..."), with the full detail logged to the console. Warnings
  and errors are never suppressed.
## 1.7.3 — 2026-07-26
### Changed
- **Reverted the experimental player-occlusion setting** that briefly appeared in testing builds
  1.7.1/1.7.2. Investigation showed the "hover reveals the building" behaviour wasn't hover-driven at all
  (tiles aren't player-interactive; occlusion is a per-pixel mask fed by a token bitmask), and the
  restriction wasn't solving a real problem. Player-side occlusion is back to Foundry's stock behaviour.
  Kept for the record: the mechanism is `TokenLayer#occlusionMode`, a union of
  `CONST.TOKEN_OCCLUSION_MODES` (OWNED 1, CONTROLLED 2, HOVERED 4, HIGHLIGHTED 8, VISIBLE 16), consulted
  by `_getOccludableTokens` — if this ever does need restricting, that getter is the lever.

## 1.7.0 — 2026-07-26
_Stable release — rolls up everything since 1.6.0._

### Added
- **Show visible tokens only (EXPERIMENTAL, module setting, default off).** Brings back the v13 Levels
  behaviour for cross-level sightlines. In v14, when a token sees a token on another level (through a
  window or floor opening), core unoccludes every tile above it — exposing its entire surroundings — and
  can even remove the floor under the viewer. With this on, cross-level tokens no longer trigger tile
  unocclusion; each seen token is instead drawn on top of its cover as its artwork with a dashed outline,
  tracking true line of sight per client. Seen tokens stay hoverable and targetable; any number can be
  revealed at once. Same-level occlusion (a roof fading over your own token) is untouched.
- **Level Manager visibility grid.** A matrix showing which levels each level can see (its "Visible
  Levels"), with click-to-toggle eyes for any pair in either direction, and a "Reset to policy" button.
  Changes apply on Apply; once you hand-customise visibility, the audit stops overriding it.
- **New audit rules that close real cross-level sight leaks:** every roof tile must carry a Define Surface
  region; every surface must be assigned to its level and every level that can see it (this replaces the
  old one-level-per-surface model — the audit fix re-tags them); floor/roof openings (stairwells,
  trapdoors, balconies) must be carried through to the surface of the level below, and the fix copies them
  down; floor/roof/basement/balcony tiles must occlude light and weather; one-way stairs (top edge not
  inclusive) are detected and fixed; a level with content but no surface gets one created.
- **Every audit rule now teaches.** All rules carry a rewritten "what's wrong → why it matters → what the
  fix does" explanation, shown on the issue's "Why this change?" expander AND as a hover tooltip on each
  rule toggle — the Audit doubles as a course in how Foundry v14 Levels works.

### Changed
- **Audit window overhaul:** results scroll; Red / Amber / Green categories collapse, each with its own
  "Fix All (n)" button; the Rules list is grouped by the same severities. Fewer, clearer rules: the two
  region-naming rules merged (surfaces and stairs still named distinctly), the stair-topology rules merged
  into one, and duplicate "missing surface" reports were eliminated.
- **Build Mode now hides overhead regions as well as overhead tiles**, so the level you're working on is
  the one you can grab — visuals only, occlusion behaviour untouched.
- **Sample Tudor scene rebuilt as a reference:** roof surfaces assigned upward, proper floor openings
  carried through between levels, window walls (sight/light proximity) instead of invisible walls, floor
  tiles marked as floors, and the whole scene audits clean.

### Fixed
- **Changing a token's level now lands it exactly on the destination floor** — up or down, including the
  first change after a scene load. (Previously the elevation correction collided with core's move
  animation and stopped at the midpoint, showing a stray elevation badge.)
- **Auto-configuring a roof reliably sets Better Roofs' "Reveals Fog of War"** (now written via the
  canonical flag API), both from the HUD and from the audit fix.
- **The audit again catches a level whose surface region was deleted.**

## 1.6.29 — 2026-07-26
### Fixed
- **Token-reveal ghost artwork renders — root cause was z-order.** The interface group sorts its children
  by zIndex, and at the default of 0 the ghost sprite sat beneath the fog/vision overlay — which covers
  exactly the unseen areas ghosts appear in, so the artwork was drawn and then painted over every frame
  (thin bright outline dashes survived visually; the art didn't). Confirmed on-camera: raising the
  sprite's zIndex made the artwork appear instantly. Ghost sprites and outlines now claim a high zIndex at
  creation.
## 1.6.28 — 2026-07-26
### Fixed
- **Token-reveal ghost artwork: flattened rendering.** With a healthy texture confirmed, the last variable
  was structure: a bare sprite added directly to the interface group rendered every time on camera, while
  the identical sprite nested inside our wrapper containers rendered nothing. Ghost sprites and outlines
  are now direct children of the interface group (no wrapper layer), exactly mirroring the configuration
  proven to work. Orphan-safety now uses a name prefix + sweep instead of a parent container.
## 1.6.27 — 2026-07-26
### Fixed
- **Token-reveal ghost artwork finally renders.** Root cause found on-camera: the ghost preferred the
  token's mesh texture — but core destroys the mesh of an invisible token, and a destroyed base texture
  keeps `valid: true` and its frame metadata while uploading nothing to the GPU. Every diagnostic said the
  sprite was healthy while it drew pure nothing. Ghosts now always build their own URL-cached texture from
  the token's image source and never touch the mesh, so the seen token's artwork appears inside the dashed
  outline.
## 1.6.26 — 2026-07-26
### Fixed
- **Token-reveal ghost artwork: second pass.** The previous fix leaned on Foundry's texture-loader
  globals, which have moved across versions and returned nothing. The ghost now loads its artwork via
  PIXI's own URL-cached loader, independent of Foundry's API surface, and re-renders when a first-time
  load completes. Ghost internals (texture validity, sprite visibility, source path) are now included in
  `api.tokenReveal.debug()`.
## 1.6.25 — 2026-07-26
### Fixed
- **Token-reveal ghosts now show the token's artwork, not just the dashed outline.** The ghost cloned its
  image from the token's canvas mesh — which core never draws for a token that's invisible under cover, so
  the clone was empty. The ghost now loads the artwork from the token's texture source directly (cached,
  with an async load on first sight), so the seen token appears as its art with the dashed outline around
  it.
## 1.6.24 — 2026-07-26
### Fixed
- **Token-reveal: stale dashed outlines can no longer linger.** A canvas redraw (switching levels, viewing
  a scene) could strand a previous ghost layer — its registry entries were dropped but the sprites kept
  rendering, un-removable until F5, which also made both sight directions look broken. Every ghost refresh
  now sweeps the canvas for any ghost container that isn't in the live registry and destroys it, so an
  orphaned outline can survive at most one refresh. A failure updating one token's ghost also no longer
  aborts the pass that removes out-of-sight ghosts.
## 1.6.23 — 2026-07-26
### Fixed
- **Token-reveal ghosts now follow core's own seen-under-cover verdict.** Neither `token.visible` (always
  true for GMs) nor a manual sight test tracked line of sight reliably. The ghost set is now keyed off
  core's own occludable-token list — the exact set core would have revealed by unoccluding tiles, and the
  same signal that drives the elevation tag. The ghost is a one-for-one substitute for core's suppressed
  reveal: token enters the list (tag appears) → ghost appears; line of sight breaks (tag disappears) →
  ghost and dashed outline disappear with it.
## 1.6.22 — 2026-07-26
### Fixed
- **Token-reveal ghosts now track true line of sight, and disappear the moment it breaks.** The ghost was
  keyed off `token.visible`, which on a GM client is always true — so ghosts persisted after line of sight
  was lost (exactly when the elevation tag disappeared). Ghosts now use the same elevation-aware vision
  test core uses (testVisibility with the token as the tested object), against the viewer's active vision
  source. When sight breaks, the ghost and its dashed outline vanish with it. With no active vision source
  (GM, nothing controlled) it falls back to the old behaviour.
## 1.6.21 — 2026-07-26
### Fixed
- **Token-reveal: ghosts re-evaluate after every token move.** Moving out of line of sight could leave a
  stale ghost (dashed outline) behind, because nothing re-ran the sight test after the move committed. Any
  committed token move now forces a full vision + occlusion recompute and re-evaluates the ghosts once the
  new visibility state lands.
## 1.6.20 — 2026-07-26
### Fixed
- **Token-reveal now actually stops the cross-level unocclusion.** Reading core's source showed the
  occlusion mask is fed from `TokenLayer._getOccludableTokens` — not the method patched previously — and
  every token in that list punches its vision/radial shape into the mask at its elevation, which is what
  made the tiles above a seen token (and the floor under the viewer) vanish. The filter now sits on that
  method: with "Show visible tokens only" enabled, tokens on other levels never enter the occlusion mask,
  so cover stays opaque and only the ghost reveals them. Same-level occlusion (a roof fading over your own
  token) is untouched.
## 1.6.19 — 2026-07-26
### Fixed
- **Token-reveal ghosts (dashed outlines) now appear only while the cover is actually opaque.** The ghost
  was drawn for any visible cross-level token under a tile, even when that tile was already faded — so the
  dashed outline sat on tokens you could see plainly. A ghost now requires the covering tile to be
  currently un-occluded (opaque), disappears the moment the cover fades, and is never drawn on a token you
  control. Ghosts also react to tile fade changes as they happen.
## 1.6.18 — 2026-07-26
### Fixed
- **Token-reveal no longer crashes canvas initialization.** Ghost sprites from the previous scene draw
  were destroyed by PIXI with the canvas, but stale references survived and the controlToken hook (which
  fires mid-canvas-draw) touched one — throwing inside core's initialization and leaving the scene draw
  half-broken. Ghost references are now forgotten at canvas teardown, destroyed objects are purged before
  any touch, refreshGhosts can never throw into a core hook, and controlToken stands down until the canvas
  is ready.
## 1.6.17 — 2026-07-26
### Added
- **EXPERIMENTAL — "Show visible tokens only" (module setting, default off).** Brings back the v13
  Levels behaviour for cross-level sightlines. In v14, when Token A sees Token B on another level
  (through a window or a floor opening), core unoccludes every tile above B — exposing B's entire
  surroundings — and can even remove the floor tile under A. With this setting on: cross-level tokens no
  longer trigger tile unocclusion (the viewer's surroundings and the seen token's cover stay intact), and
  each seen token is instead drawn on TOP of whatever covers it with a dashed outline, marking it as seen
  through cover. Supports any number of simultaneously seen tokens; the real token stays hoverable and
  targetable. Diagnostic: `api.tokenReveal.debug()`.
## 1.6.16 — 2026-07-26
### Fixed
- **The Audit's Rules list now shows the teaching tip on hover.** The rewritten "why it matters"
  explanations were only attached to found issues; hovering a rule toggle at the bottom of the Audit
  window showed nothing. Each rule toggle now carries its explanation as a hover tooltip.
## 1.6.15 — 2026-07-26
### Changed
- **Sample Tudor scene: proper floor openings on Levels 02 and 03**, carried through to the surfaces
  below them, so the scene now demonstrates working cross-level line-of-sight through the stairwell/floor
  openings. The scene audits clean (0 issues).
## 1.6.14 — 2026-07-26
### Added
- **Build Mode now hides overhead REGIONS, not just tiles.** With unified surface tagging, every surface
  region is drawn on every level, so they stack on top of each other and the wrong one grabs your click.
  Build Mode now hides regions whose own level sits above the level you're working on — the same overhead
  rule it already uses for tiles — leaving the current level's surface easy to select. It only affects the
  region outline you see/grab; a region's occlusion (its Define Surface behavior) is untouched.
### Changed
- **Sample Tudor scene: the three floor tiles are now marked as Floor** (linked to their surfaces), so a
  deleted floor surface is caught and rebuilt per-tile with its own footprint.
## 1.6.13 — 2026-07-26
### Fixed
- **Audit again catches a level whose surface was deleted.** After the unified surface tagging (every
  surface is tagged to every visible level), the "level has no floor surface" check was fooled — as long
  as any surface survived, every level looked covered. It now checks for a surface that physically sits at
  the level's own band, so deleting a level's surface is detected again.
## 1.6.12 — 2026-07-26
### Added
- **Audit now carries floor openings through to the level below.** A hole in a floor or roof surface (a
  stairwell, balcony opening or trapdoor) has to exist in the surface of the level directly beneath it too
  — otherwise that lower floor (which now occludes on the upper level) re-blocks the view and tokens on the
  two levels can't see each other through the opening. The new "Floor openings carry through to the level
  below" rule detects this and copies the opening down. A single opening drops exactly one level; a true
  multi-storey atrium (each floor has its own opening) links all the way down; openings never cross a
  sealed basement. Openings are read directly from the traced surface shapes — no image analysis — so
  detection and the fix are exact.
## 1.6.11 — 2026-07-26
### Changed
- **Unified how surfaces are tagged — simpler and more correct.** The two surface rules ("surface tagged
  to exactly its level" and "roof reaches every level above") are replaced by one: **a surface must be
  assigned to its own level and every level mutually visible with it.** A surface only occludes on the
  levels it's assigned to, so this is what makes it block cross-level sight in BOTH directions — closing an
  upward-occlusion gap the old floor-only tagging left open. Basements stay sealed automatically. The
  audit's single "Surface reaches every level that sees it" rule (and Fix All / Fix Entity, and every
  auto-configure/drop path) now apply this. The sample Tudor scene's surfaces were re-tagged to match.
## 1.6.10 — 2026-07-26
### Added
- **Audit now catches the cross-level occlusion leak.** Two new rules: **a roof tile must have a Define
  Surface** (or it can't occlude the space below it), and **a roof surface must be assigned to its level
  AND every level above it** — otherwise a token standing higher sees straight down through the roof. Fix
  All and Fix Entity both create/extend the roof surface with the right coverage, and auto-configuring a
  roof now assigns its surface to every level above automatically.
### Changed
- **Every audit rule now has a "why it matters" explanation.** The hover tips were rewritten to teach the
  Levels concept behind each check, not just describe the fix — so the Audit doubles as a way to learn how
  Foundry Levels actually work.
- **The Audit's visibility-policy rule now respects hand-set visibility.** Once you customise a scene's
  level visibility in the Level Manager grid, the audit stops flagging (and offering to overwrite) your
  choices.
- **`roof-infinity-region` reworded.** It now explains that an infinite roof top only matters for a token
  flying above the top level — it does not affect a token standing on a defined level above (that's the new
  roof-coverage rule), clearing up a misleading message.
- **Fewer, clearer rules.** The two region-naming rules merged into one (surfaces and stairs are still
  named distinctly), and the overlapping stair-topology rules merged into a single "stair connects the
  right levels." "Level missing a surface" and "floor tile missing a surface" no longer double-report the
  same level.

## 1.6.9 — 2026-07-26
### Fixed
- **The Level Manager visibility grid now saves.** Toggling a visibility cell and clicking Apply reported
  "No level changes to apply" and reverted, because Apply only checked for level create/rename/delete and
  ignored visibility edits. A visibility-only change is now detected and applied directly (no backup
  dialog, since it's non-destructive).

## 1.6.8 — 2026-07-26
### Added
- **Level Manager now has a visibility grid.** A matrix at the bottom of the Level Manager shows, at a
  glance, which levels each level can see (its "Visible Levels"). Every cell is an eye you can click to
  toggle visibility on or off between any two levels, in either direction. A "Reset to policy" button
  re-seeds the whole grid from the default (above-ground levels see each other; basements sealed), and
  your choices are written on Apply. New levels join the grid once applied.
### Changed
- **The Audit's Rules list is now grouped by severity.** The enable/disable rule toggles at the bottom of
  the Audit window are split into the same Red / Amber / Green categories as the issues — so you can see
  each rule's nature at a glance and find related rules together.

## 1.6.7 — 2026-07-26
### Fixed
- **The FIRST level change after a scene load now sets elevation too.** Everything worked except the very
  first attempt after a load/refresh, which changed the level but left the old elevation (stray elevation
  badge). Cause: on the first move the token's movement machinery isn't warmed up yet, so there's no
  animation promise to wait on and our teleport landed while core's move was still open and got dropped.
  The elevation snap is now re-asserted on the next frame, after that operation closes, so the first move
  behaves like every subsequent one. Warm moves are unaffected (the re-assert no-ops).

## 1.6.6 — 2026-07-26
### Fixed
- **Level-change button works again, and tokens land exactly on the destination floor (up and down).**
  1.6.5 tried to fold elevation into core's move inside preUpdateToken — v14 forbids movement changes
  there and silently aborted the whole update, so the level buttons went dead. Reverted. The elevation
  correction now waits for core's level-change move to finish (Token#movementAnimationPromise), then
  snaps elevation to the new level's floor with the v14 `teleport` option (instant, no animation to
  collide with). This replaces the old `animate:false` write, which the v14 movement pipeline ignored —
  the reason the token kept stopping at the midpoint (the "-5" badge).

## 1.6.5 — 2026-07-26
### Fixed
- **Changing a token's level now lands it exactly on the destination floor — the real fix.** The
  correct elevation is now folded into core's own level-change move *before* it commits (via
  preUpdateToken), so the token makes a single movement to the right spot. The previous approach wrote
  elevation in a second, separate update, which going up got overridden by core's in-flight move
  animation and stopped at the midpoint (the "-5" badge). A teleport fallback still covers any path
  where the level isn't known until after commit.

## 1.6.4 — 2026-07-26
### Fixed
- **Sending a token UP a level now lands it exactly on the destination floor.** Changing a token's level
  via the HUD moved it correctly going down, but going up it settled 5 short of the floor (the "-5"
  elevation badge). Cause: our elevation correction was animated and collided with core's in-flight
  up-move animation, stopping at the interpolated midpoint. The correction now teleports (no animation),
  so the token snaps straight to the new level's floor in both directions.

## 1.6.3 — 2026-07-25
### Fixed
- **Auto-configuring a roof (and the audit fix) now reliably sets Better Roofs' "Reveals Fog of War".**
  The flag was being written as a foreign-module dot-path key folded into a large tile update that also
  carried Mass Edit's `ignoreLinks` option — a fragile combination that didn't always land. It's now
  written with Foundry's canonical `setFlag` API, both when you Auto-configure Floor/Roof and when Fix
  All / Fix Entity apply the "roof missing Reveals Fog of War" rule.

## 1.6.2 — 2026-07-25
### Changed
- **The Audit window is now scrollable, its severity categories collapse, and each has its own "Fix All".**
  Long audit lists no longer run off the bottom of the window — the results scroll while the scene header
  stays pinned. Click a category header (Red / Amber / Green) to collapse or expand it, and each category
  now has its own **Fix All (n)** button so you can clear the low-risk Greens and Ambers in one click
  without touching the Reds. The window opens at a sensible height and is resizable.

## 1.6.1 — 2026-07-25
### Fixed
- **Audit now auto-fixes floors that are missing a surface region** instead of just telling you to run
  Auto-configure Floor. "Level has content but no Define Surface region" is no longer a dead-end
  suggestion — Fix All (and Fix Entity) create the surface: configuring the level's floor tiles if it has
  any, otherwise a level-wide floor so tokens have somewhere to stand.
- **Audit now catches floor/roof tiles that aren't set to occlude light and weather.** A new rule flags
  any floor, roof, basement or balcony tile whose "restrict light / restrict weather" boxes are off, and
  the fix turns both on so light and weather stop bleeding through between floors.
- **Audit now catches one-way stairs.** A stair whose elevation reaches the upper floor but has the
  top edge set to *exclusive* only works going up — a token on the upper floor can't travel down. The
  audit flags this (even when the band is otherwise correct) and the fix sets the top to inclusive.
  Fix Entity applies the same correction, and no longer treats such a stair as already-correct.

## 1.6.0 — 2026-07-25
_Stable release — rolls up everything since 1.5.2._
### Fixed
- **Cross-level token vision is no longer affected by the Placeables filter.** "Sync to Levels
  Elevation" now filters only the Placeables *sidebar list* — it never changes what's drawn on the
  canvas. Previously, with Sync on (the default), tokens standing on other floors could be hidden from
  view, and from each other's line of sight, so combatants couldn't see one another between levels. If
  you build multi-level scenes, this is the important one.
- **Build Mode no longer disturbs tile rendering when it's off.** It now leaves tile visibility entirely
  to Foundry unless you're actively using it to build.
- **The "corrupt region shapes — Repair" warning no longer stacks banners on your map.** When a scene
  has broken regions, the Repair action lives on a quiet button in the helper panel instead.
### Added
- **Setting: "Sync to Levels Elevation only in Build Mode"** (default off). Optionally restrict the
  placeables-list filtering to Build Mode, so the list shows everything during play.

## 1.5.9 — 2026-07-25
### Changed
- **Sync to Levels Elevation is now sidebar-only — it never touches the canvas.** This is a rewrite back
  to a clean baseline. Every token-vision problem in the 1.5.x line came from one root cause: Sync drove
  core's *own* placeable filter, which culls placeables on the CANVAS (and a token culled from the canvas
  loses line of sight). Sync now does one thing — hide rows in the Placeables sidebar list — by toggling
  each row's display, with zero effect on the canvas. Consequences: cross-level token vision can no longer
  be affected by Sync on ANY tab; all the token-tab/active-layer/perception-refresh workarounds are gone;
  the feature is far simpler and can't regress vision again. The list still narrows to the level you're
  working on, the "only in Build Mode" setting still applies, and the Token tab's list is left unfiltered.

## 1.5.8 — 2026-07-25
### Fixed
- **Tokens vanished whenever the Token tools or Token placeables tab were active (with Sync on).** The
  placeables filter state is effectively shared and applied to whichever tab is active, so the elevation
  filter set for the Tiles tab culled the tokens the moment the token layer became active — and per-tab
  clearing couldn't win because the refresh loop kept re-applying it. Sync now keys off the **active
  canvas layer**: while the token layer is active (token tools or the Token tab), the filter stands down
  entirely and the canvas is refreshed so tokens are fully visible; leaving it re-applies the filter to
  the tab you moved to.

## 1.5.7 — 2026-07-25
### Fixed
- **Regression from 1.5.6: tokens vanished whenever the Token tools or Token placeables tab were active.**
  The "is this the Token tab?" check read one signal that could return a truthy-but-wrong value (a
  "tokens" collection name instead of the "Token" document name), so the Token tab wasn't recognised —
  and instead of being *cleared*, its filter was *applied*, hiding the tokens. The new tab-activation
  hooks then fired that on token-tools activation too, making it constant. The check now matches every
  naming signal case-insensitively, so the Token tab is always recognised and never filtered.
- `api.syncLevels.debug()` now prints `isTokenTab` per tab so this is verifiable at a glance.

## 1.5.6 — 2026-07-25
### Fixed
- **Follow-up to the token-vision fix: the Token tab now clears its filter the moment you land on it, and
  the canvas actually re-renders the tokens.** The previous build stopped *us* from filtering tokens, but
  a filter already applied (including one inherited from shared filter state) lingered, and clearing it
  didn't tell the canvas to recompute vision — so tokens stayed hidden. Switching Placeables sub-tabs now
  drives it: landing on **Tokens** clears any level/elevation filter and issues a perception refresh so
  the tokens come back; leaving it re-applies the filter to whatever tab you moved to. Works on first
  open too, even if Tokens is the tab shown.

## 1.5.5 — 2026-07-25
### Fixed
- **THE cross-level vision bug: the Placeables Sync filter was culling tokens from the canvas, not just
  the sidebar.** Core's placeable filter hides matching placeables on the canvas too — harmless for
  tiles/lights/walls, but a token filtered off the canvas is filtered out of *vision*. With Sync on, a
  token on another level got culled to match the current floor, so combatants couldn't see each other
  across levels. **The Token tab now never filters by elevation — a hard rule, no setting.** Line of
  sight between levels is preserved whether Sync is on or off.
### Added
- **Setting: "Sync to Levels Elevation only in Build Mode"** (default off). When on, the Placeables list
  only narrows to the current level while Build Mode is active, and shows everything during play — so the
  filter is a building aid rather than something that quietly changes your view mid-session. Tokens are
  never filtered regardless.

## 1.5.4 — 2026-07-25
### Fixed
- **Better Levels was breaking token-to-token vision between levels — even with Build Mode off.** Build
  Mode ran on every scene load and, when OFF, force-set `visible`/`renderable`/`mesh.visible = true` on
  *every* tile and refreshed it, overriding core's own per-level tile culling. In v14 the level surfaces
  feed the token line-of-sight test, so stomping tile visibility at load corrupted the cross-level vision
  computation and made tokens on other levels read as not-visible (and un-targetable). Because the damage
  happened at load regardless of the toggle, turning Build Mode off didn't fix it — only unloading the
  module did. Build Mode is now a true no-op when off: it touches ONLY the tiles it actually hid, and
  leaves everything else for core to manage.

## 1.5.3 — 2026-07-25
### Fixed
- **Stopped the "corrupt region shapes — click Repair" banners from stacking up on the canvas.** The
  alert was flagged permanent (so it never dismissed) and re-fired every time the scene was viewed,
  piling up. It's gone. When a scene has broken regions, the helper panel still shows its **Repair**
  button with a count badge — a quieter place for it that doesn't cover your map.

## 1.5.2 — 2026-07-25
### Fixed
- **Changing a token's level via the HUD didn't move its elevation** — most visibly going *down* onto a
  band boundary. A hook trace showed why: a HUD level change is a *move*, and core doesn't put `level`
  in the incoming `preUpdateToken` changes — it derives the destination level during processing and only
  writes it into the committed update. Our handler recorded its target in `preUpdateToken` gated on
  `"level" in changes`, which is never true there, so it never actually ran. What looked like "works
  going up" was core animating the elevation on its own. The elevation is now set in `updateToken`, the
  hook where `level` genuinely appears, so it fires reliably in both directions and lands the token on
  the new level's floor. (The follow-up write is elevation-only, so it can't loop.)

## 1.5.1 — 2026-07-18
### Fixed
- **"Sync to Levels Elevation" was missing from the level dropdown on most scenes.** The menu was
  identified by looking for the literal text `Level (`, so it was only recognised on scenes whose levels
  happen to be named exactly that way. A scene naming its levels **`Level 01 (0 | 10)`**, `Ground Floor`
  or `Basement` was never matched and never got the entry. The menu is now identified by matching its
  items against the scene's **actual level names**, so it works whatever you call your levels.

## 1.5.0 — 2026-07-11
### Removed
- **Restack Tiles has been removed** — the helper-panel button, the preview window, and the
  bring-to-front / send-to-back buttons on the Tiles toolbar. Drag-to-reorder in the Placeables tab does
  the same job in the place you are already working, so this was a second way to do one thing.
- Unaffected: **drag-to-reorder** in the Placeables tab (Shift = range, Ctrl/Cmd = toggle), the
  depth-ordered tile list, and **"Mark selected tiles as Floor"** on the Tiles toolbar.

## 1.4.1 — 2026-07-11
### Changed
- **"Sync to Levels Elevation" is now ON by default.** An unfiltered placeables list on a real scene runs
  to hundreds of rows, so the filtered view is the useful default. Your choice is remembered from the
  moment you toggle it — including turning it off, which sticks.

## 1.4.0 — 2026-07-11
### Fixed
- **A level's FLOOR tiles were appearing in the list of the level below it** — which also silently broke
  group drag-to-reorder, because selecting them produced a group spanning two elevations, which cannot
  be restacked.

  Neither available signal can say which level owns a tile. `levels` tags describe **visibility**, not
  ownership — in the tavern scene **54 of 86 tiles are tagged to all four levels**, so tags would put a
  tile on every floor. And `elevation` is ambiguous at a boundary: elevation 10 is *both* the ceiling of
  Level (0|10) and the floor of Level (10|20), so a 2nd-floor floor tile genuinely sits inside the 1st
  floor's band. No test over those two fields can separate them.

  Better Levels now records ownership **explicitly**: a tile configured with a role (floor/roof/basement/
  balcony) is stamped with the level it belongs to, and the Placeables filter and the restack both treat
  that as authoritative. Tiles Better Levels has not configured behave exactly as before.

  **Self-healing:** tiles configured before this release still point at their Define Surface region, and
  that region is tagged to exactly one level — so ownership is recovered from it automatically. No
  migration, and nothing to re-configure.

## 1.3.3 — 2026-07-11
### Fixed
- **Drag worked exactly once, then stopped.** The listeners live on the tab's element, and core replaces
  that markup whenever the tab re-renders — which it does immediately after a drop, since the drop
  updates tiles. The install guard was a symbol on the *application*, so once the element and its
  listeners were replaced, the guard prevented ever re-binding: first drag fine, every drag after it
  dead until a reload. Binding is now tracked on the **element**, so a fresh element is always freshly
  bound.
- **Dragging a group did nothing.** `control()` is a no-op while the Tiles layer is not the active canvas
  layer, so selecting rows in the sidebar could *look* selected while `canvas.tiles.controlled` stayed
  empty — and the drag quietly degraded to dragging just the row under the cursor. The Tiles layer is now
  activated before any selection change.
- **A refused drop now says why.** Releasing on an illegal target used to do nothing at all, which was
  indistinguishable from the drag being broken. It now warns — and specifically calls out a selection
  that spans several elevations, which cannot be restacked together because `sort` is only compared
  within one elevation.

## 1.3.2 — 2026-07-11
### Fixed
- **Placeables-tab features are now installed independently.** They previously ran as four bare calls in
  a row at init, so a throw in any one of them silently killed every feature registered after it — and
  drag-to-reorder, being last, was always the first casualty. A failure is now caught, logged loudly by
  name, and cannot take the others down with it.

## 1.3.1 — 2026-07-11
### Fixed
- **The Better Levels panel would not open on 1.3.0.** The new "Region is both a Surface and a Stair"
  audit rule called `hasBehavior()`, which lives in `fix-entity.mjs` and was never defined in
  `audit.mjs` — so `auditScene()` threw the moment the panel asked it for an issue count, taking the
  whole panel down. It now uses audit.mjs's own `isSurfaceRegion`/`isStairRegion`.

## 1.3.0 — 2026-07-11
### Fixed
- **Stair elevation bands reached into levels the stair does not connect — and the audit was ENFORCING
  it.** A stair's band ran from the lower level's floor to the upper level's *ceiling*. A level's ceiling
  is the next level up's floor, so the band swallowed a level too many: in the tavern scene a token
  standing at elevation 20 (on the 2nd floor) was inside **all four ground-floor stairs at once**. Worse,
  the `stair-elevation` audit rule expected that same wrong band, so every "Fix All" wrote the bug back.
  Bands now run **floor-to-floor** — from the lowest connected level's floor to the **highest connected
  level's floor** — which still contains the elevation a token stands at on *both* levels, but reaches no
  further. Across the tavern's 7 stairs this drops the number containing elevation 20 from **7 to 3**
  (the 3 that legitimately connect it). It also removes the infinite-top case on the roof stair.
- **A tile could steal another tile's surface region.** Two overlapping floor plates both matched the same
  Define Surface region, so the second silently adopted the first's footprint and ended up with a surface
  that wasn't its own shape. A region already claimed by another tile is now skipped.

### Added
- **Audit rule (red): "Region is both a Surface and a Stair."** A region can be a floor you stand on, or a
  stair that moves you — never both, or standing on it teleports you. Nothing detected the ones that
  already existed. The fix strips the Change Level behavior and leaves it a Surface.
- **Audit rule (red): "Floor tile has no Define Surface region."** Every other surface rule only validated
  regions that already existed, so a floor that never got one was invisible to the audit — which is exactly
  how the tavern's floors went un-surfaced and left tokens with nothing to stand on. Also catches a
  dangling link (region deleted) and a shared link (two tiles, one region).
- **"Mark selected tiles as Floor"** on the Tiles toolbar — applies the floor preset and gives each tile
  its own Define Surface region. Better Levels cannot reliably *guess* that a tile is a floor, so this is
  the honest interface: you select, it applies.

## 1.2.0 — 2026-07-11
### Removed
- **Stair trigger gating has been removed entirely.** Better Levels no longer intercepts the core
  Change Level behavior, so **stairs now behave exactly as Foundry intends** — a token changes level on
  entering the region, with no interference from this module. The "Stairs trigger when" and "Ignore
  stairs on the far side of a wall" world settings are gone, along with the per-region
  `stairTrigger` flag override. The approach proved unreliable in play and was not worth the risk to
  token movement.
- Unaffected: **Create Stairs** mode (new regions become Change Level stairs), the stair audit rules,
  and everything else stair-related. Only the movement gating is gone.

## 1.1.5 — 2026-07-11
### Fixed
- **The drop did nothing.** `endDrag()` cleared the drag state *before* calling the commit, and the
  commit read the dragged tile ids from that state — so it always saw an empty list and returned
  without writing anything. The drag UI worked perfectly and then threw the payload away. The ids are
  now passed through explicitly.

## 1.1.4 — 2026-07-11
### Fixed
- **Drag-to-reorder: the tile thumbnails were eating the drag.** An `<img>` is draggable by default, so
  pressing on a row's thumbnail started a *native* image drag — and a native drag swallows every pointer
  event until it ends. That is why nothing happened during the press, the "N tile(s)" badge only appeared
  after the mouse was released, and the badges then piled up on screen (the pointerup that cleans them
  up never arrived). The thumbnails are no longer draggable, and native drag is suppressed outright
  inside the placeables list.
- The drag now takes **pointer capture**, so move/up are delivered even if the row is re-rendered
  mid-drag, and it cleans up on `pointercancel` — no more orphaned badges.

## 1.1.3 — 2026-07-11
### Fixed
- **Drag-to-reorder now actually drags.** Marking the rows draggable was not enough: core calls
  `preventDefault()` on the row's pointerdown for its own click handling, and a cancelled default there
  stops the browser ever raising `dragstart`. The handlers were installed and simply never invoked —
  no error, nothing to see. The drag no longer uses HTML5 drag-and-drop at all; it is driven from
  pointer events in the capture phase, which core cannot cancel out from under us.
- A press only becomes a drag after the pointer moves ~5px, so a plain click still selects as before.
  A floating "N tile(s)" badge follows the cursor, the orange line shows where the drop lands, and
  **Escape cancels** the drag mid-flight.

## 1.1.2 — 2026-07-11
### Fixed
- **Drag-to-reorder did nothing at all.** The tile rows never carried `draggable="true"`, and a browser
  fires *no* drag events whatsoever on an element without it — so the listeners were live but were never
  called. Rows are now marked draggable, and re-marked after every re-render (core rebuilds them on
  search/filter). The drag also guarantees a non-empty `dataTransfer`, without which the browser
  cancels the drag the instant it starts.
- Added `game.modules.get("baileywiki-better-levels").api.drag.debug()` — reports rows found, how many
  are draggable, and whether the handlers installed.

## 1.1.1 — 2026-07-11
### Added
- **Drag tile rows in the Placeables tab to restack them.** An orange line shows exactly where the
  drop will land (above or below the row you are hovering). Dragging an unselected row drags just that
  row; dragging a selected one drags the whole selection, preserving its internal order. Dragging a row
  out onto the canvas still works as before.
- Dropping **reindexes that elevation band** with even spacing rather than squeezing a value into a
  gap — deterministic, collision-free, and it repairs interleaved legacy sort values as a side effect.
  It reindexes over every tile at that elevation, **including ones hidden by a filter**, so reordering
  a filtered list can never scramble what you cannot see.

### Fixed
- **Selection modifiers in the Placeables tab were backwards.** Shift+click behaved like a toggle and
  Ctrl+click did nothing. Now: **Shift+click selects the whole range** between the anchor row and the
  clicked row (in displayed order), and **Ctrl/Cmd+click toggles** a single row in or out of the
  selection. Plain click selects one row and sets the anchor. Selection is the canvas selection, so the
  sidebar and canvas can never disagree.

### Notes
- Tiles can only be restacked **within their own elevation** — `sort` is only ever compared between
  tiles at the same elevation, so honouring a cross-elevation drag would mean rewriting the tile's
  elevation, which in a Levels scene silently moves it to another floor. Such a drop is refused and the
  row is marked in red.

## 1.1.0 — 2026-07-11
### Added
- **Tiles in the Placeables tab are now listed by DEPTH, not alphabetically.** Top of the list = drawn
  in front. The comparator is v14's real depth rule (elevation, then sort), so the list and the canvas
  finally agree, and you can see at a glance that a wall tile is sitting *under* a floor tile. Can be
  turned off in Settings.
- **Restack Tiles** — select tiles on the canvas and move them above (or below) everything else.
  Solves the common legacy-scene problem where wall/door tiles are stacked *beneath* the room floor
  tiles that cover them. Tiles you did not select keep their exact stacking; only the selection moves,
  and its own relative order is preserved. Measure against the **active level** or the **whole scene**.
  The window previews every sort change (from -> to) before you commit, and offers a scene backup first.
  Quick **bring to front / send to back** buttons are also on the Tiles toolbar.

## 1.0.12 — 2026-07-11
### Fixed
- **Sync to Levels Elevation now drives core's own elevation filter** — the min/max pair in the
  Placeables tab's **Advanced Filter** panel. That is the native mechanism for precisely this job, and
  it is what makes the feature actually work; the previous attempts reimplemented filtering on top of
  core's undocumented internals instead of just filling in the fields core already has. Turning Sync on
  fills Elevation min/max from the active level's band and refills them whenever you change level.
  A level with an infinite roof sets an OPEN upper bound rather than a literal Infinity, so the top
  level is not filtered down to nothing. Level assignment is still filtered alongside it.

## 1.0.11 — 2026-07-11
### Fixed
- **Sync to Levels Elevation still was not filtering.** The wraps were installed on
  `PlaceableTab.prototype`, but the concrete subclasses (`TileTab`, `WallTab`, ...) define their own
  `isEntryVisible` / `_matchesFilter` / `_onFilterByLevel`, which **shadow** the parent — so none of
  our code ran. Every wrap is now applied to the tab **instance**, where an own-property always wins
  over the prototype chain.
- Added a **DOM enforcement pass** as the guarantee: each row is resolved to its document via core's
  own `_getPlaceableFromElement()` and hidden directly if it fails the rule. Sync no longer depends on
  core's undocumented filter internals being called in the order we expect. It only ever touches rows
  it hid itself, so core's own hiding and the search box are untouched.
- `api.syncLevels.debug()` now prints a readable table (elevation / levels / assigned / in-band /
  should-show / actually-hidden) plus a count of rows that should be hidden but are not.

## 1.0.10 — 2026-07-11
### Fixed
- **Sync to Levels Elevation was not actually filtering anything.** The rule was hung solely on
  `_matchesFilter`, but core only calls that hook when `_hasAdvancedFilters()` reports an active
  advanced filter — and Sync is not one of core's filters, so the hook never fired and every entry
  passed. A ground-floor tile (elevation 0) stayed listed with Level 20–30 selected. The rule now also
  drives `isEntryVisible()` — the authoritative "is this row shown" gate — and forces the advanced
  filter path on while Sync is active.
- Added `game.modules.get("baileywiki-better-levels").api.syncLevels.debug()`, which reports the
  active level, the installed wraps, and a per-tile verdict (assigned / in-band / shown).

## 1.0.9 — 2026-07-11
### Changed
- **Sync to Levels Elevation now tests level ASSIGNMENT as well as elevation.** An entry must be both
  tagged to the active level *and* sitting inside its elevation band. Elevation alone was not a
  sufficient proxy for relevance — and for **walls, which carry no elevation at all**, it was no proxy
  whatsoever, so a wall tagged to the 2nd floor could show while you worked on the ground floor.
  Untagged placeables (empty `levels`) still count as "visible on every level" and are shown when
  their elevation is in band, so nothing legitimate silently vanishes on a partially-tagged scene.

## 1.0.8 — 2026-07-11
### Added
- **"Sync to Levels Elevation"** — a new option in the Placeables tab's level dropdown. Instead of
  pinning the list to one hand-picked level, it **follows the level you are working on in the Levels
  nav**, narrowing a several-hundred-row placeables list down to the floor you are actually on. An
  entry shows when it is both visible to the active level *and* its elevation sits inside that level's
  band. Turning Sync on clears any explicitly-picked level; picking a level (or Clear) turns Sync off.

## 1.0.7 — 2026-07-11
### Fixed
- **Placeables-tab tile thumbnails now actually appear.** The first cut located rows by matching a bare
  tile id in a `data-*` attribute; core tags rows with a **UUID** (`Scene.x.Tile.y`), so nothing matched
  and no thumbnails were drawn. Row lookup now resolves bare ids, UUIDs and embedded ids, attaches via
  render hooks as well as the palette class, and re-decorates rows the **Filter** box rebuilds as you type.
- Added `game.modules.get("baileywiki-better-levels").api.thumbs.debug()` to report what the thumbnail
  code can see, for troubleshooting.

## 1.0.6 — 2026-07-11
### Added
- **Tile thumbnails in the Placeables tab.** Each tile row in the v14 Placeables sidebar now shows a small
  preview of its own art, and **hovering a row pops a large preview** (with the tile's name, on a
  checkerboard so transparency reads clearly) — so you can hunt for a tile by sight instead of by name.
  Animated `.webm` / `.mp4` tiles show a poster frame that loops on hover. Thumbnails are lazy-loaded for
  scenes with hundreds of tiles, and the whole feature can be turned off in Settings.

## 1.0.5 — 2026-07-11
### Fixed
- **Audit & Fix no longer throws "top: must be a finite number" on scenes with a roof level.** Foundry
  *stores* an infinite level/region top as `null`, but the live document reports it as `Infinity` — and
  `top ?? 0` does not catch `Infinity`, so we wrote it straight back and Foundry rejected the update. Every
  write of an elevation top now goes through one helper that converts a non-finite value to `null`
  (= infinite). This fixes the Fix All crash and the same latent bug in stair creation, surface regions,
  and tile auto-config.
- **The Level Manager no longer silently destroys an infinite roof.** An infinite top used to load as
  `Infinity`, render as a blank number field, and get written back as `0`. Blank now *means* infinite
  (with an "∞" placeholder), round-trips correctly, and passes validation.
- **The Audit window now refreshes itself after a migration.** Running the v13 → v14 migration from the
  Audit left the window showing the stale "this scene needs migrating" result, so it looked like nothing had
  happened. The migration now waits for its document updates to settle and then re-runs any open Audit
  window against the converted scene, so you immediately see the real, v14-ready audit.

## 1.0.4 — 2026-07-11
### Changed
- **Stair triggering, redone.** The 1.0.3 "token's centre" mode turned out to be a no-op — Foundry's own
  containment is already effectively centre-based, so testing the centre changed nothing (and could never
  fix the wrong-side-of-a-wall case, since a token across a wall is still inside the region polygon). It has
  been **removed**. The two mechanisms that actually work are now separated:
  - **"Stairs trigger when"** → *On entering* (Foundry default) or ***Only when the token stops on the
    stair*** (new default), which waits for the move to genuinely finish before deciding.
  - **"Ignore stairs on the far side of a wall"** (new, on by default) → a stair region usually bleeds
    through a wall; this only fires the stair when no movement-blocking wall lies between the token and the
    staircase itself. This is the real fix for tokens going up from the wrong side of a wall.
### Fixed
- **Migrated scenes no longer keep asking to be migrated.** The legacy detector flagged *any* non-empty
  `flags.levels`, but a successful migration leaves harmless crumbs behind — `backgroundElevation` on the
  Scene and `tokenHeight` on Tokens — so an already-converted v14 scene flagged itself forever (and kept
  flagging itself after you migrated it). Detection now keys off the data that actually proves a scene is
  still v13: `flags.levels.sceneLevels` on the Scene, and `flags.levels.rangeBottom` / `rangeTop` on
  placeables. Verified against a real migrated scene (clean) and a real v13 scene (still caught).
- **"Only when the token stops" never fired.** It tested `movement.pending` for remaining waypoints, but
  `tokenMoveIn` fires *during* the move — so waypoints are always pending and the condition never passed.
  It now hangs a continuation off `movement.finished` (non-blocking, to avoid deadlocking the movement
  pipeline) and re-tests the token where it actually comes to rest.

## 1.0.3 — 2026-07-11
### Added
- **Stairs no longer trigger prematurely.** Foundry's Change Level behaviour fires the instant *any* part
  of a token's movement crosses into the stair region — which sends tokens up early, sometimes from the
  wrong side of a wall. A new **"Stairs trigger when"** setting controls this: *On entering* (Foundry
  default), ***When the token's centre ends up on the stair*** (new default), or *Only when the token stops
  on the stair*. A single stair can override the world setting via a
  `flags.baileywiki-better-levels.stairTrigger` flag. Works on **every existing stair** — no migration.
- **Legacy (v13) Levels scenes are migrated first.** Scenes built with the old Levels module store their
  elevation data in `flags.levels`. The Audit now detects this and surfaces **one** red issue — *"Migrate
  this scene to v14 Levels"* — suppressing every other check until you do, because auditing (or fixing)
  un-migrated data is meaningless. The fix runs Mass Edit's well-tested `migrateScene`, which converts the
  entities to v14 core standards *and* turns the legacy Levels settings into real v14 levels (expanding flat
  levels and generating surface regions), with a scene backup offered first.
### Changed
- The "strip legacy Levels flags" fix is now **suppressed on un-migrated scenes** — it would have destroyed
  the very data the migration reads.

## 1.0.2 — 2026-06-27
### Added
- **Sample scenes.** A new **Sample scenes** button on the helper panel opens a picker of bundled,
  ready-to-explore Levels scenes. The first is **"Sample Tudor Building with Basement"** — a four-storey
  Tudor tavern over a basement with fully wired Scene Levels (floor surfaces, stairs, lights, and walls).
  Importing creates a fresh, fully-editable copy and opens it — no compendium required.
### Fixed
- **No more black-background floors.** Generating levels (and **Add level** in the Level Manager) now gives
  every new floor the **first floor's background** instead of defaulting to black, and the ground floor's
  background is preserved when you regenerate.
- **Dropping a Mass Edit prefab no longer turns its regions into stairs** — even with Create Stairs mode on,
  a prefab's own regions are left exactly as authored.
- **A Surface region can never also be a stair.** Surfaces now strip any Change Level behaviour, and the
  stair auto-conversion is suppressed while a surface is being built (this also cleanly converts a region
  drawn as a stair into a pure surface via **Make Surface**).

## 1.0.1 — 2026-06-25
### Added
- **Explicit Close (X) button** on the helper-panel header, alongside Minimize. Closing fully dismisses the
  panel; reopen it from the single **Tiles**-toolbar button.
### Changed
- The helper panel now **auto-appears only on scenes with multiple levels**; on other scenes it stays hidden
  and is opened manually from the Tiles-toolbar button.
### Fixed
- **Build Mode is inert on scenes without multiple levels**, so it no longer hides tiles or disturbs the
  rendering of scenes that don't use Levels.

## 1.0.0 — 2026-06-25
### Added
- First release. Auto-generate level bands; one-click Floor / Roof / Basement / Balcony tile setup with
  pixel-perfect Surface regions (via Mass Edit); Build Mode; **Fix Entity** one-click configuration; a live
  **Audit & Fix** with risk-bucketed issues and plain-language explanations; the **Level Manager**; region
  tools (auto-stairs, Make Surface, smart naming); **Vehicles** (Link Token); and **Backup & Restore**.