@swimmesberger/elarion-contributions 0.2.3-preview.72.1 → 0.2.3-preview.74.1

package/README.md

@@ -6,9 +6,14 @@ typed extension-point tokens, declarative module manifests, and capability-gated
 It extends the backend's review-isolation rule — *a module only touches its own code* — to the frontend:
 adding a sidebar item or a cross-module action edits one file in the owning module, never the shell.
 
-- **Framework-free core** (`@swimmesberger/elarion-contributions`) — no dependencies, no React.
+- **Framework-free core** (`@swimmesberger/elarion-contributions`) — no dependencies, no React. `when`
+  clauses are typed **strictly** against your vocabulary (a typo'd permission is a compile error, and
+  vocabulary axes are optional — a no-auth app binds `{ module }` only and any stray axis use fails to
+  compile), `ItemOf`/`ContextOf` extract a point's declared types, and `createStaticCapabilities` is
+  the `CapabilityReader` for apps without a session snapshot yet.
 - **React bindings** (`@swimmesberger/elarion-contributions/react`) — `ContributionProvider`,
-  `useContributions`, `<ExtensionSlot>`. React is an optional peer dependency; other view frameworks
+  `useContributions`, `<ExtensionSlot>` (its `context` prop is type-checked against the point's
+  `TContext` and handed to the render prop). React is an optional peer dependency; other view frameworks
   can port the bindings in a page of code.
 - **Angular bindings** (`@swimmesberger/elarion-contributions/angular`) — `provideContributions`,
   `injectContributions` (returns a `Signal`). Idiomatic for Angular 20–22: signal-first, standalone,
@@ -25,6 +30,14 @@ adding a sidebar item or a cross-module action edits one file in the owning modu
 npm install @swimmesberger/elarion-contributions
 ```
 
+> [!IMPORTANT]
+> **Vite users:** the `/react` bindings call hooks, so they must resolve to your app's **single** React
+> instance. If the first `useContributions` throws `Invalid hook call … Cannot read properties of null
+> (reading 'useContext')`, Vite's dependency optimizer pre-bundled the package against a second React
+> copy. Add `resolve: { dedupe: ["react", "react-dom"] }` plus an `optimizeDeps.include` entry for the
+> package (and its `/react` sub-export) to `vite.config.ts`, then clear `node_modules/.vite`. Vite does
+> not consult peer-dependency metadata when pre-bundling, so there is no package-side fix.
+
 ## What you import vs. what you own
 
 This package ships the *machinery* with fixed semantics; your application owns the *points* and the shell
@@ -32,10 +45,11 @@ This package ships the *machinery* with fixed semantics; your application owns t
 
 | You import (fixed semantics) | You own (copy from the sample) |
 | --- | --- |
-| `defineExtensionPoint`, `defineModule`, `contribute` | Your extension points (`sidebarItems`, …) and their payload types |
-| `evaluateWhen` + the `when` AND semantics | The kit instantiation binding your generated vocabulary |
-| `createContributionRegistry` (filter + deterministic order) | The app shell that renders each slot |
-| `ContributionProvider` / `useContributions` / `<ExtensionSlot>` (React) | Route composition and module discovery (e.g. `import.meta.glob`) |
+| `defineExtensionPoint`, `defineModule`, `contribute`, `ItemOf`/`ContextOf` | Your extension points (`sidebarItems`, …) and their payload types |
+| `evaluateWhen` + the strict `when` AND semantics | The kit instantiation binding your (generated or hand-authored) vocabulary |
+| `createContributionRegistry` (filter + deterministic order + id validation) | The app shell that renders each slot |
+| `createStaticCapabilities` (the no-snapshot `CapabilityReader`) | The real snapshot wiring once `elarion.session` exists |
+| `ContributionProvider` / `useContributions` / `<ExtensionSlot context=…>` (React) | Route composition and module discovery (e.g. `import.meta.glob`) |
 | `provideContributions` / `injectContributions` (Angular) | Slot rendering — an `@for` block, or a small `*extensionSlot` directive you own (see below) |
 | `redirectUnless` route guard (`/tanstack-router`) | Everything else routing — the router's own API |
 
@@ -59,6 +73,12 @@ export type AppManifest = ModuleManifest<AppVocabulary>
 export const { defineModule, defineExtensionPoint, contribute } = createContributionKit<AppVocabulary>()
 ```
 
+Declare only the axes your application has — they are all optional, and `when` clauses are checked
+**strictly**: a typo'd name or a clause on an undeclared axis is a compile error, not a silently hidden
+item. No auth and no generated `session-client.ts` yet? Bind `{ module: ModuleName }` with a hand-authored
+union and use `createStaticCapabilities()` as the reader (modules/permissions/roles default `"all"`, flags
+default none); swap in the generated `SessionCapabilities` later — same structural interface.
+
 Declare a point where the *owner* of the slot lives (the shell for a sidebar, a module for its own
 extension surface), and export the token from the owner's public entry. The payload shape is yours —
 whatever your shell needs to render:
@@ -99,6 +119,16 @@ const registry = createContributionRegistry(appModules.map((m) => m.manifest), c
 const items = useContributions(sidebarItems)
 ```
 
+When a point declares a slot context (`defineExtensionPoint<TItem, TContext>`), the slot site supplies it
+through `<ExtensionSlot context=…>` — type-checked against `TContext` and handed to the render prop — and
+payloads pin their signatures to the declaration with `ContextOf`:
+
+```tsx
+// the point: export const stackDetailTabs = defineExtensionPoint<StackTab, { stack: Stack }>("stacks.detailTabs")
+// the payload type: component: (context: ContextOf<typeof stackDetailTabs>) => ReactNode
+<ExtensionSlot point={stackDetailTabs} context={{ stack }} render={(tab, ctx) => tab.component(ctx)} />
+```
+
 ## Angular
 
 Same kernel, idiomatic Angular surface. `provideContributions` is an environment provider (shaped like
@@ -178,9 +208,14 @@ export class ExtensionSlotDirective<TItem> {
 - **`when` is AND** across its fields (`module`, `permission`, `flag`, `role`), mirroring
   `[RequirePermission]`/`[RequireRole]`/`[FeatureGate]`; a manifest-level `when` is ANDed into every
   contribution. Absent capabilities fail closed.
-- **Resolution is pure and deterministic**: contributions sort by `order` (default 0), then `id`, then
-  contributing module name, using code-unit comparison — the same input renders the same UI on server
-  and client. Refreshing the snapshot means building a new registry.
+- **`when` is strictly typed** against the kit's vocabulary: out-of-vocabulary names do not compile
+  (fail-closed evaluation would otherwise turn a typo into invisibly hidden UI). Only a manifest's
+  `name` accepts free strings — it is an identity, not a lookup.
+- **Resolution is pure and deterministic**: contributions sort by `order` (default 0), then `id`, using
+  code-unit comparison — the same input renders the same UI on server and client. Two co-visible
+  contributions to one point sharing an id throw at resolution (ids double as render keys); prefix ids
+  with the module name (`"invoicing.create-invoice"`). Refreshing the snapshot means building a new
+  registry.
 - **UX projection, never security.** A hidden contribution is not a secured operation — the backend
   handler's own gates are the enforcement on every call.
 

package/dist/index.d.ts

@@ -1,24 +1,42 @@
 /**
  * The capability vocabulary a contribution kit is typed against — supplied by the application from the
- * generated literal unions in `session-client.ts` (ModuleName/PermissionName/FlagName/RoleName).
+ * generated literal unions in `session-client.ts` (ModuleName/PermissionName/FlagName/RoleName). Declare
+ * only the axes the application actually has: an omitted (or `never`) axis makes every `when` use of it
+ * a compile error, so a no-auth app binding `{ module: ModuleName }` gets a real error on a stray
+ * permission/flag/role clause instead of a silently hidden item.
  */
 export interface Vocabulary {
-    module: string;
-    permission: string;
-    flag: string;
-    role: string;
+    module?: string;
+    permission?: string;
+    flag?: string;
+    role?: string;
 }
-/** Keeps literal-union autocomplete while accepting out-of-vocabulary names (the generated accessors' shape). */
+/**
+ * Keeps literal-union autocomplete while accepting out-of-vocabulary names. Used only where a name is an
+ * *identity* (a UI-only module's `name`), never where it is a capability lookup — a lookup outside the
+ * vocabulary is exactly the drift `when` typing exists to catch.
+ */
 type Hint<T extends string> = T | (string & {});
+/**
+ * One `when`-clause axis: exactly the vocabulary's names. `Extract` keeps the unbound default permissive
+ * (`Vocabulary`'s optional `string` axes stay plain `string`) while an omitted or `never` axis reduces to
+ * `never` — unusable, by design.
+ */
+type Axis<V extends Vocabulary, K extends keyof Vocabulary> = Extract<V[K], string>;
 /**
  * The declarative visibility condition of a contribution — the frontend mirror of
  * `[RequirePermission]`/`[RequireRole]`/`[FeatureGate]`: every present field must hold (AND).
+ *
+ * Axes are checked strictly against the vocabulary: a typo'd or out-of-vocabulary name is a compile
+ * error, not a silently hidden item (the evaluator fails closed, so a wrong name would never surface at
+ * runtime either). Deliberately stricter than the generated snapshot accessors, which accept
+ * `Name | (string & {})`.
  */
 export interface WhenClause<V extends Vocabulary = Vocabulary> {
-    readonly module?: Hint<V["module"]>;
-    readonly permission?: Hint<V["permission"]>;
-    readonly flag?: Hint<V["flag"]>;
-    readonly role?: Hint<V["role"]>;
+    readonly module?: Axis<V, "module">;
+    readonly permission?: Axis<V, "permission">;
+    readonly flag?: Axis<V, "flag">;
+    readonly role?: Axis<V, "role">;
 }
 /**
  * The snapshot surface resolution reads — structurally satisfied by the `SessionCapabilities` class the
@@ -31,6 +49,34 @@ export interface CapabilityReader {
     isFlagEnabled(name: string): boolean;
 }
 export declare function evaluateWhen(when: WhenClause | undefined, capabilities: CapabilityReader): boolean;
+/** One axis of {@link createStaticCapabilities}: everything, an allow-list, or an explicit on/off map. */
+export type StaticCapabilitySet = "all" | ReadonlyArray<string> | Readonly<Record<string, boolean>>;
+/**
+ * A fixed {@link CapabilityReader} for applications without a session snapshot — self-hosted/no-auth
+ * deployments, tests, stories. Modules, permissions, and roles default to `"all"` (a no-auth app shows
+ * everything it ships); flags default to none, because a flag-gated contribution should stay hidden until
+ * the flag system that owns it exists (`when` stays fail-closed).
+ *
+ * This is a static snapshot by design, resolved once at composition. When the backend ships the
+ * `elarion.session` operation, swap it for the generated `SessionCapabilities` — same structural
+ * interface, nothing else changes.
+ *
+ * @example
+ * ```ts
+ * // Everything on (e.g. behind an authenticating reverse proxy):
+ * const capabilities = createStaticCapabilities()
+ * // Env-driven module toggles; permissions/roles open, flags off:
+ * const capabilities = createStaticCapabilities({
+ *   modules: { core: true, "ai-agent": import.meta.env.VITE_MODULE_AI_AGENT_ENABLED !== "false" },
+ * })
+ * ```
+ */
+export declare function createStaticCapabilities(init?: {
+    readonly modules?: StaticCapabilitySet;
+    readonly permissions?: StaticCapabilitySet;
+    readonly roles?: StaticCapabilitySet;
+    readonly flags?: StaticCapabilitySet;
+}): CapabilityReader;
 declare const CONTRIBUTION: unique symbol;
 declare const SLOT_CONTEXT: unique symbol;
 /**
@@ -49,11 +95,24 @@ export interface ExtensionPoint<TItem, TContext = void> {
     readonly [SLOT_CONTEXT]?: TContext;
 }
 export declare function defineExtensionPoint<TItem, TContext = void>(id: string): ExtensionPoint<TItem, TContext>;
+/** The payload type an extension point accepts — `ItemOf<typeof sidebarItems>`. */
+export type ItemOf<P extends ExtensionPoint<unknown, unknown>> = P extends ExtensionPoint<infer TItem, infer _TContext> ? TItem : never;
+/**
+ * The slot context an extension point declares — `ContextOf<typeof stackDetailTabs>`. Reference it in the
+ * point's payload signatures (`component: (context: ContextOf<typeof stackDetailTabs>) => ReactNode`) and
+ * receive it from the slot (`<ExtensionSlot context={…}>` in the React bindings), so the payload, the
+ * point, and the slot site can never drift apart.
+ */
+export type ContextOf<P extends ExtensionPoint<unknown, unknown>> = P extends ExtensionPoint<infer _TItem, infer TContext> ? TContext : never;
 /** A single contribution: the point's payload plus identity, ordering, and visibility. */
 export type Contribution<TItem, V extends Vocabulary = Vocabulary> = TItem & {
-    /** Unique within the point across all modules; part of the deterministic sort key. */
+    /**
+     * Unique within the point among co-visible contributions (enforced when the registry resolves — ids
+     * double as render keys). Prefix with the contributing module's name, e.g. `"invoicing.create-invoice"`,
+     * to stay collision-free across modules.
+     */
     readonly id: string;
-    /** Ascending sort rank (default 0); ties break by id, then by contributing module name. */
+    /** Ascending sort rank (default 0); ties break by id. */
     readonly order?: number;
     /** Visibility condition, ANDed with the contributing module's manifest-level `when`. */
     readonly when?: WhenClause<V>;
@@ -72,7 +131,7 @@ export declare function contribute<TItem, TContext, V extends Vocabulary = Vocab
  */
 export interface ModuleManifest<V extends Vocabulary = Vocabulary> {
     /** The module's name — its backend [AppModule] name when it mirrors one, any unique name when UI-only. */
-    readonly name: Hint<V["module"]>;
+    readonly name: Hint<Axis<V, "module">>;
     /**
      * Module-level visibility, ANDed into every contribution. A backend-paired module gates itself here once
      * — `when: { module: Modules.X }` — so disabling the backend module removes the whole frontend module;
@@ -91,8 +150,12 @@ export interface ContributionRegistry {
  * (manifests, capabilities) input yields the same registry, so a server render and the client hydration
  * produce identical trees. Refreshing the snapshot (login, context change) means building a new registry,
  * the same contract as the generated session provider.
+ *
+ * Resolution validates that no two co-visible contributions to one point share an id (ids double as
+ * render keys and as the deterministic tiebreak) and throws on a collision — manifests are static data,
+ * so a collision is a data bug that fails fast here rather than corrupting keyed rendering downstream.
  */
-export declare function createContributionRegistry(manifests: ReadonlyArray<ModuleManifest>, capabilities: CapabilityReader): ContributionRegistry;
+export declare function createContributionRegistry<V extends Vocabulary = Vocabulary>(manifests: ReadonlyArray<ModuleManifest<V>>, capabilities: CapabilityReader): ContributionRegistry;
 /** The vocabulary-bound facade of the kernel — created once by the application, imported by every module. */
 export interface ContributionKit<V extends Vocabulary> {
     defineModule(manifest: ModuleManifest<V>): ModuleManifest<V>;

package/dist/index.js

@@ -22,6 +22,47 @@ export function evaluateWhen(when, capabilities) {
         return false;
     return true;
 }
+/**
+ * A fixed {@link CapabilityReader} for applications without a session snapshot — self-hosted/no-auth
+ * deployments, tests, stories. Modules, permissions, and roles default to `"all"` (a no-auth app shows
+ * everything it ships); flags default to none, because a flag-gated contribution should stay hidden until
+ * the flag system that owns it exists (`when` stays fail-closed).
+ *
+ * This is a static snapshot by design, resolved once at composition. When the backend ships the
+ * `elarion.session` operation, swap it for the generated `SessionCapabilities` — same structural
+ * interface, nothing else changes.
+ *
+ * @example
+ * ```ts
+ * // Everything on (e.g. behind an authenticating reverse proxy):
+ * const capabilities = createStaticCapabilities()
+ * // Env-driven module toggles; permissions/roles open, flags off:
+ * const capabilities = createStaticCapabilities({
+ *   modules: { core: true, "ai-agent": import.meta.env.VITE_MODULE_AI_AGENT_ENABLED !== "false" },
+ * })
+ * ```
+ */
+export function createStaticCapabilities(init = {}) {
+    return {
+        isModuleEnabled: toPredicate(init.modules, true),
+        hasPermission: toPredicate(init.permissions, true),
+        hasRole: toPredicate(init.roles, true),
+        isFlagEnabled: toPredicate(init.flags, false),
+    };
+}
+function toPredicate(set, enabledByDefault) {
+    if (set === undefined)
+        return () => enabledByDefault;
+    if (set === "all")
+        return () => true;
+    if (Array.isArray(set)) {
+        const names = new Set(set);
+        return (name) => names.has(name);
+    }
+    // Array.isArray does not remove ReadonlyArray from the negated union (TS#17002), hence the assertion.
+    const map = set;
+    return (name) => map[name] === true;
+}
 export function defineExtensionPoint(id) {
     return { id };
 }
@@ -46,6 +87,10 @@ const EMPTY = [];
  * (manifests, capabilities) input yields the same registry, so a server render and the client hydration
  * produce identical trees. Refreshing the snapshot (login, context change) means building a new registry,
  * the same contract as the generated session provider.
+ *
+ * Resolution validates that no two co-visible contributions to one point share an id (ids double as
+ * render keys and as the deterministic tiebreak) and throws on a collision — manifests are static data,
+ * so a collision is a data bug that fails fast here rather than corrupting keyed rendering downstream.
  */
 export function createContributionRegistry(manifests, capabilities) {
     const byPoint = new Map();
@@ -68,9 +113,17 @@ export function createContributionRegistry(manifests, capabilities) {
     }
     const resolved = new Map();
     for (const [pointId, entries] of byPoint) {
-        entries.sort((a, b) => (a.item.order ?? 0) - (b.item.order ?? 0) ||
-            compareStrings(a.item.id, b.item.id) ||
-            compareStrings(a.module, b.module));
+        const contributors = new Map();
+        for (const entry of entries) {
+            const previous = contributors.get(entry.item.id);
+            if (previous !== undefined) {
+                throw new Error(`Duplicate contribution id "${entry.item.id}" on extension point "${pointId}" ` +
+                    `(contributed by module "${previous}" and module "${entry.module}"). Contribution ids must ` +
+                    `be unique within a point — prefix with the module name, e.g. "${entry.module}.${entry.item.id}".`);
+            }
+            contributors.set(entry.item.id, entry.module);
+        }
+        entries.sort((a, b) => (a.item.order ?? 0) - (b.item.order ?? 0) || compareStrings(a.item.id, b.item.id));
         resolved.set(pointId, entries.map((entry) => entry.item));
     }
     return {

package/dist/react.d.ts

@@ -6,8 +6,26 @@ export declare function ContributionProvider({ registry, children, }: {
 }): import("react").JSX.Element;
 /** The resolved contributions for a point — already filtered by `when` and deterministically ordered. */
 export declare function useContributions<TItem, TContext>(point: ExtensionPoint<TItem, TContext>): ReadonlyArray<Contribution<TItem>>;
-/** Renders a point's contributions through a render prop — sugar over {@link useContributions} for inline slots. */
-export declare function ExtensionSlot<TItem, TContext>({ point, render, }: {
+/**
+ * Renders a point's contributions through a render prop — sugar over {@link useContributions} for inline
+ * slots. When the point declares a slot context (`TContext`), pass it as `context` and the render prop
+ * receives it, typed, as its second argument — so what the slot site supplies can never drift from what
+ * the point declares:
+ *
+ * ```tsx
+ * <ExtensionSlot point={stackDetailTabs} context={{ stack }} render={(tab, ctx) => tab.component(ctx)} />
+ * ```
+ *
+ * Without `context`, the render prop takes only the item — for slots that render inert parts (buttons,
+ * menu entries) and hand the payload its context later, at invocation time.
+ */
+export declare function ExtensionSlot<TItem, TContext>(props: {
+    point: ExtensionPoint<TItem, TContext>;
+    /** The slot context the point declares — handed to `render` as the second argument. */
+    context: TContext;
+    render: (item: Contribution<TItem>, context: TContext) => ReactNode;
+}): ReactNode;
+export declare function ExtensionSlot<TItem, TContext>(props: {
     point: ExtensionPoint<TItem, TContext>;
     render: (item: Contribution<TItem>) => ReactNode;
-}): import("react").JSX.Element;
+}): ReactNode;

package/dist/react.js

@@ -15,8 +15,10 @@ export function useContributions(point) {
         throw new Error("useContributions requires a <ContributionProvider> above it.");
     return registry.get(point);
 }
-/** Renders a point's contributions through a render prop — sugar over {@link useContributions} for inline slots. */
-export function ExtensionSlot({ point, render, }) {
-    const items = useContributions(point);
-    return (_jsx(_Fragment, { children: items.map((item) => (_jsx(Fragment, { children: render(item) }, item.id))) }));
+// Overloads rather than a props union: JSX contextually types the render prop per overload, where a
+// union would leave the render parameters implicitly `any`. The context form must come first — JSX
+// falls through cleanly on its *missing* `context` prop, but would not fall through past an *excess* one.
+export function ExtensionSlot(props) {
+    const items = useContributions(props.point);
+    return (_jsx(_Fragment, { children: items.map((item) => (_jsx(Fragment, { children: props.render(item, props.context) }, item.id))) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swimmesberger/elarion-contributions",
-  "version": "0.2.3-preview.72.1",
+  "version": "0.2.3-preview.74.1",
   "description": "The Elarion frontend contribution model: typed extension points, declarative module manifests, and capability-gated resolution — framework-free core with React bindings under /react and Angular bindings under /angular.",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,8 +28,8 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "test": "npm run typecheck && vitest run",
     "prepack": "npm run build",
     "prepare": "npm run build"
   },