@tiledev/tile-debug

On-device debug overlay for Tile apps, plus a code push update modal. Two components, neither of which takes props.

Install

npm i @tiledev/tile-debug

Use

import { TileDebug, TileUpdateModal } from '@tiledev/tile-debug';

<YourApp />
<TileDebug />
<TileUpdateModal />

Two components, no props. Mounting one turns it on; not mounting it turns it off. They are independent — mount either, both, or neither.

| component | what it is | | --- | --- | | <TileDebug /> | two floating buttons — ⓘ for binary / OTA / Live Layer state, ⇅ for the OTA resolver network log | | <TileUpdateModal /> | the modal shown while a code push is downloading or ready to apply |

Neither imports anything from your app, and neither needs a provider or a context above it. The app id and env come from expo-constants (extra.tile), OTA state from the TilePush static API, and Live Layer state from the cache the provider persists to AsyncStorage. Mount them anywhere in the tree.

The code push modal

<TileUpdateModal /> reads useTilePushUpdate() — the SDK's own state, not a second check against the server — and shows:

• downloading — a bundle is coming, with percentage
• downloaded — it is on disk and applies on next launch; offers Restart now

Both stages are dismissible. Dismissing "downloading" does not swallow the "ready to restart" that follows it, and a modal that cannot be closed is one crash-loop away from an app that cannot be used.

Without it, OTA is invisible: TilePush.wrap downloads in the background and applies on the NEXT launch, so the app on screen is a launch behind and nothing admits it.

Why these fields

Each one has been the answer to a real bug: liveLayerEnv is baked at Gradle time so a build can silently point at the wrong environment (the wrong env is live and serves different content, so it looks like it works); the NIL bundle id means you are on the embedded bundle, not an OTA one; a fingerprint mismatch means the device is served nothing, silently; and a wrong Live Layer app id makes every lookup return undefined while the app renders hardcoded defaults.

Installing before it is on npm

dist/ is committed on purpose, so the package can be installed straight from this repo — which is what lets an app depend on it without a registry:

npm i git+ssh://[email protected]/clearsight-dev/tile-debug-overlay.git

A file: path to a local tarball works on one machine only; a cloud bundler build resolving that dependency will fail. Prefer the git url (or npm, once published).

Android note

The floating buttons carry elevation as well as zIndex. Android paints by elevation before sibling order, so zIndex alone leaves them under the navigator's screen content — mounted and invisible.

OTA and this overlay

An applied OTA bundle replaces the bundle baked into the binary. If the overlay is in your APK but not in the save a push was built from, it will disappear the moment that push lands. Whatever you push has to contain it too.