@paramour-js/next 0.11.0 → 0.11.2

package/dist/app.js

@@ -1,5 +1,11 @@
 "use client";
-import { useParams, usePathname, useRouter, useSearchParams, } from "next/navigation";
+// Extensionful for the same reason as pages.ts's `next/router.js`: `next`
+// ships no `exports` map, so wherever this package is loaded through Node's
+// ESM resolver (Vitest externalizes node_modules) the bare `next/navigation`
+// dies with ERR_MODULE_NOT_FOUND. The root stub `next/navigation.js` is the
+// file the bare specifier resolves to, and Next's bundler aliases are keyed
+// on that file, so bundles see the same module either way.
+import { useParams, usePathname, useRouter, useSearchParams, } from "next/navigation.js";
 import { decodeParams, decodeSearch, ParamsDecodeError, safeDecodeParams, safeDecodeSearch, SearchDecodeError, } from "paramour";
 import { useContext } from "react";
 import { searchWireSnapshot } from "./devtools-emit.js";

package/dist/doctor/checks.js

@@ -241,8 +241,7 @@ async function trailingSlashCheck(nextConfigPath, definitions) {
     const setting = `trailingSlash: ${String(configured)}`;
     // The routes come from the app's own paramour, which may predate the
     // option and lack the member: missing reads as the R6 default.
-    const mismatched = definitions.filter((definition) => (definition.route["~trailingSlash"] ?? false) !==
-        configured);
+    const mismatched = definitions.filter((definition) => (definition.route["~trailingSlash"] ?? false) !== configured);
     if (mismatched.length === 0) {
         return {
             label: `trailing slash: route definitions match ${name} (${setting})`,

package/dist/emit.d.ts

@@ -6,11 +6,18 @@ export interface WriteIfChangedResult {
      */
     previousContent: null | string;
     /**
-     * `false` on a byte-identical no-op — the signal `--check` and the watch
-     * loop hang off.
+     * `false` on a no-op (identical up to line endings) — the signal `--check`
+     * and the watch loop hang off.
      */
     written: boolean;
 }
+/**
+ * Content equality that ignores CRLF vs LF. A consumer repo with git
+ * `core.autocrlf=true` checks the committed LF artifact out as CRLF; that
+ * flip is not drift, and treating it as drift fails every strict build and
+ * `paramour check` on a fresh Windows checkout.
+ */
+export declare function sameContent(a: string, b: string): boolean;
 /** Input of {@link emitArtifact} — one union per router. */
 export interface EmitRoutes {
     appRoutes: readonly string[];
@@ -30,6 +37,8 @@ export declare function emitArtifact(routes: EmitRoutes): string;
 /**
  * Compare-before-write: a no-op regeneration must not touch the file — that
  * property is what prevents TS-server churn, watch-loop feedback, and
- * concurrent-generator races.
+ * concurrent-generator races. A file differing only in line endings is a
+ * no-op too, so a CRLF checkout keeps its endings and `git status` stays
+ * clean; a real change is written LF.
  */
 export declare function writeIfChanged(filePath: string, content: string): WriteIfChangedResult;

package/dist/emit.js

@@ -1,5 +1,14 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+/**
+ * Content equality that ignores CRLF vs LF. A consumer repo with git
+ * `core.autocrlf=true` checks the committed LF artifact out as CRLF; that
+ * flip is not drift, and treating it as drift fails every strict build and
+ * `paramour check` on a fresh Windows checkout.
+ */
+export function sameContent(a, b) {
+    return a.replaceAll("\r\n", "\n") === b.replaceAll("\r\n", "\n");
+}
 const HEADER = "// Generated by @paramour-js/next. Do not edit — regenerate with `paramour generate`.";
 /**
  * Artifact text for the per-router route unions: deterministic — sorted,
@@ -59,14 +68,17 @@ export function emitArtifact(routes) {
 /**
  * Compare-before-write: a no-op regeneration must not touch the file — that
  * property is what prevents TS-server churn, watch-loop feedback, and
- * concurrent-generator races.
+ * concurrent-generator races. A file differing only in line endings is a
+ * no-op too, so a CRLF checkout keeps its endings and `git status` stays
+ * clean; a real change is written LF.
  */
 export function writeIfChanged(filePath, content) {
     const previousContent = existsSync(filePath)
         ? readFileSync(filePath, "utf8")
         : null;
-    if (previousContent === content)
+    if (previousContent !== null && sameContent(previousContent, content)) {
         return { previousContent, written: false };
+    }
     // The outFile escape hatch may point into a not-yet-existing directory.
     mkdirSync(dirname(filePath), { recursive: true });
     writeFileSync(filePath, content);

package/dist/generate.d.ts

@@ -40,9 +40,10 @@ export interface RouterDrift {
     disappeared: string[];
 }
 /**
- * `--check`: scan to memory and byte-compare against disk — never writes. A
- * missing artifact is drift, not an error: that is exactly the
- * CI-degrades-to-world-A case the committed file exists to prevent.
+ * `--check`: scan to memory and compare against disk (line endings aside, as
+ * in {@link writeIfChanged}) — never writes. A missing artifact is drift, not
+ * an error: that is exactly the CI-degrades-to-world-A case the committed
+ * file exists to prevent.
  */
 export declare function checkArtifact(inputs: GenerateInputs): CheckResult;
 /**

package/dist/generate.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { emitArtifact, writeIfChanged } from "./emit.js";
+import { emitArtifact, sameContent, writeIfChanged } from "./emit.js";
 import { scanRoutes } from "./scan.js";
 /**
  * Reads the per-router unions back out of a previously emitted artifact for
@@ -11,9 +11,10 @@ import { scanRoutes } from "./scan.js";
 const MEMBER_HEADER = /^\s*(appRoutes|pagesRoutes):\s*$/;
 const UNION_MEMBER = /^\s*\| "(.*)";?\s*$/;
 /**
- * `--check`: scan to memory and byte-compare against disk — never writes. A
- * missing artifact is drift, not an error: that is exactly the
- * CI-degrades-to-world-A case the committed file exists to prevent.
+ * `--check`: scan to memory and compare against disk (line endings aside, as
+ * in {@link writeIfChanged}) — never writes. A missing artifact is drift, not
+ * an error: that is exactly the CI-degrades-to-world-A case the committed
+ * file exists to prevent.
  */
 export function checkArtifact(inputs) {
     const routes = scanRoutes(inputs, inputs.pageExtensions);
@@ -21,7 +22,7 @@ export function checkArtifact(inputs) {
     const current = existsSync(inputs.artifactPath)
         ? readFileSync(inputs.artifactPath, "utf8")
         : null;
-    if (current === expected) {
+    if (current !== null && sameContent(current, expected)) {
         return {
             app: { appeared: [], disappeared: [] },
             missingFile: false,

package/dist/navigation-adapter.d.ts

@@ -12,7 +12,7 @@ import type { ParamsSource } from "paramour";
  * (`useContext(ctx) ?? realAdapter`), so neither this module nor the
  * /testing entry ever drags a `next/*` specifier into its graph. The
  * dist.test.ts bundle-hygiene invariants (/app reaches only
- * `next/navigation`, /pages only `next/router.js`, /testing neither) depend
+ * `next/navigation.js`, /pages only `next/router.js`, /testing neither) depend
  * on exactly this split — a context whose DEFAULT VALUE were the real
  * adapter would break all three.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "type": "module",
   "exports": {
     ".": {
@@ -51,7 +51,7 @@
     "react-dom": "^19.2.0",
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
-    "paramour": "0.11.0"
+    "paramour": "0.11.2"
   },
   "description": "Next.js integration for paramour: withTypedRoutes, App and Pages Router hooks, PageProps glue, and the codegen CLI.",
   "author": "Jason Paff <jasonpaff@gmail.com>",

package/skills/paramour/SKILL.md

@@ -12,7 +12,7 @@ Paramour is a type-safe routing companion for Next.js: each route is defined onc
 1. Import only from package barrels: `paramour`, `@paramour-js/next`, `@paramour-js/next/app`, `@paramour-js/next/pages`, `@paramour-js/next/testing`. Never import `dist/` or deep source paths.
 2. Codec modifier legality is type-state: illegal chains do not compile (the method's type becomes `never`) and throw at runtime for JS callers. The rules:
    - `.optional()` and `.default()` apply only to a bare, unmodified single-value codec — at most ONE of the two, at most once. `.optional().default()`, `.default().optional()`, and any repeat are illegal.
-   - `.catch()` applies at most once and combines with either presence modifier in either order. It recovers parse failures of PRESENT wire values only — never absence. On an `.optional()` codec the fallback may be `undefined`, so a bad value reads as absent (`.optional().catch(undefined)`).
+   - `.catch()` applies at most once and combines with either presence modifier in either order, except that an `undefined` fallback needs `.optional()` first. It recovers parse failures of PRESENT wire values only — never absence. On an `.optional()` codec the fallback may be `undefined`, so a bad value reads as absent (`.optional().catch(undefined)`).
    - `p.array(...)` codecs take no `.optional()`/`.default()` (an absent key and `[]` are the same wire state). `.catch()` is allowed.
    - Codecs in a `params:` config take no presence modifiers at all (`.optional()`/`.default()` are illegal there); `.catch()` is allowed.
    - `p.csv(element)`/`p.array(element)` elements must be bare unmodified scalars: no modifiers, no csv inside csv, no array-arity element.

package/skills/paramour/references/authoring.md

@@ -92,7 +92,7 @@ href(productRoute, { params: { id: 1 }, hash: "reviews" }); // "#reviews" append
 href("/about", { hash: "team" }); // string form: registered STATIC paths only
 ```
 
-`href` returns `Href` — a string subtype accepted by `next/link`, `router.push`, `redirect` unchanged. Required params/search make the options argument required; defaulted/optional/array keys are omittable. Serialization failures (bad value, empty segment, required catch-all given `[]`) throw `SerializeError` at link-build time. A route defined with `trailingSlash: true` (match `next.config`'s `trailingSlash`) builds `/asset/?q=1` instead of `/asset?q=1`; the root stays `/` and the path literal never ends in `/`. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
+`href` returns `Href` — a string subtype accepted by `next/link`, `router.push`, `redirect` unchanged. Required params/search make the options argument required; defaulted/optional/array keys are omittable. Serialization failures (bad value, empty segment, required catch-all given `[]`) throw `SerializeError` at link-build time. A route defined with `trailingSlash: true` (match `next.config`'s `trailingSlash`) builds `/asset/?q=1` instead of `/asset?q=1`; the root stays `/` and the path literal never ends in `/`. When every route needs it, re-export a typed wrapper (`export const defineAppRoute: typeof defineRoute = (path, config) => defineRoute(path, { trailingSlash: true, ...config });`) instead of repeating it. The string form `href("/about")` has no route object, so it never adds the slash: in a `trailingSlash` app, link through the route object. In tests, set `process.env.__NEXT_TRAILING_SLASH = "true"`, or `next/link` strips the slash from rendered hrefs. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
 
 ## Client hooks
 

package/skills/paramour/references/migration.md

@@ -76,7 +76,7 @@ export default async function ProductPage(props: RouteProps) {
 - `sp.x ?? "default"` / `Number(sp.x ?? "1")` → codec with `.default(value)`. The decoded field is non-optional and the default value elides from built URLs.
 - "May be absent, no fallback" (`typeof sp.x === "string" ? sp.x : undefined`) → `.optional()`. Decoded as `T | undefined`.
 - Silent-coercion tolerance (old code shrugged off garbage, e.g. `Number(...)` producing `NaN` handled downstream) → add `.catch(fallback)` so a malformed PRESENT value falls back instead of failing the decode. `.catch()` never covers absence — combine with `.default()`/`.optional()` for that.
-- Multi-value keys (`sp.tags` handled as `string | string[]`) → `p.array()` for repeated keys (`?tags=a&tags=b`) or `p.csv()` for one comma-joined key (`?tags=a,b`). Match whichever wire form the app already emits.
+- Multi-value keys (`sp.tags` handled as `string | string[]`) → `p.array()` for repeated keys (`?tags=a&tags=b`) or `p.csv()` for one comma-joined key (`?tags=a,b`). Match whichever wire form the app already emits. Lists that nuqs's `parseAsArrayOf` already wrote (elements with `%2C`-escaped commas, bad elements dropped) → `nuqsArrayOf(element)` from `@paramour-js/nuqs`, not `p.csv()`.
 - Enumerated strings → `p.enum(["a", "b"])`; numbers → `p.number()`; booleans (`sp.flag === "true"`) → `p.boolean()`; dates → `p.isoDate()` (YYYY-MM-DD) or `p.timestamp()` (ISO instant; emits UTC).
 
 ### Behavior change to decide explicitly