@loomweaver/plugin-sdk 0.7.2

package/src/lib/plugin-state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A handle on one key of your plugin's own store. Reads are Signal-shaped, exactly like
+ * {@link ViewState} and `ctx.session`, so a template re-reads reactively without subscription
+ * bookkeeping.
+ */
+export interface StateHandle<T = unknown> {
+    /** The stored value, reactive; `undefined` when nothing is stored (apply your own default). */
+    readonly value: () => T | undefined;
+    /**
+     * Whether the store has answered yet. Check it before you apply a default, otherwise a
+     * network-backed store lands its value **after** the user has started typing and overwrites the
+     * input. With a local store this is true immediately; the gate costs nothing there and is the
+     * difference between working and losing input everywhere else.
+     */
+    readonly loaded: () => boolean;
+    /**
+     * Replace the value under this key. It replaces the **whole** value — nothing is merged — so spread
+     * the current one when you change a field. Writes are debounced; call it per keystroke if you like.
+     * Values are JSON: the store is string-valued and crosses a process boundary, so promising
+     * structured clone would be a lie.
+     */
+    set(next: T): void;
+    /** Remove the key from the store. */
+    clear(): void;
+    /** Stop watching. Any pending write is flushed first. */
+    dispose(): void;
+}
+/**
+ * Your plugin's **own** keyed store — `ctx.state`. Every surface of your plugin sees the
+ * same store, whichever dock it sits in, however many instances are open and in every browser window,
+ * which makes it both your persistence and the only channel between your own surfaces. It is
+ * plugin-private by construction: the host prefixes every key with your plugin id and you cannot
+ * leave that namespace, so there is nothing foreign to reach and no capability to grant.
+ *
+ * It holds **working state**, not settings. Settings have their own path precisely because the user
+ * can *see* them in the settings dialog; a free-form settings store would be a back door around that
+ * transparency. Uninstalling your plugin deletes this store (a settings section survives, an
+ * abandoned draft is litter).
+ *
+ * The authoring rule that follows from "set replaces the whole value": **one key per unit of
+ * editing** — a wizard step, not the whole form — and where a surface can exist more than once, key
+ * by instance as well. Two windows editing two keys converge; two windows replacing one key means
+ * last write wins, which is fine for convergence and not fine for the user's typing.
+ */
+export interface PluginState {
+    /**
+     * Watch one key and get a handle on it. This is also how the host learns which keys you care
+     * about: with free-form keys it cannot push everything, so the call that hands out the handle is
+     * the interest registration. Call {@link StateHandle.dispose} when your surface goes away.
+     */
+    watch<T = unknown>(key: string): StateHandle<T>;
+}

package/src/lib/plugin-state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-state.js.map

package/src/lib/plugin-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-state.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/plugin-state.ts"],"names":[],"mappings":""}

package/src/lib/plugin.d.ts

@@ -0,0 +1,259 @@
+import { PluginState } from './plugin-state.js';
+import { Type } from '@angular/core';
+import { Capability } from './capability.js';
+import { Command, CommandArguments, CommandOutcome, InvocableCommand } from './command.js';
+import { MenuItem } from './menu.js';
+import { Disposable } from './contribution.js';
+import { Surface } from './surface.js';
+import { OpenTabInput } from './content-route.js';
+import { BarItem } from './bar-item.js';
+import { RailItem } from './rail-item.js';
+import { SettingsSection } from './settings-model.js';
+import { DialogRef } from './dialog-ref.js';
+import { AlertOptions, ConfirmOptions, OpenOptions, ProgressHandle, ProgressOptions, PromptOptions } from './dialog.js';
+import { NotificationInput } from './notification.js';
+/** What a plugin declares about itself (grows: activation events, version, …). */
+export interface PluginManifest {
+    /** Stable plugin id. */
+    readonly id: string;
+    /** Human-readable name. */
+    readonly name?: string;
+    /**
+     * Capabilities the plugin declares it needs. This is the *request*; the
+     * distribution/tenant *grants* (default-deny, see `provideCapabilityGrants`). The effective set
+     * is what was granted — a declaration alone grants nothing. The declaration is what the install
+     * consent dialog shows and what the Permissions settings manage.
+     */
+    readonly capabilities?: readonly Capability[];
+}
+/**
+ * One row of an ad-hoc context menu opened via {@link PluginUi.openMenu}: a display `label` (a literal —
+ * the weaver localises its own body text), an optional leading `icon` (a host icon-registry name), and an
+ * in-process `run` handler invoked when the row is chosen. Trusted-rung only: `run` is a function, so it
+ * does not cross the sandbox RPC boundary — a sandboxed plugin draws its own `<lw-menu>` instead.
+ */
+export interface UiMenuItem {
+    readonly label: string;
+    readonly icon?: string;
+    readonly run: () => void;
+}
+/**
+ * Host UI services a plugin reaches through `ctx.ui`: modal
+ * dialogs + transient toasts. This is the brokered path that replaces injecting the host
+ * services directly; the `ui` capability gate (default-deny) is enforced in front
+ * of it — a call without the grant throws.
+ */
+export interface PluginUi {
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    alert(options: AlertOptions): Promise<void>;
+    prompt(options: PromptOptions): Promise<string | null>;
+    open<R = unknown>(component: Type<unknown>, options?: OpenOptions): DialogRef<R>;
+    progress(options: ProgressOptions): ProgressHandle;
+    withProgress<T>(options: ProgressOptions, work: Promise<T>): Promise<T>;
+    toast(input: NotificationInput): string;
+    /** Opens the host settings surface; the host renders the registered sections. */
+    openSettings(): DialogRef;
+    /**
+     * Opens an ad-hoc context menu at a viewport point — for a right-click on the weaver's own view body
+     * (a Library row, a canvas node, …). The host draws it with the same `<lw-menu>` popover mechanics as
+     * its own menus (positioning, Escape/outside-pointer dismiss, focus restore). Trusted-rung only: the
+     * items' `run` handlers do not cross the sandbox boundary (a sandboxed plugin self-draws a `<lw-menu>`).
+     */
+    openMenu(items: readonly UiMenuItem[], at: {
+        x: number;
+        y: number;
+    }): void;
+}
+/**
+ * Read-only host facts + app-lifecycle a plugin reaches through `ctx.host` —
+ * so a plugin's About surface gets the version + update state through the brokered `ctx`
+ * instead of importing host services directly. `version`/`updateAvailable` are signal-shaped
+ * (`() => T`) so a template re-reads them reactively.
+ */
+export interface PluginHost {
+    /** The running app version (e.g. "1.2.3"). */
+    readonly version: () => string;
+    /** True once a new version is downloaded and ready to activate. */
+    readonly updateAvailable: () => boolean;
+    /** Whether update checks are possible (a service worker is registered and enabled). */
+    readonly updatesEnabled: boolean;
+    /** Manually check for a new version. */
+    checkForUpdate(): Promise<void>;
+    /** Activate the downloaded version and reload into it. */
+    activateUpdate(): Promise<void>;
+}
+/**
+ * Read-only session facts a plugin reaches through `ctx.session` — so a plugin can gate its
+ * **own** surface/logic by the signed-in user's login state and roles, the imperative counterpart to the
+ * declarative `access` on contributions. LoomWeaver owns no auth: this only reflects the snapshot the
+ * distribution supplied (`provideAuthSource`). Signal-shaped (`() => T`) so a template re-reads reactively;
+ * roles are opaque strings — match, do not interpret. The snapshot's claim bag does not arrive here:
+ * a plugin is told the login state and the roles, and nothing else. Client-side gating is
+ * presentation, not security. Gated by the `session` capability (default-deny).
+ */
+export interface PluginSession {
+    /** Whether someone is signed in. */
+    readonly authenticated: () => boolean;
+    /** The current principal's roles (empty when anonymous). */
+    readonly roles: () => readonly string[];
+    /** Convenience: whether the current principal holds `role`. */
+    hasRole(role: string): boolean;
+}
+/**
+ * The content the URL pane currently shows — the read side of the content area a plugin reaches
+ * through `ctx.activeContent`. Path parameters are extracted against the matched
+ * route's pattern (`ask/:id` on `ask/abc` → `{ id: 'abc' }`), so a plugin never parses URLs.
+ */
+export interface ActiveContent {
+    /** The matched surface's id, or `null` when the matched route carries none. */
+    readonly surfaceId: string | null;
+    /** The full active content path (no leading slash), including any sub-route segment. */
+    readonly path: string;
+    /** The `:param` values of the matched route pattern (empty for parameter-less routes). */
+    readonly params: Readonly<Record<string, string>>;
+}
+/**
+ * The `ctx` a plugin uses to contribute to the host — one uniform contract. Trusted in-process
+ * plugins get a host-backed implementation; sandboxed plugins get the same surface over RPC.
+ */
+export interface PluginContext {
+    /**
+     * Registers a named, invocable {@link Command}. Triggers — rail/bar/
+     * view-action items (via `command: <id>`), keybindings, and the command palette — reference it
+     * by id, so one behaviour has many entry points.
+     */
+    registerCommand(command: Command): Disposable;
+    /**
+     * Registers a {@link Surface} — the **one** author contract for anything the host renders.
+     * Declare *what the surface can do* (`routable`, `instanceable`, `docks`) rather than *where it lives*;
+     * the host places it (a routable surface into the content area, else into its home dock) and the user
+     * re-arranges it from there.
+     *
+     * Replaced `registerView` + `registerRoute`, removed in 0.5.0:
+     * - a panel view → a non-routable surface: `registerSurface({ id, title, docks: ['<regionId>'], component })`
+     * - a content route → a routable surface: `registerSurface({ id, title, routable: { path }, component })`
+     *
+     * Both migrations need an `id` and a `title`, which the old contracts did not carry.
+     */
+    registerSurface(surface: Surface): Disposable;
+    registerBarItem(item: BarItem): Disposable;
+    registerRailItem(item: RailItem): Disposable;
+    /** Contributes a section to the host settings surface. */
+    registerSettingsSection(section: SettingsSection): Disposable;
+    /**
+     * Contributes an item to a named menu slot — e.g. add an action to the tab context menu
+     * (`'content/tab/context'`) or a plugin's own slot. The item names a {@link Command} by id (invoked with
+     * the menu's {@link MenuContext}) and may declare a coarse `when` filter. The host draws the menu.
+     */
+    registerMenuItem(item: MenuItem): Disposable;
+    /**
+     * Contributes custom icon names the weaver can then reference in its contributions
+     * (`Command.icon` / `View.icon` / `RailItem.icon` / `BarButtonItem.icon`). Each value
+     * is a raw SVG string (an `@ng-icons` export or hand-authored markup). Names are flat and
+     * collision-safe: a name already registered by the shell or another plugin is ignored (first-wins,
+     * dev-warned), so pick unique names. The returned {@link Disposable} removes exactly these names.
+     */
+    contributeIcons(icons: Readonly<Record<string, string>>): Disposable;
+    /**
+     * Contributes design tokens (`--lw-*` custom properties) that re-skin the whole app — host chrome and
+     * every other plugin, since all read the same tokens. The vocabulary covers colors and the
+     * UI font (`--lw-font-sans` / `--lw-font-mono`); font *size* is a user preference, not a theme token.
+     * Requires the `theme` capability. Only
+     * whitelisted `--lw-*` names apply; unknown names are ignored. Contributed tokens sit **below** any
+     * tenant/distribution branding in the cascade (Tenant > Plugin > Product), so a plugin themes freely
+     * but never overrides a token the tenant explicitly set. Collisions across plugins are first-wins:
+     * the plugin that contributes a token first owns it in **both** schemes, so a later plugin cannot
+     * take over just its dark value. The returned {@link Disposable} removes exactly these tokens and
+     * the app reverts.
+     *
+     * `tokens` apply in both light and dark mode. Pass the optional `dark` map to override specific
+     * tokens only when dark mode is active — e.g. warm dark surfaces while `tokens` carries
+     * the light palette. Dark overrides win over `tokens` in dark mode; tokens absent from `dark` keep
+     * their `tokens` value across both modes.
+     */
+    contributeTheme(tokens: Readonly<Record<string, string>>, dark?: Readonly<Record<string, string>>): Disposable;
+    /** Navigates the content area to a route path — switches perspective / full-area view (`navigation`). */
+    navigateContent(path: string): void;
+    /**
+     * Opens a titled **dynamic** tab (e.g. an open document) in the content group of the path's
+     * matched route (navigating there activates that group) and navigates to it; opening the same
+     * path again just re-activates it (`navigation`). Set `titleIsLiteral` for a
+     * non-translatable title, `onClose` to free per-tab state when the tab is closed, and `preview` to
+     * open it as a single reused *preview* slot (see {@link OpenTabInput}).
+     */
+    openContentTab(input: OpenTabInput): void;
+    /**
+     * Promotes the **preview** tab rooted at `path` to a permanent tab — the programmatic
+     * "Keep Open", e.g. bound to a double-click or fired when the content is edited. A no-op if the tab
+     * is already permanent or not open (`navigation`).
+     */
+    keepContentTab(path: string): void;
+    /**
+     * **Pins** the dynamic tab rooted at `path`: the host sorts it to the front of its
+     * group and guards it against accidental close (its close control becomes an unpin control).
+     * Pinning also promotes a preview tab. A no-op if the tab is not open (`navigation`).
+     */
+    pinContentTab(path: string): void;
+    /** Unpins the tab rooted at `path` — it returns to a normal, closable tab. No-op otherwise (`navigation`). */
+    unpinContentTab(path: string): void;
+    /** Closes a dynamic content tab by path; the host activates a neighbour (`navigation`). */
+    closeContentTab(path: string): void;
+    /**
+     * Reveals an already-**docked** surface by id (finding #29): activates its tab wherever the user
+     * has placed it — a sidebar panel (expanding a collapsed one) or a content pane — so a command
+     * like "Focus Library" can bring a docked view to the front. Routable surfaces are reached via
+     * {@link navigateContent} instead; container-only children (`docks: []`) live inside their
+     * container and are not revealed from here. A no-op for an unknown or un-placed id (`navigation`).
+     */
+    revealSurface(id: string): void;
+    /**
+     * Signal-shaped read of the {@link ActiveContent} — which routable surface the URL pane
+     * currently shows, with its path parameters (`navigation`). The read side of the content area
+     *: a panel that reacts to "which tab is focused" (an inspector, a details view) reads
+     * this instead of injecting the host's router and parsing URLs, so it stays stable across host
+     * URL-shape changes. `null` when no content route matches. Trusted rung only (like `ui.openMenu`,
+     * it does not cross the sandbox RPC boundary — a sandboxed surface already receives its own state
+     * over the surface channel).
+     */
+    readonly activeContent: () => ActiveContent | null;
+    /**
+     * Runs a registered command by id and answers what it did (`automation`, unless the command is
+     * one this plugin registered itself — its own need no grant).
+     *
+     * Unlike every other member here this **answers a refusal instead of throwing one**, because a
+     * caller working through a list of actions has to handle "you may not" as an outcome rather than as
+     * an exception. The user is still told, exactly as they are for every other refused route.
+     *
+     * A refusal reads `unavailable` for every reason a command cannot be reached — no such id, not
+     * {@link Command.callable}, the session does not meet its {@link Command.access}, this window does
+     * not host it, the grant is missing — so that invoking ids and reading the reason back cannot map
+     * what is installed.
+     */
+    invokeCommand(id: string, args?: CommandArguments): Promise<CommandOutcome>;
+    /**
+     * The commands this plugin may invoke that it did not register itself (`automation`) — the
+     * workbench's own account, already narrowed by everything that would refuse the invocation, with
+     * every text resolved to the active language. Empty without the grant, whatever is installed.
+     *
+     * Read it instead of keeping a list of your own: a second list is a second answer to "may this
+     * run", and it is not the one the user can see and withdraw.
+     */
+    readonly invocableCommands: () => readonly InvocableCommand[];
+    /** Host UI services (dialogs, toasts). */
+    readonly ui: PluginUi;
+    /** Read-only host facts + app-lifecycle (version, update). */
+    readonly host: PluginHost;
+    /** Read-only session facts (login state + roles) for self-gating (gated by `session`). */
+    readonly session: PluginSession;
+    /**
+     * Your plugin's own keyed store — working state shared by all your surfaces, in every window
+     *. Ungated: it is plugin-private by construction, so there is nothing foreign to reach.
+     */
+    readonly state: PluginState;
+}
+/** A LoomWeaver plugin: declares itself and contributes on activation. */
+export interface Plugin {
+    readonly manifest: PluginManifest;
+    activate(ctx: PluginContext): void | Promise<void>;
+    deactivate?(): void;
+}

package/src/lib/plugin.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin.js.map

package/src/lib/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/plugin.ts"],"names":[],"mappings":""}

package/src/lib/product-identity.d.ts

@@ -0,0 +1,25 @@
+import { InjectionToken, Provider } from '@angular/core';
+/**
+ * The product a LoomWeaver installation presents as (name, tagline, logo).
+ *
+ * Branding lives in the distribution (composition root), never in the platform
+ * core: a distribution provides its identity, the neutral shell renders it. The
+ * bare platform falls back to {@link LOOMWEAVER_IDENTITY}.
+ */
+export interface ProductIdentity {
+    /** Literal brand name, e.g. `Acme Studio`. Not localized. */
+    readonly name: string;
+    /** Transloco key for the tagline (a literal renders as-is if it is no key). */
+    readonly tagline: string;
+    /** URL/path to the square product logo. */
+    readonly logoUrl: string;
+}
+/** Bare-platform fallback used when no distribution configures an identity. */
+export declare const LOOMWEAVER_IDENTITY: ProductIdentity;
+/**
+ * Active product identity. Defaults to {@link LOOMWEAVER_IDENTITY}; a
+ * distribution overrides it via {@link provideProductIdentity}.
+ */
+export declare const PRODUCT_IDENTITY: InjectionToken<ProductIdentity>;
+/** Provider a distribution uses to declare its product identity. */
+export declare function provideProductIdentity(identity: ProductIdentity): Provider;

package/src/lib/product-identity.js

@@ -0,0 +1,17 @@
+import { InjectionToken } from '@angular/core';
+/** Bare-platform fallback used when no distribution configures an identity. */
+export const LOOMWEAVER_IDENTITY = {
+    name: 'LoomWeaver',
+    tagline: 'shell.tagline',
+    logoUrl: 'loom-icon-64.png',
+};
+/**
+ * Active product identity. Defaults to {@link LOOMWEAVER_IDENTITY}; a
+ * distribution overrides it via {@link provideProductIdentity}.
+ */
+export const PRODUCT_IDENTITY = new InjectionToken('PRODUCT_IDENTITY', { providedIn: 'root', factory: () => LOOMWEAVER_IDENTITY });
+/** Provider a distribution uses to declare its product identity. */
+export function provideProductIdentity(identity) {
+    return { provide: PRODUCT_IDENTITY, useValue: identity };
+}
+//# sourceMappingURL=product-identity.js.map

package/src/lib/product-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-identity.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/product-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAY,MAAM,eAAe,CAAC;AAkBzD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAoB;IAClD,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,eAAe;IACxB,OAAO,EAAE,kBAAkB;CAC5B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,cAAc,CAChD,kBAAkB,EAClB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,mBAAmB,EAAE,CAC3D,CAAC;AAEF,oEAAoE;AACpE,MAAM,UAAU,sBAAsB,CAAC,QAAyB;IAC9D,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC3D,CAAC"}

package/src/lib/rail-item.d.ts

@@ -0,0 +1,61 @@
+import { AccessRequirement } from './auth.js';
+/**
+ * A Rail/Ribbon item: an **independent command** triggered from the far
+ * rail — not a view switcher (switching views is the panel's tab bar). Mirrors
+ * Obsidian's ribbon (`addRibbonIcon`).
+ */
+export interface RailItem {
+    readonly id: string;
+    /** Target Rail region id. */
+    readonly rail: string;
+    /** Icon name — resolved by the host icon registry (a plain string). */
+    readonly icon: string;
+    /**
+     * One or two letters the host draws **instead of** the icon, for an entry whose name is the user's
+     * rather than yours (a saved workspace, a project, an account) — a fixed glyph would make every
+     * such entry look alike. {@link icon} stays required as the fallback for a name too short or too
+     * foreign to abbreviate.
+     *
+     * Keep it to two characters: the rail draws them at icon size, and three no longer read at a
+     * glance. The host renders them in the app font and in the same colour the icon would have taken,
+     * so hover and the active marker behave exactly as elsewhere.
+     */
+    readonly initials?: string;
+    /** Transloco key (or literal) for the tooltip/label. */
+    readonly title: string;
+    /** Lower renders first within its anchor group (default 0). */
+    readonly order?: number;
+    /** Pinned to the top (default) or the bottom of the rail (e.g. settings, VS Code style). */
+    readonly anchor?: 'top' | 'bottom';
+    /**
+     * Id of a menu slot to open as this item's **context menu** on right-click — region-agnostic:
+     * the host wires the right-click uniformly and passes a serialisable context (`{ targetKind, id, region }`).
+     * Contribute items to the slot with `ctx.registerMenuItem({ menu, … })`. Omit for no context menu.
+     */
+    readonly menu?: string;
+    /**
+     * Id of a registered {@link Command} this item triggers. Provide this **or** {@link run}; when
+     * set, the host runs that command (so a keybinding/palette can share the same behaviour).
+     */
+    readonly command?: string;
+    /**
+     * Declarative auth gating: the host hides (default) or disables this item when the
+     * current session does not meet the requirement. Presentation only — real enforcement is
+     * server-side. Omit for an item everyone sees.
+     */
+    readonly access?: AccessRequirement;
+    /**
+     * Id of a workspace this item switches to. The host performs the switch itself and
+     * marks the item as the current one while that workspace is active, so a rail entry for a
+     * workspace needs no command of its own. Provide this **instead of** {@link command}/{@link run};
+     * when it is set those are ignored. An id no workspace answers to warns in development.
+     */
+    readonly workspace?: string;
+    /**
+     * Inline behaviour, for an item that is not backed by a registered command. May be async; the
+     * host fires it fire-and-forget. Typed `() => void` so a one-expression arrow whose handler
+     * happens to return a value (e.g. `() => ctx.ui.openSettings()`) still assigns — the return is
+     * ignored either way.
+     */
+    run?(): void;
+}

package/src/lib/rail-item.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rail-item.js.map

package/src/lib/rail-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail-item.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/rail-item.ts"],"names":[],"mappings":""}

package/src/lib/settings-model.d.ts

@@ -0,0 +1,164 @@
+import { Type } from '@angular/core';
+import { LwButtonVariant } from './button.js';
+/**
+ * Settings vocabulary (schema-driven). The host renders a settings
+ * surface from these declarations; each contributor (shell or plugin) supplies its own
+ * value accessors, so the *owner* keeps responsibility for storage. The host only reads
+ * `value()` and calls `set()`. The control vocabulary grows demand-driven (YAGNI):
+ * `select` (single choice) · `toggle` (on/off) · `text` (a string field) · `slider` (a number) ·
+ * `button` (an action) · `component` (embed a component).
+ */
+/** An option in a {@link SettingSelect}. `label` is a Transloco key. */
+export interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * A single-choice dropdown control. It owns its value binding — the contributor supplies
+ * `value()`/`set()`, so the *owner* keeps responsibility for storage (the host only reads
+ * and writes through them). Changes save immediately (the host calls `set()` on change).
+ */
+export interface SettingSelect {
+    readonly kind: 'select';
+    readonly options: readonly SelectOption[];
+    /** Reads the current value — a signal works directly (it is a `() => string`). */
+    readonly value: () => string;
+    /** Persists a new value; the owner decides how and where. */
+    readonly set: (value: string) => void;
+}
+/**
+ * An on/off toggle (switch) control. Like {@link SettingSelect} it owns its value binding — the contributor
+ * supplies `value()`/`set()` (boolean), so the *owner* keeps storage. Changes save immediately.
+ */
+export interface SettingToggle {
+    readonly kind: 'toggle';
+    readonly value: () => boolean;
+    readonly set: (value: boolean) => void;
+}
+/**
+ * A single-line text field control. Owns its value binding (`value()`/`set()` — a string). `inputType`
+ * picks the native input type (default `text`; e.g. `date`/`email`/`number`); `placeholder` is a Transloco
+ * key. Changes save immediately.
+ */
+export interface SettingText {
+    readonly kind: 'text';
+    readonly value: () => string;
+    readonly set: (value: string) => void;
+    readonly inputType?: 'text' | 'date' | 'email' | 'number' | 'password';
+    readonly placeholder?: string;
+}
+/**
+ * A numeric slider control. Owns its value binding (`value()`/`set()` — a number). `min`/`max`/`step` bound
+ * and quantise it (defaults 0/100/1). Changes save immediately.
+ */
+export interface SettingSlider {
+    readonly kind: 'slider';
+    readonly value: () => number;
+    readonly set: (value: number) => void;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+/**
+ * An action button control — no stored value. Provide a registered {@link Command} id via
+ * `command` (so the palette/keybindings can share the behaviour), **or** an inline `run()` for a
+ * one-off action (e.g. opening a dialog). `label` is a Transloco key.
+ */
+export interface SettingButton {
+    readonly kind: 'button';
+    readonly label: string;
+    readonly variant?: LwButtonVariant;
+    /** Id of a registered command to run on click. Provide this **or** {@link run}. */
+    readonly command?: string;
+    /** Inline behaviour for a button not backed by a registered command. Provide this **or** {@link command}. */
+    readonly run?: () => void;
+}
+/**
+ * Embeds an existing component as the control — lets a
+ * setting reuse a host or plugin widget directly instead of re-describing it. The component
+ * reads/writes its own state via its own services.
+ */
+export interface SettingComponent {
+    readonly kind: 'component';
+    readonly component: Type<unknown>;
+    /**
+     * Renders the component as a full-width block instead of in the row's right-hand control slot — for
+     * a self-contained widget that owns the whole row (e.g. a table or a list), not a compact control
+     * sitting beside a label. The row's `label`/`description` are then not painted; the component
+     * provides its own heading.
+     */
+    readonly fullWidth?: boolean;
+}
+/** A settings control — the host renders each kind with the matching primitive. */
+export type SettingControl = SettingSelect | SettingToggle | SettingText | SettingSlider | SettingButton | SettingComponent;
+/**
+ * One row in a settings section: a label/description the host paints and a control it
+ * renders. Value binding (for value controls) lives on the control itself.
+ */
+export interface SettingRow {
+    readonly id: string;
+    /** Transloco key for the row label. */
+    readonly label: string;
+    /** Optional Transloco key for a secondary description line. */
+    readonly description?: string;
+    readonly control: SettingControl;
+}
+/** A contributed group of rows. The host renders sections ordered by `order` (default 0). */
+export interface SettingsSection {
+    readonly id: string;
+    /** Transloco key for the section heading (and its left-nav entry). */
+    readonly title: string;
+    /** Transloco key for the left-nav group header this section sits under (e.g. Options vs Plugins). */
+    readonly group?: string;
+    readonly order?: number;
+    readonly rows: readonly SettingRow[];
+}
+/**
+ * The **data-only** control form a *sandboxed* plugin declares over the RPC boundary (the VS Code
+ * `contributes.configuration` model): the declaration carries the control kind and its
+ * **default value** instead of `value()`/`set()` callbacks, which cannot cross the wire. The host
+ * renders the control, **owns the storage** (user-local through the distribution's `SETTINGS_STORE` port)
+ * and pushes the current values back to the plugin — once after registration and on every change —
+ * by calling the `settingsChanged(sectionId, values)` method the plugin exposes on its RPC channel.
+ */
+export type FrameSettingControl = {
+    readonly kind: 'toggle';
+    readonly value: boolean;
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+    readonly inputType?: 'text' | 'date' | 'email' | 'number' | 'password';
+    readonly placeholder?: string;
+} | {
+    readonly kind: 'select';
+    readonly value: string;
+    readonly options: readonly SelectOption[];
+} | {
+    readonly kind: 'slider';
+    readonly value: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+};
+/**
+ * One declared row of a sandboxed plugin's settings. `label`/`description` may be plain literals — a
+ * sandboxed plugin cannot contribute translations, and the host renders an unknown key as-is.
+ */
+export interface FrameSettingRow {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly control: FrameSettingControl;
+}
+/**
+ * A sandboxed plugin's settings section. Registered over RPC via
+ * `ctx.registerSettingsSection`; the host decides the nav **group** (never the plugin): an
+ * *installed* plugin's section appears under **Community plugins**, a composed frame plugin's
+ * under **App plugins** — a plugin cannot masquerade as part of the app.
+ */
+export interface FrameSettingsSection {
+    readonly id: string;
+    readonly title: string;
+    readonly order?: number;
+    readonly rows: readonly FrameSettingRow[];
+}

package/src/lib/settings-model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=settings-model.js.map

package/src/lib/settings-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-model.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/settings-model.ts"],"names":[],"mappings":""}