@paramour-js/next 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "exports": {
     ".": {
@@ -51,7 +51,7 @@
     "react-dom": "^19.2.0",
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
-    "paramour": "0.9.0"
+    "paramour": "0.10.0"
   },
   "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.
+   - `.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)`).
    - `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

@@ -27,18 +27,18 @@ Wire grammars are strict and anchored — no `Number()` coercion, no whitespace,
 
 ## Modifier chains
 
-| Modifier                        | Effect on decode                                                     | Effect on href input | Effect on URL                                                                                      |
-| ------------------------------- | -------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
-| (none — required)               | Absent key is a decode issue                                         | Key required         | Always emitted when building                                                                       |
-| `.optional()`                   | Absent → `undefined`; field type `T \| undefined`                    | Key omittable        | Omitted key emits nothing                                                                          |
-| `.default(value)`               | Absent → default; field type stays `T`                               | Key omittable        | Value equal to the default ELIDES (compared by serialized wire form) — one canonical URL per state |
-| `.default(() => value)`         | Absent → factory result; field type stays `T`                        | Key omittable        | NEVER elides (a time-varying factory would swallow explicit values)                                |
-| `.catch(v)` / `.catch(() => v)` | A PRESENT value that fails parsing → fallback. Never covers absence. | No change            | No change                                                                                          |
+| Modifier                        | Effect on decode                                                                                                                                | Effect on href input | Effect on URL                                                                                      |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
+| (none — required)               | Absent key is a decode issue                                                                                                                    | Key required         | Always emitted when building                                                                       |
+| `.optional()`                   | Absent → `undefined`; field type `T \| undefined`                                                                                               | Key omittable        | Omitted key emits nothing                                                                          |
+| `.default(value)`               | Absent → default; field type stays `T`                                                                                                          | Key omittable        | Value equal to the default ELIDES (compared by serialized wire form) — one canonical URL per state |
+| `.default(() => value)`         | Absent → factory result; field type stays `T`                                                                                                   | Key omittable        | NEVER elides (a time-varying factory would swallow explicit values)                                |
+| `.catch(v)` / `.catch(() => v)` | A PRESENT value that fails parsing → fallback. Never covers absence. After `.optional()`, the fallback may be `undefined` (bad value → absent). | No change            | No change                                                                                          |
 
 Legality (compile-time type-state — illegal calls type as `never`; runtime throws for JS):
 
-- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.catch(0).optional()`, `.default(1).catch(0)`, `.catch(0).default(1)`, `p.csv().default([])`, `p.array().catch([])`.
-- Illegal: `.optional().default(...)`, `.default(...).optional()`, `.optional().optional()`, `.default(...).default(...)`, `.catch(...).catch(...)`, `p.array().optional()`, `p.array().default(...)`, any modifier on a csv/array ELEMENT (`p.csv(p.string().optional())`), `p.csv(p.csv())`, `p.array(p.array())`, and `.default(value)` where the value's type includes a function member (use the factory form).
+- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.optional().catch(undefined)`, `.catch(0).optional()`, `.default(1).catch(0)`, `.catch(0).default(1)`, `p.csv().default([])`, `p.array().catch([])`.
+- Illegal: `.optional().default(...)`, `.default(...).optional()`, `.optional().optional()`, `.default(...).default(...)`, `.catch(...).catch(...)`, `.catch(undefined)` on a required/defaulted codec (apply `.optional()` first), `p.array().optional()`, `p.array().default(...)`, any modifier on a csv/array ELEMENT (`p.csv(p.string().optional())`), `p.csv(p.csv())`, `p.array(p.array())`, and `.default(value)` where the value's type includes a function member (use the factory form).
 - `params:` codecs additionally forbid `.optional()`/`.default()` (path optionality comes from `[[...slug]]`); `.catch()` is fine.
 
 Value vs factory `.default()`: value defaults are serialized eagerly at definition time (an invalid default fails immediately) and participate in URL elision; factory defaults are invoked per decode (fresh reference per call — use for mutable objects) and never elide. Array value defaults are handed out as fresh shallow copies per decode.