rapydscript-ns 0.8.3 → 0.9.0

package/README.md

@@ -6,11 +6,14 @@ RapydScript
 [![Current Release](https://img.shields.io/npm/v/rapydscript-ns)](https://www.npmjs.com/package/rapydscript-ns)
 [![Known Vulnerabilities](https://snyk.io/test/github/ficocelliguy/rapydscript-ns/badge.svg)](https://snyk.io/test/github/ficocelliguy/rapydscript-ns)
 
-This is a fork of the original RapydScript that adds many new (not always
-backwards compatible) features. For more on the forking, [see the bottom of this file](#reasons-for-the-fork)
-
+RapydScript is a pre-compiler for Javascript that uses syntax [identical](#python-feature-coverage) to modern Python. It transpiles 
+to native JS (with source maps) that reads like your Python code, but runs natively in the browser or node.
 [Try RapydScript-ns live via an in-browser REPL!](https://ficocelliguy.github.io/rapydscript-ns/)
 
+This is a [fork of the original RapydScript](#reasons-for-the-fork) that adds many new features. The most notable
+change is that all the Python features that are optional in RapydScript are now enabled by default.
+
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Contents**
@@ -41,6 +44,7 @@ backwards compatible) features. For more on the forking, [see the bottom of this
 - [Extended Subscript Syntax](#extended-subscript-syntax)
 - [Variable Type Annotations](#variable-type-annotations)
 - [Regular Expressions](#regular-expressions)
+- [JSX Support](#jsx-support)
 - [Creating DOM trees easily](#creating-dom-trees-easily)
 - [Classes](#classes)
   - [External Classes](#external-classes)
@@ -70,6 +74,7 @@ backwards compatible) features. For more on the forking, [see the bottom of this
     - [Virtual modules](#virtual-modules)
     - [Source maps](#source-maps)
     - [Running the tests](#running-the-tests)
+- [Python Feature Coverage](#python-feature-coverage)
 - [Reasons for the fork](#reasons-for-the-fork)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -82,20 +87,17 @@ RapydScript (pronounced 'RapidScript') is a pre-compiler for JavaScript,
 similar to CoffeeScript, but with cleaner, more readable syntax. The syntax is
 almost identical to Python, but RapydScript has a focus on performance and
 interoperability with external JavaScript libraries. This means that the
-JavaScript that RapydScript generates is performant and quite close to hand
+JavaScript that RapydScript generates is performant and quite close to hand-
 written JavaScript.
 
 RapydScript allows to write your front-end in Python without the overhead that
-other similar frameworks introduce (the performance is the same as with pure
-JavaScript). To those familiar with CoffeeScript, RapydScript is like
-CoffeeScript, but inspired by Python's readability rather than Ruby's
-cleverness. To those familiar with Pyjamas, RapydScript brings many of the same
-features and support for Python syntax without the same overhead. Don't worry
-if you've never used either of the above-mentioned compilers, if you've ever
-had to write your code in pure JavaScript you'll appreciate RapydScript.
-RapydScript combines the best features of Python as well as JavaScript,
-bringing you features most other Pythonic JavaScript replacements overlook.
-Here are a few features of RapydScript:
+other similar frameworks introduce - the performance is the same as with pure
+JavaScript. To those familiar with CoffeeScript, RapydScript is similar, but 
+inspired by Python's readability rather than Ruby's cleverness. To those familiar
+with Pyjamas, RapydScript brings many of the same features and support for Python
+syntax without the same overhead. RapydScript combines the best features of Python
+as well as JavaScript, bringing you features most other Pythonic JavaScript 
+replacements overlook. Here are a few features of RapydScript:
 
 - classes that work and feel similar to Python
 - an import system for modules/packages that works just like Python's
@@ -445,7 +447,6 @@ Class decorators are also supported with the caveat that the class properties
 must be accessed via the prototype property. For example:
 
 ```py
-
 def add_x(cls):
 	cls.prototype.x = 1
 
@@ -698,6 +699,29 @@ head, *mid, tail = [1, 2, 3, 4, 5] # head=1, mid=[2, 3, 4], tail=5
 
 Starred assignment works with any iterable, including generators and strings (which are unpacked character by character). The starred variable always receives a list, even if it captures zero elements.
 
+**Explicit tuple literals** using parentheses work the same as in Python and compile to JavaScript arrays:
+
+```py
+empty   = ()            # []
+single  = (42,)         # [42]  — trailing comma required for single-element tuple
+pair    = (1, 2)        # [1, 2]
+triple  = ('a', 'b', 'c')  # ['a', 'b', 'c']
+nested  = ((1, 2), (3, 4))  # [[1, 2], [3, 4]]
+```
+
+A parenthesised expression without a trailing comma is **not** a tuple — `(x)` is just `x`.  Add a comma to make it one: `(x,)`.
+
+Tuple literals work naturally everywhere arrays do: as return values, function arguments, in `isinstance` checks, and in destructuring assignments:
+
+```py
+def bounding_box(points):
+    return (min(p[0] for p in points), max(p[0] for p in points))
+
+ok  = isinstance(value, (int, str))   # tuple of types
+
+(a, b), c = (1, 2), 3
+```
+
 Operators and keywords
 ------------------------
 
@@ -805,9 +829,9 @@ No special flag is required. The `+` operator compiles to a lightweight helper
 
 Sets in RapydScript are identical to those in python. You can create them using
 set literals or comprehensions and all set operations are supported. You can
-store any object in a set, the only caveat is that RapydScript does not support
-the ``__hash__()`` method, so if you store an arbitrary object as opposed to a
-primitive type, object equality will be via the ``is`` operator.
+store any object in a set. For primitive types (strings, numbers) the value is
+used for equality; for class instances, object identity (``is``) is used by
+default unless the class defines a ``__hash__`` method.
 
 Note that sets are not a subclass of the ES 6 JavaScript Set object, however,
 they do use this object as a backend, when available. You can create a set from
@@ -835,8 +859,8 @@ a in s  # True
 [1, 2] in s # False
 ```
 
-This is because, as noted above, object equality is via the ```is```
-operator, not hashes.
+This is because list identity (not value) determines set membership for mutable
+objects. Define ``__hash__`` on your own classes to control set/dict membership.
 
 ### Dicts
 
@@ -855,11 +879,11 @@ differences between RapydScript dicts and Python dicts.
       RapydScript dict objects in ```for..in``` loops.
 
 Fortunately, there is a builtin ```dict``` type that behaves just like Python's
-```dict``` with all the same methods. The only caveat is that you have to add
-a special line to your RapydScript code to use these dicts, as shown below:
+```dict``` with all the same methods. The ``dict_literals`` and
+``overload_getitem`` flags are **on by default**, so dict literals and the
+``[]`` operator already behave like Python:
 
 ```py
-from __python__ import dict_literals, overload_getitem
 a = {1:1, 2:2}
 a[1]  # == 1
 a[3] = 3
@@ -867,17 +891,10 @@ list(a.keys()) == [1, 2, 3]
 a['3'] # raises a KeyError as this is a proper python dict, not a JavaScript object
 ```
 
-The special line, called a *scoped flag* tells the compiler that from
-that point on, you want it to treat dict literals and the getitem operator `[]`
-as they are treated in python, not JavaScript. 
-
-The scoped flags are local to each scope, that means that if you use it in a
-module, it will only affect code in that module, it you use it in a function,
-it will only affect code in that function. In fact, you can even use it to
-surround a few lines of code, like this:
+These are *scoped flags* — local to the scope where they appear. You can
+disable them for a region of code using the ``no_`` prefix:
 
 ```py
-from __python__ import dict_literals, overload_getitem
 a = {1:1, 2:2}
 isinstance(a, dict) == True
 from __python__ import no_dict_literals, no_overload_getitem
@@ -885,6 +902,63 @@ a = {1:1, 2:2}
 isinstance(a, dict) == False # a is a normal JavaScript object
 ```
 
+### List spread literals
+
+RapydScript supports Python's `*expr` spread syntax inside list literals.
+One or more `*expr` items can appear anywhere, interleaved with ordinary
+elements:
+
+```py
+a = [1, 2, 3]
+b = [4, 5]
+
+# Spread at the end
+result = [0, *a]            # [0, 1, 2, 3]
+
+# Spread in the middle
+result = [0, *a, *b, 6]     # [0, 1, 2, 3, 4, 5, 6]
+
+# Copy a list
+copy = [*a]                 # [1, 2, 3]
+
+# Unpack a string
+chars = [*'hello']          # ['h', 'e', 'l', 'l', 'o']
+```
+
+Spread works on any iterable (lists, strings, generators, `range()`).
+The result is always a new Python list.  Translates to JavaScript's
+`[...expr]` spread syntax.
+
+### Set spread literals
+
+The same `*expr` syntax works inside set literals `{...}`:
+
+```py
+a = [1, 2, 3]
+b = [3, 4, 5]
+
+s = {*a, *b}                # set([1, 2, 3, 4, 5]) — duplicates removed
+s2 = {*a, 10}               # set([1, 2, 3, 10])
+```
+
+Translates to `ρσ_set([...a, ...b])`.
+
+### `**expr` in function calls
+
+`**expr` in a function call now accepts any expression, not just a plain
+variable name:
+
+```py
+def f(x=0, y=0):
+    return x + y
+
+opts = {'x': 10, 'y': 20}
+f(**opts)                   # 30  (variable — always worked)
+f(**{'x': 1, 'y': 2})      # 3   (dict literal)
+f(**cfg.defaults)           # uses attribute access result
+f(**get_opts())             # uses function call result
+```
+
 ### Dict merge literals
 
 RapydScript supports Python's `{**d1, **d2}` dict merge (spread) syntax.
@@ -904,11 +978,10 @@ result = {**defaults, 'weight': 5}
 # result == {'color': 'blue', 'size': 10, 'weight': 5}
 ```
 
-This works for both plain JavaScript-object dicts (the default) and Python
-`dict` objects (enabled via `from __python__ import dict_literals`):
+This works for both plain JavaScript-object dicts and Python `dict` objects
+(``dict_literals`` is on by default):
 
 ```py
-from __python__ import dict_literals, overload_getitem
 pd1 = {'a': 1}
 pd2 = {'b': 2}
 merged = {**pd1, **pd2}   # isinstance(merged, dict) == True
@@ -919,12 +992,10 @@ and `dict.update()` for Python dicts.
 
 ### Dict merge operator `|` and `|=` (Python 3.9+)
 
-When `from __python__ import overload_operators, dict_literals` is active,
-Python dicts support the `|` (merge) and `|=` (update in-place) operators:
+Python dicts support the `|` (merge) and `|=` (update in-place) operators
+(requires ``overload_operators`` and ``dict_literals``, both on by default):
 
 ```py
-from __python__ import overload_operators, dict_literals
-
 d1 = {'x': 1, 'y': 2}
 d2 = {'y': 99, 'z': 3}
 
@@ -939,17 +1010,15 @@ d1 |= d2           # d1 is now {'x': 1, 'y': 99, 'z': 3}
 `d1 |= d2` merges `d2` into `d1` and returns `d1`.
 
 Without `overload_operators` the `|` symbol is bitwise OR — use
-`{**d1, **d2}` spread syntax as a flag-free alternative.
+`{**d1, **d2}` spread syntax as an alternative if the flag is disabled.
 
 
 ### Arithmetic operator overloading
 
 RapydScript supports Python-style arithmetic operator overloading via the
-``overload_operators`` scoped flag:
+``overload_operators`` flag, which is **on by default**:
 
 ```py
-from __python__ import overload_operators
-
 class Vector:
     def __init__(self, x, y):
         self.x = x
@@ -990,31 +1059,52 @@ The supported dunder methods are:
 Augmented assignment (``+=``, ``-=``, etc.) first tries the in-place method
 (``__iadd__``, ``__isub__``, …) and then falls back to the binary method.
 
-If neither operand defines the relevant dunder method the operation falls back
-to the native JavaScript operator, so plain numbers, strings, and booleans
-continue to work as expected with no performance penalty when no dunder method
-is defined.
+If neither operand defines the relevant dunder method, the operation enforces
+Python-style type compatibility before falling back to the native JavaScript
+operator:
+
+- ``number`` ± ``number`` → allowed (including ``bool``, which is treated as an integer subclass)
+- ``str`` + ``str`` → allowed
+- ``str`` * ``int`` and ``list`` * ``int`` → allowed (and also with ``bool`` in place of ``int``)
+- Anything else raises ``TypeError`` with a Python-style message, e.g.:
+
+```py
+1 + 'x'       # TypeError: unsupported operand type(s) for +: 'int' and 'str'
+'a' - 1       # TypeError: unsupported operand type(s) for -: 'str' and 'int'
+[1] + 'b'     # TypeError: unsupported operand type(s) for +: 'list' and 'str'
+```
+
+This type-checking is controlled by the ``strict_arithmetic`` flag, which is
+**on by default** when ``overload_operators`` is active.  To revert to
+JavaScript's silent coercion behaviour (e.g. ``1 + 'x'`` → ``'1x'``) without
+disabling dunder dispatch, use:
+
+```py
+from __python__ import no_strict_arithmetic
+```
+
+When ``overload_operators`` is
+disabled (``from __python__ import no_overload_operators``) the operators
+compile directly to JavaScript and no type checking is performed.
 
 When `overload_operators` is active, string and list repetition with `*` works just like Python:
 
 ```py
-from __python__ import overload_operators
 'ha' * 3      # 'hahaha'
 3 * 'ha'      # 'hahaha'
 [0] * 4       # [0, 0, 0, 0]
 [1, 2] * 2    # [1, 2, 1, 2]
 ```
 
-Because the dispatch adds one or two property lookups per operation, the flag
-is **opt-in** rather than always-on. Enable it only in the files or scopes
-where you need it.
+Because the dispatch adds one or two property lookups per operation, you can
+disable it in scopes where it is not needed with
+``from __python__ import no_overload_operators``.
 
 The ``collections.Counter`` class defines ``__add__``, ``__sub__``, ``__or__``,
 and ``__and__``. With ``overload_operators`` you can use the natural operator
 syntax:
 
 ```py
-from __python__ import overload_getitem, overload_operators
 from collections import Counter
 
 c1 = Counter('aab')
@@ -1032,9 +1122,35 @@ RapydScript dicts (but not arbitrary javascript objects). You can also define
 the ``__eq__(self, other)`` method in your classes to have these operators work
 for your own types.
 
-RapydScript does not overload the ordering operators ```(>, <, >=,
-<=)``` as doing so would be a big performance impact (function calls in
-JavaScript are very slow). So using them on containers is useless.
+The ordering operators ``<``, ``>``, ``<=``, ``>=`` dispatch to Python-style
+dunder methods and compare lists lexicographically — just like Python:
+
+```py
+from __python__ import overload_operators  # on by default
+
+# List comparison — lexicographic order
+assert [1, 2] < [1, 3]     # True  (first differing element: 2 < 3)
+assert [1, 2] < [1, 2, 0]  # True  (prefix is smaller)
+assert [2] > [1, 99]       # True  (first element dominates)
+
+# Works with custom __lt__ / __gt__ / __le__ / __ge__ on objects
+class Version:
+    def __init__(self, major, minor):
+        self.major = major
+        self.minor = minor
+    def __lt__(self, other):
+        return (self.major, self.minor) < (other.major, other.minor)
+
+v1 = Version(1, 5)
+v2 = Version(2, 0)
+assert v1 < v2   # dispatches to __lt__
+
+# Incompatible types raise TypeError, just like Python
+try:
+    result = [1] < 42
+except TypeError as e:
+    print(e)   # '<' not supported between instances of 'list' and 'int'
+```
 
 Chained comparisons work just like Python — each middle operand is evaluated only once:
 
@@ -1042,18 +1158,13 @@ Chained comparisons work just like Python — each middle operand is evaluated o
 # All of these work correctly, including mixed-direction chains
 assert 1 < 2 < 3      # True
 assert 1 < 2 > 0      # True  (1<2 AND 2>0)
-assert 1 < 2 > 3 == False  # 1<2 AND 2>3 = True AND False = False
+assert [1] < [2] < [3]   # True  (lexicographic chain)
 ```
 
 ### Python Truthiness and `__bool__`
 
-By default RapydScript uses JavaScript truthiness, where empty arrays `[]` and
-empty objects `{}` are **truthy**. Activate full Python truthiness semantics
-with:
-
-```py
-from __python__ import truthiness
-```
+RapydScript uses Python truthiness semantics by default (``truthiness`` is
+**on by default**):
 
 When this flag is active:
 
@@ -1064,8 +1175,6 @@ When this flag is active:
 - **All condition positions** (`if`, `while`, `assert`, `not`, ternary) use Python semantics.
 
 ```py
-from __python__ import truthiness
-
 class Empty:
     def __bool__(self): return False
 
@@ -1079,16 +1188,14 @@ z = [1] and 'ok'      # z == 'ok'
 
 The flag is **scoped** — it applies until the end of the enclosing
 function or class body. Use `from __python__ import no_truthiness` to
-disable it in a sub-scope.
+disable it in a sub-scope where JavaScript truthiness is needed.
 
 ### Callable Objects (`__call__`)
 
 Any class that defines `__call__` can be invoked directly with `obj(args)`,
-just like Python callable objects. This requires `from __python__ import truthiness`:
+just like Python callable objects:
 
 ```python
-from __python__ import truthiness
-
 class Multiplier:
     def __init__(self, factor):
         self.factor = factor
@@ -1134,6 +1241,108 @@ Mutation methods (`add`, `remove`, `discard`, `clear`, `update`) are not
 present on `frozenset` instances, enforcing immutability at the API level.
 `frozenset` objects can be iterated and copied with `.copy()`.
 
+### `bytes` and `bytearray`
+
+RapydScript provides `bytes` (immutable) and `bytearray` (mutable) builtins
+that match Python's semantics and are backed by plain JS arrays of integers
+in the range 0–255.
+
+#### `b'...'` bytes literals
+
+RapydScript supports Python `b'...'` bytes literal syntax.  The prefix may be
+`b` or `B` (and `rb`/`br` for raw bytes where backslash sequences are not
+interpreted).  Adjacent bytes literals are automatically concatenated, just
+like adjacent string literals.
+
+```python
+b'Hello'              # bytes([72, 101, 108, 108, 111])
+b'\x00\xff'           # bytes([0, 255])  — hex escape sequences work
+b'\n\t\r'             # bytes([10, 9, 13]) — control-char escapes work
+b'foo' b'bar'         # bytes([102, 111, 111, 98, 97, 114])  — concatenation
+rb'\n\t'              # bytes([92, 110, 92, 116])  — raw: backslashes literal
+B'ABC'                # bytes([65, 66, 67])  — uppercase B also accepted
+```
+
+Each `b'...'` literal is compiled to a `bytes(str, 'latin-1')` call, so the
+full `bytes` API is available on the result.
+
+#### Construction
+
+```python
+bytes()                      # empty bytes
+bytes(4)                     # b'\x00\x00\x00\x00'  (4 zero bytes)
+b'\x00\x00\x00\x00'          # same — bytes literal syntax
+bytes([72, 101, 108, 111])   # b'Hello'
+b'Hell\x6f'                  # same — mix of ASCII and hex escapes
+bytes('Hello', 'utf-8')      # encode a string
+bytes('ABC', 'ascii')        # ASCII / latin-1 encoding also accepted
+bytes.fromhex('48656c6c6f')  # from hex string → b'Hello'
+
+bytearray()                  # empty mutable byte sequence
+bytearray(3)                 # bytearray(b'\x00\x00\x00')
+bytearray([1, 2, 3])         # from list of ints
+bytearray('Hi', 'utf-8')     # from string
+bytearray(some_bytes)        # mutable copy of a bytes object
+```
+
+`Uint8Array` values may also be passed as the source argument.
+
+#### Common operations (both `bytes` and `bytearray`)
+
+```python
+b = bytes('Hello', 'utf-8')
+
+len(b)                        # 5
+b[0]                          # 72  (integer)
+b[-1]                         # 111
+b[1:4]                        # bytes([101, 108, 108])  (slice → new bytes)
+b[::2]                        # every other byte
+
+b + bytes([33])               # concatenate → b'Hello!'
+b * 2                         # repeat     → b'HelloHello'
+72 in b                       # True  (integer membership)
+bytes([101, 108]) in b        # True  (subsequence membership)
+b == bytes([72, 101, 108, 108, 111])  # True
+
+b.hex()                       # '48656c6c6f'
+b.hex(':', 2)                 # '48:65:6c:6c:6f'  (separator every 2 bytes)
+b.decode('utf-8')             # 'Hello'
+b.decode('ascii')             # works for ASCII-range bytes
+
+b.find(bytes([108, 108]))     # 2
+b.index(101)                  # 1
+b.rfind(108)                  # 3
+b.count(108)                  # 2
+b.startswith(bytes([72]))     # True
+b.endswith(bytes([111]))      # True
+b.split(bytes([108]))         # [b'He', b'', b'o']
+b.replace(bytes([108]), bytes([76]))  # b'HeLLo'
+b.strip()                     # strip leading/trailing whitespace bytes
+b.upper()                     # b'HELLO'
+b.lower()                     # b'hello'
+bytes(b' ').join([bytes('a', 'ascii'), bytes('b', 'ascii')])  # b'a b'
+
+repr(b)                       # "b'Hello'"
+isinstance(b, bytes)          # True
+isinstance(bytearray([1]), bytes)  # True  (bytearray is a subclass of bytes)
+```
+
+#### `bytearray`-only mutation methods
+
+```python
+ba = bytearray([1, 2, 3])
+ba[0] = 99                    # item assignment
+ba[1:3] = bytes([20, 30])     # slice assignment
+ba.append(4)                  # add one byte
+ba.extend([5, 6])             # add multiple bytes
+ba.insert(0, 0)               # insert at index
+ba.pop()                      # remove and return last byte (or ba.pop(i))
+ba.remove(20)                 # remove first occurrence of value
+ba.reverse()                  # reverse in place
+ba.clear()                    # remove all bytes
+ba += bytearray([7, 8])       # in-place concatenation
+```
+
 ### `issubclass`
 
 `issubclass(cls, classinfo)` checks whether a class is a subclass of another
@@ -1173,7 +1382,8 @@ semantics:
 | other `float` | derived from the bit pattern |
 | `str` | djb2 algorithm — stable within a process |
 | object with `__hash__` | dispatches to `__hash__()` |
-| class instance | stable identity hash (assigned on first call) |
+| class instance (no `__hash__`) | stable identity hash (assigned on first call) |
+| class with `__eq__` but no `__hash__` | `TypeError` (unhashable — Python semantics) |
 | `list` | `TypeError: unhashable type: 'list'` |
 | `set` | `TypeError: unhashable type: 'set'` |
 | `dict` | `TypeError: unhashable type: 'dict'` |
@@ -1193,8 +1403,213 @@ class Point:
         return self.x * 31 + self.y
 
 hash(Point(1, 2))  # 33
+
+# Python semantics: __eq__ without __hash__ → unhashable
+class Bar:
+    def __eq__(self, other):
+        return True
+hash(Bar())  # TypeError: unhashable type: 'Bar'
 ```
 
+### `eval` and `exec`
+
+Both `eval` and `exec` are supported with Python-compatible signatures.
+String literals passed to them are treated as **RapydScript source code**: the
+compiler parses and transpiles the string at compile time, so you write
+RapydScript (not raw JavaScript) inside the quotes — just like Python's
+`eval`/`exec` take Python source strings.
+
+#### `eval(expr[, globals[, locals]])`
+
+* **One argument** — the compiled expression is passed to the native JS `eval`,
+  giving direct scope access to module-level variables:
+
+  ```python
+  result = eval("1 + 2")               # 3
+  x = 7
+  sq = eval("x * x")                   # 49  (x is in scope)
+  ```
+
+* **Two or three arguments** — uses the `Function` constructor with explicit
+  variable bindings.  `locals` override `globals` when both are given:
+
+  ```python
+  eval("x + y", {"x": 10, "y": 5})          # 15
+  eval("x", {"x": 1}, {"x": 99})             # 99  (local overrides global)
+  ```
+
+#### `exec(code[, globals[, locals]])`
+
+Executes a RapydScript code string and always returns `None`, like Python's
+`exec`.
+
+* **One argument** — the compiled code runs via native `eval`:
+
+  ```python
+  exec("print('hi')")           # prints hi
+  exec("_x = 42")               # _x is discarded after exec returns
+  ```
+
+* **Two or three arguments** — uses the `Function` constructor.  Mutable
+  objects (arrays, dicts) passed in `globals` are accessible by reference, so
+  mutations are visible in the caller:
+
+  ```python
+  log = []
+  exec("log.append(1 + 2)", {"log": log})
+  print(log[0])    # 3
+
+  def add(a, b): log.append(a + b);
+  exec("fn(10, 7)", {"fn": add, "log": log})
+  print(log[1])    # 17
+  ```
+
+> **Note:** Because strings are compiled at compile time, only **string
+> literals** are transformed — dynamic strings assembled at runtime are passed
+> through unchanged.  `exec(code)` cannot modify the caller's local variables,
+> matching Python 3 semantics.
+
+### `vars`, `locals`, and `globals`
+
+#### `vars(obj)`
+
+Returns a `dict` snapshot of the object's own instance attributes, mirroring
+Python's `obj.__dict__`.  Internal RapydScript properties (prefixed `ρσ`) are
+excluded automatically.  Mutating the returned dict does **not** affect the
+original object.
+
+```python
+class Point:
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+p = Point(3, 4)
+d = vars(p)
+print(d['x'], d['y'])   # 3 4
+print(list(d.keys()))   # ['x', 'y']
+```
+
+#### `vars()` and `locals()`
+
+Both return an empty `dict`.  JavaScript has no runtime mechanism for
+introspecting the local call-frame's variables, so a faithful implementation is
+not possible.  Use them as placeholders in patterns that require a dict, or
+pass explicit dicts where you need named-value lookup.
+
+```python
+loc = locals()   # {}
+v   = vars()     # {}
+```
+
+#### `globals()`
+
+Returns a `dict` snapshot of the JS global object (`globalThis` / `window` /
+`global`).  Module-level RapydScript variables compiled inside an IIFE or
+module wrapper will **not** appear here; use a shared plain dict for that
+pattern instead.
+
+```python
+g = globals()
+# g contains JS runtime globals such as Math, console, etc.
+print('Math' in g)   # True (in a browser or Node context)
+```
+
+### Complex numbers
+
+RapydScript supports Python's complex number type via the `complex` builtin and
+the `j`/`J` imaginary literal suffix.
+
+```py
+# Imaginary literal suffix
+z = 4j          # complex(0, 4)
+w = 3 + 4j      # complex(3, 4)   — parsed as 3 + complex(0, 4)
+
+# Constructor
+z1 = complex(3, 4)    # real=3, imag=4
+z2 = complex(5)       # real=5, imag=0
+z3 = complex()        # 0+0j
+z4 = complex('2-3j')  # string parsing
+
+# Attributes
+print(z1.real)   # 3
+print(z1.imag)   # 4
+
+# Methods
+print(z1.conjugate())   # (3-4j)
+print(abs(z1))          # 5.0  — dispatches __abs__
+
+# Arithmetic (requires overload_operators, which is on by default)
+from __python__ import overload_operators
+print(z1 + z2)   # (8+4j)
+print(z1 - z2)   # (-2+4j)
+print(z1 * z2)   # (15+20j)
+print(z1 / z2)   # (0.6+0.8j)
+
+# Truthiness, repr, isinstance
+print(bool(complex(0, 0)))   # False
+print(repr(z1))              # (3+4j)
+print(isinstance(z1, complex))  # True
+```
+
+The `j`/`J` suffix is handled at the tokenizer level: `4j` is parsed into an
+`AST_Call(complex, 0, 4)` node, so it composes naturally with all other
+expressions. Mixed expressions like `3 + 4j` work without `overload_operators`
+because `ρσ_list_add` dispatches `__radd__` on the right operand.
+
+### Attribute-Access Dunders
+
+RapydScript supports the four Python attribute-interception hooks:
+`__getattr__`, `__setattr__`, `__delattr__`, and `__getattribute__`.
+When a class defines any of them, instances are automatically wrapped in a
+JavaScript `Proxy` that routes attribute access through the hooks — including
+accesses that occur inside `__init__`.
+
+| Hook | When called |
+|---|---|
+| `__getattr__(self, name)` | Fallback — only called when normal lookup finds nothing |
+| `__setattr__(self, name, value)` | Every attribute assignment (including `self.x = …` in `__init__`) |
+| `__delattr__(self, name)` | Every `del obj.attr` |
+| `__getattribute__(self, name)` | Every attribute read (overrides normal lookup) |
+
+To bypass the hooks from within the hook itself (avoiding infinite recursion),
+use the `object.*` bypass functions:
+
+| Python idiom | Compiled form | Effect |
+|---|---|---|
+| `object.__setattr__(self, name, val)` | `ρσ_object_setattr(self, name, val)` | Set attribute directly, bypassing `__setattr__` |
+| `object.__getattribute__(self, name)` | `ρσ_object_getattr(self, name)` | Read attribute directly, bypassing `__getattribute__` |
+| `object.__delattr__(self, name)` | `ρσ_object_delattr(self, name)` | Delete attribute directly, bypassing `__delattr__` |
+
+Subclasses automatically inherit proxy wrapping from their parent class — if
+`Base` defines `__getattr__`, all `Child(Base)` instances are also Proxy-wrapped.
+
+```py
+class Validated:
+    """Reject negative values at assignment time."""
+    def __setattr__(self, name, value):
+        if jstype(value) is 'number' and value < 0:
+            raise ValueError(name + ' must be non-negative')
+        object.__setattr__(self, name, value)
+
+v = Validated()
+v.x = 5    # ok
+v.x = -1   # ValueError: x must be non-negative
+
+class AttrProxy:
+    """Log every attribute read."""
+    def __init__(self):
+        object.__setattr__(self, '_log', [])
+
+    def __getattribute__(self, name):
+        self._log.append(name)          # self._log goes through __getattribute__ too!
+        return object.__getattribute__(self, name)
+```
+
+> **Proxy support required** — The hooks rely on `Proxy`, which is available
+> in all modern browsers and Node.js ≥ 6. In environments that lack `Proxy`
+> the class still works, but the hooks are silently bypassed.
+
 Loops
 -----
 RapydScript's loops work like Python, not JavaScript. You can't, for example
@@ -1377,8 +1792,33 @@ format('hi', '>10')   # '        hi' — right-aligned in 10-char field
 format(42)            # '42'        — no spec: same as str(42)
 ```
 
-Objects with a `__format__` method are dispatched to it, matching Python's
-protocol exactly.
+Objects with a `__format__` method are dispatched to it in all three contexts
+— `format(obj, spec)`, `str.format('{:spec}', obj)`, and `f'{obj:spec}'` —
+matching Python's protocol exactly. Every user-defined class automatically
+gets a default `__format__` that returns `str(self)` for an empty spec and
+raises `TypeError` for any other spec, just like `object.__format__` in
+Python:
+
+```py
+class Money:
+    def __init__(self, amount):
+        self.amount = amount
+    def __str__(self):
+        return str(self.amount)
+    def __format__(self, spec):
+        if spec == 'usd':
+            return '$' + str(self.amount)
+        return format(self.amount, spec)  # delegate numeric specs
+
+m = Money(42)
+format(m, 'usd')          # '$42'
+str.format('{:usd}', m)   # '$42'
+f'{m:usd}'                # '$42'
+f'{m:.2f}'                # '42.00'
+```
+
+The `!r`, `!s`, and `!a` conversion flags apply `repr()`/`str()`/`repr()` to the
+value before formatting, bypassing `__format__` (same as Python).
 
 String predicate methods are also available:
 
@@ -1405,6 +1845,16 @@ Case-folding for locale-insensitive lowercase comparison:
 str.casefold('ÄÖÜ') == str.casefold('äöü')  # True (maps to lowercase)
 ```
 
+Tab expansion:
+
+```py
+str.expandtabs('a\tb', 4)   # 'a   b'  — expand to next 4-space tab stop
+str.expandtabs('\t\t', 8)   # '                '  — two full tab stops
+str.expandtabs('ab\tc', 4)  # 'ab  c'  — only 2 spaces needed to reach next stop
+```
+
+The optional `tabsize` argument defaults to `8`, matching Python's default. A `tabsize` of `0` removes all tab characters. Newline (`\n`) and carriage-return (`\r`) characters reset the column counter, so each line is expanded independently.
+
 However, if you want to make the python string methods available on string
 objects, there is a convenience method in the standard library to do so. Use
 the following code:
@@ -1612,6 +2062,7 @@ can annotate a variable with a type hint, with or without an initial value:
 x: int = 42
 name: str = "Alice"
 items: list = [1, 2, 3]
+coords: tuple = (10, 20)
 
 # Annotation only: declares the type without assigning a value
 count: int
@@ -1656,18 +2107,22 @@ Regular Expressions
 ----------------------
 
 RapydScript includes a ```re``` module that mimics the interface of the Python
-re module. However, it uses the JavaScript regular expression functionality
-under the hood, which has several differences from the Python regular
-expression engine. Most importantly:
-
-  - it does not support lookbehind and group existence assertions
-  - it does not support unicode (on ES 6 runtimes, unicode is supported, but
-	with a different syntax). You can test for the presence of unicode support with
-	```re.supports_unicode```. 
-  - The ``MatchObject``'s ``start()`` and ``end()`` method cannot return correct values
-    for subgroups for some kinds of regular expressions, for example, those
-	with nested captures. This is because the JavaScript regex API does not expose
-	this information, so it has to be guessed via a heuristic.
+re module. It uses the JavaScript regular expression engine under the hood, so
+it supports the full feature set available in modern JS runtimes:
+
+  - **Lookbehind assertions** — both positive `(?<=...)` and negative `(?<!...)`
+    are fully supported (ES2018+), including variable-width lookbehind.
+  - **Unicode** — the `u` flag is added automatically on ES2015+ runtimes.
+    `re.supports_unicode` reflects whether the runtime supports it.
+  - **`re.fullmatch()`** — matches the entire string against the pattern.
+  - **`re.S` / `re.DOTALL`** — make `.` match newlines; `re.S` is now the
+    canonical alias (matching Python), with `re.D` kept for compatibility.
+  - **`re.NOFLAG`** (= 0) — the Python 3.11 no-flags sentinel.
+  - **`MatchObject.start()`/`.end()`** — return accurate positions for all
+    sub-groups on runtimes that support the ES2022 `d` (hasIndices) flag
+    (Node 18+, Chrome 90+). On older runtimes a heuristic is used.
+  - **Conditional groups** `(?(id)yes|no)` — not supported in JavaScript;
+    an `re.error` is raised if they appear in the pattern.
 
 You can use the JavaScript regex literal syntax, including verbose regex
 literals, as shown below. In verbose mode, whitespace is ignored and # comments
@@ -1682,8 +2137,338 @@ re.match(///
   a  # a comment
   b  # Another comment
   ///, 'ab')
+
+# Lookbehind and fullmatch
+re.sub(r'(?<=\d)px', '', '12px 3em')   # '12 3em'
+re.fullmatch(r'\w+', 'hello')           # MatchObject
+re.fullmatch(r'\w+', 'hello world')     # None
+```
+
+JSX Support
+-----------
+
+RapydScript supports JSX syntax for building React UI components. JSX elements compile directly to `React.createElement()` calls, so the output is plain JavaScript — no Babel or JSX transform step is needed.
+
+JSX support is **on by default**. The ``jsx`` flag can be disabled with
+``from __python__ import no_jsx`` if needed.
+
+### Requirements
+
+`React` must be in scope at runtime. How you provide it depends on your environment:
+
+- **Bundler (Vite, webpack, etc.):** `import React from 'react'` at the top of your file (or configure your bundler's global React shim).
+- **CDN / browser script tag:** load React before your compiled script.
+- **Bitburner:** React is already available as a global — no import needed.
+- **RapydScript web REPL:** a minimal React stub is injected automatically so `React.createElement` calls succeed.
+
+### Output format
+
+RapydScript compiles JSX to `React.createElement()` calls. For example:
+
+```py
+def Greeting(props):
+    return <h1>Hello, {props.name}!</h1>
+```
+
+Compiles to:
+
+```js
+function Greeting(props) {
+    return React.createElement("h1", null, "Hello, ", props.name);
+}
 ```
 
+Lowercase tags (`div`, `span`, `h1`, …) become string arguments. Capitalised names and dot-notation (`MyComponent`, `Router.Route`) are passed as references — not strings.
+
+### Attributes
+
+String, expression, boolean, and hyphenated attribute names all work:
+
+```py
+def Form(props):
+    return (
+        <form>
+            <input
+                type="text"
+                aria-label="Name"
+                disabled={props.readonly}
+                onChange={props.onChange}
+                required
+            />
+        </form>
+    )
+```
+
+Hyphenated names (e.g. `aria-label`, `data-id`) are automatically quoted as object keys: `{"aria-label": "Name"}`. Boolean attributes with no value compile to `true`.
+
+### Nested elements and expressions
+
+```py
+def UserList(users):
+    return (
+        <ul className="user-list">
+            {[<li key={u.id}>{u.name}</li> for u in users]}
+        </ul>
+    )
+```
+
+### Fragments
+
+Use `<>...</>` to return multiple elements without a wrapper node. Fragments compile to `React.createElement(React.Fragment, null, ...)`:
+
+```py
+def TwoItems():
+    return (
+        <>
+            <span>First</span>
+            <span>Second</span>
+        </>
+    )
+```
+
+### Self-closing elements
+
+```py
+def Avatar(props):
+    return <img src={props.url} alt={props.name} />
+```
+
+### Spread attributes
+
+```py
+def Button(props):
+    return <button {...props}>Click me</button>
+```
+
+Compiles to `React.createElement("button", {...props}, "Click me")`.
+
+### Component tags
+
+Capitalised names and dot-notation are treated as component references (not quoted strings):
+
+```py
+def App():
+    return (
+        <Router.Provider>
+            <MyComponent name="hello" />
+        </Router.Provider>
+    )
+```
+
+Compiles to:
+
+```js
+React.createElement(Router.Provider, null,
+    React.createElement(MyComponent, {name: "hello"})
+)
+```
+
+### Compiling JSX files
+
+Since the output is plain JavaScript, compile to a `.js` file as normal:
+
+```sh
+rapydscript mycomponent.pyj --output mycomponent.js
+```
+
+React Standard Library
+-----------------------
+
+RapydScript ships a `react` standard library module that re-exports every standard React hook and utility under their familiar Python-friendly names.  Import the pieces you need and the compiler will resolve each name to the corresponding `React.*` property at compile time.
+
+### Importing hooks
+
+```py
+from react import useState, useEffect, useCallback, useMemo, useRef
+
+def Counter():
+    count, setCount = useState(0)
+
+    def increment():
+        setCount(count + 1)
+
+    return <button onClick={increment}>{count}</button>
+```
+
+Compiles to:
+
+```js
+var useState = React.useState;
+// ...
+function Counter() {
+    var [count, setCount] = React.useState(0);
+    function increment() {
+        setCount(count + 1);
+    }
+    return React.createElement("button", {onClick: increment}, count);
+}
+```
+
+Tuple unpacking works naturally because `React.useState` returns a two-element array — `count, setCount = useState(0)` compiles to the ES6 destructuring `var [count, setCount] = React.useState(0)`.
+
+### Available exports
+
+**Hooks (React 16.8+)**
+
+| Import name | React API |
+|---|---|
+| `useState` | `React.useState` |
+| `useEffect` | `React.useEffect` |
+| `useContext` | `React.useContext` |
+| `useReducer` | `React.useReducer` |
+| `useCallback` | `React.useCallback` |
+| `useMemo` | `React.useMemo` |
+| `useRef` | `React.useRef` |
+| `useImperativeHandle` | `React.useImperativeHandle` |
+| `useLayoutEffect` | `React.useLayoutEffect` |
+| `useDebugValue` | `React.useDebugValue` |
+
+**Hooks (React 18+)**
+
+| Import name | React API |
+|---|---|
+| `useId` | `React.useId` |
+| `useTransition` | `React.useTransition` |
+| `useDeferredValue` | `React.useDeferredValue` |
+| `useSyncExternalStore` | `React.useSyncExternalStore` |
+| `useInsertionEffect` | `React.useInsertionEffect` |
+
+**Core classes and elements**
+
+| Import name | React API |
+|---|---|
+| `Component` | `React.Component` |
+| `PureComponent` | `React.PureComponent` |
+| `Fragment` | `React.Fragment` |
+| `StrictMode` | `React.StrictMode` |
+| `Suspense` | `React.Suspense` |
+| `Profiler` | `React.Profiler` |
+
+**Utilities**
+
+| Import name | React API |
+|---|---|
+| `createElement` | `React.createElement` |
+| `cloneElement` | `React.cloneElement` |
+| `createContext` | `React.createContext` |
+| `createRef` | `React.createRef` |
+| `forwardRef` | `React.forwardRef` |
+| `isValidElement` | `React.isValidElement` |
+| `memo` | `React.memo` |
+| `lazy` | `React.lazy` |
+
+### Common patterns
+
+**useEffect with cleanup**
+
+```py
+from react import useState, useEffect
+
+def Timer():
+    count, setCount = useState(0)
+    def setup():
+        interval = setInterval(def(): setCount(count + 1);, 1000)
+        def cleanup():
+            clearInterval(interval)
+        return cleanup
+    useEffect(setup, [count])
+    return count
+```
+
+**useReducer**
+
+```py
+from react import useReducer
+
+def reducer(state, action):
+    if action.type == 'increment':
+        return state + 1
+    if action.type == 'decrement':
+        return state - 1
+    return state
+
+def Counter():
+    state, dispatch = useReducer(reducer, 0)
+    def inc():
+        dispatch({'type': 'increment'})
+    return state
+```
+
+**useContext**
+
+```py
+from react import createContext, useContext
+
+ThemeContext = createContext('light')
+
+def ThemedButton():
+    theme = useContext(ThemeContext)
+    return theme
+```
+
+**useRef**
+
+```py
+from react import useRef
+
+def FocusInput():
+    inputRef = useRef(None)
+    def handleClick():
+        inputRef.current.focus()
+    return <input ref={inputRef} />
+```
+
+**memo**
+
+```py
+from react import memo
+
+def Row(props):
+    return <li>{props.label}</li>
+
+MemoRow = memo(Row)
+```
+
+**forwardRef**
+
+```py
+from react import forwardRef
+
+def FancyInput(props, ref):
+    return <input ref={ref} placeholder={props.placeholder} />
+
+FancyInputWithRef = forwardRef(FancyInput)
+```
+
+**Class component**
+
+You can extend `React.Component` directly without importing it, or import `Component` from the `react` module:
+
+```py
+from react import Component
+
+class Greeter(Component):
+    def render(self):
+        return <h1>Hello, {self.props.name}!</h1>
+```
+
+**useTransition (React 18)**
+
+```py
+from react import useState, useTransition
+
+def SearchInput():
+    isPending, startTransition = useTransition()
+    query, setQuery = useState('')
+    def handleChange(e):
+        startTransition(def(): setQuery(e.target.value);)
+    return isPending
+```
+
+### Requirements
+
+The `react` module does not bundle React itself — it provides compile-time name bindings only.  `React` must be available as a global variable at runtime, exactly as described in the [JSX Requirements](#requirements) section above.
+
 Creating DOM trees easily
 ---------------------------------
 
@@ -1914,6 +2699,117 @@ print(Counter.get_count())  # 2
 
 The `@classmethod` decorator compiles to a method placed directly on the class (not its prototype), with `cls` mapped to `this`. A prototype delegation shim is also generated so instance calls work correctly.
 
+### `__new__` Constructor Hook
+
+RapydScript supports Python's `__new__` method, which runs *before* `__init__` and controls instance creation. Use it to implement patterns like singletons or alternative constructors:
+
+```py
+class Singleton:
+    _instance = None
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    def __init__(self):
+        pass
+
+a = Singleton()
+b = Singleton()
+assert a is b  # same instance
+```
+
+`super().__new__(cls)` creates a bare instance of `cls` (equivalent to `Object.create(cls.prototype)` in JavaScript). If `__new__` returns an instance of the class, `__init__` is called on it automatically. If it returns something else, `__init__` is skipped.
+
+Class variables accessed via `cls` inside `__new__` are correctly rewritten to `cls.prototype.varname`, matching Python's semantics.
+
+### `__class_getitem__`
+
+RapydScript supports Python's `__class_getitem__` hook, which enables subscript syntax on a class itself (`MyClass[item]`).  Define `__class_getitem__(cls, item)` in a class body to intercept `ClassName[x]`:
+
+```py
+class Box:
+    def __class_getitem__(cls, item):
+        return cls.__name__ + '[' + str(item) + ']'
+
+print(Box[int])   # Box[<class 'int'>]
+print(Box['str']) # Box[str]
+```
+
+`__class_getitem__` is an implicit `@classmethod`: the compiler strips `cls` from the JS parameter list and maps it to `this`, so calling `Box[item]` compiles to `Box.__class_getitem__(item)` with `this = Box`.
+
+Subclasses inherit `__class_getitem__` from their parent and receive the subclass as `cls`:
+
+```py
+class Base:
+    def __class_getitem__(cls, item):
+        return cls.__name__ + '<' + str(item) + '>'
+
+class Child(Base):
+    pass
+
+print(Base[42])   # Base<42>
+print(Child[42])  # Child<42>
+```
+
+Class variables declared in the class body are accessible via `cls.varname` inside `__class_getitem__`, just as with `@classmethod`.
+
+### `__init_subclass__`
+
+`__init_subclass__` is a hook that is called automatically on a base class whenever a subclass is created.  It is an implicit `@classmethod`: the compiler strips `cls` from the JS signature and maps it to `this`, so `cls` receives the newly-created subclass.
+
+```py
+class PluginBase:
+    _plugins = []
+
+    def __init_subclass__(cls, **kwargs):
+        PluginBase._plugins.append(cls)
+
+class AudioPlugin(PluginBase):
+    pass
+
+class VideoPlugin(PluginBase):
+    pass
+
+print(len(PluginBase._plugins))     # 2
+print(PluginBase._plugins[0].__name__)  # AudioPlugin
+```
+
+Keyword arguments written in the class header are forwarded to `__init_subclass__`:
+
+```py
+class Base:
+    def __init_subclass__(cls, required=False, **kwargs):
+        cls._required = required
+
+class Strict(Base, required=True):
+    pass
+
+class Loose(Base):
+    pass
+
+print(Strict._required)   # True
+print(Loose._required)    # False
+```
+
+Use `super().__init_subclass__(**kwargs)` to propagate the hook up the hierarchy:
+
+```py
+class GrandParent:
+    def __init_subclass__(cls, **kwargs):
+        cls._from_grandparent = True
+
+class Parent(GrandParent):
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)   # propagates to GrandParent
+
+class Child(Parent):
+    pass
+
+print(Child._from_grandparent)   # True
+```
+
+The hook is called after the subclass is fully set up (including `__name__`, `__qualname__`, and `__module__`), so `cls.__name__` is always the correct subclass name inside the hook.
+
 ### Nested Classes
 
 A class may be defined inside another class. The nested class becomes an attribute of the outer class (accessible as `Outer.Inner`) and is also reachable via instances (`self.Inner` inside methods). This mirrors Python semantics exactly.
@@ -2014,67 +2910,51 @@ You could also use `external` decorator to bypass improperly imported RapydScrip
 
 ### Method Binding
 
-By default, RapydScript does not bind methods to the classes they're declared under. This behavior is unlike Python, but very much like the rest of JavaScript. For example, consider this code:
+RapydScript automatically binds methods to their objects by default (the
+``bound_methods`` flag is **on by default**). This means method references
+like ``getattr(obj, 'method')`` work correctly when called later.
 
-```py
-class Boy:
-	def __init__(self, name):
-		self.name = name
-
-	def greet(self):
-		if self:
-			print('My name is' + self.name)
-
-tod = Boy('Tod')
-tod.greet()                 # Hello, my name is Tod
-getattr(tod, 'greet')()     # prints nothing
-```
+If you need to disable auto-binding in a scope, use
+``from __python__ import no_bound_methods``.
 
-In some cases, however, you may wish for the functions in the class to be
-automatically bound when the objects of that class are instantiated. In order
-to do that, use a *scoped flag*, which is a simple instruction to the compiler
-telling it to auto-bind methods, as shown below:
+For example:
 
 ```py
+class C:
+    def __init__(self):
+        self.a = 3
 
-class AutoBound:
-	from __python__ import bound_methods
-
-	def __init__(self):
-		self.a = 3
-
-	def val(self):
-		return self.a
+    def val(self):
+        return self.a
 
-getattr(AutoBound(), 'val')() == 3
+getattr(C(), 'val')() == 3  # works because bound_methods is on by default
 ```
 
-If you want all classes in a module to be auto-bound simply put the scoped flag
-at the top of the module. You can even choose to have only a few methods of the
-class auto-bound, like this:
+You can mix bound and unbound methods within a class using ``no_bound_methods``
+and ``bound_methods`` to toggle at any point:
 
 ```py
 class C:
 
-	def unbound1(self):
-		pass # this method will not be auto-bound
-
-	from __python__ import bound_methods
-	# Methods below this line will be auto-bound
-
-	def bound(self):
-	   pass # This method will be auto-bound
+	def bound1(self):
+		pass # auto-bound (default)
 
 	from __python__ import no_bound_methods
 	# Methods below this line will not be auto-bound
 
-	def unbound2(self):
-		pass  # this method will be unbound
+	def unbound(self):
+		pass  # not auto-bound
+
+	from __python__ import bound_methods
+	# Methods below this line will be auto-bound again
+
+	def bound2(self):
+	   pass # auto-bound
 ```
 
 Scoped flags apply only to the scope they are defined in, so if you define them
 inside a class declaration, they only apply to that class. If you define it at
-the module level, it will only apply to all classes in the module that occur
+the module level, it will apply to all classes in the module that occur
 below that line, and so on.
 
 Iterators
@@ -2350,6 +3230,45 @@ except SomeInternalError:
 
 Basically, `try/except/finally` in RapydScript works very similar to the way it does in Python 3.
 
+### Exception Groups (`except*`, Python 3.11+)
+
+RapydScript supports exception groups via the `ExceptionGroup` class and `except*` syntax. An `ExceptionGroup` bundles multiple exceptions under a single message:
+
+```py
+eg = ExceptionGroup("network errors", [
+    TimeoutError("host A timed out"),
+    TimeoutError("host B timed out"),
+    ValueError("bad address"),
+])
+raise eg
+```
+
+Use `except*` to handle exceptions by type — each handler receives a sub-group containing only the matching exceptions:
+
+```py
+try:
+    fetch_all()
+except* TimeoutError as group:
+    for e in group.exceptions:
+        print("timeout:", e)
+except* ValueError as group:
+    print("bad input:", group.exceptions[0])
+```
+
+- Each `except*` clause sees the exceptions not already matched by earlier clauses.
+- Any unmatched exceptions are automatically re-raised as a new `ExceptionGroup`.
+- A bare `except*:` (no type) catches all remaining exceptions.
+- You cannot mix `except` and `except*` in the same `try` block.
+- Plain (non-group) exceptions can also be caught with `except*`; the variable is bound to the exception itself rather than a sub-group.
+
+`ExceptionGroup` also provides `subgroup(condition)` and `split(condition)` for programmatic filtering, where `condition` is either an exception class or a predicate function:
+
+```py
+eg = ExceptionGroup("mixed", [ValueError("v"), TypeError("t")])
+ve_group = eg.subgroup(ValueError)          # ExceptionGroup of just ValueErrors
+matched, rest = eg.split(ValueError)        # (ve_group, te_group)
+```
+
 Scope Control
 -------------
 
@@ -2416,7 +3335,16 @@ One of Python's main strengths is the number of libraries available to the devel
 	gettext             # Support for internationalization of your RapydScript app
 	operator            # a subset of Python's operator module
 	functools           # reduce, partial, wraps, lru_cache, cache, total_ordering, cmp_to_key
+	enum                # Enum base class — class Color(Enum): RED=1 with .name/.value, iteration
+	dataclasses         # @dataclass decorator — auto-generates __init__, __repr__, __eq__; field(),
+	                    # fields(), asdict(), astuple(), replace(), is_dataclass(), frozen=True, order=True
+	abc                 # ABC base class, @abstractmethod, Protocol, @runtime_checkable;
+	                    # abstract enforcement at instantiation; ABC.register() virtual subclasses
 	collections         # namedtuple, deque, Counter, OrderedDict, defaultdict
+	copy                # copy (shallow), deepcopy; honours __copy__ / __deepcopy__ hooks
+	typing              # TYPE_CHECKING, Any, Union, Optional, List, Dict, Set, Tuple, TypeVar,
+	                    # Generic, Protocol, Callable, Literal, Final, TypedDict, NamedTuple,
+	                    # ByteString, AnyStr (str | bytes), cast, …
 	itertools           # count, cycle, repeat, accumulate, chain, compress, dropwhile, filterfalse,
 	                    # groupby, islice, pairwise, starmap, takewhile, zip_longest,
 	                    # product, permutations, combinations, combinations_with_replacement
@@ -2624,18 +3552,21 @@ As a result, there are some things in RapydScript that might come as surprises
 to an experienced Python developer. The most important such gotchas are listed
 below:
 
-- Truthiness in JavaScript is very different from Python. Empty lists and dicts
-  are ``False`` in Python but ``True`` in JavaScript. You can opt in to full
-  Python truthiness semantics (where empty containers are falsy and ``__bool__``
-  is dispatched) with ``from __python__ import truthiness``. Without that flag,
-  test the length explicitly instead of the container directly.
-
-- Operators in JavaScript are very different from Python. ``1 + '1'`` would be
-  an error in Python, but results in ``'11'`` in JavaScript. Similarly, ``[1] +
-  [1]`` is a new list in Python, but a string in JavaScript. Keep that in mind
-  as you write code. By default, RapydScript does not implement operator
-  overloading for performance reasons. You can opt in via the
-  ``overload_operators`` scoped flag (see below).
+- RapydScript uses Python truthiness semantics by default: empty lists and dicts
+  are falsy and ``__bool__`` is dispatched. This is controlled by the
+  ``truthiness`` flag, which is on by default. Use
+  ``from __python__ import no_truthiness`` to fall back to JavaScript truthiness
+  in a scope.
+
+- Operator overloading is enabled by default via the ``overload_operators``
+  flag, so ``[1] + [1]`` produces a new list and ``'ha' * 3`` produces
+  ``'hahaha'``.  Type-checking is controlled by the separate ``strict_arithmetic``
+  flag (also on by default): mixing incompatible types raises ``TypeError``
+  (e.g. ``1 + 'x'`` → ``TypeError: unsupported operand type(s) for +: 'int'
+  and 'str'``).  Use ``from __python__ import no_strict_arithmetic`` to keep
+  dunder dispatch but revert to JavaScript's silent coercion for unrecognised
+  type combinations.  Use ``from __python__ import no_overload_operators`` to
+  disable operator overloading entirely.
 
 - There are many more keywords than in Python. Because RapydScript compiles
   down to JavaScript, the set of keywords is all the keywords of Python + all
@@ -2656,9 +3587,40 @@ below:
   yourself. Similarly, the compiler will try to convert SomeClass.method() into
   SomeClass.prototype.method() for you, but again, this is not 100% reliable.
 
-- The {"a":b} syntax is used to create JavaScript hashes. These do not behave
-  like python dictionaries. To create python like dictionary objects, you
-  should use a scoped flag. See the section on dictionaries above for details.
+- The ``{"a":b}`` syntax creates Python ``dict`` objects by default (the
+  ``dict_literals`` flag is on by default). Use
+  ``from __python__ import no_dict_literals`` to get plain JavaScript objects
+  in a scope. See the section on dictionaries above for details.
+
+
+Python Flags
+------------
+
+Python flags are scoped compiler directives that control Python semantics.
+All flags are **on by default**.  They can be turned off in a scope with
+the ``no_`` prefix.  In source code they are written as:
+
+```py
+from __python__ import flag_name
+```
+
+At the top level they take effect for the rest of the file; inside a function
+or class body they apply only to that scope.  Prefix a flag with `no_` to turn
+it off in a scope (e.g. `from __python__ import no_truthiness`).
+
+All flags are **on by default**.  To revert to legacy RapydScript behavior
+with no flags enabled, pass ``--legacy-rapydscript`` on the command line.
+
+| Flag | Description |
+|---|---|
+| `dict_literals` | `{k: v}` literals create Python `dict` objects instead of plain JS objects. On by default. |
+| `overload_getitem` | `obj[key]` dispatches to `__getitem__` / `__setitem__` / `__delitem__` on objects that define them. On by default. |
+| `overload_operators` | Arithmetic and bitwise operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`, `&`, `\|`, `^`, `<<`, `>>`) dispatch to dunder methods (`__add__`, `__sub__`, etc.) and their reflected variants. Unary `-`/`+`/`~` dispatch to `__neg__`/`__pos__`/`__invert__`. On by default. |
+| `strict_arithmetic` | When `overload_operators` is active, incompatible operand types (e.g. `int + str`) raise `TypeError` instead of silently coercing as JavaScript would. On by default; disable with `from __python__ import no_strict_arithmetic` to revert to JavaScript coercion behaviour. Internal RapydScript library code is unaffected. |
+| `truthiness` | Boolean tests and `bool()` dispatch to `__bool__` and treat empty containers as falsy, matching Python semantics. On by default. |
+| `bound_methods` | Method references (`obj.method`) are automatically bound to their object, so they can be passed as callbacks without losing `self`. On by default. |
+| `hash_literals` | `{k: v}` creates a Python `dict` (alias for `dict_literals`; kept for backward compatibility). On by default. |
+| `jsx` | JSX syntax (`<Tag attr={expr}>children</Tag>`) is enabled. On by default. |
 
 
 Monaco Language Service
@@ -2722,9 +3684,11 @@ when the editor is torn down.
 | `compiler` | object | — | **Required.** The `window.RapydScript` compiler bundle. |
 | `parseDelay` | number | `300` | Debounce delay (ms) before re-checking after an edit. |
 | `virtualFiles` | `{name: source}` | `{}` | Virtual modules available to `import` statements. |
+| `stdlibFiles` | `{name: source}` | `{}` | Like `virtualFiles` but treated as stdlib — always available and never produce bad-import warnings. |
 | `dtsFiles` | `[{name, content}]` | `[]` | TypeScript `.d.ts` files loaded at startup. |
 | `loadDts` | `(name) => Promise<string>` | — | Async callback for lazy-loading `.d.ts` content on demand. |
 | `extraBuiltins` | `{name: true}` | `{}` | Extra global names that suppress undefined-symbol warnings. |
+| `pythonFlags` | string | — | Comma-separated Python flags to enable globally (e.g. `"dict_literals,overload_getitem"`). See [Python Flags](#python-flags) above. |
 
 ### Runtime API
 
@@ -2744,6 +3708,9 @@ service.loadDts('lib.dom').then(function () { console.log('DOM types loaded'); }
 // Suppress undefined-symbol warnings for additional global names
 service.addGlobals(['myFrameworkGlobal', '$']);
 
+// Get the most recently built scope map for a Monaco model (null if not yet analysed)
+var scopeMap = service.getScopeMap(editorModel);
+
 // Tear down all Monaco providers and event listeners
 service.dispose();
 ```
@@ -2867,6 +3834,13 @@ original `.py` file with working breakpoints and correct error stack frames.
 | `keep_docstrings` | bool | `false` | Keep docstrings in the output. |
 | `js_version` | number | `6` | Target ECMAScript version (5 or 6). |
 | `private_scope` | bool | `false` | Wrap the output in an IIFE. |
+| `python_flags` | string | — | Comma-separated Python flags to enable for this compilation (e.g. `"dict_literals,overload_operators"`). See [Python Flags](#python-flags) above. Flags set here override any inherited from a previous `compile()` call on a streaming compiler. |
+| `virtual_files` | `{name: source}` | — | Map of module-name → RapydScript source for modules importable via `import`. Only used when the underlying streaming compiler was created with a virtual-file context (as `web_repl()` does). |
+| `discard_asserts` | bool | `false` | Strip all `assert` statements from the output. |
+| `omit_function_metadata` | bool | `false` | Omit per-function metadata (e.g. argument names) from the output for smaller bundles. |
+| `write_name` | bool | `false` | Emit a `var __name__ = "…"` assignment at the top of the output. |
+| `tree_shake` | bool | `false` | Remove unused imported names from the output (requires stdlib imports). |
+| `filename` | string | `'<input>'` | Source filename embedded in the source map and used in error messages. |
 
 **How it works**
 
@@ -2897,6 +3871,242 @@ This runs all seven language-service test suites (diagnostics, scope analysis,
 completions, signature help, hover, DTS registry, and built-in stubs).
 
 
+Python Feature Coverage
+-----------------------
+
+### Fully Supported
+
+| Feature                                                                                                                                                                                                                                                       | Notes |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
+| `super()` — 0-arg and 2-arg forms                                                                                                                                                                                                                             | `super().method()` and `super(Cls, self).method()` both work |
+| `except TypeA, TypeB as e:`                                                                                                                                                                                                                                   | RapydScript comma-separated form; catches multiple exception types |
+| `except (TypeA, TypeError) as e:`                                                                                                                                                                                                                             | Tuple form also supported |
+| `except*` / `ExceptionGroup` (Python 3.11+)                                                                                                                                                                                                                   | Full support: `ExceptionGroup` class with `subgroup()`/`split()`; `except*` dispatches to typed handlers, re-raises unmatched; bare `except*:` catches all remaining |
+| `try / else`                                                                                                                                                                                                                                                  | `else` block runs only when no exception was raised |
+| `for / else`                                                                                                                                                                                                                                                  | `else` block runs when loop completes without `break`; nested break isolation works |
+| `while / else`                                                                                                                                                                                                                                                | `else` block runs when loop condition becomes `False` without a `break`; nested `break` isolation correct |
+| `with A() as a, B() as b:`                                                                                                                                                                                                                                    | Multiple context managers in one statement; exits in LIFO order (Python-correct) |
+| `callable(fn)`                                                                                                                                                                                                                                                | Works for plain functions and objects with `__call__` |
+| `round(x, ndigits=0)`                                                                                                                                                                                                                                         | Full Python semantics including negative `ndigits` |
+| `enumerate(iterable, start=0)`                                                                                                                                                                                                                                | `start` parameter supported |
+| `str.isspace()`, `str.islower()`, `str.isupper()`                                                                                                                                                                                                             | Working string predicates |
+| `str.isalpha()`                                                                                                                                                                                                                                               | Regex-based; empty string returns `False` |
+| `str.isdigit()`                                                                                                                                                                                                                                               | Regex-based (`\d+`) |
+| `str.isalnum()`                                                                                                                                                                                                                                               | Regex-based |
+| `str.isidentifier()`                                                                                                                                                                                                                                          | Checks `^[a-zA-Z_][a-zA-Z0-9_]*$` |
+| `str.casefold()`                                                                                                                                                                                                                                              | Maps to `.toLowerCase()` |
+| `str.removeprefix(prefix)`                                                                                                                                                                                                                                    | Returns unchanged string if prefix not found |
+| `str.removesuffix(suffix)`                                                                                                                                                                                                                                    | Returns unchanged string if suffix not found |
+| `str.expandtabs(tabsize=8)`                                                                                                                                                                                                                                   | Replaces `\t` with spaces to the next tab stop; `\n`/`\r` reset the column counter; `tabsize=0` removes all tabs; available as an instance method on any string (via the default `pythonize_strings` patch) |
+| `str * n` string repetition                                                                                                                                                                                                                                   | Works (via `overload_operators`, on by default) |
+| `list * n` / `n * list`                                                                                                                                                                                                                                       | Works (via `overload_operators`); returns a proper RapydScript list |
+| `list + list` concatenation                                                                                                                                                                                                                                   | `[1,2] + [3,4]` returns `[1, 2, 3, 4]`; `+=` extends in-place. No flag required. |
+| `match / case`                                                                                                                                                                                                                                                | Structural pattern matching (Python 3.10) fully supported |
+| Variable type annotations `x: int = 1`                                                                                                                                                                                                                        | Parsed and ignored (no runtime enforcement); annotated assignments work normally |
+| Ellipsis literal `...` as expression                                                                                                                                                                                                                          | Parsed as a valid expression; evaluates to JS `undefined` at runtime |
+| Generator `.throw()`                                                                                                                                                                                                                                          | Works via JS generator protocol |
+| Generator `.send()`                                                                                                                                                                                                                                           | Works via `g.next(value)` |
+| `yield from`                                                                                                                                                                                                                                                  | Works; return value of sub-generator is not accessible |
+| `+=`, `-=`, `*=`, `/=`, `//=`, `**=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=`                                                                                                                                                                                   | All augmented assignments work |
+| `raise X from Y` exception chaining                                                                                                                                                                                                                           | Sets `__cause__` on the thrown exception; `from None` also supported |
+| Starred assignment `a, *b, c = ...`                                                                                                                                                                                                                           | Works |
+| `[*a, 1, *b]` list spread                                                                                                                                                                                                                                     | Works; any iterable; translates to `[...a, 1, ...b]` |
+| `{*a, 1, *b}` set spread                                                                                                                                                                                                                                      | Works; translates to `ρσ_set([...a, 1, ...b])` |
+| `**expr` in function calls                                                                                                                                                                                                                                    | Works with any expression (variable, attr access, call, dict literal), not just plain names |
+| `@classmethod`, `@staticmethod`, `@property` / `@prop.setter`                                                                                                                                                                                                 | All work |
+| `{**dict1, **dict2}` dict spread                                                                                                                                                                                                                              | Works as merge replacement for the missing `\|` operator |
+| `dict.fromkeys()`                                                                                                                                                                                                                                             | Works (via `dict_literals`, on by default) |
+| Chained comparisons `a < b < c` and `a < b > c`                                                                                                                                                                                                               | Same-direction and mixed-direction chains both work; middle operand evaluated once; with `overload_operators` each comparison dispatches via `ρσ_op_lt` etc. |
+| `for`, `while`, `try/except/finally`, `with`, `match/case`                                                                                                                                                                                                    | All control-flow constructs work |
+| Classes, inheritance, decorators, `__dunder__` methods                                                                                                                                                                                                        | Fully supported |
+| Nested class definitions                                                                                                                                                                                                                                      | Accessible as `Outer.Inner` and via instance (`self.Inner`); arbitrary nesting depth; nested class may inherit from outer-scope classes |
+| List / dict / set comprehensions, generator expressions                                                                                                                                                                                                       | Fully supported |
+| f-strings, `str.format()`, `format()` builtin, all common `str.*` methods                                                                                                                                                                                     | Fully supported |
+| `abs()`, `divmod()`, `any()`, `all()`, `sum()`, `min()`, `max()`                                                                                                                                                                                              | All work |
+| `sorted()`, `reversed()`, `zip()`, `map()`, `filter()`                                                                                                                                                                                                        | All work |
+| `zip(strict=True)`                                                                                                                                                                                                                                            | Raises `ValueError` when iterables have different lengths; equal-length iterables work normally |
+| `set` with full union/intersection/difference API                                                                                                                                                                                                             | Fully supported |
+| `isinstance()`, `hasattr()`, `getattr()`, `setattr()`, `dir()`                                                                                                                                                                                                | All work |
+| `bin()`, `hex()`, `oct()`, `chr()`, `ord()`                                                                                                                                                                                                                   | All work |
+| `int(x, base)`, `float(x)` with ValueError on bad input                                                                                                                                                                                                       | Works |
+| `lambda` keyword                                                                                                                                                                                                                                              | Full support: args, defaults, `*args`, ternary body, closures, nesting |
+| Arithmetic operator overloading — `__add__`, `__sub__`, `__mul__`, `__truediv__`, `__floordiv__`, `__mod__`, `__pow__`, `__neg__`, `__pos__`, `__abs__`, `__invert__`, `__lshift__`, `__rshift__`, `__and__`, `__or__`, `__xor__`, `__radd__`, `__iadd__` etc. | Dispatched via `overload_operators` (on by default) |
+| Ordered-comparison operator overloading — `__lt__`, `__gt__`, `__le__`, `__ge__`                                                                                                                                                                              | `<`, `>`, `<=`, `>=` dispatch to dunder methods (forward then reflected); lists compared lexicographically (like Python); incompatible types raise `TypeError`; chained comparisons (`a < b < c`) fully supported. Active via `overload_operators` (on by default). |
+| Nested comprehensions (multi-`for` clause)                                                                                                                                                                                                                    | `[x for row in matrix for x in row if cond]`; works for list, set, and dict comprehensions |
+| Positional-only parameters `def f(a, b, /):`                                                                                                                                                                                                                  | Full support — parser enforces placement; runtime passes positional args correctly |
+| Keyword-only parameters `def f(a, *, b):`                                                                                                                                                                                                                     | Full support — bare `*` separator enforced; `b` must be passed as keyword |
+| Walrus operator `:=`                                                                                                                                                                                                                                          | Fully supported: hoisted in `if`/`while` conditions at any scope; comprehension filter assigns to enclosing scope (Python-correct). |
+| `__call__` dunder dispatch                                                                                                                                                                                                                                    | `obj()` dispatches to `obj.__call__(args)` for callable objects; `callable(obj)` also returns `True`; both forms work. Active via `truthiness` (on by default). |
+| **Truthiness / `__bool__`**                                                                                                                                                                                                                                   | Full Python truthiness via `truthiness` (on by default): empty `[]`, `{}`, `set()`, `''` are falsy; `__bool__` is dispatched; `and`/`or` return operand values; `not`, `if`, `while`, `assert`, ternary all use `ρσ_bool()`. |
+| `frozenset(iterable)`                                                                                                                                                                                                                                         | Immutable set: construction from list/set/iterable; `in`, `len()`, iteration, `copy()`, `union()`, `intersection()`, `difference()`, `symmetric_difference()`, `issubset()`, `issuperset()`, `isdisjoint()` — all return `frozenset`. `isinstance(x, frozenset)` works. Compares equal to a `set` with the same elements via `__eq__`. No mutation methods (`add`, `remove`, etc.). |
+| `issubclass(cls, classinfo)`                                                                                                                                                                                                                                  | Checks prototype chain; `classinfo` may be a class or tuple of classes; every class is a subclass of itself; raises `TypeError` for non-class arguments. |
+| `hash(obj)` and `__hash__` dunder                                                                                                                                                                                                                             | Numbers hash by value (int identity, float → int form if whole); strings use djb2; `None` → 0; booleans → 0/1; `def __hash__(self)` in a class is dispatched by `hash()`; class instances without `__hash__` get a stable identity hash; defining `__eq__` without `__hash__` makes the class unhashable (Python semantics — `hash()` raises `TypeError`); `list`, `set`, `dict` raise `TypeError`. |
+| `__getattr__` / `__setattr__` / `__delattr__` / `__getattribute__` dunders                                                                                                                                                                                    | Full attribute-access interception via JS `Proxy`. Classes defining any of these automatically wrap instances. `__getattr__` is called only for missing attributes; `__getattribute__` overrides all lookups; `__setattr__` intercepts every assignment (including those in `__init__`); `__delattr__` intercepts `del obj.attr`. Use `object.__setattr__(self, name, value)` / `object.__getattribute__(self, name)` / `object.__delattr__(self, name)` (compiled to `ρσ_object_setattr` / `ρσ_object_getattr` / `ρσ_object_delattr`) to bypass the hooks and avoid infinite recursion. Subclasses automatically inherit proxy wrapping. Requires a JS environment that supports `Proxy`; gracefully degrades to plain attribute access in environments without `Proxy`. |
+| `__class_getitem__` dunder                                                                                                                                                                                                                                    | `Class[item]` dispatches at compile time to `Class.__class_getitem__(item)`. Behaves as an implicit `@classmethod`: `cls` is bound to the calling class. Subclasses inherit `__class_getitem__` and receive the subclass as `cls`. Multi-argument subscripts (`Class[A, B]`) are passed as a JS array. |
+| `__init_subclass__` hook                                                                                                                                                                                                                                      | Called automatically on the parent class whenever a subclass is created (e.g. `class Child(Base):`). Implicit `@classmethod`: `cls` receives the new subclass. Keyword arguments in the class header (`class Child(Base, tag='x'):`) are forwarded to `__init_subclass__` as keyword arguments. `super().__init_subclass__(**kwargs)` propagates up the hierarchy. No explicit call needed — the compiler emits it after inheritance setup and identity properties are assigned. |
+| `next(iterator[, default])`                                                                                                                                                                                                                                   | Advances a JS-protocol iterator (`{done, value}`); returns `default` when exhausted if provided, otherwise raises `StopIteration`. Works with `iter()`, `range()`, `enumerate()`, generators, and any object with a `.next()` or `__next__()` method. |
+| `StopIteration` exception                                                                                                                                                                                                                                     | Defined as a builtin exception class; raised by `next()` when an iterator is exhausted and no default is given. |
+| `iter(callable, sentinel)`                                                                                                                                                                                                                                    | Two-argument form calls `callable` (no args) repeatedly until the return value equals `sentinel` (strict `===`). Returns a lazy iterator compatible with `for` loops, `next()`, `list()`, and all iterator consumers. Works with plain functions and callable objects (`__call__`). |
+| `dict \| dict` and `dict \|= dict` (Python 3.9+)                                                                                                                                                                                                              | Dict merge via `\|` creates a new merged dict (right-side values win); `\|=` updates in-place. Active via `overload_operators` + `dict_literals` (both on by default). |
+| `__format__` dunder                                                                                                                                                                                                                                           | `format()`, `str.format()`, and f-strings all dispatch to `__format__`; default `__format__` auto-generated for classes (returns `__str__()` for empty spec, raises `TypeError` for non-empty spec); `!r`/`!s`/`!a` transformers bypass `__format__` correctly |
+| `slice(start, stop[, step])`                                                                                                                                                                                                                                  | Full Python `slice` class: 1-, 2-, and 3-argument forms; `.start`, `.stop`, `.step` attributes; `.indices(length)` → `(start, stop, step)`; `str()` / `repr()`; `isinstance(s, slice)`; equality `==`; use as subscript `lst[s]` (read, write, `del`) all work. |
+| `__import__(name[, globals, locals, fromlist, level])`                                                                                                                                                                                                        | Runtime lookup in the compiled module registry (`ρσ_modules`). Without `fromlist` (or empty `fromlist`) returns the top-level package, matching Python's semantics. `ImportError` / `ModuleNotFoundError` raised for unknown modules. **Constraint**: the module must have been statically imported elsewhere in the source so it is present in `ρσ_modules`. |
+| `ImportError`, `ModuleNotFoundError`                                                                                                                                                                                                                          | Both defined as runtime exception classes; `ModuleNotFoundError` is a subclass of `ImportError` (same as Python 3.6+). |
+| `bytes(source[, encoding[, errors]])` and `bytearray(source[, encoding[, errors]])`                                                                                                                                                                           | Full Python semantics: construction from integer (n zero bytes), list/iterable of ints (0–255), string + encoding (`utf-8`, `latin-1`, `ascii`), `Uint8Array`, or another `bytes`/`bytearray`. Key methods: `hex([sep[, bytes_per_sep]])`, `decode(encoding)`, `fromhex(s)` (static), `count`, `find`, `rfind`, `index`, `rindex`, `startswith`, `endswith`, `join`, `split`, `replace`, `strip`, `lstrip`, `rstrip`, `upper`, `lower`, `copy`. `bytearray` adds: `append`, `extend`, `insert`, `pop`, `remove`, `reverse`, `clear`, `__setitem__` (single and slice). Slicing returns a new `bytes`/`bytearray`. `+` concatenates; `*` repeats; `==` compares element-wise; `in` tests integer or subsequence membership; `isinstance(x, bytes)` / `isinstance(x, bytearray)` work; `bytearray` is a subclass of `bytes`. `repr()` returns `b'...'` notation. `Uint8Array` values may be passed anywhere a `bytes`-like object is accepted. |
+| `object()`                                                                                                                                                                                                                                                    | Featureless base-class instance: `object()` returns a unique instance; `isinstance(x, object)` works; `class Foo(object):` explicit base works; `repr()` → `'<object object at 0x…>'`; `hash()` returns a stable identity hash; each call returns a distinct object suitable as a sentinel value. Note: unlike CPython, JS objects are open, so arbitrary attributes can be set on `object()` instances. |
+| `float.is_integer()`                                                                                                                                                                                                                                          | Returns `True` if the float has no fractional part (i.e. is a whole number), `False` otherwise. `float('inf').is_integer()` and `float('nan').is_integer()` both return `False`, matching Python semantics. Added to `Number.prototype` in the baselib so it works on any numeric literal or variable. |
+| `int.bit_length()`                                                                                                                                                                                                                                            | Returns the number of bits needed to represent the integer in binary, excluding the sign and leading zeros. `(0).bit_length()` → `0`; `(255).bit_length()` → `8`; `(256).bit_length()` → `9`; sign is ignored (`(-5).bit_length()` → `3`). Added to `Number.prototype` in the baselib. |
+| Arithmetic type coercion — `TypeError` on incompatible operands                                                                                                                                                                                               | `1 + '1'` raises `TypeError: unsupported operand type(s) for +: 'int' and 'str'`; all arithmetic operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`) enforce compatible types in their `ρσ_op_*` helpers. `bool` is treated as numeric (like Python's `int` subclass). Activated by `overload_operators` (on by default). String `+` string and numeric `+` numeric are allowed; mixed types raise `TypeError` with a Python-style message. |
+| `complex(real=0, imag=0)` and complex literals `3+4j`                                                                                                                                                                                                         | Full complex number type via `ρσ_complex` class. `complex(real, imag)`, `complex(string)` (parses `'3+4j'`), and `j`/`J` imaginary literal suffix (e.g. `4j`, `3.5J`). Attributes: `.real`, `.imag`. Methods: `conjugate()`, `__abs__()`, `__bool__()`, `__repr__()`, `__str__()`. Arithmetic: `+`, `-`, `*`, `/`, `**` via dunder methods (or operator overloading with `overload_operators`). `abs(z)` dispatches `__abs__`. `isinstance(z, complex)` works. String representation matches Python: `(3+4j)`, `4j`, `(3-0j)`. |
+| `eval(expr[, globals[, locals]])`                                                                                                                                                                                                                             | String literals are compiled as **RapydScript source** at compile time (the compiler parses and transpiles the string, just like Python's `eval` takes Python source). `eval(expr)` maps to native JS direct `eval` for scope access. `eval(expr, globals)` / `eval(expr, globals, locals)` use `Function` constructor with explicit bindings; `locals` override `globals`. Runtime `ρσ_` helpers referenced in the compiled string are automatically injected into the Function scope. Only string *literals* are transformed at compile time; dynamic strings are passed through unchanged. |
+| `exec(code[, globals[, locals]])`                                                                                                                                                                                                                             | String literals are compiled as **RapydScript source** at compile time. Executes the compiled code string; always returns `None`. Without `globals`/`locals` uses native `eval` (scope access). With `globals`/`locals` uses `Function` constructor — mutable objects (lists, dicts) passed in `globals` are accessible by reference, so side-effects are visible after the call. `ρσ_dict` instances (created when `dict_literals` flag is active) are correctly unwrapped via their `jsmap` backing store. |
+| `vars(obj)`                                                                                                                                                                                                                                                   | Returns a Python `dict` snapshot of the object's own instance attributes (own enumerable JS properties, filtering internal `ρσ`-prefixed keys) — equivalent to Python's `obj.__dict__`. Mutating the returned dict does not affect the original object. Returns a proper `ρσ_dict` instance when `dict_literals` is active (default), so `.keys()`, `.values()`, `.items()`, and `[]` access work as expected. |
+| `vars()`                                                                                                                                                                                                                                                      | Zero-argument form is rewritten by the compiler to `vars(this)`, so calling `vars()` inside a method returns a snapshot of the current instance's attributes — equivalent to Python's no-arg `vars()` inside a method. |
+| `globals()`                                                                                                                                                                                                                                                   | Returns a `dict` snapshot of the JS global object's own enumerable keys (`globalThis` / `window` / `global`). Note that module-level RapydScript variables compiled inside an IIFE/module wrapper will not appear here. |
+
+---
+
+### Python Compatibility Flags (Default-On)
+
+All flags below are enabled by default. They can be turned off per-file, per-scope, or globally via the CLI.
+
+#### Opt-out: per-file or per-scope
+
+Place at the top of a file to affect the whole file, or inside a function to affect only that scope:
+
+```python
+from __python__ import no_truthiness           # single flag
+from __python__ import no_dict_literals, no_overload_operators  # multiple flags
+```
+
+To re-enable a flag in a nested scope after an outer scope turned it off:
+
+```python
+from __python__ import truthiness
+```
+
+#### Opt-out: CLI (all files)
+
+```sh
+rapydscript compile --python-flags=no_dict_literals,no_truthiness input.pyj
+```
+
+Flags in `--python-flags` are comma-separated. Prefix a flag with `no_` to disable it; omit the prefix to force-enable it (useful when combining with `--legacy-rapydscript`).
+
+#### Disable all flags (legacy mode)
+
+```sh
+rapydscript compile --legacy-rapydscript input.pyj
+```
+
+This restores the original RapydScript behavior: plain JS objects for `{}`, no operator overloading, JS truthiness, unbound methods, and no `String.prototype` patching.
+
+#### Flag reference
+
+| Flag | What it enables | Effect when disabled |
+|---|---|---|
+| `dict_literals` | `{}` creates a Python `ρσ_dict` with `.keys()`, `.values()`, `.items()`, `.get()`, `.pop()`, `.update()`, `fromkeys()`, and `KeyError` on missing key access. | `{}` becomes a plain JS object; no Python dict methods; missing key access returns `undefined`. |
+| `overload_getitem` | `obj[key]` dispatches to `obj.__getitem__(key)` when defined; `obj[a:b:c]` passes a `slice` object; dict `[]` access raises `KeyError` on missing key. | `[]` compiles to plain JS property access; no `__getitem__` dispatch; no slice dispatch. |
+| `bound_methods` | Class methods are automatically bound to `self`, so they retain their `self` binding when stored in a variable or passed as a callback. | Detached method references lose `self` (JS default behavior). |
+| `hash_literals` | When `dict_literals` is off, `{}` creates `Object.create(null)` rather than `{}`, preventing prototype-chain pollution from keys like `toString`. Has no visible effect while `dict_literals` is on. | `{}` becomes a plain `{}` (inherits from `Object.prototype`). Only relevant when `dict_literals` is also disabled. |
+| `overload_operators` | Arithmetic and bitwise operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`, `&`, `\|`, `^`, `~`, `<<`, `>>`) and ordered-comparison operators (`<`, `>`, `<=`, `>=`) dispatch to dunder methods (`__add__`, `__lt__`, etc.) when defined on the left operand. Also enables `str * n` string repetition, `list * n` / `n * list` list repetition, `dict \| dict` / `dict \|= dict` merge, and Python-style lexicographic list comparison. | All operators compile directly to JS; no dunder dispatch. `str * n` produces `NaN`; list repetition, dict merge, and Python-style list ordering are unavailable. |
+| `truthiness` | Python truthiness semantics: `[]`, `{}`, `set()`, `''`, `0`, `None` are falsy; objects with `__bool__` are dispatched; `and`/`or` return the deciding operand value (not `True`/`False`); `not`, `if`, `while`, `assert`, and ternary all route through `ρσ_bool()`. Also enables `__call__` dispatch: `obj(args)` invokes `obj.__call__(args)` for callable objects. | Truthiness is JS-native (all objects truthy); `__bool__` is never called; `and`/`or` return booleans; `__call__` is not dispatched. |
+| `jsx` | JSX syntax (`<Tag attr={expr}>children</Tag>` and `<>...</>` fragments) is recognised as expression syntax and compiled to `React.createElement` calls (or equivalent). | `<` is always a less-than operator; angle-bracket tokens are never parsed as JSX. |
+| `pythonize_strings` *(output-level option, not a `from __python__` flag)* | `String.prototype` is patched at startup with Python string methods (`strip`, `lstrip`, `rstrip`, `join`, `format`, `capitalize`, `lower`, `upper`, `find`, `rfind`, `index`, `rindex`, `count`, `startswith`, `endswith`, `center`, `ljust`, `rjust`, `zfill`, `partition`, `rpartition`, `splitlines`, `expandtabs`, `swapcase`, `title`, `isspace`, `islower`, `isupper`). Equivalent to calling `from pythonize import strings; strings()` manually. Note: `split()` and `replace()` are intentionally kept as their JS versions. | Python string methods are not available on string instances; call `str.strip(s)` etc., or import and call `strings()` from `pythonize` manually. Disable globally with `--legacy-rapydscript`. |
+
+---
+
+### Not Supported
+
+| Feature                               | Notes                                                                                   |
+|---------------------------------------|-----------------------------------------------------------------------------------------|
+| `__slots__` enforcement               | Accepted, but does not restrict attribute assignment                                    |
+| `locals()`                            | Returns an empty `dict`. JS has no runtime mechanism for introspecting local variables. |
+| `input(prompt)`                       | There is no simple cli input in browser; use `prompt()`                                 |
+| `compile()`                           | Python compile/code objects have no JS equivalent                                       |
+| `memoryview(obj)`                     | There is no buffer protocol in browser context                                          |
+| `open(path)`                          | There is no filesystem access in browser context                                        |
+| `from module import *` (star imports) | Intentionally unsupported (by design, to prevent namespace pollution)                   |
+| `__del__` destructor / finalizer      | JS has no guaranteed finalizer                                                          |
+
+---
+
+### Standard Library Modules
+
+Modules with a `src/lib/` implementation available are marked ✅. All others are absent.
+
+| Module        | Status      | Notes                                                                                         |
+|---------------|-------------|-----------------------------------------------------------------------------------------------|
+| `math`        | ✅           | Full implementation in `src/lib/math.pyj`                                                     |
+| `random`      | ✅           | RC4-seeded PRNG in `src/lib/random.pyj`                                                       |
+| `re`          | ✅           | Regex wrapper in `src/lib/re.pyj`; uses the JS engine — full PCRE-level support on modern runtimes: positive/negative lookbehind (ES2018+, including variable-width), unicode via automatic `u` flag (ES2015+), `re.fullmatch()`, `re.S`/`re.NOFLAG` aliases. `MatchObject.start()`/`.end()` return exact positions on runtimes with the ES2022 `d` flag (Node 18+); heuristic fallback on older runtimes. Conditional groups `(?(id)yes\|no)` are not supported (JS limitation) and raise `re.error`. |
+| `encodings`   | ✅           | Base64 and encoding helpers; partial `base64` coverage                                        |
+| `collections` | ✅           | `defaultdict`, `Counter`, `OrderedDict`, `deque`                                              |
+| `functools`   | ✅           | `reduce`, `partial`, `wraps`, `lru_cache`                                                     |
+| `itertools`   | ✅           | Common iteration tools                                                                        |
+| `numpy`       | ✅           | Full numpy-like library in `src/lib/numpy.pyj`; `numpy.random` and `numpy.linalg` sub-modules |
+| `copy`        | ✅           | `copy()` shallow copy and `deepcopy()` (circular-ref-safe via memo Map); `__copy__` / `__deepcopy__(memo)` hooks honoured; handles list, set, frozenset, dict, class instances, and plain JS objects |
+| `typing`      | ✅           | `TYPE_CHECKING`, `Any`, `Union`, `Optional`, `ClassVar`, `Final`, `Literal`, `NoReturn`, `List`, `Dict`, `Set`, `FrozenSet`, `Tuple`, `Type`, `Callable`, `Iterator`, `Iterable`, `Generator`, `Sequence`, `MutableSequence`, `Mapping`, `MutableMapping`, `Awaitable`, `Coroutine`, `AsyncGenerator`, `AsyncIterator`, `AsyncIterable`, `IO`, `TextIO`, `BinaryIO`, `Pattern`, `Match`, `TypeVar`, `Generic`, `Protocol`, `cast`, `overload`, `no_type_check`, `no_type_check_decorator`, `runtime_checkable`, `get_type_hints`, `TypedDict`, `NamedTuple`, `AnyStr`, `Text` — all available in `src/lib/typing.pyj` |
+| `dataclasses` | ✅           | `@dataclass`, `field()`, `asdict()`, `astuple()`, `replace()`, `fields()`, `is_dataclass()`, `MISSING` in `src/lib/dataclasses.pyj`; `frozen=True`, `order=True`, inheritance supported; note: `field()` first positional arg is the default value (JS reserved word `default` cannot be used as a kwarg) |
+| `enum`        | ✅           | `Enum` base class in `src/lib/enum.pyj`; `.name`, `.value`, iteration, `isinstance` checks; `IntEnum`/`Flag` not available |
+| `abc`         | ✅           | `ABC`, `@abstractmethod`, `Protocol`, `@runtime_checkable`, `ABCMeta` (informational), `get_cache_token()` in `src/lib/abc.pyj`; abstract method enforcement via `__init__` guard; `ABC.register()` for virtual subclasses with isinstance support; `Symbol.hasInstance` enables structural isinstance for `@runtime_checkable` protocols; `ABCMeta` metaclass not usable (no metaclass support), use `ABC` base class instead |
+| `contextlib`  | ❌           | `contextmanager`, `suppress`, `ExitStack`, `asynccontextmanager` not available                |
+| `string`      | ❌           | Character constants, `Template`, `Formatter` not available                                    |
+| `json`        | ❌           | No Python wrapper; JS `JSON.parse` / `JSON.stringify` work directly via verbatim JS           |
+| `datetime`    | ❌           | `date`, `time`, `datetime`, `timedelta` not available                                         |
+| `inspect`     | ❌           | `signature`, `getmembers`, `isfunction` etc. not available                                    |
+| `asyncio`     | ❌           | Event loop, `gather`, `sleep`, `Queue`, `Task` wrappers not available; use `async`/`await`    |
+| `io`          | ❌           | `StringIO`, `BytesIO` not available                                                           |
+| `struct`      | ❌           | Binary packing/unpacking not available                                                        |
+| `hashlib`     | ❌           | MD5, SHA-256 etc. not available; use Web Crypto API via verbatim JS                           |
+| `hmac`        | ❌           | Keyed hashing not available                                                                   |
+| `base64`      | ❌ (partial) | Partial coverage via `encodings` module; no full `base64` module                              |
+| `urllib`      | ❌           | URL parsing/encoding (`urllib.parse`) not available; use JS `URL` API                         |
+| `html`        | ❌           | `escape`, `unescape` not available; use JS DOM APIs                                           |
+| `csv`         | ❌           | CSV parsing not available                                                                     |
+| `textwrap`    | ❌           | `wrap`, `fill`, `dedent`, `indent` not available                                              |
+| `pprint`      | ❌           | Pretty-printing not available                                                                 |
+| `logging`     | ❌           | Logging framework not available; use `console.*` directly                                     |
+| `unittest`    | ❌           | Not available; RapydScript uses a custom test runner (`node bin/rapydscript test`)            |
+
+---
+
+### Semantic Differences
+
+Features that exist in RapydScript but behave differently from standard Python:
+
+| Feature | Python Behavior | RapydScript Behavior                                                                                                                                                                                                       |
+|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `is` / `is not` | Object identity | Strict equality `===` / `!==`, which is not object/pointer comparison for JS primitives  |
+| `//` floor division on floats | `math.floor(a/b)` always | uses `Math.floor` - same result for well-behaved floats                                                                                                                                                                    |
+| `%` on negative numbers | Python modulo (always non-negative) | JS remainder (can be negative)                                                                                                                                                                                             |
+| `global` / `nonlocal` scoping | Full cross-scope declaration | `global` works for module-level; if a variable exists in both an intermediate outer scope **and** the module-level scope, the outer scope takes precedence (differs from Python where `global` always forces module-level) |
+| `Exception.message` | Not standard; use `.args[0]` | `.message` is the standard attribute (JS `Error` style)                                                                                                                                                                    |
+| Function call argument count | Too few args → `TypeError`; too many → `TypeError` | Too few args → extra params are `undefined`; too many → extras silently discarded. No `TypeError` is raised in either case.                                                                                                |
+| Positional-only param enforcement | Passing by keyword raises `TypeError` | Passing by keyword is silently ignored — the named arg is discarded and the parameter gets `undefined` (no error raised)                                                                                                   |
+| Keyword-only param enforcement | Passing positionally raises `TypeError` | Passing positionally raises no error — the extra positional arg is silently discarded and the default value is used                                                                                                        |
+| Default `{}` dict — numeric keys | Integer keys are stored as integers | Numeric keys are auto-coerced to strings by the JS engine: `d[1]` and `d['1']` refer to the same slot                                                                                                                      |
+| Default `{}` dict — attribute access | `d.foo` raises `AttributeError` | `d.foo` and `d['foo']` access the same slot; keys are also properties                                                                                                                                                      |
+| String encoding | Unicode strings (full code-point aware) | UTF-16 — non-BMP characters (e.g. emoji) are stored as surrogate pairs. Use `str.uchrs()`, `str.uslice()`, `str.ulen()` for code-point-aware operations.                                                                   |
+| Multiple inheritance MRO | C3 linearization (MRO) always deterministic | Built on JS prototype chain; may differ from Python's C3 MRO in complex or diamond-inheritance hierarchies                                                                                                                 |
+| Generators — output format | Native Python generator objects | Down-compiled to ES5 state-machine switch statements by default; pass `--js-version 6` for native ES6 generators (smaller and faster)                                                                                      |
+| `dict` key ordering | Insertion order guaranteed (3.7+) | Depends on JS engine (V8 preserves insertion order in practice)                                                                                                                                                            |
+| Reserved keywords | Python keywords only | All JavaScript reserved words (`default`, `switch`, `delete`, `void`, `typeof`, etc.) are also reserved in RapydScript, since it compiles to JS                                                                            |
+| `parenthesized with (A() as a, B() as b):` | Multiple context managers in parenthesized form (3.10+) | Not meaningful in a browser/event-driven context; multi-context `with` without parens works                                                                                                                                |
+
+---
+
+### Test File
+
+`test/python_features.pyj` contains runnable assertions for all features surveyed.
+Features that are not supported have their test code commented out with a `# SKIP:` label
+and an explanation. Run with:
+
+```sh
+node bin/rapydscript test python_features
+```
+
+
 Reasons for the fork
 ----------------------
 
@@ -2910,4 +4120,4 @@ ever resumes, they are welcome to use the code from this fork. All the
 new code is under the same license, to make that possible.
 
 See the [Changelog](https://github.com/ficocelliguy/rapydscript-ns/blob/master/CHANGELOG.md)
-for a list of changes to rapydscript-ns, including this fork at version 8.0
+for a list of changes to rapydscript-ns, including this fork at version 8.0