@loomweaver/plugin-sdk 0.7.2

package/README.md

@@ -0,0 +1,11 @@
+# plugin-sdk
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build plugin-sdk` to build the library.
+
+## Running unit tests
+
+Run `nx test plugin-sdk` to execute the unit tests via [Jest](https://jestjs.io).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@loomweaver/plugin-sdk",
+  "version": "0.7.2",
+  "description": "LoomWeaver plugin contract: the public SDK a weaver depends on — ProductIdentity, Command, PluginContext and the host UI vocabulary.",
+  "keywords": [
+    "loomweaver",
+    "plugin",
+    "sdk",
+    "plugin-contract",
+    "angular",
+    "extensibility",
+    "plugin-platform"
+  ],
+  "license": "Apache-2.0",
+  "author": "Norbert Rosenwinkel (https://loomweaver.dev)",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@angular/core": "^22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://loomweaver.dev",
+  "bugs": {
+    "url": "https://github.com/yesbert/loomweaver/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yesbert/loomweaver.git",
+    "directory": "platform/libs/core/plugin-sdk"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,22 @@
+export * from './lib/product-identity.js';
+export * from './lib/contribution.js';
+export * from './lib/capability.js';
+export * from './lib/auth.js';
+export * from './lib/menu.js';
+export * from './lib/command.js';
+export * from './lib/button.js';
+export * from './lib/view.js';
+export * from './lib/view-state.js';
+export * from './lib/plugin-state.js';
+export * from './lib/dirty-surface.js';
+export * from './lib/pane-area.js';
+export * from './lib/container-handle.js';
+export * from './lib/content-route.js';
+export * from './lib/surface.js';
+export * from './lib/bar-item.js';
+export * from './lib/rail-item.js';
+export * from './lib/settings-model.js';
+export * from './lib/dialog-ref.js';
+export * from './lib/dialog.js';
+export * from './lib/notification.js';
+export * from './lib/plugin.js';

package/src/index.js

@@ -0,0 +1,23 @@
+export * from './lib/product-identity.js';
+export * from './lib/contribution.js';
+export * from './lib/capability.js';
+export * from './lib/auth.js';
+export * from './lib/menu.js';
+export * from './lib/command.js';
+export * from './lib/button.js';
+export * from './lib/view.js';
+export * from './lib/view-state.js';
+export * from './lib/plugin-state.js';
+export * from './lib/dirty-surface.js';
+export * from './lib/pane-area.js';
+export * from './lib/container-handle.js';
+export * from './lib/content-route.js';
+export * from './lib/surface.js';
+export * from './lib/bar-item.js';
+export * from './lib/rail-item.js';
+export * from './lib/settings-model.js';
+export * from './lib/dialog-ref.js';
+export * from './lib/dialog.js';
+export * from './lib/notification.js';
+export * from './lib/plugin.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../libs/core/plugin-sdk/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC"}

package/src/lib/auth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Auth-aware, declarative access gating. LoomWeaver owns **none** of authentication —
+ * login, session, tokens, IdP integration live in the product. The platform only *reacts* to a
+ * session snapshot a distribution supplies, so chrome can hide/disable itself by login state and
+ * roles. Roles/claims are **opaque strings**: the platform matches, never interprets.
+ *
+ * Client-side gating is **presentation, not security** — the real enforcement is server-side (the
+ * product BFF rejects unauthorized calls). Never treat a hidden control as a boundary.
+ */
+/** A user/session snapshot the host reacts to. Provider-neutral (OIDC/custom/anything reduces here). */
+export interface AuthSnapshot {
+    /** Whether someone is signed in. */
+    readonly authenticated: boolean;
+    /** Opaque role tokens held by the current principal (empty when anonymous). */
+    readonly roles: readonly string[];
+    /**
+     * Free-form claim bag; values are strings or string lists. It stays in the distribution's own
+     * code: **no plugin receives it** — a plugin permitted the session is told `authenticated` and
+     * `roles`, and nothing else — and **no access requirement evaluates it**, since the host matches
+     * on `authenticated` and `roles` only. Read it from your own composition; do not expect it to
+     * reach a plugin or to gate anything.
+     */
+    readonly claims: Readonly<Record<string, string | readonly string[]>>;
+    /**
+     * Optional stable subject id — the **identity anchor**: the shell's identity-change
+     * policy (`provideAuthSource(..., { onIdentityChange })`) compares it across snapshots, and an
+     * identity-scoped settings store namespaces per-user state by it. Set it whenever the product
+     * can name the signed-in principal; encode the tenant into it if tenant switches should count
+     * as identity changes. Omit it and both features stay inert.
+     */
+    readonly subject?: string;
+    /** Optional, display-only human name. */
+    readonly displayName?: string;
+}
+/** The anonymous baseline — the bare-platform default (nobody signed in). */
+export declare const ANONYMOUS: AuthSnapshot;
+/**
+ * How a contribution reacts to the auth state. Intentionally **coarse** — no expression parser
+ * (consistent with the `when` filter). Generic claim matching is the documented extension
+ * once a real case appears (YAGNI).
+ */
+export interface AccessRequirement {
+    /** Require a specific signed-in state (`true` = must be signed in, `false` = only anonymous). */
+    readonly authenticated?: boolean;
+    /** Require at least one of these roles. */
+    readonly anyRole?: readonly string[];
+    /** Require all of these roles. */
+    readonly allRoles?: readonly string[];
+    /**
+     * Effect on a chrome item when the requirement is **unmet**: `hide` (default) removes it, `disable`
+     * keeps it visible but inert. Routes/commands block on invoke regardless of this flag.
+     */
+    readonly mode?: 'hide' | 'disable';
+}
+/** True when `snapshot` satisfies `access`. An undefined requirement is always allowed. */
+export declare function meetsAccess(access: AccessRequirement | undefined, snapshot: AuthSnapshot): boolean;
+/** Whether a chrome item should render at all: unmet + `hide` (the default) → not visible. */
+export declare function isAccessVisible(access: AccessRequirement | undefined, snapshot: AuthSnapshot): boolean;
+/** Whether a rendered chrome item should be disabled: unmet + `disable`. */
+export declare function isAccessDisabled(access: AccessRequirement | undefined, snapshot: AuthSnapshot): boolean;

package/src/lib/auth.js

@@ -0,0 +1,35 @@
+/**
+ * Auth-aware, declarative access gating. LoomWeaver owns **none** of authentication —
+ * login, session, tokens, IdP integration live in the product. The platform only *reacts* to a
+ * session snapshot a distribution supplies, so chrome can hide/disable itself by login state and
+ * roles. Roles/claims are **opaque strings**: the platform matches, never interprets.
+ *
+ * Client-side gating is **presentation, not security** — the real enforcement is server-side (the
+ * product BFF rejects unauthorized calls). Never treat a hidden control as a boundary.
+ */
+/** The anonymous baseline — the bare-platform default (nobody signed in). */
+export const ANONYMOUS = { authenticated: false, roles: [], claims: {} };
+/** True when `snapshot` satisfies `access`. An undefined requirement is always allowed. */
+export function meetsAccess(access, snapshot) {
+    var _a, _b;
+    if (!access)
+        return true;
+    if (access.authenticated !== undefined && access.authenticated !== snapshot.authenticated) {
+        return false;
+    }
+    const held = new Set(snapshot.roles);
+    if (((_a = access.anyRole) === null || _a === void 0 ? void 0 : _a.length) && !access.anyRole.some((role) => held.has(role)))
+        return false;
+    if (((_b = access.allRoles) === null || _b === void 0 ? void 0 : _b.length) && !access.allRoles.every((role) => held.has(role)))
+        return false;
+    return true;
+}
+/** Whether a chrome item should render at all: unmet + `hide` (the default) → not visible. */
+export function isAccessVisible(access, snapshot) {
+    return meetsAccess(access, snapshot) || (access === null || access === void 0 ? void 0 : access.mode) === 'disable';
+}
+/** Whether a rendered chrome item should be disabled: unmet + `disable`. */
+export function isAccessDisabled(access, snapshot) {
+    return !!access && access.mode === 'disable' && !meetsAccess(access, snapshot);
+}
+//# sourceMappingURL=auth.js.map

package/src/lib/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4BH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAiB,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAqBvF,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CACzB,MAAqC,EACrC,QAAsB;;IAEtB,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,IAAI,MAAM,CAAC,aAAa,KAAK,QAAQ,CAAC,aAAa,EAAE,CAAC;QAC1F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,CAAA,MAAA,MAAM,CAAC,OAAO,0CAAE,MAAM,KAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,IAAI,CAAA,MAAA,MAAM,CAAC,QAAQ,0CAAE,MAAM,KAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAC7B,MAAqC,EACrC,QAAsB;IAEtB,OAAO,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,MAAK,SAAS,CAAC;AACrE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAC9B,MAAqC,EACrC,QAAsB;IAEtB,OAAO,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACjF,CAAC"}

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

@@ -0,0 +1,67 @@
+import { Type } from '@angular/core';
+import { AccessRequirement } from './auth.js';
+/** Bar slots. */
+export type BarSlot = 'start' | 'center' | 'end';
+interface BarItemBase {
+    /** Stable id — same id overrides in place (last wins); used for ordering and removal. */
+    readonly id: string;
+    /** Target Bar region id (e.g. the top bar or a bottom status bar). */
+    readonly bar: string;
+    /** Which Bar slot the item renders in. */
+    readonly slot: BarSlot;
+    /** Lower renders first within a slot (default 0). */
+    readonly order?: number;
+    /**
+     * Declarative auth gating: the host hides (default) or, for a {@link BarButtonItem},
+     * disables this item when the current session does not meet the requirement. `disable` mode only
+     * applies to the host-drawn button — a {@link BarComponentItem} owns its own cell, so it is only
+     * ever hidden. Presentation only; real enforcement is server-side. Omit for an item everyone sees.
+     */
+    readonly access?: AccessRequirement;
+}
+/** A bar item that renders a plugin-provided component (full control over the cell). */
+export interface BarComponentItem extends BarItemBase {
+    /** Component the host renders in the slot. */
+    readonly component: Type<unknown>;
+}
+/**
+ * A declarative bar button — the host renders the button **and** its tooltip from data
+ * (host offering). Lets a plugin add a status-/top-bar button without authoring
+ * a component or importing `<lw-tooltip>`.
+ */
+export interface BarButtonItem extends BarItemBase {
+    /** Icon name shown in the button (optional if a label is given). */
+    readonly icon?: string;
+    /** Transloco key/literal for a visible text label (optional). */
+    readonly label?: string;
+    /** Transloco key/literal for the tooltip; falls back to {@link label}. */
+    readonly tooltip?: string;
+    /**
+     * Id of a menu slot to open as this button'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 button 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;
+    /**
+     * Show the {@link command}'s keyboard shortcut hint next to the label, OS-correct (⌘K on macOS,
+     * Ctrl+K elsewhere) — the same affordance a menu entry has. Only takes effect when {@link command}
+     * names a command that declares a `shortcut`; ignored otherwise. Opt-in because a bar is tighter
+     * than a menu. Default off.
+     */
+    readonly showShortcut?: boolean;
+    /**
+     * Inline behaviour, for a button 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;
+}
+/** A control the host renders into a slot of a Bar region. */
+export type BarItem = BarComponentItem | BarButtonItem;
+export {};

package/src/lib/bar-item.js

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

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

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

package/src/lib/button.d.ts

@@ -0,0 +1,4 @@
+/** Visual weight of a button. */
+export type LwButtonVariant = 'primary' | 'default' | 'success' | 'danger' | 'warning' | 'info' | 'ghost';
+/** Button size; `md` is the default, `sm` for dense chrome (toasts, footers). */
+export type LwButtonSize = 'sm' | 'md';

package/src/lib/button.js

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

package/src/lib/button.js.map

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

package/src/lib/capability.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every coarse capability, in canonical display order. The single source of truth — {@link Capability}
+ * is derived from it so the type and the list can never drift, and a host surface (e.g. the built-in
+ * permissions settings) can iterate them.
+ */
+export declare const CAPABILITIES: readonly ["contributions", "ui", "host", "navigation", "session", "theme", "automation"];
+/**
+ * Coarse capabilities a plugin can hold — capability injection, **default-deny**: a plugin gets
+ * nothing it was not granted. Granularity is intentionally coarse first; a scope
+ * can split into finer ones later without changing the model. Each names a slice of the `ctx`:
+ *
+ * - `contributions` — register contributions (`ctx.registerSurface/Command/BarItem/RailItem/
+ *                     SettingsSection/MenuItem`, `ctx.contributeIcons`).
+ * - `ui`           — use the host UI services (`ctx.ui.*`: dialogs, toasts, settings, context menus).
+ * - `host`         — read host facts (`ctx.host`: version, update state).
+ * - `navigation`   — drive and read the content area (`ctx.navigateContent/openContentTab/
+ *                     closeContentTab/keepContentTab/pinContentTab/unpinContentTab/revealSurface`
+ *                     and the read-side `ctx.activeContent`).
+ * - `session`      — read session facts (`ctx.session`: login state + roles) for self-gating.
+ * - `theme`        — contribute design tokens that re-color the whole app (`ctx.contributeTheme`).
+ * - `automation`   — run actions other plugins contributed (`ctx.invokeCommand`,
+ *                     `ctx.invocableCommands`). A plugin reaches its own commands without it.
+ */
+export type Capability = (typeof CAPABILITIES)[number];
+/**
+ * Thrown when a plugin uses a `ctx` surface it was not granted (default-deny). A curated-v1
+ * misconfiguration (the distribution forgot to grant a capability the plugin needs) surfaces
+ * loudly here rather than as a silent no-op — part of the `ctx`-boundary error taxonomy.
+ */
+export declare class CapabilityError extends Error {
+    readonly capability: Capability;
+    readonly pluginId: string;
+    /** Why this particular call needed the capability, when that is not obvious from the member alone. */
+    readonly reason?: string | undefined;
+    constructor(capability: Capability, pluginId: string, 
+    /** Why this particular call needed the capability, when that is not obvious from the member alone. */
+    reason?: string | undefined);
+}

package/src/lib/capability.js

@@ -0,0 +1,32 @@
+/**
+ * Every coarse capability, in canonical display order. The single source of truth — {@link Capability}
+ * is derived from it so the type and the list can never drift, and a host surface (e.g. the built-in
+ * permissions settings) can iterate them.
+ */
+export const CAPABILITIES = [
+    'contributions',
+    'ui',
+    'host',
+    'navigation',
+    'session',
+    'theme',
+    'automation',
+];
+/**
+ * Thrown when a plugin uses a `ctx` surface it was not granted (default-deny). A curated-v1
+ * misconfiguration (the distribution forgot to grant a capability the plugin needs) surfaces
+ * loudly here rather than as a silent no-op — part of the `ctx`-boundary error taxonomy.
+ */
+export class CapabilityError extends Error {
+    constructor(capability, pluginId, 
+    /** Why this particular call needed the capability, when that is not obvious from the member alone. */
+    reason) {
+        super(`Plugin "${pluginId}" is missing the "${capability}" capability (default-deny).` +
+            (reason ? ` ${reason}` : ''));
+        this.capability = capability;
+        this.pluginId = pluginId;
+        this.reason = reason;
+        this.name = 'CapabilityError';
+    }
+}
+//# sourceMappingURL=capability.js.map

package/src/lib/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/capability.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,eAAe;IACf,IAAI;IACJ,MAAM;IACN,YAAY;IACZ,SAAS;IACT,OAAO;IACP,YAAY;CACJ,CAAC;AAqBX;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YACW,UAAsB,EACtB,QAAgB;IACzB,sGAAsG;IAC7F,MAAe;QAExB,KAAK,CACH,WAAW,QAAQ,qBAAqB,UAAU,8BAA8B;YAC9E,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC/B,CAAC;QARO,eAAU,GAAV,UAAU,CAAY;QACtB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,WAAM,GAAN,MAAM,CAAS;QAMxB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/src/lib/command.d.ts

@@ -0,0 +1,199 @@
+import { AccessRequirement } from './auth.js';
+import { MenuContext } from './menu.js';
+/** A single value an argument or an answer can carry across any plugin boundary. */
+export type CommandScalar = string | number | boolean;
+/** What one declared argument may be given: a single value, or a list of them. */
+export type CommandArgumentValue = CommandScalar | readonly CommandScalar[];
+/** The arguments an invocation supplies, keyed by {@link CommandArgumentBase.name}. */
+export type CommandArguments = Readonly<Record<string, CommandArgumentValue>>;
+/**
+ * What a command may answer with — plain data, because an answer crosses the same boundary its
+ * arguments came from and anything else would arrive stripped of what it was.
+ */
+export type CommandAnswer = CommandScalar | null | readonly CommandAnswer[] | {
+    readonly [key: string]: CommandAnswer;
+};
+/** What every declared argument carries, whatever kind of value it takes. */
+export interface CommandArgumentBase {
+    /** The name the invocation keys this argument by. */
+    readonly name: string;
+    /**
+     * What this argument means, in prose — a Transloco key or a literal. Written for something
+     * *choosing* a value, not for a control labelling one, so say what it selects and what a sensible
+     * value looks like.
+     */
+    readonly description: string;
+    /** Whether an invocation must supply it. Omit for an optional argument. */
+    readonly required?: boolean;
+    /** Take a list of this kind rather than a single value. Omit for a single value. */
+    readonly list?: boolean;
+}
+/** An argument taking a free value of one of the three plain kinds. */
+export interface SimpleCommandArgument extends CommandArgumentBase {
+    readonly kind: 'text' | 'number' | 'boolean';
+}
+/** An argument taking one of a fixed set of strings. */
+export interface ChoiceCommandArgument extends CommandArgumentBase {
+    readonly kind: 'choice';
+    /** The values this argument accepts; anything else is refused before the command runs. */
+    readonly choices: readonly string[];
+}
+/**
+ * One argument a command accepts. The set of kinds is closed on purpose: a caller has to be able to
+ * describe a command to something that has never seen it, and a closed set makes a wrong declaration
+ * a compile error instead of a silent no-op. Widening it later is additive; narrowing it would not be.
+ */
+export type CommandArgument = SimpleCommandArgument | ChoiceCommandArgument;
+/**
+ * Why an invocation was refused. A refusal is not a failure: the command did not run.
+ *
+ * `unavailable` is deliberately one answer for several situations — no such command, not open to a
+ * foreign caller, the session does not meet its access requirement, the window does not host it, the
+ * calling plugin was not granted the capability. Telling them apart would let a caller map what is
+ * installed by invoking ids and reading the reason back.
+ */
+export type CommandRefusalReason = 'unavailable' | 'invalid-arguments' | 'too-deep';
+/** The command ran; `value` is present where the command declares {@link Command.answers}. */
+export interface CommandAnswered {
+    readonly outcome: 'answered';
+    readonly value?: CommandAnswer;
+}
+/** The command did not run. */
+export interface CommandRefused {
+    readonly outcome: 'refused';
+    readonly reason: CommandRefusalReason;
+    /** A developer-facing explanation; never the place to show a user a message. */
+    readonly message: string;
+}
+/** The command ran and threw, or its asynchronous work rejected. */
+export interface CommandFailed {
+    readonly outcome: 'failed';
+    readonly message: string;
+}
+/**
+ * What an invocation answers with. The three cases are distinct because a caller has to tell
+ * "you may not" from "it broke" from "here is your answer", and none of the three may be presented
+ * as either of the others.
+ */
+export type CommandOutcome = CommandAnswered | CommandRefused | CommandFailed;
+/**
+ * A command as offered to a caller that may invoke it — the workbench's own account of what it can
+ * be asked to do. Every text is already resolved to the active language, because a caller outside the
+ * application cannot reach the translation bundles and a raw key would be useless to it.
+ */
+export interface InvocableCommand {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly arguments?: readonly CommandArgument[];
+    readonly answers?: string;
+}
+/**
+ * A named, invocable action.
+ * A command is the stable anchor that a keybinding, a command-palette entry, and a UI item
+ * (rail/bar/view-action/menu) all point at by {@link Command.id}: one behaviour, many triggers.
+ *
+ * Register via `ctx.registerCommand(...)`; a UI item references it with `command: <id>` instead
+ * of carrying its own inline `run()`.
+ */
+export interface Command {
+    /** Stable, namespaced id (e.g. "testbed.reset") — what triggers reference. */
+    readonly id: string;
+    /** Transloco key (or literal) for the command's label (command palette, menus). */
+    readonly title: string;
+    /** Optional icon name — resolved by the host icon registry (a plain string). */
+    readonly icon?: string;
+    /**
+     * Optional default keyboard shortcut — a chord like `"mod+enter"` or `"mod+shift+p"`. Tokens are
+     * case-insensitive and `+`-joined: modifiers `mod` (⌘ on macOS, Ctrl elsewhere), `ctrl`, `meta`/
+     * `cmd`, `alt`/`option`, `shift`, then one key (`k`, `enter`, `escape`, …). The host binds it; user
+     * rebinding is deferred.
+     */
+    readonly shortcut?: string;
+    /**
+     * Declarative auth gating: the host **blocks** this command when the current session
+     * does not meet the requirement — every trigger flows through one seam, so the keybinding no-ops,
+     * the command palette omits it, and a UI item bound to it does nothing. A command is invocable or
+     * not, so `mode` is ignored here. Presentation only — real enforcement is server-side. Omit for a
+     * command everyone can run.
+     */
+    readonly access?: AccessRequirement;
+    /**
+     * Hide this command from the command palette. Set it on a **context-only** command — one whose
+     * {@link Command.run} needs a {@link MenuContext} (a tab or view id) that only a menu supplies, so
+     * the palette (which invokes with no context) could offer nothing but a no-op. Menu items and
+     * keybindings still invoke it normally. Omit for a command the palette should list.
+     */
+    readonly paletteHidden?: boolean;
+    /**
+     * Offer this command in a **pop-out window** as well. Commands are main-window-only by
+     * default: a pop-out shows exactly one surface, with no tab strip, rail or sidebar, and is a viewer
+     * onto that surface rather than half the application. Without this flag the palette omits the
+     * command there, its keybinding no-ops and a UI item bound to it does nothing — the same one seam
+     * `access` flows through.
+     *
+     * The default is the quiet one on purpose: a command *missing* from a pop-out is a small
+     * annoyance, while one that does something surprising in a detached window is the larger failure,
+     * and the shell cannot tell the two apart for a command it did not write.
+     *
+     * Set it on what genuinely belongs beside a single surface — an about dialog, a theme toggle, an
+     * action on the surface's own data. Leave it off for anything that reaches for chrome a pop-out
+     * does not have: navigating the content area (which the shell refuses there anyway, since it would
+     * take the window out of its `/popout/…` address), opening or revealing a tab, focusing a docked
+     * view, changing the layout.
+     */
+    readonly popout?: boolean;
+    /**
+     * What this command *does*, in prose — a Transloco key or a literal. Distinct from
+     * {@link Command.title}, which labels a control: a title is read beside an icon by someone who can
+     * already see where they are, a description is read by something deciding between actions it has
+     * never seen. Omit it and the command has none; the title is never substituted, because a label is
+     * not an explanation.
+     *
+     * A command that sets {@link Command.callable} without one is unusable to the very caller it opened
+     * itself to, and the manifest validator says so.
+     */
+    readonly description?: string;
+    /**
+     * The arguments this command accepts. The host checks an invocation against them before the
+     * command runs — a missing required argument, a value of the wrong kind, or a choice outside the
+     * declared set is refused rather than reaching `run`. That check is for discovery, not for safety:
+     * validate your own inputs as you would without it.
+     */
+    readonly arguments?: readonly CommandArgument[];
+    /**
+     * What this command answers with, in prose — a Transloco key or a literal. Declaring it is what
+     * makes {@link Command.run}'s return value the invocation's answer; without it an invocation
+     * succeeds carrying nothing, whatever `run` happened to return.
+     */
+    readonly answers?: string;
+    /**
+     * Let a caller **other than this plugin** invoke this command by its id. Omitted, it cannot be
+     * reached that way by any route and is absent from everything that lists what such a caller may
+     * run; the plugin that registered it always reaches its own regardless.
+     *
+     * The default is the quiet one on purpose, exactly as {@link Command.popout} is: a command
+     * *missing* from what an automated caller can reach is a small annoyance, while one that does
+     * something surprising because something other than the user triggered it is the larger failure,
+     * and the shell cannot tell the two apart for a command it did not write.
+     *
+     * Opening a command widens nothing else. It still runs only where its {@link Command.access}, its
+     * {@link Command.popout} declaration and the caller's own granted capabilities already allow, so a
+     * caller can never reach through it to something the user could not have triggered themselves.
+     */
+    readonly callable?: boolean;
+    /**
+     * The behaviour. May be async; the host fires it and reports a failure rather than throwing.
+     * The return type is `unknown` so that a one-expression arrow handler still assigns whatever it
+     * returns; the host passes a value back to a caller only where {@link Command.answers} is declared,
+     * and only where the value is plain data.
+     *
+     * Receives an optional {@link MenuContext} when invoked from a menu — e.g. the tab context
+     * menu passes `{ tabId, … }` so `shell.tab.closeOthers` knows which tab. Triggers without a context
+     * (keybinding, palette, rail/bar item) call it with none; `run()` and `run(context)` are both valid.
+     *
+     * `args` holds what an invocation by id supplied, already checked against
+     * {@link Command.arguments}. A trigger the user drove supplies none.
+     */
+    run(context?: MenuContext, args?: CommandArguments): unknown;
+}

package/src/lib/command.js

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

package/src/lib/command.js.map

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

package/src/lib/container-handle.d.ts

@@ -0,0 +1,36 @@
+import { InjectionToken } from '@angular/core';
+/**
+ * What a container child can ask of the container it sits in. Injected by a child
+ * surface, so that a list child can open the item a row stands for in a sibling pane.
+ *
+ * It is a host operation rather than a navigation on purpose. A container tab may sit in a split
+ * pane or in a pop-out, where it holds no browser address at all, and a list whose rows only work
+ * while its container happens to hold the URL would not be a list. While the container *does* hold
+ * the address, the URL follows and shows the focused child; elsewhere the child opens just the same
+ * and the address simply does not express it.
+ *
+ * Only a **docked** surface mounted inside a container receives one; anywhere else the token resolves
+ * to `null`, so a surface that can appear in both places checks before it calls.
+ */
+export interface ContainerHandle {
+    /**
+     * Open a child at an address inside this container, or focus it where it already is. The path is
+     * the child's declared segment with its values filled in — `open('item/42')` for a child declared
+     * as `{ surface: 'app.item', segment: 'item/:itemId' }`.
+     *
+     * It lands in the pane the container declared empty (`{ tabs: [] }`), which is what declaring one
+     * says; without such a pane it lands in the pane that currently carries the container's pointer.
+     *
+     * Give the tab a label, or several open items all read as the child surface's own title.
+     */
+    open(path: string, label?: ContainerTabLabel): void;
+}
+/** How an opened child's tab is labelled — the same fields a content tab carries. */
+export interface ContainerTabLabel {
+    /** Transloco key, or a literal when {@link titleIsLiteral} is set. */
+    readonly title?: string;
+    readonly titleIsLiteral?: boolean;
+    readonly icon?: string;
+}
+/** DI token for the {@link ContainerHandle}; `null` outside a container. */
+export declare const CONTAINER_HANDLE: InjectionToken<ContainerHandle | null>;

package/src/lib/container-handle.js

@@ -0,0 +1,4 @@
+import { InjectionToken } from '@angular/core';
+/** DI token for the {@link ContainerHandle}; `null` outside a container. */
+export const CONTAINER_HANDLE = new InjectionToken('lw.container-handle', { factory: () => null });
+//# sourceMappingURL=container-handle.js.map

package/src/lib/container-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-handle.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/container-handle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAqC/C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,cAAc,CAChD,qBAAqB,EACrB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CACxB,CAAC"}