From 4946dc2e8e8982619628fbcdff2c156298afb893 Mon Sep 17 00:00:00 2001
From: Mohamed Hassan <mohamedahassan1998@gmail.com>
Date: Fri, 18 Sep 2026 12:42:34 +0100
Subject: [PATCH 1/4] feat: tunnel concepts page

---
 src/components.ts                             |   3 +
 src/components/react/container/Transport.tsx  |  12 +-
 src/components/react/diagram-weld/shapes.tsx  |  16 +-
 src/components/react/diagram-weld/welding.ts  |  28 +-
 .../react/tunnel/TunnelIdentity.tsx           | 179 ++++++++++
 src/components/react/tunnel/TunnelKit.tsx     | 190 +++++++++++
 .../react/tunnel/TunnelOutbound.tsx           | 235 +++++++++++++
 src/components/react/tunnel/TunnelTraffic.tsx | 312 ++++++++++++++++++
 src/content/docs/tunnel/concepts/index.mdx    | 103 +++++-
 src/styles/globals.css                        |  46 +++
 10 files changed, 1106 insertions(+), 18 deletions(-)
 create mode 100644 src/components/react/tunnel/TunnelIdentity.tsx
 create mode 100644 src/components/react/tunnel/TunnelKit.tsx
 create mode 100644 src/components/react/tunnel/TunnelOutbound.tsx
 create mode 100644 src/components/react/tunnel/TunnelTraffic.tsx

diff --git a/src/components.ts b/src/components.ts
index f439c2ed30f..ef8ae6e29c6 100644
--- a/src/components.ts
+++ b/src/components.ts
@@ -84,3 +84,6 @@ export { ContainerIsolation } from "./components/react/container/ContainerIsolat
 export { ContainerRequestPath } from "./components/react/container/ContainerRequestPath";
 export { ContainerLifecycle } from "./components/react/container/ContainerLifecycle";
 export { ContainerPlacement } from "./components/react/container/ContainerPlacement";
+export { TunnelOutbound } from "./components/react/tunnel/TunnelOutbound";
+export { TunnelIdentity } from "./components/react/tunnel/TunnelIdentity";
+export { TunnelTraffic } from "./components/react/tunnel/TunnelTraffic";
diff --git a/src/components/react/container/Transport.tsx b/src/components/react/container/Transport.tsx
index 6d292e1f655..e6b28d1a7cc 100644
--- a/src/components/react/container/Transport.tsx
+++ b/src/components/react/container/Transport.tsx
@@ -175,21 +175,29 @@ export function LabeledButton({
 	ariaLabel,
 	title,
 	highlight,
+	disabled,
+	ariaDisabled,
 	onClick,
 	children,
 }: {
 	ariaLabel: string;
 	title?: string;
 	highlight?: boolean;
+	disabled?: boolean;
+	/** Visually dims and blocks clicks like `disabled`, but stays
+	 *  focusable — for controls that disable themselves once used. */
+	ariaDisabled?: boolean;
 	onClick: () => void;
 	children: ReactNode;
 }) {
 	return (
 		<button
 			type="button"
-			onClick={onClick}
+			onClick={ariaDisabled ? undefined : onClick}
 			aria-label={ariaLabel}
 			title={title}
+			aria-disabled={ariaDisabled || undefined}
+			disabled={disabled}
 			className={cn(
 				"inline-flex items-center justify-center gap-1.5 px-2 py-1 font-mono text-[10px] font-medium tracking-widest uppercase",
 				"cursor-pointer rounded-sm border shadow-xs select-none active:scale-[0.97]",
@@ -197,6 +205,8 @@ export function LabeledButton({
 				"border-neutral-200 dark:border-neutral-800",
 				"bg-white hover:bg-neutral-50 dark:bg-neutral-900 dark:hover:bg-neutral-800",
 				highlight && "ring-brand ring-1",
+				(disabled || ariaDisabled) &&
+					"cursor-default opacity-45 hover:bg-white active:scale-100 dark:hover:bg-neutral-900",
 			)}
 		>
 			{children}
diff --git a/src/components/react/diagram-weld/shapes.tsx b/src/components/react/diagram-weld/shapes.tsx
index 0f161c0db83..1cbb3d59b11 100644
--- a/src/components/react/diagram-weld/shapes.tsx
+++ b/src/components/react/diagram-weld/shapes.tsx
@@ -70,6 +70,8 @@ export interface WeldedCardProps {
 	accent?: boolean;
 	/** Drop the shadow — for a card overlaid on another. */
 	flat?: boolean;
+	/** Corner radius override — pass rect.h / 2 for a fully rounded pill. */
+	rx?: number;
 }
 
 export function WeldedCard({
@@ -81,10 +83,11 @@ export function WeldedCard({
 	dashed = false,
 	accent = false,
 	flat = false,
+	rx,
 }: WeldedCardProps) {
 	return (
 		<path
-			d={indentedRect(rect, notches)}
+			d={indentedRect(rect, notches, rx)}
 			fill={accent ? "var(--color-brand)" : "white"}
 			fillOpacity={accent ? 0.06 : 1}
 			stroke={active ? "var(--color-brand)" : "currentColor"}
@@ -602,6 +605,8 @@ export interface LabelCardProps {
 	active?: boolean;
 	ghost?: boolean;
 	fontSize?: number;
+	/** Corner radius override — pass rect.h / 2 for a fully rounded pill. */
+	rx?: number;
 }
 
 export function LabelCard({
@@ -610,11 +615,18 @@ export function LabelCard({
 	label,
 	active = false,
 	ghost = false,
+	rx,
 	fontSize = 9,
 }: LabelCardProps) {
 	return (
 		<g>
-			<WeldedCard rect={rect} notches={notches} active={active} ghost={ghost} />
+			<WeldedCard
+				rect={rect}
+				notches={notches}
+				active={active}
+				ghost={ghost}
+				rx={rx}
+			/>
 			<text
 				x={rect.cx}
 				y={rect.cy + fontSize * 0.33}
diff --git a/src/components/react/diagram-weld/welding.ts b/src/components/react/diagram-weld/welding.ts
index aed8b64105a..785bcb29fcc 100644
--- a/src/components/react/diagram-weld/welding.ts
+++ b/src/components/react/diagram-weld/welding.ts
@@ -30,26 +30,36 @@ export interface NotchConfig {
 	right?: NotchSide;
 }
 
-function resolveSide(side: NotchSide | undefined, edge: number): number[] {
+function resolveSide(
+	side: NotchSide | undefined,
+	edge: number,
+	radius = RX,
+): number[] {
 	if (!side) return [];
 	const raw = side === true ? [0.5] : [...side].sort((a, b) => a - b);
 	if (edge <= 0) return [];
-	const min = (RX + NOTCH_W) / edge;
+	// a notch (width NOTCH_W, centred on f) must clear the corner arcs:
+	// centre >= radius + NOTCH_W/2 from either corner. Exact fit allowed.
+	const min = (radius + NOTCH_W / 2) / edge;
 	const max = 1 - min;
-	if (min >= max) return [];
+	if (min > max) return [];
 	return raw.filter((f) => f >= min && f <= max);
 }
 
-export function indentedRect(rect: NodeRect, notches: NotchConfig): string {
+export function indentedRect(
+	rect: NodeRect,
+	notches: NotchConfig,
+	radius = RX,
+): string {
 	const { l, t, r: right, b, w, h } = rect;
-	const rx = Math.min(RX, w / 2, h / 2);
+	const rx = Math.min(radius, w / 2, h / 2);
 	const nw = NOTCH_W;
 	const nd = NOTCH_D;
 
-	const top = resolveSide(notches.top, w);
-	const bottom = resolveSide(notches.bottom, w);
-	const leftSide = resolveSide(notches.left, h);
-	const rightSide = resolveSide(notches.right, h);
+	const top = resolveSide(notches.top, w, rx);
+	const bottom = resolveSide(notches.bottom, w, rx);
+	const leftSide = resolveSide(notches.left, h, rx);
+	const rightSide = resolveSide(notches.right, h, rx);
 
 	const parts: string[] = [`M ${l + rx},${t}`];
 
diff --git a/src/components/react/tunnel/TunnelIdentity.tsx b/src/components/react/tunnel/TunnelIdentity.tsx
new file mode 100644
index 00000000000..6a6f2d0c366
--- /dev/null
+++ b/src/components/react/tunnel/TunnelIdentity.tsx
@@ -0,0 +1,179 @@
+"use client";
+
+// Figure 2 on the Tunnel concepts page: one tunnel identity above, two
+// interchangeable connectors below, both inside the network boundary. Each
+// request pours down to whichever connector serves this turn. Stopping
+// connector B reroutes every request to connector A; the tunnel ID never
+// changes.
+import { useEffect, useRef, useState } from "react";
+import { Diagram, useDiagramOrDefault } from "@cloudflare/nimbus-docs/react";
+import { LabelCard, makeRect } from "../diagram-weld";
+import { WeldCanvas } from "../container/WeldCanvas";
+import { LabeledButton, Toolbar } from "../container/Transport";
+import type { DiagramFallbackProps } from "../container/DiagramFallback";
+import { NetBoundary, Port, Pour, ortho } from "./TunnelKit";
+
+// Layout, in SVG user units. Both connectors hang off one vertical spine.
+const VIEW_W = 340;
+const VIEW_H = 290;
+const CX = 170; // shared centre spine
+const JY = 108; // junction row: stem in from above, two branches out
+const TUN = makeRect(115, 26, 110, 40); // tunnel nameplate
+const FIELD = makeRect(38, 152, 264, 116); // "Your network" boundary
+const CARDS = [makeRect(57, 200, 104, 36), makeRect(179, 200, 104, 36)];
+const XS = [109, 231]; // branch x-coordinate for connector A / B
+
+// Animation timing.
+const ARRIVE_MS = 820; // a pour reaches the connector
+const TURN_MS = 1450; // the next request begins
+const POUR_DUR = 0.8;
+const POUR_FADE = 1.25;
+
+// Path a request follows from the tunnel port down to the given connector.
+function wavePath(lane: 0 | 1): string {
+	return ortho([
+		[CX, TUN.b - 6],
+		[CX, JY],
+		[XS[lane]!, JY],
+		[XS[lane]!, CARDS[lane]!.t],
+	]);
+}
+
+export function TunnelIdentity(_props: DiagramFallbackProps) {
+	return (
+		<Diagram label="Two connectors inside your network serve one stable tunnel identity. Requests alternate between them; stopping connector B sends every request through connector A while the tunnel ID never changes. Operate it with the Stop connector B control.">
+			<IdentityBody />
+		</Diagram>
+	);
+}
+
+function IdentityBody() {
+	const ctx = useDiagramOrDefault("TunnelIdentity");
+	const reduced = ctx.reducedMotion;
+	const [bStopped, setBStopped] = useState(false);
+	const [tick, setTick] = useState(0);
+	const [arrived, setArrived] = useState(false);
+	const [lane, setLane] = useState<0 | 1>(0);
+
+	// Sample the stop control only at a turn boundary, never mid-pour, so an
+	// in-flight request always finishes and only the following one reroutes.
+	const bStoppedRef = useRef(bStopped);
+	bStoppedRef.current = bStopped;
+
+	useEffect(() => {
+		if (reduced || !ctx.playing) {
+			setArrived(true);
+			setLane(0);
+			return;
+		}
+		setLane(bStoppedRef.current ? 0 : ((tick % 2) as 0 | 1));
+		setArrived(false);
+		const arrive = setTimeout(() => setArrived(true), ARRIVE_MS);
+		const advance = setTimeout(() => setTick((t) => t + 1), TURN_MS);
+		return () => {
+			clearTimeout(arrive);
+			clearTimeout(advance);
+		};
+	}, [tick, reduced, ctx.playing]);
+
+	return (
+		<WeldCanvas
+			width={VIEW_W}
+			height={VIEW_H}
+			liveStatus={
+				bStopped
+					? "Connector B is stopped; every request is served by connector A. The tunnel identity is unchanged."
+					: "Requests alternate between connector A and connector B under one tunnel identity."
+			}
+			controls={
+				<Toolbar
+					status={bStopped ? "Connector B stopped" : "Both connectors live"}
+				>
+					<LabeledButton
+						ariaLabel={bStopped ? "Start connector B" : "Stop connector B"}
+						onClick={() => setBStopped((v) => !v)}
+						highlight={!bStopped}
+					>
+						{bStopped ? "Start connector B" : "Stop connector B"}
+					</LabeledButton>
+				</Toolbar>
+			}
+		>
+			<NetBoundary rect={FIELD} label="Your network" labelAnchor="middle" />
+
+			{/* Stem from the tunnel down to the junction. */}
+			<path
+				d={`M ${CX} ${TUN.b + 5} L ${CX} ${JY - 4}`}
+				fill="none"
+				strokeWidth={1.25}
+				className="stroke-neutral-300 dark:stroke-neutral-700"
+			/>
+
+			{/* The two branches leaving the junction; B dims when stopped. */}
+			{CARDS.map((c, i) => (
+				<path
+					key={i}
+					d={ortho([
+						[CX, JY],
+						[XS[i]!, JY],
+						[XS[i]!, c.t - 1],
+					])}
+					fill="none"
+					strokeWidth={1.25}
+					className="stroke-neutral-300 dark:stroke-neutral-700"
+					opacity={bStopped && i === 1 ? 0.3 : 1}
+					style={{ transition: "opacity 250ms" }}
+				/>
+			))}
+
+			{/* The request: a pour down the live branch. Remounting on a new key
+			    each turn restarts the CSS draw animation. */}
+			{!reduced && ctx.playing && (
+				<Pour
+					key={`${tick}-${lane}`}
+					d={wavePath(lane)}
+					dur={POUR_DUR}
+					fade={POUR_FADE}
+				/>
+			)}
+
+			{/* Junction node. */}
+			<rect
+				x={CX - 4}
+				y={JY - 4}
+				width={8}
+				height={8}
+				rx={1.5}
+				strokeWidth={1.25}
+				fill="var(--nb-background, white)"
+				className="stroke-neutral-300 dark:stroke-neutral-700"
+			/>
+
+			{/* The tunnel: a fixed identity and its port — the one thing that
+			    never changes. */}
+			<LabelCard rect={TUN} label="Tunnel #123" fontSize={11} active />
+			<Port cx={CX} cy={TUN.b} taken />
+
+			{/* The connectors. Whichever receives this turn lights up; connector
+			    B ghosts and frees its port while stopped. */}
+			{CARDS.map((c, i) => {
+				const receiving = arrived && lane === i && !(bStopped && i === 1);
+				return (
+					<LabelCard
+						key={i}
+						rect={c}
+						label={i === 0 ? "Connector A" : "Connector B"}
+						fontSize={11}
+						active={receiving && !reduced}
+						ghost={bStopped && i === 1}
+						notches={{ top: true }}
+					/>
+				);
+			})}
+			<Port cx={XS[0]!} cy={CARDS[0]!.t} taken />
+			<Port cx={XS[1]!} cy={CARDS[1]!.t} taken={!bStopped} />
+		</WeldCanvas>
+	);
+}
+
+export default TunnelIdentity;
diff --git a/src/components/react/tunnel/TunnelKit.tsx b/src/components/react/tunnel/TunnelKit.tsx
new file mode 100644
index 00000000000..7c2af1a3e77
--- /dev/null
+++ b/src/components/react/tunnel/TunnelKit.tsx
@@ -0,0 +1,190 @@
+"use client";
+
+// Shared marks for the tunnel concept diagrams (src/content/docs/tunnel/
+// concepts/index.mdx). Built on diagram-weld; all motion is CSS
+// (weld-draw / weld-pour-fade / weld-squash / weld-spark in globals.css).
+import { WeldedCard, measureLabel, type NodeRect } from "../diagram-weld";
+
+/** Port hardware — the pad atom seated on a card edge. A live
+ *  connection's port is taken (brand inner mark); a free one rests. */
+export function Port({
+	cx,
+	cy,
+	taken,
+}: {
+	cx: number;
+	cy: number;
+	taken: boolean;
+}) {
+	return (
+		<g>
+			<rect
+				x={cx - 5}
+				y={cy - 5}
+				width={10}
+				height={10}
+				rx={2}
+				strokeWidth={1.25}
+				fill="var(--nb-background, white)"
+				className="stroke-neutral-300 dark:stroke-neutral-700"
+			/>
+			<rect
+				x={cx - 2}
+				y={cy - 2}
+				width={4}
+				height={4}
+				className={
+					taken ? "fill-brand" : "fill-neutral-400 dark:fill-neutral-600"
+				}
+				style={{ transition: "fill 250ms" }}
+			/>
+		</g>
+	);
+}
+
+/** A network / scope boundary: the dashed-fence idiom, named by a
+ *  dash-bordered pill straddling its top border. */
+export function NetBoundary({
+	rect,
+	label,
+	labelAnchor = "start",
+}: {
+	rect: NodeRect;
+	label: string;
+	labelAnchor?: "start" | "middle";
+}) {
+	const w = measureLabel(label, { fontSize: 9, letterSpacing: 0.12 }) + 18;
+	const h = 18;
+	const cx =
+		labelAnchor === "middle" ? rect.l + rect.w / 2 : rect.l + 10 + w / 2;
+	return (
+		<g>
+			<WeldedCard rect={rect} dashed muted flat notches={{}} />
+			<rect
+				x={cx - w / 2}
+				y={rect.t - h / 2}
+				width={w}
+				height={h}
+				rx={h / 2}
+				strokeWidth={1}
+				strokeDasharray="4 3"
+				fill="var(--nb-background, white)"
+				className="stroke-neutral-300 dark:stroke-neutral-700"
+			/>
+			<text
+				x={cx}
+				y={rect.t + 3}
+				textAnchor="middle"
+				className="fill-neutral-600 font-mono font-medium uppercase dark:fill-neutral-300"
+				style={{ fontSize: 9, letterSpacing: "0.12em" }}
+			>
+				{label}
+			</text>
+		</g>
+	);
+}
+
+/** Orthogonal path with rounded corners (radius 6 quadratics). */
+export function ortho(pts: [number, number][], r = 6): string {
+	if (pts.length < 2) return "";
+	let d = `M ${pts[0]![0]} ${pts[0]![1]}`;
+	for (let i = 1; i < pts.length - 1; i++) {
+		const [px, py] = pts[i - 1]!;
+		const [cx, cy] = pts[i]!;
+		const [nx, ny] = pts[i + 1]!;
+		const idx = Math.sign(cx - px),
+			idy = Math.sign(cy - py);
+		const odx = Math.sign(nx - cx),
+			ody = Math.sign(ny - cy);
+		const rr = Math.min(
+			r,
+			Math.max(Math.abs(cx - px), Math.abs(cy - py)) / 2,
+			Math.max(Math.abs(nx - cx), Math.abs(ny - cy)) / 2,
+		);
+		d += ` L ${cx - idx * rr} ${cy - idy * rr} Q ${cx} ${cy} ${cx + odx * rr} ${cy + ody * rr}`;
+	}
+	d += ` L ${pts[pts.length - 1]![0]} ${pts[pts.length - 1]![1]}`;
+	return d;
+}
+
+/** A request as a smooth pour of colour along a path — draws with the
+ *  weld-draw keyframe, holds, fades. Pure CSS; safe under SSR. */
+export function Pour({
+	d,
+	dur,
+	fade = dur + 0.45,
+}: {
+	d: string;
+	dur: number;
+	/** Total lifetime including the fade-out; defaults to dur + 0.45s. */
+	fade?: number;
+}) {
+	// weld-pour-fade holds full opacity until 72% of `fade`; the clamp
+	// keeps the stroke from fading before it finishes drawing.
+	const fadeS = Math.max(fade, dur / 0.72);
+	return (
+		<path
+			d={d}
+			fill="none"
+			strokeWidth={1.5}
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			pathLength={1}
+			strokeDasharray="1"
+			strokeDashoffset={1}
+			className="stroke-brand"
+			style={{
+				animation: `weld-draw ${dur}s cubic-bezier(0.45, 0, 0.55, 1) forwards, weld-pour-fade ${fadeS}s linear forwards`,
+			}}
+		/>
+	);
+}
+
+/** The refusal: a request squashed flat against a boundary. */
+export function Squash({ x, y }: { x: number; y: number }) {
+	return (
+		<g style={{ transform: `translate(${x}px, ${y}px)` }}>
+			<rect
+				x={-3}
+				y={-3}
+				width={6}
+				height={6}
+				className="fill-brand"
+				style={{ animation: "weld-squash 0.5s ease-out forwards" }}
+			/>
+		</g>
+	);
+}
+
+/** Open-circuit sparks at a bare conductor end. */
+export function Sparks({ x, y }: { x: number; y: number }) {
+	const jets: [number, number][] = [
+		[-9, -10],
+		[-4, -14],
+		[1, -16],
+		[6, -12],
+		[10, -8],
+	];
+	return (
+		<g style={{ transform: `translate(${x}px, ${y}px)` }}>
+			{jets.map(([dx, dy], i) => (
+				<rect
+					key={i}
+					x={-1.5}
+					y={-1.5}
+					width={3}
+					height={3}
+					className="fill-brand"
+					style={
+						{
+							"--spark-x": `${dx}px`,
+							"--spark-y": `${dy}px`,
+							animation: `weld-spark 0.5s ease-out ${i * 0.04}s forwards`,
+							opacity: 0,
+						} as React.CSSProperties
+					}
+				/>
+			))}
+		</g>
+	);
+}
diff --git a/src/components/react/tunnel/TunnelOutbound.tsx b/src/components/react/tunnel/TunnelOutbound.tsx
new file mode 100644
index 00000000000..2736276b406
--- /dev/null
+++ b/src/components/react/tunnel/TunnelOutbound.tsx
@@ -0,0 +1,235 @@
+"use client";
+
+// Figure 1 on the Tunnel concepts page: cloudflared opens connections
+// outward. Before the tunnel exists a request squashes against the
+// port-less network boundary (no public address, nothing listening).
+// Enabling the tunnel draws connections upward out of cloudflared, seating
+// into ports at both ends. There are no arrowheads: the connection is
+// hardware; direction is carried only by the moving request.
+import { useEffect, useState } from "react";
+import { Diagram, useDiagramOrDefault } from "@cloudflare/nimbus-docs/react";
+import { LabelCard, makeRect } from "../diagram-weld";
+import { WeldCanvas } from "../container/WeldCanvas";
+import { LabeledButton, Toolbar } from "../container/Transport";
+import type { DiagramFallbackProps } from "../container/DiagramFallback";
+import { NetBoundary, Port, Pour, Squash } from "./TunnelKit";
+
+// Layout, in SVG user units.
+const VIEW_W = 340;
+const VIEW_H = 258;
+const CX = 170; // centre spine
+const CF = makeRect(122, 22, 96, 40); // Cloudflare card
+const FIELD = makeRect(52, 116, 236, 122); // "Your network" boundary
+const DAEMON = makeRect(110, 148, 120, 40); // cloudflared card
+const LANES = [154, 186]; // x of the two connection lanes
+
+// Timing (ms).
+const CONNECT_MS = 1050;
+const CONNECT_MS_REDUCED = 60;
+const REFUSED_HOLD_MS = 1000;
+const FLOW_HOLD_MS = 780;
+const REDUCED_HOLD_MS = 1100;
+const SQUASH_DELAY_MS = 480;
+
+// Fraction along a card's top/bottom edge where each lane meets it.
+const laneFracs = (rect: { l: number; w: number }) =>
+	LANES.map((lx) => (lx - rect.l) / rect.w);
+
+export function TunnelOutbound(_props: DiagramFallbackProps) {
+	return (
+		<Diagram
+			label="cloudflared opens connections from a private network upward to Cloudflare; a request then travels back down through those connections. A request sent before the tunnel exists is refused at the network boundary. Operate it with the Enable tunnel and Send request controls."
+			keyboard={false}
+		>
+			<OutboundBody />
+		</Diagram>
+	);
+}
+
+function OutboundBody() {
+	const ctx = useDiagramOrDefault("TunnelOutbound");
+	const reduced = ctx.reducedMotion;
+	const [phase, setPhase] = useState<"idle" | "connecting" | "connected">(
+		"idle",
+	);
+	const [flow, setFlow] = useState<"none" | "in" | "back" | "refused">("none");
+	const connected = phase === "connected";
+
+	// Enabling the tunnel: settle into the connected state after the draw.
+	useEffect(() => {
+		if (phase !== "connecting") return;
+		const t = setTimeout(
+			() => setPhase("connected"),
+			reduced ? CONNECT_MS_REDUCED : CONNECT_MS,
+		);
+		return () => clearTimeout(t);
+	}, [phase, reduced]);
+
+	// A request advances one leg at a time (in → back → none); a refused
+	// request holds its outcome and then clears. Reduced motion still holds
+	// each outcome long enough to read.
+	useEffect(() => {
+		if (flow === "none") return;
+		const hold = reduced
+			? REDUCED_HOLD_MS
+			: flow === "refused"
+				? REFUSED_HOLD_MS
+				: FLOW_HOLD_MS;
+		const t = setTimeout(() => setFlow(flow === "in" ? "back" : "none"), hold);
+		return () => clearTimeout(t);
+	}, [flow, reduced]);
+
+	return (
+		<WeldCanvas
+			width={VIEW_W}
+			height={VIEW_H}
+			liveStatus={
+				flow === "refused"
+					? "The request was refused at the network boundary — nothing is listening."
+					: flow === "in"
+						? "A request travels down an established connection into the network."
+						: flow === "back"
+							? "The response returns to Cloudflare over the second connection."
+							: connected
+								? "cloudflared holds open connections to Cloudflare."
+								: "The private network has no inbound connections."
+			}
+			controls={
+				<Toolbar className="justify-end">
+					<div className="flex flex-col items-stretch gap-1">
+						<LabeledButton
+							ariaLabel="Enable the tunnel"
+							ariaDisabled={phase !== "idle"}
+							onClick={() => phase === "idle" && setPhase("connecting")}
+						>
+							{phase === "connecting" ? "Connecting…" : "Enable tunnel"}
+						</LabeledButton>
+						<LabeledButton
+							ariaLabel="Send a request"
+							onClick={() =>
+								flow === "none" && setFlow(connected ? "in" : "refused")
+							}
+						>
+							Send request
+						</LabeledButton>
+					</div>
+				</Toolbar>
+			}
+		>
+			<NetBoundary rect={FIELD} label="Your network" />
+			<LabelCard
+				rect={DAEMON}
+				label="cloudflared"
+				fontSize={11}
+				active
+				notches={{ top: laneFracs(DAEMON) }}
+			/>
+			<LabelCard
+				rect={CF}
+				label="Cloudflare"
+				fontSize={11}
+				active={connected || flow === "refused"}
+				notches={{ bottom: laneFracs(CF) }}
+			/>
+
+			{/* Enabling: draw both connections upward out of cloudflared. */}
+			{!reduced &&
+				phase === "connecting" &&
+				LANES.map((lx, i) => (
+					<path
+						key={lx}
+						d={`M ${lx} ${DAEMON.t - 5} L ${lx} ${CF.b + 5}`}
+						fill="none"
+						strokeWidth={1.5}
+						pathLength={1}
+						strokeDasharray="1"
+						strokeDashoffset={1}
+						className="stroke-brand"
+						style={{
+							animation: `weld-draw 0.55s cubic-bezier(0.23, 1, 0.32, 1) ${i * 0.22}s forwards`,
+						}}
+					/>
+				))}
+			{/* Established: the two connections as static conductors. */}
+			{(connected || (reduced && phase !== "idle")) &&
+				LANES.map((lx) => (
+					<line
+						key={lx}
+						x1={lx}
+						y1={CF.b + 5}
+						x2={lx}
+						y2={DAEMON.t - 5}
+						strokeWidth={1.25}
+						className="stroke-neutral-300 dark:stroke-neutral-700"
+					/>
+				))}
+			{/* Ports at both ends, taken once connected. */}
+			{phase !== "idle" &&
+				LANES.map((lx) => (
+					<g key={`ports-${lx}`}>
+						<Port cx={lx} cy={CF.b} taken={connected} />
+						<Port cx={lx} cy={DAEMON.t} taken={connected} />
+					</g>
+				))}
+
+			{/* Refused: a pour descends from Cloudflare and squashes against
+			    the port-less boundary once it arrives. */}
+			{!reduced && flow === "refused" && (
+				<g>
+					<Pour d={`M ${CX} ${CF.b} L ${CX} ${FIELD.t - 6}`} dur={0.55} />
+					<DelayedSquash x={CX} y={FIELD.t - 6} delayMs={SQUASH_DELAY_MS} />
+				</g>
+			)}
+			{/* Request in, down the first connection. */}
+			{!reduced && flow === "in" && (
+				<Pour d={`M ${LANES[0]} ${CF.b} L ${LANES[0]} ${DAEMON.t}`} dur={0.6} />
+			)}
+			{/* Response out, up the second. */}
+			{!reduced && flow === "back" && (
+				<Pour d={`M ${LANES[1]} ${DAEMON.t} L ${LANES[1]} ${CF.b}`} dur={0.6} />
+			)}
+			{/* Reduced motion: the same outcomes, held statically. */}
+			{reduced && flow === "refused" && (
+				<rect
+					x={CX - 5}
+					y={FIELD.t - 8}
+					width={10}
+					height={3}
+					rx={1}
+					className="fill-brand"
+				/>
+			)}
+			{reduced && (flow === "in" || flow === "back") && (
+				<line
+					x1={LANES[flow === "in" ? 0 : 1]}
+					y1={CF.b}
+					x2={LANES[flow === "in" ? 0 : 1]}
+					y2={DAEMON.t}
+					strokeWidth={1.5}
+					strokeLinecap="round"
+					className="stroke-brand"
+				/>
+			)}
+		</WeldCanvas>
+	);
+}
+
+/** Squash that waits for the pour to arrive before flattening. */
+function DelayedSquash({
+	x,
+	y,
+	delayMs,
+}: {
+	x: number;
+	y: number;
+	delayMs: number;
+}) {
+	const [show, setShow] = useState(false);
+	useEffect(() => {
+		const t = setTimeout(() => setShow(true), delayMs);
+		return () => clearTimeout(t);
+	}, [delayMs]);
+	return show ? <Squash x={x} y={y} /> : null;
+}
+
+export default TunnelOutbound;
diff --git a/src/components/react/tunnel/TunnelTraffic.tsx b/src/components/react/tunnel/TunnelTraffic.tsx
new file mode 100644
index 00000000000..adbf18e324c
--- /dev/null
+++ b/src/components/react/tunnel/TunnelTraffic.tsx
@@ -0,0 +1,312 @@
+"use client";
+
+// Figure 3 on the Tunnel concepts page: one vertical path from a user down
+// into a private network, assembled from named parts. "Connect hostname"
+// seats the app.example.com route inside Cloudflare; "Enable tunnel" drops
+// the tunnel card (with its two ports) into the gap between the networks.
+// "Send request" reveals whichever part is still missing — no route and the
+// request sparks out at the user's doorstep; routed but with no tunnel and
+// it is refused at Cloudflare's edge. With both parts in place, the request
+// pours the whole way through to the web service.
+import { useEffect, useRef, useState } from "react";
+import { Diagram, useDiagramOrDefault } from "@cloudflare/nimbus-docs/react";
+import { LabelCard, makeRect } from "../diagram-weld";
+import { WeldCanvas, weldEnter } from "../container/WeldCanvas";
+import { LabeledButton } from "../container/Transport";
+import type { DiagramFallbackProps } from "../container/DiagramFallback";
+import { NetBoundary, Port, Pour, Sparks, Squash } from "./TunnelKit";
+
+// Layout, in SVG user units. Everything shares one vertical spine, below
+// the overlaid button stack so nothing collides.
+const VIEW_W = 340;
+const VIEW_H = 492;
+const CX = 170;
+const USER = makeRect(136, 102, 68, 32);
+const CF_REGION = makeRect(78, 150, 184, 76);
+const HOST = makeRect(110, 180, 120, 26);
+const CHIP = makeRect(122, 252, 96, 44);
+const FIELD = makeRect(60, 328, 220, 150);
+const DAEMON = makeRect(110, 356, 120, 40);
+const RES = makeRect(110, 430, 120, 34);
+
+// Timing (ms).
+const TUNNEL_UP_MS = 700;
+const TUNNEL_UP_MS_REDUCED = 60;
+// Per-stage durations: [request travels, outcome shows, clear].
+const STAGE_MS_REDUCED = [60, 1100, 400];
+const STAGE_MS_OK = [1250, 700, 450];
+const STAGE_MS_FAIL = [650, 550, 350];
+
+export function TunnelTraffic(_props: DiagramFallbackProps) {
+	return (
+		<Diagram
+			label="One vertical path from a user into your network. Connect the public hostname and enable the tunnel to complete it; a request sent before either part exists fails at the missing layer, and a completed path delivers the request to the web service. Operate it with the Enable tunnel, Connect hostname, and Send request controls."
+			keyboard={false}
+		>
+			<TrafficBody />
+		</Diagram>
+	);
+}
+
+type Outcome = "no-route" | "no-tunnel" | "ok";
+
+function TrafficBody() {
+	const ctx = useDiagramOrDefault("TunnelTraffic");
+	const reduced = ctx.reducedMotion;
+	const [tunnel, setTunnel] = useState<"none" | "connecting" | "up">("none");
+	const [route, setRoute] = useState(false);
+	const [req, setReq] = useState<{ kind: Outcome; n: number } | null>(null);
+	const [stage, setStage] = useState(0);
+	const reqSeq = useRef(0);
+
+	// Enabling the tunnel settles to "up" after a short connect delay.
+	useEffect(() => {
+		if (tunnel !== "connecting") return;
+		const t = setTimeout(
+			() => setTunnel("up"),
+			reduced ? TUNNEL_UP_MS_REDUCED : TUNNEL_UP_MS,
+		);
+		return () => clearTimeout(t);
+	}, [tunnel, reduced]);
+
+	// A request steps through its stages, then clears itself. Reduced motion
+	// skips the travel stage but still holds the outcome.
+	useEffect(() => {
+		if (!req) return;
+		const durs = reduced
+			? STAGE_MS_REDUCED
+			: req.kind === "ok"
+				? STAGE_MS_OK
+				: STAGE_MS_FAIL;
+		if (stage < durs.length) {
+			const t = setTimeout(() => {
+				if (stage === durs.length - 1) {
+					setReq(null);
+					setStage(0);
+				} else setStage(stage + 1);
+			}, durs[stage]);
+			return () => clearTimeout(t);
+		}
+	}, [req, stage, reduced]);
+
+	// The outcome is decided the moment a request is sent: a missing route
+	// fails first, then a missing tunnel, otherwise it is delivered.
+	const send = () => {
+		if (req) return;
+		setStage(0);
+		reqSeq.current += 1;
+		setReq({
+			kind: !route ? "no-route" : tunnel !== "up" ? "no-tunnel" : "ok",
+			n: reqSeq.current,
+		});
+	};
+
+	const kind = req?.kind;
+	const delivering = kind === "ok";
+	const inPour: Record<Outcome, string> = {
+		"no-route": `M ${CX} ${USER.b} L ${CX} ${USER.b + 14}`,
+		"no-tunnel": `M ${CX} ${USER.b} L ${CX} ${CF_REGION.b - 6}`,
+		ok: `M ${CX} ${USER.b} L ${CX} ${DAEMON.t}`,
+	};
+	return (
+		<WeldCanvas
+			width={VIEW_W}
+			height={VIEW_H}
+			liveStatus={
+				kind === "no-route"
+					? "The request failed immediately: no route exists."
+					: kind === "no-tunnel"
+						? "The request matched the route but found no tunnel connection at Cloudflare's edge."
+						: kind === "ok"
+							? "The request travelled the completed path to the web service."
+							: !route && tunnel !== "up"
+								? "No route or tunnel exists yet."
+								: !route
+									? "The tunnel is up; no route exists yet."
+									: tunnel !== "up"
+										? "The route is set; the tunnel is not enabled."
+										: "The path is complete."
+			}
+			overlay={
+				<div className="absolute top-1 right-1 flex flex-col items-stretch gap-1">
+					<LabeledButton
+						ariaLabel="Enable the tunnel"
+						ariaDisabled={tunnel !== "none"}
+						onClick={() => tunnel === "none" && setTunnel("connecting")}
+					>
+						{tunnel === "connecting" ? "Connecting…" : "Enable tunnel"}
+					</LabeledButton>
+					<LabeledButton
+						ariaLabel="Connect the public hostname"
+						ariaDisabled={route}
+						onClick={() => !route && setRoute(true)}
+					>
+						Connect hostname
+					</LabeledButton>
+					<LabeledButton ariaLabel="Send a request" onClick={send}>
+						Send request
+					</LabeledButton>
+				</div>
+			}
+		>
+			<NetBoundary rect={CF_REGION} label="Cloudflare" />
+			<NetBoundary rect={FIELD} label="Your network" />
+			{/* Local wiring: cloudflared to the service it reaches. */}
+			<line
+				x1={CX}
+				y1={DAEMON.b}
+				x2={CX}
+				y2={RES.t}
+				strokeWidth={1.25}
+				className="stroke-neutral-300 dark:stroke-neutral-700"
+			/>
+			{/* The request pour, beneath the installed parts. */}
+			{req && stage === 0 && !reduced && (
+				<Pour
+					key={`p-${req.n}`}
+					d={inPour[req.kind]}
+					dur={kind === "no-route" ? 0.35 : kind === "no-tunnel" ? 0.6 : 1.05}
+				/>
+			)}
+			{req && kind === "no-route" && stage === 1 && !reduced && (
+				<Sparks x={CX} y={USER.b + 12} />
+			)}
+			{req && kind === "no-tunnel" && stage === 1 && !reduced && (
+				<Squash x={CX} y={CF_REGION.b - 6} />
+			)}
+			{req && delivering && stage >= 1 && !reduced && (
+				<Pour
+					key={`o-${req.n}`}
+					d={`M ${CX} ${DAEMON.b} L ${CX} ${RES.t}`}
+					dur={0.5}
+				/>
+			)}
+			{/* Reduced motion: the same outcomes, held statically. */}
+			{reduced && req && stage >= 1 && kind === "no-route" && (
+				<rect
+					x={CX - 5}
+					y={USER.b + 10}
+					width={10}
+					height={3}
+					rx={1}
+					className="fill-brand"
+				/>
+			)}
+			{reduced && req && stage >= 1 && kind === "no-tunnel" && (
+				<rect
+					x={CX - 5}
+					y={CF_REGION.b - 9}
+					width={10}
+					height={3}
+					rx={1}
+					className="fill-brand"
+				/>
+			)}
+			{reduced && delivering && stage >= 1 && (
+				<g>
+					<line
+						x1={CX}
+						y1={USER.b}
+						x2={CX}
+						y2={DAEMON.t}
+						strokeWidth={1.5}
+						strokeLinecap="round"
+						className="stroke-brand"
+					/>
+					<line
+						x1={CX}
+						y1={DAEMON.b}
+						x2={CX}
+						y2={RES.t}
+						strokeWidth={1.5}
+						strokeLinecap="round"
+						className="stroke-brand"
+					/>
+				</g>
+			)}
+			{/* The caller. */}
+			<LabelCard
+				rect={USER}
+				label="User"
+				fontSize={11}
+				notches={{ bottom: true }}
+				active={req !== null}
+			/>
+			{/* The route: absent until the hostname is connected. */}
+			{route && (
+				<g style={{ animation: weldEnter(reduced) }}>
+					<line
+						x1={CX}
+						y1={USER.b}
+						x2={CX}
+						y2={HOST.t}
+						strokeWidth={1.25}
+						className="stroke-neutral-300 dark:stroke-neutral-700"
+					/>
+					<line
+						x1={CX}
+						y1={HOST.b}
+						x2={CX}
+						y2={CF_REGION.b}
+						strokeWidth={1.25}
+						className="stroke-neutral-300 dark:stroke-neutral-700"
+					/>
+					<LabelCard
+						rect={HOST}
+						label="app.example.com"
+						fontSize={9}
+						rx={HOST.h / 2 - 3}
+						notches={{ top: true, bottom: true }}
+					/>
+				</g>
+			)}
+			{/* The tunnel: card, ports and conductors arrive together and
+			    bridge the gap between the two networks. */}
+			{tunnel !== "none" && (
+				<g style={{ animation: weldEnter(reduced) }}>
+					<line
+						x1={CX}
+						y1={CF_REGION.b}
+						x2={CX}
+						y2={CHIP.t - 5}
+						strokeWidth={1.25}
+						className="stroke-neutral-300 dark:stroke-neutral-700"
+					/>
+					<line
+						x1={CX}
+						y1={CHIP.b + 5}
+						x2={CX}
+						y2={DAEMON.t}
+						strokeWidth={1.25}
+						className="stroke-neutral-300 dark:stroke-neutral-700"
+					/>
+					<LabelCard
+						rect={CHIP}
+						label="Tunnel"
+						fontSize={11}
+						active={tunnel === "up"}
+					/>
+					<Port cx={CX} cy={CHIP.t} taken={tunnel === "up"} />
+					<Port cx={CX} cy={CHIP.b} taken={tunnel === "up"} />
+				</g>
+			)}
+			{/* Inside the network. */}
+			<LabelCard
+				rect={DAEMON}
+				label="cloudflared"
+				fontSize={11}
+				notches={{ top: true, bottom: true }}
+				active={delivering && stage >= 1}
+			/>
+			<LabelCard
+				rect={RES}
+				label="Web service"
+				fontSize={11}
+				notches={{ top: true }}
+				active={delivering && (reduced ? stage >= 1 : stage >= 2)}
+			/>
+		</WeldCanvas>
+	);
+}
+
+export default TunnelTraffic;
diff --git a/src/content/docs/tunnel/concepts/index.mdx b/src/content/docs/tunnel/concepts/index.mdx
index fa4c44d52dc..f403d5dad6e 100644
--- a/src/content/docs/tunnel/concepts/index.mdx
+++ b/src/content/docs/tunnel/concepts/index.mdx
@@ -1,15 +1,106 @@
 ---
-pcx_content_type: navigation
-title: Concepts
-description: Understand how Cloudflare Tunnel routes traffic to applications and origins.
+title: Tunnel fundamentals
+description: Understand what Cloudflare Tunnel is, how it connects private resources to Cloudflare, how routes work, and how to get started.
+pcx_content_type: overview
 products:
   - tunnel
 sidebar:
   order: 3
   group:
-    hideIndex: true
+    label: Concepts
 ---
 
-import { DirectoryListing } from "~/components";
+import {
+	CardGrid,
+	LinkCard,
+	TunnelOutbound,
+	TunnelIdentity,
+	TunnelTraffic,
+} from "~/components";
 
-<DirectoryListing />
+Cloudflare Tunnel creates a secure, outbound-only link between your infrastructure and Cloudflare's network, and gives that link a stable identity inside your Cloudflare account.
+
+Because a tunnel's connections open from within your network and stay held open to Cloudflare, the resources behind it need no public IP address and no inbound ports left open. Traffic reaches those resources over the tunnel instead of across the public Internet.
+
+## The connection starts with `cloudflared`
+
+_Reach Cloudflare by connecting outward, so your resources stay private._
+
+`cloudflared` is the daemon that opens and maintains a tunnel's connections to Cloudflare. It dials out from inside your network, which lets requests and responses move in both directions without your origin ever exposing a public address.
+
+That inversion is the heart of how Tunnel works: instead of Cloudflare reaching in to a public address on your server, `cloudflared` reaches out to Cloudflare first, and Cloudflare then routes traffic back down those already-open connections to your resources.
+
+<TunnelOutbound client:visible>
+
+`cloudflared` opens connections outward from a private network to Cloudflare, and traffic reaches your resources back through them. A request sent before the tunnel exists is turned away at the network boundary, because nothing inside is listening for inbound connections.
+
+</TunnelOutbound>
+
+For more information, refer to [Configuration](/tunnel/configuration/).
+
+## Tunnel identity and connectors
+
+_Separate the tunnel you configure from the software that runs it._
+
+Creating a tunnel assigns it a unique ID — the `#123` shown in the figure below, for example. Routes and other Cloudflare services refer to the tunnel by this ID.
+
+A connector is a single running instance of `cloudflared`, and each one holds several connections open to Cloudflare. Because every connector reports the same tunnel ID, you can add connectors to scale a tunnel without touching its routes. Additional connectors are called replicas and usually run on separate hosts, so if one connector drops out, Cloudflare can route new traffic through another.
+
+<TunnelIdentity client:visible>
+
+Two `cloudflared` connectors stand behind a single, stable tunnel identity, so traffic keeps flowing when one of them stops. Stop connector B and every new request travels through connector A, while the tunnel ID and its routes stay unchanged.
+
+</TunnelIdentity>
+
+For more information, refer to [Replicas and high availability](/tunnel/configuration/#replicas-and-high-availability) and [Load balancing](/tunnel/concepts/routing/#load-balancing).
+
+## How traffic reaches a resource
+
+_Route traffic to your resources through the tunnel._
+
+An open tunnel does not, on its own, make any resource reachable. What reaches a resource is decided by routing configuration: which traffic should travel over the tunnel, and which resource each request is bound for.
+
+- **Published applications** map public hostnames (for example, `app.example.com`) to services sitting behind the tunnel.
+- **Private network routes** send traffic for private hostnames, IP addresses, or network ranges through the tunnel.
+- **Workers VPC** gives Workers a path to private services through the tunnel.
+
+A single tunnel can serve many resources at once, and those resources can use different kinds of routing. Whenever traffic matches the routing configuration, Cloudflare hands it to an available tunnel connection; `cloudflared` picks it up on the other side and delivers it to a resource it can reach inside your network.
+
+Connectivity and access are separate concerns: the tunnel carries traffic, while access to each resource is governed on its own.
+
+<TunnelTraffic client:visible>
+
+Routing configuration hands traffic to an available tunnel connection and on to `cloudflared`, which delivers it to a resource it can reach. A request with no matching route fails at once, and a routed request with no tunnel fails at Cloudflare's edge, because both the route and the tunnel have to be in place.
+
+</TunnelTraffic>
+
+For more information, refer to [Routing](/tunnel/concepts/routing/), [Private networks](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/), and [Workers VPC](/workers-vpc/configuration/tunnel/).
+
+## Start building
+
+Pick the path that matches how you want to use the tunnel.
+
+<CardGrid>
+	<LinkCard
+		title="Publish an application"
+		href="/tunnel/get-started/"
+		description="Expose a service in your network at a public hostname."
+	/>
+	<LinkCard
+		title="Connect a private network"
+		href="/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/"
+		description="Route traffic from enrolled devices to private resources."
+	/>
+	<LinkCard
+		title="Connect Workers VPC"
+		href="/workers-vpc/get-started/"
+		description="Give Workers access to services in a private network."
+	/>
+</CardGrid>
+
+## Related resources
+
+- [Configuration](/tunnel/configuration/): replicas, firewall rules, and connection settings.
+- [Routing](/tunnel/concepts/routing/): public hostnames, protocols, and load balancing.
+- [Observability](/tunnel/observability/): tunnel status, logs, metrics, and notifications.
+- [Troubleshooting](/tunnel/troubleshooting/): diagnosing failures along the request path.
diff --git a/src/styles/globals.css b/src/styles/globals.css
index 216c23f4386..2f2e490eeb1 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -297,6 +297,52 @@
 	}
 }
 
+/* Tunnel concept diagrams: a request "pour" draws itself along a path
+ * (pathLength=1 + unit dash), holds, then fades out. */
+@keyframes weld-draw {
+	from {
+		stroke-dashoffset: 1;
+	}
+	to {
+		stroke-dashoffset: 0;
+	}
+}
+@keyframes weld-pour-fade {
+	0%,
+	72% {
+		opacity: 1;
+	}
+	100% {
+		opacity: 0;
+	}
+}
+/* A refused request flattens against a boundary, then fades out. */
+@keyframes weld-squash {
+	0% {
+		opacity: 1;
+		transform: scale(1, 1);
+	}
+	55% {
+		opacity: 1;
+		transform: scale(1.6, 0.3);
+	}
+	100% {
+		opacity: 0;
+		transform: scale(1.6, 0.3);
+	}
+}
+/* Sparks: small marks that drift up and outward, then fade. */
+@keyframes weld-spark {
+	from {
+		opacity: 1;
+		transform: translate(0, 0) scale(1);
+	}
+	to {
+		opacity: 0;
+		transform: translate(var(--spark-x, 0px), var(--spark-y, -12px)) scale(0.4);
+	}
+}
+
 @keyframes weld-compute-pulse {
 	0%,
 	100% {

From ac18dbb1b45913b520b2d48ecce35747ab28fb4c Mon Sep 17 00:00:00 2001
From: mohamedh <mhassan@cloudflare.com>
Date: Fri, 18 Sep 2026 16:57:55 +0100
Subject: [PATCH 2/4] chore: copy update

---
 src/components/react/tunnel/TunnelTraffic.tsx | 63 ++++++++++---------
 src/content/docs/tunnel/concepts/index.mdx    | 38 +++++------
 2 files changed, 52 insertions(+), 49 deletions(-)

diff --git a/src/components/react/tunnel/TunnelTraffic.tsx b/src/components/react/tunnel/TunnelTraffic.tsx
index adbf18e324c..98ec5732add 100644
--- a/src/components/react/tunnel/TunnelTraffic.tsx
+++ b/src/components/react/tunnel/TunnelTraffic.tsx
@@ -12,22 +12,21 @@ import { useEffect, useRef, useState } from "react";
 import { Diagram, useDiagramOrDefault } from "@cloudflare/nimbus-docs/react";
 import { LabelCard, makeRect } from "../diagram-weld";
 import { WeldCanvas, weldEnter } from "../container/WeldCanvas";
-import { LabeledButton } from "../container/Transport";
+import { LabeledButton, Toolbar } from "../container/Transport";
 import type { DiagramFallbackProps } from "../container/DiagramFallback";
 import { NetBoundary, Port, Pour, Sparks, Squash } from "./TunnelKit";
 
-// Layout, in SVG user units. Everything shares one vertical spine, below
-// the overlaid button stack so nothing collides.
+// Layout, in SVG user units. Everything shares one vertical spine.
 const VIEW_W = 340;
-const VIEW_H = 492;
+const VIEW_H = 394;
 const CX = 170;
-const USER = makeRect(136, 102, 68, 32);
-const CF_REGION = makeRect(78, 150, 184, 76);
-const HOST = makeRect(110, 180, 120, 26);
-const CHIP = makeRect(122, 252, 96, 44);
-const FIELD = makeRect(60, 328, 220, 150);
-const DAEMON = makeRect(110, 356, 120, 40);
-const RES = makeRect(110, 430, 120, 34);
+const USER = makeRect(136, 4, 68, 32);
+const CF_REGION = makeRect(78, 52, 184, 76);
+const HOST = makeRect(110, 82, 120, 26);
+const CHIP = makeRect(122, 154, 96, 44);
+const FIELD = makeRect(60, 230, 220, 150);
+const DAEMON = makeRect(110, 258, 120, 40);
+const RES = makeRect(110, 332, 120, 34);
 
 // Timing (ms).
 const TUNNEL_UP_MS = 700;
@@ -127,26 +126,28 @@ function TrafficBody() {
 										? "The route is set; the tunnel is not enabled."
 										: "The path is complete."
 			}
-			overlay={
-				<div className="absolute top-1 right-1 flex flex-col items-stretch gap-1">
-					<LabeledButton
-						ariaLabel="Enable the tunnel"
-						ariaDisabled={tunnel !== "none"}
-						onClick={() => tunnel === "none" && setTunnel("connecting")}
-					>
-						{tunnel === "connecting" ? "Connecting…" : "Enable tunnel"}
-					</LabeledButton>
-					<LabeledButton
-						ariaLabel="Connect the public hostname"
-						ariaDisabled={route}
-						onClick={() => !route && setRoute(true)}
-					>
-						Connect hostname
-					</LabeledButton>
-					<LabeledButton ariaLabel="Send a request" onClick={send}>
-						Send request
-					</LabeledButton>
-				</div>
+			controls={
+				<Toolbar className="justify-end">
+					<div className="flex flex-col items-stretch gap-1">
+						<LabeledButton
+							ariaLabel="Enable the tunnel"
+							ariaDisabled={tunnel !== "none"}
+							onClick={() => tunnel === "none" && setTunnel("connecting")}
+						>
+							{tunnel === "connecting" ? "Connecting…" : "Enable tunnel"}
+						</LabeledButton>
+						<LabeledButton
+							ariaLabel="Connect the public hostname"
+							ariaDisabled={route}
+							onClick={() => !route && setRoute(true)}
+						>
+							Connect hostname
+						</LabeledButton>
+						<LabeledButton ariaLabel="Send a request" onClick={send}>
+							Send request
+						</LabeledButton>
+					</div>
+				</Toolbar>
 			}
 		>
 			<NetBoundary rect={CF_REGION} label="Cloudflare" />
diff --git a/src/content/docs/tunnel/concepts/index.mdx b/src/content/docs/tunnel/concepts/index.mdx
index f403d5dad6e..e28c00f5dfe 100644
--- a/src/content/docs/tunnel/concepts/index.mdx
+++ b/src/content/docs/tunnel/concepts/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Tunnel fundamentals
-description: Understand what Cloudflare Tunnel is, how it connects private resources to Cloudflare, how routes work, and how to get started.
+description: Learn how Cloudflare Tunnel connects private resources to Cloudflare, how routes direct traffic, and how to get started.
 pcx_content_type: overview
 products:
   - tunnel
@@ -18,21 +18,21 @@ import {
 	TunnelTraffic,
 } from "~/components";
 
-Cloudflare Tunnel creates a secure, outbound-only link between your infrastructure and Cloudflare's network, and gives that link a stable identity inside your Cloudflare account.
+Cloudflare Tunnel creates a secure, outbound-only connection between your infrastructure and Cloudflare's network, and gives that connection a stable identity within your account.
 
-Because a tunnel's connections open from within your network and stay held open to Cloudflare, the resources behind it need no public IP address and no inbound ports left open. Traffic reaches those resources over the tunnel instead of across the public Internet.
+Each connection originates inside your network and remains open to Cloudflare, so resources behind the tunnel need neither public IP addresses nor open inbound ports. Traffic reaches them through the tunnel rather than over the public Internet.
 
 ## The connection starts with `cloudflared`
 
-_Reach Cloudflare by connecting outward, so your resources stay private._
+_Keep your resources private by connecting outward to Cloudflare._
 
-`cloudflared` is the daemon that opens and maintains a tunnel's connections to Cloudflare. It dials out from inside your network, which lets requests and responses move in both directions without your origin ever exposing a public address.
+`cloudflared` is the daemon that establishes and maintains a tunnel's connections to Cloudflare. It runs inside your network and connects outward, allowing requests and responses to flow without exposing your origin at a public address.
 
-That inversion is the heart of how Tunnel works: instead of Cloudflare reaching in to a public address on your server, `cloudflared` reaches out to Cloudflare first, and Cloudflare then routes traffic back down those already-open connections to your resources.
+In a traditional setup, Cloudflare connects to a public address on your server. Cloudflare Tunnel reverses that model: `cloudflared` connects to Cloudflare first, and Cloudflare sends traffic to your resources over those established connections.
 
 <TunnelOutbound client:visible>
 
-`cloudflared` opens connections outward from a private network to Cloudflare, and traffic reaches your resources back through them. A request sent before the tunnel exists is turned away at the network boundary, because nothing inside is listening for inbound connections.
+`cloudflared` establishes outbound connections from a private network to Cloudflare, which can then send traffic through those connections to your resources. Before the tunnel exists, requests stop at the network boundary because nothing accepts inbound connections.
 
 </TunnelOutbound>
 
@@ -42,13 +42,15 @@ For more information, refer to [Configuration](/tunnel/configuration/).
 
 _Separate the tunnel you configure from the software that runs it._
 
-Creating a tunnel assigns it a unique ID — the `#123` shown in the figure below, for example. Routes and other Cloudflare services refer to the tunnel by this ID.
+When you create a tunnel, Cloudflare assigns it a unique ID, such as `#123` in the diagram. Routes and other Cloudflare services use this ID to identify the tunnel.
 
-A connector is a single running instance of `cloudflared`, and each one holds several connections open to Cloudflare. Because every connector reports the same tunnel ID, you can add connectors to scale a tunnel without touching its routes. Additional connectors are called replicas and usually run on separate hosts, so if one connector drops out, Cloudflare can route new traffic through another.
+A connector is a running instance of `cloudflared`, and each connector maintains several connections to Cloudflare. Every connector for a tunnel reports the same tunnel ID, so you can add connectors and scale the tunnel without changing its routes.
+
+Additional connectors are called replicas and usually run on separate hosts. If one connector becomes unavailable, Cloudflare can route new traffic through another.
 
 <TunnelIdentity client:visible>
 
-Two `cloudflared` connectors stand behind a single, stable tunnel identity, so traffic keeps flowing when one of them stops. Stop connector B and every new request travels through connector A, while the tunnel ID and its routes stay unchanged.
+Two `cloudflared` connectors share one stable tunnel identity. If connector B stops, new requests travel through connector A while the tunnel ID and its routes remain unchanged.
 
 </TunnelIdentity>
 
@@ -56,21 +58,21 @@ For more information, refer to [Replicas and high availability](/tunnel/configur
 
 ## How traffic reaches a resource
 
-_Route traffic to your resources through the tunnel._
+_Use routes to send traffic through the tunnel to your resources._
 
-An open tunnel does not, on its own, make any resource reachable. What reaches a resource is decided by routing configuration: which traffic should travel over the tunnel, and which resource each request is bound for.
+Opening a tunnel does not, by itself, make resources reachable. Routing configuration determines which traffic enters the tunnel and where each request goes.
 
-- **Published applications** map public hostnames (for example, `app.example.com`) to services sitting behind the tunnel.
+- **Published applications** map public hostnames (for example, `app.example.com`) to services behind the tunnel.
 - **Private network routes** send traffic for private hostnames, IP addresses, or network ranges through the tunnel.
-- **Workers VPC** gives Workers a path to private services through the tunnel.
+- **Workers VPC** provides Workers with a path to private services through the tunnel.
 
-A single tunnel can serve many resources at once, and those resources can use different kinds of routing. Whenever traffic matches the routing configuration, Cloudflare hands it to an available tunnel connection; `cloudflared` picks it up on the other side and delivers it to a resource it can reach inside your network.
+One tunnel can serve many resources through different types of routes. When traffic matches a route, Cloudflare sends it through an available tunnel connection, and `cloudflared` delivers it to a resource it can reach inside your network.
 
-Connectivity and access are separate concerns: the tunnel carries traffic, while access to each resource is governed on its own.
+The tunnel provides connectivity, while you manage access separately for each resource.
 
 <TunnelTraffic client:visible>
 
-Routing configuration hands traffic to an available tunnel connection and on to `cloudflared`, which delivers it to a resource it can reach. A request with no matching route fails at once, and a routed request with no tunnel fails at Cloudflare's edge, because both the route and the tunnel have to be in place.
+Routing configuration sends matching traffic through an available tunnel connection to `cloudflared`, which delivers it to a reachable resource. A request without a matching route fails immediately, while a request with a route but no available tunnel fails at Cloudflare's edge. For traffic to reach a resource, both the route and tunnel must be in place.
 
 </TunnelTraffic>
 
@@ -78,7 +80,7 @@ For more information, refer to [Routing](/tunnel/concepts/routing/), [Private ne
 
 ## Start building
 
-Pick the path that matches how you want to use the tunnel.
+Choose how you want to use the tunnel.
 
 <CardGrid>
 	<LinkCard

From 8922ef092e9fb77be519d42b4983c4b9b451bc0b Mon Sep 17 00:00:00 2001
From: Mohamed Hassan <mohamedahassan1998@gmail.com>
Date: Wed, 23 Sep 2026 13:59:27 +0100
Subject: [PATCH 3/4] chore: update copy

---
 src/components.ts                             |   1 +
 .../react/tunnel/TunnelQuickNested.tsx        | 241 ++++++++++++++++++
 src/content/docs/tunnel/concepts/index.mdx    |  76 ++++--
 3 files changed, 293 insertions(+), 25 deletions(-)
 create mode 100644 src/components/react/tunnel/TunnelQuickNested.tsx

diff --git a/src/components.ts b/src/components.ts
index ef8ae6e29c6..45b0d980cea 100644
--- a/src/components.ts
+++ b/src/components.ts
@@ -86,4 +86,5 @@ export { ContainerLifecycle } from "./components/react/container/ContainerLifecy
 export { ContainerPlacement } from "./components/react/container/ContainerPlacement";
 export { TunnelOutbound } from "./components/react/tunnel/TunnelOutbound";
 export { TunnelIdentity } from "./components/react/tunnel/TunnelIdentity";
+export { TunnelQuickNested } from "./components/react/tunnel/TunnelQuickNested";
 export { TunnelTraffic } from "./components/react/tunnel/TunnelTraffic";
diff --git a/src/components/react/tunnel/TunnelQuickNested.tsx b/src/components/react/tunnel/TunnelQuickNested.tsx
new file mode 100644
index 00000000000..a54c62c3f17
--- /dev/null
+++ b/src/components/react/tunnel/TunnelQuickNested.tsx
@@ -0,0 +1,241 @@
+"use client";
+
+// Variant of the Quick tunnels figure using two nested zones instead of a
+// three-band stack. Everything Cloudflare owns sits inside one "Cloudflare"
+// boundary; inside that, a "your account" sub-box is the durable store. A named
+// tunnel keeps its identity as a record in the account; a quick tunnel keeps the
+// account empty and its address floats in the Cloudflare zone, held up only by
+// the live connection down to cloudflared in "Your network". The Quick tunnel
+// toggle empties the account, and Stop cloudflared shows the consequence: the
+// named record survives in the account, the quick address does not.
+import { useRef, useState } from "react";
+import { Diagram, useDiagramOrDefault } from "@cloudflare/nimbus-docs/react";
+import { LabelCard, WeldedCard, makeRect } from "../diagram-weld";
+import { WeldCanvas, weldEnter } from "../container/WeldCanvas";
+import { LabeledButton, Toolbar } from "../container/Transport";
+import type { DiagramFallbackProps } from "../container/DiagramFallback";
+import { NetBoundary, Port } from "./TunnelKit";
+
+// Layout, in SVG user units. Two zones on the centre spine: Cloudflare (with a
+// nested account) above, your network below.
+const VIEW_W = 340;
+const VIEW_H = 346;
+const CX = 170; // centre spine
+const CF = makeRect(24, 16, 292, 166); // "Cloudflare" zone
+const ACCT = makeRect(50, 44, 240, 72); // "your account", nested inside CF
+const IDN = makeRect(72, 62, 196, 38); // the identity record (named)
+const ADDR = makeRect(46, 128, 248, 34); // quick address, floating in CF
+const FIELD = makeRect(24, 218, 292, 108); // "Your network" zone
+const DAEMON = makeRect(110, 258, 120, 42); // cloudflared connector
+
+// The addresses a quick tunnel is handed across runs — a fixed, deterministic
+// cycle (never Math.random) so SSR and client agree; only the change matters.
+const ADDRESSES = [
+	"blue-sky-1234",
+	"quiet-frog-8842",
+	"still-lake-0271",
+	"brave-moon-5390",
+	"warm-pine-6417",
+].map((w) => `${w}.trycloudflare.com`);
+
+const SPINE = [0.5]; // centre-edge notch fraction, shared by all cards
+
+export function TunnelQuickNested(_props: DiagramFallbackProps) {
+	return (
+		<Diagram
+			label="Everything Cloudflare owns sits in one Cloudflare zone; inside it, a your-account box is the durable store. A named tunnel keeps its identity as a record in the account, so stopping cloudflared leaves the record in place. A quick tunnel keeps the account empty — its trycloudflare.com address floats in the Cloudflare zone, held up only by the live connection to cloudflared in your network, so stopping cloudflared destroys it and the next run mints a different one. Operate it with the Quick tunnel toggle and the Run cloudflared control."
+			keyboard={false}
+		>
+			<NestedBody />
+		</Diagram>
+	);
+}
+
+function NestedBody() {
+	const ctx = useDiagramOrDefault("TunnelQuickNested");
+	const reduced = ctx.reducedMotion;
+	const [quick, setQuick] = useState(false);
+	const [connected, setConnected] = useState(true);
+	const [addrIndex, setAddrIndex] = useState(0);
+	const [drawKey, setDrawKey] = useState(0);
+	const address = ADDRESSES[addrIndex % ADDRESSES.length]!;
+
+	const connectedRef = useRef(connected);
+	connectedRef.current = connected;
+
+	// Bringing the connection up: replay the wire draw, and in quick mode mint a
+	// fresh address. Switching modes always comes up connected.
+	function bringUp(nextQuick: boolean) {
+		if (nextQuick) setAddrIndex((i) => i + 1);
+		setConnected(true);
+		setDrawKey((k) => k + 1);
+	}
+
+	function toggleMode() {
+		const next = !quick;
+		setQuick(next);
+		bringUp(next);
+	}
+
+	function toggleConnection() {
+		if (connectedRef.current) setConnected(false);
+		else bringUp(quick);
+	}
+
+	// Where the connection meets what it serves: the account record (named) or
+	// the floating address (quick).
+	const anchorY = quick ? ADDR.b : IDN.b;
+
+	const modeState = quick
+		? connected
+			? "Quick · live"
+			: "Quick · no address"
+		: connected
+			? "Named · live"
+			: "Named · idle (identity kept)";
+
+	return (
+		<WeldCanvas
+			width={VIEW_W}
+			height={VIEW_H}
+			liveStatus={
+				quick
+					? connected
+						? `Cloudflare minted ${address}. It floats in the Cloudflare zone, held up only by this connection — nothing is stored in your account.`
+						: "cloudflared has stopped. The address was held only by the connection, so it is gone; the next run mints a different one."
+					: connected
+						? "Tunnel #123 is a record in your account, bound to app.example.com. cloudflared holds the connection."
+						: "cloudflared has stopped, but Tunnel #123 and its route stay in your account. Reconnecting resolves the same hostname."
+			}
+			controls={
+				<Toolbar status={modeState}>
+					<LabeledButton
+						ariaLabel={
+							quick ? "Switch to a named tunnel" : "Switch to a quick tunnel"
+						}
+						onClick={toggleMode}
+					>
+						{quick ? "Named tunnel" : "Quick tunnel"}
+					</LabeledButton>
+					<LabeledButton
+						ariaLabel={connected ? "Stop cloudflared" : "Run cloudflared"}
+						onClick={toggleConnection}
+						highlight={!connected}
+					>
+						{connected ? "Stop cloudflared" : "Run cloudflared"}
+					</LabeledButton>
+				</Toolbar>
+			}
+		>
+			{/* Zone 1 — Cloudflare, holding the nested account. */}
+			<NetBoundary rect={CF} label="Cloudflare" />
+			<NetBoundary rect={ACCT} label="your account" />
+
+			{/* Named: an identity record lives in the account and persists across a
+			    stop. Quick: the account is empty. */}
+			{quick ? (
+				<text
+					x={CX}
+					y={ACCT.t + ACCT.h / 2 + 3}
+					textAnchor="middle"
+					className="fill-neutral-400 font-mono uppercase dark:fill-neutral-600"
+					style={{ fontSize: 9, letterSpacing: "0.12em" }}
+				>
+					no record
+				</text>
+			) : (
+				<g>
+					<WeldedCard rect={IDN} active notches={{ bottom: SPINE }} />
+					<text
+						x={CX}
+						y={IDN.t + 17}
+						textAnchor="middle"
+						className="fill-neutral-900 font-mono font-medium dark:fill-neutral-100"
+						style={{ fontSize: 11 }}
+					>
+						Tunnel #123
+					</text>
+					<text
+						x={CX}
+						y={IDN.t + 31}
+						textAnchor="middle"
+						className="fill-neutral-500 font-mono dark:fill-neutral-400"
+						style={{ fontSize: 9, letterSpacing: "0.04em" }}
+					>
+						app.example.com
+					</text>
+				</g>
+			)}
+
+			{/* Quick: the address floats in the Cloudflare zone, below the account,
+			    only while connected. Re-mounting per run replays the mint. */}
+			{quick && connected && (
+				<g key={addrIndex} style={{ animation: weldEnter(reduced) }}>
+					<LabelCard
+						rect={ADDR}
+						label={address}
+						fontSize={9}
+						active
+						notches={{ bottom: SPINE }}
+					/>
+				</g>
+			)}
+
+			{/* Zone 2 — your network, holding cloudflared. Drawn before the
+			    connection so the zone's fill does not paint over the wire. */}
+			<NetBoundary
+				rect={FIELD}
+				label={quick ? "Your machine" : "Your network"}
+			/>
+			<LabelCard
+				rect={DAEMON}
+				label="cloudflared"
+				fontSize={11}
+				active={connected}
+				notches={{ top: SPINE }}
+			/>
+
+			{/* The tunnel connection: cloudflared up to what it serves, only while
+			    connected. Drawn on top of both zones so it stays visible across
+			    their boundaries; the ports cap it. A brand pulse draws along it as
+			    it comes up, then the neutral conductor remains. */}
+			{connected && (
+				<>
+					<line
+						x1={CX}
+						y1={anchorY}
+						x2={CX}
+						y2={DAEMON.t}
+						strokeWidth={1.25}
+						className="stroke-neutral-300 dark:stroke-neutral-700"
+					/>
+					{!reduced && (
+						<path
+							key={drawKey}
+							d={`M ${CX} ${anchorY} L ${CX} ${DAEMON.t}`}
+							fill="none"
+							strokeWidth={1.5}
+							pathLength={1}
+							strokeDasharray="1"
+							strokeDashoffset={1}
+							className="stroke-brand"
+							style={{
+								animation:
+									"weld-draw 0.5s cubic-bezier(0.45,0,0.55,1) forwards, weld-pour-fade 1.1s linear forwards",
+							}}
+						/>
+					)}
+				</>
+			)}
+
+			{/* Ports at both ends of the connection, seated only while live. The
+			    top port only exists when a node is there to seat it: the account
+			    record (named) or, in quick mode, the address that appears only
+			    while connected — so a stopped quick tunnel leaves no orphan socket. */}
+			{(!quick || connected) && <Port cx={CX} cy={anchorY} taken={connected} />}
+			<Port cx={CX} cy={DAEMON.t} taken={connected} />
+		</WeldCanvas>
+	);
+}
+
+export default TunnelQuickNested;
diff --git a/src/content/docs/tunnel/concepts/index.mdx b/src/content/docs/tunnel/concepts/index.mdx
index e28c00f5dfe..828d9a099ef 100644
--- a/src/content/docs/tunnel/concepts/index.mdx
+++ b/src/content/docs/tunnel/concepts/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Tunnel fundamentals
-description: Learn how Cloudflare Tunnel connects private resources to Cloudflare, how routes direct traffic, and how to get started.
+description: Understand what Cloudflare Tunnel is, how it connects private resources to Cloudflare, how routes work, and how to get started.
 pcx_content_type: overview
 products:
   - tunnel
@@ -15,24 +15,25 @@ import {
 	LinkCard,
 	TunnelOutbound,
 	TunnelIdentity,
+	TunnelQuickNested,
 	TunnelTraffic,
 } from "~/components";
 
-Cloudflare Tunnel creates a secure, outbound-only connection between your infrastructure and Cloudflare's network, and gives that connection a stable identity within your account.
+A Cloudflare Tunnel is a secure link between Cloudflare's network and your infrastructure, with a stable identity in your Cloudflare account.
 
-Each connection originates inside your network and remains open to Cloudflare, so resources behind the tunnel need neither public IP addresses nor open inbound ports. Traffic reaches them through the tunnel rather than over the public Internet.
+Tunnel connections begin inside your network and remain open to Cloudflare, so the resources behind them do not need public IP addresses or open inbound ports. Traffic can reach those resources through the tunnel instead of connecting to them directly over the Internet.
 
 ## The connection starts with `cloudflared`
 
-_Keep your resources private by connecting outward to Cloudflare._
+_Connect out to Cloudflare while keeping your resources private._
 
-`cloudflared` is the daemon that establishes and maintains a tunnel's connections to Cloudflare. It runs inside your network and connects outward, allowing requests and responses to flow without exposing your origin at a public address.
+`cloudflared` is the daemon that establishes and maintains a tunnel's connections to Cloudflare. It initiates those connections from inside your network, allowing requests and responses to travel in both directions without requiring your origin to expose a public address.
 
-In a traditional setup, Cloudflare connects to a public address on your server. Cloudflare Tunnel reverses that model: `cloudflared` connects to Cloudflare first, and Cloudflare sends traffic to your resources over those established connections.
+This is the central idea behind Tunnel: Cloudflare does not connect to a public address on your server. `cloudflared` connects to Cloudflare first, and Cloudflare uses those existing connections to reach resources in your network.
 
 <TunnelOutbound client:visible>
 
-`cloudflared` establishes outbound connections from a private network to Cloudflare, which can then send traffic through those connections to your resources. Before the tunnel exists, requests stop at the network boundary because nothing accepts inbound connections.
+`cloudflared` opens connections from a private network to Cloudflare, allowing traffic to reach resources through those connections. A request sent before the tunnel exists is refused at the network boundary, because nothing inside accepts inbound connections.
 
 </TunnelOutbound>
 
@@ -40,39 +41,59 @@ For more information, refer to [Configuration](/tunnel/configuration/).
 
 ## Tunnel identity and connectors
 
-_Separate the tunnel you configure from the software that runs it._
+_Keep the tunnel you configure separate from the software that runs it._
 
-When you create a tunnel, Cloudflare assigns it a unique ID, such as `#123` in the diagram. Routes and other Cloudflare services use this ID to identify the tunnel.
+When you create a tunnel, Cloudflare gives it a unique ID, like the `#123` in the figure below. Routes and other Cloudflare services use this ID to identify the tunnel.
 
-A connector is a running instance of `cloudflared`, and each connector maintains several connections to Cloudflare. Every connector for a tunnel reports the same tunnel ID, so you can add connectors and scale the tunnel without changing its routes.
-
-Additional connectors are called replicas and usually run on separate hosts. If one connector becomes unavailable, Cloudflare can route new traffic through another.
+Each running instance of `cloudflared` is called a connector, and it maintains several network connections to Cloudflare. A tunnel can scale beyond a single connector without changing its routes because every connector shares the same tunnel ID. Each additional connector is called a replica and usually runs on a separate host. If one connector becomes unavailable, Cloudflare can send new traffic through another.
 
 <TunnelIdentity client:visible>
 
-Two `cloudflared` connectors share one stable tunnel identity. If connector B stops, new requests travel through connector A while the tunnel ID and its routes remain unchanged.
+Two `cloudflared` connectors share one stable tunnel identity, allowing traffic to continue when one connector stops. Stopping connector B sends every new request through connector A while the tunnel ID and its routes stay unchanged.
 
 </TunnelIdentity>
 
 For more information, refer to [Replicas and high availability](/tunnel/configuration/#replicas-and-high-availability) and [Load balancing](/tunnel/concepts/routing/#load-balancing).
 
+## Quick tunnels
+
+_Reach a local service without an account or configuration._
+
+The tunnels above are persistent: each has a stable ID and stays in your account until you delete it. A quick tunnel skips that identity. It runs from a single command:
+
+```sh
+cloudflared tunnel --url http://localhost:8080
+```
+
+Cloudflare assigns a random `trycloudflare.com` address that routes back through the tunnel to your service.
+
+The connection still starts from inside your network, so your machine stays private. What changes is permanence: a quick tunnel exists only while `cloudflared` runs, and its address is different each time. This makes quick tunnels useful for temporary work, such as sharing a development preview or receiving a webhook, and unsuited to production traffic or routes you intend to keep.
+
+<TunnelQuickNested client:visible>
+
+A named tunnel keeps its identity as a record in your Cloudflare account, so stopping `cloudflared` leaves that record in place. A quick tunnel keeps the account empty: its address floats in Cloudflare's network, held up only by the live connection, so stopping `cloudflared` destroys it and the next run mints a different one.
+
+</TunnelQuickNested>
+
+For more information, refer to [Quick tunnels](/tunnel/get-started/#quick-tunnels-development).
+
 ## How traffic reaches a resource
 
-_Use routes to send traffic through the tunnel to your resources._
+_Connect traffic to resources through the tunnel._
 
-Opening a tunnel does not, by itself, make resources reachable. Routing configuration determines which traffic enters the tunnel and where each request goes.
+A connected tunnel does not make a resource reachable on its own. Routing configuration determines which traffic uses the tunnel and which resource that traffic should reach.
 
-- **Published applications** map public hostnames (for example, `app.example.com`) to services behind the tunnel.
-- **Private network routes** send traffic for private hostnames, IP addresses, or network ranges through the tunnel.
-- **Workers VPC** provides Workers with a path to private services through the tunnel.
+- **Published applications** connect public hostnames (for example, `app.example.com`) to services behind the tunnel.
+- **Private network routes** direct traffic for private hostnames, IP addresses, or network ranges through the tunnel.
+- **Workers VPC** lets Workers reach private services through the tunnel.
 
-One tunnel can serve many resources through different types of routes. When traffic matches a route, Cloudflare sends it through an available tunnel connection, and `cloudflared` delivers it to a resource it can reach inside your network.
+One tunnel can carry traffic for multiple resources, even when those resources use different types of routing. When traffic matches the routing configuration, Cloudflare sends it over an available tunnel connection. `cloudflared` receives the traffic and forwards it to a resource it can reach in your network.
 
-The tunnel provides connectivity, while you manage access separately for each resource.
+The tunnel provides connectivity. Access to each resource is controlled separately.
 
 <TunnelTraffic client:visible>
 
-Routing configuration sends matching traffic through an available tunnel connection to `cloudflared`, which delivers it to a reachable resource. A request without a matching route fails immediately, while a request with a route but no available tunnel fails at Cloudflare's edge. For traffic to reach a resource, both the route and tunnel must be in place.
+Routing configuration sends traffic through an available tunnel connection to `cloudflared`, which forwards it to a reachable resource. A request with no route fails immediately, and a routed request with no tunnel fails at Cloudflare's edge, because both the route and the tunnel are required.
 
 </TunnelTraffic>
 
@@ -80,13 +101,13 @@ For more information, refer to [Routing](/tunnel/concepts/routing/), [Private ne
 
 ## Start building
 
-Choose how you want to use the tunnel.
+When you are ready to build, choose how you want to use the tunnel.
 
 <CardGrid>
 	<LinkCard
 		title="Publish an application"
 		href="/tunnel/get-started/"
-		description="Expose a service in your network at a public hostname."
+		description="Connect a public hostname to a service in your network."
 	/>
 	<LinkCard
 		title="Connect a private network"
@@ -96,7 +117,12 @@ Choose how you want to use the tunnel.
 	<LinkCard
 		title="Connect Workers VPC"
 		href="/workers-vpc/get-started/"
-		description="Give Workers access to services in a private network."
+		description="Let Workers call services in a private network."
+	/>
+	<LinkCard
+		title="Try a quick tunnel"
+		href="/tunnel/get-started/#quick-tunnels-development"
+		description="Share a local service from a single command, without an account or configuration."
 	/>
 </CardGrid>
 
@@ -105,4 +131,4 @@ Choose how you want to use the tunnel.
 - [Configuration](/tunnel/configuration/): replicas, firewall rules, and connection settings.
 - [Routing](/tunnel/concepts/routing/): public hostnames, protocols, and load balancing.
 - [Observability](/tunnel/observability/): tunnel status, logs, metrics, and notifications.
-- [Troubleshooting](/tunnel/troubleshooting/): diagnosing failures along the request path.
+- [Troubleshooting](/tunnel/troubleshooting/): failures across the request path.

From 287ea312f82c563a53709469811ad314abf105cd Mon Sep 17 00:00:00 2001
From: Mohamed Hassan <mohamedahassan1998@gmail.com>
Date: Wed, 23 Sep 2026 15:08:05 +0100
Subject: [PATCH 4/4] fix: build

---
 src/components.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/components.ts b/src/components.ts
index 8782c0af582..16d6828df12 100644
--- a/src/components.ts
+++ b/src/components.ts
@@ -62,7 +62,6 @@ export { default as WARPReleases } from "./components/cf/WARPReleases.astro";
 export { default as AutoconfigDiagram } from "./components/cf/AutoconfigDiagram.astro";
 export { default as ResourcesBySelector } from "./components/cf/ResourcesBySelector.astro";
 export { default as SubtractIPCalculator } from "./components/react/SubtractIPCalculator";
-export { AgentPrimitivesDiagram } from "./components/react/diagram-showcase/AgentPrimitivesDiagram";
 export { default as MeshHostnameRoutingDiagram } from "./components/cf/MeshHostnameRoutingDiagram.astro";
 export { default as TunnelHostnameRoutingDiagram } from "./components/cf/TunnelHostnameRoutingDiagram.astro";
 export { ContainerConnectivity } from "./components/react/container/ContainerConnectivity";