@tumaet/apollon 4.8.0 → 5.0.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+import { CSSProperties } from 'react';
 import { Edge } from '@xyflow/react';
 import { EdgeProps } from '@xyflow/react';
 import { JSX } from 'react';
 import { Node as Node_2 } from '@xyflow/react';
 import { NodeProps } from '@xyflow/react';
+import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { XYPosition } from '@xyflow/react';
 
 declare function Activity({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
@@ -21,12 +24,29 @@ declare function ActivityMergeNode({ id, width, height, data, parentId, }: NodeP
 
 declare function ActivityObjectNode({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
-declare namespace Apollon {
+declare function ActivitySwimlane({ id, width, height, data, parentId, }: NodeProps<Node_2<ActivitySwimlaneProps>>): JSX.Element | null;
+
+/**
+ * Activity-partition (swimlane) container. Lanes are equal divisions along the
+ * primary axis (columns when vertical, rows when horizontal). Elements dropped
+ * into the swimlane become its children and move with it; which lane an element
+ * belongs to is expressed by where the modeller places it, matching the UML
+ * activity-partition notation where partition membership is positional rather
+ * than stored per element.
+ */
+declare type ActivitySwimlaneProps = DefaultNodeProps & {
+    orientation: "vertical" | "horizontal";
+    lanes: SwimlaneLane[];
+};
+
+/** React wrapper around {@link ApollonEditor}. See `@tumaet/apollon` docs. */
+export declare function Apollon(props: ApollonProps): JSX.Element;
+
+declare namespace Apollon_2 {
     export {
         UMLDiagramType,
         DiagramNodeType,
         DiagramEdgeType,
-        Styles,
         Unsubscriber,
         Subscribers,
         UMLModelElementType,
@@ -63,6 +83,24 @@ export declare type ApollonCollaborationOptions = {
     showFollow?: boolean;
 };
 
+/**
+ * Declarative façade over `editor.addControl`. Registers a control that renders
+ * a stable host node into the chosen region, and portals `children` into that
+ * node — so children render INSIDE the canvas while React owns their
+ * reconciliation. Children changes therefore never touch the overlay store; only
+ * real option changes (region/inset/order/…) push an update. Returns null in the
+ * host tree.
+ */
+export declare function ApollonControl({ children, ...options }: ApollonControlProps): ReactNode;
+
+/** Props for {@link ApollonControl}: every {@link OverlayControlOptions} field
+ *  (id, region, inset, order, …) plus the children to render in-canvas. */
+export declare type ApollonControlProps = OverlayControlOptions & {
+    /** Portaled into the control's host node inside the chosen region. Children
+     *  changes never re-register the control; only real option changes do. */
+    children: ReactNode;
+};
+
 export declare type ApollonEdge = {
     id: string;
     source: string;
@@ -82,10 +120,10 @@ export declare class ApollonEditor {
     private readonly metadataStore;
     private readonly popoverStore;
     private readonly assessmentSelectionStore;
-    private readonly alignmentGuidesStore;
-    private readonly edgeGeometryStore;
+    private readonly overlayStore;
+    private readonly hostRegionEls;
     private subscribers;
-    constructor(element: HTMLElement, options?: Apollon.ApollonOptions);
+    constructor(element: HTMLElement, options?: Apollon_2.ApollonOptions);
     private setReactFlowInstance;
     getNodes(): Node_2[];
     getEdges(): Edge[];
@@ -102,26 +140,78 @@ export declare class ApollonEditor {
         x: number;
         y: number;
     }): XYPosition | null;
+    /**
+     * Zoom/pan so the whole diagram fits, capped at `maxZoom: 1.0`. Retries up to
+     * 10 animation frames until every node is measured.
+     * @param options.padding - Scalar fraction (default `0.15`), or per-side px
+     *   that adds to a 16px gutter. A per-side object forces the inset-aware path.
+     * @param options.duration - Animation duration in ms (default `200`).
+     * @param options.respectInsets - Pad the fit by reserved overlay insets
+     *   (header, rails, …). Default `true`.
+     */
     fitView(options?: {
-        padding?: number;
+        padding?: number | Partial<Record<OverlaySide, number>>;
         duration?: number;
+        /** Pad the fit by the reserved overlay insets (header, rails, …). */
+        respectInsets?: boolean;
     }): void;
+    /**
+     * Register a floating control, returning a disposer. Re-using an id replaces
+     * (idempotent / StrictMode-safe). Pick a façade: a React host →
+     * `<ApollonControl>`; a non-React host (or one that needs its own React
+     * root/context) → `getRegionElement` + `createPortal`; a one-off imperative
+     * widget → `addControl`.
+     * @param control - id, target region, a `render` thunk, and optional layout
+     *   options ({@link OverlayControlInput}).
+     * @returns A disposer that unregisters this control; safe to call twice.
+     * @throws If `id` is empty or `region` is not a known region — mistakes fail
+     *   loudly at the edge, not silently in the renderer.
+     */
+    addControl(control: OverlayControlInput): () => void;
+    /**
+     * Patch a registered control's options/renderer (a no-op if absent).
+     * @param id - The control's immutable id (an `id` in `patch` is ignored).
+     * @param patch - Partial options/renderer merged over the existing control.
+     */
+    updateControl(id: string, patch: Partial<OverlayControlInput>): void;
+    /**
+     * @param id - A control id.
+     * @returns `true` if a control with this id is currently registered.
+     */
+    hasControl(id: string): boolean;
+    /**
+     * A stable DOM node anchored in `region`, for hosts that render their own
+     * React into it (via `createPortal`) to keep host context. Auto-measured, so
+     * the diagram makes room for whatever the host mounts. Lifetime = the editor;
+     * `releaseRegionElement` unregisters it. Reserved id: `apollon:host:<region>`.
+     * @param region - The region to anchor the node in.
+     * @returns The same node for the lifetime of one acquire; `releaseRegionElement`
+     *   drops it and the next call returns a fresh node.
+     * @throws If `region` is not a known region.
+     */
+    getRegionElement(region: OverlayRegion): HTMLElement;
+    /**
+     * Release a region acquired via {@link getRegionElement} (unregister + drop
+     * the cached node); a later `getRegionElement(region)` creates a fresh node.
+     * @param region - The region whose host node to release.
+     */
+    releaseRegionElement(region: OverlayRegion): void;
     set diagramType(type: UMLDiagramType);
     destroy(): void;
     /** Renders a model to SVG via a hidden, off-screen mount. */
-    static exportModelAsSvg(model: Apollon.UMLModel, options?: Apollon.ExportOptions): Promise<Apollon.SVG>;
+    static exportModelAsSvg(model: Apollon_2.UMLModel, options?: Apollon_2.ExportOptions): Promise<Apollon_2.SVG>;
     /**
      * exports current model as svg
      * @param options options to change the export behavior (add margin, exclude element ...)
      */
-    exportAsSVG(options?: Apollon.ExportOptions): Promise<Apollon.SVG>;
+    exportAsSVG(options?: Apollon_2.ExportOptions): Promise<Apollon_2.SVG>;
     private getNewSubscriptionId;
-    subscribeToModelChange(callback: (state: Apollon.UMLModel) => void): number;
+    subscribeToModelChange(callback: (state: Apollon_2.UMLModel) => void): number;
     subscribeToDiagramNameChange(callback: (diagramTitle: string) => void): number;
     subscribeToAssessmentSelection(callback: (selectedElementIds: string[]) => void): number;
     subscribeToSelectionChange(callback: (selectedElementIds: string[]) => void): number;
-    subscribeToAwarenessChanges(callback: (states: Map<number, Apollon.CollaborationState>) => void): number;
-    subscribeToCollaboratorChanges(callback: (collaborators: Apollon.CollaboratorInfo[]) => void): number;
+    subscribeToAwarenessChanges(callback: (states: Map<number, Apollon_2.CollaborationState>) => void): number;
+    subscribeToCollaboratorChanges(callback: (collaborators: Apollon_2.CollaboratorInfo[]) => void): number;
     unsubscribe(subscriberId: number): void;
     sendBroadcastMessage(sendFn: SendBroadcastMessage): void;
     receiveBroadcastedMessage(base64Data: string): void;
@@ -131,12 +221,12 @@ export declare class ApollonEditor {
      * absorbed by the room. See `YjsSync.broadcastFullState`.
      */
     broadcastFullState(): void;
-    setLocalAwarenessUser(user: Apollon.CollaborationUser): void;
-    setLocalAwarenessCursor(cursor: Apollon.CollaborationCursor | null): void;
+    setLocalAwarenessUser(user: Apollon_2.CollaborationUser): void;
+    setLocalAwarenessCursor(cursor: Apollon_2.CollaborationCursor | null): void;
     setLocalAwarenessSelectedElement(selectedElementId: string | null): void;
-    setLocalAwarenessState(state: Partial<Apollon.CollaborationState>): void;
+    setLocalAwarenessState(state: Partial<Apollon_2.CollaborationState>): void;
     getLocalAwarenessClientId(): number;
-    getCollaborators(): Apollon.CollaboratorInfo[];
+    getCollaborators(): Apollon_2.CollaboratorInfo[];
     updateDiagramTitle(name: string): void;
     /**
      * Toggles the editor's read-only state at runtime. Used by hosting apps
@@ -146,7 +236,7 @@ export declare class ApollonEditor {
      */
     setReadonly(readonly: boolean): void;
     /** Live-toggle modeling vs assessment vs exporting mode. */
-    setMode(mode: Apollon.ApollonMode): void;
+    setMode(mode: Apollon_2.ApollonMode): void;
     /** Live-toggle whether the canvas captures page scroll. */
     setScrollLock(scrollLock: boolean): void;
     /**
@@ -167,20 +257,18 @@ export declare class ApollonEditor {
      */
     setPreviewMode(active: boolean): void;
     toggleInteractiveElementsMode(forceEnabled?: boolean): void;
-    getInteractiveForSerialization(): Apollon.InteractiveElements | undefined;
+    getInteractiveForSerialization(): Apollon_2.InteractiveElements | undefined;
     getDiagramMetadata(): {
         diagramTitle: string;
         diagramType: "ClassDiagram" | "ObjectDiagram" | "ActivityDiagram" | "UseCaseDiagram" | "CommunicationDiagram" | "ComponentDiagram" | "DeploymentDiagram" | "PetriNet" | "ReachabilityGraph" | "SyntaxTree" | "Flowchart" | "BPMN" | "Sfc";
     };
-    get model(): Apollon.UMLModel;
-    set model(model: Apollon.UMLModel);
+    get model(): Apollon_2.UMLModel;
+    set model(model: Apollon_2.UMLModel);
     /**
      * Host-driven element highlighting. Paints a translucent overlay over each
-     * given node / edge / class-member id in the supplied CSS color — the v4
-     * replacement for v3's `UMLModelElement.highlight` field and
-     * `ApollonEditor.select()`. Typical hosts: an assessment editor marking
-     * elements that are missing feedback, or Athena marking elements that have
-     * automatic-feedback suggestions.
+     * given node / edge / class-member id in the supplied CSS color. Typical
+     * hosts: an assessment editor marking elements that are missing feedback, or
+     * Athena marking elements that have automatic-feedback suggestions.
      *
      * The highlight is an ephemeral view overlay: it is NOT written into the
      * model, NOT serialized by `get model`, and NOT shared with collaborators.
@@ -194,9 +282,9 @@ export declare class ApollonEditor {
     /** Returns a copy of the current highlight record (id -> CSS color). */
     getElementHighlights(): Record<string, string>;
     getSelectedElements(): string[];
-    get view(): Apollon.ApollonView;
-    set view(view: Apollon.ApollonView);
-    addOrUpdateAssessment(assessment: Apollon.Assessment): void;
+    get view(): Apollon_2.ApollonView;
+    set view(view: Apollon_2.ApollonView);
+    addOrUpdateAssessment(assessment: Apollon_2.Assessment): void;
     static generateInitialSyncMessage(): string;
     static generateInitialAwarenessSyncMessage(): string;
 }
@@ -239,30 +327,159 @@ export declare type ApollonOptions = {
     collaborationEnabled?: boolean;
     collaboration?: ApollonCollaborationOptions;
     scrollLock?: boolean;
+    /**
+     * Optional `--apollon-*` CSS custom properties applied to the editor's mount
+     * element. Build one with `createApollonTheme(...)`. Fully optional — an
+     * un-themed editor falls back to the library's built-in light/dark values.
+     */
+    theme?: Partial<Record<`--apollon-${string}`, string>>;
+    /**
+     * Sets `data-theme` on the mount element. Optional — when omitted the editor
+     * keeps any `data-theme` already on the element / inherited from an ancestor.
+     * See `library/THEMING.md`.
+     */
+    dataTheme?: "light" | "dark";
 };
 
-declare const apollonTheme: {
-    color: {
-        primary: string;
-        secondary: string;
-        warningYellow: string;
-        background: string;
-        backgroundVariant: string;
-        grid: string;
-        primaryContrast: string;
-        gray: string;
-        grayAccent: string;
-    };
-    font: {
-        color: string;
-        family: string;
-        size: number;
-    };
-    interactive: {
-        normal: string;
-        hovered: string;
-    };
-};
+/**
+ * Props for the {@link Apollon} React component.
+ *
+ * - `default*` / `availableViews` / `enablePopups` / `collaborationEnabled` /
+ *   `debug` are **snapshotted on mount** — re-key the component to apply
+ *   changes against a new editor instance.
+ * - `readonly` / `view` / `mode` / `scrollLock` / `previewMode` / `model`
+ *   are **reactive** — applied via the matching `ApollonEditor` setter when
+ *   the prop changes. Passing `undefined` leaves the live value untouched;
+ *   re-key the component to fully reset.
+ */
+export declare interface ApollonProps {
+    className?: string;
+    /** Inline styles. Needs an explicit non-zero height or the canvas renders blank. */
+    style?: CSSProperties;
+    /**
+     * Optional `--apollon-*` CSS custom properties spread onto the mount node's
+     * `style`. Build one with `createApollonTheme(...)`. Fully optional — an
+     * un-themed embed falls back to the library's built-in light/dark values.
+     */
+    theme?: Partial<Record<`--apollon-${string}`, string>>;
+    /**
+     * Sets `data-theme` on the mount node. Optional — when omitted the editor
+     * inherits whatever `data-theme` an ancestor declares, or the default light
+     * values. See `library/THEMING.md`.
+     */
+    dataTheme?: "light" | "dark";
+    /** Rendered inside the {@link ApollonInstanceContext} provider alongside the canvas. */
+    children?: ReactNode;
+    defaultModel?: UMLModel;
+    defaultType?: UMLDiagramType;
+    defaultMode?: ApollonMode;
+    defaultView?: ApollonView;
+    availableViews?: ApollonView[];
+    enablePopups?: boolean;
+    collaborationEnabled?: boolean;
+    collaboration?: ApollonCollaborationOptions;
+    debug?: boolean;
+    readonly?: boolean;
+    view?: ApollonView;
+    mode?: ApollonMode;
+    scrollLock?: boolean;
+    /** Local-only preview overlay. See {@link ApollonEditor.setPreviewMode}. */
+    previewMode?: boolean;
+    /**
+     * One-way reactive model push — each new value applies via
+     * `editor.model = value`. NOT a two-way controlled value: the editor's own
+     * edits are not mirrored back, and feeding `subscribeToModelChange` into this
+     * prop loops. For save-on-change use `defaultModel` + an `onMount` subscription.
+     */
+    model?: UMLModel;
+    /**
+     * Called once with the instance after mount. The optional returned function
+     * runs as cleanup before destroy (React-19-style cleanup return).
+     */
+    onMount?: (editor: ApollonEditor) => void | (() => void);
+    /**
+     * Imperative handle to the underlying {@link ApollonEditor}. Assigned once
+     * after mount and cleared on unmount.
+     */
+    ref?: Ref<ApollonEditor | null>;
+}
+
+/**
+ * Make a host-owned {@link ApollonEditor} reachable to descendants via
+ * {@link useApollonEditor}. Use when the host constructs the editor directly
+ * (non-React adapter, test fixture) instead of rendering {@link Apollon}.
+ */
+export declare function ApollonProvider({ editor, children, }: {
+    editor: ApollonEditor;
+    children: ReactNode;
+}): JSX.Element;
+
+/**
+ * The documented, stable subset of the `--apollon-*` editor theming tokens.
+ *
+ * Every field is optional: provide only the tokens you want to override; the
+ * rest fall back to the library's built-in light/dark values. Values are any
+ * valid CSS color/length string (e.g. `"#3e8acc"`, `"rgb(62 138 204)"`,
+ * `"var(--my-brand)"`).
+ *
+ * See `library/THEMING.md` for the full variable contract and host patterns.
+ */
+export declare interface ApollonTheme {
+    /** Accent / brand color. Maps to `--apollon-primary`. */
+    primary?: string;
+    /** Foreground used on top of `background`. Maps to `--apollon-primary-contrast`. */
+    primaryContrast?: string;
+    /** Muted/secondary accent. Maps to `--apollon-secondary`. */
+    secondary?: string;
+    /** Canvas / surface background. Maps to `--apollon-background`. */
+    background?: string;
+    /** Inverse of `background` (e.g. tooltips). Maps to `--apollon-background-inverse`. */
+    backgroundInverse?: string;
+    /** Slightly raised surface variant. Maps to `--apollon-background-variant`. */
+    backgroundVariant?: string;
+    /** Neutral gray surface. Maps to `--apollon-gray`. */
+    gray?: string;
+    /** Stronger gray (borders/dividers). Maps to `--apollon-gray-variant`. */
+    grayVariant?: string;
+    /** Canvas grid line color. Maps to `--apollon-grid`. */
+    grid?: string;
+    /** Vertical alignment guide color. Maps to `--apollon-guide-vertical`. */
+    guideVertical?: string;
+    /** Horizontal alignment guide color. Maps to `--apollon-guide-horizontal`. */
+    guideHorizontal?: string;
+    /** Warning alert accent. Maps to `--apollon-alert-warning-yellow`. */
+    warning?: string;
+    /** Warning alert background. Maps to `--apollon-alert-warning-background`. */
+    warningBackground?: string;
+    /** Warning alert border. Maps to `--apollon-alert-warning-border`. */
+    warningBorder?: string;
+    /** Danger alert text color. Maps to `--apollon-alert-danger-color`. */
+    danger?: string;
+    /** Danger alert background. Maps to `--apollon-alert-danger-background`. */
+    dangerBackground?: string;
+    /** Danger alert border. Maps to `--apollon-alert-danger-border`. */
+    dangerBorder?: string;
+    /** Raised card/popover/menu surface. Maps to `--apollon-surface`. */
+    surface?: string;
+    /** Sunken/recessed surface (e.g. wells, muted areas). Maps to `--apollon-surface-sunken`. */
+    surfaceSunken?: string;
+    /** Hover state of the raised surface. Maps to `--apollon-surface-hover`. */
+    surfaceHover?: string;
+    /** Default border / divider color. Maps to `--apollon-border`. */
+    border?: string;
+    /** Subtle border / divider color. Maps to `--apollon-border-subtle`. */
+    borderSubtle?: string;
+    /** Base corner radius for shared primitives (CSS length). Maps to `--apollon-radius`. */
+    radius?: string;
+    /** Toggle/switch outline. Maps to `--apollon-switch-box-border-color`. */
+    switchBoxBorderColor?: string;
+    /** List-group surface color. Maps to `--apollon-list-group-color`. */
+    listGroupColor?: string;
+    /** Outline-secondary button color. Maps to `--apollon-btn-outline-secondary-color`. */
+    btnOutlineSecondaryColor?: string;
+    /** Modal footer divider. Maps to `--apollon-modal-bottom-border`. */
+    modalBottomBorder?: string;
+}
 
 export declare enum ApollonView {
     Modelling = "Modelling",
@@ -418,10 +635,7 @@ declare function ColorDescription({ width, height, data, id, }: NodeProps<Node_2
 
 declare function CommunicationObjectName({ id, width, height, data, }: NodeProps<Node_2<CommunicationObjectNodeProps>>): JSX.Element;
 
-declare type CommunicationObjectNodeProps = {
-    methods: ClassNodeElement[];
-    attributes: ClassNodeElement[];
-} & DefaultNodeProps;
+declare type CommunicationObjectNodeProps = ObjectNodeProps;
 
 declare function Component({ id, width, height, data, parentId, }: NodeProps<Node_2<ComponentNodeProps>>): JSX.Element | null;
 
@@ -437,6 +651,23 @@ declare type ComponentSubsystemNodeProps = {
     isComponentSubsystemHeaderShown: boolean;
 } & DefaultNodeProps;
 
+/**
+ * Build a framework-agnostic style object of `--apollon-*` CSS custom
+ * properties from a (partial) {@link ApollonTheme}.
+ *
+ * Only the keys you provide are emitted — undefined fields are skipped so the
+ * library's built-in fallbacks stay in effect. The result can be spread onto
+ * any `style` object/attribute:
+ *
+ * ```tsx
+ * <Apollon theme={createApollonTheme({ primary: "#ff5722" })} />
+ * ```
+ *
+ * @param theme partial token object; unset tokens fall back to the defaults.
+ * @returns a record of `--apollon-*` variables to their string values.
+ */
+export declare function createApollonTheme(theme: ApollonTheme): Record<`--apollon-${string}`, string>;
+
 declare type CustomEdgeProps = {
     sourceRole: string | null;
     sourceMultiplicity: string | null;
@@ -529,6 +760,7 @@ declare const diagramNodeTypes: {
     activityMergeNode: typeof ActivityMergeNode;
     activityForkNode: typeof ActivityForkNode;
     activityForkNodeHorizontal: typeof ActivityForkNodeHorizontal;
+    activitySwimlane: typeof ActivitySwimlane;
     useCase: typeof UseCase;
     useCaseActor: typeof UseCaseActor;
     useCaseSystem: typeof UseCaseSystem;
@@ -653,6 +885,14 @@ export declare const getNodeAssessmentDataByNodeElementId: (nodeElementId: strin
  */
 export declare function importDiagram(data: any | V3UMLModel): UMLModel;
 
+/**
+ * How much room a control reserves so the diagram "makes way" (fed into
+ * `fitView` padding, MapLibre-style). `"auto"` measures the control via the
+ * shared ResizeObserver on the region's dominant axis; an object mixes explicit
+ * px with per-side `"auto"` (e.g. `{ top: "auto" }`).
+ */
+export declare type InsetContribution = "auto" | Partial<Record<OverlaySide, number | "auto">>;
+
 export declare type InteractiveElements = {
     elements: {
         [id: string]: boolean;
@@ -667,11 +907,6 @@ declare interface IPoint {
     y: number;
 }
 
-declare interface IPoint_2 {
-    x: number;
-    y: number;
-}
-
 export declare enum Locale {
     en = "en",
     de = "de"
@@ -700,9 +935,46 @@ declare type ObjectNodeProps = {
 
 export declare interface OrthogonalEdgeData {
     [key: string]: unknown;
-    points: IPoint_2[];
+    points: IPoint[];
 }
 
+/** The public registration payload (options + renderer). */
+export declare type OverlayControlInput = OverlayControlOptions & {
+    render: () => ReactNode;
+};
+
+export declare interface OverlayControlOptions {
+    /** Stable id. Re-adding the same id REPLACES (idempotent, StrictMode-safe). */
+    id: string;
+    /** Which band/corner the control is anchored in. */
+    region: OverlayRegion;
+    /** Reserve viewport room. Default: reserves nothing (the control floats). */
+    inset?: InsetContribution;
+    /** Stacking within a region; lower renders toward the region's anchor edge. */
+    order?: number;
+    /** When false the region frame stays pointer-transparent here too. Default true. */
+    interactive?: boolean;
+    /** Wraps the control in a `role="group"` with this aria-label. No focus
+     *  management is imposed. */
+    groupLabel?: string;
+    /** Hide without unregistering (reserves no inset while hidden). Default true. */
+    visible?: boolean;
+    /** Extra class on the control's wrapper element. */
+    className?: string;
+    /** Inline styles merged onto the control's wrapper element. */
+    style?: CSSProperties;
+}
+
+/**
+ * Where a control is anchored. The six React Flow `<Panel>` corners are
+ * screen-space and rendered through React Flow; `header`/`left-rail`/`right-rail`
+ * are library-owned bands; `on-canvas` pans/zooms with the diagram.
+ */
+export declare type OverlayRegion = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "header" | "left-rail" | "right-rail" | "on-canvas";
+
+/** One of the four edges a control can sit against / reserve room on. */
+export declare type OverlaySide = "top" | "right" | "bottom" | "left";
+
 declare function Package({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
 declare function PetriNetPlace({ id, width, height, data, }: NodeProps<Node_2<PetriNetPlaceProps>>): JSX.Element | null;
@@ -758,8 +1030,6 @@ declare type SfcTransitionBranchNodeProps = DefaultNodeProps & {
 
 declare type Sink = Pick<Console, "error" | "warn" | "debug">;
 
-export declare type Styles = typeof apollonTheme;
-
 export declare type Subscribers = {
     [key: number]: Unsubscriber;
 };
@@ -776,6 +1046,19 @@ export declare type SVG = {
 
 export declare type SvgExportMode = "web" | "compat";
 
+/** A single partition (lane) inside an activity swimlane. */
+declare type SwimlaneLane = {
+    id: string;
+    name: string;
+    /**
+     * Lane's extent along the swimlane's primary axis, in absolute flow px. The
+     * last lane is elastic (fills the remainder), so resizing the swimlane only
+     * changes the last lane. Optional: lanes without it divide the space equally,
+     * so existing saved swimlanes render as equal lanes until a separator moves.
+     */
+    size?: number;
+};
+
 declare function SyntaxTreeNonterminal({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
 declare function SyntaxTreeTerminal({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
@@ -817,6 +1100,30 @@ export declare type UMLModelElementType = DiagramNodeType | DiagramEdgeType;
 
 export declare type Unsubscriber = () => void;
 
+export declare function useApollonEditor(): ApollonEditor | null;
+
+/** Like {@link useApollonEditor}, but throws when no editor is available. */
+export declare function useApollonEditorOrThrow(): ApollonEditor;
+
+/**
+ * Subscribe to a value derived from the {@link ApollonEditor}.
+ *
+ * `getSnapshot` MUST return a referentially stable value when nothing changed;
+ * do not allocate inside it. Returns `undefined` while no editor is mounted
+ * (including during SSR). Pass the value type explicitly —
+ * `useApollonSubscription<string[]>(...)` — it can't be inferred from the
+ * `subscribe` callback (its `value` parameter is a contravariant position).
+ *
+ * @example
+ * ```tsx
+ * const selection = useApollonSubscription<string[]>(
+ *   (editor, cb) => editor.subscribeToSelectionChange(cb),
+ *   (editor) => editor.getSelectedElements(),
+ * )
+ * ```
+ */
+export declare function useApollonSubscription<T>(subscribe: (editor: ApollonEditor, cb: (value: T) => void) => number, getSnapshot: (editor: ApollonEditor) => T): T | undefined;
+
 declare function UseCase({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
 declare function UseCaseActor({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;