@ngis/plugin-sdk 0.4.0

package/dist/src/sdk/map-api.d.ts

@@ -0,0 +1,288 @@
+/**
+ * `NgisMapAPI` — the typed facade a plugin programs against (L3 SDK contract).
+ *
+ * This is the "GeoLibre `GeoLibreAppAPI`" equivalent (see
+ * `../../GEOLIBRE_VS_NGIS.md` §3, one level up from the repo). It is a **binding
+ * layer, not a fourth subsystem**: every method delegates to something that
+ * already exists —
+ *
+ *   - the scene controllers' imperative surface (draw / measure / camera),
+ *     reached today through the composed `GisMapHandle` the shell exposes
+ *     (which itself reads the *live* scene-map-context method registry
+ *     `SceneMapHandleRegistry` — see `components/scenes/map/scene-map-context.ts`,
+ *     C2/C4/C5 — so the facade never captures a stale controller instance);
+ *   - the GIS scene store (`store/gis-scene.ts`) — the `layers` facet;
+ *   - the `WorkspacePanelRegistry` (`sdk/panels.ts`, C7) — the `panels` facet;
+ *   - workspace-owned highlight + view state — the `selection.highlight` and
+ *     `camera` facets.
+ *
+ * The facade introduces **zero new direct `maplibregl.Map` access**. The one
+ * raw touch it exposes — `getMap()` — is a deliberately-unstable escape hatch
+ * that stays `null` until the host wires a raw-map getter into it (the one-line
+ * `SceneMapCanvas.tsx` provider hookup applied after C5 lands; see
+ * `docs/componentization_stage/session-C8-map-api-facade.md`).
+ *
+ * GeoLibre's proven decisions, adopted verbatim in shape:
+ *   1. **Every subscription returns an unsubscribe function** (`onX(cb) => () => void`).
+ *   2. **Newer / not-yet-proven methods are optional-typed** (`api.x?.()`) so
+ *      plugin code written against v0 keeps compiling as the surface grows.
+ *      As of 0.2.0 (session P3, plugin-runtime stage) every method is either
+ *      **real and required** or was deleted; the lone remaining optional member
+ *      is `draw.snapshot` (see its doc for the stated reason).
+ *   3. **A raw-MapLibre escape hatch** (`getMap()`), documented as unstable.
+ *
+ * Framework-agnostic on purpose: this module imports no React and only
+ * type-imports its domain types, so the pure binding/bookkeeping logic is
+ * unit-tested directly with `node:test` (`map-api.test.ts`).
+ */
+import type { Map as MapLibreMap } from "maplibre-gl";
+import type { SceneLayerHighlight, SceneMapView } from "../domain/map/types";
+import type { GisDrawMode, GisMeasureKind } from "../types/gis";
+import type { WorkspacePanelRegistry } from "./panels";
+/** Current facade contract version — bumped when the frozen surface changes.
+ * A plugin's `minNgisVersion` (`docs/frontend-map-sdk.md` §3) is
+ * checked against this. Pre-1.0: the surface may still grow (additively).
+ *
+ * 0.2.0 (plugin-runtime stage, P3): promoted `camera.flyTo`/`fitBounds`,
+ * `layers.onChange` and `draw.onDrawChange` to required; deleted the never-
+ * implemented `selection.get`/`clear`/`onChange` (+ the `"selectionchange"`
+ * event) per decision D10; bound `draw.snapshot` through the imperative
+ * handle (kept optional — see its doc). See `docs/frontend-map-sdk.md` §2.
+ *
+ * 0.3.0 (Stage 11 E7, design doc §19, ED19): added the `commands` capability
+ * (`src/sdk/commands.ts`) — a plugin-declared, externally-invocable seam the
+ * codeenv SDK bridge's plugin-invocation executor calls by id. Contract-safe
+ * in both directions (the runtime's unknown-capability refusal covers an old
+ * runtime seeing a `commands`-declaring plugin; `minNgisVersion` covers a new
+ * plugin requiring a runtime this old). The bump lands atomically with this
+ * capability's only consumer, per ED19 — never staged ahead of it.
+ *
+ * 0.4.0 (Stage 13, X4b; F13.13 + ED19): the **`NgisHostAPI` capability
+ * contract**. `NgisPluginHost` widens from `{ api }` to the full nine-facet
+ * facade (`src/sdk/host-api.ts`), the runtime's first-wins `register` gains an
+ * `unregister`/`replace` seam (F13.8), and `contributes` v1 + derived
+ * activation events land beside `capabilities`. **`host.api` — this whole
+ * module — is unchanged and stays ungated**, which is the back-compat rule: a
+ * 0.3-era plugin declares `minNgisVersion: "0.3.0"`, negotiates identically,
+ * and keeps working byte-for-byte.
+ *
+ * Bumped atomically with its consumers per ED19: `plugin.ts`'s alias,
+ * `plugin-runtime.ts`, `GisWorkspace.tsx`'s host construction and the loader
+ * path all land in the same commit. Note the reverse leg of F13.13 —
+ * a 0.4-requiring manifest on a 0.3 host is refused by the `minNgisVersion`
+ * semver compare, **not** by the unknown-capability check: `contributes` and
+ * `permissions` are top-level manifest siblings, and a 0.3 runtime inspects
+ * only `manifest.capabilities`. */
+export declare const NGIS_MAP_API_VERSION = "0.4.0";
+/** A scene layer as the SDK exposes it — a stable projection of the store's
+ * `NgisSceneLayer`, so plugins never depend on the store's internal shape. */
+export interface NgisLayerSummary {
+    id: string;
+    name: string;
+    /** Scene layer type id (e.g. `"MAPLIBRE_FILL"`); `null` when unset. */
+    type: string | null;
+    visible: boolean;
+}
+/** Camera state — identical shape to the scene's persisted `SceneMapView`. */
+export type NgisMapView = SceneMapView;
+/** Geographic bounds `[west, south, east, north]`. */
+export type NgisBounds = [number, number, number, number];
+/** An unsubscribe function — the return value of every `onX` subscription. */
+export type NgisUnsubscribe = () => void;
+/** `layers` facet — list / inspect / focus / toggle scene layers. */
+export interface NgisLayersFacet {
+    list(): NgisLayerSummary[];
+    get(id: string): NgisLayerSummary | null;
+    /** Fit/ease the camera to a layer's extent (the layer-list "focus" action). */
+    focus(id: string): void;
+    /** Show/hide a layer (persists via the scene store, like the layer list). */
+    setVisibility(id: string, visible: boolean): void;
+    /** Notified when the effective layer set changes (add/remove/reorder/
+     * visibility *and* live style-draft edits — anything that replaces the
+     * store's `effectiveLayers` array). The host's binding equality-guards the
+     * subscription so listeners only fire on real changes, never on unrelated
+     * store updates. Required since 0.2.0. */
+    onChange(listener: () => void): NgisUnsubscribe;
+}
+/** `camera` facet — read/move the viewport + observe view changes. */
+export interface NgisCameraFacet {
+    /** Current view, or `null` when the raw map isn't bound yet (`getMap()`). */
+    getView(): NgisMapView | null;
+    /** Subscribe to camera moves (drives view persistence). Returns unsubscribe. */
+    onViewChange(listener: (view: NgisMapView) => void): NgisUnsubscribe;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Ease back to the scene's default/initial view. */
+    zoomHome(): void;
+    /** Fly to an explicit view. Escape-hatch-backed: delegates to the raw map,
+     * so it is a documented **no-op while `getMap()` returns `null`** (i.e.
+     * until the host binds a raw-map getter — the first-party canvas does via
+     * `useBindNgisRawMap`). Required since 0.2.0. */
+    flyTo(view: NgisMapView): void;
+    /** Fit the camera to bounds. Escape-hatch-backed — same getMap-null no-op
+     * behavior as `flyTo`. Required since 0.2.0. */
+    fitBounds(bounds: NgisBounds): void;
+}
+/** Enumerated feature highlight — identical to the scene's `SceneLayerHighlight`. */
+export type NgisHighlight = SceneLayerHighlight;
+/** The highlight sub-facet under `selection` — set/clear the feature-state
+ * highlight the attribute table and layer list drive. */
+export interface NgisHighlightFacet {
+    get(): NgisHighlight | null;
+    set(highlight: NgisHighlight | null): void;
+    clear(): void;
+    onChange(listener: (highlight: NgisHighlight | null) => void): NgisUnsubscribe;
+}
+/** `selection` facet — feature highlight only.
+ *
+ * 0.2.0 deleted the declared-but-dead drawn-feature-selection surface
+ * (`get?`/`clear?`/`onChange?` + the `"selectionchange"` event): nothing ever
+ * implemented or emitted it (decision D10 — contract-safe pre-1.0), and the
+ * one cheap first-party emit source (`SelectionController`'s feature-select
+ * enable/disable) signals an interaction-mode toggle, not a selection-set
+ * change. If a real Terra Draw selection source lands, the members return
+ * additively. */
+export interface NgisSelectionFacet {
+    highlight: NgisHighlightFacet;
+}
+/** `draw` facet — Terra Draw mode + one-shot geometry actions. */
+export interface NgisDrawFacet {
+    setMode(mode: GisDrawMode): void;
+    /** Leave the active mode, back to idle. */
+    cancelMode(): void;
+    getActiveMode(): string | null;
+    /** Remove every drawn feature. */
+    clear(): void;
+    /** Delete the currently selected drawn feature(s). */
+    deleteSelection(): void;
+    undo(): void;
+    redo(): void;
+    /** Download the drawn features as GeoJSON. */
+    export(): void;
+    /** Snapshot the raw Terra Draw features. Bound (0.2.0) through the
+     * imperative handle's optional `getDrawSnapshot` — returns `[]` when the
+     * handle is absent or doesn't expose the service.
+     *
+     * **Live since Stage 14 (F14.18).** The first-party shell's composed
+     * `GisMapHandle` now surfaces `getDrawSnapshot`, so in the shipping host this
+     * returns the real feature list rather than always `[]`. The member **stays
+     * optional-typed** because the 0.3 surface is frozen and a host is still
+     * allowed to bind a handle without the service; callers keep writing
+     * `snapshot?.() ?? []`. */
+    snapshot?(): unknown[];
+    /** Observe draw changes (drawn-feature/query-result changes and draw-mode
+     * transitions). Wired since 0.2.0: the host feeds its draw-result/draw-mode
+     * handlers into `NgisMapAPIHandle.emitDrawChange`. Required. */
+    onDrawChange(listener: () => void): NgisUnsubscribe;
+}
+/** `measure` facet — the ephemeral distance/area overlay. (Not in GeoLibre's
+ * original facet list; added because the rail's measure tools are a real v0
+ * consumer — measuring is a sibling Terra Draw control, never a drawn feature.) */
+export interface NgisMeasureFacet {
+    start(kind: GisMeasureKind): void;
+    clear(): void;
+}
+/** Named lifecycle events a plugin can observe generically.
+ * (`"selectionchange"` was deleted in 0.2.0 alongside the dead
+ * drawn-feature-selection surface — see `NgisSelectionFacet`.) */
+export type NgisMapEventName = "viewchange" | "highlightchange" | "drawchange";
+/** `events` facet — a generic named-event bus over the same emitters the typed
+ * facet subscriptions use (a forward-compat convenience for plugins). */
+export interface NgisEventsFacet {
+    on(event: NgisMapEventName, listener: () => void): NgisUnsubscribe;
+}
+/**
+ * The typed facade. v0 — the surface a plugin (and, today, the three first-party
+ * consumers) program against. Concrete methods are frozen; optional-typed
+ * methods may light up as the map subsystems expose more.
+ */
+export interface NgisMapAPI {
+    readonly version: string;
+    layers: NgisLayersFacet;
+    camera: NgisCameraFacet;
+    selection: NgisSelectionFacet;
+    draw: NgisDrawFacet;
+    measure: NgisMeasureFacet;
+    /** The C7 workspace panel registry, re-exposed so a plugin registers UI slots
+     * through the same SDK object. */
+    panels: WorkspacePanelRegistry;
+    events: NgisEventsFacet;
+    /** Raw MapLibre instance — the **unstable escape hatch**. `null` until the
+     * host binds a getter (post-C5 `SceneMapCanvas` hookup). Anything a plugin
+     * does with this is outside the stability contract. */
+    getMap(): MapLibreMap | null;
+}
+/** The imperative surface the facade delegates draw/measure/camera to — a
+ * structural subset of the shell's `GisMapHandle`, kept structural so this
+ * module doesn't import the (large) `SceneMapCanvas` component. */
+export interface NgisMapImperativeHandle {
+    setDrawMode(mode: GisDrawMode): void;
+    cancelMode(): void;
+    getActiveMode(): string | null;
+    clearDraw(): void;
+    deleteSelection(): void;
+    undo(): void;
+    redo(): void;
+    exportDraw(): void;
+    startMeasure(kind: GisMeasureKind): void;
+    clearMeasure(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomHome(): void;
+    /** Raw Terra Draw feature snapshot (the scene-map-context `getDrawSnapshot`
+     * service). **The first-party shell supplies it since Stage 14 (F14.18)**, so
+     * `draw.snapshot` returns real data there; it stays optional so a host may
+     * still bind a handle without the service. */
+    getDrawSnapshot?(): unknown[];
+}
+/** The layer operations the `layers` facet needs (a thin adapter over the
+ * scene store, supplied by the host so the SDK stays store-agnostic). */
+export interface NgisLayersBinding {
+    list(): NgisLayerSummary[];
+    focus(id: string): void;
+    setVisibility(id: string, visible: boolean): void;
+    /** Store-change subscription backing `layers.onChange`. The host must
+     * equality-guard it (fire only when the effective layer set really changed).
+     * Required since 0.2.0 — `onChange` is part of the frozen surface. */
+    subscribe(listener: () => void): NgisUnsubscribe;
+}
+/** The highlight sink — the workspace-owned highlight state (the exact data
+ * path the attribute table uses today: this ultimately calls `setHighlight`). */
+export interface NgisHighlightBinding {
+    set(highlight: NgisHighlight | null): void;
+    /** Initial value (defaults to `null`). */
+    initial?: NgisHighlight | null;
+}
+export interface NgisMapAPIBindings {
+    /** Live composed imperative handle (`mapRef.current`), or `null` before ready. */
+    getHandle(): NgisMapImperativeHandle | null;
+    layers: NgisLayersBinding;
+    panels: WorkspacePanelRegistry;
+    highlight: NgisHighlightBinding;
+    /** Raw-map getter for `getMap()`. Usually omitted at construction and wired
+     * later via `NgisMapAPIHandle.bindRawMap` (the post-C5 hookup). */
+    getRawMap?(): MapLibreMap | null;
+}
+/**
+ * The factory's return value: the public `api` plus the host-side "driver"
+ * controls (feed-in points the host wires that are *not* part of the public
+ * plugin surface).
+ */
+export interface NgisMapAPIHandle {
+    api: NgisMapAPI;
+    /** Feed a camera-view change into the facade (called from the canvas's
+     * `onViewChange` prop today; from `CameraController` post-hookup). */
+    emitViewChange(view: NgisMapView): void;
+    /** Feed a draw change into the facade — drives `draw.onDrawChange` and the
+     * `"drawchange"` event. The host calls this from its draw-result and
+     * draw-mode handlers (0.2.0's first-party emit source). */
+    emitDrawChange(): void;
+    /** Bind (or replace) the raw-map getter behind `getMap()` — the one-line
+     * `SceneMapCanvas` provider hookup applied after rebasing onto merged C5. */
+    bindRawMap(getter: () => MapLibreMap | null): void;
+}
+/**
+ * Build a facade over the supplied bindings. Pure and framework-agnostic —
+ * create it once per workspace (the host memoizes it) and keep it stable.
+ */
+export declare function createNgisMapAPI(bindings: NgisMapAPIBindings): NgisMapAPIHandle;

package/dist/src/sdk/panels.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Workspace panel registry — the plugin-readiness seam for GIS workspace UI
+ * "slots" (today: the right dock and the bottom docks). Formalizes what used
+ * to be a hand-wired `GisRightMode` enum plus three independent booleans
+ * (`attributeOpen`/`workflowOpen`/`codeOpen`) into a generic registration API:
+ *
+ *   const unregister = registerPanel({ id, slot, icon, labelKey, render });
+ *
+ * Design notes (see `docs/componentization_stage/session-C7-*.md`):
+ * - `render(container, ctx)` is a **DOM-based, framework-agnostic** contract —
+ *   modeled on GeoLibre's lesson that forcing every panel to hand back a React
+ *   element makes a registry impossible for a future non-React plugin loader
+ *   to target. A real plugin only needs to mutate a `container: HTMLElement`
+ *   and (optionally) return a cleanup function.
+ * - `reactPanel()` below is the React *adapter* the design doc calls for.
+ *   First-party panels stay ordinary React components; the adapter's returned
+ *   `render` function still matches the generic signature (so a naive host
+ *   invoking it imperatively still works, via an internal `createRoot`
+ *   fallback), but it also carries a `reactNode` escape hatch that a
+ *   React-aware host (`GisPanelHost`) uses to mount the panel as a normal
+ *   child in the app's own React tree — preserving context (next-intl, theme)
+ *   and ordinary prop-driven reactivity, which an isolated `createRoot` tree
+ *   cannot (separate roots don't share React context).
+ * - A slot still shows only one active panel at a time, but it also tracks the
+ *   panels opened during the current workspace session. Both GIS docks present
+ *   that list as tabs and keep inactive opened bodies mounted so local UI state
+ *   survives tab switches.
+ */
+import { type ReactNode } from "react";
+/** Slots this stage. Order matters only for future additions, not behavior. */
+export type PanelSlot = "right" | "bottom";
+export interface PanelRenderContext {
+    /** Close this panel in its slot (and its tab, when the host presents tabs). */
+    close: () => void;
+}
+export type PanelDisposer = () => void;
+/**
+ * The framework-agnostic render contract. A real (future) plugin panel would
+ * implement this directly: mutate `container`, return a cleanup function.
+ */
+export type PanelRenderFn = (container: HTMLElement, ctx: PanelRenderContext) => PanelDisposer | void;
+/** `reactPanel()`'s return type — same call signature, plus the fast path. */
+export interface ReactPanelRenderFn extends PanelRenderFn {
+    /** Build the React node for this panel "live" — called on every render of
+     * the React-aware host, so ordinary prop/state reactivity works exactly
+     * like a normal child component. */
+    reactNode: (ctx: PanelRenderContext) => ReactNode;
+}
+export interface PanelRegistration {
+    id: string;
+    slot: PanelSlot;
+    /** Plain string identifier (e.g. a lucide icon name) — kept string-typed,
+     * not a React node, so the registration shape never requires React. The
+     * consuming UI (e.g. `GisCommandRail`'s right-panel entries) resolves it. */
+    icon?: string;
+    /** i18n key (e.g. `"GIS.panels.ai"`) resolved by the consumer's `t()`. */
+    labelKey?: string;
+    /** Literal label, for callers without an i18n key (e.g. a future plugin). */
+    label?: string;
+    /** Lower sorts first. Ties fall back to registration order. */
+    order?: number;
+    render: PanelRenderFn;
+}
+type Listener = () => void;
+/**
+ * A registry instance. `panels.ts` exports a process-wide singleton
+ * (`workspacePanelRegistry`) for the app to use, but the class is exported too
+ * so tests (or a future second workspace) can build an isolated instance.
+ */
+export declare class WorkspacePanelRegistry {
+    private readonly panelsBySlot;
+    private readonly orderedCache;
+    private readonly activeBySlot;
+    private readonly openBySlot;
+    private readonly listeners;
+    private seq;
+    private readonly seqById;
+    constructor(slots?: readonly PanelSlot[]);
+    /** Register a panel into its slot. Returns an unregister function — the
+     * same "every registration returns an unregister function" convention the
+     * `NgisMapAPI` facade (C8) uses. */
+    registerPanel(def: PanelRegistration): PanelDisposer;
+    /** Registered panels in a slot, sorted by `order` then registration order.
+     * Cached so repeated calls between mutations return the same array
+     * reference (required for `useSyncExternalStore`'s snapshot contract). */
+    getPanels(slot: PanelSlot): PanelRegistration[];
+    getPanel(slot: PanelSlot, id: string): PanelRegistration | null;
+    getActive(slot: PanelSlot): string | null;
+    /** Panel ids opened in this slot, in first-opened order. The returned array
+     * is referentially stable until the open set changes. */
+    getOpenPanelIds(slot: PanelSlot): readonly string[];
+    /** Open a registered panel and make it active. Reopening an existing panel
+     * only activates it; it does not duplicate or reorder its tab. */
+    open(slot: PanelSlot, id: string): void;
+    setActive(slot: PanelSlot, id: string | null): void;
+    /** Close one opened panel. When it was active, prefer the nearest tab on
+     * its left, then the nearest tab on its right. */
+    close(slot: PanelSlot, id: string): void;
+    /** Invoking the already-active panel closes it — the "toggle-off" parity
+     * every rail tool and dock icon relies on. */
+    toggle(slot: PanelSlot, id: string): void;
+    subscribe(listener: Listener): PanelDisposer;
+    private slotMap;
+    private invalidate;
+    private removeOpenPanel;
+    private notify;
+}
+/** Process-wide registry for the `/gis` workspace. */
+export declare const workspacePanelRegistry: WorkspacePanelRegistry;
+/**
+ * React adapter: wraps a `(ctx) => ReactNode` factory as a `PanelRenderFn`.
+ * First-party panels use this. See the module doc comment for why the
+ * returned function carries both an imperative `createRoot` fallback (the
+ * literal, framework-agnostic contract) and a `reactNode` fast path
+ * (`GisPanelHost` uses this one, to stay inside the app's own React tree).
+ */
+export declare function reactPanel(factory: (ctx: PanelRenderContext) => ReactNode): ReactPanelRenderFn;
+export declare function isReactPanelRenderFn(fn: PanelRenderFn): fn is ReactPanelRenderFn;
+/** Convenience: build a `reactPanel` from a fixed element (no live `ctx`
+ * dependency needed) — most first-party panels want the factory form instead
+ * so they can pass `ctx.close`, but this keeps trivial cases terse. */
+export declare function staticReactPanel(node: ReactNode): ReactPanelRenderFn;
+/** Reactive list of a slot's registered panels, sorted — for building things
+ * like `GisCommandRail`'s right-panel entry group generically. */
+export declare function usePanels(registry: WorkspacePanelRegistry, slot: PanelSlot): readonly PanelRegistration[];
+/** Reactive active-panel id for a slot (`null` when the slot is closed). */
+export declare function usePanelActive(registry: WorkspacePanelRegistry, slot: PanelSlot): string | null;
+/** Reactive first-opened list for hosts that present a slot as tabs. */
+export declare function useOpenPanelIds(registry: WorkspacePanelRegistry, slot: PanelSlot): readonly string[];
+export {};

package/dist/src/sdk/plugin.d.ts

@@ -0,0 +1,145 @@
+/**
+ * NGIS plugin manifest + plugin object types (plugin-runtime stage, session
+ * P4). This is the *implemented* version of the `docs/frontend-map-sdk.md` §3
+ * draft, with the stage's decisions of record applied
+ * (`docs/plugin_runtime_stage/README.md`):
+ *
+ * - **D3 — typed TS object, not JSON.** First-party plugins compile in-repo,
+ *   so the manifest gets compile-time checking free. `entry` stays in the type
+ *   but is optional/reserved — JSON parsing + dynamic bundle loading is
+ *   exactly the third-party leg this stage excludes (gated on backend auth
+ *   hardening; see §3.5 of the SDK doc).
+ * - **D4 — declarative capabilities, runtime-owned teardown** (deliberate
+ *   deviation from the original §3 draft): capability fields carry the actual
+ *   registration definitions, and the **runtime** performs every registration
+ *   and owns the collected unregister functions. `activate`/`deactivate`
+ *   demote to optional imperative extras. This eliminates the draft's
+ *   plugin-kept-unregister honor system — a plugin cannot forget (or refuse)
+ *   to tear down what it never registered itself.
+ *
+ * Framework-agnostic on purpose: type-only imports, no React — consumed by
+ * the node-tested runtime (`plugin-runtime.ts`).
+ */
+import type { LayerRendererEntry } from "../systems/renderer/LayerRendererRegistry";
+import type { CommandRegistration } from "./commands";
+import type { NgisContributes, NgisPermissionScope } from "./contributions/types";
+import type { NgisSymbolRendererModule } from "./contributions/symbol-renderers";
+import type { PanelRegistration } from "./panels";
+import type { GisDynamicToolDef } from "./rail-tools";
+/**
+ * **F13.1 / ED19 (Stage 13, X4b) — the `NgisPluginHost` widening.**
+ *
+ * Until 0.3.0 this module *declared* `NgisPluginHost` as `{ api: NgisMapAPI }`.
+ * At 0.4.0 the name becomes a back-compat alias of the full nine-facet
+ * `NgisHostAPI` (`./host-api`), and this is the only line in the repo that says
+ * so — `@/sdk`'s barrel keeps re-exporting the name from here, so every
+ * `activate(host: NgisPluginHost)` signature is untouched.
+ *
+ * Why an alias rather than a rename: `host.api` keeps its name **and** its
+ * position (XD1's amendment on record — design-v2 §4 spells it `host.map`, and
+ * renaming would move every first-party plugin, the E7 command executor and the
+ * loader path for zero capability). A 0.3-era plugin that only ever reads
+ * `host.api.layers` therefore still type-checks and still runs, unchanged.
+ *
+ * Type-only re-export, so it is erased at build time and introduces no module
+ * cycle: `host-api.ts` does not import this file.
+ */
+import type { NgisPluginHost } from "./host-api";
+export type { NgisPluginHost };
+/** A teardown function collected and invoked by the runtime. */
+export type NgisPluginDisposer = () => void;
+/**
+ * Declarative capabilities (D4) — each field carries the real registration
+ * definitions for one of the three SDK extension points, wired by the runtime:
+ *
+ * - `panels` → `host.api.panels.registerPanel(...)` (C7 registry)
+ * - `railTools` → `gisRailToolRegistry.register(...)` (D6 seam — ids must be
+ *   namespaced, "More tools" overflow only)
+ * - `layerTypes` → the contributed-entries bridge (D5 — applied after
+ *   built-ins into `SceneLayersController`'s per-mount renderer registry)
+ * - `commands` → `gisCommandRegistry.register(...)` (Stage 11 E7 seam —
+ *   externally-invocable capabilities a scene script can call through the
+ *   codeenv plugin-invocation bridge; ids must be namespaced like railTools)
+ *
+ * An unknown key here refuses activation (`incompatible`), so a plugin built
+ * against a newer runtime never half-activates on an older one.
+ */
+export interface NgisPluginCapabilities {
+    panels?: PanelRegistration[];
+    railTools?: GisDynamicToolDef[];
+    layerTypes?: LayerRendererEntry[];
+    commands?: CommandRegistration[];
+}
+export interface NgisPluginManifest {
+    /** Stable, namespaced, reverse-DNS-ish — **must contain a `.`**
+     * (e.g. `"ngis.workflow"`, `"org.acme.heatmap"`); validated at registration. */
+    id: string;
+    /** Display name (literal — shown in the dev "plugins" panel). */
+    name: string;
+    /** Plugin's own semver. Informational this stage. */
+    version: string;
+    /** Minimum `NGIS_MAP_API_VERSION` the plugin needs — semver-compared by the
+     * runtime; a too-new requirement marks the plugin `incompatible`. */
+    minNgisVersion: string;
+    capabilities: NgisPluginCapabilities;
+    /**
+     * **F13.3 — a top-level sibling of `capabilities`, not a capability key.**
+     * `KNOWN_CAPABILITY_KEYS` stays `panels|railTools|layerTypes|commands` in
+     * both repos, which is precisely why F13.13's reverse leg lands on the
+     * `minNgisVersion` semver compare: a 0.3 runtime inspects only
+     * `manifest.capabilities` and never sees this key at all.
+     *
+     * The split rule: `capabilities` carries **code**, `contributes` carries
+     * **only data**, and a contribution that needs code references it by id.
+     * Parsed by `parseContributes` (`@/sdk/contributions`, X4a) from the raw
+     * manifest the boot / scene-resolve payload already carries — **before any
+     * bundle is fetched** (XD4). That passthrough is the lazy-activation
+     * substrate.
+     */
+    contributes?: NgisContributes;
+    /**
+     * **F13.5 — the declared permission scopes**, encoded as a flat array of
+     * scope strings (frozen at the W1 kickoff: duplicates are a validation
+     * error, order is insignificant, an empty array means the same as an absent
+     * key). Enforcement is X5's (W3) and is facade-level; the whole 0.3
+     * `host.api` surface stays ungated, so a 0.3-era plugin declares nothing
+     * here and is never prompted.
+     */
+    permissions?: readonly NgisPermissionScope[];
+    /** **Reserved, never read this stage** (D3): the future third-party loader's
+     * ESM-bundle path. First-party plugins are statically imported instead. */
+    entry?: string;
+}
+/**
+ * A plugin = manifest + optional imperative extras (D4). Most first-party
+ * plugins are expected to be fully declarative (capabilities only).
+ *
+ * - `activate?(host)` runs after the runtime registered the declared
+ *   capabilities. Return `false` to signal a failed activation (the runtime
+ *   rolls back the capability registrations it already made); return a
+ *   disposer to have the runtime run it on deactivation; throwing is treated
+ *   like `false`.
+ * - `deactivate?()` runs on teardown, after the runtime ran every collected
+ *   unregister function.
+ */
+export interface NgisPlugin {
+    manifest: NgisPluginManifest;
+    /**
+     * **F24.13 (Stage 24) — the code half of the T3 bridge.** `manifest
+     * .contributes.symbolRenderers` declares `{ id, geometry, params?, slots? }`
+     * as data; this is what the bundle exports against those ids.
+     *
+     * A sibling of `manifest`, not a capability key, for the reason
+     * `./contributions/symbol-renderers.ts` sets out: `KNOWN_CAPABILITY_KEYS` is
+     * frozen in both repos and an unknown key refuses activation outright, so a
+     * sixth one would make a T3 plugin `incompatible` on every older host.
+     *
+     * Published by the runtime at activation and disposed with every other
+     * registration it made — which is what keeps declaring a renderer from
+     * forcing eager activation (F13.4): the plugin activates on the first
+     * *resolution* of a symbol that names it.
+     */
+    symbolRenderers?: NgisSymbolRendererModule;
+    activate?(host: NgisPluginHost): void | false | NgisPluginDisposer;
+    deactivate?(): void;
+}

package/dist/src/sdk/rail-tools.d.ts

@@ -0,0 +1,58 @@
+import type { GisRailInvokeContext } from "../types/gis";
+/** A plugin-contributed rail tool. v1 supports one-shot `kind: "action"` only
+ * (no draw-mode/measure lit-state integration — that bookkeeping is keyed to
+ * `GisToolId` and stays closed per D6). `invoke` receives the exact same ctx
+ * shape as catalog tools, so a dynamic tool drives the map through `ctx.api`
+ * like any first-party tool. */
+export interface GisDynamicToolDef {
+    /** Namespaced id — **must contain a `.`** (validated at registration), which
+     * makes collision with the dot-free `GisToolId` union impossible. */
+    id: string;
+    /** Literal display label (not an i18n key — third-party path). */
+    label: string;
+    /** Optional lucide icon name; unmapped names render without an icon. */
+    icon?: string;
+    /** v1: one-shot actions only. */
+    kind: "action";
+    /**
+     * Rendered greyed-out instead of hidden, and `invoke` is not called
+     * (Stage 13 X9, F13.9 / XD12).
+     *
+     * Additive to D6: the overflow used to have no way to say "this exists but
+     * cannot run right now", so a contributed `tools` stanza whose backend tool
+     * is missing or whose `enabledWhen` is false would have had to be *dropped*
+     * from the list — and hiding it makes a broken install indistinguishable from
+     * a feature that was never installed. Nothing about D6's frozen rules
+     * changes: ids stay namespaced, the catalog stays closed, and a def that
+     * omits this field behaves exactly as before.
+     */
+    disabled?: boolean;
+    /** Why, shown beside a disabled entry. A plugin's literal string (F13.11) or
+     *  a host-authored one; never a message key. */
+    disabledReason?: string;
+    invoke: (ctx: GisRailInvokeContext) => void;
+}
+type Listener = () => void;
+type Disposer = () => void;
+/**
+ * Registry instance. A process-wide singleton (`gisRailToolRegistry`) is what
+ * the rail and the plugin runtime use; the factory is exported so tests build
+ * isolated instances.
+ */
+export interface GisRailToolRegistry {
+    /** Register a dynamic tool. Throws if `def.id` does not contain a `.`.
+     * Returns an unregister function (idempotent; never removes a different
+     * def re-registered under the same id). */
+    register(def: GisDynamicToolDef): Disposer;
+    /** Registered tools in registration order — cached snapshot between
+     * mutations (safe as a `useSyncExternalStore` snapshot). */
+    list(): readonly GisDynamicToolDef[];
+    subscribe(listener: Listener): Disposer;
+}
+export declare function createGisRailToolRegistry(): GisRailToolRegistry;
+/** Process-wide dynamic rail-tool registry for the `/gis` workspace. */
+export declare const gisRailToolRegistry: GisRailToolRegistry;
+/** Reactive list of registered dynamic tools — `GisCommandRail` merges these
+ * into its "More tools" overflow. */
+export declare function useDynamicRailTools(registry?: GisRailToolRegistry): readonly GisDynamicToolDef[];
+export {};