@gramlot/gramlot-examples 0.2.10 → 0.2.12

package/src/gramlot_examples/pages/binding/11_complete_page.md

@@ -1,12 +1,58 @@
 # 11 · A complete page with binding
 
-The event page of HTML / SVG example 12, with its visible state in the Data record `event`.
+The event page from **A complete page** now follows shared Data. Change one value and see it update in several places. You learn how to make an existing page interactive while retaining its structure.
 
-- The heading, the hero caption and the footer read `^.title` and `^.footer`; the field in the header edits the title while you type.
-- The two checkboxes write `show.mira` and `show.theo`. Schedule rows and speaker cards bind `visible` to them; the joint session has no pointer and stays.
-- The radio buttons above the map own `stop.entrance`, `stop.studio` and `stop.hall`; each map stop shows its ring through `visible`.
-- The FAQ `details` bind `open` to one checkbox.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-The main landmark is written `html_main`, held in the variable `main_content`, because the page also has a header and a footer.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Hide Theo, move to the hall, then open all answers.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Revisit the event page with shared Data driving several destinations.
+
+**Before this lesson:** [e12 · Complete page](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/12_complete_page.md), [b05 · Checkbox and radio](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/05_checkbox_radio.md), [b06 · Style and visibility](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/06_style_and_visibility.md), [b10 · SVG shapes with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/10_svg_shapes.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b11 · Complete page with binding** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands.
+
+## Read the page
+
+The `event` Data record drives the title, speaker visibility, map selection and FAQ. `html_main`, stored in `main_content`, is the HTML landmark.
+
+```python
+header.h1("^.title", id="title")
+header.input(value="^.title", live=True, id="title-field")
+# In the hero:
+hero.p("^.title")
+```
+
+One speaker flag controls the schedule row and speaker card. The joint session has no visibility pointer and stays visible. Radio booleans control the map rings; both FAQ disclosures bind `open` to one flag.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Edit Event title: heading and hero text change together.
+2. Uncheck Sessions of Theo: his solo row and card become invisible while retaining space; the joint session remains.
+3. Choose Hall: its ring appears and Studio’s disappears. Check Open all answers: both FAQ answers open.
+
+## Change it and check yourself
+
+Change the initial `.title` setter and start with `.show.theo` false in the dictionary.
+
+**Answer:** both title destinations get the new value and both Theo destinations start invisible. You change initial Data once for each concept, not every affected Source node.
+
+## The same example across stages
+
+**Earlier e12:** schedule, cards and FAQ are static, and the map has no selection.
+
+**Later 0.2.0:** `visible="^.show.theo"` can be reused for both Theo destinations; `open="^.faq_open"` controls both answers. A set of declarative pointers replaces separate per-destination update routines. The title is deliberately reused in the hero, whose earlier static description differed. The page also omits the earlier Highlights section: this is a teaching variation, not a pixel-identical rewrite.
+
+## Limits and next step
+
+The map has no routing service. Manually toggling a native disclosure is not declared as a write-back to `.faq_open`; the shared checkbox is the state-control demonstration. No server save or booking is performed.
+
+Continue with [c01 · Formula](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/01_formula.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/README.md

@@ -1,5 +1,17 @@
 # Binding
 
+Make fields, text and drawings share the same values. Edit a value once and let every bound view follow it.
+
+**This section uses Source, Data Bags, pointers, native input binding and initialization with setters/defaults — core 0.2.0.** It makes no endpoint calls and loads no remote content.
+
+Start with **Pointers**. The final three pages revisit **Native forms**, **SVG shapes** and **A complete page**: binding replaces code that would copy values into each view.
+
+**Later follow-up:** **Freeze** also uses local button controllers and named Logic. Return after **Named logic** and **Button controller**. Its Page/Logic module layout is from 0.2.5.
+
+<details>
+<summary>More detail</summary>
+
+
 The pages of this family keep their content in the Data and let the DOM follow it.
 
 A `^` pointer in a text or an attribute reads a Data path and keeps the element up to date. A native control whose `value` is a `^` pointer also writes the Data when you edit it. `dataSetter` puts the initial values in the Data before the first render.
@@ -7,3 +19,25 @@ A `^` pointer in a text or an attribute reads a Data path and keeps the element
 Start with **Pointers**, then follow the order of the list: a context that changes, initial values and defaults, editing, booleans, style and SVG, freeze. The last three pages take the content of HTML / SVG examples 06, 08 and 12 and add the binding, so the same page shows the difference.
 
 Each example has a Python page and its JavaScript equivalent. Both run on the same packaged runtime.
+
+## Prerequisites within the release sequence
+
+The family belongs to the 0.2.0 binding stage. Use b01's pointers to read b02–b04;
+separate the first trial from the advanced symbolic-path exercises. b05/b06/b09
+cover forms and layout; b07/b10 follow e08's SVG introduction. b08 uses named
+Logic and nested button controllers: read c03/c06 and e10 first. Freeze suspends
+structural rendering, not existing Data reactions; removed nodes stop handling
+events immediately. See the [release-by-release route](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md#gc-025-015). Prerequisites support the
+chronological sequence; they do not replace it. The maintained files may use
+later APIs, so they are not snapshots of the earliest release.
+
+## How to work through a lesson
+
+Read its core release stage first, then its goal and prerequisites. Open the
+existing preview, predict the guided result, and only then try the source-change
+exercise in your own editable page. Each exercise includes an answer. Follow
+"The same example across stages" links to compare earlier/later declarations;
+keep both stages visible. A newer interactive page can contain more total code
+while requiring less explicit state synchronization or request coordination.
+
+</details>

package/src/gramlot_examples/pages/controllers/01_formula.md

@@ -1,12 +1,53 @@
 # 01 · Formula
 
-`dataFormula(result_path, formula, **parameters)` computes an expression and writes the result at `result_path`. The names of the parameters are the names inside the expression.
+A formula calculates a result from the fields. You learn which inputs trigger a calculation and which are read only when it runs: `^` follows changes, while `=` supplies the current value.
 
-- A `^` parameter triggers the formula when its Data changes: editing the price or the quantity recomputes the total.
-- A `=` parameter is read at each run but does not trigger it. The gross uses `vat='=.vat'`: changing the rate alone does not recompute it; the next change of the total does.
-- `_if` is a condition: when it is false the formula writes the `_else` expression instead.
-- `_init=True` runs each formula once when the page starts, after the setters.
+**Uses:** Data binding and formulas — core 0.2.0.
 
-A formula result is itself Data: the gross and the size are formulas of the total.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Change the VAT rate, then the quantity, and watch when the gross follows.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Separate calculation dependencies from values read only at execution.
+
+**Before this lesson:** [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md), [b03 · Setters and defaults](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/03_setters_and_defaults.md), [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c01 · Formula** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+The first `dataFormula` computes price × quantity into `.total`; gross depends on total but only **reads** VAT. The formula for size uses `_if`/`_else`. `_init=True` evaluates after setters.
+
+```python
+pane.dataFormula(".total", "price * quantity", price="^.price", quantity="^.quantity", _init=True)
+```
+
+A formula returns its result; the provider writes it. The JavaScript expression runs in the browser, even inside a Python string. The result path is bare, not `^.total`.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Initially price 12.5 × quantity 4 gives total 50, gross 60 and “small order”.
+2. Change VAT from 0.2 to 0.1: gross remains 60.
+3. Change quantity to 8: total becomes 100 and gross 110; size stays “small order” because the condition is **greater than** 100.
+
+## Change it and check yourself
+
+Change `vat="=.vat"` to `vat="^.vat"`, reload and change only VAT to 0.1.
+
+**Answer:** gross now becomes 55 immediately. VAT became a trigger. The formula body is unchanged; one declaration changes dependency tracking.
+
+## The same example across stages
+
+Earlier e05 computed totals once while building Source. In 0.2.0, `dataFormula` declares what to recompute and which paths trigger it. Compared with a controller that explicitly calls `this.SET('.total', price * quantity)`, the formula body only returns `price * quantity`; the destination declaration owns the write. These are two forms within the same release, not a fabricated later release.
+
+## Limits and next step
+
+A formula is for a derived value; use a controller for effects. VAT here is a fraction (0.2), while c09 later uses a percentage (22); do not copy the number unchanged.
+
+Continue with [c02 · Controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/02_controller.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/02_controller.js

@@ -37,11 +37,33 @@ export class Page extends BasePage {
         timed.dataController({script: "this.SET('.ticks', (ticks ?? 0) + 1)", ticks: '=.ticks', _timing: '^.interval',
             _onStart: true});
 
+        const filtered = pane.section({class: 'card stack'});
+        filtered.h2('Advanced: _userChanges filters paths, not input origin');
+        filtered.html_label('Tracked name', {for: 'tracked-name'});
+        filtered.input({value: '^.filter.name', id: 'tracked-name'});
+        for (const [label, method] of [['SET the name', 'setName'], ['Replace containing Bag', 'replaceFilter'],
+            ['Change address child', 'changeCity']]) {
+            filtered.button(label, {id: method, type: 'button'}).dataController({func: method});
+        }
+        for (const [key, path, exact] of [['name_exact', '.filter.name', true], ['name_all', '.filter.name', false],
+            ['address_exact', '.filter.address', true], ['address_all', '.filter.address', false]]) {
+            filtered.p(`^.${key}`, {mask: `${key}: %s`, id: key});
+            filtered.dataController({func: 'countPath', watched: `^${path}`, counter: `.${key}`, _userChanges: exact});
+            pane.dataSetter({destination_path: `.${key}`, value: 0});
+        }
+        pane.dataSetter({destination_path: '.filter', value: {name: 'Ada', address: {city: 'Rome'}}});
+        pane.dataSetter({destination_path: '.replacement', value: {name: 'Container', address: {city: 'Paris'}}});
+
         pane.dataSetter({destination_path: '.name', value: 'Ada'});
         pane.dataSetter({destination_path: '.requests', value: 0});
         pane.dataSetter({destination_path: '.interval', value: '1'});
     }
 }
 
-/** The page logic: this page names no methods. */
-export class Logic {}
+/** Named methods for the optional path-filtering exercise. */
+export class Logic {
+    countPath(node, {counter}) { node.SET(counter, node.GET(counter) + 1); }
+    setName(node) { node.SET('.filter.name', 'Grace'); }
+    replaceFilter(node) { node.SET('.filter', node.GET('.replacement').deepcopy()); }
+    changeCity(node) { node.SET('.filter.address.city', 'Milan'); }
+}

package/src/gramlot_examples/pages/controllers/02_controller.md

@@ -1,10 +1,65 @@
 # 02 · Controller
 
-`dataController(script, **parameters)` runs code for its effects. Inside the script `this` is the controller's Source node: `this.SET('.path', value)` writes the Data relative to its context.
+A controller reacts to Data changes and writes other values. You learn when to use a controller for an action rather than a formula for a result. Its path filter distinguishes where a change occurred, not who made it.
 
-- **React to a value.** `name='^.name'` triggers the controller at every change; it writes `.invalid`, and the warning binds `visible` to it. `_init=True` runs it once at the start.
-- **React to a fired path.** The button's `fire='.request'` fires the path at every click, also with an equal value. The controller counts the requests; `requests='=.requests'` is read without triggering.
-- **Wait for a pause.** `_delay=400` runs the controller 400 ms after the last change, once.
-- **Run at start and at intervals.** `_onStart=True` runs the controller when the page has started; `_timing='^.interval'` repeats it every *n* seconds, and 0 stops it.
+**Uses:** Data binding and local controllers — core 0.2.0.
 
-**Try it:** Clear the name, type a search quickly, then change the interval to 5.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Choose a controller for an effect and identify its trigger.
+
+**Before this lesson:** [c01 · Formula](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/01_formula.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c02 · Controller** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+A `dataController` runs code for effects. In inline code, `this` is its Source node; `this.SET` writes relative Data. The first controller writes `.invalid`, whose pointer controls the warning.
+
+```python
+check.dataController("this.SET('.invalid', !name.trim())", name="^.name", _init=True)
+```
+
+The request button fires a Data path, not an HTTP request. The search controller waits 400 ms after the last edit. The clock runs at `_onStart` and repeats every `_timing` seconds; 0 disables repetition.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Clear Name: the warning appears; type Ada: it disappears.
+2. Press Send a request twice: the local counter becomes 2, without a server call.
+3. Type a search quickly and pause: “Searching for …” appears after the debounce. Set Interval to 0: subsequent periodic ticks stop.
+
+## Change it and check yourself
+
+Change `_delay=400` to `_delay=800`, reload and type another query.
+
+**Answer:** the last text appears after about 800 ms of quiet, once; no real search service is contacted. Timing is approximate browser scheduling, not a precision clock.
+
+## The same example across stages
+
+Compare e13’s `setInterval` plus explicit disposal with this page’s `_timing` on a controller. For a repeated controller effect, the provider owns timer cleanup, so the page no longer authors a timer handle and `clearInterval` pair. Keep e13’s Source animation as its own earlier/advanced example; no animation behavior has been silently replaced.
+
+
+## Advanced: filter the changed path (0.2.0)
+
+The optional section uses named Logic from `02_controller.js`. Two controllers watch `.filter.name`, and two watch the Bag `.filter.address`; each pair differs only in `_userChanges`. Start from a reload: all counters are zero.
+
+1. Edit Tracked name, then leave the field: name_exact/name_all become 1/1.
+2. Press SET the name: both become 2/2. Programmatic writes to the exact path qualify too.
+3. Replace containing Bag: name_all becomes 3 and address_all becomes 1, while the exact counters stay 2 and 0.
+4. Change address child: address_all becomes 2; address_exact stays 0 because `.filter.address.city` lies below the watched `.filter.address`.
+
+Exercise: change `_userChanges=True` to False on an exact watcher, reload and repeat. **Answer:** that watcher now accepts container/child events as its paired unfiltered watcher does. The flag is not a human-versus-code detector. The Data Bag copy used for replacement is still ordinary Data, not a parallel state store.
+
+## Limits and next step
+
+`requests` in this page counts fired local events. The advanced `_userChanges` counters are separate from `requests`: they filter exact-path changes, including programmatic writes, not human versus code identity.
+
+Continue with [c03 · Named logic](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/03_named_logic.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/03_named_logic.md

@@ -1,12 +1,68 @@
 # 03 · Named logic
 
-The code of this page lives in `class Logic`, which `03_named_logic.js` exports beside `Page`. The core GramlotFileServer serves that module as the page logic for the JavaScript page and for the Python page `03_named_logic.py` alike.
+A price calculation and a change counter call methods in a `Logic` class. You learn how to reuse named browser behavior instead of repeating inline code. In a Python gallery, open **logic.js** to see those methods.
 
-- `func='finalPrice'` names a method of `Logic`. A formula method receives one object with the resolved parameters and returns the result: 10% off from the `threshold`.
-- A controller method receives its Source node and the parameters. `node.SET('.changes', …)` writes relative to the node's context.
-- `this` is the logic group: `this.changes` keeps a count between calls, and `this.page` is the Gramlot page.
-- The parameters also carry `_reason`, `_node` and `_triggerpars`.
+**Uses:** Local formulas, controllers and named Logic (0.2.0); shared Page/Logic module layout from 0.2.5.
 
-Named logic compiles nothing at run time, so it also works under a Content Security Policy without `'unsafe-eval'`.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Raise the price above 100, then add a second formula that names `finalPrice` with another threshold.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0). The maintained Page/Logic module arrangement is from 0.2.5; it does not move the original behavior into a later release.
+
+**Goal:** Reuse browser behavior by naming a Logic method.
+
+**Before this lesson:** [c01 · Formula](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/01_formula.md), [c02 · Controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/02_controller.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c03 · Named logic** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands.
+
+## Read the page
+
+The Python Page declares `func="finalPrice"`; `03_named_logic.js` exports the browser `Logic` used by both languages. A formula method takes resolved parameters and returns a value. A controller method receives `(node, kwargs)` and writes Data with `node.SET`.
+
+```python
+pane.dataFormula(".final", func="finalPrice", price="^.price", threshold=100, _init=True)
+```
+
+`finalPrice` applies 10% off at/above the threshold. In Logic, `this` is the logic group, `this.page` is the browser Gramlot instance, and `this.changes` is local browser state. It is not a server Page field.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python. Read the gallery’s **logic.js** tab (the Logic class from `03_named_logic.js`) beside the Python source.
+
+## Try it and predict the result
+
+1. Initial price 80 produces final 80; the change controller has not yet counted an edit.
+2. Replace Price with 120: final becomes 108. The change count advances for each emitted input edit; `_reason` explains the trigger.
+
+## Change it and check yourself
+
+Add a second formula using `func="finalPrice"`, another result path `.other_final`, and `threshold=200`; add a paragraph bound to `.other_final`.
+
+**Answer:** at price 120, the original formula gives 108 and the second gives 120. The same method is reused; only the declarations and threshold differ.
+
+## The same example across stages
+
+**0.2.0 behavior:** move reusable calculations/effects from inline strings to named methods; this removes repeated formula bodies when multiple declarations share one method.
+
+**0.2.5 arrangement:** the same exported `Logic` can live beside `Page` in the page module; Python takes it from its same-name `.js` file. A separate `*_aux.js` is then unnecessary for this page. Do not claim the method body disappeared or that named Logic itself first arrived in 0.2.5.
+
+## Resource exercise: keep styling and Logic with the page
+
+`Page.css` already selects the shared theme. In your editable project, create
+`03_named_logic.css` beside the two page modules and put `h1 { color: teal; }` in it.
+Reload the page and inspect its stylesheet requests. **Answer:** the matching
+stylesheet is served as a companion and the heading changes without adding a
+resource group or browser style-writing code. The Python page already obtains
+its root Logic from `03_named_logic.js`. Remove the temporary style afterwards.
+
+This common path covers Page.css, the same-name stylesheet and root Logic.
+`css_requires`/`js_requires` and dotted named native-event handlers need the
+separate genro-kajenn resource host; FileServer and current adapters do not supply
+that host. Do not simulate it by loading scripts in the example.
+
+## Limits and next step
+
+Named Logic works without runtime inline compilation. A root `func` method does not become a named `connect_on` group: dotted event names need a resource group unavailable in the common FileServer gallery. Server-only imports cannot be placed in a module that the browser imports for Logic.
+
+Continue with [c04 · Inline expressions](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/04_inline_expressions.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/04_inline_expressions.md

@@ -1,12 +1,55 @@
 # 04 · Inline expressions
 
-A text or an attribute that starts with `==` is a JavaScript expression. Its names are the other attributes of the same node, which are often `^` pointers: the expression is computed again when one of them changes.
+Small expressions calculate what an element displays directly from its inputs. You learn how to format a local result without adding another calculated Data field.
 
-- The heading is `==first + ' ' + last`, with `first='^.first'` and `last='^.last'`.
-- The verdict computes its text, its `class` and its `title` from `score`.
-- The SVG bar computes its `width`; the button computes `disabled` from the checkbox.
-- The button's `action` is an inline script run at the click, with `this` = the button node.
+**Uses:** Data binding and inline expressions — core 0.2.0.
 
-Inline code needs a Content Security Policy that allows `'unsafe-eval'`; under a strict policy it stops with a clear error naming the node and the attribute. The legacy macros `SET path = value` and `$1` still work and log a deprecation warning: write `this.SET(path, value)` and `arguments[0]`.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Move the score across 50, accept the rules, then press Start.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Compute a local display value without storing another derived Data field.
+
+**Before this lesson:** [c01 · Formula](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/01_formula.md), [c03 · Named logic](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/03_named_logic.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c04 · Inline expressions** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+`==` starts a browser expression. Its names come from other attributes on that same Source node: `first="^.first"`, `last="^.last"`, or `score="^.score"`.
+
+```python
+result.h2("==first + ' ' + last", first="^.first", last="^.last", id="full-name")
+```
+
+The verdict uses score for text, class and title; the SVG bar uses score × 3 for width. The button’s `action` sets `.started` after `disabled` becomes false.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Expect Ada Lovelace, score 40, “Not yet”, bar width 120 and Start disabled.
+2. Move score to 60: verdict becomes Passed and width becomes 180.
+3. Accept the rules, then Start: the Started text appears.
+
+## Change it and check yourself
+
+Predict the result at exactly score 50, then try it.
+
+**Answer:** Passed and width 150, because the condition uses `>= 50`. Changing it to `> 50` changes that boundary, not the binding mechanism.
+
+## The same example across stages
+
+For a value used only by one display, compare a `.full_name` dataFormula plus a `^.full_name` heading with the `==` heading above: it removes the extra destination and provider. Both are 0.2.0 choices. Keep a named/shared formula when the result is needed elsewhere; fewer lines is not the only criterion.
+
+## Limits and next step
+
+Inline expressions/scripts require the permitted CSP profile and are not code loaded from Data. Do not teach deprecated SET macros. An expression cannot use another `==` attribute as a computed dependency; use a Data formula when several nodes need one result.
+
+For attribute templates, compare [c16 · Attribute projection](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/16_attribute_projection.md): `${name}` consumes a declared sibling parameter; it does not permit chains of `==` attributes.
+
+Continue with [c05 · Node methods](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/05_node_methods.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/05_node_methods.md

@@ -1,11 +1,45 @@
 # 05 · Node methods
 
-Every Source node offers five methods for the Data. A path starting with `.` is relative to the node's context; here each button's `action` calls them with `this` = the button node.
+Buttons read and change Data in different ways. You learn the difference between notifying writes, quiet writes, reads and fired events.
 
-- `this.SET(path, value)` writes and notifies: the value on screen changes and the observer counts one change.
-- `this.GET(path)` reads. **GET value** copies the current value into `.read`.
-- `this.PUT(path, value)` writes silently: nothing is notified, so the value on screen keeps the old number until the next SET. **GET value** shows the real one.
-- `this.FIRE(path, value)` writes the value and resets the path silently afterwards, so every FIRE is delivered, also with an equal value.
-- `this.FIRE_AFTER(path, value, delay)` fires after `delay` ms. The timer belongs to the node: removing the node cancels it.
+**Uses:** Source, Data and local node methods — core 0.2.0.
 
-**Try it:** Press PUT, then GET value, then SET, and compare the three numbers.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Distinguish notifying writes, quiet writes, reads and fired events.
+
+**Before this lesson:** [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md), [c02 · Controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/02_controller.md), [c04 · Inline expressions](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/04_inline_expressions.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c05 · Node methods** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+The actions call methods of their Source node: `SET` writes and notifies, `GET` reads, `PUT` writes quietly, `FIRE` notifies even for the same fired value and silently resets afterwards. `FIRE_AFTER` schedules a fire in milliseconds and belongs to the node’s lifetime.
+
+The notification counter is an observer of `.value`; `.read` is only a displayed snapshot made by GET value.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Start with value 0 and notification count 0. Click PUT: the displayed value stays 0.
+2. Click GET value: its snapshot shows 10. Click SET: it reads 10, writes 11 and the displayed value becomes 11; notifications become 1.
+3. Fire “now” twice: pings advance twice. FIRE_AFTER reports “later” after about one second.
+
+## Change it and check yourself
+
+Reload and click PUT twice, then GET value, then SET.
+
+**Answer:** snapshot 20, then displayed value 21 and one notification. Quiet writes change Data even though subscribed displays have not been notified.
+
+## Limits and next step
+
+PUT is not a second state store and does not mean the write failed. Do not use it when other views must update immediately. A delayed fire is cancelled when its owning node is removed.
+
+Continue with [c06 · Button controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/06_button_controller.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/06_button_controller.md

@@ -1,11 +1,54 @@
 # 06 · Button controller
 
-A button runs one click mechanism: a nested `dataController`, an `action`, or the `fire` family. Declaring two of them on one button is an error.
+A controller inside a button runs when you click it. You learn how the button supplies click parameters, including modifier keys, to the action.
 
-- **Nested controller.** The `dataController` inside the button runs once per click. Its code reads `button_counter`, which counts the clicks of this button and survives a rebuild, and `button_shift`, `button_ctrl`, `button_alt`, `button_meta`; `_evt` is the DOM event.
-- **fire.** `fire='.saved'` fires the path at each click. The value is the modifier string, such as `Shift`, or `true` without modifiers.
-- **fire_<name>.** `fire_save` and `fire_close` fire their paths with the values `save` and `close`, in attribute order: the log gets two entries per click.
+**Uses:** Data binding and local button controllers — core 0.2.0.
 
-A button with a mechanism gets `type="button"`, so it never submits a form by itself.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Press the first button with Shift, then Save with Alt.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Use one declared button mechanism and inspect its click parameters.
+
+**Before this lesson:** [c02 · Controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/02_controller.md), [c05 · Node methods](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/05_node_methods.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c06 · Button controller** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+The first button has a nested controller; the others use `fire` or `fire_<name>`. Mechanism precedence is not a choice: combining mechanisms on one button is an error. A mechanism makes it a non-submit button.
+
+```python
+button = nested.button("Press me, also with Shift or Alt", id="press")
+button.dataController("this.SET('.clicks', button_counter)")
+```
+
+This reduced excerpt focuses on the counter; the provided page also writes modifier keys. `button_counter`, modifier booleans and `_evt` are supplied by Gramlot.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Click the first button with Shift: counter 1 and keys Shift.
+2. Click Save with Alt: the result says “fired with Alt”.
+3. Click Save and close without modifiers: the log receives “save, close” in declaration order.
+
+## Change it and check yourself
+
+Add another click to the first button without modifiers.
+
+**Answer:** the counter is 2 and keys becomes none. You did not write a counter-increment routine or extract modifiers from the browser event yourself.
+
+## The same example across stages
+
+In the later **0.2.14** [c11 · Call on click](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/11_call_on_click.md), the same nested-button pattern uses `dataRpc` for a server call. The framework supplies dispatch, response/error handling and result placement, so a click controller does not have to coordinate the request itself. Both stages remain explicit; local actions do not suddenly imply server persistence.
+
+## Limits and next step
+
+The counter belongs to the button and survives a rebuild of that node; a newly created button is not the same identity. Do not add an `action` to the existing nested-controller button.
+
+Continue with [c07 · Events](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/07_events.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/07_events.md

@@ -1,10 +1,49 @@
 # 07 · Events
 
-`connect_on<event>` adds one DOM listener to the element of its node. The event name is the part after `connect_on`, lower-cased: `connect_onclick` listens to `click`, `connect_onkeydown` to `keydown`.
+Elements declare how they respond to browser events. You learn where an event is handled and how the declaring Source node updates Data.
 
-- The value is inline code with `this` = the declaring node and the parameter `event`. `this.SET('.path', …)` writes relative to the node's context.
-- The handler runs with the declaring node also when the event hits a descendant: a click on a chip reaches the section's handler, and `event.target` names the chip.
-- A value of dotted names, such as `gui.focused`, is named logic of a `js_requires` group instead. `js_requires` needs a server with a resource system: the core `GramlotFileServer` and the current adapters have none and raise an error for any name, so this page uses inline code. The resource system comes with genro-kajenn, part of Genro.
-- Removing the node removes its listeners.
+**Uses:** Data and inline event handlers — core 0.2.0. Named event groups need the separate Kajenn resource host.
 
-**Try it:** Click the green chip, type a word, then add `connect_onfocus` to the field.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Follow a declared event to the declaring node and its Data write.
+
+**Before this lesson:** [c02 · Controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/02_controller.md), [c06 · Button controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/06_button_controller.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c07 · Events** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+`connect_onclick` declares a listener owned by the Source node. Inline `this` is the declaring node, while `event.target` may be a descendant. The section records the clicked chip’s ID; typing records length and the last key; hover writes a class.
+
+The input’s own `event.target.value.length` is used only to explain that event’s payload, not to scrape unrelated controls or create a parallel form state. Normal application field state uses a `value` binding as in b04.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+
+## Try it and predict the result
+
+1. Click green: the section display shows `chip-green`, because the child was the event target.
+2. Type “cat”: length becomes 3 and the last key reflects your last keypress.
+3. Move over/out of the box: its class changes and then returns to card.
+
+## Change it and check yourself
+
+Add `connect_onfocus="this.SET('.key', 'focused')"` to the input, reload and focus it before typing.
+
+**Answer:** Last key first shows focused; typing then replaces it with the keyboard event’s key. The same Source context resolves `.key`.
+
+## The same example across stages
+
+For most field editing, b04’s `value` pointer replaces an authored input-to-Data handler. This event lesson remains useful when the event payload itself matters. Both are 0.2.0 mechanisms, not separate release milestones.
+
+## Limits and next step
+
+Removing a node removes its listeners. Named handlers require a dotted `group.method` from `js_requires`; a root Logic method used by `func` is not a substitute. The common gallery has no resource host; the named-group lesson belongs with genro-kajenn. Inline code needs the permissive CSP profile.
+
+Continue with [c08 · End-to-end story](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/08_end_to_end.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>