Window position, size, and visibility

Declare page, size, and initial position

Replace spec inside the starter operator while keeping close results, exceptions, and open-result handling. This declares a top-right transparent window; size does not refer to the whole desktop.

spec = web.window(
    web.local_app("web/index.html"),
    title="我的工具",
    size=web.window_size((640, 420), minimum=(360, 260)),
    placement=web.window_placement("top_right", margin=(24, 24)),
    transparent=True,
)

Edge resizing is off by default. When needed, set resizable=True and choose suitable minimum and maximum viewport sizes. Reflow the page for the available space while keeping text and controls at their original sizes. With automatic overflow handling, the host leaves room to grab the edges inside the editor.

Windows belong to Blender editor regions

placement supports nine anchors; use web.window_position for exact coordinates. Opening needs a valid Blender window/editor. Background scripts or context-free timers cannot assume one exists.

Initial placement applies on opening. Dragging preserves manual position. Region shrinkage makes only necessary vertical header corrections, not automatic page reflow/scaling. Handle content overflow yourself.

Opening, closing, and reopening

Use a stable key. Reopening that key fails by default; replace_existing=True replaces, not toggles. Let close results determine sidebar behavior rather than an independent boolean drifting after page-side closing.

An external close script calls await window.acquireNexusWebUI().window.close() for the current window only. Show failures. For complete behavior and checks, see Interface entry points.

Multiple windows and editor instances

Different keys create settings/preview windows. For one tool across same-type editors, pass area_target to open_window, not the window declaration.

result = plugin.open_window(
    "studio", spec,
    target=web.area_target(scope="same_type", existing="reuse"),
)

Omitted filters infer the current editor type; Shader Editor does not mean all node editors. Inspect result.instances. Close individual instances by returned real keys, or the group with close_windows('studio'). Real keys are not guaranteed stable across restarts.

Storage scope and window size are separate

Windows share plugin browser storage by default. Use browser_state=web.browser_state(kind="window") for per-window isolation, not merely because placement differs.

• Check header and close reachability in small regions and at different UI scales.
• Open two instances and confirm actions/closing affect the intended one.
• Transparent windows also need correct click/drag markers. See Transparent shapes and drag regions.