From e7be457a56b09c850ae6613482b5fbd896280be7 Mon Sep 17 00:00:00 2001
From: Juan Castro <jfcastro9208@gmail.com>
Date: Fri, 21 Aug 2026 11:26:32 -0400
Subject: [PATCH] docs: redirect the retired perms pages, add the missing
 playground examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both were left as follow-ups on the previous commit.

Thirteen `puter.perms` method pages went when the surface collapsed onto
`request(resource, details)`, and `requestAppData` moved to `/Perms/appData`.
All fourteen had shipped, so an external link or a bookmark landed on nothing.
The build already generates meta-refresh redirects from a map; they are entries
in it now. Pages that only ever existed on the branch that removed them are
deliberately absent — nobody can hold a link to a URL that was never published.

Six documented APIs annotated a code block with a playground id but had no
example file behind it, so the build warned on every one and the Try-it link
resolved to nothing: `fs.share`, `fs.unshare`, `fs.listShared`, `fs.getShares`,
`ai.txt2speech` with Speechify, and `ui.showFeedbackDialog`. The files are the
documented blocks themselves, extracted rather than rewritten, so the example
and the page it appears on cannot drift. Each is indexed in `examples.js` beside
its siblings.

The build now runs clean: 12 warnings to none.
---
 src/docs/src/examples.js                      | 36 +++++++++++++++++++
 .../examples/ai-txt2speech-speechify.html     | 19 ++++++++++
 .../src/playground/examples/fs-getShares.html | 16 +++++++++
 .../playground/examples/fs-listShared.html    | 14 ++++++++
 .../src/playground/examples/fs-share.html     | 15 ++++++++
 .../src/playground/examples/fs-unshare.html   | 14 ++++++++
 .../examples/ui-show-feedback-dialog.html     | 14 ++++++++
 src/docs/src/redirects.js                     | 20 +++++++++++
 8 files changed, 148 insertions(+)
 create mode 100644 src/docs/src/playground/examples/ai-txt2speech-speechify.html
 create mode 100644 src/docs/src/playground/examples/fs-getShares.html
 create mode 100644 src/docs/src/playground/examples/fs-listShared.html
 create mode 100644 src/docs/src/playground/examples/fs-share.html
 create mode 100644 src/docs/src/playground/examples/fs-unshare.html
 create mode 100644 src/docs/src/playground/examples/ui-show-feedback-dialog.html

diff --git a/src/docs/src/examples.js b/src/docs/src/examples.js
index 60a2c1328..7a86913ae 100644
--- a/src/docs/src/examples.js
+++ b/src/docs/src/examples.js
@@ -193,6 +193,12 @@ const examples = [
                 slug: 'ai-txt2speech-elevenlabs',
                 source: '/playground/examples/ai-txt2speech-elevenlabs.html',
             },
+            {
+                title: 'Text to Speech with Speechify',
+                description: 'Generate speech with Speechify voices using Puter.js AI API. Run and experiment with this TTS example in the playground.',
+                slug: 'ai-txt2speech-speechify',
+                source: '/playground/examples/ai-txt2speech-speechify.html',
+            },
             {
                 title: 'Text to Speech with Gemini',
                 description: 'Generate speech with Gemini voices using Puter.js AI API. Run and experiment with this TTS example in the playground.',
@@ -378,6 +384,30 @@ const examples = [
                 slug: 'fs-delete-directory',
                 source: '/playground/examples/fs-delete-directory.html',
             },
+            {
+                title: 'Share a file',
+                description: 'Share a file with another user using Puter.js filesystem API. Run and experiment with this sharing example in the playground.',
+                slug: 'fs-share',
+                source: '/playground/examples/fs-share.html',
+            },
+            {
+                title: 'Stop sharing a file',
+                description: 'Revoke a share with Puter.js filesystem API. Run and modify this example instantly in your browser.',
+                slug: 'fs-unshare',
+                source: '/playground/examples/fs-unshare.html',
+            },
+            {
+                title: 'List what is shared with you',
+                description: 'List items other people have shared with you using Puter.js filesystem API. Run and experiment with this example in the playground.',
+                slug: 'fs-listShared',
+                source: '/playground/examples/fs-listShared.html',
+            },
+            {
+                title: 'See who a file is shared with',
+                description: 'List the shares on one of your own files with Puter.js filesystem API. Run and modify this example in your browser.',
+                slug: 'fs-getShares',
+                source: '/playground/examples/fs-getShares.html',
+            },
         ],
     },
     {
@@ -713,6 +743,12 @@ const examples = [
                 slug: 'ui-set-menubar',
                 source: '/playground/examples/ui-set-menubar.html',
             },
+            {
+                title: 'Feedback dialog',
+                description: 'Collect feedback with the built-in dialog from the Puter.js UI API. Run and experiment with this example directly in the playground.',
+                slug: 'ui-show-feedback-dialog',
+                source: '/playground/examples/ui-show-feedback-dialog.html',
+            },
         ],
     },
     {
diff --git a/src/docs/src/playground/examples/ai-txt2speech-speechify.html b/src/docs/src/playground/examples/ai-txt2speech-speechify.html
new file mode 100644
index 000000000..1f17accce
--- /dev/null
+++ b/src/docs/src/playground/examples/ai-txt2speech-speechify.html
@@ -0,0 +1,19 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="play">Use Speechify voice</button>
+    <script>
+        document.getElementById('play').addEventListener('click', async ()=>{
+            const audio = await puter.ai.txt2speech(
+                "Hello! This sample uses the Speechify Geffen voice.",
+                {
+                    provider: "speechify",
+                    model: "simba-3.2",
+                    voice: "geffen_32"
+                }
+            );
+            audio.play();
+        });
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/fs-getShares.html b/src/docs/src/playground/examples/fs-getShares.html
new file mode 100644
index 000000000..43c71f4b8
--- /dev/null
+++ b/src/docs/src/playground/examples/fs-getShares.html
@@ -0,0 +1,16 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+            await puter.fs.share('report.txt', 'friend@example.com', 'read');
+
+            const shares = await puter.fs.getShares('report.txt');
+            for (const share of shares) {
+                puter.print(`${share.holder}: ${share.mode} (from ${share.issuer})<br>`);
+            }
+        })()
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/fs-listShared.html b/src/docs/src/playground/examples/fs-listShared.html
new file mode 100644
index 000000000..371f1428a
--- /dev/null
+++ b/src/docs/src/playground/examples/fs-listShared.html
@@ -0,0 +1,14 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            const page = await puter.fs.listShared({ includeTotal: true });
+            puter.print(`About ${page.total} item(s) shared with you<br>`);
+            for (const share of page.items) {
+                puter.print(`${share.path} — ${share.mode} from ${share.issuer}<br>`);
+            }
+        })()
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/fs-share.html b/src/docs/src/playground/examples/fs-share.html
new file mode 100644
index 000000000..2de299a13
--- /dev/null
+++ b/src/docs/src/playground/examples/fs-share.html
@@ -0,0 +1,15 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            // (1) create a file
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+
+            // (2) share it, read-only
+            const shares = await puter.fs.share('report.txt', 'friend@example.com');
+            puter.print(`Shared with ${shares[0].holder} as ${shares[0].mode}<br>`);
+        })()
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/fs-unshare.html b/src/docs/src/playground/examples/fs-unshare.html
new file mode 100644
index 000000000..511681983
--- /dev/null
+++ b/src/docs/src/playground/examples/fs-unshare.html
@@ -0,0 +1,14 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+            await puter.fs.share('report.txt', 'friend@example.com');
+
+            const result = await puter.fs.unshare('report.txt', 'friend@example.com');
+            puter.print(`Removed ${result.revoked} share(s)<br>`);
+        })()
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/ui-show-feedback-dialog.html b/src/docs/src/playground/examples/ui-show-feedback-dialog.html
new file mode 100644
index 000000000..82c60807b
--- /dev/null
+++ b/src/docs/src/playground/examples/ui-show-feedback-dialog.html
@@ -0,0 +1,14 @@
+<html>
+<body>
+    <button id="feedback">Send us feedback</button>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        document.getElementById('feedback').addEventListener('click', async () => {
+            const sent = await puter.ui.showFeedbackDialog();
+            if (sent) {
+                puter.print('Thanks for your feedback!');
+            }
+        });
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/redirects.js b/src/docs/src/redirects.js
index 19d2aa289..f25a26d13 100644
--- a/src/docs/src/redirects.js
+++ b/src/docs/src/redirects.js
@@ -1,5 +1,25 @@
 const redirects = {
     '/Introduction': '/',
+
+    // `puter.perms` collapsed one-method-per-task into `request(resource,
+    // details)`, so these pages went. Every one of them shipped, which is the
+    // reason for the redirect: an external link or a bookmark would otherwise
+    // land on nothing. Pages that only ever existed on the branch that removed
+    // them are deliberately absent — nobody could have a link to those.
+    '/Perms/requestAppData': '/Perms/appData',
+    '/Perms/requestEmail': '/Perms/request',
+    '/Perms/requestManageApps': '/Perms/request',
+    '/Perms/requestManageSubdomains': '/Perms/request',
+    '/Perms/requestReadApps': '/Perms/request',
+    '/Perms/requestReadDesktop': '/Perms/request',
+    '/Perms/requestReadDocuments': '/Perms/request',
+    '/Perms/requestReadPictures': '/Perms/request',
+    '/Perms/requestReadSubdomains': '/Perms/request',
+    '/Perms/requestReadVideos': '/Perms/request',
+    '/Perms/requestWriteDesktop': '/Perms/request',
+    '/Perms/requestWriteDocuments': '/Perms/request',
+    '/Perms/requestWritePictures': '/Perms/request',
+    '/Perms/requestWriteVideos': '/Perms/request',
 };
 
 module.exports = redirects;