window.fullscreen: an app's own window in presentation full screen, from a tap

apps/AGENTS.md

@@ -42,6 +42,21 @@ app's own agent and `tools.json`, the system toolbox, `glance.publish` and
   a white card or the tab bar. News's title and then Photos' headings
   shipped in a fixed `ink` and vanished in dark mode, so check every page you
   change in dark mode as well as light.
+- Presentation full screen (a deck's Present, a reader's Read mode): call
+  `host.request("window.fullscreen", {on: true}, fn(r){…})` from the tap or
+  click handler that starts it, and `{on: false}` to leave. The shell refuses
+  a request with no press on the app in its window in the last 5 seconds
+  (`gesture_required:`; a press on a host sheet does not count, and after Esc
+  or any ending but the app's own `{on: false}` it takes a new press), one
+  while the window is not in front (`foreground_required:`), one from an
+  agent's tool call or a callback of one (`agent_call:`), and one from
+  anything but the app's own window (`not_a_window:`). No capability is
+  needed. While it presents, no screen edge brings the shell's bar,
+  the title bar or the dock out. Esc is the shell's key there, and ⌘F or the
+  window losing the focus also ends it. Define `fn on_app_fullscreen(on)` to follow both ends,
+  so the app leaves its Present or Read layout when the person presses Esc. A
+  phone answers `{applied: false, fullscreen: false, fills_screen: true}`.
+  The contract is in `../crates/shell/src/app_fullscreen.rs`.
 - Mail's service: change `apps/mail/host-service` and run
   `cargo test --locked -p octosense-mail-service`. Calendar's and News's:
   `apps/calendar/host-service`, `apps/news/host-service`, and

apps/README.md

@@ -529,6 +529,36 @@ isolate under no app's policy. Calls from the sheet arrive marked
   they come from the sheet, before any service sees them;
 - only a service can open a sheet; an app cannot.
 
+### The `window` service
+
+The shell's own service for an app's window. `window.fullscreen {on: true}`
+puts the app's own window in presentation full screen when the person taps or
+clicks something in it (a deck's Present, a reader's Read mode), and
+`{on: false}` takes it out. On a desktop the window then covers the whole desk
+with no title bar, the shell's bar and dock hide (no screen edge brings them
+out while it presents), and the OctoSense window enters full screen unless it
+is already there. **Esc** ends it (the shell's
+key: a script app gets no keys), as do `{on: false}`, ⌘F, the window losing
+the focus and the app failing, and the shell shows "Press Esc to exit full
+screen" for three seconds. The answer is `{applied, fullscreen, fills_screen}`.
+A refusal starts with `gesture_required:` (no press on the app in its window
+in the last 5 seconds; a press on a host sheet over the app does not count),
+`foreground_required:` (the window is not in front: the focus is elsewhere,
+or it is on another workspace or minimized), `agent_call:` (the request came
+from an agent's tool call or from a callback of one), `not_a_window:` (a
+glance card, a sheet or another app's window) or `invalid_arguments:`.
+`{on: false}` is never refused for the first three. No capability is needed:
+`prompt`, like every declaration, neither grants nor denies the method. After
+a presentation ends any other way than the app's own `{on: false}` (Esc, ⌘F,
+the focus leaving), going full screen again needs a new press, so an app
+that asks again from `on_app_fullscreen(false)` is refused. An app may define
+`fn on_app_fullscreen(on)`, which the shell calls in the app's isolate when
+full screen starts and when it ends. On
+a phone, where every app fills the screen, nothing changes:
+`{applied: false, fullscreen: false, fills_screen: true}`. The service is the
+shell's (`crates/shell/src/app_fullscreen.rs`), not App Hub's, and
+`runtime.list` does not list it yet.
+
 ### The `mail` service
 
 Ordinary App Hub apps now have account-bound compose/status APIs and native SMTP review. See the [Mail service guide and migration example](mail/host-service/README.md); direct agent or synthetic sending remains refused.

apps/README.zh-CN.md

@@ -431,6 +431,26 @@ python3 apps/writer/tests/ui.py --card-host <App Hub>/target/release/card-host -
   `mail.sheet.cancel`），只有来自面板的调用才会被分发，且在任何服务看到之前就已检查；
 - 只有服务能打开面板，应用不能。
 
+### `window` 服务
+
+Shell 自己为应用窗口提供的服务。用户点按或点击应用窗口中的某个控件时（演示文稿的 Present、
+阅读器的 Read 模式），`window.fullscreen {on: true}` 让应用自己的窗口进入演示全屏，
+`{on: false}` 让它退出。在桌面上，窗口随即铺满整个桌面且没有标题栏，Shell 的栏和程序坞
+隐藏（演示期间屏幕边缘也不会把它们唤出），OctoSense 窗口如果还不在全屏中也会进入全屏。按 **Esc** 结束（这是 Shell 的按键：
+脚本应用收不到按键），`{on: false}`、⌘F、窗口失去焦点以及应用出错也会结束它；Shell 会显示
+"Press Esc to exit full screen" 三秒。回答是 `{applied, fullscreen, fills_screen}`。
+拒绝以下列前缀开头：`gesture_required:`（最近 5 秒内没有在这个窗口里按过应用本身；在应用上方
+的宿主面板里按下不算）、`foreground_required:`（窗口不在最前：焦点在别处，或窗口在另一个
+工作区、已最小化）、`agent_call:`（请求来自 Agent 的工具调用或它的回调）、`not_a_window:`
+（glance 卡片、面板或其他应用的窗口）、`invalid_arguments:`。`{on: false}` 不会因为前三种
+原因被拒绝。不需要任何能力：`prompt` 和其他声明一样，既不授予也不拒绝这个方法。演示全屏以
+应用自己的 `{on: false}` 以外的方式结束后（Esc、⌘F、焦点离开），再次进入全屏需要新的一次
+按下，所以应用在 `on_app_fullscreen(false)` 里再次请求会被拒绝。应用可以定义 `fn on_app_fullscreen(on)`，
+全屏开始和结束时 Shell 都会在应用的 isolate 中调用它。在手机上，每个应用本来就占满屏幕，
+所以什么都不会改变：`{applied: false, fullscreen: false, fills_screen: true}`。这个服务
+属于 Shell（`crates/shell/src/app_fullscreen.rs`），不属于 App Hub，`runtime.list` 目前还
+不列出它。
+
 ### `mail` 服务
 
 普通 App Hub 应用现可使用按应用/账户隔离的撰写、状态查询和原生 SMTP 审阅接口。见 [Mail 服务与迁移示例](mail/host-service/README.zh-CN.md)；Agent 和合成输入仍不能直接批准发送。