@humanforest/slidev-theme 0.1.0 → 0.1.2

package/debug/layoutDebug.js

@@ -0,0 +1,70 @@
+// task-14-brief.md, requirement 6 — the shared toggle behind the layout-debug (red-line) overlay.
+// Split out from global-top.vue itself so setup/shortcuts.ts can flip it without importing a .vue
+// file into a plain Slidev setup module — the same reasoning backgrounds.js/iconSlugs.js are split
+// from the components that read them.
+//
+// OFF BY DEFAULT, ALWAYS — this is the one property every other guarantee in this module and in
+// global-top.vue is built on top of:
+//   - `ref(false)`, never read from anywhere at import time — no localStorage/sessionStorage
+//     restore, no query-string read, nothing that could start this ref at `true` on a page this
+//     module has never seen interacted with. A fresh page load — which is EXACTLY what `slidev
+//     export`'s Playwright run does; it never presses a key or replays a prior session — starts
+//     here, at `false`, unconditionally.
+//   - No persistence at all. Nothing in this module writes to storage, so there is nothing for a
+//     later, unrelated page load (an export tab reusing a browser profile a presenter had toggled
+//     debug on in, during a live review) to inherit. The cost is that the toggle does not survive
+//     a manual reload — accepted deliberately, because the alternative is a mechanism that could
+//     leak state into an export, which is the one outcome requirement 6 names as worse than not
+//     having this tool at all.
+//
+// This module does NOT decide whether the overlay is currently SAFE to show — it has no way to
+// know it's running inside an export. global-top.vue is what gates the actual render on
+// `useNav().isPrintMode` as well as this ref, so even a hypothetical future bug that flipped
+// `layoutDebugEnabled` true during an export still could not paint anything — see that file's own
+// comment for the two-guard shape and why neither guard alone is treated as sufficient.
+import { reactive, ref } from 'vue';
+
+/** @type {import('vue').Ref<boolean>} */
+export const layoutDebugEnabled = ref(false);
+
+/** Flips the overlay. The one write site this ref has — used by setup/shortcuts.ts's 'l' binding.
+ * Never called from a layout, a component, or a slide. */
+export function toggleLayoutDebug() {
+  layoutDebugEnabled.value = !layoutDebugEnabled.value;
+}
+
+/*
+  THE FIVE TIERS, individually switchable — one on/off for the whole overlay was not enough once it
+  started drawing element boxes and gaps as well as rules. A dense slide carries 40-120 element
+  hairlines, which is exactly the texture you want when checking whether a paragraph sits where you
+  think and exactly the noise you do not want when checking a split's columns.
+
+  SAME NO-PERSISTENCE DISCIPLINE as `layoutDebugEnabled`, and for the same reason: a plain object
+  with literal defaults, never read from storage or a query string, so an export starts here every
+  time. All five start ON: boxing the content is half of what makes this a schematic rather than a
+  set of rules, so it is there the first time you open it. `element` is the one to switch off when a
+  dense slide gets busy, which is exactly why the switches exist.
+
+  Not a second nav button and not five more shortcuts: the key already names every tier, so the
+  key's own rows are the switches. See global-top.vue.
+*/
+export const layoutDebugTiers = reactive({
+  /*
+    ★ THE GRID WASH IS A TIER LIKE THE REST, and it was the one thing the overlay drew that nothing
+    could switch off. It is also the densest thing on screen — a 40px lattice under every other
+    line — so the moment a reader wants to check one measurement it is the first thing in the way.
+    Jose, doing exactly that: "can you remove the grid for a moment? too many lines i want to see if
+    everything is correct".
+  */
+  grid: true,
+  frame: true,
+  region: true,
+  gap: true,
+  element: true,
+  hazard: true,
+});
+
+/** Flips one tier. Called only from the overlay's own key. */
+export function toggleTier(id) {
+  if (id in layoutDebugTiers) layoutDebugTiers[id] = !layoutDebugTiers[id];
+}

package/debug/reviewToggles.js

@@ -0,0 +1,34 @@
+// Preview-only overrides for the running chrome, driven from the nav bar.
+//
+// WHAT THIS IS FOR. Reviewing a deck means asking "what does this look like without the
+// confidentiality chip / with the inset frames drawn", and the honest answers were previously "edit
+// the frontmatter and reload" and "remember that the key is `l`". Slidev renders a theme's own
+// `custom-nav-controls.vue` inside its toolbar (@slidev/client/internals/NavControls.vue imports
+// `#slidev/custom-nav-controls`), which is the right home for both: a reviewer's control, sitting
+// with the other reviewer's controls, rather than a frontmatter edit that has to be undone.
+//
+// ★★ AN OVERRIDE, NEVER A SETTING — and specifically never one that can reach an export.
+//
+// These refs only ever SUBTRACT from what the frontmatter already asked for. A slide with no
+// `confidential:` cannot be made to show one here, because that would let a reviewer see a deck the
+// deck does not describe. And every consumer must gate on `isPrintMode` the way global-top.vue
+// already does for the debug overlay: `slidev export` drives a real Playwright browser through the
+// same client, so a toggle left on at export time would otherwise silently ship a PDF missing its
+// own confidentiality marking. That is a worse failure than the inconvenience it saves.
+//
+// The debug overlay's own flag stays in ./layoutDebug.js — it already had a home, a keyboard
+// shortcut and a test, and moving it here to make one tidy module would be churn. This file
+// re-exports it so the nav control has a single import.
+import { ref } from 'vue';
+
+export { layoutDebugEnabled, toggleLayoutDebug } from './layoutDebug.js';
+
+/**
+ * Hide the confidentiality chip in PREVIEW only. False by default, so a fresh load always shows
+ * exactly what the frontmatter says.
+ */
+export const confidentialHidden = ref(false);
+
+export function toggleConfidential() {
+  confidentialHidden.value = !confidentialHidden.value;
+}

package/global-top.vue

@@ -58,9 +58,53 @@ import { useNav } from '@slidev/client';
 import { layoutDebugEnabled, layoutDebugTiers, toggleTier } from './debug/layoutDebug.js';
 import deckTokens from '@humanforest/tokens/deck/deck.json';
 
-const { isPrintMode, slides, currentPage } = useNav();
+const { isPrintMode, slides, currentPage, prevRoute, nextRoute } = useNav();
 const show = computed(() => layoutDebugEnabled.value && !isPrintMode.value);
 
+/*
+  ── NEIGHBOUR CHUNK WARM-UP ────────────────────────────────────────────────────────────────────
+  ★★ NOT PART OF THE OVERLAY. It lives here because Slidev gives a theme exactly one seam that is
+  mounted once for the whole deck rather than re-mounted per slide, and this is it — the same
+  reason the overlay itself is here. It needs `useNav()`, which is a composable and so cannot run
+  from `setup/main.ts` where this would otherwise belong.
+
+  WHAT IT FIXES. The deck's headmatter sets `preload: false` (scripts/deckSpecimen.ts's
+  HEAD_DEFAULTS) because Slidev otherwise mounts every route three seconds after load — measured
+  at 245 slides: 33,435 nodes and 1.7s of blocking time. But `preloadRoute()` in
+  @slidev/client's internals/SlidesShow.vue gates TWO separate things on that one key:
+
+    watchEffect(() => { preloadRoute(current); preloadRoute(prev); preloadRoute(next) })   // ← A
+    watchEffect(() => setTimeout(() => routes.forEach(preloadRoute), 3000))                // ← B
+
+  B is the stampede. A is not, and turning off B took A with it. So nothing was fetched ahead any
+  more, and a slide's own chunk was pulled on arrival instead.
+
+  ★★ THAT SHOWED AS A WHITE FLASH ON EVERY FORWARD STEP OF THE DEPLOYED DECK, and it did not
+  reproduce locally, which is why the comment in HEAD_DEFAULTS priced the trade at "about 30ms" —
+  a warm dev server. MEASURED on the gh-pages build instead, stepping onto a cold slide: the
+  wrapper lands in the DOM with NO `.slidev-layout` inside it for 278ms while `md-*.js`,
+  `LondonMap-*.js` and `LondonMap-*.css` are in flight. An empty slide paints Slidev's own
+  `bg-main` on `#slide-content` (internals/SlideContainer.vue), which is white. `SlideLoading`
+  never appears either — the async component's `delay` is 300ms and the gap is shorter.
+
+  ⚠ NO COMPOSITING FIX CAN REACH THIS, which is worth stating because styles/base.css already
+  carries one for a DIFFERENT white leak on the same seam. `useViewTransition` starts the
+  transition 50ms after `beforeResolve` and ends it on `router.afterEach`, and neither waits for
+  the slide's async component. The API is asked to cross-fade into a frame that is genuinely
+  white, and does so correctly.
+
+  WHY `load()` AND NOT `preloadRoute()`. The DOM cost that made B unaffordable comes from
+  `meta.__preloaded`, which is what puts a route into SlidesShow's `loadedRoutes` and mounts it.
+  `route.load()` only runs the slide's dynamic import, filling the `componentsCache` entry that
+  `#slidev/slides` keys its `defineAsyncComponent` loader off. So this buys back A's warm chunk
+  without buying back any of B's mounted DOM: still one page in the document, and a re-measured
+  navigation onto an already-loaded slide reports a single mutation with the layout ALREADY
+  present — zero frames of empty slide, zero requests.
+
+  ±1 only, matching what A itself did. A jump from the goto dialog still lands cold.
+*/
+watch([prevRoute, nextRoute], routes => routes.forEach(route => route?.load()), { immediate: true });
+
 /*
   task-14b-brief.md — the overlay now also has to show split.vue's Y-ANCHOR and its CONDITIONAL
   gutter, and unlike the three edge insets, both depend on the CURRENT SLIDE's own frontmatter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanforest/slidev-theme",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Forest brand theme for Slidev — the guardrail. Layouts + components wired to @humanforest/tokens, so any deck is on-brand by construction. Do not hand-pick colours/fonts here; everything aliases the engine tokens.",
   "keywords": [
     "slidev-theme",
@@ -31,10 +31,10 @@
     }
   },
   "dependencies": {
-    "@humanforest/fonts": "^0.1.0",
-    "@humanforest/frames": "^0.1.0",
-    "@humanforest/tokens": "^0.1.0",
-    "@humanforest/ui": "^0.1.0",
+    "@humanforest/fonts": "^0.1.2",
+    "@humanforest/frames": "^0.1.2",
+    "@humanforest/tokens": "^0.1.2",
+    "@humanforest/ui": "^0.1.2",
     "@iconify-json/lucide": "^1.2.0",
     "@iconify-json/vscode-icons": "^1.2.75",
     "@unovis/ts": "^1.6.7",
@@ -48,13 +48,18 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "unocss": ">=66"
+    "@slidev/client": ">=52",
+    "@slidev/types": ">=52",
+    "shiki": ">=1",
+    "unocss": ">=66",
+    "vue": "^3.5"
   },
   "files": [
     "layouts",
     "components",
     "styles",
     "setup",
+    "debug",
     "global-top.vue",
     "slide-top.vue",
     "slide-bottom.vue",