@abide/abide 0.41.1 → 0.43.0

package/src/lib/ui/compile/stripEffects.ts

@@ -2,12 +2,14 @@ import ts from 'typescript'
 import { TS_PRINTER } from './TS_PRINTER.ts'
 
 /*
-Removes `effect(...)` calls from a script for the SSR back-end. Effects are client
+Removes effect calls from a script for the SSR back-end. Effects are client
 lifecycle — they touch the DOM / run side effects and emit no HTML, so the server
 render (a snapshot of the pre-effect markup, like every framework) must not run
-them. Every `effect(<args>)` call is replaced by `undefined`, dropping its body:
-an `effect(() => …)` statement becomes a no-op, and a `const stop = effect(…)`
-binding keeps a defined (unused) name. Client compilation keeps effects untouched.
+them. Both surfaces are stripped: the generated/runtime bare `effect(<args>)` and
+the authored scope form `scope().effect(<args>)` (and a captured/destructured handle
+`c.effect(<args>)`), each replaced by `undefined` — an `effect(() => …)` statement
+becomes a no-op, and a `const stop = effect(…)` binding keeps a defined (unused) name.
+Client compilation keeps effects untouched.
 */
 export function stripEffects(code: string): string {
     const source = ts.createSourceFile('script.ts', code, ts.ScriptTarget.Latest, true)
@@ -23,11 +25,7 @@ export function stripEffects(code: string): string {
 export function stripEffectsTransformer(): ts.TransformerFactory<ts.SourceFile> {
     return (context) => (root) => {
         const visit = (node: ts.Node): ts.Node => {
-            if (
-                ts.isCallExpression(node) &&
-                ts.isIdentifier(node.expression) &&
-                node.expression.text === 'effect'
-            ) {
+            if (ts.isCallExpression(node) && isEffectCallee(node.expression)) {
                 return ts.factory.createIdentifier('undefined')
             }
             return ts.visitEachChild(node, visit, context)
@@ -35,3 +33,13 @@ export function stripEffectsTransformer(): ts.TransformerFactory<ts.SourceFile>
         return ts.visitNode(root, visit) as ts.SourceFile
     }
 }
+
+/* An effect callee: the bare runtime helper (`effect`) or the scope-method form
+   (`scope().effect`, `c.effect`) the author writes. Receiver-agnostic on the `.effect`
+   member name, matching `effect` being reserved as a scope primitive. */
+function isEffectCallee(expression: ts.Expression): boolean {
+    if (ts.isIdentifier(expression)) {
+        return expression.text === 'effect'
+    }
+    return ts.isPropertyAccessExpression(expression) && expression.name.text === 'effect'
+}

package/src/lib/ui/compile/structuralBlockTokens.ts

@@ -0,0 +1,101 @@
+import type { SemanticToken } from './types/SemanticToken.ts'
+
+/*
+Lexical highlighting for `{#…}`/`{:…}`/`{/…}` control-flow framing — the part the
+HTML grammar sees only as text and the shadow program lowers away. A pure scan of
+raw source (independent of a successful parse, so it survives mid-edit), it emits
+an `operator` token for the `{`+sigil opener and a `keyword` token for the block
+word, plus the `of`/`by` connectors inside a `{#for …}` head. Expression interiors
+(and the `{@const}`/`{@html}` tags and bare `{expr}` interpolations) are NOT touched
+here — those are the shadow's job. A keyword allowlist after the sigil prevents
+matching arbitrary `{:foo}` text. Longest phrases first so `for await` beats `for`
+and `else if` beats `else`.
+*/
+const BLOCK_KEYWORDS = [
+    'for await',
+    'else if',
+    'if',
+    'for',
+    'await',
+    'switch',
+    'case',
+    'default',
+    'try',
+    'catch',
+    'finally',
+    'then',
+    'else',
+]
+
+const BLOCK_HEAD = new RegExp(`\\{([#:/])\\s*(${BLOCK_KEYWORDS.join('|')})\\b`, 'g')
+
+export function structuralBlockTokens(source: string): SemanticToken[] {
+    const tokens: SemanticToken[] = []
+    for (const match of source.matchAll(BLOCK_HEAD)) {
+        const braceStart = match.index
+        const sigil = match[1]
+        const keyword = match[2]
+        if (keyword === undefined) {
+            continue
+        }
+        const keywordStart = braceStart + match[0].length - keyword.length
+        tokens.push({ start: braceStart, length: 2, type: 'operator', modifiers: [] })
+        tokens.push({ start: keywordStart, length: keyword.length, type: 'keyword', modifiers: [] })
+        /* A `{#for …}` head carries abide-only connectors `of`/`by` that the shadow
+           lowers away (`of`) or never emits (`by`), so color them here. */
+        if (sigil === '#' && (keyword === 'for' || keyword === 'for await')) {
+            tokens.push(...forHeadConnectors(source, keywordStart + keyword.length))
+        }
+    }
+    return tokens
+}
+
+/*
+Scans a `{#for …}` head from `from` to its closing `}`, emitting `keyword` tokens
+for the `of`/`by` connectors at brace depth 0 — skipping any `of`/`by` nested in a
+destructure, call, or string so an identifier or object key is never miscolored.
+*/
+function forHeadConnectors(source: string, from: number): SemanticToken[] {
+    const tokens: SemanticToken[] = []
+    let depth = 0
+    let cursor = from
+    while (cursor < source.length) {
+        const char = source.charAt(cursor)
+        if (char === '"' || char === "'" || char === '`') {
+            cursor += 1
+            while (cursor < source.length && source.charAt(cursor) !== char) {
+                if (source.charAt(cursor) === '\\') {
+                    cursor += 1
+                }
+                cursor += 1
+            }
+        } else if (char === '{' || char === '(' || char === '[') {
+            depth += 1
+        } else if (char === ')' || char === ']') {
+            depth -= 1
+        } else if (char === '}') {
+            if (depth === 0) {
+                break
+            }
+            depth -= 1
+        } else if (depth === 0 && (char === 'o' || char === 'b')) {
+            const word = source.startsWith('of', cursor)
+                ? 'of'
+                : source.startsWith('by', cursor)
+                  ? 'by'
+                  : undefined
+            const isWordBoundary = (offset: number): boolean => /\s/.test(source.charAt(offset))
+            if (
+                word !== undefined &&
+                isWordBoundary(cursor - 1) &&
+                isWordBoundary(cursor + word.length)
+            ) {
+                tokens.push({ start: cursor, length: word.length, type: 'keyword', modifiers: [] })
+                cursor += word.length
+                continue
+            }
+        }
+        cursor += 1
+    }
+    return tokens
+}

package/src/lib/ui/compile/switchPlan.ts

@@ -0,0 +1,22 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+type Case = Extract<TemplateNode, { kind: 'case' }>
+
+/* The structural shape of a `switch`, resolved once so the build and SSR back-ends share one
+   reading of its cases and only own emission. Both previously recomputed the `case` filter;
+   SSR additionally located the match-less default. */
+export type SwitchPlan = {
+    /* The `case` branches in source order (`match` set; the default leaves it unset). */
+    cases: Case[]
+    /* The match-less default branch, if present. */
+    fallback: Case | undefined
+}
+
+/* Resolves a `switch` node's cases into the shared structural plan. */
+export function switchPlan(node: Extract<TemplateNode, { kind: 'switch' }>): SwitchPlan {
+    const cases = node.children.filter((child): child is Case => child.kind === 'case')
+    return {
+        cases,
+        fallback: cases.find((branch) => branch.match === undefined),
+    }
+}

package/src/lib/ui/compile/tryPlan.ts

@@ -0,0 +1,29 @@
+import { resolveBranches } from './resolveBranches.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The structural shape of a `try` error boundary, resolved once so the build and SSR
+   back-ends share one reading and only own emission. Both previously recomputed branch
+   resolution, the `finallyChildren` default, the guarded (children-minus-branch) split, and
+   the catch binding / presence. */
+export type TryPlan = {
+    /* The guarded content — every child except the `catch`/`finally` branch nodes. */
+    guarded: TemplateNode[]
+    /* The catch content + its bound name (`_error` default); empty when no catch branch. */
+    catchChildren: TemplateNode[]
+    catchAs: string
+    finallyChildren: TemplateNode[]
+    /* No catch → a throw propagates to the enclosing boundary (re-throw / `undefined` thunk). */
+    hasCatch: boolean
+}
+
+/* Resolves a `try` node's branches into the shared structural plan. */
+export function tryPlan(node: Extract<TemplateNode, { kind: 'try' }>): TryPlan {
+    const [catchBranch, finallyBranch] = resolveBranches(node, 'catch', 'finally')
+    return {
+        guarded: node.children.filter((child) => child.kind !== 'branch'),
+        catchChildren: catchBranch?.children ?? [],
+        catchAs: catchBranch?.as ?? '_error',
+        finallyChildren: finallyBranch?.children ?? [],
+        hasCatch: catchBranch !== undefined,
+    }
+}

package/src/lib/ui/compile/types/SemanticToken.ts

@@ -0,0 +1,11 @@
+/*
+A semantic-highlighting token in original `.abide` source coordinates. `type` and
+`modifiers` are legend names (see ABIDE_SEMANTIC_TOKENS_LEGEND), resolved to wire
+indices only at encode time.
+*/
+export type SemanticToken = {
+    start: number
+    length: number
+    type: string
+    modifiers: string[]
+}

package/src/lib/ui/compile/types/TemplateAttr.ts

@@ -13,9 +13,15 @@ absolute offset of `code` in the original `.abide` source (see TextPart) —
 optional, set only when the parser tracks positions for the type-checking shadow.
 */
 export type TemplateAttr =
-    | { kind: 'static'; name: string; value: string; bare?: true }
-    | { kind: 'expression'; name: string; code: string; loc?: number }
+    | { kind: 'static'; name: string; value: string; bare?: true; nameLoc?: number }
+    | { kind: 'expression'; name: string; code: string; loc?: number; nameLoc?: number }
     | { kind: 'event'; event: string; code: string; loc?: number }
     | { kind: 'bind'; property: string; code: string; loc?: number }
+    /* `class:<name>={code}` — toggles the class on/off by `code`'s truthiness, written
+       surgically (classList.toggle) without re-rendering the element. */
+    | { kind: 'class'; name: string; code: string; loc?: number }
+    /* `style:<property>={code}` — writes one inline style/custom property (style.setProperty)
+       reactively, again without a re-render. `property` may be a CSS custom prop (`--pct`). */
+    | { kind: 'style'; property: string; code: string; loc?: number }
     | { kind: 'attach'; code: string; loc?: number }
     | { kind: 'spread'; code: string; loc?: number }

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -40,6 +40,11 @@ export type TemplateNode =
           async: boolean
           children: TemplateNode[]
           loc?: number
+          /* Source offsets of the binding name, `by` key, and index — so the shadow
+             maps hover/highlighting onto them (absent for synthesised/missing parts). */
+          asLoc?: number
+          keyLoc?: number
+          indexLoc?: number
       }
     | { kind: 'if'; condition: string; children: TemplateNode[]; loc?: number }
     | {
@@ -52,6 +57,8 @@ export type TemplateNode =
           as: string | undefined
           children: TemplateNode[]
           loc?: number
+          /* Source offset of an inline blocking `then` binding (`{#await p then v}`). */
+          asLoc?: number
       }
     | { kind: 'try'; children: TemplateNode[] }
     | {
@@ -59,13 +66,19 @@ export type TemplateNode =
           branch: 'then' | 'catch' | 'finally'
           as: string | undefined
           children: TemplateNode[]
+          /* Source offset of the `then`/`catch` binding, so the shadow maps it. */
+          asLoc?: number
       }
     | {
           kind: 'component'
           name: string
+          /* Source offset of the tag name — the anchor for a whole-mount diagnostic
+             (a missing required prop, which has no supplied expression to point at). */
+          loc?: number
           /* Each authored attribute as a prop. A `spread` entry (`{...code}`) carries no
-             `name`; its keys merge in at runtime (`mergeProps`/`spreadProps`). */
-          props: { name: string; code: string; loc?: number; spread?: boolean }[]
+             `name`; its keys merge in at runtime (`mergeProps`/`spreadProps`). `nameLoc` is
+             the prop name's source offset — the anchor for an excess-prop diagnostic. */
+          props: { name: string; code: string; loc?: number; nameLoc?: number; spread?: boolean }[]
           children: TemplateNode[]
       }
     | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }

package/src/lib/ui/createScope.ts

@@ -1,4 +1,5 @@
 import { computed } from './computed.ts'
+import { effect } from './effect.ts'
 import { history } from './history.ts'
 import { linked } from './linked.ts'
 import { persist as persistDoc } from './persist.ts'
@@ -37,6 +38,10 @@ export function createScope(
     const data = (): Doc => (document ??= createDoc({}))
     const id = parent === undefined ? `scope-${nextId++}` : `${parent.id}.${nextId++}`
     const children: Scope[] = []
+    /* Adopted build teardowns (the reactivity stopper from the mount core). Disposed
+       first and in reverse on teardown, before children and capabilities — so the one
+       `dispose` runs the order the call sites hand-composed as `stop(); lexical.dispose()`. */
+    const owned: Array<() => void> = []
     /* Context values shared down the tree, held apart from the reactive doc (which
        a child does not inherit): keyed by name, read by the closest ancestor walk. */
     const shared = new Map<string, unknown>()
@@ -56,11 +61,17 @@ export function createScope(
         cell: (path) => data().cell(path),
         derive: (path, compute) => data().derive(path, compute),
         snapshot: () => data().snapshot(),
-        /* The `.value`-cell signal forms, namespaced under the scope — standalone
-           non-serializing cells (owned by the render scope), reached only here. */
+        /* The reactive primitives — namespaced under the scope but AMBIENT-bound, not
+           receiver-bound: each binds whatever scope is rendering and the finest ambient
+           build window (branch/row), so the handle is namespacing, not a binding target.
+           Binding to the receiver would leak branch-local cells (see ADR-0012). */
         state,
         linked,
         computed,
+        effect,
+        own: (dispose) => {
+            owned.push(dispose)
+        },
         child: (childInitial = {}) => {
             const created = createScope(childInitial, self)
             children.push(created)
@@ -91,6 +102,13 @@ export function createScope(
         canUndo: () => past?.canUndo() ?? false,
         canRedo: () => past?.canRedo() ?? false,
         dispose: () => {
+            /* Stop the build's reactivity first (reverse order), before tearing down nested
+               children and the boundary-crossing capabilities — the order the call sites
+               hand-composed as `stop(); lexical.dispose()`. */
+            for (let index = owned.length - 1; index >= 0; index -= 1) {
+                owned[index]?.()
+            }
+            owned.length = 0
             for (const created of children) {
                 created.dispose()
             }

package/src/lib/ui/dom/appendText.ts

@@ -4,6 +4,7 @@ import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { appendSnippet } from './appendSnippet.ts'
+import { isComment } from './isComment.ts'
 import { parseRawNodes } from './parseRawNodes.ts'
 
 const CLOSE = '/abide:html'
@@ -106,8 +107,3 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
         set(markup())
     })
 }
-
-/* A comment node carrying exactly `data`. */
-function isComment(node: Node, data: string): boolean {
-    return (node as { data?: string }).data === data && node.childNodes.length === 0
-}

package/src/lib/ui/dom/applyResolved.ts

@@ -1,4 +1,5 @@
 import { seedResolved } from '../seedResolved.ts'
+import { isComment } from './isComment.ts'
 
 /*
 Bundle-side consumer of an SSR stream chunk, the counterpart of the doc stream's inline
@@ -71,11 +72,6 @@ export function applyResolved(root: Element, frame: string): void {
     }
 }
 
-/* A comment node carrying exactly `data`. */
-function isComment(node: Node, data: string): boolean {
-    return (node as { data?: string }).data === data && node.childNodes.length === 0
-}
-
 /* Depth-first search for the parent + open-marker comment of a boundary. */
 function findBoundary(node: Node, open: string): { parent: Node; start: Node } | undefined {
     for (const child of [...node.childNodes]) {

package/src/lib/ui/dom/disposeRange.ts

@@ -3,18 +3,14 @@ import { clearBetween } from './clearBetween.ts'
 
 /*
 The standard teardown for a marker-bounded range (component, layout/page boundary,
-slot): stop the content's reactivity, dispose its lexical scope, and clear the nodes
-between the markers — leaving the markers in place so a hot swap rebuilds the range.
-Shared by every range mount (`fillRange`, `mountRange`, `fillBoundary`) so the one
-disposer contract lives in a single place.
+slot): dispose its lexical scope (which stops the content's reactivity first, then its
+nested children and capabilities), and clear the nodes between the markers — leaving the
+markers in place so a hot swap rebuilds the range. Shared by every range mount
+(`fillRange`, `mountRange`, `fillBoundary`) so the one disposer contract lives in a
+single place.
 */
-export function disposeRange(
-    scoped: { stop: () => void; lexical: Scope },
-    start: Comment,
-    end: Comment,
-): () => void {
+export function disposeRange(scoped: { lexical: Scope }, start: Comment, end: Comment): () => void {
     return () => {
-        scoped.stop()
         scoped.lexical.dispose()
         clearBetween(start, end)
     }

package/src/lib/ui/dom/hydrate.ts

@@ -29,11 +29,8 @@ export function hydrate(
     try {
         /* Same shared mount core as `mount` (see `withScope`) — a hydrated component owns a
            scope too, adopting the model its build adopts — run with the claim cursor active. */
-        const { stop, lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
-        return () => {
-            stop()
-            lexical.dispose()
-        }
+        const { lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
+        return () => lexical.dispose()
     } finally {
         RENDER.hydration = previous
     }

package/src/lib/ui/dom/isComment.ts

@@ -0,0 +1,6 @@
+/* A comment node carrying exactly `data`. Empty-child check distinguishes the
+   `<!--data-->` marker from an element that happens to expose a `data` property.
+   Shared by the marker-range scanners in appendText/applyResolved. */
+export function isComment(node: Node, data: string): boolean {
+    return (node as { data?: string }).data === data && node.childNodes.length === 0
+}

package/src/lib/ui/dom/mount.ts

@@ -23,9 +23,8 @@ export function mount(
     /* Establish this component's lexical scope (nested, `awaiting` so it adopts the model
        doc the build's first `doc()` creates) and render pass, run the build under it, and
        restore the previous scope — the shared mount core (see `withScope`). */
-    const { stop, lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
+    const { lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
     return () => {
-        stop()
         lexical.dispose()
         host.textContent = ''
     }

package/src/lib/ui/dom/withScope.ts

@@ -11,23 +11,20 @@ under the current one in `awaiting` mode — so it adopts the model doc its firs
 creates — brackets a render pass — so its `await`/`try` block ids draw from the shared
 counter in SSR-stream order — runs `build`, then restores the previous scope (synchronous
 build, so the restore is exact). `build` returns its reactivity stopper (from `scope` or
-`fillBefore`); the caller composes its own DOM teardown (clear host vs clear range) around
-the returned `stop`/`lexical`, keeping the one scope/render-pass contract in a single place.
+`fillBefore`), which the lexical scope ADOPTS (`own`) so the scope has a single teardown:
+the caller wraps its own DOM teardown (clear host vs clear range) around one
+`lexical.dispose()`, no longer composing a separate `stop()` at every site.
 */
-export function withScope(
-    label: string | undefined,
-    build: () => () => void,
-): { stop: () => void; lexical: Scope } {
+export function withScope(label: string | undefined, build: () => () => void): { lexical: Scope } {
     const parentScope = CURRENT_SCOPE.current
     const lexical = createScope({}, parentScope, true, label)
     enterRenderPass()
     CURRENT_SCOPE.current = lexical
-    let stop: () => void = () => undefined
     try {
-        stop = build()
+        lexical.own(build())
     } finally {
         exitRenderPass()
         CURRENT_SCOPE.current = parentScope
     }
-    return { stop, lexical }
+    return { lexical }
 }

package/src/lib/ui/effect.ts

@@ -10,9 +10,11 @@ dispose — and may be async (its teardown then runs once the promise settles, b
 only the reads before its first `await` are tracked). Returns a dispose that runs
 the final teardown and detaches it from the graph. This is abide's from-scratch
 effect primitive: the open-on-first-read / close-on-last-reader lifecycle,
-grounded in abide's own reactive core.
+grounded in abide's own reactive core. Authored as `scope().effect(...)` (the bare
+name is reserved); this module export stays for the generated binding code that
+calls it directly (and for the SSR strip), so it carries no standalone demo.
 */
-// @documentation effect
+// @documentation plumbing
 export function effect(fn: () => EffectResult): () => void {
     /* Re-runs fire after the build, so pin the scope this effect was created under
        (the dep-tracking observer is managed separately, so this can't disturb it). */

package/src/lib/ui/navigate.ts

@@ -1,3 +1,6 @@
+import { parseRouteSegments } from '../shared/parseRouteSegments.ts'
+import type { PageRoutes, PathParams } from '../shared/url.ts'
+import { url } from '../shared/url.ts'
 import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 
@@ -8,21 +11,19 @@ export type NavigateOptions = {
     keepScroll?: boolean
 }
 
-/* Navigates to `path`: writes a history entry (when available) and updates the
-   reactive route, which re-mounts the matching page via `router`. `replace` swaps
-   the current entry instead of pushing — used when honouring a server redirect, so
-   the blocked URL isn't left behind in history. Each entry carries a monotonic
-   `abideEntry` id so the router can bucket/restore its scroll offset across the page
-   teardown the rebuild does. A push leaves the current entry behind — its scroll is
-   bucketed so back restores it — and mints a fresh id. A replace destroys the current
-   entry and lands fresh content (a redirect), so its saved scroll no longer applies:
+/* Writes an ALREADY-RESOLVED path into history + the reactive route. The router uses this
+   for paths it built from a real URL (a clicked link, a popstate, a server redirect) — they
+   already carry the mount base, so they must NOT pass through `url()` again. Each entry
+   carries a monotonic `abideEntry` id so the router can bucket/restore its scroll offset
+   across the page teardown the rebuild does. A push leaves the current entry behind — its
+   scroll is bucketed so back restores it — and mints a fresh id. A replace destroys the
+   current entry and lands fresh content (a redirect), so its saved scroll no longer applies:
    the bucket is discarded and the id kept, so the new page restores to top/anchor.
    `keepScroll` opts the destination out of that reset — for an in-page URL swap (e.g.
-   selecting another episode on the same detail page) where a top jump is jarring: the
-   live offset is bucketed under the destination entry id, so the post-rebuild `restore`
-   reapplies it instead of scrolling to top. */
-// @documentation navigate
-export function navigate(
+   selecting another episode on the same detail page) where a top jump is jarring: the live
+   offset is bucketed under the destination entry id, so the post-rebuild `restore` reapplies
+   it instead of scrolling to top. */
+export function navigatePath(
     path: string,
     { replace = false, keepScroll = false }: NavigateOptions = {},
 ): void {
@@ -48,3 +49,29 @@ export function navigate(
     }
     runtimePath.value = path
 }
+
+/* Navigates to a typed in-app path: a route literal with `[name]` segments takes its params
+   first (`navigate('/p/[id]', { id })`), then options; a paramless or already-interpolated
+   path takes options directly (`navigate('/p', { replace })`). The path is built through
+   `url()` — base-correct, params interpolated — exactly as a link href would be, so a
+   dynamic `/p/${x}` falls through url()'s paramless branch and is base-prefixed too. */
+// @documentation navigate
+export function navigate<P extends keyof PageRoutes | (string & {})>(
+    path: P,
+    ...rest: keyof PathParams<P> extends never
+        ? [options?: NavigateOptions]
+        : [params: PathParams<P>, options?: NavigateOptions]
+): void {
+    /* A path declaring `[name]` segments takes params first, options second — mirroring
+       url()'s own arg discrimination; otherwise the first arg is options. */
+    const hasParams = parseRouteSegments(path).some((segment) => segment.kind === 'param')
+    const [first, second] = rest as [unknown, NavigateOptions?]
+    /* Params ride url()'s first vararg slot — a path with `[name]` segments interpolates
+       them, a paramless one ignores undefined and just base-prefixes. Widen `path` to
+       string so url() takes its plain-path overload; its runtime keys off the segments. */
+    const params = hasParams
+        ? (first as Record<string, string | number | boolean | undefined>)
+        : undefined
+    const options = (hasParams ? second : (first as NavigateOptions | undefined)) ?? {}
+    navigatePath(url(path as string, params), options)
+}