@preact-mvc/core 0.1.2 → 0.1.4

package/dist/decorators.d.ts

@@ -1,4 +1,14 @@
 import type { Provider, Type } from './injector';
+/** A class's own decorator metadata — never the inherited static chain. */
+export declare function ownMeta<T>(target: any, key: string): T | undefined;
+/** Identity stamp: a subclass of a @Controller stays a controller. */
+export declare function isController(t: any): boolean;
+/** Injectable metadata — reads the chain on purpose (providedIn inherits). */
+export declare function getInjectableMeta(t: any): InjectableMeta | undefined;
+/** Identity read: the class carries @Injectable metadata. */
+export declare function isInjectable(t: any): boolean;
+/** Component metadata — own-class only; a subclass re-declares its own. */
+export declare function getComponentMeta(t: any): ComponentMeta | undefined;
 export interface InjectableMeta {
     providedIn?: 'root';
 }

package/dist/decorators.js

@@ -1,3 +1,41 @@
+// Decorators attach metadata to the class constructor. They work with
+// experimentalDecorators (esbuild honors the tsconfig flag) and can also be
+// invoked manually: `Module({ ... })(MyModule)`.
+//
+// Two stamp families:
+//   identity (__view, __controller) — booleans answering "is this class a
+//     kind of thing"; they inherit through the constructor chain, so a
+//     subclass keeps the kind.
+//   config (__module, __component, __injectable) — metadata describing one
+//     class; readers use ownMeta so a subclass never borrows its parent's
+//     config (Angular's rule: @NgModule/@Component metadata does not
+//     inherit). __injectable is the exception at read time: the injector
+//     resolves providedIn through the chain, matching Angular's ɵprov.
+/** A class's own decorator metadata — never the inherited static chain. */
+export function ownMeta(target, key) {
+    return target != null && Object.prototype.hasOwnProperty.call(target, key)
+        ? target[key]
+        : undefined;
+}
+// --- Flag accessors -----------------------------------------------------------
+// The read surface for the stamps below. Callers go through these instead of
+// touching `__x` properties, so the own-vs-inherited rules live in one place.
+/** Identity stamp: a subclass of a @Controller stays a controller. */
+export function isController(t) {
+    return typeof t === 'function' && !!t.__controller;
+}
+/** Injectable metadata — reads the chain on purpose (providedIn inherits). */
+export function getInjectableMeta(t) {
+    return t?.__injectable;
+}
+/** Identity read: the class carries @Injectable metadata. */
+export function isInjectable(t) {
+    return getInjectableMeta(t) != null;
+}
+/** Component metadata — own-class only; a subclass re-declares its own. */
+export function getComponentMeta(t) {
+    return ownMeta(t, '__component');
+}
 export function Injectable(meta = {}) {
     return function (target) {
         target.__injectable = meta;

package/dist/index.d.ts

@@ -5,9 +5,12 @@ export type { Provider, Token, Type } from './injector';
 export { Injectable, Controller, Module, Component } from './decorators';
 export type { InjectableMeta, ModuleMeta, ComponentMeta } from './decorators';
 export { View, installViewInterop } from './view';
-export { bootstrap, createModuleInjector, getModuleInjector, getModuleMeta } from './module';
+export { bootstrap, createModuleInjector, getModuleInjector } from './module';
+export { pmvc } from './pmvc';
 export { InjectorContext, useInjector, useService, Provide } from './context';
 export { useController } from './controller';
 export type { OnInit, OnDestroy } from './controller';
+export { lazyView, lazyModule } from './lazy';
+export type { LazyResource, LazyResourceState } from './lazy';
 export { Router, ROUTES, ROUTER_BASE, RouterModule, RouterOutlet, Link, defaultBasePath } from './router';
 export type { Route, RouteMatch, RouterOptions } from './router';

package/dist/index.js

@@ -7,9 +7,13 @@ export { Injectable, Controller, Module, Component } from './decorators';
 // Class-based views
 export { View, installViewInterop } from './view';
 // Modules & bootstrap
-export { bootstrap, createModuleInjector, getModuleInjector, getModuleMeta } from './module';
+export { bootstrap, createModuleInjector, getModuleInjector } from './module';
+// Class-flag utilities — pmvc.isView(x), pmvc.isController(x), ...
+export { pmvc } from './pmvc';
 // View integration
 export { InjectorContext, useInjector, useService, Provide } from './context';
 export { useController } from './controller';
+// Lazy loading — usable in route configs and straight in JSX
+export { lazyView, lazyModule } from './lazy';
 // Router
 export { Router, ROUTES, ROUTER_BASE, RouterModule, RouterOutlet, Link, defaultBasePath } from './router';

package/dist/injector.js

@@ -1,3 +1,4 @@
+import { isController, getInjectableMeta } from './decorators';
 export class InjectionToken {
     constructor(_desc) {
         this._desc = _desc;
@@ -116,7 +117,7 @@ export class Injector {
     has(token) {
         if (this.records.has(token))
             return true;
-        if (token.__controller)
+        if (isController(token))
             return true;
         if (this.parent)
             return this.parent.has(token);
@@ -135,7 +136,7 @@ export class Injector {
         }
         // Controllers are transient unless explicitly provided: one instance per
         // requesting scope, so a view always gets its own controller.
-        if (token.__controller) {
+        if (isController(token)) {
             this.provide(token);
             return this.resolveRecord(token, this.records.get(token));
         }
@@ -165,8 +166,7 @@ export class Injector {
         return rec.value;
     }
     isRootProvided(token) {
-        const meta = token.__injectable;
-        return meta?.providedIn === 'root';
+        return getInjectableMeta(token)?.providedIn === 'root';
     }
     instantiate(cls, ...args) {
         const inst = runInInjectionContext(this, () => new cls(...args));

package/dist/lazy.d.ts

@@ -0,0 +1,50 @@
+import type { FunctionComponent } from 'preact';
+export type LazyResourceState<R> = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    value: R;
+} | {
+    status: 'error';
+    error: unknown;
+};
+/**
+ * A deferred loader. `.state` reads kick the import on first access and
+ * subscribe the reader (a component render or a computed); `.ready` is the
+ * same resolution as a promise.
+ */
+export interface LazyResource<R> {
+    readonly state: LazyResourceState<R>;
+    readonly ready: Promise<R>;
+}
+export declare function isComponent(v: any): boolean;
+export declare function pickComponent(ns: any, label: string): any;
+export declare function pickLazyFeature(ns: any, label: string): any;
+export declare function pickModule(ns: any, label: string): any;
+/**
+ * `lazyView(() => import('./hello.view'))` — a lazy standalone component.
+ * Usable as a Route `component` or directly in JSX: the facade suspends on
+ * the import, then mounts the resolved view with the same props.
+ */
+export declare function lazyView(load: () => Promise<any>): FunctionComponent<any>;
+/**
+ * `lazyModule(() => import('./admin.module'))` — a lazy feature module.
+ * Usable as a Route `module` (the outlet resolves the real module and its
+ * injector) or `component`, or directly in JSX: mounts the module's
+ * bootstrap view inside the module injector once the chunk lands.
+ */
+export declare function lazyModule(load: () => Promise<any>): FunctionComponent<any>;
+/**
+ * Read a lazyView/lazyModule facade's resource state — kicks the loader on
+ * first read and subscribes the reader (outlet render, router.pending
+ * computed). Non-facade values answer null.
+ */
+export declare function lazyStateOf(v: any): LazyResourceState<any> | null;
+/**
+ * Sync unwrap for the Route `module` field: a lazyModule facade answers
+ * with the resolved module class once loaded (undefined while pending or
+ * after a failure). Reading the resource state subscribes the caller.
+ */
+export declare function moduleRefOf(m: any): any;
+/** Async unwrap — awaits the ref's own resolution (kicking it if needed). */
+export declare function lazyModuleReady(m: any): Promise<any> | null;

package/dist/lazy.js

@@ -0,0 +1,148 @@
+import { Fragment as _Fragment, jsx as _jsx } from "preact/jsx-runtime";
+import { h } from 'preact';
+import { signal } from '@preact/signals';
+import { InjectorContext, useInjector } from './context';
+import { getModuleInjector, getModuleMeta } from './module';
+import { isView } from './view';
+function lazyResource(run, label) {
+    let s;
+    let promise;
+    const start = () => {
+        if (!s) {
+            s = signal({ status: 'loading' });
+            promise = run().then((value) => {
+                s.value = { status: 'ready', value };
+                return value;
+            }, (error) => {
+                console.error(`[framework] ${label} failed to load:`, error);
+                s.value = { status: 'error', error };
+                throw error;
+            });
+            // The state object carries failures to renderers; keep the promise
+            // from also reporting an unhandled rejection.
+            promise.catch(() => { });
+        }
+        return { s: s, promise: promise };
+    };
+    return {
+        get state() {
+            return start().s.value;
+        },
+        get ready() {
+            return start().promise;
+        },
+    };
+}
+// --- Export pickers ---------------------------------------------------------
+// A lazy import resolves to: the ES module namespace ({ default: X, Y }),
+// a value picked by .then(m => m.X), or a bare Route[]. Candidates are
+// ordered default-first so `export default` always wins.
+function exportCandidates(ns) {
+    if (Array.isArray(ns) || typeof ns !== 'object' || ns === null)
+        return [ns];
+    return 'default' in ns ? [ns.default, ...Object.values(ns)] : Object.values(ns);
+}
+export function isComponent(v) {
+    // Detection is an is-a question, so these read the chain: a subclass of a
+    // stamped component is still renderable (config reads stay own-only).
+    return (typeof v === 'function' &&
+        (isView(v) || !!v.__component || !!v.__lazyView));
+}
+export function pickComponent(ns, label) {
+    for (const c of exportCandidates(ns)) {
+        if (isComponent(c))
+            return c;
+    }
+    // Unstamped function components resolve only where unambiguous: the
+    // loader's direct return value (.then(m => m.X)) or a default export.
+    if (typeof ns === 'function')
+        return ns;
+    if (typeof ns === 'object' && ns !== null && typeof ns.default === 'function') {
+        return ns.default;
+    }
+    throw new Error(`${label} resolved no view — expected a View class, @Component class, ` +
+        `or function component (default export or .then(m => m.X))`);
+}
+export function pickLazyFeature(ns, label) {
+    for (const c of exportCandidates(ns)) {
+        if (getModuleMeta(c) || Array.isArray(c))
+            return c;
+    }
+    throw new Error(`${label} resolved no feature — expected the module to export an ` +
+        `@Module class or a Route[] (default or named export)`);
+}
+export function pickModule(ns, label) {
+    const v = pickLazyFeature(ns, label);
+    if (Array.isArray(v)) {
+        throw new Error(`${label} resolved a Route[] — expected an @Module class`);
+    }
+    return v;
+}
+// --- Facades ----------------------------------------------------------------
+/**
+ * `lazyView(() => import('./hello.view'))` — a lazy standalone component.
+ * Usable as a Route `component` or directly in JSX: the facade suspends on
+ * the import, then mounts the resolved view with the same props.
+ */
+export function lazyView(load) {
+    const res = lazyResource(() => load().then((ns) => pickComponent(ns, 'lazyView')), 'lazyView');
+    const LazyView = ({ fallback, ...props }) => {
+        const st = res.state;
+        if (st.status === 'ready')
+            return h(st.value, props);
+        return st.status === 'loading' ? _jsx(_Fragment, { children: fallback ?? null }) : null;
+    };
+    LazyView.__lazyView = res;
+    LazyView.displayName = 'LazyView';
+    return LazyView;
+}
+/**
+ * `lazyModule(() => import('./admin.module'))` — a lazy feature module.
+ * Usable as a Route `module` (the outlet resolves the real module and its
+ * injector) or `component`, or directly in JSX: mounts the module's
+ * bootstrap view inside the module injector once the chunk lands.
+ */
+export function lazyModule(load) {
+    const res = lazyResource(() => load().then((ns) => pickModule(ns, 'lazyModule')), 'lazyModule');
+    const LazyModule = ({ fallback, ...props }) => {
+        const parent = useInjector();
+        const st = res.state;
+        const mod = st.status === 'ready' ? st.value : undefined;
+        const Boot = mod ? getModuleMeta(mod)?.bootstrap?.[0] : null;
+        if (!Boot)
+            return st.status === 'loading' ? _jsx(_Fragment, { children: fallback ?? null }) : null;
+        const inj = getModuleInjector(mod, parent);
+        return h(InjectorContext.Provider, { value: inj }, h(Boot, props));
+    };
+    LazyModule.__lazyModule = res;
+    LazyModule.displayName = 'LazyModule';
+    return LazyModule;
+}
+// --- Route-field integration -------------------------------------------------
+/**
+ * Read a lazyView/lazyModule facade's resource state — kicks the loader on
+ * first read and subscribes the reader (outlet render, router.pending
+ * computed). Non-facade values answer null.
+ */
+export function lazyStateOf(v) {
+    const res = typeof v === 'function' ? v.__lazyView ?? v.__lazyModule : null;
+    return res ? res.state : null;
+}
+/**
+ * Sync unwrap for the Route `module` field: a lazyModule facade answers
+ * with the resolved module class once loaded (undefined while pending or
+ * after a failure). Reading the resource state subscribes the caller.
+ */
+export function moduleRefOf(m) {
+    if (typeof m === 'function' && m.__lazyModule) {
+        const st = m.__lazyModule.state;
+        return st.status === 'ready' ? st.value : undefined;
+    }
+    return m;
+}
+/** Async unwrap — awaits the ref's own resolution (kicking it if needed). */
+export function lazyModuleReady(m) {
+    return typeof m === 'function' && m.__lazyModule
+        ? m.__lazyModule.ready
+        : null;
+}

package/dist/module.d.ts

@@ -1,6 +1,7 @@
 import { Injector } from './injector';
 import type { ModuleMeta } from './decorators';
 export declare function getModuleMeta(mod: any): ModuleMeta | undefined;
+export declare function isModule(mod: any): boolean;
 export declare function registerModule(mod: any, injector: Injector, seen: Set<any>): void;
 export declare function createModuleInjector(mod: any, parent: Injector): Injector;
 export declare function getModuleInjector(mod: any, parent: Injector): Injector;

package/dist/module.js

@@ -2,12 +2,16 @@ import { h, render } from 'preact';
 import { Injector } from './injector';
 import { InjectorContext } from './context';
 import { installViewInterop } from './view';
+import { ownMeta } from './decorators';
 // Modules are the unit of provider scoping. A module's providers (plus those
 // of its imports, transitively) register into a single child Injector. The
 // injector tree mirrors the view tree: root injector -> AppModule injector ->
 // feature/lazy module injectors -> per-view injectors.
 export function getModuleMeta(mod) {
-    return mod?.__module;
+    return ownMeta(mod, '__module');
+}
+export function isModule(mod) {
+    return getModuleMeta(mod) != null;
 }
 // Applies a module to an injector: registers all transitively imported
 // modules (and their providers/controllers) into it and marks them visible

package/dist/pmvc.d.ts

@@ -0,0 +1,14 @@
+import { isView } from './view';
+import { isController, isInjectable, getComponentMeta, getInjectableMeta } from './decorators';
+import { getModuleMeta, isModule } from './module';
+import { isComponent } from './lazy';
+export declare const pmvc: Readonly<{
+    isView: typeof isView;
+    isController: typeof isController;
+    isModule: typeof isModule;
+    isInjectable: typeof isInjectable;
+    isComponent: typeof isComponent;
+    getModuleMeta: typeof getModuleMeta;
+    getComponentMeta: typeof getComponentMeta;
+    getInjectableMeta: typeof getInjectableMeta;
+}>;

package/dist/pmvc.js

@@ -0,0 +1,22 @@
+import { isView } from './view';
+import { isController, isInjectable, getComponentMeta, getInjectableMeta, } from './decorators';
+import { getModuleMeta, isModule } from './module';
+import { isComponent } from './lazy';
+// The framework's class-flag read surface in one place: `pmvc.isView(x)`,
+// `pmvc.isController(x)`. Classes are identified by `__x` stamps (see
+// decorators.ts for the stamp families); these accessors encode the
+// own-vs-inherited rules so callers never touch the raw fields:
+//
+//   identity, inherited:  isView, isController, isInjectable, isComponent
+//   config,   own-class:  isModule, getModuleMeta, getComponentMeta
+//   config,   inherited:  getInjectableMeta (Angular's ɵprov rule)
+export const pmvc = Object.freeze({
+    isView,
+    isController,
+    isModule,
+    isInjectable,
+    isComponent,
+    getModuleMeta,
+    getComponentMeta,
+    getInjectableMeta,
+});

package/dist/router/lazy.d.ts

@@ -0,0 +1,48 @@
+import type { Signal } from '@preact/signals';
+import type { Route } from './router';
+export interface RouteResolution {
+    /** The view/component this route renders at its depth (null = componentless
+     *  wrapper — the outlet passes through to the next depth). */
+    component: any;
+    /** Module whose injector scopes this level (its bootstrap view is the
+     *  fallback component). */
+    module?: any;
+    /** Child routes — static `children`, or a Route[] resolved by loadChildren. */
+    children?: Route[];
+}
+export type LazyRouteState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    resolved: RouteResolution;
+} | {
+    status: 'error';
+    error: unknown;
+};
+export declare function isLazyRoute(route: Route): boolean;
+/** Sync resolution — what the route's static fields already know. Used for
+ *  eager routes and as the render answer while a lazy route's chunk loads
+ *  (an eager shell mounts immediately; its lazy children extend the match).
+ *  A `module: lazyModule(...)` field reads the facade's resource: pending
+ *  resolves to no module yet, and the read subscribes the outlet so 'ready'
+ *  swaps the real module in. */
+export declare function resolveRouteSync(route: Route): RouteResolution;
+/**
+ * True while the route's own render target is still resolving — powers
+ * `router.pending` and the outlet's `fallback`. Only matched routes are
+ * asked, so the reads merely subscribe work the outlet would kick anyway.
+ */
+export declare function routePending(route: Route): boolean;
+/**
+ * True while a matched route's `loadChildren` is holding back deeper
+ * matches — the pending match alone ends the chain, so an outlet sitting
+ * one depth past it is where the loaded child will appear. Mirrors the
+ * condition matching uses before consulting the resolution signal.
+ */
+export declare function routeChildPending(route: Route): boolean;
+/**
+ * Per-route resolution state. First call kicks the loaders; the signal flips
+ * to 'ready'/'error' when they settle — `router.matches` re-runs because
+ * matching reads it for `loadChildren`, and outlets re-render on read.
+ */
+export declare function lazyRouteState(route: Route): Signal<LazyRouteState>;

package/dist/router/lazy.js

@@ -0,0 +1,88 @@
+import { signal } from '@preact/signals';
+import { getModuleMeta } from '../module';
+import { lazyModuleReady, lazyStateOf, moduleRefOf, pickComponent, pickLazyFeature, } from '../lazy';
+export function isLazyRoute(route) {
+    return !!(route.loadComponent || route.loadChildren);
+}
+/** Sync resolution — what the route's static fields already know. Used for
+ *  eager routes and as the render answer while a lazy route's chunk loads
+ *  (an eager shell mounts immediately; its lazy children extend the match).
+ *  A `module: lazyModule(...)` field reads the facade's resource: pending
+ *  resolves to no module yet, and the read subscribes the outlet so 'ready'
+ *  swaps the real module in. */
+export function resolveRouteSync(route) {
+    const mod = moduleRefOf(route.module);
+    return {
+        component: route.component ?? getModuleMeta(mod)?.bootstrap?.[0] ?? null,
+        module: mod,
+        children: route.children,
+    };
+}
+/**
+ * True while the route's own render target is still resolving — powers
+ * `router.pending` and the outlet's `fallback`. Only matched routes are
+ * asked, so the reads merely subscribe work the outlet would kick anyway.
+ */
+export function routePending(route) {
+    if (isLazyRoute(route) && lazyRouteState(route).value.status === 'loading') {
+        return true;
+    }
+    return (lazyStateOf(route.component)?.status === 'loading' ||
+        lazyStateOf(route.module)?.status === 'loading');
+}
+/**
+ * True while a matched route's `loadChildren` is holding back deeper
+ * matches — the pending match alone ends the chain, so an outlet sitting
+ * one depth past it is where the loaded child will appear. Mirrors the
+ * condition matching uses before consulting the resolution signal.
+ */
+export function routeChildPending(route) {
+    return (!route.children?.length &&
+        !!route.loadChildren &&
+        lazyRouteState(route).value.status === 'loading');
+}
+const states = new WeakMap();
+/**
+ * Per-route resolution state. First call kicks the loaders; the signal flips
+ * to 'ready'/'error' when they settle — `router.matches` re-runs because
+ * matching reads it for `loadChildren`, and outlets re-render on read.
+ */
+export function lazyRouteState(route) {
+    let s = states.get(route);
+    if (!s) {
+        s = signal({ status: 'loading' });
+        states.set(route, s);
+        resolveLazyRoute(route).then((resolved) => {
+            s.value = { status: 'ready', resolved };
+        }, (error) => {
+            console.error(`[framework] lazy route '${route.path}' failed to load:`, error);
+            s.value = { status: 'error', error };
+        });
+    }
+    return s;
+}
+async function resolveLazyRoute(route) {
+    const lazyMod = lazyModuleReady(route.module);
+    const [feature, comp, awaitedMod] = await Promise.all([
+        route.loadChildren ? route.loadChildren() : undefined,
+        route.loadComponent ? route.loadComponent() : undefined,
+        lazyMod ?? undefined,
+    ]);
+    let mod = lazyMod ? awaitedMod : route.module;
+    let children = route.children;
+    if (route.loadChildren) {
+        const picked = pickLazyFeature(feature, `loadChildren for route '${route.path}'`);
+        if (Array.isArray(picked)) {
+            if (!children?.length)
+                children = picked;
+        }
+        else {
+            mod ?? (mod = picked);
+        }
+    }
+    const component = route.component ??
+        (route.loadComponent ? pickComponent(comp, `loadComponent for route '${route.path}'`) : undefined) ??
+        getModuleMeta(mod)?.bootstrap?.[0] ??
+        null;
+    return { component, module: mod, children };
+}

package/dist/router/module.js

@@ -1,5 +1,5 @@
-import { getModuleMeta } from '../module';
 import { ROUTES, ROUTER_BASE, Router, defaultBasePath } from './router';
+import { resolveRouteSync } from './lazy';
 // RouterModule.forRoot(routes) returns a module-shaped object — anything with
 // __module metadata can sit in `imports`, so static config works the same as
 // a decorated module class.
@@ -23,10 +23,5 @@ export class RouterModule {
 // Resolve which view a matched route should render: an explicit component, or
 // the module's declared bootstrap component.
 export function routeComponent(match) {
-    const { route } = match;
-    if (route.component)
-        return route.component;
-    if (route.module)
-        return getModuleMeta(route.module)?.bootstrap?.[0] ?? null;
-    return null;
+    return resolveRouteSync(match.route).component;
 }

package/dist/router/outlet.d.ts

@@ -1 +1,4 @@
-export declare function RouterOutlet(): import("preact").JSX.Element | null;
+import type { ComponentChildren } from 'preact';
+export declare function RouterOutlet(props: {
+    fallback?: ComponentChildren;
+}): import("preact").JSX.Element | null;

package/dist/router/outlet.js

@@ -1,10 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
 import { createContext } from 'preact';
 import { useContext } from 'preact/hooks';
 import PRRouter from 'preact-router';
 import { useInjector, useService, InjectorContext } from '../context';
 import { getModuleInjector } from '../module';
-import { routeComponent } from './module';
+import { lazyStateOf } from '../lazy';
+import { isLazyRoute, lazyRouteState, resolveRouteSync, routeChildPending, } from './lazy';
 import { Router } from './router';
 /**
  * Which depth of the matched chain this outlet renders — the root outlet
@@ -20,25 +21,47 @@ const OutletDepth = createContext(0);
  * The sink renders nothing; url/matches props die on the component.
  */
 const BridgeSink = () => null;
-export function RouterOutlet() {
+export function RouterOutlet(props) {
     const router = useService(Router);
     const parent = useInjector();
     const depth = useContext(OutletDepth);
     const matches = router.matches.value;
     const match = matches?.[depth];
     if (!match) {
+        // One depth past the chain while the last match's lazy children load —
+        // this outlet is where the loaded child will appear, so the fallback
+        // marks the spot. (Only loadChildren can hold back deeper matches.)
+        const chainLen = matches?.length ?? 0;
+        const last = chainLen ? matches[chainLen - 1] : undefined;
+        if (last && depth === chainLen && routeChildPending(last.route)) {
+            return _jsx(_Fragment, { children: props.fallback ?? null });
+        }
         // The outermost outlet keeps the bridge mounted even with no match, so
         // route() interop survives 404s.
         return depth === 0 ? (_jsx(PRRouter, { onChange: (e) => router.syncUrl(e.url), children: _jsx(BridgeSink, { default: true }) })) : null;
     }
-    const Component = routeComponent(match);
-    if (!Component)
-        return null;
+    // Lazy routes resolve through a per-route signal: while 'loading' the
+    // static fields still answer (an eager shell mounts while its lazy
+    // children load); 'ready' swaps in the resolved component/module.
+    const st = isLazyRoute(match.route) ? lazyRouteState(match.route).value : null;
+    const resolved = st?.status === 'ready' ? st.resolved : resolveRouteSync(match.route);
+    const Component = resolved.component;
     // A route with `module` gets the module's injector — its providers are
     // scoped to that feature. Nesting is automatic: a deeper outlet resolves
     // its module under this level's injector.
-    const injector = match.route.module
-        ? getModuleInjector(match.route.module, parent)
+    const injector = resolved.module
+        ? getModuleInjector(resolved.module, parent)
         : parent;
-    return (_jsxs(OutletDepth.Provider, { value: depth + 1, children: [depth === 0 && (_jsx(PRRouter, { onChange: (e) => router.syncUrl(e.url), children: _jsx(BridgeSink, { default: true }) })), _jsx(InjectorContext.Provider, { value: injector, children: _jsx(Component, {}) })] }));
+    // This depth is pending while its own render target is unresolved:
+    // route-level loaders with nothing statically known yet, a lazyModule
+    // facade in the module field, or a lazyView/lazyModule facade suspending
+    // on mount. An eager shell under a pending loadChildren is NOT pending —
+    // it renders now and the deeper outlet's fallback covers the child.
+    const pending = (st?.status === 'loading' && !Component && !resolved.module) ||
+        lazyStateOf(Component)?.status === 'loading' ||
+        lazyStateOf(match.route.module)?.status === 'loading';
+    return (_jsxs(OutletDepth.Provider, { value: depth + 1, children: [depth === 0 && (_jsx(PRRouter, { onChange: (e) => router.syncUrl(e.url), children: _jsx(BridgeSink, { default: true }) })), _jsx(InjectorContext.Provider, { value: injector, children: pending ? (props.fallback ?? null) : Component ? (_jsx(Component, {})) : (
+                /* A componentless route is a pure wrapper — the chain continues
+                   one depth down without needing a shell view. */
+                _jsx(RouterOutlet, { fallback: props.fallback })) })] }));
 }

package/dist/router/router.d.ts

@@ -3,6 +3,20 @@ export interface Route {
     path: string;
     component?: any;
     module?: any;
+    /**
+     * Lazy standalone component — a bundler split point. The loader resolves
+     * to a View class / @Component-stamped class / function component, picked
+     * from the module's default export or stamped named exports (or selected
+     * explicitly: `() => import('./x.view').then(m => m.XView)`).
+     */
+    loadComponent?: () => Promise<any>;
+    /**
+     * Lazy feature — resolves to an @Module class (its bootstrap view renders
+     * inside the module injector, like `module`) or a Route[] spliced in as
+     * this route's children. Matching reads the resolution signal, so the
+     * chain extends as soon as the chunk lands.
+     */
+    loadChildren?: () => Promise<any>;
     children?: Route[];
 }
 export interface RouteMatch {
@@ -32,6 +46,12 @@ export declare class Router {
     match: import("@preact/signals-core").ReadonlySignal<RouteMatch | null>;
     /** Params merged across the whole chain (inner levels win on collision). */
     params: import("@preact/signals-core").ReadonlySignal<any>;
+    /**
+     * True while any route in the matched chain is still resolving its lazy
+     * chunk (loadComponent/loadChildren/lazyView/lazyModule) — parents read
+     * it to render loading UI anywhere above the outlet.
+     */
+    pending: import("@preact/signals-core").ReadonlySignal<boolean>;
     constructor(routes: Route[], base?: string);
     /**
      * Static-host deep links: the site's 404 shim redirects

package/dist/router/router.js

@@ -8,6 +8,7 @@ import { computed, signal } from '@preact/signals';
 import { route as prRoute } from 'preact-router';
 import { Injectable } from '../decorators';
 import { InjectionToken } from '../injector';
+import { lazyRouteState, routePending } from './lazy';
 export const ROUTES = new InjectionToken('ROUTES');
 export const ROUTER_BASE = new InjectionToken('ROUTER_BASE');
 /**
@@ -56,8 +57,25 @@ function matchSegments(routes, segs) {
         const m = matchPrefix(route.path, segs);
         if (m === null)
             continue;
-        if (route.children?.length) {
-            const child = matchSegments(route.children, m.rest);
+        let children = route.children;
+        let pending = false;
+        if (!children?.length && route.loadChildren) {
+            // Reading the resolution signal inside the matches computed does two
+            // things: kicks the loader, and subscribes this computed so the chain
+            // re-matches the moment a lazy Route[] lands.
+            const st = lazyRouteState(route).value;
+            if (st.status === 'loading')
+                pending = true;
+            else if (st.status === 'ready')
+                children = st.resolved.children;
+        }
+        if (pending) {
+            // Lazy children unresolved — the parent claims the URL alone until the
+            // chunk lands and the computed re-matches into the loaded tree.
+            return [{ route, params: m.params }];
+        }
+        if (children?.length) {
+            const child = matchSegments(children, m.rest);
             if (child !== null)
                 return [{ route, params: m.params }, ...child];
             if (m.rest.length === 0)
@@ -86,6 +104,12 @@ let Router = class Router {
         this.match = computed(() => this.matches.value?.[0] ?? null);
         /** Params merged across the whole chain (inner levels win on collision). */
         this.params = computed(() => Object.assign({}, ...(this.matches.value ?? []).map((m) => m.params)));
+        /**
+         * True while any route in the matched chain is still resolving its lazy
+         * chunk (loadComponent/loadChildren/lazyView/lazyModule) — parents read
+         * it to render loading UI anywhere above the outlet.
+         */
+        this.pending = computed(() => !!this.matches.value?.some((m) => routePending(m.route)));
         this.onPopState = () => {
             this.syncUrl(location.pathname + location.search);
         };

package/dist/view.d.ts

@@ -1,8 +1,11 @@
 import { Component as PreactComponent } from 'preact';
 import type { ComponentChildren } from 'preact';
 export declare abstract class View<P = {}> extends PreactComponent<P> {
+    static readonly __view = true;
     abstract render(): ComponentChildren;
     setState(): never;
     forceUpdate(): never;
 }
+/** Identity stamp read — a subclass of a View stays a view. */
+export declare function isView(t: any): boolean;
 export declare function installViewInterop(): void;

package/dist/view.js

@@ -3,7 +3,7 @@ import { useLayoutEffect, useRef } from 'preact/hooks';
 import { InjectorContext, useInjector } from './context';
 import { Injector } from './injector';
 import { registerModule } from './module';
-import { ownerOf } from './decorators';
+import { ownerOf, getComponentMeta } from './decorators';
 // --- Class-based views -----------------------------------------------------
 // A View subclass is never instantiated by Preact. The options.vnode hook
 // below swaps any vnode whose type is a View subclass for a host function
@@ -23,8 +23,13 @@ export class View extends PreactComponent {
         throw new Error('View components are signal-driven — assign a signal instead of calling forceUpdate()');
     }
 }
-function isViewClass(t) {
-    return typeof t === 'function' && t.prototype instanceof View;
+// Identity stamp, not instanceof: statics inherit through the constructor
+// chain, so subclasses (and subclasses of subclasses) read true, and a
+// view class built against a second copy of this package still interops.
+View.__view = true;
+/** Identity stamp read — a subclass of a View stays a view. */
+export function isView(t) {
+    return typeof t === 'function' && !!t.__view;
 }
 // --- Error boundary ----------------------------------------------------------
 // Real Preact class component (not a View — it must be instantiated by Preact).
@@ -61,7 +66,7 @@ function hostFor(cls) {
     let host = hostCache.get(cls);
     if (host)
         return host;
-    const meta = (cls.__component ?? {});
+    const meta = getComponentMeta(cls) ?? {};
     const inner = function ViewHost(props) {
         const parent = useInjector();
         const ref = useRef(null);
@@ -125,7 +130,7 @@ export function installViewInterop() {
     const prev = options.vnode;
     options.vnode = (vnode) => {
         const t = vnode.type;
-        if (isViewClass(t))
+        if (isView(t))
             vnode.type = hostFor(t);
         prev?.(vnode);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preact-mvc/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Angular-inspired modules/DI/decorators + class-based JSX views rendered by Preact + signal reactivity",
   "type": "module",
   "sideEffects": false,