rapydscript-ns 0.8.3 → 0.8.4

package/README.md

@@ -41,6 +41,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)
@@ -805,9 +806,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 +836,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
 
@@ -885,6 +886,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.
@@ -1173,7 +1231,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 +1252,67 @@ 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'
 ```
 
+### 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
@@ -1405,6 +1523,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 +1740,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
@@ -1684,6 +1813,353 @@ re.match(///
   ///, 'ab')
 ```
 
+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.
+
+Enable JSX support with:
+
+```py
+from __python__ import jsx
+```
+
+### 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
+from __python__ import jsx
+
+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
+from __python__ import jsx
+
+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
+from __python__ import jsx
+
+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
+from __python__ import jsx
+
+def TwoItems():
+    return (
+        <>
+            <span>First</span>
+            <span>Second</span>
+        </>
+    )
+```
+
+### Self-closing elements
+
+```py
+from __python__ import jsx
+
+def Avatar(props):
+    return <img src={props.url} alt={props.name} />
+```
+
+### Spread attributes
+
+```py
+from __python__ import jsx
+
+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
+from __python__ import jsx
+
+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 __python__ import jsx
+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 __python__ import jsx
+from react import useRef
+
+def FocusInput():
+    inputRef = useRef(None)
+    def handleClick():
+        inputRef.current.focus()
+    return <input ref={inputRef} />
+```
+
+**memo**
+
+```py
+from __python__ import jsx
+from react import memo
+
+def Row(props):
+    return <li>{props.label}</li>
+
+MemoRow = memo(Row)
+```
+
+**forwardRef**
+
+```py
+from __python__ import jsx
+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 __python__ import jsx
+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 +2390,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.
@@ -2350,6 +2937,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
 -------------
 
@@ -2417,6 +3043,7 @@ One of Python's main strengths is the number of libraries available to the devel
 	operator            # a subset of Python's operator module
 	functools           # reduce, partial, wraps, lru_cache, cache, total_ordering, cmp_to_key
 	collections         # namedtuple, deque, Counter, OrderedDict, defaultdict
+	copy                # copy (shallow), deepcopy; honours __copy__ / __deepcopy__ hooks
 	itertools           # count, cycle, repeat, accumulate, chain, compress, dropwhile, filterfalse,
 	                    # groupby, islice, pairwise, starmap, takewhile, zip_longest,
 	                    # product, permutations, combinations, combinations_with_replacement
@@ -2661,6 +3288,31 @@ below:
   should use a scoped flag. See the section on dictionaries above for details.
 
 
+Python Flags
+------------
+
+Python flags are scoped compiler directives that opt in to stricter Python
+semantics or language features.  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 nested scope.
+
+| Flag | Description |
+|---|---|
+| `dict_literals` | `{k: v}` literals create Python `dict` objects instead of plain JS objects. |
+| `overload_getitem` | `obj[key]` dispatches to `__getitem__` / `__setitem__` / `__delitem__` on objects that define them. |
+| `overload_operators` | Arithmetic and bitwise operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`, `&`, `\|`, `^`, `<<`, `>>`) dispatch to dunder methods (`__add__`, `__sub__`, etc.) and their reflected variants. Unary `-`/`+`/`~` dispatch to `__neg__`/`__pos__`/`__invert__`. |
+| `truthiness` | Boolean tests and `bool()` dispatch to `__bool__` and treat empty containers as falsy, matching Python semantics. |
+| `bound_methods` | Method references (`obj.method`) are automatically bound to their object, so they can be passed as callbacks without losing `self`. |
+| `hash_literals` | `{k: v}` creates a Python `dict` (alias for `dict_literals`; kept for backward compatibility). |
+| `jsx` | Enable JSX syntax (`<Tag attr={expr}>children</Tag>`). Required for files that contain JSX elements. |
+
+
 Monaco Language Service
 -----------------------
 
@@ -2722,9 +3374,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 +3398,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 +3524,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**