JS interop — IJSRuntime, typed APIs & refs

Calling JS from C#, the typed browser-API layer, element refs, and wrapping a third-party JS library. The browser-side half is TypeScript — a .js sibling is RASK055.

‹ Back to JavaScript interop

Calling JS from C# (IJSRuntime)

Your component's own scoped .ts needs none of this — its exports are typed private methods (await Width(_box)), see Calling your script from C#. IJSRuntime is for everything else: a browser API, a library's global, another component's script.

Inject IJSRuntime through the constructor (not a property — a non-nullable settable property would become a required chain step) and dispatch from a lifecycle hook or event handler:

public sealed partial class CodeSample : Component
{
    private readonly IJSRuntime _js;
    public CodeSample(IJSRuntime js) => _js = js;

    protected override async Task OnRendered() =>
        await _js.InvokeVoidAsync("hljs.highlightAll");
}

Nothing (no el) is passed automatically — pass what the function needs. For a return value use InvokeAsync<T>. On WASM a non-primitive T must be rooted for the trimmer (DAM annotation or a JsonSerializerContext).

A sessionStorage round-trip through the unified IJSRuntime — set, read, and remove, each a plain InvokeVoidAsync / InvokeAsync<string?> against a built-in browser API, identical on both transports:

using Microsoft.JSInterop;

namespace Rask.Site.Features;

/// <summary>
///     Round-trips <see cref="IJSRuntime" /> against <c>sessionStorage</c>. Works on both Server
///     (per-session WS-bound <c>RaskJSRuntime</c>) and WASM (in-process bridge via <c>JSImport</c>) —
///     the unified IJSRuntime surface keeps the component identical across hosts. IJSRuntime is
///     injected through the ctor (the framework's DI seam), mirroring <c>ElementRefDemo</c>.
/// </summary>
public sealed partial class JsRuntimeDemo(IJSRuntime js) : Component
{
    private string _input = string.Empty;
    private string? _lastRead;
    private string? _status;

    protected override async Task OnFirstRender()
    {
        try
        {
            _lastRead = await js.InvokeAsync<string?>("sessionStorage.getItem", "rask.jsruntime.demo");
            _status = _lastRead is null ? "(no value yet — try Set)" : $"Read on mount: {_lastRead}";
        }
        catch (Exception ex)
        {
            _status = "Read failed: " + ex.Message;
        }
    }

    protected override Component? Render() =>
        Ui.Card[
                Div.Class("mb-3")[
                    Ui.Input.Value(_input).Label("sessionStorage value")
                        .Id("demo-input")
                        .OnInput(v => _input = v)
                ],
                Div.Class("flex gap-2 flex-wrap items-center mb-3")[
                    Ui.Button.Primary.Icon(Ui.IconName.ArrowDownOnSquare).Id("demo-set").OnClick(Set)["Set"],
                    Ui.Button.Icon(Ui.IconName.ArrowPath)
                        .Id("demo-read")
                        .OnClick(Read)["Read"],
                    Ui.Button.Red.Icon(Ui.IconName.Trash)
                        .Id("demo-remove")
                        .OnClick(Remove)["Remove"]
                ],
                Div.Class("mb-2")[
                    Span.Class("text-zinc-500 dark:text-white/70 text-sm uppercase")["Last read"],
                    Div[Code.Class("text-base").Id("demo-last-read")[_lastRead ?? "(null)"]]
                ],
                Div[
                    Span.Class("text-zinc-500 dark:text-white/70 text-sm uppercase")["Status"],
                    Div[Code.Class("text-base").Id("demo-status")[_status ?? "(idle)"]]
                ]
            ];

    private async Task Set()
    {
        try
        {
            await js.InvokeVoidAsync("sessionStorage.setItem", "rask.jsruntime.demo", _input);
            _status = $"Set to: {_input}";
        }
        catch (Exception ex)
        {
            _status = "Set failed: " + ex.Message;
        }
    }

    private async Task Read()
    {
        try
        {
            _lastRead = await js.InvokeAsync<string?>("sessionStorage.getItem", "rask.jsruntime.demo");
            _status = _lastRead is null ? "Read: (null)" : $"Read: {_lastRead}";
        }
        catch (Exception ex)
        {
            _status = "Read failed: " + ex.Message;
        }
    }

    private async Task Remove()
    {
        try
        {
            await js.InvokeVoidAsync("sessionStorage.removeItem", "rask.jsruntime.demo");
            _lastRead = null;
            _status = "Removed";
        }
        catch (Exception ex)
        {
            _status = "Remove failed: " + ex.Message;
        }
    }
}

Typed browser APIs

For the full map of every wrapper (shared vs WASM-only, one-shot vs subscription), see the Browser APIs overview. This section covers the shared set and the transport "why".

Rather than spelling out raw IJSRuntime identifiers ("localStorage.getItem", "navigator.clipboard.writeText") and getting the JSON shape right by hand, call MDN's own surface from Rask.Web — await LocalStorage.GetItem("theme"), await Navigator.Clipboard.WriteText("hi"), await Crypto.RandomUUID() — or inject one of the built-in typed wrappers below through a component constructor. Each is a thin, awaitable layer over the same unified IJSRuntime, so it behaves identically on Server and WASM. These are the Web APIs that work on both transports; WASM-only PWA APIs (service worker, cache, manifest) are a later step on the same pattern.

The storage estimate is await Navigator.Storage.Estimate() in Rask.Web, with Persist() and Persisted() beside it. Device tilt and motion are Window events there: await Window.OnDeviceOrientation(e => _angle = e.Alpha, every: 100.Milliseconds), throttled in the browser by every:.

public sealed partial class Drafts(IIndexedDb db) : Component
{
    private async Task Save() => await (await db.OpenStore("drafts")).Set("note", "hi");

    protected override async Task OnFirstRender()
    {
        var note = await (await db.OpenStore("drafts")).Get("note");   // string?, null if absent
        var cookies = await Document.Cookie;                                       // "a=1; b=2", from Rask.Web
        var id = await Crypto.RandomUUID();                                        // string, from Rask.Web
    }
}

Call them from an event handler or lifecycle hook (not from Render()). Some APIs (WebAuthn, the file system pickers, crypto.subtle) are browser-gated — they need a secure context (HTTPS or localhost) and the user's permission; a denial or timeout surfaces as a JSException from the awaited task, so wrap those calls in try/catch.

User-activation and the transport — why one API is WASM-only. Some browser APIs require transient activation: they must run inside the live user-gesture task. On WASM an event handler's interop call runs synchronously in that gesture's call stack, so it qualifies; on Server the click is forwarded over the WebSocket and the interop call runs a round-trip later, after the transient activation has expired. The practical effect:

• Sharing splits by when you fire it. The headless declarative Shareable (Rask.Core) attaches data-rask-share to your element and the shared client fires navigator.share inside the click's own call stack, so the activation is still live — it therefore works on every host, Server included. The imperative await Navigator.Share(…) (Rask.Web) lets you share from code (a lifecycle hook, after an await), which needs the in-process transport to keep the activation — so it compiles only in a WASM app (on Server navigator.share would reject with "Must be handling a user gesture").
• Fullscreen and Picture-in-Picture need transient activation too. They are await _stage.RequestFullscreen() and await _video.RequestPictureInPicture() on an element ref in Rask.Web, generated into WASM only. On Server, Trigger.Fullscreen and Trigger.PictureInPicture run them in the click.
• A custom install button's await _prompt.Prompt() (the kept beforeinstallprompt from Window.OnBeforeInstallPrompt, Rask.Web) needs the click too, so it is WASM-only; on Server, Trigger.Install shows the same kept prompt in the click. Screen capture, await Navigator.MediaDevices.GetDisplayMedia(), is a Rask.Web call generated into WASM only. See the Mobile & PWA guide.
• The screen wake lock, await Navigator.WakeLock.Request(WakeLockType.Screen) in Rask.Web, needs no transient activation, so it works on both hosts. The app badge is await Navigator.SetAppBadge(3) in Rask.Web.
• Everything else here (cookies, indexeddb) is unaffected by activation and behaves identically on both transports.

These are one-shot request/response calls. A subscription — ISignaling, IWebRtc, or a Rask.Web event such as Window.OnDeviceMotion — hands back an IAsyncDisposable and the browser pushes each change to a C# handler. Open it from a lifecycle hook and dispose of it on unmount. See the push pattern.

This is the rule for the whole surface: shared APIs live in Rask.Core.Browser; APIs that can't work on Server live in Rask.Wasm.Browser (the home for upcoming PWA-only APIs too).

Under the hood: the wrappers' helpers (and __raskEl) live in src/Rask.Core/Resources/rask-api.ts and are imported by both client runtimes at build time, so the two transports never drift. The types they deserialize are rooted for the WASM trimmer by the framework, so they work in a PublishTrimmed app.

Runnable demos: the Browser APIs section of the showcase at rask.sh/docs — one demo per API, from src/Rask.Site/Features/Browser/.

Element refs

A ref is a handle on one rendered element. Type it to the element's MDN interface and it carries that interface's DOM members, generated from MDN — the same data the elements and their events come from:

public sealed partial class RefDemo : Component
{
    private readonly ElementRef<HTMLDialogElement> _dialog = new();   // a field: the id is stable across renders
    private readonly ElementRef<HTMLInputElement> _name = new();
    private readonly ElementRef<HTMLVideoElement> _video = new();

    protected override Component? Render() =>
        Div[
            Input.Of<string>().Ref(_name),
            Video.Src("/intro.mp4").Ref(_video),
            Button.OnClick(Open)["Open"],
            Dialog.Ref(_dialog)[Button.OnClick(async () => await _dialog.Close())["Close"]]
        ];

    private async Task Open()
    {
        await _dialog.ShowModal();                     // MDN's showModal()
        var open = await _dialog.Open;                 // MDN's open, read from the live element
        await _name.Focus();                           // HTMLElement's focus(), which a dialog ref has too
        var box = await _name.GetBoundingClientRect(); // a DOMRect record
        await _video.SetCurrentTime(12);               // a write, where the render does not own the value
        await _video.Play();
    }
}

• An operation is a method, an attribute an awaitable read, named as MDN names them, with no Async suffix and no IJSRuntime to inject: the ref finds its element's session itself. Each member's doc comment gives its browser support and links to MDN.
• Bases come with it. IElementRef<out T> is covariant, so an ElementRef<HTMLDialogElement> has HTMLElement's Focus() and Element's ScrollIntoView(…), GetBoundingClientRect() and ScrollTop. An untyped ElementRef.New() carries Element's.
• Options are MDN's dictionaries, as records; IDL enums are enums: ScrollIntoView(new ScrollIntoViewOptions { Behavior = ScrollBehavior.Smooth, Block = ScrollLogicalPosition.Nearest }).
• The render stays in charge. There is no setter for what the render writes — Open, Id, a control's Value — and nothing that rewrites the tree, the attributes or the content (innerHTML, append, setAttribute). Drive those from state; keep the ref for what only the live node knows or does.
• Only members whose values cross the wire are there. A member that takes a kept Rask.Web object takes its handle (await _video.SetSrcObject(stream)); one that hands back a live Node is left out, and a ref still hands the element to your own TypeScript for those.
• A typed ref on the wrong element throws where it is put: an ElementRef<HTMLVideoElement> on a Div.
• A member a browser only allows during a click (RequestFullscreen(), RequestPointerLock(), an input's ShowPicker()) is generated into Rask.Wasm alone, where the handler runs in the click. On the Server host the call would reach the browser after the click has ended and be refused, so there it does not compile; Trigger.Fullscreen and Trigger.PictureInPicture run it in the click from markup instead.

A ref still serializes as {"__raskRef__":"id"}, and both clients revive it to the live DOM element, so it passes to IJSRuntime or to your scoped TypeScript as the element itself:

var width = await Width(_box);   // RefDemo.ts's `export function width(el: HTMLElement | null)`

Focus an input, measure a box, and open a dialog from C#, then measure the box again in a sibling .ts:

namespace Rask.Site.Features;

// Element refs end to end: a ref typed to the element's MDN interface carries that interface's DOM members, generated
// from MDN (Focus, GetBoundingClientRect), and any ref still hands the element to scoped TypeScript. The refs are
// fields so their ids stay stable across renders.
public sealed partial class ElementRefDemo : Component
{
    private readonly ElementRef<HTMLInputElement> _input = new();
    private readonly ElementRef<HTMLElement> _box = new();
    private readonly ElementRef<HTMLDialogElement> _dialog = new();
    private string _measured = "";

    protected override Component? Render() =>
        Div[
            Ui.Input.Of<string>().Label("Focus me from C#")
                .Type(InputType.Text)
                .Placeholder("Focus me from C#")
                .Ref(_input).Class("mb-2"),
            Div.Class("flex gap-2 flex-wrap items-center mb-3")[
                Ui.Button.Primary.OnClick(FocusInput)["Focus the input"],
                Ui.Button.OnClick(MeasureBox)["Measure the box"],
                Ui.Button.OnClick(MeasureInJs)["Measure it in TypeScript"],
                Ui.Button.OnClick(OpenDialog)["Open the dialog"]
            ],
            Div.Ref(_box).Class("border rounded p-3 bg-zinc-50 dark:bg-zinc-900")[
                "A box carrying an ElementRef — measured from C# through MDN's getBoundingClientRect, or in TypeScript."
            ],
            Dialog.Ref(_dialog).Class("rounded-xl border border-zinc-200 bg-white p-6 text-zinc-800 shadow-lg dark:border-white/10 dark:bg-zinc-800 dark:text-white")[
                P.Class("mb-3")["Opened with MDN's showModal(), from C#."],
                Ui.Button.OnClick(CloseDialog)["Close"]
            ],
            _measured.Length > 0
                ? P.Class("text-sm text-zinc-500 dark:text-white/70 mt-2 mb-0")[_measured]
                : null
        ];

    // MDN's HTMLDialogElement.showModal(), then its open attribute read back from the live element.
    private async Task OpenDialog()
    {
        await _dialog.ShowModal();
        _measured = $"Dialog open: {await _dialog.Open}";
    }

    private async Task CloseDialog()
    {
        await _dialog.Close();
        _measured = $"Dialog open: {await _dialog.Open}";
    }

    // MDN's HTMLElement.focus(), on the live input.
    private async Task FocusInput() => await _input.Focus();

    // MDN's Element.getBoundingClientRect(), returned as a DOMRect record.
    private async Task MeasureBox()
    {
        var rect = await _box.GetBoundingClientRect();
        _measured = $"Box width: {rect.Width:F0}px (MDN's getBoundingClientRect, from C#)";
    }

    // User scoped TS: Width is generated from ElementRefDemo.ts's `export function width`, and the ref
    // resolves to the element before the script sees it.
    private async Task MeasureInJs()
    {
        var width = await Width(_box);
        _measured = $"Box width: {width:F0}px (measured in TypeScript from the passed element)";
    }
}

Wrapping a third-party JS library

Everything above is enough to wrap a library that owns its own DOM — a chart, a code editor, a map. Two questions come up every time: what happens to the DOM the library builds, and what happens to the <style> it injects. Rask answers the second for you; the first is one rule.

Describing the library to TypeScript

There is no node_modules in a Rask app, so a library's own typings are not there to install. Write a .d.ts beside your component describing only what you actually call — any .d.ts in the project is compiled alongside your scoped files, and a narrow declaration that is true is worth more than a complete one copied from upstream that drifts, because the compiler believes either equally.

A hand-written .d.ts beside the scoped file is a worked example: about fifty lines covering one constructor, two methods and three callbacks. Rask's own globals (window.DotNet, window.Rask) are already declared for you and need no work.

Give the library a leaf to own

Render the host element with no children and let the library fill it. That's the whole rule, and it works because of how the diff addresses nodes: ops are computed from your C# render tree and applied by positional path, so a node your components never render is a node the diff can never reach.

private readonly ElementRef _host = ElementRef.New();   // a field — the id must be stable across renders

// A leaf: no children here, ever. The library owns everything inside it.
protected override Component? Render() => Div.Ref(_host).Class("chart");

// Mount the library in OnFirstRender, not OnMount — OnMount runs *before* the first render, so the element
// doesn't exist yet and the ref would resolve to null. OnFirstRender runs once, so it never mounts twice.
// Mount and Update are Chart.ts's own exports, called as typed methods.
protected override async Task OnFirstRender()
{
    await Mount(_host, DataAsJson());
}

// Fires only on a real prop change — push new data at the library instead of re-mounting it.
protected override async Task OnUpdated() => await Update(_host, DataAsJson());

// Sync and fire-and-forget — see the note below on why this must not be an awaited DisposeAsync.
protected override async Task OnUnmount() => _ = DestroyQuietly();

There is one exception to "the diff can't reach it", and it is not optional. Not every frame is a diff: the first interactive frame after page load always ships the body in full, and a structural change can too. The client applies a full frame by morphing the document, and a morph pairs each live child against the rendered one — your host has live children where the render says none, so the morph clears it. Skip that and the chart is deleted seconds after it draws. Tag the library's nodes; the reconciler leaves marked nodes alone:

// Right after the library builds its DOM. Mark what it created — never the host itself, which your
// component *does* render (marking that makes the morph treat it as missing and append a duplicate).
for (const child of host.children) child.setAttribute("data-rask-managed", "");

One more identity rule, because it bites stateful wrappers specifically: a component's identity is its (type, position) among its parent's children. A sibling rendered as cond ? node : null shifts every later child's position when it vanishes, so the wrapper gets matched against the wrong slot and rebuilt — remounting the widget on an unrelated click. Prefer disabling to un-rendering a sibling above a stateful component.

For events coming back the other way, give your scoped export a callback parameter — mount(host, data, onSelect: (id: string) => void) is Mount(_host, data, id => _selected = id) in C#. It re-renders the component after it runs and is released when the component unmounts; nothing to register.

A script you do not own can't reach an instance method — the JS shim dispatches to static [JSInvokable]s by assembly and name. Hand JS a token at mount, keep a static ConcurrentDictionary<string, YourComponent>, route on it, and unregister on unmount. Two things to get right, because a [JSInvokable] is callable by any script on the page with any arguments:

• Make the token unguessable (Guid.NewGuid().ToString("N")). That dictionary is static, so on the Server host it is shared by every live session — with a sequential int, one visitor could drive another's widget by counting from 1. Holding the token is what proves ownership.
• Unregister on unmount, or the entry pins the component for the life of the process.

Keep the boundary to primitives and JSON strings and a trimmed WASM publish stays clean. Prefer callbacks that take one argument (bundle extras into a record): the generated chain step only wraps arity-≤1 delegates for auto-re-render, so a two-arg callback silently leaves the caller reaching for StateHasChanged().

Finally, tear down from OnUnmount without awaiting the interop call. An IAsyncDisposable component is awaited by the framework's dispose walk, and that walk also runs for a session whose socket has already closed — where an interop call has nobody to answer it and never completes.

A scoped {Component}.css cannot style the library's internals: scoping works by stamping data-{scopeId} on the elements your component renders, and the library's nodes never get it. Size the host in scoped CSS; let the library's own stylesheet handle the rest.

What it injects into <head>

Rask treats <head> as authoritative: on every re-render the live-diff reconciler morphs the live head back to what your components rendered, which keeps <title>/<meta>/scoped-CSS links correct. A <style>/<link>/<script> that a JS library injects into <head> at runtime (a code editor's theme colours, a charting library, a syntax highlighter, an analytics tag) isn't part of that render — so Rask preserves it for you automatically. The reconciler watches <head> and tags anything a library injects with data-rask-managed (the same marker it uses for its own scoped-asset tags), so it survives every re-render with no code on your side. A code editor keeping its injected theme across a re-render is the usual case.

The mechanism only preserves nodes injected after an initial render (the common case — libraries set up once your component has mounted). If you need to keep something present at first paint, or want to be explicit, mark it yourself — the reconciler never touches a head child carrying data-rask-managed:

// You rarely need this — runtime-injected head nodes are preserved automatically. Use it only to opt a
// node out explicitly (e.g. one present before the app's first render).
styleEl.setAttribute("data-rask-managed", "");

An event that outlived its render

A click leaves the browser naming a handler by the id in the markup it was read from (data-rask-on-click="h3"). The id is a position — the fourth handler its component rendered — so when an earlier button leaves or arrives, the id names another handler. An event that left before a re-render and arrived after it used to run whichever handler held the id by then.

The rule: such an event reaches the handler it was sent to, or nothing. Never another handler. Every event says which page it was read from (v, a number the page carried when it was put on screen), and Rask finds the handler that page had under that id as the page has it now:

• It is still there — in the same place, or moved because something before it left or arrived: it runs. A click on Delete sent just before Cancel disappeared still deletes.
• It is gone — its button, its row or its whole component left the page: nothing runs. The event is still answered, so a button waiting on it stops waiting, and no error is shown. The second click of a double click on a row that the first click removed does nothing.

"The same handler" is the same lambda or method of the same component. Where one lambda makes several handlers in a render — a row's button, written once and rendered per row — the one an event was sent to is found by what tells those handlers apart: the values they captured that differ from row to row. A value every row shares (a view of the list the render worked out, a page number) is not which row it is, and may change between renders. Captured values are compared for equality: the same instance, a type that says two instances are equal (a number, a string, a record), or a plain object whose own fields are all equal.

What follows for a list of rows:

• Capture what identifies the row. .OnClick(() => Remove(row)) works when row is the same object, an equal record, or an object with equal fields after a reload. A row whose captured object changed in any field between the two renders — its name was edited while the click was on its way — is not found, and the click is dropped rather than risked. Taking the id into a local first — var id = row.Id; … .OnClick(() => Remove(id)) — captures only what never changes.
• Do not capture a position. .OnClick(() => RemoveAt(i)) is the same handler in every render: after the first row is removed, i names the next row, and no rule can tell that it should not.
• Key rows that are components (.Key(row.Id)). A row that is a component of its own and carries no key is the same instance by position, whatever record it is handed — so after the first row is removed, the instance in second place shows the third record, and a click sent to "the second row" reaches it. A key ties the instance to its record, and that click then reaches its own row or nothing.

Three cases are worth knowing:

• One button over "the current item" — a lambda rendered once that captures the item on screen — is one handler whatever item it shows. A second click sent before the next item arrived acts on the item that is there now. A handler that must not run twice checks for itself (if (item.Id != _current.Id) return;), or renders one keyed button per item.
• Older than two pages. Rask remembers what a place held for the last two pages sent whose handlers moved — enough for a handler that awaits, which is rendered while it waits and again when it is done. A click that was on its way through three such renders (a page that ticks several times a second on a slow link) is dropped. Handlers that are methods of the component (.OnClick(Save)), and lambdas that capture only the component, are the same handler in every render and are never dropped for this.
• A list longer than 4,096 handlers in one component is not searched for a handler that moved.

A dropped event is counted in the rask.handlers.stale metric (observability), and in Development it is logged on Rask.Live at Information, naming the component, the handler's position, the page the event was read from and the page as it is.

Frames written by hand — a test, a script — that carry no v are read against the page as it is, as before.

Behaviour hooks (data-rask-*)

Some behaviour can be written neither as a render (which only writes attributes) nor as a handler (which runs a round trip later, after the gesture is gone): showing a popover under the pointer, writing the clipboard, keeping a caret in place. For those the runtime carries small generic hooks. An element asks for one by carrying an attribute; every hook is a delegated listener on the document. Rask UI is built on them, and they are just as usable from your own markup: Div.Data("rask-tooltip", "tip-1")[…].

They live in src/Rask.Core/Resources/rask-hooks.ts (one module per concern) beside the older ones in rask-dom.ts — data-rask-dismiss, data-rask-dismiss-after, data-rask-dismiss-hold, data-rask-focus-trap, data-rask-popover-open, data-rask-dropzone, data-rask-shortcut, data-rask-contextmenu — which are part of the runtime itself.

How the hooks load

A page that carries none of these attributes does not download them. The hooks in the tables below are a script of their own, rask-hooks.js (49 kB, 15 kB gzipped), beside the runtime every page loads (rask.js on the Server host, rask.wasm.js in a WebAssembly app). The runtime keeps only the list of attributes that ask for a hook, and fetches the script the first time the page carries one — at most once per document:

Nothing is asked of you: there is no tag to write and nothing to register. Both scripts are served with the same caching (one ?v= names the pair on the Server host and both are immutable under it; a WebAssembly app serves rask-hooks.js as it serves rask.wasm.js, and its service worker keeps it for offline use once fetched), from your own origin, with the runtime's nonce when its <script> has one. Under a Content-Security-Policy the hooks need what the runtime already needs — script-src 'self', or the nonce — and no inline script.

Any element counts, whoever wrote it: your own markup, a Raw fragment, a node a script of yours inserted. Besides the data-rask-* names, six of the platform's own ask for a hook, because a hook improves them unasked: popover, commandfor, aria-activedescendant, role="switch" on a checkbox, role="tablist" and role="menu".

What a hook module may import

For whoever adds a hook to the runtime: a hook module imports other hook modules, rask-bound.ts and rask-owned.ts, and nothing else. The hooks are bundled apart from the runtime, and a bundle gets its own copy of every module it imports. A hook that imported rask-host.ts to ask inRoot() would be asking a copy no host was ever installed in; one that imported rask-morph.ts or rask-loading.ts would read dirty fields and loading buttons nobody recorded there. What the two bundles must agree on hangs off one object on the global, __raskHookSeam, declared in rask-owned.ts — the only module both carry, which itself imports nothing. Something new a hook needs from the runtime goes on that seam. HookBundleContractTests fails for a second module in both bundles.

The runtime itself runs a document once. Its shared modules bind their document listeners as the script is read, so a second copy in the same document — the Server host's tag is a child of the render root, and a navigation to a page with more or fewer top-level nodes puts it back — is never run by the morph, and a copy that arrives some other way stands down: its listeners answer nothing and send nothing (standDown in rask-host.ts).

Pointer-opened popovers

Popovers, dialogs and the page behind them

Open and shut has two hands, and the reader's comes first. A popover with data-rask-popover-open, a dialog with data-rask-modal-open and a <details> whose open the page renders are opened and shut by a render — and by the reader, in the browser, at once. From the moment the browser opens or shuts one until the server has answered that event (its toggle, or a dialog's close), no render drives it: a reply rendered before the server heard Escape cannot open the list again. What a render was refused meanwhile is carried out once the answer is on the page. And the toggle the runtime raises by opening or shutting one to match a render is not sent back: OnToggle and OnBeforeToggle hear what the reader did, not the page's own change of mind. A dialog's OnClose hears every close, the page's own included.

Menus

Fields

Keys and focus

Gestures, capabilities and uploads

Toasts

State the reader owns

Carousels

Scrolling

A render removes only what the server wrote (rask-written.ts): an attribute a script put on a rendered element itself — a canvas's width and height, sized by its scoped TypeScript — stays through every diff, morph and whole-page reply until a render writes that attribute; from then on it is the render's, and a render that leaves it out removes it. One attribute watch on the document tells the two apart; the runtime's own patch writes are not counted.

A hook that writes an attribute holds it against the morph (rask-owned.ts): data-open, data-copied, a tooltip's aria-expanded and a carousel's disabled are not what the page rendered, and a re-render neither strips them nor puts the rendered value back over them.