@pithyjs/router 0.1.0-beta.0

package/dist/router/features/ux/transitions.d.ts

@@ -0,0 +1,120 @@
+/** @codex
+{
+  "id": "pithy.router.view-transitions",
+  "title": "View Transitions API Integration",
+  "category": "runtime"
+}
+*/
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"ViewTransitionPreset","stability":"experimental","signature":"type ViewTransitionPreset"} */
+/**
+ * Built-in transition presets
+ * These transitions work globally without requiring additional parameters.
+ */
+export type ViewTransitionPreset = 'slide' | 'fade' | 'none';
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"ViewTransitionType","stability":"experimental","signature":"type ViewTransitionType"} */
+/**
+ * View transition types
+ * Includes built-in presets plus 'custom' for element-specific transitions.
+ * The 'custom' type requires a transition name via data-transition-name attribute.
+ */
+export type ViewTransitionType = ViewTransitionPreset | 'custom';
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"ViewTransitionConfig","stability":"experimental","signature":"interface ViewTransitionConfig"} */
+/**
+ * View transition configuration
+ * Controls global view transition behavior for the router.
+ * Browser support required: Chrome 111+, Edge 111+
+ */
+export interface ViewTransitionConfig {
+    /** Whether to enable view transitions */
+    enabled?: boolean;
+    /** Default transition preset (cannot be 'custom' as it requires a name parameter) */
+    defaultTransition?: ViewTransitionPreset;
+    /** Custom transition duration (ms) */
+    duration?: number;
+    /** Easing function for transitions */
+    easing?: string;
+}
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"ViewTransitionOptions","stability":"experimental","signature":"interface ViewTransitionOptions"} */
+/**
+ * View transition options for individual navigations
+ * Allows per-navigation customization of transition behavior.
+ */
+export interface ViewTransitionOptions {
+    /** Transition type to use */
+    type?: ViewTransitionType | undefined;
+    /** Whether to skip transition for this navigation */
+    skipTransition?: boolean | undefined;
+    /** Custom transition name */
+    name?: string | undefined;
+}
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"ViewTransitionManager","stability":"experimental","signature":"class ViewTransitionManager"} */
+/**
+ * View transition manager for enhanced navigation UX
+ * Integrates the browser's View Transitions API for smooth route changes.
+ * Provides slide, fade, and custom animations with graceful fallback for unsupported browsers.
+ */
+export declare class ViewTransitionManager {
+    private config;
+    constructor(config?: ViewTransitionConfig);
+    /**
+     * Check if View Transitions API is supported (dynamic check for testing)
+     */
+    private isSupported;
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"isAvailable","stability":"experimental","signature":"() => boolean"} */
+    /**
+     * Check if view transitions are supported and enabled
+     * Returns true only if both browser support exists AND transitions are enabled in config.
+     */
+    isAvailable(): boolean;
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"executeTransition","stability":"experimental","signature":"<T>(updateCallback: () => Promise<T> | T, options?: ViewTransitionOptions) => Promise<T>"} */
+    /**
+     * Execute a view transition for navigation
+     * Wraps the DOM update callback with View Transitions API animation.
+     * Gracefully falls back to immediate execution if unsupported or disabled.
+     */
+    executeTransition<T>(updateCallback: () => Promise<T> | T, options?: ViewTransitionOptions): Promise<T>;
+    /**
+     * Apply custom transition styles
+     */
+    private applyTransitionStyles;
+    /**
+     * Clear transition styles
+     */
+    private clearTransitionStyles;
+    /**
+     * Get transition options from element attributes
+     * Reads data-transition and data-transition-name attributes to configure transitions.
+     * If no element is provided, returns default transition options from config.
+     * @internal Used internally by the router during navigation
+     */
+    getTransitionOptionsFromElement(element?: Element | null): ViewTransitionOptions | null;
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"updateConfig","stability":"experimental","signature":"(config: Partial<ViewTransitionConfig>) => void"} */
+    /**
+     * Update configuration
+     * Allows runtime configuration changes for view transitions.
+     */
+    updateConfig(config: Partial<ViewTransitionConfig>): void;
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"cleanup","stability":"experimental","signature":"() => void"} */
+    /**
+     * Cleanup transition styles and resources
+     * Removes injected transition styles from the document.
+     */
+    cleanup(): void;
+}
+/**
+ * Global view transition manager instance
+ * Singleton instance used by the router for view transition management.
+ * @internal Used internally by the router; users should configure via RouterConfig
+ */
+export declare const viewTransitionManager: ViewTransitionManager;
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"useViewTransitions","stability":"experimental","signature":"(config?: ViewTransitionConfig) => ViewTransitionManager"} */
+/**
+ * View transition utilities
+ */
+export declare function useViewTransitions(config?: ViewTransitionConfig): ViewTransitionManager;
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"supportsViewTransitions","stability":"stable","signature":"() => boolean"} */
+/**
+ * Check if view transitions are supported in the current environment
+ */
+export declare function supportsViewTransitions(): boolean;
+//# sourceMappingURL=transitions.d.ts.map

package/dist/router/features/ux/transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../../../../src/router/features/ux/transitions.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,4JAA4J;AAC5J;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D,wJAAwJ;AACxJ;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,GAAG,QAAQ,CAAC;AAEjE,iKAAiK;AACjK;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,oBAAoB,CAAC;IACzC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mKAAmK;AACnK;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACtC,qDAAqD;IACrD,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,+JAA+J;AAC/J;;;;GAIG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAiC;gBAEnC,MAAM,GAAE,oBAAyB;IAU7C;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB,uIAAuI;IACvI;;;OAGG;IACH,WAAW,IAAI,OAAO;IAItB,wNAAwN;IACxN;;;;OAIG;IACG,iBAAiB,CAAC,CAAC,EACvB,cAAc,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACpC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,CAAC,CAAC;IA+Cb;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA4E7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;OAKG;IACH,+BAA+B,CAC7B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,qBAAqB,GAAG,IAAI;IA4B/B,0KAA0K;IAC1K;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IAIzD,gIAAgI;IAChI;;;OAGG;IACH,OAAO,IAAI,IAAI;CAGhB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,uBAA8B,CAAC;AAEjE,yLAAyL;AACzL;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,qBAAqB,CAKvB;AAED,6IAA6I;AAC7I;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}

package/dist/router/features/ux/transitions.js

@@ -0,0 +1,235 @@
+/** @codex
+{
+  "id": "pithy.router.view-transitions",
+  "title": "View Transitions API Integration",
+  "category": "runtime"
+}
+*/
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"ViewTransitionManager","stability":"experimental","signature":"class ViewTransitionManager"} */
+/**
+ * View transition manager for enhanced navigation UX
+ * Integrates the browser's View Transitions API for smooth route changes.
+ * Provides slide, fade, and custom animations with graceful fallback for unsupported browsers.
+ */
+export class ViewTransitionManager {
+    constructor(config = {}) {
+        this.config = {
+            enabled: true,
+            defaultTransition: 'fade',
+            duration: 400,
+            easing: 'ease-in-out',
+            ...config,
+        };
+    }
+    /**
+     * Check if View Transitions API is supported (dynamic check for testing)
+     */
+    isSupported() {
+        return typeof document !== 'undefined' && 'startViewTransition' in document;
+    }
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"isAvailable","stability":"experimental","signature":"() => boolean"} */
+    /**
+     * Check if view transitions are supported and enabled
+     * Returns true only if both browser support exists AND transitions are enabled in config.
+     */
+    isAvailable() {
+        return this.isSupported() && this.config.enabled;
+    }
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"executeTransition","stability":"experimental","signature":"<T>(updateCallback: () => Promise<T> | T, options?: ViewTransitionOptions) => Promise<T>"} */
+    /**
+     * Execute a view transition for navigation
+     * Wraps the DOM update callback with View Transitions API animation.
+     * Gracefully falls back to immediate execution if unsupported or disabled.
+     */
+    async executeTransition(updateCallback, options) {
+        // If transitions are not available or disabled, just run the callback
+        if (!this.isAvailable() || options?.skipTransition) {
+            return await updateCallback();
+        }
+        // Apply custom transition styles BEFORE starting transition
+        if (options?.type && options.type !== 'none') {
+            this.applyTransitionStyles(options.type, options.name);
+        }
+        // Use the native View Transitions API
+        if (document.startViewTransition) {
+            return await new Promise((resolve, reject) => {
+                const transition = document.startViewTransition(async () => {
+                    try {
+                        const result = await updateCallback();
+                        return result;
+                    }
+                    catch (error) {
+                        reject(error);
+                        throw error;
+                    }
+                });
+                // Handle transition completion
+                transition.finished
+                    .then(() => {
+                    // Transition completed successfully
+                })
+                    .catch(error => {
+                    console.warn('View transition failed:', error);
+                    // Continue with the result even if transition failed
+                });
+                // The result will be available when the callback completes
+                transition.ready
+                    .then(result => {
+                    resolve(result);
+                })
+                    .catch(reject);
+            });
+        }
+        // Fallback for browsers without View Transitions API
+        return await updateCallback();
+    }
+    /**
+     * Apply custom transition styles
+     */
+    applyTransitionStyles(type, name) {
+        if (typeof document === 'undefined')
+            return;
+        // Remove existing transition styles
+        this.clearTransitionStyles();
+        const style = document.createElement('style');
+        style.id = 'pithy-view-transition-styles';
+        let css = '';
+        switch (type) {
+            case 'slide':
+                css = `
+          ::view-transition-old(root) {
+            animation: slide-out ${this.config.duration}ms ${this.config.easing} both;
+          }
+          ::view-transition-new(root) {
+            animation: slide-in ${this.config.duration}ms ${this.config.easing} both;
+          }
+          @keyframes slide-out {
+            from { transform: translateX(0); }
+            to { transform: translateX(-100%); }
+          }
+          @keyframes slide-in {
+            from { transform: translateX(100%); }
+            to { transform: translateX(0); }
+          }
+        `;
+                break;
+            case 'fade':
+                css = `
+          ::view-transition-old(root) {
+            animation: fade-out ${this.config.duration}ms ${this.config.easing} both;
+          }
+          ::view-transition-new(root) {
+            animation: fade-in ${this.config.duration}ms ${this.config.easing} both;
+          }
+          @keyframes fade-out {
+            from { opacity: 1; }
+            to { opacity: 0; }
+          }
+          @keyframes fade-in {
+            from { opacity: 0; }
+            to { opacity: 1; }
+          }
+        `;
+                break;
+            case 'custom':
+                if (name) {
+                    css = `
+            ::view-transition-old(${name}) {
+              animation: custom-out ${this.config.duration}ms ${this.config.easing} both;
+            }
+            ::view-transition-new(${name}) {
+              animation: custom-in ${this.config.duration}ms ${this.config.easing} both;
+            }
+            @keyframes custom-out {
+              from { opacity: 1; transform: scale(1); }
+              to { opacity: 0.8; transform: scale(0.95); }
+            }
+            @keyframes custom-in {
+              from { opacity: 0.8; transform: scale(0.95); }
+              to { opacity: 1; transform: scale(1); }
+            }
+          `;
+                }
+                break;
+        }
+        style.textContent = css;
+        document.head.appendChild(style);
+    }
+    /**
+     * Clear transition styles
+     */
+    clearTransitionStyles() {
+        if (typeof document === 'undefined')
+            return;
+        const existingStyle = document.getElementById('pithy-view-transition-styles');
+        if (existingStyle) {
+            existingStyle.remove();
+        }
+    }
+    /**
+     * Get transition options from element attributes
+     * Reads data-transition and data-transition-name attributes to configure transitions.
+     * If no element is provided, returns default transition options from config.
+     * @internal Used internally by the router during navigation
+     */
+    getTransitionOptionsFromElement(element) {
+        // If no element provided, use default transition from config
+        if (!element) {
+            return {
+                type: this.config.defaultTransition,
+                name: undefined,
+            };
+        }
+        const skipTransition = element.hasAttribute('data-no-transition') ||
+            element.closest('[data-no-transition]') !== null;
+        if (skipTransition) {
+            return { skipTransition: true };
+        }
+        const transitionType = element.getAttribute('data-transition');
+        const transitionName = element.getAttribute('data-transition-name');
+        return {
+            type: transitionType || this.config.defaultTransition,
+            name: transitionName || undefined,
+        };
+    }
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"updateConfig","stability":"experimental","signature":"(config: Partial<ViewTransitionConfig>) => void"} */
+    /**
+     * Update configuration
+     * Allows runtime configuration changes for view transitions.
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /** @codexApi {"parent":"pithy.router.view-transitions","name":"cleanup","stability":"experimental","signature":"() => void"} */
+    /**
+     * Cleanup transition styles and resources
+     * Removes injected transition styles from the document.
+     */
+    cleanup() {
+        this.clearTransitionStyles();
+    }
+}
+/**
+ * Global view transition manager instance
+ * Singleton instance used by the router for view transition management.
+ * @internal Used internally by the router; users should configure via RouterConfig
+ */
+export const viewTransitionManager = new ViewTransitionManager();
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"useViewTransitions","stability":"experimental","signature":"(config?: ViewTransitionConfig) => ViewTransitionManager"} */
+/**
+ * View transition utilities
+ */
+export function useViewTransitions(config) {
+    if (config) {
+        viewTransitionManager.updateConfig(config);
+    }
+    return viewTransitionManager;
+}
+/** @codexApi {"parent":"pithy.router.view-transitions","name":"supportsViewTransitions","stability":"stable","signature":"() => boolean"} */
+/**
+ * Check if view transitions are supported in the current environment
+ */
+export function supportsViewTransitions() {
+    return typeof document !== 'undefined' && 'startViewTransition' in document;
+}
+//# sourceMappingURL=transitions.js.map

package/dist/router/features/ux/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../../../src/router/features/ux/transitions.ts"],"names":[],"mappings":"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"}

package/dist/router/integration/directive-binder.d.ts

@@ -0,0 +1,20 @@
+/** @codex
+{
+  "id": "pithy.router.directive-binding",
+  "title": "Router Directive Binding System",
+  "category": "runtime"
+}
+*/
+import type { Router } from '../core/router';
+/** @codexApi {"parent":"pithy.router.directive-binding","name":"setGlobalRouter","stability":"stable","signature":"(router: Router) => void"} */
+/**
+ * Set the global router instance for directive binding.
+ * Also registers the directive binder with core and scans for unbound links.
+ */
+export declare function setGlobalRouter(router: Router): void;
+/** @codexApi {"parent":"pithy.router.directive-binding","name":"getGlobalRouter","stability":"stable","signature":"() => Router | null"} */
+/**
+ * Get the global router instance
+ */
+export declare function getGlobalRouter(): Router | null;
+//# sourceMappingURL=directive-binder.d.ts.map

package/dist/router/integration/directive-binder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-binder.d.ts","sourceRoot":"","sources":["../../../src/router/integration/directive-binder.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAiBF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AA8I7C,iJAAiJ;AACjJ;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASpD;AAED,4IAA4I;AAC5I;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C"}

package/dist/router/integration/directive-binder.js

@@ -0,0 +1,139 @@
+/** @codex
+{
+  "id": "pithy.router.directive-binding",
+  "title": "Router Directive Binding System",
+  "category": "runtime"
+}
+*/
+/**
+ * Router Directive Binder
+ *
+ * Handles binding of router directives (@routerOutlet, @routerLink) in templates.
+ * Registers with core's directive registry to integrate with template compilation.
+ *
+ * @module router/integration/directive-binder
+ */
+import { registerDirectiveBinder } from '@pithyjs/core';
+import { routerLink, routerOutlet } from './directives';
+import { PREFETCH_STRATEGIES, } from '../features/prefetch';
+function resolvePrefetchAttr(value) {
+    if (value === null)
+        return 'none';
+    if (PREFETCH_STRATEGIES.includes(value)) {
+        return value;
+    }
+    if (import.meta.env?.DEV) {
+        console.warn(`[@routerLink] invalid data-prefetch="${value}" — expected one of ${PREFETCH_STRATEGIES.join(', ')}; falling back to "none".`);
+    }
+    return 'none';
+}
+/**
+ * Global router instance - will be set by the router when it mounts
+ */
+let globalRouter = null;
+/**
+ * Bind existing router links that were rendered before the router was available
+ * Looks for @routerLink elements that don't have cleanup functions attached yet
+ */
+function bindExistingRouterLinks(router) {
+    const unboundLinks = document.querySelectorAll('a[data-router-link]:not([data-router-bound])');
+    unboundLinks.forEach(el => {
+        const element = el;
+        // Mark as bound to avoid double-binding
+        element.setAttribute('data-router-bound', 'true');
+        const prefetchStrategy = resolvePrefetchAttr(element.getAttribute('data-prefetch'));
+        // Extract other router link options
+        const activeClass = element.getAttribute('active-class') || 'router-link-active';
+        const exactMatch = element.hasAttribute('exact-match');
+        const replace = element.hasAttribute('replace');
+        const options = {
+            activeClass,
+            exactMatch,
+            prefetch: prefetchStrategy,
+            replace,
+        };
+        routerLink(element, router, options);
+    });
+}
+/**
+ * Binds router directives (@routerOutlet, @routerLink) within the DOM tree
+ * This integrates the router directives into the core template compilation system
+ */
+const bindRouterDirectives = (root, _context, disposers) => {
+    if (!globalRouter) {
+        // Router not yet initialized, skip binding
+        return;
+    }
+    // Type narrowing: router is non-null after the check above
+    const router = globalRouter;
+    // Find all elements with router directives
+    const elements = root.querySelectorAll('*');
+    elements.forEach(el => {
+        const element = el;
+        // Handle @routerOutlet directive
+        if (element.hasAttribute('data-router-outlet')) {
+            routerOutlet(element, router);
+            // Add cleanup
+            disposers.push(() => {
+                const target = element;
+                const cleanup = target.__routerOutletCleanup;
+                if (cleanup) {
+                    cleanup();
+                    delete target.__routerOutletCleanup;
+                }
+            });
+        }
+        // Handle @routerLink directive
+        if (element.hasAttribute('data-router-link') && element.tagName === 'A') {
+            const anchorElement = element;
+            // Skip if already bound (to avoid double-binding)
+            if (anchorElement.hasAttribute('data-router-bound')) {
+                return;
+            }
+            // Mark as bound to avoid double-binding
+            anchorElement.setAttribute('data-router-bound', 'true');
+            const prefetchStrategy = resolvePrefetchAttr(element.getAttribute('data-prefetch'));
+            // Extract other router link options
+            const activeClass = element.getAttribute('active-class') || 'router-link-active';
+            const exactMatch = element.hasAttribute('exact-match');
+            const replace = element.hasAttribute('replace');
+            const options = {
+                activeClass,
+                exactMatch,
+                prefetch: prefetchStrategy,
+                replace,
+            };
+            routerLink(anchorElement, router, options);
+            // Add cleanup
+            disposers.push(() => {
+                const target = anchorElement;
+                const cleanup = target.__routerLinkCleanup;
+                if (cleanup) {
+                    cleanup();
+                    delete target.__routerLinkCleanup;
+                }
+            });
+        }
+    });
+};
+/** @codexApi {"parent":"pithy.router.directive-binding","name":"setGlobalRouter","stability":"stable","signature":"(router: Router) => void"} */
+/**
+ * Set the global router instance for directive binding.
+ * Also registers the directive binder with core and scans for unbound links.
+ */
+export function setGlobalRouter(router) {
+    globalRouter = router;
+    // Register our directive binder with core (idempotent - won't double-register)
+    registerDirectiveBinder(bindRouterDirectives);
+    // Scan the DOM for any unbound router links and bind them
+    // This handles the case where links were rendered before the router was mounted
+    bindExistingRouterLinks(router);
+}
+/** @codexApi {"parent":"pithy.router.directive-binding","name":"getGlobalRouter","stability":"stable","signature":"() => Router | null"} */
+/**
+ * Get the global router instance
+ */
+export function getGlobalRouter() {
+    return globalRouter;
+}
+//# sourceMappingURL=directive-binder.js.map

package/dist/router/integration/directive-binder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-binder.js","sourceRoot":"","sources":["../../../src/router/integration/directive-binder.ts"],"names":[],"mappings":"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"}

package/dist/router/integration/directives.d.ts

@@ -0,0 +1,42 @@
+/** @codex
+{
+  "id": "pithy.router.directives",
+  "title": "Router Directives (@routerOutlet, @routerLink)",
+  "category": "directive"
+}
+*/
+import type { Router } from '../core/router';
+import { type PrefetchStrategy } from '../features/prefetch';
+/** @codexApi {"parent":"pithy.router.directives","name":"routerOutlet","stability":"experimental","signature":"(element: HTMLElement, router: Router) => void"} */
+/**
+ * Router outlet directive - marks where child routes should be rendered
+ *
+ * NOTE: This directive only marks the outlet element. The actual route component
+ * rendering is handled by OutletManager.mountSegments() when router.mount() is called.
+ */
+export declare function routerOutlet(element: HTMLElement, _router: Router): void;
+/** @codexApi {"parent":"pithy.router.directives","name":"routerLink","stability":"stable","signature":"(element: HTMLAnchorElement, router: Router, options?: RouterLinkOptions) => void"} */
+/**
+ * Router link directive - enhances anchor tags with client-side navigation
+ * Fixed to prevent URL changes when guards deny navigation
+ */
+export declare function routerLink(element: HTMLAnchorElement, router: Router, options?: RouterLinkOptions): void;
+/**
+ * Router link options
+ */
+export interface RouterLinkOptions {
+    /** CSS class to apply when link is active */
+    activeClass?: string;
+    /** Whether to match the exact path or allow partial matches */
+    exactMatch?: boolean;
+    /** Prefetch strategy */
+    prefetch?: PrefetchStrategy;
+    /** Replace current history entry instead of pushing a new one */
+    replace?: boolean;
+}
+/** @codexApi {"parent":"pithy.router.directives","name":"cleanupRouterDirectives","stability":"experimental","signature":"(element: HTMLElement) => void"} */
+/**
+ * Cleanup router directive subscriptions
+ */
+export declare function cleanupRouterDirectives(element: HTMLElement): void;
+//# sourceMappingURL=directives.d.ts.map

package/dist/router/integration/directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../../src/router/integration/directives.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAG9B,mKAAmK;AACnK;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAUxE;AAED,8LAA8L;AAC9L;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,IAAI,CAsEN;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,8JAA8J;AAC9J;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAuBlE"}