@tumaet/apollon 5.0.1 → 5.1.1

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { EdgeProps } from '@xyflow/react';
 import { JSX } from 'react';
 import { Node as Node_2 } from '@xyflow/react';
 import { NodeProps } from '@xyflow/react';
+import { PanelPosition } from '@xyflow/react';
+import { Position } from '@xyflow/react';
 import { ReactNode } from 'react';
 import { Ref } from 'react';
 import { XYPosition } from '@xyflow/react';
@@ -42,8 +44,17 @@ declare type ActivitySwimlaneProps = DefaultNodeProps & {
 /** React wrapper around {@link ApollonEditor}. See `@tumaet/apollon` docs. */
 export declare function Apollon(props: ApollonProps): JSX.Element;
 
+export declare namespace Apollon {
+    var Palette: typeof ApollonPalette;
+    var Zoom: typeof ApollonZoom;
+    var MiniMap: typeof ApollonMiniMap;
+    var SelectionToolbar: typeof ApollonSelectionToolbar;
+    var DefaultControls: typeof ApollonDefaultControls;
+}
+
 declare namespace Apollon_2 {
     export {
+        ApollonLabels,
         UMLDiagramType,
         DiagramNodeType,
         DiagramEdgeType,
@@ -101,6 +112,10 @@ export declare type ApollonControlProps = OverlayControlOptions & {
     children: ReactNode;
 };
 
+/** The editor's default chrome. Render it explicitly when adding host children
+ *  that should keep palette + zoom + minimap visible. */
+export declare function ApollonDefaultControls(): JSX.Element;
+
 export declare type ApollonEdge = {
     id: string;
     source: string;
@@ -122,6 +137,7 @@ export declare class ApollonEditor {
     private readonly assessmentSelectionStore;
     private readonly overlayStore;
     private readonly hostRegionEls;
+    private readonly controlGenerations;
     private subscribers;
     constructor(element: HTMLElement, options?: Apollon_2.ApollonOptions);
     private setReactFlowInstance;
@@ -147,7 +163,8 @@ export declare class ApollonEditor {
      *   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`.
+     *   (header, rails, …). Default `true`. The device safe area (notch, home
+     *   indicator) is always cleared — it is a hardware constraint, not chrome.
      */
     fitView(options?: {
         padding?: number | Partial<Record<OverlaySide, number>>;
@@ -174,11 +191,25 @@ export declare class ApollonEditor {
      * @param patch - Partial options/renderer merged over the existing control.
      */
     updateControl(id: string, patch: Partial<OverlayControlInput>): void;
+    /**
+     * Unregister a control by id (a no-op if absent). Hides a built-in imperatively
+     * — e.g. `editor.removeControl(ZOOM_ID)` — the parity for omitting it from a
+     * React composition. Equivalent to the disposer `addControl` returns.
+     * @param id - The control's id.
+     */
+    removeControl(id: string): void;
     /**
      * @param id - A control id.
      * @returns `true` if a control with this id is currently registered.
      */
     hasControl(id: string): boolean;
+    /**
+     * @param id - A control id.
+     * @returns The registered control options, or `undefined` if absent — e.g. to
+     *   read a built-in's current `region` after `updateControl`. The renderer is
+     *   intentionally omitted; replace a renderer explicitly with `updateControl`.
+     */
+    getControl(id: string): OverlayControlSnapshot | undefined;
     /**
      * 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
@@ -239,6 +270,13 @@ export declare class ApollonEditor {
     setMode(mode: Apollon_2.ApollonMode): void;
     /** Live-toggle whether the canvas captures page scroll. */
     setScrollLock(scrollLock: boolean): void;
+    /**
+     * Replace the editor's user-facing strings (i18n). Merged over the English
+     * defaults, so a partial map only changes the keys it provides. Reactive — the
+     * chrome re-renders, so a host can switch language without remounting.
+     * @param labels - A partial {@link ApollonLabels} in the host's language.
+     */
+    setLabels(labels: Partial<Apollon_2.ApollonLabels>): void;
     /**
      * Toggle preview-overlay mode. When `true`, subsequent `model = …`
      * assignments and other store mutators update the local Zustand caches
@@ -263,7 +301,7 @@ export declare class ApollonEditor {
         diagramType: "ClassDiagram" | "ObjectDiagram" | "ActivityDiagram" | "UseCaseDiagram" | "CommunicationDiagram" | "ComponentDiagram" | "DeploymentDiagram" | "PetriNet" | "ReachabilityGraph" | "SyntaxTree" | "Flowchart" | "BPMN" | "Sfc";
     };
     get model(): Apollon_2.UMLModel;
-    set model(model: Apollon_2.UMLModel);
+    set model(incoming: Apollon_2.UMLModel);
     /**
      * Host-driven element highlighting. Paints a translucent overlay over each
      * given node / edge / class-member id in the supplied CSS color. Typical
@@ -289,6 +327,217 @@ export declare class ApollonEditor {
     static generateInitialAwarenessSyncMessage(): string;
 }
 
+/**
+ * Flat, typed dictionary of the strings the editor renders itself. The library
+ * ships English defaults; a host overrides any subset via `labels` (a shallow,
+ * per-key merge). Strings that interpolate are functions so a translation keeps
+ * control of word order.
+ */
+export declare interface ApollonLabels {
+    zoomToolbar: string;
+    zoomIn: string;
+    zoomOut: string;
+    fitView: string;
+    /** Tooltip on the % readout button. */
+    resetZoom: string;
+    /** Accessible name of the % readout (interpolates the live zoom level). */
+    zoomReadout: (percent: number) => string;
+    undo: string;
+    /** Tooltip incl. the keyboard shortcut. */
+    undoHint: string;
+    redo: string;
+    redoHint: string;
+    miniMap: string;
+    showMinimap: string;
+    /** Tooltip on the collapsed minimap toggle. */
+    showMinimapHint: string;
+    hideMinimap: string;
+    selectionActions: string;
+    elementPalette: string;
+    paletteModelView: string;
+    paletteSelectElementsView: string;
+    paletteHighlightHint: string;
+    edge: string;
+    label: string;
+    type: string;
+    connection: string;
+    stereotype: string;
+    object: string;
+    source: string;
+    target: string;
+    style: string;
+    selectPlaceholder: string;
+    addComment: string;
+    points: string;
+    negativePointsAllowed: string;
+    feedback: string;
+    deleteAssessment: string;
+    deleteAssessmentFor: (name: string) => string;
+    assessmentFor: (type: string) => string;
+    nextAssessment: string;
+    noComment: string;
+    notGraded: string;
+    node: string;
+    attribute: string;
+    method: string;
+    /** Visible title for a concrete node type identifier. */
+    nodeTypeLabel: (nodeType?: string) => string;
+    startEvent: string;
+    intermediateEvent: string;
+    gateway: string;
+    gatewayType: string;
+    startType: string;
+    endType: string;
+    intermediateType: string;
+    taskType: string;
+    marker: string;
+    pool: string;
+    task: string;
+    endEvent: string;
+    bpmnDefault: string;
+    bpmnTimer: string;
+    bpmnConditional: string;
+    bpmnSignal: string;
+    bpmnEscalation: string;
+    bpmnError: string;
+    bpmnCompensation: string;
+    bpmnTerminate: string;
+    bpmnMessageCatch: string;
+    bpmnMessageThrow: string;
+    bpmnTimerCatch: string;
+    bpmnEscalationThrow: string;
+    bpmnConditionalCatch: string;
+    bpmnLinkCatch: string;
+    bpmnLinkThrow: string;
+    bpmnCompensationThrow: string;
+    bpmnSignalCatch: string;
+    bpmnSignalThrow: string;
+    bpmnExclusive: string;
+    bpmnParallel: string;
+    bpmnInclusive: string;
+    bpmnEventBased: string;
+    bpmnComplex: string;
+    bpmnUser: string;
+    bpmnSend: string;
+    bpmnReceive: string;
+    bpmnManual: string;
+    bpmnBusinessRule: string;
+    bpmnScript: string;
+    bpmnMarkerNone: string;
+    bpmnParallelMultiInstance: string;
+    bpmnSequentialMultiInstance: string;
+    bpmnLoop: string;
+    marking: string;
+    tokens: string;
+    capacity: string;
+    weight: string;
+    setFiniteCapacity: string;
+    setInfiniteCapacity: string;
+    nonterminal: string;
+    terminal: string;
+    class: string;
+    classType: string;
+    abstractClass: string;
+    interface: string;
+    enumeration: string;
+    reorderAttribute: string;
+    newAttribute: string;
+    addAttribute: string;
+    deleteAttribute: string;
+    attributes: string;
+    reorderMethod: string;
+    newMethod: string;
+    addMethod: string;
+    deleteMethod: string;
+    methods: string;
+    markMethodAsAbstract: string;
+    unmarkMethodAsAbstract: string;
+    abstractMethod: string;
+    messages: string;
+    message: string;
+    addMessage: string;
+    deleteMessage: (label: string) => string;
+    switchDirection: (direction: string) => string;
+    switchDirectionFor: (label: string, direction: string) => string;
+    messagePlaceholder: (index: number) => string;
+    messageFallbackLabel: (index: number) => string;
+    messageExists: string;
+    duplicateMessage: string;
+    swimlane: string;
+    lanes: string;
+    reorderLane: string;
+    deleteLane: string;
+    addLane: string;
+    laneName: string;
+    defaultLaneName: (index: number) => string;
+    orientation: string;
+    orientationVertical: string;
+    orientationHorizontal: string;
+    resizeLane: string;
+    componentName: string;
+    subsystemName: string;
+    stereotypePlaceholder: string;
+    isInitialMarking: string;
+    actionTable: string;
+    actions: string;
+    id: string;
+    actionName: string;
+    condition: string;
+    deleteActionRow: string;
+    addActionRow: string;
+    showCrossbar: string;
+    negatedCondition: string;
+    edgeType: string;
+    swapSourceTarget: string;
+    multiplicityLabel: (name: string) => string;
+    roleLabel: (name: string) => string;
+    deleteEdge: string;
+    editEdge: string;
+    deploymentAssociation: string;
+    deploymentDependency: string;
+    providedInterface: string;
+    requiredInterface: string;
+    sequenceFlow: string;
+    messageFlow: string;
+    associationFlow: string;
+    dataAssociationFlow: string;
+    association: string;
+    include: string;
+    extend: string;
+    generalization: string;
+    biAssociation: string;
+    uniAssociation: string;
+    aggregation: string;
+    composition: string;
+    inheritance: string;
+    dependency: string;
+    realization: string;
+    lineColor: string;
+    textColor: string;
+    fillColor: string;
+    namePlaceholder: string;
+    editColors: string;
+    editColorsFor: (label: string) => string;
+    colorPicker: (label: string) => string;
+    pickColor: string;
+    customColor: string;
+    custom: string;
+    reset: string;
+    /** Interpolated a11y label + tooltip for the header stereotype toggle. */
+    stereotypeToggleLabel: (name: string) => string;
+    stereotypeToggleTooltip: (shown: boolean, name: string) => string;
+    attributeWord: string;
+    methodWord: string;
+    classWord: string;
+    objectWord: string;
+    communicationObjectWord: string;
+    componentWord: string;
+    subsystemWord: string;
+    nodeWord: string;
+}
+
+export declare function ApollonMiniMap({ pannable, zoomable, ...placement }?: MiniMapControlOptions): null;
+
 export declare enum ApollonMode {
     Modelling = "Modelling",
     Exporting = "Exporting",
@@ -327,6 +576,22 @@ export declare type ApollonOptions = {
     collaborationEnabled?: boolean;
     collaboration?: ApollonCollaborationOptions;
     scrollLock?: boolean;
+    /**
+     * The chrome to register (vanilla / imperative). Build descriptors with the
+     * built-in factories — `paletteControl()`, `zoomControl({ history })`,
+     * `miniMapControl()` — and/or your own. OMIT for the editor defaults (palette +
+     * zoom + minimap); pass `[]` for a bare canvas; pass a subset to show only
+     * those. In React, compose `<Apollon.Palette|Zoom|MiniMap>` / `<ApollonControl>`
+     * children instead — both compile to the same registry records.
+     */
+    controls?: OverlayControlInput[];
+    /**
+     * Override any of the editor's own user-facing strings (palette / zoom / minimap
+     * tooltips and aria-labels) for i18n. Ships English; a host passes a partial map
+     * in its own language and the rest fall back to English. Reactive via
+     * `<Apollon labels>` / `editor.setLabels`. See {@link ApollonLabels}.
+     */
+    labels?: Partial<ApollonLabels>;
     /**
      * Optional `--apollon-*` CSS custom properties applied to the editor's mount
      * element. Build one with `createApollonTheme(...)`. Fully optional — an
@@ -341,6 +606,15 @@ export declare type ApollonOptions = {
     dataTheme?: "light" | "dark";
 };
 
+/**
+ * Compose the editor's built-in chrome as children of `<Apollon>`: presence
+ * renders it, omission hides it, and its typed props reconfigure it. Replacing a
+ * built-in is just rendering your own `<ApollonControl>` at the reserved id. All
+ * three register through the one overlay registry, identical to the vanilla
+ * `paletteControl()/zoomControl()/miniMapControl()` descriptors.
+ */
+export declare function ApollonPalette(props?: PaletteControlOptions): null;
+
 /**
  * Props for the {@link Apollon} React component.
  *
@@ -383,6 +657,8 @@ export declare interface ApollonProps {
     view?: ApollonView;
     mode?: ApollonMode;
     scrollLock?: boolean;
+    /** Override the editor's own strings for i18n. See {@link ApollonEditor.setLabels}. */
+    labels?: Partial<ApollonLabels>;
     /** Local-only preview overlay. See {@link ApollonEditor.setPreviewMode}. */
     previewMode?: boolean;
     /**
@@ -414,6 +690,45 @@ export declare function ApollonProvider({ editor, children, }: {
     children: ReactNode;
 }): JSX.Element;
 
+/**
+ * A selection-anchored control group: your controls float just above (or beside)
+ * the current selection, follow it as it moves, and stay a constant on-screen
+ * size at any zoom. Unlike `on-canvas` chrome (which lives in diagram space and
+ * scales), this is screen-space and only appears while something is selected.
+ *
+ * Compose it as a child of `<Apollon>`. It reserves no room (floats over the
+ * canvas) and needs no positioning props beyond the anchor side.
+ *
+ * ```tsx
+ * <Apollon>
+ *   <Apollon.Palette />
+ *   <Apollon.Zoom />
+ *   <Apollon.MiniMap />
+ *   <Apollon.SelectionToolbar position="top" ariaLabel="Selection actions">
+ *     <button onClick={onDelete}>Delete</button>
+ *     <button onClick={onDuplicate}>Duplicate</button>
+ *   </Apollon.SelectionToolbar>
+ * </Apollon>
+ * ```
+ */
+export declare function ApollonSelectionToolbar({ children, position, offset, id, ariaLabel, role, }: ApollonSelectionToolbarProps): ReactNode;
+
+export declare type ApollonSelectionToolbarProps = {
+    /** Toolbar content — your own buttons/menu. Portaled in, so it keeps host
+     *  context (theme, router) and reconciles normally. */
+    children: ReactNode;
+    /** Which side of the selection to anchor to. Default `"top"`. */
+    position?: "top" | "bottom" | "left" | "right";
+    /** Gap in px between the selection bounding box and the toolbar. Default 8. */
+    offset?: number;
+    /** Stable control id. Default `"apollon:selection-toolbar"`. */
+    id?: string;
+    /** Accessible name for the wrapper. */
+    ariaLabel?: string;
+    /** Wrapper landmark for the host controls. Use `"toolbar"` only when children implement toolbar keyboard behavior. */
+    role?: "toolbar" | "group";
+};
+
 /**
  * The documented, stable subset of the `--apollon-*` editor theming tokens.
  *
@@ -427,14 +742,23 @@ export declare function ApollonProvider({ editor, children, }: {
 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;
+    /**
+     * Ink drawn ON `primary` (accent buttons, the active tool). Defaults to white;
+     * set it when `primary` is light so on-accent text stays legible (white-on-light
+     * otherwise). Maps to `--apollon-primary-foreground`.
+     */
+    primaryForeground?: string;
+    /**
+     * Page foreground — the ink drawn on `background` (text, icons, chrome).
+     * This is NOT "a color that contrasts with `primary`"; it is the editor's
+     * base text color, and the whole chrome ramp derives from it plus
+     * `background`. Maps to `--apollon-foreground`.
+     */
+    foreground?: 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`. */
@@ -447,38 +771,18 @@ export declare interface ApollonTheme {
     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`. */
+    /** Error/danger text color (e.g. validation messages). Maps to `--apollon-danger`. */
     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 {
@@ -487,6 +791,8 @@ export declare enum ApollonView {
     Highlight = "Highlight"
 }
 
+export declare function ApollonZoom({ history, ...placement }?: ZoomControlOptions): null;
+
 export declare type Assessment = {
     modelElementId: string;
     elementType: string;
@@ -575,22 +881,46 @@ declare function BPMNTransaction({ id, width, height, data, parentId, }: NodePro
 
 declare type BPMNTransactionProps = DefaultNodeProps;
 
+declare type BuiltInPlacement<Region extends OverlayControlOptions["region"]> = Partial<Omit<OverlayControlOptions, "id" | "region">> & {
+    region?: Region;
+};
+
 declare function Class({ id, width, height, data, }: NodeProps<Node_2<ClassNodeProps>>): JSX.Element;
 
 declare type ClassNodeElement = {
     id: string;
+    /**
+     * Abstract modifier — renders the member's signature in italics (UML 2.5.1
+     * §9.4). Only ever set on *methods*: attributes are `StructuralFeature`s and
+     * cannot be abstract, so the attribute editor never surfaces the control.
+     */
+    isAbstract?: boolean;
 } & DefaultNodeProps;
 
 declare type ClassNodeProps = {
     methods: ClassNodeElement[];
     attributes: ClassNodeElement[];
-    stereotype?: ClassType;
+    /** Metaclass keyword only (`«interface»` / `«enumeration»`). */
+    stereotype?: ClassStereotype;
+    /**
+     * Class-level abstract modifier — renders the class name in italics (UML
+     * 2.5.1 §9.2.4). Orthogonal to `stereotype`; there is no `«abstract»` keyword.
+     */
+    isAbstract?: boolean;
 } & DefaultNodeProps;
 
-declare enum ClassType {
-    Abstract = "Abstract",
-    Interface = "Interface",
-    Enumeration = "Enumeration"
+/**
+ * UML class-diagram metaclass keywords, rendered in guillemets above the class
+ * name (e.g. `«interface»`). These are keywords denoting a distinct metaclass —
+ * NOT modifiers. Abstractness is a separate boolean (`isAbstract`), shown by an
+ * italic name, per UML 2.5.1 §9.2.4; there is no `«abstract»` keyword.
+ *
+ * Values are the serialized, already-lowercase spelling from the UML keyword
+ * table (UML 2.5.1 Annex C, Table C.1), so the stored value equals what renders.
+ */
+declare enum ClassStereotype {
+    Interface = "interface",
+    Enumeration = "enumeration"
 }
 
 export declare const collabColorFromName: (name: string) => string;
@@ -674,12 +1004,20 @@ declare type CustomEdgeProps = {
     targetRole: string | null;
     targetMultiplicity: string | null;
     points: IPoint[];
+    sourceAnchor?: FreeformEdgeAnchor;
+    targetAnchor?: FreeformEdgeAnchor;
     label?: string | null;
     messages?: MessageData[];
     strokeColor?: string;
     textColor?: string;
 };
 
+/** The shipped English strings — the fallback for any key a host doesn't override. */
+export declare const DEFAULT_LABELS: ApollonLabels;
+
+/** The editor's default chrome — palette, zoom/history cluster, minimap. */
+export declare function defaultControls(): OverlayControlInput[];
+
 declare type DefaultNodeProps = {
     name: string;
     fillColor?: string;
@@ -871,6 +1209,16 @@ declare function FlowchartTerminal({ id, width, height, data, parentId, }: NodeP
  */
 export declare const FONT_FAMILY = "Inter, system-ui, Avenir, Helvetica, Arial, sans-serif";
 
+declare type FreeformEdgeAnchor = {
+    side: Position;
+    /**
+     * Offset along the side, normalized to the current node side length. The
+     * editor rounds the resolved point to whole flow pixels, so a drop can land
+     * on any pixel while still scaling sensibly if the node is resized later.
+     */
+    ratio: number;
+};
+
 export declare const getAssessmentNameForArtemis: (elementId: string, model: UMLModel) => {
     name: string;
     type: string;
@@ -926,6 +1274,19 @@ declare interface MessageData {
     direction: "target" | "source";
 }
 
+export declare const MINIMAP_ID = "apollon:minimap";
+
+export declare function miniMapControl({ pannable, zoomable, region, ...placement }?: MiniMapControlOptions): OverlayControlInput;
+
+export declare type MiniMapControlOptions = BuiltInPlacement<MiniMapRegion> & {
+    /** Drag the minimap to pan the diagram. Default `true`. */
+    pannable?: boolean;
+    /** Scroll over the minimap to zoom the diagram. Default `true`. */
+    zoomable?: boolean;
+};
+
+declare type MiniMapRegion = Extract<PanelPosition, OverlayControlOptions["region"]>;
+
 declare function ObjectName({ id, width, height, data, }: NodeProps<Node_2<ObjectNodeProps>>): JSX.Element;
 
 declare type ObjectNodeProps = {
@@ -952,6 +1313,16 @@ export declare interface OverlayControlOptions {
     inset?: InsetContribution;
     /** Stacking within a region; lower renders toward the region's anchor edge. */
     order?: number;
+    /**
+     * Band lane (bands only). Controls in the SAME lane sit along the band's axis
+     * (side by side on `header`/`footer`, top-to-bottom on the rails) and reserve
+     * the taller/wider of them. Controls in DIFFERENT lanes STACK across the band's
+     * cross-axis and their reservations SUM — so two independently-registered bars
+     * on one edge (e.g. an exam bar in lane 0 and a "problem statement changed"
+     * banner in lane 1) both get room instead of overlapping. Lane 0 (default) sits
+     * against the band's anchor edge; higher lanes stack toward the canvas. Ignored
+     * for slots and `on-canvas`. */
+    lane?: 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
@@ -965,18 +1336,38 @@ export declare interface OverlayControlOptions {
     style?: CSSProperties;
 }
 
+/** Immutable public view of a registered control. Renderer internals are omitted. */
+export declare type OverlayControlSnapshot = Readonly<OverlayControlOptions>;
+
 /**
- * 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.
+ * Where a control is anchored. The six corners and the `header`/`footer`/rail
+ * bands are screen-space cells of the overlay grid; `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";
+export declare type OverlayRegion = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "header" | "footer" | "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;
 
+/**
+ * Framework-agnostic factories for the editor's built-in chrome. Each returns an
+ * {@link OverlayControlInput} descriptor under a reserved id, so the built-ins are
+ * the same registry records host controls use — registered via `editor.addControl`
+ * (vanilla / imperative) or the `<Apollon.Palette|Zoom|MiniMap>` compound
+ * components (React). Placement/appearance overrides ride the shared
+ * {@link OverlayControlOptions} vocabulary; the reserved id and default `render`
+ * are fixed here.
+ */
+export declare const PALETTE_ID = "apollon:palette";
+
+export declare function paletteControl(options?: PaletteControlOptions): OverlayControlInput;
+
+export declare type PaletteControlOptions = BuiltInPlacement<PaletteRegion>;
+
+declare type PaletteRegion = "left-rail" | "right-rail";
+
 declare function PetriNetPlace({ id, width, height, data, }: NodeProps<Node_2<PetriNetPlaceProps>>): JSX.Element | null;
 
 declare type PetriNetPlaceProps = {
@@ -1130,6 +1521,25 @@ declare function UseCaseActor({ id, width, height, data, parentId, }: NodeProps<
 
 declare function UseCaseSystem({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
+/**
+ * Register an overlay control for the component's lifetime, re-applying when
+ * `deps` change and disposing on unmount (react-map-gl's `useControl` shape). The
+ * built-in `render` runs inside the editor's overlay layer, so it resolves React
+ * Flow + store context regardless of where the component sits in the consumer's
+ * tree.
+ *
+ * `deps` gate re-registration, so — exactly as with `useMemo`/`useEffect` — they
+ * MUST list every value `make`'s returned `render` closes over, or the control
+ * keeps rendering stale values. Unlike `<ApollonControl>` (which portals children
+ * that reconcile on their own), here the closure IS the content, so the dep list
+ * is the only update signal.
+ */
+export declare function useControl(make: () => OverlayControlInput, deps: readonly unknown[]): void;
+
+/** The editor's active label set (English defaults merged with host overrides).
+ *  Reactive — a host swapping `labels` re-renders chrome without a remount. */
+export declare const useLabels: () => ApollonLabels;
+
 declare type V3Assessment = {
     modelElementId: string;
     elementType: string;
@@ -1260,4 +1670,13 @@ declare type V3UMLRelationship = V3UMLModelElement & {
     flowType?: string;
 };
 
+export declare const ZOOM_ID = "apollon:zoom";
+
+export declare function zoomControl({ history, region, ...placement }?: ZoomControlOptions): OverlayControlInput;
+
+export declare type ZoomControlOptions = BuiltInPlacement<OverlayControlOptions["region"]> & {
+    /** Show the undo / redo island (when an undo manager exists). Default `true`. */
+    history?: boolean;
+};
+
 export { }