[Salazareo]

Collaborative lists in Tasks were built on the assumption that Puter storage is strictly per-account and that there is no inbox:

• every participant published a replica of the list as a public read URL, valid for up to a year
• the owner kept a manifest of members
• joining took a two-link handshake

Puter's KV shares (HeyPuter/puter#4331) make that unnecessary, and they fix three problems with it:

• Anyone holding a replica or manifest link could read the list.
• Revoking a member didn't cut their access.
• Every join needed the manual confirmation step.

How it works now

• Data: the owner keeps the list in their own KV under tasks:collab:<id>:. That prefix holds meta (name, icon, colour, owner username), one t:<taskId> key per task, and one d:<taskId> tombstone per deletion. Each collaboration gets a fresh id, so restarting one never picks up keys or shares an earlier one left behind.
• Invite: the owner invites by Puter username. The first invite asks for consent, perms.request('kvShare', { prefix: 'tasks:collab:', access: 'write' }), or the permission string on older SDKs. The list is then shared at write, with its cleaned name as the label.
• Discovery: invitees find new lists through listShared() at startup, on the kv.share.received notice, and on focus or poll. No link is involved.
• Sync: reads and writes go through the handle and use the existing merge rules (ids, updatedAt, tombstones). Shared data can't touch other lists.
• Live updates: the owner watches kv:<appID>:<prefix>* and members watch kv:<handle>:*. Polling stays as a fallback.
  • A watched list still gets a sync every five minutes. Revoking a share stops its deliveries without ending the subscription, so only a sync shows that the handle is gone.
• Ending access: removing a member, stopping collaboration (revokes every share and clears the prefix) and leaving all go through unshare. A member whose handle stops working gets a private copy, the same as today's ended collaborations.

Compatibility

• New collaborations use KV shares where the SDK has kv.share.
• The old link protocol is used when the SDK lacks it, the page can't ask for consent, or the deployment has shares turned off. If shares turn out to be off on the first invite and nobody has joined yet, the sheet switches to the invite link.
• Lists already collaborating the old way stay on it, unchanged.
• To move one over, the owner stops collaborating and invites people again. Old lists aren't linked to new shares automatically: meta is writable by any member, so a former member could use it to take over someone's list.

Worth a look from reviewers

• Shared lists appear without an accept step, with a "X shared Y with you" toast. Puter lets a user block someone or stop accepting shares, but anyone can still put a list in a stranger's sidebar. If we'd rather have pending invitations, that's a follow-up.
• Only write shares are adopted; read and watch shares are ignored.
• The share label isn't updated on rename; members read the current name from meta.

Testing

• New tests/kvshare.test.js (24 tests) covers:
  • sharing, consent and denial, the deprecated permission string, and label cleaning
  • invite errors and discovery (no duplicates, second device, notification)
  • hostile meta and tampered keys
  • edits in both directions, conflicts and rename
  • live events, and a revoked share on a watched list
  • revoke, a dead handle becoming a private copy, stop, leave, a failed leave being retried, and re-invite
  • SDKs without shares, deployments with shares off, and an old-protocol list on a new SDK
• The fake Puter adds shares behind createMockPuter({ kvShares: true }). Holders are usernames, and errors are { message, code } without status, as the real API returns them.
• Full suite passes (235 tests), and npm run build succeeds. The owner flow was tried in Chrome with the dev mock (?kvshare); the member flow is covered by tests only.