Edits.

Author: ntoll

docs/faq.md

@@ -705,10 +705,10 @@ done"` message is written to the browser's console.
 
 Applications need third party packages and [PyScript can be configured to
 automatically install packages for you](user-guide/configuration/#packages).
-Yet packaging can be a complicated beast, so here are some
+Yet [packaging can be a complicated beast](#python-packages), so here are some
 hints for a painless packaging experience with PyScript.
 
-There are essentially four ways in which a third party package can become
+There are essentially five ways in which a third party package can become
 available in PyScript.
 
 1. The module is already part of either the Pyodide or MicroPython
@@ -724,10 +724,11 @@ available in PyScript.
 3. Reference hosted Python source files, to be included on the file
    system, via the [`files` setting](../user-guide/configuration/#files).
 4. Create a folder containing the package's files and sub folders, and create
-   a hosted `.zip` or `.tgz`/`.tar.gz`/`.whl` archive to be decompressed into the file
-   system (again, via the
+   a hosted `.zip` or `.tgz`/`.tar.gz`/`.whl` archive to be decompressed into
+   the file system (again, via the
    [`files` setting](../user-guide/configuration/#files)).
-5. provide your own `.whl` package as part of the `packages = [...]` list to see it available within your project
+5. Provide your own `.whl` package and reference it via a URL in the
+   `packages = [...]` list.
 
 #### Host a package
 
@@ -1207,19 +1208,23 @@ js.callback(
     )
 )
 ```
+!!! info
 
-Ultimately though, Pyodide maps can be consumed out of the box as literals, so that *some* required conversion might not be needed anymore and `to_js` might be enough, without specifying the `dict_converter` as that's inferred, once consumed, behind the scene.
+    Thanks to a
+    [recent change in Pyodide](https://github.com/pyodide/pyodide/pull/4576),
+    such `Map` instances are
+    [duck-typed](https://en.wikipedia.org/wiki/Duck_typing) to behave like
+    object literals. Conversion may not be needed anymore, and `to_js` may just
+    work without the need of the `dict_converter`. Please check.
 
-In addition, MicroPython's version of `to_js` takes the opposite approach (for
+MicroPython's version of `to_js` takes the opposite approach (for
 many of the reasons stated above) and converts Python dictionaries to object
 literals instead of `Map` objects.
 
 As a result, **the PyScript `pyscript.ffi.to_js` ALWAYS returns a JavaScript
 object literal by default when converting a Python dictionary** no matter if
 you're using Pyodide or MicroPython as your interpreter.
 
-That being said, in MicroPython things work closely to JS users' expectations, memory friendly too, so using the `to_js` is more a cross-interpreter guard than a necessity these days.
-
 #### Caveat
 
 !!! warning

docs/user-guide/builtins.md

@@ -573,13 +573,20 @@ sync.hello("PyScript")
 
 ### `pyscript.py_modules`
 
-Bootstrapping *Pyodide* or *MicroPython* with a lot of packages might degrade the time to readyness.
+!!! warning
+
+    **This is an experimental feature.**
 
-When some dependency is needed only under certain conditions or after some specific user action, we are offering an asynchronuos way to lazily import packages that were not present already in the *config*.
+    Feedback and bug reports are welcome!
 
-A bare minimal example of how this feature works can be summarized as such:
+If you have a lot of packages referenced in your configuration, startup
+performance may be degraded as these are downloaded.
 
-```html title="pyscript.py_modules example"
+If a package is only needed under certain circumstances, we provide an
+asynchronous way to import packages that were not originally referenced in your
+configuration.
+
+```html title="a pyscript.py_modules example"
 <script type="py" async>
 from pyscript import py_modules
 
@@ -589,8 +596,8 @@ print(matplotlib, regex)
 </script>
 ```
 
-The `py_modules` then returns an asynchronous tuple with one or more modules passed as string and it's compatible with `.whl` packages too.
-
+The `py_modules` call returns an asynchronous tuple containing the modules
+referenced as string arguments.
 
 ## HTML attributes
 

docs/user-guide/editor.md

@@ -18,7 +18,8 @@ contained therein in a non-blocking worker.
 
 !!! info
 
-    Once clicked, the *Run* button will show a spinner until the code is executed. This might not be visible if the code took nothing to execute, but if the code took any measurable time longer, one will notice such spinner before results will be shown.
+    Once clicked, the "run" button will show a spinner until the code is
+    executed. This may not be visible if the code evaluation completed quickly.
 
 
 The interpreter is not loaded onto the page until the run button is clicked. By
@@ -137,43 +138,40 @@ not expect the same behavior regular *PyScript* elements follow, most notably:
 
 ## Read / Write / Execute
 
-Behind the scene, we bootstrap an editor that provides:
-
-  * highlights around the Python code in it
-  * a Run button to execute the code
-  * a `target` reference where the code output lands, once printed
-
-This is all great and sound, but there is also a way to read the *editor* code, and update it with ease, that's the `code` accessor any editor gets, once bootstrapped:
+Sometimes you need to programatically read, write or execute code in an
+editor. Once PyScript has started, every py-editor/mpy-editor script tag gets
+a `code` accessor attached to it.
 
 ```python
 from pyscript import document
 
-# grab the editor script reference
+# Grab the editor script reference.
 editor = document.querySelector('#editor')
 
-# output its content
+# Output the live content of the editor.
 print(editor.code)
 
-# or update its content
+# Update the live content of the editor.
 editor.code = """
 a = 1
 b = 2
 print(a + b)
 """
-```
-
-To execute that new editor content a user might click the *Run* button one more time, or the driver of such editor can use `editor.process(editor.code)`, or any other arbitrary code, to actually bypass the need to click *Run* and execute the code passed along the `.process(...)` invoke.
 
-These utilities are helpful to let consumers of the editor change its view state and/or execute it out the box.
-
-## Config
-
-Differently from `<script type="py">` or `<py-script>`, and the `mpy` counterpart, a *PyEditor* is not affected by the presence of `<py-config>` elements in the page: it requires an explicit `config="..."` attribute to specify its dependencies, behavior and whatnot.
+# Evaluate the live code in the editor.
+# This could be any arbitrary code to evaluate in the editor's Python context.
+editor.process(editor.code)
+```
 
-If a `setup` editor is present though, that's the only *PyEditor* that needs a config, so that any further related editor will have already such config parsed and bootstrapped.
+## Configuration
 
-That is: do not expect `<py-config>` to dictate the behavior of a `py-editor`, these are *two different kind of custom script* so that an editor, when needed, must use a `config` attribute.
+Unlike `<script type="py">` or `<py-script>` (and the `mpy` equivalents), a
+PyEditor is not influenced by the presence of `<py-config>` elements in the
+page: it requires an explicit `config="..."` attribute.
 
+If a `setup` editor is present, that's the only PyEditor that needs a config.
+Any subsequent related editor will reuse the config parsed and bootstrapped for
+the `setup` editor.
 
 ## Still missing
 

docs/user-guide/terminal.md

@@ -153,20 +153,36 @@ may wish to use.
 
 ### MicroPython
 
-When it comes to *MicroPython*, we recently enabled a proper *REPL* mode that offers an easier way to have a fully functional terminal, including:
-
-  * all *Ctrl+X* strokes are handled, including *paste mode* and kill switches
-  * **history** works out of the box, *arrow up* and see what you pasted or typed before
-  * **tab completion** works too, *tab* away to see your previously referenced variables or available globals
-  * **copy and paste** improved, out of a singe terminal entry or a *paste mode* enabled variant
-
-In few words, the *MicroPython* terminal is somehow superior and broadly aligned with a regular *MicroPython terminal / REPL* experience, and strawberry on top, it works on both *main* thread and *worker* related one, and these are the differences:
-
-  * **main thread terminal**
-    * the `input` is, as blocking requirement, delegated to the native Web [prompt](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) utility
-    * there is no guard against blocking executing code, such as `while True:` loops and friends
-  * **worker thread terminal**
-    * full support for `input` directives without ever blocking the main thread or showing *prompt* blocking relates UI around
-    * `while True:` loops, or any other loop based, or blocking, directive, is handled out of the box without blocking the main thread UI
-
-In short, we still encourage the usage of `worker` attribute to bootstrap a *MicroPython* terminal, but fear not, the script without such attribute will not throw anymore on *input* calls and it will just work almost as fine out of the main thread as long as nothing is really blocking such thread execution.
+MicroPython has a
+[very complete REPL](https://docs.micropython.org/en/latest/reference/repl.html)
+already built into it.
+
+  * All `Ctrl+X` strokes are handled, including paste mode and kill switches.
+  * History works out of the box. Access this via the up and down arrows to
+    view your command history.
+  * Tab completion works like a charm. Use the `tab` key to see available
+    variables or objects in `globals`.
+  * Copy and paste is much improved. This is true for a single terminal entry,
+    or a
+    [paste mode](https://docs.micropython.org/en/latest/reference/repl.html#paste-mode)
+    enabled variant.
+
+As a bonus, the MicroPython terminal works on both the main thread and in
+web workers, with the following caveats:
+
+* **Main thread:**
+    * Calls to the blocking `input` function are delegated to the native browser
+      based
+      [prompt](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt)
+      utility.
+    * There are no guards against blocking code (e.g. `while True:` loops).
+      Such blocking code _could freeze your page_.
+* **Web worker:**
+    * Conventional support for the `input` function, without blocking the main
+      thread.
+    * Blocking code (e.g. `while True:` loops) does not block the main thread
+      and your page will remain responsive.
+
+We encourage the usage of `worker` attribute to bootstrap a MicroPython
+terminal. But now you have an option to run the terminal in the main thread.
+Just remember not to block!

docs/user-guide/workers.md

@@ -147,18 +147,17 @@ into the DOM and access some `window` based APIs.
       comes great responsibility... and we've given you a bazooka (so please
       remember not to shoot yourself in the foot with it).
 
-## PyWorker
+## Common Use Case
 
-It is possible to bootstrap either a *micropython* or a *pyodide* worker from either *micropython* or *pyodide* and within *Python* code.
+While it is possible to start a MicroPython or Pyodide worker from either
+MicroPython or Pyodide running on the main thread, the most common use case
+we have encountered is MicroPython on the main thread starting a Pyodide
+worker.
 
-Due different bootstrap time, the most common use case that is going to be tackled in here is *MicroPython* bootstrapping *Pyodide* out of *Python* code, underlying each step within the process.
+Here's how:
 
-#### Structure
-
-For highlight goodness and simplicity sake, we are going to use an `mpy` script on the main page, which points at a `main.py` file that bootstraps a `worker.py` file.
-
-**html**
-```HTML title="Pyodide worker via MicroPython"
+**index.html**
+```HTML title="Evaluate main.py via MicroPython on the main thread"
 <!DOCTYPE html>
 <html lang="en">
   <head>
@@ -176,48 +175,52 @@ For highlight goodness and simplicity sake, we are going to use an `mpy` script
 ```
 
 **main.py**
-```Python title="MicroPython bootstrapping a Pyodide worker"
+```Python title="MicroPython's main.py: bootstrapping a Pyodide worker."
 from pyscript import PyWorker, document
 
-# bootstrap the pyodide worker with optional config too
-# the worker here is:
-#   * owned by this script, no JS or Pyodide code in the same page can access it
-#   * it allows pre-sync methods exposure
-#   * it exposes a ready Promise to await pyodide on the worker side
-#   * it then allows using post-sync (utilities exposed by pyodide)
+# Bootstrap the Pyodide worker, with optional config too.
+# The worker is:
+#   * Owned by this script, no JS or Pyodide code in the same page can access
+#     it.
+#   * It allows pre-sync methods to be exposed.
+#   * It has a ready Promise to await for when Pyodide is ready in the worker. 
+#   * It allows the use of post-sync (methods exposed by Pyodide in the
+#     worker).
 worker = PyWorker("worker.py", type="pyodide")
 
-# expose an utility that can be invoke *out of the box* in worker.py
+# Expose a utility that can be immediately invoked in the worker. 
 worker.sync.greetings = lambda: print("Pyodide bootstrapped")
 
 print("before ready")
-# await for Pyodide to complete its bootstrap
+# Await until Pyodide has completed its bootstrap, and is ready.
 await worker.ready
 print("after ready")
 
-# await any exposed utility exposed via Pyodide
+# Await any exposed methods exposed via Pyodide in the worker.
 result = await worker.sync.heavy_computation()
 print(result)
 
-# show the result at the end of the body
+# Show the result at the end of the body.
 document.body.append(result)
 
-# here we free memory and get rid of everything
+# Free memory and get rid of everything in the worker.
 worker.terminate()
 ```
 
 **worker.py**
-```Python title="A Pyodide worker"
+```Python title="The worker.py script runs in the Pyodide worker."
 from pyscript import sync
 
-# use any already exposed utility from main.py
+# Use any methods from main.py on the main thread.
 sync.greetings()
 
-# expose any method meant to be used from main
+# Expose any methods meant to be used from main.
 sync.heavy_computation = lambda: 6 * 7
 ```
 
-Save these files in a *tmp* folder and use `npx mini-coi ./tmp` to reach out that `index.html` and see the following outcome in *devtools*:
+Save these files in a `tmp` folder, ensure [your headers](#http-headers) (just
+use `npx mini-coi ./tmp` and update `index.html`) then see the following
+outcome in the browser's devtools. 
 
 ```
 before ready