From 4fe96236055daa82632bbfd48945b5ea0ab88491 Mon Sep 17 00:00:00 2001
From: David Blass <david@arktype.io>
Date: Thu, 16 Jan 2025 19:57:45 -0500
Subject: [PATCH] feat: 2.0 (#1256)

---
 .gitignore                                    |    1 +
 ark/attest/package.json                       |    2 +-
 ark/dark/README.md                            |   14 +
 ark/dark/arktype.scratch.ts                   |    3 +
 ark/dark/injected.tmLanguage.json             |    2 +-
 ark/dark/package.json                         |    2 +-
 ark/dark/tsWithArkType.tmLanguage.json        |    5 +-
 ark/docs/app/(home)/layout.tsx                |    8 +-
 ark/docs/app/docs/[[...slug]]/page.tsx        |   17 +-
 ark/docs/app/global.css                       |   15 +-
 ark/docs/app/layout.tsx                       |    2 +
 ark/docs/components/ApiTable.tsx              |   59 +-
 ark/docs/components/Banner.tsx                |  145 ++
 ark/docs/components/FloatYourBoat.tsx         |   84 +-
 ark/docs/components/LocalFriendlyUrl.tsx      |    6 +-
 ark/docs/components/ReleaseBanner.tsx         |   12 +
 ark/docs/components/apiData.ts                | 1267 +++++++++++++----
 ark/docs/components/snippets/contentsById.ts  |   19 +-
 ark/docs/content/docs/blog/2.0.mdx            |   52 +
 ark/docs/content/docs/blog/index.mdx          |   11 +
 ark/docs/content/docs/blog/meta.json          |    5 +
 ark/docs/content/docs/configuration/index.mdx |  260 +++-
 ark/docs/content/docs/configuration/meta.json |    2 +-
 ark/docs/content/docs/expressions/index.mdx   |   41 +
 ark/docs/content/docs/meta.json               |    4 +-
 ark/docs/content/docs/traversal-api.mdx       |    7 +
 ark/docs/content/docs/type-api.mdx            |    8 -
 ark/docs/lib/shiki.ts                         |   34 +-
 ark/docs/lib/writeSnippetsEntrypoint.ts       |   11 +-
 ark/docs/package.json                         |   28 +-
 ark/fast-check/arbitraries/date.ts            |    4 +-
 ark/fast-check/arbitraries/number.ts          |   27 +-
 ark/fast-check/arktypeFastCheck.ts            |    8 +-
 ark/fs/package.json                           |    2 +-
 ark/repo/build.ts                             |    2 +-
 ark/repo/{jsdocGen.ts => jsDocGen.ts}         |  167 ++-
 ark/repo/package.json                         |    2 +-
 ark/repo/scratch.ts                           |   77 +-
 ark/repo/testV8.js                            |    4 +-
 ark/schema/config.ts                          |   94 +-
 ark/schema/kinds.ts                           |   31 +-
 ark/schema/node.ts                            |   20 +-
 ark/schema/package.json                       |    2 +-
 ark/schema/parse.ts                           |   25 +-
 ark/schema/predicate.ts                       |    9 +-
 ark/schema/roots/domain.ts                    |   67 +-
 ark/schema/roots/intersection.ts              |   58 +-
 ark/schema/roots/morph.ts                     |    4 +-
 ark/schema/roots/proto.ts                     |   75 +-
 ark/schema/roots/root.ts                      |   10 +-
 ark/schema/roots/union.ts                     |    4 +-
 ark/schema/scope.ts                           |  118 +-
 ark/schema/shared/declare.ts                  |    7 +-
 ark/schema/shared/disjoint.ts                 |    4 +
 ark/schema/shared/errors.ts                   |   16 +-
 ark/schema/shared/implement.ts                |   18 +-
 ark/schema/shared/traversal.ts                |  260 ++--
 ark/schema/structure/structure.ts             |   56 +-
 ark/type/__tests__/clone.test.ts              |    3 +
 ark/type/__tests__/config.test.ts             |   82 ++
 ark/type/__tests__/filter.test.ts             |   52 +
 ark/type/__tests__/get.test.ts                |    2 +-
 ark/type/__tests__/keywords/number.test.ts    |    9 +-
 ark/type/__tests__/realWorld.test.ts          |   39 +
 ark/type/__tests__/submodule.test.ts          |    4 +-
 ark/type/__tests__/traverse.test.ts           |   25 +
 ark/type/__tests__/type.test.ts               |   10 +
 ark/type/keywords/keywords.ts                 |    2 +
 ark/type/keywords/number.ts                   |   11 +-
 ark/type/keywords/string.ts                   |   10 +-
 ark/type/methods/base.ts                      |  337 +++--
 ark/type/package.json                         |   12 +-
 ark/type/parser/definition.ts                 |   29 +-
 ark/type/scope.ts                             |   14 +-
 ark/util/package.json                         |    2 +-
 ark/util/records.ts                           |   10 +
 ark/util/registry.ts                          |    2 +-
 ark/util/strings.ts                           |    9 +
 package.json                                  |   34 +-
 79 files changed, 3085 insertions(+), 910 deletions(-)
 create mode 100644 ark/docs/components/Banner.tsx
 create mode 100644 ark/docs/components/ReleaseBanner.tsx
 create mode 100644 ark/docs/content/docs/blog/2.0.mdx
 create mode 100644 ark/docs/content/docs/blog/index.mdx
 create mode 100644 ark/docs/content/docs/blog/meta.json
 create mode 100644 ark/docs/content/docs/traversal-api.mdx
 rename ark/repo/{jsdocGen.ts => jsDocGen.ts} (59%)
 create mode 100644 ark/type/__tests__/filter.test.ts

diff --git a/.gitignore b/.gitignore
index cd854c3aeb..116d714293 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 dist
 out
+*.vsix
 node_modules
 temp
 tmp
diff --git a/ark/attest/package.json b/ark/attest/package.json
index 41c2898994..a9e31098d2 100644
--- a/ark/attest/package.json
+++ b/ark/attest/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@ark/attest",
-	"version": "0.37.0",
+	"version": "0.38.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",
diff --git a/ark/dark/README.md b/ark/dark/README.md
index 5f4a3d1778..61ac55a992 100644
--- a/ark/dark/README.md
+++ b/ark/dark/README.md
@@ -45,6 +45,20 @@ To determine which scopes need to be changed, you can view scopes applied to any
 
 Changes to `injected.tmLanguage.json` should be mirrored to [tsWithArkType.tmLanguage.json](./tsWithArkType.tmLanguage.json).
 
+#### Testing tsWithArkType.tmLanguage.json
+
+To test the standalone rules for TS w/ ArkType highlighting, replace `grammars` in `package.json` with the following:
+
+```json
+	"grammars": {
+				"scopeName": "source.ts",
+				"language": "typescript",
+				"path": "tsWithArkType.tmLanguage.json"
+			}
+```
+
+Be sure to switch back before publishing!
+
 > [!IMPORTANT]  
 > You must reload the extension host window to see scope changes reflected
 
diff --git a/ark/dark/arktype.scratch.ts b/ark/dark/arktype.scratch.ts
index 5c74c08e01..eed8c03f8d 100644
--- a/ark/dark/arktype.scratch.ts
+++ b/ark/dark/arktype.scratch.ts
@@ -164,3 +164,6 @@ const highlighted = type({
 	pattern: "/^(?:4[0-9]{12}(?:[0-9]{3,6}))$/",
 	bar: "(string | number)[]"
 })
+
+// chained calls should be highlighted
+highlighted.or("string[]").or({ object: "string[]" })
diff --git a/ark/dark/injected.tmLanguage.json b/ark/dark/injected.tmLanguage.json
index b7174cdcbf..bc1cf52c3d 100644
--- a/ark/dark/injected.tmLanguage.json
+++ b/ark/dark/injected.tmLanguage.json
@@ -40,7 +40,7 @@
 		},
 		"arkChained": {
 			"contentName": "meta.embedded.arktype.definition",
-			"begin": "([^\\)\\(\\s]+)?(\\.)\\b(and|or|when|extends|ifExtends|intersect|merge|exclude|extract|overlaps|subsumes|to)(\\()",
+			"begin": "([^\\)\\(\\s]+)?(\\.)\\b(and|or|when|extends|ifExtends|intersect|merge|exclude|extract|overlaps|subsumes|to|satisfies)(\\()",
 			"beginCaptures": {
 				"2": {
 					"name": "punctuation.accessor.ts"
diff --git a/ark/dark/package.json b/ark/dark/package.json
index 39df47823c..45e37e911c 100644
--- a/ark/dark/package.json
+++ b/ark/dark/package.json
@@ -2,7 +2,7 @@
 	"name": "arkdark",
 	"displayName": "ArkDark",
 	"description": "Syntax highlighting, inline errors and theme for ArkType⛵",
-	"version": "5.13.0",
+	"version": "5.14.0",
 	"publisher": "arktypeio",
 	"type": "module",
 	"license": "MIT",
diff --git a/ark/dark/tsWithArkType.tmLanguage.json b/ark/dark/tsWithArkType.tmLanguage.json
index bc561f821c..45d53e97cf 100644
--- a/ark/dark/tsWithArkType.tmLanguage.json
+++ b/ark/dark/tsWithArkType.tmLanguage.json
@@ -48,7 +48,7 @@
 		},
 		"arkChained": {
 			"contentName": "meta.embedded.arktype.definition",
-			"begin": "([^\\)\\(\\s]+)?(\\.)\\b(and|or|when|extends|ifExtends|intersect|merge|exclude|extract|overlaps|subsumes|to)(\\()",
+			"begin": "([^\\)\\(\\s]+)?(\\.)\\b(and|or|when|extends|ifExtends|intersect|merge|exclude|extract|overlaps|subsumes|to|satisfies)(\\()",
 			"beginCaptures": {
 				"2": {
 					"name": "punctuation.accessor.ts"
@@ -498,6 +498,9 @@
 				{
 					"include": "#arkDefinition"
 				},
+				{
+					"include": "#arkChained"
+				},
 				{
 					"include": "#string"
 				},
diff --git a/ark/docs/app/(home)/layout.tsx b/ark/docs/app/(home)/layout.tsx
index 673b9b57d2..350be2d177 100644
--- a/ark/docs/app/(home)/layout.tsx
+++ b/ark/docs/app/(home)/layout.tsx
@@ -9,8 +9,14 @@ export type LayoutProps = {
 
 export default ({ children }: LayoutProps): React.ReactElement => (
 	<HomeLayout
+		style={{
+			paddingTop: 0
+		}}
 		{...baseOptions}
-		nav={{ ...baseOptions.nav, children: <FloatYourBoat /> }}
+		nav={{
+			...baseOptions.nav,
+			children: <FloatYourBoat kind="header" />
+		}}
 	>
 		{children}
 	</HomeLayout>
diff --git a/ark/docs/app/docs/[[...slug]]/page.tsx b/ark/docs/app/docs/[[...slug]]/page.tsx
index 13165cf6cd..4e5a404349 100644
--- a/ark/docs/app/docs/[[...slug]]/page.tsx
+++ b/ark/docs/app/docs/[[...slug]]/page.tsx
@@ -25,10 +25,21 @@ export default async (props: { params: Promise<{ slug?: string[] }> }) => {
 
 	const MDX = page.data.body
 
+	const isApiPage =
+		page.data.title.endsWith("API") || page.data.title.endsWith("Configuration")
+
 	return (
-		<DocsPage toc={page.data.toc} full={page.data.full ?? false}>
-			<DocsTitle>{page.data.title}</DocsTitle>
-			<DocsDescription>{page.data.description}</DocsDescription>
+		<DocsPage
+			toc={isApiPage ? [] : page.data.toc}
+			full={page.data.full ?? false}
+		>
+			<DocsTitle>
+				{page.data.title}
+				<DocsDescription style={{ margin: 0 }}>
+					{page.data.description}
+				</DocsDescription>
+			</DocsTitle>
+
 			<DocsBody>
 				<MDX
 					components={{
diff --git a/ark/docs/app/global.css b/ark/docs/app/global.css
index 0e83774864..8e121f95ac 100644
--- a/ark/docs/app/global.css
+++ b/ark/docs/app/global.css
@@ -90,9 +90,9 @@ div.twoslash-popup-container {
 
 .error.highlighted {
 	position: relative;
-	background-color: #f8585822;
-	border-left: 3px solid var(--ark-runtime-error);
 	padding: 4px;
+	background-color: var(--twoslash-error-bg);
+	border-left: 3px solid var(--ark-error);
 	padding-right: 16px;
 	margin: 0.2em 0;
 	min-width: 100%;
@@ -100,6 +100,15 @@ div.twoslash-popup-container {
 }
 
 .error.highlighted > span {
+	color: var(--twoslash-error-color) !important;
+}
+
+.error.highlighted.runtime-error {
+	background-color: #f8585822;
+	border-left: 3px solid var(--ark-runtime-error);
+}
+
+.error.highlighted.runtime-error > span {
 	color: var(--ark-runtime-error) !important;
 }
 
@@ -135,7 +144,7 @@ div.twoslash-popup-container {
 }
 
 .completions-block code {
-	padding-bottom: 3rem;
+	padding-bottom: 2rem;
 }
 
 /** avoid a janky white outline on hovers: 
diff --git a/ark/docs/app/layout.tsx b/ark/docs/app/layout.tsx
index 35f2cfa927..8d899187b3 100644
--- a/ark/docs/app/layout.tsx
+++ b/ark/docs/app/layout.tsx
@@ -3,6 +3,7 @@ import "fumadocs-twoslash/twoslash.css"
 import { RootProvider } from "fumadocs-ui/provider"
 import { Raleway } from "next/font/google"
 import type { ReactNode } from "react"
+import { ReleaseBanner } from "../components/ReleaseBanner.tsx"
 
 const raleway = Raleway({
 	subsets: ["latin"]
@@ -23,6 +24,7 @@ export default ({ children }: { children: ReactNode }) => (
 					defaultTheme: "dark"
 				}}
 			>
+				<ReleaseBanner />
 				{children}
 			</RootProvider>
 		</body>
diff --git a/ark/docs/components/ApiTable.tsx b/ark/docs/components/ApiTable.tsx
index 7616eb3930..148c59a6ac 100644
--- a/ark/docs/components/ApiTable.tsx
+++ b/ark/docs/components/ApiTable.tsx
@@ -1,33 +1,28 @@
-import type { JSX } from "react"
-import type { ApiGroup, ParsedJsDocPart } from "../../repo/jsdocGen.ts"
+import type { ApiGroup, ParsedJsDocPart } from "../../repo/jsDocGen.ts"
 import { apiDocsByGroup } from "./apiData.ts"
 import { CodeBlock } from "./CodeBlock.tsx"
 import { LocalFriendlyUrl } from "./LocalFriendlyUrl.tsx"
 
 export type ApiTableProps = {
 	group: ApiGroup
-	rows: JSX.Element[]
 }
 
 export const ApiTable = ({ group }: ApiTableProps) => (
-	<>
-		<h2>{group}</h2>
-		<div className="w-full overflow-x-auto">
-			<table className="w-full table-fixed border-collapse">
-				<colgroup>
-					<col className="w-28" />
-					<col className="w-1/4" />
-					<col className="w-full" />
-				</colgroup>
-				<ApiTableHeader />
-				<tbody>
-					{apiDocsByGroup[group].map(props => (
-						<ApiTableRow key={props.name} {...props} />
-					))}
-				</tbody>
-			</table>
-		</div>
-	</>
+	<div className="w-full overflow-x-auto">
+		<table className="w-full table-fixed border-collapse">
+			<colgroup>
+				<col className="w-28" />
+				<col className="w-1/4" />
+				<col className="w-full" />
+			</colgroup>
+			<ApiTableHeader />
+			<tbody>
+				{apiDocsByGroup[group].map(props => (
+					<ApiTableRow key={props.name} {...props} />
+				))}
+			</tbody>
+		</table>
+	</div>
 )
 
 const ApiTableHeader = () => (
@@ -37,7 +32,7 @@ const ApiTableHeader = () => (
 				Name
 			</th>
 			<th className="p-2 text-left align-top min-w-[200px]">Summary</th>
-			<th className="p-2 text-left align-top">Example</th>
+			<th className="p-2 text-left align-top">Notes & Examples</th>
 		</tr>
 	</thead>
 )
@@ -51,7 +46,17 @@ interface ApiTableRowProps {
 
 const ApiTableRow = ({ name, summary, example, notes }: ApiTableRowProps) => (
 	<tr key={name}>
-		<td className="p-2 align-top whitespace-nowrap w-auto">{name}</td>
+		<td
+			style={{
+				fontSize:
+					name.length < 12 ? "1rem"
+					: name.length < 16 ? "0.7rem"
+					: "0.6rem"
+			}}
+			className="p-2 align-top whitespace-nowrap w-auto"
+		>
+			{name}
+		</td>
 		<td className="p-2 align-top">{JsDocParts(summary)}</td>
 		<td className="p-2 align-top">
 			{notes.map((note, i) => (
@@ -70,13 +75,9 @@ const JsDocParts = (parts: readonly ParsedJsDocPart[]) =>
 					{part.value}
 				</LocalFriendlyUrl>
 			: part.kind === "reference" ?
-				<a href={`#${part.value}`} key={i}>
+				<a style={{ display: "inline-block" }} href={`#${part.value}`} key={i}>
 					{part.value}
 				</a>
-			: part.kind === "tag" ?
-				<p key={i}>
-					{part.name} {JsDocParts(part.value)}
-				</p>
 			:	<p
 					style={{ display: "inline" }}
 					key={i}
@@ -84,6 +85,8 @@ const JsDocParts = (parts: readonly ParsedJsDocPart[]) =>
 						__html: part.value
 							.replace(/(\*\*|__)([^*_]+)\1/g, "<strong>$2</strong>")
 							.replace(/(\*|_)([^*_]+)\1/g, "<em>$2</em>")
+							.replace(/`([^`]+)`/g, "<code>$1</code>")
+							.replace(/^-(.*)/g, "• $1")
 					}}
 				/>
 			}
diff --git a/ark/docs/components/Banner.tsx b/ark/docs/components/Banner.tsx
new file mode 100644
index 0000000000..3e7379a11d
--- /dev/null
+++ b/ark/docs/components/Banner.tsx
@@ -0,0 +1,145 @@
+"use client"
+
+import { buttonVariants, cn } from "fumadocs-ui/components/api"
+import { X } from "lucide-react"
+import { type HTMLAttributes, useCallback, useEffect, useState } from "react"
+import { FloatYourBoat } from "./FloatYourBoat.tsx"
+
+// Based on:
+// https://github.com/fuma-nama/fumadocs/blob/1e6ece043987c8bf607249b66a8945632b229982/packages/ui/src/components/banner.tsx#L65
+
+export const Banner = ({
+	id = "banner",
+	changeLayout = true,
+	boat,
+	children,
+	...props
+}: HTMLAttributes<HTMLDivElement> & {
+	boat?: boolean
+	/**
+	 * Change Fumadocs layout styles
+	 *
+	 * @defaultValue true
+	 */
+	changeLayout?: boolean
+}): React.ReactElement => {
+	const [open, setOpen] = useState(true)
+	const globalKey = id ? `nd-banner-${id}` : undefined
+
+	useEffect(() => {
+		if (globalKey) setOpen(localStorage.getItem(globalKey) !== "true")
+	}, [globalKey])
+
+	const onClick = useCallback(() => {
+		setOpen(false)
+		if (globalKey) localStorage.setItem(globalKey, "true")
+	}, [globalKey])
+
+	return (
+		<div
+			id={id}
+			{...props}
+			className={cn(
+				"sticky top-0 z-40 flex h-12 flex-row items-center justify-around bg-fd-secondary px-4 text-center text-sm font-medium",
+				"bg-fd-background",
+				!open && "hidden",
+				props.className
+			)}
+		>
+			<div>
+				{changeLayout && open ?
+					<style>{`
+        :root:not(.${globalKey ?? "nd-banner-never"}) { --fd-banner-height: 3rem; }
+        `}</style>
+				:	null}
+				{globalKey ?
+					<style>{`.${globalKey} #${id} { display: none; }`}</style>
+				:	null}
+				{id ?
+					<script
+						dangerouslySetInnerHTML={{
+							__html: `if (localStorage.getItem('${globalKey}') === 'true') document.documentElement.classList.add('${globalKey}');`
+						}}
+					/>
+				:	null}
+				{background}
+				<div style={{ width: 100 }}>
+					{boat ?
+						<FloatYourBoat kind="banner" />
+					:	null}
+				</div>
+			</div>
+			<div>{children}</div>
+			<div style={{ width: 100 }}>
+				{id ?
+					<button
+						type="button"
+						aria-label="Close Banner"
+						onClick={onClick}
+						className={cn(
+							buttonVariants({
+								color: "ghost",
+								className:
+									"absolute end-2 top-1/2 -translate-y-1/2 text-fd-muted-foreground",
+								size: "icon"
+							})
+						)}
+					>
+						<X />
+					</button>
+				:	null}
+			</div>
+		</div>
+	)
+}
+
+const maskImage =
+	"linear-gradient(to bottom,white,transparent), radial-gradient(circle at top center, white, transparent)"
+
+const palette = {
+	"--start": "hsla(207, 100%, 9%, 0.35)",
+	"--mid": "hsla(207, 100%, 36%, 0.35)",
+	"--end": "hsla(207, 100%, 63%, 0.35)",
+	"--via": "hsla(207, 100%, 46%, 0.35)"
+}
+
+const background = (
+	<>
+		<div
+			className="absolute inset-0 z-[-1]"
+			style={{
+				maskImage,
+				maskComposite: "intersect",
+				animation: "fd-moving-banner 16s linear infinite",
+				animationDirection: "reverse",
+				...palette,
+				// A wave-like repeating gradient with blues only
+				backgroundImage:
+					"repeating-linear-gradient(60deg, var(--start), var(--start) 5%, var(--via) 12%, var(--mid) 20%, var(--end) 28%, transparent 40%)",
+				backgroundSize: "200% 100%",
+				// Use 'normal' to avoid darkening or rainbow on text
+				mixBlendMode: "normal"
+			}}
+		/>
+		<div
+			className="absolute inset-0 z-[-1]"
+			style={{
+				maskImage,
+				maskComposite: "intersect",
+				animation: "fd-moving-banner 20s linear infinite",
+				...palette,
+				// Another wave-like gradient
+				backgroundImage:
+					"repeating-linear-gradient(45deg, var(--start), var(--start) 5%, var(--via) 12%, var(--mid) 20%, var(--end) 28%, transparent 40%)",
+				backgroundSize: "200% 100%",
+				mixBlendMode: "normal"
+			}}
+		/>
+		<style>
+			{`@keyframes fd-moving-banner {
+                from { background-position: 0% 0; }
+                to { background-position: 100% 0; }
+            }`}
+		</style>
+	</>
+)
diff --git a/ark/docs/components/FloatYourBoat.tsx b/ark/docs/components/FloatYourBoat.tsx
index 9e5b5ad1b9..9d463ce2c4 100644
--- a/ark/docs/components/FloatYourBoat.tsx
+++ b/ark/docs/components/FloatYourBoat.tsx
@@ -7,47 +7,81 @@ import { BoatIcon } from "./icons/boat.tsx"
 const BOB_HEIGHT_PX = 2
 const BOB_WIDTH_PX = 16
 
-export const FloatYourBoat = () => {
-	const [loopDuration, setLoopDuration] = useState<number | null>(null)
+export type FloatYourBoatProps = {
+	kind: "header" | "banner"
+}
+
+const selectorsByKind = {
+	header: "header",
+	banner: "#banner"
+}
+
+export const FloatYourBoat = ({ kind }: FloatYourBoatProps) => {
+	const [headerRect, setHeaderRect] = useState<DOMRect | null>()
+
+	const loopDuration = headerRect ? headerRect.width / BOB_WIDTH_PX : 0
 
 	const bobFrames = useMemo(() => {
 		if (!loopDuration) return []
+
 		const frames: number[] = []
 		for (let i = 0; i < loopDuration; i++)
 			frames.push(i % 2 ? BOB_HEIGHT_PX : 0)
 		return frames
-	}, [loopDuration])
+	}, [headerRect])
 
 	useLayoutEffect(() => {
-		const width = window.innerWidth
-		setLoopDuration(width / BOB_WIDTH_PX)
+		setHeaderRect(
+			document.querySelector(selectorsByKind[kind])?.getBoundingClientRect()
+		)
 	}, [])
 
-	if (loopDuration === null) return null
+	if (!headerRect) return null
 
-	return <Boat loopDuration={loopDuration} bobFrames={bobFrames} />
+	return (
+		<Boat
+			headerRect={headerRect}
+			loopDuration={loopDuration}
+			bobFrames={bobFrames}
+		/>
+	)
 }
 
 type BoatProps = {
+	headerRect: DOMRect
 	loopDuration: number
 	bobFrames: number[]
 }
 
-const Boat = ({ loopDuration, bobFrames }: BoatProps) => (
-	<motion.div
-		className="absolute z-10 -top-10 pointer-events-none"
-		initial={{ left: "-7%" }}
-		animate={{
-			left: "100%",
-			y: bobFrames
-		}}
-		transition={{
-			duration: loopDuration,
-			repeat: Infinity,
-			ease: "linear",
-			delay: 1
-		}}
-	>
-		<BoatIcon height={120} />
-	</motion.div>
-)
+const Boat = ({ headerRect, loopDuration, bobFrames }: BoatProps) => {
+	const opacityFrames = bobFrames.map((_, i) =>
+		i === 0 || i === bobFrames.length - 1 ? 0
+		: i === 1 || i === bobFrames.length - 2 ? 0.5
+		: 1
+	)
+	return (
+		<motion.div
+			className="pointer-events-none"
+			initial={{
+				position: "relative",
+				top: headerRect.height - 60,
+				left: -40,
+				zIndex: -10,
+				opacity: 0
+			}}
+			animate={{
+				left: headerRect.width - 100,
+				y: bobFrames,
+				opacity: opacityFrames
+			}}
+			transition={{
+				duration: loopDuration,
+				repeat: Infinity,
+				ease: "linear",
+				delay: 1
+			}}
+		>
+			<BoatIcon height={100} />
+		</motion.div>
+	)
+}
diff --git a/ark/docs/components/LocalFriendlyUrl.tsx b/ark/docs/components/LocalFriendlyUrl.tsx
index f9f015a79d..2b28705376 100644
--- a/ark/docs/components/LocalFriendlyUrl.tsx
+++ b/ark/docs/components/LocalFriendlyUrl.tsx
@@ -20,7 +20,11 @@ export const LocalFriendlyUrl = (props: LocalFriendlyUrlProps) => {
 	}
 
 	return (
-		<a href={locallyAccessibleUrl} key={props.key}>
+		<a
+			style={{ display: "inline-block" }}
+			href={locallyAccessibleUrl}
+			key={props.key}
+		>
 			{props.children}
 		</a>
 	)
diff --git a/ark/docs/components/ReleaseBanner.tsx b/ark/docs/components/ReleaseBanner.tsx
new file mode 100644
index 0000000000..76a62fff6e
--- /dev/null
+++ b/ark/docs/components/ReleaseBanner.tsx
@@ -0,0 +1,12 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import { Banner } from "./Banner.tsx"
+
+const text = "🎉 Announcing ArkType 2.0 🎉"
+
+export const ReleaseBanner = () => (
+	<Banner style={{ fontSize: 16 }} boat={usePathname().includes("docs")}>
+		{text}
+	</Banner>
+)
diff --git a/ark/docs/components/apiData.ts b/ark/docs/components/apiData.ts
index 9ddcf25143..783c952a4c 100644
--- a/ark/docs/components/apiData.ts
+++ b/ark/docs/components/apiData.ts
@@ -1,253 +1,1020 @@
-import type { ApiDocsByGroup } from "../../repo/jsdocGen.ts"
+import type { ApiDocsByGroup } from "../../repo/jsDocGen.ts"
 
+/** THIS FILE IS AUTOGENERATED FROM ark/repo/jsDocGen.ts **/
+// prettier-ignore
 export const apiDocsByGroup: ApiDocsByGroup = {
-	Type: [
-		{
-			group: "Type",
-			name: "$",
-			summary: [
-				{
-					kind: "text",
-					value: "The"
-				},
-				{
-					kind: "reference",
-					value: "Scope"
-				},
-				{
-					kind: "text",
-					value:
-						"in which definitions for this Type its chained methods are parsed"
-				}
-			],
-			notes: []
-		},
-		{
-			group: "Type",
-			name: "infer",
-			summary: [
-				{
-					kind: "text",
-					value: "The type of data this returns"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value:
-							"🥸 Inference-only property that will be `undefined` at runtime"
-					}
-				]
-			],
-			example:
-				'const parseNumber = type("string").pipe(s => Number.parseInt(s))\ntype ParsedNumber = typeof parseNumber.infer // number'
-		},
-		{
-			group: "Type",
-			name: "inferIn",
-			summary: [
-				{
-					kind: "text",
-					value: "The type of data this expects"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value:
-							"🥸 Inference-only property that will be `undefined` at runtime"
-					}
-				]
-			],
-			example:
-				'const parseNumber = type("string").pipe(s => Number.parseInt(s))\ntype UnparsedNumber = typeof parseNumber.inferIn // string'
-		},
-		{
-			group: "Type",
-			name: "json",
-			summary: [
-				{
-					kind: "text",
-					value: "The internal JSON representation"
-				}
-			],
-			notes: []
-		},
-		{
-			group: "Type",
-			name: "toJsonSchema",
-			summary: [
-				{
-					kind: "text",
-					value: "Generate a JSON Schema"
-				}
-			],
-			notes: []
-		},
-		{
-			group: "Type",
-			name: "meta",
-			summary: [
-				{
-					kind: "text",
-					value: "Metadata like custom descriptions and error messages"
-				}
-			],
-			notes: []
-		},
-		{
-			group: "Type",
-			name: "description",
-			summary: [
-				{
-					kind: "text",
-					value: "An English description"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value: "Work best for primitive values"
-					}
-				]
-			],
-			example:
-				'const n = type("0 < number <= 100")\nconsole.log(n.description) // positive and at most 100'
-		},
-		{
-			group: "Type",
-			name: "expression",
-			summary: [
-				{
-					kind: "text",
-					value: "A syntactic representation similar to native TypeScript"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value: "Works well for both primitives and structures"
-					}
-				]
-			],
-			example:
-				'const loc = type({ coords: ["number", "number"] })\nconsole.log(loc.expression) // { coords: [number, number] }'
-		},
-		{
-			group: "Type",
-			name: "assert",
-			summary: [
-				{
-					kind: "text",
-					value:
-						"Validate and morph data, throwing a descriptive AggregateError on failure"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value: "Sugar to avoid checking for"
-					},
-					{
-						kind: "reference",
-						value: "type.errors"
-					},
-					{
-						kind: "text",
-						value: "if they are unrecoverable"
-					}
-				]
-			],
-			example:
-				'const criticalPayload = type({\n    superImportantValue: "string"\n})\n// throws AggregateError: superImportantValue must be a string (was missing)\nconst data = criticalPayload.assert({ irrelevantValue: "whoops" })\nconsole.log(data.superImportantValue) // valid output can be accessed directly'
-		},
-		{
-			group: "Type",
-			name: "allows",
-			summary: [
-				{
-					kind: "text",
-					value: "Validate input data without applying morphs"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value:
-							"Good for cases like filtering that don't benefit from detailed errors"
-					}
-				]
-			],
-			example:
-				'const numeric = type("number | bigint")\n// [0, 2n]\nconst numerics = [0, "one", 2n].filter(numeric.allows)'
-		},
-		{
-			group: "Type",
-			name: "configure",
-			summary: [
-				{
-					kind: "text",
-					value: "Clone and add metadata to shallow references"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value:
-							"Does not affect error messages within properties of an object"
-					}
-				],
-				[
-					{
-						kind: "noteStart",
-						value: "Overlapping keys on existing meta will be overwritten"
-					}
-				]
-			],
-			example:
-				'const notOdd = type("number % 2").configure({ description: "not odd" })\n// all constraints at the root are affected\nconst odd = notOdd(3) // must be not odd (was 3)\nconst nonNumber = notOdd("two") // must be not odd (was "two")\n\nconst notOddBox = type({\n   // we should have referenced notOdd or added meta here\n   notOdd: "number % 2",\n// but instead chained from the root object\n}).configure({ description: "not odd" })\n// error message at path notOdd is not affected\nconst oddProp = notOddBox({ notOdd: 3 }) // notOdd must be even (was 3)\n// error message at root is affected, leading to a misleading description\nconst nonObject = notOddBox(null) // must be not odd (was null)'
-		},
-		{
-			group: "Type",
-			name: "describe",
-			summary: [
-				{
-					kind: "text",
-					value: "Clone and add the description to shallow references"
-				}
-			],
-			notes: [
-				[
-					{
-						kind: "noteStart",
-						value: "Equivalent to `.configure({ description })` (see"
-					},
-					{
-						kind: "reference",
-						value: "configure"
-					},
-					{
-						kind: "text",
-						value: ")"
-					}
-				],
-				[
-					{
-						kind: "noteStart",
-						value:
-							"Does not affect error messages within properties of an object"
-					}
-				]
-			],
-			example:
-				'const aToZ = type(/^a.*z$/).describe("a string like \'a...z\'")\nconst good = aToZ("alcatraz") // "alcatraz"\n// notice how our description is integrated with other parts of the message\nconst badPattern = aToZ("albatross") // must be a string like \'a...z\' (was "albatross")\nconst nonString = aToZ(123) // must be a string like \'a...z\' (was 123)'
-		}
-	]
+    "Type": [
+        {
+            "group": "Type",
+            "name": "$",
+            "summary": [
+                {
+                    "kind": "reference",
+                    "value": "Scope"
+                },
+                {
+                    "kind": "text",
+                    "value": "in which chained methods are parsed"
+                }
+            ],
+            "notes": []
+        },
+        {
+            "group": "Type",
+            "name": "infer",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "type of output this returns"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🥸 inference-only property that will be `undefined` at runtime"
+                    }
+                ]
+            ],
+            "example": "const parseNumber = type(\"string\").pipe(s => Number.parseInt(s))\ntype ParsedNumber = typeof parseNumber.infer // number"
+        },
+        {
+            "group": "Type",
+            "name": "inferIn",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "type of input this allows"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🥸 inference-only property that will be `undefined` at runtime"
+                    }
+                ]
+            ],
+            "example": "const parseNumber = type(\"string\").pipe(s => Number.parseInt(s))\ntype UnparsedNumber = typeof parseNumber.inferIn // string"
+        },
+        {
+            "group": "Type",
+            "name": "json",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "internal JSON representation"
+                }
+            ],
+            "notes": []
+        },
+        {
+            "group": "Type",
+            "name": "toJsonSchema",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "generate a JSON Schema"
+                }
+            ],
+            "notes": []
+        },
+        {
+            "group": "Type",
+            "name": "meta",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "metadata like custom descriptions and error messages"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ type"
+                    },
+                    {
+                        "kind": "link",
+                        "url": "https://arktype.io/docs/configuration#custom",
+                        "value": "can be customized"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "for your project"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Type",
+            "name": "description",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "human-readable English description"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ works best for primitive values"
+                    }
+                ]
+            ],
+            "example": "const n = type(\"0 < number <= 100\")\nconsole.log(n.description) // positive and at most 100"
+        },
+        {
+            "group": "Type",
+            "name": "expression",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "syntax string similar to native TypeScript"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ works well for both primitives and structures"
+                    }
+                ]
+            ],
+            "example": "const loc = type({ coords: [\"number\", \"number\"] })\nconsole.log(loc.expression) // { coords: [number, number] }"
+        },
+        {
+            "group": "Type",
+            "name": "assert",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "validate and return transformed data or throw"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ sugar to avoid checking for"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "type.errors"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "if they are unrecoverable"
+                    }
+                ]
+            ],
+            "example": "const criticalPayload = type({\n    superImportantValue: \"string\"\n})\n// throws AggregateError: superImportantValue must be a string (was missing)\nconst data = criticalPayload.assert({ irrelevantValue: \"whoops\" })\nconsole.log(data.superImportantValue) // valid output can be accessed directly"
+        },
+        {
+            "group": "Type",
+            "name": "allows",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "check input without applying morphs"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ good for stuff like filtering that doesn't benefit from detailed errors"
+                    }
+                ]
+            ],
+            "example": "const numeric = type(\"number | bigint\")\n// [0, 2n]\nconst numerics = [0, \"one\", 2n].filter(numeric.allows)"
+        },
+        {
+            "group": "Type",
+            "name": "configure",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "add metadata to shallow references"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ does not affect error messages within properties of an object"
+                    }
+                ]
+            ],
+            "example": "const notOdd = type(\"number % 2\").configure({ description: \"not odd\" })\n// all constraints at the root are affected\nconst odd = notOdd(3) // must be not odd (was 3)\nconst nonNumber = notOdd(\"two\") // must be not odd (was \"two\")\n\nconst notOddBox = type({\n   // we should have referenced notOdd or added meta here\n   notOdd: \"number % 2\",\n// but instead chained from the root object\n}).configure({ description: \"not odd\" })\n// error message at path notOdd is not affected\nconst oddProp = notOddBox({ notOdd: 3 }) // notOdd must be even (was 3)\n// error message at root is affected, leading to a misleading description\nconst nonObject = notOddBox(null) // must be not odd (was null)"
+        },
+        {
+            "group": "Type",
+            "name": "describe",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "add description to shallow references"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🔗 equivalent to `.configure({ description })` (see"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "configure"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ")"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ does not affect error messages within properties of an object"
+                    }
+                ]
+            ],
+            "example": "const aToZ = type(/^a.*z$/).describe(\"a string like 'a...z'\")\nconst good = aToZ(\"alcatraz\") // \"alcatraz\"\n// ArkErrors: must be a string like 'a...z' (was \"albatross\")\nconst badPattern = aToZ(\"albatross\")"
+        },
+        {
+            "group": "Type",
+            "name": "onUndeclaredKey",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "apply undeclared key behavior"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "- `\"ignore\"` (default) - allow and preserve extra properties"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "- `\"reject\"` - disallow extra properties"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "- `\"delete\"` - clone and remove extra properties from output"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Type",
+            "name": "onDeepUndeclaredKey",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "deeply apply undeclared key behavior"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "- `\"ignore\"` (default) - allow and preserve extra properties"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "- `\"reject\"` - disallow extra properties"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "- `\"delete\"` - clone and remove extra properties from output"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Type",
+            "name": "from",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "alias for"
+                },
+                {
+                    "kind": "reference",
+                    "value": "assert"
+                },
+                {
+                    "kind": "text",
+                    "value": "with typed input"
+                }
+            ],
+            "notes": [],
+            "example": "const t = type({ foo: \"string\" });\n// TypeScript: foo must be a string (was 5)\nconst data = t.from({ foo: 5 });"
+        },
+        {
+            "group": "Type",
+            "name": "as",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "cast the way this is inferred"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🥸 inference-only function that does nothing runtime"
+                    }
+                ]
+            ],
+            "example": "// Type<`LEEEEEEEE${string}ROY`>\nconst leeroy = type(/^LE{8,}ROY$/).as<`LEEEEEEEE${string}ROY`>()"
+        },
+        {
+            "group": "Type",
+            "name": "brand",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "add a compile-time brand to output"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🥸 inference-only function that does nothing runtime"
+                    }
+                ]
+            ],
+            "example": "const palindrome = type(\"string\")\n    .narrow(s => s === [...s].reverse().join(\"\"))\n    .brand(\"palindrome\")\n// Brand<string, \"palindrome\">\nconst out = palindrome.assert(\"racecar\")"
+        },
+        {
+            "group": "Type",
+            "name": "and",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "intersect the parsed Type, throwing if the result is unsatisfiable"
+                }
+            ],
+            "notes": [],
+            "example": "// Type<{ foo: number; bar: string }>\nconst t = type({ foo: \"number\" }).and({ bar: \"string\" })\n// ParseError: Intersection at foo of number and string results in an unsatisfiable type\nconst bad = type({ foo: \"number\" }).and({ foo: \"string\" })"
+        },
+        {
+            "group": "Type",
+            "name": "or",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "union with the parsed Type"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ a union that could apply different morphs to the same data is a ParseError ([docs](https://arktype.io/docs/expressions/union-morphs))"
+                    }
+                ]
+            ],
+            "example": "// Type<string | { box: string }>\nconst t = type(\"string\").or({ box: \"string\" })"
+        },
+        {
+            "group": "Type",
+            "name": "array",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "an array of this"
+                }
+            ],
+            "notes": [],
+            "example": "// Type<{ rebmun: number }[]>\nconst t = type({ rebmun: \"number\" }).array();"
+        },
+        {
+            "group": "Type",
+            "name": "optional",
+            "summary": [
+                {
+                    "kind": "link",
+                    "url": "https://arktype.io/docs/objects#properties-optional",
+                    "value": "optional definition"
+                }
+            ],
+            "notes": [
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ unlike most other methods, this creates a definition rather than a Type (read why)"
+                    }
+                ]
+            ],
+            "example": "const prop = type({ foo: \"number\" })\n// Type<{ bar?: { foo: number } }>\nconst obj = type({ bar: prop.optional() })"
+        },
+        {
+            "group": "Type",
+            "name": "default",
+            "summary": [
+                {
+                    "kind": "link",
+                    "url": "https://arktype.io/docs/objects#properties-defaultable",
+                    "value": "defaultable definition"
+                }
+            ],
+            "notes": [
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ object defaults can be returned from a function"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ throws if the default value is not allowed"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ unlike most other methods, this creates a definition rather than a Type (read why)"
+                    }
+                ]
+            ],
+            "example": "// Type<{ count: Default<number, 0> }>\nconst state = type({ count: type.number.default(0) })\nconst prop = type({ nested: \"boolean\" })\nconst forObj = type({\n    key: nested.default(() => ({ nested: false }))\n})"
+        },
+        {
+            "group": "Type",
+            "name": "filter",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "apply a predicate function to input"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ the behavior of"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "narrow"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ", this method's output counterpart, is usually more desirable"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ most useful for morphs with input types that are re-used externally"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🥸"
+                    },
+                    {
+                        "kind": "link",
+                        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates",
+                        "value": "Type predicates"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "can be used as casts"
+                    }
+                ]
+            ],
+            "example": "const stringifyUser = type({ name: \"string\" }).pipe(user => JSON.stringify(user))\nconst stringifySafe = stringifyUser.filter(user => user.name !== \"Bobby Tables\")\n// Type<(In: `${string}Z`) => To<Date>>\nconst withPredicate = type(\"string.date.parse\").filter((s): s is `${string}Z` =>\n    s.endsWith(\"Z\")\n)"
+        },
+        {
+            "group": "Type",
+            "name": "narrow",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "apply a predicate function to output"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ go-to fallback for validation not composable via built-in types and operators"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ runs after all other validators and morphs, if present"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🥸"
+                    },
+                    {
+                        "kind": "link",
+                        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates",
+                        "value": "Type predicates"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "can be used as casts"
+                    }
+                ]
+            ],
+            "example": "const palindrome = type(\"string\").narrow(s => s === [...s].reverse().join(\"\"))\n\nconst palindromicEmail = type(\"string.date.parse\").narrow((date, ctx) =>\n\t\tdate.getFullYear() === 2025 || ctx.mustBe(\"the current year\")\n)\n// Type<`${string}.tsx`>\nconst withPredicate = type(\"string\").narrow((s): s is `${string}.tsx` => /\\.tsx?$/.test(s))"
+        },
+        {
+            "group": "Type",
+            "name": "intersect",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "intersect the parsed Type, returning an introspectable"
+                },
+                {
+                    "kind": "reference",
+                    "value": "Disjoint"
+                },
+                {
+                    "kind": "text",
+                    "value": "if the result is unsatisfiable"
+                }
+            ],
+            "notes": [],
+            "example": "// Type<{ foo: number; bar: string }>\nconst t = type({ foo: \"number\" }).intersect({ bar: \"string\" })\nconst bad = type(\"number > 10\").intersect(\"number < 5\")\n// logs \"Intersection of > 10 and < 5 results in an unsatisfiable type\"\nif (bad instanceof Disjoint) console.log(`${bad.summary}`)"
+        },
+        {
+            "group": "Type",
+            "name": "equals",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "check if the parsed Type's constraints are identical"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ equal types have identical input and output constraints and transforms"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ ignores associated"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "meta"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ", which does not affect the set of allowed values"
+                    }
+                ]
+            ],
+            "example": "const divisibleBy6 = type.number.divisibleBy(6).moreThan(0)\n// false (left side must also be positive)\ndivisibleBy6.equals(\"number % 6\")\n// false (right side has an additional <100 constraint)\nconsole.log(divisibleBy6.equals(\"0 < (number % 6) < 100\"))\nconst thirdTry = type(\"(number % 2) > 0\").divisibleBy(3)\n// true (types are normalized and reduced)\nconsole.log(divisibleBy6.equals(thirdTry))"
+        },
+        {
+            "group": "Type",
+            "name": "ifEquals",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "narrow this based on an"
+                },
+                {
+                    "kind": "reference",
+                    "value": "equals"
+                },
+                {
+                    "kind": "text",
+                    "value": "check"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ ignores associated"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "meta"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ", which does not affect the set of allowed values"
+                    }
+                ]
+            ],
+            "example": "const n = type.raw(`${Math.random()}`)\n// Type<0.5> | undefined\nconst ez = n.ifEquals(\"0.5\")"
+        },
+        {
+            "group": "Type",
+            "name": "extends",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "check if this is a subtype of the parsed Type"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ a subtype must include all constraints from the base type"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ unlike"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "equals"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ", additional constraints may be present"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ ignores associated"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "meta"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ", which does not affect the set of allowed values"
+                    }
+                ]
+            ],
+            "example": "type.string.extends(\"unknown\") // true\ntype.string.extends(/^a.*z$/) // false"
+        },
+        {
+            "group": "Type",
+            "name": "ifExtends",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "narrow this based on an"
+                },
+                {
+                    "kind": "reference",
+                    "value": "extends"
+                },
+                {
+                    "kind": "text",
+                    "value": "check"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ ignores associated"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "meta"
+                    },
+                    {
+                        "kind": "text",
+                        "value": ", which does not affect the set of allowed values"
+                    }
+                ]
+            ],
+            "example": "const n = type(Math.random() > 0.5 ? \"true\" : \"0\") // Type<0 | true>\nconst ez = n.ifExtends(\"boolean\") // Type<true> | undefined"
+        },
+        {
+            "group": "Type",
+            "name": "overlaps",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "check if a value could satisfy this and the parsed Type"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ will return true unless a"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "Disjoint"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "can be proven"
+                    }
+                ]
+            ],
+            "example": "type.string.overlaps(\"string | number\") // true (e.g. \"foo\")\ntype(\"string | number\").overlaps(\"1\") // true (1)\ntype(\"number > 0\").overlaps(\"number < 0\") // false (no values exist)\n\nconst noAt = type(\"string\").narrow(s => !s.includes(\"@\"))\nnoAt.overlaps(\"string.email\") // true (no values exist, but not provable)"
+        },
+        {
+            "group": "Type",
+            "name": "extract",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "extract branches"
+                },
+                {
+                    "kind": "reference",
+                    "value": "extend"
+                },
+                {
+                    "kind": "text",
+                    "value": "ing the parsed Type"
+                }
+            ],
+            "notes": [],
+            "example": "// Type<true | 0 | 2>\nconst t = type(\"boolean | 0 | 'one' | 2 | bigint\").extract(\"number | 0n | true\")"
+        },
+        {
+            "group": "Type",
+            "name": "exclude",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "exclude branches"
+                },
+                {
+                    "kind": "reference",
+                    "value": "extend"
+                },
+                {
+                    "kind": "text",
+                    "value": "ing the parsed Type"
+                }
+            ],
+            "notes": [],
+            "example": "// Type<false | 'one' | bigint>\nconst t = type(\"boolean | 0 | 'one' | 2 | bigint\").exclude(\"number | 0n | true\")"
+        }
+    ],
+    "Traversal": [
+        {
+            "group": "Traversal",
+            "name": "path",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "the path being validated or morphed"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ array indices represented as numbers"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "⚠️ mutated during traversal - use `path.slice(0)` to snapshot"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🔗 use"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "propString"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "for a stringified version"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Traversal",
+            "name": "errors",
+            "summary": [
+                {
+                    "kind": "reference",
+                    "value": "ArkErrors"
+                },
+                {
+                    "kind": "text",
+                    "value": "that will be part of this traversal's finalized result"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ will always be an empty array for a valid traversal"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Traversal",
+            "name": "root",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "the original value being traversed"
+                }
+            ],
+            "notes": []
+        },
+        {
+            "group": "Traversal",
+            "name": "config",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "configuration for this traversal"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ options can affect traversal results and error messages"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ defaults < global config < scope config"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ does not include options configured on individual types"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Traversal",
+            "name": "reject",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "add an"
+                },
+                {
+                    "kind": "reference",
+                    "value": "ArkError"
+                },
+                {
+                    "kind": "text",
+                    "value": "and return `false`"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ useful for predicates like `.narrow`"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Traversal",
+            "name": "mustBe",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "add an"
+                },
+                {
+                    "kind": "reference",
+                    "value": "ArkError"
+                },
+                {
+                    "kind": "text",
+                    "value": "from a description and return `false`"
+                }
+            ],
+            "notes": [
+                [],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ useful for predicates like `.narrow`"
+                    }
+                ],
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "🔗 equivalent to"
+                    },
+                    {
+                        "kind": "reference",
+                        "value": "reject"
+                    },
+                    {
+                        "kind": "text",
+                        "value": "({ expected })"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Traversal",
+            "name": "error",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "add and return an"
+                },
+                {
+                    "kind": "reference",
+                    "value": "ArkError"
+                }
+            ],
+            "notes": [
+                [
+                    {
+                        "kind": "noteStart",
+                        "value": "✅ useful for morphs like `.pipe`"
+                    }
+                ]
+            ]
+        },
+        {
+            "group": "Traversal",
+            "name": "hasError",
+            "summary": [
+                {
+                    "kind": "text",
+                    "value": "whether"
+                },
+                {
+                    "kind": "reference",
+                    "value": "currentBranch"
+                },
+                {
+                    "kind": "text",
+                    "value": "(or the traversal root, outside a union) has one or more errors"
+                }
+            ],
+            "notes": []
+        }
+    ]
 }
diff --git a/ark/docs/components/snippets/contentsById.ts b/ark/docs/components/snippets/contentsById.ts
index 45e4e8ad64..17a2b7e79b 100644
--- a/ark/docs/components/snippets/contentsById.ts
+++ b/ark/docs/components/snippets/contentsById.ts
@@ -1,14 +1,9 @@
+// prettier-ignore
 export default {
-	betterErrors:
-		'import { type, type ArkErrors } from "arktype"\n\nconst user = type({\n\tname: "string",\n\tplatform: "\'android\' | \'ios\'",\n\t"versions?": "(number | string)[]"\n})\n\ninterface RuntimeErrors extends ArkErrors {\n\t/**platform must be "android" or "ios" (was "enigma")\nversions[2] must be a number or a string (was bigint)*/\n\tsummary: string\n}\n\nconst narrowMessage = (e: ArkErrors): e is RuntimeErrors => true\n\n// ---cut---\nconst out = user({\n\tname: "Alan Turing",\n\tplatform: "enigma",\n\tversions: [0, "1", 0n]\n})\n\nif (out instanceof type.errors) {\n\t// ---cut-start---\n\tif (!narrowMessage(out)) throw new Error()\n\t// ---cut-end---\n\t// hover summary to see validation errors\n\tconsole.error(out.summary)\n}\n',
-	clarityAndConcision:
-		'// @errors: 2322\nimport { type } from "arktype"\n// this file is written in JS so that it can include a syntax error\n// without creating a type error while still displaying the error in twoslash\n// ---cut---\n// hover me\nconst user = type({\n\tname: "string",\n\tplatform: "\'android\' | \'ios\'",\n\t"versions?": "number | string)[]"\n})\n',
-	deepIntrospectability:
-		'import { type } from "arktype"\n\nconst user = type({\n\tname: "string",\n\tdevice: {\n\t\tplatform: "\'android\' | \'ios\'",\n\t\t"version?": "number | string"\n\t}\n})\n\n// ---cut---\nuser.extends("object") // true\nuser.extends("string") // false\n// true (string is narrower than unknown)\nuser.extends({\n\tname: "unknown"\n})\n// false (string is wider than "Alan")\nuser.extends({\n\tname: "\'Alan\'"\n})\n',
-	intrinsicOptimization:
-		'import { type } from "arktype"\n// prettier-ignore\n// ---cut---\n// all unions are optimally discriminated\n// even if multiple/nested paths are needed\nconst account = type({\n\tkind: "\'admin\'",\n\t"powers?": "string[]"\n}).or({\n\tkind: "\'superadmin\'",\n\t"superpowers?": "string[]"\n}).or({\n\tkind: "\'pleb\'"\n})\n',
-	unparalleledDx:
-		'// @noErrors\nimport { type } from "arktype"\n// prettier-ignore\n// ---cut---\nconst user = type({\n\tname: "string",\n\tplatform: "\'android\' | \'ios\'",\n\t"version?": "number | s"\n\t//                     ^|\n})\n',
-	nestedTypeInScopeError:
-		'// @errors: 2322\nimport { scope } from "arktype"\n// ---cut---\nconst myScope = scope({\n\tid: "string#id",\n\tuser: type({\n\t\tname: "string",\n\t\tid: "id"\n\t})\n})\n'
+    "betterErrors": "import { type, type ArkErrors } from \"arktype\"\n\nconst user = type({\n\tname: \"string\",\n\tplatform: \"'android' | 'ios'\",\n\t\"versions?\": \"(number | string)[]\"\n})\n\ninterface RuntimeErrors extends ArkErrors {\n\t/**platform must be \"android\" or \"ios\" (was \"enigma\")\nversions[2] must be a number or a string (was bigint)*/\n\tsummary: string\n}\n\nconst narrowMessage = (e: ArkErrors): e is RuntimeErrors => true\n\n// ---cut---\nconst out = user({\n\tname: \"Alan Turing\",\n\tplatform: \"enigma\",\n\tversions: [0, \"1\", 0n]\n})\n\nif (out instanceof type.errors) {\n\t// ---cut-start---\n\tif (!narrowMessage(out)) throw new Error()\n\t// ---cut-end---\n\t// hover summary to see validation errors\n\tconsole.error(out.summary)\n}",
+    "clarityAndConcision": "// @errors: 2322\nimport { type } from \"arktype\"\n// this file is written in JS so that it can include a syntax error\n// without creating a type error while still displaying the error in twoslash\n// ---cut---\n// hover me\nconst user = type({\n\tname: \"string\",\n\tplatform: \"'android' | 'ios'\",\n\t\"versions?\": \"number | string)[]\"\n})",
+    "deepIntrospectability": "import { type } from \"arktype\"\n\nconst user = type({\n\tname: \"string\",\n\tdevice: {\n\t\tplatform: \"'android' | 'ios'\",\n\t\t\"version?\": \"number | string\"\n\t}\n})\n\n// ---cut---\nuser.extends(\"object\") // true\nuser.extends(\"string\") // false\n// true (string is narrower than unknown)\nuser.extends({\n\tname: \"unknown\"\n})\n// false (string is wider than \"Alan\")\nuser.extends({\n\tname: \"'Alan'\"\n})",
+    "intrinsicOptimization": "import { type } from \"arktype\"\n// prettier-ignore\n// ---cut---\n// all unions are optimally discriminated\n// even if multiple/nested paths are needed\nconst account = type({\n\tkind: \"'admin'\",\n\t\"powers?\": \"string[]\"\n}).or({\n\tkind: \"'superadmin'\",\n\t\"superpowers?\": \"string[]\"\n}).or({\n\tkind: \"'pleb'\"\n})",
+    "unparalleledDx": "// @noErrors\nimport { type } from \"arktype\"\n// prettier-ignore\n// ---cut---\nconst user = type({\n\tname: \"string\",\n\tplatform: \"'android' | 'ios'\",\n\t\"version?\": \"number | s\"\n\t//                     ^|\n})",
+    "nestedTypeInScopeError": "// @errors: 2322\nimport { scope } from \"arktype\"\n// ---cut---\nconst myScope = scope({\n\tid: \"string#id\",\n\tuser: type({\n\t\tname: \"string\",\n\t\tid: \"id\"\n\t})\n})"
 }
diff --git a/ark/docs/content/docs/blog/2.0.mdx b/ark/docs/content/docs/blog/2.0.mdx
new file mode 100644
index 0000000000..7e8ed8b4a3
--- /dev/null
+++ b/ark/docs/content/docs/blog/2.0.mdx
@@ -0,0 +1,52 @@
+---
+title: Announcing ArkType 2.0
+description: 100x faster validation with DX that will blow your mind
+---
+
+import { CodeBlock } from "../../../components/CodeBlock.tsx"
+import { RuntimeBenchmarksGraph } from "../../../components/RuntimeBenchmarksGraph.tsx"
+
+As of today, `arktype@2.0.0` is generally available and fully stable.
+
+ArkType 2.0 brings types to runtime JS in a way that, until today, was a pipedream. Whether you're a first-time TypeScript dev trying to validate a form or a library author introspecting relationships, ArkType offers fundamentally better tools for navigating the perils of JavaScript.
+
+### Unparalleled DX
+
+Type syntax you already know with safety and completions unlike anything
+you&apos;ve ever seen
+
+<CodeBlock fromFile="unparalleledDx" includesCompletions />
+
+### Faster... everything
+
+100x faster than Zod at runtime with editor performance that will remind you
+how autocomplete is supposed to feel
+
+<RuntimeBenchmarksGraph className="mt-2" />
+
+### Clarity and Concision
+
+Definitions are half as long, type errors are twice as readable, and hovers
+tell you just what really matters
+
+<CodeBlock fromFile="clarityAndConcision" />
+
+### Better Errors
+
+Deeply customizable messages with great defaults
+
+<CodeBlock fromFile="betterErrors" />
+
+### Deep Introspectability
+
+ArkType uses set theory to understand and expose the relationships between
+your types at runtime the way TypeScript does at compile time
+
+<CodeBlock fromFile="deepIntrospectability" />
+
+### Intrinsic Optimization
+
+Every schema is internally normalized and reduced to its purest and fastest
+representation
+
+<CodeBlock fromFile="intrinsicOptimization" />
diff --git a/ark/docs/content/docs/blog/index.mdx b/ark/docs/content/docs/blog/index.mdx
new file mode 100644
index 0000000000..d6c275dfa9
--- /dev/null
+++ b/ark/docs/content/docs/blog/index.mdx
@@ -0,0 +1,11 @@
+---
+title: Posts
+---
+
+import { LinkCard } from "../../../components/LinkCard.tsx"
+
+<LinkCard
+	title="Announcing ArkType 2.0"
+	description="100x faster validation with DX that will blow your mind"
+	href="/docs/blog/2.0"
+/>
diff --git a/ark/docs/content/docs/blog/meta.json b/ark/docs/content/docs/blog/meta.json
new file mode 100644
index 0000000000..d89f5afbfb
--- /dev/null
+++ b/ark/docs/content/docs/blog/meta.json
@@ -0,0 +1,5 @@
+{
+	"title": "Blog",
+	"defaultOpen": true,
+	"pages": ["[2.0 Announcement](/docs/blog/2.0)"]
+}
diff --git a/ark/docs/content/docs/configuration/index.mdx b/ark/docs/content/docs/configuration/index.mdx
index dffee6c9b2..b4c119bf7f 100644
--- a/ark/docs/content/docs/configuration/index.mdx
+++ b/ark/docs/content/docs/configuration/index.mdx
@@ -2,9 +2,237 @@
 title: Configuration
 ---
 
+A great out-of-the-box experience is a core goal of ArkType, including safe defaults and helpful messages for complex errors.
+
+However, it's equally important that when you need different behavior, you can easily configure it with the right granularity.
+
+<table>
+  <thead>
+    <tr>
+      <th>Level</th>
+      <th>Applies To</th>
+      <th>Example</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>**default**</td>
+      <td>built-in defaults for all Types</td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>**global**</td>
+      <td>all Types parsed after the config is applied</td>
+      <td>
+```ts
+import { configure } from "arktype/config"
+// importing from "arktype/config" first is recommended (see note)
+configure({ numberAllowsNaN: true })
+
+import { type } from "arktype"
+// true
+type.number.allows(Number.NaN) 
+```
+     </td>
+    </tr>
+    <tr>
+      <td>**scope**</td>
+      <td>all Types parsed in the configured Scope</td>
+      <td>
+```ts
+const closedObjectScope = scope(
+	{ user: {  name: "string" } },
+	{ onUndeclaredKey: "reject" }
+)
+const types = closedObjectScope.export()
+// ArkErrors: age must be removed
+types.user({ name: "Alice", age: 99 })
+const parsedAfter = closedObjectScope.type({
+  name: "string"
+})
+// ArkErrors: age must be removed
+parsedAfter({ name: "Alice", age: 99 })
+```
+      </td>
+    </tr>
+    <tr>
+      <td>**type**</td>
+      <td>all Types shallowly referenced by the configured Type</td>
+      <td>
+```ts
+// avoid logging "was xxx" for password
+const password = type("string >= 8").configure({ actual: () => "" })
+const user = type({
+	email: "string.email",
+	password
+})
+// ArkErrors: password must be at least length 8
+const out = user({
+	email: "david@arktype.io",
+	password: "ez123"
+})
+```
+
+      </td>
+    </tr>
+
+  </tbody>
+</table>
+
+Some options only apply at specific levels, as reflected in the corresponding input types.
+
+<Callout
+	type="warn"
+	title='Use the `"arktype/config"` entrypoint if for global config!'
+>
+	If you need your config to apply to built-in keywords (important for options
+	like `jitless`, `numberAllowsNaN`, `dateAllowsInvalid`), you should import and
+	`configure` from `"arktype/config"` before importing anything from
+	`"arktype"`.
+
+Otherwise, keywords will have already been parsed by the time your config applies!
+
+</Callout>
+
 ### Errors
 
-🚧 Coming soon ™️🚧
+To allow custom errors to be integrated seemlessly with built-in logic for composite errors (i.e. `union` and `intersection`), ArkType supports a set of composable options:
+
+<table>
+<thead>
+<tr>
+<th>optional</th>
+<th>description</th>
+<th>example</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>**description**</td>
+<td>
+✅ a summary of the constraint that could complete the phrase "must be ___"
+
+🥇 reused by other metadata and should be your first go-to for customizing a message
+
+</td>
+<td>
+```ts
+const password = type.string.atLeastLength(8).describe("a valid password")
+// ArkErrors: must be a valid password
+const out = password("ez123")
+```
+</td>
+</tr>
+<tr>
+<td>**expected**</td>
+<td>
+✅ a function accepting the error context and returning a string of the format "must be ___"
+
+✅ specific to errors and takes precedence over `description` in those cases
+
+</td>
+    <td>
+```ts
+const password = type.string.atLeastLength(8).configure({
+	expected: ctx =>
+		ctx.code === "minLength" ? `${ctx.rule} characters or better` : "way better"
+})
+// ArkErrors: must be 8 characters or better (was 5)
+const out1 = password("ez123").toString()
+// ArkErrors: must be way better (was a number)
+const out2 = password(12345678).toString()
+```
+</td>
+</tr>
+<tr>
+<td>**actual**</td>
+<td>
+✅ a function accepting the data that caused the error and returning a string of the format "(was ___)"
+
+✅ if an empty string is returned, the actual portion of the message will be omitted
+
+</td>
+    <td>
+```ts
+const password = type("string >= 8").configure({ actual: () => "" })
+// ArkErrors: password must be at least length 8
+const out = password("ez123")
+```
+</td>
+</tr>
+<tr>
+<td>**problem**</td>
+<td>
+✅ a function accepting the results of `expected` and `actual` in addition to other context and returning a complete description of the problem like "must be a string (was a number)"
+
+❌ may not apply to composite errors like unions
+
+</td>
+<td>
+```ts
+const password = type("string >= 8").configure({
+	problem: ctx => `${ctx.actual} isn't ${ctx.expected}`
+})
+// ArkErrors: 5 isn't at least length 8
+const out1 = password("ez123")
+// ArkErrors: a number isn't a string
+const out2 = password(12345678)
+```
+</td>
+</tr>
+<tr>
+<td>**message**</td>
+<td>
+✅ a function accepting the result of `problem` in addition to other context and returning a complete description of the problem including the path at which it occurred
+
+❌ may not apply to composite errors like unions
+
+</td>
+<td>
+```ts
+const user = type({
+	password: "string >= 8"
+}).configure({
+	message: ctx =>
+		`${ctx.propString || "(root)"}: ${ctx.actual} isn't ${ctx.expected}`
+})
+// ArkErrors: (root): a string isn't an object
+const out1 = user("ez123")
+// `.configure` only applies shallowly, so the nested error isn't changed!
+// ArkErrors: password must be at least length 8 (was 5)
+const out2 = user({ password: "ez123" })
+```
+</td>
+</tr>
+</tbody>
+</table>
+
+#### By Code
+
+Errors can also be configured by their associated `code` property at a _scope_ or _global_ level.
+
+For example:
+
+```ts
+const mod = type.module(
+	{ isEven: "number%2" },
+	{
+		divisor: {
+			// the available `ctx` types will include data specific to your errors
+			expected: ctx => `% ${ctx.rule} !== 0`,
+			problem: ctx => `${ctx.actual} ${ctx.expected}`
+		}
+	}
+)
+// ArkErrors: 3 % 2 !== 0
+mod.isEven(3)
+```
+
+#### ArkErrors
+
+For use cases like i18n that fall outside the scope of this composable message config, the `ArkErrors` array returned on validation failure contains `ArkError` instances that can be discriminated via calls like `.hasCode("divisor")` and contain contextual data specific to that error type as well as getters for each composable error part.
+
+These `ArkError` instances can be arbitrarily transformed and composed with an internationalization library. This is still a topic we're working on investigating and documenting, so please reach out with any questions or feedback!
 
 ### Clone
 
@@ -50,7 +278,31 @@ console.log(formData.age)
 
 ### onUndeclaredKey
 
-🚧 Coming soon ™️🚧
+Like TypeScript, ArkType defaults to ignoring undeclared keys during validation. However, it also supports two additional behaviors:
+
+- `"ignore"` (default): Allow undeclared keys on input, preserve them on output
+- `"delete"`: Allow undeclared keys on input, delete them before returning output
+- `"reject"`: Reject input with undeclared keys
+
+These behaviors can be associated with individual Types via the builtin `"+"` syntax (see [those docs](/docs/objects/properties-undeclared) for more on how they work). You can also change the default globally:
+
+```ts
+import { configure } from "arktype/config"
+
+configure({ onUndeclaredKey: "delete" })
+
+import { type } from "arktype"
+
+const userForm = type({
+	name: "string"
+})
+
+// out is now { name: "Alice" }
+const out = userForm({
+	name: "Alice",
+	age: "42"
+})
+```
 
 ### jitless
 
@@ -61,10 +313,6 @@ If you'd like to opt out of it for another reason, you can set the `jitless` con
 ```ts
 import { configure } from "arktype/config"
 
-// IMPORTANT: make sure you import from the "arktype/config" entry point
-// and invoke configure before importing anything else from ArkType
-// unless you want the builtin types to be precompiled
-
 configure({ jitless: true })
 
 import { type } from "arktype"
diff --git a/ark/docs/content/docs/configuration/meta.json b/ark/docs/content/docs/configuration/meta.json
index fabb09c530..b809fc8dad 100644
--- a/ark/docs/content/docs/configuration/meta.json
+++ b/ark/docs/content/docs/configuration/meta.json
@@ -3,7 +3,7 @@
 	"pages": [
 		"[errors](/docs/configuration#errors)",
 		"[clone](/docs/configuration#clone)",
-		"[onUndeclaredKey](/docs/configuration#onUndeclaredKey)",
+		"[onUndeclaredKey](/docs/configuration#onundeclaredkey)",
 		"[jitless](/docs/configuration#jitless)"
 	]
 }
diff --git a/ark/docs/content/docs/expressions/index.mdx b/ark/docs/content/docs/expressions/index.mdx
index 30be2d6d74..5989edffbb 100644
--- a/ark/docs/content/docs/expressions/index.mdx
+++ b/ark/docs/content/docs/expressions/index.mdx
@@ -118,6 +118,47 @@ const unions = type({
 
 </SyntaxTabs>
 
+<a id="union-morphs" />
+
+<Callout
+	type="warn"
+	title="A union that could apply different morphs to the same data throws a ParseError!"
+>
+```ts
+// operands overlap, but neither transforms data
+const okay = type("number > 0").or("number < 10")
+// operand transforms data, but there's no overlap between the inputs
+const alsoOkay = type("string.numeric.parse").or({ box: "string" })
+// operands overlap and transform data, but in the same way
+const stillOkay = type("string > 5", "=>", Number.parseFloat).or([
+	"0 < string < 10",
+	"=>",
+	Number.parseFloat
+])
+// ParseError: An unordered union of a type including a morph and a type with overlapping input is indeterminate
+const bad = type({ box: "string.numeric.parse" }).or({ box: "string" })
+const sameError = type({ a: "string.numeric.parse" }).or({ b: "string.numeric.parse" })
+```
+
+<details>
+	<summary>Learn the basic set theory behind this restriction</summary>
+
+If you're relatively new to set-based types, that error might be daunting, but if you take a second to think through the example, it becomes clear why this isn't allowed. The logic of `bad` is essentially:
+
+- If the input is an object where `box` is a `string`, parse and return it as a number
+- If the input is an object where `box` is a `string`, return it as a string
+
+There is no way to deterministically return an output for this type without sacrificing the [commutativity](https://en.wikipedia.org/wiki/Commutative_property) of the union operator.
+
+`sameError` may look more innocuous, but has the same problem for an input like `{ a: "1", b: "2" }`.
+
+- Left branch would only parse `a`, resulting in `{ a: 1, b: "2" }`
+- Right branch would only parse `b`, resulting in `{ a: "1", b: 2 }`
+
+</details>
+
+</Callout>
+
 ### Brand
 
 Add a type-only symbol to an existing type so that the only values that satisfy is are those that have been directly validated.
diff --git a/ark/docs/content/docs/meta.json b/ark/docs/content/docs/meta.json
index cb8fa6f63e..5be9f669f8 100644
--- a/ark/docs/content/docs/meta.json
+++ b/ark/docs/content/docs/meta.json
@@ -5,11 +5,13 @@
 		"objects",
 		"keywords",
 		"expressions",
-		"type-api",
 		"configuration",
+		"type-api",
+		"traversal-api",
 		"integrations",
 		"scopes",
 		"generics",
+		"blog",
 		"faq"
 	]
 }
diff --git a/ark/docs/content/docs/traversal-api.mdx b/ark/docs/content/docs/traversal-api.mdx
new file mode 100644
index 0000000000..ff82b9fce8
--- /dev/null
+++ b/ark/docs/content/docs/traversal-api.mdx
@@ -0,0 +1,7 @@
+---
+title: Traversal API
+---
+
+import { ApiTable } from "../../components/ApiTable.tsx"
+
+<ApiTable group="Traversal" />
diff --git a/ark/docs/content/docs/type-api.mdx b/ark/docs/content/docs/type-api.mdx
index 1e9d7482d6..a0cfcda280 100644
--- a/ark/docs/content/docs/type-api.mdx
+++ b/ark/docs/content/docs/type-api.mdx
@@ -5,11 +5,3 @@ title: Type API
 import { ApiTable } from "../../components/ApiTable.tsx"
 
 <ApiTable group="Type" />
-
-### Properties
-
-🚧 Coming soon ™️🚧
-
-### Utilities
-
-🚧 Coming soon ™️🚧
diff --git a/ark/docs/lib/shiki.ts b/ark/docs/lib/shiki.ts
index 9cf03769a7..cf4b6213c7 100644
--- a/ark/docs/lib/shiki.ts
+++ b/ark/docs/lib/shiki.ts
@@ -2,6 +2,7 @@ import { transformerNotationErrorLevel } from "@shikijs/transformers"
 import type { RehypeCodeOptions } from "fumadocs-core/mdx-plugins"
 import { transformerTwoslash } from "fumadocs-twoslash"
 import { createRequire } from "node:module"
+import type { ShikiTransformer } from "shiki"
 
 /** for some reason a standard import with an attribute like:
  
@@ -74,11 +75,11 @@ declare global {
 					if (node.text.startsWith("const")) {
 						// show type with completions populated for known examples
 						node.text = node.text.replace(
-							"version?: never",
+							"version?: undefined",
 							`version?: number | string`
 						)
 						node.text = node.text.replace(
-							"versions?: never",
+							"versions?: undefined",
 							"versions?: (number | string)[]"
 						)
 						// filter out the type of Type's invocation
@@ -131,13 +132,40 @@ declare global {
 	}
 })
 
+type HastElement = Parameters<ShikiTransformer["line"] & {}>[0]
+const descendantIncludesText = (
+	node: HastElement,
+	...texts: string[]
+): boolean =>
+	node.children &&
+	node.children.some(
+		c =>
+			(c.type === "text" && texts.some(s => c.value.includes(s))) ||
+			descendantIncludesText(c as never, ...texts)
+	)
+
 export const shikiConfig = {
 	themes: {
 		dark: arkDarkTheme,
 		light: arkDarkTheme
 	},
 	langs: ["json", "bash", { ...arkTypeTmJson, name: "ts" }],
-	transformers: [twoslash, transformerNotationErrorLevel()]
+	transformers: [
+		{
+			line(node) {
+				if (descendantIncludesText(node, "// ArkErrors:", "// ParseError:")) {
+					this.addClassToHast(node, "highlighted")
+					this.addClassToHast(node, "error")
+					this.addClassToHast(node, "runtime-error")
+				} else if (descendantIncludesText(node, "// TypeScript:")) {
+					this.addClassToHast(node, "highlighted")
+					this.addClassToHast(node, "error")
+				}
+			}
+		},
+		twoslash,
+		transformerNotationErrorLevel()
+	]
 } as const satisfies RehypeCodeOptions
 
 export type shikiConfig = typeof shikiConfig
diff --git a/ark/docs/lib/writeSnippetsEntrypoint.ts b/ark/docs/lib/writeSnippetsEntrypoint.ts
index 0866c54330..a494ba9324 100644
--- a/ark/docs/lib/writeSnippetsEntrypoint.ts
+++ b/ark/docs/lib/writeSnippetsEntrypoint.ts
@@ -1,4 +1,4 @@
-import { fromHere, readFile, shell, writeFile } from "@ark/fs"
+import { fromHere, readFile, writeFile } from "@ark/fs"
 import { flatMorph, throwInternalError } from "@ark/util"
 import { existsSync } from "fs"
 
@@ -27,17 +27,16 @@ export const updateSnippetsEntrypoint = () => {
 			: throwInternalError(
 					`Expected a snippet file at ${tsPath} or ${jsPath} (neither existed).`
 				)
-		return [id, readFile(path)]
+		// don't include trailing newline
+		return [id, readFile(path).trimEnd()]
 	})
 
 	const toPath = snippetPath("contentsById.ts")
 
-	const contents = `export default ${JSON.stringify(snippetContentsById, null, 4)}`
+	const contents = `// prettier-ignore\nexport default ${JSON.stringify(snippetContentsById, null, 4)}\n`
 
-	if (!existsSync(toPath) || readFile(toPath) !== contents) {
+	if (!existsSync(toPath) || readFile(toPath) !== contents)
 		writeFile(toPath, contents)
-		shell(`pnpm prettier --write ${toPath}`)
-	}
 }
 
 const snippetIds = [
diff --git a/ark/docs/package.json b/ark/docs/package.json
index 8af8c7cc16..030de07a5c 100644
--- a/ark/docs/package.json
+++ b/ark/docs/package.json
@@ -15,30 +15,30 @@
 	"dependencies": {
 		"@ark/fs": "workspace:*",
 		"@ark/util": "workspace:*",
-		"@fumadocs/cli": "0.0.6",
-		"@icons-pack/react-simple-icons": "10.2.0",
-		"@shikijs/transformers": "1.26.1",
+		"@fumadocs/cli": "0.0.7",
+		"@icons-pack/react-simple-icons": "11.0.1",
+		"@shikijs/transformers": "1.27.2",
 		"@types/mdx": "2.0.13",
-		"@types/react": "19.0.2",
-		"@types/react-dom": "19.0.2",
+		"@types/react": "19.0.7",
+		"@types/react-dom": "19.0.3",
 		"arkdark": "workspace:*",
 		"arktype": "workspace:*",
 		"autoprefixer": "10.4.20",
 		"class-variance-authority": "0.7.1",
-		"framer-motion": "11.15.0",
-		"fumadocs-core": "14.6.8",
-		"fumadocs-mdx": "11.2.1",
+		"framer-motion": "11.18.0",
+		"fumadocs-core": "14.7.4",
+		"fumadocs-mdx": "11.3.1",
 		"fumadocs-twoslash": "2.0.2",
-		"fumadocs-ui": "14.6.8",
+		"fumadocs-ui": "14.7.4",
 		"hast-util-to-jsx-runtime": "2.3.2",
 		"linkinator": "6.1.2",
-		"lucide-react": "0.469.0",
-		"next": "15.1.3",
-		"postcss": "8.4.49",
-		"prettier-plugin-tailwindcss": "0.6.9",
+		"lucide-react": "0.471.1",
+		"next": "15.1.4",
+		"postcss": "8.5.1",
+		"prettier-plugin-tailwindcss": "0.6.10",
 		"react": "19.0.0",
 		"react-dom": "19.0.0",
-		"shiki": "1.26.1",
+		"shiki": "1.27.2",
 		"tailwindcss": "3.4.17",
 		"ts-morph": "25.0.0",
 		"twoslash": "0.2.12",
diff --git a/ark/fast-check/arbitraries/date.ts b/ark/fast-check/arbitraries/date.ts
index 242d9b43f5..94557c966a 100644
--- a/ark/fast-check/arbitraries/date.ts
+++ b/ark/fast-check/arbitraries/date.ts
@@ -6,8 +6,8 @@ export const buildDateArbitrary = (
 ): fc.Arbitrary<Date> => {
 	if (node.hasKind("intersection")) {
 		const fastCheckDateConstraints: fc.DateConstraints = {}
-		if (node.after) fastCheckDateConstraints.min = node.after.rule
-		if (node.before) fastCheckDateConstraints.max = node.before.rule
+		if (node.inner.after) fastCheckDateConstraints.min = node.inner.after.rule
+		if (node.inner.before) fastCheckDateConstraints.max = node.inner.before.rule
 
 		return fc.date(fastCheckDateConstraints)
 	}
diff --git a/ark/fast-check/arbitraries/number.ts b/ark/fast-check/arbitraries/number.ts
index 95669a7c77..8d52cff011 100644
--- a/ark/fast-check/arbitraries/number.ts
+++ b/ark/fast-check/arbitraries/number.ts
@@ -1,13 +1,17 @@
-import type { nodeOfKind, RefinementKind } from "@ark/schema"
-import { hasKey, nearestFloat, throwInternalError, type array } from "@ark/util"
+import type { IntersectionNode } from "@ark/schema"
+import { hasKey, nearestFloat, throwInternalError } from "@ark/util"
 import * as fc from "fast-check"
 import type { DomainInputNode } from "./domain.ts"
 
 export const buildNumberArbitrary = (
 	node: DomainInputNode
 ): fc.Arbitrary<number> => {
-	if (node.hasKind("domain")) return fc.integer()
-	const numberConstraints = getFastCheckNumberConstraints(node.refinements)
+	if (node.hasKind("domain")) {
+		return fc.double({
+			noNaN: !node.numberAllowsNaN
+		})
+	}
+	const numberConstraints = getFastCheckNumberConstraints(node)
 	const hasMax = hasKey(numberConstraints, "max")
 	const hasMin = hasKey(numberConstraints, "min")
 
@@ -64,16 +68,17 @@ export const buildNumberArbitrary = (
 	return integersDivisibleByDivisor
 }
 
-const getFastCheckNumberConstraints = (
-	refinements: array<nodeOfKind<RefinementKind>>
-) => {
-	const hasDivisor = refinements.find(refinement =>
+const getFastCheckNumberConstraints = (node: IntersectionNode) => {
+	const hasDivisor = node.refinements.find(refinement =>
 		refinement.hasKind("divisor")
 	)
-	const numberConstraints: fc.IntegerConstraints & {
+	const numberConstraints: fc.DoubleConstraints & {
 		divisor?: number
-	} = {}
-	for (const refinement of refinements) {
+	} = {
+		noNaN: !node.inner.domain?.numberAllowsNaN
+	}
+
+	for (const refinement of node.refinements) {
 		if (refinement.hasKindIn("min", "max")) {
 			let rule = refinement.rule
 			if ("exclusive" in refinement) {
diff --git a/ark/fast-check/arktypeFastCheck.ts b/ark/fast-check/arktypeFastCheck.ts
index eb7490eb4f..c8b16f4315 100644
--- a/ark/fast-check/arktypeFastCheck.ts
+++ b/ark/fast-check/arktypeFastCheck.ts
@@ -110,11 +110,13 @@ export const buildStructureArbitrary = (
 		return buildObjectArbitrary(structure, ctx)
 	}
 
-	if (node.exactLength?.rule === 0) return fc.tuple()
+	if (node.inner.exactLength?.rule === 0) return fc.tuple()
 
 	const fcArrayConstraints: fc.ArrayConstraints = {}
-	if (node.minLength) fcArrayConstraints.minLength = node.minLength.rule
-	if (node.maxLength) fcArrayConstraints.maxLength = node.maxLength.rule
+	if (node.inner.minLength)
+		fcArrayConstraints.minLength = node.inner.minLength.rule
+	if (node.inner.maxLength)
+		fcArrayConstraints.maxLength = node.inner.maxLength.rule
 
 	const arrArbitrary =
 		structure?.sequence ?
diff --git a/ark/fs/package.json b/ark/fs/package.json
index 4f6b4e6da2..f99b238d34 100644
--- a/ark/fs/package.json
+++ b/ark/fs/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@ark/fs",
-	"version": "0.33.0",
+	"version": "0.34.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",
diff --git a/ark/repo/build.ts b/ark/repo/build.ts
index f359d94911..4ba24115cb 100644
--- a/ark/repo/build.ts
+++ b/ark/repo/build.ts
@@ -9,7 +9,7 @@ import {
 	shell,
 	writeJson
 } from "../fs/index.ts"
-import { buildApi } from "./jsdocGen.ts"
+import { buildApi } from "./jsDocGen.ts"
 
 const buildKind =
 	process.argv.includes("--cjs") || process.env.ARKTYPE_CJS ? "cjs" : "esm"
diff --git a/ark/repo/jsdocGen.ts b/ark/repo/jsDocGen.ts
similarity index 59%
rename from ark/repo/jsdocGen.ts
rename to ark/repo/jsDocGen.ts
index 45c78c30ae..65bb78cf8b 100644
--- a/ark/repo/jsdocGen.ts
+++ b/ark/repo/jsDocGen.ts
@@ -11,24 +11,44 @@ import {
 import ts from "typescript"
 import { bootstrapFs, bootstrapUtil, repoDirs } from "./shared.ts"
 
-const { flatMorph, includes, throwInternalError } = bootstrapUtil
-const { writeFile, shell } = bootstrapFs
+const { flatMorph, throwInternalError, emojiToUnicode } = bootstrapUtil
+const { writeFile } = bootstrapFs
 
 const inheritDocToken = "@inheritDoc"
-const typeOnlyToken = "@typeonly"
-const typeOnlyMessage =
-	"- 🥸 Inference-only property that will be `undefined` at runtime"
-const typeNoopToken = "@typenoop"
-const typeNoopMessage = "- 🥸 Inference-only function that does nothing runtime"
 
-const arkTypeBuildDir = join(repoDirs.arkDir, "type", "out")
-const jsdocSourcesGlob = `${arkTypeBuildDir}/**/*.d.ts`
+// used to delimit notes in JSDoc.
+// add to the list if you need new ones!
+const noteEmoji = ["✅", "🥸", "⚠️", "🔗"]
+
+const noteEmojiUnicode = noteEmoji.map(emojiToUnicode)
+const noteDelimiterRegex = new RegExp(`(?=\\n\\s*[-${noteEmojiUnicode}])`, "u")
+
+const replacedDecorators = {
+	"@typeonly": "🥸 inference-only property that will be `undefined` at runtime",
+	"@typenoop": "🥸 inference-only function that does nothing runtime",
+	"@chainedDefinition":
+		"⚠️ unlike most other methods, this creates a definition rather than a Type (read why)",
+	"@predicateCast":
+		"🥸 {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates | Type predicates} can be used as casts",
+	"@ignoresMeta":
+		"✅ ignores associated {@link meta}, which does not affect the set of allowed values",
+	"@propString":
+		"✅ uses `.access` {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors#dot_notation | where allowed by JS}, falling back to `[indexAccess]`\n" +
+		`@example
+const path = ["key1", Symbol("key2"), "key3", 4, "~key5"]
+const propString = 'key1[Symbol(key2)].key3[4]["~key5"]'`
+} as const
+
+const typeBuildDir = join(repoDirs.arkDir, "type", "out")
+const typeBuildGlob = `${typeBuildDir}/**/*.d.ts`
+const schemaBuildDir = join(repoDirs.arkDir, "schema", "out")
+const schemaBuildGlob = `${schemaBuildDir}/**/*.d.ts`
 
 let updateCount = 0
 
 export const buildApi = () => {
 	const project = createProject()
-	jsdocGen(project)
+	jsDocGen(project)
 	const docs = getAllJsDoc(project)
 
 	const apiDocsByGroup = flatMorph(docs, (i, doc) => {
@@ -43,19 +63,19 @@ export const buildApi = () => {
 
 	writeFile(
 		apiDataPath,
-		`import type { ApiDocsByGroup } from "../../repo/jsdocGen.ts"
+		`import type { ApiDocsByGroup } from "../../repo/jsDocGen.ts"
 
-export const apiDocsByGroup: ApiDocsByGroup = ${JSON.stringify(apiDocsByGroup, null, 4)}`
+/** THIS FILE IS AUTOGENERATED FROM ark/repo/jsDocGen.ts **/
+// prettier-ignore
+export const apiDocsByGroup: ApiDocsByGroup = ${JSON.stringify(apiDocsByGroup, null, 4)}\n`
 	)
-
-	shell(`prettier --write ${apiDataPath}`)
 }
 
-export const jsdocGen = (project: Project) => {
+export const jsDocGen = (project: Project) => {
 	const sourceFiles = project.getSourceFiles()
 
 	console.log(
-		`✍️ Generating JSDoc for ${sourceFiles.length} files in ${arkTypeBuildDir}...`
+		`✍️ Generating JSDoc for ${sourceFiles.length} files in ${typeBuildDir} and ${schemaBuildDir}...`
 	)
 
 	project.getSourceFiles().forEach(docgenForFile)
@@ -75,28 +95,21 @@ export const getAllJsDoc = (project: Project) => {
 	)
 }
 
-const apiGroups = ["Type"] as const
-
-export type ApiGroup = (typeof apiGroups)[number]
-
-export type JsdocComment = ReturnType<JSDoc["getComment"]>
+export type ApiGroup = "Type" | "Traversal"
 
-export type JsdocPart = Extract<JsdocComment, readonly unknown[]>[number] & {}
+export type JsDocComment = ReturnType<JSDoc["getComment"]>
 
-export type ParsedJsDocPart = ShallowJsDocPart | ParsedJsDocTag
+export type RawJsDocPart = Extract<
+	JsDocComment,
+	readonly unknown[]
+>[number] & {}
 
-export type ShallowJsDocPart =
+export type ParsedJsDocPart =
 	| { kind: "text"; value: string }
 	| { kind: "noteStart"; value: string }
 	| { kind: "reference"; value: string }
 	| { kind: "link"; value: string; url: string }
 
-export type ParsedJsDocTag = {
-	kind: "tag"
-	name: string
-	value: ParsedJsDocPart[]
-}
-
 export type ApiDocsByGroup = {
 	readonly [k in ApiGroup]: readonly ParsedJsDocBlock[]
 }
@@ -112,32 +125,37 @@ export type ParsedJsDocBlock = {
 const createProject = () => {
 	const project = new Project()
 
-	if (!existsSync(arkTypeBuildDir)) {
-		throw new Error(
-			`jsdocGen rewrites ${arkTypeBuildDir} but that directory doesn't exist. Did you run "pnpm build" there first?`
-		)
-	}
+	assertBuildDirExists(typeBuildDir)
+	assertBuildDirExists(schemaBuildDir)
 
-	project.addSourceFilesAtPaths(jsdocSourcesGlob)
+	project.addSourceFilesAtPaths(typeBuildGlob)
+	project.addSourceFilesAtPaths(schemaBuildGlob)
 
 	return project
 }
 
+const assertBuildDirExists = (path: string) => {
+	if (!existsSync(path)) {
+		throw new Error(
+			`jsDocGen rewrites ${path} but that directory doesn't exist. Did you run "pnpm build" there first?`
+		)
+	}
+}
+
 const parseBlock = (doc: JSDoc): ParsedJsDocBlock | undefined => {
 	const name = doc.getNextSiblingIfKind(SyntaxKind.Identifier)?.getText()
 
 	if (!name) return
 
-	const tags = doc.getTags()
-	const group = tags.find(t => t.getTagName() === "api")?.getCommentText()
+	const filePath = doc.getSourceFile().getFilePath()
+	let group: ApiGroup
+	if (filePath.includes("methods")) group = "Type"
+	else if (filePath.endsWith("traversal.d.ts")) group = "Traversal"
+	else return
 
-	if (!group) return
+	if (!doc.getInnerText().trim().startsWith("#")) return
 
-	if (!includes(apiGroups, group)) {
-		return throwInternalError(
-			`Invalid API group ${group} for name ${name}. Should be defined like @api Type`
-		)
-	}
+	const tags = doc.getTags()
 
 	const rootComment = doc.getComment()
 
@@ -146,15 +164,21 @@ const parseBlock = (doc: JSDoc): ParsedJsDocBlock | undefined => {
 
 	const allParts: ParsedJsDocPart[] =
 		typeof rootComment === "string" ?
-			parseJsdocText(rootComment)
+			parseJsDocText(rootComment)
 			// remove any undefined parts before parsing
-		:	rootComment.filter(part => !!part).flatMap(parseJsdocPart)
+		:	rootComment.filter(part => !!part).flatMap(parseJsDocPart)
 
 	const summaryParts: ParsedJsDocPart[] = []
 	const notePartGroups: ParsedJsDocPart[][] = []
 
+	if (allParts[0].kind === "text") {
+		allParts[0].value = allParts[0].value.replace(/^#+\s*/, "")
+		if (allParts[0].value === "") allParts.shift()
+	}
+
 	allParts.forEach(part => {
-		if (part.kind === "noteStart") notePartGroups.push([part])
+		if (part.kind === "noteStart") notePartGroups.push(part.value ? [part] : [])
+		else if (part.value === "") return
 		else if (notePartGroups.length) notePartGroups.at(-1)!.push(part)
 		else summaryParts.push(part)
 	})
@@ -172,12 +196,12 @@ const parseBlock = (doc: JSDoc): ParsedJsDocBlock | undefined => {
 	return result
 }
 
-const parseJsdocPart = (part: JsdocPart): ParsedJsDocPart[] => {
+const parseJsDocPart = (part: RawJsDocPart): ParsedJsDocPart[] => {
 	switch (part.getKindName()) {
 		case "JSDocText":
-			return parseJsdocText(part.compilerNode.text)
+			return parseJsDocText(part.compilerNode.text)
 		case "JSDocLink":
-			return [parseJsdocLink(part)]
+			return [parseJsDocLink(part)]
 		default:
 			return throwInternalError(
 				`Unsupported JSDoc part kind ${part.getKindName()} at position ${part.getPos()} in ${part.getSourceFile().getFilePath()}`
@@ -185,8 +209,8 @@ const parseJsdocPart = (part: JsdocPart): ParsedJsDocPart[] => {
 	}
 }
 
-const parseJsdocText = (text: string): ParsedJsDocPart[] => {
-	const sections = text.split(/\n\s*-/)
+const parseJsDocText = (text: string): ParsedJsDocPart[] => {
+	const sections = text.split(noteDelimiterRegex)
 	return sections.map((sectionText, i) => ({
 		kind: i === 0 ? "text" : "noteStart",
 		value: sectionText.trim()
@@ -196,7 +220,7 @@ const parseJsdocText = (text: string): ParsedJsDocPart[] => {
 const describedLinkRegex =
 	/\{@link\s+(https?:\/\/[^\s|}]+)(?:\s*\|\s*([^}]*))?\}/
 
-const parseJsdocLink = (part: JsdocPart): ParsedJsDocPart => {
+const parseJsDocLink = (part: RawJsDocPart): ParsedJsDocPart => {
 	const linkText = part.getText()
 	const match = describedLinkRegex.exec(linkText)
 	if (match) {
@@ -227,37 +251,36 @@ const parseJsdocLink = (part: JsdocPart): ParsedJsDocPart => {
 }
 
 type MatchContext = {
-	matchedJsdoc: JSDoc
-	updateJsdoc: (text: string) => void
+	matchedJsDoc: JSDoc
+	updateJsDoc: (text: string) => void
 	inheritDocsSource: string | undefined
 }
 
 const docgenForFile = (sourceFile: SourceFile) => {
 	const path = sourceFile.getFilePath()
 
-	const jsdocNodes = sourceFile.getDescendantsOfKind(SyntaxKind.JSDoc)
+	const jsDocNodes = sourceFile.getDescendantsOfKind(SyntaxKind.JSDoc)
 
-	const matchContexts: MatchContext[] = jsdocNodes.flatMap(jsdoc => {
-		const text = jsdoc.getText()
+	const matchContexts: MatchContext[] = jsDocNodes.flatMap(jsDoc => {
+		const text = jsDoc.getText()
 
 		const inheritDocsSource = extractInheritDocName(path, text)
 
 		if (
 			!inheritDocsSource &&
-			!text.includes(typeOnlyToken) &&
-			!text.includes(typeNoopToken)
+			!Object.keys(replacedDecorators).some(k => text.includes(k))
 		)
 			return []
 
 		return {
-			matchedJsdoc: jsdoc,
+			matchedJsDoc: jsDoc,
 			inheritDocsSource,
-			updateJsdoc: text => {
-				const parent = jsdoc.getParent() as JSDocableNode
+			updateJsDoc: text => {
+				const parent = jsDoc.getParent() as JSDocableNode
 
 				// replace the original JSDoc node in the AST with a new one
 				// created from updatedContents
-				jsdoc.remove()
+				jsDoc.remove()
 				parent.addJsDoc(text)
 
 				updateCount++
@@ -268,21 +291,23 @@ const docgenForFile = (sourceFile: SourceFile) => {
 	matchContexts.forEach(ctx => {
 		const inheritedDocs = findInheritedDocs(sourceFile, ctx)
 
-		let updatedContents = ctx.matchedJsdoc.getInnerText()
+		let updatedContents = ctx.matchedJsDoc.getInnerText()
 
 		if (inheritedDocs)
 			updatedContents = `${inheritedDocs.originalSummary}\n${inheritedDocs.inheritedDescription}`
 
-		updatedContents = updatedContents.replace(typeOnlyToken, typeOnlyMessage)
-		updatedContents = updatedContents.replace(typeNoopToken, typeNoopMessage)
+		updatedContents = Object.entries(replacedDecorators).reduce(
+			(contents, [decorator, message]) => contents.replace(decorator, message),
+			updatedContents
+		)
 
-		ctx.updateJsdoc(updatedContents)
+		ctx.updateJsDoc(updatedContents)
 	})
 }
 
 const findInheritedDocs = (
 	sourceFile: SourceFile,
-	{ inheritDocsSource, matchedJsdoc }: MatchContext
+	{ inheritDocsSource, matchedJsDoc }: MatchContext
 ) => {
 	if (!inheritDocsSource) return
 
@@ -294,7 +319,7 @@ const findInheritedDocs = (
 
 	if (!sourceDeclaration || !canHaveJsDoc(sourceDeclaration)) return
 
-	const matchedDescription = matchedJsdoc.getDescription()
+	const matchedDescription = matchedJsDoc.getDescription()
 
 	const inheritedDescription = sourceDeclaration.getJsDocs()[0].getDescription()
 
@@ -356,6 +381,6 @@ const throwJsDocgenParseError = (
 	message: string
 ): never => {
 	throw new Error(
-		`jsdocGen ParseError in ${path}: ${message}\nComment text: ${commentText}`
+		`jsDocGen ParseError in ${path}: ${message}\nComment text: ${commentText}`
 	)
 }
diff --git a/ark/repo/package.json b/ark/repo/package.json
index 5dae015be3..bd79119a91 100644
--- a/ark/repo/package.json
+++ b/ark/repo/package.json
@@ -9,8 +9,8 @@
 		"@sinclair/typebox": "0.34.13",
 		"@trpc/server": "10.45.2",
 		"arktype": "workspace:*",
-		"type-fest": "4.31.0",
 		"ts-morph": "25.0.0",
+		"type-fest": "4.32.0",
 		"typescript": "catalog:",
 		"zod": "3.24.1"
 	},
diff --git a/ark/repo/scratch.ts b/ark/repo/scratch.ts
index 9d7296bdd2..05204d9200 100644
--- a/ark/repo/scratch.ts
+++ b/ark/repo/scratch.ts
@@ -1,5 +1,6 @@
-import { type } from "arktype"
-import { buildApi, jsdocGen } from "./jsdocGen.ts"
+import { scope, type } from "arktype"
+import { Disjoint } from "../schema/shared/disjoint.ts"
+import { buildApi, jsDocGen } from "./jsDocGen.ts"
 
 // type stats on attribute removal merge 12/18/2024
 // {
@@ -8,19 +9,67 @@ import { buildApi, jsdocGen } from "./jsdocGen.ts"
 //     "instantiations": 5066185
 // }
 
-const t = type("(number % 2) > 0")
+const uniqueStrings = type("string[]").narrow((arr, ctx) => {
+	const seen: Record<string, number> = {}
+	for (let i = 0; i < arr.length; i++) {
+		if (arr[i] in seen) {
+			return ctx.reject({
+				expected: "a unique string",
+				actual: `a duplicate of '${arr[i]}' at index ${seen[arr[i]]}`,
+				relativePath: [i]
+			})
+		} else seen[arr[i]] = i
+	}
+	return true
+})
 
-// buildApi()
+//   const notFoo = type.string.narrow((s, ctx) => {
+//       if (s !== "foo") return true
+//       // ["names", 1]
+//       console.warn(ctx.path)
+//       return ctx.mustBe("not foo")
+//   })
 
-t.configure
+//  const obj = type({
+//       names: notFoo.array()
+//   })
 
-t.description //?
-// an integer and more than 0 and at most 10
+//  // ArkErrors: names[1] must be not foo (was "foo")
+//  obj({ names: ["bar", "foo"] })
 
-const text = `FOo bar
-- baz
-    - back
-    track 
- -squz`
-const s = text.split(/\n\s*-/)
-console.log(s)
+const closedObjectScope = scope(
+	{
+		user: {
+			name: "string"
+		}
+	},
+	{
+		onUndeclaredKey: "reject"
+	}
+)
+const types = closedObjectScope.export()
+types.user({ name: "Alice", age: 99 }).toString() //?
+
+const user = type({
+	password: "string >= 8"
+}).configure({
+	message: ctx =>
+		`${ctx.propString || "(root)"}: ${ctx.actual} isn't ${ctx.expected}`
+})
+// ArkErrors: (root): a string isn't an object
+const out1 = user("ez123")
+// but `.configure` only applies shallowly, so the nested error isn't changed!
+// ArkErrors: password must be at least length 8 (was 5)
+const out2 = user({ password: "ez123" })
+
+const mod = type.module(
+	{ isEven: "number%2" },
+	{
+		divisor: {
+			expected: ctx => `% ${ctx.rule} !== 0`,
+			problem: ctx => `${ctx.actual} ${ctx.expected}`
+		}
+	}
+)
+// ArkErrors: 3 % 2 !== 0
+mod.isEven(3)
diff --git a/ark/repo/testV8.js b/ark/repo/testV8.js
index 8f3cfe4bcd..3444e614f4 100644
--- a/ark/repo/testV8.js
+++ b/ark/repo/testV8.js
@@ -6,8 +6,8 @@ console.log(
 )
 
 const t = type({
-	a: "string",
-	b: "number"
+	name: "string",
+	age: "number"
 })
 
 let hasFastProperties
diff --git a/ark/schema/config.ts b/ark/schema/config.ts
index 018e6d6496..bd76bb4e06 100644
--- a/ark/schema/config.ts
+++ b/ark/schema/config.ts
@@ -1,4 +1,11 @@
-import type { ArkRegistry, mutable, requireKeys, show } from "@ark/util"
+import {
+	keysOf,
+	type ArkRegistry,
+	type dict,
+	type mutable,
+	type requireKeys,
+	type show
+} from "@ark/util"
 import type { intrinsic } from "./intrinsic.ts"
 import type { nodesByRegisteredId } from "./parse.ts"
 import type {
@@ -9,6 +16,7 @@ import type {
 	ProblemWriter
 } from "./shared/errors.ts"
 import {
+	defaultValueSerializer,
 	isNodeKind,
 	type DescriptionWriter,
 	type NodeKind
@@ -19,7 +27,8 @@ import type { UndeclaredKeyBehavior } from "./structure/structure.ts"
 export interface ArkSchemaRegistry extends ArkRegistry {
 	intrinsic: typeof intrinsic
 	config: ArkConfig
-	defaultConfig: ResolvedArkConfig
+	defaultConfig: ResolvedConfig
+	resolvedConfig: ResolvedConfig
 	nodesByRegisteredId: typeof nodesByRegisteredId
 }
 
@@ -65,24 +74,39 @@ export type ResolvedUnknownNodeConfig = requireKeys<
 // dedicated config entrypoint, in which case we don't want to reinitialize it
 $ark.config ??= {}
 
-export const configure = (config: ArkConfig): ArkConfig =>
-	Object.assign($ark.config, mergeConfigs($ark.config, config))
+export const configure = (config: ArkConfig): ArkConfig => {
+	const result = Object.assign($ark.config, mergeConfigs($ark.config, config))
+
+	$ark.resolvedConfig &&= mergeConfigs($ark.resolvedConfig, result)
+
+	return result
+}
 
-export const mergeConfigs = (
-	base: ArkConfig,
+export const mergeConfigs = <base extends ArkConfig>(
+	base: base,
 	extensions: ArkConfig
-): mutable<ArkConfig> => {
-	const result: any = { ...base }
-	let k: keyof ArkConfig
-	for (k in extensions) {
-		result[k] =
-			isNodeKind(k) ?
-				{
-					...base[k],
-					...extensions[k]
-				}
-			:	extensions[k]
+): mutable<base extends ResolvedConfig ? ResolvedConfig : ArkConfig> => {
+	// always maintains alphabetized keys (important for normalized comparisons)
+	const keys = keysOf({ ...base, ...extensions }).sort()
+
+	const result: any = {}
+
+	for (const k of keys) {
+		let v: unknown
+		if (isNodeKind(k)) {
+			if (base[k]) {
+				if (extensions[k]) {
+					v = {
+						...base[k],
+						...extensions[k]
+					}
+				} else v = base[k]
+			} else v = extensions[k]
+		} else v = extensions[k] === undefined ? base[k] : extensions[k]
+
+		if (v !== undefined) result[k] = v
 	}
+
 	return result
 }
 
@@ -94,6 +118,8 @@ export interface ArkConfig extends Partial<Readonly<NodeConfigsByKind>> {
 	jitless?: boolean
 	clone?: boolean | CloneImplementation
 	onUndeclaredKey?: UndeclaredKeyBehavior
+	numberAllowsNaN?: boolean
+	dateAllowsInvalid?: boolean
 }
 
 export type resolveConfig<config extends ArkConfig> = show<
@@ -104,18 +130,28 @@ export type resolveConfig<config extends ArkConfig> = show<
 	} & Omit<config, keyof ArkConfig>
 >
 
-export type ResolvedArkConfig = resolveConfig<ArkConfig>
+export type ResolvedConfig = resolveConfig<ArkConfig>
 
-export const extendConfig = (
-	base: ArkConfig,
-	extension: ArkConfig | undefined
-): ArkConfig => {
-	if (!extension) return base
-	const result = mergeConfigs(base, extension)
-	return result
+export const serializeConfig = (config: ArkConfig): string => {
+	const keys = keysOf(config).sort()
+	const serializableConfig: dict = {}
+
+	for (const k of keys) {
+		serializableConfig[k] =
+			isNodeKind(k) ?
+				serializeNodeConfig(config[k]!)
+			:	defaultValueSerializer(config[k])
+	}
+
+	return JSON.stringify(serializableConfig)
 }
 
-export const resolveConfig = <config extends ArkConfig>(
-	config: config | undefined
-): resolveConfig<config> =>
-	extendConfig(extendConfig($ark.defaultConfig, $ark.config), config) as never
+const serializeNodeConfig = (nodeConfig: dict) => {
+	const keys = Object.keys(nodeConfig).sort()
+
+	const result: dict = {}
+
+	for (const k of keys) result[k] = defaultValueSerializer(nodeConfig[k])
+
+	return result
+}
diff --git a/ark/schema/kinds.ts b/ark/schema/kinds.ts
index 46b02b6be1..80ae32792e 100644
--- a/ark/schema/kinds.ts
+++ b/ark/schema/kinds.ts
@@ -2,10 +2,11 @@ import {
 	deepClone,
 	envHasCsp,
 	flatMorph,
+	withAlphabetizedKeys,
 	type array,
 	type listable
 } from "@ark/util"
-import type { ResolvedArkConfig } from "./config.ts"
+import { mergeConfigs, type ResolvedConfig } from "./config.ts"
 import type { BaseNode } from "./node.ts"
 import { Predicate } from "./predicate.ts"
 import { Divisor } from "./refinements/divisor.ts"
@@ -80,17 +81,23 @@ export const nodeImplementationsByKind: Record<
 	structure: Structure.implementation
 } satisfies Record<NodeKind, unknown> as never
 
-$ark.defaultConfig = Object.assign(
-	flatMorph(nodeImplementationsByKind, (kind, implementation) => [
-		kind,
-		implementation.defaults
-	]),
-	{
-		jitless: envHasCsp(),
-		clone: deepClone,
-		onUndeclaredKey: "ignore"
-	} satisfies Omit<ResolvedArkConfig, NodeKind>
-) as never
+$ark.defaultConfig = withAlphabetizedKeys(
+	Object.assign(
+		flatMorph(nodeImplementationsByKind, (kind, implementation) => [
+			kind,
+			implementation.defaults
+		]),
+		{
+			jitless: envHasCsp(),
+			clone: deepClone,
+			onUndeclaredKey: "ignore",
+			numberAllowsNaN: false,
+			dateAllowsInvalid: false
+		} satisfies Omit<ResolvedConfig, NodeKind>
+	) as never
+)
+
+$ark.resolvedConfig = mergeConfigs($ark.defaultConfig, $ark.config)
 
 export const nodeClassesByKind: Record<
 	NodeKind,
diff --git a/ark/schema/node.ts b/ark/schema/node.ts
index a3f2c0ea11..f26a3bed9d 100644
--- a/ark/schema/node.ts
+++ b/ark/schema/node.ts
@@ -52,7 +52,7 @@ import {
 } from "./shared/implement.ts"
 import { $ark } from "./shared/registry.ts"
 import {
-	TraversalContext,
+	Traversal,
 	type TraverseAllows,
 	type TraverseApply
 } from "./shared/traversal.ts"
@@ -64,7 +64,7 @@ export abstract class BaseNode<
 	 * @ts-ignore allow instantiation assignment to the base type */
 	out d extends BaseNodeDeclaration = BaseNodeDeclaration
 > extends Callable<
-	(data: d["prerequisite"], ctx?: TraversalContext) => unknown,
+	(data: d["prerequisite"], ctx?: Traversal) => unknown,
 	attachmentsOf<d>
 > {
 	attachments: UnknownAttachments
@@ -72,7 +72,7 @@ export abstract class BaseNode<
 
 	constructor(attachments: UnknownAttachments, $: BaseScope) {
 		super(
-			(data: any, pipedFromCtx?: TraversalContext) => {
+			(data: any, pipedFromCtx?: Traversal) => {
 				if (
 					!this.includesMorph &&
 					!this.allowsRequiresContext &&
@@ -87,7 +87,7 @@ export abstract class BaseNode<
 						:	pipedFromCtx.data
 				}
 
-				const ctx = new TraversalContext(data, this.$.resolvedConfig)
+				const ctx = new Traversal(data, this.$.configSnapshot.resolved)
 				this.traverseApply(data, ctx)
 				return ctx.finalize()
 			},
@@ -141,14 +141,10 @@ export abstract class BaseNode<
 	}
 
 	get description(): string {
-		const writer =
-			this.$?.resolvedConfig[this.kind].description ??
-			$ark.config[this.kind]?.description ??
-			$ark.defaultConfig[this.kind].description
-
 		return this.cacheGetter(
 			"description",
-			this.meta?.description ?? writer(this as never)
+			this.meta?.description ??
+				this.configSnapshot.resolved[this.kind].description(this as never)
 		)
 	}
 
@@ -162,7 +158,7 @@ export abstract class BaseNode<
 		return this.cacheGetter(
 			"shallowReferences",
 			this.hasKind("structure") ?
-				[this as BaseNode, ...this.children]
+				[this as BaseNode, ...(this.children as never)]
 			:	this.children.reduce<BaseNode[]>(
 					(acc, child) => appendUniqueNodes(acc, child.shallowReferences),
 					[this]
@@ -206,7 +202,7 @@ export abstract class BaseNode<
 		if (this.allowsRequiresContext) {
 			return this.traverseAllows(
 				data as never,
-				new TraversalContext(data, this.$.resolvedConfig)
+				new Traversal(data, this.$.configSnapshot.resolved)
 			)
 		}
 		return (this.traverseAllows as any)(data)
diff --git a/ark/schema/package.json b/ark/schema/package.json
index 3fedece9b7..71a4a62463 100644
--- a/ark/schema/package.json
+++ b/ark/schema/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@ark/schema",
-	"version": "0.33.0",
+	"version": "0.34.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",
diff --git a/ark/schema/parse.ts b/ark/schema/parse.ts
index b4e094a18e..8245644f23 100644
--- a/ark/schema/parse.ts
+++ b/ark/schema/parse.ts
@@ -143,8 +143,10 @@ export const registerNodeId = (prefix: string): NodeId => {
 
 export const parseNode = (ctx: NodeParseContext): BaseNode => {
 	const impl = nodeImplementationsByKind[ctx.kind]
+	const configuredSchema =
+		impl.applyConfig?.(ctx.def, ctx.$.configSnapshot.resolved) ?? ctx.def
 	const inner: dict = {}
-	const { meta: metaSchema, ...schema } = ctx.def as dict & {
+	const { meta: metaSchema, ...innerSchema } = configuredSchema as dict & {
 		meta?: MetaSchema
 	}
 
@@ -155,7 +157,7 @@ export const parseNode = (ctx: NodeParseContext): BaseNode => {
 
 	// ensure node entries are parsed in order of precedence, with non-children
 	// parsed first
-	const innerSchemaEntries = entriesOf(schema)
+	const innerSchemaEntries = entriesOf(innerSchema)
 		.sort(([lKey], [rKey]) =>
 			isNodeKind(lKey) ?
 				isNodeKind(rKey) ? precedenceOfKind(lKey) - precedenceOfKind(rKey)
@@ -252,9 +254,17 @@ export const createNode = (
 	const collapsibleJson = possiblyCollapse(json, impl.collapsibleKey, true)
 	const hash = JSON.stringify({ kind, ...json })
 
+	const configSnapshot = $.configSnapshot
 	// we have to wait until after reduction to return a cached entry,
 	// since reduction can add impliedSiblings
-	if ($.nodesByHash[hash] && !ignoreCache) return $.nodesByHash[hash]
+	if ($.nodesByHash[hash] && !ignoreCache) {
+		const cached = $.nodesByHash[hash]
+		if (cached.configSnapshot.hash !== configSnapshot.hash)
+			// update to show the node reflects the latest parse config, if it has changed
+			Object.assign(cached, { configSnapshot } satisfies Partial<BaseNode>)
+
+		return cached
+	}
 
 	const attachments: UnknownAttachments & dict = {
 		id,
@@ -269,11 +279,14 @@ export const createNode = (
 		json,
 		hash,
 		collapsibleJson: collapsibleJson as Json,
-		children
+		children,
+		configSnapshot
 	}
 
-	for (const k in inner)
-		if (k !== "in" && k !== "out") attachments[k] = inner[k]
+	if (kind !== "intersection") {
+		for (const k in inner)
+			if (k !== "in" && k !== "out") attachments[k] = inner[k]
+	}
 
 	const node: BaseNode = new nodeClassesByKind[kind](attachments as never, $)
 
diff --git a/ark/schema/predicate.ts b/ark/schema/predicate.ts
index fae6ceec26..cc75469511 100644
--- a/ark/schema/predicate.ts
+++ b/ark/schema/predicate.ts
@@ -16,7 +16,7 @@ import {
 	registeredReference
 } from "./shared/registry.ts"
 import type {
-	TraversalContext,
+	Traversal,
 	TraverseAllows,
 	TraverseApply
 } from "./shared/traversal.ts"
@@ -118,15 +118,12 @@ export const Predicate = {
 	Node: PredicateNode
 }
 
-export type Predicate<data = any> = (
-	data: data,
-	ctx: TraversalContext
-) => boolean
+export type Predicate<data = any> = (data: data, ctx: Traversal) => boolean
 
 export declare namespace Predicate {
 	export type Casted<input = never, narrowed extends input = input> = (
 		input: input,
-		ctx: TraversalContext
+		ctx: Traversal
 	) => input is narrowed
 
 	export type Castable<input = never, narrowed extends input = input> =
diff --git a/ark/schema/roots/domain.ts b/ark/schema/roots/domain.ts
index 8a053285e0..1b923d7ed3 100644
--- a/ark/schema/roots/domain.ts
+++ b/ark/schema/roots/domain.ts
@@ -1,4 +1,10 @@
-import { domainDescriptions, domainOf, type Domain as _Domain } from "@ark/util"
+import {
+	domainDescriptions,
+	domainOf,
+	hasKey,
+	throwParseError,
+	type Domain as _Domain
+} from "@ark/util"
 import type {
 	BaseErrorContext,
 	BaseNormalizedSchema,
@@ -22,13 +28,13 @@ export declare namespace Domain {
 
 	export interface Inner<domain extends NonEnumerable = NonEnumerable> {
 		readonly domain: domain
+		readonly numberAllowsNaN?: boolean
 	}
 
 	export interface NormalizedSchema<
 		domain extends NonEnumerable = NonEnumerable
-	> extends BaseNormalizedSchema {
-		readonly domain: domain
-	}
+	> extends BaseNormalizedSchema,
+			Inner<domain> {}
 
 	export type Schema<
 		// only domains with an infinite number of values are allowed as bases
@@ -55,33 +61,64 @@ const implementation: nodeImplementationOf<Domain.Declaration> =
 		hasAssociatedError: true,
 		collapsibleKey: "domain",
 		keys: {
-			domain: {}
+			domain: {},
+			numberAllowsNaN: {}
 		},
 		normalize: schema =>
-			typeof schema === "string" ? { domain: schema } : schema,
+			typeof schema === "string" ? { domain: schema }
+			: hasKey(schema, "numberAllowsNaN") && schema.domain !== "number" ?
+				throwParseError(Domain.writeBadAllowNanMessage(schema.domain))
+			:	schema,
+		applyConfig: (schema, config) =>
+			(
+				schema.numberAllowsNaN === undefined &&
+				schema.domain === "number" &&
+				config.numberAllowsNaN
+			) ?
+				{ ...schema, numberAllowsNaN: true }
+			:	schema,
 		defaults: {
 			description: node => domainDescriptions[node.domain],
-			actual: data => domainDescriptions[domainOf(data)]
+			actual: data =>
+				Number.isNaN(data) ? "NaN" : domainDescriptions[domainOf(data)]
 		},
 		intersections: {
-			domain: (l, r) => Disjoint.init("domain", l, r)
+			domain: (l, r) =>
+				// since l === r is handled by default, remaining cases are disjoint
+				// outside those including options like numberAllowsNaN
+				l.domain === "number" && r.domain === "number" ?
+					l.numberAllowsNaN ?
+						r
+					:	l
+				:	Disjoint.init("domain", l, r)
 		}
 	})
 
 export class DomainNode extends InternalBasis<Domain.Declaration> {
-	traverseAllows: TraverseAllows = data => domainOf(data) === this.domain
+	private readonly requiresNaNCheck =
+		this.domain === "number" && !this.numberAllowsNaN
+
+	readonly traverseAllows: TraverseAllows =
+		this.requiresNaNCheck ?
+			data => typeof data === "number" && !Number.isNaN(data)
+		:	data => domainOf(data) === this.domain
 
 	readonly compiledCondition: string =
 		this.domain === "object" ?
 			`((typeof data === "object" && data !== null) || typeof data === "function")`
-		:	`typeof data === "${this.domain}"`
+		:	`typeof data === "${this.domain}"${this.requiresNaNCheck ? " && !Number.isNaN(data)" : ""}`
 
 	readonly compiledNegation: string =
 		this.domain === "object" ?
 			`((typeof data !== "object" || data === null) && typeof data !== "function")`
-		:	`typeof data !== "${this.domain}"`
+		:	`typeof data !== "${this.domain}"${this.requiresNaNCheck ? " || Number.isNaN(data)" : ""}`
+
+	readonly expression: string =
+		this.numberAllowsNaN ? "number | NaN" : this.domain
 
-	readonly expression: string = this.domain
+	get nestableExpression(): string {
+		return this.numberAllowsNaN ? `(${this.expression})` : this.expression
+	}
 
 	get shortDescription(): string {
 		return domainDescriptions[this.domain]
@@ -98,5 +135,9 @@ export class DomainNode extends InternalBasis<Domain.Declaration> {
 
 export const Domain = {
 	implementation,
-	Node: DomainNode
+	Node: DomainNode,
+	writeBadAllowNanMessage: (
+		actual: Exclude<Domain.NonEnumerable, "number">
+	): string =>
+		`numberAllowsNaN may only be specified with domain "number" (was ${actual})`
 }
diff --git a/ark/schema/roots/intersection.ts b/ark/schema/roots/intersection.ts
index 87db958251..c3b52963ff 100644
--- a/ark/schema/roots/intersection.ts
+++ b/ark/schema/roots/intersection.ts
@@ -243,8 +243,11 @@ const implementation: nodeImplementationOf<Intersection.Declaration> =
 					childDescriptions.push(...sortedRefinementDescriptions)
 				}
 
-				if (node.predicate)
-					childDescriptions.push(...node.predicate.map(p => p.description))
+				if (node.inner.predicate) {
+					childDescriptions.push(
+						...node.inner.predicate.map(p => p.description)
+					)
+				}
 
 				return childDescriptions.join(" and ")
 			},
@@ -253,7 +256,8 @@ const implementation: nodeImplementationOf<Intersection.Declaration> =
 			problem: ctx => `(${ctx.actual}) must be...\n${ctx.expected}`
 		},
 		intersections: {
-			intersection: (l, r, ctx) => intersectIntersections(l, r, ctx),
+			intersection: (l, r, ctx) =>
+				intersectIntersections(l.inner, r.inner, ctx),
 			...defineRightwardIntersections("intersection", (l, r, ctx) => {
 				// if l is unknown, return r
 				if (l.children.length === 0) return r
@@ -283,20 +287,15 @@ const implementation: nodeImplementationOf<Intersection.Declaration> =
 
 export class IntersectionNode extends BaseRoot<Intersection.Declaration> {
 	basis: nodeOfKind<Intersection.BasisKind> | null =
-		this.domain ?? this.proto ?? null
+		this.inner.domain ?? this.inner.proto ?? null
 
 	refinements: array<nodeOfKind<RefinementKind>> = this.children.filter(node =>
 		node.isRefinement()
 	)
 
-	get expression(): string {
-		let expression =
-			this.structure?.expression ||
-			`${this.basis ? this.basis.nestableExpression + " " : ""}${this.refinements.join(" & ")}` ||
-			"unknown"
-		if (expression === "Array == 0") expression = "[]"
-		return this.cacheGetter("expression", expression)
-	}
+	structure: Structure.Node | undefined = this.inner.structure
+
+	expression: string = describeIntersection(this)
 
 	get shortDescription(): string {
 		return this.basis?.shortDescription ?? "present"
@@ -334,12 +333,12 @@ export class IntersectionNode extends BaseRoot<Intersection.Declaration> {
 			this.structure.traverseApply(data as never, ctx)
 			if (ctx.currentErrorCount > errorCount) return
 		}
-		if (this.predicate) {
-			for (let i = 0; i < this.predicate.length - 1; i++) {
-				this.predicate[i].traverseApply(data as never, ctx)
+		if (this.inner.predicate) {
+			for (let i = 0; i < this.inner.predicate.length - 1; i++) {
+				this.inner.predicate[i].traverseApply(data as never, ctx)
 				if (ctx.failFast && ctx.currentErrorCount > errorCount) return
 			}
-			this.predicate.at(-1)!.traverseApply(data as never, ctx)
+			this.inner.predicate.at(-1)!.traverseApply(data as never, ctx)
 		}
 	}
 
@@ -363,20 +362,20 @@ export class IntersectionNode extends BaseRoot<Intersection.Declaration> {
 				js.returnIfFailFast()
 			}
 			js.check(this.refinements.at(-1)!)
-			if (this.structure || this.predicate) js.returnIfFail()
+			if (this.structure || this.inner.predicate) js.returnIfFail()
 		}
 		if (this.structure) {
 			js.check(this.structure)
-			if (this.predicate) js.returnIfFail()
+			if (this.inner.predicate) js.returnIfFail()
 		}
-		if (this.predicate) {
-			for (let i = 0; i < this.predicate.length - 1; i++) {
-				js.check(this.predicate[i])
+		if (this.inner.predicate) {
+			for (let i = 0; i < this.inner.predicate.length - 1; i++) {
+				js.check(this.inner.predicate[i])
 				// since predicates can be chained, we have to fail immediately
 				// if one fails
 				js.returnIfFail()
 			}
-			js.check(this.predicate.at(-1)!)
+			js.check(this.inner.predicate.at(-1)!)
 		}
 	}
 }
@@ -386,17 +385,20 @@ export const Intersection = {
 	Node: IntersectionNode
 }
 
+const describeIntersection = (node: Intersection.Node) => {
+	let expression =
+		node.structure?.expression ||
+		`${node.basis ? node.basis.nestableExpression + " " : ""}${node.refinements.join(" & ")}` ||
+		"unknown"
+	if (expression === "Array == 0") expression = "[]"
+	return expression
+}
+
 const intersectIntersections = (
 	l: Intersection.Inner,
 	r: Intersection.Inner,
 	ctx: IntersectionContext
 ): BaseRoot | Disjoint => {
-	// avoid treating adding instance keys as keys of lRoot, rRoot
-	if (hasArkKind(l, "root") && l.hasKind("intersection"))
-		return intersectIntersections(l.inner, r, ctx)
-	if (hasArkKind(r, "root") && r.hasKind("intersection"))
-		return intersectIntersections(l, r.inner, ctx)
-
 	const baseInner: Intersection.Inner.mutable = {}
 
 	const lBasis = l.proto ?? l.domain
diff --git a/ark/schema/roots/morph.ts b/ark/schema/roots/morph.ts
index 6ead9d9bd5..7761dbec57 100644
--- a/ark/schema/roots/morph.ts
+++ b/ark/schema/roots/morph.ts
@@ -19,7 +19,7 @@ import { intersectOrPipeNodes } from "../shared/intersections.ts"
 import { JsonSchema } from "../shared/jsonSchema.ts"
 import { $ark, registeredReference } from "../shared/registry.ts"
 import type {
-	TraversalContext,
+	Traversal,
 	TraverseAllows,
 	TraverseApply
 } from "../shared/traversal.ts"
@@ -54,7 +54,7 @@ export declare namespace Morph {
 	export type Node = MorphNode
 }
 
-export type Morph<i = any, o = unknown> = (In: i, ctx: TraversalContext) => o
+export type Morph<i = any, o = unknown> = (In: i, ctx: Traversal) => o
 
 const implementation: nodeImplementationOf<Morph.Declaration> =
 	implementNode<Morph.Declaration>({
diff --git a/ark/schema/roots/proto.ts b/ark/schema/roots/proto.ts
index 8083761a35..d018c89450 100644
--- a/ark/schema/roots/proto.ts
+++ b/ark/schema/roots/proto.ts
@@ -2,8 +2,10 @@ import {
 	builtinConstructors,
 	constructorExtends,
 	getBuiltinNameOfConstructor,
+	hasKey,
 	objectKindDescriptions,
 	objectKindOrDomainOf,
+	throwParseError,
 	type BuiltinObjectKind,
 	type Constructor
 } from "@ark/util"
@@ -35,14 +37,17 @@ export declare namespace Proto {
 	export interface NormalizedSchema<proto extends Constructor = Constructor>
 		extends BaseNormalizedSchema {
 		readonly proto: proto
+		readonly dateAllowsInvalid?: boolean
 	}
 
 	export interface ExpandedSchema<proto extends Reference = Reference> {
 		readonly proto: proto
+		readonly dateAllowsInvalid?: boolean
 	}
 
 	export interface Inner<proto extends Constructor = Constructor> {
 		readonly proto: proto
+		readonly dateAllowsInvalid?: boolean
 	}
 
 	export interface ErrorContext extends BaseErrorContext<"proto">, Inner {}
@@ -68,26 +73,50 @@ const implementation: nodeImplementationOf<Proto.Declaration> =
 			proto: {
 				serialize: ctor =>
 					getBuiltinNameOfConstructor(ctor) ?? defaultValueSerializer(ctor)
-			}
+			},
+			dateAllowsInvalid: {}
+		},
+		normalize: schema => {
+			const normalized: Proto.NormalizedSchema<Constructor> =
+				typeof schema === "string" ? { proto: builtinConstructors[schema] }
+				: typeof schema === "function" ?
+					isNode(schema) ? (schema as {} as ProtoNode)
+					:	{ proto: schema }
+				: typeof schema.proto === "string" ?
+					{ ...schema, proto: builtinConstructors[schema.proto] }
+				:	(schema as never)
+			if (hasKey(normalized, "dateAllowsInvalid") && normalized.proto !== Date)
+				throwParseError(Proto.writeBadInvalidDateMessage(normalized.proto))
+			return normalized
+		},
+		applyConfig: (schema, config) => {
+			if (
+				schema.dateAllowsInvalid === undefined &&
+				schema.proto === Date &&
+				config.dateAllowsInvalid
+			)
+				return { ...schema, dateAllowsInvalid: true }
+			return schema
 		},
-		normalize: schema =>
-			typeof schema === "string" ? { proto: builtinConstructors[schema] }
-			: typeof schema === "function" ?
-				isNode(schema) ? (schema as {} as ProtoNode)
-				:	{ proto: schema }
-			: typeof schema.proto === "string" ?
-				{ ...schema, proto: builtinConstructors[schema.proto] }
-			:	(schema as Proto.ExpandedSchema<Constructor>),
 		defaults: {
 			description: node =>
 				node.builtinName ?
 					objectKindDescriptions[node.builtinName]
 				:	`an instance of ${node.proto.name}`,
-			actual: data => objectKindOrDomainOf(data)
+			actual: data =>
+				data instanceof Date && data.toString() === "Invalid Date" ?
+					"an invalid Date"
+				:	objectKindOrDomainOf(data)
 		},
 		intersections: {
 			proto: (l, r) =>
-				constructorExtends(l.proto, r.proto) ? l
+				l.proto === Date && r.proto === Date ?
+					// since l === r is handled by default,
+					// exactly one of l or r must have allow invalid dates
+					l.dateAllowsInvalid ?
+						r
+					:	l
+				: constructorExtends(l.proto, r.proto) ? l
 				: constructorExtends(r.proto, l.proto) ? r
 				: Disjoint.init("proto", l, r),
 			domain: (proto, domain) =>
@@ -106,7 +135,16 @@ export class ProtoNode extends InternalBasis<Proto.Declaration> {
 		this.proto
 	)
 	serializedConstructor: string = (this.json as { proto: string }).proto
-	compiledCondition = `data instanceof ${this.serializedConstructor}`
+
+	private readonly requiresInvalidDateCheck =
+		this.proto === Date && !this.dateAllowsInvalid
+
+	traverseAllows: TraverseAllows =
+		this.requiresInvalidDateCheck ?
+			data => data instanceof Date && data.toString() !== "Invalid Date"
+		:	data => data instanceof this.proto
+
+	compiledCondition = `data instanceof ${this.serializedConstructor}${this.requiresInvalidDateCheck ? ` && data.toString() !== "Invalid Date"` : ""}`
 	compiledNegation = `!(${this.compiledCondition})`
 
 	protected innerToJsonSchema(): JsonSchema.Array {
@@ -120,8 +158,13 @@ export class ProtoNode extends InternalBasis<Proto.Declaration> {
 		}
 	}
 
-	traverseAllows: TraverseAllows = data => data instanceof this.proto
-	expression: string = this.proto.name
+	expression: string =
+		this.dateAllowsInvalid ? "Date | InvalidDate" : this.proto.name
+
+	get nestableExpression(): string {
+		return this.dateAllowsInvalid ? `(${this.expression})` : this.expression
+	}
+
 	readonly domain = "object"
 
 	get shortDescription(): string {
@@ -131,5 +174,7 @@ export class ProtoNode extends InternalBasis<Proto.Declaration> {
 
 export const Proto = {
 	implementation,
-	Node: ProtoNode
+	Node: ProtoNode,
+	writeBadInvalidDateMessage: (actual: Constructor): string =>
+		`dateAllowsInvalid may only be specified with constructor Date (was ${actual.name})`
 }
diff --git a/ark/schema/roots/root.ts b/ark/schema/roots/root.ts
index 0c90a9addd..75bfc39753 100644
--- a/ark/schema/roots/root.ts
+++ b/ark/schema/roots/root.ts
@@ -107,14 +107,6 @@ export abstract class BaseRoot<
 		return this
 	}
 
-	brandAttributes(): this {
-		return this
-	}
-
-	unbrandAttributes(): this {
-		return this
-	}
-
 	readonly(): this {
 		return this
 	}
@@ -520,7 +512,7 @@ export abstract class BaseRoot<
 	}
 
 	filter(predicate: Predicate): BaseRoot {
-		return this.constrain("predicate", predicate)
+		return this.constrainIn("predicate", predicate)
 	}
 
 	divisibleBy(schema: Divisor.Schema): BaseRoot {
diff --git a/ark/schema/roots/union.ts b/ark/schema/roots/union.ts
index 4fabb5ad87..014a950d58 100644
--- a/ark/schema/roots/union.ts
+++ b/ark/schema/roots/union.ts
@@ -286,10 +286,10 @@ export class UnionNode extends BaseRoot<Union.Declaration> {
 			this.branches[i].traverseApply(data, ctx)
 			if (!ctx.hasError()) {
 				if (this.branches[i].includesMorph)
-					return ctx.queuedMorphs.push(...ctx.popBranch().queuedMorphs)
+					return ctx.queuedMorphs.push(...ctx.popBranch()!.queuedMorphs)
 				return ctx.popBranch()
 			}
-			errors.push(ctx.popBranch().error!)
+			errors.push(ctx.popBranch()!.error!)
 		}
 		ctx.errorFromNodeContext({ code: "union", errors, meta: this.meta })
 	}
diff --git a/ark/schema/scope.ts b/ark/schema/scope.ts
index 17cd027284..cda9f976cf 100644
--- a/ark/schema/scope.ts
+++ b/ark/schema/scope.ts
@@ -3,6 +3,7 @@ import {
 	flatMorph,
 	hasDomain,
 	isArray,
+	isEmptyObject,
 	isThunk,
 	printable,
 	throwInternalError,
@@ -14,11 +15,17 @@ import {
 	type anyOrNever,
 	type array,
 	type conform,
+	type dict,
 	type flattenListable,
 	type listable,
 	type noSuggest
 } from "@ark/util"
-import { resolveConfig, type ArkConfig } from "./config.ts"
+import {
+	mergeConfigs,
+	serializeConfig,
+	type ArkConfig,
+	type resolveConfig
+} from "./config.ts"
 import {
 	GenericRoot,
 	LazyGenericBody,
@@ -58,7 +65,11 @@ import { Alias } from "./roots/alias.ts"
 import type { BaseRoot } from "./roots/root.ts"
 import type { UnionNode } from "./roots/union.ts"
 import { CompiledFunction, NodeCompiler } from "./shared/compile.ts"
-import type { NodeKind, RootKind } from "./shared/implement.ts"
+import type {
+	NodeKind,
+	ParseConfigSnapshot,
+	RootKind
+} from "./shared/implement.ts"
 import { $ark } from "./shared/registry.ts"
 import type { TraverseAllows, TraverseApply } from "./shared/traversal.ts"
 import { arkKind, hasArkKind, isNode } from "./shared/utils.ts"
@@ -122,15 +133,14 @@ export interface ArkScopeConfig extends ArkConfig {
 	prereducedAliases?: boolean
 }
 
-export type ResolvedArkScopeConfig = resolveConfig<ArkScopeConfig>
+export type ResolvedScopeConfig = resolveConfig<ArkScopeConfig>
 
 $ark.ambient ??= {} as never
 
 let rawUnknownUnion: UnionNode | undefined
 
 export abstract class BaseScope<$ extends {} = {}> {
-	readonly config: ArkScopeConfig
-	readonly resolvedConfig: ResolvedArkScopeConfig
+	readonly config: ArkScopeConfig | undefined
 	readonly id = `${Object.keys(scopesById).length}$`
 
 	get [arkKind](): "scope" {
@@ -154,8 +164,7 @@ export abstract class BaseScope<$ extends {} = {}> {
 		def: Record<string, unknown>,
 		config?: ArkScopeConfig
 	) {
-		this.config = config ?? {}
-		this.resolvedConfig = resolveConfig(config)
+		this.config = config && !isEmptyObject(config) ? config : undefined
 
 		const aliasEntries = Object.entries(def).map(entry =>
 			this.preparseOwnAliasEntry(...entry)
@@ -214,6 +223,37 @@ export abstract class BaseScope<$ extends {} = {}> {
 		scopesById[this.id] = this
 	}
 
+	protected cacheGetter<name extends keyof this>(
+		name: name,
+		value: this[name]
+	): this[name] {
+		Object.defineProperty(this, name, { value })
+		return value
+	}
+
+	private _lastGlobalResolvedConfig: ArkConfig | undefined
+	private _lastConfigSnapshot: ParseConfigSnapshot | undefined
+	get configSnapshot(): ParseConfigSnapshot {
+		// can't use $ark.config for this check since it gets mutated
+		if (
+			this._lastConfigSnapshot &&
+			this._lastGlobalResolvedConfig === $ark.resolvedConfig
+		)
+			return this._lastConfigSnapshot
+		const configured =
+			this.config ? mergeConfigs($ark.config, this.config) : $ark.config
+		const hash = serializeConfig(configured)
+		const resolved = mergeConfigs($ark.defaultConfig, configured)
+
+		this._lastGlobalResolvedConfig = $ark.resolvedConfig
+
+		return {
+			configured,
+			hash,
+			resolved
+		}
+	}
+
 	get internal(): this {
 		return this
 	}
@@ -302,8 +342,11 @@ export abstract class BaseScope<$ extends {} = {}> {
 			}
 		}
 
+		if (isNode(schema) && schema.kind === kind) return schema
+
 		const impl = nodeImplementationsByKind[kind]
 		const normalizedSchema = impl.normalize?.(schema, this) ?? schema
+
 		// check again after normalization in case a node is a valid collapsed
 		// schema for the kind (e.g. sequence can collapse to element accepting a Node')
 		if (isNode(normalizedSchema)) {
@@ -324,17 +367,30 @@ export abstract class BaseScope<$ extends {} = {}> {
 	bindReference<reference extends BaseNode | GenericRoot>(
 		reference: reference
 	): reference {
-		const bound: reference =
-			reference.$ === this ? reference
-			: isNode(reference) ?
-				new (reference.constructor as any)(reference.attachments, this)
-			:	new GenericRoot(
-					reference.params as never,
-					reference.bodyDef,
-					reference.$,
-					this as never,
-					reference.hkt
-				)
+		let bound: reference
+
+		if (isNode(reference)) {
+			bound =
+				reference.configSnapshot.hash === this.configSnapshot.hash ?
+					reference.$ === this ?
+						reference
+					:	new (reference.constructor as any)(reference.attachments, this)
+				:	this.node(reference.kind, nodeToSchema(reference))
+		} else {
+			bound =
+				reference.$ === this ?
+					// for now, we don't worry about parseConfig updates on generics since
+					// they will be reflected when the type is instantiated, although we may
+					// want to reconsider this behavior for constraints
+					reference
+				:	(new GenericRoot(
+						reference.params as never,
+						reference.bodyDef,
+						reference.$,
+						this as never,
+						reference.hkt
+					) as never)
+		}
 
 		if (!this.resolved) {
 			// we're still parsing the scope itself, so defer compilation but
@@ -375,7 +431,7 @@ export abstract class BaseScope<$ extends {} = {}> {
 	maybeResolve(name: string): Exclude<CachedResolution, string> | undefined {
 		const cached = this.resolutions[name]
 		if (cached) {
-			if (typeof cached !== "string") return cached
+			if (typeof cached !== "string") return this.bindReference(cached)
 
 			const v = nodesByRegisteredId[cached]
 			if (hasArkKind(v, "root")) return (this.resolutions[name] = v)
@@ -479,13 +535,13 @@ export abstract class BaseScope<$ extends {} = {}> {
 
 			this.lazyResolutions.forEach(node => node.resolution)
 
-			if (this.resolvedConfig.ambient === true)
+			if (this.configSnapshot.resolved.ambient === true)
 				// spread all exports to ambient
 				Object.assign($ark.ambient as {}, this._exports)
-			else if (typeof this.resolvedConfig.ambient === "string") {
+			else if (typeof this.configSnapshot.resolved.ambient === "string") {
 				// add exports as a subscope with the config value as a name
 				Object.assign($ark.ambient as {}, {
-					[this.resolvedConfig.ambient]: new RootModule({
+					[this.configSnapshot.resolved.ambient]: new RootModule({
 						...this._exports
 					})
 				})
@@ -497,7 +553,7 @@ export abstract class BaseScope<$ extends {} = {}> {
 			Object.assign(this.resolutions, this._exportedResolutions)
 
 			this.references = Object.values(this.referencesById)
-			if (!this.resolvedConfig.jitless) {
+			if (!this.configSnapshot.resolved.jitless) {
 				this.precompilation = writePrecompilation(this.references)
 				bindPrecompilation(this.references, this.precompilation)
 			}
@@ -535,9 +591,11 @@ export abstract class BaseScope<$ extends {} = {}> {
 
 		const ctx = this.createParseContext(ctxOrNode)
 
-		return (nodesByRegisteredId[ctx.id] = this.bindReference(
-			parseNode(ctx)
-		)) as never
+		const node = parseNode(ctx)
+
+		const bound = this.bindReference(node)
+
+		return (nodesByRegisteredId[ctx.id] = bound) as never
 	}
 
 	parse = (def: unknown, opts: BaseParseOptions = {}): BaseRoot =>
@@ -565,7 +623,7 @@ export abstract class BaseScope<$ extends {} = {}> {
 
 	finalize<node extends BaseRoot>(node: node): node {
 		bootstrapAliasReferences(node)
-		if (!node.precompilation && !this.resolvedConfig.jitless)
+		if (!node.precompilation && !this.configSnapshot.resolved.jitless)
 			precompile(node.references)
 		return node
 	}
@@ -622,6 +680,12 @@ const bootstrapAliasReferences = (resolution: BaseRoot | GenericRoot) => {
 	return resolution
 }
 
+const nodeToSchema = (node: BaseNode): dict => {
+	const result: dict = { ...node.inner }
+	if (!isEmptyObject(node.meta)) result.meta = node.meta
+	return result
+}
+
 const resolutionsToJson = (resolutions: InternalResolutions): JsonStructure =>
 	flatMorph(resolutions, (k, v) => [
 		k,
diff --git a/ark/schema/shared/declare.ts b/ark/schema/shared/declare.ts
index 80b5fa0079..1a90593012 100644
--- a/ark/schema/shared/declare.ts
+++ b/ark/schema/shared/declare.ts
@@ -72,7 +72,12 @@ type prerequisiteOf<d extends DeclarationInput> =
 	"prerequisite" extends keyof d ? d["prerequisite"] : unknown
 
 export type attachmentsOf<d extends BaseNodeDeclaration> =
-	NarrowedAttachments<d> & d["inner"]
+	NarrowedAttachments<d> & attachedInner<d>
+
+// some nonsense to allow TS to infer attache properties on nodes with
+// a base declaration like Prop and Range
+type attachedInner<d extends BaseNodeDeclaration> =
+	"intersection" & d["kind"] extends never ? d["inner"] : {}
 
 export interface BaseNodeDeclaration {
 	kind: NodeKind
diff --git a/ark/schema/shared/disjoint.ts b/ark/schema/shared/disjoint.ts
index c84a3d4c2b..897f27fa65 100644
--- a/ark/schema/shared/disjoint.ts
+++ b/ark/schema/shared/disjoint.ts
@@ -63,6 +63,10 @@ export class Disjoint extends Array<DisjointEntry> {
 		return this
 	}
 
+	get summary(): string {
+		return this.describeReasons()
+	}
+
 	describeReasons(): string {
 		if (this.length === 1) {
 			const { path, l, r } = this[0]
diff --git a/ark/schema/shared/errors.ts b/ark/schema/shared/errors.ts
index 83ec6e3ddb..6bc32dce1f 100644
--- a/ark/schema/shared/errors.ts
+++ b/ark/schema/shared/errors.ts
@@ -10,12 +10,12 @@ import {
 	type propwiseXor,
 	type show
 } from "@ark/util"
-import type { ResolvedArkConfig } from "../config.ts"
+import type { ResolvedConfig } from "../config.ts"
 import type { Prerequisite, errorContext } from "../kinds.ts"
 import type { BaseMeta } from "./declare.ts"
 import type { NodeKind } from "./implement.ts"
 import type { StandardSchemaV1 } from "./standardSchema.ts"
-import type { TraversalContext } from "./traversal.ts"
+import type { Traversal } from "./traversal.ts"
 import { arkKind } from "./utils.ts"
 
 export type ArkErrorResult = ArkError | ArkErrors
@@ -26,12 +26,12 @@ export class ArkError<
 	readonly [arkKind] = "error"
 	path: ReadonlyPath
 	data: Prerequisite<code>
-	private nodeConfig: ResolvedArkConfig[code]
+	private nodeConfig: ResolvedConfig[code]
 	protected input: ArkErrorContextInput<code>
 
-	constructor(input: ArkErrorContextInput<code>, ctx: TraversalContext)
+	constructor(input: ArkErrorContextInput<code>, ctx: Traversal)
 	// TS gets confused by <code>, so internally we just use the base type for input
-	constructor(input: ArkErrorContextInput, ctx: TraversalContext) {
+	constructor(input: ArkErrorContextInput, ctx: Traversal) {
 		super()
 		this.input = input as never
 		defineProperties(this, input)
@@ -109,9 +109,9 @@ export class ArkErrors
 	extends ReadonlyArray<ArkError>
 	implements StandardSchemaV1.FailureResult
 {
-	protected ctx: TraversalContext
+	protected ctx: Traversal
 
-	constructor(ctx: TraversalContext) {
+	constructor(ctx: Traversal) {
 		super()
 		this.ctx = ctx
 	}
@@ -149,7 +149,7 @@ export class ArkErrors
 
 	/**
 	 * Add all errors from an ArkErrors instance, ignoring duplicates and
-	 * prefixing their paths with that of the current TraversalContext.
+	 * prefixing their paths with that of the current Traversal.
 	 */
 	merge(errors: ArkErrors): void {
 		errors.forEach(e => {
diff --git a/ark/schema/shared/implement.ts b/ark/schema/shared/implement.ts
index b6696b91f3..1b998b4411 100644
--- a/ark/schema/shared/implement.ts
+++ b/ark/schema/shared/implement.ts
@@ -22,7 +22,11 @@ import type {
 	schemaKindOrRightOf,
 	schemaKindRightOf
 } from "../roots/root.ts"
-import type { BaseScope } from "../scope.ts"
+import type {
+	ArkScopeConfig,
+	BaseScope,
+	ResolvedScopeConfig
+} from "../scope.ts"
 import type { Structure } from "../structure/structure.ts"
 import { compileSerializedValue } from "./compile.ts"
 import type {
@@ -299,6 +303,10 @@ interface CommonNodeImplementationInput<d extends BaseNodeDeclaration> {
 	kind: d["kind"]
 	keys: keySchemaDefinitions<d>
 	normalize: (schema: d["schema"], $: BaseScope) => d["normalizedSchema"]
+	applyConfig?: (
+		schema: d["normalizedSchema"],
+		config: ResolvedScopeConfig
+	) => d["normalizedSchema"]
 	hasAssociatedError: d["errorContext"] extends null ? false : true
 	finalizeInnerJson?: (json: {
 		[k in keyof d["inner"]]: Json
@@ -360,6 +368,12 @@ export type DescriptionWriter<kind extends NodeKind = NodeKind> = (
 	node: nodeOfKind<kind>
 ) => string
 
+export interface ParseConfigSnapshot {
+	configured: ArkScopeConfig
+	hash: string
+	resolved: ResolvedScopeConfig
+}
+
 export interface UnknownAttachments {
 	alias?: string
 	readonly kind: NodeKind
@@ -378,6 +392,8 @@ export interface UnknownAttachments {
 	readonly hash: string
 	readonly collapsibleJson: Json
 	readonly children: BaseNode[]
+
+	readonly configSnapshot: ParseConfigSnapshot
 }
 
 export interface NarrowedAttachments<d extends BaseNodeDeclaration>
diff --git a/ark/schema/shared/traversal.ts b/ark/schema/shared/traversal.ts
index cf806f3b91..49b913c8b9 100644
--- a/ark/schema/shared/traversal.ts
+++ b/ark/schema/shared/traversal.ts
@@ -1,5 +1,5 @@
-import { ReadonlyPath, type array } from "@ark/util"
-import type { ResolvedArkConfig } from "../config.ts"
+import { ReadonlyPath, stringifyPath, type array } from "@ark/util"
+import type { ResolvedConfig } from "../config.ts"
 import type { Morph } from "../roots/morph.ts"
 import {
 	ArkError,
@@ -16,41 +16,124 @@ export type MorphsAtPath = {
 	morphs: array<Morph>
 }
 
-export type BranchTraversalContext = {
+export type BranchTraversal = {
 	error: ArkError | undefined
 	queuedMorphs: MorphsAtPath[]
 }
 
 // avoid sugar methods internally
-export type InternalTraversalContext = Omit<
-	TraversalContext,
-	"error" | "mustBe" | "reject"
->
-
-export class TraversalContext {
+export type InternalTraversal = Omit<Traversal, "error" | "mustBe" | "reject">
+
+export class Traversal {
+	/**
+	 * #### the path being validated or morphed
+	 *
+	 * ✅ array indices represented as numbers
+	 * ⚠️ mutated during traversal - use `path.slice(0)` to snapshot
+	 * 🔗 use {@link propString} for a stringified version
+	 */
 	path: PropertyKey[] = []
-	queuedMorphs: MorphsAtPath[] = []
-	errors: ArkErrors = new ArkErrors(this)
-	branches: BranchTraversalContext[] = []
 
-	seen: { [id in string]?: unknown[] } = {}
+	/**
+	 * #### {@link ArkErrors} that will be part of this traversal's finalized result
+	 *
+	 * ✅ will always be an empty array for a valid traversal
+	 */
+	errors: ArkErrors = new ArkErrors(this)
 
+	/**
+	 * #### the original value being traversed
+	 */
 	root: unknown
-	config: ResolvedArkConfig
 
-	constructor(root: unknown, config: ResolvedArkConfig) {
+	/**
+	 * #### configuration for this traversal
+	 *
+	 * ✅ options can affect traversal results and error messages
+	 * ✅ defaults < global config < scope config
+	 * ✅ does not include options configured on individual types
+	 */
+	config: ResolvedConfig
+
+	queuedMorphs: MorphsAtPath[] = []
+	branches: BranchTraversal[] = []
+	seen: { [id in string]?: unknown[] } = {}
+
+	constructor(root: unknown, config: ResolvedConfig) {
 		this.root = root
 		this.config = config
 	}
 
-	// convenience for casting from InternalTraversalContext to TraversalContext
-	// for cases where the extra methods on the external type are expected, e.g.
-	// a morph or predicate
-	get external(): this {
-		return this
+	/**
+	 * #### the data being validated or morphed
+	 *
+	 * ✅ extracted from {@link root} at {@link path}
+	 */
+	get data(): unknown {
+		let result: any = this.root
+		for (const segment of this.path) result = result?.[segment]
+
+		return result
+	}
+
+	/**
+	 * #### a string representing {@link path}
+	 *
+	 * @propString
+	 */
+	get propString(): string {
+		return stringifyPath(this.path)
+	}
+
+	/**
+	 * #### add an {@link ArkError} and return `false`
+	 *
+	 * ✅ useful for predicates like `.narrow`
+	 */
+	reject(input: ArkErrorInput): false {
+		this.error(input)
+		return false
+	}
+
+	/**
+	 * #### add an {@link ArkError} from a description and return `false`
+	 *
+	 * ✅ useful for predicates like `.narrow`
+	 * 🔗 equivalent to {@link reject}({ expected })
+	 */
+	mustBe(expected: string): false {
+		this.error(expected)
+		return false
+	}
+
+	/**
+	 * #### add and return an {@link ArkError}
+	 *
+	 * ✅ useful for morphs like `.pipe`
+	 */
+	error<input extends ArkErrorInput>(
+		input: input
+	): ArkError<
+		input extends { code: ArkErrorCode } ? input["code"] : "predicate"
+	>
+	error(input: ArkErrorInput): ArkError {
+		const errCtx: ArkErrorContextInput =
+			typeof input === "object" ?
+				input.code ?
+					input
+				:	{ ...input, code: "predicate" }
+			:	{ code: "predicate", expected: input }
+		return this.errorFromContext(errCtx)
+	}
+
+	/**
+	 * #### whether {@link currentBranch} (or the traversal root, outside a union) has one or more errors
+	 */
+	hasError(): boolean {
+		return this.currentErrorCount !== 0
 	}
 
-	get currentBranch(): BranchTraversalContext | undefined {
+	get currentBranch(): BranchTraversal | undefined {
 		return this.branches.at(-1)
 	}
 
@@ -79,6 +162,59 @@ export class TraversalContext {
 		return this.hasError() ? this.errors : this.root
 	}
 
+	get currentErrorCount(): number {
+		return (
+			this.currentBranch ?
+				this.currentBranch.error ?
+					1
+				:	0
+			:	this.errors.count
+		)
+	}
+
+	get failFast(): boolean {
+		return this.branches.length !== 0
+	}
+
+	pushBranch(): void {
+		this.branches.push({
+			error: undefined,
+			queuedMorphs: []
+		})
+	}
+
+	popBranch(): BranchTraversal | undefined {
+		return this.branches.pop()
+	}
+
+	/**
+	 * @internal
+	 * Convenience for casting from InternalTraversal to Traversal
+	 * for cases where the extra methods on the external type are expected, e.g.
+	 * a morph or predicate.
+	 */
+	get external(): this {
+		return this
+	}
+
+	/**
+	 * @internal
+	 */
+	errorFromNodeContext<input extends NodeErrorContextInput>(
+		input: input
+	): ArkError<input["code"]>
+	errorFromNodeContext(input: NodeErrorContextInput): ArkError {
+		return this.errorFromContext(input)
+	}
+
+	private errorFromContext(errCtx: ArkErrorContextInput): ArkError {
+		const error = new ArkError(errCtx, this)
+		if (this.currentBranch) this.currentBranch.error = error
+		else this.errors.add(error)
+
+		return error as never
+	}
+
 	private applyQueuedMorphs() {
 		// invoking morphs that are Nodes will reuse this context, potentially
 		// adding additional morphs, so we have to continue looping until
@@ -144,89 +280,13 @@ export class TraversalContext {
 			this.applyQueuedMorphs()
 		}
 	}
-
-	get currentErrorCount(): number {
-		return (
-			this.currentBranch ?
-				this.currentBranch.error ?
-					1
-				:	0
-			:	this.errors.count
-		)
-	}
-
-	hasError(): boolean {
-		return this.currentErrorCount !== 0
-	}
-
-	get failFast(): boolean {
-		return this.branches.length !== 0
-	}
-
-	errorFromNodeContext<input extends NodeErrorContextInput>(
-		input: input
-	): ArkError<input["code"]>
-	errorFromNodeContext(input: NodeErrorContextInput): ArkError {
-		return this.errorFromContext(input)
-	}
-
-	error<input extends ArkErrorInput>(
-		input: input
-	): ArkError<
-		input extends { code: ArkErrorCode } ? input["code"] : "predicate"
-	>
-	error(input: ArkErrorInput): ArkError {
-		const errCtx: ArkErrorContextInput =
-			typeof input === "object" ?
-				input.code ?
-					input
-				:	{ ...input, code: "predicate" }
-			:	{ code: "predicate", expected: input }
-		return this.errorFromContext(errCtx)
-	}
-
-	private errorFromContext(errCtx: ArkErrorContextInput): ArkError {
-		const error = new ArkError(errCtx, this)
-		if (this.currentBranch) this.currentBranch.error = error
-		else this.errors.add(error)
-
-		return error as never
-	}
-
-	get data(): unknown {
-		let result: any = this.root
-		for (const segment of this.path) result = result?.[segment]
-
-		return result
-	}
-
-	reject(input: ArkErrorInput): false {
-		this.error(input)
-		return false
-	}
-
-	mustBe(expected: string): false {
-		this.error(expected)
-		return false
-	}
-
-	pushBranch(): void {
-		this.branches.push({
-			error: undefined,
-			queuedMorphs: []
-		})
-	}
-
-	popBranch(): BranchTraversalContext {
-		return this.branches.pop()!
-	}
 }
 
 export const traverseKey = <result>(
 	key: PropertyKey,
 	fn: () => result,
 	// ctx will be undefined if this node isn't context-dependent
-	ctx: InternalTraversalContext | undefined
+	ctx: InternalTraversal | undefined
 ): result => {
 	if (!ctx) return fn()
 
@@ -245,9 +305,9 @@ export type TraversalKind = keyof TraversalMethodsByKind
 
 export type TraverseAllows<data = unknown> = (
 	data: data,
-	ctx: InternalTraversalContext
+	ctx: InternalTraversal
 ) => boolean
 export type TraverseApply<data = unknown> = (
 	data: data,
-	ctx: InternalTraversalContext
+	ctx: InternalTraversal
 ) => void
diff --git a/ark/schema/structure/structure.ts b/ark/schema/structure/structure.ts
index 8fe38b1a30..dc7414e755 100644
--- a/ark/schema/structure/structure.ts
+++ b/ark/schema/structure/structure.ts
@@ -35,7 +35,7 @@ import {
 } from "../shared/registry.ts"
 import {
 	traverseKey,
-	type InternalTraversalContext,
+	type InternalTraversal,
 	type TraversalKind,
 	type TraverseAllows,
 	type TraverseApply
@@ -53,11 +53,9 @@ import type { Sequence } from "./sequence.ts"
 import { arrayIndexMatcherReference } from "./shared.ts"
 
 /**
- * `"ignore"` (default) - allow and preserve extra properties
- *
- * `"reject"` - disallow extra properties
- *
- * `"delete"` - clone and remove extra properties from output
+ * - `"ignore"` (default) - allow and preserve extra properties
+ * - `"reject"` - disallow extra properties
+ * - `"delete"` - clone and remove extra properties from output
  */
 export type UndeclaredKeyBehavior = "ignore" | UndeclaredKeyHandling
 
@@ -120,11 +118,12 @@ const implementation: nodeImplementationOf<Structure.Declaration> =
 	implementNode<Structure.Declaration>({
 		kind: "structure",
 		hasAssociatedError: false,
-		normalize: (schema, $) => {
-			if (!schema.undeclared && $.resolvedConfig.onUndeclaredKey !== "ignore") {
+		normalize: schema => schema,
+		applyConfig: (schema, config) => {
+			if (!schema.undeclared && config.onUndeclaredKey !== "ignore") {
 				return {
 					...schema,
-					undeclared: $.resolvedConfig.onUndeclaredKey
+					undeclared: config.onUndeclaredKey
 				}
 			}
 			return schema
@@ -169,7 +168,16 @@ const implementation: nodeImplementationOf<Structure.Declaration> =
 				parse: constraintKeyParser("sequence")
 			},
 			undeclared: {
-				parse: behavior => (behavior === "ignore" ? undefined : behavior)
+				parse: behavior => (behavior === "ignore" ? undefined : behavior),
+				reduceIo: (ioKind, inner, value) => {
+					if (value !== "delete") return
+
+					// if base is "delete", undeclared keys are "ignore" (i.e. unconstrained)
+					// on input and "reject" on output
+
+					if (ioKind === "in") delete inner.undeclared
+					else inner.undeclared = "reject"
+				}
 			}
 		},
 		defaults: {
@@ -441,9 +449,6 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 		return required ? result : result.or($ark.intrinsic.undefined)
 	}
 
-	readonly exhaustive: boolean =
-		this.undeclared !== undefined || this.index !== undefined
-
 	pick(...keys: KeyOrKeyNode[]): StructureNode {
 		this.assertHasKeys(keys)
 		return this.$.node("structure", this.filterKeys("pick", keys))
@@ -523,7 +528,7 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 	protected _traverse = (
 		traversalKind: TraversalKind,
 		data: object,
-		ctx: InternalTraversalContext
+		ctx: InternalTraversal
 	): boolean => {
 		const errorCount = ctx?.currentErrorCount ?? 0
 		for (let i = 0; i < this.props.length; i++) {
@@ -544,7 +549,7 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 			}
 		}
 
-		if (!this.exhaustive) return true
+		if (!requireExhasutiveTraversal(this, traversalKind)) return true
 
 		const keys: Key[] = Object.keys(data)
 		keys.push(...Object.getOwnPropertySymbols(data))
@@ -626,7 +631,7 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 			if (js.traversalKind === "Apply") js.returnIfFailFast()
 		}
 
-		if (this.exhaustive) {
+		if (requireExhasutiveTraversal(this, js.traversalKind)) {
 			js.const("keys", "Object.keys(data)")
 			js.line("keys.push(...Object.getOwnPropertySymbols(data))")
 			js.for("i < keys.length", () => this.compileExhaustiveEntry(js))
@@ -699,7 +704,7 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 			this.props.forEach(prop => {
 				if (typeof prop.key === "symbol") {
 					return JsonSchema.throwUnjsonifiableError(
-						`Sybolic key ${prop.serializedKey}`
+						`Symbolic key ${prop.serializedKey}`
 					)
 				}
 
@@ -722,7 +727,7 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 			index.signature.branches.forEach(keyBranch => {
 				if (
 					!keyBranch.hasKind("intersection") ||
-					keyBranch.pattern?.length !== 1
+					keyBranch.inner.pattern?.length !== 1
 				) {
 					return JsonSchema.throwUnjsonifiableError(
 						`Index signature ${keyBranch}`
@@ -730,7 +735,7 @@ export class StructureNode extends BaseConstraint<Structure.Declaration> {
 				}
 
 				schema.patternProperties ??= {}
-				schema.patternProperties[keyBranch.pattern[0].rule] =
+				schema.patternProperties[keyBranch.inner.pattern[0].rule] =
 					index.value.toJsonSchema()
 			})
 		})
@@ -760,6 +765,19 @@ export const Structure = {
 	Node: StructureNode
 }
 
+const requireExhasutiveTraversal = (
+	node: Structure.Node,
+	traversalKind: TraversalKind
+) => {
+	if (node.index || node.undeclared === "reject") return true
+
+	// when applying key deletion, we must queue morphs for all undeclared keys
+	// when checking whether an input is allowed, they are irrelevant because it always will be
+	if (node.undeclared === "delete" && traversalKind === "Apply") return true
+
+	return false
+}
+
 const indexerToKey = (indexable: GettableKeyOrNode): KeyOrKeyNode => {
 	if (hasArkKind(indexable, "root") && indexable.hasKind("unit"))
 		indexable = indexable.unit as Key
diff --git a/ark/type/__tests__/clone.test.ts b/ark/type/__tests__/clone.test.ts
index 88d80179ab..5dfc8e49c9 100644
--- a/ark/type/__tests__/clone.test.ts
+++ b/ark/type/__tests__/clone.test.ts
@@ -1,4 +1,5 @@
 import { attest, contextualize } from "@ark/attest"
+import { $ark } from "@ark/schema"
 import { configure, type } from "arktype"
 
 contextualize(() => {
@@ -112,5 +113,7 @@ contextualize(() => {
 		// the original object's age key is now a number
 		attest(formData.age).unknown.equals(42)
 		attest(formData).unknown.equals(out)
+
+		configure({ clone: $ark.defaultConfig.clone })
 	})
 })
diff --git a/ark/type/__tests__/config.test.ts b/ark/type/__tests__/config.test.ts
index 8300db7c72..6838361575 100644
--- a/ark/type/__tests__/config.test.ts
+++ b/ark/type/__tests__/config.test.ts
@@ -157,4 +157,86 @@ contextualize(() => {
 		})
 		attest(types.inner.foo.precompilation).satisfies("string")
 	})
+
+	it("numberAllowsNaN", () => {
+		const { nanable } = type.module(
+			{ nanable: "number" },
+			{ numberAllowsNaN: true }
+		)
+
+		attest(nanable.allows(Number.NaN)).equals(true)
+
+		const { nonNanable } = type.module({
+			nonNanable: "number"
+		})
+
+		attest(nonNanable.allows(Number.NaN)).equals(false)
+	})
+
+	it("dateAllowsInvalid", () => {
+		const { invalidable } = type.module(
+			{ invalidable: "Date" },
+			{ dateAllowsInvalid: true }
+		)
+
+		attest(invalidable.allows(new Date("!"))).equals(true)
+
+		const { uninvalidable } = type.module({
+			uninvalidable: "number"
+		})
+
+		attest(uninvalidable.allows(new Date("!"))).equals(false)
+	})
+
+	it("rebinds config in new scope", () => {
+		const t = type({
+			foo: "string"
+		})
+
+		const types = type.module(
+			{
+				foo: t
+			},
+			{ onUndeclaredKey: "reject" }
+		)
+
+		attest(types.foo.json).snap({
+			undeclared: "reject",
+			required: [{ key: "foo", value: "string" }],
+			domain: "object"
+		})
+	})
+
+	it("docs actual example", () => {
+		// avoid logging "was xxx" for password
+		const password = type("string >= 8", "@", { actual: () => "" })
+
+		const user = type({
+			email: "string.email",
+			password
+		})
+
+		const out = user({
+			email: "david@arktype.io",
+			password: "ez123"
+		})
+
+		attest(out.toString()).snap("password must be at least length 8")
+	})
+
+	it("docs message example", () => {
+		const user = type({
+			password: "string >= 8"
+		}).configure({
+			message: ctx =>
+				`${ctx.propString || "(root)"}: ${ctx.actual} isn't ${ctx.expected}`
+		})
+		// ArkErrors: (root): a string isn't an object
+		const out1 = user("ez123")
+		attest(out1.toString()).snap("(root): a string isn't an object")
+		// but `.configure` only applies shallowly, so the nested error isn't changed!
+		// ArkErrors: password must be at least length 8 (was 5)
+		const out2 = user({ password: "ez123" })
+		attest(out2.toString()).snap("password must be at least length 8 (was 5)")
+	})
 })
diff --git a/ark/type/__tests__/filter.test.ts b/ark/type/__tests__/filter.test.ts
new file mode 100644
index 0000000000..236ca89bce
--- /dev/null
+++ b/ark/type/__tests__/filter.test.ts
@@ -0,0 +1,52 @@
+import { attest, contextualize } from "@ark/attest"
+import { type } from "arktype"
+import type { Out } from "arktype/internal/attributes.ts"
+
+contextualize(() => {
+	const parseNumber = (s: string) => Number(s)
+
+	it("applies to input", () => {
+		const stringIsLong = (s: string) => s.length > 5
+		const parseLongNumber = type("string")
+			.pipe(parseNumber)
+			.filter(stringIsLong)
+
+		attest<(In: string) => Out<number>>(parseLongNumber.t)
+
+		attest(parseLongNumber.json).snap({
+			in: { domain: "string", predicate: ["$ark.stringIsLong"] },
+			morphs: ["$ark.parseNumber"]
+		})
+
+		attest(parseLongNumber("123456")).snap(123456)
+		attest(parseLongNumber("123").toString()).snap(
+			'must be valid according to stringIsLong (was "123")'
+		)
+		attest(parseLongNumber(123456).toString()).snap(
+			"must be a string (was a number)"
+		)
+	})
+
+	it("predicate inferred on input", () => {
+		const stringIsIntegerLike = (s: string): s is `${bigint}` =>
+			/^-?\d+$/.test(s)
+		const parseIntegerLike = type("string")
+			.pipe(parseNumber)
+			.filter(stringIsIntegerLike)
+
+		attest<(In: `${bigint}`) => Out<number>>(parseIntegerLike.t)
+
+		attest(parseIntegerLike.json).snap({
+			in: { domain: "string", predicate: ["$ark.stringIsIntegerLike"] },
+			morphs: ["$ark.parseNumber"]
+		})
+
+		attest(parseIntegerLike("123456")).snap(123456)
+		attest(parseIntegerLike("3.14159").toString()).snap(
+			'must be valid according to stringIsIntegerLike (was "3.14159")'
+		)
+		attest(parseIntegerLike(123456).toString()).snap(
+			"must be a string (was a number)"
+		)
+	})
+})
diff --git a/ark/type/__tests__/get.test.ts b/ark/type/__tests__/get.test.ts
index 3bb88ed27d..28b69e4de6 100644
--- a/ark/type/__tests__/get.test.ts
+++ b/ark/type/__tests__/get.test.ts
@@ -132,7 +132,7 @@ contextualize(() => {
 			writeInvalidKeysMessage(t.expression, ["5.5"])
 		)
 
-		attest(t.get(keywords.Array.index).expression).snap("string | undefined")
+		attest(t.get(type.arrayIndex).expression).snap("string | undefined")
 	})
 
 	it("number access on non-variadic", () => {
diff --git a/ark/type/__tests__/keywords/number.test.ts b/ark/type/__tests__/keywords/number.test.ts
index 7882466299..3eaf0e02c5 100644
--- a/ark/type/__tests__/keywords/number.test.ts
+++ b/ark/type/__tests__/keywords/number.test.ts
@@ -51,7 +51,14 @@ contextualize(() => {
 		attest(safe(-Infinity).toString()).snap(
 			"must be at least -9007199254740991 (was -Infinity)"
 		)
-		attest(safe(NaN).toString()).snap("must be a safe number (was NaN)")
+		attest(safe(NaN).toString()).snap("must be a number (was NaN)")
+	})
+
+	it("doesn't allow NaN by default", () => {
+		attest(type.number.allows(Number.NaN)).equals(false)
+		attest(type.number(Number.NaN).toString()).snap(
+			"must be a number (was NaN)"
+		)
 	})
 
 	it("NaN", () => {
diff --git a/ark/type/__tests__/realWorld.test.ts b/ark/type/__tests__/realWorld.test.ts
index 6be3ea5ca9..2dae6ec6bc 100644
--- a/ark/type/__tests__/realWorld.test.ts
+++ b/ark/type/__tests__/realWorld.test.ts
@@ -1031,4 +1031,43 @@ nospace must be matched by ^\\S*$ (was "One space")`)
 		)
 		attest(feedbackSchema.t).type.toString.snap(`{ contact: string }`)
 	})
+
+	it("deleted undeclared keys allowed in input", () => {
+		const t = type({ foo: "string" }).onUndeclaredKey("delete")
+
+		attest(t.json).snap({
+			undeclared: "delete",
+			required: [{ key: "foo", value: "string" }],
+			domain: "object"
+		})
+
+		attest(t.in.json).snap({
+			required: [{ key: "foo", value: "string" }],
+			domain: "object"
+		})
+
+		const extras = { foo: "hi", bar: 3 }
+
+		attest(t(extras)).equals({ foo: "hi" })
+		attest(t.allows(extras)).equals(true)
+		attest(t.in(extras)).equals(extras)
+	})
+
+	it("deleted undeclared keys rejected in output", () => {
+		const t = type({ foo: "string" }).onUndeclaredKey("delete")
+
+		attest(t.json).snap({
+			undeclared: "delete",
+			required: [{ key: "foo", value: "string" }],
+			domain: "object"
+		})
+
+		attest(t.out.json).snap({
+			undeclared: "reject",
+			required: [{ key: "foo", value: "string" }],
+			domain: "object"
+		})
+
+		attest(t.out({ foo: "hi", bar: 3 }).toString()).snap("bar must be removed")
+	})
 })
diff --git a/ark/type/__tests__/submodule.test.ts b/ark/type/__tests__/submodule.test.ts
index a9dd271f26..74438b197f 100644
--- a/ark/type/__tests__/submodule.test.ts
+++ b/ark/type/__tests__/submodule.test.ts
@@ -37,8 +37,8 @@ contextualize.each(
 
 			attest<number>(types.sub.alias.infer)
 			const expected = type("number").json
-			attest(types.sub.alias.json).is(expected)
-			attest(types.b.json).is(expected)
+			attest(types.sub.alias.json).equals(expected)
+			attest(types.b.json).equals(expected)
 		})
 
 		it("non-submodule dot access", $ => {
diff --git a/ark/type/__tests__/traverse.test.ts b/ark/type/__tests__/traverse.test.ts
index be94f319a4..734809e750 100644
--- a/ark/type/__tests__/traverse.test.ts
+++ b/ark/type/__tests__/traverse.test.ts
@@ -241,4 +241,29 @@ age must be more than 18 (was 2)`)
 		attest(out.toString()).snap('must be valid (was {"foo":1})')
 		attest(callCount).equals(0)
 	})
+
+	it("ctx.path docs example", () => {
+		const symbolicKey = Symbol("ctxPathExampleSymbol")
+
+		let path: PropertyKey[] | undefined
+
+		const notFoo = type.string.narrow((s, ctx) => {
+			if (s !== "foo") return true
+			path = ctx.path.slice(0)
+			return ctx.mustBe("not foo")
+		})
+
+		const obj = type({
+			stringKey: {
+				[symbolicKey]: notFoo.array()
+			}
+		})
+
+		attest(
+			obj({ stringKey: { [symbolicKey]: ["bar", "foo"] } }).toString()
+		).snap(
+			'stringKey[Symbol(ctxPathExampleSymbol)][1] must be not foo (was "foo")'
+		)
+		attest(path).snap(["stringKey", "Symbol(ctxPathExampleSymbol)", 1])
+	})
 })
diff --git a/ark/type/__tests__/type.test.ts b/ark/type/__tests__/type.test.ts
index f4282f58da..3d08cddf07 100644
--- a/ark/type/__tests__/type.test.ts
+++ b/ark/type/__tests__/type.test.ts
@@ -28,6 +28,15 @@ contextualize(() => {
 		attest(numerics).snap([0, 2n])
 	})
 
+	it("extends doc example", () => {
+		const n = type(Math.random() > 0.5 ? "boolean" : "string")
+		attest(n.expression).satisfies("string | boolean")
+		attest(n.t).type.toString.snap("string | boolean")
+		const ez = n.ifExtends("boolean")
+		attest(ez?.expression).satisfies("'boolean' | undefined")
+		attest(ez?.t).type.toString.snap("boolean | undefined")
+	})
+
 	it("errors can be thrown", () => {
 		const t = type("number")
 		try {
@@ -113,6 +122,7 @@ contextualize(() => {
 			true: "true",
 			unknown: "unknown",
 			undefined: "undefined",
+			arrayIndex: type.arrayIndex.expression,
 			Key: "string | symbol",
 			Record: keywords.Record.internal.json,
 			Date: "Date",
diff --git a/ark/type/keywords/keywords.ts b/ark/type/keywords/keywords.ts
index 7920c8d336..8a18aa8526 100644
--- a/ark/type/keywords/keywords.ts
+++ b/ark/type/keywords/keywords.ts
@@ -42,6 +42,7 @@ export declare namespace Ark {
 	}
 
 	export interface typeAttachments extends arkTsKeywords.$ {
+		arrayIndex: arkPrototypes.$["Array"]["index"]
 		Key: arkBuiltins.$["Key"]
 		Record: arkTsGenerics.$["Record"]
 		Date: arkPrototypes.$["Date"]
@@ -54,6 +55,7 @@ export declare namespace Ark {
 
 $arkTypeRegistry.typeAttachments = {
 	...arkTsKeywords,
+	arrayIndex: arkPrototypes.Array.index,
 	Key: arkBuiltins.Key,
 	Record: arkTsGenerics.Record,
 	Array: arkPrototypes.Array.root,
diff --git a/ark/type/keywords/number.ts b/ark/type/keywords/number.ts
index b2b1570dae..8962a9cd6b 100644
--- a/ark/type/keywords/number.ts
+++ b/ark/type/keywords/number.ts
@@ -39,13 +39,12 @@ export const number: number.module = Scope.module({
 	integer,
 	epoch,
 	safe: rootSchema({
-		domain: "number",
+		domain: {
+			domain: "number",
+			numberAllowsNaN: false
+		},
 		min: Number.MIN_SAFE_INTEGER,
-		max: Number.MAX_SAFE_INTEGER,
-		predicate: {
-			predicate: n => !Number.isNaN(n),
-			meta: "a safe number"
-		}
+		max: Number.MAX_SAFE_INTEGER
 	}),
 	NaN: ["===", Number.NaN],
 	Infinity: ["===", Number.POSITIVE_INFINITY],
diff --git a/ark/type/keywords/string.ts b/ark/type/keywords/string.ts
index 83121ffcc9..0f81e292cc 100644
--- a/ark/type/keywords/string.ts
+++ b/ark/type/keywords/string.ts
@@ -5,7 +5,7 @@ import {
 	rootSchema,
 	type IntersectionNode,
 	type Morph,
-	type TraversalContext
+	type Traversal
 } from "@ark/schema"
 import {
 	flatMorph,
@@ -42,7 +42,7 @@ export const stringInteger: stringInteger.module = Scope.module({
 	root: stringIntegerRoot,
 	parse: rootSchema({
 		in: stringIntegerRoot,
-		morphs: (s: string, ctx: TraversalContext) => {
+		morphs: (s: string, ctx: Traversal) => {
 			const parsed = Number.parseInt(s)
 			return Number.isSafeInteger(parsed) ? parsed : (
 					ctx.error(
@@ -297,7 +297,7 @@ export const stringDate: stringDate.module = Scope.module({
 	parse: rootSchema({
 		declaredIn: parsableDate,
 		in: "string",
-		morphs: (s: string, ctx: TraversalContext) => {
+		morphs: (s: string, ctx: Traversal) => {
 			const date = new Date(s)
 			if (Number.isNaN(date.valueOf())) return ctx.error("a parsable date")
 			return date
@@ -409,7 +409,7 @@ const jsonRoot = rootSchema({
 	}
 })
 
-const parseJson: Morph<string> = (s: string, ctx: TraversalContext) => {
+const parseJson: Morph<string> = (s: string, ctx: Traversal) => {
 	if (s.length === 0) {
 		return ctx.error({
 			code: "predicate",
@@ -684,7 +684,7 @@ export const url: url.module = Scope.module({
 	parse: rootSchema({
 		declaredIn: urlRoot,
 		in: "string",
-		morphs: (s: string, ctx: TraversalContext) => {
+		morphs: (s: string, ctx: Traversal) => {
 			try {
 				return new URL(s)
 			} catch {
diff --git a/ark/type/methods/base.ts b/ark/type/methods/base.ts
index dcca3ad1d1..579cd624b1 100644
--- a/ark/type/methods/base.ts
+++ b/ark/type/methods/base.ts
@@ -41,46 +41,46 @@ interface Type<out t = unknown, $ = {}>
 	[inferred]: t
 
 	/**
-	 * The precompiled JS used to optimize validation.
-	 * Will be `undefined` in [jitless](https://arktype.io/docs/configuration#jitless) mode.
+	 * precompiled JS used to optimize validation
+	 *
+	 * ⚠️ will be `undefined` in [jitless](https://arktype.io/docs/configuration#jitless) mode
 	 */
 	precompilation: string | undefined
 
 	/**
-	 * The generic parameter representing this Type
+	 * generic parameter representing this Type
 	 *
 	 * @typeonly
 	 *
-	 * - ⚠️ May contain types representing morphs or default values that would
+	 * ⚠️ May contain types representing morphs or default values that would
 	 * be inaccurate if used directly for runtime values. In those cases,
 	 * you should use {@link infer} or {@link inferIn} on this object instead.
 	 */
 	t: t
 
 	/**
-	 * The {@link Scope} in which definitions for this Type its chained methods are parsed
-	 * @api Type
+	 * #### {@link Scope} in which chained methods are parsed
 	 */
 	$: Scope<$>
 
 	/**
-	 * The type of data this returns
+	 * #### type of output this returns
 	 *
 	 * @typeonly
 	 *
 	 * @example
 	 * const parseNumber = type("string").pipe(s => Number.parseInt(s))
 	 * type ParsedNumber = typeof parseNumber.infer // number
-	 *
-	 * @api Type
 	 */
 	infer: this["inferOut"]
 
 	/**
-	 * Alias of {@link infer}
+	 * type of output this returns
 	 *
+	 * 🔗 alias of {@link infer}
 	 * @typeonly
 	 *
+	 *
 	 * @example
 	 * const parseNumber = type("string").pipe(s => Number.parseInt(s))
 	 * type ParsedNumber = typeof parseNumber.infer // number
@@ -88,10 +88,11 @@ interface Type<out t = unknown, $ = {}>
 	inferOut: distill.Out<t>
 
 	/**
-	 * The type of output that can be introspected at runtime (e.g. via {@link out})
+	 * type of output that can be introspected at runtime (e.g. via {@link out})
 	 *
-	 * - If your Type contains morphs, they will be inferred as `unknown` unless
+	 * ⚠️ If your Type contains morphs, they will be inferred as `unknown` unless
 	 * they are an ArkType keyword or have an explicitly defined output validator.
+	 *
 	 * @typeonly
 	 *
 	 * @example
@@ -112,73 +113,66 @@ interface Type<out t = unknown, $ = {}>
 	inferIntrospectableOut: distill.introspectable.Out<t>
 
 	/**
-	 * The type of data this expects
+	 * #### type of input this allows
 	 *
 	 * @typeonly
 	 *
 	 * @example
 	 * const parseNumber = type("string").pipe(s => Number.parseInt(s))
 	 * type UnparsedNumber = typeof parseNumber.inferIn // string
-	 * @api Type
 	 */
 	inferIn: distill.In<t>
 
 	/**
-	 * The internal JSON representation
-	 * @api Type
+	 * #### internal JSON representation
 	 */
 	json: JsonStructure
 
 	/**
-	 * Alias of {@link json} for `JSON.stringify` compatibility
+	 * alias of {@link json} for `JSON.stringify` compatibility
 	 */
 	toJSON(): JsonStructure
 
 	/**
-	 * Generate a JSON Schema
+	 * #### generate a JSON Schema
+	 *
 	 * @throws {JsonSchema.UnjsonifiableError} if this cannot be converted to JSON Schema
-	 * @api Type
 	 */
 	toJsonSchema(): JsonSchema
 
 	/**
-	 * Metadata like custom descriptions and error messages
+	 * #### metadata like custom descriptions and error messages
 	 *
-	 * @description The type of this property {@link https://arktype.io/docs/configuration#custom | can be extended} by your project.
-	 * @api Type
+	 * ✅ type {@link https://arktype.io/docs/configuration#custom | can be customized} for your project
 	 */
 	meta: ArkAmbient.meta
 
 	/**
-	 * An English description
+	 * #### human-readable English description
 	 *
-	 * - Work best for primitive values
+	 * ✅ works best for primitive values
 	 *
 	 * @example
 	 * const n = type("0 < number <= 100")
 	 * console.log(n.description) // positive and at most 100
-	 *
-	 * @api Type
 	 */
 	description: string
 
 	/**
-	 * A syntax string similar to native TypeScript
+	 * #### syntax string similar to native TypeScript
 	 *
-	 * - Works well for both primitives and structures
+	 * ✅ works well for both primitives and structures
 	 *
 	 * @example
 	 * const loc = type({ coords: ["number", "number"] })
 	 * console.log(loc.expression) // { coords: [number, number] }
-	 *
-	 * @api Type
 	 */
 	expression: string
 
 	/**
-	 * Validate and morph data, throwing a descriptive AggregateError on failure
+	 * #### validate and return transformed data or throw
 	 *
-	 * - Sugar to avoid checking for {@link type.errors} if they are unrecoverable
+	 * ✅ sugar to avoid checking for {@link type.errors} if they are unrecoverable
 	 *
 	 * @example
 	 * const criticalPayload = type({
@@ -189,29 +183,25 @@ interface Type<out t = unknown, $ = {}>
 	 * console.log(data.superImportantValue) // valid output can be accessed directly
 	 *
 	 * @throws {AggregateError}
-	 * @api Type
 	 */
 	assert(data: unknown): this["infer"]
 
 	/**
-	 * Validate input data without applying morphs
+	 * #### check input without applying morphs
 	 *
-	 * - Good for cases like filtering that don't benefit from detailed errors
+	 * ✅ good for stuff like filtering that doesn't benefit from detailed errors
 	 *
 	 * @example
 	 * const numeric = type("number | bigint")
 	 * // [0, 2n]
 	 * const numerics = [0, "one", 2n].filter(numeric.allows)
-	 *
-	 * @api Type
 	 */
 	allows(data: unknown): data is this["inferIn"]
 
 	/**
-	 * Clone and add metadata to shallow references
+	 * #### add metadata to shallow references
 	 *
-	 * - Does not affect error messages within properties of an object
-	 * - Overlapping keys on existing meta will be overwritten
+	 * ⚠️ does not affect error messages within properties of an object
 	 *
 	 * @example
 	 * const notOdd = type("number % 2").configure({ description: "not odd" })
@@ -228,128 +218,222 @@ interface Type<out t = unknown, $ = {}>
 	 * const oddProp = notOddBox({ notOdd: 3 }) // notOdd must be even (was 3)
 	 * // error message at root is affected, leading to a misleading description
 	 * const nonObject = notOddBox(null) // must be not odd (was null)
-	 *
-	 * @api Type
 	 */
 	configure(meta: MetaSchema): this
 
 	/**
-	 * Clone and add the description to shallow references
+	 * #### add description to shallow references
 	 *
-	 * - Equivalent to `.configure({ description })` (see {@link configure})
-	 * - Does not affect error messages within properties of an object
+	 * 🔗 equivalent to `.configure({ description })` (see {@link configure})
+	 * ⚠️ does not affect error messages within properties of an object
 	 *
 	 * @example
 	 * const aToZ = type(/^a.*z$/).describe("a string like 'a...z'")
 	 * const good = aToZ("alcatraz") // "alcatraz"
-	 * // notice how our description is integrated with other parts of the message
-	 * const badPattern = aToZ("albatross") // must be a string like 'a...z' (was "albatross")
-	 * const nonString = aToZ(123) // must be a string like 'a...z' (was 123)
-	 *
-	 * @api Type
+	 * // ArkErrors: must be a string like 'a...z' (was "albatross")
+	 * const badPattern = aToZ("albatross")
 	 */
 	describe(description: string): this
 
 	/**
-	 * Clone to a new Type with the specified undeclared key behavior.
+	 * #### apply undeclared key behavior
 	 *
 	 * {@inheritDoc UndeclaredKeyBehavior}
-	 * @api Type
 	 */
 	onUndeclaredKey(behavior: UndeclaredKeyBehavior): this
 
 	/**
-	 * Deeply clone to a new Type with the specified undeclared key behavior.
+	 * #### deeply apply undeclared key behavior
 	 *
 	 * {@inheritDoc UndeclaredKeyBehavior}
-	 * @api Type
 	 **/
 	onDeepUndeclaredKey(behavior: UndeclaredKeyBehavior): this
 
 	/**
-	 * Identical to `assert`, but with a typed input as a convenience for providing a typed value.
-	 * @example const ConfigT = type({ foo: "string" }); export const config = ConfigT.from({ foo: "bar" })
+	 * #### alias for {@link assert} with typed input
+	 *
+	 * @example
+	 * const t = type({ foo: "string" });
+	 * // TypeScript: foo must be a string (was 5)
+	 * const data = t.from({ foo: 5 });
 	 */
 	from(literal: this["inferIn"]): this["infer"]
 
 	/**
-	 * A `Type` representing the deeply-extracted input of the `Type` (before morphs are applied).
-	 * @example const inputT = T.in
+	 * #### deeply extract inputs
+	 *
+	 * ✅ will never include morphs
+	 * ✅ good for generating JSON Schema or other non-transforming formats
+	 *
+	 * @example
+	 * const createUser = type({
+	 *    age: "string.numeric.parse"
+	 * })
+	 * // { age: 25 } (age parsed to a number)
+	 * const out = createUser({ age: "25" })
+	 * // { age: "25" } (age is still a string)
+	 * const inOut = createUser.in({ age: "25" })
 	 */
 	get in(): instantiateType<this["inferIn"], $>
 
 	/**
-	 * A `Type` representing the deeply-extracted output of the `Type` (after morphs are applied).\
-	 * **IMPORTANT**: If your type includes morphs, their output will likely be unknown
-	 *   unless they were defined with an explicit output validator via `.to(outputType)`, `.pipe(morph, outputType)`, etc.
-	 * @example const outputT = T.out
+	 * #### deeply extract outputs
+	 *
+	 * ✅ will never include morphs
+	 * ⚠️ if your type includes morphs, their output will likely be unknown unless they
+	 * were defined with an explicit output validator via `.to(outputDef)` or `.pipe(morph, outputType)`
+	 *
+	 * @example
+	 * const userMorph = type("string[]").pipe(a => a.join(","))
+	 *
+	 * const t = type({
+	 *    // all keywords have introspectable output
+	 *    keyword: "string.numeric.parse",
+	 *    // TypeScript knows this returns a boolean, but we can't introspect that at runtime
+	 *    unvalidated: userMorph,
+	 *    // if needed, it can be made introspectable with an output validator
+	 *    validated: userMorph.to("string")
+	 * })
+	 *
+	 * // Type<{ keyword: number; unvalidated: unknown; validated: string }>
+	 * const baseOut = base.out
 	 */
 	get out(): instantiateType<this["inferIntrospectableOut"], $>
 
 	/**
-	 * Cast the way this `Type` is inferred (has no effect at runtime).
-	 * const branded = type(/^a/).as<`a${string}`>() // Type<`a${string}`>
+	 * #### cast the way this is inferred
+	 *
+	 * @typenoop
+	 *
+	 * @example
+	 * // Type<`LEEEEEEEE${string}ROY`>
+	 * const leeroy = type(/^LE{8,}ROY$/).as<`LEEEEEEEE${string}ROY`>()
 	 */
 	as<castTo = unset>(
 		...args: validateChainedAsArgs<castTo>
 	): instantiateType<castTo, $>
 
+	/**
+	 * #### add a compile-time brand to output
+	 *
+	 * @typenoop
+	 *
+	 * @example
+	 * const palindrome = type("string")
+	 *     .narrow(s => s === [...s].reverse().join(""))
+	 *     .brand("palindrome")
+	 * // Brand<string, "palindrome">
+	 * const out = palindrome.assert("racecar")
+	 */
 	brand<const name extends string, r = type.brand<t, name>>(
 		name: name
 	): instantiateType<r, $>
 
 	/**
-	 * Intersect another `Type` definition, throwing an error if the result is unsatisfiable.
-	 * @example const intersection = type({ foo: "number" }).intersect({ bar: "string" }) // Type<{ foo: number; bar: string }>
+	 * #### intersect the parsed Type, throwing if the result is unsatisfiable
+	 *
+	 * @example
+	 * // Type<{ foo: number; bar: string }>
+	 * const t = type({ foo: "number" }).and({ bar: "string" })
+	 * // ParseError: Intersection at foo of number and string results in an unsatisfiable type
+	 * const bad = type({ foo: "number" }).and({ foo: "string" })
 	 */
 	and<const def, r = type.infer<def, $>>(
 		def: type.validate<def, $>
 	): instantiateType<inferIntersection<t, r>, $>
 
 	/**
-	 * Union another `Type` definition.\
-	 * If the types contain morphs, input shapes should be distinct. Otherwise an error will be thrown.
-	 * @example const union = type({ foo: "number" }).or({ foo: "string" }) // Type<{ foo: number } | { foo: string }>
-	 * @example const union = type("string.numeric.parse").or("number") // Type<((In: string) => Out<number>) | number>
+	 * #### union with the parsed Type
+	 *
+	 * ⚠️ a union that could apply different morphs to the same data is a ParseError ([docs](https://arktype.io/docs/expressions/union-morphs))
+	 *
+	 * @example
+	 * // Type<string | { box: string }>
+	 * const t = type("string").or({ box: "string" })
 	 */
 	or<const def, r = type.infer<def, $>>(
 		def: type.validate<def, $>
 	): instantiateType<t | r, $>
 
 	/**
-	 * Create a `Type` for array with elements of this `Type`
-	 * @example const T = type(/^foo/); const array = T.array() // Type<string[]>
+	 * #### an array of this
+	 *
+	 * @example
+	 * // Type<{ rebmun: number }[]>
+	 * const t = type({ rebmun: "number" }).array();
 	 */
 	array(): ArrayType<t[], $>
 
+	/**
+	 * #### {@link https://arktype.io/docs/objects#properties-optional | optional definition}
+	 *
+	 * @chainedDefinition
+	 *
+	 * @example
+	 * const prop = type({ foo: "number" })
+	 * // Type<{ bar?: { foo: number } }>
+	 * const obj = type({ bar: prop.optional() })
+	 */
 	optional(): [this, "?"]
 
 	/**
-	 * Add a default value for this `Type` when it is used as a property.\
-	 * Default value should be a valid input value for this `Type, or a function that returns a valid input value.\
-	 * If the type has a morph, it will be applied to the default value.
-	 * @example const withDefault = type({ foo: type("string").default("bar") }); withDefault({}) // { foo: "bar" }
-	 * @example const withFactory = type({ foo: type("number[]").default(() => [1])) }); withFactory({baz: 'a'}) // { foo: [1], baz: 'a' }
-	 * @example const withMorph = type({ foo: type("string.numeric.parse").default("123") }); withMorph({}) // { foo: 123 }
+	 * #### {@link https://arktype.io/docs/objects#properties-defaultable | defaultable definition}
+	 *
+	 * ✅ object defaults can be returned from a function
+	 * ⚠️ throws if the default value is not allowed
+	 * @chainedDefinition
+	 *
+	 * @example
+	 * // Type<{ count: Default<number, 0> }>
+	 * const state = type({ count: type.number.default(0) })
+	 * const prop = type({ nested: "boolean" })
+	 * const forObj = type({
+	 *     key: nested.default(() => ({ nested: false }))
+	 * })
 	 */
 	default<const value extends defaultFor<this["inferIn"]>>(
 		value: value
 	): [this, "=", value]
 
+	/**
+	 * #### apply a predicate function to input
+	 *
+	 * ⚠️ the behavior of {@link narrow}, this method's output counterpart, is usually more desirable
+	 * ✅ most useful for morphs with input types that are re-used externally
+	 * @predicateCast
+	 *
+	 * @example
+	 * const stringifyUser = type({ name: "string" }).pipe(user => JSON.stringify(user))
+	 * const stringifySafe = stringifyUser.filter(user => user.name !== "Bobby Tables")
+	 * // Type<(In: `${string}Z`) => To<Date>>
+	 * const withPredicate = type("string.date.parse").filter((s): s is `${string}Z` =>
+	 *     s.endsWith("Z")
+	 * )
+	 */
 	filter<
 		narrowed extends this["inferIn"] = never,
 		r = [narrowed] extends [never] ? t
 		: t extends InferredMorph<any, infer o> ? (In: narrowed) => o
 		: narrowed
 	>(
-		predicate: Predicate.Castable<this["inferIn"]>
+		predicate: Predicate.Castable<this["inferIn"], narrowed>
 	): instantiateType<r, $>
 
 	/**
-	 * Add a custom predicate to this `Type`.
-	 * @example const nan = type('number').narrow(n => Number.isNaN(n)) // Type<number>
-	 * @example const foo = type("string").narrow((s): s is `foo${string}` => s.startsWith('foo') || ctx.mustBe('string starting with "foo"')) // Type<"foo${string}">
-	 * @example const unique = type('string[]').narrow((a, ctx) => new Set(a).size === a.length || ctx.mustBe('array with unique elements'))
+	 * #### apply a predicate function to output
+	 *
+	 * ✅ go-to fallback for validation not composable via built-in types and operators
+	 * ✅ runs after all other validators and morphs, if present
+	 * @predicateCast
+	 *
+	 * @example
+	 * const palindrome = type("string").narrow(s => s === [...s].reverse().join(""))
+	 *
+	 * const palindromicEmail = type("string.date.parse").narrow((date, ctx) =>
+	 *		date.getFullYear() === 2025 || ctx.mustBe("the current year")
+	 * )
+	 * // Type<`${string}.tsx`>
+	 * const withPredicate = type("string").narrow((s): s is `${string}.tsx` => /\.tsx?$/.test(s))
 	 */
 	narrow<
 		narrowed extends this["infer"] = never,
@@ -374,38 +458,115 @@ interface Type<out t = unknown, $ = {}>
 	// that can lead to incorrect results. See:
 	// https://discord.com/channels/957797212103016458/1285420361415917680/1285545752172429312
 	/**
-	 * Intersect another `Type` definition, returning an introspectable `Disjoint` if the result is unsatisfiable.
-	 * @example const intersection = type({ foo: "number" }).intersect({ bar: "string" }) // Type<{ foo: number; bar: string }>
-	 * @example const intersection = type({ foo: "number" }).intersect({ foo: "string" }) // Disjoint
+	 * #### intersect the parsed Type, returning an introspectable {@link Disjoint} if the result is unsatisfiable
+	 *
+	 * @example
+	 * // Type<{ foo: number; bar: string }>
+	 * const t = type({ foo: "number" }).intersect({ bar: "string" })
+	 * const bad = type("number > 10").intersect("number < 5")
+	 * // logs "Intersection of > 10 and < 5 results in an unsatisfiable type"
+	 * if (bad instanceof Disjoint) console.log(`${bad.summary}`)
 	 */
 	intersect<const def, r = type.infer<def, $>>(
 		def: type.validate<def, $>
 	): instantiateType<inferIntersection<t, r>, $> | Disjoint
 
+	/**
+	 * #### check if the parsed Type's constraints are identical
+	 *
+	 * ✅ equal types have identical input and output constraints and transforms
+	 * @ignoresMeta
+	 *
+	 * @example
+	 * const divisibleBy6 = type.number.divisibleBy(6).moreThan(0)
+	 * // false (left side must also be positive)
+	 * divisibleBy6.equals("number % 6")
+	 * // false (right side has an additional <100 constraint)
+	 * console.log(divisibleBy6.equals("0 < (number % 6) < 100"))
+	 * const thirdTry = type("(number % 2) > 0").divisibleBy(3)
+	 * // true (types are normalized and reduced)
+	 * console.log(divisibleBy6.equals(thirdTry))
+	 */
 	equals<const def>(def: type.validate<def, $>): boolean
 
+	/**
+	 * #### narrow this based on an {@link equals} check
+	 *
+	 * @ignoresMeta
+	 *
+	 * @example
+	 * const n = type.raw(`${Math.random()}`)
+	 * // Type<0.5> | undefined
+	 * const ez = n.ifEquals("0.5")
+	 */
 	ifEquals<const def, r = type.infer<def, $>>(
 		def: type.validate<def, $>
 	): instantiateType<r, $> | undefined
 
+	/**
+	 * #### check if this is a subtype of the parsed Type
+	 *
+	 * ✅ a subtype must include all constraints from the base type
+	 * ✅ unlike {@link equals}, additional constraints may be present
+	 * @ignoresMeta
+	 *
+	 * @example
+	 * type.string.extends("unknown") // true
+	 * type.string.extends(/^a.*z$/) // false
+	 */
 	extends<const def>(other: type.validate<def, $>): boolean
 
+	/**
+	 * #### narrow this based on an {@link extends} check
+	 *
+	 * @ignoresMeta
+	 *
+	 * @example
+	 * const n = type(Math.random() > 0.5 ? "true" : "0") // Type<0 | true>
+	 * const ez = n.ifExtends("boolean") // Type<true> | undefined
+	 */
 	ifExtends<const def, r = type.infer<def, $>>(
 		other: type.validate<def, $>
 	): instantiateType<r, $> | undefined
 
+	/**
+	 * #### check if a value could satisfy this and the parsed Type
+	 *
+	 * ⚠️ will return true unless a {@link Disjoint} can be proven
+	 *
+	 * @example
+	 * type.string.overlaps("string | number") // true (e.g. "foo")
+	 * type("string | number").overlaps("1") // true (1)
+	 * type("number > 0").overlaps("number < 0") // false (no values exist)
+	 *
+	 * const noAt = type("string").narrow(s => !s.includes("@"))
+	 * noAt.overlaps("string.email") // true (no values exist, but not provable)
+	 */
 	overlaps<const def>(r: type.validate<def, $>): boolean
 
+	/**
+	 * #### extract branches {@link extend}ing the parsed Type
+	 *
+	 * @example
+	 * // Type<true | 0 | 2>
+	 * const t = type("boolean | 0 | 'one' | 2 | bigint").extract("number | 0n | true")
+	 */
 	extract<const def, r = type.infer<def, $>>(
 		r: type.validate<def, $>
 	): instantiateType<Extract<t, r>, $>
 
+	/**
+	 * #### exclude branches {@link extend}ing the parsed Type
+	 *
+	 * @example
+	 *
+	 * // Type<false | 'one' | bigint>
+	 * const t = type("boolean | 0 | 'one' | 2 | bigint").exclude("number | 0n | true")
+	 */
 	exclude<const def, r = type.infer<def, $>>(
 		r: type.validate<def, $>
 	): instantiateType<Exclude<t, r>, $>
 
-	traverse(data: unknown): this["infer"] | ArkErrors
-
 	/**
 	 * @experimental
 	 * Map and optionally reduce branches of a union. Types that are not unions
diff --git a/ark/type/package.json b/ark/type/package.json
index 2410f2e6da..bb2b4b43be 100644
--- a/ark/type/package.json
+++ b/ark/type/package.json
@@ -1,18 +1,18 @@
 {
 	"name": "arktype",
 	"description": "TypeScript's 1:1 validator, optimized from editor to runtime",
-	"version": "2.0.0-rc.33",
+	"version": "2.0.0",
 	"license": "MIT",
-	"author": {
-		"name": "David Blass",
-		"email": "david@arktype.io",
-		"url": "https://arktype.io"
-	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/arktypeio/arktype.git",
 		"directory": "ark/type"
 	},
+	"author": {
+		"name": "David Blass",
+		"email": "david@arktype.io",
+		"url": "https://arktype.io"
+	},
 	"type": "module",
 	"main": "./out/index.js",
 	"types": "./out/index.d.ts",
diff --git a/ark/type/parser/definition.ts b/ark/type/parser/definition.ts
index 3b510079c9..ebe6eacb21 100644
--- a/ark/type/parser/definition.ts
+++ b/ark/type/parser/definition.ts
@@ -1,4 +1,9 @@
-import { hasArkKind, type BaseParseContext, type BaseRoot } from "@ark/schema"
+import {
+	hasArkKind,
+	isNode,
+	type BaseParseContext,
+	type BaseRoot
+} from "@ark/schema"
 import {
 	domainOf,
 	hasDomain,
@@ -51,7 +56,7 @@ import {
 } from "./tupleLiteral.ts"
 
 const parseCache: {
-	[scopeId: string]: { [def: string]: InnerParseResult } | undefined
+	[cacheId: string]: { [def: string]: InnerParseResult } | undefined
 } = {}
 
 export const parseInnerDefinition = (
@@ -64,9 +69,27 @@ export const parseInnerDefinition = (
 			// resolutions like "this" or generic args
 			return parseString(def, ctx)
 		}
-		const scopeCache = (parseCache[ctx.$.id] ??= {})
+
+		// include parseConfigHash in cacheId to ensure that if global config
+		// is updated, we reparse strings
+		const cacheId = `${ctx.$.id}:${ctx.$.configSnapshot.hash}`
+		const scopeCache = (parseCache[cacheId] ??= {})
+		const cachedResult = scopeCache[def]
+		if (cachedResult) {
+			// even though we know $ is the same, we still need to call bindReference
+			// to ensure config changes have been reflected
+			if (isNode(cachedResult))
+				scopeCache[def] = ctx.$.bindReference(cachedResult)
+			else {
+				// update node element of optional or defaultable tuple
+				;(cachedResult as any)[0] = ctx.$.bindReference(cachedResult[0])
+			}
+			return scopeCache[def]
+		}
+		// if we're parsing from scratch, we don't need to worry about binding
 		return (scopeCache[def] ??= parseString(def, ctx))
 	}
+
 	return hasDomain(def, "object") ?
 			parseObject(def, ctx)
 		:	throwParseError(writeBadDefinitionTypeMessage(domainOf(def)))
diff --git a/ark/type/scope.ts b/ark/type/scope.ts
index 88e46d1bf5..55684cfa1d 100644
--- a/ark/type/scope.ts
+++ b/ark/type/scope.ts
@@ -184,14 +184,6 @@ export interface InternalScope {
 }
 
 export class InternalScope<$ extends {} = {}> extends BaseScope<$> {
-	protected cacheGetter<name extends keyof this>(
-		name: name,
-		value: this[name]
-	): this[name] {
-		Object.defineProperty(this, name, { value })
-		return value
-	}
-
 	get ambientAttachments(): Ark.boundTypeAttachments<$> | undefined {
 		if (!$arkTypeRegistry.typeAttachments) return
 		return this.cacheGetter(
@@ -237,7 +229,11 @@ export class InternalScope<$ extends {} = {}> extends BaseScope<$> {
 		return parseGenericParamName(
 			new ArkTypeScanner(def),
 			[],
-			this.createParseContext({ ...opts, def, prefix: "generic" })
+			this.createParseContext({
+				...opts,
+				def,
+				prefix: "generic"
+			})
 		)
 	}
 
diff --git a/ark/util/package.json b/ark/util/package.json
index 79870a8938..7260c680fb 100644
--- a/ark/util/package.json
+++ b/ark/util/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@ark/util",
-	"version": "0.33.0",
+	"version": "0.34.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",
diff --git a/ark/util/records.ts b/ark/util/records.ts
index 13559124f9..9a38360a46 100644
--- a/ark/util/records.ts
+++ b/ark/util/records.ts
@@ -308,6 +308,16 @@ export const defineProperties: <base extends object, merged extends object>(
 		Object.getOwnPropertyDescriptors(merged)
 	) as never
 
+/** Copies enumerable keys of o to a new object in alphabetical order */
+export const withAlphabetizedKeys: <o extends object>(o: o) => o = (o: any) => {
+	const keys = Object.keys(o).sort()
+	const result: any = {}
+
+	for (let i = 0; i < keys.length; i++) result[keys[i]] = o[keys[i]]
+
+	return result
+}
+
 export type invert<t extends Record<PropertyKey, PropertyKey>> = {
 	[k in t[keyof t]]: {
 		[k2 in keyof t]: t[k2] extends k ? k2 : never
diff --git a/ark/util/registry.ts b/ark/util/registry.ts
index f350e70e7f..dea78c4669 100644
--- a/ark/util/registry.ts
+++ b/ark/util/registry.ts
@@ -7,7 +7,7 @@ import { FileConstructor, objectKindOf } from "./objectKinds.ts"
 // recent node versions (https://nodejs.org/api/esm.html#json-modules).
 
 // For now, we assert this matches the package.json version via a unit test.
-export const arkUtilVersion = "0.33.0"
+export const arkUtilVersion = "0.34.0"
 
 export const initialRegistryContents = {
 	version: arkUtilVersion,
diff --git a/ark/util/strings.ts b/ark/util/strings.ts
index e7b8e403a7..b7ddee9aae 100644
--- a/ark/util/strings.ts
+++ b/ark/util/strings.ts
@@ -90,3 +90,12 @@ export type isStringLiteral<t> =
 			:	false
 		:	false
 	:	false
+
+export const emojiToUnicode = (emoji: string): string =>
+	emoji
+		.split("")
+		.map(char => {
+			const codePoint = char.codePointAt(0)
+			return codePoint ? `\\u${codePoint.toString(16).padStart(4, "0")}` : ""
+		})
+		.join("")
diff --git a/package.json b/package.json
index dcf4298dd5..12da4595ef 100644
--- a/package.json
+++ b/package.json
@@ -54,22 +54,21 @@
 		"@ark/fs": "workspace:*",
 		"@ark/repo": "workspace:*",
 		"@ark/util": "workspace:*",
-		"@eslint/js": "9.17.0",
-		"@standard-schema/spec": "1.0.0-beta.4",
+		"@eslint/js": "9.18.0",
+		"@standard-schema/spec": "1.0.0-rc.0",
 		"@types/mocha": "10.0.10",
-		"@types/node": "22.10.4",
+		"@types/node": "22.10.6",
 		"c8": "10.1.3",
-		"eslint": "9.17.0",
+		"eslint": "9.18.0",
 		"eslint-plugin-import": "2.31.0",
 		"eslint-plugin-only-warn": "1.1.0",
-		"eslint-plugin-prefer-arrow-functions": "3.4.1",
-		"knip": "5.41.1",
+		"eslint-plugin-prefer-arrow-functions": "3.6.2",
+		"knip": "5.42.1",
 		"mocha": "11.0.1",
 		"prettier": "3.4.2",
-		"prettier-plugin-astro": "0.14.1",
 		"tsx": "4.19.2",
 		"typescript": "catalog:",
-		"typescript-eslint": "8.19.0"
+		"typescript-eslint": "8.20.0"
 	},
 	"mocha": {
 		"//": "IF YOU UPDATE THE MOCHA CONFIG HERE, PLEASE ALSO UPDATE ark/repo/mocha.jsonc AND .vscode/settings.json",
@@ -81,7 +80,8 @@
 			"conditions=ark-ts",
 			"import=tsx"
 		],
-		"require": "./ark/repo/mocha.globalSetup.ts"
+		"require": "./ark/repo/mocha.globalSetup.ts",
+		"timeout": 10000
 	},
 	"c8": {
 		"checkCoverage": true,
@@ -98,27 +98,13 @@
 		"semi": false,
 		"trailingComma": "none",
 		"experimentalTernaries": true,
-		"arrowParens": "avoid",
-		"plugins": [
-			"prettier-plugin-astro"
-		],
-		"overrides": [
-			{
-				"files": "*.astro",
-				"options": {
-					"parser": "astro"
-				}
-			}
-		]
+		"arrowParens": "avoid"
 	},
 	"pnpm": {
 		"peerDependencyRules": {
 			"allowedVersions": {
 				"eslint": "*"
 			}
-		},
-		"overrides": {
-			"@shikijs/types": "1.26.1"
 		}
 	},
 	"packageManager": "pnpm@9.14.4"