@loomweaver/plugin-sdk 0.7.2

package/src/lib/content-route.d.ts

@@ -0,0 +1,254 @@
+import { Type } from '@angular/core';
+import { AccessRequirement } from './auth.js';
+import { PaneArea } from './pane-area.js';
+/**
+ * A **container** surface ("workspace-in-a-tab"): instead of rendering one thing, the host
+ * draws a nested, host-managed pane tree of **child surfaces** inside this surface's content tab —
+ * the same drag/split/min/max mechanics as the top level, one level nested and scoped to
+ * the parent tab instance. A container is always `routable` (it holds its own `:id`); its children are
+ * non-routable surfaces mounted off-router, each receiving the container's route params (its `:id`).
+ */
+export interface ContainerSpec {
+    /**
+     * The child surfaces this container may hold — a bare surface id, or the object form when the child
+     * should also carry an **address** inside the container (see {@link ContainerChildEntry.segment}).
+     * The list is what the inner "new tab" picker offers, access-gated.
+     */
+    readonly children: readonly ContainerChild[];
+    /**
+     * How the tree looks when a container tab is opened fresh — either a plain list of child surface
+     * ids, which is shorthand for one tabs area, or an arrangement in the {@link PaneArea} grammar:
+     *
+     * ```ts
+     * initial: {
+     *   columns: [
+     *     { size: 60, tabs: ['quotes.positions'] },
+     *     { size: 40, rows: [{ tabs: ['quotes.customer'] }, { tabs: ['quotes.margin'] }] },
+     *   ],
+     * }
+     * ```
+     *
+     * A container whose path carries an `:id` needs this: its tree is keyed per instance, so no user
+     * gesture can ever become the default for the next one. The declaration applies whenever the tab
+     * is opened fresh; while it stays open the user's own arrangement wins.
+     *
+     * Every named child must also be listed in {@link children} — an entry that is not is dropped with
+     * a developer warning, as is a structurally invalid area. A child the current user may not see is
+     * still laid out and shows the host's access placeholder in its pane, so a session that has not
+     * arrived yet cannot flatten the declared layout.
+     */
+    readonly initial?: readonly string[] | ContainerArea;
+}
+/** A container child — a bare surface id, or the object form for a child that carries an address. */
+export type ContainerChild = string | ContainerChildEntry;
+export interface ContainerChildEntry {
+    /** The child surface id. */
+    readonly surface: string;
+    /**
+     * The child's address **inside** this container, in Angular path syntax, so it may carry values:
+     * `'list'`, `'entry/:entryId'`. Declaring one turns the child into something a sibling can open
+     * several times over — a list child opens `entry/e-01` and `entry/e-02` as two tabs, each its own
+     * pane if the user splits them, each with its own `VIEW_STATE`, all of it surviving a reload
+     * because it lives in the container's tree.
+     *
+     * The address is **relative**: it means nothing outside this container, which is what lets the same
+     * child surface serve several containers under different names, and what keeps the container
+     * sealed. While the container tab holds the browser address, the URL shows the focused child
+     * (`/runs/abc123/verdict`); in a split pane or a pop-out the child stays put and the address simply
+     * does not express it.
+     *
+     * Without a segment the child behaves exactly as it always has: reachable from the inner picker,
+     * one instance, no address.
+     *
+     * A child whose segment carries a value cannot be seeded in {@link ContainerSpec.initial} or offered
+     * by the picker — neither knows what value to use. It is opened by a sibling, which is the point.
+     * Declare a pane as `{ tabs: [] }` to say where those children land.
+     */
+    readonly segment?: string;
+}
+/** A container's initial arrangement — the {@link PaneArea} grammar over child surface ids. */
+export type ContainerArea = PaneArea<ContainerTabEntry>;
+/** A tab in a container declaration — a child surface id, or the object form for the extra flags. */
+export type ContainerTabEntry = string | ContainerTab;
+export interface ContainerTab {
+    /** The child surface id the tab mounts; it must be listed in {@link ContainerSpec.children}. */
+    readonly surface: string;
+    /**
+     * `false` fixes the tab inside this container: it shows no close affordance, "close others" and
+     * "close all" spare it, and it cannot be dragged to another pane of the container.
+     */
+    readonly closable?: boolean;
+    /** Marks the area's initially active tab; without it the first tab is active. */
+    readonly active?: boolean;
+}
+/**
+ * What a content route renders from (the UI-boundary form). Exactly one is set:
+ *
+ * - `component` — an Angular class rendered in-process (trusted rung; the default today). Cannot
+ *   cross an RPC boundary, so a **sandboxed** plugin never uses this form.
+ * - `iframe` — a URL the host mounts as an **isolated** `<iframe sandbox>` surface. A plain string, so it
+ *   serialises over the `ctx`-RPC boundary; this is how a sandboxed, non-Angular plugin contributes a
+ *   content view (the first untrusted rung). A **trusted** plugin may use it too, to embed a foreign
+ *   origin on purpose (a dashboard, a docs site, a video): a sandboxed plugin is confined to same-origin
+ *   URLs at the RPC seam, whereas for a trusted one the distribution's CSP `frame-src` decides.
+ * - `container` — the host draws a nested pane tree of child surfaces.
+ *
+ * (`element` — a Web-Component tag — is the reserved form for the later WC rung; not yet.)
+ */
+export type ContentSurface = {
+    readonly component: Type<unknown>;
+    readonly loadComponent?: never;
+    readonly iframe?: never;
+    readonly container?: never;
+} | {
+    readonly loadComponent: () => Promise<Type<unknown>>;
+    readonly component?: never;
+    readonly iframe?: never;
+    readonly container?: never;
+} | {
+    readonly iframe: string;
+    readonly component?: never;
+    readonly loadComponent?: never;
+    readonly container?: never;
+} | {
+    readonly container: ContainerSpec;
+    readonly component?: never;
+    readonly loadComponent?: never;
+    readonly iframe?: never;
+};
+/** The route metadata shared by every surface form. */
+export interface ContentRouteBase {
+    /**
+     * The originating surface's id — the handle a distribution omits the route by
+     * (`provideShell({ omit: ['route:<id>'] })`). Distinct from {@link path}, which stays the
+     * **override** handle (re-registering a path replaces it in place, last-in wins). Carried through
+     * from `ctx.registerSurface`; a route without an id can never be omitted.
+     */
+    readonly id?: string;
+    /** Route path (Angular syntax), e.g. `'reports'`, `'doc/:id'`, `'dashboard'`. */
+    readonly path: string;
+    /**
+     * A chromeless surface owns the whole content area while active — carried through from
+     * `SurfaceRoutable.chromeless`: no tab strip, never a tab, excluded from splits, drags and the
+     * new-tab picker.
+     */
+    readonly chromeless?: boolean;
+    /**
+     * Default title/icon for the tab the host opens when navigation lands on this route without an
+     * explicit `openContentTab` (a shared deep-link, browser history, `navigateContent`). A plugin can
+     * still refine it via `openContentTab` (e.g. the real document name). Omit and the host falls back
+     * to the last path segment.
+     */
+    readonly title?: string;
+    readonly icon?: string;
+    /**
+     * Facet ordering — carried through from `SurfaceBase.order`: a following surface's permanent facet
+     * tab renders lower orders first.
+     */
+    readonly order?: number;
+    /**
+     * Whether {@link title} is a **literal** (shown verbatim) rather than a Transloco key. Default `false`
+     * (translated). The auto-open fallback (last path segment) is always treated as a literal. Set this
+     * `true` when the route's default title is a non-translatable string, to avoid a benign
+     * "missing translation" dev warning.
+     */
+    readonly titleIsLiteral?: boolean;
+    /**
+     * Nested sub-route segments under this route — the view's own level-2 tabs (e.g. `['code','preview']`),
+     * reflected in the URL as real path segments (`doc/:id/code`) so they are shareable and restorable
+     *. Angular syntax, so a segment may **carry a value** (`'structure/:structureId'`). There is
+     * **no forced default**: the bare tab root is a valid address and the surface decides what it shows
+     * there. The route's `path` stays the **tab root**: navigating between sub-routes stays in one tab and
+     * preserves the parent component's state. The view reads the active sub from the URL and renders it
+     * (a component view needs a `<router-outlet>`; an `iframe` surface is told the active sub over its
+     * channel).
+     */
+    readonly subRoutes?: readonly string[];
+    /**
+     * Keep this route's permanent tab pointing at the current selection — carried through from
+     * {@link SurfaceRoutable.follows}: the host substitutes the parameter values it knows by name into
+     * this pattern, truncating before the first it does not know.
+     */
+    readonly follows?: boolean;
+    /**
+     * Own everything below {@link path} — carried through from {@link SurfaceRoutable.rest}: the host
+     * routes any deeper address to this route and hands the remainder over as the rest (verbatim,
+     * including the query string), while {@link path} stays the tab root.
+     */
+    readonly rest?: boolean;
+    /**
+     * Declarative auth gating: when the current session does not meet the requirement the host
+     * renders a neutral **"sign-in required" placeholder** at this URL instead of the route's surface (the
+     * URL is preserved), or — if the distribution provided one via `provideUnauthorizedRedirect` — redirects
+     * to the product's login. Reactive: the surface appears once the session qualifies, no reload. A route
+     * is reachable or not, so `mode` is ignored. Presentation only — real enforcement is server-side. Omit
+     * for a route everyone can reach.
+     */
+    readonly access?: AccessRequirement;
+    /**
+     * Retention when this route's surface is hidden — carried through from
+     * {@link Surface.retain}. `'always'` keeps the instance alive while hidden; `'never'` forces
+     * destruction; omitted falls back to the distribution's retention default (destroy).
+     */
+    readonly retain?: 'always' | 'never';
+    /**
+     * Auto-save on hiding — carried through from {@link Surface.saveOn}: a hidden dirty
+     * instance's `surfaceSave` is called fire-and-forget.
+     */
+    readonly saveOn?: 'hide';
+    /** Whether the user may close a tab of this route — carried through from {@link Surface.closable}. */
+    readonly closable?: boolean;
+    /**
+     * Whether the host insets this surface from its pane edges (default `true`). Declare `false` for a
+     * surface that owns its own edges — a viewer, a canvas, a map, an edge-to-edge table. See
+     * `SurfaceBase.padded`.
+     */
+    readonly padded?: boolean;
+}
+/**
+ * A URL-addressed view in the content area. Unlike a {@link View} (which docks into
+ * a Panel region and is chrome-local), a content route is reached by its `path`, so it is a shareable
+ * deep-link with browser back/forward. The content area has a single `<router-outlet>`, so a route
+ * needs no region id. Its surface is either an Angular `component` (trusted only — it cannot cross an RPC
+ * boundary) or an `iframe` URL (the form a sandboxed plugin uses; a trusted plugin may also use
+ * it to embed a foreign origin) — see {@link ContentSurface}. This is the host's **internal** shape
+ * for a routable surface: authors do not build one directly — contribute a {@link Surface} via
+ * `ctx.registerSurface` and the host normalises it into this.
+ */
+export type ContentRoute = ContentRouteBase & ContentSurface;
+/** Input to `ctx.openContentTab` — opens a titled **dynamic** tab and navigates to it. */
+export interface OpenTabInput {
+    /** Concrete path to navigate to, e.g. `'doc/abc'` (not a pattern). */
+    readonly path: string;
+    /** Human title for the tab (e.g. the document name) — dynamic, not known from the URL. */
+    readonly title: string;
+    /** Icon name for the tab. */
+    readonly icon?: string;
+    /**
+     * Whether {@link title} is a **literal** (shown verbatim) rather than a Transloco key. Default
+     * `false` (the host translates it, preserving key-titled dynamic tabs). Set `true` for an inherently
+     * dynamic title — a document name, an entity label — so the host skips the i18n lookup and does not
+     * log a benign "missing translation" dev warning (finding #8).
+     */
+    readonly titleIsLiteral?: boolean;
+    /**
+     * Runs once when **this** tab is closed (the host's close control, or `ctx.closeContentTab`), giving
+     * the weaver a hook to free per-tab state, cancel in-flight work or persist a draft. Not called when
+     * the tab is merely deactivated (still open) or when the whole plugin deactivates. Re-opening the same
+     * path replaces the handler with the latest one. (The callback itself cannot cross the sandbox RPC
+     * boundary and is dropped there — instead the host calls the optional `contentTabClosed(path)` method
+     * a sandboxed plugin's entry document may expose on its RPC channel.)
+     */
+    readonly onClose?: () => void;
+    /**
+     * Opens this as a **preview tab** (VS-Code "Preview Editors") — a single, reused, *italic*
+     * slot per pane for transient browsing: a subsequent `openContentTab({ preview: true })` for
+     * a **different** path replaces this tab's content instead of adding a tab, so browsing many items
+     * doesn't pile up tabs. Promotion to a permanent tab is **explicit**: double-click the tab, or call
+     * `ctx.keepContentTab(path)`. Re-opening the **same** path deliberately does *not* promote it and
+     * preserves the tab's current state — a view commonly re-opens itself on mount to refine its title,
+     * which would otherwise make every preview tab permanent the moment it renders. Default `false`
+     * (a permanent tab). Ignored when the distribution disabled preview (`provideShellFeatures({ content: { preview: false } })`).
+     */
+    readonly preview?: boolean;
+}

package/src/lib/content-route.js

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

package/src/lib/content-route.js.map

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

package/src/lib/contribution.d.ts

@@ -0,0 +1,4 @@
+/** Handle to undo a contribution (a plugin keeps it to clean up on deactivate). */
+export interface Disposable {
+    dispose(): void;
+}

package/src/lib/contribution.js

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

package/src/lib/contribution.js.map

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

package/src/lib/dialog-ref.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Handle to an open dialog. A plugin's dialog body injects it to close itself
+ * and read its `data`; `open()` returns it so the caller can await the result via `closed`.
+ */
+export declare class DialogRef<R = unknown> {
+    readonly data: unknown;
+    private resolveClosed;
+    private settled;
+    private readonly maximizedState;
+    /**
+     * Whether the dialog is currently maximized to near-fullscreen. The host frame reacts (panel
+     * size); a bare dialog body reads it to stretch its own chrome.
+     */
+    readonly maximized: import("@angular/core").Signal<boolean>;
+    /** Resolves with the dialog result once it closes (or `undefined` if dismissed). */
+    readonly closed: Promise<R | undefined>;
+    constructor(data?: unknown);
+    /**
+     * Toggles near-fullscreen. The host frame shows a maximize/restore control when the dialog was
+     * opened with `maximizable`; a bare dialog draws its own control and calls this directly.
+     */
+    toggleMaximized(): void;
+    /** Closes the dialog with an optional result. Idempotent — later calls are ignored. */
+    close(result?: R): void;
+}

package/src/lib/dialog-ref.js

@@ -0,0 +1,37 @@
+import { signal } from '@angular/core';
+/**
+ * Handle to an open dialog. A plugin's dialog body injects it to close itself
+ * and read its `data`; `open()` returns it so the caller can await the result via `closed`.
+ */
+export class DialogRef {
+    constructor(data = undefined) {
+        this.data = data;
+        this.settled = false;
+        this.maximizedState = signal(false);
+        /**
+         * Whether the dialog is currently maximized to near-fullscreen. The host frame reacts (panel
+         * size); a bare dialog body reads it to stretch its own chrome.
+         */
+        this.maximized = this.maximizedState.asReadonly();
+        /** Resolves with the dialog result once it closes (or `undefined` if dismissed). */
+        this.closed = new Promise((resolve) => {
+            this.resolveClosed = resolve;
+        });
+    }
+    /**
+     * Toggles near-fullscreen. The host frame shows a maximize/restore control when the dialog was
+     * opened with `maximizable`; a bare dialog draws its own control and calls this directly.
+     */
+    toggleMaximized() {
+        this.maximizedState.update((value) => !value);
+    }
+    /** Closes the dialog with an optional result. Idempotent — later calls are ignored. */
+    close(result) {
+        if (this.settled) {
+            return;
+        }
+        this.settled = true;
+        this.resolveClosed(result);
+    }
+}
+//# sourceMappingURL=dialog-ref.js.map

package/src/lib/dialog-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog-ref.js","sourceRoot":"","sources":["../../../../../../libs/core/plugin-sdk/src/lib/dialog-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC;;;GAGG;AACH,MAAM,OAAO,SAAS;IAgBpB,YAAqB,OAAgB,SAAS;QAAzB,SAAI,GAAJ,IAAI,CAAqB;QAdtC,YAAO,GAAG,KAAK,CAAC;QACP,mBAAc,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAEhD;;;WAGG;QACM,cAAS,GAAG,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC;QAEtD,oFAAoF;QAC3E,WAAM,GAA2B,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAChE,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC/B,CAAC,CAAC,CAAC;IAE8C,CAAC;IAElD;;;OAGG;IACH,eAAe;QACb,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,MAAU;QACd,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/src/lib/dialog.d.ts

@@ -0,0 +1,105 @@
+import { LwButtonVariant } from './button.js';
+/**
+ * Severity of a dialog. Drives the leading icon + its tint and the confirm
+ * button colour in one field, so they always match the theme.
+ */
+export type DialogTone = 'default' | 'info' | 'success' | 'warning' | 'danger';
+/** Panel width for a dialog opened with a custom body. Defaults to `md`. */
+export type DialogSize = 'md' | 'lg' | 'xl';
+/**
+ * Validated single-input guard for a confirm (e.g. type-to-confirm a destructive action).
+ * `validate` is the uniform validation contract: return `null` to **allow**
+ * confirming, or a string to **block** it. A non-empty string is shown inline as the reason;
+ * an **empty string blocks silently** (e.g. a type-to-confirm whose instruction is in `label`).
+ */
+export interface RequireConfirmation {
+    /** Label above the input (Markdown), e.g. `Type **Reset** to confirm`. */
+    readonly label: string;
+    /** `null` = allow; a string = block (non-empty shown inline, empty blocks silently). */
+    readonly validate: (value: string) => string | null;
+    readonly placeholder?: string;
+}
+/** Options for a yes/no confirm. `message` is Markdown. */
+export interface ConfirmOptions {
+    readonly title?: string;
+    readonly message: string;
+    readonly confirmLabel?: string;
+    readonly cancelLabel?: string;
+    /** Severity → icon + confirm button colour. Defaults to `default` (primary). */
+    readonly tone?: DialogTone;
+    /** Override the tone's default leading icon (host icon name). */
+    readonly icon?: string;
+    /** Require the user to type an exact phrase before confirming (destructive guard). */
+    readonly requireConfirmation?: RequireConfirmation;
+}
+/** Options for an alert (single acknowledge button). `message` is Markdown. */
+export interface AlertOptions {
+    readonly title?: string;
+    readonly message: string;
+    readonly okLabel?: string;
+    readonly tone?: DialogTone;
+    readonly icon?: string;
+}
+/** Options for a text prompt. `message` is Markdown. */
+export interface PromptOptions {
+    readonly title?: string;
+    readonly message: string;
+    readonly initial?: string;
+    readonly placeholder?: string;
+    readonly confirmLabel?: string;
+    readonly cancelLabel?: string;
+    readonly tone?: DialogTone;
+    readonly icon?: string;
+}
+/** A footer button declared for a custom-body dialog. */
+export interface DialogButton {
+    /** Transloco key or literal. */
+    readonly label: string;
+    readonly variant?: LwButtonVariant;
+    /** Value the dialog resolves to when this button is clicked. */
+    readonly value?: unknown;
+}
+/** Options for a progress indicator. */
+export interface ProgressOptions {
+    readonly title?: string;
+    /** Status text shown next to the spinner (updatable via the handle). */
+    readonly message: string;
+}
+/** Controls a live progress dialog. */
+export interface ProgressHandle {
+    /** Replace the status text. */
+    update(message: string): void;
+    /** Close the progress dialog. */
+    close(): void;
+}
+/** Options for opening a custom body component as a dialog. */
+export interface OpenOptions {
+    readonly title?: string;
+    readonly data?: unknown;
+    readonly buttons?: readonly DialogButton[];
+    /** Backdrop click / Escape / close-X dismiss the dialog. Defaults to `true`. */
+    readonly dismissable?: boolean;
+    readonly tone?: DialogTone;
+    /** Host icon name. */
+    readonly icon?: string;
+    /** Panel width. Defaults to `md`. */
+    readonly size?: DialogSize;
+    /**
+     * The host frame shows a maximize/restore control (near-fullscreen). A bare dialog draws its own
+     * control instead and may call `DialogRef.toggleMaximized` regardless of this flag.
+     */
+    readonly maximizable?: boolean;
+    /**
+     * Render only the component filling the panel — no host icon/title/close/footer/padding.
+     * The component owns its full chrome (e.g. the two-column settings surface). Defaults to `false`.
+     */
+    readonly bare?: boolean;
+    /**
+     * Vertical anchor of the panel. `'top'` pins the panel's top edge near the top of the viewport on
+     * every width — phones included — so a panel whose height follows its content (a filtering list
+     * like the command palette) grows and shrinks downward instead of jumping around the centre, and
+     * an on-screen keyboard never covers it. `'center'` (the default) keeps the centred desktop panel
+     * and the mobile bottom sheet.
+     */
+    readonly align?: 'center' | 'top';
+}

package/src/lib/dialog.js

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

package/src/lib/dialog.js.map

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

package/src/lib/dirty-surface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Implemented by a surface **component instance** to take part in the retention/close protocol
+ *. It lives on the instance, not on the {@link Surface} declaration, because one
+ * declaration can back many open tabs (`doc/:id`) and "this tab has unsaved changes" is a question
+ * about one instance. The host discovers it structurally — implement the interface and you are in.
+ *
+ * While {@link surfaceDirty} returns `true` the instance is **never destroyed on hide** (a tab
+ * switch, a minimised pane, a collapsed sidebar — no gesture that merely hides is ever blocked or
+ * prompted), and **closing asks**: the host shows its own localised "unsaved changes" dialog with
+ * *Save* (only when {@link surfaceSave} is implemented) · *Discard* · *Cancel*. Once the instance
+ * reports clean again it is released back to the normal retention rule. Two boundaries: a
+ * **sandboxed** (`iframe`) surface — which reports dirty by pushing `setDirty(true|false)` over its
+ * surface channel — survives gestures that hide it *in place* (tab switch, collapse) but is rebuilt
+ * by any gesture that *moves* its element (a split, a drag into another pane, a minimise), because
+ * moving an `<iframe>` in the DOM reloads it; and a **pop-out window** closes without the ask — the
+ * unsaved-changes protocol guards the main window, a pop-out is a viewer onto the same state.
+ */
+export interface DirtySurface {
+    /**
+     * Veto hook for a **user-initiated close** of this instance (tab ×, `Delete`, close pane, close
+     * others/all/to the right, `ctx.closeContentTab`). Return `false` to cancel the close, `true` to
+     * let it continue — a surface may draw its own dialog first and resolve the returned promise with
+     * the user's answer. It runs **before** the host's unsaved-changes dialog, and a `true` result
+     * does not bypass it: an instance that is still dirty afterwards still gets the standard
+     * *Save · Discard · Cancel* ask, so approving the close never discards silently.
+     *
+     * The host enforces a timeout with a guaranteed "close anyway" escape, and a hook that throws or
+     * rejects counts as approval — a broken or hung veto can never make a tab unclosable
+     *. Programmatic destruction (disabling or uninstalling the plugin, resetting or
+     * switching the workspace) does **not** consult this hook; only the unsaved-changes dialog guards
+     * those, because a plugin must not be able to veto its own removal.
+     */
+    surfaceBeforeClose?(): boolean | Promise<boolean>;
+    /**
+     * Unsaved changes? The host reads this **reactively** — read your own signals inside so the host
+     * notices the moment the instance becomes clean (a surface that stays "dirty" forever is a leak).
+     * A save in flight keeps this `true` until the save has actually succeeded — that is what makes
+     * fire-and-forget saving safe.
+     */
+    surfaceDirty(): boolean;
+    /**
+     * Persists the unsaved changes. Optional: without it the host's close dialog offers only
+     * *Discard* / *Cancel*. Also the target of the declaration-level `saveOn: 'hide'`
+     * ({@link SurfaceBase.saveOn}). A rejection keeps the instance dirty and therefore alive — the
+     * host reports the failure, it never discards silently.
+     */
+    surfaceSave?(): Promise<void>;
+}

package/src/lib/dirty-surface.js

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

package/src/lib/dirty-surface.js.map

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

package/src/lib/menu.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The **serialisable** context an opener passes when it shows a menu — e.g. the tab strip
+ * passes `{ targetKind: 'content-tab', tabId, group, pinned, closable }`. Primitives only, so it crosses
+ * the sandbox RPC boundary and reaches a command's `run(context)` intact. It is both the payload handed to
+ * the invoked command **and** what {@link MenuItem.when} is matched against for visibility.
+ */
+export type MenuContext = Readonly<Record<string, string | number | boolean>>;
+/**
+ * A contribution to a named menu slot — the menu analogue of a rail/bar/view-action item: it
+ * names a {@link menu} slot and points at a {@link command} by id (so it serialises across the sandbox
+ * boundary), or carries an inline {@link run} (trusted, in-process only). The host draws the menu; a
+ * right-click on host chrome opens the slot with a {@link MenuContext}.
+ */
+export interface MenuItem {
+    /**
+     * Optional stable identity. With an `id`, registering again **replaces** the entry (last-in wins — the
+     * same override-by-id rule as every other contribution), and a distribution can drop it via
+     * `provideShell({ omit: [id] })`. Built-in host entries use `menu:<commandId>` (e.g.
+     * `menu:shell.tab.closeOthers`) — distinct from the command id, so omitting the entry keeps the command
+     * itself (palette/shortcut) alive. Without an `id` the item is purely additive.
+     */
+    readonly id?: string;
+    /** Slot id: a host slot (`'content/tab/context'`) or a plugin's own (`'<weaver>.<surface>/context'`). */
+    readonly menu: string;
+    /** The behaviour: a registered command id (preferred — crosses the RPC boundary), invoked with the context. */
+    readonly command?: string;
+    /** Inline behaviour (trusted in-process only; a sandboxed plugin uses `command` instead). */
+    run?(context?: MenuContext): void;
+    /** Label — Transloco key or literal. Defaults to the referenced command's title when omitted. */
+    readonly title?: string;
+    /** Group id for ordering + separators; groups render in `group` order, items in `order` within a group. */
+    readonly group?: string;
+    /** Lower renders first (default 0). */
+    readonly order?: number;
+    /**
+     * Coarse visibility filter: the item shows only when **every** key here equals the same key
+     * in the opener's {@link MenuContext} (a subset match). Omit to always show. No expression language — a
+     * data-only predicate, so it is serialisable and sandbox-safe.
+     */
+    readonly when?: MenuContext;
+    /**
+     * Makes this a **checkbox** menu item (`role="menuitemcheckbox"`): present ⇒ the item shows a
+     * check indicator, checked exactly when every key here equals the same key in the opener's context (a
+     * subset match, like {@link when}). Lets one toggle item replace a pair (e.g. "Pinned ✓" instead of
+     * separate Pin/Unpin); the referenced command reads the current state from the context and flips it.
+     */
+    readonly checkedWhen?: MenuContext;
+}

package/src/lib/menu.js

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

package/src/lib/menu.js.map

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

package/src/lib/notification.d.ts

@@ -0,0 +1,28 @@
+/** Severity of a notification — drives icon and accent. */
+export type NotificationKind = 'info' | 'success' | 'warning' | 'error';
+/**
+ * A single action button on a toast (e.g. "Reload" on an update notice).
+ * Trusted in-process runtime only — a sandboxed plugin's `action` does not cross the RPC
+ * boundary and is dropped (like `OpenTabInput.onClose`).
+ */
+export interface NotificationAction {
+    /** Transloco key or literal for the button label. */
+    readonly label: string;
+    run(): void;
+}
+/** What a caller passes to the host notification service. */
+export interface NotificationInput {
+    /** Transloco key or literal for the message. */
+    readonly message: string;
+    /** Severity; defaults to `info`. */
+    readonly kind?: NotificationKind;
+    /**
+     * Optional single action button. (Trusted in-process runtime only — over the sandbox RPC
+     * boundary the action is dropped and the toast shows without a button.)
+     */
+    readonly action?: NotificationAction;
+    /** Auto-dismiss after this many ms. Omit or `0` = sticky until dismissed. */
+    readonly timeoutMs?: number;
+    /** Stable id — reusing an id replaces the existing toast instead of stacking. */
+    readonly id?: string;
+}

package/src/lib/notification.js

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

package/src/lib/notification.js.map

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

package/src/lib/pane-area.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The grammar for a **declared** pane arrangement, generic over what one of its tabs addresses.
+ *
+ * An area either holds `tabs`, splits into `rows` (top to bottom) or splits into `columns` (left to
+ * right) — exactly one of the three. It is the same vocabulary wherever a product or a plugin writes
+ * an arrangement down, so there is one grammar to learn and one conversion behind it: a distribution
+ * instantiates it over **route paths** for a workspace (`WorkspaceArea` in `@loomweaver/shell`), a plugin
+ * over **child surface ids** for a container (`ContainerArea`).
+ */
+export type PaneArea<T> = PaneTabArea<T> | PaneRowArea<T> | PaneColumnArea<T>;
+export interface PaneAreaBase {
+    /**
+     * Optional share of the parent split in percent. Unspecified siblings share the remainder evenly;
+     * values that do not sum to 100 are normalized proportionally rather than rejected.
+     */
+    readonly size?: number;
+}
+/** An area that holds tabs. */
+export interface PaneTabArea<T> extends PaneAreaBase {
+    readonly tabs: readonly T[];
+}
+/** An area that splits into rows, top to bottom. */
+export interface PaneRowArea<T> extends PaneAreaBase {
+    readonly rows: readonly PaneArea<T>[];
+}
+/** An area that splits into columns, left to right. */
+export interface PaneColumnArea<T> extends PaneAreaBase {
+    readonly columns: readonly PaneArea<T>[];
+}

package/src/lib/pane-area.js

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

package/src/lib/pane-area.js.map

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