@gramlot/gramlot-examples 0.2.11 → 0.2.14

package/src/gramlot_examples/pages/controllers/14_data_remote.js

@@ -19,6 +19,10 @@ export class Page extends BasePage {
         result.h2('Menu, loaded by the server when it is read');
         result.p('^.menu', {id: 'menu'});
 
+        result.button('Read current value', {id: 'read-menu'}).dataController({func: 'readMenu'});
+        result.p('Snapshot returned by the explicit read:', {class: 'muted'});
+        result.p('^.read_value', {id: 'read-value'});
+
         pane.dataRemote({destination_path: '.menu', method: 'load_menu', cacheTime: 5, table: '^.table'});
         pane.dataSetter({destination_path: '.table', value: 'dishes'});
     }
@@ -27,5 +31,9 @@ export class Page extends BasePage {
 }
 Page.registerEndpoint('load_menu');
 
-/** The page logic: this page names no methods. */
-export class Logic {}
+/** The explicit read returns the stored value and may start a resolver refresh. */
+export class Logic {
+    readMenu(node) {
+        node.SET('.read_value', node.GET('.menu'));
+    }
+}

package/src/gramlot_examples/pages/controllers/14_data_remote.md

@@ -1,10 +1,69 @@
 # 14 · Data remote
 
-`dataRemote(destination_path, method, cacheTime=None, **params)` makes a Data path a value computed by an endpoint of the page. The endpoint is called when the path is read, not when the page starts.
+A menu loads when its Data path is read. You learn how `dataRemote` supplies values on demand. The read button copies the stored value; a fresh response can arrive afterwards. After the five-second cache expires, another read starts a refresh; expiry alone makes no call.
 
-- **Declare the endpoint** as for `dataRpc`: Python `@endpoint`, with `**kwargs`; JavaScript `Page.registerEndpoint('load_menu')`.
-- **A read never waits.** The paragraph `^.menu` reads the path: the read returns the current value, empty before the first call, and starts the call. The answer is written with the Data event, so the paragraph shows the menu.
-- **`cacheTime`** is in seconds. `5` serves the stored value for five seconds, then the next read calls again. `None` or a negative value calls once; `0` calls at every read and writes the answer without the Data event.
-- **`table='^.table'`** is an argument of the endpoint. After the first call, a change of a `^` argument loads the value again at once and the paragraph receives it.
+**Uses:** Data binding and an endpoint-backed resolver — core 0.2.16. An in-memory example, not a database service.
 
-**Try it:** Choose Drinks: the menu changes to the drinks that the server returns.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Remote Source and lazy Data (core 0.2.16), after the 0.2.14 endpoint lessons.
+
+**Goal:** Distinguish resolver installation, first read, response and later refresh.
+
+**Before this lesson:** [c09 · Endpoint](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/09_endpoint.md), [c10 · Call on change](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/10_call_on_change.md), [c13 · Cached remote](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/13_cached_remote.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **c14 · Data remote** 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
+
+`dataRemote` installs a resolver at `.menu`. Installation alone sends no call. The paragraph’s `^.menu` immediately reads it, which starts `load_menu`; the first read returns the stored value (initially null) without waiting.
+
+```python
+pane.dataRemote(".menu", "load_menu", cacheTime=5, table="^.table")
+```
+
+After the response, the resolver writes Data and notifies the paragraph for a nonzero cacheTime. The Read current value button calls named Logic: `node.GET('.menu')` reads synchronously and `node.SET('.read_value', ...)` displays that snapshot. A later response updates Menu; it does not retroactively change an already copied snapshot. Read `readMenu` in the gallery’s **logic.js** tab (the Logic class from `14_data_remote.js`) beside the Python source.
+
+Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Endpoint/fragment methods execute there too; bindings and any Logic execute in the browser. A Worker is not a private server.
+
+## Try it and predict the result
+
+1. On opening, the paragraph reads and then shows “Soup, Risotto, Fish”. The read snapshot is empty until you press the button.
+2. Press Read current value within five seconds of loading: the snapshot shows the stored menu; no additional call is needed.
+3. Choose Drinks: since the old resolver had already loaded, its replacement loads immediately and Menu becomes “Water, Lemonade, Coffee”. The earlier snapshot stays unchanged until another explicit read.
+
+## Change it and check yourself
+
+To isolate **installation from first read**, temporarily remove the `result.p("^.menu", id="menu")` declaration in your editable copy. Keep the button and `.read_value` display.
+
+**Answer:** opening installs the resolver but does not call `load_menu`. The first button press returns the current empty value and starts a call. After the response, a second press displays the loaded menu. No explicit fetch or await was added to the page.
+
+## The same example across stages
+
+0.2.14’s `dataRpc` explicitly triggers a Page computation and places its result in Data. In 0.2.16, a read of a declared Data path can own that loading through a resolver: you no longer author “if absent or expired, call and store” coordination. The endpoint method remains the same kind of Page method.
+
+This is a variation of server-backed Data, not an automatic replacement for every RPC. Choose dataRpc for a commanded action/error callback, remote for Source content, and dataRemote for read-driven values. The advanced exercises modify this same menu page rather than introducing a parallel request/state system.
+
+## Advanced practice
+
+Start each trial from a reload and inspect only `load_menu` calls in Network on HTTP. In a Worker environment the equivalent calls are messages.
+
+- **Expiry then read (5).** Wait for the first response, then wait more than five seconds without changing anything. Expect no timer-driven call. Press Read current value: it immediately displays the old value and starts a refresh. Wait for the response and read again within its cache window: no extra refresh is needed. Read twice while a deliberately delayed response is pending: only one call is in flight.
+- **Zero (0).** In the no-automatic-consumer variant from the exercise above, change `cacheTime=5` to 0. First click starts a call and returns empty. After it finishes, the next click displays the previous result **and starts another call**. Zero-cache writes do not emit a Data event, so a permanently bound Menu paragraph would not announce the completed response; do not mistake that for failed transport.
+- **Once (`None`, JS `null`, or negative).** Repeat reads: one call per installed resolver. Change Table after it has loaded: the reactive argument replaces the resolver and loads a new value; “once” is not forever across all parameter combinations.
+- **Failure.** Change the Drinks option’s authored value to a missing key, reload, first load Dishes, then choose it. Expect a console error while the last successful menu remains. Restore the option. No custom error callback is invented.
+- **Condition and lifetime.** In an editable copy, add an enabled checkbox/setter and `enabled="^.enabled", _if="enabled"`. Disabling it removes the resolver, retains the last value and cancels its pending call. Re-enabling after it previously loaded starts a replacement load. Removing the declaration’s owning Source branch or disposing the page also aborts its pending call; an aborted response must not overwrite the Data. These conditional declarations use inline code and require the permitted CSP profile.
+
+These are separate advanced trials, not prerequisites for the first menu read. The release sequence continues with future agreed features; the complete-page extension and environment-wide qualification are separate planned work.
+
+## Limits and next step
+
+A resolver read is not a promise for the fresh response. `cacheTime` uses **seconds**, unlike controller delays in milliseconds. `None` (JS null) or a negative value means once per resolver instance; 0 means every explicit read, with concurrent reads coalesced. Failures retain the stored value and reach the console naming the declaration.
+
+Do not copy dataRpc’s `_onCalling`, `_onResult` or `_onError` onto dataRemote, or use `_init`, `_onBuilt`, `_onStart` there. An auth-aware environment is still needed for protected methods. This in-memory menu is not a database service.
+
+Continue with [setup and release sequence](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.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/15_lifecycle.js

@@ -0,0 +1,51 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Lifecycle';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'lifecycle'});
+        pane.h1('Lifecycle');
+        pane.p('Follow initialization, building, starting and removal of one branch.');
+        const actions = pane.div({class: 'actions'});
+        for (const [label, method] of [['Freeze', 'freeze'], ['Thaw', 'thaw'],
+            ['Inspect Source and DOM', 'inspect'], ['Remove branch', 'remove']]) {
+            actions.button(label, {id: method, type: 'button'}).dataController({func: method});
+        }
+        for (const [label, key] of [['Hook trace', 'trace'], ['Data ticks', 'ticks'], ['Lookup', 'lookup']]) {
+            pane.h2(label); pane.p(`^.${key}`, {id: key});
+        }
+        const observed = pane.section({node_id: 'observed', id: 'observed', class: 'card stack'});
+        observed.h2('Observed branch');
+        observed.p('^.ticks', {id: 'branch-ticks'});
+        for (const [hook, stage] of [['_init', 'init'], ['_onBuilt', 'built'], ['_onStart', 'start']]) {
+            observed.dataController({func: 'record', stage, [hook]: true});
+        }
+        observed.dataController({func: 'tick', _timing: 1, _onStart: true});
+        pane.dataSetter({destination_path: '.trace', value: ''});
+        pane.dataSetter({destination_path: '.ticks', value: 0});
+        pane.dataSetter({destination_path: '.lookup', value: 'Press Inspect'});
+    }
+}
+
+export class Logic {
+    branch() { return this.page.src.source.getNodeByAttr('node_id', 'observed'); }
+    record(node, {stage}) {
+        const previous = node.GET('.trace');
+        node.SET('.trace', previous ? `${previous} → ${stage}` : stage);
+    }
+    tick(node) { node.SET('.ticks', node.GET('.ticks') + 1); }
+    freeze() { const branch = this.branch(); if (branch) this.page.src.renderer.freeze(branch); }
+    thaw() { const branch = this.branch(); if (branch) this.page.src.renderer.unfreeze(branch); }
+    inspect(node) {
+        const branch = this.branch();
+        if (!branch) { node.SET('.lookup', 'Source branch absent'); return; }
+        const element = this.page.dom.getDomNode(branch);
+        node.SET('.lookup', element && this.page.dom.getBaseSourceNode(element) === branch
+            ? 'Source → DOM → same Source' : 'Source present; DOM absent');
+    }
+    remove() {
+        const branch = this.branch();
+        if (branch) branch.parentBag.popNode(branch.label);
+    }
+}

package/src/gramlot_examples/pages/controllers/15_lifecycle.md

@@ -0,0 +1,59 @@
+# 15 · Lifecycle
+
+Start and stop a branch, then remove it. You learn when its lifecycle actions run and which work ends with that branch.
+
+**Uses:** Source, Data, controllers and lifecycle (0.2.0); module layout from 0.2.5.
+
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** core 0.2.0; the maintained Page/Logic file layout is from 0.2.5.
+
+**Goal:** Predict when a branch starts and which work ends when it is removed.
+
+**Before this lesson:** [c03 · Named logic](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/03_named_logic.md), [c06 · Button controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/06_button_controller.md), [b08 · Freeze](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/08_freeze.md).
+
+**Open and edit:** open this page in your environment's gallery. Read Python first; Python builds Source on the host and named JavaScript Logic runs in the browser. The JavaScript Page is the equivalent host/Worker declaration. The gallery shows source; to change it, copy the page into your editable project following the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md). Read the **logic.js** tab (the Logic class from `15_lifecycle.js`) when using Python. Reload after source edits.
+
+## Read the page
+
+The same branch contains three named controllers. Each labels a different hook:
+
+```python
+observed.dataController(func="record", stage="init", _init=True)
+observed.dataController(func="record", stage="built", _onBuilt=True)
+observed.dataController(func="record", stage="start", _onStart=True)
+```
+
+Data setters run before these hooks. `_init` installs initial behavior, `_onBuilt` follows the first successful build, and `_onStart` follows readiness. A separate timer controller uses `_timing=1` (seconds). Hook delays, if numeric, are milliseconds. The trace and tick count are ordinary Data, displayed outside the removable branch.
+
+Inspect uses `gramlot.dom.getDomNode(sourceNode)` and `getBaseSourceNode(domNode)` for read-only identity lookup. It does not mutate the DOM. `node_id` locates Source; the separate HTML `id` locates the rendered element.
+
+## Try it and predict the result
+
+1. Open the page: Hook trace becomes `init → built → start`. Data ticks begins at 1 because the timer also has `_onStart=True`.
+2. Press Inspect: expect `Source → DOM → same Source`.
+3. Freeze; wait two seconds. Both Data ticks and the number already built inside the branch continue increasing. Freeze defers structural Source projection, not updates to existing bound text.
+4. Thaw: the three hooks are not appended again. Compare b08, where pending structural removals appear at thaw.
+5. Remove branch and wait two seconds: its DOM disappears, the hook trace remains unchanged and ticks stop. Timer cancellation is observed from the stopped counter; the page does not invent a disposal hook. Inspect now reports `Source branch absent`. Reload to restore the original branch.
+
+## Change it and check yourself
+
+Change `_timing=1` to 2 in the Python timer declaration (or `_timing: 2` in JS), then reload.
+
+**Answer:** the initial start still adds one tick; subsequent ticks are about two seconds apart. Do not change `_onStart` to 2 expecting seconds: its numeric delay uses milliseconds.
+
+Advanced: freeze, then remove the branch before thawing. The Data ticks stop even though the frozen DOM remains visible. Inspect reports that Source is absent. The buttons no longer find that removed Source branch, so reload to reset this trial. Use the Data count as the cleanup evidence, not whether old pixels are still visible.
+
+## The same example across stages
+
+b08 introduced a frozen visual branch. This lesson revisits it with explicit lifecycle observations. Compared with e13's manually owned animation timer, `_timing` owns repeated controller scheduling and cancellation: no page timer handle or `clearInterval` is needed. Source/DOM lookup is diagnostic; it does not introduce another state system.
+
+## Limits and next step
+
+Freeze defers structural projection and insertion/rebuild work; existing nodes still follow Data. Removing a branch is different from hiding it. This page uses named Logic; no new lifecycle hook or timer implementation is invented. Full page disposal also ends its providers. Late startup and insertion while frozen are advanced contract cases, not extra steps needed for the basic trace.
+
+Continue with [c16 · Attribute projection](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/16_attribute_projection.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) provides the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/16_attribute_projection.js

@@ -0,0 +1,25 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Attribute projection';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'projection'});
+        pane.h1('Attribute projection');
+        pane.h2('0.2.0: one value, several projections');
+        pane.html_label('Name', {for: 'name'});
+        pane.input({value: '^.name', live: true, id: 'name'});
+        pane.p('^.name', {mask: 'Hello, %s', id: 'greeting'});
+        pane.div('Hover to read the title', {customer: '^.name', title: 'Customer: ${customer}', id: 'card'});
+        pane.p('The template consumes customer; it is not a DOM attribute.');
+        pane.h2('0.2.3: a separate HTML preview');
+        pane.html_label('Preview HTML', {for: 'html'});
+        pane.textarea({value: '^.html', live: true, id: 'html'});
+        pane.iframe({srcdoc: '^.html', title: 'Sandboxed preview', id: 'preview'});
+        pane.p('Data-bound srcdoc receives an empty sandbox; this preview only displays content.');
+        pane.dataSetter({destination_path: '.name', value: 'Ada'});
+        pane.dataSetter({destination_path: '.html', value: '<h2>Hello, Ada</h2><p>A separate document.</p>'});
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/controllers/16_attribute_projection.md

@@ -0,0 +1,58 @@
+# 16 · Attribute projection
+
+One name appears in a greeting and a tooltip with different formatting. You learn how templates and masks reuse a bound value without copying text. The later **0.2.3** section previews HTML in a separate sandboxed frame.
+
+**Uses:** Data binding, attribute templates and text masks (0.2.0); sandboxed Data `srcdoc` only in the later part (0.2.3).
+
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** core 0.2.0 templates/masks, followed by the separate 0.2.3 Data-srcdoc sandbox step.
+
+**Goal:** Reuse one Data value in text and attributes, then distinguish text from a sandboxed HTML document.
+
+**Before this lesson:** [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md), [b06 · Style and visibility](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/06_style_and_visibility.md), [c04 · Inline expressions](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/04_inline_expressions.md).
+
+**Open and edit:** open this page in your environment's gallery. Read Python first; Python builds Source on the host and named JavaScript Logic runs in the browser. The JavaScript Page is the equivalent host/Worker declaration. The gallery shows source; to change it, copy the page into your editable project following the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md). This page needs no Logic methods; compare the Python and JavaScript Page declarations. Reload after source edits.
+
+## Read the page
+
+A template reads another attribute of its own Source node **after pointer resolution**:
+
+```python
+pane.div("Hover to read the title", customer="^.name",
+         title="Customer: ${customer}")
+pane.p("^.name", mask="Hello, %s")
+```
+
+`${customer}` is Gramlot syntax, not Python interpolation. `customer` supplies the template and is consumed instead of becoming a DOM attribute. `mask` formats the projected text; it does not enable HTML.
+
+The later section uses `pane.iframe(srcdoc="^.html", ...)`. Data-provided HTML gets `sandbox=""`: it is an isolated document, with scripts/forms/popups blocked by default. Ordinary `pane.p("^.html")` would show literal markup instead.
+
+## Try it and predict the result
+
+1. Initially the greeting is “Hello, Ada”; hover the card and expect title “Customer: Ada”.
+2. Type Grace: both follow the same Data value. Inspect the card: it has `title`, but no `customer` attribute.
+3. Clear Name: the greeting becomes empty; the title retains its authored prefix.
+4. Replace Preview HTML with `<h2>Preview two</h2><p>Only this frame changes.</p>`. The heading appears inside the frame; the outer page stays intact. Inspect the iframe's `sandbox` attribute: it is present with an empty value.
+
+## Change it and check yourself
+
+Change the mask to `Welcome, %s` and the title to `Guest: ${customer}`. Leave the Data pointer alone.
+
+**Answer:** one Name edit still updates both destinations with different formatting; no extra provider or shared formatted Data value is needed.
+
+Separate invalid-edit exercise: rename only the template reference to `${missing}`, then reload. Expect an unknown-template-parameter error, not a blank substitute. Restore it. A preceding backslash escapes `${`; an `==` attribute cannot supply a template parameter, and `==` expressions cannot contain a template. See the reference for the permitted expression/template dependency order.
+
+## The same example across stages
+
+e02 taught literal text; b01 added a pointer. The 0.2.0 stage now adds presentation around that same value without a controller copying strings into multiple outputs. The 0.2.3 section is explicitly later: an iframe preview is not a replacement for safe literal text, and the sandbox does not imply a widget or raw-HTML injection API.
+
+## Limits and next step
+
+Templates apply to visual attributes, not node text or data-element declarations. A static Python f-string runs on the host once. A mask never interprets HTML. Keep the default empty sandbox for this exercise; do not add script permissions. A literal authored srcdoc has a different contract. JavaScript counterparts use quoted template text here, not JS backtick interpolation.
+
+Continue with [c17 · Data exchange](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/17_data_exchange.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) provides the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/17_data_exchange.js

@@ -0,0 +1,51 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Data exchange';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'exchange'});
+        pane.h1('Data exchange');
+        const form = pane.section({class: 'card stack', datapath: '.record'});
+        form.html_label('Name', {for: 'name'});
+        form.input({value: '^.name', id: 'name'});
+        form.html_label('Seats', {for: 'seats'});
+        form.input({type: 'number', value: '^.seats', id: 'seats'});
+        form.html_label('Confirmed', {for: 'confirmed'});
+        form.input({type: 'checkbox', value: '^.confirmed', id: 'confirmed'});
+        form.p('The record also contains a null note and a nested address.');
+        const actions = pane.div({class: 'actions'});
+        for (const [label, method] of [['Inspect types', 'inspect'], ['Save TYTX', 'save'],
+            ['Restore TYTX', 'restore'], ['Export JSON', 'exportJson'], ['Export XML', 'exportXml'],
+            ['Preview email text', 'previewMail']]) {
+            actions.button(label, {type: 'button', id: method}).dataController({func: method});
+        }
+        pane.p('^.status', {id: 'status'});
+        pane.pre('^.types', {id: 'types'});
+        pane.pre('^.mail', {id: 'mail'});
+        pane.dataSetter({destination_path: '.record', value: {name: 'Ada', seats: 2, confirmed: true,
+            note: null, address: {city: 'Rome'}}});
+        pane.dataSetter({destination_path: '.status', value: 'Choose an action; files stay under your control.'});
+    }
+}
+
+export class Logic {
+    inspect(node) {
+        const record = node.GET('.record');
+        node.SET('.types', `name: ${typeof record.getItem('name')}
+seats: ${typeof record.getItem('seats')}
+confirmed: ${typeof record.getItem('confirmed')}
+note: ${record.getItem('note') === null ? 'null' : typeof record.getItem('note')}
+city: ${record.getItem('address.city')}`);
+    }
+    save(node) { this.page.utl.inout.save('exchange.record', 'registration.tytx.json'); node.SET('.status', 'TYTX download requested'); }
+    async restore(node) {
+        try {
+            await this.page.utl.inout.restore('exchange.record');
+            this.inspect(node); node.SET('.status', 'Restored typed Data');
+        } catch (error) { node.SET('.status', error.message); }
+    }
+    exportJson() { this.page.utl.inout.download('exchange.record', 'registration.json', 'json'); }
+    exportXml() { this.page.utl.inout.download('exchange.record', 'registration.xml', 'xml'); }
+    previewMail(node) { node.SET('.mail', this.page.utl.inout.mailText('exchange.record')); }
+}

package/src/gramlot_examples/pages/controllers/17_data_exchange.md

@@ -0,0 +1,61 @@
+# 17 · Data exchange
+
+Edit a record, save it as TYTX, change it again and restore the file. You learn how to save a whole Data Bag with its supported types. JSON/XML exports are for interchange, not Restore TYTX.
+
+The record contains text, numbers, a boolean, a null value and a nested address. The email button previews text only.
+
+**Uses:** Data binding, named Logic and local InOut utilities (0.2.5), with the utility name from 0.2.10. No HTTP service or email delivery.
+
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** core 0.2.5; the public `gramlot.utl.inout` spelling is from 0.2.10.
+
+**Goal:** Save and restore a typed Data Bag, and distinguish round-trip files from interchange exports.
+
+**Before this lesson:** [b09 · Forms with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/09_forms.md), [c03 · Named logic](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/03_named_logic.md), [c06 · Button controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/06_button_controller.md).
+
+**Open and edit:** open this page in your environment's gallery. Read Python first; Python builds Source on the host and named JavaScript Logic runs in the browser. The JavaScript Page is the equivalent host/Worker declaration. The gallery shows source; to change it, copy the page into your editable project following the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md). Read the **logic.js** tab (the Logic class from `17_data_exchange.js`) when using Python. Reload after source edits.
+
+## Read the page
+
+Python initializes one record with strings, a number, a boolean, a null note and a nested address. Three fields are editable.
+
+Each Python button declares one named method, for example:
+
+```python
+actions.button("Save TYTX", type="button").dataController(func="save")
+```
+
+Its Logic calls `this.page.utl.inout.save('exchange.record', 'registration.tytx.json')`. Restore opens the framework's file picker and waits for `restore(...)`; after it resolves, the fields follow the replaced Bag. Errors are written to the status. The application authors no file input, Blob, request envelope or DOM listener.
+
+## Try it and predict the result
+
+1. Press Inspect types: expect string, number, boolean, null, and city Rome.
+2. Edit Name to Grace and leave the field; set Seats to 3. Press Save TYTX and retain the downloaded file.
+3. Change Name again, then Restore TYTX and select that saved file: Name returns to Grace, Seats to 3, and Inspect still reports number, boolean and null for their respective fields.
+4. Export JSON and Export XML: inspect these files as interchange data, not as a Gramlot restore file. JSON is Bag’s list of `label`/`value`/`attr` nodes, not the plain-object JSON used by `sendHttp`; XML has a `record` root. Try restoring exported JSON; expect an error and the existing record to remain intact.
+5. Preview email text: inspect the leaf values, including the nested `address.city` line. This button only renders `mailText`; it does not open a mail program.
+
+## Change it and check yourself
+
+Add `"department": "Research"` to the initial Python record and a bound paragraph `form.p("^.department")` (the JS equivalent belongs in its object and Source).
+
+**Answer:** Save/Restore includes the new field without another serialization handler, because the utility operates on the whole Bag. Reloading resets the authored defaults; restoring reintroduces the saved values.
+
+Advanced transport study: `sendMail(path, email)` opens the user's mail program and has a 2000-character limit; it does not itself submit an email. `sendHttp(path, url)` posts JSON and rejects non-2xx responses; it is not a page endpoint call. Exercise these only with an explicitly chosen mail action or an environment-owned local receiving fixture. The common gallery supplies no HTTP receiver. The core's `inout.test.js` and `scripts/verify_inout_browser.mjs` show intercepted mail links and local HTTP checks; they are verification fixtures, not application networking code to copy. No real messages or external service requests are part of this trial.
+
+## The same example across stages
+
+b09 made a form share one Data record with its display. This later release lets the same record cross the file boundary: two utility calls replace bespoke serialization, file-choice and restore coordination. Earlier form examples remain valid without file operations. The next release stage introduces endpoints; a download is not server persistence.
+
+## Limits and next step
+
+**Scope of this lesson:** this example uses strings, numbers, booleans, null and nested Bags. Dates and decimals are deferred while [Bag issue #69](https://github.com/genro-org/genro-bag/issues/69) addresses typed object initialization in JavaScript and Python/JS API consistency. The owner accepted this reduced scope for now. The verified defect affects object initialization; it does not establish a failure of TYTX Save/Restore. No alternate initialization path is needed for this lesson.
+
+TYTX Save/Restore preserves supported types. JSON/XML exports are for other programs; the `.json` suffix alone does not make a file restorable. File dialogs require a user gesture. If you cancel a picker, the existing Data remains; start a new Restore action when ready. Browser download settings may prompt or save automatically. Named Logic handles these actions without an inline-code CSP requirement. The catalogue entry is a local file lesson; mail and HTTP environment checks are separately classified.
+
+Continue with [c09 · Endpoint](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/09_endpoint.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) provides the full contract.
+
+</details>

package/src/gramlot_examples/pages/controllers/18_publish_subscribe.js

@@ -0,0 +1,36 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Publish and subscribe';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'messages'});
+        pane.h1('The same action, two entry points');
+        pane.p('Compare the direct controller with a page topic. Both update the same summary.');
+        pane.dataSetter({destination_path: '.text', value: 'Hello'});
+        pane.html_label('Message', {for: 'message'});
+        pane.input({id: 'message', value: '^.text', live: true});
+        pane.button('Direct controller', {id: 'direct'}).dataController({func: 'save', text: '=.text'});
+        pane.button('Publish', {id: 'publish'}).dataController({func: 'publishMessage', text: '=.text'});
+        pane.dataController({func: 'save', subscribe_saved: true});
+        pane.p('^.summary', {id: 'summary'});
+        pane.button('Ask, then publish', {id: 'ask'}).dataController({func: 'publishMessage',
+            _ask: {title: 'Message', fields: [{name: 'text', lbl: 'Message', required: true}]}, text: '=.text'});
+        pane.h2('Two independent receivers');
+        for (const name of ['left', 'right']) {
+            const box = pane.section({class: 'card stack', datapath: `.${name}`});
+            box.h3(name[0].toUpperCase() + name.slice(1));
+            const target = box.dataController({func: 'receive', selfsubscribe_refresh: true});
+            box.button(`Send to ${name}`, {id: `send-${name}`}).dataController({func: 'sendToNode', target, text: '=.text'});
+            box.p('^.received', {id: `received-${name}`});
+            box.dataSetter({destination_path: '.text', value: `Hello ${name}`});
+        }
+    }
+}
+
+export class Logic {
+    save(node, {text, _reason}) { node.SET('.summary', `${text} (${_reason})`); }
+    publishMessage(node, {text}) { this.page.publish('saved', {text}); }
+    sendToNode(node, {target, text}) { target.publish('refresh', {text}); }
+    receive(node, {text}) { node.SET('.received', text); }
+}

package/src/gramlot_examples/pages/controllers/18_publish_subscribe.md

@@ -0,0 +1,20 @@
+# 18 · Publish and subscribe
+
+Revisit **Button controller**: one button calls a controller directly, another publishes a message to the same behavior. Then address two independent receivers without looking up their IDs, and collect a message in a dialog.
+
+**Uses:** Source, Data, named Logic, page/self subscriptions, authored references and native `ask` — core 0.2.18. No endpoint calls. Earlier lessons remain the 0.2.0 stage.
+
+**Try it:** edit Message, press Direct controller, then Publish. The summary is the same except for the trigger reason. Send to left: only the left receiver changes. Ask, then publish lets you edit the outgoing message; Cancel leaves the summary unchanged.
+
+<details>
+<summary>More detail</summary>
+
+The direct controller keeps the c06 click mechanism. The publishing controller knows the topic `saved`; `subscribe_saved=True` connects the receiver. The publisher does not need a Data trigger path to activate that receiver. Repeating the same message still delivers it.
+
+Each receiver declares `selfsubscribe_refresh=True`. Python passes that controller as `target`; Gramlot resolves the authored reference in the browser. `target.publish('refresh', {text})` addresses only that node. The JavaScript Page makes the same declaration, and both use the shared Logic class.
+
+`_ask` adds native field collection to the existing controller. It runs the controller once after confirmation and never after cancellation. This example uses named methods throughout; it does not need inline JavaScript evaluation. For a conditional confirmation use a string `_ask` with `_ask_if`; those inline conditions need the corresponding CSP policy.
+
+**Exercise:** subscribe a second controller to `saved`, writing another Data path. Predict whether both run when Publish is pressed. **Answer:** both run, in registration order; each should write its own result. A self-subscription does not also subscribe to the plain page topic.
+
+</details>

package/src/gramlot_examples/pages/controllers/19_frame_messages.js

@@ -0,0 +1,39 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Parent and child messages';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'frames'});
+        pane.h1('Parent and child messages');
+        pane.dataSetter({destination_path: '.child', value: false});
+        pane.dataSetter({destination_path: '.text', value: 'Hello'});
+        pane.html_label('Message', {for: 'message'});
+        pane.input({id: 'message', value: '^.text', live: true});
+        const parent = pane.section({hidden: '^.child'});
+        const frame = parent.iframe({id: 'detail', title: 'Child page', style: 'width:100%;height:260px;border:1px solid #aab4c2'});
+        parent.button('Send to child', {id: 'send-child'}).dataController({func: 'sendChild', target: frame, text: '=.text'});
+        pane.button('Reply to parent', {id: 'reply'}).dataController({func: 'reply', text: '=.text', child: '=.child'});
+        pane.p('^.received', {id: 'received'});
+        pane.dataController({func: 'receive', subscribe_message: true});
+        pane.dataController({func: 'setup', frame, _onStart: true});
+    }
+}
+
+export class Logic {
+    setup(node, {frame}) {
+        const url = new URL(this.page.dom.getDomNode(node.parentNode).ownerDocument.location.href);
+        const child = url.hash === '#child';
+        node.SET('.child', child);
+        if (!child) { url.hash = 'child'; frame.setAttr({src: url.href}); }
+    }
+    sendChild(node, {target, text}) {
+        try { this.page.publish({topic: 'message', iframe: target}, {text}); }
+        catch (error) { node.SET('.received', error.message); }
+    }
+    reply(node, {text, child}) {
+        if (child) this.page.publish({topic: 'message', parent: true}, {text});
+        else node.SET('.received', 'Use Reply inside the child page.');
+    }
+    receive(node, {text}) { node.SET('.received', text); }
+}

package/src/gramlot_examples/pages/controllers/19_frame_messages.md

@@ -0,0 +1,20 @@
+# 19 · Parent and child messages
+
+Send a message to the embedded page, then reply from that page. The example reuses the page-topic receiver from **Publish and subscribe** and adds a destination to `publish`.
+
+**Uses:** Source, Data, named Logic, authored iframe references and direct parent/child `postMessage` — core 0.2.18. No endpoint calls or server messaging.
+
+**Try it:** wait for the child field to appear, edit the outer Message and press Send to child. Both summaries change: publication is local first, then reaches the selected child. Edit the child's Message and press its Reply to parent. The child publishes locally first and the parent receives the reply.
+
+<details>
+<summary>More detail</summary>
+
+The same page opens with `#child` inside the iframe. Its setup controller hides the parent section and does not load another iframe, so nesting stops after one child. The URL hash is only this example's mode selector; it is not a messaging address.
+
+Python passes the iframe Source as `target`. Logic uses `{topic: 'message', iframe: target}`. The child uses `{topic: 'message', parent: true}`. All cross-frame calls use postMessage, including same-origin pages; each receiving page activates its ordinary subscribe_message controller.
+
+The child must be connected and ready. An early click reports the readiness error; retry after the child appears. There is no automatic queue or broadcast. Source/DOM objects stay local: the iframe reference selects a local destination, while only the message data crosses the connection. Reloading the child establishes a new connection.
+
+**Exercise:** add another owned child and send only to its reference. **Answer:** local delivery still occurs, but only the selected child receives the remote copy. There is no recursive broadcast in this release.
+
+</details>

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

@@ -1,11 +1,67 @@
 # Controllers
 
+Add calculations and actions to bound pages, then calls to their host. Each stage uses the earlier building blocks plus only the features listed here.
+
+- **0.2.0:** local formulas, controllers, Logic, events and lifecycle. Begin with **Formula**; the first part of **End-to-end story** combines them without a host call.
+- **0.2.3:** the later part of **Attribute projection** adds a sandboxed HTML preview.
+- **0.2.5:** revisit **Named logic** for the shared module layout; **Data exchange** adds local file save/restore, using the utility name introduced in 0.2.10.
+- **0.2.14:** **Endpoint**, **Call on change** and **Call on click** add `dataRpc`. Then revisit the quote section of **End-to-end story** with the same inputs.
+- **0.2.15:** the later part of **Call on click** adds Source authorization.
+- **0.2.16:** **Remote**, **Cached remote** and **Data remote** add Source fragments and values loaded on demand.
+
+- **0.2.18:** revisit **Button controller** in **Publish and subscribe**, then use **Parent and child messages** for direct iframe exchange. These pages require core 0.2.18 or later.
+
+The host is Python, Node/Bun or a standalone browser Worker. Local Logic runs in the browser. Stable example numbers identify pages; the menu follows release order.
+
+<details>
+<summary>More detail</summary>
+
+
 The pages of this family run code when the Data changes.
 
 `dataFormula` computes a value and writes it to its result path. `dataController` runs code for its effects. `dataRpc` calls an endpoint of the page on the server and writes the answer to its result path. `remote` makes the content of an element a fragment built by the page on the server; `dataRemote` makes a Data path a value computed by an endpoint when it is read. A button runs a nested controller at every click; `connect_on<event>` attributes connect other DOM events. The code is inline in the page, or a method of the `Logic` class that the page module `NN_name.js` exports; the Python page takes it from there.
 
 Inline code needs a Content Security Policy that allows it. Named logic in the `Logic` class also runs under a strict policy.
 
-Start with **Formula** and **Controller**, then move the code to the `Logic` class with **Named logic**. **End-to-end story** puts every piece of the two families on one page. Six pages call the server. **Endpoint**, **Call on change** and **Call on click** use `dataRpc`; **Remote** and **Cached remote** mount a fragment of the page with `remote`; **Data remote** computes a Data value with `dataRemote`.
+Start with **Formula** and **Controller**, then move the code to the `Logic` class with **Named logic**. **End-to-end story** preserves its local binding/lifecycle stage and adds a separately labelled endpoint trial to revisit later. Seven pages call the server. **End-to-end story** (later section), **Endpoint**, **Call on change** and **Call on click** use `dataRpc`; **Remote** and **Cached remote** mount a fragment of the page with `remote`; **Data remote** computes a Data value with `dataRemote`.
 
 Each example has a Python page and its JavaScript equivalent. Both use the `Logic` class of the JavaScript module. An endpoint is a method of the page in each language: Python `@endpoint`, JavaScript `Page.registerEndpoint`. A fragment method is declared with Python `@source`, JavaScript `Page.registerSource`.
+
+## Prerequisites within the release sequence
+
+The 0.2.0 stage starts with c01/c02's calculation/effect distinction, then c03 for the
+recommended named-Logic form. c06/c09/c11 teach click, server value and errors;
+c12 teaches Source replacement in the later 0.2.16 stage.
+The Page/Logic module arrangement is a 0.2.5 addition to the named-logic lesson. c08's first pass combines local binding/lifecycle. Return after c09/c11 for its
+0.2.14 quote/result/error section; it does not run automatically or add remote/lazy Data. After b02 and c12, use c13
+for a first cache trial; c14 needs the endpoint concepts of c09/c10. Advanced
+cache/lifecycle exercises are separate in c13/c14; their corrected cache behavior
+is available from core 0.2.17. 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.
+
+_userChanges filters exact-path changes, not user versus programmatic input.
+Named connect_on handlers require dotted resource groups, unlike a root func
+method in c03; the common FileServer gallery has no such resource host.
+
+## 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.
+
+
+## Added depth in release order
+
+After the local c08 stage, use c15 for lifecycle (0.2.0), c16 for attribute
+projection (0.2.0) and its separately labelled sandbox step (0.2.3), then c17 for
+Data exchange (0.2.5, utility path since 0.2.10). Continue with c09–c11 (0.2.14),
+return to c08's 0.2.14 quote extension, then c11's later Source-auth section (0.2.15), and c12–c14 (0.2.16). Stable keys are
+identifiers, not release numbers: their order in this menu follows these stages.
+The date initialization issue in c17 and named-resource-host prerequisites remain
+explicit gaps; the local file lesson does not imply HTTP service or mail delivery.
+
+</details>