feat(mcp): diary-map v2 — no-forced-scroll inline + fullscreen escape hatch (display-mode-aware)

[legreffier]

Context

Follow-up to #1194 / #1229 (the v1 diary-map MCP app). v1 ships an overview + zone + entry-mosaic UI, validated in the mcp-host fixture. But the real runtime is an embedded iframe inside a chat turn (Claude Desktop, ChatGPT), and a mosaic of many EntryCards does not fit there.

Goal (from design discussion): the inline view must never force the user to scroll. Scrolling is allowed as an escape hatch (fullscreen), not the default. Folders / nested "zoom into a sub-zone" is explicitly a later iteration — not this one.

Verified host constraints (research captured in signed diary entry on issue-1194-diary-map-app)

Source: @modelcontextprotocol/ext-apps@1.7.2 SDK + MCP Apps spec 2026-01-26 + Claude/ChatGPT docs.

• Claude / Claude Desktop: published design guideline = inline max height ~500px, auto-fit, no nested scrolling inline; beyond that Claude scrolls the whole card. Claude ignores size-changed notifications and reads iframe.contentDocument.documentElement height directly → must drive height via document.documentElement.style.height (cap to budget, min-height not 100vh, never set height pre-paint). Fullscreen supported on desktop/web, NOT on Claude mobile (inline only).
• ChatGPT Apps SDK: inline has no observed max-height (grows to content); fullscreen supported but fullscreen↔inline can remount + lose state.
• displayMode ∈ {inline, fullscreen, pip}. App reads via getHostContext(), requests via requestDisplayMode({mode}) which returns the actual mode (host may refuse) — always gate on availableDisplayModes.
• containerDimensions in host context is optional/host-populated — read if present, never depend on it.
• No server-side size hint exists (_meta.ui = csp/permissions/domain/prefersBorder only).

Proposed v2 scope

1. Inline budget ≈ 500px (Claude worst case). Inline = zone overview and/or a compact focused view; never a long entry list inline.
2. Fullscreen is the scroll escape hatch. "View all entries" requests fullscreen (gated on availableDisplayModes), where scrolling/the full list is allowed. Inline-only fallback for Claude mobile (e.g. a compact paged/top-N control surface, no nested scroll).
3. Display-mode-aware layouts: branch at runtime on getHostContext() platform + availableDisplayModes + theme. Inline-compact vs fullscreen-rich.
4. Claude height handling: explicitly set documentElement.style.height (the autoResize fixes in feat(mcp): human-first diary map exploration app (rebuild #1194, supersedes #1212) #1229 work in the fixture but Claude ignores size-changed).
5. Out of scope (later): nested sub-zones / drill-down folders.

Acceptance

• In an inline iframe constrained to ~500px, the user can understand the diary and navigate zones without being forced to scroll.
• "See all entries in a zone" works via fullscreen where available, with a non-broken inline fallback on Claude mobile.
• Verified against the real Claude Desktop + ChatGPT hosts (not just the local fixture).

Relates to #1194, builds on #1229.

[legreffier]

Also for the next PR: e2e tests must use @moltnet/api-client, not raw fetch

apps/mcp-host-e2e/src/entry-map.spec.ts (from #1229) and the shared libs/mcp-test-harness seed diaries/entries with raw fetch to POST /diaries[/:id/entries], while apps/rest-api/e2e/* and apps/mcp-server/e2e/* correctly use createClient + createDiaryEntry from @moltnet/api-client. Both endpoints are in the generated spec, so raw fetch violates the established convention (raw fetch allowed only for /health, /oauth2/token, /auth/register).

This is a recurrence of a previously-ruled-against anti-pattern — captured in signed diary entries:

• incident cbdd365c (this recurrence) → supports → incident 24e3532a (original) + decision 7b0a6488 (enforce api-client in e2e)
• compiled into a pinned knowledge pack 141fdb3d (CID bafyreia7ed3z…) for "how to write MoltNet e2e tests"

Next-PR work:

• Refactor entry-map.spec.ts seeding → createDiaryEntry via createClient
• Fix libs/mcp-test-harness public-diary creation → createDiary (higher leverage — it's the template every MCP e2e suite copies)

Deliberately deferred from #1229 to avoid scope creep.

[getlarge]

It seems like agent are not passing entries correctly, or the MCP app has some sort of issues. Also see the error when saving the zone. Yes pack create does NOT return an id.

[legreffier]

Diagnosed from the inputs you shared — thanks, that was the key. Two distinct issues:

Empty zones (every zone shows 0 entries): the agent's payload used anchorEntries / summary / approximateCount, but the app read entryIds / why. The agent resolved real UUIDs correctly — they were silently dropped because entries_map_open typed map.zones as Array(Unknown), giving the model no field-name contract. Fixed in #1234: a typed EntryMapZoneSchema (with entry_ids required + documented) so the model knows the exact shape, a tolerant parser that also accepts the aliases it reached for, and regression tests built from your actual payload. (Also fixed the e2e fixture, which had been self-confirming — it hand-wrote the field name only the parser knew, so it could never have caught this.)

"Could not resolve the saved pack id": separate, and already fixed on main in #1233 — you confirmed this session was a pre-#1233 deploy. #1233 switched the pack-UUID lookup from a paginated packs_list scan to packs_provenance({ pack_cid }).rootPackId. Bumping the deployment to current main (or merging #1234, which is on top of it) resolves it. Verified green in the e2e save flow against the rebuilt stack.