@paramour-js/next 0.4.0 → 0.5.0

package/dist/scan-pages.d.ts

@@ -1,10 +1,10 @@
 /**
  * Walk a pages dir and return the sorted union of URL-shaped route paths —
- * exactly the strings `definePagesRoute` accepts (PR4). A route is any file
- * whose extension is in `pageExtensions`, mapped by its path relative to the
- * dir; `index.<ext>` maps to its directory. Two files resolving to one URL
- * path — folder/file spelling (`blog.tsx` + `blog/index.tsx`) or extension
- * twins (`about.tsx` + `about.jsx`) — throw a {@link RouteCollisionError},
- * never dedupe: both are Next's own build errors (PR9).
+ * exactly the strings `definePagesRoute` accepts. A route is any file whose
+ * extension is in `pageExtensions`, mapped by its path relative to the dir;
+ * `index.<ext>` maps to its directory. Two files resolving to one URL path —
+ * folder/file spelling (`blog.tsx` + `blog/index.tsx`) or extension twins
+ * (`about.tsx` + `about.jsx`) — throw a {@link RouteCollisionError}, never
+ * dedupe: both are Next's own build errors.
  */
 export declare function scanPagesRoutes(pagesDir: string, pageExtensions?: readonly string[]): string[];

package/dist/scan-pages.js

@@ -3,18 +3,18 @@ import { join } from "node:path";
 import { assertNoStructuralCollisions, RouteCollisionError, } from "./collisions.js";
 import { DEFAULT_PAGE_EXTENSIONS, resolvesToFile } from "./scan-app.js";
 /**
- * Pages Router scanner (PR4). Deliberately a separate walker from
- * `scan-app.ts` — the rule sets barely overlap (routes live on FILES here,
- * and none of TR2's skip rules apply), and a shared walker would have to
- * take its rule set as a parameter to be worth having (PR8).
+ * Pages Router scanner. Deliberately a separate walker from `scan-app.ts` —
+ * the rule sets barely overlap (routes live on FILES here, and none of the
+ * app scanner's skip rules apply), and a shared walker would have to take
+ * its rule set as a parameter to be worth having.
  */
 /**
- * Names special to Next at the TOP level of the pages dir only (PR4):
+ * Names special to Next at the TOP level of the pages dir only:
  * `_app`/`_document`/`_error` are framework files, `404`/`500` are error
  * pages, not navigation targets — `href("/404")` should not type-check.
  * Nested twins (`pages/blog/404.tsx`) are ordinary pages and route.
- * Every other `_`-prefixed file routes too (spike 1: co-location under
- * `pages/` was requested, vercel/next.js#8454, and never implemented).
+ * Every other `_`-prefixed file routes too — co-location under `pages/` was
+ * requested (vercel/next.js#8454) and never implemented.
  */
 const TOP_LEVEL_EXCLUDED = new Set([
     "404",
@@ -25,22 +25,22 @@ const TOP_LEVEL_EXCLUDED = new Set([
 ]);
 /**
  * Walk a pages dir and return the sorted union of URL-shaped route paths —
- * exactly the strings `definePagesRoute` accepts (PR4). A route is any file
- * whose extension is in `pageExtensions`, mapped by its path relative to the
- * dir; `index.<ext>` maps to its directory. Two files resolving to one URL
- * path — folder/file spelling (`blog.tsx` + `blog/index.tsx`) or extension
- * twins (`about.tsx` + `about.jsx`) — throw a {@link RouteCollisionError},
- * never dedupe: both are Next's own build errors (PR9).
+ * exactly the strings `definePagesRoute` accepts. A route is any file whose
+ * extension is in `pageExtensions`, mapped by its path relative to the dir;
+ * `index.<ext>` maps to its directory. Two files resolving to one URL path —
+ * folder/file spelling (`blog.tsx` + `blog/index.tsx`) or extension twins
+ * (`about.tsx` + `about.jsx`) — throw a {@link RouteCollisionError}, never
+ * dedupe: both are Next's own build errors.
  */
 export function scanPagesRoutes(pagesDir, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
     // Path → the fs path (relative to pagesDir) that produced it, so a
     // collision can name both files.
     const out = new Map();
     walk(pagesDir, [], pageExtensions, out, true);
-    // Code-unit sort, never localeCompare — locale independence feeds TR3's
+    // Code-unit sort, never localeCompare — locale independence feeds the
     // byte-identical-on-every-OS guarantee.
     const paths = [...out.keys()].sort();
-    // PR9 structural collisions (different slug names, optional-catch-all
+    // Structural collisions (different slug names, optional-catch-all
     // specificity) — non-equal strings the Map above cannot catch.
     assertNoStructuralCollisions(paths.map((path) => ({ path, router: "pages" })));
     return paths;
@@ -62,10 +62,11 @@ function walk(dir, urlSegments, pageExtensions, out, isTopLevel) {
         const name = entry.name;
         // A real file, or a symlink whose target is a file: Next resolves and
         // serves symlinked page files, so a file symlink routes exactly like a
-        // real file (Bug 4, TR2 shared posture). Directory symlinks fall through
-        // to the directory guard below and stay not-followed.
+        // real file (Bug 4, the same posture the app scanner takes). Directory
+        // symlinks fall through to the directory guard below and stay
+        // not-followed.
         if (resolvesToFile(entry, dir)) {
-            // Declaration files match `.ts` but are never pages (PR11 §1).
+            // Declaration files match `.ts` but are never pages.
             if (name.endsWith(".d.ts"))
                 continue;
             const ext = matchExtension(name, pageExtensions);
@@ -75,26 +76,27 @@ function walk(dir, urlSegments, pageExtensions, out, isTopLevel) {
             if (isTopLevel && TOP_LEVEL_EXCLUDED.has(base))
                 continue;
             // `index.<ext>` maps to its directory; everything else — dynamic
-            // segments included — is a path segment of its own (PR4).
+            // segments included — is a path segment of its own.
             const segments = base === "index" ? urlSegments : [...urlSegments, base];
             const path = segments.length === 0 ? "/" : `/${segments.join("/")}`;
             const file = [...urlSegments, name].join("/");
             const existing = out.get(path);
             if (existing !== undefined) {
-                throw new RouteCollisionError(`pages route collision at "${path}": ${existing} and ${file} resolve to the same path (PR9)`);
+                throw new RouteCollisionError(`pages route collision at "${path}": ${existing} and ${file} resolve to the same path`);
             }
             out.set(path, file);
             continue;
         }
-        // Symlinked directories are deliberately not followed (TR2 v1 stance,
-        // shared posture): `resolvesToFile` returned false and `isDirectory()` is
-        // false for the link Dirent, so the subtree is skipped here.
+        // Symlinked directories are deliberately not followed (the v1 stance,
+        // shared with the app scanner): `resolvesToFile` returned false and
+        // `isDirectory()` is false for the link Dirent, so the subtree is
+        // skipped here.
         if (!entry.isDirectory())
             continue;
         // `pages/api/**` is excluded — top level only, so `pages/foo/api/bar.tsx`
-        // routes (API-route typing is deferred to v1.x, PR4/§14). NO app-style
-        // skip rules beyond this: `(group)`, `@slot`, `(.)x`, and `_`-prefixed
-        // dirs are ordinary literal segments in the Pages Router (PR4).
+        // routes (API-route typing is deferred to v1.x). NO app-style skip rules
+        // beyond this: `(group)`, `@slot`, `(.)x`, and `_`-prefixed dirs are
+        // ordinary literal segments in the Pages Router.
         if (isTopLevel && name === "api")
             continue;
         walk(join(dir, name), [...urlSegments, name], pageExtensions, out, false);

package/dist/scan.d.ts

@@ -1,20 +1,23 @@
 /**
- * The thin orchestrator over the two scanners (PR8): joint directory
- * discovery, delegation, and the cross-router collision checks (PR9).
+ * The thin orchestrator over the two scanners: joint directory discovery,
+ * delegation, and the cross-router collision checks.
+ */
+/**
+ * The two route dirs of a project; either may be absent — hybrid app/pages
+ * projects are supported, as are app-only and pages-only ones.
  */
-/** The two route dirs of a project; either may be absent (PR1 hybrid). */
 export interface RouteDirs {
     appDir?: string | undefined;
     pagesDir?: string | undefined;
 }
-/** Result of {@link scanRoutes} — the input shape of the PR9 artifact. */
+/** Result of {@link scanRoutes} — the input shape of the artifact. */
 export interface ScanRoutesResult {
     appRoutes: string[];
     pagesRoutes: string[];
 }
 /**
- * Joint route-dir discovery (spike-2 ruling). Next's documented rule is one
- * decision, not two probes: `src/app` AND `src/pages` are both ignored
+ * Joint route-dir discovery. Next's documented rule is one decision, not
+ * two probes: `src/app` AND `src/pages` are both ignored
  * whenever `app/` OR `pages/` exists at the project root. An ignored src dir
  * that contains page files is a hard config error — Next silently serves
  * none of those pages (and has shipped bugs in the mixed case,
@@ -22,10 +25,10 @@ export interface ScanRoutesResult {
  */
 export declare function resolveRouteDirs(projectRoot: string, pageExtensions?: readonly string[]): RouteDirs;
 /**
- * Scan whichever route dirs exist and return both route unions (PR1). After
- * each scanner's own intra-router checks, two cross-router passes run (PR9):
- * a path in BOTH unions is Next's "Conflicting app and page file" build
- * error, and the structural pass re-runs over the merged, labeled union so
+ * Scan whichever route dirs exist and return both route unions. After each
+ * scanner's own intra-router checks, two cross-router passes run: a path in
+ * BOTH unions is Next's "Conflicting app and page file" build error, and the
+ * structural pass re-runs over the merged, labeled union so
  * shared-prefix slug conflicts and cross-router optional-catch-all
  * specificity are caught too.
  */

package/dist/scan.js

@@ -4,8 +4,8 @@ import { assertNoStructuralCollisions, RouteCollisionError, } from "./collisions
 import { DEFAULT_PAGE_EXTENSIONS, scanAppRoutes } from "./scan-app.js";
 import { scanPagesRoutes } from "./scan-pages.js";
 /**
- * Joint route-dir discovery (spike-2 ruling). Next's documented rule is one
- * decision, not two probes: `src/app` AND `src/pages` are both ignored
+ * Joint route-dir discovery. Next's documented rule is one decision, not
+ * two probes: `src/app` AND `src/pages` are both ignored
  * whenever `app/` OR `pages/` exists at the project root. An ignored src dir
  * that contains page files is a hard config error — Next silently serves
  * none of those pages (and has shipped bugs in the mixed case,
@@ -47,10 +47,10 @@ export function resolveRouteDirs(projectRoot, pageExtensions = DEFAULT_PAGE_EXTE
     return { appDir: rootApp, pagesDir: rootPages };
 }
 /**
- * Scan whichever route dirs exist and return both route unions (PR1). After
- * each scanner's own intra-router checks, two cross-router passes run (PR9):
- * a path in BOTH unions is Next's "Conflicting app and page file" build
- * error, and the structural pass re-runs over the merged, labeled union so
+ * Scan whichever route dirs exist and return both route unions. After each
+ * scanner's own intra-router checks, two cross-router passes run: a path in
+ * BOTH unions is Next's "Conflicting app and page file" build error, and the
+ * structural pass re-runs over the merged, labeled union so
  * shared-prefix slug conflicts and cross-router optional-catch-all
  * specificity are caught too.
  */
@@ -62,7 +62,7 @@ export function scanRoutes(dirs, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
     const appSet = new Set(appRoutes);
     const shared = pagesRoutes.filter((path) => appSet.has(path));
     if (shared.length > 0) {
-        throw new RouteCollisionError(`route collision between app/ and pages/: ${shared.map((path) => `"${path}"`).join(", ")} — Next fails the build on conflicting app and page files (PR9)`);
+        throw new RouteCollisionError(`route collision between app/ and pages/: ${shared.map((path) => `"${path}"`).join(", ")} — Next fails the build on conflicting app and page files`);
     }
     assertNoStructuralCollisions([
         ...appRoutes.map((path) => ({ path, router: "app" })),

package/dist/select.d.ts

@@ -1,63 +1,63 @@
 import type { AnyRoute, ParamsSource, SafeResult } from "paramour";
 /**
- * Shared internals of the read hooks' selector surface (design-07): the
- * raw-slice stabilization layer (SEL4) and the selector layer (SEL2/SEL3).
- * Deliberately NO `"use client"` directive: app.ts (which carries one) and
- * pages.ts (which must not carry one, design-06 PR2) both import from here,
- * and the directive belongs on the entry modules, not a shared leaf.
+ * Shared internals of the read hooks' selector surface: the raw-slice
+ * stabilization layer and the selector layer. Deliberately NO `"use client"`
+ * directive: app.ts (which carries one) and pages.ts (which must not carry
+ * one) both import from here, and the directive belongs on the entry
+ * modules, not a shared leaf.
  *
- * Both layers are `useRef` caches mutated during render (SEL8) — the
- * Redux/TanStack selector pattern, and the one sanctioned departure from the
- * hooks' pure-`useMemo` discipline: result equality needs memory across
- * renders, which no pure memo can provide. Every cache is cleared BEFORE a
- * compute that can throw, so a throwing decode or selector never strands a
- * stale entry.
+ * Both layers are `useRef` caches mutated during render — the Redux/TanStack
+ * selector pattern, and the one sanctioned departure from the hooks'
+ * pure-`useMemo` discipline: result equality needs memory across renders,
+ * which no pure memo can provide. Every cache is cleared BEFORE a compute
+ * that can throw, so a throwing decode or selector never strands a stale
+ * entry.
  */
 /**
- * Options bag accepted by every read hook (design-07 SEL1).
+ * Options bag accepted by every read hook.
  */
 export interface SelectOptions<T, U> {
     /**
-     * Result-equality mode for the selected value (SEL3): `Object.is` by
-     * default — free and correct for primitive selections — with one-level
-     * `"shallow"` as the opt-in for tuple/object selections.
+     * Result-equality mode for the selected value: `Object.is` by default —
+     * free and correct for primitive selections — with one-level `"shallow"`
+     * as the opt-in for tuple/object selections.
      */
     readonly equality?: "shallow";
     /**
-     * Pure projection of the decoded value; runs only on the success arm
-     * (SEL2). Identity is never compared, so inline arrows are fine — and when
-     * the underlying result is reference-stable the selector is NOT re-run
-     * (SEL6), so it must not read changing outside state. A throw propagates to
-     * the nearest error boundary (SEL5): a selector bug is a code bug, never
-     * the `SafeResult` error arm, which is reserved for URL data problems.
+     * Pure projection of the decoded value; runs only on the success arm.
+     * Identity is never compared, so inline arrows are fine — and when the
+     * underlying result is reference-stable the selector is NOT re-run, so it
+     * must not read changing outside state. A throw propagates to the nearest
+     * error boundary: a selector bug is a code bug, never the `SafeResult`
+     * error arm, which is reserved for URL data problems.
      */
     readonly select: (value: T) => U;
 }
 /**
- * Fingerprint of the pages hooks' pre-`isReady` state (design-06 PR5). Every
- * real fingerprint is a `JSON.stringify`'d array (starts with `[`), so this
- * can never collide with one.
+ * Fingerprint of the pages hooks' pre-`isReady` state. Every real
+ * fingerprint is a `JSON.stringify`'d array (starts with `[`), so this can
+ * never collide with one.
  */
 export declare const PENDING_FINGERPRINT = "pending";
 /**
- * Raw slice of a params source (SEL4): the route's dynamic segment names'
- * raw values, from the define-time `~segments` token cache. Unknown keys —
+ * Raw slice of a params source: the route's dynamic segment names' raw
+ * values, from the define-time `~segments` token cache. Unknown keys —
  * e.g. a parallel route's params in the same `useParams()` bag — never bust
  * the fingerprint, because the decode never reads them.
  */
 export declare function paramsFingerprint(route: AnyRoute, source: ParamsSource): string;
 /**
- * Raw slice of a pages `router.query` bag for the search half (SEL4). A
- * codec-map route reads exactly its declared keys (query junk and the
- * route's own path params are invisible to the decode, PR9 disjointness); a
+ * Raw slice of a pages `router.query` bag for the search half. A codec-map
+ * route reads exactly its declared keys (query junk and the route's own path
+ * params are invisible to the decode — the two namespaces are disjoint); a
  * `rawSearch` route has no enumerable declared-key set — the schema sees
- * every key except the route's path params (design-06 PR5 subtraction), so
- * exactly that slice is fingerprinted, in sorted-key order for record-order
- * independence.
+ * every key except the route's path params (by subtracting them from the
+ * bag), so exactly that slice is fingerprinted, in sorted-key order for
+ * record-order independence.
  */
 export declare function queryFingerprint(route: AnyRoute, query: ParamsSource): string;
 /**
- * Raw slice of an app `useSearchParams()` source (SEL4): the declared keys'
+ * Raw slice of an app `useSearchParams()` source: the declared keys'
  * `[key, value]` pairs in wire order — order is load-bearing for repeated
  * keys (array codecs decode in wire order, P5/S5), and iterating the live
  * pairs preserves the relative order of declared entries while `?utm_*`
@@ -66,8 +66,8 @@ export declare function queryFingerprint(route: AnyRoute, query: ParamsSource):
  */
 export declare function searchParamsFingerprint(route: AnyRoute, source: URLSearchParams): string;
 /**
- * The selector layer for the safe hooks (SEL2): projects the success arm and
- * reference-stabilizes the projected WRAPPER by result equality (SEL3) — a
+ * The selector layer for the safe hooks: projects the success arm and
+ * reference-stabilizes the projected WRAPPER by result equality — a
  * stable `data` inside a fresh wrapper would still churn every consumer.
  * Error and pending arms pass through untouched; they are already
  * reference-stabilized by {@link useStableResult}'s raw-slice layer.
@@ -79,16 +79,16 @@ export declare function useSelectedResult<T, U>(result: SafeResult<T> | {
     status: "pending";
 };
 /**
- * {@link useSelectedResult}'s twin for the `*OrThrow` hooks (SEL2): same
- * layering, no wrapper — the hook's return IS the (selected) value.
+ * {@link useSelectedResult}'s twin for the `*OrThrow` hooks: same layering,
+ * no wrapper — the hook's return IS the (selected) value.
  */
 export declare function useSelectedValue<T, U>(value: T, options: SelectOptions<T, U> | undefined): T | U;
 /**
- * The raw-slice stabilization layer (SEL4): while `route` and `fingerprint`
- * are unchanged from the previous render, the previous result — success OR
+ * The raw-slice stabilization layer: while `route` and `fingerprint` are
+ * unchanged from the previous render, the previous result — success OR
  * error arm — is returned without recomputing, so a fresh `useSearchParams()`
  * / `query` object whose DECLARED slice is unchanged (`?utm_source=` churn)
  * costs neither a decode nor anyone's referential equality. This replaces
- * the pre-design-07 "memo keyed on Next's object reference" behavior.
+ * the earlier "memo keyed on Next's object reference" behavior.
  */
 export declare function useStableResult<T>(route: AnyRoute, fingerprint: string, compute: () => T): T;

package/dist/select.js

@@ -1,13 +1,13 @@
 import { useRef } from "react";
 /**
- * Fingerprint of the pages hooks' pre-`isReady` state (design-06 PR5). Every
- * real fingerprint is a `JSON.stringify`'d array (starts with `[`), so this
- * can never collide with one.
+ * Fingerprint of the pages hooks' pre-`isReady` state. Every real
+ * fingerprint is a `JSON.stringify`'d array (starts with `[`), so this can
+ * never collide with one.
  */
 export const PENDING_FINGERPRINT = "pending";
 /**
- * Raw slice of a params source (SEL4): the route's dynamic segment names'
- * raw values, from the define-time `~segments` token cache. Unknown keys —
+ * Raw slice of a params source: the route's dynamic segment names' raw
+ * values, from the define-time `~segments` token cache. Unknown keys —
  * e.g. a parallel route's params in the same `useParams()` bag — never bust
  * the fingerprint, because the decode never reads them.
  */
@@ -15,13 +15,13 @@ export function paramsFingerprint(route, source) {
     return recordFingerprint(dynamicSegmentNames(route), source);
 }
 /**
- * Raw slice of a pages `router.query` bag for the search half (SEL4). A
- * codec-map route reads exactly its declared keys (query junk and the
- * route's own path params are invisible to the decode, PR9 disjointness); a
+ * Raw slice of a pages `router.query` bag for the search half. A codec-map
+ * route reads exactly its declared keys (query junk and the route's own path
+ * params are invisible to the decode — the two namespaces are disjoint); a
  * `rawSearch` route has no enumerable declared-key set — the schema sees
- * every key except the route's path params (design-06 PR5 subtraction), so
- * exactly that slice is fingerprinted, in sorted-key order for record-order
- * independence.
+ * every key except the route's path params (by subtracting them from the
+ * bag), so exactly that slice is fingerprinted, in sorted-key order for
+ * record-order independence.
  */
 export function queryFingerprint(route, query) {
     const declared = declaredSearchKeys(route);
@@ -34,7 +34,7 @@ export function queryFingerprint(route, query) {
     return recordFingerprint(keys, query);
 }
 /**
- * Raw slice of an app `useSearchParams()` source (SEL4): the declared keys'
+ * Raw slice of an app `useSearchParams()` source: the declared keys'
  * `[key, value]` pairs in wire order — order is load-bearing for repeated
  * keys (array codecs decode in wire order, P5/S5), and iterating the live
  * pairs preserves the relative order of declared entries while `?utm_*`
@@ -62,15 +62,15 @@ export function useSelectedResult(result, options) {
         return result;
     const previous = cache.current;
     if (previous !== null && Object.is(previous.input, result.data)) {
-        // Reference-stable input ⇒ equal output by selector purity (SEL6); the
-        // selector is deliberately not re-run.
+        // Reference-stable input ⇒ equal output by selector purity; the selector
+        // is deliberately not re-run.
         return previous.wrapped;
     }
-    const selected = options.select(result.data); // a throw propagates (SEL5)
+    const selected = options.select(result.data); // a throw propagates
     if (previous !== null &&
         selectedEquals(options.equality, previous.wrapped.data, selected)) {
-        // Same selection out of a new decode: keep the previous wrapper (SEL2)
-        // and re-key the cache so the next render takes the reference fast path.
+        // Same selection out of a new decode: keep the previous wrapper and
+        // re-key the cache so the next render takes the reference fast path.
         previous.input = result.data;
         return previous.wrapped;
     }
@@ -82,8 +82,8 @@ export function useSelectedResult(result, options) {
     return wrapped;
 }
 /**
- * {@link useSelectedResult}'s twin for the `*OrThrow` hooks (SEL2): same
- * layering, no wrapper — the hook's return IS the (selected) value.
+ * {@link useSelectedResult}'s twin for the `*OrThrow` hooks: same layering,
+ * no wrapper — the hook's return IS the (selected) value.
  */
 export function useSelectedValue(value, options) {
     const cache = useRef(null);
@@ -91,9 +91,9 @@ export function useSelectedValue(value, options) {
         return value;
     const previous = cache.current;
     if (previous !== null && Object.is(previous.input, value)) {
-        return previous.selected; // SEL6: selector purity, not re-run
+        return previous.selected; // selector purity: not re-run
     }
-    const selected = options.select(value); // a throw propagates (SEL5)
+    const selected = options.select(value); // a throw propagates
     if (previous !== null &&
         selectedEquals(options.equality, previous.selected, selected)) {
         previous.input = value;
@@ -103,12 +103,12 @@ export function useSelectedValue(value, options) {
     return selected;
 }
 /**
- * The raw-slice stabilization layer (SEL4): while `route` and `fingerprint`
- * are unchanged from the previous render, the previous result — success OR
+ * The raw-slice stabilization layer: while `route` and `fingerprint` are
+ * unchanged from the previous render, the previous result — success OR
  * error arm — is returned without recomputing, so a fresh `useSearchParams()`
  * / `query` object whose DECLARED slice is unchanged (`?utm_source=` churn)
  * costs neither a decode nor anyone's referential equality. This replaces
- * the pre-design-07 "memo keyed on Next's object reference" behavior.
+ * the earlier "memo keyed on Next's object reference" behavior.
  */
 export function useStableResult(route, fingerprint, compute) {
     const cache = useRef(null);
@@ -120,7 +120,7 @@ export function useStableResult(route, fingerprint, compute) {
             throw cached.outcome.thrown;
         return cached.outcome.value;
     }
-    // Cleared BEFORE computing (SEL8): no half-computed state may survive a
+    // Cleared BEFORE computing: no half-computed state may survive a
     // throw, and a NEW fingerprint always recomputes — an error boundary
     // reset after the URL is fixed can never be served a stale entry.
     cache.current = null;
@@ -152,7 +152,7 @@ export function useStableResult(route, fingerprint, compute) {
  * Declared search keys of a route's `~search` slot, or `null` for a
  * `rawSearch` route (whose schema owns every key, so no declared subset
  * exists). The `~kind` marker is unambiguous against a codec map, which
- * never carries a top-level `~`-prefixed key (design-04 SS2).
+ * never carries a top-level `~`-prefixed key (SS2).
  */
 function declaredSearchKeys(route) {
     const config = route["~search"];
@@ -185,16 +185,16 @@ function recordFingerprint(keys, source) {
         Object.hasOwn(source, key) ? (source[key] ?? null) : null,
     ]));
 }
-/** SEL3: `Object.is`, widened one level by the `"shallow"` opt-in. */
+/** Result equality: `Object.is`, widened one level by `"shallow"`. */
 function selectedEquals(equality, a, b) {
     if (Object.is(a, b))
         return true;
     return equality === "shallow" && shallowEqual(a, b);
 }
 /**
- * One-level equality for the `"shallow"` opt-in (SEL3): arrays element-wise,
- * plain objects by own enumerable keys — `Object.is` at each leaf, nothing
- * recursive (deep comparison in a render path is a non-goal, design-07).
+ * One-level equality for the `"shallow"` opt-in: arrays element-wise, plain
+ * objects by own enumerable keys — `Object.is` at each leaf, nothing
+ * recursive (deep comparison in a render path is a non-goal).
  */
 function shallowEqual(a, b) {
     if (typeof a !== "object" ||

package/dist/skills/doctor.d.ts

@@ -0,0 +1,11 @@
+import type { DoctorCheck } from "../doctor/checks.js";
+/**
+ * Doctor's skills battery. Intent comes from manifest presence — doctor is
+ * passive and must not nag a project that never opted into skills — unlike
+ * `skills --check`, whose intent is the detection result (it is added to CI
+ * deliberately). Findings are warn-level, never fail: stale agent guidance
+ * degrades agent output but breaks nothing at build or runtime, and a fail
+ * here would flip doctor's exit to 1 in every consumer the day after every
+ * paramour release. The CI-fatal surface is `paramour skills --check`.
+ */
+export declare function skillsDoctorChecks(projectRoot: string): DoctorCheck[];

package/dist/skills/doctor.js

@@ -0,0 +1,71 @@
+import { message } from "../cli-io.js";
+import { loadPackagedSkill } from "./packaged.js";
+import { auditTarget, FILE_STATUS_DETAIL, isOutdated } from "./sync.js";
+import { detectTargets } from "./targets.js";
+/**
+ * Doctor's skills battery. Intent comes from manifest presence — doctor is
+ * passive and must not nag a project that never opted into skills — unlike
+ * `skills --check`, whose intent is the detection result (it is added to CI
+ * deliberately). Findings are warn-level, never fail: stale agent guidance
+ * degrades agent output but breaks nothing at build or runtime, and a fail
+ * here would flip doctor's exit to 1 in every consumer the day after every
+ * paramour release. The CI-fatal surface is `paramour skills --check`.
+ */
+export function skillsDoctorChecks(projectRoot) {
+    try {
+        const detected = detectTargets(projectRoot);
+        if (detected.length === 0) {
+            return [
+                {
+                    label: "skills: no agent tooling detected — skipped",
+                    status: "pass",
+                },
+            ];
+        }
+        const packaged = loadPackagedSkill();
+        const audits = detected
+            .map((target) => auditTarget(target, packaged))
+            .filter((audit) => audit.manifest !== undefined);
+        if (audits.length === 0) {
+            // Pass with an advisory label (check 1's "defaults in effect"
+            // precedent): declining skills is a legitimate steady state.
+            return [
+                {
+                    label: `skills: not installed (\`paramour skills\` installs agent skills for ${detected
+                        .map((target) => `${target.rel.split("/")[0] ?? ""}/`)
+                        .join(", ")})`,
+                    status: "pass",
+                },
+            ];
+        }
+        return audits.map((audit) => {
+            const detail = audit.files
+                .map((file) => {
+                const note = FILE_STATUS_DETAIL[file.status];
+                return note === undefined ? undefined : `${file.relPath}: ${note}`;
+            })
+                .filter((line) => line !== undefined);
+            if (detail.length === 0) {
+                return {
+                    label: `skills: ${audit.target.rel} is up to date`,
+                    status: "pass",
+                };
+            }
+            const outdated = audit.files.some((file) => isOutdated(file.status));
+            return {
+                detail,
+                label: `skills: ${audit.target.rel} ${outdated ? "is stale" : "has local edits"}`,
+                status: "warn",
+            };
+        });
+    }
+    catch (error) {
+        return [
+            {
+                detail: [message(error)],
+                label: "skills: could not audit installed skills",
+                status: "warn",
+            },
+        ];
+    }
+}

package/dist/skills/manifest.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The sidecar stamp `paramour skills` writes next to every installed copy.
+ * It lives inside the installed skill directory (not at the project root) so
+ * deleting a tool directory is a clean uninstall — no orphaned record keeps
+ * reporting the skill as missing after a deliberate removal. Skill loaders
+ * ignore dotfiles under progressive disclosure, so the installed skill files
+ * themselves stay byte-identical to the published ones.
+ */
+export interface SkillManifest {
+    /** POSIX-relative path → `sha256:<hex>` of the content last synced. */
+    files: Record<string, string>;
+    skill: "paramour";
+    /**
+     * The `@paramour-js/next` version that last wrote this manifest.
+     * Informational only: staleness truth is always hash comparison, so a
+     * version bump without content changes never reads as stale.
+     */
+    version: string;
+}
+export declare const MANIFEST_FILENAME = ".paramour-skills.json";
+/**
+ * CRLF-normalized sha256. Normalizing before hashing makes every status
+ * computation immune to a consumer repo's git `autocrlf` rewriting the
+ * installed markdown on checkout — a line-ending flip is not a content edit.
+ */
+export declare function hashContent(text: string): string;
+/**
+ * Read a target's manifest; `undefined` when absent or malformed. A corrupt
+ * manifest degrades to "no provenance": byte-identical files still audit as
+ * fresh and anything else audits as locally modified, which the installer
+ * refuses to overwrite without `--force` — the safe direction. A manifest
+ * containing any file key that could escape the skill directory is treated
+ * as corrupt the same way, since those keys become deletion paths in sync.
+ */
+export declare function readSkillManifest(skillDir: string): SkillManifest | undefined;
+/**
+ * Deterministic serialization: sorted file keys, two-space indent, LF,
+ * trailing newline, no timestamps — same doctrine as the generated artifact,
+ * so a re-run that changes nothing writes nothing.
+ */
+export declare function renderManifest(manifest: SkillManifest): string;