From 26687055163f102f6c61674872d0b4d2ff277fcc Mon Sep 17 00:00:00 2001
From: archipelago <archipelago@localhost>
Date: Thu, 30 Jul 2026 08:40:27 -0400
Subject: [PATCH] fix(02-02): restore page margins and slide transitions broken
 by KeepAlive restructure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Task 3 checkpoint failed on the real preview: outer page margins broke
and the up/down main-tab slide animations stopped playing. Root cause: the
02-02 restructure moved view-wrapper (absolute inset-0) onto each view's
root inside the padded wrapper, and split navigation across two sibling
Transitions behind a stable intermediate div — but dashboard-styles.css
scopes every transition as a compound selector on .view-wrapper, which must
be the keyed direct child of .perspective-container.

- Restore the pre-02-02 rendered DOM exactly: single Transition whose child
  is a keyed div.view-wrapper containing the per-route wrapper shape
- Re-integrate KeepAlive via statically-named per-route wrapper components
  (dashboardViewWrappers.ts) so the keyed div.view-wrapper is the cached
  component's own root; cache membership gated by :include on wrapper names
  derived from KEEP_ALIVE_PATHS
- Drop the scroll-retention Map: scroll containers now live inside keyed/
  cached wrappers, restoring the old reset-to-top behavior for non-kept routes
- Pin the visual contract structurally in keepAliveTabs.test.ts (padded
  wrapper classes must render INSIDE div.view-wrapper)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../views/dashboard/DashboardRouterView.vue   | 160 ++++++------------
 .../dashboard/__tests__/keepAliveTabs.test.ts |  50 ++++++
 .../views/dashboard/dashboardViewWrappers.ts  | Bin 0 -> 5332 bytes
 3 files changed, 101 insertions(+), 109 deletions(-)
 create mode 100644 neode-ui/src/views/dashboard/dashboardViewWrappers.ts

diff --git a/neode-ui/src/views/dashboard/DashboardRouterView.vue b/neode-ui/src/views/dashboard/DashboardRouterView.vue
index b8135c53..c0356a83 100644
--- a/neode-ui/src/views/dashboard/DashboardRouterView.vue
+++ b/neode-ui/src/views/dashboard/DashboardRouterView.vue
@@ -1,126 +1,68 @@
 <template>
   <RouterView v-slot="{ Component, route }">
-    <div
-      ref="wrapperRef"
-      class="mobile-safe-top"
-      :class="wrapperClass(route)"
-      :style="wrapperStyle"
-    >
-      <!-- KeepAlive itself is never conditionally removed — only its child
-           is, via v-if on the <component> below. Toggling KeepAlive itself
-           with v-if would destroy its whole instance cache on every
-           navigation away from a kept-alive route, which defeats the point. -->
-      <Transition :name="getTransitionName(route)">
-        <KeepAlive :max="KEEP_ALIVE_MAX">
-          <component
-            v-if="shouldKeepAlive(route)"
-            :is="Component"
-            :key="route.path"
-            :class="componentClass(route)"
-          />
-        </KeepAlive>
-      </Transition>
-      <Transition :name="getTransitionName(route)">
+    <Transition :name="getTransitionName(route)">
+      <KeepAlive :max="KEEP_ALIVE_MAX" :include="keepAliveIncludes">
         <component
-          v-if="!shouldKeepAlive(route)"
-          :is="Component"
+          :is="wrapperFor(route.path)"
           :key="route.path"
-          :class="componentClass(route)"
-        />
-      </Transition>
-      <div v-if="!isFullBleedRoute(route)" class="shrink-0 h-6 md:h-12" aria-hidden="true"></div>
-    </div>
+          :mobile-tab-padding-top="mobileTabPaddingTop"
+          :needs-mobile-back-button-space="needsMobileBackButtonSpace"
+        >
+          <component
+            :is="Component"
+            :class="isFullBleedPath(route.path) ? undefined : 'view-container flex-none'"
+          />
+        </component>
+      </KeepAlive>
+    </Transition>
   </RouterView>
 </template>
 
 <script setup lang="ts">
-// The KeepAlive host extracted from Dashboard.vue's nested RouterView (D-01).
+// The KeepAlive host extracted from Dashboard.vue's nested RouterView (D-01),
+// restructured after the Task 3 checkpoint failure (broken margins + missing
+// slide transitions) to restore the pre-02-02 rendered DOM exactly.
 //
-// Structural invariants (see 02-02-PLAN.md Task 1 for the full rationale —
-// the tests in __tests__/keepAliveTabs.test.ts pin these):
-// 1. Nothing between the RouterView slot and <KeepAlive> carries a binding
-//    that changes identity per route — the outer wrapper div below is
-//    stable (no :key); only its *classes* are route-derived. A keyed
-//    ancestor would tear down KeepAlive's entire instance cache on every
-//    navigation.
-// 2. Composition order is <Transition> outside <KeepAlive> outside
-//    <component :is="Component">.
-// 3. :key="route.path" lives on <component :is> itself, never on an
-//    ancestor of <KeepAlive> — putting it on a wrapping div would make
-//    KeepAlive cache that div (keyed, torn down every navigation) instead
-//    of the view.
-// 4. Both pre-existing wrapper shapes (full-bleed chat/mesh vs. the default
-//    padded/scrollable shape) survive byte-for-byte via wrapperClass() /
-//    wrapperStyle() / componentClass() below.
-import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
-import { RouterView, useRoute, type RouteLocationNormalizedLoaded } from 'vue-router'
+// Structural invariants — the tests in __tests__/keepAliveTabs.test.ts pin
+// these, and dashboard-styles.css is the contract they serve:
+//
+// 1. The <Transition> child is a keyed `div.view-wrapper` that sits directly
+//    in the RouterView slot (so it is the direct child of
+//    `.perspective-container` in Dashboard.vue). Every transition in
+//    dashboard-styles.css is a compound selector
+//    (`.slide-up-enter-active.view-wrapper`, `.depth-forward-enter-from.view-wrapper`,
+//    …), so the transition classes and `view-wrapper` MUST share one element,
+//    with no intermediate wrapper flattening the 3D perspective or clipping
+//    slide movement.
+// 2. The per-route wrapper shapes (full-bleed chat/mesh vs. the default
+//    padded/scrollable shape) live INSIDE `div.view-wrapper` — `view-wrapper`
+//    is `absolute inset-0` and must never be applied to the view's own root
+//    inside the padded wrapper (that pins the view over the page padding:
+//    the broken-margins regression).
+// 3. KeepAlive caching is reconciled with (1) and (2) by making the keyed
+//    `div.view-wrapper` the root of a statically-defined per-route wrapper
+//    component (dashboardViewWrappers.ts). KeepAlive sits between
+//    <Transition> and the keyed wrapper vnode — the canonical composition —
+//    and `:include` (matching the wrappers' static names, derived from
+//    KEEP_ALIVE_PATHS) decides which wrappers are instance-cached. Caching
+//    the wrapper caches its whole subtree, including the routed view.
+// 4. KeepAlive itself is never keyed, toggled with v-if, or nested under a
+//    per-route element — any of those tears down its instance cache.
+//
+// Scroll behavior: each route's scroll container lives inside its keyed
+// wrapper, so non-kept routes reset to top on entry (the pre-02-02 behavior)
+// and the kept-alive tab's scroll container is part of its cached subtree —
+// no manual scroll-retention bookkeeping needed.
+import { RouterView } from 'vue-router'
 import { useRouteTransitions } from './useRouteTransitions'
-import { KEEP_ALIVE_MAX, shouldKeepAlive } from './keepAliveRoutes'
+import { KEEP_ALIVE_MAX } from './keepAliveRoutes'
+import { isFullBleedPath, keepAliveIncludeNames, wrapperFor } from './dashboardViewWrappers'
 
-const props = defineProps<{
+defineProps<{
   mobileTabPaddingTop: number | null
   needsMobileBackButtonSpace: boolean
 }>()
 
-const route = useRoute()
 const { getTransitionName } = useRouteTransitions()
-const wrapperRef = ref<HTMLElement | null>(null)
-
-type RouteLike = RouteLocationNormalizedLoaded | { path: string }
-
-function isFullBleedRoute(r: RouteLike): boolean {
-  return r.path === '/dashboard/chat' || r.path === '/dashboard/mesh'
-}
-
-/** Classes for the stable outer wrapper — was previously split across two
- * v-if/v-else divs; unified here into one so it never needs a per-route key
- * (invariant 1) while still producing the exact same visual result. */
-function wrapperClass(r: RouteLike) {
-  if (isFullBleedRoute(r)) {
-    return [
-      'h-full',
-      r.path === '/dashboard/mesh' ? 'dashboard-scroll-panel mobile-scroll-pad mesh-dashboard-panel' : '',
-      props.mobileTabPaddingTop ? 'overflow-y-auto' : '',
-    ]
-  }
-  return [
-    'absolute inset-0 px-4 pt-4 md:pt-8 md:px-8 overflow-y-auto dashboard-scroll-panel',
-    props.needsMobileBackButtonSpace ? 'mobile-scroll-pad-back' : 'mobile-scroll-pad',
-  ]
-}
-
-const wrapperStyle = computed(() =>
-  props.mobileTabPaddingTop ? { paddingTop: `${props.mobileTabPaddingTop + 16}px` } : undefined,
-)
-
-/** Classes merged onto the transitioning component's own root element via
- * Vue's attribute fallthrough. `view-wrapper` carries the transition/
- * positioning CSS (dashboard-styles.css) that used to live on the outer,
- * now-stable wrapper div; `view-container flex-none` matches the default
- * shape's previous per-component class. */
-function componentClass(r: RouteLike): string {
-  return isFullBleedRoute(r) ? 'view-wrapper' : 'view-wrapper view-container flex-none'
-}
-
-// ── Per-route scroll retention ─────────────────────────────────────────────
-// The default shape's wrapper is the scroll container and is now stable
-// across navigations (no key), so without this a kept-alive tab would
-// inherit whatever scroll offset the previous tab left behind — worse than
-// the old reset-to-top. Bounded by the route table (open item, accepted per
-// 02-02-PLAN.md assumptions).
-const scrollPositions = new Map<string, number>()
-
-watch(
-  () => route.path,
-  (newPath, oldPath) => {
-    if (wrapperRef.value && oldPath) scrollPositions.set(oldPath, wrapperRef.value.scrollTop)
-    nextTick(() => {
-      if (wrapperRef.value) wrapperRef.value.scrollTop = scrollPositions.get(newPath) ?? 0
-    })
-  },
-)
-
-onBeforeUnmount(() => {
-  if (wrapperRef.value) scrollPositions.set(route.path, wrapperRef.value.scrollTop)
-})
+const keepAliveIncludes = keepAliveIncludeNames()
 </script>
diff --git a/neode-ui/src/views/dashboard/__tests__/keepAliveTabs.test.ts b/neode-ui/src/views/dashboard/__tests__/keepAliveTabs.test.ts
index e10fc9a1..35c13707 100644
--- a/neode-ui/src/views/dashboard/__tests__/keepAliveTabs.test.ts
+++ b/neode-ui/src/views/dashboard/__tests__/keepAliveTabs.test.ts
@@ -101,6 +101,56 @@ describe('DashboardRouterView keep-alive behavior', () => {
     expect(shouldKeepAlive({ path: '/dashboard/marketplace' })).toBe(true)
     expect(shouldKeepAlive({ path: '/dashboard/marketplace/abc' })).toBe(false)
   })
+
+  // Visual contract (Task 3 checkpoint regression): the padded default-shape
+  // wrapper must render INSIDE `div.view-wrapper`, never the other way around.
+  // dashboard-styles.css scopes every transition as a compound selector
+  // (`.slide-up-enter-active.view-wrapper`, …) and `.view-wrapper` is
+  // `absolute inset-0` — if `view-wrapper` ever moves onto the view root
+  // inside the padded wrapper, page margins break and the slide/depth
+  // transitions stop firing. This test pins the structure so that regression
+  // cannot silently return.
+  it('renders the padded default wrapper inside div.view-wrapper', async () => {
+    const router = makeRouter()
+    router.push('/dashboard/other')
+    await router.isReady()
+
+    const wrapper = mount(DashboardRouterView, {
+      props: { mobileTabPaddingTop: null, needsMobileBackButtonSpace: false },
+      global: { plugins: [router] },
+    })
+    await flushPromises()
+
+    const viewWrapper = wrapper.find('.view-wrapper')
+    expect(viewWrapper.exists()).toBe(true)
+
+    // view-wrapper is the bare transition surface — no padding classes on it.
+    expect(viewWrapper.classes()).not.toContain('px-4')
+    expect(viewWrapper.classes()).not.toContain('view-container')
+
+    // Its first child is the padded scroll container carrying the page margins.
+    const padded = viewWrapper.element.firstElementChild as HTMLElement
+    expect(padded).not.toBeNull()
+    for (const cls of [
+      'absolute', 'inset-0', 'px-4', 'pt-4', 'md:pt-8', 'md:px-8',
+      'overflow-y-auto', 'mobile-safe-top', 'dashboard-scroll-panel', 'mobile-scroll-pad',
+    ]) {
+      expect(padded.classList.contains(cls), `padded wrapper missing ${cls}`).toBe(true)
+    }
+
+    // The routed view sits inside the padded wrapper with its per-component
+    // classes, followed by the scroll-clearance spacer.
+    const view = wrapper.find('.other-stub')
+    expect(view.exists()).toBe(true)
+    expect(view.classes()).toContain('view-container')
+    expect(view.classes()).toContain('flex-none')
+    expect(padded.contains(view.element)).toBe(true)
+    const spacer = padded.querySelector('[aria-hidden="true"]')
+    expect(spacer).not.toBeNull()
+    expect(spacer!.classList.contains('shrink-0')).toBe(true)
+
+    wrapper.unmount()
+  })
 })
 
 describe('RefreshIndicator', () => {
diff --git a/neode-ui/src/views/dashboard/dashboardViewWrappers.ts b/neode-ui/src/views/dashboard/dashboardViewWrappers.ts
new file mode 100644
index 0000000000000000000000000000000000000000..001be55eb00817fa4be42ff5ffbeb15c3deb85b1
GIT binary patch
literal 5332
zcmcIo?QYx35$$h1#q_oSDMys-+#oHOIDwqVh>`flu$1HmK@hFPmB}lLOK_LA)x^Mk
zh(1Ff>^@1)?D9jB<@Qf&1d&DV&d!{fIdj&70bR%<C{$@AT_^H}ZVHj-vY@$I<tmez
z(X>zny%sv2DN#h1ytMepOZ~&g!Qo?CB)8puXE4A&`t;^AP2QZ1>GbT~h(^DjjVELJ
z<M)4(iP^p`MGDKADa731nJ_df)KU_D;T031m-I6mn#Xd!%vF*Z5?Ms6QX9(TH5{82
zQY=Yai6jfFQ={6sK$~?cb$_lk>AA|KrqRdI<!5pM;@C_lCQ%s)O~S=k!n~HLoEug2
z_-NU`>eIBZ(<G8XnFqiC5W(T(TJ{;Epu%X{!?H-`CJq464Zx|^E(*2UUdi~-gyUUF
z_&^^^>1o>VXPyeJ;VuWuNKCg5BKw-oKa3}o@)DJ?L0&i>o{tFbui$3SZl7)+O@6Li
z&>@MLRw?rLjFL=C6VhSVK|7PRy(lRF1@KQ&9J4@#s0N+m8Nv@ZcK}`%Q_{+w|MP3w
zSb%+a%@xzwV|+Fu)s)~Ltl$uiBvU3%vMWTG<Uj-wS>S1<u5C;fx!sU#IfxW4Xd~A2
z{=;N^_IhM@=OT(^G|=-xrKy;ulHGF!&MwvE9VOS=7G_==!{_e+juK&CI15OWy2(&N
z$}nuG3Vy}L+*ysy9B-Rl1pkZ5qboQ8xA+*})_X=PQCwkp(>P;?W?K<h+@qyj%c#yS
z#VA^%Xol*5`#V{#GJ|b3@=e^0gE|(uv{B1j;GeFYe}zOFb0;@V-oGv-ySOZKSGkIY
z@5b-xN*a1AWj;(%3=D=5*<8|Gpj_Br+tJQxcvzPfcN$j6h&^j~WdqheT0?4N-UyS-
zMVhXING?!jQR8~EO;cW|Yb3#iiH_pL^yx#ECLj_{n$YWPUbXzjKL2tw9t|&Fy`kX|
z4G1CrrU!FXSWAC7I{MqwC*9sYA2w{n0&y2IO>AXNGqI9WjZLbB#nbHBG|A>^8ObR^
z&*(~kUM&Xb|J4i)6(>2()=hY9sNd-%;M~H{cXHvssyVnvF~D6Tc^i-H_lrX16Mk_=
z%sS*DEU&fmb~L*9Hhg#XarEtCIC(RMtFbE6s7+$MuRmDUiM153y-sIva6rGnGeC}X
z+}c54qp;Cet>oJ1hPkb=irlsUtb{@Gb)OCf9eHa5M6rU;t#h9)hZo;2E=Q+lztS;z
zY~m9}P*@%Bd~t<U$Sgun$>>T3Mg{yyex}e{ZG&|;k6Dx%XbY{J=+iPyPf{tP3t?hE
z$A2MGU7%{aA<dLZLCf^LLrAVEiwriwTF1xmXwXcT0m#jG^yA0=w=1b*uXE>MYw|>#
zTHQiZC7@}ZzyjJs#tZaRWV6_z0|(AV=D5b(6tlA+S)fsDY|Ma|c8DaEfmUTPm(gAj
zn*5%*(&Wr)AK^P3zI@$`e^?Y^-RF|>@7IvUuS>@-?x*mP#im=s@II4GjW=z?j0|ea
zO&~0fSgd&#@bd){6@az@1wVfV@^G;+C?K!`FIr11O;{DI31bAieKd|JQxjOK>k$gT
zGEdiG*GC@KK#FOC?YWl30Mc}WIl>5GI6;&sr~(|s$|aJRc&XcuWeMt{%<2WXD8$M-
zs@a}D-KZAkPigX0%;g|VBB+Hwe*agOKyN6r5_HF0RYg>}U1MbjIUAfbie=C=7xI<B
zMwH+)yDAfn@fyn&W|g362=+bx$rehV@%w2Ctx$(s55Mb7Mbg%YYsA;1)8U7AlW*LM
z7o*E>Z%3cG7yndw<#pV$YWpij6z?-gz;ls5cjeP-sp*B^?R1*nTZyIQjz)5~`mX2D
zXDVqr5XIOw4tJwFm}|l|FHYUp%H6hacZkzxBSau%>-9Eo@igNcR8$=}qJktrV?1+Z
z<+O=Rc{p+HA<NF3u&b~gwC8kbMRP6j*|C6PLUFkj^}KW~AN8#*J}hjZpqCHz6ouq9
z1Df@B1*+Gxb}$ul9oiOV7guVQq;eu=7fyIgRF0Q+hJ^G>$uo#Ga6LYrXYSDt%7FC?
zrX$-&q5V#G?hHa8GScVP_KBD;PavLDHqKGvt@RVfrW-aEkZPDv&PeqE`B~<^^|}Yg
zbgFRExa&3nAZ3@9@13N=1o{sm1*6nR7U2Q^5?VlP)(LI0t&|v?-Jj>dhCn4<77GM~
z9<0<dbG0<V;ig$@nEVa4dVdKXVC~73lFKd;%-YdZX+3BTr%Ji1or>PJh#j_ZBP%;!
z(3eM~8QS7&wXT{?zNKDQ*&K>%l1gEY`38hOvB>uKltE>SH@*b$)izrn)4zUya2q|M
zqo;TI?Ue2|EQH`f*K$$w)VY&nxFx`krgxk7d~WP-d}UWW<f*D;{_1|(5bGy)_J#Ci
zXE(q0a0^52-ZR4Q_D*v*ule=v&r7(|UMcNOBFIH1)2gikmq$Fq%@k8VXjj{1-X8ae
z`**){+`0QQ1)My-MJ!Tv6RZPK8s$A`#dE0+v{<k@%J&@gweI3JUVC2->msnVv%9G2
z{d$*eRor_mLA>ny-R&Jr#`RD5e@XOiUs8S>JR!)5C$x$}eE!{j-r{oyz9xSaNYo~-
zNh#922Rqb|P1C~!$l0oMP?t;;%)pX1Y4=|3Iplwop!?nNUsA^D0^gn}u=%Ru9IJh5
zzJfZ25W!84|8fHD!L;T^VV!CIjD6R|V3n#*Jsm@0FM~shgQuL7I5>Lj^~e)NB7!&p
zU1lEo!W6i*fc>{CiD(CqwzMiH+;igQ-%Vh$M_()xeXaL8_OeBN*T~d!xl+kLK;5-M
zN|nOh*I{6+YG^el?w*-R%-YITC&{7B%M8~-T=T$#2hewcyR6iszrX<{{+7jZV_p_`
zX)MX_73!4}r)pa;Js^&(hP5spWAbcW?tG?q=v4$-PYK9FkaD{Rmzlka3e{}4hO|c<
z!deRLRD*R~|7JB-AF|5FF??pSApg(RvU;?)yLOe~h9Y#?s+Kyl7{P3|S0BbpIGI%`
JRBLhZ_&4HTqtXBX

literal 0
HcmV?d00001