# Freelens extension API — contracts This is the **normative** half of the extension specification of Freelens 2: what the host guarantees, what surface an extension may rely on, and what happens when a contract is violated. The developer-facing porting guide is [`docs/extensions/migrating-from-v1.md`](./migrating-from-v1.md); the binary side is [`docs/extensions/binaries.md`](./binaries.md). **No compatibility is promised for v1 extensions.** The migration guide is what they get instead. ## How to read this document Each contract states three things: - **Guarantee** — what the host promises. - **Surface** — the stable names the guarantee is expressed in. - **Failure mode** — what an author sees when the contract is violated. This is recorded because most of these fail at runtime rather than at build time, and several fail _silently_. Anything not stated here is not part of the contract. Extensions run with full privileges and can reach much more than this document describes; reaching it is not supported, and it may change without notice. --- ## C1. Packaging and publication **Guarantee.** `@freelensapp/extensions` is the **only** published package of this repository. Every other `@freelensapp/*` package is private and must never appear in an extension's dependencies. **Surface.** One package, two files: `dist/extension-api.d.ts` (the rolled-up declaration) and `dist/extension-api.js` (the runtime shim, with no dependencies). The bundled declaration is what makes the single-package model work rather than merely assert it: `rolldown.dts.config.mjs` maps every workspace entry to its emitted declaration and its `external` predicate returns false for them, so every `@freelensapp/*` is inlined. Nothing else needs publishing. **Failure mode.** A direct dependency on any other `@freelensapp/*` package fails to install — the package does not exist on the registry. **Consequence worth stating separately.** Because workspace packages are private _and_ inlined, **a symbol the API namespaces do not re-export is unreachable by any means.** There is no package left to install and a type-only import fails at module resolution with no `@types/` fallback. Re-export completeness is therefore a correctness property, not a convenience. See [C5](#c5-namespace-enumeration). --- ## C2. The runtime-global API **Guarantee.** The host assigns one object at startup, in each process: ```ts // main (freelens/src/main/index.ts) globalThis.FreelensExtensionApi = { Common, Main, ...mainExtensionApiSingletons }; // renderer (freelens/src/renderer/index.ts) globalThis.FreelensExtensionApi = { Common, Renderer, ...rendererExtensionApiSingletons }; ``` The singletons of [C3](#c3-host-provided-singletons) ride on the same object rather than on globals of their own: one object to publish, one place in the contract, and it is what the shim already reads. `@freelensapp/extensions` is a thin shim that re-exports that global, so the members resolve identically whether an extension inlines the shim or marks it external. The import specifier does not change from v1: ```ts import { Common, Main, Renderer } from "@freelensapp/extensions"; ``` **Surface.** `Common`, `Main`, `Renderer` — as values and as type namespaces (`Renderer.Component.IconProps`, `Common.PackageJson`). **Failure mode.** The wrong-process namespace is `undefined` **at runtime** while the types expose the full surface, so `Main.Util.fetch` in a renderer entry type-checks and throws `Cannot read properties of undefined`. Touch only the namespace for the process your code runs in. --- ## C3. Host-provided singletons **Guarantee.** The host publishes its singleton libraries on the **same** global object. An extension declares them in `devDependencies` for compilation only, marks them external, and lets its bundler rewrite the bare id to the global. **Surface.** A closed list of module ids: | Module id | Global | Published in | | ------------------- | ----------------- | ------------ | | `react` | `React` | renderer | | `react-dom` | `ReactDom` | renderer | | `react/jsx-runtime` | `ReactJsxRuntime` | renderer | | `mobx` | `Mobx` | both | | `mobx-react` | `MobxReact` | renderer | | `monaco-editor` | `MonacoEditor` | renderer | An extension declares a listed package also when it does not import it but uses a host API whose types name it: `Renderer.Component.MonacoEditor` takes its `options` and the arguments of its callbacks from `monaco-editor`, so an extension that renders it declares `monaco-editor`, at the host's version ([C11](#c11-third-party-bundled-libraries)). **Each process publishes the set it has**, which is why the third column exists. Main has no window, so it publishes no DOM renderer and no code editor. What it has is what an extension's main entry point can really share: `mobx`, where an extension's stores and catalog entities live. **A package belongs on this list if two instances of it misbehave.** React (hook and reconciler identity), mobx (observable identity), monaco (global theme and worker registration). Nothing else in the API's dependency set meets it. **The names follow a mechanical rule:** strip the scope, split on `-`, `/` and `.`, upper-case each segment, so `react-dom` is `ReactDom` and `react/jsx-runtime` is `ReactJsxRuntime`. The host asserts at startup that every key it publishes follows the rule, so a bundler plugin can derive each name from the specifier instead of carrying a map. These ids are **not** on the list, and an extension that still maps one of them to the global gets `undefined` at runtime, not a build error: - **`@freelensapp/extensions`** — the package is a thin shim that already reads the global, so bundling it is correct. - **`react-router` and `react-router-dom`** — not dependencies of the host. An extension that wants them bundles its own ([C9](#c9-routing)). - **`node-pty`** — v2 publishes no `Pty` global. An extension that needs to run a program uses `node:child_process` in its main entry point (see [`docs/extensions/binaries.md`](./binaries.md)). - **`@ogre-tools/injectable` and `@ogre-tools/injectable-react`** — the host's dependency-injection library, which it keeps as an implementation detail (see [C7](#c7-the-dependency-injection-surface)). An extension that uses them bundles its own copy, at any version. **The process entries export nothing to extensions.** Neither build of the host assigns its entry's exports onto `globalThis`: the renderer is an app, and main is an `es`-format library build whose `export` statements nothing imports, because Electron runs it as the process entry point. A v1 extension that read `global.React`, `global.Pty` or another export of a host entry finds nothing; the singletons are reachable only through `FreelensExtensionApi`. The maps live in `packages/core/src/extensions/api-globals/`, one per process, each paired with the module id of every name it publishes. Membership cannot drift between the two objects — the id map is typed `Record` — and a name cannot drift from the rule: `assertExtensionApiSingletonNames` checks every key against `globalNameForModuleId` at startup, and a unit test runs the same assertion over both maps so a typo fails in CI without launching the app. **Failure mode.** Bundling your own copy of a listed package. React throws `invalid hook call`; **mobx fails silently** — two instances interoperate through shared global state well enough that observables appear to work and reactions simply do not fire where they should. A typo in a global name yields `undefined`, not a build error. Code built against another major of a listed package runs against the host's copy anyway: a mobx class compiled with legacy (`experimentalDecorators`) decorators throws when its module is evaluated, so the extension fails to load, and the annotations that do not throw are dropped silently (see [MobX 7 and mobx-react 10](./migrating-from-v1.md#mobx-7-and-mobx-react-10-standard-decorators-only) for the messages). --- ## C4. Module format and loading **Guarantee.** - **Main** accepts ESM or CommonJS. The host imports the manifest's `main` entry from a real file path. **Only ESM reloads**: a development install whose `main` was loaded as CommonJS, or whose format changed since it was loaded, needs the application restarted to run its new build. Loading it the first time is unaffected, which is what this guarantee is about. - **Renderer** entry points are **ESM**, loaded by URL from the privileged `freelens-extension` scheme. - **Top-level await is allowed** in either entry point: the renderer imports the served URL and main imports a `file:` URL, both asynchronously. - **Renderer code gets no guarantee of Node or Electron**, `require()` included. They are reachable only because the renderer is not context-isolated, and they may disappear in any release, a minor one included: being reachable does not make them part of the surface that [C14](#c14-versioning-and-compatibility) freezes. **Main** keeps both. **Surface.** `main` and `renderer` in the manifest, each a path relative to the package root. Under URL-based loading the renderer has **no `__dirname`**, which makes `LensExtension.manifestPath` the only route to an extension's own files — see [C6](#c6-registration-and-the-extension-instance). What a renderer entry point may rely on is what a browser page has — `fetch`, Web Crypto, `TextEncoder` / `TextDecoder`, `Uint8Array` — plus the API object of [C2](#c2-the-runtime-global-api) and the singletons of [C3](#c3-host-provided-singletons). Work that needs Node or Electron belongs in the main entry point, reached over `Renderer.Ipc` / `Main.Ipc`. The migration guide lists the replacement for each Node and Electron module v1 extensions used in the renderer, under [Node and Electron in the renderer](./migrating-from-v1.md#node-and-electron-in-the-renderer). The declaration cannot enforce this: `extension-api.d.ts` is one file for every process. The environment has to come from the extension's own compiler configuration, and the migration guide specifies the layout that provides it, under [Source layout: one tsconfig per runtime environment](./migrating-from-v1.md#source-layout-one-tsconfig-per-runtime-environment): `src/main/`, `src/renderer/` and `src/common/`, each with a `tsconfig.json` for its environment, so a Node API in renderer code or a DOM API in main code fails the type check rather than the running extension. **Reloading.** A development install is reloaded when its entry points are rebuilt: the host tears the extension down through `onDeactivate` and imports it again under a fresh URL. That is why only an ESM `main` reloads. Node keys its module map by URL, so the fresh URL is what makes a new module of the rebuilt file — but a CommonJS module is cached below that by filename, which no URL reaches, and the format Node resolved for a path is cached with it. So a path once loaded as CommonJS is frozen as the module it was, for the life of the process, however the file is rewritten; and a CommonJS build reached through the ESM loader throws `ReferenceError: module is not defined in ES module scope`. Neither cache can be evicted, so the host refuses those reloads instead of attempting them. **Failure mode.** A load failure is recorded in the extension's metadata and logged; the extension is skipped and nothing else aborts. A renderer bundle served with a wrong MIME type does not execute at all — the host maps types by file extension and serves anything unknown as `application/octet-stream`, which correctly refuses. A rebuild which cannot be reloaded is **refused and logged**, naming the extension and the reason; the extension goes on running the build it already has, in both processes, rather than one process moving on without the other. Extension code calling `globalThis.require` in the renderer is **warned, not blocked**: the host logs a deprecation warning once per extension and module id, and returns the module. Nothing stronger would hold while the renderer is not context-isolated, since the globals are shared. The warning goes by the **immediate caller** — the call is the extension's when the frame that made it is at a `freelens-extension://extensions//` URL, which also names the extension. So the host's own calls, and host code an extension calls into, do not warn; code an extension bundles is part of its file and does. The wrapper is installed in every frame that loads extensions, cluster frames included, before the first extension loads. --- ## C5. Namespace enumeration **Guarantee.** These are the members of each namespace. A symbol not listed here is not reachable (see [C1](#c1-packaging-and-publication)). | Namespace | Members | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Common` | `App`, `Catalog`, `Clusters`, `EventBus`, `Proxy`, `Store`, `Types`, `Util`, `logger`; types `InstalledExtension`, `LensExtension`, `LensExtensionManifest`, `Logger`, `PackageJson` | | `Main` | `Catalog`, `Ipc`, `K8s`, `K8sApi`, `LensExtension`, `Navigation`, `Power`, `Shell`, `Util` | | `Renderer` | `Catalog`, `Component`, `Ipc`, `K8s`, `K8sApi`, `LensExtension`, `Navigation`, `Theme`, `Util` | There is no `Renderer.React`, no `Renderer.ReactDOM` and no `Renderer.Registrations`. React reaches extensions through [C3](#c3-host-provided-singletons), registrations through [C6](#c6-registration-and-the-extension-instance). The table is asserted, not generated, by three checks: - `packages/core/src/extensions/__tests__/extension-api.test.ts` asserts the three member lists **exactly** — the table is that list — and then asserts only that each sub-namespace exists, is non-empty and still carries a handful of anchor symbols. - `packages/core/src/extensions/__tests__/extension-api.types.ts` names those anchors and the types of this section's failure mode **as types**, so a symbol that stops being nameable stops `pnpm type:check` compiling. - `packages/fixture-extension/src/common/contract-types.ts` does the same against the **built** declaration, which is the artifact an author resolves. **Failure mode.** A missing re-export is a compile error with no workaround. That is why `K8sApi` exports all of `@freelensapp/kube-object`, and why the kube-api option and descriptor types that appear in exported signatures — `KubeApiOptions`, `DerivedKubeApiOptions`, `KubeObjectStoreOptions`, `KubeApiListOptions`, `KubeApiQueryParams`, `DeleteOptions`, `PropagationPolicy`, `ResourceDescriptor`, `IKubeWatchEvent` — are exported alongside `parseKubeApi` and `createKubeApiURL`, so they are nameable and not merely callable. ### `K8sApi` exports all of `@freelensapp/kube-object` The namespace exports **all** of `@freelensapp/kube-object`, including the shared spec vocabulary — `Affinity`, `Capabilities`, `ContainerPort`, `Probe`, `ResourceRequirements`, `SecurityContext`, `Toleration` — that an extension adding resource views needs. Most of the package is interfaces, type aliases and enums transcribing upstream Kubernetes API shapes, whose stability is inherited from Kubernetes; its classes, functions and constants are what can change the behaviour of the API. **Two types share the name `KubeObjectStatus` in the source**: a Kubernetes resource status shape (`{ conditions?: BaseKubeObjectCondition[] }`) and the status registration type that extensions register status providers against. The registration type keeps the name `KubeObjectStatus`. The resource status shape is exported as **`BaseKubeObjectStatus`** — the base that `DeploymentStatus`, `JobStatus` and the other resource statuses extend. **The namespace reaches only what the package's own index exports.** `export *` resolves through a package's index, so a module the index skips is invisible to the namespace no matter what the namespace does. `SecurityContext`, `PreemptionPolicy`, `JSONSchemaProps` and `ExternalDocumentation` appear in the signatures of types the package exports (`Container.securityContext`, `PriorityClass.preemptionPolicy`, the CRD schema), so its `src/types/index.ts` exports the modules that declare them, and a type added to the package later needs the same. `json-schema-props` carries documented `string` aliases (`UUIDRegexString`, `UUID3RegexString`, `UUID4RegexString`, `UUID5RegexString`, `CreditCardRegexString`) alongside `JSONSchemaProps`; they are the `format` vocabulary for the CRD schema and are frozen with it under [C14](#c14-versioning-and-compatibility). ### `Util` is `@freelensapp/utilities` minus the Node-bound members `Common.Util` is delimited by a rule rather than by a list of what it offers: - **Every export of `@freelensapp/utilities` is extension API**, and frozen with the rest under [C14](#c14-versioning-and-compatibility) — including an export added to the package later. - **Except a member that needs Node or Electron in the renderer**, because renderer code gets no guarantee of either ([C4](#c4-module-format-and-loading)). Such a member goes on the omit list in `packages/core/src/extensions/common-api/utils.ts`, which destructures it out of the spread so that its name and types do not reach the bundled declarations either. Keeping them out also takes `rolldown-plugin-dts` 0.28.8 or newer: an older one keeps every member of `@freelensapp/utilities` in the bundle, because `utils.ts` reaches them through `import * as utilities`, and `build:dist` fails on their Node imports ([C11](#c11-third-party-bundled-libraries)). `Main.Util` and `Renderer.Util` spread `Common.Util`, so an omitted member is gone from all three; `Main.Util` adds `fetch` ([C12](#c12-http)). `Common.Util.getAppVersion` is the one member the host defines itself. **Whoever adds an export to the package** is therefore adding API, and checks one thing: does it need Node or Electron to run in the renderer — a `node:`/Electron import, a Node global such as `Buffer` or `process`, or a Node type such as `NodeJS.ErrnoException` in its signature? If the dependency is incidental to the implementation, remove it; if it is what the function does, add the member to the omit list and a line to the migration guide. **Failure mode.** A member that needs a Node global and is not on the list fails at runtime in a renderer without Node — a `ReferenceError` for a global such as `Buffer` — and not at compile time. ### `Catalog.getAllClusters()` and `getClusterById()` are observable `Main.Catalog` and `Renderer.Catalog` both have `getAllClusters()` and `getClusterById(id)`, which answer with `Common.Clusters.ClusterInfo` objects. **Both are observable through the host's mobx** ([C3](#c3-host-provided-singletons)), in both processes. Called inside a `reaction`, an `autorun`, a `computed` or an `observer` component, they make it run again when a cluster is added or removed and when a field of a cluster changes, its `status` among them. This is how an extension follows a cluster connecting or disconnecting: there is no event for it. ```ts import { Common, Main } from "@freelensapp/extensions"; import { reaction } from "mobx"; const { ClusterConnectionStatus } = Common.Clusters; const dispose = reaction( () => Main.Catalog.getClusterById(clusterId)?.status, (status) => { if (status === ClusterConnectionStatus.CONNECTED) { // ask Main.Shell.getEnvironment(clusterId) again, start what needs it } else { // stop what runs with the cluster's environment } }, ); // in onDeactivate() dispose(); ``` The functions are what is observable, not the objects they return: a `ClusterInfo` is a snapshot, and a later change gives new objects. Call the function inside the reaction, rather than keeping an object and reading its `status` later. A reaction is the extension's to dispose of, in `onDeactivate` at the latest. `packages/core/src/extensions/__tests__/catalog-clusters-observable-main.test.ts` and `catalog-clusters-observable-renderer.test.ts` run a `reaction` on each function through the API and change a cluster's status the way the host does. **Failure mode.** A reaction made with the extension's own copy of mobx rather than the host's fails silently, as [C3](#c3-host-provided-singletons) describes: it does not fire where it should, and nothing reports it. --- ## C6. Registration and the extension instance **Guarantee.** An extension contributes through **declarative fields on its `LensExtension` subclass**. Host-side registrators translate those fields into injectables, scoped to the extension and torn down with it. **Surface.** `LensRendererExtension` fields: `globalPages`, `clusterPages`, `clusterPageMenus`, `clusterFrameComponents`, `appPreferences`, `appPreferenceTabs`, `entitySettings`, `statusBarItems`, `kubeObjectDetailItems`, `kubeObjectMenuItems`, `kubeWorkloadsOverviewItems`, `commands`, `welcomeMenus`, `catalogEntityDetailItems`, `topBarItems`, `additionalCategoryColumns`, `customCategoryViews`, `kubeObjectHandlers`, `customResources`. Every component in a renderer registration is typed with the props the host renders it with and nothing more, so a component that requires another prop does not compile. One that needs the extension instance gets it from the registration, which runs inside the extension class: `Input: () => `. Pages are described in [C9](#c9-routing). The `Details` of a `kubeObjectDetailItems` registration and the `MenuItem` of a `kubeObjectMenuItems` one are typed with the object as `any`, so a component typed for the registered resource fits, a built-in class or an extension's own `LensExtensionKubeObject` subclass alike. A plain registration does not tie the component to its `kind` and `apiVersions`: the host renders it only for the registered kind, but nothing checks that the component was written for that kind. `Renderer.K8sApi.detailsFor(Class, { Details, apiVersions?, priority?, visible? })` and `Renderer.K8sApi.menuItemFor(Class, { MenuItem, apiVersions?, visible? })` make that check. Each takes the model class and returns a plain registration whose `kind` is the class's static `kind`, and types the component's `object` as an instance of the class, so a component written for another kind does not compile, a function component and a class component alike. `apiVersions` is, in this order: 1. the `apiVersions` given to the helper; 2. the `crd.apiVersions` of a `LensExtensionKubeObject` subclass; 3. the group and version of the class's static `apiBase`, as `parseKubeApi` reads it: `/api/v1/pods` gives `v1`, `/apis/apps/v1/deployments` gives `apps/v1`. The class's `apiBase` names one version, and the host reads some resources under more: `HorizontalPodAutoscaler` under each version its API allows, `Ingress` and `IngressClass` under `extensions/v1beta1` as well. An object read under a version the registration does not list carries that `apiVersion` and does not match it, so a registration for such a resource gives `apiVersions`. An extension with one class per version of its resource calls the helper once per class. The check is structural, and declaring the `spec` and `status` types is not enough for it. Two models of the same shape, such as two with `spec: unknown`, are not told apart, and neither are two whose `spec` types differ only in optional fields: each is assignable to the other, so a component written for one compiles against the class of the other. The classes of two versions of one kind usually have that shape. A model class therefore declares its instance `kind` and `apiVersion` as literal types, matching its static `kind` and `crd.apiVersions`, with a union of literals for a class that serves several versions: ```ts export class Example extends Renderer.K8sApi.LensExtensionKubeObject< Renderer.K8sApi.NamespaceScopedMetadata, ExampleStatus, ExampleSpec > { declare kind: "Example"; declare apiVersion: "example.freelens.app/v1alpha1"; static readonly kind = "Example"; static readonly namespaced = true; static readonly apiBase = "/apis/example.freelens.app/v1alpha1/examples"; static readonly crd = { apiVersions: ["example.freelens.app/v1alpha1"], plural: "examples", singular: "example", }; } ``` With the literals, a component written for the `v1alpha2` class does not compile against the `v1alpha1` one, whatever their specs. `declare` emits nothing, so the class behaves at runtime as it did without the two lines, and the narrowing holds: the host renders the component only for objects of the registered `kind` and `apiVersions`. The two lines need `declare`: written as fields (`kind!: "Example"`) under standard class-field semantics (`useDefineForClassFields`, the default from target ES2022), they are defined after the base constructor has assigned the object's data, and reset `kind` and `apiVersion` to `undefined`. `customResources` takes the model classes of the custom resources the extension presents with pages of its own, typed `Common.Types.CustomResourceRegistration`: ```ts customResources = [Example]; ``` The host reads each class's group and plural from the first of these it has: 1. the groups of its `crd.apiVersions` and its `crd.plural`, one resource per group, for a class with a `crd` such as a `LensExtensionKubeObject` subclass; 2. the group and resource of its static `apiBase`, as `parseKubeApi` reads it. While the extension is enabled for the cluster, the **Custom Resources** tree of the cluster sidebar leaves those resources out, and a group of the tree left with no kinds leaves with them. Disabled or uninstalled, the extension's resources are back in the tree. That is the whole effect: the definition of a registered resource stays in the **Definitions** list, and the resource's list, details and route are the host's as before, so it stays reachable by URL, from its definition and from the command palette. A favorite the user made of it in the tree stays in the Favorites section and opens the host's list, and a favorite of its group lists every kind of the group, those left out of the tree included. The registration is opt-in, so a model the extension declares without presenting it, one it only decorates through `kubeObjectDetailItems` or `kubeObjectMenuItems`, stays out of the field and in the tree. `LensMainExtension` fields: `terminalShellEnvModifier`, a function the host calls with the environment of every local shell it opens in a cluster's terminal. The environment `Main.Shell.getEnvironment` hands to an extension does not go through it ([C15](#c15-the-hosts-kubectl-helm-and-terminal-environment)). There is no field for the application menu or the tray: both are the host's own. `LensExtension` (both processes): `protocolHandlers`; the read-only `id`, `manifest`, `manifestPath`, `name`, `version`, `description`, `storeName`, `sanitizedExtensionId`, `isEnabled`; `getExtensionFileFolder()`; and the author hooks `onActivate()` / `onDeactivate()`. `LensRendererExtension` adds the two methods that navigate: `navigate()` to the extension's own pages and `navigateToPreferences()` to its preferences tab, both described in [C9](#c9-routing). Two of these matter more than they look: - **`manifestPath`** is how an extension locates its own shipped files. In the renderer it is the _only_ route, since there is no `__dirname` under URL loading. - **`getExtensionFileFolder()`** returns a writable directory for this extension alone, resolved from `storeName` through a hash — so it is **unaffected by reinstalls and version changes**, which the install path deliberately is not. The folder name is obfuscation, not a security boundary. **Failure mode.** A field left at its default contributes nothing, silently — a registration that never appears is the common symptom of a typo in a field name or of registering after the host has already read the field. A field the host cannot read, such as one set to something other than an array, costs that field alone: the host logs an error with the extension's name and the registrator that failed on it, skips the field, and goes on with the extension's other fields and with the other extensions. `detailsFor` and `menuItemFor` throw when the class has no `kind`, or when no `apiVersions` is given and the class has neither `crd.apiVersions` nor an `apiBase` it can be read from, or when the list resolved is empty; called from a field initializer, that fails the extension's load rather than leaving a registration that never appears. A `customResources` entry is rejected when it is not a class, has no static `kind`, has neither a `crd` nor an `apiBase` it can be read from, has a `crd` with no `apiVersions` or no `plural`, or names a resource of the core group. The host logs the error with the extension's name, the entry's index and the class's name, skips the entry and keeps the others, and the rejected resource stays in the Custom Resources tree. A `customResources` that is not an array is rejected whole: the host logs one error with the extension's name and what the field holds, and registers none of it. The field is read once, when the extension is registered, so a class assigned to it later is not seen. --- ## C7. The dependency-injection surface **Guarantee.** **The container and the DI library stay in the host.** The host is built on `@ogre-tools/injectable`, but neither its container nor the library is part of the extension API: no namespace exposes a container, an injection token or a hook that registers an injectable, and the global publishes neither `@ogre-tools/injectable` nor `@ogre-tools/injectable-react` ([C3](#c3-host-provided-singletons)). The host may change its DI library, or the library's major, in any release. **Surface.** None for authors. An extension contributes through the declarative fields of [C6](#c6-registration-and-the-extension-instance), and the host's registrators turn those fields into injectables in a view of the host's container kept for that extension. An extension that wants dependency injection for its own code bundles a DI library as an ordinary dependency — ogre-tools at any version, or anything else — with its own container and, for `withInjectables`, its own `DiContextProvider`. That container is the extension's alone: it holds none of the host's injectables, and the host never reads from it. **The per-extension view is host-internal and no security boundary.** It is a namespaced view, not an isolated container: the registrations made for an extension get an id prefix and are torn down with the extension, and nothing else about them is private. With `contextIsolation: false` an extension reaches everything through `globalThis` anyway, so keeping the container out of the API is a contract boundary, not a security one. What is supported is what the namespaces expose; anything else may change without notice. **The lifecycle invariant:** _the view exists before the author's first hook and is released after their last._ The loader injects it right after it constructs the extension instance; the registrators populate it after activation, because activation can register catalog categories they must see; and `disable()` runs `onDeactivate` before `deregister()`. **Failure mode.** An extension that still maps `@ogre-tools/*` to `FreelensExtensionApi` gets `undefined` at runtime, not a build error. An injectable created by an extension's own copy of ogre-tools means nothing to the host's container, so there is nothing of the host's to pass it to. --- ## C8. React **Guarantee.** Host-provided React **19**, reached through [C3](#c3-host-provided-singletons). Extensions must not bundle their own. **Surface.** `react`, `react-dom`, `react/jsx-runtime` as externals; `@types/react`, and `@types/react-dom` for an extension that imports `react-dom`, as devDependencies at the host's version. `@freelensapp/extensions` declares both as optional peers ([C11](#c11-third-party-bundled-libraries)), so the package manager resolves the declaration's React types to the author's copy and reports a version outside the host's range. React is not reached through a `Renderer.React` namespace, which does not exist, and an extension does not declare React as a peer dependency: the host provides it through the global, in development and in an installed extension alike. **Failure mode.** The invalid-hook-call trap: two copies of React in one renderer break the Rules of Hooks, and any hook — including those inside host components an extension renders — throws at runtime. It fails only at runtime, never at build time. --- ## C9. Routing **Guarantee.** Navigation runs on the in-house `@freelensapp/routing`. The API re-exports no `react-router`, `react-router-dom` or `history`. **Surface.** Pages are registered through `globalPages` / `clusterPages` ([C6](#c6-registration-and-the-extension-instance)). The **react-router 5 path dialect is supported** — `/:param?` optionals and inline `/:param(regex)` patterns — by the in-house `matchPath`, so existing path strings need no rewriting. Three calls navigate: - **`LensRendererExtension#navigate(pageId?, params?)`** goes to one of the extension's own pages, found by the `id` of its registration; no `pageId` means the page registered without an `id`. `params` become the page's parameters, keyed by the names the registration's `params` declares; another key rejects the returned promise. A `pageId` that matches no registration does nothing. - **`LensRendererExtension#navigateToPreferences()`** opens the application preferences on this extension's own tab, the one that holds the items of its `appPreferences`, from any frame, the cluster frame included. It takes no argument, so it reaches neither the host's tabs nor another extension's. - **`Renderer.Navigation.navigate(location)`** goes to any location, a path string or a `{ pathname, search, hash }` object, whose **pathname is absolute**. The location is pushed onto the browser history of the frame the call runs in, as given, and the browser resolves a relative pathname against the current URL. The preferences live in the root frame, so from a cluster frame this call does not reach them; `navigateToPreferences()` does. The `dependencies` of `LensRendererExtension`, which the declaration shows because they are `protected`, are the host's injection bag ([C7](#c7-the-dependency-injection-surface)) and not part of this surface; `navigateToRoute` among them may change in any release. A page component receives **only `params`**: `PageComponentProps`, one `PageParam` for each entry of the registration's `params`. `components.Page` is typed with exactly that, so a component that requires another prop does not compile. A page that needs the extension instance gets it from the registration, which runs inside the extension class: ```tsx clusterPages = [{ id: "my-page", components: { Page: () => } }]; ``` A page reads a named parameter from `params`: it takes `PageComponentProps` and reads `params.`, a `PageParam` whose `get()` returns the current value. The names are the keys of the registration's `params`, and a name the registration does not declare is `undefined`, which the type does not show: ```tsx const MyPage = ({ params }: PageComponentProps) =>

{params.query.get()}

; clusterPages = [{ id: "my-page", params: { query: "" }, components: { Page: MyPage } }]; ``` A props type with named parameters, such as `PageComponentProps<{ query: string }>`, does not fit `Page`: the host knows the names only at runtime, from the registration, so `Page` is typed with the general form and a component that requires particular names is not assignable to it. **Failure mode.** `import { Link } from "react-router-dom"` through the Freelens bundle does not resolve. A link in the markup is `Renderer.Component.MaybeLink`. An extension that wants react-router JSX bundles its own and mounts its own router around it: the host renders no react-router ``, so a bundled `Link` in a page the host renders has no router context. A relative pathname passed to `Renderer.Navigation.navigate` does not fail: it lands on a page that depends on the current URL, so it works from one page and goes wrong from another, without an error. The host logs a warning naming the location, in every build, which is the only sign of it. --- ## C10. Styling and CSS **Guarantee.** The host injects an extension's sibling stylesheet — either `.css` or a `style.css` next to the renderer entry — as a `` at the URL main serves it from, the same route the renderer entry point takes. A normal stylesheet import therefore works without the v1 `?inline` + `