@hamak/ui-shell 0.10.0 → 0.11.0

package/README.md

@@ -164,6 +164,32 @@ router.subscribe((route) => {
 });
 ```
 
+### Contributed Routes and Store-fs Views
+
+Plugins contribute routes and view resolvers through `createViewRoutingPlugin()`:
+
+```typescript
+import { ROUTE_REGISTRY_TOKEN, VIEW_RESOLVER_REGISTRY_TOKEN } from '@hamak/ui-shell';
+
+// manifest: { name: 'studio', dependsOn: ['view-routing'], ... }
+initialize(ctx) {
+  ctx.resolve(ROUTE_REGISTRY_TOKEN).register({ path: '/content/*', component: ContentPage, plugin: 'studio' });
+  ctx.resolve(VIEW_RESOLVER_REGISTRY_TOKEN).register({
+    id: 'studio-model',
+    priority: 10,
+    resolve: (ref) => (ref.node.name.endsWith('.dm.json') ? ModelStudio : undefined),
+  });
+}
+```
+
+`<ContentView path fs />` (from `@hamak/ui-shell/react`) observes the store-fs node at `path` and renders the component
+the highest-priority resolver returns, or a default view. It dispatches nothing; loading the node is the host's job.
+
+**Which route type?** `RouteContribution` (the route registry) is for hosts that render routes with their own router,
+such as react-router: read `useRouteContributions()` in the layout. `RouteConfig` is the table of the shell's built-in
+`DefaultRouter` (lazy components, guards). Registrations are not removed when a plugin deactivates, so keep the
+`dispose` handle if your plugin can be deactivated.
+
 ### Layout Management
 
 ```typescript

package/dist/api/tokens/service-tokens.d.ts

@@ -54,4 +54,16 @@ export declare const ShellViewSlots: {
     readonly FOOTER: "shell.footer";
     readonly OVERLAY: "shell.overlay";
 };
+/**
+ * Token for the route contribution registry (`IRouteRegistry`)
+ *
+ * The view-routing tokens use `Symbol.for`, so two copies of this module (a
+ * plugin bundled with its own copy of ui-shell) still name the same service.
+ * The older tokens above predate that and still use `Symbol()`.
+ */
+export declare const ROUTE_REGISTRY_TOKEN: unique symbol;
+/**
+ * Token for the view resolver registry (`IViewResolverRegistry`)
+ */
+export declare const VIEW_RESOLVER_REGISTRY_TOKEN: unique symbol;
 //# sourceMappingURL=service-tokens.d.ts.map

package/dist/api/tokens/service-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-tokens.d.ts","sourceRoot":"","sources":["../../../src/api/tokens/service-tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,eAAkB,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAyB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAA2B,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,YAAY,eAAmB,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAA0B,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;CAQhB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC"}
+{"version":3,"file":"service-tokens.d.ts","sourceRoot":"","sources":["../../../src/api/tokens/service-tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,eAAkB,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAyB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAA2B,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,YAAY,eAAmB,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAA0B,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;CAQhB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,eAA8C,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,4BAA4B,eAAqD,CAAC"}

package/dist/api/tokens/service-tokens.js

@@ -54,3 +54,15 @@ export const ShellViewSlots = {
     FOOTER: 'shell.footer',
     OVERLAY: 'shell.overlay',
 };
+/**
+ * Token for the route contribution registry (`IRouteRegistry`)
+ *
+ * The view-routing tokens use `Symbol.for`, so two copies of this module (a
+ * plugin bundled with its own copy of ui-shell) still name the same service.
+ * The older tokens above predate that and still use `Symbol()`.
+ */
+export const ROUTE_REGISTRY_TOKEN = Symbol.for('@hamak/ui-shell:RouteRegistry');
+/**
+ * Token for the view resolver registry (`IViewResolverRegistry`)
+ */
+export const VIEW_RESOLVER_REGISTRY_TOKEN = Symbol.for('@hamak/ui-shell:ViewResolverRegistry');

package/dist/api/types/index.d.ts

@@ -8,4 +8,5 @@ export * from './route-types.js';
 export * from './layout-types.js';
 export * from './event-types.js';
 export * from './shell-context.js';
+export * from './view-routing-types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/api/types/index.js

@@ -8,3 +8,4 @@ export * from './route-types.js';
 export * from './layout-types.js';
 export * from './event-types.js';
 export * from './shell-context.js';
+export * from './view-routing-types.js';

package/dist/api/types/view-routing-types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * View routing: routes that plugins contribute, and the resolvers that decide
+ * which component displays a store-fs node.
+ *
+ * The types are framework-neutral: a component is whatever the host renders
+ * (`C`, a React `ComponentType` for `@hamak/ui-shell/react`).
+ */
+import type { FileNode } from '@hamak/shared-utils';
+/**
+ * A route a plugin contributes.
+ *
+ * `RouteContribution` is what plugins add to the {@link IRouteRegistry}, for a
+ * host whose own router (e.g. react-router) renders them. `RouteConfig` is the
+ * route table of the shell's built-in `DefaultRouter` (`ROUTER_TOKEN`), with
+ * lazy components and guards. A host using `DefaultRouter` can map
+ * contributions into it; a host with its own router reads the registry.
+ */
+export interface RouteContribution<C = unknown> {
+    /** Router path pattern, e.g. `/content/*`. Unique within a registry. */
+    path: string;
+    /** Rendered for the route. */
+    component: C;
+    /** Human label, e.g. for a generated navigation. */
+    title?: string;
+    /** Name of the contributing plugin, for reports. */
+    plugin?: string;
+    /** Anything else the host's router needs. */
+    meta?: Record<string, unknown>;
+}
+/** A registration refused because another entry already holds its key. */
+export interface DuplicateContribution<T> {
+    /** The path (routes) or id (resolvers) both entries claim. */
+    key: string;
+    /** The entry that holds the key; it stays registered. */
+    existing: T;
+    /** The entry that was refused. */
+    rejected: T;
+}
+export type Registration<T> = {
+    accepted: true;
+    dispose: () => void;
+} | {
+    accepted: false;
+    duplicate: DuplicateContribution<T>;
+};
+export interface IRouteRegistry<C = unknown> {
+    /**
+     * Add a route. A path that is already registered is refused and reported
+     * (the earlier registration stays), never silently replaced. `dispose`
+     * removes this registration once; registrations are not removed when the
+     * contributing plugin deactivates.
+     */
+    register(route: RouteContribution<C>): Registration<RouteContribution<C>>;
+    /** Every accepted route, in registration order. */
+    list(): readonly RouteContribution<C>[];
+    /** The most recent refused registrations (at most 100), oldest first. */
+    duplicates(): readonly DuplicateContribution<RouteContribution<C>>[];
+    /** Called after every change to `list()`. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * What a resolver is asked about: one store-fs file, as the store holds it now.
+ */
+export interface StoreFsNodeRef<T = unknown> {
+    /** Path segments from the store-fs root. */
+    path: readonly string[];
+    /** Media type from the file name's suffix (`contentTypeOf`, `@hamak/shared-utils`). */
+    contentType: string;
+    /** The parsed content, as held in the store (`undefined` until loaded). */
+    content: T;
+    /** The store-fs node itself: name, schema, state. */
+    node: FileNode<T>;
+}
+/**
+ * Decides whether it displays a store-fs node. Resolvers are asked in priority
+ * order and the first component returned wins.
+ */
+export interface ViewResolver<C = unknown> {
+    /** Unique within a registry. */
+    id: string;
+    /**
+     * Higher is asked first; equal priorities keep registration order. Default 0.
+     * Read when the resolver is registered: to change it, unregister and register
+     * the resolver again.
+     */
+    priority?: number;
+    /** The component that displays `ref`, or `undefined` / `null` to pass. */
+    resolve(ref: StoreFsNodeRef): C | null | undefined;
+    /** Name of the contributing plugin, for reports. */
+    plugin?: string;
+}
+export interface ResolvedView<C = unknown> {
+    resolver: ViewResolver<C>;
+    component: C;
+}
+export interface IViewResolverRegistry<C = unknown> {
+    /**
+     * Add a resolver. An id that is already registered is refused and reported.
+     * The returned `dispose` removes the resolver. Its `priority` is read now; a
+     * later change to it does not re-order the registry (unregister and register
+     * again instead).
+     */
+    register(resolver: ViewResolver<C>): Registration<ViewResolver<C>>;
+    /** Remove the resolver with this id. Returns whether one was removed. */
+    unregister(id: string): boolean;
+    /** Every resolver, in the order they are asked. */
+    list(): readonly ViewResolver<C>[];
+    /** The first resolver's answer for `ref`, or `undefined` when all pass. */
+    resolve(ref: StoreFsNodeRef): ResolvedView<C> | undefined;
+    /** The most recent refused registrations (at most 100), oldest first. */
+    duplicates(): readonly DuplicateContribution<ViewResolver<C>>[];
+    /** Called after every change to `list()`. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+//# sourceMappingURL=view-routing-types.d.ts.map

package/dist/api/types/view-routing-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-routing-types.d.ts","sourceRoot":"","sources":["../../../src/api/types/view-routing-types.ts"],"names":[],"mappings":"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"}

package/dist/api/types/view-routing-types.js

@@ -0,0 +1,8 @@
+/**
+ * View routing: routes that plugins contribute, and the resolvers that decide
+ * which component displays a store-fs node.
+ *
+ * The types are framework-neutral: a component is whatever the host renders
+ * (`C`, a React `ComponentType` for `@hamak/ui-shell/react`).
+ */
+export {};

package/dist/impl/index.d.ts

@@ -12,6 +12,7 @@ export * from './providers/index.js';
 export * from './utils/index.js';
 export * from './styles/index.js';
 export * from './plugin/index.js';
+export * from './view-routing/index.js';
 import { DefaultShell } from './core/DefaultShell.js';
 import { DefaultLayoutManager } from './core/DefaultLayoutManager.js';
 import type { ShellConfig } from '../api/index.js';

package/dist/impl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/impl/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,aAAa,CAAC;AAG5B,cAAc,SAAS,CAAC;AAGxB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAE9D;AAED,wBAAgB,mBAAmB,IAAI,oBAAoB,CAE1D;AAKD,wBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAK3D;AAED,wBAAgB,UAAU,IAAI,IAAI,CAKjC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/impl/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,aAAa,CAAC;AAG5B,cAAc,SAAS,CAAC;AAGxB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAE9D;AAED,wBAAgB,mBAAmB,IAAI,oBAAoB,CAE1D;AAKD,wBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAK3D;AAED,wBAAgB,UAAU,IAAI,IAAI,CAKjC"}

package/dist/impl/index.js

@@ -18,6 +18,8 @@ export * from './utils/index.js';
 export * from './styles/index.js';
 // Export plugin integration
 export * from './plugin/index.js';
+// Export route contributions and view resolvers
+export * from './view-routing/index.js';
 // Factory functions
 import { DefaultShell } from './core/DefaultShell.js';
 import { DefaultLayoutManager } from './core/DefaultLayoutManager.js';

package/dist/impl/view-routing/contribution-registry.d.ts

@@ -0,0 +1,29 @@
+import type { DuplicateContribution, Registration } from '../../api/index.js';
+/** How many refused registrations `duplicates()` keeps (the most recent ones). */
+export declare const MAX_REPORTED_DUPLICATES = 100;
+/**
+ * Keyed, ordered contributions with change notification. A second entry for a
+ * key is refused and reported; the first registration stays.
+ *
+ * Registrations are not tied to a plugin's lifecycle: a contributor that can be
+ * deactivated keeps its `dispose` handles. A route disposed and registered
+ * again goes to the end of the list, so the list follows `dependsOn` order for
+ * registrations made during `initialize()`.
+ */
+export declare class ContributionRegistry<T> {
+    private readonly keyOf;
+    private readonly onChange;
+    private readonly records;
+    private readonly refused;
+    private readonly listeners;
+    private readonly onDuplicate;
+    constructor(keyOf: (entry: T) => string, kind: string, onDuplicate?: (duplicate: DuplicateContribution<T>) => void, onChange?: () => void);
+    add(entry: T): Registration<T>;
+    removeKey(key: string): boolean;
+    list(): readonly T[];
+    duplicates(): readonly DuplicateContribution<T>[];
+    subscribe(listener: () => void): () => void;
+    private removeRecord;
+    private notify;
+}
+//# sourceMappingURL=contribution-registry.d.ts.map

package/dist/impl/view-routing/contribution-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution-registry.d.ts","sourceRoot":"","sources":["../../../src/impl/view-routing/contribution-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAErE,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAO3C;;;;;;;;GAQG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IAO/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAGtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgD;gBAGzD,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAC5C,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC1C,QAAQ,GAAE,MAAM,IAAe;IAOlD,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;IAkB9B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK/B,IAAI,IAAI,SAAS,CAAC,EAAE;IAIpB,UAAU,IAAI,SAAS,qBAAqB,CAAC,CAAC,CAAC,EAAE;IAIjD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,MAAM;CAIf"}

package/dist/impl/view-routing/contribution-registry.js

@@ -0,0 +1,101 @@
+/** How many refused registrations `duplicates()` keeps (the most recent ones). */
+export const MAX_REPORTED_DUPLICATES = 100;
+/**
+ * Keyed, ordered contributions with change notification. A second entry for a
+ * key is refused and reported; the first registration stays.
+ *
+ * Registrations are not tied to a plugin's lifecycle: a contributor that can be
+ * deactivated keeps its `dispose` handles. A route disposed and registered
+ * again goes to the end of the list, so the list follows `dependsOn` order for
+ * registrations made during `initialize()`.
+ */
+export class ContributionRegistry {
+    constructor(keyOf, kind, onDuplicate, onChange = () => { }) {
+        Object.defineProperty(this, "keyOf", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: keyOf
+        });
+        Object.defineProperty(this, "onChange", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: onChange
+        });
+        Object.defineProperty(this, "records", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "refused", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "onDuplicate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.onDuplicate = onDuplicate ?? ((duplicate) => {
+            console.warn(`Duplicate ${kind} '${duplicate.key}' refused; the first registration stays`, duplicate);
+        });
+    }
+    add(entry) {
+        const key = this.keyOf(entry);
+        const existing = this.records.find((record) => this.keyOf(record.entry) === key);
+        if (existing !== undefined) {
+            const duplicate = { key, existing: existing.entry, rejected: entry };
+            this.refused.push(duplicate);
+            if (this.refused.length > MAX_REPORTED_DUPLICATES)
+                this.refused.shift();
+            this.onDuplicate(duplicate);
+            return { accepted: false, duplicate };
+        }
+        const record = { entry };
+        this.records.push(record);
+        this.notify();
+        // The handle removes this registration only: once it has run, or once the
+        // entry was removed and registered again, it does nothing.
+        return { accepted: true, dispose: () => this.removeRecord(record) };
+    }
+    removeKey(key) {
+        const record = this.records.find((r) => this.keyOf(r.entry) === key);
+        return record !== undefined && this.removeRecord(record);
+    }
+    list() {
+        return this.records.map((record) => record.entry);
+    }
+    duplicates() {
+        return [...this.refused];
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    removeRecord(record) {
+        const index = this.records.indexOf(record);
+        if (index < 0)
+            return false;
+        this.records.splice(index, 1);
+        this.notify();
+        return true;
+    }
+    notify() {
+        this.onChange();
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}

package/dist/impl/view-routing/index.d.ts

@@ -0,0 +1,6 @@
+export * from './contribution-registry.js';
+export * from './route-registry.js';
+export * from './view-resolver-registry.js';
+export * from './store-fs-node-ref.js';
+export * from './view-routing-plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/impl/view-routing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/impl/view-routing/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/impl/view-routing/index.js

@@ -0,0 +1,5 @@
+export * from './contribution-registry.js';
+export * from './route-registry.js';
+export * from './view-resolver-registry.js';
+export * from './store-fs-node-ref.js';
+export * from './view-routing-plugin.js';

package/dist/impl/view-routing/route-registry.d.ts

@@ -0,0 +1,18 @@
+import type { DuplicateContribution, IRouteRegistry, Registration, RouteContribution } from '../../api/index.js';
+export type DuplicateReporter<T> = (duplicate: DuplicateContribution<T>) => void;
+/**
+ * Routes contributed by plugins, keyed by path.
+ *
+ * `list()` keeps registration order. Plugins register during `initialize()`,
+ * which the microkernel runs in `dependsOn` order, so a route of a plugin comes
+ * after the routes of the plugins it depends on.
+ */
+export declare class RouteRegistry<C = unknown> implements IRouteRegistry<C> {
+    private readonly routes;
+    constructor(onDuplicate?: DuplicateReporter<RouteContribution<C>>);
+    register(route: RouteContribution<C>): Registration<RouteContribution<C>>;
+    list(): readonly RouteContribution<C>[];
+    duplicates(): readonly DuplicateContribution<RouteContribution<C>>[];
+    subscribe(listener: () => void): () => void;
+}
+//# sourceMappingURL=route-registry.d.ts.map

package/dist/impl/view-routing/route-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-registry.d.ts","sourceRoot":"","sources":["../../../src/impl/view-routing/route-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAGnB,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEjF;;;;;;GAMG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,cAAc,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;gBAExD,WAAW,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAIjE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAIzE,IAAI,IAAI,SAAS,iBAAiB,CAAC,CAAC,CAAC,EAAE;IAIvC,UAAU,IAAI,SAAS,qBAAqB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE;IAIpE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAG5C"}

package/dist/impl/view-routing/route-registry.js

@@ -0,0 +1,31 @@
+import { ContributionRegistry } from './contribution-registry.js';
+/**
+ * Routes contributed by plugins, keyed by path.
+ *
+ * `list()` keeps registration order. Plugins register during `initialize()`,
+ * which the microkernel runs in `dependsOn` order, so a route of a plugin comes
+ * after the routes of the plugins it depends on.
+ */
+export class RouteRegistry {
+    constructor(onDuplicate) {
+        Object.defineProperty(this, "routes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.routes = new ContributionRegistry((route) => route.path, 'route', onDuplicate);
+    }
+    register(route) {
+        return this.routes.add(route);
+    }
+    list() {
+        return this.routes.list();
+    }
+    duplicates() {
+        return this.routes.duplicates();
+    }
+    subscribe(listener) {
+        return this.routes.subscribe(listener);
+    }
+}

package/dist/impl/view-routing/store-fs-node-ref.d.ts

@@ -0,0 +1,8 @@
+import { type FileSystemNode } from '@hamak/shared-utils';
+import type { StoreFsNodeRef } from '../../api/index.js';
+/**
+ * The resolver input for a store-fs node, or `undefined` when the node is not
+ * a file. The content type comes from the file name's suffix.
+ */
+export declare function storeFsNodeRef(path: string | readonly string[], node: FileSystemNode | undefined): StoreFsNodeRef | undefined;
+//# sourceMappingURL=store-fs-node-ref.d.ts.map

package/dist/impl/view-routing/store-fs-node-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-fs-node-ref.d.ts","sourceRoot":"","sources":["../../../src/impl/view-routing/store-fs-node-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAK7H"}

package/dist/impl/view-routing/store-fs-node-ref.js

@@ -0,0 +1,12 @@
+import { contentTypeOf, pathSteps } from '@hamak/shared-utils';
+/**
+ * The resolver input for a store-fs node, or `undefined` when the node is not
+ * a file. The content type comes from the file name's suffix.
+ */
+export function storeFsNodeRef(path, node) {
+    if (node === undefined || node.type !== 'file')
+        return undefined;
+    const steps = typeof path === 'string' ? pathSteps(path) : [...path];
+    const name = node.name ?? steps[steps.length - 1] ?? '';
+    return { path: steps, contentType: contentTypeOf(name), content: node.content, node };
+}

package/dist/impl/view-routing/view-resolver-registry.d.ts

@@ -0,0 +1,20 @@
+import type { DuplicateContribution, IViewResolverRegistry, Registration, ResolvedView, StoreFsNodeRef, ViewResolver } from '../../api/index.js';
+import type { DuplicateReporter } from './route-registry.js';
+/**
+ * View resolvers, keyed by id and asked by descending `priority`; equal
+ * priorities are asked in registration order. A resolver's `priority` is read
+ * when it is registered; to change it, unregister and register it again.
+ */
+export declare class ViewResolverRegistry<C = unknown> implements IViewResolverRegistry<C> {
+    private readonly resolvers;
+    /** The resolvers in asking order; cleared on every change. */
+    private ordered;
+    constructor(onDuplicate?: DuplicateReporter<ViewResolver<C>>);
+    register(resolver: ViewResolver<C>): Registration<ViewResolver<C>>;
+    unregister(id: string): boolean;
+    list(): readonly ViewResolver<C>[];
+    resolve(ref: StoreFsNodeRef): ResolvedView<C> | undefined;
+    duplicates(): readonly DuplicateContribution<ViewResolver<C>>[];
+    subscribe(listener: () => void): () => void;
+}
+//# sourceMappingURL=view-resolver-registry.d.ts.map

package/dist/impl/view-routing/view-resolver-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-resolver-registry.d.ts","sourceRoot":"","sources":["../../../src/impl/view-routing/view-resolver-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,YAAY,EACb,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,oBAAoB,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,qBAAqB,CAAC,CAAC,CAAC;IAChF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,8DAA8D;IAC9D,OAAO,CAAC,OAAO,CAAyC;gBAE5C,WAAW,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAW5D,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAIlE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,IAAI,IAAI,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE;IASlC,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;IAWzD,UAAU,IAAI,SAAS,qBAAqB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE;IAI/D,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAG5C"}

package/dist/impl/view-routing/view-resolver-registry.js

@@ -0,0 +1,56 @@
+import { ContributionRegistry } from './contribution-registry.js';
+/**
+ * View resolvers, keyed by id and asked by descending `priority`; equal
+ * priorities are asked in registration order. A resolver's `priority` is read
+ * when it is registered; to change it, unregister and register it again.
+ */
+export class ViewResolverRegistry {
+    constructor(onDuplicate) {
+        Object.defineProperty(this, "resolvers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The resolvers in asking order; cleared on every change. */
+        Object.defineProperty(this, "ordered", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.resolvers = new ContributionRegistry((resolver) => resolver.id, 'view resolver', onDuplicate, () => {
+            this.ordered = undefined;
+        });
+    }
+    register(resolver) {
+        return this.resolvers.add(resolver);
+    }
+    unregister(id) {
+        return this.resolvers.removeKey(id);
+    }
+    list() {
+        this.ordered ?? (this.ordered = this.resolvers
+            .list()
+            .map((resolver, index) => ({ resolver, index }))
+            .sort((a, b) => (b.resolver.priority ?? 0) - (a.resolver.priority ?? 0) || a.index - b.index)
+            .map(({ resolver }) => resolver));
+        return [...this.ordered];
+    }
+    resolve(ref) {
+        this.list();
+        for (const resolver of this.ordered) {
+            const component = resolver.resolve(ref);
+            if (component !== undefined && component !== null) {
+                return { resolver, component };
+            }
+        }
+        return undefined;
+    }
+    duplicates() {
+        return this.resolvers.duplicates();
+    }
+    subscribe(listener) {
+        return this.resolvers.subscribe(listener);
+    }
+}

package/dist/impl/view-routing/view-routing-plugin.d.ts

@@ -0,0 +1,17 @@
+import type { PluginModule } from '@hamak/microkernel-spi';
+import { RouteRegistry, type DuplicateReporter } from './route-registry.js';
+import { ViewResolverRegistry } from './view-resolver-registry.js';
+import type { RouteContribution, ViewResolver } from '../../api/index.js';
+export interface ViewRoutingPluginOptions<C = unknown> {
+    routes?: RouteRegistry<C>;
+    resolvers?: ViewResolverRegistry<C>;
+    onDuplicateRoute?: DuplicateReporter<RouteContribution<C>>;
+    onDuplicateResolver?: DuplicateReporter<ViewResolver<C>>;
+}
+/**
+ * Provides {@link ROUTE_REGISTRY_TOKEN} and {@link VIEW_RESOLVER_REGISTRY_TOKEN}.
+ * Plugins that contribute routes or resolvers list this plugin in `dependsOn`
+ * and register from their own `initialize()`.
+ */
+export declare function createViewRoutingPlugin<C = unknown>(options?: ViewRoutingPluginOptions<C>): PluginModule;
+//# sourceMappingURL=view-routing-plugin.d.ts.map

package/dist/impl/view-routing/view-routing-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-routing-plugin.d.ts","sourceRoot":"","sources":["../../../src/impl/view-routing/view-routing-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEjE,MAAM,WAAW,wBAAwB,CAAC,CAAC,GAAG,OAAO;IACnD,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,SAAS,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACpC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,mBAAmB,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,GAAE,wBAAwB,CAAC,CAAC,CAAM,GAAG,YAAY,CAY5G"}

package/dist/impl/view-routing/view-routing-plugin.js

@@ -0,0 +1,21 @@
+import { ROUTE_REGISTRY_TOKEN, VIEW_RESOLVER_REGISTRY_TOKEN } from '../../api/index.js';
+import { RouteRegistry } from './route-registry.js';
+import { ViewResolverRegistry } from './view-resolver-registry.js';
+/**
+ * Provides {@link ROUTE_REGISTRY_TOKEN} and {@link VIEW_RESOLVER_REGISTRY_TOKEN}.
+ * Plugins that contribute routes or resolvers list this plugin in `dependsOn`
+ * and register from their own `initialize()`.
+ */
+export function createViewRoutingPlugin(options = {}) {
+    const routes = options.routes ?? new RouteRegistry(options.onDuplicateRoute);
+    const resolvers = options.resolvers ?? new ViewResolverRegistry(options.onDuplicateResolver);
+    return {
+        initialize(ctx) {
+            ctx.provide({ provide: ROUTE_REGISTRY_TOKEN, useValue: routes });
+            ctx.provide({ provide: VIEW_RESOLVER_REGISTRY_TOKEN, useValue: resolvers });
+        },
+        activate() {
+            /* registries are live from initialize */
+        },
+    };
+}

package/dist/templates/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @hamak/ui-shell/react
+ * React bindings for contributed routes and store-fs view resolution.
+ */
+export * from './view-routing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,gBAAgB,CAAC"}

package/dist/templates/index.js

@@ -0,0 +1,5 @@
+/**
+ * @hamak/ui-shell/react
+ * React bindings for contributed routes and store-fs view resolution.
+ */
+export * from './view-routing.js';

package/dist/templates/view-routing.d.ts

@@ -0,0 +1,65 @@
+import { type ComponentType, type ReactNode } from 'react';
+import { type DirectoryNode, type FileSystemNode } from '@hamak/shared-utils';
+import type { IRouteRegistry, IViewResolverRegistry, RouteContribution, StoreFsNodeRef } from '../api/index.js';
+/** Props of a component a view resolver returns. */
+export interface ResolvedViewProps<T = unknown> {
+    node: StoreFsNodeRef<T>;
+}
+export type ViewComponent = ComponentType<ResolvedViewProps<any>>;
+export type RouteComponent = ComponentType<any>;
+export interface ViewRoutingContextValue {
+    routes?: IRouteRegistry<RouteComponent>;
+    resolvers?: IViewResolverRegistry<ViewComponent>;
+}
+export declare const ViewRoutingContext: import("react").Context<ViewRoutingContextValue>;
+export interface ViewRoutingProviderProps extends ViewRoutingContextValue {
+    children?: ReactNode;
+}
+/** Makes the registries available to {@link ContentView} and the hooks below. */
+export declare function ViewRoutingProvider({ routes, resolvers, children }: ViewRoutingProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<ViewRoutingContextValue>>;
+/** The contributed routes, re-read whenever the registry changes. */
+export declare function useRouteContributions(registry?: IRouteRegistry<RouteComponent>): readonly RouteContribution<RouteComponent>[];
+/** The part of a store-fs facade {@link ContentView} reads through. */
+export interface StoreFsNodeSelectorFactory {
+    createSelector(path: string | string[]): (state: any) => FileSystemNode | undefined;
+}
+/** What {@link ContentView} renders when no resolver claims a file: its content, as text. */
+export declare function DefaultContentView({ node }: ResolvedViewProps): import("react").ReactElement<{
+    'data-content-type': string;
+}, string | import("react").JSXElementConstructor<any>>;
+export interface ContentViewProps {
+    /** The store-fs path of the node to display. */
+    path: string | string[];
+    fs: StoreFsNodeSelectorFactory;
+    /** Defaults to the registry of the enclosing {@link ViewRoutingProvider}. */
+    resolvers?: IViewResolverRegistry<ViewComponent>;
+    /** Rendered for a file no resolver claims. Defaults to {@link DefaultContentView}. */
+    fallback?: ViewComponent;
+    /** Rendered for a directory node. Defaults to nothing. */
+    directory?: ComponentType<{
+        path: string[];
+        node: DirectoryNode;
+    }>;
+    /** Rendered while the path names no node. Defaults to nothing. */
+    missing?: ReactNode;
+}
+/**
+ * The generic content route: observes one store-fs node and renders the
+ * component the view resolvers return for it. A path that runs past a file
+ * (`a.json/nope`, `a.json/a.json`) names no node and renders `missing`.
+ *
+ * It reads the store and nothing else. A change to the node re-renders the view
+ * with the new content, and loading the node is the host's business: this
+ * component dispatches nothing. A resolver registered or removed later takes
+ * effect on the next render; with every resolver passing, `fallback` renders.
+ *
+ * Resolvers should return a stable component (not one created per call), or
+ * the view remounts on every change.
+ */
+export declare function ContentView({ path, fs, resolvers, fallback, directory, missing }: ContentViewProps): import("react").FunctionComponentElement<{
+    children?: ReactNode | undefined;
+}> | import("react").ReactElement<{
+    path: string[];
+    node: DirectoryNode;
+}, string | import("react").JSXElementConstructor<any>> | import("react").ReactElement<ResolvedViewProps<any>, string | import("react").JSXElementConstructor<any>> | null;
+//# sourceMappingURL=view-routing.d.ts.map

package/dist/templates/view-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-routing.d.ts","sourceRoot":"","sources":["../../src/templates/view-routing.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACf,MAAM,QAAQ,CAAC;AAGhB,oDAAoD;AACpD,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;AAEhD,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,kBAAkB,kDAA6C,CAAC;AAE7E,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;IACvE,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,wBAAwB,oGAG5F;AAcD,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,QAAQ,CAAC,EAAE,cAAc,CAAC,cAAc,CAAC,GACxC,SAAS,iBAAiB,CAAC,cAAc,CAAC,EAAE,CAM9C;AAED,uEAAuE;AACvE,MAAM,WAAW,0BAA0B;IACzC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,cAAc,GAAG,SAAS,CAAC;CACrF;AAsBD,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE,iBAAiB;;wDAG7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,EAAE,EAAE,0BAA0B,CAAC;IAC/B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACjD,sFAAsF;IACtF,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IACnE,kEAAkE;IAClE,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,QAA6B,EAAE,SAAS,EAAE,OAAc,EAAE,EAAE,gBAAgB;;;UAlB3F,MAAM,EAAE;UAAQ,aAAa;2KAwChE"}

package/dist/templates/view-routing.js

@@ -0,0 +1,89 @@
+import { createContext, createElement, Fragment, useContext, useEffect, useMemo, useState, } from 'react';
+import { useSelector } from 'react-redux';
+import { pathSteps } from '@hamak/shared-utils';
+import { storeFsNodeRef } from '../impl/view-routing/store-fs-node-ref.js';
+export const ViewRoutingContext = createContext({});
+/** Makes the registries available to {@link ContentView} and the hooks below. */
+export function ViewRoutingProvider({ routes, resolvers, children }) {
+    const value = useMemo(() => ({ routes, resolvers }), [routes, resolvers]);
+    return createElement(ViewRoutingContext.Provider, { value }, children);
+}
+/** A counter that moves on every registry change, so readers re-render. */
+function useRegistryVersion(registry) {
+    const [version, setVersion] = useState(0);
+    useEffect(() => {
+        if (registry === undefined)
+            return undefined;
+        // A change between render and subscription would otherwise be missed.
+        setVersion((v) => v + 1);
+        return registry.subscribe(() => setVersion((v) => v + 1));
+    }, [registry]);
+    return version;
+}
+/** The contributed routes, re-read whenever the registry changes. */
+export function useRouteContributions(registry) {
+    const contextRoutes = useContext(ViewRoutingContext).routes;
+    const routes = registry ?? contextRoutes;
+    const version = useRegistryVersion(routes);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return useMemo(() => routes?.list() ?? [], [routes, version]);
+}
+/**
+ * Selects the node at exactly `steps`. A store-fs selector stops at a file and
+ * returns it for any deeper step, so `a.json/nope` and even `a.json/a.json`
+ * would select `a.json`. The node only counts when the parent path selects a
+ * directory holding it under the last step; past a file, the parent path
+ * selects that file instead. The result is the node itself (or `undefined`),
+ * so a change to a sibling does not re-render.
+ */
+function strictNodeSelector(fs, steps) {
+    const nodeAt = fs.createSelector(steps);
+    if (steps.length === 0)
+        return nodeAt;
+    const parentAt = fs.createSelector(steps.slice(0, -1));
+    const name = steps[steps.length - 1];
+    return (state) => {
+        const node = nodeAt(state);
+        const parent = parentAt(state);
+        return node !== undefined && parent?.type === 'directory' && parent.children[name] === node ? node : undefined;
+    };
+}
+/** What {@link ContentView} renders when no resolver claims a file: its content, as text. */
+export function DefaultContentView({ node }) {
+    const text = typeof node.content === 'string' ? node.content : JSON.stringify(node.content, null, 2);
+    return createElement('pre', { 'data-content-type': node.contentType }, text ?? '');
+}
+/**
+ * The generic content route: observes one store-fs node and renders the
+ * component the view resolvers return for it. A path that runs past a file
+ * (`a.json/nope`, `a.json/a.json`) names no node and renders `missing`.
+ *
+ * It reads the store and nothing else. A change to the node re-renders the view
+ * with the new content, and loading the node is the host's business: this
+ * component dispatches nothing. A resolver registered or removed later takes
+ * effect on the next render; with every resolver passing, `fallback` renders.
+ *
+ * Resolvers should return a stable component (not one created per call), or
+ * the view remounts on every change.
+ */
+export function ContentView({ path, fs, resolvers, fallback = DefaultContentView, directory, missing = null }) {
+    const contextResolvers = useContext(ViewRoutingContext).resolvers;
+    const registry = resolvers ?? contextResolvers;
+    const version = useRegistryVersion(registry);
+    const pathKey = JSON.stringify(path);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const steps = useMemo(() => pathSteps(path), [pathKey]);
+    const selector = useMemo(() => strictNodeSelector(fs, steps), [fs, steps]);
+    const node = useSelector(selector);
+    const ref = useMemo(() => storeFsNodeRef(path, node), [node, pathKey]); // eslint-disable-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const resolved = useMemo(() => (ref === undefined ? undefined : registry?.resolve(ref)), [registry, version, ref]);
+    if (node === undefined)
+        return createElement(Fragment, null, missing);
+    if (node.type === 'directory') {
+        return directory === undefined
+            ? null
+            : createElement(directory, { path: steps, node });
+    }
+    return createElement(resolved?.component ?? fallback, { node: ref });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamak/ui-shell",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "UI Shell Framework with theming, routing, and layout management",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,6 +20,11 @@
       "types": "./dist/spi/index.d.ts",
       "import": "./dist/spi/index.js",
       "default": "./dist/spi/index.js"
+    },
+    "./react": {
+      "types": "./dist/templates/index.d.ts",
+      "import": "./dist/templates/index.js",
+      "default": "./dist/templates/index.js"
     }
   },
   "typesVersions": {
@@ -29,6 +34,9 @@
       ],
       "spi": [
         "./dist/spi/index.d.ts"
+      ],
+      "react": [
+        "./dist/templates/index.d.ts"
       ]
     }
   },
@@ -45,7 +53,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json && node ../../scripts/fix-esm-extensions.mjs ./dist",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "vitest run"
   },
   "keywords": [
     "ui-shell",
@@ -59,9 +68,31 @@
   "license": "MIT",
   "dependencies": {
     "@hamak/microkernel-api": "*",
-    "@hamak/microkernel-spi": "*"
+    "@hamak/microkernel-spi": "*",
+    "@hamak/shared-utils": "*"
   },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "react-redux": "^9.1.0",
+    "vitest": "^2.0.0",
+    "@hamak/microkernel-impl": "*",
+    "@hamak/ui-store": "*",
+    "@reduxjs/toolkit": "^2.0.0",
+    "@testing-library/react": "^14.0.0",
+    "jsdom": "^27.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-redux": "^9.1.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-redux": {
+      "optional": true
+    }
   }
 }