Expose Viser viewer extension context

[ruziniuuuuu]

Description

Expose a typed, non-owning context from ViewerViser for applications that add scene nodes and GUI controls to the existing Viser session.

The context contains only the scene API, GUI API, and initial-camera configuration. It deliberately omits the ViserServer: Newton continues to own the server and viewer lifecycle, while the application owns the nodes, controls, callbacks, and background work it creates.

This is intentionally narrower than #4039. It does not discover or load third-party viewer classes; callers construct the normal ViewerViser and extend that instance through capability-limited handles.

Closes #4091.

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• For user-facing changes, a fragment has been added by following the changelog fragment instructions

Test plan

uv run --extra dev -m newton.tests -k viewer_viser_extension_context
uv run --extra dev -m newton.tests -k viewer_layers
uvx pre-commit run -a

Results: 1 extension-context test passed, 22 viewer-layer tests passed, and every pre-commit hook passed.

New feature / API change

from newton.viewer import ViewerViser

viewer = ViewerViser()
context = viewer.extension_context

origin = context.scene.add_frame("/application/origin")
visible = context.gui.add_checkbox("Show origin", initial_value=True)

@visible.on_update
def _(_event):
    origin.visible = visible.value

context.initial_camera.position = (3.0, 3.0, 2.0)

Summary by CodeRabbit

• New Features

  • Applications can now extend Viser scenes with custom scene nodes, GUI controls, and callbacks through a dedicated extension context.
  • The extension context provides access to scene, GUI, and initial-camera controls without exposing the underlying viewer server.
  • The new extension context is publicly available through the viewer API.

• Documentation

  • Added usage guidance and API reference documentation for application extensions.

[github-actions]

API review

Detected 5 interface change(s): 5 added, 0 removed, 0 modified.

• Added: newton.viewer.ViewerViser.extension_context (property)
• Added: newton.viewer.ViewerViserExtensionContext (class)
• Added: newton.viewer.ViewerViserExtensionContext.gui (constant)
• Added: newton.viewer.ViewerViserExtensionContext.initial_camera (constant)
• Added: newton.viewer.ViewerViserExtensionContext.scene (constant)

This check is advisory: the label means API review needed, not that a breaking change is proven.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: d2e99923-f43a-4ced-9661-3f3ec39183b4

📥 Commits

Reviewing files that changed from the base of the PR and between 18f1d8b and 1d29c2f.

📒 Files selected for processing (7)

• changelog/4091.added.md
• docs/api/newton_viewer.rst
• docs/guide/visualization.rst
• newton/_src/viewer/__init__.py
• newton/_src/viewer/viewer_viser.py
• newton/tests/test_viewer_viser_extension_context.py
• newton/viewer.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

ViewerViser application extensions

Layer / File(s)	Summary
Context contract and ViewerViser wiring newton/_src/viewer/viewer_viser.py	ViewerViserExtensionContext exposes scene, GUI, and initial-camera handles without exposing the Viser server. ViewerViser creates and caches the context.
Public exports and context validation newton/_src/viewer/__init__.py, newton/viewer.py, newton/tests/test_viewer_viser_extension_context.py	The context is publicly exported. Tests verify handle exposure, cached identity, server omission, and operation forwarding.
Extension context documentation docs/api/newton_viewer.rst, docs/guide/visualization.rst, changelog/4091.added.md	The API reference, guide, and changelog describe application extensions through ViewerViser.extension_context.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to 1d29c

The change is mergeable with explicit owner awareness: applications using the new context must clean up extension-created callbacks, controls, nodes, and background work before viewer shutdown because those resources are not centrally invalidated by the viewer.

Suggested reviewers: eric-heiden

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant ViewerViser
  participant ViewerViserExtensionContext
  participant ViserSession
  ViewerViser->>ViserSession: create server
  ViewerViser->>ViewerViserExtensionContext: store scene, GUI, and initial camera handles
  Application->>ViewerViser: read extension_context
  ViewerViser-->>Application: return cached context
  Application->>ViewerViserExtensionContext: add scene nodes and GUI controls
  ViewerViserExtensionContext->>ViserSession: forward operations through exposed handles

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: exposing the Viser viewer extension context.
Linked Issues check	✅ Passed	The implementation satisfies issue #4091. It adds a typed, stable, non-owning context with scene, GUI, and initial-camera handles, omits the server, exports the API publicly, and adds tests and docume…
Out of Scope Changes check	✅ Passed	The changes remain within scope. The implementation, public exports, tests, documentation, and changelog all support the extension-context objective, with no unrelated feature or third-party viewer di…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (3 skipped: 3 …

Full details: Linked Issues check

Explanation

The implementation satisfies issue #4091. It adds a typed, stable, non-owning context with scene, GUI, and initial-camera handles, omits the server, exports the API publicly, and adds tests and documentation.

Full details: Out of Scope Changes check

Explanation

The changes remain within scope. The implementation, public exports, tests, documentation, and changelog all support the extension-context objective, with no unrelated feature or third-party viewer discovery work.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (3 skipped: 3 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}