@paramour-js/next 0.4.0 → 0.5.0

package/dist/skills/manifest.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+export 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 function hashContent(text) {
+    const digest = createHash("sha256")
+        .update(text.replaceAll("\r\n", "\n"))
+        .digest("hex");
+    return `sha256:${digest}`;
+}
+/**
+ * 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 function readSkillManifest(skillDir) {
+    const path = join(skillDir, MANIFEST_FILENAME);
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return undefined;
+    }
+    // Fields typed unknown, not Partial<SkillManifest> — the JSON is
+    // arbitrary bytes, and asserting the target shape up front would make
+    // these guards type-narrow the wrong way.
+    const candidate = parsed;
+    if (candidate.skill !== "paramour")
+        return undefined;
+    if (typeof candidate.version !== "string")
+        return undefined;
+    const files = candidate.files;
+    if (typeof files !== "object" || files === null || Array.isArray(files)) {
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(files)) {
+        if (!isSafeManifestKey(key, skillDir))
+            return undefined;
+        if (typeof value !== "string")
+            return undefined;
+    }
+    return {
+        files: files,
+        skill: "paramour",
+        version: candidate.version,
+    };
+}
+/**
+ * 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 function renderManifest(manifest) {
+    // Byte-order comparison, not localeCompare — locale collation varies by
+    // machine, and this file must be byte-identical wherever it is written.
+    const files = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+    const ordered = {
+        files,
+        skill: manifest.skill,
+        version: manifest.version,
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+/**
+ * Manifest keys are joined onto the skill directory and fed to the
+ * filesystem during sync — orphan removal in particular deletes the path a
+ * key names — so a tampered key like `"../../../src/index.ts"` would reach
+ * files far outside the install. Only a plain relative POSIX path that
+ * resolves strictly inside the skill directory is acceptable: no empty
+ * keys, no backslashes, no absolute paths (POSIX, Windows drive, or UNC),
+ * and the resolved path must sit under `resolve(skillDir)` followed by a
+ * separator so a sibling directory sharing the prefix does not slip
+ * through.
+ */
+function isSafeManifestKey(key, skillDir) {
+    if (key === "" || key.includes("\\"))
+        return false;
+    if (isAbsolute(key) || key.startsWith("/") || /^[A-Za-z]:/.test(key)) {
+        return false;
+    }
+    return resolve(skillDir, key).startsWith(resolve(skillDir) + sep);
+}

package/dist/skills/packaged.d.ts

@@ -0,0 +1,21 @@
+/** One file of the bundled skill, hashed and ready to install. */
+export interface PackagedFile {
+    content: string;
+    hash: string;
+    /** POSIX-relative to the skill root, e.g. `references/setup.md`. */
+    relPath: string;
+}
+/** The bundled skill as shipped in this package's `skills/` directory. */
+export interface PackagedSkill {
+    files: readonly PackagedFile[];
+    /** This package's own version — the value stamped into manifests. */
+    version: string;
+}
+/**
+ * Load the bundled skill content. Hashes are computed here, at read time,
+ * never committed — the changesets release flow bumps versions without a
+ * build step, so any committed hash would go stale on the first release.
+ * Throws when the bundled content is unreadable (an operational error: the
+ * package itself is broken).
+ */
+export declare function loadPackagedSkill(): PackagedSkill;

package/dist/skills/packaged.js

@@ -0,0 +1,32 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hashContent } from "./manifest.js";
+// Two levels up is the package root from both `src/skills/` (vitest runs
+// the sources) and `dist/skills/` (the built CLI): tsc mirrors src/ into
+// dist/ at the same depth, so one relative URL serves both worlds.
+const PACKAGE_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+/**
+ * Load the bundled skill content. Hashes are computed here, at read time,
+ * never committed — the changesets release flow bumps versions without a
+ * build step, so any committed hash would go stale on the first release.
+ * Throws when the bundled content is unreadable (an operational error: the
+ * package itself is broken).
+ */
+export function loadPackagedSkill() {
+    const root = join(PACKAGE_ROOT, "skills", "paramour");
+    const files = readdirSync(root, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => {
+        const content = readFileSync(join(entry.parentPath, entry.name), "utf8");
+        return {
+            content,
+            hash: hashContent(content),
+            relPath: relative(root, join(entry.parentPath, entry.name)).replaceAll("\\", "/"),
+        };
+    })
+        // Byte-order, not localeCompare — locale collation varies by machine.
+        .sort((a, b) => a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0);
+    const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+    return { files, version: manifest.version };
+}

package/dist/skills/sync.d.ts

@@ -0,0 +1,84 @@
+import { type SkillManifest } from "./manifest.js";
+import { type PackagedSkill } from "./packaged.js";
+import { type SkillTarget } from "./targets.js";
+/** One packaged file's audit against a target. */
+export interface FileAudit {
+    relPath: string;
+    status: FileStatus;
+}
+/**
+ * Per-file audit verdict, from three hashes: P (packaged), M (what the
+ * manifest recorded at last sync, possibly absent), I (installed on disk).
+ * - `fresh` — I equals P; nothing to do (identical unmanaged files are
+ *   adopted rather than flagged).
+ * - `missing` — no file on disk.
+ * - `stale` — I equals M but M differs from P: untouched locally, the
+ *   package moved on. Safe to overwrite.
+ * - `modified` — local edits relative to the current package (M equals P but
+ *   I differs, or no provenance at all). Never overwritten without --force.
+ * - `stale-modified` — all three differ: local edits on an outdated base.
+ *   Never overwritten without --force, but stale as far as `--check` cares.
+ */
+export type FileStatus = "fresh" | "missing" | "modified" | "stale" | "stale-modified";
+/**
+ * One human-readable detail line per file status, shared verbatim by
+ * `skills --check`, doctor, and init's summary so every surface describes
+ * the same state in the same words. `fresh` needs no line. Exhaustively
+ * typed: a new FileStatus member fails to compile until it gets an entry.
+ */
+export declare const FILE_STATUS_DETAIL: Record<FileStatus, string | undefined>;
+/** A manifest entry whose file is no longer part of the packaged skill. */
+export interface OrphanAudit {
+    /**
+     * True when the installed bytes still match the manifest record (or the
+     * file is already gone) — provably ours and untouched, so sync may remove
+     * it. False means local edits: sync leaves the file and stops tracking it.
+     */
+    managed: boolean;
+    relPath: string;
+}
+/** Everything `--check`, doctor, and the installer need about one target. */
+export interface TargetAudit {
+    files: FileAudit[];
+    manifest: SkillManifest | undefined;
+    orphans: OrphanAudit[];
+    target: SkillTarget;
+}
+/** What `syncTarget` did (or, under `dry`, would do) to one target. */
+export interface TargetSyncResult {
+    audit: TargetAudit;
+    /** Unmanaged orphans left on disk, no longer tracked by the manifest. */
+    keptOrphans: string[];
+    /** Managed orphans removed from disk. */
+    removedOrphans: string[];
+    /** Files with local edits, left as-is because `force` was off. */
+    skippedModified: string[];
+    /** Files written (created or overwritten). */
+    written: string[];
+}
+/** Audit one target without writing anything. */
+export declare function auditTarget(target: SkillTarget, packaged: PackagedSkill): TargetAudit;
+/**
+ * Whether a status means the installed copy no longer reflects the packaged
+ * skill — the single classifier behind `skills --check` failures, doctor's
+ * stale verdict, and init's summary line. `modified` is deliberate local
+ * tailoring, not drift, so it does not count. The lookup is exhaustively
+ * typed: a new FileStatus member fails to compile until it is classified.
+ */
+export declare function isOutdated(status: FileStatus): boolean;
+/**
+ * Install or re-sync one target: write missing/stale files, leave fresh
+ * ones alone, refuse to overwrite local edits unless `force`, then rewrite
+ * the manifest. Skipped modified files keep their previously recorded hash
+ * so a later audit can still tell `stale-modified` from `modified`; orphans
+ * are dropped from the manifest either way (a kept unmanaged orphan becomes
+ * the user's file — reported once here, never nagged about again). One
+ * exception to the manifest rewrite: when the target had no manifest,
+ * nothing was written, and every packaged file was refused as locally
+ * modified, no manifest is written either — that directory is the user's
+ * own work and must not be adopted as paramour-managed.
+ */
+export declare function syncTarget(target: SkillTarget, packaged: PackagedSkill, options: {
+    dry: boolean;
+    force: boolean;
+}): TargetSyncResult;

package/dist/skills/sync.js

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeIfChanged } from "../emit.js";
+import { hashContent, MANIFEST_FILENAME, readSkillManifest, renderManifest, } from "./manifest.js";
+import {} from "./packaged.js";
+import {} from "./targets.js";
+/**
+ * One human-readable detail line per file status, shared verbatim by
+ * `skills --check`, doctor, and init's summary so every surface describes
+ * the same state in the same words. `fresh` needs no line. Exhaustively
+ * typed: a new FileStatus member fails to compile until it gets an entry.
+ */
+export const FILE_STATUS_DETAIL = {
+    fresh: undefined,
+    missing: "missing — run `paramour skills`",
+    modified: "locally modified",
+    stale: "packaged content changed — run `paramour skills`",
+    "stale-modified": "locally modified on an outdated base — `paramour skills --force` overwrites",
+};
+/** Audit one target without writing anything. */
+export function auditTarget(target, packaged) {
+    const manifest = readSkillManifest(target.skillDir);
+    const files = packaged.files.map((file) => {
+        const installedPath = join(target.skillDir, file.relPath);
+        if (!existsSync(installedPath)) {
+            return { relPath: file.relPath, status: "missing" };
+        }
+        const installed = hashContent(readFileSync(installedPath, "utf8"));
+        const recorded = manifest?.files[file.relPath];
+        const status = installed === file.hash
+            ? "fresh"
+            : recorded === undefined || recorded === file.hash
+                ? "modified"
+                : installed === recorded
+                    ? "stale"
+                    : "stale-modified";
+        return { relPath: file.relPath, status };
+    });
+    const packagedPaths = new Set(packaged.files.map((file) => file.relPath));
+    const orphans = Object.entries(manifest?.files ?? {})
+        .filter(([relPath]) => !packagedPaths.has(relPath))
+        .map(([relPath, recorded]) => {
+        const installedPath = join(target.skillDir, relPath);
+        const managed = !existsSync(installedPath) ||
+            hashContent(readFileSync(installedPath, "utf8")) === recorded;
+        return { managed, relPath };
+    });
+    return { files, manifest, orphans, target };
+}
+/**
+ * Whether a status means the installed copy no longer reflects the packaged
+ * skill — the single classifier behind `skills --check` failures, doctor's
+ * stale verdict, and init's summary line. `modified` is deliberate local
+ * tailoring, not drift, so it does not count. The lookup is exhaustively
+ * typed: a new FileStatus member fails to compile until it is classified.
+ */
+export function isOutdated(status) {
+    const outdated = {
+        fresh: false,
+        missing: true,
+        modified: false,
+        stale: true,
+        "stale-modified": true,
+    };
+    return outdated[status];
+}
+/**
+ * Install or re-sync one target: write missing/stale files, leave fresh
+ * ones alone, refuse to overwrite local edits unless `force`, then rewrite
+ * the manifest. Skipped modified files keep their previously recorded hash
+ * so a later audit can still tell `stale-modified` from `modified`; orphans
+ * are dropped from the manifest either way (a kept unmanaged orphan becomes
+ * the user's file — reported once here, never nagged about again). One
+ * exception to the manifest rewrite: when the target had no manifest,
+ * nothing was written, and every packaged file was refused as locally
+ * modified, no manifest is written either — that directory is the user's
+ * own work and must not be adopted as paramour-managed.
+ */
+export function syncTarget(target, packaged, options) {
+    const audit = auditTarget(target, packaged);
+    const statusOf = new Map(audit.files.map((file) => [file.relPath, file.status]));
+    const manifestFiles = {};
+    const skippedModified = [];
+    const written = [];
+    for (const file of packaged.files) {
+        const status = statusOf.get(file.relPath) ?? "missing";
+        if (status === "fresh") {
+            manifestFiles[file.relPath] = file.hash;
+            continue;
+        }
+        if ((status === "modified" || status === "stale-modified") &&
+            !options.force) {
+            skippedModified.push(file.relPath);
+            const recorded = audit.manifest?.files[file.relPath];
+            if (recorded !== undefined)
+                manifestFiles[file.relPath] = recorded;
+            continue;
+        }
+        if (!options.dry) {
+            writeIfChanged(join(target.skillDir, file.relPath), file.content);
+        }
+        manifestFiles[file.relPath] = file.hash;
+        written.push(file.relPath);
+    }
+    const keptOrphans = [];
+    const removedOrphans = [];
+    for (const orphan of audit.orphans) {
+        if (orphan.managed) {
+            if (!options.dry) {
+                rmSync(join(target.skillDir, orphan.relPath), { force: true });
+            }
+            removedOrphans.push(orphan.relPath);
+        }
+        else {
+            keptOrphans.push(orphan.relPath);
+        }
+    }
+    // Writing the manifest is what marks a directory as paramour-managed. A
+    // target with no prior manifest where nothing was written and every
+    // packaged file was refused as locally modified is a hand-authored
+    // directory that happens to share the path — dropping a manifest there
+    // would adopt it and have doctor report local edits forever. Anything
+    // written, any prior provenance, or an all-fresh byte-identical tree (the
+    // designed adoption case) still rewrites the manifest.
+    const wouldAdoptUserDir = audit.manifest === undefined &&
+        skippedModified.length > 0 &&
+        written.length === 0;
+    if (!options.dry && !wouldAdoptUserDir) {
+        writeIfChanged(join(target.skillDir, MANIFEST_FILENAME), renderManifest({
+            files: manifestFiles,
+            skill: "paramour",
+            version: packaged.version,
+        }));
+    }
+    return { audit, keptOrphans, removedOrphans, skippedModified, written };
+}

package/dist/skills/targets.d.ts

@@ -0,0 +1,29 @@
+/** One resolved install destination. */
+export interface SkillTarget {
+    /** POSIX display path, e.g. `.claude/skills/paramour`. */
+    rel: string;
+    /** Absolute path to the skill's install directory. */
+    skillDir: string;
+    tool: ToolId;
+}
+/** The agent tools the installer knows how to target. */
+export type ToolId = "agents" | "claude" | "codex" | "cursor";
+export declare const TOOL_IDS: readonly ToolId[];
+/** `resolveTargets` result when the inputs were valid. */
+export interface ResolvedTargets {
+    /** True when nothing was detected and the portable location was chosen. */
+    fallback: boolean;
+    targets: SkillTarget[];
+}
+/** Targets whose tool is present in the project, alphabetical by tool. */
+export declare function detectTargets(projectRoot: string): SkillTarget[];
+/**
+ * Resolve install destinations: explicit `--tool` values (repeatable and
+ * comma-splittable) override detection entirely; otherwise every detected
+ * tool is targeted; with nothing detected the portable `.agents/skills/`
+ * location is the fallback so a bare `paramour skills` always installs
+ * somewhere tools can find.
+ */
+export declare function resolveTargets(projectRoot: string, toolFlags: readonly string[] | undefined): ResolvedTargets | {
+    error: string;
+};

package/dist/skills/targets.js

@@ -0,0 +1,73 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+// Detection is directory presence only — no config parsing. Per-tool config
+// formats move monthly; the dot-directory at the project root is the one
+// signal that has stayed stable across the ecosystem. `agents` additionally
+// matches an AGENTS.md file, the portable convention's sibling marker.
+const TOOLS = {
+    agents: {
+        detect: (root) => isDirectory(join(root, ".agents")) || existsSync(join(root, "AGENTS.md")),
+        dir: ".agents",
+    },
+    claude: {
+        detect: (root) => isDirectory(join(root, ".claude")),
+        dir: ".claude",
+    },
+    codex: { detect: (root) => isDirectory(join(root, ".codex")), dir: ".codex" },
+    cursor: {
+        detect: (root) => isDirectory(join(root, ".cursor")),
+        dir: ".cursor",
+    },
+};
+export const TOOL_IDS = Object.keys(TOOLS);
+/** Targets whose tool is present in the project, alphabetical by tool. */
+export function detectTargets(projectRoot) {
+    return TOOL_IDS.filter((tool) => TOOLS[tool].detect(projectRoot)).map((tool) => toTarget(projectRoot, tool));
+}
+/**
+ * Resolve install destinations: explicit `--tool` values (repeatable and
+ * comma-splittable) override detection entirely; otherwise every detected
+ * tool is targeted; with nothing detected the portable `.agents/skills/`
+ * location is the fallback so a bare `paramour skills` always installs
+ * somewhere tools can find.
+ */
+export function resolveTargets(projectRoot, toolFlags) {
+    const requested = (toolFlags ?? [])
+        .flatMap((flag) => flag.split(","))
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+    if (requested.length > 0) {
+        for (const id of requested) {
+            if (!TOOL_IDS.includes(id)) {
+                return {
+                    error: `unknown --tool "${id}" (expected one of: ${TOOL_IDS.join(", ")})`,
+                };
+            }
+        }
+        const unique = TOOL_IDS.filter((tool) => requested.includes(tool)); /* dedupes and restores alphabetical order */
+        return {
+            fallback: false,
+            targets: unique.map((tool) => toTarget(projectRoot, tool)),
+        };
+    }
+    const detected = detectTargets(projectRoot);
+    if (detected.length > 0)
+        return { fallback: false, targets: detected };
+    return { fallback: true, targets: [toTarget(projectRoot, "agents")] };
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function toTarget(projectRoot, tool) {
+    const { dir } = TOOLS[tool];
+    return {
+        rel: `${dir}/skills/paramour`,
+        skillDir: join(projectRoot, dir, "skills", "paramour"),
+        tool,
+    };
+}

package/dist/testing.d.ts

@@ -1,46 +1,42 @@
 import type { ParamsSource } from "paramour";
 import type { ReactElement, ReactNode } from "react";
 /**
- * `@paramour-js/next/testing` (design-16): a provider that overrides the
- * hooks' framework reads through the adapter seam (TA1), so client
- * components calling `useSearch`/`useRouteParams` (either flavor) can be
- * unit-tested without runner-specific `next/*` module mocking. One provider
- * feeds BOTH flavor contexts (TA5) — hybrid apps and pages components need
- * no second import. Server code needs none of this: `parse`/`safeParse` and
- * server components are pure functions over props (TA8).
+ * `@paramour-js/next/testing`: a provider that overrides the hooks'
+ * framework reads through the adapter seam, so client components calling
+ * `useSearch`/`useRouteParams` (either flavor) can be unit-tested without
+ * runner-specific `next/*` module mocking. One provider feeds BOTH flavor
+ * contexts — hybrid apps and pages components need no second import. Server
+ * code needs none of this: `parse`/`safeParse` and server components are
+ * pure functions over props.
  *
  * This module imports ONLY react and the (Next-free) adapter-seam module —
- * no `next/*` specifier and no `@testing-library/*` (TA5; dist.test.ts pins
- * the bundle graph, and the hermeticity check there is why these docs never
- * spell out the two Next specifiers). It carries `"use client"` like
- * app.ts.
+ * no `next/*` specifier and no `@testing-library/*`; dist.test.ts pins the
+ * bundle graph, and the hermeticity check there is why these docs never
+ * spell out the two Next specifiers. It carries `"use client"` like app.ts.
  *
- * Stability contract (TA4): the provider holds ONE adapter pair for its
- * lifetime, created once and closing over a latest-props ref that is
- * reassigned every render — prop changes mutate what the stable adapters
- * RETURN, they never mint new adapters, so the hooks' context reads stay
- * identity-stable and mid-test URL changes are driven by ordinary rerenders
- * with new props.
+ * Stability contract: the provider holds ONE adapter pair for its lifetime,
+ * created once and closing over a latest-props ref that is reassigned every
+ * render — prop changes mutate what the stable adapters RETURN, they never
+ * mint new adapters, so the hooks' context reads stay identity-stable and
+ * mid-test URL changes are driven by ordinary rerenders with new props.
  */
 /**
- * Input shape mirrors what Next hands the hooks (TA6) — no `url`
- * reverse-matching in v1 (deferred: needs a core matcher). `params: null`
- * and `mounted: false` are first-class because they are the two states
- * nobody hand-rolling a mock models.
+ * Input shape mirrors what Next hands the hooks — no `url` reverse-matching
+ * in v1 (deferred: needs a core matcher). `params: null` and
+ * `mounted: false` are first-class because they are the two states nobody
+ * hand-rolling a mock models.
  */
 export interface ParamourTestingOptions {
     /**
      * Pages flavor only: `false` is the pre-hydration state of a
-     * statically-optimized page (`query` not yet populated — the PR5
-     * `pending` arm). Defaults to `true`. design-16 listed this as deferred,
-     * but TA7 migrates the whole pages suite — which pins the pending arm —
-     * to this provider, so it was promoted from the deferred list.
+     * statically-optimized page (`query` not yet populated — the hooks'
+     * `pending` arm). Defaults to `true`.
      */
     isReady?: boolean;
     /**
      * Pages flavor only: `false` reproduces the pages router's
-     * throw-on-unmounted state under `app/` (PR5) — pages.ts translates it to
-     * a `ParamourError` naming the actual mistake.
+     * throw-on-unmounted state under `app/` — pages.ts translates it to a
+     * `ParamourError` naming the actual mistake.
      */
     mounted?: boolean;
     /** Captures `replace(href)` from either flavor's router. */
@@ -56,16 +52,16 @@ export interface ParamourTestingOptions {
     search?: string | URLSearchParams;
 }
 /**
- * Renders BOTH flavor contexts' providers around `children` (TA5). Exported
- * for people composing their own wrappers (Storybook decorators, custom
- * render helpers); testing-library users want {@link withParamourTesting}.
+ * Renders BOTH flavor contexts' providers around `children`. Exported for
+ * people composing their own wrappers (Storybook decorators, custom render
+ * helpers); testing-library users want {@link withParamourTesting}.
  */
 export declare function ParamourTestingProvider(props: ParamourTestingOptions & {
     children?: ReactNode;
 }): ReactElement;
 /**
- * Wrapper-component form for testing-library's `wrapper` option (TA5,
- * mirroring `withNuqsTestingAdapter`).
+ * Wrapper-component form for testing-library's `wrapper` option, mirroring
+ * `withNuqsTestingAdapter`.
  */
 export declare function withParamourTesting(options?: ParamourTestingOptions): (props: {
     children?: ReactNode;

package/dist/testing.js

@@ -3,21 +3,21 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useRef, useState } from "react";
 import { AppNavigationContext, PagesNavigationContext, } from "./navigation-adapter.js";
 /**
- * Renders BOTH flavor contexts' providers around `children` (TA5). Exported
- * for people composing their own wrappers (Storybook decorators, custom
- * render helpers); testing-library users want {@link withParamourTesting}.
+ * Renders BOTH flavor contexts' providers around `children`. Exported for
+ * people composing their own wrappers (Storybook decorators, custom render
+ * helpers); testing-library users want {@link withParamourTesting}.
  */
 export function ParamourTestingProvider(props) {
-    // Latest-ref pattern (TA4): reassigned every render so the stable
-    // adapters below always read the CURRENT render's props.
+    // Latest-ref pattern: reassigned every render so the stable adapters
+    // below always read the CURRENT render's props.
     const latest = useRef(props);
     latest.current = props;
     const [adapters] = useState(() => createAdapters(latest));
     return (_jsx(AppNavigationContext.Provider, { value: adapters.app, children: _jsx(PagesNavigationContext.Provider, { value: adapters.pages, children: props.children }) }));
 }
 /**
- * Wrapper-component form for testing-library's `wrapper` option (TA5,
- * mirroring `withNuqsTestingAdapter`).
+ * Wrapper-component form for testing-library's `wrapper` option, mirroring
+ * `withNuqsTestingAdapter`.
  */
 export function withParamourTesting(options = {}) {
     return function ParamourTestingWrapper({ children, }) {
@@ -25,10 +25,10 @@ export function withParamourTesting(options = {}) {
     };
 }
 /**
- * The one adapter pair a provider instance ever holds (TA4). Every read
- * defers to `latest.current`, so the adapters are stable while their
- * answers track prop updates. Fresh `URLSearchParams` per call is fine —
- * the hooks fingerprint the declared slice (SEL4), not the instance.
+ * The one adapter pair a provider instance ever holds. Every read defers to
+ * `latest.current`, so the adapters are stable while their answers track
+ * prop updates. Fresh `URLSearchParams` per call is fine — the hooks
+ * fingerprint the declared slice, not the instance.
  */
 function createAdapters(latest) {
     const app = {
@@ -57,20 +57,20 @@ function createAdapters(latest) {
             const options = latest.current;
             if (options.mounted === false) {
                 // Verbatim prefix of next/router's real unmounted error — pages.ts
-                // matches on the message to translate it (PR5).
+                // matches on the message to translate it.
                 throw new Error("NextRouter was not mounted. https://nextjs.org/docs/messages/next-router-not-mounted");
             }
             const search = normalizeSearch(options.search);
             return {
-                // asPath derives from pathname + normalized search (TA6) —
+                // asPath derives from pathname + normalized search —
                 // basePath-relative, what the devtools navigate capability resolves
-                // against (DT8).
+                // against.
                 asPath: (options.pathname ?? "/") + (search === "" ? "" : `?${search}`),
                 isReady: options.isReady ?? true,
                 query: mergedQuery(options),
                 replace(url) {
                     latest.current.onReplace?.(url);
-                    // Real next/router resolves `true` on a completed replace (TA6).
+                    // Real next/router resolves `true` on a completed replace.
                     return Promise.resolve(true);
                 },
             };