@ngis/plugin-sdk 0.4.0

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

@@ -0,0 +1,288 @@
+/**
+ * Stage 13 (capability contract) — the frozen type text for `contributes` v1.
+ *
+ * **Authored at the W2 kickoff, not by a session.** X4a parses these shapes,
+ * X4b's loader path consumes the parse result, and X3's settings renderer
+ * consumes `NgisSettingsContribution`. Three concurrent agents needing the same
+ * type names is exactly the collision that bit W1 (X1 and X2 both declared
+ * `NgisResourceType` and clashed on the exported *name*, invisible to either
+ * agent alone until merge). So the names live here, owned by the kickoff, and
+ * **no W2 session declares any of them**.
+ *
+ * Every shape below is **F13.3 verbatim**
+ * (`docs/capability_contract_stage/README.md` → "Frozen contracts (X0)").
+ * A session that needs a change here stops and raises it — it does not diverge
+ * locally, because XB1's validator (already merged) and X4a's parser must agree
+ * fixture-for-fixture on the six frozen manifests in `src/sdk/__fixtures__/`.
+ *
+ * Type-only module: no runtime imports, no React. The caps are `const` because
+ * they are the same numbers XB1 enforces at publish time — a drift between the
+ * two is a silent-truncation bug (F13.10 makes over-cap a *rejection*, never a
+ * truncation).
+ */
+/** F13.10. Enforced by XB1 at publish time and X4a at parse time. */
+export declare const NGIS_MAX_STATUS_ITEMS_PER_PLUGIN = 2;
+/** F13.10. Host row capacity; the rest collapse into a `+N` popover. */
+export declare const NGIS_MAX_VISIBLE_STATUS_ITEMS = 6;
+/** F13.10. Per plugin, per slot. */
+export declare const NGIS_MAX_MENU_ITEMS_PER_PLUGIN_PER_SLOT = 5;
+/**
+ * Every contribution point carries these. `when` false ⇒ not rendered.
+ * `enabledWhen` false ⇒ rendered, disabled, with `disabledReason` (or a generic
+ * host string). `views` takes `when` only — a disabled-but-visible panel has no
+ * meaning, so `NgisViewContribution` does not extend this.
+ */
+export interface NgisGatedContribution {
+    when?: string;
+    enabledWhen?: string;
+    disabledReason?: string;
+}
+export interface NgisStatusItemContribution extends NgisGatedContribution {
+    /** Required, unique within the plugin. */
+    id: string;
+    /** Literal, single-locale (F13.11) — plugin strings are never `labelKey`s. */
+    label?: string;
+    /** lucide icon name. */
+    icon?: string;
+    tooltip?: string;
+    /** A `capabilities.commands` id. */
+    command?: string;
+    /** Rendered as the item's count. */
+    badge?: {
+        contextKey: string;
+    };
+    /** Default 0; higher sorts first. Order is `priority` desc, then plugin id,
+     *  then item id — deterministic, never install-order (F13.10). */
+    priority?: number;
+}
+/** v1 slots — exactly these two. No `map/context`, no `panel/title` (XD19). */
+export type NgisMenuSlot = "layer/context" | "resource/context";
+/** Groups render in this fixed order, separated; within a group, `order` asc
+ *  then item id. Host items always precede plugin items. */
+export type NgisMenuGroup = "navigation" | "modification" | "export" | "plugin";
+export interface NgisMenuItemContribution extends NgisGatedContribution {
+    /** Required — a `capabilities.commands` id. The split rule: `contributes`
+     *  carries only data, and anything needing code references it by id. */
+    command: string;
+    /** Required; literal (F13.11). */
+    label: string;
+    /** Default `"plugin"`. */
+    group?: NgisMenuGroup;
+    order?: number;
+}
+export type NgisMenuContributions = {
+    readonly [S in NgisMenuSlot]?: readonly NgisMenuItemContribution[];
+};
+/**
+ * The two existing panel slots (`PanelSlot` from `./panels`, restated here so
+ * this module stays import-free).
+ *
+ * **Amended 2026-07-27 (W2, X4a finding).** F13.3 originally froze this as
+ * `"left" | "right"` while describing it as "the two existing panel slots".
+ * Both values were wrong: `PanelSlot` has been `"right" | "bottom"` since C7
+ * (`src/sdk/panels.ts:36`, and `workspacePanelRegistry` is constructed with
+ * exactly those two at `:240`). There is no `left` slot — the GIS workspace's
+ * left region is the scene sidebar, a fixed layout column rather than a
+ * registry slot — and `bottom` is a real slot a view could legitimately target.
+ *
+ * The orchestrator amended F13.3 to the union below rather than mapping `left`
+ * onto `right`, because rendering a view in a dock its author did not ask for
+ * is the failure mode F13.9 elsewhere calls out as worse than refusing.
+ * `left` is now an out-of-allowlist value and refuses like any other.
+ * `PackageManifestValidator.VIEW_SLOTS` changed with it; **no fixture changed**,
+ * since `m2-full-0.4.json` is the only fixture declaring a view slot and it
+ * declares `"right"`, which is valid under both unions.
+ */
+export type NgisViewSlot = "right" | "bottom";
+export interface NgisViewContribution {
+    id: string;
+    slot: NgisViewSlot;
+    /** Literal (F13.11). */
+    title: string;
+    icon?: string;
+    order?: number;
+    /** `when` only — see `NgisGatedContribution`. */
+    when?: string;
+}
+export interface NgisToolPreset {
+    id: string;
+    label: string;
+    /** String-valued, matching the task API — the facade does not coerce. */
+    params: Readonly<Record<string, string>>;
+}
+/**
+ * F13.9. Launch + presets + enablement **only**. A stanza cannot expose a free
+ * parameter; generated forms are Stage 14's `ParamForm`. Mounts through the
+ * existing rail "More tools" overflow seam — no new host real estate.
+ */
+export interface NgisToolContribution extends NgisGatedContribution {
+    /** Required, unique within the plugin. */
+    id: string;
+    /** Required — a backend analysis/workflow tool id. */
+    toolId: string;
+    /** Required; literal (F13.11). */
+    label: string;
+    icon?: string;
+    presets?: readonly NgisToolPreset[];
+    /** Only honoured with exactly one preset. */
+    autoRun?: boolean;
+}
+/** Selects the storage leg (F13.7). */
+export type NgisSettingsScope = "user" | "scene";
+export type NgisSettingsPropertyType = "string" | "number" | "integer" | "boolean";
+/**
+ * The JSON-Schema **subset** X3 renders — flat object only. No nested objects,
+ * no arrays, no `$ref`, no `oneOf`/`allOf`, no `pattern`. Widget mapping is
+ * total and fixed, so there is no "unsupported widget" fallback to design:
+ *
+ * | schema | widget |
+ * |---|---|
+ * | `enum` present | `<Select>` |
+ * | `boolean` | `<Switch>` |
+ * | `number` / `integer` | number `<Input>` (with `min`/`max` when given) |
+ * | `string` | text `<Input>` |
+ *
+ * Anything outside the subset is a validation error at publish (XB1) and a
+ * parse refusal (X4a) — the renderer never sees it.
+ */
+export interface NgisSettingsProperty {
+    type: NgisSettingsPropertyType;
+    title?: string;
+    description?: string;
+    default?: string | number | boolean;
+    /** string/number only. */
+    enum?: readonly (string | number)[];
+    /** number/integer only. */
+    minimum?: number;
+    /** number/integer only. */
+    maximum?: number;
+    order?: number;
+}
+export interface NgisSettingsContribution {
+    scope: NgisSettingsScope;
+    properties: Readonly<Record<string, NgisSettingsProperty>>;
+}
+/**
+ * A T3 symbol renderer a plugin **declares**. Stage 24, F24.13, which **amends
+ * F13.3**: `contributes` gained a sixth key.
+ *
+ * The split rule holds — this is data, not code. What the bundle exports is
+ * `symbolRenderers: Record<id, (ctx: SymbolRenderContext) => Layer[]>`; what the
+ * manifest declares is only enough to resolve a symbol reference, draw a param
+ * form and intersect ACLs **before any bundle is fetched**. That ordering is the
+ * whole point: `plugin:<extId>@<version>/<rendererId>` must be answerable from
+ * the manifest alone, or resolution would have to activate every plugin that
+ * might own the renderer.
+ *
+ * Declaring a renderer does **not** force eager activation (F13.4 still holds).
+ * The plugin activates on the first *resolution* of a symbol that names it.
+ *
+ * Shapes are re-declared here rather than imported from
+ * `@/domain/models/symbol`: the SDK's contribution types are the plugin-facing
+ * surface and must not depend on the symbol registry's domain model, and the
+ * manifest's `params`/`slots` are a *declaration subset* — no `layers`, no
+ * `fallback`, no `animation`. The two are held together by the fixture pair
+ * (`m7`/`m8`), not by a shared import.
+ */
+export type NgisSymbolRendererGeometry = "point" | "line" | "polygon";
+export type NgisSymbolRendererParamType = "number" | "color" | "boolean" | "enum" | "angle" | "percent";
+export interface NgisSymbolRendererParam {
+    type: NgisSymbolRendererParamType;
+    label?: string;
+    default: string | number | boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    /** `enum` only. */
+    values?: readonly string[];
+}
+/** The nine slot names of F24.5. A renderer declares which it reads; a slot it
+ *  does not declare is not offered a binding in the scene editor. */
+export type NgisSymbolRendererSlot = "size" | "color" | "angle" | "startTime" | "phase" | "data0" | "data1" | "data2" | "data3";
+export interface NgisSymbolRendererContribution {
+    /** Unique within the plugin. The reference a symbol writes is
+     *  `plugin:<extId>@<version>/<id>`. */
+    id: string;
+    geometry: NgisSymbolRendererGeometry;
+    label?: string;
+    params?: Readonly<Record<string, NgisSymbolRendererParam>>;
+    slots?: readonly NgisSymbolRendererSlot[];
+}
+/** F24.13's cap. Declared here so the two validators quote one number. */
+export declare const NGIS_MAX_SYMBOL_RENDERERS_PER_PLUGIN = 8;
+/**
+ * The top-level `contributes` block. A **sibling of `capabilities`**, not a
+ * capability key (XD3): `KNOWN_CAPABILITY_KEYS` stays
+ * `panels|railTools|layerTypes|commands` in both repos, unchanged.
+ *
+ * The split rule: `capabilities` carries **code** (render functions, handlers,
+ * renderer entries); `contributes` carries **only data**.
+ */
+export interface NgisContributes {
+    statusItems?: readonly NgisStatusItemContribution[];
+    menus?: NgisMenuContributions;
+    views?: readonly NgisViewContribution[];
+    tools?: readonly NgisToolContribution[];
+    settings?: NgisSettingsContribution;
+    /** F24.13 (Stage 24) — amends F13.3 five-key list. Max
+     *  `NGIS_MAX_SYMBOL_RENDERERS_PER_PLUGIN`; duplicate `id` is a validation
+     *  error in both repos. */
+    symbolRenderers?: readonly NgisSymbolRendererContribution[];
+}
+/** F13.5's ten grantable scopes. Frozen at the W1 kickoff as a **flat array of
+ *  scope strings** on the manifest — duplicates are a validation error, order is
+ *  insignificant, an empty array means the same as an absent key. */
+export type NgisPermissionScope = "scene:read" | "resources:read" | "models:read" | "models:run" | "tasks:read" | "tasks:cancel" | "viz:write" | "storage:user" | "storage:scene" | "ui:notify";
+/**
+ * F13.4. Auto-derived from the manifest; a plugin never writes an activation
+ * list. A plugin declaring `capabilities.panels`, `railTools` or `layerTypes` —
+ * the three code-carrying points with no declarative twin — **activates
+ * eagerly**, which is why `"eager"` is a member of this union rather than a
+ * separate flag: the loader branches on one value.
+ */
+export type NgisActivationEvent = "eager" | `onCommand:${string}` | `onView:${string}` | `onTool:${string}` | `onSceneType:${string}` | `onResourceType:${string}`;
+/**
+ * One refusal, naming its field by full path (`contributes.menus.layer/context[2].command`)
+ * — the same discipline XB1's validator errors already follow, so a manifest
+ * rejected by the backend and one refused by the parser read the same way.
+ */
+export interface NgisContributionParseError {
+    /** Full dotted/bracketed path from the manifest root. */
+    path: string;
+    message: string;
+}
+/**
+ * **Total, never throwing.** A malformed `contributes` block must not take the
+ * workspace down — the plugin loads with `contributes: null` and its errors
+ * surfaced, exactly as a bundle that fails to negotiate becomes a `"failed"`
+ * status rather than a boot crash (G-D criterion 6, structural).
+ */
+export interface NgisContributesParseResult {
+    /** `null` when the block is absent **or** refused — `errors` distinguishes. */
+    contributes: NgisContributes | null;
+    /** F13.4's derived set. Empty only for a manifest with no capabilities and no
+     *  contributions at all. */
+    activationEvents: readonly NgisActivationEvent[];
+    /** Empty on success. Non-empty ⇒ `contributes` is `null`. */
+    errors: readonly NgisContributionParseError[];
+}
+/**
+ * The seam between X4a (which implements it) and X4b (which calls it from the
+ * restructured load path).
+ *
+ * X4b takes this **by injection** so it compiles and unit-tests standalone
+ * against a fake, exactly as X1's publishers and X2's facet sources were
+ * dependency-injected in W1. The stub in `./index.ts` satisfies the type until
+ * X4a's implementation merges; **X4b must never import that stub in shipping
+ * code** — it takes the port as a parameter.
+ */
+export interface NgisContributionsPort {
+    /**
+     * @param manifest the raw manifest `JsonNode` as it arrives on the boot /
+     *   scene-resolve payload — parsed **before any bundle is fetched** (XD4).
+     *   That passthrough is the lazy-activation substrate and needs zero backend
+     *   change.
+     */
+    parseContributes(manifest: unknown): NgisContributesParseResult;
+}

package/dist/src/sdk/contributions/views-bridge.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The `views` → workspace-panel bridge (Stage 13 X4a, F13.3 / F13.4).
+ *
+ * A `views` contribution is **data only** (XD3's split rule): an id, a slot, a
+ * literal title, an icon name, an order and a `when`. It carries no render
+ * function, because the bundle that would provide one has not been imported
+ * yet — the manifest arrives on the boot / scene-resolve payload and the whole
+ * point of F13.4 is that opening the view is what *triggers* the import.
+ *
+ * So this bridge registers a real `WorkspacePanelRegistry` entry per visible
+ * view — which is what puts it in the right dock's tab strip and the rail's
+ * panel group — and renders a **host placeholder** as its body. Opening it
+ * fires `onViewOpened`, the seam X4b wires to the derived `onView:<id>`
+ * activation event; once the plugin activates, its real
+ * `capabilities.panels` registration replaces the placeholder under the same
+ * slot (the panel registry is last-wins on id).
+ *
+ * ## The hand-off is one-way (`V-124`, X9c)
+ *
+ * "Replaces the placeholder" was only half true. `sync()` used to re-register
+ * the placeholder **unconditionally** on every contribution notification, and
+ * because `registerPanel` is last-wins on id, an activated plugin's real panel
+ * was reverted to the host placeholder the next time anything changed in the
+ * registry — a plugin whose panel worked when opened and became an empty title
+ * a moment later. The comment justifying the unconditional call was legitimate
+ * (title/icon/order move with the manifest), so the fix is not to stop
+ * re-registering: it is to re-register only over **this bridge's own**
+ * registration, checked by identity against `panels.getPanel(slot, id)`.
+ *
+ * ## The slot union — amended, not mapped
+ *
+ * F13.3 originally froze `views[].slot` as `"left" | "right"` while calling
+ * them "the two existing panel slots". Both values were wrong: `PanelSlot` has
+ * been `"right" | "bottom"` since C7 (`src/sdk/panels.ts:36`). X4a found it,
+ * the orchestrator verified it independently and **amended F13.3 to
+ * `"right" | "bottom"`** — so `NgisViewSlot` and `PanelSlot` are now the same
+ * two values and this bridge does no mapping at all. A `bottom` view registers
+ * into the bottom dock, a `right` view into the right dock, and `left` is
+ * refused by the parser like any other out-of-allowlist value.
+ *
+ * `toPanelSlot` survives as an explicit, tested identity so that a future
+ * divergence between the two unions fails here rather than silently coercing.
+ */
+import type { NgisUnsubscribe } from "../map-api";
+import { type PanelRenderFn, type PanelSlot, type WorkspacePanelRegistry } from "../panels";
+import { type NgisContributionRegistry, type NgisRegisteredView } from "./registry";
+import type { NgisViewSlot } from "./types";
+/**
+ * Both names now live in `./panel-id.ts` — a dependency-free module — because
+ * F14.12 made the id a contract `activation.ts` must build too, and importing
+ * it from here would drag `react-dom/client` into the boot-payload parse path.
+ * Re-exported rather than re-implemented: one declaration, every existing
+ * import path unchanged (`V-127`'s lesson, applied before it happened).
+ */
+export { CONTRIBUTED_VIEW_PANEL_PREFIX, contributedViewPanelId } from "./panel-id";
+/**
+ * Maps a declared `NgisViewSlot` onto a real `PanelSlot`.
+ *
+ * An identity since the F13.3 amendment — the two unions are the same two
+ * values. Kept as a named, tested function rather than inlined so that if the
+ * unions ever diverge again the compiler catches it in one place.
+ */
+export declare function toPanelSlot(slot: NgisViewSlot): PanelSlot;
+export interface ContributedViewPanelsOptions {
+    registry?: NgisContributionRegistry;
+    panels?: WorkspacePanelRegistry;
+    /**
+     * Builds the placeholder body for a contributed view. Defaults to a bare
+     * text node — the framework-agnostic `PanelRenderFn` contract, so this module
+     * needs no React and stays node-testable. The React mount passes a localized
+     * `GIS.contrib.*` string in.
+     */
+    placeholderText?: (view: NgisRegisteredView) => string;
+    /** Full render override, for a host that wants more than a text placeholder. */
+    renderPanel?: (view: NgisRegisteredView) => PanelRenderFn;
+    /**
+     * Fired once per open of a contributed panel. **X4b's seam**: this is where
+     * the derived `onView:<id>` activation event is dispatched, which is what
+     * imports the bundle. Left injectable (and defaulting to a no-op) because
+     * the load path is X4b's file ownership, not this session's.
+     */
+    onViewOpened?: (pluginId: string, viewId: string) => void;
+}
+/**
+ * Keeps `workspacePanelRegistry` in sync with the contribution registry's
+ * visible `views`, and reports opens.
+ *
+ * Returns a disposer that unregisters every panel it created. Idempotent under
+ * repeated calls: registering the same panel id twice is a replace, not a
+ * duplicate (C7 semantics).
+ */
+export declare function bindContributedViewPanels(options?: ContributedViewPanelsOptions): NgisUnsubscribe;

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

@@ -0,0 +1,17 @@
+/**
+ * `defineNgisPlugin()` — a typing-only identity helper for plugin authors
+ * (Stage 11 E3, DevKit). Exists purely so an author writing an `NgisPlugin`
+ * object gets full contextual type inference/autocomplete on `manifest` and
+ * `capabilities` (and, if a future capability adds a generic parameter, on
+ * that too) without hand-annotating the object's type — the same ergonomic
+ * pattern as `defineConfig()` helpers in other tools' SDKs.
+ *
+ * Zero runtime behavior beyond returning its argument: it does not register,
+ * validate, or negotiate anything (that stays the runtime's job, per
+ * `plugin-runtime.ts`). Re-exported by `@ngis/plugin-sdk` (the external
+ * DevKit distribution, `docs/design-extension-platform.md` §13) alongside the
+ * rest of `./plugin`'s types — this file is its single source of truth, not
+ * hand-copied into the published package.
+ */
+import type { NgisPlugin } from "./plugin";
+export declare function defineNgisPlugin(plugin: NgisPlugin): NgisPlugin;

package/dist/src/sdk/facets/storage.d.ts

@@ -0,0 +1,152 @@
+/**
+ * `host.storage` (Stage 13 X3) — the two persistence legs of F13.7.
+ *
+ * |  | user leg | scene leg |
+ * |---|---|---|
+ * | Backing | `ngis_extension_install.settings` (XB2, V4) | `ngis_scene.extension_config` → `plugins[].settings` |
+ * | Key | (user, extension) | (scene, extension) |
+ * | Write path | `PUT /api/extensions/{extId}/settings` | the composition `PUT`, echoing `revision` |
+ * | Who may write | the installer | **the scene owner only** |
+ * | Cap | 32 KiB serialized, server-enforced (`400`) | 32 KiB, **new writes only** |
+ * | Lifecycle | dies with the install row; survives disable | lives and dies with the composition entry |
+ *
+ * ### Three rules this module exists to keep, each a data-loss risk
+ *
+ * 1. **The composition `PUT` carries an opaque `revision` and it must ride the
+ *    round-trip.** {@link createNgisStorageFacet}'s scene leg is a
+ *    read-modify-write that *spreads* the composition it just read
+ *    (`{...composition}`, `{...entry}`), so `revision`, `layout` and every
+ *    field this client has never heard of survive. Rebuilding the object
+ *    literally would drop `revision` silently and restore last-write-wins —
+ *    which is a verified, real data-loss bug (Stage 12 row V-17), not a
+ *    theoretical one. A refusal of a stale revision surfaces as
+ *    `NgisStorageError("conflict")`.
+ * 2. **Existing `plugins[].settings` rows are unvalidated free-form and must
+ *    keep parsing.** Nothing here validates on *read*: `get()` returns whatever
+ *    the entry holds, including shapes no settings schema would accept. The
+ *    32 KiB cap is a **write-path** rule. A change that makes an old row
+ *    unreadable is a data-loss bug.
+ * 3. **Refusals are surfaced, never masked.** `canWrite()` reports the truth so
+ *    a settings form can render read-only instead of failing on submit, and
+ *    `set()` never silently no-ops — it resolves or it rejects.
+ *
+ * ### The one place the contract could not be met (recorded, not worked around)
+ *
+ * F13.7's scene-leg row *"Read by non-installer: yes — a viewer of a shared
+ * scene reads the owner's settings"* has **no endpoint behind it this wave**.
+ * `GET /api/scenes/{id}/extensions` is owner-only (`403`), and W2 froze
+ * `SceneExtensionEntryDto` unchanged, so the scene-resolve payload carries no
+ * `settings`. A viewer therefore reads `null` and `canWrite()` is `false`. The
+ * UI states that in words rather than pretending the plugin has no settings;
+ * the missing projection is backlog row **V-49**.
+ */
+import type { NgisUnsubscribe } from "../map-api";
+import type { NgisStorageFacet, NgisStorageLeg, NgisStorageWriteFailure } from "../host-api";
+import type { NgisContextConfigSource } from "../context/publishers";
+import type { NgisContextValue } from "../context/keys";
+import type { SceneExtensionComposition } from "../../types/extensions";
+/**
+ * The 32 KiB cap (XD11), measured on the **serialized** form — the same thing
+ * the server measures. Not exported from `@/sdk`: the barrel's X3 hunk lists
+ * the names this session may claim there, and this constant is an
+ * implementation detail the settings UI imports by path.
+ */
+export declare const NGIS_STORAGE_MAX_BYTES: number;
+/**
+ * F13.2's typed write refusal. The reason union is **closed** — `read-only`,
+ * `too-large`, `conflict` — so a caller can branch on it exhaustively.
+ */
+export declare class NgisStorageError extends Error {
+    readonly reason: NgisStorageWriteFailure;
+    constructor(reason: NgisStorageWriteFailure, message?: string);
+}
+/**
+ * The user leg's transport — XB2's install-row endpoints, whose contract is
+ * frozen in the W2 kickoff §8:
+ *
+ * - `GET /api/extensions/{extId}/settings` → `200 {"settings": <object|null>}`;
+ *   **`404` when the caller has no install row** (hence `installed`, which is
+ *   what `canWrite()` reports — the leg is writable exactly while installed).
+ * - `PUT /api/extensions/{extId}/settings` — the settings object *is* the body,
+ *   bare; the response is the same `{"settings": …}` envelope the `GET` uses.
+ *   `PUT null` clears. Over-cap is **`400`, not `413`** (the gateway owns 413,
+ *   and the client must be able to tell "your JSON is too big" from "your
+ *   request was too big"), and `400` is also the answer for a non-object body.
+ *
+ * `write` returns the **stored** value, which is *not* byte-comparable with
+ * what was sent: the column is Postgres `jsonb` and normalizes key order,
+ * whitespace, duplicate keys and number formatting. Nothing in this module
+ * diffs the echo against the request — a client that did would decide it had
+ * failed to save and re-save forever.
+ *
+ * Injected rather than imported so this module compiles and unit-tests against
+ * a fake.
+ */
+export interface NgisUserStorageSource {
+    read(extId: string): Promise<{
+        installed: boolean;
+        settings: unknown | null;
+    }>;
+    write(extId: string, value: unknown): Promise<{
+        settings: unknown | null;
+    }>;
+    /** Optional push channel. Absent ⇒ `onChange` still fires on local writes. */
+    subscribe?(listener: () => void): NgisUnsubscribe;
+}
+/**
+ * The scene leg's transport — the existing composition `GET`/`PUT` on
+ * `ngis-scene`. `readComposition` reports `forbidden` rather than throwing on a
+ * `403`, because "you are a viewer" is a normal state this leg must render, not
+ * a failure.
+ */
+export interface NgisSceneStorageSource {
+    getSceneId(): string | null;
+    readComposition(sceneId: string): Promise<{
+        forbidden: boolean;
+        composition: SceneExtensionComposition | null;
+    }>;
+    /** Full replace. The body must be the document `readComposition` returned,
+     *  spread and patched — never rebuilt. */
+    writeComposition(sceneId: string, body: SceneExtensionComposition): Promise<SceneExtensionComposition>;
+    subscribe?(listener: () => void): NgisUnsubscribe;
+}
+export interface NgisStorageSource {
+    /** `NgisHostAPI.pluginId` — the extension id both legs are keyed by. */
+    pluginId: string;
+    user: NgisUserStorageSource;
+    scene: NgisSceneStorageSource;
+}
+/** Serialized byte length — what the cap is measured against. */
+export declare function serializedByteLength(value: unknown): number;
+export declare function createNgisStorageFacet(source: NgisStorageSource): NgisStorageFacet;
+/**
+ * Flattens one plugin's stored settings into the flat map
+ * `publishConfigContextKeys` turns into `config:<pluginId>:<key>` context keys
+ * (F14.11 — the publisher owns the namespacing, and it also owns the skip for a
+ * settings key that cannot *be* namespaced).
+ *
+ * Only what `NgisContextValue` can hold survives: scalars, `null`, and arrays
+ * of string/number. A nested object or a mixed array is **skipped**, not
+ * stringified — a `when` expression comparing against a JSON blob would be a
+ * footgun, and an absent key already evaluates falsy by design (F13.6).
+ */
+export declare function flattenConfigValues(value: unknown): Record<string, NgisContextValue>;
+/**
+ * The real `config:*` key source X1 left a stub for
+ * (`emptyContextConfigSource`, `src/sdk/context/publishers.ts`).
+ *
+ * `NgisContextConfigSource.read()` is **synchronous** while every storage leg is
+ * async, so this holds a cache: `track()` reads the leg once, subscribes to it,
+ * and republishes on every change. Untracking removes the plugin's keys, which
+ * `publishConfigContextKeys` turns into `undefined` writes — an uninstalled
+ * plugin's `config:*` keys stop existing rather than lingering at their last
+ * value.
+ *
+ * Deliberately **not** exported from `@/sdk`: the host call site that would
+ * wire it (`GisWorkspace`'s facade construction) is X4b's file this wave, so
+ * the barrel export lands with the session that mounts it.
+ */
+export declare function createStorageConfigContextSource(): {
+    source: NgisContextConfigSource;
+    track(pluginId: string, leg: NgisStorageLeg): NgisUnsubscribe;
+};