@preact-mvc/core 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@preact-mvc/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Angular-inspired modules/DI/decorators + class-based JSX views rendered by Preact + signal reactivity",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@preact/signals": "^1.3.0",
+    "preact": "^10.24.0",
+    "preact-router": "^4.1.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwhenry3/preact-mvc",
+    "directory": "packages/core"
+  },
+  "license": "MIT"
+}

package/src/context.tsx

@@ -0,0 +1,39 @@
+import { createContext } from 'preact';
+import type { ComponentChildren } from 'preact';
+import { useContext, useRef } from 'preact/hooks';
+import { Injector } from './injector';
+import type { Provider, Token } from './injector';
+
+// The current injector travels through the view tree as Preact context.
+// Module and route boundaries swap in child injectors.
+
+export const InjectorContext = createContext<Injector>(null as unknown as Injector);
+
+export function useInjector(): Injector {
+  const injector = useContext(InjectorContext);
+  if (!injector) {
+    throw new Error('No injector in context — is this view mounted under bootstrap()?');
+  }
+  return injector;
+}
+
+// Resolve a service/store from the view's injector scope.
+export function useService<T>(token: Token<T>): T {
+  return useInjector().get(token);
+}
+
+// View-local provider scope: equivalent to a component-level providers array.
+// Providers created here live and die with this subtree.
+export function Provide(props: { providers: Provider[]; children?: ComponentChildren }) {
+  const parent = useInjector();
+  const ref = useRef<Injector | null>(null);
+  if (!ref.current) {
+    ref.current = new Injector(parent, 'view providers');
+    for (const p of props.providers) ref.current.provide(p);
+  }
+  return (
+    <InjectorContext.Provider value={ref.current}>
+      {props.children}
+    </InjectorContext.Provider>
+  );
+}

package/src/controller.ts

@@ -0,0 +1,30 @@
+import { useLayoutEffect, useRef } from 'preact/hooks';
+import { useInjector } from './context';
+import { Injector } from './injector';
+import type { Type } from './injector';
+
+export interface OnInit {
+  onInit(): void;
+}
+export interface OnDestroy {
+  onDestroy(): void;
+}
+
+// Binds a controller class to a view instance. The controller is created once
+// per mounted view inside its own child injector, so `inject()` in its
+// constructor sees every provider from the enclosing module scope upward.
+// Lifecycle maps to mount/unmount: onInit on mount, onDestroy on unmount.
+export function useController<T extends object>(cls: Type<T>): T {
+  const parent = useInjector();
+  const ref = useRef<{ injector: Injector; ctrl: T } | null>(null);
+  if (!ref.current) {
+    const injector = new Injector(parent, `controller ${cls.name}`);
+    ref.current = { injector, ctrl: injector.instantiate(cls) };
+  }
+  const { ctrl, injector } = ref.current;
+  useLayoutEffect(() => {
+    injector.activate();
+    return () => injector.deactivate();
+  }, []);
+  return ctrl;
+}

package/src/decorators.ts

@@ -0,0 +1,77 @@
+import type { Provider, Type } from './injector';
+
+// Decorators attach metadata to the class constructor. They work with
+// experimentalDecorators (esbuild honors the tsconfig flag) and can also be
+// invoked manually: `Module({ ... })(MyModule)`.
+
+export interface InjectableMeta {
+  providedIn?: 'root';
+}
+
+export function Injectable(meta: InjectableMeta = {}) {
+  return function <T extends Type<any>>(target: T): T {
+    (target as any).__injectable = meta;
+    return target;
+  };
+}
+
+export function Controller() {
+  return function <T extends Type<any>>(target: T): T {
+    (target as any).__controller = true;
+    return target;
+  };
+}
+
+export interface ComponentMeta {
+  // Scoped to the component instance — like Angular component-level providers.
+  providers?: Provider[];
+  // Controllers registered in this view's scope: shared with the entire
+  // subtree (a child view injecting the same controller gets this instance).
+  // Undeclared controllers stay transient — one per injecting scope.
+  controllers?: Type<any>[];
+  // Modules whose providers and declared components join this view's scope —
+  // Angular's standalone-component `imports`. Enables module-less views that
+  // still participate in module-based scoping.
+  imports?: any[];
+}
+
+export function Component(meta: ComponentMeta = {}) {
+  return function <T>(target: T): T {
+    (target as any).__component = meta;
+    return target;
+  };
+}
+
+export interface ModuleMeta {
+  imports?: any[];
+  providers?: Provider[];
+  controllers?: Type<any>[];
+  components?: any[];
+  exports?: any[];
+  bootstrap?: any[];
+}
+
+// View class -> the module that declared it. Built as module classes are
+// decorated; consulted at mount time to enforce scope ownership.
+const componentOwners = new Map<any, any>();
+
+export function ownerOf(view: any): any {
+  return componentOwners.get(view);
+}
+
+export function Module(meta: ModuleMeta) {
+  return function <T>(target: T): T {
+    (target as any).__module = meta;
+    for (const c of [...(meta.components ?? []), ...(meta.bootstrap ?? [])]) {
+      const prev = componentOwners.get(c);
+      if (prev && prev !== target) {
+        console.warn(
+          `[framework] ${c.name ?? c} is declared by both ${prev.name} and ${(target as any).name}; keeping ${prev.name}`
+        );
+        continue;
+      }
+      componentOwners.set(c, target);
+    }
+    return target;
+  };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// Signals — the reactivity primitive shared by models, controllers, and views.
+export { signal, computed, effect, batch, untracked } from './signals';
+export type { Signal, ReadonlySignal } from './signals';
+
+// Dependency injection
+export {
+  Injector,
+  InjectionToken,
+  inject,
+  runInInjectionContext,
+  getCurrentInjector,
+  DestroyRef,
+} from './injector';
+export type { Provider, Token, Type } from './injector';
+
+// Metadata
+export { Injectable, Controller, Module, Component } from './decorators';
+export type { InjectableMeta, ModuleMeta, ComponentMeta } from './decorators';
+
+// Class-based views
+export { View, installViewInterop } from './view';
+
+// Modules & bootstrap
+export { bootstrap, createModuleInjector, getModuleInjector, getModuleMeta } from './module';
+
+// View integration
+export { InjectorContext, useInjector, useService, Provide } from './context';
+export { useController } from './controller';
+export type { OnInit, OnDestroy } from './controller';
+
+// Router
+export { Router, ROUTES, ROUTER_BASE, RouterModule, RouterOutlet, Link, defaultBasePath } from './router';
+export type { Route, RouteMatch, RouterOptions } from './router';

package/src/injector.ts

@@ -0,0 +1,228 @@
+export type Type<T> = new (...args: any[]) => T;
+
+export class InjectionToken<T> {
+  constructor(protected readonly _desc: string) {}
+  toString() {
+    return `InjectionToken ${this._desc}`;
+  }
+}
+
+export type Token<T> = Type<T> | InjectionToken<T> | (abstract new (...args: any[]) => T);
+
+export type Provider =
+  | Type<any>
+  | { provide: Token<any>; useClass: Type<any> }
+  | { provide: Token<any>; useValue: any }
+  | { provide: Token<any>; useFactory: (...deps: any[]) => any; deps?: Token<any>[] };
+
+interface Record {
+  factory: () => any;
+  resolving: boolean;
+  resolved: boolean;
+  value: any;
+}
+
+// --- Injection context -----------------------------------------------------
+// While an Injector constructs a class (service, controller, factory), it
+// becomes the "current" injector so `inject()` calls inside the constructor
+// or field initializers resolve against it — the same model as Angular's
+// injection context.
+
+let currentInjector: Injector | null = null;
+
+export function runInInjectionContext<T>(injector: Injector, fn: () => T): T {
+  const prev = currentInjector;
+  currentInjector = injector;
+  try {
+    return fn();
+  } finally {
+    currentInjector = prev;
+  }
+}
+
+export function inject<T>(token: Token<T>): T {
+  if (!currentInjector) {
+    throw new Error(
+      'inject() called outside an injection context. It can only be used in the ' +
+        'constructor/field initializers of a class instantiated by the framework.'
+    );
+  }
+  return currentInjector.get(token);
+}
+
+export function getCurrentInjector(): Injector | null {
+  return currentInjector;
+}
+
+// --- Injector ---------------------------------------------------------------
+
+function tokenName(token: Token<any>): string {
+  return typeof token === 'function' ? token.name : token.toString();
+}
+
+// Injectable handle to the enclosing scope's destruction — inject(DestroyRef)
+// anywhere to register cleanup that runs when the scope is deactivated.
+export class DestroyRef {
+  constructor(private readonly injector: Injector) {}
+  onDestroy(fn: () => void): void {
+    this.injector.registerCleanup(fn);
+  }
+}
+
+export class Injector {
+  private records = new Map<Token<any>, Record>();
+
+  // Every module whose providers AND declared components are visible in this
+  // scope: the module this injector was created for plus its transitive
+  // imports. Populated by registerModule(); read by view-mount enforcement.
+  readonly modules = new Set<any>();
+
+  constructor(
+    readonly parent: Injector | null = null,
+    readonly name = 'injector'
+  ) {
+    this.records.set(DestroyRef, {
+      factory: () => null,
+      resolving: false,
+      resolved: true,
+      value: new DestroyRef(this),
+    });
+  }
+
+  get root(): Injector {
+    let node: Injector = this;
+    while (node.parent) node = node.parent;
+    return node;
+  }
+
+  provide(provider: Provider): void {
+    if (typeof provider === 'function') {
+      const cls = provider;
+      this.records.set(cls, {
+        factory: () => this.instantiate(cls),
+        resolving: false,
+        resolved: false,
+        value: undefined,
+      });
+    } else if ('useValue' in provider) {
+      this.records.set(provider.provide, {
+        factory: () => provider.useValue,
+        resolving: false,
+        resolved: false,
+        value: undefined,
+      });
+    } else if ('useClass' in provider) {
+      const cls = provider.useClass;
+      this.records.set(provider.provide, {
+        factory: () => this.instantiate(cls),
+        resolving: false,
+        resolved: false,
+        value: undefined,
+      });
+    } else {
+      const { useFactory, deps = [] } = provider;
+      this.records.set(provider.provide, {
+        factory: () => useFactory(...deps.map((d) => this.get(d))),
+        resolving: false,
+        resolved: false,
+        value: undefined,
+      });
+    }
+  }
+
+  has(token: Token<any>): boolean {
+    if (this.records.has(token)) return true;
+    if ((token as any).__controller) return true;
+    if (this.parent) return this.parent.has(token);
+    return this.isRootProvided(token);
+  }
+
+  get<T>(token: Token<T>): T {
+    // Nearest explicit registration wins, walking up the scope chain. This is
+    // what makes declaring a controller/provider in a scope meaningful: every
+    // descendant resolves that shared instance.
+    let node: Injector | null = this;
+    while (node) {
+      const rec = node.records.get(token);
+      if (rec) return node.resolveRecord(token, rec);
+      node = node.parent;
+    }
+    // Controllers are transient unless explicitly provided: one instance per
+    // requesting scope, so a view always gets its own controller.
+    if ((token as any).__controller) {
+      this.provide(token as Type<any>);
+      return this.resolveRecord(token, this.records.get(token)!);
+    }
+    // providedIn: 'root' lazily registers at the top — local providers still
+    // shadow it because the chain walk runs first.
+    const root = this.root;
+    if (root.isRootProvided(token)) {
+      root.provide({ provide: token, useClass: token as Type<T> });
+      return root.get(token);
+    }
+    throw new Error(`No provider for ${tokenName(token)} (looked up from "${this.name}")`);
+  }
+
+  private resolveRecord<T>(token: Token<T>, rec: Record): T {
+    if (rec.resolving) {
+      throw new Error(`Circular dependency detected while resolving ${tokenName(token)}`);
+    }
+    if (!rec.resolved) {
+      rec.resolving = true;
+      try {
+        rec.value = rec.factory();
+        rec.resolved = true;
+      } finally {
+        rec.resolving = false;
+      }
+    }
+    return rec.value;
+  }
+
+  private isRootProvided(token: Token<any>): boolean {
+    const meta = (token as any).__injectable as { providedIn?: 'root' } | undefined;
+    return meta?.providedIn === 'root';
+  }
+
+  instantiate<T>(cls: Type<T>, ...args: any[]): T {
+    const inst = runInInjectionContext(this, () => new cls(...args));
+    this.trackLifecycle(inst);
+    return inst;
+  }
+
+  // --- Scope lifecycle -----------------------------------------------------
+  // Every class this injector constructs (view, injected controllers,
+  // view-scoped providers) is managed together: activate() fires onInit on
+  // all of them at mount, deactivate() fires onDestroy at unmount — the same
+  // way Angular ties provider lifecycles to their injector's scope.
+
+  private managed: any[] = [];
+  private active = false;
+
+  private trackLifecycle(inst: any): void {
+    if (typeof inst?.onInit !== 'function' && typeof inst?.onDestroy !== 'function') return;
+    this.managed.push(inst);
+    if (this.active) inst.onInit?.();
+  }
+
+  activate(): void {
+    this.active = true;
+    for (const inst of this.managed) inst.onInit?.();
+  }
+
+  deactivate(): void {
+    for (const inst of this.managed) inst.onDestroy?.();
+    for (const cleanup of this.cleanups) cleanup();
+    this.managed.length = 0;
+    this.cleanups.length = 0;
+    this.active = false;
+  }
+
+  private cleanups: Array<() => void> = [];
+
+  // Register teardown (effect disposers, subscriptions, timers) that runs
+  // when this scope is deactivated. Exposed to classes via DestroyRef.
+  registerCleanup(fn: () => void): void {
+    this.cleanups.push(fn);
+  }
+}

package/src/module.ts

@@ -0,0 +1,76 @@
+import { h, render } from 'preact';
+import { Injector } from './injector';
+import { InjectorContext } from './context';
+import { installViewInterop } from './view';
+import type { ModuleMeta } 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: any): ModuleMeta | undefined {
+  return mod?.__module;
+}
+
+// Applies a module to an injector: registers all transitively imported
+// modules (and their providers/controllers) into it and marks them visible
+// on injector.modules. Used for module injectors and standalone-component
+// `imports` alike.
+export function registerModule(mod: any, injector: Injector, seen: Set<any>): void {
+  if (seen.has(mod)) return;
+  seen.add(mod);
+  const meta = getModuleMeta(mod);
+  if (!meta) {
+    throw new Error(`${mod?.name ?? mod} is not a module — missing @Module() metadata`);
+  }
+  for (const imp of meta.imports ?? []) registerModule(imp, injector, seen);
+  injector.modules.add(mod);
+  for (const provider of meta.providers ?? []) injector.provide(provider);
+  // Module-declared controllers register at module scope: one shared
+  // instance for everything injected under that module.
+  for (const c of meta.controllers ?? []) injector.provide(c);
+}
+
+export function createModuleInjector(mod: any, parent: Injector): Injector {
+  const meta = getModuleMeta(mod);
+  if (!meta) {
+    throw new Error(`${mod?.name ?? mod} is not a module — missing @Module() metadata`);
+  }
+  const injector = new Injector(parent, `module ${mod.name ?? '(anonymous)'}`);
+  registerModule(mod, injector, new Set());
+  return injector;
+}
+
+// Lazy/feature modules get one injector per parent injector, cached so a
+// route-mounted module's providers stay alive across navigations.
+const moduleInjectorCache = new WeakMap<Injector, Map<any, Injector>>();
+
+export function getModuleInjector(mod: any, parent: Injector): Injector {
+  let byModule = moduleInjectorCache.get(parent);
+  if (!byModule) {
+    byModule = new Map();
+    moduleInjectorCache.set(parent, byModule);
+  }
+  let injector = byModule.get(mod);
+  if (!injector) {
+    injector = createModuleInjector(mod, parent);
+    byModule.set(mod, injector);
+  }
+  return injector;
+}
+
+export function bootstrap(RootModule: any, el: HTMLElement): void {
+  installViewInterop();
+  const root = new Injector(null, 'root');
+  const appInjector = createModuleInjector(RootModule, root);
+  const meta = getModuleMeta(RootModule)!;
+  const App = meta.bootstrap?.[0];
+  if (!App) {
+    throw new Error('Root module must declare a bootstrap component: @Module({ bootstrap: [AppView] })');
+  }
+  render(
+    h(InjectorContext.Provider, { value: appInjector }, h(App, {})),
+    el
+  );
+}

package/src/router/index.ts

@@ -0,0 +1,6 @@
+export { Router, ROUTES, ROUTER_BASE, defaultBasePath } from './router';
+export type { Route, RouteMatch } from './router';
+export { RouterModule, routeComponent } from './module';
+export type { RouterOptions } from './module';
+export { RouterOutlet } from './outlet';
+export { Link } from './link';

package/src/router/link.tsx

@@ -0,0 +1,25 @@
+import type { ComponentChildren } from 'preact';
+import type { JSX } from 'preact';
+import { useService } from '../context';
+import { Router } from './router';
+
+export function Link(props: {
+  to: string;
+  class?: string;
+  children?: ComponentChildren;
+}) {
+  const router = useService(Router);
+  const onClick = (e: JSX.TargetedMouseEvent<HTMLAnchorElement>) => {
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+    e.preventDefault();
+    // preact-router's document-level <a> interceptor routes any plain
+    // anchor click it sees — stop propagation so ours doesn't double-nav.
+    e.stopPropagation();
+    router.navigate(props.to);
+  };
+  return (
+    <a href={router.href(props.to)} class={props.class} onClick={onClick}>
+      {props.children}
+    </a>
+  );
+}

package/src/router/module.ts

@@ -0,0 +1,42 @@
+import { getModuleMeta } from '../module';
+import { ROUTES, ROUTER_BASE, Router, defaultBasePath } from './router';
+import type { Route } from './router';
+
+export interface RouterOptions {
+  /**
+   * Mount prefix the app is served under ('/demo/'), Angular's APP_BASE_HREF.
+   * Defaults to the document's own directory (document.baseURI), so apps
+   * hosted under a subpath need no config; '/' disables prefixing.
+   */
+  basePath?: string;
+}
+
+// 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.
+export class RouterModule {
+  static forRoot(routes: Route[], opts: RouterOptions = {}) {
+    return {
+      __module: {
+        providers: [
+          { provide: ROUTES, useValue: routes },
+          { provide: ROUTER_BASE, useValue: opts.basePath ?? defaultBasePath() },
+          {
+            provide: Router,
+            useFactory: (r: Route[], base: string) => new Router(r, base),
+            deps: [ROUTES, ROUTER_BASE],
+          },
+        ],
+      },
+    };
+  }
+}
+
+// Resolve which view a matched route should render: an explicit component, or
+// the module's declared bootstrap component.
+export function routeComponent(match: { route: Route }): any {
+  const { route } = match;
+  if (route.component) return route.component;
+  if (route.module) return getModuleMeta(route.module)?.bootstrap?.[0] ?? null;
+  return null;
+}

package/src/router/outlet.tsx

@@ -0,0 +1,65 @@
+import { createContext } from 'preact';
+import type { FunctionComponent } from 'preact';
+import { useContext } from 'preact/hooks';
+import PRRouter from 'preact-router';
+import type { RoutableProps } from 'preact-router';
+import { useInjector, useService, InjectorContext } from '../context';
+import { getModuleInjector } from '../module';
+import { routeComponent } from './module';
+import { Router } from './router';
+
+/**
+ * Which depth of the matched chain this outlet renders — the root outlet
+ * is depth 0, an outlet inside a routed view is depth 1, and so on.
+ */
+const OutletDepth = createContext(0);
+
+/**
+ * The preact-router bridge: a mounted PR <Router> claiming every URL via a
+ * `default` sink child. Its existence makes preact-router's machinery live
+ * in this app — foreign `route()` calls and the global `<a href>` click
+ * interceptor resolve through it — and its onChange feeds our `url`
+ * signal, so navigations from ANY preact-routing code drive our router.
+ * The sink renders nothing; url/matches props die on the component.
+ */
+const BridgeSink: FunctionComponent<RoutableProps> = () => null;
+
+export function RouterOutlet() {
+  const router = useService(Router);
+  const parent = useInjector();
+  const depth = useContext(OutletDepth);
+  const matches = router.matches.value;
+  const match = matches?.[depth];
+  if (!match) {
+    // The outermost outlet keeps the bridge mounted even with no match, so
+    // route() interop survives 404s.
+    return depth === 0 ? (
+      <PRRouter onChange={(e) => router.syncUrl(e.url)}>
+        <BridgeSink default />
+      </PRRouter>
+    ) : null;
+  }
+
+  const Component = routeComponent(match);
+  if (!Component) return null;
+
+  // 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)
+    : parent;
+
+  return (
+    <OutletDepth.Provider value={depth + 1}>
+      {depth === 0 && (
+        <PRRouter onChange={(e) => router.syncUrl(e.url)}>
+          <BridgeSink default />
+        </PRRouter>
+      )}
+      <InjectorContext.Provider value={injector}>
+        <Component />
+      </InjectorContext.Provider>
+    </OutletDepth.Provider>
+  );
+}

package/src/router/router.ts

@@ -0,0 +1,165 @@
+import { computed, signal } from '@preact/signals';
+import { route as prRoute } from 'preact-router';
+import { Injectable } from '../decorators';
+import { InjectionToken } from '../injector';
+
+export interface Route {
+  path: string;
+  component?: any; // view function
+  module?: any; // module class — its bootstrap component renders inside its injector
+  children?: Route[];
+}
+
+export interface RouteMatch {
+  route: Route;
+  params: Record<string, string>;
+}
+
+export const ROUTES = new InjectionToken<Route[]>('ROUTES');
+export const ROUTER_BASE = new InjectionToken<string>('ROUTER_BASE');
+
+/**
+ * The directory the app's document lives at, e.g. '/demo/' when the page is
+ * served from `host/demo/index.html`. Deriving the base from baseURI (rather
+ * than baking it at build time) means the same bundle works under any mount
+ * path — GitHub Pages project dirs, reverse-proxy prefixes, iframed demos.
+ */
+export function defaultBasePath(): string {
+  if (typeof document === 'undefined') return '/';
+  const p = new URL(document.baseURI).pathname;
+  return p.endsWith('/') ? p : p.slice(0, p.lastIndexOf('/') + 1);
+}
+
+/**
+ * Prefix match: consume the pattern's leading segments off `segs`, returning
+ * the captured params and the unconsumed tail. `'*'` consumes everything;
+ * `''` consumes nothing (an index route — leaf check decides validity).
+ */
+function matchPrefix(
+  pattern: string,
+  segs: string[],
+): { params: Record<string, string>; rest: string[] } | null {
+  if (pattern === '*') return { params: {}, rest: [] };
+  const pSegs = pattern.split('/').filter(Boolean);
+  if (pSegs.length > segs.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < pSegs.length; i++) {
+    const p = pSegs[i];
+    const u = decodeURIComponent(segs[i]);
+    if (p.startsWith(':')) params[p.slice(1)] = u;
+    else if (p !== u) return null;
+  }
+  return { params, rest: segs.slice(pSegs.length) };
+}
+
+/**
+ * Match `segs` against a route list into a chain outermost → innermost.
+ * A route with `children` matches by prefix and the tail recurses; a leaf
+ * route must consume the whole tail. Parents may match alone when the tail
+ * is exhausted (Angular semantics: `/users` renders the parent shell even
+ * if it has children).
+ */
+function matchSegments(routes: Route[], segs: string[]): RouteMatch[] | null {
+  for (const route of routes) {
+    const m = matchPrefix(route.path, segs);
+    if (m === null) continue;
+    if (route.children?.length) {
+      const child = matchSegments(route.children, m.rest);
+      if (child !== null) return [{ route, params: m.params }, ...child];
+      if (m.rest.length === 0) return [{ route, params: m.params }];
+      continue;
+    }
+    if (m.rest.length === 0) return [{ route, params: m.params }];
+  }
+  return null;
+}
+
+function matchRoutes(routes: Route[], url: string): RouteMatch[] | null {
+  const path = url.split('?')[0].split('#')[0];
+  return matchSegments(routes, path.split('/').filter(Boolean));
+}
+
+@Injectable()
+export class Router {
+  /** Mount prefix, normalized to '' or '/demo' (no trailing slash). */
+  readonly base: string;
+  url = signal(typeof location === 'undefined' ? '/' : '');
+  /**
+   * The matched chain outermost → innermost — depth d is what the d-th
+   * nested <RouterOutlet/> renders.
+   */
+  matches = computed(() => matchRoutes(this.routes, this.url.value));
+  /** Back-compat: the chain's outermost match. */
+  match = computed(() => this.matches.value?.[0] ?? null);
+  /** Params merged across the whole chain (inner levels win on collision). */
+  params = computed(() =>
+    Object.assign({}, ...(this.matches.value ?? []).map((m) => m.params)),
+  );
+
+  constructor(
+    private routes: Route[],
+    base = defaultBasePath(),
+  ) {
+    this.base = base === '/' ? '' : base.replace(/\/+$/, '');
+    this.consumeShimParam();
+    if (typeof location !== 'undefined') {
+      this.url.value = this.strip(location.pathname) + location.search;
+    }
+    if (typeof window !== 'undefined') {
+      window.addEventListener('popstate', this.onPopState);
+    }
+  }
+
+  /**
+   * Static-host deep links: the site's 404 shim redirects
+   * `/docs/<app>/<rest>` to `<app>/?__pmvc_path=<rest>` so the app loads;
+   * restore the real URL via replaceState before seeding `url` — the
+   * browser history never sees the hop. No-op everywhere else.
+   */
+  private consumeShimParam(): void {
+    if (typeof location === 'undefined' || typeof history === 'undefined') return;
+    const rest = new URL(location.href).searchParams.get('__pmvc_path');
+    if (rest === null) return;
+    history.replaceState(null, '', this.base + '/' + rest);
+  }
+
+  private strip(path: string): string {
+    if (this.base && path.startsWith(this.base)) {
+      return path.slice(this.base.length) || '/';
+    }
+    return path;
+  }
+
+  /** Absolute href for an in-app path — what <a href> and pushState see. */
+  href(to: string): string {
+    return this.base + to;
+  }
+
+  /** Called by the preact-router bridge on any URL change it sees —
+   *  foreign route() calls, its global <a> interceptor, popstate. */
+  syncUrl(fullUrl: string): void {
+    const [path, search = ''] = fullUrl.split('?');
+    const stripped = this.strip(path);
+    const next = stripped + (search ? `?${search}` : '');
+    if (next !== this.url.value) this.url.value = next;
+  }
+
+  private onPopState = () => {
+    this.syncUrl(location.pathname + location.search);
+  };
+
+  navigate(to: string): void {
+    // Through preact-router: updates every mounted <Router> in the tree —
+    // ours and foreign ones — not just our own subscriber. route() is a
+    // no-op when no mounted PR Router claims the url, so fall back to a
+    // manual push when the bridge isn't up yet.
+    if (!prRoute(this.base + to)) {
+      history.pushState(null, '', this.base + to);
+      this.url.value = to;
+    }
+  }
+
+  isActive(path: string): boolean {
+    return this.url.value === path;
+  }
+}

package/src/signals.ts

@@ -0,0 +1,19 @@
+// Re-export the signal primitives. Importing through here guarantees the
+// @preact/signals integration (auto re-render on .value read during render)
+// is installed before any view uses it.
+import { effect as preactEffect } from '@preact/signals';
+import { getCurrentInjector } from './injector';
+
+export { signal, computed, batch, untracked } from '@preact/signals';
+export type { Signal, ReadonlySignal } from '@preact/signals';
+
+// Scope-bound effect: created during a class's construction (field
+// initializers or constructor body), it registers on that scope's injector
+// and is disposed automatically when the scope is deactivated — Angular's
+// DestroyRef semantics. Outside an injection context it's the raw primitive:
+// call the returned disposer yourself.
+export function effect(fn: Parameters<typeof preactEffect>[0]): () => void {
+  const dispose = preactEffect(fn);
+  getCurrentInjector()?.registerCleanup(dispose);
+  return dispose;
+}

package/src/view.ts

@@ -0,0 +1,153 @@
+import { Component as PreactComponent, h, options } from 'preact';
+import type { ComponentChildren, VNode } from 'preact';
+import { useLayoutEffect, useRef } from 'preact/hooks';
+import { InjectorContext, useInjector } from './context';
+import { Injector } from './injector';
+import { registerModule } from './module';
+import { ownerOf } from './decorators';
+import type { ComponentMeta } 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
+// component, which constructs the class ONCE per mount inside a child
+// injector — so `inject()` in field initializers resolves against that view's
+// scope (component providers -> module providers -> root).
+//
+// render() runs on every render pass with no framework involvement: signals
+// read inside it subscribe the host component automatically.
+
+export abstract class View<P = {}> extends PreactComponent<P> {
+  abstract render(): ComponentChildren;
+
+  // Views are signal-driven; setState/forceUpdate would hit Preact internals
+  // on an instance Preact never mounted. Fail loudly instead of corrupting.
+  override setState(): never {
+    throw new Error('View components are signal-driven — assign a signal instead of calling setState()');
+  }
+  override forceUpdate(): never {
+    throw new Error('View components are signal-driven — assign a signal instead of calling forceUpdate()');
+  }
+}
+
+function isViewClass(t: any): boolean {
+  return typeof t === 'function' && t.prototype instanceof View;
+}
+
+// --- Error boundary ----------------------------------------------------------
+// Real Preact class component (not a View — it must be instantiated by Preact).
+// Wraps every view host so mount/render failures stay local instead of
+// aborting the whole render pass.
+
+class ViewErrorBoundary extends PreactComponent<
+  { viewName: string; children?: ComponentChildren },
+  { error: any }
+> {
+  override state = { error: null as any };
+
+  override componentDidCatch(error: any) {
+    console.error(`[framework] ${this.props.viewName} failed:`, error);
+    this.setState({ error });
+  }
+
+  override render() {
+    const err = this.state.error;
+    if (!err) return this.props.children;
+    return h(
+      'div',
+      {
+        style: {
+          border: '1px solid #e53935',
+          background: '#ffebee',
+          padding: '0.75rem',
+          borderRadius: '4px',
+          fontFamily: 'monospace',
+          fontSize: '0.85rem',
+        },
+      },
+      h('strong', null, `${this.props.viewName} failed to mount`),
+      h('pre', { style: { whiteSpace: 'pre-wrap', margin: '0.5rem 0' } }, String(err?.message ?? err)),
+      h('button', { onClick: () => this.setState({ error: null }) }, 'Retry')
+    );
+  }
+}
+
+// --- Host -------------------------------------------------------------------
+
+const hostCache = new Map<any, any>();
+
+function hostFor(cls: any): any {
+  let host = hostCache.get(cls);
+  if (host) return host;
+
+  const meta = (cls.__component ?? {}) as ComponentMeta;
+
+  const inner = function ViewHost(props: any) {
+    const parent = useInjector();
+    const ref = useRef<{ inj: Injector; inst: any } | null>(null);
+    if (!ref.current) {
+      // Module ownership: a view declared in a module's components/bootstrap
+      // may only mount where that module's injector is an ancestor — Angular's
+      // declaration rule enforced at mount. Undeclared views mount freely.
+      const owner = ownerOf(cls);
+      if (owner) {
+        let node: Injector | null = parent;
+        while (node && !node.modules.has(owner)) node = node.parent;
+        if (!node) {
+          throw new Error(
+            `${cls.name} is declared by ${owner.name ?? 'a module'} but mounted outside its injector scope. ` +
+              `Mount it under a route/module that includes ${owner.name ?? 'that module'}.`
+          );
+        }
+      }
+      const inj = new Injector(parent, `view ${cls.name}`);
+      // Standalone scope: imported modules contribute providers (and mark
+      // themselves visible for ownership checks); view-level providers and
+      // declared controllers register on top, closest-scope-wins.
+      const seen = new Set<any>();
+      for (const imp of meta.imports ?? []) registerModule(imp, inj, seen);
+      for (const p of meta.providers ?? []) inj.provide(p);
+      for (const c of meta.controllers ?? []) inj.provide(c);
+      ref.current = { inj, inst: inj.instantiate(cls, props) };
+    }
+    const { inj, inst } = ref.current;
+    inst.props = props;
+    // Mount activates the whole view scope: onInit for the view and every
+    // controller/provider its injector constructed; unmount fires onDestroy.
+    // useLayoutEffect (synchronous at commit) is deliberate: deferred
+    // useEffect callbacks are dropped if the host unmounts before they flush,
+    // which would silently lose onInit on same-tick mount+navigate.
+    useLayoutEffect(() => {
+      inj.activate();
+      return () => inj.deactivate();
+    }, []);
+    // The view's injector becomes the scope for everything it renders, so
+    // child components resolve through it — the element-injector hierarchy.
+    return h(InjectorContext.Provider, { value: inj }, inst.render());
+  };
+  (inner as any).displayName = cls.name;
+
+  host = function BoundedView(props: any) {
+    return h(ViewErrorBoundary, { viewName: cls.name }, h(inner, props));
+  };
+  (host as any).displayName = cls.name;
+  hostCache.set(cls, host);
+  return host;
+}
+
+let installed = false;
+
+// Install the vnode interceptor. Must run before any view class is rendered;
+// called on module load and again defensively from bootstrap().
+export function installViewInterop(): void {
+  if (installed) return;
+  installed = true;
+  const prev = (options as any).vnode as ((vnode: VNode) => void) | undefined;
+  (options as any).vnode = (vnode: VNode) => {
+    const t = vnode.type;
+    if (isViewClass(t)) vnode.type = hostFor(t);
+    prev?.(vnode);
+  };
+}
+
+installViewInterop();

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.