@paramour-js/devtools-panel 0.6.0

package/dist/components/search-table.js

@@ -0,0 +1,177 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { buildSearchString } from "paramour";
+import { useState } from "react";
+import { buildCommittedPairs, draftLines } from "../edit.js";
+import { formatShape, formatWire, jsLiteral } from "../format.js";
+import { attributionFor, previewDecode } from "../inference.js";
+import { CodecInput, isMultilineWidget } from "./codec-input.js";
+import { AttributionTag, ValueCell } from "./primitives.js";
+/**
+ * The search half of the inspector and the panel's editing surface: per-key
+ * widgets validating live through the codec, a per-key RAW WIRE toggle for
+ * reproducing invalid values, clear-to-absent, and a commit-to-push flow —
+ * Enter/blur assembles the FULL pair list (untouched and unknown keys
+ * carried verbatim), serializes through `buildSearchString` (spaces as %20
+ * — S-rule fidelity), and navigates via the EMITTING hook's `navigate`
+ * capability. The parent remounts this component when the observed wire
+ * changes (its React key), which is the drafts-invalidation rule: an
+ * external navigation resets the edit session.
+ */
+export function SearchTable({ changeStamps, description, navigate, observation, searchConfig, }) {
+    const [drafts, setDrafts] = useState({});
+    const [invalidKeys, setInvalidKeys] = useState([]);
+    if (description.kind === "none") {
+        return (_jsxs(_Fragment, { children: [_jsx("div", { className: "pmr-section-title", children: "Search" }), _jsx("div", { className: "pmr-muted", children: "no search params declared" })] }));
+    }
+    const wire = observation?.kind === "search" ? observation.wire : [];
+    const parsed = observation?.result.status === "success"
+        ? observation.result.data
+        : undefined;
+    if (description.kind === "raw") {
+        // A rawSearch route renders its parsed value with the schema shown as
+        // opaque; per-key editing has no per-key codecs to validate through.
+        return (_jsxs(_Fragment, { children: [_jsx("div", { className: "pmr-section-title", children: "Search" }), _jsxs("table", { className: "pmr-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "wire" }), _jsx("th", { children: "parsed" }), _jsx("th", { children: "shape" })] }) }), _jsx("tbody", { children: _jsxs("tr", { children: [_jsx("td", { children: _jsx(ValueCell, { stamp: 0, children: wire.length === 0
+                                                ? "—"
+                                                : wire.map(([key, value]) => `${key}=${value}`).join(" & ") }) }), _jsx("td", { children: _jsx(ValueCell, { stamp: 0, children: parsed === undefined ? "—" : jsLiteral(parsed) }) }), _jsx("td", { className: "pmr-mono pmr-muted", children: "raw (opaque schema)" })] }) })] })] }));
+    }
+    const config = searchConfig ?? {};
+    const wireValuesFor = (key) => wire.filter((pair) => pair[0] === key).map((pair) => pair[1]);
+    // `overrides` carries a same-event draft (the checkbox's toggle-and-
+    // commit) that the `drafts` state cannot deliver yet — `setDrafts` lands
+    // next render, after this commit already read it.
+    const commit = (overrides) => {
+        const effective = { ...drafts, ...overrides };
+        if (navigate === undefined || Object.keys(effective).length === 0)
+            return;
+        let search;
+        try {
+            // Untouched pairs carry from the LIVE URL, not the observation's
+            // decode-time snapshot: undeclared-key churn (utm_* stripped or added
+            // by the app) never re-emits — the emit fingerprint covers declared
+            // keys only — so the snapshot can be stale in both directions, and
+            // committing it would resurrect removed pairs and drop added ones.
+            // `navigate` is only handed to CURRENT sessions, so the live URL is
+            // this session's page.
+            const result = buildCommittedPairs(config, liveWirePairs(), effective);
+            if (result.status === "invalid") {
+                setInvalidKeys(result.invalidKeys);
+                return;
+            }
+            search = buildSearchString(result.pairs);
+        }
+        catch {
+            // A serializer/byte-layer throw (SerializeError — custom codec, lone
+            // surrogate) surfaces after the preview validated the parse; it must
+            // not escape the event handler. Drafts stay editable.
+            setInvalidKeys(Object.keys(effective));
+            return;
+        }
+        setInvalidKeys([]);
+        // Search string ONLY: the hook-side navigate resolves it against
+        // its own basePath-/locale-relative pathname — `window.location.pathname`
+        // here would double a configured basePath through router.replace.
+        navigate(search);
+        setDrafts({});
+    };
+    const setDraft = (key, draft) => {
+        setDrafts((previous) => ({ ...previous, [key]: draft }));
+        setInvalidKeys((previous) => previous.filter((entry) => entry !== key));
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "pmr-section-title", children: "Search" }), _jsxs("table", { className: "pmr-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "key" }), _jsx("th", { children: "wire" }), _jsx("th", { children: "parsed" }), _jsx("th", { children: "shape" }), _jsx("th", { "aria-label": "attribution" }), _jsx("th", { children: "edit" })] }) }), _jsx("tbody", { children: Object.entries(description.keys).map(([key, keyDescription]) => {
+                            const codec = config[key];
+                            const wireValues = wireValuesFor(key);
+                            const draft = drafts[key];
+                            const attribution = codec === undefined
+                                ? undefined
+                                : attributionFor(keyDescription, codec, wireValues);
+                            return (_jsx(SearchRow, { attribution: attribution, changeStamp: changeStamps[key] ?? 0, codec: codec, dataKey: key, description: keyDescription, draft: draft, invalid: invalidKeys.includes(key), onCommit: (override) => {
+                                    commit(override === undefined ? undefined : { [key]: override });
+                                }, onDraftChange: (next) => {
+                                    setDraft(key, next);
+                                }, parsedValue: parsed?.[key], showParsed: parsed !== undefined, wireValues: wireValues }, key));
+                        }) })] })] }));
+}
+/**
+ * The search pairs as they are on the wire RIGHT NOW. `URLSearchParams`
+ * decoding matches what the emitting hooks' sources see (`useSearchParams`
+ * IS a URLSearchParams view), so carried pairs round-trip through
+ * `buildSearchString` with the same fidelity as the observed snapshot's.
+ */
+function liveWirePairs() {
+    const pairs = [];
+    for (const [key, value] of new URLSearchParams(window.location.search)) {
+        pairs.push([key, value]);
+    }
+    return pairs;
+}
+function previewLine(codec, description, key, draft, invalid) {
+    // Same arity rule and line-splitting as the commit path (draftLines), so
+    // what the preview shows is what a commit would do.
+    const input = draft.value.kind === "absent"
+        ? undefined
+        : description.arity === "many"
+            ? draftLines(draft.value.text)
+            : draft.value.text;
+    const preview = previewDecode(codec, key, input);
+    if (preview.status === "error") {
+        return (_jsxs("div", { className: "pmr-preview pmr-preview--error", children: [invalid ? "✕ " : "", preview.issues[0]?.message ?? "invalid"] }));
+    }
+    return (_jsxs("div", { className: "pmr-preview pmr-preview--ok", children: ["\u2192 ", jsLiteral(preview.value)] }));
+}
+function SearchRow({ attribution, changeStamp, codec, dataKey, description, draft, invalid, onCommit, onDraftChange, parsedValue, showParsed, wireValues, }) {
+    const [raw, setRaw] = useState(false);
+    // Only the multi-line textarea can represent repeated wire values; a
+    // single-line widget seeded with a newline join would value-sanitize the
+    // `\n` away ('1\n2' → '12'), and the first keystroke turns that
+    // fabricated value into a committed draft replacing every original pair.
+    // Broken wire (repeated key on an arity-one codec) seeds from the FIRST
+    // pair; the wire column still shows all of them.
+    const seedText = isMultilineWidget(description, raw)
+        ? wireValues.join("\n")
+        : (wireValues[0] ?? "");
+    const draftText = draft === undefined || draft.value.kind === "absent"
+        ? seedText
+        : draft.value.text;
+    const absent = draft?.value.kind === "absent";
+    return (_jsxs("tr", { children: [_jsx("td", { className: "pmr-mono", children: dataKey }), _jsx("td", { children: _jsx(ValueCell, { stamp: 0, children: formatWire(wireValues.length === 0 ? undefined : wireValues) }) }), _jsx("td", { children: _jsx(ValueCell, { stamp: changeStamp, children: showParsed ? jsLiteral(parsedValue) : "—" }) }), _jsx("td", { className: "pmr-mono pmr-muted", children: formatShape(description) }), _jsx("td", { children: attribution === undefined ? null : (_jsx(AttributionTag, { kind: attribution })) }), _jsx("td", { children: codec === undefined ? null : (_jsxs(_Fragment, { children: [_jsx(CodecInput, { codec: codec, dataKey: dataKey, description: description, draftText: absent ? "" : draftText, hasDraft: draft?.value.kind === "text", onCommit: (immediateText) => {
+                                onCommit(immediateText === undefined
+                                    ? undefined
+                                    : {
+                                        mode: raw ? "raw" : "codec",
+                                        value: { kind: "text", text: immediateText },
+                                    });
+                            }, onDraftChange: (text) => {
+                                onDraftChange({
+                                    mode: raw ? "raw" : "codec",
+                                    value: { kind: "text", text },
+                                });
+                            }, parsedValue: parsedValue, raw: raw }), _jsx("button", { "aria-label": `toggle raw wire editing for ${dataKey}`, className: "pmr-icon-button", "data-active": raw, onClick: () => {
+                                setRaw((previous) => {
+                                    const next = !previous;
+                                    if (draft?.value.kind === "text") {
+                                        onDraftChange({
+                                            mode: next ? "raw" : "codec",
+                                            value: draft.value,
+                                        });
+                                    }
+                                    return next;
+                                });
+                            }, 
+                            // Mousedown on the button would BLUR a focused input first,
+                            // and blur commits — navigating with the pending draft before
+                            // this button's click ever runs. preventDefault keeps focus.
+                            onMouseDown: (event) => {
+                                event.preventDefault();
+                            }, type: "button", children: "raw" }), _jsx("button", { "aria-label": `clear ${dataKey} to absent`, className: "pmr-icon-button", onClick: () => {
+                                onDraftChange({
+                                    mode: raw ? "raw" : "codec",
+                                    value: { kind: "absent" },
+                                });
+                            }, 
+                            // Same blur-commit race as the raw toggle above.
+                            onMouseDown: (event) => {
+                                event.preventDefault();
+                            }, type: "button", children: "\u2300" }), draft === undefined
+                            ? null
+                            : previewLine(codec, description, dataKey, draft, invalid)] })) })] }));
+}

package/dist/components/sidebar.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+import type { RouteSession } from "../store.js";
+/**
+ * The session rail: every route observed this session in first-observed
+ * order — route pattern, router micro-badge, last-status dot
+ * (gray/stale when not matching the current URL). Selecting an entry pins
+ * it; selecting the pinned entry again returns to auto-follow-current.
+ */
+export declare function Sidebar({ currentKeys, onSelect, selectedKey, sessions, }: {
+    readonly currentKeys: readonly string[];
+    readonly onSelect: (key: null | string) => void;
+    readonly selectedKey: null | string;
+    readonly sessions: readonly RouteSession[];
+}): ReactNode;

package/dist/components/sidebar.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RouterBadge, StatusDot } from "./primitives.js";
+/**
+ * The session rail: every route observed this session in first-observed
+ * order — route pattern, router micro-badge, last-status dot
+ * (gray/stale when not matching the current URL). Selecting an entry pins
+ * it; selecting the pinned entry again returns to auto-follow-current.
+ */
+export function Sidebar({ currentKeys, onSelect, selectedKey, sessions, }) {
+    return (_jsx("nav", { "aria-label": "observed routes", className: "pmr-sidebar", children: sessions.map((session) => {
+            const current = currentKeys.includes(session.key);
+            const selected = selectedKey === null ? current : selectedKey === session.key;
+            return (_jsxs("button", { className: "pmr-sidebar-entry", "data-selected": selected, "data-stale": !current, onClick: () => {
+                    onSelect(selectedKey === session.key ? null : session.key);
+                }, type: "button", children: [_jsx(StatusDot, { status: current ? session.status : "stale" }), _jsx("span", { className: "pmr-sidebar-path", children: session.route.path }), _jsx(RouterBadge, { router: session.params?.routerKind ??
+                            session.search?.routerKind ??
+                            "app" })] }, session.key));
+        }) }));
+}

package/dist/edit.d.ts

@@ -0,0 +1,50 @@
+import type { AnyCodec } from "paramour";
+import type { ParamourSearchWire } from "./seam.js";
+/**
+ * Pure commit-flow assembly: merge the user's per-key drafts into the
+ * observed wire pairs, preserving everything untouched.
+ */
+export type CommitResult = {
+    readonly invalidKeys: readonly string[];
+    readonly status: "invalid";
+} | {
+    readonly pairs: ParamourSearchWire;
+    readonly status: "ok";
+};
+/** One key's edit state. `text` is the WIRE string — the single draft currency. */
+export interface Draft {
+    readonly mode: "codec" | "raw";
+    readonly value: DraftValue;
+}
+export type DraftValue = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
+/**
+ * The commit semantics:
+ * - Untouched keys (declared, unknown, even invalid/caught wire) carry
+ *   VERBATIM in original wire order — never re-serialized.
+ * - A codec-mode draft validates through the single-key decode; any failure
+ *   blocks the whole commit. On success its pairs come from the single-key
+ *   `encodeSearch`, so D8 default-elision and optional absence fall out
+ *   (`[]` → key omitted).
+ * - A raw-mode draft contributes its text verbatim (one pair per line for a
+ *   multi-line draft) and is NEVER blocked — reproducing invalid wire is
+ *   the point. Byte-layer percent-encoding still happens downstream in
+ *   `buildSearchString`; raw mode bypasses codec serialization only.
+ * - An `absent` draft omits the key.
+ * - A drafted key not on the wire appends after the carried pairs, in
+ *   drafts order.
+ */
+export declare function buildCommittedPairs(config: Readonly<Record<string, AnyCodec>>, wire: ParamourSearchWire, drafts: Readonly<Record<string, Draft>>): CommitResult;
+/**
+ * Draft text → wire values, shared by the commit path and the live preview
+ * so they can never disagree: one value per non-empty line, and a FULLY
+ * CLEARED textarea is zero values (`[]` → key omitted through
+ * `encodeSearch`), not one empty-string element. Raw mode shares the
+ * line-splitting but maps the empty draft to one `key=` pair at its call
+ * site — a raw empty draft is a legal wire value.
+ */
+export declare function draftLines(text: string): string[];

package/dist/edit.js

@@ -0,0 +1,81 @@
+import { describeCodec, encodeSearch } from "paramour";
+import { previewDecode } from "./inference.js";
+/**
+ * The commit semantics:
+ * - Untouched keys (declared, unknown, even invalid/caught wire) carry
+ *   VERBATIM in original wire order — never re-serialized.
+ * - A codec-mode draft validates through the single-key decode; any failure
+ *   blocks the whole commit. On success its pairs come from the single-key
+ *   `encodeSearch`, so D8 default-elision and optional absence fall out
+ *   (`[]` → key omitted).
+ * - A raw-mode draft contributes its text verbatim (one pair per line for a
+ *   multi-line draft) and is NEVER blocked — reproducing invalid wire is
+ *   the point. Byte-layer percent-encoding still happens downstream in
+ *   `buildSearchString`; raw mode bypasses codec serialization only.
+ * - An `absent` draft omits the key.
+ * - A drafted key not on the wire appends after the carried pairs, in
+ *   drafts order.
+ */
+export function buildCommittedPairs(config, wire, drafts) {
+    const invalidKeys = [];
+    const replacements = new Map();
+    for (const [key, draft] of Object.entries(drafts)) {
+        replacements.set(key, pairsForDraft(config, key, draft, invalidKeys));
+    }
+    if (invalidKeys.length > 0)
+        return { invalidKeys, status: "invalid" };
+    const pairs = [];
+    const replaced = new Set();
+    for (const [key, value] of wire) {
+        const replacement = replacements.get(key);
+        if (replacement === undefined) {
+            pairs.push([key, value]);
+            continue;
+        }
+        if (replaced.has(key))
+            continue;
+        replaced.add(key);
+        for (const pair of replacement)
+            pairs.push([pair[0], pair[1]]);
+    }
+    for (const [key, replacement] of replacements) {
+        if (replaced.has(key))
+            continue;
+        for (const pair of replacement)
+            pairs.push([pair[0], pair[1]]);
+    }
+    return { pairs, status: "ok" };
+}
+/**
+ * Draft text → wire values, shared by the commit path and the live preview
+ * so they can never disagree: one value per non-empty line, and a FULLY
+ * CLEARED textarea is zero values (`[]` → key omitted through
+ * `encodeSearch`), not one empty-string element. Raw mode shares the
+ * line-splitting but maps the empty draft to one `key=` pair at its call
+ * site — a raw empty draft is a legal wire value.
+ */
+export function draftLines(text) {
+    if (text === "")
+        return [];
+    return text.split("\n").filter((line) => line !== "");
+}
+function pairsForDraft(config, key, draft, invalidKeys) {
+    if (draft.value.kind === "absent")
+        return [];
+    const { text } = draft.value;
+    const codec = config[key];
+    if (draft.mode === "raw" || codec === undefined) {
+        // Multi-line raw drafts (arity-"many" textareas) contribute one pair
+        // per line; the empty draft — a legal wire value in raw mode —
+        // contributes exactly one `key=` pair rather than draftLines's absence.
+        const lines = text === "" ? [""] : draftLines(text);
+        return lines.map((line) => [key, line]);
+    }
+    const preview = previewDecode(codec, key, describeCodec(codec).arity === "many" ? draftLines(text) : text);
+    if (preview.status === "error") {
+        invalidKeys.push(key);
+        return [];
+    }
+    const singleKeyConfig = { [key]: codec };
+    return encodeSearch(singleKeyConfig, { [key]: preview.value });
+}

package/dist/format.d.ts

@@ -0,0 +1,36 @@
+import type { CodecDescription, RouterKind } from "paramour";
+/**
+ * Pure presentation helpers: codec shapes, wire and parsed value rendering,
+ * and the `href()` reproduction snippet.
+ */
+/**
+ * One-line shape label from a `CodecDescription`, e.g.
+ * `enum(asc|desc)? =asc catch` — core's shared walk in its compact skin,
+ * so the panel and `paramour list` can never drift on the field set.
+ */
+export declare function formatShape(description: CodecDescription): string;
+/**
+ * Wire column rendering: absence is `—`; present values are
+ * JSON-quoted so whitespace and emptiness are visible, repeated keys
+ * comma-joined in wire order.
+ */
+export declare function formatWire(values: readonly string[] | string | undefined): string;
+/**
+ * A JS source literal for a decoded value: `Date` prints as
+ * `new Date("<iso>")` so the snippet round-trips through `href`, arrays and
+ * plain objects recurse, identifier-safe keys go unquoted.
+ */
+export declare function jsLiteral(value: unknown): string;
+/**
+ * The `href(route, { params, search })` reproduction snippet: the user's
+ * route identifier is unknowable, so a path-derived placeholder name
+ * carries the true pattern in a trailing comment. Empty halves are omitted.
+ * The snippet doubles as documentation of the API the user should be
+ * writing.
+ */
+export declare function reproSnippet(path: string, router: RouterKind, params: Readonly<Record<string, unknown>> | undefined, search: Readonly<Record<string, unknown>> | undefined): string;
+/**
+ * `/shop/[slug]` → `shopSlugRoute`; `/` → `route`. Brackets and catch-all
+ * dots strip to the bare name; segments camelCase-join.
+ */
+export declare function routeVariableName(path: string): string;

package/dist/format.js

@@ -0,0 +1,109 @@
+import { formatCodecDescription } from "paramour";
+/**
+ * Pure presentation helpers: codec shapes, wire and parsed value rendering,
+ * and the `href()` reproduction snippet.
+ */
+/**
+ * One-line shape label from a `CodecDescription`, e.g.
+ * `enum(asc|desc)? =asc catch` — core's shared walk in its compact skin,
+ * so the panel and `paramour list` can never drift on the field set.
+ */
+export function formatShape(description) {
+    return formatCodecDescription(description, "compact");
+}
+/**
+ * Wire column rendering: absence is `—`; present values are
+ * JSON-quoted so whitespace and emptiness are visible, repeated keys
+ * comma-joined in wire order.
+ */
+export function formatWire(values) {
+    if (values === undefined)
+        return "—";
+    if (typeof values === "string")
+        return JSON.stringify(values);
+    if (values.length === 0)
+        return "—";
+    return values.map((value) => JSON.stringify(value)).join(", ");
+}
+/**
+ * A JS source literal for a decoded value: `Date` prints as
+ * `new Date("<iso>")` so the snippet round-trips through `href`, arrays and
+ * plain objects recurse, identifier-safe keys go unquoted.
+ */
+export function jsLiteral(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    if (value instanceof Date) {
+        return `new Date(${JSON.stringify(value.toISOString())})`;
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((element) => jsLiteral(element)).join(", ")}]`;
+    }
+    switch (typeof value) {
+        case "bigint":
+            return `${String(value)}n`;
+        case "boolean":
+        case "number":
+            return String(value);
+        case "object": {
+            const entries = Object.entries(value);
+            if (entries.length === 0)
+                return "{}";
+            const body = entries
+                .map(([key, entry]) => `${literalKey(key)}: ${jsLiteral(entry)}`)
+                .join(", ");
+            return `{ ${body} }`;
+        }
+        case "string":
+            return JSON.stringify(value);
+        default:
+            // function / symbol: not representable as a value literal.
+            return `[${typeof value}]`;
+    }
+}
+/**
+ * The `href(route, { params, search })` reproduction snippet: the user's
+ * route identifier is unknowable, so a path-derived placeholder name
+ * carries the true pattern in a trailing comment. Empty halves are omitted.
+ * The snippet doubles as documentation of the API the user should be
+ * writing.
+ */
+export function reproSnippet(path, router, params, search) {
+    const name = `${routeVariableName(path)} /* ${path} (${router} router) */`;
+    const lines = [];
+    if (params !== undefined && Object.keys(params).length > 0) {
+        lines.push(`  params: ${jsLiteral(params)},`);
+    }
+    if (search !== undefined && Object.keys(search).length > 0) {
+        lines.push(`  search: ${jsLiteral(search)},`);
+    }
+    if (lines.length === 0)
+        return `href(${name})`;
+    return `href(${name}, {\n${lines.join("\n")}\n})`;
+}
+/**
+ * `/shop/[slug]` → `shopSlugRoute`; `/` → `route`. Brackets and catch-all
+ * dots strip to the bare name; segments camelCase-join.
+ */
+export function routeVariableName(path) {
+    const words = path
+        .split("/")
+        .map((segment) => segment.replaceAll(/[[\].]/g, ""))
+        .filter((segment) => segment !== "")
+        .flatMap((segment) => segment.split(/[^a-zA-Z0-9]+/))
+        .filter((word) => word !== "");
+    if (words.length === 0)
+        return "route";
+    const camel = words
+        .map((word, index) => index === 0
+        ? word.charAt(0).toLowerCase() + word.slice(1)
+        : word.charAt(0).toUpperCase() + word.slice(1))
+        .join("");
+    return `${camel}Route`;
+}
+const IDENTIFIER = /^[$A-Z_a-z][\w$]*$/;
+function literalKey(key) {
+    return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@paramour-js/devtools-panel` — a TanStack Devtools panel for paramour routes.
+ * The public surface is deliberately tiny: the panel component and the
+ * plugin-entry helper. The observation seam's types stay internal — their
+ * contract of record is `@paramour-js/next/devtools-seam`.
+ */
+export { ParamourDevtoolsPanel, type ParamourDevtoolsPanelProps, } from "./components/panel.js";
+export { paramourDevtoolsPlugin, type ParamourDevtoolsPluginEntry, type ParamourDevtoolsPluginOptions, } from "./plugin.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@paramour-js/devtools-panel` — a TanStack Devtools panel for paramour routes.
+ * The public surface is deliberately tiny: the panel component and the
+ * plugin-entry helper. The observation seam's types stay internal — their
+ * contract of record is `@paramour-js/next/devtools-seam`.
+ */
+export { ParamourDevtoolsPanel, } from "./components/panel.js";
+export { paramourDevtoolsPlugin, } from "./plugin.js";

package/dist/inference.d.ts

@@ -0,0 +1,41 @@
+import type { AnyCodec, CodecDescription, Issue } from "paramour";
+/**
+ * Pure decode/attribution logic. Everything here goes through core's
+ * published surface — `parseValue`, `foreignMessage`, and `codecShapeLabel`
+ * via the `paramour/internal` tooling entry (the catch-attribution probe
+ * and issue-label helpers core exports for exactly this) and the single-key
+ * `decodeSearch` trick — a synthesized one-key config gives full
+ * presence/default/catch/duplicate semantics for one value without touching
+ * `~`-internals.
+ */
+/** Why a rendered value differs from the wire. */
+export type Attribution = "catch" | "default" | undefined;
+export type PreviewResult = {
+    readonly issues: readonly Issue[];
+    readonly status: "error";
+} | {
+    readonly status: "ok";
+    readonly value: unknown;
+};
+/**
+ * The attribution rule: default = wire absent + presence declared
+ * "defaulted"; catch = wire present + `.catch()` declared + the parse would
+ * have failed without it. The duplicate-scalar case (two values for a
+ * single-value param) is a parse failure decodeSearch raises itself, so it
+ * can't be probed through `parseValue` — special-cased here.
+ */
+export declare function attributionFor(description: CodecDescription, codec: AnyCodec, wireValues: readonly string[]): Attribution;
+/**
+ * The raw parse outcome WITHOUT `.catch()` recovery — core's `parseValue`
+ * exists for this probe. Foreign throws from a custom codec count as
+ * failures too: whatever the class, the wire value did not parse cleanly.
+ */
+export declare function parseWouldFail(codec: AnyCodec, raw: string): boolean;
+/**
+ * What WOULD this wire draft decode to — the live edit validation.
+ * `draft === undefined` previews absence — surfacing the default value or
+ * `undefined`, teaching presence semantics. Full fidelity via the
+ * single-key `decodeSearch`: defaults, catches, required-missing, and the
+ * duplicate-scalar rejection all behave exactly as the real decode would.
+ */
+export declare function previewDecode(codec: AnyCodec, key: string, draft: readonly string[] | string | undefined): PreviewResult;

package/dist/inference.js

@@ -0,0 +1,78 @@
+import { decodeSearch, SearchDecodeError } from "paramour";
+import { codecShapeLabel, foreignMessage, parseValue } from "paramour/internal";
+/**
+ * The attribution rule: default = wire absent + presence declared
+ * "defaulted"; catch = wire present + `.catch()` declared + the parse would
+ * have failed without it. The duplicate-scalar case (two values for a
+ * single-value param) is a parse failure decodeSearch raises itself, so it
+ * can't be probed through `parseValue` — special-cased here.
+ */
+export function attributionFor(description, codec, wireValues) {
+    if (wireValues.length === 0) {
+        return description.presence === "defaulted" ? "default" : undefined;
+    }
+    if (!description.caught)
+        return undefined;
+    if (description.arity === "single" && wireValues.length > 1)
+        return "catch";
+    return wireValues.some((raw) => parseWouldFail(codec, raw))
+        ? "catch"
+        : undefined;
+}
+/**
+ * The raw parse outcome WITHOUT `.catch()` recovery — core's `parseValue`
+ * exists for this probe. Foreign throws from a custom codec count as
+ * failures too: whatever the class, the wire value did not parse cleanly.
+ */
+export function parseWouldFail(codec, raw) {
+    try {
+        parseValue(codec, raw);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * What WOULD this wire draft decode to — the live edit validation.
+ * `draft === undefined` previews absence — surfacing the default value or
+ * `undefined`, teaching presence semantics. Full fidelity via the
+ * single-key `decodeSearch`: defaults, catches, required-missing, and the
+ * duplicate-scalar rejection all behave exactly as the real decode would.
+ */
+export function previewDecode(codec, key, draft) {
+    const config = { [key]: codec };
+    const source = {};
+    if (draft !== undefined) {
+        source[key] = typeof draft === "string" ? draft : [...draft];
+    }
+    try {
+        const decoded = decodeSearch(config, source);
+        return { status: "ok", value: decoded[key] };
+    }
+    catch (error) {
+        if (error instanceof SearchDecodeError) {
+            return { issues: error.issues, status: "error" };
+        }
+        // Foreign throws arrive UNWRAPPED (decodeSearch's taxonomy) from user
+        // schema/custom-codec code, including values String() itself cannot
+        // stringify — core's foreignMessage carries the hardening. The
+        // synthesized issue is enriched like a real one: the codec is in hand
+        // for `expected` — labeled by core's own codecShapeLabel, no forceMany,
+        // because this is a whole-codec search-position decode (the codec's own
+        // arity carries any `[]`), matching decodeSearch's issue labels — and a
+        // scalar draft IS the offending wire value (a string[] draft has no
+        // single one — same absence rule as core).
+        return {
+            issues: [
+                {
+                    expected: codecShapeLabel(codec),
+                    key,
+                    message: foreignMessage(error),
+                    ...(typeof draft === "string" ? { wire: draft } : {}),
+                },
+            ],
+            status: "error",
+        };
+    }
+}

package/dist/match.d.ts

@@ -0,0 +1,16 @@
+import type { AnyRoute } from "paramour";
+/**
+ * Structural view of a route's define-time segment tokens (`~segments`) —
+ * derived from the route type rather than importing core's non-barrel
+ * `PathSegment`, so this stays pinned to what a live route actually carries.
+ */
+export type RouteSegments = AnyRoute["~segments"];
+/**
+ * Does `pathname` (from `window.location`) match this route's pattern?
+ * Powers the "current URL" grouping: static segments compare against the
+ * percent-DECODED path part; `single` consumes exactly one part; `catchall`
+ * one-plus; `optional-catchall` zero-plus (both are terminal by Next's
+ * grammar, mirrored by core's tokenizer). Trailing slashes are
+ * normalization noise (`/shop/` matches `/shop`).
+ */
+export declare function matchesPathname(segments: RouteSegments, pathname: string): boolean;