Sync Puter.js types and docs

[reynaldichernando]

closes #3192
closes #3221
closes #3261

summary:

• add missing type definitions
• add jsdoc
• update outdated docs

notes

• for some they are intentionally left undocumented (internal) and having all of them will just confuse users
• we probably won't have 100% coverage right away for the jsdoc, but since we are regularly updating and polishing our types, this should be fine

[Copilot]

Pull request overview

Syncs the public puter.js SDK surface area by updating TypeScript declaration files and documentation pages to better match the current runtime behavior (including previously missing APIs and updated return shapes).

Changes:

• Expanded/adjusted SDK typings across AI, KV, FS, UI, Workers, Hosting, Apps, Auth, Perms, Peer, and Networking modules.
• Updated and added docs pages/examples to reflect current signatures, return values, and new objects (e.g., TTS engine/voice objects; streaming chat chunk shapes).
• Updated sidebar + Objects index to include newly documented object pages.

Reviewed changes

Copilot reviewed 46 out of 58 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/puter-js/types/modules/workers.d.ts	Adds JSDoc and overloads for workers; documents worker info/deployment types.
src/puter-js/types/modules/ui.d.ts	Adds extensive UI JSDoc/types; corrects/removes previously misleading/phantom members; adds connection event typing.
src/puter-js/types/modules/perms.d.ts	Adds missing request* permission request typings and JSDoc.
src/puter-js/types/modules/peer.d.ts	Adds docs/JSDoc for peer APIs and event payload types.
src/puter-js/types/modules/networking.d.ts	Improves socket API docs and corrects event payload typing.
src/puter-js/types/modules/kv.d.ts	Adds batch/object overload typings + richer option/result types and JSDoc.
src/puter-js/types/modules/hosting.d.ts	Refines hosting method signatures/return types and adds docs.
src/puter-js/types/modules/fs-item.d.ts	Updates FSItem docs/types and adds richer FSItem surface typing.
src/puter-js/types/modules/filesystem.d.ts	Adds detailed FS option typings and docs; updates some parameter/return documentation.
src/puter-js/types/modules/auth.d.ts	Adds docs for auth/user/usage types and updates Auth method typings.
src/puter-js/types/modules/apps.d.ts	Adds app/user iteration typings and richer app CRUD option/result typing.
src/puter-js/types/modules/ai.d.ts	Expands AI typing coverage (chat options, streaming chunks, TTS helpers, STT result fields, txt2img/txt2vid options).
src/docs/src/Workers/exec.md	Documents exec() accepting Fetch-compatible request inputs.
src/docs/src/Workers/create.md	Documents create() overloads and sandbox/app binding behavior.
src/docs/src/UI/showSaveFilePicker.md	Documents third type argument and content interpretation.
src/docs/src/UI/prompt.md	Updates cancel return value behavior in docs.
src/docs/src/UI/onItemsOpened.md	Marks onItemsOpened as deprecated and clarifies behavior.
src/docs/src/UI/on.md	Documents new connection broadcast payload.
src/docs/src/UI/notify.md	Documents type and duration notification options.
src/docs/src/UI/launchApp.md	Documents additional launchApp option fields (file_paths, items, pseudonym).
src/docs/src/UI/createWindow.md	Documents return value shape (window handle with id).
src/docs/src/UI/alert.md	Documents body_icon and icon fields for alerts.
src/docs/src/sidebar.js	Adds sidebar entries for new object docs (TTSEngine, TTSVoice).
src/docs/src/playground/examples/hosting-update.html	Updates hosting examples to pass a directory path and fixes cleanup call.
src/docs/src/playground/examples/hosting-get.html	Updates hosting example to pass a directory path.
src/docs/src/playground/examples/hosting-delete.html	Updates hosting example to pass a directory path and adjusts delete usage.
src/docs/src/playground/examples/ai-speech2txt.html	Updates example to match default Speech2TxtResult return shape.
src/docs/src/Objects/ttsvoice.md	Adds new TTSVoice object documentation page.
src/docs/src/Objects/ttsengine.md	Adds new TTSEngine object documentation page.
src/docs/src/Objects/speech2txtresult.md	Documents additional optional fields (duration, words).
src/docs/src/Objects/fsitem.md	Reworks FSItem docs and adds method documentation.
src/docs/src/Objects/chatresponsechunk.md	Documents streaming chunk discriminator and fields.
src/docs/src/Objects/chatresponse.md	Documents additional message fields (tool_call_id, cache_control, images).
src/docs/src/Objects/app.md	Documents app.users(pageSize) parameter.
src/docs/src/Objects.md	Adds TTSEngine/TTSVoice to the Objects index.
src/docs/src/Networking/TLSSocket.md	Corrects error callback payload docs to Error.
src/docs/src/Networking/Socket.md	Corrects error callback payload docs to Error.
src/docs/src/KV/update.md	Updates TTL naming and documents object-form update.
src/docs/src/KV/set.md	Documents batch/object forms of kv.set().
src/docs/src/KV/get.md	Corrects missing-key return from null to undefined.
src/docs/src/KV/flush.md	Corrects rejection behavior documentation.
src/docs/src/KV/add.md	Documents default behavior when value is omitted.
src/docs/src/Hosting/update.md	Updates hosting update docs and examples to require dirPath.
src/docs/src/Hosting/list.md	Updates hosting list example to pass a directory path.
src/docs/src/Hosting/get.md	Updates hosting get example to pass a directory path.
src/docs/src/Hosting/delete.md	Updates hosting delete return shape docs and examples.
src/docs/src/Hosting/create.md	Updates hosting create docs to require a directory path.
src/docs/src/Hosting.md	Updates hosting overview examples to pass a directory path and adjust delete usage.
src/docs/src/FS/upload.md	Corrects dedupeName default and overwrite interaction docs.
src/docs/src/FS/getReadURL.md	Updates expiresIn type/semantics docs.
src/docs/src/Auth/signIn.md	Documents rejection cases for popup-blocked / cancelled auth.
src/docs/src/Apps/delete.md	Updates delete return value shape docs.
src/docs/src/AI/txt2speech.md	Removes incorrect xAI max-length claim.
src/docs/src/AI/txt2speech.listVoices.md	Points return value to TTSVoice object docs.
src/docs/src/AI/txt2speech.listEngines.md	Points return value to TTSEngine object docs.
src/docs/src/AI/speech2txt.md	Clarifies streaming support and default return shape.
src/docs/src/AI/img2txt.md	Documents max input size.
src/docs/src/AI/chat.md	Updates verbosity option documentation to match runtime keys.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.