@marianmeres/simple-router 3.1.0 → 3.3.0

package/AGENTS.md

@@ -6,7 +6,7 @@ Machine-readable documentation for AI coding assistants.
 
 ```yaml
 name: "@marianmeres/simple-router"
-version: "2.2.3"
+version: "3.2.0"
 runtime: ["deno", "node"]
 module_system: "ESM"
 entry_point: "src/mod.ts"
@@ -38,11 +38,11 @@ key_features:
 source_files:
   - path: "src/mod.ts"
     purpose: "Main entry point, re-exports public API"
-    exports: ["SimpleRoute", "SimpleRouter", "RouteConfig", "RouteParams", "Logger", "RouteCallback", "RouterConfig", "RouterCurrent", "RouterOnOptions", "RouterOptions", "RouterSubscriber", "RouterUnsubscribe"]
+    exports: ["SimpleRoute", "SimpleRouter", "RouteConfig", "RouteParams", "SimpleRouteOptions", "Logger", "RouteCallback", "RouterConfig", "RouterCurrent", "RouterOnOptions", "RouterOptions", "RouterSubscriber", "RouterUnsubscribe"]
 
   - path: "src/route.ts"
     purpose: "Low-level pattern parser"
-    exports: ["SimpleRoute", "RouteConfig", "RouteParams"]
+    exports: ["SimpleRoute", "RouteConfig", "RouteParams", "SimpleRouteOptions"]
     class: "SimpleRoute"
 
   - path: "src/router.ts"
@@ -52,12 +52,10 @@ source_files:
 
 test_files:
   - path: "tests/route.test.ts"
-    test_count: 63
-    coverage: "Pattern matching, query params, errors"
+    coverage: "Pattern matching, query params, regex-with-parens constraints, strict mode, optional-position rules"
 
   - path: "tests/router.test.ts"
-    test_count: 24
-    coverage: "Router lifecycle, subscriptions, logger, edge cases"
+    coverage: "Router lifecycle, subscriptions, logger, strict propagation, specificity-shadowing warning"
 
 build_files:
   - path: "scripts/build-npm.ts"
@@ -102,7 +100,7 @@ constructor:
     - name: "config"
       type: "RouterConfig<T> | RouterOptions<T> | null"
       optional: true
-      description: "Route config or options object with routes and logger"
+      description: "Route config or options object with routes, logger, and strict"
 
 methods:
   - name: "on"
@@ -155,7 +153,11 @@ constructor:
     - name: "route"
       type: "string"
       description: "Pattern string"
-  throws: "Error if pattern invalid"
+    - name: "options"
+      type: "SimpleRouteOptions"
+      optional: true
+      description: "e.g. { strict: true } to disable empty-segment collapsing"
+  throws: "Error if pattern invalid (multiple spread segments, invalid regex, invalid param name, optional-followed-by-required)"
 
 static_methods:
   - name: "parseQueryString"
@@ -187,12 +189,13 @@ patterns:
     syntax: "[name(regex)]"
     example: "[id([0-9]+)]"
     captures: "{ id: '123' }"
-    constraint: "Must match regex"
+    constraint: "name must match /^\\w+$/. Regex may contain parentheses (capturing/non-capturing groups, alternation) — balanced-paren splitting is used."
 
   optional:
     syntax: "[name]?"
     example: "[id]?"
     captures: "{} or { id: 'value' }"
+    constraint: "Only allowed in trailing position (or directly before wildcard). Optional-followed-by-required throws at construction."
 
   spread:
     syntax: "[...name]"
@@ -229,6 +232,7 @@ interface Logger {
 interface RouterOptions<T = unknown> {
   routes?: RouterConfig<T> | null;
   logger?: Logger | null;
+  strict?: boolean;             // propagates to every registered route
 }
 
 interface RouterCurrent {
@@ -240,6 +244,11 @@ interface RouterCurrent {
 interface RouterOnOptions {
   label?: string | null;
   allowQueryParams?: boolean;
+  strict?: boolean;             // overrides router-level default
+}
+
+interface SimpleRouteOptions {
+  strict?: boolean;             // disables empty-segment collapsing
 }
 
 type RouterSubscriber = (current: RouterCurrent) => void;
@@ -298,11 +307,14 @@ const router = new SimpleRouter({
 behaviors:
   - name: "First Match Wins"
     description: "Routes matched in registration order"
-    implication: "Register specific routes before generic ones"
+    implication: "Register specific routes before generic ones. When SimpleRouter.debug is true, shadowing is detected at registration and warned via the logger (or console.warn)."
 
   - name: "Separator Normalization"
-    description: "Multiple separators normalized, trimmed from ends"
-    example: "//foo//bar// matches foo/bar"
+    description: "Non-strict (default): multiple separators are collapsed and trimmed from ends. Strict (opt-in): internal empty segments are preserved."
+    example: "non-strict: '//foo//bar//' matches 'foo/bar'. strict: '/a//b' does NOT match '/a/b'."
+
+  - name: "Optional Segment Position"
+    description: "Optional segments ('[x]?') may only appear trailing (or immediately before wildcard '*'). Optional-followed-by-required throws at construction — register separate routes instead."
 
   - name: "Query String Priority"
     description: "Path params override same-name query params"
@@ -312,6 +324,9 @@ behaviors:
 
   - name: "Immediate Subscription Call"
     description: "subscribe() calls callback immediately with current state"
+
+  - name: "Parameter Names Are Literal"
+    description: "Parameter names in the pattern are NOT URI-decoded. The pattern '[id%20x]' produces the key 'id%20x'. Parameter values ARE decoded."
 ```
 
 ## Error Conditions
@@ -330,6 +345,12 @@ errors:
   - condition: "Invalid regex in pattern"
     message: "Invalid regex in route pattern '{segment}': {error}"
 
+  - condition: "Invalid parameter name in named constraint"
+    message: "Invalid parameter name '{name}' in route pattern '{segment}' (must match /^\\w+$/)"
+
+  - condition: "Optional segment followed by a required segment"
+    message: "Invalid route '{route}': optional segment '{segment}?' must not be followed by a required segment ..."
+
   - condition: "Non-function subscriber"
     throws: "TypeError: Subscription is not a function"
 ```
@@ -352,7 +373,27 @@ guidelines:
   - "First-match-wins is core behavior - do not change"
   - "Query param parsing must remain toggleable per-route"
   - "Keep catch-all ('*') handling separate from regular routes"
-  - "URL encoding/decoding must be handled for params"
+  - "URL encoding/decoding: param VALUES are decoded; param NAMES are not"
   - "Logger interface must remain compatible with @marianmeres/clog"
-  - "Tests cover 87 cases - run before any changes"
+  - "Strict mode is opt-in and propagates router → route; per-route can override"
+  - "Shadowing warning runs only when SimpleRouter.debug is true (no perf cost otherwise)"
+  - "Run `deno task test` before any changes"
+```
+
+## Breaking Changes (3.2.0)
+
+```yaml
+breaking_changes:
+  - id: "optional-middle-rejected"
+    description: "Patterns like '/foo/[bar]?/baz' now throw at construction. Previously they parsed but silently treated the optional marker as required. Register two separate routes instead."
+
+  - id: "param-names-not-decoded"
+    description: "Parameter names are taken literally from the pattern. '/foo/[id%20x]' used to produce the key 'id x'; now produces 'id%20x'. Parameter values are still URI-decoded."
+
+  - id: "named-constraint-name-validated"
+    description: "In a named regex constraint '[name(regex)]', 'name' must match /^\\w+$/. Previously this was not validated."
+
+bug_fixes:
+  - id: "regex-constraint-with-parens"
+    description: "Constraints containing parentheses (e.g. '[s((?:a|b)+)]', '[x((\\d+)-(\\d+))]') used to produce garbage regexes or throw obscure errors due to greedy regex-based splitting. Now uses balanced-paren splitting and works correctly."
 ```

package/API.md

@@ -136,6 +136,7 @@ Registers one or more route patterns with a callback function.
 |------|------|---------|-------------|
 | `label` | `string \| null` | `null` | Label for debugging/identification |
 | `allowQueryParams` | `boolean` | `true` | Whether to parse query parameters |
+| `strict` | `boolean` | _inherits from router_ | Strict segment matching (see `RouterOptions.strict`) |
 
 **Example:**
 
@@ -164,6 +165,8 @@ router.on("*", () => NotFoundPage);
 
 **Important:** Routes are matched in registration order. First match wins!
 
+**Shadowing warning:** When `SimpleRouter.debug` is enabled, registering a route that is strictly more specific than an already-registered route emits a `warn`-level log message (via the provided `Logger` if any, otherwise `console.warn`). The check is skipped when `debug` is off, so there is no runtime cost in production.
+
 ---
 
 #### `exec()`
@@ -297,7 +300,7 @@ Low-level route pattern parser. Use this directly only when you need pattern mat
 ### Constructor
 
 ```ts
-new SimpleRoute(pattern: string)
+new SimpleRoute(pattern: string, options?: SimpleRouteOptions)
 ```
 
 Creates a new route pattern parser.
@@ -307,14 +310,18 @@ Creates a new route pattern parser.
 | Name | Type | Description |
 |------|------|-------------|
 | `pattern` | `string` | Route pattern to match against |
+| `options` | `SimpleRouteOptions` | Optional configuration (currently `{ strict?: boolean }`) |
 
-**Throws:** `Error` if pattern is invalid (e.g., multiple spread segments, invalid regex)
+**Throws:** `Error` if pattern is invalid — multiple spread segments, invalid regex, invalid parameter name in a named constraint, or an optional segment followed by a required one.
 
 **Example:**
 
 ```ts
 const route = new SimpleRoute("/user/[id([0-9]+)]");
 const route2 = new SimpleRoute("/files/[...path]");
+
+// Strict mode — '/a//b' will NOT match '/a/b'
+const strict = new SimpleRoute("/a/b", { strict: true });
 ```
 
 <a id="simpleroute-static-properties"></a>
@@ -462,11 +469,22 @@ Current router state object.
 interface RouterOnOptions {
   label?: string | null;      // Optional label for debugging
   allowQueryParams?: boolean; // Whether to parse query params (default: true)
+  strict?: boolean;           // Per-route strict mode (overrides router default)
 }
 ```
 
 Options for the `on()` method.
 
+### SimpleRouteOptions
+
+```ts
+interface SimpleRouteOptions {
+  strict?: boolean; // Disable empty-segment collapsing (default: false)
+}
+```
+
+Options for the `SimpleRoute` constructor.
+
 ### Logger
 
 ```ts
@@ -486,6 +504,7 @@ Logger interface compatible with `@marianmeres/clog`. Provides console-compatibl
 interface RouterOptions<T = unknown> {
   routes?: RouterConfig<T> | null;  // Route configuration
   logger?: Logger | null;           // Optional logger instance
+  strict?: boolean;                 // Strict mode; propagates to every route
 }
 ```
 
@@ -494,6 +513,8 @@ Options object for the constructor (alternative to plain `RouterConfig`).
 **Type Parameters:**
 - `T` - The return type of route callbacks (default: `unknown`)
 
+**`strict` mode:** when `true`, empty segments in both patterns and inputs (e.g. `/a//b`) are preserved rather than collapsed. This means `/a//b` will NOT match the canonical pattern `/a/b` — useful for URL canonicalization and preventing accidental shadow-matching in environments where concatenation bugs can produce doubled separators. Per-route `RouterOnOptions.strict` overrides this default.
+
 ### RouterSubscriber
 
 ```ts
@@ -541,11 +562,11 @@ Internal configuration for a parsed route segment. Exported for advanced use cas
 
 ### Key Behaviors
 
-1. **Separator Normalization:** Multiple separators normalized to single; trimmed from ends
-2. **First Match Wins:** Routes matched in registration order
-3. **Query String Parsing:** Enabled by default, can disable per-route
-4. **Path Params Priority:** Path params override query params with same name
-5. **URL Decoding:** Both param names and values are URL-decoded
+1. **Separator Normalization:** Multiple separators are collapsed in non-strict mode (default); trimmed from ends. Enable `strict: true` to preserve them.
+2. **First Match Wins:** Routes matched in registration order. Enable `SimpleRouter.debug` for shadowing warnings at registration time.
+3. **Query String Parsing:** Enabled by default, can disable per-route.
+4. **Path Params Priority:** Path params override query params with the same name.
+5. **URL Decoding:** Parameter _values_ are URL-decoded. Parameter _names_ are taken literally from the pattern (not decoded).
 
 ### Pattern Constraints
 
@@ -553,6 +574,12 @@ Internal configuration for a parsed route segment. Exported for advanced use cas
 - Only one spread segment allowed per route
 - Wildcard `*` must be the last segment
 - Regex in `[name(regex)]` must be valid JavaScript regex
+- In a named constraint `[name(regex)]`, `name` must match `/^\w+$/`
+- An optional segment (`[x]?`) may not be followed by a required segment — optional segments are only allowed in trailing position (or directly before a wildcard `*`)
+
+### Security (regex constraints)
+
+Regex constraints are compiled as ordinary JavaScript regexes. Some patterns (notably nested quantifiers like `(a+)+`) can exhibit catastrophic backtracking on crafted inputs. Route patterns are author-controlled — **never** accept them from untrusted input. Prefer simple character classes (`[0-9]+`, `[a-z]+`) over nested quantifiers.
 
 ### Examples
 

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/README.md

@@ -77,7 +77,35 @@ window.onhashchange = () => {
 
 ### Separators
 
-The default separator is `/`. Multiple separators are normalized to single, and separators are trimmed from both ends before matching.
+The default separator is `/`. By default (non-strict mode), multiple consecutive separators are collapsed into a single one, and separators are trimmed from both ends before matching. So `/foo//bar` and `/foo/bar/` both resolve to `/foo/bar`.
+
+If you need to treat consecutive separators as significant (for example, to canonicalize URLs and prevent accidental shadow-matching), enable **strict mode**:
+
+```ts
+// At router level (propagates to every route):
+const router = new SimpleRouter({ strict: true, routes: { "/a/b": handler } });
+router.exec("/a/b");   // matches
+router.exec("/a//b");  // false (no match)
+
+// Per-route override:
+router.on("/legacy", handler, { strict: true });
+
+// Or directly on SimpleRoute:
+new SimpleRoute("/a/b", { strict: true });
+```
+
+### Optional segments
+
+Optional segments (`[name]?`) are only allowed in **trailing position** (or directly before a trailing wildcard `*`). Optional-followed-by-required patterns are rejected at construction:
+
+```ts
+new SimpleRoute("/foo/[bar]?/baz");
+// Throws: optional segment '[bar]?' must not be followed by a required segment
+
+// Instead, register two routes:
+router.on("/foo/[bar]/baz", handler);
+router.on("/foo/baz",       handler);
+```
 
 ## Pattern Examples
 
@@ -96,7 +124,6 @@ The default separator is `/`. Multiple separators are normalized to single, and
 | `/foo/[bar]/[id([0-9]+)]`     | `/foo/baz/123`     | `{ bar: "baz", id: "123" }`      |
 | `/foo/[bar]?`                 | `/foo`             | `{}`                             |
 | `/foo/[bar]?`                 | `/foo/bar`         | `{ bar: "bar" }`                 |
-| `/foo/[bar]?/baz`             | `/foo/bar/baz`     | `{ bar: "bar" }`                 |
 | `/[...path]/[file]`           | `/foo/bar/baz.js`  | `{ path: "foo/bar", file: "baz.js" }` |
 | `/foo/*`                      | `/foo/bar/baz.js`  | `{}`                             |
 | `/[foo]/*`                    | `/foo/bar`         | `{ foo: "foo" }`                 |
@@ -126,7 +153,7 @@ const router = new SimpleRouter({
 });
 ```
 
-- `config` - Either a `RouterConfig` object mapping route patterns to callbacks, or a `RouterOptions` object with `routes` and `logger` properties
+- `config` - Either a `RouterConfig` object mapping route patterns to callbacks, or a `RouterOptions` object with `routes`, `logger`, and `strict` properties
 
 #### Methods
 
@@ -156,8 +183,9 @@ router.on("/raw", (params) => RawPage, { allowQueryParams: false });
 **Options:**
 - `label` - Optional label for debugging (visible via `info()`)
 - `allowQueryParams` - Whether to parse query parameters (default: `true`)
+- `strict` - Per-route strict matching (overrides router default)
 
-**Important:** Routes are matched in registration order. First match wins!
+**Important:** Routes are matched in registration order. First match wins! When `SimpleRouter.debug` is enabled, a warning is logged at registration time if a new route would be shadowed by an already-registered one.
 
 ##### `exec(url, fallbackFn?)`
 
@@ -287,13 +315,14 @@ const router2 = new SimpleRouter({
 import type {
 	Logger,
 	RouteParams,
-	RouteCallback,     // RouteCallback<T = unknown>
-	RouterConfig,      // RouterConfig<T = unknown>
+	RouteCallback,      // RouteCallback<T = unknown>
+	RouterConfig,       // RouterConfig<T = unknown>
 	RouterCurrent,
 	RouterOnOptions,
-	RouterOptions,     // RouterOptions<T = unknown>
+	RouterOptions,      // RouterOptions<T = unknown>
 	RouterSubscriber,
 	RouterUnsubscribe,
+	SimpleRouteOptions, // { strict?: boolean }
 } from "@marianmeres/simple-router";
 ```
 
@@ -394,5 +423,19 @@ dotRouter.exec("app.settings.profile");
 // Returns: "Settings: profile"
 ```
 
+## Security notes
+
+Regex constraints inside a route pattern (e.g. `[id([0-9]+)]`) are compiled with `RegExp`, so any valid JavaScript regex is accepted. A handful of patterns — typically nested quantifiers such as `(a+)+` — can exhibit catastrophic backtracking (ReDoS) on crafted inputs.
+
+- Route patterns are author-controlled: **never** accept them from untrusted input.
+- Prefer simple character classes (`[0-9]+`, `[a-z]+`) over nested quantifiers.
+- If you need a complex constraint, test it against adversarial inputs first.
+
+## Breaking changes
+
+### 3.2.0
 
+- **Optional-followed-by-required is now rejected at construction.** Patterns like `/foo/[bar]?/baz` previously parsed but silently treated the optional marker as required — `/foo/baz` never matched. Such patterns now throw with a clear error. Register two separate routes instead (`/foo/[bar]/baz` and `/foo/baz`).
+- **Parameter names are no longer URI-decoded.** A pattern like `/foo/[id%20x]` used to produce the key `id x` in the params object; it now produces `id%20x`. Param values are still decoded. Parameter names in a named constraint (`[name(regex)]`) must now match `\w+`.
+- **Regex constraints with parentheses now work correctly.** Patterns like `/[id((?:a|b)+)]` previously produced garbage regexes or threw obscure "Invalid regular expression" errors; they now parse and match as expected.
 

package/dist/mod.d.ts

@@ -1,4 +1,4 @@
 export { SimpleRoute } from "./route.js";
 export { SimpleRouter } from "./router.js";
-export type { RouteConfig, RouteParams } from "./route.js";
+export type { RouteConfig, RouteParams, SimpleRouteOptions } from "./route.js";
 export type { Logger, RouteCallback, RouterConfig, RouterCurrent, RouterOnOptions, RouterOptions, RouterSubscriber, RouterUnsubscribe, } from "./router.js";

package/dist/route.d.ts

@@ -13,6 +13,17 @@ export interface RouteConfig {
  * Route parameters extracted from URL segments and query strings.
  */
 export type RouteParams = Record<string, any>;
+/**
+ * Options for the `SimpleRoute` constructor.
+ */
+export interface SimpleRouteOptions {
+    /**
+     * When true, empty segments (caused by consecutive separators) are preserved
+     * rather than silently collapsed. In strict mode, inputs like `/a//b` will
+     * NOT match a pattern `/a/b`. Default: false.
+     */
+    strict?: boolean;
+}
 export declare class SimpleRoute {
     #private;
     readonly route: string;
@@ -30,7 +41,9 @@ export declare class SimpleRoute {
      * Creates a new SimpleRoute instance.
      *
      * @param route - Pattern string to match against (URL, file path, command, or any string identifier)
-     * @throws {Error} If route pattern is invalid (e.g., multiple spread segments)
+     * @param options - Optional configuration (e.g. `{ strict: true }` to disable empty-segment collapsing)
+     * @throws {Error} If route pattern is invalid (multiple spread segments, optional
+     * segment followed by a required one, invalid regex constraint, etc.)
      *
      * @example
      * ```ts
@@ -44,9 +57,12 @@ export declare class SimpleRoute {
      *
      * // Command patterns
      * new SimpleRoute("user:delete:[id]");
+     *
+     * // Strict mode: '/a//b' will NOT match '/a/b'
+     * new SimpleRoute("/a/b", { strict: true });
      * ```
      */
-    constructor(route: string);
+    constructor(route: string, options?: SimpleRouteOptions);
     /**
      * Parses a query string into an object of key-value pairs.
      * Handles URL decoding of both keys and values.

package/dist/route.js

@@ -11,11 +11,14 @@ export class SimpleRoute {
      */
     static WILDCARD = "*";
     #parsed;
+    #strict;
     /**
      * Creates a new SimpleRoute instance.
      *
      * @param route - Pattern string to match against (URL, file path, command, or any string identifier)
-     * @throws {Error} If route pattern is invalid (e.g., multiple spread segments)
+     * @param options - Optional configuration (e.g. `{ strict: true }` to disable empty-segment collapsing)
+     * @throws {Error} If route pattern is invalid (multiple spread segments, optional
+     * segment followed by a required one, invalid regex constraint, etc.)
      *
      * @example
      * ```ts
@@ -29,31 +32,54 @@ export class SimpleRoute {
      *
      * // Command patterns
      * new SimpleRoute("user:delete:[id]");
+     *
+     * // Strict mode: '/a//b' will NOT match '/a/b'
+     * new SimpleRoute("/a/b", { strict: true });
      * ```
      */
-    constructor(route) {
+    constructor(route, options = {}) {
         this.route = route;
-        this.#parsed = SimpleRoute.#parse(route);
+        this.#strict = options.strict === true;
+        this.#parsed = SimpleRoute.#parse(route, this.#strict);
     }
     // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
     static #escapeRegExp(str) {
         return str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
     }
-    static #sanitizeAndSplit(str) {
+    static #sanitizeAndSplit(str, strict) {
         const s = SimpleRoute.#escapeRegExp(SimpleRoute.SPLITTER);
-        return (`${str}`
+        let out = `${str}`
             .trim()
             // Trim splitters from left and right
             .replace(new RegExp(`^(${s})+`), "")
             .replace(new RegExp(`(${s})+$`), "")
-            .split(SimpleRoute.SPLITTER)
-            // Remove empty segments (normalizes multiple splitters into one)
-            .filter(Boolean));
+            .split(SimpleRoute.SPLITTER);
+        // In non-strict mode, empty (internal) segments are silently collapsed.
+        // In strict mode, they are preserved and treated as literal empty segments
+        // (which generally will not match any parameterized pattern position).
+        if (!strict)
+            out = out.filter(Boolean);
+        return out;
+    }
+    /**
+     * Splits a bracketed definition like "name(regex)" into its two parts.
+     * Uses balanced-paren tracking so nested groups in the regex are preserved.
+     * Returns null if the input is not in the name(...)  shape.
+     */
+    static #splitNamedConstraint(inner) {
+        const open = inner.indexOf("(");
+        if (open <= 0)
+            return null;
+        if (!inner.endsWith(")"))
+            return null;
+        const name = inner.slice(0, open);
+        const regex = inner.slice(open + 1, -1);
+        return { name, regex };
     }
-    static #parse(route) {
+    static #parse(route, strict) {
         let wasSpread = false;
         let wasWildcard = false;
-        return SimpleRoute.#sanitizeAndSplit(route).reduce((memo, segment, idx, all) => {
+        const parsed = SimpleRoute.#sanitizeAndSplit(route, strict).reduce((memo, segment, idx, all) => {
             let name = null;
             // If optional, remove trailing '?' marker
             let isOptional = segment.endsWith("?");
@@ -84,12 +110,16 @@ export class SimpleRoute {
                 if (m) {
                     name = m[1];
                     test = /.+/;
-                    // id([0-9]+)
-                    const m2 = m[1].match(/^(\w.*)\((.+)\)$/);
-                    if (m2) {
-                        name = m2[1];
+                    // Named constraint: [id([0-9]+)], [s((?:a|b)+)], ...
+                    // Split on first '(' (balanced-paren-safe).
+                    const split = SimpleRoute.#splitNamedConstraint(m[1]);
+                    if (split) {
+                        if (!/^\w+$/.test(split.name)) {
+                            throw new Error(`Invalid parameter name '${split.name}' in route pattern '${segment}' (must match /^\\w+$/)`);
+                        }
+                        name = split.name;
                         try {
-                            test = new RegExp("^" + m2[2] + "$");
+                            test = new RegExp("^" + split.regex + "$");
                         }
                         catch (e) {
                             throw new Error(`Invalid regex in route pattern '${segment}': ${e.message}`);
@@ -104,6 +134,24 @@ export class SimpleRoute {
             memo.push({ segment, name, test, isOptional, isSpread });
             return memo;
         }, []);
+        // An optional segment may only appear in trailing position (or directly
+        // before a wildcard, which itself is optional). Otherwise the 'optional'
+        // marker is misleading — it can never actually be skipped.
+        for (let i = 0; i < parsed.length; i++) {
+            const p = parsed[i];
+            if (!p.isOptional)
+                continue;
+            // segment is optional — all following segments must also be optional
+            for (let j = i + 1; j < parsed.length; j++) {
+                if (!parsed[j].isOptional) {
+                    throw new Error(`Invalid route '${route}': optional segment '${p.segment}?' must not be followed by a required segment ('${parsed[j].segment}'). ` +
+                        `Optional segments are only allowed in trailing position. ` +
+                        `Register separate routes instead.`);
+                }
+            }
+            break;
+        }
+        return parsed;
     }
     /**
      * Parses a query string into an object of key-value pairs.
@@ -186,7 +234,7 @@ export class SimpleRoute {
             url = _backup.slice(0, qPos);
             matched = SimpleRoute.parseQueryString(_backup.slice(qPos + 1));
         }
-        let segments = SimpleRoute.#sanitizeAndSplit(url);
+        let segments = SimpleRoute.#sanitizeAndSplit(url, this.#strict);
         // If there are spread definitions, we need to adjust input by grouping
         // (joining) segments that were initially split
         const hasSpread = this.#parsed.some((v) => v.isSpread);
@@ -238,7 +286,7 @@ export class SimpleRoute {
             }
             if (p.name) {
                 try {
-                    matched[decodeURIComponent(p.name)] = decodeURIComponent(s);
+                    matched[p.name] = decodeURIComponent(s);
                 }
                 catch {
                     // Fallback for malformed URI components

package/dist/router.d.ts

@@ -46,6 +46,11 @@ export interface RouterOnOptions {
     label?: string | null;
     /** Whether to parse query parameters (default: true) */
     allowQueryParams?: boolean;
+    /**
+     * Strict matching mode for this route (overrides router-level default).
+     * See `RouterOptions.strict`.
+     */
+    strict?: boolean;
 }
 /**
  * Configuration object for initializing the router with routes.
@@ -87,6 +92,13 @@ export interface RouterOptions<T = unknown> {
     routes?: RouterConfig<T> | null;
     /** Optional logger instance for debug output (compatible with @marianmeres/clog) */
     logger?: Logger | null;
+    /**
+     * Strict matching mode. When true, empty segments in inputs (caused by
+     * consecutive separators like `/a//b`) are NOT silently collapsed — such
+     * inputs will not match the canonical pattern `/a/b`. Propagates to every
+     * route registered via this router. Default: false.
+     */
+    strict?: boolean;
 }
 /**
  * Unsubscribe function returned by the `subscribe()` method.

package/dist/router.js

@@ -42,6 +42,7 @@ export class SimpleRouter {
     static debug = false;
     #routes = [];
     #catchAll = null;
+    #strict = false;
     #current = {
         route: null,
         params: null,
@@ -76,11 +77,12 @@ export class SimpleRouter {
     constructor(config = null) {
         let routes = null;
         if (config) {
-            // Check if config is RouterOptions (has 'routes' or 'logger' key)
-            if ("routes" in config || "logger" in config) {
+            // Check if config is RouterOptions (has 'routes', 'logger' or 'strict' key)
+            if ("routes" in config || "logger" in config || "strict" in config) {
                 const options = config;
                 routes = options.routes ?? null;
                 this.#logger = options.logger ?? null;
+                this.#strict = options.strict === true;
             }
             else {
                 // Backwards compatible: treat as RouterConfig
@@ -180,6 +182,7 @@ export class SimpleRouter {
      */
     on(routes, cb, options = {}) {
         const { label = null, allowQueryParams = true } = options;
+        const strict = options.strict ?? this.#strict;
         if (!Array.isArray(routes))
             routes = [routes];
         routes.forEach((route) => {
@@ -187,15 +190,43 @@ export class SimpleRouter {
                 this.#catchAll = cb;
             }
             else {
-                this.#routes.push([
-                    new SimpleRoute(route),
-                    cb,
-                    allowQueryParams,
-                    label,
-                ]);
+                const sr = new SimpleRoute(route, { strict });
+                // Dev-only shadowing warning: if an earlier route would consume the
+                // literal form of this one, the new route is unreachable. Only runs
+                // when debug logging is enabled to avoid per-registration overhead
+                // in production.
+                if (SimpleRouter.debug)
+                    this.#warnIfShadowed(route);
+                this.#routes.push([sr, cb, allowQueryParams, label]);
             }
         });
     }
+    #warnIfShadowed(route) {
+        for (const [existing] of this.#routes) {
+            if (existing.route === route)
+                continue;
+            // If the existing pattern matches the literal text of the new route,
+            // any real input intended for the new route will also match the
+            // existing one first (first-match-wins).
+            let matched = null;
+            try {
+                matched = existing.parse(route);
+            }
+            catch {
+                // ignore — some patterns may not be parseable as inputs
+            }
+            if (matched !== null) {
+                const msg = `[SimpleRouter] route '${route}' is shadowed by earlier ` +
+                    `route '${existing.route}' (first-match-wins). ` +
+                    `Register the more specific route first.`;
+                if (this.#logger)
+                    this.#logger.warn(msg);
+                else
+                    console.warn(msg);
+                break;
+            }
+        }
+    }
     /**
      * Executes pattern matching against the provided string.
      * Returns the value returned by the matched route's callback (type `T`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/simple-router",
-	"version": "3.1.0",
+	"version": "3.3.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -10,10 +10,18 @@
 			"import": "./dist/mod.js"
 		}
 	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md"
+	],
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/pubsub": "^2.4.4"
+		"@marianmeres/pubsub": "^3.0.0"
 	},
 	"repository": {
 		"type": "git",