@procaaso/alphinity-ui-components 1.12.0 → 1.14.0

package/dist/index.d.cts

@@ -528,10 +528,29 @@ interface CustomAction {
  * Device control capabilities and commands
  */
 interface ControlCapabilities {
-    /** Can the device be started? */
+    /**
+     * Can the device be started? When `canStart` or `canStop` is true, the
+     * panel shows BOTH the START and the STOP button, each in a fixed place
+     * (alphinity-tffi #3853). A false `canStart` then shows START disabled.
+     * It does not remove START and it does not let STOP take its place.
+     */
     canStart?: boolean;
-    /** Can the device be stopped? */
+    /** Can the device be stopped? See `canStart`. */
     canStop?: boolean;
+    /**
+     * Does START apply now? Default: true (enabled). Set false to show START
+     * disabled, for example on a pump that runs already. Use this with
+     * `canStart: true` to keep "the device has a START" apart from "START
+     * applies now". A disabled START does not call `onStart`.
+     */
+    startEnabled?: boolean;
+    /**
+     * Does STOP apply now? Default: true (enabled). Set false to show STOP
+     * disabled, for example on a pump that is stopped. The panel itself never
+     * disables STOP for a pending command. A disabled STOP does not call
+     * `onStop`.
+     */
+    stopEnabled?: boolean;
     /** Can the device be paused? */
     canPause?: boolean;
     /** Can the device be reset? */
@@ -609,8 +628,11 @@ interface ControlState {
      * Current status. `unknown` marks an untrusted read (OPC UA StatusCode
      * severity Bad). This library never infers `unknown`; it only displays a
      * value the backend has already published as `unknown`.
+     *
+     * `forced` marks a device that a maintenance force holds. It resolves to
+     * `FORCED_MARK_COLOR`, the same violet as every other forced mark.
      */
-    status?: 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown';
+    status?: 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown' | 'forced';
     /** Status message */
     statusMessage?: string;
     /** Last command timestamp */
@@ -775,12 +797,18 @@ interface DeviceControlPanelProps {
     /** Called when stop button clicked */
     onStop?: () => void;
     /**
-     * Start command is in flight (awaiting ack). Shows a busy affordance on the
-     * START button and disables it, without locking STOP — wire from the hook's
-     * `isCommandPending(nodeId, 'start')`.
+     * Start command is in flight (awaiting ack). START shows "STARTING..." and
+     * is disabled, so a second tap cannot send a second start. STOP stays
+     * enabled: a pending start never disables STOP (alphinity-tffi #3853).
+     * Wire from the hook's `isCommandPending(nodeId, 'start')`, or from the
+     * host's own in-flight state.
      */
     startPending?: boolean;
-    /** Stop command is in flight (awaiting ack). See `startPending`. */
+    /**
+     * Stop command is in flight (awaiting ack). STOP shows "STOPPING..." and
+     * stays enabled, so STOP is always one tap. Only `capabilities.canStop`
+     * or `capabilities.stopEnabled` can disable STOP.
+     */
     stopPending?: boolean;
     /** Called when custom action clicked */
     onCustomAction?: (actionId: string) => void;
@@ -1166,7 +1194,7 @@ declare const ThemeToggle: React__default.FC<ThemeToggleProps>;
  * from a number or a threshold. The library only displays an `unknown` value
  * that the backend has already published.
  */
-type DeviceStatus = 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown';
+type DeviceStatus = 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown' | 'forced';
 /** Color entry covering both SVG node and overlay/panel needs */
 interface StatusColorEntry {
     /** Fill color for SVG node symbols */
@@ -1219,6 +1247,22 @@ declare const ISA_UNKNOWN_DARK: {
     readonly bg: "#23263a";
     readonly border: "#6f74a3";
 };
+/**
+ * Maintenance-force marking color (#3607, R19). A forced value is not a
+ * health status, and must never share a color with warning/alarm/fault or
+ * read as one of them. Violet is unused elsewhere in this palette.
+ *
+ * `DEFAULT_STATUS_COLORS.forced` points at this same object (alphinity-tffi
+ * #3771). A device that a maintenance force holds then gets the forced
+ * violet on its status dot, and not the `off` grey fallback. The forced
+ * entry is a marker, not a severity: it stays outside the
+ * warning/alarm/fault colours.
+ *
+ * Light fill + dark text, not a solid vivid chip: reads as a calm marker
+ * rather than an alarm sticker, while the vivid `border` shade still
+ * outlines a forced value's box/ring so it stays findable at a glance.
+ */
+declare const FORCED_MARK_COLOR: StatusColorEntry;
 /**
  * ISA-101 defaults.
  *
@@ -1231,6 +1275,8 @@ declare const ISA_UNKNOWN_DARK: {
  * - stopping: amber (transitional)
  * - unknown:  periwinkle (untrusted read; OPC UA severity Bad). Derived
  *             from ISA_UNKNOWN above, the shared token.
+ * - forced:   violet (a maintenance force holds the device). The same
+ *             object as FORCED_MARK_COLOR above.
  *
  * The unknown entry deliberately does NOT rely on its fill. The flat fill
  * sits a CIEDE2000 delta-E of 0.45 from the off fill after greyscale
@@ -1245,17 +1291,6 @@ declare const ISA_UNKNOWN_DARK: {
  * apart. That is why unknown never relies on colour anywhere.
  */
 declare const DEFAULT_STATUS_COLORS: Record<DeviceStatus, StatusColorEntry>;
-/**
- * Maintenance-force marking color (#3607, R19). Deliberately outside
- * DEFAULT_STATUS_COLORS: a forced value is not a health status, and must
- * never share a color with warning/alarm/fault or read as one of them.
- * Violet is unused elsewhere in this palette.
- *
- * Light fill + dark text, not a solid vivid chip: reads as a calm marker
- * rather than an alarm sticker, while the vivid `border` shade still
- * outlines a forced value's box/ring so it stays findable at a glance.
- */
-declare const FORCED_MARK_COLOR: StatusColorEntry;
 /**
  * Normalize a status string to its canonical `DeviceStatus` key.
  *
@@ -1337,6 +1372,54 @@ interface UnknownStatusGlyphProps extends Omit<React__default.SVGProps<SVGSVGEle
  */
 declare function UnknownStatusGlyph({ size, counterRotate, style, ...rest }: UnknownStatusGlyphProps): React__default.ReactElement;
 
+/**
+ * A corner badge slot on a node (#33).
+ *
+ * A badge marks a condition that is NOT a health severity (`NodeInstance.status`)
+ * and must never replace the node's body color. A device can be tripped AND
+ * blocked at the same time; `status` shows the trip, the badge shows the
+ * block, and both render at once. This is a general slot, not a fixed
+ * prohibition badge: the consumer names the glyph, the colors, the corner,
+ * the size, and the motion. Register additional glyphs with
+ * `registerBadgeGlyph` (`src/diagram/badges`) rather than hardcoding a new
+ * one here.
+ */
+interface NodeBadgeAppearance {
+    /**
+     * Which glyph to draw. `'prohibit'` (a circle with a slash) ships with the
+     * library. The set is extensible: register more with `registerBadgeGlyph`
+     * / `registerBadgeGlyphs` and reference them by id here, the same way
+     * `symbolId` references a registered symbol.
+     */
+    glyph: 'prohibit' | string;
+    /** Glyph color (stroke/fill). Consumer picks; no status-driven default. */
+    color?: string;
+    /** Disc background color behind the glyph. Consumer picks. */
+    backgroundColor?: string;
+    /** Which corner of the node's bounding box the badge anchors to. Defaults to 'top-right'. */
+    corner?: NodeBadgeCorner;
+    /** Badge disc diameter, in the symbol's local SVG units. Defaults to 14. */
+    size?: number;
+    /** Accessible label read by assistive tech (e.g. "Start blocked"). */
+    label?: string;
+}
+type NodeBadgeCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Motion for a `NodeBadge`. Steady by default. A consumer that turns on
+ * `blink` MUST supply `blinkPeriodMs` - the library has no default period.
+ * TFFi drives its status tower, its batch bar, and this badge off one shared
+ * constant so all three beat together; a period fixed in the library would
+ * break that agreement, so there is deliberately no fallback value here.
+ */
+type NodeBadgeMotion = {
+    blink?: false;
+} | {
+    blink: true;
+    blinkPeriodMs: number;
+};
+/** The full badge: appearance plus motion. This is the type `NodeInstance.badge` carries. */
+type NodeBadge = NodeBadgeAppearance & NodeBadgeMotion;
+
 interface NodeInstance {
     id: string;
     symbolId: string;
@@ -1361,6 +1444,13 @@ interface NodeInstance {
      * symbol. Default off. Wins over status and customColors.
      */
     positionUnknown?: boolean;
+    /**
+     * A corner badge for a condition that is NOT a health severity (#33),
+     * e.g. a device blocked from starting. Stacks on top of `status` /
+     * `customColors` / `positionUnknown` - it never replaces the node's body
+     * color, so a node can show `status: 'fault'` and a badge at once.
+     */
+    badge?: NodeBadge;
     metadata?: Record<string, unknown>;
 }
 interface Transform {
@@ -2063,6 +2153,36 @@ declare function readAppearanceValue(node: NodeInstance, field: AppearanceField)
 /** Produce the NodeInstance update for a new field value. */
 declare function writeAppearanceValue(node: NodeInstance, field: AppearanceField, value: AppearanceValue): Partial<NodeInstance>;
 
+/**
+ * Registry of badge glyphs for the `NodeBadge` corner slot (#33).
+ *
+ * Mirrors `diagram/symbols/mockSymbolLibrary`'s registration pattern: a
+ * built-in set plus a consumer-registered set, looked up by id. A consumer
+ * calls `registerBadgeGlyph` from its own app code to add a glyph the
+ * library does not ship - the same escape hatch `registerSymbol` already
+ * gives P&ID symbols. This is deliberately NOT a string resolved only
+ * inside the library (the mistake `Overlay.content.component` made, per
+ * #33): the consumer supplies the real markup.
+ */
+interface BadgeGlyphDefinition {
+    /** Id a `NodeBadge.glyph` references. */
+    id: string;
+    /**
+     * Raw SVG markup, drawn centered in a 24x24 local box (0,0 to 24,24).
+     * Use `stroke="currentColor"` / `fill="currentColor"` so the glyph picks
+     * up `NodeBadge.color` - the glyph carries no color of its own, only shape.
+     */
+    svgContent: string;
+}
+/** Register a single custom badge glyph, or replace a built-in one by reusing its id. */
+declare function registerBadgeGlyph(glyph: BadgeGlyphDefinition): void;
+/** Register multiple custom badge glyphs at once. */
+declare function registerBadgeGlyphs(glyphs: BadgeGlyphDefinition[] | Record<string, BadgeGlyphDefinition>): void;
+/** Get a badge glyph definition by id (checks custom glyphs before built-ins). */
+declare function getBadgeGlyph(glyphId: string): BadgeGlyphDefinition | undefined;
+/** List every registered badge glyph id (built-in plus custom). */
+declare function getAvailableBadgeGlyphs(): string[];
+
 /**
  * Telemetry status type
  */
@@ -2479,4 +2599,4 @@ interface SimulationOptions {
  */
 declare function useSimulation(telemetry: TelemetryMap, updateTelemetryBatch: (updates: Array<any>) => void, options?: SimulationOptions): void;
 
-export { type AnchorType, type AppearanceField, type AppearanceFieldKind, type AppearanceTarget, type AppearanceValue, Button, type ButtonProps, COLOR_PRESETS, CardHeader, CardUnit, CardValue, CircularGauge, type CircularGaugeProps, type CommandKind, type ConfigActions, type ConfigDisplay, type ConfigParameter, type ConfigSection, type ConfigState, type ConfigTheme, type ControlCapabilities, type ControlMode, ControlPanel, type ControlPanelProps, type ControlParameter, type ControlState, type CustomAction, DEFAULT_STATUS_COLORS, DEFAULT_THRESHOLDS, DashboardCard, type DataBinding, type DeviceConfigBinding, type DeviceConfigMap, DeviceConfigPanel, type DeviceConfigPanelProps, type DeviceControlBinding, type DeviceControlMap, DeviceControlPanel, type DeviceControlPanelProps, type DeviceStatus, type Diagram, type DiagramMetadata, type DisplayMode, DisplayModeToggle, type DragPoint, type DragState, EquipmentIndicator, type EquipmentIndicatorProps, EquipmentIndicatorWithSparkline, type EquipmentIndicatorWithSparklineProps, FORCED_MARK_COLOR, FixedSVGContainer, FooterPanel, type ForcedState, FullscreenContainer, FullscreenWorkspace, type FullscreenWorkspaceProps, type FullscreenWorkspaceTab, ISA_UNKNOWN, ISA_UNKNOWN_DARK, type KeyboardShortcutsOptions, LeftPanel, LeftToggleButton, LegacyValueEntry, type LegacyValueEntryProps, type ModeConfig, NodeConfigPanel, type NodeConfigPanelProps, type NodeControlConfig, NodeControlsPanel, type NodeControlsPanelProps, type NodeInstance, NumpadDialog, type NumpadDialogProps, type Overlay, type OverlayContent, type OverlayTheme, type OverlayType, PIDCanvas, type PIDCanvasControls, type PIDCanvasFeatures, type PIDCanvasProps, PanelContent, PanelTabs, type PipeEdge, type PipeStyle, type Point, type PortDefinition, type PortInstance, type PortType, RightPanel, RightToggleButton, STATUS_LED_APPEARANCE, SVGArea, SVGLockedOverlay, type SVGLockedOverlayProps, type ScalingMetadata, ScrollableSVGWrapper, type SelectionState, Selector, type SelectorOption, type SelectorProps, type SimulationOptions, Sparkline, type SparklineProps, type StatusColorEntry, type StatusColorMap, StatusIndicator, type StatusIndicatorProps, type SymbolCategory, type SymbolDefinition, SymbolLibrary, type SymbolLibraryProps, type SymbolMetadata, type TelemetryBinding, type TelemetryMap, type TelemetryStatus$1 as TelemetryStatus, type TelemetryValue, ThemeProvider, ThemeToggle, type ThemeToggleProps, type Thresholds, type Transform, TrendLine, type TrendLineProps, UNKNOWN_GLYPH_RING_DASH, UNKNOWN_STATUS_GLYPH_COLOR_VAR, type UnknownGlyphSize, UnknownStatusGlyph, type UnknownStatusGlyphProps, type UseBooleanIndicatorsOptions, type UseDeviceControlsOptions, type UseDragOptions, type UseDragResult, type UseSelectionOptions, type UseSelectionResult, type UseTelemetryOptions, type UseTelemetryResult, type UseTelemetryStatusOptions, type UseViewBoxOptions, type UseViewBoxResult, ValueEntry, type ValueEntryProps, type ViewBox, ZoomButton, ZoomControls, calculateThresholdStatus, createConfigBinding, createControlBinding, exampleDiagram, exportDiagram, generateRoutePoints, getAppearanceDefaults, getAppearanceSchema, getAvailableSymbols, getPortWorldPosition, getSymbolDefinition, importDiagram, mockSymbolLibrary, nodeHasPort, normalizeDeviceStatus, overlayStyles, readAppearanceValue, registerSymbol, registerSymbols, resolvePresetColor, resolveStatusColor, useBooleanIndicators, useDeviceConfigs, useDeviceControls, useDrag, useKeyboardShortcuts, useSelection, useSimulation, useTelemetry, useTelemetryStatus, useTheme, useViewBox, validateDiagram, writeAppearanceValue };
+export { type AnchorType, type AppearanceField, type AppearanceFieldKind, type AppearanceTarget, type AppearanceValue, type BadgeGlyphDefinition, Button, type ButtonProps, COLOR_PRESETS, CardHeader, CardUnit, CardValue, CircularGauge, type CircularGaugeProps, type CommandKind, type ConfigActions, type ConfigDisplay, type ConfigParameter, type ConfigSection, type ConfigState, type ConfigTheme, type ControlCapabilities, type ControlMode, ControlPanel, type ControlPanelProps, type ControlParameter, type ControlState, type CustomAction, DEFAULT_STATUS_COLORS, DEFAULT_THRESHOLDS, DashboardCard, type DataBinding, type DeviceConfigBinding, type DeviceConfigMap, DeviceConfigPanel, type DeviceConfigPanelProps, type DeviceControlBinding, type DeviceControlMap, DeviceControlPanel, type DeviceControlPanelProps, type DeviceStatus, type Diagram, type DiagramMetadata, type DisplayMode, DisplayModeToggle, type DragPoint, type DragState, EquipmentIndicator, type EquipmentIndicatorProps, EquipmentIndicatorWithSparkline, type EquipmentIndicatorWithSparklineProps, FORCED_MARK_COLOR, FixedSVGContainer, FooterPanel, type ForcedState, FullscreenContainer, FullscreenWorkspace, type FullscreenWorkspaceProps, type FullscreenWorkspaceTab, ISA_UNKNOWN, ISA_UNKNOWN_DARK, type KeyboardShortcutsOptions, LeftPanel, LeftToggleButton, LegacyValueEntry, type LegacyValueEntryProps, type ModeConfig, type NodeBadge, type NodeBadgeAppearance, type NodeBadgeCorner, type NodeBadgeMotion, NodeConfigPanel, type NodeConfigPanelProps, type NodeControlConfig, NodeControlsPanel, type NodeControlsPanelProps, type NodeInstance, NumpadDialog, type NumpadDialogProps, type Overlay, type OverlayContent, type OverlayTheme, type OverlayType, PIDCanvas, type PIDCanvasControls, type PIDCanvasFeatures, type PIDCanvasProps, PanelContent, PanelTabs, type PipeEdge, type PipeStyle, type Point, type PortDefinition, type PortInstance, type PortType, RightPanel, RightToggleButton, STATUS_LED_APPEARANCE, SVGArea, SVGLockedOverlay, type SVGLockedOverlayProps, type ScalingMetadata, ScrollableSVGWrapper, type SelectionState, Selector, type SelectorOption, type SelectorProps, type SimulationOptions, Sparkline, type SparklineProps, type StatusColorEntry, type StatusColorMap, StatusIndicator, type StatusIndicatorProps, type SymbolCategory, type SymbolDefinition, SymbolLibrary, type SymbolLibraryProps, type SymbolMetadata, type TelemetryBinding, type TelemetryMap, type TelemetryStatus$1 as TelemetryStatus, type TelemetryValue, ThemeProvider, ThemeToggle, type ThemeToggleProps, type Thresholds, type Transform, TrendLine, type TrendLineProps, UNKNOWN_GLYPH_RING_DASH, UNKNOWN_STATUS_GLYPH_COLOR_VAR, type UnknownGlyphSize, UnknownStatusGlyph, type UnknownStatusGlyphProps, type UseBooleanIndicatorsOptions, type UseDeviceControlsOptions, type UseDragOptions, type UseDragResult, type UseSelectionOptions, type UseSelectionResult, type UseTelemetryOptions, type UseTelemetryResult, type UseTelemetryStatusOptions, type UseViewBoxOptions, type UseViewBoxResult, ValueEntry, type ValueEntryProps, type ViewBox, ZoomButton, ZoomControls, calculateThresholdStatus, createConfigBinding, createControlBinding, exampleDiagram, exportDiagram, generateRoutePoints, getAppearanceDefaults, getAppearanceSchema, getAvailableBadgeGlyphs, getAvailableSymbols, getBadgeGlyph, getPortWorldPosition, getSymbolDefinition, importDiagram, mockSymbolLibrary, nodeHasPort, normalizeDeviceStatus, overlayStyles, readAppearanceValue, registerBadgeGlyph, registerBadgeGlyphs, registerSymbol, registerSymbols, resolvePresetColor, resolveStatusColor, useBooleanIndicators, useDeviceConfigs, useDeviceControls, useDrag, useKeyboardShortcuts, useSelection, useSimulation, useTelemetry, useTelemetryStatus, useTheme, useViewBox, validateDiagram, writeAppearanceValue };

package/dist/index.d.ts

@@ -528,10 +528,29 @@ interface CustomAction {
  * Device control capabilities and commands
  */
 interface ControlCapabilities {
-    /** Can the device be started? */
+    /**
+     * Can the device be started? When `canStart` or `canStop` is true, the
+     * panel shows BOTH the START and the STOP button, each in a fixed place
+     * (alphinity-tffi #3853). A false `canStart` then shows START disabled.
+     * It does not remove START and it does not let STOP take its place.
+     */
     canStart?: boolean;
-    /** Can the device be stopped? */
+    /** Can the device be stopped? See `canStart`. */
     canStop?: boolean;
+    /**
+     * Does START apply now? Default: true (enabled). Set false to show START
+     * disabled, for example on a pump that runs already. Use this with
+     * `canStart: true` to keep "the device has a START" apart from "START
+     * applies now". A disabled START does not call `onStart`.
+     */
+    startEnabled?: boolean;
+    /**
+     * Does STOP apply now? Default: true (enabled). Set false to show STOP
+     * disabled, for example on a pump that is stopped. The panel itself never
+     * disables STOP for a pending command. A disabled STOP does not call
+     * `onStop`.
+     */
+    stopEnabled?: boolean;
     /** Can the device be paused? */
     canPause?: boolean;
     /** Can the device be reset? */
@@ -609,8 +628,11 @@ interface ControlState {
      * Current status. `unknown` marks an untrusted read (OPC UA StatusCode
      * severity Bad). This library never infers `unknown`; it only displays a
      * value the backend has already published as `unknown`.
+     *
+     * `forced` marks a device that a maintenance force holds. It resolves to
+     * `FORCED_MARK_COLOR`, the same violet as every other forced mark.
      */
-    status?: 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown';
+    status?: 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown' | 'forced';
     /** Status message */
     statusMessage?: string;
     /** Last command timestamp */
@@ -775,12 +797,18 @@ interface DeviceControlPanelProps {
     /** Called when stop button clicked */
     onStop?: () => void;
     /**
-     * Start command is in flight (awaiting ack). Shows a busy affordance on the
-     * START button and disables it, without locking STOP — wire from the hook's
-     * `isCommandPending(nodeId, 'start')`.
+     * Start command is in flight (awaiting ack). START shows "STARTING..." and
+     * is disabled, so a second tap cannot send a second start. STOP stays
+     * enabled: a pending start never disables STOP (alphinity-tffi #3853).
+     * Wire from the hook's `isCommandPending(nodeId, 'start')`, or from the
+     * host's own in-flight state.
      */
     startPending?: boolean;
-    /** Stop command is in flight (awaiting ack). See `startPending`. */
+    /**
+     * Stop command is in flight (awaiting ack). STOP shows "STOPPING..." and
+     * stays enabled, so STOP is always one tap. Only `capabilities.canStop`
+     * or `capabilities.stopEnabled` can disable STOP.
+     */
     stopPending?: boolean;
     /** Called when custom action clicked */
     onCustomAction?: (actionId: string) => void;
@@ -1166,7 +1194,7 @@ declare const ThemeToggle: React__default.FC<ThemeToggleProps>;
  * from a number or a threshold. The library only displays an `unknown` value
  * that the backend has already published.
  */
-type DeviceStatus = 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown';
+type DeviceStatus = 'normal' | 'warning' | 'alarm' | 'fault' | 'off' | 'starting' | 'stopping' | 'unknown' | 'forced';
 /** Color entry covering both SVG node and overlay/panel needs */
 interface StatusColorEntry {
     /** Fill color for SVG node symbols */
@@ -1219,6 +1247,22 @@ declare const ISA_UNKNOWN_DARK: {
     readonly bg: "#23263a";
     readonly border: "#6f74a3";
 };
+/**
+ * Maintenance-force marking color (#3607, R19). A forced value is not a
+ * health status, and must never share a color with warning/alarm/fault or
+ * read as one of them. Violet is unused elsewhere in this palette.
+ *
+ * `DEFAULT_STATUS_COLORS.forced` points at this same object (alphinity-tffi
+ * #3771). A device that a maintenance force holds then gets the forced
+ * violet on its status dot, and not the `off` grey fallback. The forced
+ * entry is a marker, not a severity: it stays outside the
+ * warning/alarm/fault colours.
+ *
+ * Light fill + dark text, not a solid vivid chip: reads as a calm marker
+ * rather than an alarm sticker, while the vivid `border` shade still
+ * outlines a forced value's box/ring so it stays findable at a glance.
+ */
+declare const FORCED_MARK_COLOR: StatusColorEntry;
 /**
  * ISA-101 defaults.
  *
@@ -1231,6 +1275,8 @@ declare const ISA_UNKNOWN_DARK: {
  * - stopping: amber (transitional)
  * - unknown:  periwinkle (untrusted read; OPC UA severity Bad). Derived
  *             from ISA_UNKNOWN above, the shared token.
+ * - forced:   violet (a maintenance force holds the device). The same
+ *             object as FORCED_MARK_COLOR above.
  *
  * The unknown entry deliberately does NOT rely on its fill. The flat fill
  * sits a CIEDE2000 delta-E of 0.45 from the off fill after greyscale
@@ -1245,17 +1291,6 @@ declare const ISA_UNKNOWN_DARK: {
  * apart. That is why unknown never relies on colour anywhere.
  */
 declare const DEFAULT_STATUS_COLORS: Record<DeviceStatus, StatusColorEntry>;
-/**
- * Maintenance-force marking color (#3607, R19). Deliberately outside
- * DEFAULT_STATUS_COLORS: a forced value is not a health status, and must
- * never share a color with warning/alarm/fault or read as one of them.
- * Violet is unused elsewhere in this palette.
- *
- * Light fill + dark text, not a solid vivid chip: reads as a calm marker
- * rather than an alarm sticker, while the vivid `border` shade still
- * outlines a forced value's box/ring so it stays findable at a glance.
- */
-declare const FORCED_MARK_COLOR: StatusColorEntry;
 /**
  * Normalize a status string to its canonical `DeviceStatus` key.
  *
@@ -1337,6 +1372,54 @@ interface UnknownStatusGlyphProps extends Omit<React__default.SVGProps<SVGSVGEle
  */
 declare function UnknownStatusGlyph({ size, counterRotate, style, ...rest }: UnknownStatusGlyphProps): React__default.ReactElement;
 
+/**
+ * A corner badge slot on a node (#33).
+ *
+ * A badge marks a condition that is NOT a health severity (`NodeInstance.status`)
+ * and must never replace the node's body color. A device can be tripped AND
+ * blocked at the same time; `status` shows the trip, the badge shows the
+ * block, and both render at once. This is a general slot, not a fixed
+ * prohibition badge: the consumer names the glyph, the colors, the corner,
+ * the size, and the motion. Register additional glyphs with
+ * `registerBadgeGlyph` (`src/diagram/badges`) rather than hardcoding a new
+ * one here.
+ */
+interface NodeBadgeAppearance {
+    /**
+     * Which glyph to draw. `'prohibit'` (a circle with a slash) ships with the
+     * library. The set is extensible: register more with `registerBadgeGlyph`
+     * / `registerBadgeGlyphs` and reference them by id here, the same way
+     * `symbolId` references a registered symbol.
+     */
+    glyph: 'prohibit' | string;
+    /** Glyph color (stroke/fill). Consumer picks; no status-driven default. */
+    color?: string;
+    /** Disc background color behind the glyph. Consumer picks. */
+    backgroundColor?: string;
+    /** Which corner of the node's bounding box the badge anchors to. Defaults to 'top-right'. */
+    corner?: NodeBadgeCorner;
+    /** Badge disc diameter, in the symbol's local SVG units. Defaults to 14. */
+    size?: number;
+    /** Accessible label read by assistive tech (e.g. "Start blocked"). */
+    label?: string;
+}
+type NodeBadgeCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Motion for a `NodeBadge`. Steady by default. A consumer that turns on
+ * `blink` MUST supply `blinkPeriodMs` - the library has no default period.
+ * TFFi drives its status tower, its batch bar, and this badge off one shared
+ * constant so all three beat together; a period fixed in the library would
+ * break that agreement, so there is deliberately no fallback value here.
+ */
+type NodeBadgeMotion = {
+    blink?: false;
+} | {
+    blink: true;
+    blinkPeriodMs: number;
+};
+/** The full badge: appearance plus motion. This is the type `NodeInstance.badge` carries. */
+type NodeBadge = NodeBadgeAppearance & NodeBadgeMotion;
+
 interface NodeInstance {
     id: string;
     symbolId: string;
@@ -1361,6 +1444,13 @@ interface NodeInstance {
      * symbol. Default off. Wins over status and customColors.
      */
     positionUnknown?: boolean;
+    /**
+     * A corner badge for a condition that is NOT a health severity (#33),
+     * e.g. a device blocked from starting. Stacks on top of `status` /
+     * `customColors` / `positionUnknown` - it never replaces the node's body
+     * color, so a node can show `status: 'fault'` and a badge at once.
+     */
+    badge?: NodeBadge;
     metadata?: Record<string, unknown>;
 }
 interface Transform {
@@ -2063,6 +2153,36 @@ declare function readAppearanceValue(node: NodeInstance, field: AppearanceField)
 /** Produce the NodeInstance update for a new field value. */
 declare function writeAppearanceValue(node: NodeInstance, field: AppearanceField, value: AppearanceValue): Partial<NodeInstance>;
 
+/**
+ * Registry of badge glyphs for the `NodeBadge` corner slot (#33).
+ *
+ * Mirrors `diagram/symbols/mockSymbolLibrary`'s registration pattern: a
+ * built-in set plus a consumer-registered set, looked up by id. A consumer
+ * calls `registerBadgeGlyph` from its own app code to add a glyph the
+ * library does not ship - the same escape hatch `registerSymbol` already
+ * gives P&ID symbols. This is deliberately NOT a string resolved only
+ * inside the library (the mistake `Overlay.content.component` made, per
+ * #33): the consumer supplies the real markup.
+ */
+interface BadgeGlyphDefinition {
+    /** Id a `NodeBadge.glyph` references. */
+    id: string;
+    /**
+     * Raw SVG markup, drawn centered in a 24x24 local box (0,0 to 24,24).
+     * Use `stroke="currentColor"` / `fill="currentColor"` so the glyph picks
+     * up `NodeBadge.color` - the glyph carries no color of its own, only shape.
+     */
+    svgContent: string;
+}
+/** Register a single custom badge glyph, or replace a built-in one by reusing its id. */
+declare function registerBadgeGlyph(glyph: BadgeGlyphDefinition): void;
+/** Register multiple custom badge glyphs at once. */
+declare function registerBadgeGlyphs(glyphs: BadgeGlyphDefinition[] | Record<string, BadgeGlyphDefinition>): void;
+/** Get a badge glyph definition by id (checks custom glyphs before built-ins). */
+declare function getBadgeGlyph(glyphId: string): BadgeGlyphDefinition | undefined;
+/** List every registered badge glyph id (built-in plus custom). */
+declare function getAvailableBadgeGlyphs(): string[];
+
 /**
  * Telemetry status type
  */
@@ -2479,4 +2599,4 @@ interface SimulationOptions {
  */
 declare function useSimulation(telemetry: TelemetryMap, updateTelemetryBatch: (updates: Array<any>) => void, options?: SimulationOptions): void;
 
-export { type AnchorType, type AppearanceField, type AppearanceFieldKind, type AppearanceTarget, type AppearanceValue, Button, type ButtonProps, COLOR_PRESETS, CardHeader, CardUnit, CardValue, CircularGauge, type CircularGaugeProps, type CommandKind, type ConfigActions, type ConfigDisplay, type ConfigParameter, type ConfigSection, type ConfigState, type ConfigTheme, type ControlCapabilities, type ControlMode, ControlPanel, type ControlPanelProps, type ControlParameter, type ControlState, type CustomAction, DEFAULT_STATUS_COLORS, DEFAULT_THRESHOLDS, DashboardCard, type DataBinding, type DeviceConfigBinding, type DeviceConfigMap, DeviceConfigPanel, type DeviceConfigPanelProps, type DeviceControlBinding, type DeviceControlMap, DeviceControlPanel, type DeviceControlPanelProps, type DeviceStatus, type Diagram, type DiagramMetadata, type DisplayMode, DisplayModeToggle, type DragPoint, type DragState, EquipmentIndicator, type EquipmentIndicatorProps, EquipmentIndicatorWithSparkline, type EquipmentIndicatorWithSparklineProps, FORCED_MARK_COLOR, FixedSVGContainer, FooterPanel, type ForcedState, FullscreenContainer, FullscreenWorkspace, type FullscreenWorkspaceProps, type FullscreenWorkspaceTab, ISA_UNKNOWN, ISA_UNKNOWN_DARK, type KeyboardShortcutsOptions, LeftPanel, LeftToggleButton, LegacyValueEntry, type LegacyValueEntryProps, type ModeConfig, NodeConfigPanel, type NodeConfigPanelProps, type NodeControlConfig, NodeControlsPanel, type NodeControlsPanelProps, type NodeInstance, NumpadDialog, type NumpadDialogProps, type Overlay, type OverlayContent, type OverlayTheme, type OverlayType, PIDCanvas, type PIDCanvasControls, type PIDCanvasFeatures, type PIDCanvasProps, PanelContent, PanelTabs, type PipeEdge, type PipeStyle, type Point, type PortDefinition, type PortInstance, type PortType, RightPanel, RightToggleButton, STATUS_LED_APPEARANCE, SVGArea, SVGLockedOverlay, type SVGLockedOverlayProps, type ScalingMetadata, ScrollableSVGWrapper, type SelectionState, Selector, type SelectorOption, type SelectorProps, type SimulationOptions, Sparkline, type SparklineProps, type StatusColorEntry, type StatusColorMap, StatusIndicator, type StatusIndicatorProps, type SymbolCategory, type SymbolDefinition, SymbolLibrary, type SymbolLibraryProps, type SymbolMetadata, type TelemetryBinding, type TelemetryMap, type TelemetryStatus$1 as TelemetryStatus, type TelemetryValue, ThemeProvider, ThemeToggle, type ThemeToggleProps, type Thresholds, type Transform, TrendLine, type TrendLineProps, UNKNOWN_GLYPH_RING_DASH, UNKNOWN_STATUS_GLYPH_COLOR_VAR, type UnknownGlyphSize, UnknownStatusGlyph, type UnknownStatusGlyphProps, type UseBooleanIndicatorsOptions, type UseDeviceControlsOptions, type UseDragOptions, type UseDragResult, type UseSelectionOptions, type UseSelectionResult, type UseTelemetryOptions, type UseTelemetryResult, type UseTelemetryStatusOptions, type UseViewBoxOptions, type UseViewBoxResult, ValueEntry, type ValueEntryProps, type ViewBox, ZoomButton, ZoomControls, calculateThresholdStatus, createConfigBinding, createControlBinding, exampleDiagram, exportDiagram, generateRoutePoints, getAppearanceDefaults, getAppearanceSchema, getAvailableSymbols, getPortWorldPosition, getSymbolDefinition, importDiagram, mockSymbolLibrary, nodeHasPort, normalizeDeviceStatus, overlayStyles, readAppearanceValue, registerSymbol, registerSymbols, resolvePresetColor, resolveStatusColor, useBooleanIndicators, useDeviceConfigs, useDeviceControls, useDrag, useKeyboardShortcuts, useSelection, useSimulation, useTelemetry, useTelemetryStatus, useTheme, useViewBox, validateDiagram, writeAppearanceValue };
+export { type AnchorType, type AppearanceField, type AppearanceFieldKind, type AppearanceTarget, type AppearanceValue, type BadgeGlyphDefinition, Button, type ButtonProps, COLOR_PRESETS, CardHeader, CardUnit, CardValue, CircularGauge, type CircularGaugeProps, type CommandKind, type ConfigActions, type ConfigDisplay, type ConfigParameter, type ConfigSection, type ConfigState, type ConfigTheme, type ControlCapabilities, type ControlMode, ControlPanel, type ControlPanelProps, type ControlParameter, type ControlState, type CustomAction, DEFAULT_STATUS_COLORS, DEFAULT_THRESHOLDS, DashboardCard, type DataBinding, type DeviceConfigBinding, type DeviceConfigMap, DeviceConfigPanel, type DeviceConfigPanelProps, type DeviceControlBinding, type DeviceControlMap, DeviceControlPanel, type DeviceControlPanelProps, type DeviceStatus, type Diagram, type DiagramMetadata, type DisplayMode, DisplayModeToggle, type DragPoint, type DragState, EquipmentIndicator, type EquipmentIndicatorProps, EquipmentIndicatorWithSparkline, type EquipmentIndicatorWithSparklineProps, FORCED_MARK_COLOR, FixedSVGContainer, FooterPanel, type ForcedState, FullscreenContainer, FullscreenWorkspace, type FullscreenWorkspaceProps, type FullscreenWorkspaceTab, ISA_UNKNOWN, ISA_UNKNOWN_DARK, type KeyboardShortcutsOptions, LeftPanel, LeftToggleButton, LegacyValueEntry, type LegacyValueEntryProps, type ModeConfig, type NodeBadge, type NodeBadgeAppearance, type NodeBadgeCorner, type NodeBadgeMotion, NodeConfigPanel, type NodeConfigPanelProps, type NodeControlConfig, NodeControlsPanel, type NodeControlsPanelProps, type NodeInstance, NumpadDialog, type NumpadDialogProps, type Overlay, type OverlayContent, type OverlayTheme, type OverlayType, PIDCanvas, type PIDCanvasControls, type PIDCanvasFeatures, type PIDCanvasProps, PanelContent, PanelTabs, type PipeEdge, type PipeStyle, type Point, type PortDefinition, type PortInstance, type PortType, RightPanel, RightToggleButton, STATUS_LED_APPEARANCE, SVGArea, SVGLockedOverlay, type SVGLockedOverlayProps, type ScalingMetadata, ScrollableSVGWrapper, type SelectionState, Selector, type SelectorOption, type SelectorProps, type SimulationOptions, Sparkline, type SparklineProps, type StatusColorEntry, type StatusColorMap, StatusIndicator, type StatusIndicatorProps, type SymbolCategory, type SymbolDefinition, SymbolLibrary, type SymbolLibraryProps, type SymbolMetadata, type TelemetryBinding, type TelemetryMap, type TelemetryStatus$1 as TelemetryStatus, type TelemetryValue, ThemeProvider, ThemeToggle, type ThemeToggleProps, type Thresholds, type Transform, TrendLine, type TrendLineProps, UNKNOWN_GLYPH_RING_DASH, UNKNOWN_STATUS_GLYPH_COLOR_VAR, type UnknownGlyphSize, UnknownStatusGlyph, type UnknownStatusGlyphProps, type UseBooleanIndicatorsOptions, type UseDeviceControlsOptions, type UseDragOptions, type UseDragResult, type UseSelectionOptions, type UseSelectionResult, type UseTelemetryOptions, type UseTelemetryResult, type UseTelemetryStatusOptions, type UseViewBoxOptions, type UseViewBoxResult, ValueEntry, type ValueEntryProps, type ViewBox, ZoomButton, ZoomControls, calculateThresholdStatus, createConfigBinding, createControlBinding, exampleDiagram, exportDiagram, generateRoutePoints, getAppearanceDefaults, getAppearanceSchema, getAvailableBadgeGlyphs, getAvailableSymbols, getBadgeGlyph, getPortWorldPosition, getSymbolDefinition, importDiagram, mockSymbolLibrary, nodeHasPort, normalizeDeviceStatus, overlayStyles, readAppearanceValue, registerBadgeGlyph, registerBadgeGlyphs, registerSymbol, registerSymbols, resolvePresetColor, resolveStatusColor, useBooleanIndicators, useDeviceConfigs, useDeviceControls, useDrag, useKeyboardShortcuts, useSelection, useSimulation, useTelemetry, useTelemetryStatus, useTheme, useViewBox, validateDiagram, writeAppearanceValue };