@fiddle-digital/string-tune 1.1.53 → 1.1.55

package/dist/index.d.ts

@@ -407,6 +407,22 @@ declare class EventManager {
     clearAll(): void;
 }
 
+type StringTokenModeSpec = {
+    kind: "default";
+    values: [];
+} | {
+    kind: "all";
+    values: [];
+} | {
+    kind: "include";
+    values: ScrollMode[];
+};
+interface StringToken {
+    raw: string;
+    key: string;
+    modeSpec: StringTokenModeSpec;
+}
+
 type MirrorEasingFn = (value: number) => number;
 /**
  * Lightweight wrapper that mirrors a primary StringObject while keeping
@@ -448,6 +464,7 @@ declare class StringObject {
      * Space-separated list of all attribute keys associated with this object.
      */
     keys: string[];
+    tokens: StringToken[];
     /**
      * Mirror objects linked via `string-copy-from`.
      */
@@ -458,28 +475,6 @@ declare class StringObject {
     private properties;
     private eventNameCache;
     private eventNameSuffixCache;
-    /**
-     * Direct properties for extremely hot, per-frame accessed metrics
-     * to avoid going through the Map and incurring overhead.
-     */
-    progress: number;
-    progressRaw: number;
-    startPosition: number;
-    differencePosition: number;
-    transformValue: {
-        transform: string;
-    } | null;
-    eventProgressName: string | null;
-    lerp: number;
-    glide: number;
-    isMagneting: boolean;
-    magneticX: number;
-    magneticY: number;
-    magneticTargetX: number;
-    magneticTargetY: number;
-    eventLerpName: string | null;
-    eventGlideName: string | null;
-    eventMagneticName: string | null;
     /**
      * Modules currently connected to this object.
      */
@@ -524,6 +519,9 @@ declare class StringObject {
      * modules it is associated with.
      */
     remove(): void;
+    setInviewAutoBlocked(blocked: boolean): void;
+    isInviewAutoBlocked(): boolean;
+    syncInviewClass(): void;
     /**
      * Shows the object, applies visual class and notifies connected modules.
      */
@@ -537,6 +535,10 @@ declare class StringObject {
      * @param module - The module to connect
      */
     connect(module: IStringModule): boolean;
+    disconnect(module: IStringModule): boolean;
+    isConnectedTo(module: IStringModule): boolean;
+    setTokens(tokens: StringToken[]): void;
+    getToken(key: string): StringToken | null;
     addMirror(mirror: StringMirrorObject): void;
     removeMirror(id: string): void;
     get mirrorObjects(): StringMirrorObject[];
@@ -1262,23 +1264,28 @@ declare class StringModule implements IStringModule {
      * This map is used to manage and track `StringObject` instances on a page.
      */
     protected objectMapOnPage: Map<string, StringObject>;
+    protected allObjectMapOnPage: Map<string, StringObject>;
     /**
      * A protected array that holds the collection of `StringObject` instances
      * currently present on the page.
      */
     protected objectsOnPage: StringObject[];
+    protected allObjectsOnPage: StringObject[];
     /**
      * A map of all entered objects by their unique ID.
      */
     protected objectMap: Map<string, StringObject>;
+    protected allObjectMap: Map<string, StringObject>;
     /**
      * A flat array of all connected objects.
      */
     protected objects: StringObject[];
+    protected allObjects: StringObject[];
     /**
      * The HTML attribute key that identifies objects this module is responsible for.
      */
     protected htmlKey: string;
+    protected defaultModeScope: "all" | ScrollMode[];
     /**
      * Module type ID used internally to categorize module behavior.
      */
@@ -1288,6 +1295,7 @@ declare class StringModule implements IStringModule {
      * Type 1 = core module, type 2 = UI module.
      */
     get type(): number;
+    get key(): string;
     /**
      * Tools container providing utilities for attribute parsing, unit conversion, etc.
      * Acts as a dependency injection hub for core IStringTool implementations.
@@ -1341,6 +1349,9 @@ declare class StringModule implements IStringModule {
      * 6. Sets the processed attributes as properties on the `StringObject` instance.
      */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    protected cacheLayoutSnapshot(object: StringObject, element: HTMLElement): void;
+    private getOffsetSize;
+    private getOffsetChainPosition;
     /**
      * Calculates object-specific positions or metrics based on the current layout or scroll state.
      * This method is intended to be overridden in subclasses if the module needs to precompute
@@ -1373,6 +1384,9 @@ declare class StringModule implements IStringModule {
      * @returns `true` if the module can connect, `false` otherwise.
      */
     canConnect(object: StringObject): boolean;
+    protected isTokenEnabledInCurrentMode(token: StringToken): boolean;
+    protected isObjectEnabledInCurrentMode(object: StringObject): boolean;
+    disconnectObject(object: StringObject): void;
     /**
      * Registers the module on a given object, adds the object to internal list,
      * and triggers connection logic.
@@ -1449,6 +1463,10 @@ declare class StringModule implements IStringModule {
      * Returns a cached per-object event name to avoid building strings in hot paths.
      */
     protected getObjectEventName(object: StringObject, prefix: string, suffix?: string): string;
+    protected clearManagedStyles(object: StringObject): void;
+    protected onObjectModeActivated(object: StringObject): void;
+    protected onObjectModeDeactivated(object: StringObject): void;
+    protected rebuildActiveObjectsForCurrentMode(): void;
     /**
      * Cleans up internal state and detaches the module from the system.
      */
@@ -1566,6 +1584,8 @@ declare class ObjectManager {
     add(el: HTMLElement): void;
     setDOMBatcherEnabled(enabled: boolean): void;
     setIntersectionObserverEnabled(enabled: boolean): void;
+    attachModule(module: StringModule): void;
+    refreshModuleConnectionsForCurrentMode(): void;
     invalidateInviewIndex(): void;
     refreshLayoutForRoot(root: HTMLElement): void;
     /**
@@ -1636,6 +1656,8 @@ declare class ObjectManager {
     private rebuildInviewIndex;
     private upperBound;
     private splitPipeAndTrim;
+    private parseStringTokens;
+    private splitTopLevelPipe;
     destroy(): void;
 }
 
@@ -1884,6 +1906,7 @@ declare class StringAnchor extends StringModule {
  * to create a smooth scrolling effect for objects.
  */
 declare class StringGlide extends StringModule {
+    protected defaultModeScope: string[];
     private previousLerp;
     private displacement;
     private acceleration;
@@ -1896,9 +1919,8 @@ declare class StringGlide extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     private setupItem;
-    private onUpdateDesktopEvent;
-    private onUpdateMobileEvent;
-    private onUpdateEvent;
+    private updateTransforms;
+    private resetObjectStyles;
     private calcExpanderFactor;
     onStart(): void;
     onResize(): void;
@@ -1906,7 +1928,9 @@ declare class StringGlide extends StringModule {
     onScrollStart(): void;
     onScrollStop(): void;
     onFrame(data: StringData): void;
+    protected onObjectModeDeactivated(object: StringObject): void;
     onMutate(): void;
+    private applyPendingGlideStylesForObject;
     private applyPendingGlideStyles;
     private flushPendingGlideStyles;
 }
@@ -1917,6 +1941,7 @@ declare class StringGlide extends StringModule {
  */
 declare class StringLerp extends StringModule {
     private hasInitializedCSS;
+    protected defaultModeScope: string[];
     constructor(context: StringContext);
     /**
      * Initialize lerp value when object connects.
@@ -1960,6 +1985,7 @@ declare class StringProgress extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     private sanitizeRawProgress;
+    private resolveRawProgress;
     private applyRawProgress;
     private recomputeProgress;
     private ensureBatchCapacity;
@@ -1979,6 +2005,7 @@ declare class StringProgress extends StringModule {
  * necessary transformations based on scroll progress and viewport size.
  */
 declare class StringParallax extends StringProgress {
+    protected defaultModeScope: string[];
     private updateScheduledTransform;
     private calculateParallaxForObject;
     constructor(context: StringContext);
@@ -1988,11 +2015,9 @@ declare class StringParallax extends StringProgress {
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
-    onResize(): void;
     onScrollMeasure(data: StringData): void;
     onMutate(): void;
-    private calculateDesktopParallax;
-    private calculateMobileParallax;
+    private calculateParallax;
 }
 
 declare class StringScrollbar extends StringModule {
@@ -2671,6 +2696,672 @@ declare class ScrollController {
     scrollTo(position: number, immediate?: boolean): void;
 }
 
+interface StringDevtoolState {
+    active: boolean;
+}
+interface StringDevtoolDefinition {
+    id: string;
+    label: string;
+    icon: string;
+    order?: number;
+    getState: () => StringDevtoolState;
+    setActive: (active: boolean) => void;
+    subscribe?: (listener: (state: StringDevtoolState) => void) => () => void;
+}
+interface StringDevtoolProvider {
+    getDevtoolDefinition(): StringDevtoolDefinition | null;
+}
+
+declare class StringDevViewportLayer {
+    private readonly id;
+    private readonly zIndex;
+    private screenRoot;
+    private world;
+    private screen;
+    private worldHost;
+    private hostPositionWasPatched;
+    private hostPositionInlineValue;
+    constructor(id: string, zIndex: number);
+    ensure(host?: HTMLElement | null): HTMLDivElement;
+    getElement(): HTMLDivElement | null;
+    getWorldElement(host?: HTMLElement | null): HTMLDivElement;
+    getScreenElement(): HTMLDivElement;
+    destroy(): void;
+    private attachWorldToHost;
+    private restoreHostPosition;
+}
+
+declare class StringDevOverlayRegistry {
+    private static instance;
+    private readonly layers;
+    static getInstance(): StringDevOverlayRegistry;
+    acquire(id: string, zIndex: number): StringDevViewportLayer;
+    release(id: string): void;
+}
+
+interface StringDevModuleDefinitionConfig {
+    id: string;
+    label: string;
+    icon: string;
+    order?: number;
+}
+interface StringDevOverlayConfig {
+    /** Unique layer name, e.g. "devtools-progress" */
+    layerName: string;
+    /** Z-index for the viewport layer */
+    zIndex: number;
+    /** Data-attribute added to the layer root, e.g. "data-string-progress-layer" */
+    layerAttribute?: string;
+    /** Overlay ID used for the anchor/collision system. Omit if not needed. */
+    overlayId?: string;
+    /** Whether the overlay starts enabled before dock preferences apply. Default: false */
+    defaultEnabled?: boolean;
+    /** For badge overlay modules: data-attribute placed on each badge element */
+    badgeAttribute?: string;
+}
+interface StringDevModuleConfig extends StringDevModuleDefinitionConfig {
+    /** Declare CSS styles to inject once. Can be a string or a lazy getter. */
+    styles?: string | (() => string);
+    /** Overlay layer configuration. Declare for any module that uses a viewport layer. */
+    overlay?: StringDevOverlayConfig;
+}
+declare class StringDevModule extends StringModule implements StringDevtoolProvider {
+    /** Declare module metadata statically. Subclasses override this. */
+    static devtool: StringDevModuleConfig | null;
+    protected readonly overlayRegistry: StringDevOverlayRegistry;
+    private readonly acquiredViewportLayers;
+    private readonly devtoolListeners;
+    protected devtoolConfig: StringDevModuleDefinitionConfig | null;
+    constructor(context: StringContext);
+    protected getStyleScopeId(stylesText: string): string;
+    protected getStyles(): string | null;
+    getDevtoolDefinition(): StringDevtoolDefinition | null;
+    protected configureDevtool(config: StringDevModuleDefinitionConfig): void;
+    protected emitDevtoolState(active?: boolean): void;
+    protected acquireViewportLayer(id: string, zIndex: number): StringDevViewportLayer;
+    protected releaseViewportLayer(id: string): void;
+    protected ensureStyle(styleId: string, cssText: string): HTMLStyleElement;
+    protected getWorldHost(): HTMLElement;
+    protected getDevtoolActiveState(): boolean;
+    protected setDevtoolActiveState(_active: boolean): void;
+    destroy(): void;
+}
+
+declare function buildGridCSS(): string;
+
+/**
+ * StringDevLayout — developer utility module for layout overlays.
+ *
+ * Usage:
+ *   <div string="grid">...</div>
+ *
+ * No configuration attributes needed. All configuration happens
+ * through the interactive HUD panel (hover top-right corner).
+ *
+ * Supports multiple grid types via the adapter pattern:
+ * - Columns, Rows, Center
+ * - Rule of Thirds, Phi Grid, Golden Rectangle, Harmonic Armature
+ * - Extensible via `st.use(StringDevLayout, { adapters: [MyAdapter] })`
+ */
+declare class StringDevLayout extends StringDevModule {
+    private gridManager;
+    private viewportLayer;
+    private overlays;
+    private huds;
+    private elementMap;
+    private triggerEntries;
+    private triggerMeasurements;
+    private enabled;
+    private needsMeasure;
+    private hasPendingMutate;
+    static devtool: {
+        id: string;
+        label: string;
+        icon: string;
+        order: number;
+        styles: typeof buildGridCSS;
+    };
+    constructor(context: StringContext);
+    onInit(): void;
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    onResize(): void;
+    onScroll(): void;
+    onScrollMeasure(): void;
+    onMutate(): void;
+    onDOMRebuild(): void;
+    destroy(): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    protected getDevtoolActiveState(): boolean;
+    protected setDevtoolActiveState(active: boolean): void;
+    private handleAdd;
+    private handleRemove;
+    private handleToggle;
+    private handleSettingChange;
+    private handleReorder;
+    private handleMoveToEnd;
+    private handleSelectLayout;
+    private handleUpdateLayoutMinWidth;
+    private handlePreviewResponsiveLayout;
+    private handleCommitResponsiveLayout;
+    private handleRenameInstance;
+    private handleHUDOpen;
+    private handleHUDClose;
+    private handleLayoutPanelOpen;
+    private handleLayoutPanelClose;
+    private handleExport;
+    private handleImport;
+    private renderElement;
+    private refreshHUD;
+    private resolveActiveLayoutState;
+    private syncSelectedLayoutToResolved;
+    private destroyElement;
+    private ensureTriggerLayer;
+    private applyTriggerLayerState;
+    private scheduleTriggerSync;
+    private collectTriggerMeasurements;
+    private measureTrigger;
+    private applyTriggerMeasurement;
+    protected getWorldHost(): HTMLElement;
+    private getObjectDocY;
+    private getViewportScrollLeft;
+    private getViewportScrollTop;
+    private resolveTriggerStackOffset;
+    private registerBuiltInAdapters;
+    private registerExternalAdapters;
+}
+
+/**
+ * Discriminated union of all UI field descriptors.
+ * Each devtool module returns an array of these to describe its settings panel.
+ */
+type StringDevUIFieldDescriptor = StringDevUIFieldNumber | StringDevUIFieldRange | StringDevUIFieldColor | StringDevUIFieldSelect | StringDevUIFieldToggle | StringDevUIFieldDivider;
+interface StringDevUIFieldNumber {
+    readonly type: "number";
+    readonly key: string;
+    readonly label: string;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+interface StringDevUIFieldRange {
+    readonly type: "range";
+    readonly key: string;
+    readonly label: string;
+    readonly default: number;
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+    /** When provided, a compact unit dropdown is shown next to the value input. */
+    readonly units?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    /** Default unit value (used when no persisted unit exists). */
+    readonly defaultUnit?: string;
+}
+interface StringDevUIFieldColor {
+    readonly type: "color";
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+}
+interface StringDevUIFieldSelect {
+    readonly type: "select";
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+    readonly options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+interface StringDevUIFieldToggle {
+    readonly type: "toggle";
+    readonly key: string;
+    readonly label: string;
+    readonly default: boolean;
+}
+interface StringDevUIFieldDivider {
+    readonly type: "divider";
+    readonly label?: string;
+}
+
+/**
+ * Abstract base class for all grid adapters.
+ *
+ * Each adapter is a self-contained unit that:
+ * - Declares its own default settings
+ * - Describes its UI schema for the settings panel
+ * - Renders itself into an SVG overlay
+ *
+ * To create a new grid type, extend this class and implement
+ * all abstract members. The system handles everything else.
+ */
+declare abstract class GridAdapter {
+    /** Unique type key used for serialization and registry lookup */
+    abstract readonly type: string;
+    /** Human-readable label shown in the HUD menu */
+    abstract readonly label: string;
+    /** SVG icon string (inline SVG markup) */
+    abstract readonly icon: string;
+    /**
+     * Returns the default settings for this adapter.
+     * These are used when a new grid instance is created.
+     */
+    abstract getDefaults(): Record<string, any>;
+    /**
+     * Returns the UI field descriptors that GridUIBuilder
+     * uses to construct the settings panel.
+     */
+    abstract getUISchema(): StringDevUIFieldDescriptor[];
+    /**
+     * Renders the grid into the given SVG element.
+     *
+     * @param svg    The SVG overlay element (same size as target)
+     * @param width  Element width in px
+     * @param height Element height in px
+     * @param settings  Current settings for this instance
+     */
+    abstract render(svg: SVGSVGElement, width: number, height: number, settings: Record<string, any>): void;
+    /**
+     * Removes all elements previously rendered by this adapter.
+     * Default implementation clears the adapter's group element.
+     */
+    clear(svg: SVGSVGElement, instanceId: string): void;
+    /**
+     * Creates or retrieves a <g> group element scoped to a grid instance.
+     * All rendering should happen inside this group for clean cleanup.
+     */
+    protected getGroup(svg: SVGSVGElement, instanceId: string): SVGGElement;
+    /**
+     * Helper: creates an SVG line element.
+     */
+    protected createLine(x1: number, y1: number, x2: number, y2: number, color: string, opacity: number, strokeWidth?: number): SVGLineElement;
+    /**
+     * Helper: creates an SVG rect element.
+     */
+    protected createRect(x: number, y: number, width: number, height: number, fill: string, opacity: number): SVGRectElement;
+    /**
+     * Converts a value from the given unit to pixels.
+     *
+     * @param value     Raw numeric value
+     * @param unit      "px" | "%" | "vw" | "vh" | "em" | "rem"
+     * @param dimension Reference dimension (element width or height) for "%" mode
+     */
+    protected resolveUnit(value: number, unit: string, dimension: number, referenceElement?: Element | null): number;
+    /**
+     * Helper: creates an SVG path element.
+     */
+    protected createPath(d: string, stroke: string, opacity: number, strokeWidth?: number, fill?: string): SVGPathElement;
+}
+
+type StringDevtoolsOverlayId = string;
+
+interface OverlayBaseMetrics {
+    visible: boolean;
+    contentX: number;
+    contentY: number;
+    width: number;
+    height: number;
+    isOffscreen: boolean;
+    baseAnchorX: number;
+    baseAnchorY: number;
+    collisionOffset: number;
+}
+interface StringDevOverlayBadgeInit {
+    targetId: string;
+    selectorAttribute?: string;
+    depth?: number;
+    attributes?: Record<string, string | boolean | number | null | undefined>;
+}
+interface StringDevOverlayBadgeState {
+    visible?: boolean;
+    active?: boolean;
+    disabled?: boolean;
+    title?: string;
+    html?: string;
+    attributes?: Record<string, string | boolean | number | null | undefined>;
+}
+declare abstract class StringDevOverlayModule<TEntry = unknown, TMeasurement = unknown> extends StringDevModule {
+    private _viewportLayer?;
+    protected get viewportLayer(): StringDevViewportLayer;
+    protected readonly entries: Map<string, TEntry>;
+    protected readonly measurements: Map<string, TMeasurement>;
+    protected enabled: boolean;
+    protected needsMeasure: boolean;
+    protected hasPendingMutate: boolean;
+    private readonly onOverlayLayoutChangeBind;
+    private get _overlayConfig();
+    /** Override to provide the overlay ID for the anchor/collision system. */
+    protected get overlayId(): StringDevtoolsOverlayId | null;
+    /** 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. */
+    protected get layerZIndex(): number;
+    /** Override to define the data-attribute added to the layer root. Falls back to devtool.overlay.layerAttribute. */
+    protected get layerAttribute(): string;
+    /** Override when an overlay module should start enabled before dock preferences apply. Falls back to devtool.overlay.defaultEnabled. */
+    protected get defaultEnabled(): boolean;
+    constructor(context: StringContext);
+    onInit(): void;
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    protected getDevtoolActiveState(): boolean;
+    protected setDevtoolActiveState(active: boolean): void;
+    /** Create DOM and return state for the given element */
+    protected abstract createOverlayEntry(object: StringObject): TEntry | null;
+    /** Clean up DOM and listeners for the given element */
+    protected abstract destroyOverlayEntry(entry: TEntry): void;
+    /** Produce a custom measurement state utilizing the provided base metrics */
+    protected abstract measureEntry(entry: TEntry, baseMetrics: OverlayBaseMetrics): TMeasurement;
+    /** Render DOM efficiently utilizing `styleTxn` */
+    protected abstract applyMeasurement(entry: TEntry, measurement: TMeasurement | undefined): void;
+    /** Called when `setEnabled` state flips, allowing subclasses to show/hide specific entries */
+    protected onEnabledChange(_enabled: boolean): void;
+    onScroll(): void;
+    onScrollMeasure(): void;
+    onMutate(): void;
+    onResize(): void;
+    onDOMRebuild(): void;
+    protected scheduleFullSync(): void;
+    protected collectMeasurements(): void;
+    protected flushMeasurements(): void;
+    protected ensureLayer(): HTMLDivElement;
+    protected applyEnabledState(): void;
+    protected resolveOverlayTargetId(object: StringObject): string;
+    protected resolveOverlayObjectDepth(element: HTMLElement): number;
+    protected createOverlayBadge(init: StringDevOverlayBadgeInit): HTMLButtonElement;
+    protected applyOverlayBadgeState(badge: HTMLElement, state: StringDevOverlayBadgeState): void;
+    protected applyOverlayBadgePosition(badge: HTMLElement, measurement: {
+        visible: boolean;
+        docX: number;
+        docY: number;
+    } | undefined): void;
+    protected computeBaseMetrics(entry: any): OverlayBaseMetrics;
+    private getHiddenMetrics;
+    protected getObjectDocY(object: StringObject): number;
+    protected getViewportScrollLeft(): number;
+    protected getViewportScrollTop(): number;
+    destroy(): void;
+}
+
+interface StringDevBadgeMeasurement {
+    visible: boolean;
+    docX: number;
+    docY: number;
+}
+interface StringDevBadgeEntry<TExtra = undefined> {
+    object: StringObject;
+    targetId: string;
+    badge: HTMLButtonElement;
+    depth: number;
+    extra: TExtra;
+    cleanup: Array<() => void>;
+}
+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 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 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;
+    overlayVisible: boolean;
+    badgeVisible: 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> {
+    static devtool: {
+        id: string;
+        label: string;
+        icon: string;
+        order: number;
+        styles: string;
+        overlay: {
+            layerName: string;
+            zIndex: number;
+            layerAttribute: string;
+            overlayId: string;
+        };
+    };
+    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 hiddenMeasurement;
+    private isEntryEnabled;
+    private setEntryEnabled;
+    private getViewportAnchorOffset;
+}
+
+interface ProgressEntry {
+    object: StringObject;
+    chrome: 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;
+    progress: number;
+    rawProgress: number;
+    startPosition: number;
+    endPosition: number;
+    currentScroll: number;
+    key: string;
+}
+declare class StringDevProgress extends StringDevOverlayModule<ProgressEntry, ProgressMeasurement> {
+    static devtool: {
+        id: string;
+        label: string;
+        icon: string;
+        order: number;
+        styles: string;
+        overlay: {
+            layerName: string;
+            zIndex: number;
+            layerAttribute: string;
+            overlayId: string;
+        };
+    };
+    private openEntryId;
+    private readonly onDocumentPointerDownBind;
+    constructor(context: any);
+    onInit(): void;
+    destroy(): void;
+    protected createOverlayEntry(object: StringObject): ProgressEntry;
+    protected destroyOverlayEntry(entry: ProgressEntry): void;
+    protected measureEntry(entry: ProgressEntry, metrics: OverlayBaseMetrics): ProgressMeasurement;
+    protected applyMeasurement(entry: ProgressEntry, measurement: ProgressMeasurement | undefined): void;
+    protected onEnabledChange(enabled: boolean): void;
+    private applyEntryEnabledState;
+    private openPanel;
+    private closePanel;
+    private closeAllPanels;
+    private onDocumentPointerDown;
+    private resolveEntryRawProgress;
+    private resolveEasedProgress;
+    private setEntryProgressOverride;
+    private clearEntryProgressOverride;
+    private clearAllProgressOverrides;
+    private applyObjectProgress;
+}
+
+declare class StringDevIconRegistry {
+    private static instance;
+    private readonly icons;
+    private constructor();
+    static getInstance(): StringDevIconRegistry;
+    register(id: string, svg: string): void;
+    get(id: string): string | null;
+    resolve(iconOrId: string): string;
+}
+declare function resolveDevtoolsIcon(iconOrId: string): string;
+
+type StringDevStyleTokens = Record<string, string>;
+declare function buildDevtoolsThemeBlock(selectors: string | string[], overrides?: StringDevStyleTokens): string;
+declare function ensureStringDevtoolsSharedStyles(): HTMLStyleElement | null;
+
 /**
  * What the trigger does when activated.
  * Defaults to "toggle" when not specified.
@@ -2804,12 +3495,16 @@ declare class DOMBatcher {
 }
 
 declare class StringTune {
+    private static readonly DEVTOOLS_ACCESS_URL;
+    private static readonly DEVTOOLS_LOG_PREFIX;
     /** Bound handler for the scroll start event */
     private onScrollStartBind;
     /** Bound handler for the scroll stop event */
     private onScrollStopBind;
     /** Bound handler for the scroll direction change event */
     private onDirectionChangeBind;
+    /** Bound handler for scroll mode/config changes */
+    private onScrollConfigChangeBind;
     /** Bound wheel event handler */
     private onWheelBind;
     /** Bound scroll event handler */
@@ -2860,7 +3555,16 @@ declare class StringTune {
     private centers;
     /** Tracks hover states of string objects. */
     private hoverManager;
+    private devtools;
+    private devtoolsFpsLastSampleTime;
+    private devtoolsFpsFrameCount;
     private observerContainerResize;
+    private devtoolsAccessToken;
+    private devtoolsAccessState;
+    private devtoolsAccessRequestId;
+    private pendingDevtoolUses;
+    private hasStarted;
+    private devtoolsAccessLastMessage;
     canRebuild: boolean;
     /**
      * Sets the scroll position manually.
@@ -2870,6 +3574,7 @@ declare class StringTune {
      * @param value The new scroll position in pixels.
      */
     set scrollPosition(value: number);
+    set accessDevtoolToken(value: string);
     /**
      * Configures the container element(s) used for scroll tracking.
      * Accepts either the `Window` object or an `HTMLElement`.
@@ -2937,6 +3642,11 @@ declare class StringTune {
      * @param settings Optional settings specific to this module.
      */
     use(objectClass: typeof StringModule, settings?: any): void;
+    private instantiateModule;
+    private shouldDeferDevtoolModule;
+    private validateDevtoolsAccess;
+    private logDevtoolsAccess;
+    private resolveDevtoolsAccessResponse;
     /**
      * Registers a new scroll mode (provider) to the system.
      * Allows integrating custom scroll implementations (e.g. Lenis, Locomotive).
@@ -3040,6 +3750,8 @@ declare class StringTune {
      * Triggers module scroll stop lifecycle hook.
      */
     private onDirectionChange;
+    private onScrollConfigChange;
+    private syncDebugScrollState;
     /**
      * Called when global or module settings are updated.
      * Notifies all managers and modules to re-read new settings.
@@ -3057,6 +3769,7 @@ declare class StringTune {
      * Triggers scroll engine, modules, and global `update` event.
      */
     private onUpdateEvent;
+    private updateDevtoolsFPS;
     /**
      * Handles resize events from scroll container or window.
      * Ignores height-only changes on mobile to prevent layout jumps.
@@ -3064,11 +3777,25 @@ declare class StringTune {
      */
     onResize(force?: boolean): void;
     invalidateCenter(id: string): void;
-    scrollTo(value: number | {
+    scrollTo(position: number): void;
+    scrollTo(selector: string): void;
+    scrollTo(element: HTMLElement): void;
+    scrollTo(options: {
         position: number;
         immediate?: boolean;
+        offset?: number;
+    } | {
+        selector: string;
+        immediate?: boolean;
+        offset?: number;
+    } | {
+        element: HTMLElement;
+        immediate?: boolean;
+        offset?: number;
     }): void;
+    private resolveScrollToValue;
+    private resolveElementScrollPosition;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, 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, StringTune as default, frameDOM, styleTxn };
+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 };