@ngis/plugin-sdk 0.4.0

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

@@ -0,0 +1,113 @@
+import type { NgisHostAPI } from "./host-api";
+import type { NgisMapAPI } from "./map-api";
+import type { NgisContributionCommandTarget } from "./contributions/dispatch";
+/** Context handed to a command's `invoke` — the full map facade, same object `NgisPluginHost.api`
+ * carries into `activate(host)`. Grows on demand, mirroring `NgisPluginHost`. */
+export interface CommandInvokeContext {
+    api: NgisMapAPI;
+    /**
+     * What the contribution was invoked **over** — the layer or scene resource a
+     * `layer/context` / `resource/context` menu was opened on (Stage 13 X9c,
+     * `V-120`).
+     *
+     * `undefined` for a `statusItems` click, a `tools` launch, and every codeenv
+     * `scene.plugin(extId).invoke(...)` — none of those has a target, and a
+     * command must be able to tell "no target" from "a target I did not read".
+     *
+     * **Why the ctx and not `args`.** `args` is the *caller's* data channel: a
+     * scene script's mailbox row already puts arbitrary values there, and a
+     * command invocable from both codeenv and a menu could not tell a host-
+     * supplied target from its own arguments. The ctx is the *host's* channel —
+     * it already carries `api` — so adding a member here cannot change the shape
+     * any existing command receives, while merging into `args` would.
+     */
+    target?: NgisContributionCommandTarget;
+    /**
+     * The **command-owning** plugin's own 0.4 facade — the same scope-enforced
+     * object `activate(host)` received, resolved through the host's
+     * `createGisPluginHostFactory` and never assembled (`V-121`).
+     *
+     * Owner, not caller: derived from `commandPluginId(id)`, because v1 allows
+     * one plugin's contribution to invoke another's command and the ctx belongs
+     * to the code that runs.
+     *
+     * `undefined` when the host cannot resolve an owning plugin for the id — a
+     * host that installed only `api`, or an id whose namespace matches no
+     * registered plugin. Optional, so every existing `{ api }` ctx still
+     * type-checks and a 0.3-era command is unaffected.
+     */
+    host?: NgisHostAPI;
+}
+/** A plugin-declared, externally-invocable command (§19). `invoke` may be sync or async; its return
+ * value (or thrown error) is exactly what the codeenv plugin-invocation executor reports back to the
+ * scene script as the mailbox's `DONE` result (or `FAILED` error, verbatim). */
+export interface CommandRegistration {
+    /** Namespaced id — **must contain a `.`** (validated at registration), mirrors the `ext_id`/rail-tool
+     * charset convention so a command id can never collide with a first-party reserved namespace. */
+    id: string;
+    title?: string;
+    /** Declarative JSON Schema — not enforced client-side beyond basic shape; informs the package
+     * manifest's capability summary and any future invocation UI. */
+    paramsSchema?: object;
+    invoke: (args: unknown, ctx: CommandInvokeContext) => unknown | Promise<unknown>;
+}
+/**
+ * The declaring plugin id, derived from the command id.
+ *
+ * Command ids are namespaced ({@link GisCommandRegistry.register} throws without a `.`) and, by the
+ * same convention `NgisPluginManifest.id` follows, the namespace *is* the plugin: `ngis.workflow.run`
+ * is `ngis.workflow`'s. F13.2 wants `pluginId` on `NgisCommandSummary` so "a plugin can see that a
+ * command is not its own"; deriving it from the id keeps that true without adding a field to the
+ * frozen `CommandRegistration` shape (E7's, not Stage 13's).
+ *
+ * Lives here rather than in `facets/commands.ts` (X4b's original home) because X8 made it the
+ * derivation *two* layers depend on — the summary's `pluginId` and the ctx's `host` owner — and the
+ * id convention it reads is this module's. `facets/commands.ts` re-exports it, so its published
+ * spelling is unchanged.
+ */
+export declare function commandPluginId(commandId: string): string;
+/**
+ * Resolves one plugin's scope-enforced 0.4 facade, or `null` when the host knows no such plugin.
+ *
+ * `null` rather than a minted facade is the whole contract (`V-121`): `createGisPluginHostFactory`
+ * is a memoizing factory that will happily build a host for an id nobody registered — one with no
+ * install row and, under F13.12, no grants — which would refuse every call for a reason the author
+ * cannot see. A resolver must answer from the set of plugins the host actually knows.
+ */
+export type CommandHostResolver = (pluginId: string) => NgisHostAPI | null;
+/**
+ * The ctx one invocation receives, with the owning plugin's facade attached when there is one
+ * (`V-121`).
+ *
+ * Every invoke site builds its ctx through here so the owner derivation happens once: X9c's `V-120`
+ * had to be fixed twice because two sites built the same object independently.
+ *
+ * `host` is spread conditionally, exactly as `target` is: an unresolvable owner leaves **no `host`
+ * key at all**, so "this host installed no 0.4 facade" stays distinguishable from `host: undefined`.
+ */
+export declare function buildCommandInvokeContext(commandId: string, base: CommandInvokeContext, resolveHost?: CommandHostResolver | null): CommandInvokeContext;
+type Listener = () => void;
+type Disposer = () => void;
+/**
+ * Registry instance. A process-wide singleton (`gisCommandRegistry`) is what the plugin runtime and
+ * the codeenv plugin-invocation executor use; the factory is exported so tests build isolated
+ * instances (mirrors `createGisRailToolRegistry`).
+ */
+export interface GisCommandRegistry {
+    /** Register a command. 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: CommandRegistration): Disposer;
+    /** Registered commands in registration order — cached snapshot between mutations (safe as a
+     * `useSyncExternalStore` snapshot). */
+    list(): readonly CommandRegistration[];
+    /** Look a command up by id — the executor's primary entry point. */
+    get(id: string): CommandRegistration | null;
+    subscribe(listener: Listener): Disposer;
+}
+export declare function createGisCommandRegistry(): GisCommandRegistry;
+/** Process-wide dynamic command registry for the `/gis` workspace. */
+export declare const gisCommandRegistry: GisCommandRegistry;
+/** Reactive list of registered commands — for a future invocation-management/debug surface, mirroring
+ * `useDynamicRailTools`. */
+export declare function useGisCommands(registry?: GisCommandRegistry): readonly CommandRegistration[];
+export {};

package/dist/src/sdk/context/keys.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Context-key vocabulary and value semantics (Stage 13, F13.6 / XD8;
+ * Stage 14, F14.11).
+ *
+ * The context store is the host's published view of "what is true right now",
+ * addressed by dotted keys — except for the two plugin-scoped namespaces, which
+ * F14.11 re-delimits with `:` (see `toPluginContextKey`). Contributions gate on
+ * it through `when` / `enabledWhen` expressions; a plugin reads it through
+ * `host.context`.
+ *
+ * Two rules bind everything in this folder:
+ *
+ * 1. **A key a plugin references but the host does not publish evaluates to
+ *    `undefined` — and therefore falsy — it never throws.** Contributions come
+ *    from third-party manifests; a typo in a `when` clause must degrade to
+ *    "not shown", not to a broken workspace.
+ * 2. **Values are JSON-serializable scalars or flat arrays of scalars**
+ *    (`NgisContextValue`). The whole 0.4 surface is worker-ready (F13.1 L6);
+ *    a context value must survive `structuredClone`/RPC unchanged.
+ */
+/** F13.2, verbatim. */
+export type NgisContextValue = string | number | boolean | null | readonly (string | number)[];
+/**
+ * The guaranteed key set (F13.6). X1 publishes exactly these; everything else
+ * is either a `config:<pluginId>:<key>` / `plugin:<pluginId>:<key>` namespace
+ * entry (F14.11) or absent.
+ *
+ * Every guaranteed key is **seeded with a default** at publisher start
+ * (`seedGuaranteedContextKeys`) so that "the scene has no layers" and "the
+ * context store has not booted yet" are distinguishable: the former publishes
+ * `0`, the latter leaves the key absent.
+ */
+export declare const GUARANTEED_CONTEXT_KEYS: readonly ["scene.id", "scene.type", "scene.isOwner", "scene.resourceCount", "scene.layerCount", "selection.layerId", "selection.featureCount", "draw.mode", "resources.types", "resources.count", "tasks.activeCount", "tasks.hasFailed", "user.role"];
+export type GuaranteedContextKey = (typeof GUARANTEED_CONTEXT_KEYS)[number];
+/**
+ * Namespaces a plugin may not write into via `host.context.set`.
+ *
+ * `plugin` and `config` are listed too: `set` auto-namespaces to
+ * `plugin:<pluginId>:<key>`, so a caller passing `plugin.foo.bar` is either
+ * confused about the contract or trying to write into another plugin's
+ * namespace. F13.2 requires that to be **rejected, not silently re-prefixed**.
+ *
+ * `target` is reserved by F14.7 even though nothing populates it yet: it is a
+ * *per-invocation overlay*, answered by a reader wrapper rather than written to
+ * the store, so a plugin that grabbed the head first would shadow a namespace
+ * the host is about to own.
+ */
+export declare const RESERVED_CONTEXT_NAMESPACES: readonly ["scene", "selection", "draw", "resources", "tasks", "user", "target", "config", "plugin"];
+/**
+ * The four `NgisResourceType` values (F13.2). **`"table"` is never emitted in
+ * v1** (XD7) — see `classifySceneResourceType`.
+ *
+ * X1 and X2 both needed this union and independently declared identical copies;
+ * F13.2 places it in the resources facet, so `facets/types.ts` is the one source
+ * of truth and this is a type-only re-export. Resolved at the W1 merge.
+ */
+export type { NgisResourceType } from "../facets/types";
+/** The three values `resources.types` may contain in v1 (XD7). */
+export declare const V1_EMITTED_RESOURCE_TYPES: readonly ["vector", "raster", "file"];
+/**
+ * Thrown by `host.context.set` for a key that is empty, malformed, or carries
+ * a reserved namespace prefix.
+ *
+ * Typed rather than a bare `Error` because the caller is plugin code: it must
+ * be able to tell "you may not write there" from a transport failure.
+ */
+export declare class NgisContextKeyError extends Error {
+    readonly code: "invalid-key";
+    readonly key: string;
+    constructor(key: string, message: string);
+}
+/**
+ * `true` when `key` is a well-formed dotted key — i.e. when it is spellable in
+ * a when-expression. `-` is a legal ident character because extension ids
+ * routinely contain one (`ngis.sample-coordinate-pin`), and the grammar has no
+ * subtraction operator for it to collide with.
+ *
+ * **This is deliberately colon-free, and it diverges from the `when` grammar's
+ * `key` production as of F14.11.** What it validates is the **bare** key a
+ * plugin passes to `host.context.set` — the host adds the namespace and the
+ * delimiter, so a bare key containing `:` is exactly the mistake
+ * `toPluginContextKey` must reject. The tokenizer, by contrast, has to *read*
+ * the namespaced form. Two different jobs, two different productions.
+ */
+export declare function isValidContextKey(key: string): boolean;
+/**
+ * `true` when `key` can be namespaced into a **plugin**-scoped context key —
+ * i.e. the non-throwing form of `toPluginContextKey`'s check, reserved head
+ * included.
+ *
+ * It is **not** `toConfigContextKey`'s check any more: F15.14/`V-241` dropped
+ * the reserved-head rejection there, so the config publisher asks
+ * `isValidContextKey` instead. Two different jobs — this one guards the key a
+ * plugin hands to `host.context.set`, where a reserved head means the author
+ * believes they can write host state.
+ */
+export declare function isScopableContextKey(key: string): boolean;
+/**
+ * Validates a plugin-supplied key and returns its canonical namespaced form
+ * `plugin:<pluginId>:<key>` (**F14.11**).
+ *
+ * The delimiter is `:` rather than `.` because the dotted join was not uniquely
+ * decodable — plugin `a.b` + key `c.d` and plugin `a.b.c` + key `d` both spell
+ * `plugin.a.b.c.d` (`X9-I-5`). `:` occurs in neither an extension id
+ * (`^[a-z0-9-]+(\.[a-z0-9-]+)+$`) nor a key segment, so splitting on the first
+ * two `:` yields exactly three fields and the key may still contain dots.
+ *
+ * @throws {NgisContextKeyError} on an empty/malformed key or one that already
+ * carries a reserved namespace prefix.
+ */
+export declare function toPluginContextKey(pluginId: string, key: string): string;
+/**
+ * The canonical `config:<pluginId>:<key>` spelling (fed by `host.storage`,
+ * W2/X3).
+ *
+ * **Validates shape, and — as of F15.14 — nothing else (`V-241`).** F14.11 gave
+ * it `toPluginContextKey`'s whole check, reserved head included, so that the two
+ * spellings of the dual-write could not disagree about what they accepted. With
+ * the dotted spelling gone, that reason is gone: `config:a.b:scene` collides
+ * with `scene.id`, with `config:a.b.scene:…` and with nothing else, because the
+ * namespace and the delimiter are both fixed by the host. A settings property
+ * named `scene` is an author's word for their own setting, not an attempt to
+ * write host state — the sibling's check exists to catch *that*, and this
+ * function is never reached from `host.context.set`.
+ *
+ * @throws {NgisContextKeyError} on an empty or malformed key.
+ */
+export declare function toConfigContextKey(pluginId: string, key: string): string;
+/**
+ * Value equality for the store's change guard and for the `==` operator.
+ *
+ * - Arrays compare element-wise (a re-derived `resources.types` array is a new
+ *   reference on every store update but usually the same content — without
+ *   this guard every unrelated scene-store write would wake every subscriber).
+ * - `undefined` and `null` are the same value. An absent key is "nothing", and
+ *   `someKey == null` reading `true` for an unpublished key is the behaviour an
+ *   expression author expects.
+ */
+export declare function contextValueEquals(a: NgisContextValue | undefined, b: NgisContextValue | undefined): boolean;
+/**
+ * Truthiness for a bare-key test (`when: "scene.isOwner"`).
+ *
+ * Deliberately **not** JavaScript truthiness for arrays: `[]` is truthy in JS,
+ * but `when: "resources.types"` plainly means "the scene has some resources".
+ * An empty array is falsy here, and that is a contract of the grammar rather
+ * than an implementation detail.
+ */
+export declare function isContextValueTruthy(value: NgisContextValue | undefined): boolean;

package/dist/src/sdk/context/publishers.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Guaranteed-key publishers (Stage 13, F13.6).
+ *
+ * Every publisher here is **dependency-injected and store-agnostic**: it takes
+ * a `{ getState, subscribe }` handle (the shape a Zustand store already has)
+ * or a facet-shaped observer, never an import of `@/store/*`. Two reasons:
+ *
+ * - `src/sdk/**` does not depend on `src/store/**` anywhere else — the C8 map
+ *   facade takes injected bindings from `GisWorkspace` for exactly this
+ *   reason, and the context store is the same kind of seam.
+ * - It is what makes "key-publisher tests against fake stores" a two-line
+ *   fixture instead of a Zustand harness.
+ *
+ * Subscriptions use the **equality-guarded pattern** at
+ * `GisWorkspace.tsx:164-167`: compare the specific slice references between
+ * `state` and `prevState` and do nothing when they are identical, so an
+ * unrelated store write (a loading flag, a style draft) costs one reference
+ * compare rather than a re-derivation and a notification.
+ */
+import type { NgisUnsubscribe } from "../map-api";
+import { type NgisContextValue, type NgisResourceType } from "./keys";
+import type { NgisContextStore } from "./store";
+/** The subset of a Zustand store a publisher uses. */
+export interface ContextStoreSource<T> {
+    getState(): T;
+    subscribe(listener: (state: T, prevState: T) => void): () => void;
+}
+/**
+ * Writes the default for every guaranteed key.
+ *
+ * Without this, "no scene is open" and "the context store has not booted" look
+ * identical to a `when` clause, and a plugin gating on `scene.layerCount > 0`
+ * would behave differently during the first frame than after it. Publishers
+ * overwrite these immediately; the defaults are the resting state.
+ */
+export declare function seedGuaranteedContextKeys(store: NgisContextStore): void;
+export interface SceneContextResource {
+    /**
+     * `SceneResourceDto.geometryType`. The scene store hydrates it from
+     * `DatasetInfo` (`scene-store.ts` `getDatasetGeometry`): the literal
+     * `"Raster"` for a RASTER dataset, the vector geometry type for a VECTOR
+     * one, and `null` for everything else — which is the signal
+     * `classifySceneResourceType` reads.
+     */
+    geometryType?: string | null;
+}
+export interface SceneContextScene {
+    id: string;
+    ownerId?: string | null;
+    type?: string | null;
+}
+/** The slice of `createSceneStore()`'s state the scene publisher reads. */
+export interface SceneContextSlice {
+    sceneId: string | null;
+    scene: SceneContextScene | null;
+    resources: readonly SceneContextResource[];
+    layers: readonly unknown[];
+    selectedLayerId: string | null;
+}
+/** The slice of the auth store the publishers read. */
+export interface AuthContextSlice {
+    user: {
+        id?: string;
+        role?: string;
+    } | null;
+}
+/**
+ * Scene-resource → `NgisResourceType` (XD7).
+ *
+ * **Never returns `"table"`.** The reserved fourth value needs
+ * `NgisFile.fileType`, i.e. a `GET /api/files/{fileId}` per resource, and no
+ * v1 dogfood plugin needs the distinction. `'table' in resources.types` is on
+ * the W3 grep-proof list precisely so nobody writes a plugin against a value
+ * this function cannot produce.
+ *
+ * Classification is a projection of `DatasetInfo.datasetType` as the scene
+ * store already recorded it: `RASTER` → `"raster"` (the store writes the
+ * literal `"Raster"` as the geometry type), any other non-empty geometry type
+ * → `"vector"`, absent → `"file"` (which covers `GENERIC` and a dataset whose
+ * metadata fetch failed). The authoritative join lives in X2's
+ * `host.resources` facet; wiring this publisher to it is backlog row **V-21**.
+ */
+export declare function classifySceneResourceType(resource: SceneContextResource): NgisResourceType;
+/**
+ * Distinct resource types, in the fixed `vector → raster → file` order.
+ *
+ * Deterministic ordering is not cosmetic: the store's equality guard compares
+ * arrays element-wise, so an unstable order would report a change on every
+ * scene-store write.
+ */
+export declare function deriveResourceTypes(resources: readonly SceneContextResource[], classify?: (resource: SceneContextResource) => NgisResourceType): string[];
+export interface SceneContextPublisherOptions {
+    /**
+     * Override the resource classifier. The seam X2/X3 use to swap in the
+     * dataset-backed join without editing this file.
+     */
+    classifyResource?: (resource: SceneContextResource) => NgisResourceType;
+}
+/**
+ * Publishes `scene.*`, `selection.layerId` and `resources.*`.
+ *
+ * `scene.isOwner` needs both stores, so the auth handle is optional but
+ * strongly recommended: without it ownership is unknowable and the key stays
+ * `false`, which is the safe reading (a read-only viewer).
+ *
+ * Note that `selection.layerId` is the **layer-list** selection
+ * (`selectedLayerId`), while `selection.featureCount` comes from the feature
+ * highlight (`publishHighlightContextKeys`). Those are two distinct host
+ * selection surfaces today — `NgisSelectionFacet` is highlight-only since
+ * 0.2.0 (decision D10) — and F13.6 does not require them to be the same
+ * selection. Recorded as a decision rather than papered over.
+ */
+export declare function publishSceneContextKeys(store: NgisContextStore, scene: ContextStoreSource<SceneContextSlice>, auth?: ContextStoreSource<AuthContextSlice>, options?: SceneContextPublisherOptions): NgisUnsubscribe;
+export interface TaskContextTask {
+    status: string;
+}
+export interface TaskContextSlice {
+    tasks: readonly TaskContextTask[];
+}
+/** Publishes `tasks.activeCount` and `tasks.hasFailed`. */
+export declare function publishTaskContextKeys(store: NgisContextStore, tasks: ContextStoreSource<TaskContextSlice>): NgisUnsubscribe;
+/**
+ * `user.role` is **presentational only and never an authorization decision.**
+ *
+ * The server stays authoritative for every capability: the market's ADMIN
+ * surface is established by calling the review queue and handling `403`, not
+ * by reading a role off the client. This key exists so a contribution can say
+ * "don't show this to a non-admin", which is a UI affordance, not a gate. A
+ * plugin that treats it as one is wrong, and the value is trivially forgeable
+ * from the console anyway (F13.6, ground-truth correction 7).
+ */
+export declare function publishUserContextKeys(store: NgisContextStore, auth: ContextStoreSource<AuthContextSlice>): NgisUnsubscribe;
+/** The `NgisDrawFacet` members the publisher needs (`host.api.draw`). */
+export interface DrawContextSource {
+    getActiveMode(): string | null;
+    onDrawChange(listener: () => void): NgisUnsubscribe;
+}
+/** Publishes `draw.mode`. */
+export declare function publishDrawContextKeys(store: NgisContextStore, draw: DrawContextSource): NgisUnsubscribe;
+/** The `NgisHighlightFacet` members the publisher needs (`host.api.selection.highlight`). */
+export interface HighlightContextSource {
+    get(): {
+        featureIds?: readonly string[];
+    } | null;
+    onChange(listener: (highlight: unknown) => void): NgisUnsubscribe;
+}
+/** Publishes `selection.featureCount` from the enumerated feature highlight. */
+export declare function publishHighlightContextKeys(store: NgisContextStore, highlight: HighlightContextSource): NgisUnsubscribe;
+/**
+ * The `config:<pluginId>:<key>` key source — **the W2 seam, frozen now**.
+ *
+ * F13.6 assigns `config:*` to `host.storage`, which is X3's in W2. X1 ships
+ * the interface and an empty implementation so that contributions can already
+ * reference `config:*` keys (they evaluate falsy, as an unpublished key must)
+ * and X3 wires a real source without touching this file or the store.
+ */
+export interface NgisContextConfigSource {
+    /** `pluginId` → flat map of that plugin's scalar settings. */
+    read(): Readonly<Record<string, Readonly<Record<string, NgisContextValue>>>>;
+    subscribe(listener: () => void): NgisUnsubscribe;
+}
+/** The stub source: no config keys, no changes. Replaced by X3 in W2. */
+export declare const emptyContextConfigSource: NgisContextConfigSource;
+/**
+ * Publishes `config:<pluginId>:<key>`, removing keys the source drops.
+ *
+ * **A settings key that cannot be namespaced is skipped, not thrown on.** The
+ * keys here are the top-level members of a plugin's stored settings JSON —
+ * arbitrary author-chosen text, reaching this loop through
+ * `flattenConfigValues` with no ident check. `{"my key": 1}` would make
+ * `toConfigContextKey` throw *inside* the loop and kill `config:*` publication
+ * for **every** plugin, not just the one with the odd blob. Skipping is also
+ * what this path already does one level down: `flattenConfigValues` drops a
+ * value `NgisContextValue` cannot hold, and an absent key is falsy by design
+ * (F13.6).
+ *
+ * The guard is `isValidContextKey`, not `isScopableContextKey`: F15.14/`V-241`
+ * relaxed `toConfigContextKey`'s reserved-head rejection, so `{"scene": "x"}`
+ * now publishes as `config:<pluginId>:scene` instead of being dropped. It is a
+ * setting called `scene`, and the fixed `config:` namespace means it can reach
+ * nothing else.
+ */
+export declare function publishConfigContextKeys(store: NgisContextStore, source: NgisContextConfigSource): NgisUnsubscribe;
+export interface GuaranteedContextPublisherDeps {
+    scene?: ContextStoreSource<SceneContextSlice>;
+    auth?: ContextStoreSource<AuthContextSlice>;
+    tasks?: ContextStoreSource<TaskContextSlice>;
+    draw?: DrawContextSource;
+    highlight?: HighlightContextSource;
+    config?: NgisContextConfigSource;
+    classifyResource?: (resource: SceneContextResource) => NgisResourceType;
+}
+/**
+ * Seeds every guaranteed key and starts whichever publishers the host can
+ * supply sources for. Missing sources leave their keys at the seeded default —
+ * an absent publisher must never leave a guaranteed key undefined.
+ */
+export declare function startGuaranteedContextPublishers(store: NgisContextStore, deps: GuaranteedContextPublisherDeps): NgisUnsubscribe;

package/dist/src/sdk/context/store.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The context-key store (Stage 13, F13.6 / XD8).
+ *
+ * Host-published keys in, gated contributions out. Three properties are
+ * contractual, not incidental:
+ *
+ * 1. **Compile once.** An expression is parsed the first time it is seen and
+ *    cached by its source text — including a *failed* parse, so a malformed
+ *    `when` in a manifest costs one tokenizer run for the life of the session,
+ *    not one per key change. `getCompileCount()` exists so a test can observe
+ *    that rather than a comment asserting it.
+ * 2. **Batched per microtask.** Publishers write many keys per store update
+ *    (a scene load moves `scene.id`, `scene.type`, `scene.layerCount`,
+ *    `resources.*` at once). Writes accumulate and flush on one microtask, so
+ *    N key changes cost exactly one notification and one re-evaluation.
+ * 3. **Dependency-indexed.** A watched expression re-evaluates only when a key
+ *    in its own read-set changed. With dozens of contributions from a handful
+ *    of plugins, the alternative — re-run everything on every change — is what
+ *    makes declarative gating too slow to be the default.
+ *
+ * Writes are equality-guarded (`contextValueEquals`): a publisher re-deriving
+ * `resources.types` into a fresh array with identical content is not a change,
+ * and never wakes a subscriber.
+ */
+import type { NgisUnsubscribe } from "../map-api";
+import { type NgisContextValue } from "./keys";
+import { type CompiledWhenExpression } from "./when";
+/** The changed-key payload. A key that was removed reads back as `null`. */
+export type ContextChangeListener = (changed: Readonly<Record<string, NgisContextValue>>) => void;
+export interface NgisContextStore {
+    get(key: string): NgisContextValue | undefined;
+    /** Frozen snapshot; the same reference until the next write (`useSyncExternalStore`-safe). */
+    getAll(): Readonly<Record<string, NgisContextValue>>;
+    /** `undefined` removes the key. Equality-guarded; batched to a microtask. */
+    set(key: string, value: NgisContextValue | undefined): void;
+    setMany(entries: Readonly<Record<string, NgisContextValue | undefined>>): void;
+    /**
+     * Fires when any of `keys` changes. `null` subscribes to every key — the
+     * dev inspector's mode, not something a contribution should use.
+     */
+    subscribeKeys(keys: readonly string[] | null, listener: ContextChangeListener): NgisUnsubscribe;
+    /** Compiles (or returns the cached compilation of) an expression. */
+    compile(expression: string): CompiledWhenExpression;
+    /** Compile-and-evaluate. Throws `NgisWhenSyntaxError` on malformed input. */
+    evaluate(expression: string): boolean;
+    /**
+     * Re-evaluates `expression` whenever a key in its read-set changes, calling
+     * `listener` only when the boolean result actually flips. Does **not** fire
+     * on subscribe — call `evaluate` for the initial value.
+     */
+    watch(expression: string, listener: (value: boolean) => void): NgisUnsubscribe;
+    /** Test seam: how many times an expression has been parsed. */
+    getCompileCount(): number;
+}
+export interface NgisContextStoreOptions {
+    /**
+     * Compiler override. Production uses `compileWhenExpression`; tests wrap it
+     * to count parses and evaluations, which is how "compile once" and "one
+     * re-evaluation per microtask" are *observed* rather than asserted.
+     */
+    compile?: (expression: string) => CompiledWhenExpression;
+    /**
+     * Flush scheduler. Defaults to `queueMicrotask`. A test may pass a manual
+     * scheduler to drive flushes deterministically.
+     */
+    schedule?: (flush: () => void) => void;
+}
+export declare function createNgisContextStore(options?: NgisContextStoreOptions): NgisContextStore;
+/**
+ * The host-wide context store.
+ *
+ * A module-level singleton for the same reason `workspacePanelRegistry` and
+ * `gisCommandRegistry` are: there is exactly one host, plugin facades are
+ * created per plugin but must all see the same world, and the dev inspector
+ * needs to reach it without a prop chain. Tests use `createNgisContextStore()`
+ * for isolation.
+ */
+export declare const ngisContextStore: NgisContextStore;

package/dist/src/sdk/context/when.d.ts

@@ -0,0 +1,69 @@
+/**
+ * When-grammar v1 — lexer, recursive-descent parser, and compiler (F13.6 / XD8).
+ *
+ * ```
+ * expr    := or
+ * or      := and ( "||" and )*
+ * and     := cmp ( "&&" cmp )*
+ * cmp     := unary ( ( "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" ) unary )?
+ * unary   := "!" unary | primary
+ * primary := "(" expr ")" | literal | key
+ * literal := 'single-quoted string' | number | true | false | null
+ * key     := ident ( "." ident )*        // bare key => truthiness test
+ *          | ( "plugin" | "config" ) ":" ident ( "." ident )* ":" ident ( "." ident )*
+ * ```
+ *
+ * The second `key` alternative is **F14.11** and is additive: `:` was previously
+ * a lex error, so no existing valid expression changes meaning. It is positional
+ * and not a charset widening — `:` is legal at exactly two offsets of a key
+ * whose head is the bare ident `plugin` or `config`, which is what keeps `a:b`,
+ * `plugin:a`, `plugin:a:b:c` and `scene:id` lex errors. Implementing the clause
+ * as "add `:` to `isIdentPart`" would admit all four.
+ *
+ * Note the deliberate divergence from `isValidContextKey` (`keys.ts`): that
+ * function validates the **bare** key a plugin hands to `host.context.set`,
+ * which must stay colon-free because the host supplies the delimiter. This
+ * production reads the namespaced result.
+ *
+ * XD8 **amended** design-v2's asymmetric `&& || ! == != < >= in` set to add
+ * `>` and `<=`: an author writing `x <= 3` and getting a parse error for no
+ * reason is a footgun, and symmetry costs two parser cases.
+ *
+ * `cmp` takes **at most one** comparison — `a == b == c` is a syntax error, not
+ * a left-associative chain. That is the grammar as frozen, and XB1's validator
+ * plus X4's parser must round-trip the same text, so it is not negotiable here.
+ *
+ * **Compile once.** `compileWhenExpression` returns a closure plus the set of
+ * keys it reads; the store caches by expression text and never re-parses. The
+ * read-set is what makes dependency-indexed batching possible: an expression
+ * re-evaluates only when a key it actually mentions changes.
+ */
+import { type NgisContextValue } from "./keys";
+/** How a compiled expression reads the world. Missing key => `undefined`. */
+export type ContextReader = (key: string) => NgisContextValue | undefined;
+export interface CompiledWhenExpression {
+    /** The source text, verbatim — the cache key and the error-message subject. */
+    readonly expression: string;
+    /** Every key the expression reads, de-duplicated, in first-seen order. */
+    readonly keys: readonly string[];
+    /** Evaluates against a reader. Never throws for missing or odd-typed keys. */
+    evaluate(read: ContextReader): boolean;
+}
+/**
+ * A malformed expression. Typed so a contribution registrar can refuse one
+ * manifest entry with a precise reason instead of failing the whole plugin —
+ * and so the refusal is distinguishable from a host bug.
+ */
+export declare class NgisWhenSyntaxError extends Error {
+    readonly code: "when-syntax";
+    readonly expression: string;
+    /** 0-based offset into `expression` where parsing stopped. */
+    readonly position: number;
+    constructor(expression: string, position: number, message: string);
+}
+/**
+ * Compiles a when-grammar v1 expression into a closure plus its read-set.
+ *
+ * @throws {NgisWhenSyntaxError} on malformed input.
+ */
+export declare function compileWhenExpression(expression: string): CompiledWhenExpression;