# The frame viewer facade

**🟠 Advanced · Lesson 13**

THE FRAME VIEWER - the room's read surface, and the first place in melder where the AIX claim stops being a design philosophy and becomes methods you can call.

IT IS A FACADE, AND IT SAYS SO. FrameViewer's own docstrings read "FACADE PASS-THROUGH to ViewMultiFrame.list_frame_names(...)" and note that it builds "a ViewMultiFrame per invocation against a freshly resolved" source. That second half matters more than the first: THERE IS NO CACHED SNAPSHOT. Every read resolves fresh, so a viewer you held onto for an hour cannot hand you an hour-old world. You trade a little work per call for never having to ask "is this stale?"

FOUR SPECIALIZED VIEWS BEHIND IT, IN TWO GROUPS get_view_multiframe() HOST-SCOPED - all frames, needs no name get_view_frame() FRAME-SCOPED - targets, visibility, topology get_view_conduit() FRAME-SCOPED - records, roots, relationships get_view_spell() FRAME-SCOPED - identity, source, binding

AND THERE IS NO DEFAULT FRAME. The three frame-scoped accessors REQUIRE a frame name, because "the viewer no longer supports default-frame routing for frame-local operations". A freshly opened rift is contracted to no frames, so until you assign one there is no name to pass - and that is the honest state, not a bug in your code.

SIGNATURE DEFECT FOUND AND FIXED (2026-08-02): these were typed `frame_name: Optional[str] = None` and then rejected None unconditionally - the documented default was never valid, so a reader who trusted the signature got an error for using it. 33 methods on FrameViewer now declare `frame_name: str`, so omitting it fails at the CALL with a TypeError instead of inside the body.

NOTE THE DISTINCTION THAT SURVIVED THE FIX, because it is real: FrameViewer.describe_missing_surface(frame_name) SELECTOR, required ViewFrame.describe_missing_surface(frame_name=None) ASSERTION, optional A ViewFrame is ALREADY bound to one frame, so naming it there is a guard against reading the wrong world, not a choice of which to read. Optional is correct on one and a lie on the other.

AND THEN THE PART WORTH THE WHOLE LESSON.

The viewer carries a surface built FOR AGENTS, by name:

describe_agent_onboarding_json() how to use me describe_viewer_agent_purpose_json() what I am for describe_viewer_method_surface() what I can do list_viewer_method_names_ast_json() my methods, from the AST describe_viewer_class_surface_ast_json()

Most libraries expect a reader to arrive already knowing the API - docs live in a website, and the object tells you nothing about itself. These methods invert that. The object onboards its own caller, in JSON, at runtime.

For a human that is a curiosity. For an agent it is the difference between guessing a surface and reading it - and it is the same idea as list_supported_command_methods() in lesson 11. Twice now, melder has answered "what may I do here?" with a method instead of a manual.

## Before you run

Use the [Advanced guide](../../advanced/index.md) for prerequisite concepts. Run from a checkout with Melder installed and Python 3.14 free-threading selected. The collection download includes the level's local helper modules.

## Run the saved script

```bash
python UX_and_AIX_experiences/03_advanced/13_the_frame_viewer_facade.py
```

```powershell
py -3.14t UX_and_AIX_experiences/03_advanced/13_the_frame_viewer_facade.py
```

{download}`Download this collection <../../downloads/advanced-examples.zip>` · [Source on GitHub](https://github.com/Synaptic724/melder/blob/90d52e0a12cb0743d62568d5a19ce954a54443bc/UX_and_AIX_experiences/03_advanced/13_the_frame_viewer_facade.py)

## Public surface

room.frame_viewer, get_view_* accessors,
                   describe_available_views, describe_viewer_method_surface,
                   describe_agent_onboarding_json

## Code

```{literalinclude} ../../downloads/03_advanced/13_the_frame_viewer_facade.py
:language: python
:linenos:
```

## Check the outcome

The script contains its own assertions or demonstrated refusal paths. Run it to evaluate those checks against your installed version. The code above is taken directly from the saved file; no run output is invented here.

[More advanced examples](index.md) · [Level guide](../../advanced/index.md)

## Related guides

- [Viewer navigation and the describe ladder](../../advanced/viewers.md)
- [World inspection walkthrough](../../advanced/inspection-walkthrough.md)