@fiddle-digital/string-tune 1.1.55 → 1.2.0

package/dist/index.d.mts

@@ -469,12 +469,13 @@ declare class StringObject {
      * Mirror objects linked via `string-copy-from`.
      */
     private mirrors;
+    private _cachedMirrorObjects;
+    private _cachedConnects;
+    private _mirrorsDirty;
     /**
      * Internal key-value store of dynamic object properties (like offsets, progress, etc.).
      */
     private properties;
-    private eventNameCache;
-    private eventNameSuffixCache;
     /**
      * Modules currently connected to this object.
      */
@@ -484,6 +485,8 @@ declare class StringObject {
      * Provides functionality to register, trigger, and manage event listeners.
      */
     events: EventManager;
+    private eventNameCache;
+    private eventNameSuffixCache;
     constructor(id: string, element: HTMLElement);
     /**
      * Returns a cached event name in one of these forms:
@@ -521,6 +524,8 @@ declare class StringObject {
     remove(): void;
     setInviewAutoBlocked(blocked: boolean): void;
     isInviewAutoBlocked(): boolean;
+    setInviewManualActive(active: boolean): void;
+    isInviewManualActive(): boolean;
     syncInviewClass(): void;
     /**
      * Shows the object, applies visual class and notifies connected modules.
@@ -539,6 +544,7 @@ declare class StringObject {
     isConnectedTo(module: IStringModule): boolean;
     setTokens(tokens: StringToken[]): void;
     getToken(key: string): StringToken | null;
+    private updateMirrorsCache;
     addMirror(mirror: StringMirrorObject): void;
     removeMirror(id: string): void;
     get mirrorObjects(): StringMirrorObject[];
@@ -1061,6 +1067,7 @@ interface ISplitOptionItem {
  */
 interface ISplitOptions {
     fit?: boolean;
+    trimInlineGaps?: boolean;
     line?: ISplitOptionItem[];
     word?: ISplitOptionItem[];
     char?: ISplitOptionItem[];
@@ -1237,6 +1244,12 @@ type AttributeMapping = {
     transform?: (value: any) => any;
 };
 
+interface ParseContext {
+    element?: HTMLElement;
+    boundingRect?: DOMRect;
+    viewportHeight?: number;
+    baseRem?: number;
+}
 /**
  * Base class for a module used in the string-tune system.
  * Extend this class to create custom modules that respond to scroll, resize, input, etc.
@@ -1370,12 +1383,7 @@ declare class StringModule implements IStringModule {
      * @param context Optional helper values like element or viewport size.
      * @returns The parsed and transformed value.
      */
-    protected parseAttribute(value: string | null, type: AttributeType, context?: {
-        element?: HTMLElement;
-        boundingRect?: DOMRect;
-        viewportHeight?: number;
-        baseRem?: number;
-    }): any;
+    protected parseAttribute(value: string | null, type: AttributeType, context?: ParseContext): any;
     /**
      * Determines whether the module should attach to a given object,
      * based on the presence of the module's `htmlKey` in the object keys.
@@ -1398,6 +1406,7 @@ declare class StringModule implements IStringModule {
      * Registers the object internally when it enters the module’s scope.
      */
     enterObject(id: string, object: StringObject): void;
+    protected fastRemoveFromArray<T>(array: T[], index: number): void;
     /**
      * Unregisters the object when it leaves the module’s scope.
      */
@@ -1436,6 +1445,8 @@ declare class StringModule implements IStringModule {
      * @param object The disconnected object.
      */
     onObjectDisconnected(object: StringObject): void;
+    protected get respectSelfDisable(): boolean;
+    protected isPrimaryElementEnabled(object: StringObject): boolean;
     /**
      * Applies a style or callback to both the main element and all its connected elements.
      *
@@ -2053,11 +2064,31 @@ declare class StringScrollbar extends StringModule {
  * computes alignment/random values, and applies CSS vars.
  */
 declare class StringSplit extends StringModule {
+    /** Last content-width (px) at which each element was split. Keyed by element itself. */
+    private lastSplitWidth;
     constructor(context: StringContext);
     onInit(): void;
+    onObjectDisconnected(object: StringObject): void;
     onResizeWidth(): void;
     onObjectConnected(object: StringObject): void;
-    split(element: HTMLElement, options: ISplitOptions): {
+    private extractTextContent;
+    private getSplitOptions;
+    private hasLineDrivenSplit;
+    private needsWidthRebuild;
+    private needsForcedRebuildOnFontLoad;
+    private getDebugStoreKey;
+    private writeDebugRecord;
+    private isDebugEnabled;
+    private getDebugLabel;
+    private logConnectionStart;
+    private captureBaselineSnapshot;
+    private logSplitAnalysis;
+    private getTokenDebugText;
+    private logRenderedState;
+    private applyFlexLineBreaks;
+    private getBlockContainerContentWidth;
+    private getElementContentWidth;
+    split(element: HTMLElement, options: ISplitOptions, debugEnabled?: boolean): {
         fragment: DocumentFragment;
         result: DocumentFragment;
         extraProps: Map<string, string>;
@@ -2591,104 +2622,36 @@ declare class StringRandom extends StringModule {
     onObjectConnected(object: StringObject): void;
 }
 
-/**
- * Base class for managing scroll behavior in the system.
- * Handles abstract scroll state and updates, intended for extension.
- */
 declare class ScrollController {
-    /** Shared context containing data and tools */
     protected context: StringContext;
-    /** Reference to the document object */
     protected document: Document;
-    /** Name of the scroll mode (e.g. 'default', 'smooth', etc.) */
     name: string;
-    /** Whether the system is in programmatic scroll mode */
     isProg: boolean;
-    /** Whether parallax-related logic should be active */
     isParallaxEnabled: boolean;
-    /** Scroll direction: vertical or horizontal */
-    protected _scrollDirection: "vertical" | "horizontal";
-    /**
-     * Current scroll direction.
-     * - `true` — scrolling down
-     * - `false` — scrolling up
-     * - `null` — unknown (initial state)
-     */
-    protected isBottomScrollDirection: boolean | null;
+    protected _isVertical: boolean;
+    protected _scrollDirState: number;
+    protected _lastAppliedDirState: number;
     protected isLastBottomScrollDirection: boolean;
     protected scrollTriggerRules: Array<ScrollMarkRule>;
-    /** Tracks whether this controller is currently active */
     protected isActive: boolean;
-    /** Last direction applied to DOM classes (for global-class toggles) */
-    protected lastAppliedDirection: boolean | null;
-    /**
-     * Sets scroll direction and updates internal scroll logic.
-     * @param scrollDirection Either 'vertical' or 'horizontal'.
-     */
-    set scrollDirection(scrollDirection: "vertical" | "horizontal");
-    /**
-     * Creates a new ScrollController instance.
-     * @param context Shared context containing data and settings.
-     */
+    set scrollDirection(dir: "vertical" | "horizontal");
     constructor(context: StringContext);
-    /**
-     * Called when scroll direction changes (up ↔ down).
-     * Override this callback in subclasses or instances.
-     */
     onChangeDirection: () => void;
-    /**
-     * Called when scroll starts (user input).
-     * Override this callback in subclasses or instances.
-     */
     onScrollStart: () => void;
-    /**
-     * Called when scroll ends.
-     * Override this callback in subclasses or instances.
-     */
     onScrollStop: () => void;
-    /**
-     * Scroll-to function called on each frame.
-     * This will be reassigned depending on scroll direction.
-     */
-    onCalcUpdate: () => void;
-    /**
-     * Called every animation frame.
-     * Intended to be overridden in subclasses.
-     */
+    onCalcUpdate(): void;
     onFrame(): void;
-    /**
-     * Called when wheel event is fired.
-     * Override to implement custom scroll interaction.
-     * @param e Wheel event.
-     */
     onWheel(e: any): void;
-    /**
-     * Called when native scroll event is fired.
-     * Override to track native scroll position.
-     * @param e Scroll event.
-     */
     onScroll(e: any): void;
+    onTouchStart(e: TouchEvent): void;
+    onTouchMove(e: TouchEvent): void;
+    onTouchEnd(e: TouchEvent): void;
     disableScrollEvents(): void;
     enableScrollEvents(): void;
-    /**
-     * Called when this controller becomes the active scroll engine.
-     * Ensures event bindings are attached only once.
-     */
     activate(): void;
-    /**
-     * Called when this controller is deactivated.
-     * Ensures event bindings are detached only once.
-     */
     deactivate(): void;
-    /**
-     * Allows controllers to clean up resources on global destroy.
-     */
     destroy(): void;
-    /**
-     * Updates scroll direction state, emits events, and toggles global classes.
-     * Intended for reuse by custom scroll adapters.
-     */
-    protected updateScrollDirection(newDirection: boolean): void;
+    protected updateScrollDirection(isDown: boolean): void;
     protected clearScrollingClasses(): void;
     protected triggerScrollRules(): void;
     addScrollMark(rule: ScrollMarkRule): void;
@@ -2699,11 +2662,31 @@ declare class ScrollController {
 interface StringDevtoolState {
     active: boolean;
 }
+interface StringDevtoolHotkey {
+    key: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+}
+interface StringDevtoolSubBadge {
+    id: string;
+    icon: string;
+    label: string;
+    /** Extra attribute used as a CSS selector hook (e.g. "data-string-grid-global-toggle"). */
+    selectorAttribute?: string;
+    /** Additional data-* attributes applied to the badge button. */
+    attributes?: Record<string, string | boolean | number | null | undefined>;
+    onClick: (anchorElement?: HTMLElement) => void;
+}
 interface StringDevtoolDefinition {
     id: string;
     label: string;
     icon: string;
     order?: number;
+    group?: number;
+    hotkey?: StringDevtoolHotkey;
+    subBadges?: StringDevtoolSubBadge[];
     getState: () => StringDevtoolState;
     setActive: (active: boolean) => void;
     subscribe?: (listener: (state: StringDevtoolState) => void) => () => void;
@@ -2744,6 +2727,16 @@ interface StringDevModuleDefinitionConfig {
     label: string;
     icon: string;
     order?: number;
+    group?: number;
+    hotkey?: StringDevtoolHotkey;
+}
+interface StringDevConnectsConfig {
+    /** If true, connects to every StringObject (overlay default). If false, only explicit matches below + dev-inspect fallback. */
+    global?: boolean;
+    /** Connect to objects whose string="…" token list includes any of these keys. */
+    keys?: string[];
+    /** Connect to objects whose DOM element has any of these attributes present. */
+    attributes?: string[];
 }
 interface StringDevOverlayConfig {
     /** Unique layer name, e.g. "devtools-progress" */
@@ -2764,6 +2757,8 @@ interface StringDevModuleConfig extends StringDevModuleDefinitionConfig {
     styles?: string | (() => string);
     /** Overlay layer configuration. Declare for any module that uses a viewport layer. */
     overlay?: StringDevOverlayConfig;
+    /** Declare which StringObjects this module connects to. Replaces htmlKey assignment in constructor. */
+    connects?: StringDevConnectsConfig;
 }
 declare class StringDevModule extends StringModule implements StringDevtoolProvider {
     /** Declare module metadata statically. Subclasses override this. */
@@ -2771,12 +2766,18 @@ declare class StringDevModule extends StringModule implements StringDevtoolProvi
     protected readonly overlayRegistry: StringDevOverlayRegistry;
     private readonly acquiredViewportLayers;
     private readonly devtoolListeners;
+    private hotkeyHandler;
     protected devtoolConfig: StringDevModuleDefinitionConfig | null;
     constructor(context: StringContext);
+    protected get respectSelfDisable(): boolean;
+    protected get connectsConfig(): StringDevConnectsConfig | undefined;
+    canConnect(object: StringObject): boolean;
     protected getStyleScopeId(stylesText: string): string;
     protected getStyles(): string | null;
     getDevtoolDefinition(): StringDevtoolDefinition | null;
+    protected getDevtoolSubBadges(): StringDevtoolSubBadge[];
     protected configureDevtool(config: StringDevModuleDefinitionConfig): void;
+    protected bindDevtoolHotkey(hotkey?: StringDevtoolHotkey): void;
     protected emitDevtoolState(active?: boolean): void;
     protected acquireViewportLayer(id: string, zIndex: number): StringDevViewportLayer;
     protected releaseViewportLayer(id: string): void;
@@ -2793,7 +2794,7 @@ declare function buildGridCSS(): string;
  * StringDevLayout — developer utility module for layout overlays.
  *
  * Usage:
- *   <div string="grid">...</div>
+ *   <div string="layout">...</div>
  *
  * No configuration attributes needed. All configuration happens
  * through the interactive HUD panel (hover top-right corner).
@@ -2806,6 +2807,7 @@ declare function buildGridCSS(): string;
 declare class StringDevLayout extends StringDevModule {
     private gridManager;
     private viewportLayer;
+    private overlayLayer;
     private overlays;
     private huds;
     private elementMap;
@@ -2814,15 +2816,29 @@ declare class StringDevLayout extends StringDevModule {
     private enabled;
     private needsMeasure;
     private hasPendingMutate;
+    private globalHost;
+    private globalOverlay;
+    private globalHUD;
+    private globalSubBadge;
     static devtool: {
         id: string;
         label: string;
         icon: string;
         order: number;
+        group: number;
+        hotkey: {
+            key: string;
+            shiftKey: boolean;
+        };
         styles: typeof buildGridCSS;
+        connects: {
+            global: boolean;
+            keys: string[];
+        };
     };
     constructor(context: StringContext);
     onInit(): void;
+    protected getDevtoolSubBadges(): StringDevtoolSubBadge[];
     onObjectConnected(object: StringObject): void;
     onObjectDisconnected(object: StringObject): void;
     onResize(): void;
@@ -2843,9 +2859,10 @@ declare class StringDevLayout extends StringDevModule {
     private handleMoveToEnd;
     private handleSelectLayout;
     private handleUpdateLayoutMinWidth;
-    private handlePreviewResponsiveLayout;
-    private handleCommitResponsiveLayout;
+    private handleAddLayout;
+    private handleRemoveLayout;
     private handleRenameInstance;
+    private handleRenamePanelTitle;
     private handleHUDOpen;
     private handleHUDClose;
     private handleLayoutPanelOpen;
@@ -2853,9 +2870,17 @@ declare class StringDevLayout extends StringDevModule {
     private handleExport;
     private handleImport;
     private renderElement;
+    private syncToResolved;
+    private syncSelectedLayoutToViewport;
     private refreshHUD;
-    private resolveActiveLayoutState;
-    private syncSelectedLayoutToResolved;
+    private ensureGlobalGrid;
+    private syncGlobalHostSize;
+    private renderGlobal;
+    private refreshGlobalHUD;
+    private toggleGlobalPanel;
+    private syncGlobalSubBadgeState;
+    private positionGlobalHudAtAnchor;
+    private destroyGlobalGrid;
     private destroyElement;
     private ensureTriggerLayer;
     private applyTriggerLayerState;
@@ -2877,7 +2902,14 @@ declare class StringDevLayout extends StringDevModule {
  * Each devtool module returns an array of these to describe its settings panel.
  */
 type StringDevUIFieldDescriptor = StringDevUIFieldNumber | StringDevUIFieldRange | StringDevUIFieldColor | StringDevUIFieldSelect | StringDevUIFieldToggle | StringDevUIFieldDivider;
-interface StringDevUIFieldNumber {
+interface StringDevUIFieldDisabledWhen {
+    readonly key: string;
+    readonly equals: string | number | boolean;
+}
+interface StringDevUIFieldBase {
+    readonly disabledWhen?: StringDevUIFieldDisabledWhen;
+}
+interface StringDevUIFieldNumber extends StringDevUIFieldBase {
     readonly type: "number";
     readonly key: string;
     readonly label: string;
@@ -2886,7 +2918,7 @@ interface StringDevUIFieldNumber {
     readonly max?: number;
     readonly step?: number;
 }
-interface StringDevUIFieldRange {
+interface StringDevUIFieldRange extends StringDevUIFieldBase {
     readonly type: "range";
     readonly key: string;
     readonly label: string;
@@ -2894,6 +2926,12 @@ interface StringDevUIFieldRange {
     readonly min: number;
     readonly max: number;
     readonly step?: number;
+    /** Multiplies the stored value for display/editing in the UI. */
+    readonly displayMultiplier?: number;
+    /** Optional UI step in display-space (e.g. 10 for 0..100 opacity UX). */
+    readonly displayStep?: number;
+    /** Optional display-only suffix rendered next to the numeric value. */
+    readonly suffix?: string;
     /** When provided, a compact unit dropdown is shown next to the value input. */
     readonly units?: ReadonlyArray<{
         value: string;
@@ -2902,13 +2940,13 @@ interface StringDevUIFieldRange {
     /** Default unit value (used when no persisted unit exists). */
     readonly defaultUnit?: string;
 }
-interface StringDevUIFieldColor {
+interface StringDevUIFieldColor extends StringDevUIFieldBase {
     readonly type: "color";
     readonly key: string;
     readonly label: string;
     readonly default: string;
 }
-interface StringDevUIFieldSelect {
+interface StringDevUIFieldSelect extends StringDevUIFieldBase {
     readonly type: "select";
     readonly key: string;
     readonly label: string;
@@ -2918,7 +2956,7 @@ interface StringDevUIFieldSelect {
         label: string;
     }>;
 }
-interface StringDevUIFieldToggle {
+interface StringDevUIFieldToggle extends StringDevUIFieldBase {
     readonly type: "toggle";
     readonly key: string;
     readonly label: string;
@@ -2998,8 +3036,94 @@ declare abstract class GridAdapter {
     protected createPath(d: string, stroke: string, opacity: number, strokeWidth?: number, fill?: string): SVGPathElement;
 }
 
+/**
+ * StringDevRulers — developer utility module for guide-line rulers.
+ *
+ * Usage:
+ *   st.use(StringDevRulers)
+ *   st.use(StringDevRulers, { triggers: [...], grid: { type: "columns", count: 12, ... } })
+ *
+ * Default trigger: Shift + R
+ *
+ * Settings:
+ *   triggers               — array of trigger descriptors (keyboard / element / event)
+ *   rulers-snap            — grid step in px (0 = off)
+ *   rulers-snap-elements   — snap to [string] element edges (default: true)
+ *   rulers-snap-threshold  — snap pull radius in px (default: 8)
+ *   rulers-snap-selector   — CSS selector for snap targets
+ *   grid                   — RulersLayoutGrid | RulersLayoutGrid[]
+ *
+ * Snap visual feedback:
+ *   amber → snapping to a DOM element edge / center
+ *   green → snapping to a layout-grid line
+ */
+declare class StringDevRulers extends StringDevModule {
+    private manager;
+    private overlay;
+    private visible;
+    private dockDisabled;
+    private currentModeId;
+    private readonly modeStore;
+    private readonly viewportLayer;
+    private _kbHandlers;
+    private _elHandlers;
+    private _evHandlers;
+    static devtool: {
+        id: string;
+        label: string;
+        icon: string;
+        order: number;
+        group: number;
+        hotkey: {
+            key: string;
+            shiftKey: boolean;
+        };
+        styles: string;
+        connects: {
+            global: boolean;
+            keys: string[];
+        };
+    };
+    constructor(context: StringContext);
+    onInit(): void;
+    onSettingsChange(): void;
+    onSubscribe(): void;
+    onUnsubscribe(): void;
+    onFrame(data: StringData): void;
+    onResize(): void;
+    destroy(): void;
+    toggle(): void;
+    show(): void;
+    hide(): void;
+    clear(): void;
+    isVisible(): boolean;
+    protected getDevtoolActiveState(): boolean;
+    protected setDevtoolActiveState(active: boolean): void;
+    protected getDevtoolSubBadges(): StringDevtoolSubBadge[];
+    private _bindTriggers;
+    private _unbindTriggers;
+    private _applyAction;
+    private setVisible;
+    private setDockActive;
+    private mountOverlay;
+    private cycleMode;
+    private switchMode;
+    private applyStyleSettings;
+    private clearStyleSettings;
+    /** Normalises the `grid` setting to RulersLayoutGrid[] (or undefined). */
+    private _resolveGrids;
+    private syncOverlayMetrics;
+    private pushScrollToOverlay;
+}
+
 type StringDevtoolsOverlayId = string;
+interface AnchorPoint {
+    docX: number;
+    docY: number;
+}
 
+type OverlayAxis = "y" | "x";
+type OverlayAnchor = "start" | "end";
 interface OverlayBaseMetrics {
     visible: boolean;
     contentX: number;
@@ -3010,6 +3134,17 @@ interface OverlayBaseMetrics {
     baseAnchorX: number;
     baseAnchorY: number;
     collisionOffset: number;
+    axis: OverlayAxis;
+    primarySize: number;
+    crossSize: number;
+    primaryContentOffset: number;
+    viewportPrimarySize: number;
+}
+interface OverlayObjectGeometry {
+    contentX: number;
+    contentY: number;
+    width: number;
+    height: number;
 }
 interface StringDevOverlayBadgeInit {
     targetId: string;
@@ -3023,20 +3158,29 @@ interface StringDevOverlayBadgeState {
     disabled?: boolean;
     title?: string;
     html?: string;
+    label?: string;
     attributes?: Record<string, string | boolean | number | null | undefined>;
 }
 declare abstract class StringDevOverlayModule<TEntry = unknown, TMeasurement = unknown> extends StringDevModule {
     private _viewportLayer?;
+    private _badgeLayer?;
+    private _hudLayer?;
     protected get viewportLayer(): StringDevViewportLayer;
+    protected get badgeLayer(): StringDevViewportLayer;
+    protected get hudLayer(): StringDevViewportLayer;
     protected readonly entries: Map<string, TEntry>;
     protected readonly measurements: Map<string, TMeasurement>;
     protected enabled: boolean;
     protected needsMeasure: boolean;
     protected hasPendingMutate: boolean;
+    private _rafId;
+    private _pendingSingleIds;
     private readonly onOverlayLayoutChangeBind;
     private get _overlayConfig();
     /** Override to provide the overlay ID for the anchor/collision system. */
     protected get overlayId(): StringDevtoolsOverlayId | null;
+    /** Override to declare how many badge slots this overlay occupies. */
+    protected get overlayBadgeCount(): number;
     /** Override to define your viewport layer name. Falls back to devtool.overlay.layerName. */
     protected get layerName(): string;
     /** Override to define your viewport layer z-index. Falls back to devtool.overlay.zIndex. */
@@ -3068,11 +3212,29 @@ declare abstract class StringDevOverlayModule<TEntry = unknown, TMeasurement = u
     onMutate(): void;
     onResize(): void;
     onDOMRebuild(): void;
+    /**
+     * Immediate synchronous full sync — use only when instant visual response
+     * is required (e.g. setEnabled). For everything else prefer scheduleSync().
+     */
     protected scheduleFullSync(): void;
+    /**
+     * Deferred full sync — batches multiple calls within the same animation
+     * frame into a single measure+flush pass. Use for resize, layout changes,
+     * object connected, and any other non-immediate triggers.
+     */
+    protected scheduleSync(): void;
+    /**
+     * Deferred single-entry sync — measures and flushes only the given entry.
+     * Multiple calls for different entries within the same frame are batched
+     * together into one styleTxn flush. Use for per-object events like
+     * object:inview or slider input where only one entry changes.
+     */
+    protected scheduleSingleSync(entry: TEntry): void;
     protected collectMeasurements(): void;
     protected flushMeasurements(): void;
     protected ensureLayer(): HTMLDivElement;
     protected applyEnabledState(): void;
+    private syncSlotRegistration;
     protected resolveOverlayTargetId(object: StringObject): string;
     protected resolveOverlayObjectDepth(element: HTMLElement): number;
     protected createOverlayBadge(init: StringDevOverlayBadgeInit): HTMLButtonElement;
@@ -3081,19 +3243,66 @@ declare abstract class StringDevOverlayModule<TEntry = unknown, TMeasurement = u
         visible: boolean;
         docX: number;
         docY: number;
+        translate?: string;
     } | undefined): void;
+    protected getOverlayTargetLabel(object: StringObject): string;
+    protected getViewportAnchorOffset(anchor: OverlayAnchor, metrics: OverlayBaseMetrics): number;
+    protected getOverlayAnchorAdjustment(_object: StringObject, _anchor: AnchorPoint, _metrics?: {
+        contentX: number;
+        contentY: number;
+        width: number;
+        height: number;
+    }): AnchorPoint;
+    protected resolveRulerPanelOffset(contentX: number, contentY: number): {
+        x: number;
+        y: number;
+    };
     protected computeBaseMetrics(entry: any): OverlayBaseMetrics;
-    private getHiddenMetrics;
+    protected getHiddenMetrics(): OverlayBaseMetrics;
     protected getObjectDocY(object: StringObject): number;
+    protected resolveOverlayObjectGeometry(object: StringObject, element?: HTMLElement): OverlayObjectGeometry;
     protected getViewportScrollLeft(): number;
     protected getViewportScrollTop(): number;
+    protected resolveLiveElementMetrics(element: HTMLElement, rect: DOMRect): {
+        docLeft?: number;
+        docTop?: number;
+        width: number;
+        height: number;
+    };
     destroy(): void;
 }
 
-interface StringDevBadgeMeasurement {
+type StringDevBadgeSlot = "top-left" | "top-right" | "bottom-right" | "bottom-left";
+interface StringDevBadgeSlotConfig {
+    gap?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+interface StringDevBadgeDescriptor {
+    id: string;
+    slot?: StringDevBadgeSlot;
+    group?: string;
+    selectorAttribute?: string;
+    depth?: number;
+    attributes?: Record<string, string | boolean | number | null | undefined>;
+    gap?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+interface StringDevManagedBadge {
+    id: string;
+    descriptor: StringDevBadgeDescriptor;
+    element: HTMLButtonElement;
+}
+interface StringDevBadgePositionMeasurement {
     visible: boolean;
     docX: number;
     docY: number;
+    translate?: string;
+}
+interface StringDevBadgeMeasurement {
+    visible: boolean;
+    badges: Record<string, StringDevBadgePositionMeasurement>;
 }
 interface StringDevBadgeEntry<TExtra = undefined> {
     object: StringObject;
@@ -3102,207 +3311,139 @@ interface StringDevBadgeEntry<TExtra = undefined> {
     depth: number;
     extra: TExtra;
     cleanup: Array<() => void>;
+    badges: Map<string, StringDevManagedBadge>;
+    groups: Map<string, HTMLDivElement>;
 }
 declare abstract class StringDevBadgeOverlayModule<TExtra = undefined, TMeasurement extends StringDevBadgeMeasurement = StringDevBadgeMeasurement> extends StringDevOverlayModule<StringDevBadgeEntry<TExtra>, TMeasurement> {
-    /** Override to define the data-attribute on the badge element. Falls back to devtool.overlay.badgeAttribute. */
     protected get badgeAttribute(): string;
     protected createOverlayEntry(object: StringObject): StringDevBadgeEntry<TExtra>;
     protected destroyOverlayEntry(entry: StringDevBadgeEntry<TExtra>): void;
-    protected measureEntry(_entry: StringDevBadgeEntry<TExtra>, metrics: OverlayBaseMetrics): TMeasurement;
+    protected measureEntry(entry: StringDevBadgeEntry<TExtra>, metrics: OverlayBaseMetrics): TMeasurement;
     protected applyMeasurement(entry: StringDevBadgeEntry<TExtra>, measurement: TMeasurement | undefined): void;
     protected onEnabledChange(_enabled: boolean): void;
     protected createBadgeExtra(_object: StringObject, _badge: HTMLButtonElement, _targetId: string, _depth: number): TExtra;
     protected destroyBadgeExtra(_entry: StringDevBadgeEntry<TExtra>): void;
     protected bindBadge(_entry: StringDevBadgeEntry<TExtra>): Array<() => void> | void;
     protected resolveBadgeDepth(object: StringObject): number;
+    protected getBadgeSlotConfig(): Partial<Record<StringDevBadgeSlot, StringDevBadgeSlotConfig>>;
+    protected getBadgeDescriptors(object: StringObject, targetId: string, depth: number): Array<StringDevBadgeDescriptor>;
     protected getInitialBadgeAttributes(_object: StringObject, _targetId: string, _depth: number): Record<string, string | boolean | number | null | undefined> | undefined;
     protected applyBadgeEnabledState(entry: StringDevBadgeEntry<TExtra>): void;
     protected renderBadge(entry: StringDevBadgeEntry<TExtra>): void;
     protected afterBadgeMeasurement(_entry: StringDevBadgeEntry<TExtra>, _measurement: TMeasurement | undefined): void;
-    protected abstract onBadgeClick(entry: StringDevBadgeEntry<TExtra>, event: MouseEvent): void;
-    protected abstract getBadgeState(entry: StringDevBadgeEntry<TExtra>): StringDevOverlayBadgeState;
-}
-
-interface InviewToggleExtra {
-    onInviewChange: () => void;
-}
-declare class StringDevInviewToggle extends StringDevBadgeOverlayModule<InviewToggleExtra> {
-    static devtool: {
-        id: string;
-        label: string;
-        icon: string;
-        order: number;
-        styles: string;
-        overlay: {
-            layerName: string;
-            zIndex: number;
-            layerAttribute: string;
-            overlayId: string;
-            badgeAttribute: string;
-            defaultEnabled: boolean;
-        };
-    };
-    canConnect(_object: StringObject): boolean;
-    protected createBadgeExtra(object: StringObject): InviewToggleExtra;
-    protected bindBadge(entry: StringDevBadgeEntry<InviewToggleExtra>): Array<() => void>;
-    protected onBadgeClick(entry: StringDevBadgeEntry<InviewToggleExtra>, _event: MouseEvent): void;
-    protected getBadgeState(entry: StringDevBadgeEntry<InviewToggleExtra>): StringDevOverlayBadgeState;
-}
-
-/**
- * StringDevRulers — developer utility module for guide-line rulers.
- *
- * Usage:
- *   st.use(StringDevRulers)
- *   st.use(StringDevRulers, { triggers: [...], grid: { type: "columns", count: 12, ... } })
- *
- * Default trigger: Shift + R
- *
- * Settings:
- *   triggers               — array of trigger descriptors (keyboard / element / event)
- *   rulers-snap            — grid step in px (0 = off)
- *   rulers-snap-elements   — snap to [string] element edges (default: true)
- *   rulers-snap-threshold  — snap pull radius in px (default: 8)
- *   rulers-snap-selector   — CSS selector for snap targets
- *   grid                   — RulersLayoutGrid | RulersLayoutGrid[]
- *
- * Snap visual feedback:
- *   amber → snapping to a DOM element edge / center
- *   green → snapping to a layout-grid line
- */
-declare class StringDevRulers extends StringDevModule {
-    private manager;
-    private overlay;
-    private visible;
-    private dockDisabled;
-    private currentModeId;
-    private readonly viewportLayer;
-    private _kbHandlers;
-    private _elHandlers;
-    private _evHandlers;
-    static devtool: {
-        id: string;
-        label: string;
-        icon: string;
-        order: number;
-        styles: string;
-    };
-    constructor(context: StringContext);
-    onInit(): void;
-    onSettingsChange(): void;
-    onSubscribe(): void;
-    onUnsubscribe(): void;
-    onFrame(data: StringData): void;
-    onResize(): void;
-    destroy(): void;
-    toggle(): void;
-    show(): void;
-    hide(): void;
-    isVisible(): boolean;
-    protected getDevtoolActiveState(): boolean;
-    protected setDevtoolActiveState(active: boolean): void;
-    private _bindTriggers;
-    private _unbindTriggers;
-    private _applyAction;
-    private setVisible;
-    private setDockActive;
-    private mountOverlay;
-    private cycleMode;
-    private switchMode;
-    private applyStyleSettings;
-    private clearStyleSettings;
-    /** Normalises the `grid` setting to RulersLayoutGrid[] (or undefined). */
-    private _resolveGrids;
-    private syncOverlayMetrics;
-}
-
-interface OffsetOverlayEntry {
-    object: StringObject;
-    root: HTMLDivElement;
-    box: HTMLDivElement;
-    topZone: HTMLDivElement;
-    bottomZone: HTMLDivElement;
-    topMarker: HTMLDivElement;
-    bottomMarker: HTMLDivElement;
-    topMarkerValue: HTMLSpanElement;
-    bottomMarkerValue: HTMLSpanElement;
-    badge: HTMLButtonElement;
-    badgeDepth: number;
-    onBadgeClick: (event: MouseEvent) => void;
-}
-interface OffsetOverlayMeasurement {
-    visible: boolean;
+    protected abstract onBadgeClick(entry: StringDevBadgeEntry<TExtra>, event: MouseEvent, badge: StringDevManagedBadge): void;
+    protected abstract getBadgeState(entry: StringDevBadgeEntry<TExtra>, badge?: StringDevManagedBadge): StringDevOverlayBadgeState;
+    private resolveBadgeSlotConfig;
+    private resolveBadgePosition;
+}
+
+interface InviewExtra {
+    outline: HTMLDivElement;
+    enterConnector: HTMLDivElement;
+    exitConnector: HTMLDivElement;
+    enterMarker: HTMLDivElement;
+    exitMarker: HTMLDivElement;
+    enterMarkerLabel: HTMLSpanElement;
+    exitMarkerLabel: HTMLSpanElement;
+}
+interface InviewMeasurement extends StringDevBadgeMeasurement {
     overlayVisible: boolean;
     badgeVisible: boolean;
+    markersVisible: boolean;
     inview: boolean;
-    boxDocX: number;
-    boxDocY: number;
-    width: number;
-    height: number;
-    borderRadius: string;
-    topZoneDocX: number;
-    topZoneDocY: number;
-    topZoneWidth: number;
-    topZoneHeight: number;
-    topZoneEmpty: boolean;
-    bottomZoneDocX: number;
-    bottomZoneDocY: number;
-    bottomZoneWidth: number;
-    bottomZoneHeight: number;
-    bottomZoneEmpty: boolean;
-    topMarkerDocX: number;
-    topMarkerDocY: number;
-    topMarkerValue: string;
-    bottomMarkerDocX: number;
-    bottomMarkerDocY: number;
-    bottomMarkerValue: string;
-    badgeDocX: number;
-    badgeDocY: number;
-}
-declare class StringDevOffsets extends StringDevOverlayModule<OffsetOverlayEntry, OffsetOverlayMeasurement> {
+    outlineDocX: number;
+    outlineDocY: number;
+    outlineWidth: number;
+    outlineHeight: number;
+    enterConnectorDocX: number;
+    enterConnectorDocY: number;
+    enterConnectorWidth: number;
+    enterConnectorHeight: number;
+    exitConnectorDocX: number;
+    exitConnectorDocY: number;
+    exitConnectorWidth: number;
+    exitConnectorHeight: number;
+    enterMarkerDocX: number;
+    enterMarkerDocY: number;
+    enterMarkerFlippedY: boolean;
+    exitMarkerDocX: number;
+    exitMarkerDocY: number;
+    exitMarkerFlippedY: boolean;
+}
+declare class StringDevInview extends StringDevBadgeOverlayModule<InviewExtra, InviewMeasurement> {
     static devtool: {
         id: string;
         label: string;
         icon: string;
         order: number;
+        group: number;
+        hotkey: {
+            key: string;
+            shiftKey: boolean;
+        };
         styles: string;
         overlay: {
             layerName: string;
             zIndex: number;
             layerAttribute: string;
             overlayId: string;
+            defaultEnabled: boolean;
+        };
+        connects: {
+            global: boolean;
         };
     };
+    protected get overlayBadgeCount(): number;
+    protected getDevtoolSubBadges(): StringDevtoolSubBadge[];
     private entryEnabled;
-    canConnect(_object: StringObject): boolean;
-    protected createOverlayEntry(object: StringObject): OffsetOverlayEntry;
-    protected destroyOverlayEntry(entry: OffsetOverlayEntry): void;
-    protected measureEntry(entry: OffsetOverlayEntry, metrics: OverlayBaseMetrics): OffsetOverlayMeasurement;
-    protected applyMeasurement(entry: OffsetOverlayEntry, measurement: OffsetOverlayMeasurement | undefined): void;
+    private markerSizeCache;
+    private readonly disabledStore;
+    private readonly markerStore;
+    private disabledTargetIds;
+    private markerOffsets;
+    private stableCoarseViewportWidth;
+    private stableCoarseViewportHeight;
+    protected getBadgeDescriptors(_object: StringObject, _targetId: string, _depth: number): Array<StringDevBadgeDescriptor>;
+    protected createBadgeExtra(object: StringObject, _badge: HTMLButtonElement, targetId: string, _depth: number): InviewExtra;
+    protected destroyBadgeExtra(entry: StringDevBadgeEntry<InviewExtra>): void;
+    protected bindBadge(entry: StringDevBadgeEntry<InviewExtra>): Array<() => void>;
+    protected measureEntry(entry: StringDevBadgeEntry<InviewExtra>, metrics: OverlayBaseMetrics): InviewMeasurement;
+    protected afterBadgeMeasurement(entry: StringDevBadgeEntry<InviewExtra>, measurement: InviewMeasurement | undefined): void;
+    protected onBadgeClick(entry: StringDevBadgeEntry<InviewExtra>, _event: MouseEvent, badge: StringDevManagedBadge): void;
+    protected getBadgeState(entry: StringDevBadgeEntry<InviewExtra>, badge?: StringDevManagedBadge): StringDevOverlayBadgeState;
     private hiddenMeasurement;
+    private getInviewBadgeState;
+    private toggleInview;
+    private isInviewBadgeActive;
     private isEntryEnabled;
     private setEntryEnabled;
-    private getViewportAnchorOffset;
+    private disableAllOffsets;
+    private bindMarkerDrag;
+    private getMarkerOffset;
+    private setMarkerOffset;
+    private syncMarkerContent;
+    private getViewportMarkerLabel;
+    private measureMarkerSize;
+    private resolveLiveStickyGeometry;
+    private clampMarkerPercentInViewport;
+    private clampMarkerPercentInClientViewport;
+    private syncCompactMode;
+    private syncCompactModeForExtra;
+    private setAttributeIfChanged;
+    private getStableViewportHeight;
 }
 
 interface ProgressEntry {
     object: StringObject;
-    chrome: HTMLDivElement;
+    hud: HTMLDivElement;
     badge: HTMLButtonElement;
-    panel: HTMLDivElement;
-    title: HTMLSpanElement;
-    slider: HTMLInputElement;
-    easedValue: HTMLSpanElement;
-    rawValue: HTMLSpanElement;
-    rangeValue: HTMLSpanElement;
     onBadgeClick: (event: MouseEvent) => void;
-    onSliderInput: () => void;
 }
 interface ProgressMeasurement {
     visible: boolean;
     docX: number;
     docY: number;
-    targetLabel: string;
+    targetId: string;
     progress: number;
     rawProgress: number;
     startPosition: number;
@@ -3316,6 +3457,11 @@ declare class StringDevProgress extends StringDevOverlayModule<ProgressEntry, Pr
         label: string;
         icon: string;
         order: number;
+        group: number;
+        hotkey: {
+            key: string;
+            shiftKey: boolean;
+        };
         styles: string;
         overlay: {
             layerName: string;
@@ -3323,10 +3469,24 @@ declare class StringDevProgress extends StringDevOverlayModule<ProgressEntry, Pr
             layerAttribute: string;
             overlayId: string;
         };
+        connects: {
+            keys: string[];
+        };
     };
-    private openEntryId;
-    private readonly onDocumentPointerDownBind;
-    constructor(context: any);
+    private openTargetLabel;
+    private panelRoot;
+    private panelTitle;
+    private panelSlider;
+    private panelValue;
+    private panelEasedValue;
+    private panelPlayForwardButton;
+    private panelPlayBackwardButton;
+    private autoplayRaf;
+    private autoplayDirection;
+    private autoplayProgress;
+    private readonly onPanelSliderInputBind;
+    private unbindOutsideClick;
+    constructor(context: StringContext);
     onInit(): void;
     destroy(): void;
     protected createOverlayEntry(object: StringObject): ProgressEntry;
@@ -3338,25 +3498,40 @@ declare class StringDevProgress extends StringDevOverlayModule<ProgressEntry, Pr
     private openPanel;
     private closePanel;
     private closeAllPanels;
-    private onDocumentPointerDown;
+    private collectEntryHuds;
+    private startAutoplay;
+    private stopAutoplay;
+    private syncPlayButtonState;
+    private getEntryRange;
     private resolveEntryRawProgress;
     private resolveEasedProgress;
     private setEntryProgressOverride;
     private clearEntryProgressOverride;
     private clearAllProgressOverrides;
     private applyObjectProgress;
+    private ensurePanel;
+    private onPanelSliderInput;
+    private renderPanel;
+    private findEntryByTargetLabel;
+}
+
+interface DevtoolsIconDef {
+    id: string;
+    viewBox: string;
+    content: string;
 }
 
+type DevtoolsIconSize = 12 | 16 | 20;
 declare class StringDevIconRegistry {
     private static instance;
-    private readonly icons;
+    private spriteRoot;
     private constructor();
     static getInstance(): StringDevIconRegistry;
-    register(id: string, svg: string): void;
-    get(id: string): string | null;
-    resolve(iconOrId: string): string;
+    register(icon: DevtoolsIconDef): void;
+    resolve(size: DevtoolsIconSize, name: string, ...modifiers: string[]): string;
+    private ensureSprite;
 }
-declare function resolveDevtoolsIcon(iconOrId: string): string;
+declare function resolveDevtoolsIcon(size: DevtoolsIconSize, name: string, ...modifiers: string[]): string;
 
 type StringDevStyleTokens = Record<string, string>;
 declare function buildDevtoolsThemeBlock(selectors: string | string[], overrides?: StringDevStyleTokens): string;
@@ -3497,6 +3672,7 @@ declare class DOMBatcher {
 declare class StringTune {
     private static readonly DEVTOOLS_ACCESS_URL;
     private static readonly DEVTOOLS_LOG_PREFIX;
+    private static readonly DEVTOOLS_ARTIFACT_SELECTORS;
     /** Bound handler for the scroll start event */
     private onScrollStartBind;
     /** Bound handler for the scroll stop event */
@@ -3642,6 +3818,7 @@ declare class StringTune {
      * @param settings Optional settings specific to this module.
      */
     use(objectClass: typeof StringModule, settings?: any): void;
+    private cleanupExistingDevtoolsArtifacts;
     private instantiateModule;
     private shouldDeferDevtoolModule;
     private validateDevtoolsAccess;
@@ -3798,4 +3975,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringDevIconRegistry, StringDevInviewToggle, StringDevLayout, StringDevModule, StringDevOffsets, StringDevOverlayRegistry, StringDevProgress, StringDevRulers, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };
+export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringDevIconRegistry, StringDevInview, StringDevLayout, StringDevModule, StringDevOverlayRegistry, StringDevProgress, StringDevRulers, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };