Debug Toolbar

The debug toolbar is a visual overlay injected by the theme worker when debug mode is active. It shows real-time cache stats, per-section detail, and a live feed of purge events — all without leaving the page.

Activating debug mode

Add ?lk-debug=1 to any page URL:

https://your-site.layerkick.com/?lk-debug=1

This sets a cookie, so subsequent page loads stay in debug mode. Remove it with ?lk-debug=0 or clear the lk-debug cookie.

Debug mode enables:

• The visual debug toolbar (bottom pill + panels)
• Console logging via window.lk API
• The ?lk-fresh=1 cache bypass (only works with debug cookie set)

The pill

A fixed bar at the bottom center of the page. Always visible in debug mode.

Element	Description
Status dot	Green (≥80% hit rate), yellow (≥50%), red (<50%)
LK brand	Confirms the debug bar is active
Cached ratio	e.g. “12/14 cached” — sections served from cache vs total
Hit rate	Percentage of sections served from cache
Render time	Total server-side render time for uncached sections

Hover the pill to reveal the action bar.

Action bar

Appears on hover above the pill. Five buttons:

Button	Action
Sections	Opens the sections panel
Events	Opens the events panel (badge shows unseen event count)
Page	Purges the current page’s cached sections. Click once to arm (3s countdown), click again to confirm
Site	Purges all cached sections site-wide. Click once to arm (5s countdown), click again to confirm
Fresh	Reloads the page with ?lk-fresh=1 to bypass section cache entirely

Sections panel

Slides in from the right. Shows every section rendered on the page:

• Cache dot — green (HIT) or red (MISS)
• Section type — e.g. hero, header, product-information
• HIT / MISS badge — whether the section was served from cache
• Render time — milliseconds spent in executeComponent() (0ms for cache hits)
• Size — HTML output size in bytes

Section highlighting

Click any section row to:

1. Scroll the page to the matching [data-lk-section] element
2. Show a colored overlay border (green = cached, red = miss) with a label badge
3. Click the same row again or a different row to clear

Per-section purge

Each section row has a purge button (circular arrow icon). Clicking it:

1. Sends a POST /api/cache/purge with the section path
2. Shows a spin animation while purging
3. Displays a toast on completion

Events panel

Slides in from the right. Shows a live feed of cache purge events.

The panel polls GET /__dev/purge-events?since=<timestamp> every 5 seconds. New events trigger a yellow toast notification and increment the badge counter on the Events button.

Each event shows:

• Type badge — path, key, d1, or full
• Paths affected — which URLs or keys were purged
• Sections / keys evicted — counts of cache entries removed
• Timestamp — when the purge occurred
• Duration — how long the purge took

Per-isolate limitation

The event buffer is in-memory per Worker isolate. If a purge webhook hits a different isolate than the one serving your debug bar poll, those events won’t appear. This is expected for local dev — the feed isn’t guaranteed to be complete.

Console API

The debug toolbar extends the existing window.lk API with a .bar namespace:

window.lk.bar.toggle("sections")   // toggle sections panel
window.lk.bar.toggle("events")     // toggle events panel
window.lk.bar.highlight(0)         // highlight first section
window.lk.bar.highlight(3)         // highlight fourth section
window.lk.bar.clear()              // clear section highlight
window.lk.bar.toast("Hello!", "green")  // show a toast (green/yellow/blue)

The existing window.lk console API (cache stats, section list, etc.) continues to work alongside the toolbar.

Purge endpoint

The toolbar’s purge buttons call the existing POST /api/cache/purge endpoint. For local dev, CACHE_PURGE_TOKEN must be set in wrangler.toml:

[env.dev.vars]
CACHE_PURGE_TOKEN = "dev-debug-token"

This is already configured. The toolbar reads the token from the server-injected data — no manual auth needed.

Purge events endpoint

GET /__dev/purge-events?since=<timestamp>&limit=<n>

Returns recent purge events as JSON. Gated by the debug cookie.

Param	Default	Description
since	—	Only return events after this Unix timestamp (ms)
limit	50	Maximum events to return

Response is an array of PurgeEvent objects, newest first.

Key files

File	Role
cf-client-site/src/lib/debug-bar.ts	Builder — assembles CSS + DOM + JS
cf-client-site/src/lib/debug-bar-css.ts	Scoped CSS (all under #lk-debug)
cf-client-site/src/lib/debug-bar-js.ts	Client-side JS — pill, panels, events, highlighting
cf-client-site/src/lib/purge-events.ts	In-memory ring buffer for purge events
cf-client-site/src/render/page-renderer.ts	Collects SectionDebugInfo per section
cf-client-site/src/worker.ts	Injects debug bar HTML + serves event endpoint