From 551c3d1efc33ffe1379bbbb18a0521680dec7177 Mon Sep 17 00:00:00 2001
From: Jimmy <git@jimmy.nz>
Date: Sun, 14 Jun 2026 22:34:55 +1200
Subject: [PATCH] Add PyPI package installer, file-tree context menu, and demos
 UI

Expose micropip installs from the menu, right-click actions on the file
tree, local folder/file open shortcuts, and browse demos/ alongside code/.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/static/index.html    |   30 +-
 src/static/script.js     | 1496 +++++++++++++++++++++++++++++++++++---
 src/static/styles.css    |  194 +++++
 src/static/tutorial.html |    2 +-
 src/static/tutorial.js   |    2 +-
 5 files changed, 1616 insertions(+), 108 deletions(-)
diff --git a/src/static/index.html b/src/static/index.html
index f55663c..1404ed4 100644
--- a/src/static/index.html
+++ b/src/static/index.html
@@ -6,7 +6,7 @@
   <meta name="theme-color" content="#2d3748">
   <title>LED Editor</title>
   <link rel="icon" href="data:,">
-  <link rel="stylesheet" href="/static/styles.css?v=36">
+  <link rel="stylesheet" href="/static/styles.css?v=41">
 </head>
 <body>
   <div class="container">
@@ -26,6 +26,8 @@
       </div>
     </div>
 
+    <div id="file-tree-context-menu" class="file-tree-context-menu" role="menu" hidden aria-hidden="true"></div>
+
     <div class="main-content">
       <div class="editor-header">
         <button id="sidebar-toggle" class="sidebar-toggle" type="button" aria-label="Toggle file tree" aria-controls="sidebar" aria-expanded="true" title="Toggle file browser"><span class="sidebar-toggle-icon" aria-hidden="true">‹</span></button>
@@ -48,6 +50,9 @@
                 <input type="checkbox" id="panel-16x16-checkbox" />
                 16×16 panel
               </label>
+              <button type="button" class="menu-item menu-button" id="packages-menu-btn" role="menuitem">📦 Python packages…</button>
+              <button type="button" class="menu-item menu-button" id="menu-open-local-folder-btn" role="menuitem">📂 Open local folder…</button>
+              <button type="button" class="menu-item menu-button" id="menu-open-local-file-btn" role="menuitem">📄 Open local file…</button>
               <div class="menu-separator" role="separator"></div>
               <div class="menu-section-label" id="workspace-menu-label">Workspace</div>
               <div id="workspace-menu-actions" role="group"></div>
@@ -121,6 +126,27 @@
     </div>
   </div>
 
-  <script type="module" src="/static/script.js?v=59"></script>
+  <div id="packages-modal" class="modal">
+    <div class="modal-content packages-modal-content">
+      <h3>Python packages (Pyodide)</h3>
+      <p class="packages-modal-hint">Install from PyPI using micropip inside the browser. Pure-Python wheels (or packages built for WebAssembly) usually work; manylinux-only C extensions often do not.</p>
+      <label class="packages-field-label" for="packages-install-input">Package names or PEP 508 specs</label>
+      <input type="text" id="packages-install-input" placeholder="e.g. httpx, phonenumbers" autocomplete="off" />
+      <div id="packages-pypi-info" class="packages-pypi-info" aria-live="polite"></div>
+      <div class="packages-modal-actions-row">
+        <button type="button" id="packages-lookup-btn" class="packages-secondary-btn">Look up on PyPI</button>
+      </div>
+      <div id="packages-modal-status" class="packages-modal-status" aria-live="polite"></div>
+      <pre id="packages-install-log" class="packages-install-log hidden" aria-label="Micropip installer output"></pre>
+      <p class="packages-saved-label">Saved in this browser (restored when the editor loads Pyodide):</p>
+      <ul id="packages-saved-list" class="packages-saved-list"></ul>
+      <div class="modal-actions">
+        <button type="button" id="packages-install-btn">Install</button>
+        <button type="button" id="packages-close-btn">Close</button>
+      </div>
+    </div>
+  </div>
+
+  <script type="module" src="/static/script.js?v=83"></script>
 </body>
 </html>
diff --git a/src/static/script.js b/src/static/script.js
index 6c4418c..97064b2 100644
--- a/src/static/script.js
+++ b/src/static/script.js
@@ -1,12 +1,28 @@
 import { EditorView, basicSetup } from "https://esm.sh/codemirror";
 import { Compartment } from "https://esm.sh/@codemirror/state";
 import { python } from "https://esm.sh/@codemirror/lang-python";
-import { LocalWorkspaceClient, isLocalModeEnabled, exitLocalMode, supportsFolderPicker } from "/static/local-workspace.js?v=4";
+import { LocalWorkspaceClient, isLocalModeEnabled, exitLocalMode, supportsFolderPicker } from "/static/local-workspace.js?v=7";
 import { createZip, readZip } from "/static/zip-utils.js?v=2";
 
+/** Legacy browser-local paths (older sessions); new mounts use *-local at workspace root. */
+const BROWSER_LOCAL_LEGACY_ROOT = '__local__';
+const BROWSER_LOCAL_LEGACY_PREFIX = '__local__/';
+const BROWSER_LOCAL_SEG_CHANGE = '__change_folder__';
+const BROWSER_LOCAL_LEGACY_VIRTUAL = /(__change_folder__|__choose_folder__|__open_file__|__menu_hint__|__info_unsupported__)$/;
+const BROWSER_LOCAL_FOLDER_IDB_NAME = 'python-editor.browser-local-folder';
+const BROWSER_LOCAL_FOLDER_IDB_VER = 1;
+const BROWSER_LOCAL_FOLDER_IDB_STORE = 'folder';
+
 class TextEditor {
   constructor() {
     this.sessionStorageKey = 'python-editor.editor.session.v1';
+    /** PEP 508 specs installed via micropip; persisted in localStorage (see getPersistedMicropipPackages). */
+    this.micropipPackagesStorageKey = 'python-editor.micropip.packages.v1';
+    /** When true, worker stdout/stderr is appended to #packages-install-log during micropip installs. */
+    this.micropipInstallCaptureIo = false;
+    /** Briefly true after a worker run so late batched stdout still reaches the console. */
+    this.workerConsoleIoGrace = false;
+    this._workerConsoleIoGraceTimer = null;
     this.pyWorker = null;
     this.pyWorkerMsgId = 0;
     this.pyWorkerHandlers = new Map();
@@ -77,6 +93,11 @@ class TextEditor {
     this._claimedPins = new Set();
     this.localMode = isLocalModeEnabled();
     this.localWorkspace = this.localMode ? new LocalWorkspaceClient() : null;
+    this._browserLocalRootHandle = null;
+    /** Top-level directory name for the picked folder (e.g. `Photos-local`). */
+    this._browserLocalFolderMount = null;
+    this._browserLocalHandles = new Map();
+    this._onFileTreeContextMenuDismiss = null;
 
     this.init();
   }
@@ -119,12 +140,12 @@ class TextEditor {
     this.setLspStatus('LSP: n/a', 'Open a Python file for diagnostics');
     this.updateWorkspaceBanner();
     this.prewarmPyWorker();
-    this.fetchViewerRole()
-      .finally(() =>
-        this.loadInitialDirectoryState().then(() =>
-          this.restoreSessionTabs().then(() => this.ensureDefaultMainOpen())
-        )
-      );
+    this.fetchViewerRole().finally(() =>
+      this.loadInitialDirectoryState()
+        .then(() => this.restoreBrowserLocalFolderFromPersistence())
+        .then(() => this.restoreSessionTabs())
+        .then(() => this.ensureDefaultMainOpen()),
+    );
   }
 
   async fetchViewerRole() {
@@ -222,7 +243,7 @@ class TextEditor {
         menuActions.appendChild(
           makeMenuButton(
             '↻ Reset demos',
-            'Re-copy the bundled demos into code/ (overwrites your edits to those files)',
+            'Re-copy bundled demos into demos/ (overwrites your edits to those files)',
             () => this.resetDemoFiles(),
           ),
         );
@@ -293,7 +314,7 @@ class TextEditor {
       menuActions.appendChild(
         makeMenuButton(
           '↻ Reset demos',
-          'Re-copy the bundled demos into code/ (overwrites your edits to those files)',
+          'Re-copy bundled demos into demos/ (overwrites your edits to those files)',
           () => this.resetDemoFiles(),
         ),
       );
@@ -317,18 +338,21 @@ class TextEditor {
       this.showError('No demos in bundle');
       return;
     }
+    const demoBasename = (n) => (n.startsWith('demo/') ? n.slice(5) : n);
+    const editorDemoPath = (base) => `demos/${base}`;
     if (!confirm(
       `Reset ${names.length} demo file${names.length === 1 ? '' : 's'}?\n\n` +
-        names.map((n) => `  • code/${n}`).join('\n') +
-        '\n\nAny edits you made to these files will be overwritten. Other ' +
-        'files (main.py, your own scripts) are not touched.'
+        names.map((n) => `  • ${editorDemoPath(demoBasename(n))}`).join('\n') +
+        '\n\nAny edits you made to these files will be overwritten. ' +
+        'main.py, code/, and lib/ are not touched.'
     )) return;
 
     let written = 0;
     let failed = 0;
     for (const name of names) {
       try {
-        const r = await fetch(`/static/bundled-demos/${encodeURIComponent(name)}`, {
+        const urlPath = name.split('/').map(encodeURIComponent).join('/');
+        const r = await fetch(`/static/bundled-demos/${urlPath}`, {
           cache: 'no-store',
         });
         if (!r.ok) {
@@ -336,7 +360,9 @@ class TextEditor {
           continue;
         }
         const content = await r.text();
-        const w = await this.apiFetch(`/api/file/code/${encodeURIComponent(name)}`, {
+        const codeName = demoBasename(name);
+        const filePath = editorDemoPath(codeName);
+        const w = await this.apiFetch(`/api/file/${this.encodeApiFilePath(filePath)}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ content }),
@@ -355,10 +381,10 @@ class TextEditor {
     /* If a stale demo is currently open in a tab, refresh the editor
        contents from disk so the user sees the new version. */
     for (const name of names) {
-      const path = `code/${name}`;
+      const path = editorDemoPath(demoBasename(name));
       if (this.findTab(path)) {
         try {
-          const fr = await this.apiFetch(`/api/file/${encodeURIComponent(path)}`);
+          const fr = await this.apiFetch(`/api/file/${this.encodeApiFilePath(path)}`);
           if (fr && fr.ok) {
             const fd = await fr.json();
             const tab = this.findTab(path);
@@ -403,7 +429,7 @@ class TextEditor {
     }
     this.workspaceSourcesCache = null;
     this.directoryCache.clear();
-    this.expandedDirs = new Set(['', 'code']);
+    this.expandedDirs = new Set(['', 'code', 'demos']);
     await this.loadInitialDirectoryState();
     await this.updateWorkspaceBanner();
     this.showSuccess('Now saving to the picked folder');
@@ -420,7 +446,7 @@ class TextEditor {
     }
     this.workspaceSourcesCache = null;
     this.directoryCache.clear();
-    this.expandedDirs = new Set(['', 'code']);
+    this.expandedDirs = new Set(['', 'code', 'demos']);
     await this.loadInitialDirectoryState();
     await this.updateWorkspaceBanner();
     this.showSuccess('Storage: IndexedDB');
@@ -434,7 +460,7 @@ class TextEditor {
    */
   async _walkUserFiles() {
     const out = {};
-    const queue = ['code'];
+    const queue = ['code', 'demos'];
     while (queue.length) {
       const path = queue.shift();
       let resp;
@@ -456,7 +482,7 @@ class TextEditor {
           queue.push(child);
         } else {
           try {
-            const fr = await this.apiFetch(`/api/file/${encodeURIComponent(child)}`);
+            const fr = await this.apiFetch(`/api/file/${this.encodeApiFilePath(child)}`);
             if (fr && fr.ok) {
               const fd = await fr.json();
               out[child] = typeof fd.content === 'string' ? fd.content : '';
@@ -545,7 +571,7 @@ class TextEditor {
       const parts = raw.split('/').filter((seg) => seg && seg !== '.' && seg !== '..');
       if (!parts.length) continue;
       if (parts[0] === 'lib') continue;
-      if (parts[0] !== 'code') parts.unshift('code');
+      if (parts[0] !== 'code' && parts[0] !== 'demos') parts.unshift('code');
       const path = parts.join('/');
       safeEntries.push({ path, content: entry.content });
     }
@@ -557,14 +583,14 @@ class TextEditor {
     if (!confirm(
       `Import ${fileCount} file${fileCount === 1 ? '' : 's'} from "${file.name}"?\n\n` +
         `Existing files with the same path will be overwritten. ` +
-        `Files in lib/ are skipped.`
+        `Files in lib/ are skipped. Paths default to code/ unless they start with demos/.`
     )) return;
 
     let written = 0;
     let failed = 0;
     for (const entry of safeEntries) {
       try {
-        const r = await this.apiFetch(`/api/file/${encodeURIComponent(entry.path)}`, {
+        const r = await this.apiFetch(`/api/file/${this.encodeApiFilePath(entry.path)}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ content: entry.content }),
@@ -580,7 +606,7 @@ class TextEditor {
     }
     this.workspaceSourcesCache = null;
     this.directoryCache.clear();
-    this.expandedDirs = new Set(['', 'code']);
+    this.expandedDirs = new Set(['', 'code', 'demos']);
     await this.loadInitialDirectoryState();
     if (failed) {
       this.showError(`Imported ${written} file${written === 1 ? '' : 's'} (${failed} failed)`);
@@ -604,7 +630,7 @@ class TextEditor {
     }
     this.workspaceSourcesCache = null;
     this.directoryCache.clear();
-    this.expandedDirs = new Set(['', 'code']);
+    this.expandedDirs = new Set(['', 'code', 'demos']);
     await this.loadInitialDirectoryState();
     await this.updateWorkspaceBanner();
     this.showSuccess('Folder reconnected');
@@ -641,6 +667,13 @@ class TextEditor {
     poll();
   }
 
+  /** Build `/api/file/...` or `/api/folder/...` paths: encode each segment so `/` is not `%2F` (many servers reject that). */
+  encodeApiFilePath(relPath) {
+    const s = String(relPath || '').replace(/^\/+/, '');
+    if (!s) return '';
+    return s.split('/').map(encodeURIComponent).join('/');
+  }
+
   async apiFetch(url, init = {}) {
     if (this.localWorkspace && typeof url === 'string') {
       const local = await this.localWorkspace.dispatch(url, init);
@@ -670,6 +703,11 @@ class TextEditor {
   }
 
   disposePyWorker() {
+    if (this._workerConsoleIoGraceTimer) {
+      clearTimeout(this._workerConsoleIoGraceTimer);
+      this._workerConsoleIoGraceTimer = null;
+    }
+    this.workerConsoleIoGrace = false;
     for (const [, pending] of this.pyWorkerHandlers) {
       pending.reject(new Error('Worker terminated'));
     }
@@ -683,7 +721,7 @@ class TextEditor {
 
   ensurePyWorker() {
     if (!this.pyWorker) {
-      const worker = new Worker('/static/pyodide-worker.js?v=8');
+      const worker = new Worker('/static/pyodide-worker.js?v=24');
       this.pyWorker = worker;
       worker.onmessage = (event) => this.handlePyWorkerMessage(event);
     }
@@ -696,7 +734,20 @@ class TextEditor {
       return;
     }
     if (data.type === 'io') {
-      if (this.isPythonRunning) {
+      if (this.micropipInstallCaptureIo) {
+        const logEl = document.getElementById('packages-install-log');
+        const chunk = data.text || '';
+        if (logEl && chunk) {
+          const next = logEl.textContent + chunk;
+          logEl.textContent =
+            next.length > 64000 ? `…(truncated)\n${next.slice(next.length - 63000)}` : next;
+          logEl.scrollTop = logEl.scrollHeight;
+        }
+      }
+      if (
+        !this.micropipInstallCaptureIo &&
+        (this.isPythonRunning || this.workerConsoleIoGrace)
+      ) {
         const prefix = data.stream === 'stderr' ? '[stderr] ' : '';
         this.appendConsoleOutput([`${prefix}${data.text || ''}`]);
       }
@@ -728,12 +779,18 @@ class TextEditor {
     if (this.pyodideInited) {
       return;
     }
-    await this.callPyWorker('init', {
+    const initData = await this.callPyWorker('init', {
       adcSab: this.getAdcSab(),
       serialSab: this.getSerialSab(),
       pinOutSab: this.getPinOutSab(),
       pinInSab: this.getPinInSab(),
+      persistedMicropipPackages: this.getPersistedMicropipPackages(),
     });
+    if (initData && initData.micropipRestoreError) {
+      this.showError(
+        `Could not restore saved PyPI packages (editor still works): ${initData.micropipRestoreError}`,
+      );
+    }
     this.pyodideInited = true;
   }
 
@@ -830,6 +887,235 @@ class TextEditor {
       });
   }
 
+  getPersistedMicropipPackages() {
+    try {
+      const raw = localStorage.getItem(this.micropipPackagesStorageKey);
+      if (!raw) {
+        return [];
+      }
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? this.normalizePackageSpecList(parsed) : [];
+    } catch (_error) {
+      return [];
+    }
+  }
+
+  normalizePackageSpecList(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+      const t = typeof item === 'string' ? item.trim() : '';
+      if (!t) {
+        continue;
+      }
+      const key = t.toLowerCase();
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      out.push(t);
+    }
+    return out;
+  }
+
+  /** Split user input on commas or newlines (one spec per segment). */
+  parsePackageSpecsInput(text) {
+    const raw = String(text || '')
+      .split(/[,\n]+/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return this.normalizePackageSpecList(raw);
+  }
+
+  savePersistedMicropipPackages(specs) {
+    try {
+      const list = this.normalizePackageSpecList(specs);
+      localStorage.setItem(this.micropipPackagesStorageKey, JSON.stringify(list));
+    } catch (_error) {
+      // Ignore storage failures (private mode, quota).
+    }
+  }
+
+  pypiProjectNameFromInput(text) {
+    const first = String(text || '')
+      .split(/[,\n]+/)[0]
+      .trim();
+    if (!first) {
+      return '';
+    }
+    const base = first.split(/[\s\[<>=!]/)[0];
+    return (base || first).trim();
+  }
+
+  escapeHtml(str) {
+    return String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  renderPackagesSavedList() {
+    const ul = document.getElementById('packages-saved-list');
+    if (!ul) {
+      return;
+    }
+    const specs = this.getPersistedMicropipPackages();
+    if (!specs.length) {
+      ul.innerHTML = '<li class="packages-saved-empty">None yet</li>';
+      return;
+    }
+    ul.innerHTML = specs
+      .map(
+        (s) =>
+          `<li class="packages-saved-item"><span>${this.escapeHtml(s)}</span>` +
+          `<button type="button" class="packages-remove-btn" data-spec="${encodeURIComponent(s)}">Remove</button></li>`,
+      )
+      .join('');
+  }
+
+  showPackagesModal() {
+    const modal = document.getElementById('packages-modal');
+    const status = document.getElementById('packages-modal-status');
+    const info = document.getElementById('packages-pypi-info');
+    if (!modal) {
+      return;
+    }
+    if (status) {
+      status.textContent = '';
+    }
+    if (info) {
+      info.textContent = '';
+    }
+    const installLog = document.getElementById('packages-install-log');
+    if (installLog) {
+      installLog.textContent = '';
+      installLog.classList.add('hidden');
+    }
+    this.renderPackagesSavedList();
+    modal.style.display = 'block';
+    const input = document.getElementById('packages-install-input');
+    if (input) {
+      input.focus();
+    }
+  }
+
+  hidePackagesModal() {
+    const modal = document.getElementById('packages-modal');
+    if (modal) {
+      modal.style.display = 'none';
+    }
+  }
+
+  async removePersistedPackage(encodedSpec) {
+    let spec = encodedSpec;
+    try {
+      spec = decodeURIComponent(encodedSpec);
+    } catch (_e) {
+      // use raw
+    }
+    const next = this.getPersistedMicropipPackages().filter((s) => s !== spec);
+    this.savePersistedMicropipPackages(next);
+    this.renderPackagesSavedList();
+    this.disposePyWorker();
+    this.pyodideInited = false;
+    this.prewarmPyWorker();
+    this.showSuccess('Removed from saved list. Pyodide reloads in the background.');
+  }
+
+  async lookupPackageOnPyPI() {
+    const input = document.getElementById('packages-install-input');
+    const infoEl = document.getElementById('packages-pypi-info');
+    const name = this.pypiProjectNameFromInput((input && input.value) || '');
+    if (!name) {
+      this.showError('Enter a package name to look up');
+      return;
+    }
+    if (infoEl) {
+      infoEl.textContent = 'Loading…';
+    }
+    try {
+      const r = await fetch(`https://pypi.org/pypi/${encodeURIComponent(name)}/json`);
+      if (!r.ok) {
+        throw new Error('No such project on PyPI');
+      }
+      const j = await r.json();
+      const ver = j.info && j.info.version;
+      const sum = j.info && j.info.summary;
+      const bits = [name, ver ? `(latest: ${ver})` : '', sum ? `— ${sum}` : ''].filter(Boolean);
+      if (infoEl) {
+        infoEl.textContent = bits.join(' ');
+      }
+    } catch (err) {
+      if (infoEl) {
+        infoEl.textContent = '';
+      }
+      const msg = err && err.message ? err.message : String(err);
+      this.showError(`PyPI lookup failed: ${msg}`);
+    }
+  }
+
+  async installPackagesFromModal() {
+    const input = document.getElementById('packages-install-input');
+    const status = document.getElementById('packages-modal-status');
+    const btn = document.getElementById('packages-install-btn');
+    const text = (input && input.value) || '';
+    const newSpecs = this.parsePackageSpecsInput(text);
+    if (!newSpecs.length) {
+      this.showError('Enter at least one package name or version spec.');
+      return;
+    }
+    if (btn) {
+      btn.disabled = true;
+    }
+    const logEl = document.getElementById('packages-install-log');
+    if (logEl) {
+      logEl.textContent = '';
+      logEl.classList.remove('hidden');
+    }
+    if (status) {
+      status.textContent = 'Installing (may download from PyPI)…';
+    }
+    const t0 = typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now();
+    this.micropipInstallCaptureIo = true;
+    try {
+      await this.ensurePyodideReady();
+      await this.callPyWorker('micropipInstall', { specs: newSpecs });
+      const merged = this.normalizePackageSpecList([...this.getPersistedMicropipPackages(), ...newSpecs]);
+      this.savePersistedMicropipPackages(merged);
+      if (input) {
+        input.value = '';
+      }
+      const elapsedSec =
+        ((typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now()) - t0) /
+        1000;
+      const elapsed = elapsedSec < 10 ? elapsedSec.toFixed(2) : elapsedSec.toFixed(1);
+      if (status) {
+        const hasLog = logEl && logEl.textContent.trim();
+        status.textContent = hasLog
+          ? `Installed: ${newSpecs.join(', ')} (${elapsed}s). Installer output below.`
+          : `Installed: ${newSpecs.join(', ')} (${elapsed}s). No installer console output (often normal for tiny pure-Python wheels).`;
+      }
+      this.renderPackagesSavedList();
+      this.showSuccess('Packages installed');
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      const elapsedSec =
+        ((typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now()) - t0) /
+        1000;
+      const elapsed = elapsedSec < 10 ? elapsedSec.toFixed(2) : elapsedSec.toFixed(1);
+      if (status) {
+        status.textContent = `Install failed after ${elapsed}s.`;
+      }
+      this.showError(`Install failed: ${msg}`);
+    } finally {
+      this.micropipInstallCaptureIo = false;
+      if (btn) {
+        btn.disabled = false;
+      }
+    }
+  }
+
   loadSessionState() {
     try {
       const raw = localStorage.getItem(this.sessionStorageKey);
@@ -886,6 +1172,12 @@ class TextEditor {
       return;
     }
     for (const path of session.openTabPaths) {
+      if (this.isBrowserLocalPath(path) && !this.isBrowserLocalFilePath(path)) {
+        continue;
+      }
+      if (this.isBrowserLocalFilePath(path) && !this._browserLocalHandles.has(path)) {
+        continue;
+      }
       await this.openFile(path);
     }
     if (session.activeTabPath && this.findTab(session.activeTabPath)) {
@@ -914,7 +1206,12 @@ class TextEditor {
 
   async restoreExplorerState(session) {
     const expanded = Array.isArray(session.expandedDirs)
-      ? session.expandedDirs.filter((path) => typeof path === 'string')
+      ? session.expandedDirs.filter(
+          (path) =>
+            typeof path === 'string' &&
+            path !== BROWSER_LOCAL_LEGACY_ROOT &&
+            !path.startsWith(BROWSER_LOCAL_LEGACY_PREFIX),
+        )
       : [];
     this.expandedDirs = new Set(expanded.length ? expanded : ['']);
     if (!this.expandedDirs.has('')) {
@@ -923,16 +1220,19 @@ class TextEditor {
     this.selectedPath = typeof session.selectedPath === 'string' ? session.selectedPath : '';
     this.selectedIsDirectory = Boolean(session.selectedIsDirectory);
 
-    for (const path of this.expandedDirs) {
+    for (const path of [...this.expandedDirs]) {
       if (!path || this.directoryCache.has(path)) continue;
-      await this.loadDirectory(path, { suppressError: true });
+      const ok = await this.loadDirectory(path, { suppressError: true });
+      if (!ok && this.isBrowserLocalPath(path)) {
+        this.expandedDirs.delete(path);
+      }
     }
     this.renderFileTree();
   }
 
   getVisibleTopLevelNames() {
     /* lib is shared read-only for everyone; browsing is allowed, saves are blocked in API/UI. */
-    return new Set(['code', 'lib']);
+    return new Set(['code', 'demos', 'lib']);
   }
 
   getDefaultEditableRoot() {
@@ -942,10 +1242,13 @@ class TextEditor {
   async loadInitialDirectoryState() {
     await this.loadDirectory('');
     await this.ensureFolderExists('code');
+    await this.ensureFolderExists('demos');
     this.selectedPath = 'code';
     this.selectedIsDirectory = true;
     this.expandedDirs.add('code');
+    this.expandedDirs.add('demos');
     await this.loadDirectory('code', { suppressError: true });
+    await this.loadDirectory('demos', { suppressError: true });
     await this.loadDirectory('lib', { suppressError: true });
     this.renderFileTree();
   }
@@ -959,7 +1262,7 @@ class TextEditor {
       if (existing.status && existing.status !== 404) {
         return false;
       }
-      const response = await this.apiFetch(`/api/folder/new/${encodeURIComponent(folderPath)}`, {
+      const response = await this.apiFetch(`/api/folder/new/${this.encodeApiFilePath(folderPath)}`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ path: folderPath })
@@ -980,6 +1283,9 @@ class TextEditor {
     while (parts.length >= 2 && parts[0] === 'code' && parts[1] === 'code') {
       parts.shift();
     }
+    while (parts.length >= 2 && parts[0] === 'demos' && parts[1] === 'demos') {
+      parts.shift();
+    }
     return parts.join('/');
   }
 
@@ -988,6 +1294,711 @@ class TextEditor {
     this.expandedDirs = new Set(['']);
   }
 
+  ensureExpandedAncestorsForPath(relativePath, { isDirectory = false } = {}) {
+    if (!relativePath || typeof relativePath !== 'string') return;
+    this.expandedDirs.add('');
+    const parts = relativePath.split('/').filter(Boolean);
+    if (!parts.length) return;
+    const depth = isDirectory ? parts.length : Math.max(0, parts.length - 1);
+    let acc = '';
+    for (let i = 0; i < depth; i++) {
+      acc = acc ? `${acc}/${parts[i]}` : parts[i];
+      this.expandedDirs.add(acc);
+    }
+  }
+
+  pruneExpandedDirsAtAndUnder(prefix) {
+    if (!prefix || typeof prefix !== 'string') return;
+    const norm = prefix.replace(/\/+$/g, '');
+    for (const p of [...this.expandedDirs]) {
+      if (!p) continue;
+      if (p === norm || p.startsWith(`${norm}/`)) {
+        this.expandedDirs.delete(p);
+      }
+    }
+    this.expandedDirs.add('');
+  }
+
+  pathDepthForSort(p) {
+    if (!p) return 0;
+    return p.split('/').length;
+  }
+
+  async refreshFileTreePreservingExpansion(options = {}) {
+    const { pruneDeletedPrefix = null } = options;
+    if (pruneDeletedPrefix) {
+      this.pruneExpandedDirsAtAndUnder(pruneDeletedPrefix);
+    }
+    this.directoryCache.clear();
+    const sorted = Array.from(this.expandedDirs).sort((a, b) => {
+      const da = this.pathDepthForSort(a);
+      const db = this.pathDepthForSort(b);
+      if (da !== db) return da - db;
+      if (a < b) return -1;
+      if (a > b) return 1;
+      return 0;
+    });
+    for (const p of sorted) {
+      await this.loadDirectory(p, { suppressError: true, suppressRender: true });
+    }
+    this.renderFileTree();
+  }
+
+  browserLocalChangePath() {
+    return this._browserLocalFolderMount
+      ? `${this._browserLocalFolderMount}/${BROWSER_LOCAL_SEG_CHANGE}`
+      : null;
+  }
+
+  isBrowserLocalVirtualPath(path) {
+    if (!path || typeof path !== 'string') return false;
+    const ch = this.browserLocalChangePath();
+    if (ch && path === ch) return true;
+    if (BROWSER_LOCAL_LEGACY_VIRTUAL.test(path)) return true;
+    return false;
+  }
+
+  isBrowserLocalPath(path) {
+    if (!path || typeof path !== 'string') return false;
+    if (path === BROWSER_LOCAL_LEGACY_ROOT || path.startsWith(BROWSER_LOCAL_LEGACY_PREFIX)) return true;
+    if (this._browserLocalFolderMount) {
+      if (path === this._browserLocalFolderMount) return true;
+      if (path.startsWith(`${this._browserLocalFolderMount}/`)) return true;
+    }
+    if (!path.includes('/') && path.endsWith('-local')) {
+      return true;
+    }
+    return false;
+  }
+
+  isBrowserLocalFilePath(path) {
+    if (!path || this.isBrowserLocalVirtualPath(path)) return false;
+    const h = this._browserLocalHandles.get(path);
+    return Boolean(h && h.kind === 'file');
+  }
+
+  slugifyLocalMountBase(raw) {
+    let s = String(raw || '').trim() || 'folder';
+    s = s.replace(/[/\\:*?"<>|]+/g, '-').replace(/\s+/g, '-').replace(/-+/g, '-');
+    s = s.replace(/^-|-$/g, '') || 'folder';
+    return s.slice(0, 96);
+  }
+
+  rootTopLevelNameTaken(name) {
+    const rootFiles = this.directoryCache.get('') || [];
+    return rootFiles.some((f) => f && f.name === name);
+  }
+
+  allocateBrowserLocalFolderMount(rawName) {
+    const base = this.slugifyLocalMountBase(rawName);
+    let candidate = `${base}-local`;
+    let n = 2;
+    while (
+      candidate === 'code' ||
+      candidate === 'demos' ||
+      candidate === 'lib' ||
+      this.rootTopLevelNameTaken(candidate) ||
+      this._browserLocalHandles.has(candidate)
+    ) {
+      candidate = `${base}-${n}-local`;
+      n += 1;
+    }
+    return candidate;
+  }
+
+  allocateBrowserLocalFileMount(baseName) {
+    const base = this.slugifyLocalMountBase(baseName);
+    let candidate = `${base}-local`;
+    let n = 2;
+    const dot = baseName.lastIndexOf('.');
+    const stem = dot === -1 ? baseName : baseName.slice(0, dot);
+    const ext = dot === -1 ? '' : baseName.slice(dot);
+    while (
+      this._browserLocalHandles.has(candidate) ||
+      this.findTab(candidate) ||
+      candidate === this._browserLocalFolderMount ||
+      this.rootTopLevelNameTaken(candidate)
+    ) {
+      candidate = `${this.slugifyLocalMountBase(`${stem} (${n})${ext}`)}-local`;
+      n += 1;
+    }
+    return candidate;
+  }
+
+  formatBrowserLocalError(err) {
+    const msg = err && err.message ? err.message : String(err);
+    if (/aborted|cancel/i.test(msg)) return '';
+    if (/permission|not allowed|denied/i.test(msg)) {
+      return 'Permission was denied for local folder access. Choose the folder again if you need access.';
+    }
+    return `Local folder: ${msg}`;
+  }
+
+  showBrowserLocalUnsupportedHelp() {
+    this.showError(
+      'Opening local folders needs the File System Access API (Chromium: Chrome, Edge, Brave, Opera). ' +
+        'Firefox and Safari are not supported. The page must be served over HTTPS or from localhost. ' +
+        'In Brave, you may need to enable the File System Access API flag or relax Shields for this site.',
+    );
+  }
+
+  async browserLocalFolderIdbOpen() {
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open(BROWSER_LOCAL_FOLDER_IDB_NAME, BROWSER_LOCAL_FOLDER_IDB_VER);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(BROWSER_LOCAL_FOLDER_IDB_STORE)) {
+          db.createObjectStore(BROWSER_LOCAL_FOLDER_IDB_STORE);
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  async saveBrowserLocalFolderPersistence() {
+    if (!this._browserLocalFolderMount || !this._browserLocalRootHandle) return;
+    try {
+      const db = await this.browserLocalFolderIdbOpen();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(BROWSER_LOCAL_FOLDER_IDB_STORE, 'readwrite');
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.objectStore(BROWSER_LOCAL_FOLDER_IDB_STORE).put(
+          { mount: this._browserLocalFolderMount, handle: this._browserLocalRootHandle },
+          'saved',
+        );
+      });
+      db.close();
+    } catch (_e) {
+      // Ignore IDB failures (private mode, quota, etc.).
+    }
+  }
+
+  async clearBrowserLocalFolderPersistence() {
+    try {
+      const db = await this.browserLocalFolderIdbOpen();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(BROWSER_LOCAL_FOLDER_IDB_STORE, 'readwrite');
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.objectStore(BROWSER_LOCAL_FOLDER_IDB_STORE).delete('saved');
+      });
+      db.close();
+    } catch (_e) {
+      // Ignore.
+    }
+  }
+
+  async loadBrowserLocalFolderPersistenceRecord() {
+    try {
+      const db = await this.browserLocalFolderIdbOpen();
+      const rec = await new Promise((resolve, reject) => {
+        const tx = db.transaction(BROWSER_LOCAL_FOLDER_IDB_STORE, 'readonly');
+        const r = tx.objectStore(BROWSER_LOCAL_FOLDER_IDB_STORE).get('saved');
+        r.onsuccess = () => resolve(r.result || null);
+        r.onerror = () => reject(r.error);
+      });
+      db.close();
+      return rec;
+    } catch (_e) {
+      return null;
+    }
+  }
+
+  async restoreBrowserLocalFolderFromPersistence() {
+    if (!supportsFolderPicker() || typeof indexedDB === 'undefined') return;
+    const rec = await this.loadBrowserLocalFolderPersistenceRecord();
+    if (!rec || !rec.mount || !rec.handle || rec.handle.kind !== 'directory') {
+      await this.clearBrowserLocalFolderPersistence();
+      return;
+    }
+    if (this.rootTopLevelNameTaken(rec.mount)) {
+      await this.clearBrowserLocalFolderPersistence();
+      return;
+    }
+    let perm = 'granted';
+    try {
+      perm = rec.handle.queryPermission ? await rec.handle.queryPermission({ mode: 'read' }) : 'granted';
+    } catch (_e) {
+      perm = 'prompt';
+    }
+    if (perm === 'denied') {
+      await this.clearBrowserLocalFolderPersistence();
+      return;
+    }
+    if (perm === 'prompt') {
+      try {
+        perm = rec.handle.requestPermission ? await rec.handle.requestPermission({ mode: 'read' }) : 'denied';
+      } catch (_e) {
+        perm = 'denied';
+      }
+    }
+    if (perm !== 'granted') {
+      return;
+    }
+    this._browserLocalFolderMount = rec.mount;
+    this._browserLocalRootHandle = rec.handle;
+    this._browserLocalHandles.clear();
+    this._browserLocalHandles.set(rec.mount, rec.handle);
+    this.expandedDirs.add(rec.mount);
+    await this.loadBrowserLocalDirectory(rec.mount, { suppressError: true });
+  }
+
+  async pickBrowserLocalRootDirectory() {
+    if (!supportsFolderPicker()) {
+      this.showBrowserLocalUnsupportedHelp();
+      return;
+    }
+    try {
+      const handle = await window.showDirectoryPicker({
+        id: 'python-editor-local-browse',
+        mode: 'read',
+      });
+      const prevMount = this._browserLocalFolderMount;
+      for (const key of [...this.directoryCache.keys()]) {
+        if (
+          key.startsWith(BROWSER_LOCAL_LEGACY_PREFIX) ||
+          key === BROWSER_LOCAL_LEGACY_ROOT ||
+          (prevMount && (key === prevMount || key.startsWith(`${prevMount}/`))) ||
+          (!key.includes('/') && key.endsWith('-local'))
+        ) {
+          this.directoryCache.delete(key);
+        }
+      }
+      this._browserLocalHandles.clear();
+      const mount = this.allocateBrowserLocalFolderMount(handle.name);
+      this._browserLocalFolderMount = mount;
+      this._browserLocalRootHandle = handle;
+      this._browserLocalHandles.set(mount, handle);
+      this.expandedDirs.add(mount);
+      await this.loadBrowserLocalDirectory(mount, { suppressError: true });
+      await this.saveBrowserLocalFolderPersistence();
+      this.showSuccess(`Opened local folder as “${mount}” (read-only in the editor).`);
+    } catch (err) {
+      const msg = this.formatBrowserLocalError(err);
+      if (msg) this.showError(msg);
+    }
+  }
+
+  async changeBrowserLocalFolder() {
+    if (!supportsFolderPicker()) {
+      this.showBrowserLocalUnsupportedHelp();
+      return;
+    }
+    this.openTabs
+      .filter((tab) => this.isBrowserLocalFilePath(tab.path))
+      .forEach((tab) => this.closeTabWithoutPrompt(tab.path));
+    await this.clearBrowserLocalFolderPersistence();
+    const prevMount = this._browserLocalFolderMount;
+    this._browserLocalRootHandle = null;
+    this._browserLocalFolderMount = null;
+    this._browserLocalHandles.clear();
+    for (const key of [...this.directoryCache.keys()]) {
+      if (
+        key.startsWith(BROWSER_LOCAL_LEGACY_PREFIX) ||
+        key === BROWSER_LOCAL_LEGACY_ROOT ||
+        (prevMount && (key === prevMount || key.startsWith(`${prevMount}/`))) ||
+        (!key.includes('/') && key.endsWith('-local'))
+      ) {
+        this.directoryCache.delete(key);
+      }
+    }
+    if (prevMount) {
+      this.expandedDirs.delete(prevMount);
+    }
+    await this.pickBrowserLocalRootDirectory();
+  }
+
+  async removeBrowserLocalFolderConnection() {
+    if (!this._browserLocalFolderMount) {
+      return;
+    }
+    const label = this._browserLocalFolderMount;
+    if (
+      !confirm(
+        `Remove “${label}” from the file browser? Open tabs from that folder will close. Nothing is deleted on disk.`,
+      )
+    ) {
+      return;
+    }
+    await this.clearBrowserLocalFolderPersistence();
+    const prevMount = this._browserLocalFolderMount;
+    this.openTabs
+      .filter((tab) => tab.path === prevMount || tab.path.startsWith(`${prevMount}/`))
+      .forEach((tab) => this.closeTabWithoutPrompt(tab.path));
+    this._browserLocalRootHandle = null;
+    this._browserLocalFolderMount = null;
+    for (const k of [...this._browserLocalHandles.keys()]) {
+      if (k === prevMount || k.startsWith(`${prevMount}/`)) {
+        this._browserLocalHandles.delete(k);
+      }
+    }
+    for (const key of [...this.directoryCache.keys()]) {
+      if (key.startsWith(BROWSER_LOCAL_LEGACY_PREFIX) || key === BROWSER_LOCAL_LEGACY_ROOT) {
+        this.directoryCache.delete(key);
+      } else if (prevMount && (key === prevMount || key.startsWith(`${prevMount}/`))) {
+        this.directoryCache.delete(key);
+      }
+    }
+    this.expandedDirs.delete(prevMount);
+    this.selectedPath = null;
+    this.selectedIsDirectory = false;
+    this.renderFileTree();
+    this.showSuccess('Removed local folder from the editor.');
+  }
+
+  async removeBrowserLocalRootFileEntry(filePath) {
+    if (!filePath || filePath.includes('/') || !filePath.endsWith('-local')) {
+      return;
+    }
+    if (!this.isBrowserLocalFilePath(filePath)) {
+      return;
+    }
+    if (!confirm(`Remove “${filePath}” from the editor? The file on disk is not deleted.`)) {
+      return;
+    }
+    this._browserLocalHandles.delete(filePath);
+    if (this.findTab(filePath)) {
+      this.closeTabWithoutPrompt(filePath);
+    }
+    this.renderFileTree();
+    this.showSuccess('Removed local file from the editor.');
+  }
+
+  async closeLocalBrowserFileUnderFolder(filePath) {
+    if (!this.isBrowserLocalFilePath(filePath)) {
+      return;
+    }
+    const mount = this._browserLocalFolderMount;
+    if (!mount || !filePath.startsWith(`${mount}/`)) {
+      return;
+    }
+    if (!confirm(`Close “${filePath}” in the editor? The file on disk is not deleted.`)) {
+      return;
+    }
+    this._browserLocalHandles.delete(filePath);
+    if (this.findTab(filePath)) {
+      this.closeTabWithoutPrompt(filePath);
+    }
+    const parent = this.getParentDirectory(filePath);
+    if (parent) {
+      this.directoryCache.delete(parent);
+      await this.loadBrowserLocalDirectory(parent, { suppressError: true });
+    } else {
+      this.renderFileTree();
+    }
+    this.showSuccess('Removed from editor.');
+  }
+
+  hideFileTreeContextMenu() {
+    const menu = document.getElementById('file-tree-context-menu');
+    if (menu) {
+      menu.hidden = true;
+      menu.setAttribute('aria-hidden', 'true');
+      menu.innerHTML = '';
+      menu.style.left = '';
+      menu.style.top = '';
+    }
+    if (this._onFileTreeContextMenuDismiss) {
+      document.removeEventListener('pointerdown', this._onFileTreeContextMenuDismiss, true);
+      document.removeEventListener('keydown', this._onFileTreeContextMenuDismiss, true);
+      this._onFileTreeContextMenuDismiss = null;
+    }
+  }
+
+  setupFileTreeContextMenu() {
+    const tree = document.getElementById('file-tree');
+    if (!tree || tree.dataset.contextMenuBound === '1') {
+      return;
+    }
+    tree.dataset.contextMenuBound = '1';
+    tree.addEventListener('contextmenu', (e) => {
+      if (!tree.contains(e.target)) {
+        return;
+      }
+      e.preventDefault();
+      this.openFileTreeContextMenu(e);
+    });
+  }
+
+  openFileTreeContextMenu(e) {
+    const tree = document.getElementById('file-tree');
+    const menu = document.getElementById('file-tree-context-menu');
+    if (!tree || !menu) {
+      return;
+    }
+    this.hideFileTreeContextMenu();
+
+    const item = e.target.closest('.file-item');
+    let path = '';
+    let isDirectory = false;
+    if (item) {
+      path = item.dataset.path || '';
+      isDirectory = item.dataset.isDirectory === 'true';
+      this.selectedPath = path;
+      this.selectedIsDirectory = isDirectory;
+    } else {
+      this.selectedPath = 'code';
+      this.selectedIsDirectory = true;
+    }
+
+    const ch = this.browserLocalChangePath();
+    const isEmpty = !item;
+    const isLib = Boolean(path && (path === 'lib' || path.startsWith('lib/')));
+    const isProjectWritable = Boolean(
+      path &&
+        (path === 'code' ||
+          path.startsWith('code/') ||
+          path === 'demos' ||
+          path.startsWith('demos/')),
+    );
+    const isLocalChange = Boolean(ch && path === ch);
+    const isLocalMount = Boolean(this._browserLocalFolderMount && path === this._browserLocalFolderMount);
+    const isUnderLocal = Boolean(
+      this._browserLocalFolderMount &&
+        path &&
+        path.startsWith(`${this._browserLocalFolderMount}/`) &&
+        path !== ch,
+    );
+    const isLocalFile = this.isBrowserLocalFilePath(path);
+    const isRootLocalFile =
+      Boolean(path && !path.includes('/') && path.endsWith('-local')) && this.isBrowserLocalFilePath(path);
+
+    const frag = document.createDocumentFragment();
+    const addBtn = (label, onClick, opts = {}) => {
+      const b = document.createElement('button');
+      b.type = 'button';
+      b.setAttribute('role', 'menuitem');
+      b.textContent = label;
+      if (opts.danger) {
+        b.className = 'file-tree-cm-danger';
+      }
+      if (opts.disabled) {
+        b.disabled = true;
+      } else {
+        b.addEventListener('click', () => {
+          this.hideFileTreeContextMenu();
+          onClick();
+        });
+      }
+      frag.appendChild(b);
+    };
+    const addSep = () => {
+      const hr = document.createElement('hr');
+      hr.className = 'file-tree-cm-sep';
+      frag.appendChild(hr);
+    };
+    const addNote = (text) => {
+      const n = document.createElement('div');
+      n.className = 'file-tree-cm-note';
+      n.textContent = text;
+      frag.appendChild(n);
+    };
+    const refreshTree = () => {
+      this.refreshFileTreePreservingExpansion();
+    };
+
+    if (isLib) {
+      addNote('Shared library is read-only.');
+      addBtn('Refresh file tree', refreshTree);
+    } else if (isLocalChange || isLocalMount) {
+      if (typeof window.showOpenFilePicker === 'function') {
+        addBtn('Open local file…', async () => {
+          await this.pickBrowserLocalSingleFile();
+          this.renderFileTree();
+        });
+      }
+      addBtn('Change local folder…', async () => {
+        await this.changeBrowserLocalFolder();
+      });
+      addBtn('Remove local folder from editor…', () => this.removeBrowserLocalFolderConnection(), {
+        danger: true,
+      });
+    } else if (isUnderLocal) {
+      if (isLocalFile) {
+        addBtn('Remove from editor…', () => this.closeLocalBrowserFileUnderFolder(path), {
+          danger: true,
+        });
+      } else {
+        addNote('Local folders are read-only here.');
+        addBtn('Refresh this folder', async () => {
+          this.directoryCache.delete(path);
+          await this.loadBrowserLocalDirectory(path, { suppressError: true });
+        });
+      }
+    } else if (isRootLocalFile) {
+      addBtn('Remove local file from editor…', () => this.removeBrowserLocalRootFileEntry(path), {
+        danger: true,
+      });
+    } else if (isEmpty) {
+      addBtn('New file…', () => this.showNewFileModal());
+      addBtn('New folder…', () => this.createNewFolder());
+      addSep();
+      if (supportsFolderPicker()) {
+        addBtn('Open local folder…', async () => {
+          await this.pickBrowserLocalRootDirectory();
+          this.renderFileTree();
+        });
+      }
+      if (typeof window.showOpenFilePicker === 'function') {
+        addBtn('Open local file…', async () => {
+          await this.pickBrowserLocalSingleFile();
+          this.renderFileTree();
+        });
+      }
+      addSep();
+      addBtn('Refresh file tree', refreshTree);
+    } else if (isProjectWritable) {
+      addBtn('New file…', () => this.showNewFileModal());
+      addBtn('New folder…', () => this.createNewFolder(this.getNewFolderPromptDefault()));
+      addSep();
+      const canDel =
+        !((path === 'code' || path === 'demos') && isDirectory) && !this.isBrowserLocalVirtualPath(path);
+      addBtn('Delete…', () => this.deleteSelected(), { danger: true, disabled: !canDel });
+      addSep();
+      if (supportsFolderPicker() && !this._browserLocalFolderMount) {
+        addBtn('Open local folder…', async () => {
+          await this.pickBrowserLocalRootDirectory();
+          this.renderFileTree();
+        });
+      }
+      if (typeof window.showOpenFilePicker === 'function') {
+        addBtn('Open local file…', async () => {
+          await this.pickBrowserLocalSingleFile();
+          this.renderFileTree();
+        });
+      }
+      addBtn('Refresh file tree', refreshTree);
+    } else {
+      addBtn('Refresh file tree', refreshTree);
+    }
+
+    menu.appendChild(frag);
+    menu.hidden = false;
+    menu.removeAttribute('aria-hidden');
+    let x = e.clientX;
+    let y = e.clientY;
+    const pad = 6;
+    requestAnimationFrame(() => {
+      const rr = menu.getBoundingClientRect();
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      if (x + rr.width + pad > vw) {
+        x = Math.max(pad, vw - rr.width - pad);
+      }
+      if (y + rr.height + pad > vh) {
+        y = Math.max(pad, vh - rr.height - pad);
+      }
+      menu.style.left = `${x}px`;
+      menu.style.top = `${y}px`;
+    });
+
+    this._onFileTreeContextMenuDismiss = (ev) => {
+      const m = document.getElementById('file-tree-context-menu');
+      if (!m || m.hidden) {
+        return;
+      }
+      if (ev.type === 'keydown') {
+        if (ev.key === 'Escape') {
+          this.hideFileTreeContextMenu();
+        }
+        return;
+      }
+      if (ev.type === 'pointerdown' && ev.target instanceof Node && m.contains(ev.target)) {
+        return;
+      }
+      if (ev.type === 'pointerdown') {
+        this.hideFileTreeContextMenu();
+      }
+    };
+    setTimeout(() => {
+      document.addEventListener('pointerdown', this._onFileTreeContextMenuDismiss, true);
+      document.addEventListener('keydown', this._onFileTreeContextMenuDismiss, true);
+    }, 10);
+  }
+
+  async pickBrowserLocalSingleFile() {
+    if (typeof window.showOpenFilePicker !== 'function') {
+      this.showError('Single-file picker is not available in this browser.');
+      return;
+    }
+    try {
+      const picked = await window.showOpenFilePicker({ multiple: false });
+      const handle = picked && picked[0];
+      if (!handle || handle.kind !== 'file') return;
+      const baseName = handle.name || 'file';
+      const path = this.allocateBrowserLocalFileMount(baseName);
+      this._browserLocalHandles.set(path, handle);
+      await this.openFile(path);
+      if (this.isMobileViewport()) {
+        this.setMobileSidebarOpen(false);
+      }
+    } catch (err) {
+      const msg = this.formatBrowserLocalError(err);
+      if (msg) this.showError(msg);
+    }
+  }
+
+  async listBrowserLocalDirectory(dirPath) {
+    const handle = this._browserLocalHandles.get(dirPath);
+    if (!handle || handle.kind !== 'directory') {
+      return [];
+    }
+    const out = [];
+    for await (const [name, h] of handle.entries()) {
+      const fullPath = `${dirPath}/${name}`;
+      this._browserLocalHandles.set(fullPath, h);
+      if (h.kind === 'directory') {
+        out.push({ name, is_directory: true, size: null });
+      } else {
+        let size = null;
+        try {
+          const f = await h.getFile();
+          size = typeof f.size === 'number' ? f.size : null;
+        } catch (_e) {
+          size = null;
+        }
+        out.push({ name, is_directory: false, size });
+      }
+    }
+    out.sort((a, b) => {
+      if (a.is_directory !== b.is_directory) return a.is_directory ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+    return out;
+  }
+
+  async loadBrowserLocalDirectory(path, options = {}) {
+    const { suppressError = false, suppressRender = false } = options;
+    try {
+      if (path === this._browserLocalFolderMount) {
+        if (!this._browserLocalRootHandle || !this._browserLocalFolderMount) {
+          return false;
+        }
+        const ch = this.browserLocalChangePath();
+        const files = [
+          { name: '↻ Change folder…', is_directory: false, virtualPath: ch },
+          ...(await this.listBrowserLocalDirectory(path)),
+        ];
+        this.directoryCache.set(path, files);
+        if (!suppressRender) this.renderFileTree();
+        return true;
+      }
+      const inner = await this.listBrowserLocalDirectory(path);
+      this.directoryCache.set(path, inner);
+      if (!suppressRender) this.renderFileTree();
+      return true;
+    } catch (err) {
+      if (!suppressError) {
+        console.error('Local folder listing failed:', err);
+        const msg = this.formatBrowserLocalError(err);
+        if (msg) this.showError(msg);
+      }
+      return false;
+    }
+  }
+
   setupEditor() {
     this.editor = new EditorView({
       doc: '',
@@ -1091,7 +2102,11 @@ class TextEditor {
       await this.ensurePyodideReady();
       const extraFiles = await this.getWorkspacePythonSources();
       for (const tab of this.openTabs) {
-        if (tab.path && tab.path.toLowerCase().endsWith('.py')) {
+        if (
+          tab.path &&
+          tab.path.toLowerCase().endsWith('.py') &&
+          !this.isBrowserLocalPath(tab.path)
+        ) {
           extraFiles[tab.path] = tab.content;
         }
       }
@@ -1173,7 +2188,11 @@ class TextEditor {
       await this.ensurePyodideReady();
       const extraFiles = await this.getWorkspacePythonSources();
       for (const tab of this.openTabs) {
-        if (tab.path && tab.path.toLowerCase().endsWith('.py')) {
+        if (
+          tab.path &&
+          tab.path.toLowerCase().endsWith('.py') &&
+          !this.isBrowserLocalPath(tab.path)
+        ) {
           extraFiles[tab.path] = tab.content;
         }
       }
@@ -1416,7 +2435,7 @@ class TextEditor {
        takes over the screen) can halt without returning to the editor. */
     window.addEventListener('message', (event) => {
       const data = event && event.data;
-      if (data && data.type === 'neopixel-popup-stop' && this.isPythonRunning) {
+      if (data && data.type === 'neopixel-popup-stop') {
         this.stopPython();
       }
     });
@@ -1477,8 +2496,7 @@ class TextEditor {
     });
 
     document.getElementById('refresh-btn').addEventListener('click', () => {
-      this.resetDirectoryState();
-      this.loadDirectory(this.getTreeRootPath());
+      this.refreshFileTreePreservingExpansion();
     });
 
     document.getElementById('new-file-btn').addEventListener('click', () => {
@@ -1542,7 +2560,100 @@ class TextEditor {
       }
     });
 
+    const packagesMenuBtn = document.getElementById('packages-menu-btn');
+    if (packagesMenuBtn) {
+      packagesMenuBtn.addEventListener('click', () => {
+        const headerMenu = document.getElementById('header-menu');
+        if (headerMenu) {
+          headerMenu.open = false;
+        }
+        this.showPackagesModal();
+      });
+    }
+    const menuOpenLocalFolderBtn = document.getElementById('menu-open-local-folder-btn');
+    if (menuOpenLocalFolderBtn) {
+      menuOpenLocalFolderBtn.addEventListener('click', async (e) => {
+        /* Keep the user activation for showDirectoryPicker: do not close <details> first. */
+        e.preventDefault();
+        e.stopPropagation();
+        try {
+          await this.pickBrowserLocalRootDirectory();
+        } finally {
+          const headerMenu = document.getElementById('header-menu');
+          if (headerMenu) {
+            headerMenu.open = false;
+          }
+          this.renderFileTree();
+        }
+      });
+    }
+    const menuOpenLocalFileBtn = document.getElementById('menu-open-local-file-btn');
+    if (menuOpenLocalFileBtn) {
+      menuOpenLocalFileBtn.addEventListener('click', async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        try {
+          await this.pickBrowserLocalSingleFile();
+        } finally {
+          const headerMenu = document.getElementById('header-menu');
+          if (headerMenu) {
+            headerMenu.open = false;
+          }
+          this.renderFileTree();
+        }
+      });
+    }
+    const packagesCloseBtn = document.getElementById('packages-close-btn');
+    if (packagesCloseBtn) {
+      packagesCloseBtn.addEventListener('click', () => {
+        this.hidePackagesModal();
+      });
+    }
+    const packagesInstallBtn = document.getElementById('packages-install-btn');
+    if (packagesInstallBtn) {
+      packagesInstallBtn.addEventListener('click', () => {
+        this.installPackagesFromModal();
+      });
+    }
+    const packagesLookupBtn = document.getElementById('packages-lookup-btn');
+    if (packagesLookupBtn) {
+      packagesLookupBtn.addEventListener('click', () => {
+        this.lookupPackageOnPyPI();
+      });
+    }
+    const packagesInstallInput = document.getElementById('packages-install-input');
+    if (packagesInstallInput) {
+      packagesInstallInput.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          this.installPackagesFromModal();
+        }
+      });
+    }
+    const packagesModal = document.getElementById('packages-modal');
+    if (packagesModal) {
+      packagesModal.addEventListener('click', (e) => {
+        if (e.target.id === 'packages-modal') {
+          this.hidePackagesModal();
+        }
+      });
+    }
+    const packagesSavedList = document.getElementById('packages-saved-list');
+    if (packagesSavedList) {
+      packagesSavedList.addEventListener('click', (e) => {
+        const t = e.target.closest('.packages-remove-btn');
+        if (!t || !packagesSavedList.contains(t)) {
+          return;
+        }
+        const specEnc = t.getAttribute('data-spec');
+        if (specEnc) {
+          this.removePersistedPackage(specEnc);
+        }
+      });
+    }
+
     this.setupHeaderMenu();
+    this.setupFileTreeContextMenu();
 
     const runMainCheckbox = document.getElementById('run-main-checkbox');
     if (runMainCheckbox) {
@@ -1585,7 +2696,16 @@ class TextEditor {
     tabsContainer.innerHTML = this.openTabs.map((tab) => {
       const activeClass = tab.path === this.activeTabPath ? 'active' : '';
       const modifiedMark = tab.isModified ? '*' : '';
-      const displayPath = tab.path.startsWith('code/') ? tab.path.slice('code/'.length) : tab.path;
+      let displayPath = tab.path;
+      if (tab.path.startsWith('code/')) {
+        displayPath = tab.path.slice('code/'.length);
+      } else if (tab.path.startsWith('demos/')) {
+        displayPath = tab.path;
+      } else if (this._browserLocalFolderMount && tab.path.startsWith(`${this._browserLocalFolderMount}/`)) {
+        displayPath = tab.path.slice(this._browserLocalFolderMount.length + 1);
+      } else if (tab.path.startsWith(BROWSER_LOCAL_LEGACY_PREFIX)) {
+        displayPath = tab.path.slice(BROWSER_LOCAL_LEGACY_PREFIX.length);
+      }
       return `
         <div class="tab ${activeClass}" data-path="${tab.path}">
           <span class="tab-title">${displayPath}${modifiedMark}</span>
@@ -1617,7 +2737,9 @@ class TextEditor {
   }
 
   isReadOnlyPath(path) {
-    return typeof path === 'string' && path.startsWith('lib/');
+    if (typeof path !== 'string') return false;
+    if (path.startsWith('lib/')) return true;
+    return this.isBrowserLocalFilePath(path);
   }
 
   setEditorReadOnly(isReadOnly) {
@@ -1713,7 +2835,10 @@ class TextEditor {
   }
 
   async loadDirectory(path = "", options = {}) {
-    const { suppressError = false } = options;
+    if (this.isBrowserLocalPath(path)) {
+      return this.loadBrowserLocalDirectory(path, options);
+    }
+    const { suppressError = false, suppressRender = false } = options;
     try {
       const response = await this.apiFetch(`/api/files?path=${encodeURIComponent(path)}`);
       if (!response.ok) {
@@ -1721,7 +2846,7 @@ class TextEditor {
       }
       const data = await response.json();
       this.directoryCache.set(path, data.files || []);
-      this.renderFileTree();
+      if (!suppressRender) this.renderFileTree();
       return true;
     } catch (error) {
       if (!suppressError) {
@@ -1741,6 +2866,9 @@ class TextEditor {
       if (visibleNames) {
         rootFiles = rootFiles.filter((file) => visibleNames.has(file.name));
       }
+      if (this._browserLocalFolderMount && this._browserLocalRootHandle) {
+        rootFiles = [...rootFiles, { name: this._browserLocalFolderMount, is_directory: true }];
+      }
     }
 
     if (rootFiles.length === 0) {
@@ -1760,6 +2888,12 @@ class TextEditor {
         if (isDirectory && path) {
           await this.toggleDirectory(path);
         } else if (!isDirectory) {
+          const changePath = this.browserLocalChangePath();
+          if (changePath && path === changePath) {
+            await this.changeBrowserLocalFolder();
+            this.renderFileTree();
+            return;
+          }
           await this.openFile(path);
           this.renderFileTree();
           if (this.isMobileViewport()) {
@@ -1772,8 +2906,11 @@ class TextEditor {
     });
 
     fileTreeElement.querySelectorAll('.file-item').forEach((item) => {
-      item.setAttribute('draggable', 'true');
+      const p = item.dataset.path || '';
+      const noDrag = item.dataset.noDrag === 'true' || this.isBrowserLocalPath(p);
+      item.setAttribute('draggable', noDrag ? 'false' : 'true');
       item.addEventListener('dragstart', () => {
+        if (noDrag) return;
         this.draggedItemPath = item.dataset.path || null;
         this.draggedItemIsDirectory = item.dataset.isDirectory === 'true';
         item.classList.add('dragging-file');
@@ -1864,14 +3001,15 @@ class TextEditor {
     let html = "";
 
     for (const file of files) {
-      const fullPath = basePath ? `${basePath}/${file.name}` : file.name;
+      const fullPath = file.virtualPath || (basePath ? `${basePath}/${file.name}` : file.name);
       const isDir = file.is_directory;
       const selectedClass = this.selectedPath === fullPath ? "selected" : "";
       const indent = depth * 16;
       /* The top-level "code" folder is the user's editable root; show it as "/" while keeping the underlying path "code" for the API. */
-      const displayName = depth === 0 && !basePath && file.is_directory && file.name === 'code'
-        ? '/'
-        : file.name;
+      let displayName = file.name;
+      if (depth === 0 && !basePath && file.is_directory && file.name === 'code') {
+        displayName = '/';
+      }
 
       if (isDir) {
         const expanded = this.expandedDirs.has(fullPath);
@@ -1949,7 +3087,57 @@ class TextEditor {
         return;
       }
 
-      const response = await this.apiFetch(`/api/file/${encodeURIComponent(filePath)}`);
+      if (this.isBrowserLocalFilePath(filePath)) {
+        const handle = this._browserLocalHandles.get(filePath);
+        if (!handle || handle.kind !== 'file') {
+          this.showError(
+            'That local file is no longer available. Use ⋮ → Open local folder… again, or re-open the file.',
+          );
+          return;
+        }
+        const file = await handle.getFile();
+        const maxBytes = 4 * 1024 * 1024;
+        if (typeof file.size === 'number' && file.size > maxBytes) {
+          this.showError('That file is larger than 4MB; open a smaller file in the browser editor.');
+          return;
+        }
+        let content = '';
+        try {
+          content = await file.text();
+        } catch (readErr) {
+          const hint = this.formatBrowserLocalError(readErr);
+          this.showError(hint || 'Could not read that file (it may be binary or no longer permitted).');
+          return;
+        }
+        this.openTabs.push({
+          path: filePath,
+          content,
+          isModified: false,
+        });
+        this.activeTabPath = filePath;
+        this.currentFilePath = filePath;
+        this.ignoreNextChange = true;
+        this.editor.dispatch({
+          changes: {
+            from: 0,
+            to: this.editor.state.doc.length,
+            insert: content,
+          },
+        });
+        this.ignoreNextChange = false;
+        this.setLanguageForPath(filePath);
+        this.markAsSaved();
+        this.setEditorReadOnly(this.isReadOnlyPath(filePath));
+        const currentFileEl = document.getElementById('current-file');
+        if (currentFileEl) currentFileEl.textContent = filePath;
+        this.updateRunButtonState();
+        this.scheduleDiagnostics();
+        this.renderTabs();
+        this.saveSessionState();
+        return;
+      }
+
+      const response = await this.apiFetch(`/api/file/${this.encodeApiFilePath(filePath)}`);
       if (!response.ok) {
         throw new Error(`Failed to open file: ${response.statusText}`);
       }
@@ -1990,13 +3178,17 @@ class TextEditor {
   async saveFile() {
     if (!this.currentFilePath) return;
     if (this.isReadOnlyPath(this.currentFilePath)) {
-      this.showError('Files in lib are read-only');
+      this.showError(
+        this.isBrowserLocalFilePath(this.currentFilePath)
+          ? 'Local folder and picked files are read-only in this editor.'
+          : 'Files in lib are read-only',
+      );
       return;
     }
 
     try {
       const content = this.editor.state.doc.toString();
-      const response = await this.apiFetch(`/api/file/${encodeURIComponent(this.currentFilePath)}`, {
+      const response = await this.apiFetch(`/api/file/${this.encodeApiFilePath(this.currentFilePath)}`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json'
@@ -2024,6 +3216,10 @@ class TextEditor {
 
   async deleteFile() {
     if (!this.currentFilePath) return;
+    if (this.isBrowserLocalPath(this.currentFilePath)) {
+      this.showError('Deleting local disk files from the tree is not supported. Use your file manager.');
+      return;
+    }
 
     if (!confirm(`Are you sure you want to delete "${this.currentFilePath}"?`)) {
       return;
@@ -2031,7 +3227,7 @@ class TextEditor {
 
     try {
       const deletedPath = this.currentFilePath;
-      const response = await this.apiFetch(`/api/file/${encodeURIComponent(this.currentFilePath)}`, {
+      const response = await this.apiFetch(`/api/file/${this.encodeApiFilePath(this.currentFilePath)}`, {
         method: 'DELETE'
       });
 
@@ -2062,8 +3258,7 @@ class TextEditor {
         this.setLspStatus('LSP: n/a', 'Open a Python file for diagnostics');
       }
 
-      this.directoryCache.clear();
-      this.loadDirectory("");
+      await this.refreshFileTreePreservingExpansion();
       this.renderTabs();
       this.showSuccess('File deleted successfully');
     } catch (error) {
@@ -2107,7 +3302,9 @@ class TextEditor {
     const runMainCheckbox = document.getElementById('run-main-checkbox');
     const runMainSelected = Boolean(runMainCheckbox && runMainCheckbox.checked);
     const hasPythonFile = Boolean(this.currentFilePath && this.currentFilePath.toLowerCase().endsWith('.py'));
-    const canRun = runMainSelected || hasPythonFile;
+    const runnablePython =
+      hasPythonFile && !this.isBrowserLocalPath(this.currentFilePath);
+    const canRun = runMainSelected || runnablePython;
     runButton.disabled = !canRun;
     stopButton.disabled = !this.isPythonRunning;
     this.updateLedWindowControls();
@@ -2183,39 +3380,41 @@ class TextEditor {
           border: 1px solid rgba(255, 255, 255, 0.2);
           box-shadow: inset 0 0 8px rgba(0, 0, 0, 0.45);
         }
-        .stop-fab {
+        /* Match main editor #stop-btn.icon-btn (see styles.css .editor-actions) */
+        #led-popup-stop-btn.icon-btn {
           position: fixed;
-          top: max(20px, env(safe-area-inset-top));
-          right: max(20px, env(safe-area-inset-right));
-          width: clamp(120px, 18vmin, 200px);
-          height: clamp(120px, 18vmin, 200px);
-          border-radius: 999px;
-          border: 3px solid rgba(255, 255, 255, 0.35);
-          background: #c53030;
-          color: white;
-          font-size: clamp(2.5rem, 6vmin, 4rem);
-          line-height: 1;
-          cursor: pointer;
-          box-shadow: 0 12px 30px rgba(0, 0, 0, 0.55);
+          top: max(12px, env(safe-area-inset-top));
+          right: max(12px, env(safe-area-inset-right));
           z-index: 10;
+          font-size: 1rem;
+          line-height: 1;
+          padding: 0.5rem 0.75rem;
+          min-width: 40px;
+          border: 1px solid #e2e8f0;
+          background-color: white;
+          color: #c53030;
+          border-radius: 6px;
+          cursor: pointer;
+          font-family: system-ui, sans-serif;
+          transition: all 0.2s;
         }
-        .stop-fab:hover {
-          background: #9b2c2c;
+        #led-popup-stop-btn.icon-btn:hover:not(:disabled) {
+          background-color: #f7fafc;
+          border-color: #cbd5e0;
         }
-        .stop-fab:active {
-          transform: scale(0.96);
+        #led-popup-stop-btn.icon-btn:active:not(:disabled) {
+          background-color: #edf2f7;
         }
-        body.led-panel-popup-desktop .stop-fab {
-          display: none;
+        #led-popup-stop-btn.icon-btn:disabled {
+          opacity: 0.5;
+          cursor: not-allowed;
         }
       </style>
       <div id="grid" class="grid"></div>
-      <button id="stop-fab" class="stop-fab" type="button" aria-label="Stop" title="Stop">\u25A0</button>
+      <button id="led-popup-stop-btn" class="icon-btn" type="button" disabled aria-label="Stop" title="Stop">\u25A0</button>
     `;
-    if (!this.isMobileViewport()) {
-      win.document.body.classList.add('led-panel-popup-desktop');
-    }
-    win.document.getElementById('stop-fab')?.addEventListener('click', () => {
+    this.updateLedWindowControls();
+    win.document.getElementById('led-popup-stop-btn')?.addEventListener('click', () => {
       try {
         if (win.opener && !win.opener.closed) {
           win.opener.postMessage({ type: 'neopixel-popup-stop' }, '*');
@@ -2616,12 +3815,20 @@ class TextEditor {
   updateLedWindowControls() {
     const runBtn = document.getElementById('led-run-btn');
     const stopBtn = document.getElementById('led-stop-btn');
-    if (!runBtn || !stopBtn) return;
-    const runMainCheckbox = document.getElementById('run-main-checkbox');
-    const runMainSelected = Boolean(runMainCheckbox && runMainCheckbox.checked);
-    const hasPythonFile = Boolean(this.currentFilePath && this.currentFilePath.toLowerCase().endsWith('.py'));
-    runBtn.disabled = !(runMainSelected || hasPythonFile);
-    stopBtn.disabled = !this.isPythonRunning;
+    if (runBtn && stopBtn) {
+      const runMainCheckbox = document.getElementById('run-main-checkbox');
+      const runMainSelected = Boolean(runMainCheckbox && runMainCheckbox.checked);
+      const hasPythonFile = Boolean(this.currentFilePath && this.currentFilePath.toLowerCase().endsWith('.py'));
+      runBtn.disabled = !(runMainSelected || hasPythonFile);
+      stopBtn.disabled = !this.isPythonRunning;
+    }
+    const popup = this.ledPanelWindow;
+    if (popup && !popup.closed) {
+      const popupStop = popup.document.getElementById('led-popup-stop-btn');
+      if (popupStop) {
+        popupStop.disabled = !this.isPythonRunning;
+      }
+    }
   }
 
   renderLedSimulation(frame) {
@@ -2845,6 +4052,12 @@ class TextEditor {
   async runPython() {
     const runMainCheckbox = document.getElementById('run-main-checkbox');
     const selectedRunFile = runMainCheckbox && runMainCheckbox.checked ? 'code/main.py' : this.currentFilePath;
+    if (this.isBrowserLocalPath(selectedRunFile)) {
+      this.showError(
+        'The workspace runner cannot execute files from a local folder or *-local file tab. Open a file under code/ or demos/, or enable “Run main.py”.',
+      );
+      return;
+    }
     if (selectedRunFile && selectedRunFile !== this.currentFilePath && this.findTab(selectedRunFile)) {
       this.switchToTab(selectedRunFile);
     }
@@ -2853,6 +4066,7 @@ class TextEditor {
       return;
     }
 
+    let workerRunIssued = false;
     try {
       if (this.isPythonRunning) {
         await this.stopPython();
@@ -2868,7 +4082,11 @@ class TextEditor {
       const bundle = await bundleResp.json();
       const files = { ...(bundle.files || {}) };
       for (const tab of this.openTabs) {
-        if (tab.path && tab.path.toLowerCase().endsWith('.py')) {
+        if (
+          tab.path &&
+          tab.path.toLowerCase().endsWith('.py') &&
+          !this.isBrowserLocalPath(tab.path)
+        ) {
           files[tab.path] = tab.content;
         }
       }
@@ -2880,6 +4098,7 @@ class TextEditor {
       this.updateRunButtonState();
       const generation = ++this.pyRunGeneration;
       await this.ensurePyodideReady();
+      workerRunIssued = true;
       await this.callPyWorker('run', {
         files,
         mainPath: selectedRunFile,
@@ -2896,6 +4115,16 @@ class TextEditor {
       this.appendConsoleOutput([`\n${error.message}\n`]);
     } finally {
       this.isPythonRunning = false;
+      if (workerRunIssued) {
+        this.workerConsoleIoGrace = true;
+        if (this._workerConsoleIoGraceTimer) {
+          clearTimeout(this._workerConsoleIoGraceTimer);
+        }
+        this._workerConsoleIoGraceTimer = setTimeout(() => {
+          this.workerConsoleIoGrace = false;
+          this._workerConsoleIoGraceTimer = null;
+        }, 800);
+      }
       this.updateRunButtonState();
     }
   }
@@ -2921,6 +4150,18 @@ class TextEditor {
       this.showError('Select a file or folder first');
       return;
     }
+    if (this.selectedPath === 'code' && this.selectedIsDirectory) {
+      this.showError('The workspace root folder “code” cannot be deleted.');
+      return;
+    }
+    if (this.selectedPath === 'demos' && this.selectedIsDirectory) {
+      this.showError('The demos folder cannot be deleted.');
+      return;
+    }
+    if (this.isBrowserLocalPath(this.selectedPath)) {
+      this.showError('Local folder files are read-only. Delete or move them in your file manager instead.');
+      return;
+    }
     const targetType = this.selectedIsDirectory ? "folder" : "file";
     if (!confirm(`Delete ${targetType} "${this.selectedPath}"?`)) {
       return;
@@ -2928,8 +4169,8 @@ class TextEditor {
 
     try {
       const endpoint = this.selectedIsDirectory
-        ? `/api/folder/${encodeURIComponent(this.selectedPath)}`
-        : `/api/file/${encodeURIComponent(this.selectedPath)}`;
+        ? `/api/folder/${this.encodeApiFilePath(this.selectedPath)}`
+        : `/api/file/${this.encodeApiFilePath(this.selectedPath)}`;
       const response = await this.apiFetch(endpoint, { method: 'DELETE' });
       if (!response.ok) {
         throw new Error(`Failed to delete ${targetType}: ${response.statusText}`);
@@ -2945,10 +4186,15 @@ class TextEditor {
         this.closeTabWithoutPrompt(this.selectedPath);
       }
 
+      const deletedPath = this.selectedPath;
+      const wasDirectory = this.selectedIsDirectory;
       this.selectedPath = null;
       this.selectedIsDirectory = false;
-      this.resetDirectoryState();
-      this.loadDirectory(this.getTreeRootPath());
+      if (wasDirectory) {
+        await this.refreshFileTreePreservingExpansion({ pruneDeletedPrefix: deletedPath });
+      } else {
+        await this.refreshFileTreePreservingExpansion();
+      }
       this.showSuccess(`${targetType} deleted successfully`);
     } catch (error) {
       console.error(`Error deleting ${targetType}:`, error);
@@ -2966,9 +4212,32 @@ class TextEditor {
     if (!this.selectedPath) {
       return fallbackRoot;
     }
+    if (this.isBrowserLocalPath(this.selectedPath)) {
+      return fallbackRoot;
+    }
+    if (this.selectedPath === 'lib' || this.selectedPath.startsWith('lib/')) {
+      return fallbackRoot;
+    }
     return this.selectedIsDirectory ? this.selectedPath : this.getParentDirectory(this.selectedPath);
   }
 
+  getNewFolderPromptDefault() {
+    const base = this.getNewFileBasePath();
+    if (!base || base === 'code') {
+      return 'src/';
+    }
+    if (base.startsWith('code/')) {
+      return `${base.slice('code/'.length)}/`;
+    }
+    if (base === 'demos') {
+      return '';
+    }
+    if (base.startsWith('demos/')) {
+      return `${base.slice('demos/'.length)}/`;
+    }
+    return 'src/';
+  }
+
   showNewFileModal() {
     const basePath = this.getNewFileBasePath();
     const input = document.getElementById('new-filename');
@@ -3000,9 +4269,18 @@ class TextEditor {
         this.showError('Please enter a filename');
         return;
       }
-      const targetRoot = this.getDefaultEditableRoot();
-      const targetPath = `${targetRoot}/${cleanName}`;
-      const response = await this.apiFetch(`/api/file/${encodeURIComponent(targetPath)}`, {
+      const basePath = this.getNewFileBasePath() || this.getDefaultEditableRoot();
+      let targetPath;
+      if (
+        cleanName.startsWith('code/') ||
+        cleanName.startsWith('demos/') ||
+        cleanName.startsWith('lib/')
+      ) {
+        targetPath = cleanName;
+      } else {
+        targetPath = `${basePath}/${cleanName}`.replace(/\/+/g, '/');
+      }
+      const response = await this.apiFetch(`/api/file/${this.encodeApiFilePath(targetPath)}`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json'
@@ -3015,8 +4293,8 @@ class TextEditor {
       }
 
       this.hideNewFileModal();
-      this.resetDirectoryState();
-      this.loadDirectory(this.getTreeRootPath());
+      this.ensureExpandedAncestorsForPath(targetPath, { isDirectory: false });
+      await this.refreshFileTreePreservingExpansion();
       this.showSuccess('File created successfully');
     } catch (error) {
       console.error('Error creating file:', error);
@@ -3037,6 +4315,9 @@ class TextEditor {
     if (!sourcePath) {
       return;
     }
+    if (this.isBrowserLocalPath(sourcePath) || this.isBrowserLocalPath(destinationFolder)) {
+      return;
+    }
     if (sourcePath === destinationFolder) {
       return;
     }
@@ -3080,29 +4361,36 @@ class TextEditor {
         }
       }
 
-      this.directoryCache.clear();
-      this.expandedDirs.add('');
       this.renderTabs();
-      this.loadDirectory(this.getTreeRootPath());
+      await this.refreshFileTreePreservingExpansion();
       this.showSuccess('Path moved successfully');
     } catch (error) {
       this.showError(`Failed to move path: ${error.message}`);
     }
   }
 
-  async createNewFolder() {
-    const folderPath = prompt('Enter folder path (e.g., src/components)');
+  async createNewFolder(overrideSuggestedPath) {
+    const suggestion =
+      typeof overrideSuggestedPath === 'string' && overrideSuggestedPath.length
+        ? overrideSuggestedPath
+        : this.getNewFolderPromptDefault();
+    const folderPath = prompt('Enter folder path (under code/ or demos/)', suggestion);
     if (!folderPath) return;
     let cleanPath = this.normalizeRelativePathInput(folderPath);
     if (!cleanPath) {
       this.showError('Please enter a folder path');
       return;
     }
-    const targetRoot = this.getDefaultEditableRoot();
-    const targetPath = `${targetRoot}/${cleanPath}`;
+    const basePath = this.getNewFileBasePath() || this.getDefaultEditableRoot();
+    let targetPath;
+    if (cleanPath.startsWith('code/') || cleanPath.startsWith('demos/') || cleanPath.startsWith('lib/')) {
+      targetPath = cleanPath;
+    } else {
+      targetPath = `${basePath}/${cleanPath}`.replace(/\/+/g, '/');
+    }
 
     try {
-      const response = await this.apiFetch(`/api/folder/new/${encodeURIComponent(targetPath)}`, {
+      const response = await this.apiFetch(`/api/folder/new/${this.encodeApiFilePath(targetPath)}`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json'
@@ -3112,8 +4400,8 @@ class TextEditor {
       if (!response.ok) {
         throw new Error(`Failed to create folder: ${response.statusText}`);
       }
-      this.resetDirectoryState();
-      this.loadDirectory(this.getTreeRootPath());
+      this.ensureExpandedAncestorsForPath(targetPath, { isDirectory: true });
+      await this.refreshFileTreePreservingExpansion();
       this.showSuccess('Folder created successfully');
     } catch (error) {
       console.error('Error creating folder:', error);
diff --git a/src/static/styles.css b/src/static/styles.css
index b5c3fd9..08a88eb 100644
--- a/src/static/styles.css
+++ b/src/static/styles.css
@@ -138,6 +138,15 @@ button,
   background: #f7fafc;
 }
 
+button.menu-item.menu-button {
+  border: none;
+  background: transparent;
+  width: 100%;
+  text-align: left;
+  font: inherit;
+  font-family: inherit;
+}
+
 .menu-checkbox input[type="checkbox"] {
   margin: 0;
 }
@@ -239,6 +248,63 @@ button,
   padding: 0.5rem;
 }
 
+.file-tree-context-menu {
+  position: fixed;
+  z-index: 250;
+  min-width: 210px;
+  max-width: min(92vw, 300px);
+  background: #fff;
+  border: 1px solid #cbd5e0;
+  border-radius: 8px;
+  box-shadow: 0 10px 28px rgba(0, 0, 0, 0.16);
+  padding: 0.35rem 0;
+  font-size: 0.875rem;
+  color: #2d3748;
+}
+
+.file-tree-context-menu[hidden] {
+  display: none !important;
+}
+
+.file-tree-context-menu .file-tree-cm-note {
+  padding: 0.35rem 0.85rem 0.5rem;
+  font-size: 0.75rem;
+  color: #718096;
+  line-height: 1.35;
+}
+
+.file-tree-context-menu button {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.45rem 0.85rem;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  font: inherit;
+  color: inherit;
+}
+
+.file-tree-context-menu button:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.file-tree-context-menu button:hover:not(:disabled) {
+  background: #edf2f7;
+}
+
+.file-tree-context-menu button.file-tree-cm-danger {
+  color: #c53030;
+}
+
+.file-tree-context-menu hr.file-tree-cm-sep {
+  height: 1px;
+  margin: 0.3rem 0.5rem;
+  background: #e2e8f0;
+  border: none;
+}
+
 .file-item {
   padding: 0.5rem;
   cursor: pointer;
@@ -1126,6 +1192,134 @@ button,
   border-color: #2c5aa0;
 }
 
+.packages-modal-content {
+  width: min(440px, 92vw);
+  max-height: 85vh;
+  overflow-y: auto;
+  margin: 6% auto;
+}
+
+.packages-modal-hint {
+  font-size: 0.8rem;
+  color: #718096;
+  line-height: 1.45;
+  margin: 0 0 0.75rem;
+}
+
+.packages-field-label {
+  display: block;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: #64748b;
+  margin: 0.25rem 0 0.35rem;
+}
+
+.packages-pypi-info {
+  min-height: 1.2rem;
+  font-size: 0.85rem;
+  color: #334155;
+  margin: 0.15rem 0 0.5rem;
+}
+
+.packages-modal-actions-row {
+  margin-bottom: 0.65rem;
+}
+
+.packages-secondary-btn {
+  padding: 0.4rem 0.75rem;
+  border: 1px solid #cbd5e0;
+  background: #f8fafc;
+  color: #334155;
+  border-radius: 6px;
+  font-size: 0.8rem;
+  cursor: pointer;
+}
+
+.packages-secondary-btn:hover {
+  background: #edf2f7;
+}
+
+.packages-modal-status {
+  min-height: 1.25rem;
+  font-size: 0.85rem;
+  color: #2b6cb0;
+  margin-bottom: 0.5rem;
+}
+
+.packages-install-log {
+  max-height: 12rem;
+  overflow: auto;
+  margin: 0 0 0.65rem;
+  padding: 0.45rem 0.5rem;
+  font-size: 0.72rem;
+  line-height: 1.35;
+  color: #1e293b;
+  background: #f8fafc;
+  border: 1px solid #e2e8f0;
+  border-radius: 6px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.packages-saved-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: #64748b;
+  margin: 0 0 0.35rem;
+}
+
+.packages-saved-list {
+  list-style: none;
+  margin: 0 0 1rem;
+  padding: 0;
+  border: 1px solid #e2e8f0;
+  border-radius: 6px;
+  max-height: 10rem;
+  overflow-y: auto;
+}
+
+.packages-saved-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.4rem 0.55rem;
+  border-bottom: 1px solid #f1f5f9;
+  font-size: 0.85rem;
+  color: #2d3748;
+}
+
+.packages-saved-item:last-child {
+  border-bottom: none;
+}
+
+.packages-saved-item span {
+  word-break: break-all;
+}
+
+.packages-saved-empty {
+  padding: 0.55rem 0.65rem;
+  color: #94a3b8;
+  font-size: 0.85rem;
+}
+
+.packages-remove-btn {
+  flex-shrink: 0;
+  padding: 0.2rem 0.45rem;
+  font-size: 0.75rem;
+  border: 1px solid #e2e8f0;
+  background: white;
+  border-radius: 4px;
+  cursor: pointer;
+  color: #4a5568;
+}
+
+.packages-remove-btn:hover {
+  background: #fff5f5;
+  border-color: #feb2b2;
+  color: #c53030;
+}
+
 /* Desktop: hide the file browser when collapsed via the hamburger toggle. */
 @media (min-width: 769px) {
   .sidebar.is-collapsed {
diff --git a/src/static/tutorial.html b/src/static/tutorial.html
index 5b507d3..78c15e4 100644
--- a/src/static/tutorial.html
+++ b/src/static/tutorial.html
@@ -245,6 +245,6 @@
       </section>
     </div>
   </main>
-  <script type="module" src="/static/tutorial.js?v=2"></script>
+  <script type="module" src="/static/tutorial.js?v=4"></script>
 </body>
 </html>
diff --git a/src/static/tutorial.js b/src/static/tutorial.js
index 08df2f5..227afa8 100644
--- a/src/static/tutorial.js
+++ b/src/static/tutorial.js
@@ -289,7 +289,7 @@ class TutorialApp {
 
   ensurePyWorker() {
     if (!this.pyWorker) {
-      this.pyWorker = new Worker("/static/pyodide-worker.js?v=4");
+      this.pyWorker = new Worker("/static/pyodide-worker.js?v=24");
       this.pyWorker.onmessage = (event) => this.onWorkerMessage(event);
     }
     return this.pyWorker;
