Page markers and script loading

Hit-test shapes for transparent windows

Set transparent=True in the Python window declaration, then define the page's visible region. Explicit Python settings take priority over page declarations. Hit testing uses geometry, not per-pixel alpha analysis.

Item	Usage and limitations
data-nexus-window	Place on the full panel or an independent clickable region, not just its header. Missing markers fall back to a full-page rectangle.
data-nexus-hit	Supports rect, rounded, circle, ellipse, and path. Match the actual interface shape.
data-nexus-hit-path	Path points use normalized coordinates from 0 to 1. Invalid shapes are ignored.
Counts and clipping	At most 32 window shapes and 96 drag/exclusion rectangles. Regions that are unrendered, invisible, fully transparent, pointer-disabled, or fully clipped are not valid drag regions.

Movement, font loading, scrolling, and layout changes update geometry snapshots. Without a valid snapshot, the host conservatively uses a rectangle. Do not rely on missing snapshots for click-through behavior.

Dragging, exclusions, and text selection

Item	Usage and limitations
data-nexus-drag	A host-window drag handle. Do not place on workspaces that need web middle-button actions, context menus, or their own pointer gestures.
data-nexus-no-drag	Declares exceptions inside a handle so controls remain usable.
data-nexus-selectable	Allows display text selection, inherited by descendants. Inputs and editable content remain selectable themselves.

Transparent page structure; keep styles in an external CSS file

html

<main data-nexus-window data-nexus-hit="rounded">
  <header data-nexus-drag>
    <span>My tool</span>
    <button type="button" data-nexus-no-drag>Close </button>
  </header>
  <p data-nexus-selectable>Copyable instructions</p>
  <input aria-label="Name">
</main>

The close button still needs a handler. Standard inputs and buttons are automatically excluded, but complex custom controls need explicit no-drag. Host dragging uses the left button by default; middle-button panning does not move the window.

File interaction markers

Item	Usage and limitations
data-nexus-import="images\|text\|files\|event"	Display images, text, or file entries, or pass only to event handlers without automatic display. The vertical bar indicates alternatives.
data-nexus-import-mode="append\|replace\|event"	Appends by default. replace replaces target content; event does not modify the DOM automatically.
data-nexus-import-max / data-nexus-import-fit	max is a positive display-count limit for this operation. fit sets image object-fit without changing the host import budget.
data-nexus-pick / data-nexus-accept / data-nexus-target	pick selects images, files, or directory. accept filters file types; target specifies the target selector. Ordinary picking is enabled by default. Directory picking does not use accept filtering.
data-nexus-save / data-nexus-source / data-nexus-name	save='image' saves a canvas or img; json parses source text as JSON; text saves text. source is a selector and name suggests a filename. It does not call custom adapter export automatically or screenshot arbitrary elements.

For complete copyable examples, see Import tutorial and Save tutorial. Button targets use built-in DOM or canvas import and do not automatically forward to custom adapters. Complex components should update internal state through their own pick handlers. Use script calls to display save results or errors.

Script order and optional layers

Page resource scripts: copy from your framework into the local websdk directory

html

<script defer src="websdk/nexus-resource-io.js"></script>
<script defer src="websdk/nexus-resource-dom.js"></script>
<script defer src="websdk/nexus-resource-kit.js"></script>
<script defer src="app.js"></script>

The trusted host injects the communication core. There is no separate script for manually injecting it. Load io and dom before kit, and application scripts afterward. Do not use async for ordered dependencies. These scripts do not give an ordinary browser Blender communication.

Item	Usage and limitations
Read-only resource images	Load only kit for readers such as loadImage.
High-level file operations	Load io before kit; add dom for attributes or component adapters.
Standard file-input/download-link interception	Load file-input-takeover or download-takeover as needed; both enable by default. Avoid duplicating the same operation with your own handlers.
React / Vue / Svelte	Choose the adapter for your frontend framework; do not load them all.
Type files	Use both .d.ts files in your editor. Do not execute them through script tags.

Troubleshooting boundaries

Check actual script/style loading, then window declarations and page markers. A visible page does not prove correct drag snapshots. Hit regions must match visible content. See Cannot drag, Clicks pass through or controls cannot be clicked.