@paramour-js/next 0.1.1 → 0.2.0

package/dist/app.d.ts

@@ -36,6 +36,29 @@ export type { SelectOptions } from "./select.js";
  * at one of these call sites is a compile error, not a runtime surprise —
  * these hooks read Next's App-Router navigation hooks, whose pages twin has
  * different state cardinality (`@paramour-js/next/pages`).
+ *
+ * Devtools instrumentation (design-12): each hook reports through the shared
+ * emitter in observe.ts — `observe` from inside the `useStableResult`
+ * compute callback, which runs exactly on a `(route, fingerprint)` cache
+ * miss, so the SEL4 fingerprint layer IS the decode-change dedup (DT4;
+ * StrictMode's dev double render reuses the ref cache and cannot
+ * double-emit), and `refresh` after the stable result returns, re-emitting
+ * the CACHED result when the pathname moved under an unchanged decode so
+ * the seam's `navigate`/`pathname` never go stale (DT8). Observations carry
+ * the full pre-`select` result (DT12), and the `OrThrow` hooks report the
+ * error observation BEFORE rethrowing — only render-phase can, since an
+ * effect never runs for a throwing render. Every emit sits behind
+ * `process.env.NODE_ENV !== "production"`, which bundlers constant-fold and
+ * erase along with the seam module (DT6); the spec each hook hands the
+ * emitter is built behind the same literal guard, so prod allocates
+ * nothing. `useRouter` and `usePathname` are called unconditionally in
+ * every hook (rules of hooks — a build-constant-guarded call would make
+ * hook order differ between dev and prod bundles); their cost is a
+ * referentially-stable context read each, and only the dev-only spec
+ * captures them. The `navigate` capability receives the panel's SEARCH
+ * STRING only and resolves it against `usePathname()` — basePath-/locale-
+ * relative, exactly what `router.replace` expects back (DT8; the live hash
+ * is preserved at call time).
  */
 /**
  * Decoded route params as a `SafeResult` (discriminated on `status`, PR12),

package/dist/app.js

@@ -1,24 +1,125 @@
 "use client";
-import { useParams, useSearchParams } from "next/navigation";
-import { decodeParams, decodeSearch, safeDecodeParams, safeDecodeSearch, } from "paramour";
+import { useParams, usePathname, useRouter, useSearchParams, } from "next/navigation";
+import { decodeParams, decodeSearch, ParamsDecodeError, safeDecodeParams, safeDecodeSearch, SearchDecodeError, } from "paramour";
+import { searchWireSnapshot } from "./devtools-seam.js";
+import { makeAppNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, searchParamsFingerprint, useSelectedResult, useSelectedValue, useStableResult, } from "./select.js";
 export function useRouteParams(route, options) {
     const params = useParams() ?? {};
-    const result = useStableResult(route, paramsFingerprint(route, params), () => safeDecodeParams(route, params));
+    const router = useRouter();
+    const pathname = usePathname();
+    const emitter = useDevtoolsEmitter();
+    const spec = process.env.NODE_ENV === "production"
+        ? undefined
+        : {
+            hook: "app.useRouteParams",
+            kind: "params",
+            navigate: makeAppNavigate(router, pathname),
+            pathname,
+            route,
+            routerKind: "app",
+            wire: () => ({ ...params }),
+        };
+    const result = useStableResult(route, paramsFingerprint(route, params), () => {
+        const decoded = safeDecodeParams(route, params);
+        if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+            emitter.observe(spec, decoded);
+        }
+        return decoded;
+    });
+    if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+        emitter.refresh(spec);
+    }
     return useSelectedResult(result, options);
 }
 export function useRouteParamsOrThrow(route, options) {
     const params = useParams() ?? {};
-    const value = useStableResult(route, paramsFingerprint(route, params), () => decodeParams(route, params));
+    const router = useRouter();
+    const pathname = usePathname();
+    const emitter = useDevtoolsEmitter();
+    const spec = process.env.NODE_ENV === "production"
+        ? undefined
+        : {
+            hook: "app.useRouteParamsOrThrow",
+            kind: "params",
+            navigate: makeAppNavigate(router, pathname),
+            pathname,
+            route,
+            routerKind: "app",
+            wire: () => ({ ...params }),
+        };
+    const value = useStableResult(route, paramsFingerprint(route, params), () => {
+        // The duplicated decode call across the prod/dev branches is the price
+        // of literal-zero prod cost — the bundler keeps exactly one branch (DT6).
+        if (process.env.NODE_ENV === "production") {
+            return decodeParams(route, params);
+        }
+        try {
+            const data = decodeParams(route, params);
+            if (spec !== undefined) {
+                emitter.observe(spec, { data, status: "success" });
+            }
+            return data;
+        }
+        catch (error) {
+            // Report BEFORE the throw reaches the error boundary (DT4). Only the
+            // decode-error class is observed — foreign errors are not URL facts
+            // the panel explains, matching safeDecode*'s taxonomy.
+            if (error instanceof ParamsDecodeError && spec !== undefined) {
+                emitter.observe(spec, { error, status: "error" });
+            }
+            throw error;
+        }
+    });
+    if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+        emitter.refresh(spec);
+    }
     return useSelectedValue(value, options);
 }
 export function useSearch(route, options) {
     const searchParams = useSearchParams();
-    const result = useStableResult(route, searchParamsFingerprint(route, searchParams), () => safeDecodeSearch(route, searchParams));
+    const router = useRouter();
+    const pathname = usePathname();
+    const emitter = useDevtoolsEmitter();
+    const spec = process.env.NODE_ENV === "production"
+        ? undefined
+        : {
+            hook: "app.useSearch",
+            kind: "search",
+            navigate: makeAppNavigate(router, pathname),
+            pathname,
+            route,
+            routerKind: "app",
+            wire: () => searchWireSnapshot(searchParams),
+        };
+    const result = useStableResult(route, searchParamsFingerprint(route, searchParams), () => {
+        const decoded = safeDecodeSearch(route, searchParams);
+        if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+            emitter.observe(spec, decoded);
+        }
+        return decoded;
+    });
+    if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+        emitter.refresh(spec);
+    }
     return useSelectedResult(result, options);
 }
 export function useSearchOrThrow(route, options) {
     const searchParams = useSearchParams();
+    const router = useRouter();
+    const pathname = usePathname();
+    const emitter = useDevtoolsEmitter();
+    const spec = process.env.NODE_ENV === "production"
+        ? undefined
+        : {
+            hook: "app.useSearchOrThrow",
+            kind: "search",
+            navigate: makeAppNavigate(router, pathname),
+            pathname,
+            route,
+            routerKind: "app",
+            wire: () => searchWireSnapshot(searchParams),
+        };
     const value = useStableResult(route, searchParamsFingerprint(route, searchParams), 
     // decodeSearch is keyed on SearchOutputOf (design-04 SS6) — the correct
     // public type — but AnyAppRoute erases its SC to `any`, so for a still-
@@ -26,7 +127,32 @@ export function useSearchOrThrow(route, options) {
     // on the value side while staying deferred on the annotation side. The
     // cast bridges that inference gap to the SAME (correct) type, so a
     // rawSearch route now infers its schema output here, not a garbage
-    // {~kind, ~schema} shape.
-    () => decodeSearch(route["~search"], searchParams));
+    // {~kind, ~schema} shape. The cast appears in both branches below — the
+    // prod/dev split (and its duplicated decode call) is the price of
+    // literal-zero prod cost; the bundler keeps exactly one branch (DT6).
+    () => {
+        if (process.env.NODE_ENV === "production") {
+            return decodeSearch(route["~search"], searchParams);
+        }
+        try {
+            const data = decodeSearch(route["~search"], searchParams);
+            if (spec !== undefined) {
+                emitter.observe(spec, { data, status: "success" });
+            }
+            return data;
+        }
+        catch (error) {
+            // Report BEFORE the throw reaches the error boundary (DT4); only
+            // the decode-error class is observed, matching safeDecode*'s
+            // taxonomy.
+            if (error instanceof SearchDecodeError && spec !== undefined) {
+                emitter.observe(spec, { error, status: "error" });
+            }
+            throw error;
+        }
+    });
+    if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+        emitter.refresh(spec);
+    }
     return useSelectedValue(value, options);
 }

package/dist/devtools-seam.d.ts

@@ -0,0 +1,147 @@
+import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
+/**
+ * The devtools observation seam (design-12 DT5): a dependency-free global
+ * slot the hooks push decode observations into and the devtools panel
+ * (`@paramour-js/devtools`) reads out of. This module's JSDoc is the
+ * CONTRACT OF RECORD for the slot — the panel never imports runtime code
+ * from this package (its `./devtools-seam` exports entry is types-only, so
+ * a runtime import fails module resolution); it attaches to the same
+ * `globalThis` slot by key.
+ *
+ * - Slot key: `Symbol.for("paramour.devtools.seam")` — the realm-global
+ *   symbol registry, the same cross-copy identity idiom as core's error
+ *   brands (RL6): a second physical copy of this module (dual-package
+ *   hazard, bundler duplication) mints the SAME symbol and lands on the
+ *   same slot. Either side — hooks or panel — may create the slot; both
+ *   sides are create-if-absent.
+ * - The slot is DATA-ONLY (no function fields): a function property would
+ *   close over whichever module copy created the slot first, letting a
+ *   duplicated or version-skewed copy pin stale behavior. With plain data,
+ *   every copy of the emit/attach code operates on shared state and
+ *   `version` is the only skew guard needed.
+ * - Protocol: subscribe = `listeners.add(fn)`; unsubscribe =
+ *   `listeners.delete(fn)`; replay = synchronously read `buffer`, then
+ *   `add` — same JS thread, so nothing can be emitted between the read and
+ *   the add. Emitters push to `buffer` (FIFO-capped at
+ *   {@link OBSERVATION_BUFFER_CAP}) and then invoke every listener.
+ * - Production (DT6): every emit call site sits behind
+ *   `process.env.NODE_ENV !== "production"`, which Next's compilers
+ *   constant-fold; with the package's `sideEffects: false` the then-dead
+ *   import of this module is dropped entirely. The emitted JS here imports
+ *   NOTHING (the one `paramour` import is type-only) — load-bearing for
+ *   that erasure.
+ */
+/** The `Symbol.for("paramour.devtools.seam")` slot shape — the DT5 contract. */
+export interface ParamourDevtoolsSeam {
+    /** Capped FIFO; oldest dropped past the cap. Replay = read it. */
+    readonly buffer: ParamourObservation[];
+    /** Subscribe = add; unsubscribe = delete. Invoked synchronously per emit. */
+    readonly listeners: Set<(observation: ParamourObservation) => void>;
+    /**
+     * Bumped only when an EXISTING field's semantics change; additive fields
+     * never bump it.
+     */
+    readonly version: 1;
+}
+/** Discriminant naming which hook reported (design-12 DT4). */
+export type ParamourHookId = "app.useRouteParams" | "app.useRouteParamsOrThrow" | "app.useSearch" | "app.useSearchOrThrow" | "pages.useRouteParams" | "pages.useSearch";
+/**
+ * Navigation capability captured from the EMITTING hook's router (design-12
+ * DT8): the panel commits URL edits through this, so it never guesses which
+ * router is live and never imports Next. The panel passes ONLY the
+ * serialized search string (`""` or `"?…"`); the hook resolves it against
+ * its OWN current pathname — `usePathname()` (App) / `asPath`'s path part
+ * (Pages), both basePath-/locale-relative, which is what `replace()`
+ * expects back. The panel reading `window.location.pathname` instead would
+ * double a configured basePath through `router.replace`. `replace`
+ * semantics — the panel's commit-to-push editing is an experiment loop, and
+ * history entries per experiment would make the back button a slog;
+ * extending to an options bag later is additive.
+ */
+export type ParamourNavigate = (search: string) => void;
+/**
+ * One hook decode, reported on decode CHANGE (design-12 DT4) — and
+ * re-reported when the hook's resolution base moves under an unchanged
+ * decode (a layout surviving `/product/1?q=a` → `/product/2?q=a`), so the
+ * captured `navigate`/`pathname` never go stale while the hook is mounted.
+ */
+export type ParamourObservation = ParamourParamsObservation | ParamourSearchObservation;
+/**
+ * Pre-`select` decode result (design-12 DT12): the hook's full `SafeResult`
+ * — the error arm carries the LIVE `ParamsDecodeError`/`SearchDecodeError`
+ * with its `issues` — never the user's `select` projection. `pending` is
+ * the Pages-only third state (DT11). Generic-erased on purpose: the panel
+ * treats `data` structurally.
+ */
+export type ParamourObservationResult = SafeResult<unknown> | {
+    readonly status: "pending";
+};
+/** Params decode: wire is a decode-time shallow copy of the source record. */
+export interface ParamourParamsObservation extends ParamourObservationBase {
+    readonly kind: "params";
+    readonly wire: Readonly<ParamsSource>;
+}
+/**
+ * Search decode: wire is decode-time `[key, value]` pairs in wire order —
+ * order is load-bearing for repeated keys (P5/S5), and pairs round-trip
+ * losslessly into the panel's raw-wire editing (DT8).
+ */
+export interface ParamourSearchObservation extends ParamourObservationBase {
+    readonly kind: "search";
+    readonly wire: ParamourSearchWire;
+}
+export type ParamourSearchWire = readonly (readonly [string, string])[];
+interface ParamourObservationBase {
+    readonly hook: ParamourHookId;
+    readonly navigate: ParamourNavigate;
+    /**
+     * The emitting hook's OWN resolution base at decode time —
+     * `usePathname()` (App) / `asPath`'s path part (Pages), both
+     * basePath-/locale-relative like {@link ParamourNavigate}'s. The panel
+     * keys "is this session the page on screen?" on it (suffix-matched
+     * against `window.location.pathname`, which DOES carry the prefix), so it
+     * never has to reverse-engineer a configured basePath. Additive field —
+     * no `version` bump.
+     */
+    readonly pathname: string;
+    readonly result: ParamourObservationResult;
+    /**
+     * The LIVE route object (DT5: same JS context, no serialization) — the
+     * panel calls `describeRoute`, the route's own codecs, and
+     * `buildSearchString` on it directly.
+     */
+    readonly route: AnyRoute;
+    readonly routerKind: RouterKind;
+}
+/**
+ * 128: replay only needs the pre-panel-mount window. One observation per
+ * decode CHANGE per hook (DT4) means even a long pre-open session is dozens
+ * of entries, not thousands; the panel keys on route, so depth beyond
+ * "every route seen recently" adds nothing — the cap mostly bounds how many
+ * live route/result references the buffer retains.
+ */
+export declare const OBSERVATION_BUFFER_CAP = 128;
+/**
+ * Pushes one observation and notifies listeners. The internal production
+ * early-return is belt-and-suspenders under DT6 (every call site is ALSO
+ * guarded, which is what the bundler erases); it makes the guard directly
+ * unit-testable and keeps a future unguarded call site failing safe.
+ */
+export declare function emitObservation(observation: ParamourObservation): void;
+/**
+ * The slot, created on first touch by whichever side (hooks or panel) runs
+ * first.
+ */
+export declare function getParamourSeam(): ParamourDevtoolsSeam;
+/**
+ * Pages `query` record → wire pairs; `string[]` values expand to repeated
+ * keys in array order, `undefined` values are wire absence and are skipped.
+ */
+export declare function recordWireSnapshot(source: ParamsSource): ParamourSearchWire;
+/**
+ * Decode-time freeze of the (live, mutable) `URLSearchParams` into wire
+ * pairs: the observation outlives the render in the ring buffer, so it must
+ * capture what the DECODE saw, not a live view.
+ */
+export declare function searchWireSnapshot(source: URLSearchParams): ParamourSearchWire;
+export {};

package/dist/devtools-seam.js

@@ -0,0 +1,78 @@
+/**
+ * 128: replay only needs the pre-panel-mount window. One observation per
+ * decode CHANGE per hook (DT4) means even a long pre-open session is dozens
+ * of entries, not thousands; the panel keys on route, so depth beyond
+ * "every route seen recently" adds nothing — the cap mostly bounds how many
+ * live route/result references the buffer retains.
+ */
+export const OBSERVATION_BUFFER_CAP = 128;
+const SEAM_KEY = Symbol.for("paramour.devtools.seam");
+const globalSlots = globalThis;
+/**
+ * Pushes one observation and notifies listeners. The internal production
+ * early-return is belt-and-suspenders under DT6 (every call site is ALSO
+ * guarded, which is what the bundler erases); it makes the guard directly
+ * unit-testable and keeps a future unguarded call site failing safe.
+ */
+export function emitObservation(observation) {
+    if (process.env.NODE_ENV === "production")
+        return;
+    const seam = getParamourSeam();
+    seam.buffer.push(observation);
+    if (seam.buffer.length > OBSERVATION_BUFFER_CAP)
+        seam.buffer.shift();
+    for (const listener of seam.listeners) {
+        try {
+            listener(observation);
+        }
+        catch {
+            // A panel bug must never break app render — emit runs render-phase.
+        }
+    }
+}
+/**
+ * The slot, created on first touch by whichever side (hooks or panel) runs
+ * first.
+ */
+export function getParamourSeam() {
+    const existing = globalSlots[SEAM_KEY];
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        buffer: [],
+        listeners: new Set(),
+        version: 1,
+    };
+    globalSlots[SEAM_KEY] = created;
+    return created;
+}
+/**
+ * Pages `query` record → wire pairs; `string[]` values expand to repeated
+ * keys in array order, `undefined` values are wire absence and are skipped.
+ */
+export function recordWireSnapshot(source) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const element of value)
+                pairs.push([key, element]);
+        }
+        else {
+            pairs.push([key, value]);
+        }
+    }
+    return pairs;
+}
+/**
+ * Decode-time freeze of the (live, mutable) `URLSearchParams` into wire
+ * pairs: the observation outlives the render in the ring buffer, so it must
+ * capture what the DECODE saw, not a live view.
+ */
+export function searchWireSnapshot(source) {
+    const pairs = [];
+    for (const [key, value] of source)
+        pairs.push([key, value]);
+    return pairs;
+}

package/dist/list/render.d.ts

@@ -27,8 +27,9 @@ export interface ListReport {
  */
 export declare function buildListJson(report: ListReport): unknown;
 /**
- * `integer`, `enum(a, b)`, `string[]`, with annotations in fixed order:
- * presence, default, catch.
+ * `integer`, `enum(a, b)`, `string[]`, `csv<integer>`, with annotations in
+ * fixed order: presence, default, catch — core's shared walk in its verbose
+ * skin, so the CLI and the devtools panel can never drift on the field set.
  */
 export declare function formatCodec(description: CodecDescription): string;
 /** Human report; one string per output line. */

package/dist/list/render.js

@@ -1,3 +1,4 @@
+import { formatCodecDescription } from "paramour";
 /**
  * `--json` payload. Keys are alphabetical; a route with no definition
  * carries `definition: null` rather than an absent member — friendlier to
@@ -13,26 +14,12 @@ export function buildListJson(report) {
     };
 }
 /**
- * `integer`, `enum(a, b)`, `string[]`, with annotations in fixed order:
- * presence, default, catch.
+ * `integer`, `enum(a, b)`, `string[]`, `csv<integer>`, with annotations in
+ * fixed order: presence, default, catch — core's shared walk in its verbose
+ * skin, so the CLI and the devtools panel can never drift on the field set.
  */
 export function formatCodec(description) {
-    let base = description.enumMembers === undefined
-        ? description.kind
-        : `enum(${description.enumMembers.join(", ")})`;
-    if (description.arity === "many")
-        base += "[]";
-    const notes = [];
-    if (description.presence === "optional")
-        notes.push("(optional)");
-    if (description.defaultValue !== undefined) {
-        notes.push(description.defaultValue.kind === "value"
-            ? `(default: ${description.defaultValue.wire})`
-            : "(default: factory)");
-    }
-    if (description.caught)
-        notes.push("(catch)");
-    return [base, ...notes].join(" ");
+    return formatCodecDescription(description, "verbose");
 }
 /** Human report; one string per output line. */
 export function renderListReport(report) {

package/dist/observe.d.ts

@@ -0,0 +1,71 @@
+import type { AnyRoute, ParamsSource, RouterKind } from "paramour";
+import type { ParamourHookId, ParamourNavigate, ParamourObservationResult, ParamourSearchWire } from "./devtools-seam.js";
+/**
+ * Shared devtools seam wiring for the six read hooks (design-12 DT4/DT8):
+ * the navigate builders (one per router flavor) and the per-hook emitter
+ * that owns WHEN an observation goes out. Deliberately NO `"use client"`
+ * directive — app.ts (which carries one) and pages.ts (which must not,
+ * PR2) both import from here, like select.ts.
+ *
+ * Emission policy: the hooks call {@link DevtoolsEmitter.observe} from
+ * inside the `useStableResult` compute — the SEL4 fingerprint cache miss IS
+ * the decode-change dedup (DT4), and only render-phase can report the
+ * OrThrow hooks' error observation before the rethrow. `observe` alone
+ * would leave one staleness hole: a component that survives a navigation
+ * whose decode is unchanged (`/product/1?q=a` → `/product/2?q=a` in a
+ * layout) never recomputes, so its last-emitted `navigate` stays bound to
+ * the OLD pathname — committing a panel edit through it would silently
+ * navigate back to the old resource. {@link DevtoolsEmitter.refresh},
+ * called render-phase after the stable result returns, closes it: when the
+ * resolution base (or a HMR-reminted route) moved under a cached decode, it
+ * re-emits the CACHED result with the fresh spec — decode stability (SEL4)
+ * is untouched, only the seam payload is renewed.
+ *
+ * Production erasure (DT6): every call site keeps a literal
+ * `process.env.NODE_ENV` guard the bundler constant-folds, and both emitter
+ * methods early-return behind the same literal guard, so the
+ * `emitObservation` import above is dead in a production bundle and drops
+ * with `sideEffects: false`. The unconditional `useRef` here is the same
+ * bargain the hooks already make for `useRouter`/`usePathname` — hook order
+ * must not differ between dev and prod bundles.
+ */
+/** Per-hook emitter; see the module doc for the observe/refresh split. */
+export interface DevtoolsEmitter {
+    readonly observe: (spec: ObservationSpec, result: ParamourObservationResult) => void;
+    readonly refresh: (spec: ObservationSpec) => void;
+}
+/**
+ * Everything one emission needs, rebuilt per render so `navigate` and
+ * `wire` always close over the CURRENT render's router/pathname/source.
+ * Call sites construct it behind their literal dev guard (undefined in
+ * prod), keeping prod allocation at zero.
+ */
+export interface ObservationSpec {
+    readonly hook: ParamourHookId;
+    readonly kind: "params" | "search";
+    readonly navigate: ParamourNavigate;
+    readonly pathname: string;
+    readonly route: AnyRoute;
+    readonly routerKind: RouterKind;
+    /** Decode-time wire snapshot, taken fresh at each emission. */
+    readonly wire: () => ParamourSearchWire | Readonly<ParamsSource>;
+}
+/**
+ * App-flavor navigate capability (DT8): `next/navigation`'s `replace`
+ * returns void and resolves the basePath-/locale-relative join itself.
+ */
+export declare function makeAppNavigate(router: {
+    replace: (href: string) => void;
+}, pathname: string): ParamourNavigate;
+/**
+ * Pages-flavor navigate capability (DT8): `next/router`'s `replace` returns
+ * a promise that REJECTS on routine navigation aborts (rapid re-commits
+ * from the panel), marked with next's `cancelled` discriminant — those must
+ * not surface as unhandled rejections. Anything else is a real failure
+ * (render error, route-info error) silently discarding the user's edit, so
+ * it is reported to the console instead of swallowed.
+ */
+export declare function makePagesNavigate(router: {
+    replace: (url: string) => Promise<boolean>;
+}, pathname: string): ParamourNavigate;
+export declare function useDevtoolsEmitter(): DevtoolsEmitter;

package/dist/observe.js

@@ -0,0 +1,73 @@
+import { useRef } from "react";
+import { emitObservation } from "./devtools-seam.js";
+/**
+ * App-flavor navigate capability (DT8): `next/navigation`'s `replace`
+ * returns void and resolves the basePath-/locale-relative join itself.
+ */
+export function makeAppNavigate(router, pathname) {
+    return (search) => {
+        router.replace(`${pathname}${search}${window.location.hash}`);
+    };
+}
+/**
+ * Pages-flavor navigate capability (DT8): `next/router`'s `replace` returns
+ * a promise that REJECTS on routine navigation aborts (rapid re-commits
+ * from the panel), marked with next's `cancelled` discriminant — those must
+ * not surface as unhandled rejections. Anything else is a real failure
+ * (render error, route-info error) silently discarding the user's edit, so
+ * it is reported to the console instead of swallowed.
+ */
+export function makePagesNavigate(router, pathname) {
+    return (search) => {
+        void router
+            .replace(`${pathname}${search}${window.location.hash}`)
+            .catch((error) => {
+            if (!isCancelledNavigation(error))
+                console.error(error);
+        });
+    };
+}
+export function useDevtoolsEmitter() {
+    const ref = useRef(null);
+    ref.current ??= createEmitter();
+    return ref.current;
+}
+function createEmitter() {
+    let last = null;
+    const observe = (spec, result) => {
+        if (process.env.NODE_ENV === "production")
+            return;
+        last = { pathname: spec.pathname, result, route: spec.route };
+        // `kind` and `wire` are pairwise-correct by construction at the six
+        // call sites; the correlated union is beyond TS narrowing, hence the
+        // cast.
+        emitObservation({
+            hook: spec.hook,
+            kind: spec.kind,
+            navigate: spec.navigate,
+            pathname: spec.pathname,
+            result,
+            route: spec.route,
+            routerKind: spec.routerKind,
+            wire: spec.wire(),
+        });
+    };
+    return {
+        observe,
+        refresh: (spec) => {
+            if (process.env.NODE_ENV === "production")
+                return;
+            if (last === null)
+                return;
+            if (last.pathname === spec.pathname && last.route === spec.route)
+                return;
+            observe(spec, last.result);
+        },
+    };
+}
+/** Next's pages router marks genuine navigation aborts with `cancelled`. */
+function isCancelledNavigation(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.cancelled === true);
+}

package/dist/pages.d.ts

@@ -25,6 +25,15 @@ export type { SelectOptions } from "./select.js";
  * `query` (+ `isReady`), then an optional `{ select }` projection with
  * result-equality checking — the `pending` arm passes through the selector
  * untouched (SEL2), and `PENDING` itself is one referentially stable object.
+ *
+ * Devtools instrumentation (design-12): each hook reports through the
+ * shared emitter in observe.ts — `observe` from inside the `useStableResult`
+ * compute callback (DT4 — the fingerprint cache miss IS the decode-change
+ * dedup; see app.ts's fuller account), `refresh` after it for pathname
+ * moves under an unchanged decode (DT8). The `pending` arm emits as a
+ * first-class observation (DT11), keyed by `PENDING_FINGERPRINT` so the
+ * pre-`isReady` render reports exactly once. Every emit sits behind
+ * `process.env.NODE_ENV !== "production"` (DT6).
  */
 /**
  * Three-state result for the pages hooks (PR5): core's `SafeResult` plus a

package/dist/pages.js

@@ -1,30 +1,83 @@
 import { useRouter } from "next/router";
 import { ParamourError, safeDecodeParams, safeDecodeSearch, } from "paramour";
+import { recordWireSnapshot } from "./devtools-seam.js";
+import { makePagesNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, PENDING_FINGERPRINT, queryFingerprint, useSelectedResult, useStableResult, } from "./select.js";
 /** Referentially stable across every pending render. */
 const PENDING = { status: "pending" };
 export function useRouteParams(route, options) {
-    const { isReady, query } = usePagesRouter();
+    const router = usePagesRouter();
+    const { isReady, query } = router;
+    const pathname = asPathPathname(router.asPath);
+    const emitter = useDevtoolsEmitter();
+    const spec = process.env.NODE_ENV === "production"
+        ? undefined
+        : {
+            hook: "pages.useRouteParams",
+            kind: "params",
+            navigate: makePagesNavigate(router, pathname),
+            pathname,
+            route,
+            routerKind: "pages",
+            wire: () => ({ ...query }),
+        };
     const result = useStableResult(route, isReady ? paramsFingerprint(route, query) : PENDING_FINGERPRINT, () => {
-        if (!isReady)
-            return PENDING;
         // The merged query is a legal params source as-is: decodeParams reads
         // only the route's own segment names, never unknown keys. R5: next/router
         // has already percent-decoded `query`, so skip core's decode to avoid a
         // double-decode (`/product/a%2520b` → `"a%20b"` must survive as-is).
-        return safeDecodeParams(route, query, { percentDecode: false });
+        const decoded = isReady
+            ? safeDecodeParams(route, query, { percentDecode: false })
+            : PENDING;
+        if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+            emitter.observe(spec, decoded);
+        }
+        return decoded;
     });
+    if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+        emitter.refresh(spec);
+    }
     return useSelectedResult(result, options);
 }
 export function useSearch(route, options) {
-    const { isReady, query } = usePagesRouter();
+    const router = usePagesRouter();
+    const { isReady, query } = router;
+    const pathname = asPathPathname(router.asPath);
+    const emitter = useDevtoolsEmitter();
+    const spec = process.env.NODE_ENV === "production"
+        ? undefined
+        : {
+            hook: "pages.useSearch",
+            kind: "search",
+            navigate: makePagesNavigate(router, pathname),
+            pathname,
+            route,
+            routerKind: "pages",
+            // Lazy, so the path-param subtraction only runs when an emission
+            // actually snapshots the wire.
+            wire: () => recordWireSnapshot(omitPathParams(query, route)),
+        };
     const result = useStableResult(route, isReady ? queryFingerprint(route, query) : PENDING_FINGERPRINT, () => {
-        if (!isReady)
-            return PENDING;
-        return safeDecodeSearch(route, omitPathParams(query, route));
+        const source = omitPathParams(query, route);
+        const decoded = isReady ? safeDecodeSearch(route, source) : PENDING;
+        if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+            emitter.observe(spec, decoded);
+        }
+        return decoded;
     });
+    if (process.env.NODE_ENV !== "production" && spec !== undefined) {
+        emitter.refresh(spec);
+    }
     return useSelectedResult(result, options);
 }
+/**
+ * `asPath`'s path part: basePath-/locale-relative — exactly what
+ * `replace()` expects back — so the panel's search-only string (DT8)
+ * resolves without doubling a configured basePath.
+ */
+function asPathPathname(asPath) {
+    return asPath.split(/[#?]/)[0] ?? "/";
+}
 /**
  * `query` minus the route's own path-param names (PR5) — the client twin of
  * `parseContext`'s server-side subtraction (core route.ts, PR10). Entries →

package/dist/select.js

@@ -116,15 +116,37 @@ export function useStableResult(route, fingerprint, compute) {
     if (cached !== null &&
         cached.route === route &&
         cached.fingerprint === fingerprint) {
-        return cached.value;
+        if (cached.outcome.status === "thrown")
+            throw cached.outcome.thrown;
+        return cached.outcome.value;
     }
-    // Cleared BEFORE computing (SEL8): a throwing decode must not strand the
-    // previous entry, or the rerender after an error boundary reset would
-    // serve a stale value under the new fingerprint.
+    // Cleared BEFORE computing (SEL8): 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;
-    const value = compute();
-    cache.current = { fingerprint, route, value };
-    return value;
+    try {
+        const value = compute();
+        cache.current = {
+            fingerprint,
+            outcome: { status: "value", value },
+            route,
+        };
+        return value;
+    }
+    catch (error) {
+        // Cache the throw under ITS fingerprint (see StableOutcome): update
+        // renders share this ref with the committed fiber, so re-render
+        // attempts while the URL stays invalid rethrow instead of re-decoding
+        // (and re-emitting). A throwing MOUNT discards its work-in-progress
+        // hooks, so replayed mounts still recompute — per-instance semantics,
+        // same as the success arm's.
+        cache.current = {
+            fingerprint,
+            outcome: { status: "thrown", thrown: error },
+            route,
+        };
+        throw error;
+    }
 }
 /**
  * Declared search keys of a route's `~search` slot, or `null` for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,11 +11,15 @@
       "types": "./dist/app.d.ts",
       "default": "./dist/app.js"
     },
+    "./devtools-seam": {
+      "types": "./dist/devtools-seam.d.ts"
+    },
     "./pages": {
       "types": "./dist/pages.d.ts",
       "default": "./dist/pages.js"
     }
   },
+  "sideEffects": false,
   "bin": {
     "paramour": "./bin/paramour.js"
   },
@@ -26,7 +30,7 @@
     "jiti": "^2.7.0",
     "magicast": "^0.3.5",
     "tinyglobby": "^0.2.15",
-    "paramour": "0.2.0"
+    "paramour": "0.3.0"
   },
   "peerDependencies": {
     "next": ">=15",
@@ -60,6 +64,10 @@
     "bin",
     "dist"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit"