@ngis/plugin-sdk 0.4.0

package/dist/src/sdk/contributions/dispatch.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The command-dispatch seam for contributions (Stage 13 X4a).
+ *
+ * A `statusItems` entry, a menu item and a `tools` stanza all reference code by
+ * **id** and never carry it (XD3's split rule). Turning that id into a running
+ * command is the load path's job: F13.4 derives `onCommand:<id>` from exactly
+ * these references, so clicking one is precisely the moment the bundle may
+ * still be un-imported and must be activated first. That path — activation,
+ * `host.commands.invoke`, the runtime reopen — is **X4b's file ownership**, not
+ * this session's.
+ *
+ * So the mounts call `dispatchContributionCommand` and this module holds a
+ * single settable port. **The real one is installed by `GisWorkspace`** (X4c
+ * item I-1, `createContributionCommandPort` in
+ * `src/features/gis/lib/pluginActivationTriggers.ts`): it fires
+ * `onCommand:<id>`, awaits the activation, and only then invokes. The fallback
+ * below survives for the windows in which no port is installed — server
+ * rendering, a unit test, a tree that mounts a contribution outside the GIS
+ * workspace — where it runs a command that is *already* registered and
+ * otherwise refuses visibly rather than pretending the click worked.
+ *
+ * One setter, not several, on purpose: a second global would let the port and
+ * its map facade drift out of step.
+ */
+import type { NgisMapAPI } from "../map-api";
+import { type CommandHostResolver } from "../commands";
+import type { NgisMenuSlot } from "./types";
+/** What the menu was opened over — `undefined` for a status item or a tool. */
+export interface NgisContributionCommandTarget {
+    slot: NgisMenuSlot;
+    /** Scene-layer id for `layer/context`, scene-resource id for `resource/context`. */
+    id: string;
+    name?: string;
+}
+export interface NgisContributionCommandRequest {
+    /** The plugin that declared the contribution — **not** necessarily the
+     *  plugin that owns the command. Cross-plugin invocation is allowed in v1
+     *  (F13.2's `commands` facet), so both are reported. */
+    pluginId: string;
+    commandId: string;
+    source: "statusItem" | "menu" | "tool";
+    target?: NgisContributionCommandTarget;
+    params?: Record<string, string>;
+}
+/**
+ * The injected invoker. Installed by the host once; `null` restores the
+ * fallback. Returning a promise is fine — nothing awaits it, because a
+ * contribution click is fire-and-forget from the UI's point of view and the
+ * plugin reports its own progress through `host.ui`.
+ */
+export interface NgisContributionCommandPort {
+    /** The real, activation-aware invoker. When absent, the fallback below runs
+     *  instead — a host may install `api` alone and get eager-only dispatch. */
+    invoke?(request: NgisContributionCommandRequest): void | Promise<void>;
+    /** The 0.3 map facade, for the fallback path's `CommandInvokeContext`. */
+    api?: NgisMapAPI | null;
+    /**
+     * The **command owner's** 0.4 facade, for the fallback path's `ctx.host`
+     * (`V-121`).
+     *
+     * Beside `api` and optional for the same reason: a host may install neither
+     * and get a 0.3-shaped ctx, which is exactly what a tree mounting a
+     * contribution outside the GIS workspace has. Never derived from
+     * `request.pluginId` — see {@link NgisContributionCommandRequest.pluginId}.
+     */
+    resolveHost?: CommandHostResolver | null;
+}
+export declare function setNgisContributionCommandPort(next: NgisContributionCommandPort | null): void;
+/** Test/inspection seam — never used to make a decision in shipping code. */
+export declare function getNgisContributionCommandPort(): NgisContributionCommandPort | null;
+/**
+ * Dispatches one contribution's command.
+ *
+ * Returns `true` when something ran (or was handed to the port), `false` when
+ * the command could not be reached. Never throws: a plugin command that blows
+ * up must not take a context menu — or the top bar — down with it.
+ */
+export declare function dispatchContributionCommand(request: NgisContributionCommandRequest): boolean;

package/dist/src/sdk/contributions/panel-id.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The contributed-view panel id, in one dependency-free module.
+ *
+ * **Why it moved here at the W5 kickoff (Stage 14).** F14.12 makes the id a
+ * *contract*: `capabilities.panels` stops implying eager activation exactly
+ * when every declared panel id is `contributedViewPanelId(pluginId, viewId)`
+ * for a view the same plugin declares. So `activation.ts` — which runs over the
+ * boot payload before any bundle is fetched, and in Node tests — now has to
+ * build the id too. Importing it from `views-bridge.ts` would have dragged
+ * `../panels` and therefore `react-dom/client` into the activation path's
+ * module graph, which is the opposite of what a lazy-activation substrate is
+ * for.
+ *
+ * The alternative was a second two-line implementation, and that is the defect
+ * class this stage exists to remove (`V-127`, `V-262`). One declaration, two
+ * importers: `views-bridge.ts` re-exports both names, so every existing import
+ * path — including `@/sdk/contributions`' barrel and `@ngis/plugin-sdk`'s
+ * published value list (F14.13) — is unchanged.
+ */
+/** Panel-id prefix for a contributed view. Namespaced so it can never collide
+ *  with a first-party panel id (none of which contain a `:`). */
+export declare const CONTRIBUTED_VIEW_PANEL_PREFIX = "contrib:";
+/** `contrib:<pluginId>:<viewId>` — stable, so a re-register targets the same
+ *  tab and a plugin's own panel can deliberately take it over. */
+export declare function contributedViewPanelId(pluginId: string, viewId: string): string;

package/dist/src/sdk/contributions/registry.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The contribution registry (Stage 13 X4a, F13.3 / F13.6 / F13.10).
+ *
+ * Parsed `contributes` blocks in, **gated and ordered** contribution lists out.
+ * Nothing here renders; the host mounts (`GisContributedStatusItems`, the two
+ * context-menu mounts, the `views` bridge) read from it.
+ *
+ * ## Three properties that are contractual
+ *
+ * 1. **`when` and `enabledWhen` are evaluated on every point.** `when` false ⇒
+ *    the contribution is not in the list at all. `enabledWhen` false ⇒ it is in
+ *    the list with `gate.enabled === false` and its `disabledReason`, so the
+ *    host renders it disabled rather than hiding it. `views` carries `when`
+ *    only — a disabled-but-visible panel has no meaning (F13.3).
+ * 2. **Compile once, dependency-indexed.** Every distinct expression is
+ *    compiled by X1's store (which caches by source text, *including* failed
+ *    parses) and watched through `store.watch`, which re-evaluates only when a
+ *    key in that expression's own read-set changes and only notifies on an
+ *    actual boolean flip. No expression is ever re-parsed, and an unrelated key
+ *    change costs nothing.
+ * 3. **Order is deterministic and never install-order** (F13.10). statusItems:
+ *    `priority` desc → plugin id → item id. menus: group order
+ *    `navigation → modification → export → plugin`, then `order` asc → plugin
+ *    id → command. views: `order` asc → plugin id → view id.
+ *
+ * ## Failing closed on a malformed expression
+ *
+ * XB1 deliberately never interprets when-expressions, so a syntactically
+ * invalid `when` publishes fine and arrives here. F13.3 does not say what to do
+ * with it. The rule taken, and documented at the call site:
+ *
+ * - a `when` that will not compile ⇒ **not rendered** (fail closed — the author
+ *   asked for conditional visibility and the host cannot honour the condition);
+ * - an `enabledWhen` that will not compile ⇒ **rendered, disabled**, with the
+ *   generic host reason (the item is real; only its enablement is unknowable).
+ *
+ * Either way one contribution degrades and the plugin keeps working, which is
+ * the same posture X1's store takes for an unknown key.
+ */
+import type { NgisUnsubscribe } from "../map-api";
+import { type NgisContextStore } from "../context/store";
+import { type NgisContributes, type NgisMenuGroup, type NgisMenuItemContribution, type NgisMenuSlot, type NgisStatusItemContribution, type NgisSymbolRendererContribution, type NgisToolContribution, type NgisViewContribution } from "./types";
+/**
+ * The evaluated `when` / `enabledWhen` answer for one contribution.
+ *
+ * `disabledReason` is the plugin's **literal** string (F13.11 — plugin strings
+ * are never message keys) or `null`, in which case the host substitutes its own
+ * localized generic reason from `GIS.contrib`. Returning `null` rather than a
+ * baked-in English fallback is what keeps this module i18n-free and keeps the
+ * host string localized in both locales.
+ */
+export interface NgisContributionGateState {
+    /** `when` — false means the caller never sees this entry at all. */
+    readonly visible: boolean;
+    /** `enabledWhen` — false means rendered but disabled. */
+    readonly enabled: boolean;
+    /** The plugin's literal reason, or `null` for the host's generic string. */
+    readonly disabledReason: string | null;
+}
+export interface NgisRegisteredStatusItem {
+    /** `<pluginId>::<item.id>` — stable across re-evaluations; a React key. */
+    readonly key: string;
+    readonly pluginId: string;
+    readonly item: NgisStatusItemContribution;
+    readonly gate: NgisContributionGateState;
+    /**
+     * The resolved `badge.contextKey` value, coerced to a number, or `null` when
+     * no badge is declared / the key is unpublished / the value is not numeric.
+     * Coerced here rather than in the host so the badge cannot render `[object
+     * Object]` for a plugin that pointed at an array-valued key.
+     */
+    readonly badge: number | null;
+}
+export interface NgisRegisteredMenuItem {
+    /** `<pluginId>::<slot>::<command>::<index>` — commands may legitimately
+     *  repeat within a slot with different labels, so the index is part of it. */
+    readonly key: string;
+    readonly pluginId: string;
+    readonly slot: NgisMenuSlot;
+    /** Resolved group — `"plugin"` when the manifest omitted it (F13.3). */
+    readonly group: NgisMenuGroup;
+    readonly item: NgisMenuItemContribution;
+    readonly gate: NgisContributionGateState;
+}
+export interface NgisRegisteredView {
+    readonly key: string;
+    readonly pluginId: string;
+    readonly view: NgisViewContribution;
+    /** `views` takes `when` only, so `enabled` is always `true` here. */
+    readonly gate: NgisContributionGateState;
+}
+export interface NgisRegisteredTool {
+    readonly key: string;
+    readonly pluginId: string;
+    readonly tool: NgisToolContribution;
+    readonly gate: NgisContributionGateState;
+}
+/**
+ * A T3 renderer one installed plugin **declares** (F24.13).
+ *
+ * No `gate`: `symbolRenderers` carries neither `when` nor `enabledWhen`, and
+ * that is the contract rather than an omission — a renderer is selected by a
+ * *symbol manifest*, not by the host chrome, so there is no surface on which a
+ * hidden-or-disabled state would mean anything. Registration is therefore
+ * unconditional and the ordering rules above do not apply either: lookup is by
+ * `(pluginId, rendererId)`, which is what a `plugin:<extId>@<version>/<id>`
+ * reference names.
+ */
+export interface NgisRegisteredSymbolRenderer {
+    /** `<pluginId>::<renderer.id>`. */
+    readonly key: string;
+    readonly pluginId: string;
+    readonly renderer: NgisSymbolRendererContribution;
+}
+/** One consistent read of every contribution point — the `useSyncExternalStore`
+ *  snapshot. Referentially stable until a registration or a gate actually
+ *  changes. */
+export interface NgisContributionSnapshot {
+    readonly statusItems: readonly NgisRegisteredStatusItem[];
+    readonly menus: Readonly<Record<NgisMenuSlot, readonly NgisRegisteredMenuItem[]>>;
+    readonly views: readonly NgisRegisteredView[];
+    readonly tools: readonly NgisRegisteredTool[];
+    /** F24.13. Sorted by plugin id then renderer id, like every other point. */
+    readonly symbolRenderers: readonly NgisRegisteredSymbolRenderer[];
+}
+export interface NgisContributionRegistry {
+    /**
+     * Register (or replace) one plugin's parsed contributions. Passing `null` —
+     * an absent or refused block — registers nothing but still claims the plugin
+     * id, so a later `unregister` is symmetric.
+     *
+     * Returns a disposer, matching every other registry in `@/sdk`
+     * (`workspacePanelRegistry`, `gisRailToolRegistry`, `gisCommandRegistry`).
+     * Unlike the plugin *record* map, this registry is **last-wins**: a
+     * re-register replaces, because a version swap (F13.8) must not be blocked by
+     * a first-wins rule on data.
+     */
+    register(pluginId: string, contributes: NgisContributes | null): NgisUnsubscribe;
+    /** Drops a plugin's contributions. `false` if it was not registered. */
+    unregister(pluginId: string): boolean;
+    /** Registered plugin ids, sorted — deterministic for tests and inspectors. */
+    pluginIds(): readonly string[];
+    /** All contribution points in one consistent, referentially stable read. */
+    snapshot(): NgisContributionSnapshot;
+    /** Visible status items in F13.10 order. Convenience over `snapshot()`. */
+    statusItems(): readonly NgisRegisteredStatusItem[];
+    /** Visible menu items for one slot, in F13.10 group/order sequence. */
+    menuItems(slot: NgisMenuSlot): readonly NgisRegisteredMenuItem[];
+    /** Visible declarative views, `order` asc. */
+    views(): readonly NgisRegisteredView[];
+    /** Visible tool stanzas. Mounting them is F13.9's rail-overflow seam. */
+    tools(): readonly NgisRegisteredTool[];
+    /** Every declared T3 renderer (F24.13). */
+    symbolRenderers(): readonly NgisRegisteredSymbolRenderer[];
+    /**
+     * The declaration a `plugin:<extId>@<version>/<rendererId>` reference names,
+     * or `null`. **Answerable with the bundle un-imported** — that is what keeps
+     * declaring a renderer from forcing eager activation (F13.4, F24.13).
+     */
+    symbolRenderer(pluginId: string, rendererId: string): NgisRegisteredSymbolRenderer | null;
+    subscribe(listener: () => void): NgisUnsubscribe;
+}
+export interface NgisContributionRegistryOptions {
+    /** The context store gating is evaluated against. Tests inject an isolated
+     *  `createNgisContextStore()`; production uses the host-wide singleton. */
+    context?: NgisContextStore;
+}
+export declare function createNgisContributionRegistry(options?: NgisContributionRegistryOptions): NgisContributionRegistry;
+/**
+ * The host-wide contribution registry.
+ *
+ * A module-level singleton for the same reason `workspacePanelRegistry`,
+ * `gisRailToolRegistry` and `ngisContextStore` are: there is exactly one host,
+ * and the mounts (a status row in the GIS top bar, two context menus inside
+ * shared scene components) must reach it without a prop chain through files
+ * this session does not own. Tests build isolated instances with
+ * `createNgisContributionRegistry({ context: createNgisContextStore() })`.
+ */
+export declare const ngisContributionRegistry: NgisContributionRegistry;
+/**
+ * Splits an ordered status-item list at F13.10's host-row capacity.
+ *
+ * The cap is a *rendering* rule, not a validation rule: a plugin may legally
+ * declare two items and six plugins may legally be installed. The overflow
+ * collapses into a `+N` popover rather than disappearing.
+ */
+export declare function splitStatusItemsAtCap(items: readonly NgisRegisteredStatusItem[], cap?: number): {
+    visible: readonly NgisRegisteredStatusItem[];
+    overflow: readonly NgisRegisteredStatusItem[];
+};
+/**
+ * Groups an ordered menu list into F13.10's separated groups, preserving the
+ * fixed `navigation → modification → export → plugin` sequence and dropping
+ * groups with no visible item (so the host never renders a stray separator).
+ */
+export declare function groupMenuItems(items: readonly NgisRegisteredMenuItem[]): readonly {
+    group: NgisMenuGroup;
+    items: readonly NgisRegisteredMenuItem[];
+}[];

package/dist/src/sdk/contributions/symbol-renderers.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The **code** half of F24.13's T3 bridge (Stage 24 W3, S24-31).
+ *
+ * `contributes.symbolRenderers` is data — an id, a geometry, a param form and a
+ * slot list, parsed off the boot payload before any bundle is fetched. This
+ * module is the other side of F13.3's split rule: what the *bundle* exports, and
+ * where it lands once the plugin has been activated.
+ *
+ * ## Why the functions live on the plugin object rather than in `capabilities`
+ *
+ * `KNOWN_CAPABILITY_KEYS` is frozen at `panels|railTools|layerTypes|commands` in
+ * both repos (F13.3), and `plugin-runtime.ts` refuses an unknown capability key
+ * with `incompatible` — so a sixth capability key would make every plugin that
+ * used it fail negotiation on any host older than this one. `symbolRenderers`
+ * is therefore a **sibling of `manifest`** on the plugin object, exactly as
+ * `activate`/`deactivate` are, and the runtime publishes it here at activation
+ * and disposes it at teardown along with every other registration it made.
+ *
+ * ## Lazy by construction
+ *
+ * Nothing in this module is populated by parsing a manifest. A declared renderer
+ * is answerable from `ngisContributionRegistry.symbolRenderer(...)` with the
+ * bundle un-imported; the *function* only appears here once someone has resolved
+ * a symbol that names it and the plugin has been activated in consequence
+ * (F13.4, F24.13). That ordering is the whole reason the declaration and the
+ * function are two different things.
+ */
+import type { NgisUnsubscribe } from "../map-api";
+/**
+ * F24.13's frozen render context: `{ data, params, bindings, time, dataTime,
+ * pixelRatio, zoom }`.
+ *
+ * **No host handle, and that is the F15.2 worker-readiness rule, not an
+ * oversight**: everything a renderer reads has to be JSON, and so is everything
+ * it returns, so the same function can one day run somewhere a host facade
+ * cannot be passed. It is also async-free — a renderer returns descriptors, it
+ * does not go and fetch anything.
+ */
+export interface NgisSymbolRenderContext {
+    /** Whatever the host's builder feeds the stack — today the scene resource's
+     *  vector-tile URL, the same value every other symbol layer reads. */
+    data: unknown;
+    /** The symbol's resolved param values, after defaults and bindings. */
+    params: Readonly<Record<string, string | number | boolean>>;
+    /** The resolved F24.5 slots, by slot name. */
+    bindings: Readonly<Record<string, unknown>>;
+    /** The wall clock (F24.7), in seconds. `0` when nothing drives a clock. */
+    time: number;
+    /** The data clock (F24.7), in seconds. */
+    dataTime: number;
+    pixelRatio: number;
+    zoom: number;
+}
+/**
+ * What a T3 render function returns: **data, never a deck object** (F24.13 as
+ * amended 2026-09-02).
+ *
+ * The clause used to say `Layer[]`, and it cited F15.2's worker-readiness rule
+ * in the same sentence — while F15.2(1) forbids a host-crossing surface from
+ * returning *"a class instance"*, which a deck `Layer` is. Honouring only half
+ * of that rule cost the bundle: a plugin that constructs `Layer`s must `import`
+ * deck at runtime, so it either ships its own copy (the dogfood measured
+ * 1,463,082 bytes against 5.9–11.1 KB for the packages that do not, and two deck
+ * copies means two layer managers over one map) or deck's public API becomes a
+ * frozen plugin ABI.
+ *
+ * So the plugin names a layer **type** and hands over JSON props; the host looks
+ * the type up in its own allowlist, constructs it from its own deck and assigns
+ * the id. `type` is a string here rather than a union because the allowlist is
+ * the *host's* — a plugin compiled against an older SDK must not be prevented
+ * from naming a type a newer host has, and a type no host has is refused at
+ * build time with `incompatible` rather than silently dropped.
+ *
+ * **Nesting.** `props` is JSON, and a nested descriptor is JSON too: a tile
+ * layer's `renderSubLayers` prop may itself be a descriptor, which is how a
+ * plugin says "an `MVTLayer` whose tiles draw as `ScatterplotLayer`s" without
+ * writing the closure that deck's prop actually wants. The host writes that
+ * closure. Anywhere else, `renderSubLayers` is refused.
+ */
+export interface NgisSymbolLayerDescriptor {
+    /** A stock deck layer type on the host's allowlist, e.g. `"ScatterplotLayer"`. */
+    type: string;
+    /** JSON props for the constructed layer. The host owns `id`; setting it here has no effect. */
+    props?: Readonly<Record<string, unknown>>;
+}
+export type NgisSymbolRendererFn = (context: NgisSymbolRenderContext) => NgisSymbolLayerDescriptor[];
+/** What the bundle exports: renderer id → render function (F24.13). */
+export type NgisSymbolRendererModule = Readonly<Record<string, NgisSymbolRendererFn>>;
+/**
+ * Publish one activated plugin's render functions. Called by
+ * `plugin-runtime.ts` at activation, and disposed by the same disposer chain
+ * that unwinds `panels`/`railTools`/`layerTypes`/`commands` — so a function can
+ * never outlive the record that owns it.
+ *
+ * Last-wins by plugin id, like `ngisContributionRegistry.register`, because a
+ * version swap (F13.8) must not be blocked by a first-wins rule.
+ */
+export declare function publishNgisSymbolRenderers(pluginId: string, version: string, renderers: NgisSymbolRendererModule): NgisUnsubscribe;
+/**
+ * The activated function a `plugin:<extId>@<version>/<rendererId>` reference
+ * names, or `null` — including when the activated bundle is a *different*
+ * version from the one the reference pinned, which is a real mismatch rather
+ * than a near-miss to paper over.
+ */
+export declare function getNgisSymbolRenderer(pluginId: string, version: string, rendererId: string): NgisSymbolRendererFn | null;
+/** Test seam: forget every published module. */
+export declare function resetNgisSymbolRenderers(): void;