PR-119: Correct Fliplet.Socket docs for V3 apps and reconnects

[farhantariq12b]

JIRA Issue

https://weboo.atlassian.net/browse/PR-119

Summary

Corrects docs/API/fliplet-socket.md, the page the V3 AI builder reads for real-time features.

• States what the API does not do: store events, keep rooms private, log in app users, send events from App Actions, or remove a socket from a room.
• login option: works only for Fliplet Studio accounts. App users get loginError. Removed the claim that App Actions can push to user-<id> rooms.
• New "Joining rooms" section: rejoin on every connect (the server forgets rooms after a reconnect), include the app ID in room names, avoid the user- / app- / organization- prefixes Fliplet uses, no leave event.
• socket.to(room).emit(): the sender receives its own event; events sent while offline are held until the connection returns.
• Vue examples rewritten for V3 apps:
  • The old ones used <script setup> and import, which V3 apps can't run.
  • On the live site Jekyll stripped their {{ }}, leaving empty <li> templates.
  • The new examples are component objects with setup(), wrapped in {% raw %}, and keep the socket out of reactive state.
• Presence example replaced. The old one waited for a presence:update event that nothing sends; the new one uses a heartbeat.
• New "Native apps" section: starting offline, reconnects after backgrounding or network changes, events missed while away, and slow detection of devices that disappear.
• Frontmatter: description no longer says "auto-authentication"; removed the server push capability keyword.
• Regenerated .well-known and v3/capabilities.md. llms-full.txt also picks up AI doc changes already on master that hadn't been regenerated (API/core/ai.md, ai/chatbot.md and three other AI pages); no AI doc source changed here.

Merge after the API PR for the same ticket (https://github.com/Fliplet/fliplet-api/pull/8772) is deployed. That PR makes the socket log in again after a reconnect, which this page describes.

Testing

• node bin/build-agent-indexes.mjs --strict passes (frontmatter, capabilities, cross-links).

• npm run test:unit: 164 of 166 pass. The 2 failing files can't load jsdom (not installed in a fresh checkout) and test other docs.

• Every behavioral claim was tested against the local API (api.fliplet.test):

  Claim	Result
  connect fires again after a reconnect	yes
  Rooms survive a reconnect without rejoining	no
  Rejoining in connect restores delivery	yes
  Sender receives its own event when in the room	yes
  leave removes a socket from a room	no (no handler)
  A socket that never logged in can send to any room	yes
  Login with a session that has no Studio account	loginError 404 "User not found"
  Fliplet.Socket.disconnect()'d socket reconnects	no ("io client disconnect")

• The three Vue examples were run as written. They were extracted from the page and mounted in two Chrome tabs ("Alice" and "Bob") on a local V3 app preview:

  • each tab listed both people;
  • chat worked both ways, in the same order in both tabs;
  • after Bob's connection was forced to drop, his status went offline → online and he still received Alice's next message;
  • unmounting Bob's presence component removed him from Alice's list.

• Jekyll could not run locally (bundler version mismatch). The live V3 Vue guide uses the same {% raw %} wrapping and renders correctly; please check the Cloudflare preview for this page.

Testing notes

1. Open the Fliplet.Socket page on the PR preview site and scroll to the Vue examples → each example shows its template text, such as {{ person.name }} and {{ message.text }}, not an empty list item.
2. After this and the API change are live, ask the V3 AI builder for a simple live chat app, then open it in two browser tabs → each tab shows both people as online, and a message sent in one tab appears in the other within a second or two.
3. In that app, turn Wi-Fi off for 10 seconds and back on in one tab → it shows offline, then online, and messages from the other tab appear again without reloading.
4. Close one tab → within about a minute the other tab stops showing that person as online.

Risk Assessment

• Risk Level: LOW
• Files Modified: 1 doc + 6 generated index files
• Type: Docs

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying fliplet-cli with    Cloudflare Pages

Latest commit:	90b0703
Status:	✅  Deploy successful!
Preview URL:	https://0d82d41d.fliplet-cli.pages.dev
Branch Preview URL:	https://docs-pr-119-socket-docs.fliplet-cli.pages.dev

View logs