Why The Browser Is Not The Agent
One of the most important design choices in ImpactRoom is that the browser is not the external agent. That sounds simple, but it changes the entire shape of the demo. Many interactive systems quietly let the browser become the hidden control plane. The visible page looks like an observer, but behind the scenes it is the most privileged client in the room. ImpactRoom is built to avoid that pattern. The browser observes public projection and performs operator actions through a separate operator route. The agent uses the Agent Surface. Those are different roles on purpose.
What The Observer Sees
The observer side of the system reads sanitized public projection. That means the browser sees what the demo intends to make public: current public state, compact state evidence, the room map, the agent marker, the event ledger, and the latest Public Observation. It does not see or need raw private adapter state. It does not need internal identifiers. It does not need to participate in the deeper execution path. Its job is to show the public story clearly.
Why Public Projection Is Smaller Than Private State
This public projection is smaller than the private state behind it. That is not a limitation of the demo. It is one of the things the demo is trying to teach. If the browser saw every internal runtime detail, there would be no meaningful boundary between what is public, what is operator-relevant, and what belongs to the adapter or its private host path. Instead, the observer view is deliberately curated. It shows enough to explain what happened and why, while leaving out details that do not belong in a public surface.
The Map And Ledger As Public Evidence
The room map is a good example of this approach. It is rich enough to show the stations, the agent’s current location, the door state, and the rough logic of the environment. It also shows the latest Public Observation near the agent as a map bubble. But the map is still only a view of the sanitized public projection. It is not a substitute for the agent’s own state reads, and it is not the source of truth for the agent’s next move.
The event ledger plays a similar role. It surfaces compact evidence about what the boundary checked and what public result followed. It can show that an override attempt was blocked, that approval was required, that a stale key led to no visible impact, or that a fresh key allowed the door to open. What it does not do is turn raw backend execution records into public interface concepts. A visitor does not need raw execution identifiers to understand the demo. They need a readable public story about what the system admitted, blocked, or materialized.
Operator Approval As A Separate Role
Operator behavior is kept separate for the same reason. The browser may act as an operator only through the credentialed operator route. This is a human role, not an agent capability. In the demo, the agent can request the scoped key, but it cannot approve that request for itself. That separation matters because approval is one of the core moments in the story. If the agent could simply approve its own work, the demo would collapse one of its most important boundaries.
In the local preview, operator approval is submitted through the credentialed POST /operator/intent route.
The operator route therefore represents a distinct authority. The exact credential value is not the public point of the demo and is not exposed through the public page or the agent state. What matters publicly is that the operator action exists, that it is different from the agent route, and that the browser can exercise it in the local preview only through the intended operator path. That is enough for a visitor to understand the model without learning private runtime details that do not belong in public docs.
Why Browser And Agent Roles Stay Separate
The same concern still matters even without a built-in replay. A preview could easily cheat by driving the room through private methods and then repainting the observer UI to look coherent. ImpactRoom avoids that by keeping the browser as observer/operator only and by reserving agent action for the guided public Agent Surface. That means the browser is not a hidden shortcut around the public contract.
Observer-Safe Evidence And Hidden Runtime Internals
The phrase observer-safe demo codes can sound abstract until you see why they exist. ImpactRoom exposes compact codes such as the public door state code so the ledger and boundary checks can stay concrete. Those codes help visitors see that a capability was bound to a state and later became stale. They help people understand why a no-impact result happened. What they are not is secret data. They are short public evidence tokens used for explanation, not private runtime credentials. This distinction is important because it shows how a demo can be honest and legible at the same time.
What the browser does not expose is just as important. Raw WorkOrder, Decision, and Lease identifiers are not public UI concepts in ImpactRoom. They belong to deeper runtime layers. The same is true for private callback endpoints, raw token values, and other private infrastructure details. The browser does not need them to explain the room, and visitors are better served by a public story that stays close to the real product boundaries instead of pretending that every internal object is a public concept.
The observer surface also keeps operator-only action names out of public output. Implementation names such as approve_scoped_key, deny_scoped_key, and operator_required_actions may exist below the public layer, but the observer story should use neutral public language such as approval granted, operator denial, or Game Over. Observer/public board output also must not expose agent session_id values.
Why This Separation Matters
This makes the observer and operator model more than a UI decision. It is part of the architectural lesson. If the observer UI becomes the real control plane, public docs start teaching the wrong thing. They teach people to scrape whatever the page happens to render instead of reading the guided state surface. They teach people to view operator approval as just another button in the same role instead of a separate authority. ImpactRoom avoids that by keeping the browser honest about what it is allowed to do.
For technical visitors, this separation is one of the most useful parts of the demo. It shows that a polished public preview can still respect role boundaries. The map can be rich. The ledger can be informative. The built-in demo can be helpful. None of that requires the browser to become the true control system. That is a strong pattern for anyone building public AI demos or reference adapters: make the observer view useful, keep the operator role explicit, and leave the agent to the agent surface.