Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix(web): checkpoint community navigation frames (#593)

Gener2474a3daf780
diff --git a/scripts/ci/e2e-shards.mjs b/scripts/ci/e2e-shards.mjs
index 6c8dc4cc3..9d23e4ae8 100644
--- a/scripts/ci/e2e-shards.mjs
+++ b/scripts/ci/e2e-shards.mjs
@@ -48,6 +48,7 @@ export const SPEC_SECONDS = {
"35-channel-ref-directory-states.spec.ts": 60,
"36-server-switch-pending-checkpoint.spec.ts": 60,
"37-server-rail-pdd.spec.ts": 10,
+ "38-community-navigation-checkpoint-matrix.spec.ts": 60,
}
function walk(directory) {
diff --git a/scripts/ci/e2e-shards.test.ts b/scripts/ci/e2e-shards.test.ts
index c7a9b316b..4a64da9f9 100644
--- a/scripts/ci/e2e-shards.test.ts
+++ b/scripts/ci/e2e-shards.test.ts
@@ -70,7 +70,7 @@ describe("planE2eShards", () => {
expect(first).toHaveLength(E2E_SHARD_COUNT)
expect([...assigned].sort()).toEqual(specs)
expect(new Set(assigned).size).toBe(specs.length)
- expect(totals.sort((left, right) => left - right)).toEqual([302, 303, 305, 305, 307])
+ expect(totals.sort((left, right) => left - right)).toEqual([314, 314, 318, 318, 318])
expect(Math.max(...totals) / Math.min(...totals)).toBeLessThanOrEqual(1.15)
})
diff --git a/src/web/src/app/c/channels/layout.tsx b/src/web/src/app/c/channels/layout.tsx
index e3973931b..d52260304 100644
--- a/src/web/src/app/c/channels/layout.tsx
+++ b/src/web/src/app/c/channels/layout.tsx
@@ -15,6 +15,7 @@ import { ShellFrame } from "@/components/community/shell/shell-frame"
import {
channelHref,
serverModalMarkerCleanupHref,
+ serverRootHref,
} from "@/lib/community/community-route"
import { useBreakpoint } from "@/hooks/use-mobile"
import { ChannelSidebar } from "@/components/community/channels/channel-sidebar"
@@ -575,6 +576,9 @@ export default function ServerLayout({ children }: { children: ReactNode }) {
/>
)
+ const structuralFrameHref = routeChannelId
+ ? channelHref(serverId, routeChannelId)
+ : serverRootHref(serverId)
const content = routeChannelId
? (
<ChannelRoute
@@ -589,6 +593,7 @@ export default function ServerLayout({ children }: { children: ReactNode }) {
<ShellFrame
view="server"
activeServerId={serverId}
+ frameHref={structuralFrameHref}
sidebar={sidebar}
extraDialogs={<>{serverSettingsDialog}{iconCropDialog}</>}
onOpenActiveServerSettings={onSidebarOpenSettings}
diff --git a/src/web/src/app/c/me/layout.tsx b/src/web/src/app/c/me/layout.tsx
index 22234580c..82d70437f 100644
--- a/src/web/src/app/c/me/layout.tsx
+++ b/src/web/src/app/c/me/layout.tsx
@@ -2,7 +2,12 @@
import { useCallback, useEffect, useMemo, type ReactNode } from "react"
import { useQueryClient } from "@tanstack/react-query"
-import { usePathname, useRouter, useParams } from "next/navigation"
+import {
+ useParams,
+ usePathname,
+ useRouter,
+ useSelectedLayoutSegments,
+} from "next/navigation"
import { ShellFrame } from "@/components/community/shell/shell-frame"
import { CommunityPendingFrame } from "@/components/community/shell/community-pending-frame"
import { DmRouteErrorFrame } from "@/components/community/channels/dm-route-error-frame"
@@ -29,6 +34,10 @@ export default function MeLayout({ children }: { children: ReactNode }) {
const router = useRouter()
const pathname = usePathname()
const params = useParams<{ dmId?: string }>()
+ const selectedSegments = useSelectedLayoutSegments()
+ const structuralFrameHref = selectedSegments.length === 0
+ ? "/c/me"
+ : `/c/me/${selectedSegments.join("/")}`
const {
dms: rawDms,
isLoading: dmsLoading,
@@ -166,6 +175,7 @@ export default function MeLayout({ children }: { children: ReactNode }) {
<ShellFrame
view="dm"
activeServerId={undefined}
+ frameHref={structuralFrameHref}
sidebar={sidebar}
>
{params.dmId && dmRouteVerification.status === "error"
diff --git a/src/web/src/components/community/channels/dm-sidebar.prefetch.test.ts b/src/web/src/components/community/channels/dm-sidebar.prefetch.test.ts
index 19f8de09c..3a2307716 100644
--- a/src/web/src/components/community/channels/dm-sidebar.prefetch.test.ts
+++ b/src/web/src/components/community/channels/dm-sidebar.prefetch.test.ts
@@ -2,11 +2,26 @@ import { createElement } from "react"
import TestRenderer, { act, type ReactTestRenderer } from "react-test-renderer"
import { describe, expect, it, vi } from "vitest"
import { tid } from "@/lib/community/testids"
-import { DmSidebar } from "./dm-sidebar"
+import { DmSidebar, DmSidebarSkeleton } from "./dm-sidebar"
;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
describe("DmSidebar navigation intent", () => {
+ it("keeps the pending DM sidebar inert and accessible", async () => {
+ let renderer!: ReactTestRenderer
+ await act(async () => {
+ renderer = TestRenderer.create(createElement(DmSidebarSkeleton))
+ })
+ const aside = renderer.root.findByType("aside")
+ expect(aside.props).toMatchObject({
+ "data-testid": tid.dmSidebarPending,
+ "aria-label": "Loading direct messages",
+ "aria-busy": true,
+ })
+ expect(renderer.root.findAllByType("button")).toHaveLength(0)
+ act(() => renderer.unmount())
+ })
+
it("keeps shortcuts outside the independently scrolling DM list", async () => {
let renderer!: ReactTestRenderer
diff --git a/src/web/src/components/community/channels/dm-sidebar.tsx b/src/web/src/components/community/channels/dm-sidebar.tsx
index 345f184b4..b468b0a91 100644
--- a/src/web/src/components/community/channels/dm-sidebar.tsx
+++ b/src/web/src/components/community/channels/dm-sidebar.tsx
@@ -110,6 +110,28 @@ export const DmSidebar = memo(function DmSidebar({
)
})
+export function DmSidebarSkeleton() {
+ return (
+ <aside
+ data-testid={tid.dmSidebarPending}
+ aria-label="Loading direct messages"
+ aria-busy={true}
+ className="flex min-h-0 min-w-0 flex-1 flex-col"
+ >
+ <div className="shrink-0 px-2 pt-4">
+ <Skeleton className="mb-1 h-9 w-full rounded-md" />
+ <Skeleton className="mb-1 h-9 w-full rounded-md" />
+ <Skeleton className="mb-2 h-9 w-full rounded-md" />
+ <div className="my-2 h-px bg-border" />
+ </div>
+ <div className="min-h-0 flex-1 overflow-y-auto thin-scrollbar px-2 pb-4">
+ <Skeleton className="mb-2 ml-2 h-3 w-24 rounded" />
+ <DmRowsSkeleton />
+ </div>
+ </aside>
+ )
+}
+
// Loading placeholder for the DM sidebar — mirrors the Friends button + DM
// row footprint so the column doesn't reflow when conversations arrive.
function DmRowsSkeleton() {
diff --git a/src/web/src/components/community/shell/shell-frame-contract.test.ts b/src/web/src/components/community/shell/shell-frame-contract.test.ts
index a92b26233..a7e099200 100644
--- a/src/web/src/components/community/shell/shell-frame-contract.test.ts
+++ b/src/web/src/components/community/shell/shell-frame-contract.test.ts
@@ -31,8 +31,11 @@ describe("ShellFrame public contract", () => {
}
expect(channels).toContain('view="server"')
expect(channels).toContain("activeServerId={serverId}")
+ expect(channels).toContain("frameHref={structuralFrameHref}")
expect(dm).toContain('view="dm"')
expect(dm).toContain("activeServerId={undefined}")
+ expect(dm).toContain("useSelectedLayoutSegments")
+ expect(dm).toContain("frameHref={structuralFrameHref}")
})
it("keeps shell-frame as orchestration with one public component", () => {
@@ -42,7 +45,7 @@ describe("ShellFrame public contract", () => {
expect(source).toContain("useShellRailController")
expect(source).toContain("useShellProfileController")
expect(source).toContain("useShellInboxController")
- expect(source).toContain("resolveCommunityRoute(pathname)")
+ expect(source).toContain("resolveCommunityCheckpointPlan")
expect(source).toContain("useCommunityNavigationController")
expect(source).toContain("<ShellFrameView")
expect(source).not.toContain("<ServerRail")
diff --git a/src/web/src/components/community/shell/shell-frame-types.ts b/src/web/src/components/community/shell/shell-frame-types.ts
index ebb850f89..319c4b745 100644
--- a/src/web/src/components/community/shell/shell-frame-types.ts
+++ b/src/web/src/components/community/shell/shell-frame-types.ts
@@ -4,6 +4,7 @@ import type { View } from "./shell-types"
export type ShellFrameProps = {
view: View
activeServerId: string | undefined
+ frameHref: string
sidebar: (opts?: { noHeader?: boolean }) => ReactNode
children: ReactNode
extraDialogs?: ReactNode
diff --git a/src/web/src/components/community/shell/shell-frame-view.test.ts b/src/web/src/components/community/shell/shell-frame-view.test.ts
index 69739a5c3..2ad3fe8a6 100644
--- a/src/web/src/components/community/shell/shell-frame-view.test.ts
+++ b/src/web/src/components/community/shell/shell-frame-view.test.ts
@@ -2,6 +2,7 @@ import { createElement, useState } from "react"
import TestRenderer, { act } from "react-test-renderer"
import { beforeEach, describe, expect, it, vi } from "vitest"
import { ShellFrameView } from "./shell-frame-view"
+import type { CommunityCheckpointPlan, CommunitySurface } from "@/lib/community/community-route"
const mocks = vi.hoisted(() => ({
observe: vi.fn(),
@@ -42,6 +43,34 @@ vi.mock("./community-pending-frame", () => ({
vi.mock("@/components/community/channels/channel-sidebar", () => ({
ChannelSidebarSkeleton: (props: Record<string, unknown>) => createElement("channel-sidebar-skeleton", props),
}))
+vi.mock("@/components/community/channels/dm-sidebar", () => ({
+ DmSidebarSkeleton: (props: Record<string, unknown>) => createElement("dm-sidebar-skeleton", props),
+}))
+
+function committedCheckpoint(
+ href: string,
+ surface: CommunitySurface,
+): CommunityCheckpointPlan {
+ return {
+ mode: "committed",
+ surface,
+ targetHref: href,
+ rail: { kind: "keep" },
+ sidebar: { kind: "keep" },
+ main: { kind: "keep" },
+ }
+}
+
+function pendingCheckpoint(
+ href: string,
+ surface: CommunitySurface,
+): CommunityCheckpointPlan {
+ return {
+ ...committedCheckpoint(href, surface),
+ mode: "same-scope-leaf",
+ main: { kind: "target-skeleton", href },
+ }
+}
const rail = { railProps: { activeServerId: "s1" } } as never
const profile = {
@@ -80,9 +109,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer = TestRenderer.create(createElement(ShellFrameView, {
breakpoint: "unknown",
- surface: "detail",
- loadingHref: "/c/me/dm_1",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/me/dm_1", "detail"),
sidebar: () => createElement("sidebar-content"),
cancelPendingNavigation: vi.fn(),
rail,
@@ -106,9 +133,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer = TestRenderer.create(createElement(ShellFrameView, {
breakpoint: "unknown",
- surface: "list",
- loadingHref: "/c/me",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/me", "list"),
sidebar: () => createElement("sidebar-content"),
cancelPendingNavigation: vi.fn(),
rail,
@@ -129,9 +154,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer = TestRenderer.create(createElement(ShellFrameView, {
breakpoint: "desktop",
- surface: "detail",
- loadingHref: "/c/channels/s1/c1",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/channels/s1/c1", "detail"),
sidebar,
cancelPendingNavigation: vi.fn(),
rail,
@@ -181,9 +204,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer = TestRenderer.create(createElement(ShellFrameView, {
breakpoint: "desktop",
- surface: "list",
- loadingHref: "/c/channels/s1",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/channels/s1", "list"),
sidebar,
cancelPendingNavigation: vi.fn(),
rail,
@@ -206,9 +227,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer = TestRenderer.create(createElement(ShellFrameView, {
breakpoint: "mobile",
- surface: "list",
- loadingHref: "/c/me",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/me", "list"),
sidebar,
cancelPendingNavigation: vi.fn(),
rail,
@@ -245,9 +264,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer.update(createElement(ShellFrameView, {
breakpoint: "mobile",
- surface: "detail",
- loadingHref: "/c/me/dm_1",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/me/dm_1", "detail"),
sidebar,
cancelPendingNavigation: vi.fn(),
rail,
@@ -275,9 +292,7 @@ describe("ShellFrameView", () => {
return createElement("stateful-main", { identity })
}
const common = {
- surface: "detail" as const,
- loadingHref: "/c/me/dm_1",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/me/dm_1", "detail"),
sidebar: () => createElement("sidebar-content"),
cancelPendingNavigation: vi.fn(),
rail,
@@ -311,9 +326,7 @@ describe("ShellFrameView", () => {
it("disconnects and re-subscribes sidebar observation across breakpoint changes", async () => {
const sidebar = vi.fn(() => createElement("sidebar-content"))
const common = {
- surface: "list" as const,
- loadingHref: "/c/me",
- navigationPending: false,
+ checkpoint: committedCheckpoint("/c/me", "list"),
sidebar,
cancelPendingNavigation: vi.fn(),
rail,
@@ -356,9 +369,7 @@ describe("ShellFrameView", () => {
const sidebar = vi.fn(() => createElement("sidebar-content"))
const common = {
sidebar,
- loadingHref: "/c/me/friends",
cancelPendingNavigation: vi.fn(),
- navigationPending: true,
rail,
profile,
inbox,
@@ -367,7 +378,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer = TestRenderer.create(createElement(
ShellFrameView,
- { ...common, breakpoint: "desktop", surface: "detail" },
+ { ...common, breakpoint: "desktop", checkpoint: pendingCheckpoint("/c/me/friends", "detail") },
createElement("main-content"),
), { createNodeMock: () => ({ offsetWidth: 240 }) })
})
@@ -379,7 +390,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer.update(createElement(
ShellFrameView,
- { ...common, breakpoint: "mobile", surface: "list" },
+ { ...common, breakpoint: "mobile", checkpoint: pendingCheckpoint("/c/me", "list") },
createElement("main-content"),
))
})
@@ -397,7 +408,7 @@ describe("ShellFrameView", () => {
await act(async () => {
renderer.update(createElement(
ShellFrameView,
- { ...common, breakpoint: "mobile", surface: "detail" },
+ { ...common, breakpoint: "mobile", checkpoint: pendingCheckpoint("/c/me/friends", "detail") },
createElement("main-content"),
))
})
@@ -412,11 +423,15 @@ describe("ShellFrameView", () => {
it("replaces the committed sidebar with one target-scoped cold server checkpoint", async () => {
const sidebar = vi.fn(() => createElement("old-sidebar"))
const common = {
- surface: "list" as const,
- loadingHref: "/c/channels/s2",
cancelPendingNavigation: vi.fn(),
- navigationPending: true,
- serverSwitchTargetId: "s2",
+ checkpoint: {
+ mode: "cold-scope",
+ surface: "list",
+ targetHref: "/c/channels/s2",
+ rail: { kind: "target", view: "server", activeServerId: "s2" },
+ sidebar: { kind: "server-skeleton", serverId: "s2" },
+ main: { kind: "target-skeleton", href: "/c/channels/s2" },
+ } satisfies CommunityCheckpointPlan,
sidebar,
rail,
profile,
@@ -449,4 +464,38 @@ describe("ShellFrameView", () => {
expect(mainPanel?.props.hidden).toBe(true)
expect(sidebar).not.toHaveBeenCalled()
})
+
+ it("renders an inert me sidebar checkpoint for a cold server-to-home target", async () => {
+ const sidebar = vi.fn(() => createElement("old-sidebar"))
+ const checkpoint: CommunityCheckpointPlan = {
+ mode: "cold-scope",
+ surface: "list",
+ targetHref: "/c/me",
+ rail: { kind: "target", view: "dm" },
+ sidebar: { kind: "me-skeleton" },
+ main: { kind: "target-skeleton", href: "/c/me" },
+ }
+ let renderer!: TestRenderer.ReactTestRenderer
+ await act(async () => {
+ renderer = TestRenderer.create(createElement(
+ ShellFrameView,
+ {
+ breakpoint: "desktop",
+ checkpoint,
+ sidebar,
+ cancelPendingNavigation: vi.fn(),
+ rail,
+ profile,
+ inbox,
+ },
+ createElement("old-main"),
+ ), { createNodeMock: () => ({ offsetWidth: 240 }) })
+ })
+
+ expect(sidebar).not.toHaveBeenCalled()
+ expect(renderer.root.findAllByType("old-sidebar")).toHaveLength(0)
+ expect(renderer.root.findAllByType("old-main")).toHaveLength(0)
+ expect(renderer.root.findAllByType("dm-sidebar-skeleton")).toHaveLength(1)
+ expect(renderer.root.findByType("channel-loading-frame").props.href).toBe("/c/me")
+ })
})
diff --git a/src/web/src/components/community/shell/shell-frame-view.tsx b/src/web/src/components/community/shell/shell-frame-view.tsx
index fdc39e786..52f9484c5 100644
--- a/src/web/src/components/community/shell/shell-frame-view.tsx
+++ b/src/web/src/components/community/shell/shell-frame-view.tsx
@@ -5,6 +5,7 @@ import { useDefaultLayout } from "react-resizable-panels"
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from "@/components/ui/resizable"
import { AppSurface } from "@/components/ui/app-surface"
import { ChannelSidebarSkeleton } from "@/components/community/channels/channel-sidebar"
+import { DmSidebarSkeleton } from "@/components/community/channels/dm-sidebar"
import { CommunityPendingFrame } from "./community-pending-frame"
import { Shell } from "./shell"
import { ServerRail } from "./server-rail"
@@ -17,7 +18,7 @@ import {
desktopUserBarOverlayWidth,
} from "./shell-frame-geometry"
import type { Breakpoint } from "@/hooks/use-mobile"
-import type { CommunitySurface } from "@/lib/community/community-route"
+import type { CommunityCheckpointPlan } from "@/lib/community/community-route"
import type { ShellFrameProps } from "./shell-frame-types"
import type { useShellRailController } from "./use-shell-rail-controller"
import type { useShellProfileController } from "./use-shell-profile-controller"
@@ -25,11 +26,8 @@ import type { useShellInboxController } from "./use-shell-inbox-controller"
type Props = Pick<ShellFrameProps, "sidebar" | "children" | "extraDialogs"> & {
breakpoint: Breakpoint
- surface: CommunitySurface
- loadingHref: string
+ checkpoint: CommunityCheckpointPlan
cancelPendingNavigation: () => void
- navigationPending: boolean
- serverSwitchTargetId?: string | null
rail: ReturnType<typeof useShellRailController>
profile: ReturnType<typeof useShellProfileController>
inbox: ReturnType<typeof useShellInboxController>
@@ -39,18 +37,16 @@ const SHELL_SURFACE_CLASS = "rounded-tl-xl rounded-tr-none rounded-br-none round
export function ShellFrameView({
breakpoint,
- surface,
- loadingHref,
+ checkpoint,
sidebar,
children,
extraDialogs,
cancelPendingNavigation,
- navigationPending,
- serverSwitchTargetId = null,
rail,
profile,
inbox,
}: Props) {
+ const { surface } = checkpoint
const { defaultLayout, onLayoutChanged } = useDefaultLayout({
id: "community-shell",
onlySaveAfterUserInteractions: true,
@@ -133,9 +129,11 @@ export function ShellFrameView({
>
<div ref={sidebarPanelRef} className="flex min-h-0 min-w-0 flex-1 flex-col">
{!isMobileDetail && (
- serverSwitchTargetId
- ? <ChannelSidebarSkeleton targetServerId={serverSwitchTargetId} />
- : isDesktop ? sidebar() : sidebar({ noHeader: false })
+ checkpoint.sidebar.kind === "server-skeleton"
+ ? <ChannelSidebarSkeleton targetServerId={checkpoint.sidebar.serverId} />
+ : checkpoint.sidebar.kind === "me-skeleton"
+ ? <DmSidebarSkeleton />
+ : isDesktop ? sidebar() : sidebar({ noHeader: false })
)}
</div>
</ResizablePanel>
@@ -151,19 +149,19 @@ export function ShellFrameView({
isInitialDetail && "max-sm:flex-1!",
)}
>
- {navigationPending || isInitial ? (
+ {checkpoint.main.kind === "target-skeleton" || isInitial ? (
isInitialDetail ? (
<>
<div className="flex min-h-0 flex-1 sm:hidden">
- <CommunityPendingFrame href={loadingHref} reserveBackSlot />
+ <CommunityPendingFrame href={checkpoint.targetHref} reserveBackSlot />
</div>
<div className="hidden min-h-0 flex-1 sm:flex">
- <CommunityPendingFrame href={loadingHref} />
+ <CommunityPendingFrame href={checkpoint.targetHref} />
</div>
</>
) : (
<CommunityPendingFrame
- href={loadingHref}
+ href={checkpoint.targetHref}
reserveBackSlot={isMobileDetail}
/>
)
diff --git a/src/web/src/components/community/shell/shell-frame.test.ts b/src/web/src/components/community/shell/shell-frame.test.ts
index 27ce7feb2..def287bd5 100644
--- a/src/web/src/components/community/shell/shell-frame.test.ts
+++ b/src/web/src/components/community/shell/shell-frame.test.ts
@@ -50,7 +50,7 @@ vi.mock("@/lib/community-onboarding", () => ({
}))
vi.mock("./use-community-navigation-controller", () => ({
useCommunityNavigationController: () => ({
- currentHref: mocks.currentHref.current,
+ publishedHref: mocks.currentHref.current,
navigationPending: mocks.navigationPending.current,
pendingHref: mocks.pendingHref.current,
push: mocks.push,
@@ -84,6 +84,7 @@ vi.mock("./shell-frame-view", () => ({
const baseProps = {
view: "server" as const,
activeServerId: "s1",
+ frameHref: "/c/channels/s1",
sidebar: () => createElement("sidebar"),
}
@@ -103,38 +104,66 @@ describe("ShellFrame orchestration", () => {
afterEach(() => vi.unstubAllGlobals())
- it("derives list and detail surfaces from the pathname", async () => {
+ it("does not rewrite the committed frame from an eagerly published pathname", async () => {
let renderer!: TestRenderer.ReactTestRenderer
await act(async () => {
renderer = TestRenderer.create(createElement(ShellFrame, baseProps))
})
- expect(renderer.root.findByType("shell-frame-view").props.surface).toBe("list")
- expect(renderer.root.findByType("shell-frame-view").props.loadingHref).toBe("/c/channels/s1")
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint.surface).toBe("list")
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint.targetHref).toBe("/c/channels/s1")
mocks.currentHref.current = "/c/channels/s1/c1?keep=1"
await act(async () => {
renderer.update(createElement(ShellFrame, baseProps, "next"))
})
- expect(renderer.root.findByType("shell-frame-view").props.surface).toBe("detail")
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint.surface).toBe("list")
+ })
+
+ it("advances the committed descriptor from layout-owned frameHref", async () => {
+ mocks.currentHref.current = "/c/channels/s1/c2"
+ mocks.pendingHref.current = "/c/channels/s1/c2"
+ mocks.navigationPending.current = true
+ const sourceProps = { ...baseProps, frameHref: "/c/channels/s1/c1" }
+ let renderer!: TestRenderer.ReactTestRenderer
+ await act(async () => {
+ renderer = TestRenderer.create(createElement(ShellFrame, sourceProps))
+ })
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint.mode)
+ .toBe("same-scope-leaf")
+
+ await act(async () => {
+ renderer.update(createElement(ShellFrame, {
+ ...sourceProps,
+ frameHref: "/c/channels/s1/c2",
+ }))
+ })
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint.mode)
+ .toBe("committed")
})
it("uses the pending destination surface before the committed href changes", async () => {
mocks.currentHref.current = "/c/channels/s1/c1"
mocks.pendingHref.current = "/c/channels/s1"
+ mocks.navigationPending.current = true
+ const sourceProps = { ...baseProps, frameHref: "/c/channels/s1/c1" }
let renderer!: TestRenderer.ReactTestRenderer
await act(async () => {
- renderer = TestRenderer.create(createElement(ShellFrame, baseProps))
+ renderer = TestRenderer.create(createElement(ShellFrame, sourceProps))
+ })
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint).toMatchObject({
+ surface: "list",
+ targetHref: "/c/channels/s1",
+ main: { kind: "target-skeleton", href: "/c/channels/s1" },
})
- expect(renderer.root.findByType("shell-frame-view").props.surface).toBe("list")
- expect(renderer.root.findByType("shell-frame-view").props.loadingHref).toBe("/c/channels/s1")
mocks.pendingHref.current = "/c/me/dm_1?from=inbox"
await act(async () => {
- renderer.update(createElement(ShellFrame, baseProps, "next"))
+ renderer.update(createElement(ShellFrame, sourceProps, "next"))
+ })
+ expect(renderer.root.findByType("shell-frame-view").props.checkpoint).toMatchObject({
+ surface: "detail",
+ targetHref: "/c/me/dm_1?from=inbox",
})
- expect(renderer.root.findByType("shell-frame-view").props.surface).toBe("detail")
- expect(renderer.root.findByType("shell-frame-view").props.loadingHref)
- .toBe("/c/me/dm_1?from=inbox")
})
it("projects one cold cross-server target into rail, middle, and right", async () => {
@@ -143,18 +172,22 @@ describe("ShellFrame orchestration", () => {
mocks.navigationPending.current = true
let renderer!: TestRenderer.ReactTestRenderer
await act(async () => {
- renderer = TestRenderer.create(createElement(ShellFrame, baseProps))
+ renderer = TestRenderer.create(createElement(ShellFrame, {
+ ...baseProps,
+ frameHref: "/c/channels/s1/c1",
+ }))
})
const view = renderer.root.findByType("shell-frame-view")
- expect(view.props).toMatchObject({
+ expect(view.props.checkpoint).toMatchObject({
+ mode: "cold-scope",
surface: "list",
- loadingHref: "/c/channels/s2",
- navigationPending: true,
- serverSwitchTargetId: "s2",
+ targetHref: "/c/channels/s2",
+ sidebar: { kind: "server-skeleton", serverId: "s2" },
})
expect(mocks.railOptions).toHaveBeenLastCalledWith(expect.objectContaining({
activeServerId: "s1",
+ projectedView: "server",
projectedActiveServerId: "s2",
}))
})
@@ -166,18 +199,22 @@ describe("ShellFrame orchestration", () => {
mocks.serverCache.add("s2")
let renderer!: TestRenderer.ReactTestRenderer
await act(async () => {
- renderer = TestRenderer.create(createElement(ShellFrame, baseProps))
+ renderer = TestRenderer.create(createElement(ShellFrame, {
+ ...baseProps,
+ frameHref: "/c/channels/s1/c1",
+ }))
})
const view = renderer.root.findByType("shell-frame-view")
- expect(view.props).toMatchObject({
+ expect(view.props.checkpoint).toMatchObject({
+ mode: "warm-scope",
surface: "detail",
- loadingHref: "/c/channels/s1/c1",
- navigationPending: false,
- serverSwitchTargetId: null,
+ targetHref: "/c/channels/s2",
+ main: { kind: "keep" },
})
expect(mocks.railOptions).toHaveBeenLastCalledWith(expect.objectContaining({
activeServerId: "s1",
+ projectedView: "server",
projectedActiveServerId: "s1",
}))
})
@@ -187,7 +224,10 @@ describe("ShellFrame orchestration", () => {
mocks.currentHref.current = "/c/channels/s1/c1"
let renderer!: TestRenderer.ReactTestRenderer
await act(async () => {
- renderer = TestRenderer.create(createElement(ShellFrame, baseProps))
+ renderer = TestRenderer.create(createElement(ShellFrame, {
+ ...baseProps,
+ frameHref: "/c/channels/s1/c1",
+ }))
})
const handlers = mocks.registerUiHandlers.mock.calls.at(-1)?.[0]
handlers.goBackMobile()
@@ -200,7 +240,12 @@ describe("ShellFrame orchestration", () => {
mocks.onboardingState.current = { status: "active", stage: "server" }
await act(async () => {
- TestRenderer.create(createElement(ShellFrame, baseProps))
+ TestRenderer.create(createElement(ShellFrame, {
+ ...baseProps,
+ view: "dm",
+ activeServerId: undefined,
+ frameHref: "/c/me/dm_1",
+ }))
})
expect(mocks.replace).toHaveBeenCalledWith("/c/me")
@@ -212,7 +257,12 @@ describe("ShellFrame orchestration", () => {
mocks.onboardingState.current = { status: "active", stage: "server" }
await act(async () => {
- TestRenderer.create(createElement(ShellFrame, baseProps))
+ TestRenderer.create(createElement(ShellFrame, {
+ ...baseProps,
+ view: "dm",
+ activeServerId: undefined,
+ frameHref: "/c/me",
+ }))
})
expect(mocks.replace).not.toHaveBeenCalled()
@@ -221,7 +271,10 @@ describe("ShellFrame orchestration", () => {
it("registers the shared navigation and UI handlers", async () => {
let renderer!: TestRenderer.ReactTestRenderer
await act(async () => {
- renderer = TestRenderer.create(createElement(ShellFrame, baseProps))
+ renderer = TestRenderer.create(createElement(ShellFrame, {
+ ...baseProps,
+ frameHref: "/c/channels/s1/c1",
+ }))
})
const first = mocks.registerUiHandlers.mock.calls.at(-1)?.[0]
expect(Object.keys(first).sort()).toEqual([
@@ -237,14 +290,20 @@ describe("ShellFrame orchestration", () => {
mocks.currentHref.current = "/c/channels/s1/c1?msg=m1"
await act(async () => {
- renderer.update(createElement(ShellFrame, baseProps, "message"))
+ renderer.update(createElement(ShellFrame, {
+ ...baseProps,
+ frameHref: "/c/channels/s1/c1",
+ }, "message"))
})
const withMessage = mocks.registerUiHandlers.mock.calls.at(-1)?.[0]
withMessage.goBackMobile()
expect(mocks.replace).toHaveBeenLastCalledWith("/c/channels/s1")
await act(async () => {
- renderer.update(createElement(ShellFrame, baseProps, "rerender"))
+ renderer.update(createElement(ShellFrame, {
+ ...baseProps,
+ frameHref: "/c/channels/s1/c1",
+ }, "rerender"))
})
const second = mocks.registerUiHandlers.mock.calls.at(-1)?.[0]
expect(second.navigatePath).toBe(withMessage.navigatePath)
diff --git a/src/web/src/components/community/shell/shell-frame.tsx b/src/web/src/components/community/shell/shell-frame.tsx
index 23f1ded54..382cb73ae 100644
--- a/src/web/src/components/community/shell/shell-frame.tsx
+++ b/src/web/src/components/community/shell/shell-frame.tsx
@@ -1,13 +1,15 @@
"use client"
-import { useCallback, useEffect } from "react"
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react"
import { useQueryClient } from "@tanstack/react-query"
import { useBreakpoint } from "@/hooks/use-mobile"
import { useCommunityOnboarding } from "@/lib/community-onboarding"
import {
- communityServerId,
+ advanceCommunityCommittedFrame,
+ normalizeCommunityHref,
+ resolveCommunityCheckpointPlan,
resolveCommunityRoute,
- resolveServerSwitchCheckpoint,
+ type CommunityCommittedFrame,
} from "@/lib/community/community-route"
import { communityKeys } from "@/lib/query-keys"
import { useCommunityStore } from "@/stores/community"
@@ -23,6 +25,7 @@ export function ShellFrame(props: ShellFrameProps) {
const {
view,
activeServerId,
+ frameHref,
sidebar,
children,
extraDialogs,
@@ -32,26 +35,43 @@ export function ShellFrame(props: ShellFrameProps) {
const queryClient = useQueryClient()
const breakpoint = useBreakpoint()
const onboardingState = useCommunityOnboarding()
- const navigation = useCommunityNavigationController()
+ const initialCommittedFrame: CommunityCommittedFrame = {
+ ...normalizeCommunityHref(frameHref),
+ revision: 0,
+ }
+ const committedFrameRef = useRef(initialCommittedFrame)
+ const [committedFrame, setCommittedFrame] = useState(initialCommittedFrame)
+ const commitFrame = useCallback((href: string) => {
+ const current = committedFrameRef.current
+ const next = advanceCommunityCommittedFrame(current, href)
+ if (next === current) return
+ committedFrameRef.current = next
+ setCommittedFrame(next)
+ }, [])
+ useLayoutEffect(() => commitFrame(frameHref), [commitFrame, frameHref])
+ const navigation = useCommunityNavigationController(committedFrame)
const replacePath = navigation.replace
- const pathname = navigation.currentHref.split("?")[0]!
- const route = resolveCommunityRoute(pathname)
- const pendingPathname = navigation.pendingHref?.split("?")[0]
- const pendingRoute = pendingPathname ? resolveCommunityRoute(pendingPathname) : null
- const pendingServerId = navigation.pendingHref
- ? communityServerId(navigation.pendingHref)
+ const route = resolveCommunityRoute(committedFrame.pathname)
+ const target = navigation.pendingHref
+ ? normalizeCommunityHref(navigation.pendingHref)
: null
- const serverSwitch = resolveServerSwitchCheckpoint({
- currentHref: navigation.currentHref,
- pendingHref: navigation.pendingHref,
- hasExactServerDetail: pendingServerId
- ? queryClient.getQueryData(communityKeys.server(pendingServerId)) !== undefined
- : false,
+ const targetReady = target?.scope.kind === "server"
+ ? queryClient.getQueryData(communityKeys.server(target.scope.serverId)) !== undefined
+ : target?.scope.kind === "me"
+ ? queryClient.getQueryData(communityKeys.dms()) !== undefined
+ : false
+ const checkpoint = resolveCommunityCheckpointPlan({
+ committedFrame,
+ targetHref: navigation.pendingHref,
+ pending: navigation.navigationPending,
+ targetReady,
})
- const coldServerSwitchTargetId = serverSwitch?.cold
- ? serverSwitch.targetServerId
- : null
- const warmServerSwitch = serverSwitch != null && !serverSwitch.cold
+ const projectedView = checkpoint.rail.kind === "target"
+ ? checkpoint.rail.view
+ : view
+ const projectedActiveServerId = checkpoint.rail.kind === "target"
+ ? checkpoint.rail.activeServerId
+ : activeServerId
const rail = useShellRailController({
navigation,
@@ -59,7 +79,8 @@ export function ShellFrame(props: ShellFrameProps) {
breakpoint,
view,
activeServerId,
- projectedActiveServerId: coldServerSwitchTargetId ?? activeServerId,
+ projectedView,
+ projectedActiveServerId,
onOpenActiveServerSettings,
onOpenActiveServerInvite,
})
@@ -115,15 +136,10 @@ export function ShellFrame(props: ShellFrameProps) {
return (
<ShellFrameView
breakpoint={breakpoint}
- surface={warmServerSwitch ? route.surface : pendingRoute?.surface ?? route.surface}
- loadingHref={warmServerSwitch
- ? navigation.currentHref
- : navigation.pendingHref ?? navigation.currentHref}
+ checkpoint={checkpoint}
sidebar={sidebar}
extraDialogs={extraDialogs}
cancelPendingNavigation={navigation.cancelPendingNavigation}
- navigationPending={navigation.navigationPending && !warmServerSwitch}
- serverSwitchTargetId={coldServerSwitchTargetId}
rail={rail}
profile={profile}
inbox={inbox}
diff --git a/src/web/src/components/community/shell/use-community-navigation-controller.test.ts b/src/web/src/components/community/shell/use-community-navigation-controller.test.ts
index 1aed5c843..4e98ced3d 100644
--- a/src/web/src/components/community/shell/use-community-navigation-controller.test.ts
+++ b/src/web/src/components/community/shell/use-community-navigation-controller.test.ts
@@ -1,7 +1,8 @@
import { createElement } from "react"
import TestRenderer, { act } from "react-test-renderer"
-import { beforeEach, describe, expect, it, vi } from "vitest"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
import { useCommunityNavigationController } from "./use-community-navigation-controller"
+import { normalizeCommunityHref, type CommunityCommittedFrame } from "@/lib/community/community-route"
const mocks = vi.hoisted(() => ({
pathname: { current: "/c/me" },
@@ -9,6 +10,9 @@ const mocks = vi.hoisted(() => ({
push: vi.fn(),
replace: vi.fn(),
prefetch: vi.fn(),
+ frame: {
+ current: null as CommunityCommittedFrame | null,
+ },
}))
vi.mock("next/navigation", () => ({
@@ -24,7 +28,7 @@ vi.mock("next/navigation", () => ({
type Result = ReturnType<typeof useCommunityNavigationController>
function Capture({ onResult }: { onResult: (result: Result) => void }) {
- onResult(useCommunityNavigationController())
+ onResult(useCommunityNavigationController(mocks.frame.current!))
return null
}
@@ -50,9 +54,13 @@ describe("useCommunityNavigationController", () => {
mocks.push.mockReset()
mocks.replace.mockReset()
mocks.prefetch.mockReset()
+ mocks.frame.current = { ...normalizeCommunityHref("/c/me"), revision: 0 }
+ vi.stubGlobal("window", new EventTarget())
})
- it("sets pending immediately and clears it after the committed href changes", async () => {
+ afterEach(() => vi.unstubAllGlobals())
+
+ it("does not treat published pathname as commit and clears after frame evidence", async () => {
const hook = await renderController()
expect(hook.current.navigationPending).toBe(false)
expect(hook.current.pendingHref).toBeNull()
@@ -64,6 +72,11 @@ describe("useCommunityNavigationController", () => {
mocks.pathname.current = "/c/me/friends"
await hook.rerender()
+ expect(hook.current.navigationPending).toBe(true)
+ expect(hook.current.pendingHref).toBe("/c/me/friends")
+
+ mocks.frame.current = { ...normalizeCommunityHref("/c/me/friends"), revision: 1 }
+ await hook.rerender()
expect(hook.current.navigationPending).toBe(false)
expect(hook.current.pendingHref).toBeNull()
})
@@ -81,14 +94,13 @@ describe("useCommunityNavigationController", () => {
expect(hook.current.pendingHref).toBe("/c/channels/s2")
mocks.pathname.current = "/c/channels/s1"
+ mocks.frame.current = { ...normalizeCommunityHref("/c/channels/s1"), revision: 1 }
await hook.rerender()
expect(hook.current.navigationPending).toBe(true)
expect(hook.current.pendingHref).toBe("/c/channels/s2")
- // The semantic server-root intent may commit through its canonical
- // landing redirect. That leaf still commits the exact latest server
- // target; the stale s1 leaf above must not.
mocks.pathname.current = "/c/channels/s2/c2"
+ mocks.frame.current = { ...normalizeCommunityHref("/c/channels/s2"), revision: 2 }
await hook.rerender()
expect(hook.current.navigationPending).toBe(false)
expect(hook.current.pendingHref).toBeNull()
@@ -102,6 +114,45 @@ describe("useCommunityNavigationController", () => {
expect(hook.current.pendingHref).toBe("/c/channels/s1")
})
+ it("keeps a same-server root intent pending until the exact root frame commits", async () => {
+ mocks.pathname.current = "/c/channels/s1/c1"
+ mocks.frame.current = { ...normalizeCommunityHref("/c/channels/s1/c1"), revision: 6 }
+ const hook = await renderController()
+
+ await act(async () => hook.current.replace("/c/channels/s1"))
+ mocks.pathname.current = "/c/channels/s1"
+ await hook.rerender()
+ expect(hook.current.pendingHref).toBe("/c/channels/s1")
+
+ mocks.frame.current = { ...normalizeCommunityHref("/c/channels/s1/c1"), revision: 7 }
+ await hook.rerender()
+ expect(hook.current.pendingHref).toBe("/c/channels/s1")
+
+ mocks.frame.current = { ...normalizeCommunityHref("/c/channels/s1"), revision: 8 }
+ await hook.rerender()
+ expect(hook.current.pendingHref).toBeNull()
+ })
+
+ it("settles same-leaf query and hash targets without a structural frame revision", async () => {
+ mocks.pathname.current = "/c/me/friends"
+ mocks.frame.current = { ...normalizeCommunityHref("/c/me/friends"), revision: 3 }
+ const hook = await renderController()
+
+ await act(async () => hook.current.push("/c/me/friends?b=2&a=1#card"))
+ mocks.search.current = new URLSearchParams("a=1&b=2")
+ await hook.rerender()
+ expect(hook.current.pendingHref).toBeNull()
+ })
+
+ it("cancels pending on popstate without synthesizing router history", async () => {
+ const hook = await renderController()
+ await act(async () => hook.current.push("/c/me/friends"))
+ await act(async () => window.dispatchEvent(new Event("popstate")))
+ expect(hook.current.pendingHref).toBeNull()
+ expect(mocks.replace).not.toHaveBeenCalled()
+ expect(mocks.push).toHaveBeenCalledTimes(1)
+ })
+
it("commits only the latest async destination", async () => {
const hook = await renderController()
let resolveFirst!: (href: string) => void
diff --git a/src/web/src/components/community/shell/use-community-navigation-controller.ts b/src/web/src/components/community/shell/use-community-navigation-controller.ts
index 9bd234af5..4da3cfe1d 100644
--- a/src/web/src/components/community/shell/use-community-navigation-controller.ts
+++ b/src/web/src/components/community/shell/use-community-navigation-controller.ts
@@ -7,11 +7,16 @@ import {
createNavigationIntentGate,
supersedeNavigationIntent,
} from "@/lib/community/navigation-intent"
-import { communityServerId, serverRootHref } from "@/lib/community/community-route"
+import {
+ isPublishedNonStructuralCommit,
+ isStructuralFrameCommit,
+ normalizeCommunityHref,
+ type CommunityCommittedFrame,
+} from "@/lib/community/community-route"
import type { ShellRouter } from "./shell-frame-types"
export type CommunityNavigationController = {
- currentHref: string
+ publishedHref: string
navigationPending: boolean
pendingHref: string | null
push: (href: string) => void
@@ -21,22 +26,17 @@ export type CommunityNavigationController = {
cancelPendingNavigation: () => void
}
-function hasCommittedPendingHref(currentHref: string, pendingHref: string): boolean {
- if (currentHref === pendingHref) return true
- const pendingServerId = communityServerId(pendingHref)
- if (!pendingServerId) return false
- const pendingPathname = pendingHref.split(/[?#]/, 1)[0]
- return pendingPathname === serverRootHref(pendingServerId)
- && communityServerId(currentHref) === pendingServerId
-}
-
-export function useCommunityNavigationController(): CommunityNavigationController {
+export function useCommunityNavigationController(
+ committedFrame: CommunityCommittedFrame,
+): CommunityNavigationController {
const router = useRouter() as ShellRouter
const pathname = usePathname()
const searchParams = useSearchParams()
const search = searchParams.toString()
- const currentHref = search ? `${pathname}?${search}` : pathname
+ const publishedHref = search ? `${pathname}?${search}` : pathname
const gateRef = useRef(createNavigationIntentGate())
+ const pendingBaselineRevisionRef = useRef(committedFrame.revision)
+ const pendingBaselineLeafRef = useRef(committedFrame.leafKey)
const [navigationPending, setNavigationPending] = useState(false)
const [pendingHref, setPendingHref] = useState<string | null>(null)
@@ -47,37 +47,56 @@ export function useCommunityNavigationController(): CommunityNavigationControlle
}, [])
useEffect(() => {
- // A stale route commit must not clear a newer synchronous intent. Keep the
- // latest pending href until that exact destination becomes current; Shell
- // navigation intent/cancellation still clears it explicitly.
- if (pendingHref !== null && !hasCommittedPendingHref(currentHref, pendingHref)) return
+ if (pendingHref === null) return
+ const target = normalizeCommunityHref(pendingHref)
+ const settled = target.leafKey === pendingBaselineLeafRef.current
+ ? isPublishedNonStructuralCommit(committedFrame, publishedHref, pendingHref)
+ : isStructuralFrameCommit({
+ committedFrame,
+ targetHref: pendingHref,
+ baselineRevision: pendingBaselineRevisionRef.current,
+ })
+ if (!settled) return
supersedeNavigationIntent(gateRef.current)
setNavigationPending(false)
- if (pendingHref !== null) setPendingHref(null)
- }, [currentHref, pendingHref])
+ setPendingHref(null)
+ }, [committedFrame, pendingHref, publishedHref])
+
+ useEffect(() => {
+ if (typeof window === "undefined") return
+ const onPopState = () => cancelPendingNavigation()
+ window.addEventListener("popstate", onPopState)
+ return () => window.removeEventListener("popstate", onPopState)
+ }, [cancelPendingNavigation])
const push = useCallback((href: string) => {
- if (href === currentHref) return
+ if (href === publishedHref) return
supersedeNavigationIntent(gateRef.current)
+ pendingBaselineRevisionRef.current = committedFrame.revision
+ pendingBaselineLeafRef.current = committedFrame.leafKey
setNavigationPending(true)
setPendingHref(href)
router.push(href)
- }, [currentHref, router])
+ }, [committedFrame.leafKey, committedFrame.revision, publishedHref, router])
const replace = useCallback((href: string) => {
- if (href === currentHref) return
+ if (href === publishedHref) return
supersedeNavigationIntent(gateRef.current)
+ pendingBaselineRevisionRef.current = committedFrame.revision
+ pendingBaselineLeafRef.current = committedFrame.leafKey
setNavigationPending(true)
setPendingHref(href)
router.replace(href)
- }, [currentHref, router])
+ }, [committedFrame.leafKey, committedFrame.revision, publishedHref, router])
const resolveAndPush = useCallback(async (resolve: () => Promise<string>) => {
+ pendingBaselineRevisionRef.current = committedFrame.revision
+ pendingBaselineLeafRef.current = committedFrame.leafKey
setNavigationPending(true)
setPendingHref(null)
try {
return await commitLatestNavigationIntent(gateRef.current, resolve, (href) => {
- if (href === currentHref) {
+ if (href === publishedHref) {
setNavigationPending(false)
setPendingHref(null)
return
@@ -90,10 +109,10 @@ export function useCommunityNavigationController(): CommunityNavigationControlle
setPendingHref(null)
throw error
}
- }, [currentHref, router])
+ }, [committedFrame.leafKey, committedFrame.revision, publishedHref, router])
return {
- currentHref,
+ publishedHref,
navigationPending,
pendingHref,
push,
diff --git a/src/web/src/components/community/shell/use-shell-rail-controller.test.ts b/src/web/src/components/community/shell/use-shell-rail-controller.test.ts
index 457ced96e..eddfcab38 100644
--- a/src/web/src/components/community/shell/use-shell-rail-controller.test.ts
+++ b/src/web/src/components/community/shell/use-shell-rail-controller.test.ts
@@ -71,7 +71,7 @@ async function renderController(overrides: Record<string, unknown> = {}) {
prefetch: (href: string) => { prefetched.push(href) },
}
const navigation = {
- currentHref: "/c/channels/s1",
+ publishedHref: "/c/channels/s1",
navigationPending: false,
pendingHref: null,
push: router.push,
@@ -91,6 +91,7 @@ async function renderController(overrides: Record<string, unknown> = {}) {
breakpoint: "desktop",
view: "server",
activeServerId: "s1",
+ projectedActiveServerId: "s1",
...overrides,
} as never
let current!: Result
@@ -160,6 +161,23 @@ describe("useShellRailController", () => {
expect(hook.pushed).toEqual(["/c/channels/s2?settings=1"])
})
+ it("projects Home visually without changing committed server action scope", async () => {
+ const openSettings = vi.fn()
+ const hook = await renderController({
+ projectedView: "dm",
+ projectedActiveServerId: undefined,
+ onOpenActiveServerSettings: openSettings,
+ })
+
+ expect(hook.current.railProps.view).toBe("dm")
+ expect(hook.current.railProps.activeServerId).toBeUndefined()
+ expect(hook.current.railProps.servers.every((server) => !server.active)).toBe(true)
+
+ await act(async () => hook.current.railProps.onOpenSettings("s1"))
+ expect(openSettings).toHaveBeenCalledTimes(1)
+ expect(hook.pushed).toEqual([])
+ })
+
it("does not leave deferred server work that can overwrite a direct channel navigation", async () => {
const hook = await renderController()
await act(async () => {
diff --git a/src/web/src/components/community/shell/use-shell-rail-controller.ts b/src/web/src/components/community/shell/use-shell-rail-controller.ts
index a5ad94c2c..68f639bf3 100644
--- a/src/web/src/components/community/shell/use-shell-rail-controller.ts
+++ b/src/web/src/components/community/shell/use-shell-rail-controller.ts
@@ -19,6 +19,7 @@ import type { Breakpoint } from "@/hooks/use-mobile"
import { useCommunityStore } from "@/stores/community"
import { resolveServerRailOverlayAction } from "./server-rail-actions"
import type { ShellFrameProps } from "./shell-frame-types"
+import type { View } from "./shell-types"
import type { CommunityNavigationController } from "./use-community-navigation-controller"
import type { QueryClient } from "@tanstack/react-query"
@@ -32,7 +33,8 @@ type Options = Pick<
navigation: CommunityNavigationController
queryClient: QueryClient
breakpoint: Breakpoint
- projectedActiveServerId?: string
+ projectedView?: View
+ projectedActiveServerId: string | undefined
}
export function useShellRailController({
@@ -40,8 +42,9 @@ export function useShellRailController({
queryClient,
breakpoint,
view,
+ projectedView = view,
activeServerId,
- projectedActiveServerId = activeServerId,
+ projectedActiveServerId,
onOpenActiveServerSettings,
onOpenActiveServerInvite,
}: Options) {
@@ -169,7 +172,7 @@ export function useShellRailController({
folders,
activeServerId: projectedActiveServerId,
serversLoading: serversQuery.isLoading,
- view,
+ view: projectedView,
onHome,
onHomePrefetch,
onServerNavigate,
diff --git a/src/web/src/lib/community/community-route.test.ts b/src/web/src/lib/community/community-route.test.ts
index 8cd0e1bfd..cca1e6c71 100644
--- a/src/web/src/lib/community/community-route.test.ts
+++ b/src/web/src/lib/community/community-route.test.ts
@@ -1,10 +1,14 @@
import { describe, expect, it } from "vitest"
import {
+ advanceCommunityCommittedFrame,
channelHref,
+ isPublishedNonStructuralCommit,
+ isStructuralFrameCommit,
+ normalizeCommunityHref,
communityServerId,
removeCommunityParam,
+ resolveCommunityCheckpointPlan,
resolveCommunityRoute,
- resolveServerSwitchCheckpoint,
serverModalMarkerCleanupHref,
serverRootHref,
} from "./community-route"
@@ -36,44 +40,111 @@ describe("community route", () => {
expect(communityServerId(href)).toBe(serverId)
})
- it("keeps a cold target checkpoint through eager pathname publication", () => {
- expect(resolveServerSwitchCheckpoint({
- currentHref: "/c/channels/server_1/channel_1",
- pendingHref: "/c/channels/server_2?settings=1",
- hasExactServerDetail: false,
- })).toEqual({ targetServerId: "server_2", cold: true })
- expect(resolveServerSwitchCheckpoint({
- currentHref: "/c/channels/server_1/channel_1",
- pendingHref: "/c/channels/server_2",
- hasExactServerDetail: true,
- })).toEqual({ targetServerId: "server_2", cold: false })
- expect(resolveServerSwitchCheckpoint({
- currentHref: "/c/channels/server_2",
- pendingHref: "/c/channels/server_2",
- hasExactServerDetail: false,
- })).toEqual({ targetServerId: "server_2", cold: true })
- expect(resolveServerSwitchCheckpoint({
- currentHref: "/c/channels/server_1/channel_1",
- pendingHref: "/c/channels/server_1/channel_2#message",
- hasExactServerDetail: true,
- })).toBeNull()
+ it("normalizes query order and keeps structural scope independent from hash", () => {
+ expect(normalizeCommunityHref("/c/channels/server_1/channel_1?z=2&a=1#message"))
+ .toEqual({
+ href: "/c/channels/server_1/channel_1?a=1&z=2",
+ pathname: "/c/channels/server_1/channel_1",
+ search: "a=1&z=2",
+ scope: { kind: "server", serverId: "server_1" },
+ surface: "detail",
+ leafKey: "/c/channels/server_1/channel_1",
+ })
+ })
- for (const pendingHref of [
- null,
- "/c/me/friends",
- "/malformed",
- ]) {
- expect(resolveServerSwitchCheckpoint({
- currentHref: "/c/channels/server_1/channel_1",
- pendingHref,
- hasExactServerDetail: false,
- })).toBeNull()
+ it("keeps an unknown pending href on the committed frame", () => {
+ const committedFrame = {
+ ...normalizeCommunityHref("/c/channels/s1/c1"),
+ revision: 4,
}
- expect(resolveServerSwitchCheckpoint({
- currentHref: "/c/me/friends",
- pendingHref: "/c/channels/server_2",
- hasExactServerDetail: false,
- })).toBeNull()
+ expect(resolveCommunityCheckpointPlan({
+ committedFrame,
+ targetHref: "/malformed",
+ pending: true,
+ targetReady: false,
+ })).toEqual({
+ mode: "committed",
+ surface: "detail",
+ targetHref: "/malformed",
+ rail: { kind: "keep" },
+ sidebar: { kind: "keep" },
+ main: { kind: "keep" },
+ })
+ })
+
+ it.each([
+ ["/c/channels/s1/c1", "/c/channels/s1/c2", false, "same-scope-leaf"],
+ ["/c/me/friends", "/c/me/machines", false, "same-scope-leaf"],
+ ["/c/channels/s1/c1", "/c/channels/s2/c2", false, "cold-scope"],
+ ["/c/channels/s1/c1", "/c/channels/s2/c2", true, "warm-scope"],
+ ["/c/channels/s1/c1", "/c/me/friends", false, "cold-scope"],
+ ["/c/me/friends", "/c/channels/s2", false, "cold-scope"],
+ ])("resolves %s -> %s with targetReady=%s as %s", (
+ source,
+ target,
+ targetReady,
+ mode,
+ ) => {
+ const committedFrame = { ...normalizeCommunityHref(source), revision: 4 }
+ expect(resolveCommunityCheckpointPlan({
+ committedFrame,
+ targetHref: target,
+ pending: true,
+ targetReady,
+ }).mode).toBe(mode)
+ })
+
+ it("keeps committed A as the source after the router publishes B", () => {
+ const committedFrame = {
+ ...normalizeCommunityHref("/c/channels/s1/c1"),
+ revision: 7,
+ }
+ expect(resolveCommunityCheckpointPlan({
+ committedFrame,
+ targetHref: "/c/channels/s2/c2",
+ pending: true,
+ targetReady: false,
+ })).toEqual({
+ mode: "cold-scope",
+ surface: "detail",
+ targetHref: "/c/channels/s2/c2",
+ rail: { kind: "target", view: "server", activeServerId: "s2" },
+ sidebar: { kind: "server-skeleton", serverId: "s2" },
+ main: { kind: "target-skeleton", href: "/c/channels/s2/c2" },
+ })
+ })
+
+ it("settles non-structural publication but requires newer exact frame evidence structurally", () => {
+ const c1 = { ...normalizeCommunityHref("/c/channels/s1/c1"), revision: 10 }
+ expect(isPublishedNonStructuralCommit(
+ c1,
+ "/c/channels/s1/c1?b=2&a=1",
+ "/c/channels/s1/c1?a=1&b=2#message",
+ )).toBe(true)
+ expect(isStructuralFrameCommit({
+ committedFrame: c1,
+ targetHref: "/c/channels/s1",
+ baselineRevision: 10,
+ })).toBe(false)
+ expect(isStructuralFrameCommit({
+ committedFrame: { ...normalizeCommunityHref("/c/channels/s1"), revision: 11 },
+ targetHref: "/c/channels/s1",
+ baselineRevision: 10,
+ })).toBe(true)
+ expect(isStructuralFrameCommit({
+ committedFrame: { ...normalizeCommunityHref("/c/channels/s1/c1"), revision: 11 },
+ targetHref: "/c/channels/s1",
+ baselineRevision: 10,
+ })).toBe(false)
+ })
+
+ it("advances frame revision only from a different structural commit marker", () => {
+ const c1 = { ...normalizeCommunityHref("/c/channels/s1/c1"), revision: 4 }
+ expect(advanceCommunityCommittedFrame(c1, "/c/channels/s1/c1")).toBe(c1)
+ expect(advanceCommunityCommittedFrame(c1, "/c/channels/s1/c2")).toEqual({
+ ...normalizeCommunityHref("/c/channels/s1/c2"),
+ revision: 5,
+ })
})
it("removes one query key while preserving the rest and the hash", () => {
diff --git a/src/web/src/lib/community/community-route.ts b/src/web/src/lib/community/community-route.ts
index d4c77ae13..e89daf13a 100644
--- a/src/web/src/lib/community/community-route.ts
+++ b/src/web/src/lib/community/community-route.ts
@@ -5,9 +5,36 @@ export type CommunityRoute = {
parentPath: string | null
}
-export type ServerSwitchCheckpoint = {
- targetServerId: string
- cold: boolean
+type CommunityScope =
+ | { kind: "server"; serverId: string }
+ | { kind: "me" }
+ | { kind: "unknown" }
+
+export type CommunityHref = {
+ href: string
+ pathname: string
+ search: string
+ scope: CommunityScope
+ surface: CommunitySurface
+ leafKey: string
+}
+
+export type CommunityCommittedFrame = CommunityHref & {
+ revision: number
+}
+
+export type CommunityCheckpointPlan = {
+ mode: "committed" | "same-scope-leaf" | "warm-scope" | "cold-scope"
+ surface: CommunitySurface
+ targetHref: string
+ rail:
+ | { kind: "keep" }
+ | { kind: "target"; view: "dm" | "server"; activeServerId?: string }
+ sidebar:
+ | { kind: "keep" }
+ | { kind: "server-skeleton"; serverId: string }
+ | { kind: "me-skeleton" }
+ main: { kind: "keep" } | { kind: "target-skeleton"; href: string }
}
export function communityServerId(href: string): string | null {
@@ -18,25 +45,136 @@ export function communityServerId(href: string): string | null {
: null
}
-export function resolveServerSwitchCheckpoint({
- currentHref,
- pendingHref,
- hasExactServerDetail,
+export function normalizeCommunityHref(href: string): CommunityHref {
+ const hashIndex = href.indexOf("#")
+ const withoutHash = hashIndex === -1 ? href : href.slice(0, hashIndex)
+ const queryIndex = withoutHash.indexOf("?")
+ const pathname = queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex)
+ const searchParams = new URLSearchParams(
+ queryIndex === -1 ? "" : withoutHash.slice(queryIndex + 1),
+ )
+ searchParams.sort()
+ const search = searchParams.toString()
+ const segments = pathname.split("/").filter(Boolean)
+ const scope: CommunityScope = segments[0] === "c" && segments[1] === "channels" && segments[2]
+ ? { kind: "server", serverId: segments[2] }
+ : segments[0] === "c" && segments[1] === "me"
+ ? { kind: "me" }
+ : { kind: "unknown" }
+ return {
+ href: `${pathname}${search ? `?${search}` : ""}`,
+ pathname,
+ search,
+ scope,
+ surface: resolveCommunityRoute(pathname).surface,
+ leafKey: pathname,
+ }
+}
+
+function communityScopeEqual(a: CommunityScope, b: CommunityScope): boolean {
+ if (a.kind !== b.kind) return false
+ if (a.kind === "server" && b.kind === "server") return a.serverId === b.serverId
+ return a.kind !== "unknown"
+}
+
+export function isPublishedNonStructuralCommit(
+ committedFrame: CommunityCommittedFrame,
+ publishedHref: string,
+ targetHref: string,
+): boolean {
+ const published = normalizeCommunityHref(publishedHref)
+ const target = normalizeCommunityHref(targetHref)
+ return committedFrame.leafKey === target.leafKey && published.href === target.href
+}
+
+export function isStructuralFrameCommit({
+ committedFrame,
+ targetHref,
+ baselineRevision,
}: {
- currentHref: string
- pendingHref: string | null
- hasExactServerDetail: boolean
-}): ServerSwitchCheckpoint | null {
- if (!pendingHref) return null
- const currentServerId = communityServerId(currentHref)
- const targetServerId = communityServerId(pendingHref)
- if (!currentServerId || !targetServerId) return null
- // Next may publish the target pathname before the target layout's exact
- // server detail is ready. pendingHref is still authoritative during that
- // gap: keep the target-scoped cold checkpoint instead of exposing an empty
- // target sidebar merely because both parsed ids now match.
- if (currentServerId === targetServerId && hasExactServerDetail) return null
- return { targetServerId, cold: !hasExactServerDetail }
+ committedFrame: CommunityCommittedFrame
+ targetHref: string
+ baselineRevision: number
+}): boolean {
+ if (committedFrame.revision <= baselineRevision) return false
+ return committedFrame.leafKey === normalizeCommunityHref(targetHref).leafKey
+}
+
+export function advanceCommunityCommittedFrame(
+ current: CommunityCommittedFrame,
+ href: string,
+): CommunityCommittedFrame {
+ const next = normalizeCommunityHref(href)
+ if (current.leafKey === next.leafKey) return current
+ return { ...next, revision: current.revision + 1 }
+}
+
+export function resolveCommunityCheckpointPlan({
+ committedFrame,
+ targetHref,
+ pending,
+ targetReady,
+}: {
+ committedFrame: CommunityCommittedFrame
+ targetHref: string | null
+ pending: boolean
+ targetReady: boolean
+}): CommunityCheckpointPlan {
+ if (!pending || !targetHref) {
+ return committedPlan(committedFrame)
+ }
+
+ const target = normalizeCommunityHref(targetHref)
+ if (target.scope.kind === "unknown" || target.leafKey === committedFrame.leafKey) {
+ return committedPlan(committedFrame, target.href)
+ }
+
+ if (communityScopeEqual(committedFrame.scope, target.scope)) {
+ return {
+ mode: "same-scope-leaf",
+ surface: target.surface,
+ targetHref: target.href,
+ rail: { kind: "keep" },
+ sidebar: { kind: "keep" },
+ main: { kind: "target-skeleton", href: target.href },
+ }
+ }
+
+ if (targetReady) {
+ return {
+ ...committedPlan(committedFrame, target.href),
+ mode: "warm-scope",
+ }
+ }
+
+ const rail = target.scope.kind === "server"
+ ? { kind: "target" as const, view: "server" as const, activeServerId: target.scope.serverId }
+ : { kind: "target" as const, view: "dm" as const }
+ const sidebar = target.scope.kind === "server"
+ ? { kind: "server-skeleton" as const, serverId: target.scope.serverId }
+ : { kind: "me-skeleton" as const }
+ return {
+ mode: "cold-scope",
+ surface: target.surface,
+ targetHref: target.href,
+ rail,
+ sidebar,
+ main: { kind: "target-skeleton", href: target.href },
+ }
+}
+
+function committedPlan(
+ frame: CommunityCommittedFrame,
+ targetHref = frame.href,
+): CommunityCheckpointPlan {
+ return {
+ mode: "committed",
+ surface: frame.surface,
+ targetHref,
+ rail: { kind: "keep" },
+ sidebar: { kind: "keep" },
+ main: { kind: "keep" },
+ }
}
export function resolveCommunityRoute(pathname: string): CommunityRoute {
diff --git a/src/web/src/lib/community/testids.test.ts b/src/web/src/lib/community/testids.test.ts
index b6fa996cc..9f971c8b1 100644
--- a/src/web/src/lib/community/testids.test.ts
+++ b/src/web/src/lib/community/testids.test.ts
@@ -47,6 +47,7 @@ describe("community QA selectors", () => {
it("keys a pending channel sidebar by its target server", () => {
expect(tid.channelSidebarPending("server_1"))
.toBe("community-channel-sidebar-pending-server_1")
+ expect(tid.dmSidebarPending).toBe("community-dm-sidebar-pending")
})
it("exposes attachment preview selectors from one canonical map", () => {
diff --git a/src/web/src/lib/community/testids.ts b/src/web/src/lib/community/testids.ts
index b542427de..13ed2839d 100644
--- a/src/web/src/lib/community/testids.ts
+++ b/src/web/src/lib/community/testids.ts
@@ -23,6 +23,7 @@ export const tid = {
serverRailMoveConfirm: "community-server-rail-move-confirm",
channelSidebarScroll: "community-channel-sidebar-scroll",
channelSidebarPending: (serverId: string) => `community-channel-sidebar-pending-${serverId}`,
+ dmSidebarPending: "community-dm-sidebar-pending",
createServerSubmit: "community-create-server-submit",
createServerName: "community-create-server-name",
createChannelSubmit: "community-create-channel-submit",
diff --git a/src/web/src/test/e2e-ui/38-community-navigation-checkpoint-matrix.spec.ts b/src/web/src/test/e2e-ui/38-community-navigation-checkpoint-matrix.spec.ts
new file mode 100644
index 000000000..a1002bbf1
--- /dev/null
+++ b/src/web/src/test/e2e-ui/38-community-navigation-checkpoint-matrix.spec.ts
@@ -0,0 +1,93 @@
+import type { Page, Route } from "@playwright/test"
+import { test, expect } from "./_fixtures/community-fixture"
+import { seedChannel, seedServer } from "./_fixtures/seed"
+import { tid } from "./_fixtures/testids"
+
+async function holdRoute(page: Page, pathname: string) {
+ let releaseGate!: () => void
+ const gate = new Promise<void>((resolve) => { releaseGate = resolve })
+ let held = 0
+ const pattern = `**${pathname}**`
+ const handler = async (route: Route) => {
+ held += 1
+ await gate
+ await route.continue()
+ }
+ await page.route(pattern, handler)
+ return {
+ held: () => held,
+ release: async () => {
+ releaseGate()
+ await page.waitForTimeout(100)
+ await page.unroute(pattern, handler)
+ },
+ }
+}
+
+test("community checkpoint waits for layout-owned frame commits", async ({ asUser }) => {
+ test.setTimeout(120_000)
+ const stamp = Date.now()
+ const serverId = await seedServer("alice", `Frame Gate ${stamp}`)
+ const channelAName = `frame-a-${stamp}`
+ const channelBName = `frame-b-${stamp}`
+ const channelA = await seedChannel("alice", serverId, channelAName)
+ const channelB = await seedChannel("alice", serverId, channelBName)
+ const { page } = await asUser("alice")
+ await page.setViewportSize({ width: 1280, height: 900 })
+ await page.goto(`/c/channels/${serverId}/${channelA}`)
+ await expect(page.getByRole("heading", { name: channelAName })).toBeVisible({ timeout: 30_000 })
+
+ const readOnlyPostPaths = new Set([
+ "/api/community/messages/batch",
+ "/api/community/messages/tags/batch",
+ "/api/community/channels/participants/batch",
+ ])
+ const mutations: string[] = []
+ page.on("request", (request) => {
+ const method = request.method()
+ const pathname = new URL(request.url()).pathname
+ if (
+ !["GET", "HEAD", "OPTIONS"].includes(method)
+ && !(method === "POST" && readOnlyPostPaths.has(pathname))
+ ) mutations.push(`${method} ${pathname}`)
+ })
+
+ const leafGate = await holdRoute(page, `/c/channels/${serverId}/${channelB}`)
+ await page.getByTestId(tid.channelRow(channelB)).click({ noWaitAfter: true })
+ await expect.poll(leafGate.held).toBeGreaterThan(0)
+ await expect(page.getByLabel("Loading conversation")).toBeVisible()
+ await expect(page.getByRole("heading", { name: channelAName })).toHaveCount(0)
+ await page.waitForTimeout(150)
+ await expect(page.getByLabel("Loading conversation")).toBeVisible()
+ await leafGate.release()
+ await expect(page.getByRole("heading", { name: channelBName })).toBeVisible({ timeout: 30_000 })
+
+ await page.setViewportSize({ width: 390, height: 844 })
+ const rootGate = await holdRoute(page, `/c/channels/${serverId}`)
+ await page.getByRole("button", { name: "Back" }).click({ noWaitAfter: true })
+ await expect.poll(rootGate.held).toBeGreaterThan(0)
+ await page.setViewportSize({ width: 1280, height: 900 })
+ await expect(page.getByLabel("Loading conversation")).toBeVisible()
+ await expect(page.getByRole("heading", { name: channelBName })).toHaveCount(0)
+ await page.waitForTimeout(150)
+ await expect(page.getByLabel("Loading conversation")).toBeVisible()
+ await rootGate.release()
+ await expect(page.getByRole("heading", { name: channelBName })).toBeVisible({ timeout: 30_000 })
+
+ await page.goto("/c/me/friends")
+ await expect(page.getByPlaceholder("Search friends")).toBeVisible({ timeout: 30_000 })
+ const machinesGate = await holdRoute(page, "/c/me/machines")
+ await page.getByRole("button", { name: "Machines", exact: true }).click({ noWaitAfter: true })
+ await expect.poll(machinesGate.held).toBeGreaterThan(0)
+ await expect(page.getByLabel("Loading conversation")).toHaveCount(0)
+ await expect(page.getByRole("button", { name: "Machines", exact: true }))
+ .toHaveClass(/bg-sidebar-accent/)
+ await expect(page.getByPlaceholder("Search friends")).toHaveCount(0)
+ await page.waitForTimeout(150)
+ await expect(page.getByPlaceholder("Search friends")).toHaveCount(0)
+ await machinesGate.release()
+ await expect(page.getByRole("heading", { name: "No machines yet", exact: true }))
+ .toBeVisible({ timeout: 30_000 })
+
+ expect(mutations).toEqual([])
+})