Targets And Portals

The most important StringCursor concept is that it manages two different surfaces.

targets: elements marked with string="cursor"
portals: floating elements marked with string-cursor="..."

These are related, but they are not the same thing.

Cursor Targets

A cursor target is a normal element inside the layout. It receives target-local cursor values and target-scoped events.

Typical target attributes:

string-cursor-target
string-cursor-class
string-alignment
string-cursor-enter
string-cursor-leave
string-cursor-leave-hold
string-lerp
string-cursor-vars

Important detail: target-local values are calculated relative to the hovered element, not relative to the viewport.

Cursor Portals

A cursor portal is a floating DOM node that follows the global pointer position.

Typical portal attributes:

string-cursor
string-cursor-lerp

The portal does not need to be inside the hovered target. It is just addressable by ID.

How Linking Works

Targets link to portals through string-cursor-target.

Examples:

HTML

<div string-cursor="default" class="cursor-portal"></div>
<div string-cursor="media" class="cursor-portal"></div>

<button string="cursor" string-cursor-target="default">Open</button>
<article string="cursor" string-cursor-target="media">Project</article>
<section string="cursor" string-cursor-target="default|media">Shared control</section>

Rules:

empty target config falls back to default
IDs can be split with , or |
* targets every registered portal
if nothing resolves, the runtime falls back to the default portal or the first available portal bucket

Portal Classes

While a target is hovered, the runtime can apply the class from string-cursor-class to the matched portal elements.

That gives you a clean split:

target owns semantic hover intent
portal owns floating cursor visuals

Hover Visibility

Portals do not show themselves by default. The runtime toggles -show while at least one linked target is hovered.

That means a portal element usually needs CSS for both states:

CSS

.cursor-portal {
  opacity: 0;
}

.cursor-portal.-show {
  opacity: 1;
}