docs(frame): state the portal-side contract for closing a slider app

[IgorShevchik]

Refs #328 — the documentation half, which a comment on that issue argued is not optional.

Why documentation is our half of a platform bug

The SDK's part of closeApplication works: it posts the command to the parent window and stops. Everything after — animating the slider shut, releasing the focus trap, removing the frame — is the portal's, and an application author cannot reach any of it from inside the iframe. So when a close misbehaves, our documentation is where they look first.

Ours said, in full: "Closes the application slider."

Same shape as #356/#357, where the SDK's half was correct, the failure was entirely framework-side, and the documentation still had to change — because it could not tell the developer their half had succeeded.

What is now stated

At parent.closeApplication, with slider.closeSliderAppPage pointing at it:

• The promise is not a completion signal. A resolve means the portal acknowledged the message; nothing in the protocol reports the state of the page you are being removed from.
• It may never settle at all. Unlike most frame commands this one is sent with isSafely: false, so only the portal's answer settles it — and on affected builds that answer never comes, because the exception fires before the response postMessage. await $b24.parent.closeApplication() then waits forever. Cleanup belongs before the call, never after it.
• The inert defect, in a warning block: what the reader is actually seeing when the portal freezes after a close, that a page reload is the only recovery, that it is reported and handed to the core team, and that it is not a bug in their application.

We were teaching the broken shape

Two of our own files told readers to do the thing that hangs:

File	Was
99.examples/2.frame-app-skeleton.md	async function close() { await $b24?.parent.closeApplication() }
skills/b24jssdk-frame-ui/SKILL.md	await $b24.parent.closeApplication()

Both now fire-and-forget with a .catch(() => {}) and a comment saying why. The skill gained the gotcha line; it already warned about the unhandled rejection at destroy(), but not about the await that never returns.

The JSDoc @memo was falsified

Both methods carried this justification for isSafely: false:

There is no point - everything will be closed, and timeout will not be able to do anything

#328 is precisely the case that reasoning does not cover. When the portal throws, the frame is not destroyed — the report shows the closed slider's iframe still in the DOM at zero width — so there is no "everything will be closed", and the promise is simply stranded. The note now says so, and leaves the switch to isSafely: true explicitly open rather than implying it was settled.

Not in this PR

The isSafely: true mitigation itself. It changes runtime behaviour of a public method, so it wants the full review panel and a maintainer's decision — raised separately.

Verification

docs-typecheck-blocks (158), skills:typecheck-blocks (83), jsdoc:typecheck-blocks (41) and package-jssdk:typecheck all clean; docs-lint --strict, md-internal-links and lint:md clean; 121 script tests green. The audited: stamps on the two touched pages moved to today, since their cited sources changed.

The docs gate caught my own snippet using an undeclared saveDraft() — worth noting as the gate doing its job on this very PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr

---

Generated by Claude Code