Skip to content

Add the spaces core for the Stoa - #1

Closed
guohai wants to merge 16 commits into
mainfrom
feat/stoa-spaces
Closed

guohai wants to merge 16 commits into
mainfrom
feat/stoa-spaces

Conversation

@guohai

@guohai guohai commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Why

Agora.build is becoming a walkable virtual world built on resource discovery. This PR is Plan A of 5: the server side of Stoa spaces. The design is in docs/superpowers/specs/2026-10-07-stoa-spaces-design.md and the plan is in docs/superpowers/plans/2026-10-07-spaces-core.md.

What changes

  • Spaces model: visibility (listed, unlisted, private) and access (open, house, members) are separate settings, and one can() function checks every action.
  • Plaza: capacity 1000. When it is full, people are offered their unlisted spaces instead.
  • Lot rooms: six first-come rooms come from the map. The first person in becomes host and can set a topic with tags and decorate.
  • User-created spaces: unlisted or private, with hashed, expiring invitations and member lists. Basic plans get 3 spaces and Premium gets 20.
  • Entry leases: capacity and host handover are decided inside one store transaction, and expired leases are cleared on each write and by a 15-second sweeper.
  • Agora tokens:
    • RTC tokens go only to people currently inside a room.
    • Signaling tokens grant login only, so protection does not depend on Agora's per-channel permissions. Unlisted and private channel names are derived from a secret, each space has its own key, and both change when someone is removed.
  • Privacy: a private space a person can't see answers every operation, page and API with the same 404 as a missing space.
  • Maps: world/map.js is shared by browser and server (Tiled parsing, A* pathfinding, reachability). The generated plaza and room maps are in worlds/ (npm run maps).
  • HTTP and pages: routes in scripts/spaces/routes.mjs, /stoa pages (stoa.html is a placeholder until Plan C), and build and Docker output.
  • Configuration: .env.example adds SPACE_CHANNEL_SECRET, AGORA_RTM_PERMISSIONS and PLATFORM_ADMINS.

Existing meeting rooms are copied into spaces as unlisted, members-only spaces. /meet keeps working until Plan C adds the redirect.

Verification

  • rm -rf dist && npm test: 121 pass, 0 fail, 1 skipped (the skip predates this branch).
  • Built the Docker image and ran it: /stoa/ returned 200 and /api/spaces returned the plaza and six rooms.
  • Each task had a spec and code review, and the whole branch had a final review. Review fixes cover shared state in system spaces, 404 parity for private spaces, removing people a space no longer admits, rotating the channel when access tightens, and idle sweeps that no longer write.

Not in this PR

Follow-ups are listed at the end of the plan:

  • Plan B: the world engine and themes
  • Plan C: the walkable client and the /meet redirect
  • Plan D: Agora Chat
  • Plan E: discovery hooks
  • Moving leases out of the single state document before real plaza load

No visual changes yet, so there are no screenshots.

Generated with SMT smt@agora.build

guohai added 16 commits October 7, 2026 17:56
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
…istener safety

🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
@guohai

guohai commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

Replaced by #2, which includes this work (Plan A) together with Plans B, C1 and C2.

@guohai guohai closed this Oct 9, 2026
@guohai
guohai deleted the feat/stoa-spaces branch October 9, 2026 00:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant