From 9f29f30a68b1590bd4a64127f494eb67354299a2 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Sun, 25 Oct 2026 22:33:21 +0000 Subject: [PATCH 01/19] feat: section on widgets --- Manual/Interaction.lean | 3 + Manual/Interaction/Widgets.lean | 269 ++++++++++++++++++++++++++++++++ 2 files changed, 272 insertions(+) create mode 100644 Manual/Interaction/Widgets.lean diff --git a/Manual/Interaction.lean b/Manual/Interaction.lean index e0ca9af59..aef34e343 100644 --- a/Manual/Interaction.lean +++ b/Manual/Interaction.lean @@ -8,6 +8,7 @@ import VersoManual import Manual.Meta import Manual.Interaction.FormatRepr +import Manual.Interaction.Widgets open Lean.MessageSeverity @@ -754,3 +755,5 @@ info: Tree.branches ::: {include 1 Manual.Interaction.FormatRepr} + +{include 1 Manual.Interaction.Widgets} diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean new file mode 100644 index 000000000..8c1654f5b --- /dev/null +++ b/Manual/Interaction/Widgets.lean @@ -0,0 +1,269 @@ +/- +Copyright (c) 2026 Lean FRO LLC. All rights reserved. +Released under Apache 2.0 license as described in the file LICENSE. +Author: Wojciech Nawrocki +-/ + +import VersoManual + +import Manual.Meta +import Lean.Widget + +open Verso.Genre Manual InlineLean +open Lean Widget + +#doc (Manual) "Widgets" => +%%% +tag := "widgets" +%%% + +The widget system enables Lean code to define and render user interface components, loosely referred to as _widgets_. +In graphical development environments such as VS Code with the [official Lean extension](https://github.com/leanprover/vscode-lean4/), widgets are displayed in the [InfoView](https://github.com/leanprover/vscode-lean4/blob/master/vscode-lean4/manual/manual.md#infoview) (the editor panel that shows tactic states, messages, and other information relevant to the current cursor position). +Besides communicating additional information or visuals, widgets may manipulate Lean values and run Lean functions, as well as edit source files (for example in response to UI events). +To start using widgets, import {module}`Lean.Widget`. +:::TODO +- When verso#311 lands, note it as another usecase. +::: + +# Client-Side JavaScript + +In general, widgets combine client-side JavaScript code that executes in the InfoView with server-side Lean code implementing {ref "widgets-remote-procedure-calls"}[RPC method handlers]. +However, many widgets don't use RPC methods, so only have a client part. + +Client-side code is organized into {deftech (key := "widget module")}_widget modules_. +And [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) compatible with the {ref "widgets-javascript-environment"}[InfoView JavaScript environment] can be used as a widget module. +There are no generic requirements on its exports; requirements are imposed when some export is used in a specific way, for example as an {tech}[InfoView panel widget]. + +To register a widget module in Lean, tag its definition with the {attr}`widget_module` attribute. +The definition must have a type convertible to {name}`Widget.Module`, i.e., a type with a {name}`Widget.ToModule` instance. + +:::example "Registering a widget module" +```imports -show +import Lean.Data.Widget.UserWidget +``` +```lean -show +open Lean +``` +```lean +@[widget_module] +def foo : Widget.Module where + javascript := r#" + export default function() { return "Hello, world!" } + "# +``` +::: + +{docstring Widget.Module} + +{docstring +allowMissing Widget.ToModule} + +## InfoView JavaScript Environment +%%% +tag := "widgets-javascript-environment" +%%% + +The JavaScript environment in which widget modules execute is a standard browser environment, extended by the following Lean-specific features. + +: Preloaded Libraries + + These packages are preloaded. + Each can be imported by using its name as the module specifier (under the hood, an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) is configured). + For example, `import * as React from 'react'` would work. + - [`'react'`](https://www.npmjs.com/package/react), [`'react-dom'`](https://www.npmjs.com/package/react-dom), and `'react/jsx-runtime'` provide the [React](https://react.dev/) runtime shared with the InfoView. + - [`'@leanprover/infoview'`](https://www.npmjs.com/package/@leanprover/infoview) allows widgets to reuse UI components used by the InfoView, as well as to communicate with other parts of the InfoView, with the editor, and with the Lean language server. + Documentation can be found [here](https://leanprover.github.io/vscode-lean4/infoview). + +: Importing by Hash + + A widget module may import another widget module via the module specifier `'widget_module:hash,'`, where `` is the dependency's {name}`Widget.Module.javascriptHash`. + The imported module must be registered via `@[widget_module]` before the importing module is registered (i.e., it must be registered earlier in the same file, or be registered in an imported Lean module). + +## Bundling + +A {tech}[widget module] must be a single, self-contained JavaScript module. +In order to compile an [`npm`](https://www.npmjs.com/) package (with dependencies, TypeScript, and so on) into this format, one may use a _bundler_. +The following bundler-specific instructions may be useful. + +: [Rollup.js](https://rollupjs.org/) + + A working [Rollup.js configuration](https://github.com/leanprover-community/ProofWidgets4/blob/main/widget/rollup.config.js) for widgets can be found in the ProofWidgets package. + + - Set [`output.format`](https://rollupjs.org/guide/en/#outputformat) to `'es'` so that a module is produced. + - [Externalize](https://rollupjs.org/guide/en/#external) the preloaded libraries—`react`, `react-dom`, `react/jsx-runtime`, and `@leanprover/infoview`—so that their global state is not duplicated in your bundle. + +: [esbuild](https://esbuild.github.io/) + + Does not work due to issue [evanw/esbuild#1944](https://github.com/evanw/esbuild/issues/1944). + +# Displaying Widgets + +Widgets are [React components](https://react.dev/learn/your-first-component) exported from widget modules. +The InfoView is a React application, and is capable of embedding these components. +A widget must be the [`default` export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export) of its module. + +When registering a widget for display in Lean, we can provide [props](https://react.dev/learn/passing-props-to-a-component) that it will receive when it is rendered by the InfoView. +In Lean, a {name}`Widget.WidgetInstance` bundles such an assignment of props together with a reference to the widget module that exports the component being instantiated. +The assignment is stored as a {name}`Json` object—later decoded into a JavaScript object—and more generally a {lean}`StateM Server.RpcObjectStore Json` computation, in order to support {ref "widgets-remote-procedure-calls"}[RPC references]. + +{docstring Widget.WidgetInstance} + +Lean can display widgets in two ways: within messages in the {tech}[message log], or as {tech (key := "InfoView panel widget")}[InfoView panels] associated with a source span. + +: Widgets in Messages + + A widget component is displayed inline in a Lean message. + + {docstring MessageData.ofWidget} + +: InfoView Panels + + By default, the InfoView conveys information about a given position in a Lean source file by means of three panels: _Tactic state_, _Expected type_, and _Messages_. + This listing can be extended by user-defined panels (appearing below _Expected type_), for instance to render tactic states in custom proof modes. + + Such an {deftech}_InfoView panel widget_ is associated with a source span. + It is drawn whenever the InfoView is describing a position within this span (either because the editor cursor is there, or because that position is [pinned](https://github.com/leanprover/vscode-lean4/blob/master/vscode-lean4/manual/manual.md#status-bar)). + + :::sectionNote + Panel widgets saved by {name}`Widget.savePanelWidgetInfo` are stored in the enclosing command's {tech (key := "info trees")}[info tree], while those saved by {keywordOf Lean.Widget.showPanelWidgetsCmd}`show_panel_widgets` are stored in an environment extension. + ::: + + - To associate a widget instance with the span of a piece of {name}`Lean.Syntax`, use {name}`Widget.savePanelWidgetInfo`. + - To associate it with all positions in a Lean module, scope, or set of modules downstream of a given module, use the {keywordOf Lean.Widget.showPanelWidgetsCmd}`show_panel_widgets` command. + + {docstring Widget.savePanelWidgetInfo} + + When rendering a panel widget, the InfoView extends the props object obtained from the {name}`Widget.WidgetInstance` by additional, automatically computed properties that reflect the editor state (for instance the current cursor position). + These additional props are documented as [`PanelWidgetProps`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.PanelWidgetProps.html). + + A panel widget should be collapsible (conventionally a [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) element). + + A panel widget is re-rendered when the source position it describes is re-elaborated. + +:::example "Displaying widgets with the #widget command" +A panel widget is associated with the source line the {keywordOf Lean.Widget.widgetCmd}`#widget` command appears on. +Internally, this command invokes {name}`Widget.savePanelWidgetInfo`. + +```imports -show +import Lean.Widget +``` +```lean -show +open Lean +``` +```lean +@[widget_module] +def helloWidget : Widget.Module where + javascript := " + import * as React from 'react'; + export default function(props) { + const name = props.name || 'world' + return React.createElement('p', {}, 'Hello, ' + name + '!') + }" + +#widget helloWidget with json% { name: "Hexapus" } +``` +::: + +# Remote Procedure Calls +%%% +tag := "widgets-remote-procedure-calls" +%%% + +The InfoView—together with any embedded widgets—is a web application running on the same computer as the IDE. +The Lean language server, which {tech (key := "Lean elaborator")}[elaborates] source files and interprets Lean code, is a separate process. +The two may be resident on two different machines, e.g. when using Lean in a server-backed web IDE or over SSH. + +It can be useful for widgets to maintain part of their state or input data in the server, as opposed to sending it to the client. +Transfer may be impractical due to a slow network, and objects may not be easily serializable (as is the case for closures, {name}`IO.Promise`s, or {name}`Lean.Environment`s). +The Remote Procedure Call (RPC) mechanism allows client-side widget code to manipulate {tech (key := "RPC reference")}[RPC references] to server-side data, and to execute {tech (key := "RPC method")}[RPC methods] in the server. + +## Encoding and References + +The {name}`Server.RpcEncodable` typeclass marks client-server transferrable types. +The wire format is JSON, and any type with both {name}`Lean.ToJson` and {name}`Lean.FromJson` instances is encodable. +An instance can be derived automatically, as documented below. + +The main purpose of {name}`Server.RpcEncodable` is to support—in addition to JSON—structures containing {deftech (key := "RPC reference")}[RPC references]. +Every reference is marked with the {name}`Server.WithRpcRef` wrapper. +A value wrapped with {name}`Server.WithRpcRef` is not serialized during transfer. +Instead, the client receives an opaque identifier that can later be used to retrieve the value server-side, in an {tech}[RPC method] call. + +::::leanSection +```lean -show +variable (α : Type) +``` +The type {lean}`α` must have a {name}`TypeName` instance for {lean}`Server.RpcEncodable (Server.WithRpcRef α)` to be inhabited. + +:::example "TypeName and imported constants" +We discourage deriving {lean}`TypeName α` outside of the module where {lean}`α` is defined. +Instead, define a single-field structure (a “newtype”) wrapping {lean}`α`, and derive {lean}`TypeName` for that. +```lean +structure MyNat where + val : Nat + deriving TypeName +``` +::: +:::: + +{docstring +allowMissing Server.RpcEncodable} + +{docstring +allowMissing Server.WithRpcRef} + +Use {name}`Server.WithRpcRef.mk` to construct references. + +{docstring Server.WithRpcRef.mk} + +## RPC Methods +### Server + +:::leanSection +```lean -show +variable (α β : Type) +``` +To register an {deftech}[RPC method], use the {attr}`server_rpc_method` attribute. +The method must be a function of type {lean}`α → Server.RequestM (Server.RequestTask β)`, where `α` and `β` are {name}`Server.RpcEncodable`. + +The {name}`Server.RequestM` monad supports IO actions, and provides access to parts of the language server state. + +The output is wrapped in {name}`Server.RequestTask` to support asynchronous execution of RPC methods. +Ideally, a method implementation returns immediately, doing most of its work in the returned task. +The {name}`Server.RequestM.asTask` convenience function does exactly this. +::: + +:::example "Registering an RPC method" +```imports -show +import Lean.Widget +``` +```lean -show +open Lean +``` +```lean +structure Args where + n : Nat + deriving TypeName + +@[server_rpc_method] +def extract (args : Server.WithRpcRef Args) : + Server.RequestM (Server.RequestTask Nat) := + Server.RequestM.asTask <| return args.val.n +``` +::: + +:::sectionNote +As an alternative to passing {name}`Server.WithRpcRef` values as RPC method arguments, RPC methods may refer to global {name}`IO.Ref`s. +However, these behave differently. +A single copy of the {name}`IO.Ref` resides in server memory and is shared by all widgets that refer to it, whereas distinct RPC references can be created for each widget instance. +Make sure not to accidentally share state that you did not intend to across copies of your UI component. +::: + +### Client + +:::sectionNote +The RPC system does not depend on JavaScript. +Any LSP client may create RPC sessions and invoke RPC methods. +::: + +Widget React components may invoke RPC methods. +To do so, the component should first use the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/docs/functions/index.useRpcSession.html) hook. +This gives an _RPC session_ handle tied to a specific position in a Lean source file. +The handle may be used to call RPC methods registered in Lean code above that position (including in imported modules); +see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.RpcSessionAtPos.html#call). From 863764f020cbfdf57a8f7c1de163633f1d74a286 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Mon, 26 Oct 2026 19:38:54 +0000 Subject: [PATCH 02/19] fix: imports --- Manual/Interaction/Widgets.lean | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 8c1654f5b..33f5c5809 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -39,7 +39,7 @@ The definition must have a type convertible to {name}`Widget.Module`, i.e., a ty :::example "Registering a widget module" ```imports -show -import Lean.Data.Widget.UserWidget +import Lean.Widget.UserWidget ``` ```lean -show open Lean @@ -144,7 +144,7 @@ A panel widget is associated with the source line the {keywordOf Lean.Widget.wid Internally, this command invokes {name}`Widget.savePanelWidgetInfo`. ```imports -show -import Lean.Widget +import Lean.Widget.Commands ``` ```lean -show open Lean @@ -231,7 +231,7 @@ The {name}`Server.RequestM.asTask` convenience function does exactly this. :::example "Registering an RPC method" ```imports -show -import Lean.Widget +import Lean.Server.Rpc ``` ```lean -show open Lean From 20629bec1748f3f41f14351bc08c4ead9122b8b5 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Mon, 26 Oct 2026 20:01:43 +0000 Subject: [PATCH 03/19] chore: silence Vale --- .vale/styles/config/ignore/terms.txt | 6 ++++-- Manual/Interaction/Widgets.lean | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.vale/styles/config/ignore/terms.txt b/.vale/styles/config/ignore/terms.txt index 9b62e2f18..377ff31d0 100644 --- a/.vale/styles/config/ignore/terms.txt +++ b/.vale/styles/config/ignore/terms.txt @@ -9,8 +9,6 @@ Goguen Kissat Kleisli Mathlib's -Noncomputable -Nullability Packrat antiquotation's antiquotations @@ -81,10 +79,12 @@ effectful elaborator elaborator's elaborators +encodable enum entailment entailments equational +esbuild executable's extensional extensionality @@ -175,6 +175,7 @@ postfix poststate predicative predicativity +preloaded prepending preprocesses propositionally @@ -201,6 +202,7 @@ selectable's semigroup semireducible semiring +serializable setoid setoid's setoids diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 33f5c5809..31425731e 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -178,7 +178,7 @@ The Remote Procedure Call (RPC) mechanism allows client-side widget code to mani ## Encoding and References -The {name}`Server.RpcEncodable` typeclass marks client-server transferrable types. +The {name}`Server.RpcEncodable` type class marks client-server transferrable types. The wire format is JSON, and any type with both {name}`Lean.ToJson` and {name}`Lean.FromJson` instances is encodable. An instance can be derived automatically, as documented below. From b73105c5049b36b8ae077caee5ca3d586c15d88d Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Mon, 26 Oct 2026 21:28:52 +0000 Subject: [PATCH 04/19] copyedit --- Manual/Interaction/Widgets.lean | 99 +++++++++++++++++---------------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 31425731e..f6bc1a450 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -31,7 +31,7 @@ In general, widgets combine client-side JavaScript code that executes in the Inf However, many widgets don't use RPC methods, so only have a client part. Client-side code is organized into {deftech (key := "widget module")}_widget modules_. -And [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) compatible with the {ref "widgets-javascript-environment"}[InfoView JavaScript environment] can be used as a widget module. +Any [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) compatible with the {ref "widgets-javascript-environment"}[InfoView JavaScript environment] can be used as a widget module. There are no generic requirements on its exports; requirements are imposed when some export is used in a specific way, for example as an {tech}[InfoView panel widget]. To register a widget module in Lean, tag its definition with the {attr}`widget_module` attribute. @@ -76,12 +76,11 @@ The JavaScript environment in which widget modules execute is a standard browser : Importing by Hash A widget module may import another widget module via the module specifier `'widget_module:hash,'`, where `` is the dependency's {name}`Widget.Module.javascriptHash`. - The imported module must be registered via `@[widget_module]` before the importing module is registered (i.e., it must be registered earlier in the same file, or be registered in an imported Lean module). ## Bundling A {tech}[widget module] must be a single, self-contained JavaScript module. -In order to compile an [`npm`](https://www.npmjs.com/) package (with dependencies, TypeScript, and so on) into this format, one may use a _bundler_. +In order to compile an [`npm`](https://www.npmjs.com/) package (with dependencies, TypeScript, and so on) into this format, one typically uses a _bundler_. The following bundler-specific instructions may be useful. : [Rollup.js](https://rollupjs.org/) @@ -101,9 +100,9 @@ Widgets are [React components](https://react.dev/learn/your-first-component) exp The InfoView is a React application, and is capable of embedding these components. A widget must be the [`default` export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export) of its module. -When registering a widget for display in Lean, we can provide [props](https://react.dev/learn/passing-props-to-a-component) that it will receive when it is rendered by the InfoView. -In Lean, a {name}`Widget.WidgetInstance` bundles such an assignment of props together with a reference to the widget module that exports the component being instantiated. -The assignment is stored as a {name}`Json` object—later decoded into a JavaScript object—and more generally a {lean}`StateM Server.RpcObjectStore Json` computation, in order to support {ref "widgets-remote-procedure-calls"}[RPC references]. +When registering a widget for display in Lean, we provide [props](https://react.dev/learn/passing-props-to-a-component) that it will receive when it is rendered by the InfoView. +In Lean, a {name}`Widget.WidgetInstance` bundles such an assignment of props with a reference to the widget module that exports the component. +The assignment is stored as a {name}`Json` object—later decoded into a JavaScript object—and more generally a {lean}`StateM Server.RpcObjectStore Json` computation, in order to support {tech (key := "RPC reference")}[RPC references]. {docstring Widget.WidgetInstance} @@ -120,7 +119,7 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] By default, the InfoView conveys information about a given position in a Lean source file by means of three panels: _Tactic state_, _Expected type_, and _Messages_. This listing can be extended by user-defined panels (appearing below _Expected type_), for instance to render tactic states in custom proof modes. - Such an {deftech}_InfoView panel widget_ is associated with a source span. + Such an {deftech}_InfoView panel widget_ is associated with a span—a range of characters—in the source code. It is drawn whenever the InfoView is describing a position within this span (either because the editor cursor is there, or because that position is [pinned](https://github.com/leanprover/vscode-lean4/blob/master/vscode-lean4/manual/manual.md#status-bar)). :::sectionNote @@ -128,40 +127,43 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] ::: - To associate a widget instance with the span of a piece of {name}`Lean.Syntax`, use {name}`Widget.savePanelWidgetInfo`. - - To associate it with all positions in a Lean module, scope, or set of modules downstream of a given module, use the {keywordOf Lean.Widget.showPanelWidgetsCmd}`show_panel_widgets` command. - {docstring Widget.savePanelWidgetInfo} + {docstring Widget.savePanelWidgetInfo} + + - To associate it with all positions in a Lean module, scope, or set of modules downstream of a given module, use the {keywordOf Lean.Widget.showPanelWidgetsCmd}`show_panel_widgets` command. - When rendering a panel widget, the InfoView extends the props object obtained from the {name}`Widget.WidgetInstance` by additional, automatically computed properties that reflect the editor state (for instance the current cursor position). + When rendering a panel widget, the InfoView extends the props object obtained from the {name}`Widget.WidgetInstance` with additional, automatically computed properties that reflect the editor state (for instance the current cursor position). These additional props are documented as [`PanelWidgetProps`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.PanelWidgetProps.html). A panel widget should be collapsible (conventionally a [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) element). A panel widget is re-rendered when the source position it describes is re-elaborated. -:::example "Displaying widgets with the #widget command" -A panel widget is associated with the source line the {keywordOf Lean.Widget.widgetCmd}`#widget` command appears on. -Internally, this command invokes {name}`Widget.savePanelWidgetInfo`. - -```imports -show -import Lean.Widget.Commands -``` -```lean -show -open Lean -``` -```lean -@[widget_module] -def helloWidget : Widget.Module where - javascript := " - import * as React from 'react'; - export default function(props) { - const name = props.name || 'world' - return React.createElement('p', {}, 'Hello, ' + name + '!') - }" - -#widget helloWidget with json% { name: "Hexapus" } -``` -::: + Finally, the {keywordOf Lean.Widget.widgetCmd}`#widget` command can be used to quickly render a panel widget. + + :::example "Using the #widget command" + The panel widget is associated with the source line the command appears on. + Internally, this command invokes {name}`Widget.savePanelWidgetInfo`. + + ```imports -show + import Lean.Widget.Commands + ``` + ```lean -show + open Lean + ``` + ```lean + @[widget_module] + def helloWidget : Widget.Module where + javascript := " + import * as React from 'react'; + export default function(props) { + const name = props.name || 'world' + return React.createElement('p', {}, 'Hello, ' + name + '!') + }" + + #widget helloWidget with json% { name: "Hexapus" } + ``` + ::: # Remote Procedure Calls %%% @@ -170,9 +172,9 @@ tag := "widgets-remote-procedure-calls" The InfoView—together with any embedded widgets—is a web application running on the same computer as the IDE. The Lean language server, which {tech (key := "Lean elaborator")}[elaborates] source files and interprets Lean code, is a separate process. -The two may be resident on two different machines, e.g. when using Lean in a server-backed web IDE or over SSH. +The InfoView and the language server may reside on two different machines, e.g. when using Lean in a server-backed web IDE or over SSH. -It can be useful for widgets to maintain part of their state or input data in the server, as opposed to sending it to the client. +It can be useful for widgets to maintain part of their state or input data in the server, as opposed to serializing and transferring it to the client. Transfer may be impractical due to a slow network, and objects may not be easily serializable (as is the case for closures, {name}`IO.Promise`s, or {name}`Lean.Environment`s). The Remote Procedure Call (RPC) mechanism allows client-side widget code to manipulate {tech (key := "RPC reference")}[RPC references] to server-side data, and to execute {tech (key := "RPC method")}[RPC methods] in the server. @@ -182,11 +184,15 @@ The {name}`Server.RpcEncodable` type class marks client-server transferrable typ The wire format is JSON, and any type with both {name}`Lean.ToJson` and {name}`Lean.FromJson` instances is encodable. An instance can be derived automatically, as documented below. +{docstring +allowMissing Server.RpcEncodable} + The main purpose of {name}`Server.RpcEncodable` is to support—in addition to JSON—structures containing {deftech (key := "RPC reference")}[RPC references]. Every reference is marked with the {name}`Server.WithRpcRef` wrapper. -A value wrapped with {name}`Server.WithRpcRef` is not serialized during transfer. +A value wrapped with {name}`Server.WithRpcRef` is not serialized or transferred to the client. Instead, the client receives an opaque identifier that can later be used to retrieve the value server-side, in an {tech}[RPC method] call. +{docstring +allowMissing Server.WithRpcRef} + ::::leanSection ```lean -show variable (α : Type) @@ -204,11 +210,7 @@ structure MyNat where ::: :::: -{docstring +allowMissing Server.RpcEncodable} - -{docstring +allowMissing Server.WithRpcRef} - -Use {name}`Server.WithRpcRef.mk` to construct references. +Use {name}`Server.WithRpcRef.mk` to construct RPC references. {docstring Server.WithRpcRef.mk} @@ -238,13 +240,13 @@ open Lean ``` ```lean structure Args where - n : Nat + num : Nat deriving TypeName @[server_rpc_method] -def extract (args : Server.WithRpcRef Args) : +def extractNum (args : Server.WithRpcRef Args) : Server.RequestM (Server.RequestTask Nat) := - Server.RequestM.asTask <| return args.val.n + Server.RequestM.asTask <| return args.val.num ``` ::: @@ -262,8 +264,7 @@ The RPC system does not depend on JavaScript. Any LSP client may create RPC sessions and invoke RPC methods. ::: -Widget React components may invoke RPC methods. -To do so, the component should first use the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/docs/functions/index.useRpcSession.html) hook. -This gives an _RPC session_ handle tied to a specific position in a Lean source file. -The handle may be used to call RPC methods registered in Lean code above that position (including in imported modules); -see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.RpcSessionAtPos.html#call). +Any widget React component may invoke RPC methods. +To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/docs/functions/index.useRpcSession.html) hook. +The handle may then be used to call RPC methods; see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.RpcSessionAtPos.html#call). + From 310dc113ea3f943b65b8a3e030f572a9ac28ae89 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Mon, 26 Oct 2026 22:27:14 +0000 Subject: [PATCH 05/19] better examples --- Manual/Interaction/Widgets.lean | 91 ++++++++++++++++++++++++++++----- 1 file changed, 77 insertions(+), 14 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index f6bc1a450..68ee4e838 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -152,16 +152,20 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] open Lean ``` ```lean + structure Props where + name : String + deriving FromJson, ToJson + @[widget_module] def helloWidget : Widget.Module where javascript := " import * as React from 'react'; export default function(props) { const name = props.name || 'world' - return React.createElement('p', {}, 'Hello, ' + name + '!') + return React.createElement('b', {}, 'Hello, ' + name + '!') }" - #widget helloWidget with json% { name: "Hexapus" } + #widget helloWidget with { name := "Hexapus" : Props } ``` ::: @@ -186,6 +190,11 @@ An instance can be derived automatically, as documented below. {docstring +allowMissing Server.RpcEncodable} +:::sectionNote +RPC references are not JSON-serializable without additional state in the encoder, so require {name}`Server.RpcEncodable`. +But for data structures that do have JSON representations, prefer simply deriving {name}`FromJson` and {name}`ToJson`. +::: + The main purpose of {name}`Server.RpcEncodable` is to support—in addition to JSON—structures containing {deftech (key := "RPC reference")}[RPC references]. Every reference is marked with the {name}`Server.WithRpcRef` wrapper. A value wrapped with {name}`Server.WithRpcRef` is not serialized or transferred to the client. @@ -215,6 +224,14 @@ Use {name}`Server.WithRpcRef.mk` to construct RPC references. {docstring Server.WithRpcRef.mk} ## RPC Methods + +:::sectionNote +As an alternative to passing {name}`Server.WithRpcRef` values as RPC method arguments, RPC methods may refer to global {name}`IO.Ref`s. +However, these behave differently. +A single copy of the {name}`IO.Ref` is shared by all widgets that refer to it, whereas distinct RPC references can be created for each widget instance. +Make sure not to accidentally share state that you did not intend to across copies of your UI component by using {name}`IO.Ref`s. +::: + ### Server :::leanSection @@ -240,23 +257,18 @@ open Lean ``` ```lean structure Args where - num : Nat - deriving TypeName + str : Server.WithRpcRef String + deriving Server.RpcEncodable +/-- Extracts a string from a server-side cell +and sends it to the client. -/ @[server_rpc_method] -def extractNum (args : Server.WithRpcRef Args) : - Server.RequestM (Server.RequestTask Nat) := - Server.RequestM.asTask <| return args.val.num +def unwrapStr (args : Args) : + Server.RequestM (Server.RequestTask String) := + Server.RequestM.asTask <| return args.str.val ``` ::: -:::sectionNote -As an alternative to passing {name}`Server.WithRpcRef` values as RPC method arguments, RPC methods may refer to global {name}`IO.Ref`s. -However, these behave differently. -A single copy of the {name}`IO.Ref` resides in server memory and is shared by all widgets that refer to it, whereas distinct RPC references can be created for each widget instance. -Make sure not to accidentally share state that you did not intend to across copies of your UI component. -::: - ### Client :::sectionNote @@ -267,4 +279,55 @@ Any LSP client may create RPC sessions and invoke RPC methods. Any widget React component may invoke RPC methods. To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/docs/functions/index.useRpcSession.html) hook. The handle may then be used to call RPC methods; see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.RpcSessionAtPos.html#call). +Invoking RPC is an asynchronous operation that generally occurs in a [React effect](https://react.dev/reference/react/useEffect). +RPC methods are identified in JavaScript by their fully qualified Lean names. +:::example "Calling an RPC method" +As remarked above, widgets can receive RPC references as props. +In this example, we pass such a reference prop. +We then invoke an RPC method, using the reference as an argument. + +```imports -show +import Lean.Widget +``` +```lean -show +open Lean +``` +```lean +structure Args where + str : Server.WithRpcRef String + deriving Server.RpcEncodable + +@[server_rpc_method] +def unwrapStr (args : Args) : + Server.RequestM (Server.RequestTask String) := + Server.RequestM.asTask <| return args.str.val + +structure Props where + str : Server.WithRpcRef String + deriving Server.RpcEncodable + +@[widget_module] +def rpcCallWidget : Widget.Module where + javascript := r#" + import * as React from 'react' + import { useRpcSession } from '@leanprover/infoview' + + export default function({ str }) { + const rs = useRpcSession() + const [display, setDisplay] = React.useState() + React.useEffect(() => { + rs.call('unwrapStr', { str }).then(s => setDisplay(s)) + }, []) + return React.createElement('b', {}, [display]) + } + "# + +run_meta + let str ← Server.WithRpcRef.mk "Server-side hello!" + Widget.addPanelWidgetLocal { rpcCallWidget with + id := .anonymous + props := Server.rpcEncode { str : Props } + } +``` +::: From e30d53e1aa9cb21c3ef534deb3abfcd3f26e2a09 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 27 Oct 2026 15:09:17 +0000 Subject: [PATCH 06/19] fix: class --- Manual/Interaction/Widgets.lean | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 68ee4e838..22d8c842f 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -256,16 +256,16 @@ import Lean.Server.Rpc open Lean ``` ```lean -structure Args where - str : Server.WithRpcRef String - deriving Server.RpcEncodable +structure Cell where + str : String + deriving TypeName /-- Extracts a string from a server-side cell and sends it to the client. -/ @[server_rpc_method] -def unwrapStr (args : Args) : +def unwrapStr (cell : Server.WithRpcRef Cell) : Server.RequestM (Server.RequestTask String) := - Server.RequestM.asTask <| return args.str.val + Server.RequestM.asTask <| return cell.val.str ``` ::: @@ -294,17 +294,17 @@ import Lean.Widget open Lean ``` ```lean -structure Args where - str : Server.WithRpcRef String - deriving Server.RpcEncodable +structure Cell where + str : String + deriving TypeName @[server_rpc_method] -def unwrapStr (args : Args) : +def unwrapStr (cell : Server.WithRpcRef Cell) : Server.RequestM (Server.RequestTask String) := - Server.RequestM.asTask <| return args.str.val + Server.RequestM.asTask <| return cell.val.str structure Props where - str : Server.WithRpcRef String + cell : Server.WithRpcRef Cell deriving Server.RpcEncodable @[widget_module] @@ -313,21 +313,21 @@ def rpcCallWidget : Widget.Module where import * as React from 'react' import { useRpcSession } from '@leanprover/infoview' - export default function({ str }) { + export default function({ cell }) { const rs = useRpcSession() const [display, setDisplay] = React.useState() React.useEffect(() => { - rs.call('unwrapStr', { str }).then(s => setDisplay(s)) + rs.call('unwrapStr', cell).then(s => setDisplay(s)) }, []) return React.createElement('b', {}, [display]) } "# run_meta - let str ← Server.WithRpcRef.mk "Server-side hello!" + let cell ← Server.WithRpcRef.mk { str := "Server-side hello!" } Widget.addPanelWidgetLocal { rpcCallWidget with id := .anonymous - props := Server.rpcEncode { str : Props } + props := Server.rpcEncode { cell : Props } } ``` ::: From 0e48220d45e220a91a5dc07f50bea00310fd95d1 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 27 Oct 2026 16:54:12 +0000 Subject: [PATCH 07/19] fix: links --- Manual/Interaction/Widgets.lean | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 22d8c842f..57b54d72d 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -133,7 +133,7 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] - To associate it with all positions in a Lean module, scope, or set of modules downstream of a given module, use the {keywordOf Lean.Widget.showPanelWidgetsCmd}`show_panel_widgets` command. When rendering a panel widget, the InfoView extends the props object obtained from the {name}`Widget.WidgetInstance` with additional, automatically computed properties that reflect the editor state (for instance the current cursor position). - These additional props are documented as [`PanelWidgetProps`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.PanelWidgetProps.html). + These additional props are documented as [`PanelWidgetProps`](https://leanprover.github.io/vscode-lean4/infoview/interfaces/index.PanelWidgetProps.html). A panel widget should be collapsible (conventionally a [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) element). @@ -277,8 +277,8 @@ Any LSP client may create RPC sessions and invoke RPC methods. ::: Any widget React component may invoke RPC methods. -To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/docs/functions/index.useRpcSession.html) hook. -The handle may then be used to call RPC methods; see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/docs/interfaces/index.RpcSessionAtPos.html#call). +To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/functions/index.useRpcSession.html) hook. +The handle may then be used to call RPC methods; see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/interfaces/index.RpcSessionAtPos.html#call). Invoking RPC is an asynchronous operation that generally occurs in a [React effect](https://react.dev/reference/react/useEffect). RPC methods are identified in JavaScript by their fully qualified Lean names. From bb05aabb39be48bdf35e7e196be29addbef4d90e Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Fri, 6 Nov 2026 23:06:53 +0000 Subject: [PATCH 08/19] review 1 Co-authored-by: David Thrane Christiansen --- Manual/Interaction/Widgets.lean | 69 ++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 57b54d72d..b7863ba2e 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -18,8 +18,9 @@ tag := "widgets" %%% The widget system enables Lean code to define and render user interface components, loosely referred to as _widgets_. -In graphical development environments such as VS Code with the [official Lean extension](https://github.com/leanprover/vscode-lean4/), widgets are displayed in the [InfoView](https://github.com/leanprover/vscode-lean4/blob/master/vscode-lean4/manual/manual.md#infoview) (the editor panel that shows tactic states, messages, and other information relevant to the current cursor position). -Besides communicating additional information or visuals, widgets may manipulate Lean values and run Lean functions, as well as edit source files (for example in response to UI events). +In graphical development environments such as VS Code with the [official Lean extension](https://github.com/leanprover/vscode-lean4/), the {deftech (key := "InfoView")}[[InfoView](https://github.com/leanprover/vscode-lean4/blob/master/vscode-lean4/manual/manual.md#infoview)] is the editor panel that shows tactic states, messages, and other information relevant to the current cursor position. +Widgets are displayed in the InfoView. +In addition to communicating additional information or visuals, widgets may manipulate Lean values and run Lean functions, as well as edit source files (for example in response to UI events). To start using widgets, import {module}`Lean.Widget`. :::TODO - When verso#311 lands, note it as another usecase. @@ -27,17 +28,18 @@ To start using widgets, import {module}`Lean.Widget`. # Client-Side JavaScript -In general, widgets combine client-side JavaScript code that executes in the InfoView with server-side Lean code implementing {ref "widgets-remote-procedure-calls"}[RPC method handlers]. -However, many widgets don't use RPC methods, so only have a client part. +In general, widgets combine client-side JavaScript code that executes in the InfoView with server-side Lean code that implements {ref "widgets-remote-procedure-calls"}[RPC method handlers]. +However, many widgets don't use RPC methods, so they only have a client part. Client-side code is organized into {deftech (key := "widget module")}_widget modules_. Any [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) compatible with the {ref "widgets-javascript-environment"}[InfoView JavaScript environment] can be used as a widget module. -There are no generic requirements on its exports; requirements are imposed when some export is used in a specific way, for example as an {tech}[InfoView panel widget]. +A widget module may simply export utility functions for use in other modules, so there are no generic requirements on its exports. +Requirements are imposed when an export is used in a specific way, for example as an {tech}[InfoView panel widget]. To register a widget module in Lean, tag its definition with the {attr}`widget_module` attribute. -The definition must have a type convertible to {name}`Widget.Module`, i.e., a type with a {name}`Widget.ToModule` instance. +It must be possible to convert the definition to a {name}`Widget.Module`, i.e., the definition's type must have a {name}`Widget.ToModule` instance. -:::example "Registering a widget module" +:::example "Registering a Widget Module" ```imports -show import Lean.Widget.UserWidget ``` @@ -70,7 +72,7 @@ The JavaScript environment in which widget modules execute is a standard browser Each can be imported by using its name as the module specifier (under the hood, an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) is configured). For example, `import * as React from 'react'` would work. - [`'react'`](https://www.npmjs.com/package/react), [`'react-dom'`](https://www.npmjs.com/package/react-dom), and `'react/jsx-runtime'` provide the [React](https://react.dev/) runtime shared with the InfoView. - - [`'@leanprover/infoview'`](https://www.npmjs.com/package/@leanprover/infoview) allows widgets to reuse UI components used by the InfoView, as well as to communicate with other parts of the InfoView, with the editor, and with the Lean language server. + - [`'@leanprover/infoview'`](https://www.npmjs.com/package/@leanprover/infoview) allows widgets to reuse UI components used by the {tech}[InfoView], as well as to communicate with other parts of the InfoView, with the editor, and with the Lean language server. Documentation can be found [here](https://leanprover.github.io/vscode-lean4/infoview). : Importing by Hash @@ -97,10 +99,10 @@ The following bundler-specific instructions may be useful. # Displaying Widgets Widgets are [React components](https://react.dev/learn/your-first-component) exported from widget modules. -The InfoView is a React application, and is capable of embedding these components. +The InfoView is a React application and is capable of embedding these components. A widget must be the [`default` export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export) of its module. -When registering a widget for display in Lean, we provide [props](https://react.dev/learn/passing-props-to-a-component) that it will receive when it is rendered by the InfoView. +When registering a widget for display in Lean, you provide the [props](https://react.dev/learn/passing-props-to-a-component) that it will receive when it is rendered by the InfoView. In Lean, a {name}`Widget.WidgetInstance` bundles such an assignment of props with a reference to the widget module that exports the component. The assignment is stored as a {name}`Json` object—later decoded into a JavaScript object—and more generally a {lean}`StateM Server.RpcObjectStore Json` computation, in order to support {tech (key := "RPC reference")}[RPC references]. @@ -108,13 +110,13 @@ The assignment is stored as a {name}`Json` object—later decoded into a JavaScr Lean can display widgets in two ways: within messages in the {tech}[message log], or as {tech (key := "InfoView panel widget")}[InfoView panels] associated with a source span. -: Widgets in Messages +: Widgets in messages A widget component is displayed inline in a Lean message. {docstring MessageData.ofWidget} -: InfoView Panels +: InfoView panels By default, the InfoView conveys information about a given position in a Lean source file by means of three panels: _Tactic state_, _Expected type_, and _Messages_. This listing can be extended by user-defined panels (appearing below _Expected type_), for instance to render tactic states in custom proof modes. @@ -141,7 +143,7 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] Finally, the {keywordOf Lean.Widget.widgetCmd}`#widget` command can be used to quickly render a panel widget. - :::example "Using the #widget command" + :::example "Using the `#widget` Command" The panel widget is associated with the source line the command appears on. Internally, this command invokes {name}`Widget.savePanelWidgetInfo`. @@ -176,9 +178,9 @@ tag := "widgets-remote-procedure-calls" The InfoView—together with any embedded widgets—is a web application running on the same computer as the IDE. The Lean language server, which {tech (key := "Lean elaborator")}[elaborates] source files and interprets Lean code, is a separate process. -The InfoView and the language server may reside on two different machines, e.g. when using Lean in a server-backed web IDE or over SSH. +Indeed, the InfoView and the language server may reside on two different machines, e.g. when using Lean in a server-backed web IDE or over SSH. -It can be useful for widgets to maintain part of their state or input data in the server, as opposed to serializing and transferring it to the client. +Widgets can maintain part of their state or input data in the server, as opposed to serializing and transferring it all to the client. Transfer may be impractical due to a slow network, and objects may not be easily serializable (as is the case for closures, {name}`IO.Promise`s, or {name}`Lean.Environment`s). The Remote Procedure Call (RPC) mechanism allows client-side widget code to manipulate {tech (key := "RPC reference")}[RPC references] to server-side data, and to execute {tech (key := "RPC method")}[RPC methods] in the server. @@ -191,14 +193,16 @@ An instance can be derived automatically, as documented below. {docstring +allowMissing Server.RpcEncodable} :::sectionNote -RPC references are not JSON-serializable without additional state in the encoder, so require {name}`Server.RpcEncodable`. +RPC references are not JSON-serializable without additional state in the encoder, so encoding them requires a {name}`Server.RpcEncodable` instance. But for data structures that do have JSON representations, prefer simply deriving {name}`FromJson` and {name}`ToJson`. ::: -The main purpose of {name}`Server.RpcEncodable` is to support—in addition to JSON—structures containing {deftech (key := "RPC reference")}[RPC references]. +The main purpose of {name}`Server.RpcEncodable` is to support exchanging {deftech (key := "RPC reference")}[RPC references] between the language server and widgets. +Data containing references cannot be simply converted to JSON. + Every reference is marked with the {name}`Server.WithRpcRef` wrapper. A value wrapped with {name}`Server.WithRpcRef` is not serialized or transferred to the client. -Instead, the client receives an opaque identifier that can later be used to retrieve the value server-side, in an {tech}[RPC method] call. +Instead, the client receives an opaque identifier that can later be used to retrieve the value in server-side code during an {tech}[RPC method] call. {docstring +allowMissing Server.WithRpcRef} @@ -206,9 +210,9 @@ Instead, the client receives an opaque identifier that can later be used to retr ```lean -show variable (α : Type) ``` -The type {lean}`α` must have a {name}`TypeName` instance for {lean}`Server.RpcEncodable (Server.WithRpcRef α)` to be inhabited. +For a {lean}`Server.RpcEncodable (Server.WithRpcRef α)` instance to synthesize, the type {lean}`α` must have a {name}`TypeName` instance. -:::example "TypeName and imported constants" +:::example "TypeName and Imported Constants" We discourage deriving {lean}`TypeName α` outside of the module where {lean}`α` is defined. Instead, define a single-field structure (a “newtype”) wrapping {lean}`α`, and derive {lean}`TypeName` for that. ```lean @@ -239,7 +243,7 @@ Make sure not to accidentally share state that you did not intend to across copi variable (α β : Type) ``` To register an {deftech}[RPC method], use the {attr}`server_rpc_method` attribute. -The method must be a function of type {lean}`α → Server.RequestM (Server.RequestTask β)`, where `α` and `β` are {name}`Server.RpcEncodable`. +The method must be a function of type {lean}`α → Server.RequestM (Server.RequestTask β)`, where there are {name}`Server.RpcEncodable` instances for `α` and `β`. The {name}`Server.RequestM` monad supports IO actions, and provides access to parts of the language server state. @@ -248,7 +252,7 @@ Ideally, a method implementation returns immediately, doing most of its work in The {name}`Server.RequestM.asTask` convenience function does exactly this. ::: -:::example "Registering an RPC method" +:::example "Registering an RPC Method" ```imports -show import Lean.Server.Rpc ``` @@ -258,10 +262,12 @@ open Lean ```lean structure Cell where str : String - deriving TypeName +deriving TypeName -/-- Extracts a string from a server-side cell -and sends it to the client. -/ +/-- +Extracts a string from a server-side cell +and sends it to the client. +-/ @[server_rpc_method] def unwrapStr (cell : Server.WithRpcRef Cell) : Server.RequestM (Server.RequestTask String) := @@ -278,14 +284,13 @@ Any LSP client may create RPC sessions and invoke RPC methods. Any widget React component may invoke RPC methods. To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/functions/index.useRpcSession.html) hook. -The handle may then be used to call RPC methods; see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/interfaces/index.RpcSessionAtPos.html#call). +The handle may then be used to call RPC methods; for details, see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/interfaces/index.RpcSessionAtPos.html#call) in the InfoView API documentation. Invoking RPC is an asynchronous operation that generally occurs in a [React effect](https://react.dev/reference/react/useEffect). RPC methods are identified in JavaScript by their fully qualified Lean names. -:::example "Calling an RPC method" -As remarked above, widgets can receive RPC references as props. -In this example, we pass such a reference prop. -We then invoke an RPC method, using the reference as an argument. +:::example "Calling an RPC Method" +Widgets can receive RPC references as props. +This example demonstrates how to pass a reference as a prop and how to invoke an RPC method using the reference as an argument. ```imports -show import Lean.Widget @@ -296,7 +301,7 @@ open Lean ```lean structure Cell where str : String - deriving TypeName +deriving TypeName @[server_rpc_method] def unwrapStr (cell : Server.WithRpcRef Cell) : @@ -305,7 +310,7 @@ def unwrapStr (cell : Server.WithRpcRef Cell) : structure Props where cell : Server.WithRpcRef Cell - deriving Server.RpcEncodable +deriving Server.RpcEncodable @[widget_module] def rpcCallWidget : Widget.Module where From c39559bf2aefc005619d5ad0cf54ed8046c69ff1 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 01:20:18 +0000 Subject: [PATCH 09/19] simple widgets --- Manual/Interaction/Widgets.lean | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index b7863ba2e..ffa559fe6 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -82,7 +82,9 @@ The JavaScript environment in which widget modules execute is a standard browser ## Bundling A {tech}[widget module] must be a single, self-contained JavaScript module. -In order to compile an [`npm`](https://www.npmjs.com/) package (with dependencies, TypeScript, and so on) into this format, one typically uses a _bundler_. +Simple widgets can be written directly in this form. +Beyond a certain complexity level, though, it becomes useful to define an [`npm`](https://www.npmjs.com/) package with dependencies, TypeScript, and so on. +In order to compile such a package into a JavaScript module, one typically uses a _bundler_. The following bundler-specific instructions may be useful. : [Rollup.js](https://rollupjs.org/) From 196a0747809d7f96d97b7d8b48eb409f051f8d7b Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 01:20:29 +0000 Subject: [PATCH 10/19] clarify RPC storage --- Manual/Interaction/Widgets.lean | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index ffa559fe6..01925315f 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -105,8 +105,12 @@ The InfoView is a React application and is capable of embedding these components A widget must be the [`default` export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export) of its module. When registering a widget for display in Lean, you provide the [props](https://react.dev/learn/passing-props-to-a-component) that it will receive when it is rendered by the InfoView. -In Lean, a {name}`Widget.WidgetInstance` bundles such an assignment of props with a reference to the widget module that exports the component. -The assignment is stored as a {name}`Json` object—later decoded into a JavaScript object—and more generally a {lean}`StateM Server.RpcObjectStore Json` computation, in order to support {tech (key := "RPC reference")}[RPC references]. +A {name}`Widget.WidgetInstance` bundles such an assignment of props with a reference to the widget module that exports the component. + +In order to support {tech (key := "RPC reference")}[RPC references], the assignment is stored as a {lean}`StateM Server.RpcObjectStore Json` computation. +The computation must produce a JSON object, which in the InfoView is decoded into a JavaScript object and passed to the widget. + +Many widgets do not need RPC references—these can simply use a {lean (type := "Json → StateM Server.RpcObjectStore Json")}`pure` computation. {docstring Widget.WidgetInstance} From 1d7ad4f7310f6e7ab1c9d645701d25ca231abbe3 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 01:20:38 +0000 Subject: [PATCH 11/19] reword example --- Manual/Interaction/Widgets.lean | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 01925315f..da647e054 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -150,8 +150,8 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] Finally, the {keywordOf Lean.Widget.widgetCmd}`#widget` command can be used to quickly render a panel widget. :::example "Using the `#widget` Command" - The panel widget is associated with the source line the command appears on. - Internally, this command invokes {name}`Widget.savePanelWidgetInfo`. + This example defines a minimal panel widget and uses the `#widget` command to display it. + Internally, the command invokes {name}`Widget.savePanelWidgetInfo` to associate the panel widget with the source line the command appears on. ```imports -show import Lean.Widget.Commands From be1a8e7a41657ac69b7d1c05edf78ee6ac668966 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 01:20:44 +0000 Subject: [PATCH 12/19] link JSON --- Manual/Interaction/Widgets.lean | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index da647e054..f2f86b58c 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -193,7 +193,7 @@ The Remote Procedure Call (RPC) mechanism allows client-side widget code to mani ## Encoding and References The {name}`Server.RpcEncodable` type class marks client-server transferrable types. -The wire format is JSON, and any type with both {name}`Lean.ToJson` and {name}`Lean.FromJson` instances is encodable. +The wire format is {ref "JSON"}[JSON], and any type with both {name}`Lean.ToJson` and {name}`Lean.FromJson` instances is encodable. An instance can be derived automatically, as documented below. {docstring +allowMissing Server.RpcEncodable} From caf5f0db6e192885ada7b90a92b2977cf5afc3c0 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 01:20:50 +0000 Subject: [PATCH 13/19] wording --- Manual/Interaction/Widgets.lean | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index f2f86b58c..071ca677a 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -216,7 +216,7 @@ Instead, the client receives an opaque identifier that can later be used to retr ```lean -show variable (α : Type) ``` -For a {lean}`Server.RpcEncodable (Server.WithRpcRef α)` instance to synthesize, the type {lean}`α` must have a {name}`TypeName` instance. +For a {lean}`Server.RpcEncodable (Server.WithRpcRef α)` instance to synthesize successfully, the type {lean}`α` must have a {name}`TypeName` instance. :::example "TypeName and Imported Constants" We discourage deriving {lean}`TypeName α` outside of the module where {lean}`α` is defined. From b17bb5edfe08728cbf5c6a65c8fd3ffe14a7bba9 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 02:08:32 +0000 Subject: [PATCH 14/19] include_str --- Manual/Interaction/Widgets.lean | 267 ++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 071ca677a..ad1781762 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -8,6 +8,7 @@ import VersoManual import Manual.Meta import Lean.Widget +import Lake.Build open Verso.Genre Manual InlineLean open Lean Widget @@ -98,6 +99,272 @@ The following bundler-specific instructions may be useful. Does not work due to issue [evanw/esbuild#1944](https://github.com/evanw/esbuild/issues/1944). +The output of a bundler is typically a JavaScript file on disk. +To include the contents of such a file in a {name}`Widget.Module` definition, use the {keywordOf Lean.includeStr}`include_str` term elaborator. +This elaborator reads a file and produces a string literal from its contents. +By default, {keywordOf Lean.includeStr}`include_str` does not register a {ref "lake"}[Lake] dependency of the Lean file on the JS file, so changing the JS would not automatically rebuild the Lean module. +The missing dependency can be added using the {tomlField Lake.LeanLibConfig}`needs` configuration option. + +::::example "Adding a JavaScript Target to a Lakefile" + +This example shows how to build an `npm` package as a dependency of a Lean library. +The {ref "lake-config-lean"}[Lean configuration format] for Lake is necessary for this custom build job. + +In the `lakefile.lean` below, the [package-lock.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json) file and the source directory `widget/src` are first registered as additional build inputs. +The targets are named `widgetPackageLock` and `widgetDir`, respectively. +Their existence ensures that changes to the input files trigger a rebuild. +In order to normalize line endings, the `text` option is set. +The example assumes that no other files influence the build; in real projects, additional files may need to be included: bundler configuration, TypeScript settings, etc. + +A `widgetJs` target that builds the JavaScript bundle is then defined. +The bundle resides in `widget/dist/index.js` and is generated as the output of `npm run build`. +By using {name}`Lake.buildFileUnlessUpToDate'`, this script only runs the build command if the input files have changed. + +Finally, the Lean library target takes `widgetJs` as an additional dependency via the {tomlField Lake.LeanLibConfig}`needs` array. + +:::lakeLean +```lean +import Lake +open Lake DSL + +package MyPackage + +input_file widgetPackageLock where + path := "widget/package-lock.json" + text := true + +input_dir widgetDir where + path := "widget/src" + text := true + +target widgetJs pkg : Unit := do + let inputs := (← widgetPackageLock.fetch).mix (← widgetDir.fetch) + inputs.mapM fun _ => do + let bundlePath := pkg.dir / "widget" / "dist" / "index.js" + buildFileUnlessUpToDate' bundlePath (text := true) do + proc { + cmd := "npm" + args := #["run", "build"] + cwd := some (pkg.dir / "widget") + } + +@[default_target] +lean_lib MyLibrary where + needs := #[widgetJs] +``` +```expected +{wsIdx := 0, + baseName := `MyPackage, + keyName := Lean.Name.mkNum `MyPackage 0, + origName := `MyPackage, + dir := FilePath.mk ".", + relDir := FilePath.mk ".", + config := + {toWorkspaceConfig := { packagesDir := FilePath.mk ".lake/packages" }, + toLeanConfig := + { buildType := Lake.BuildType.release, + leanOptions := #[], + moreLeanArgs := #[], + weakLeanArgs := #[], + moreLeancArgs := #[], + moreServerOptions := #[], + weakLeancArgs := #[], + moreLinkObjs := #[], + moreLinkLibs := #[], + moreLinkArgs := #[], + weakLinkArgs := #[], + backend := Lake.Backend.default, + platformIndependent := none, + precompileImports := false, + dynlibs := #[], + plugins := #[], + requiresModuleSystem := false, + allowNonModules := false }, + bootstrap := false, + extraDepTargets := #[], + precompileModules := false, + moreGlobalServerArgs := #[], + srcDir := FilePath.mk ".", + buildDir := FilePath.mk ".lake/build", + leanLibDir := FilePath.mk "lib/lean", + nativeLibDir := FilePath.mk "lib", + binDir := FilePath.mk "bin", + irDir := FilePath.mk "ir", + releaseRepo := none, + buildArchive := ELIDED, + preferReleaseBuild := false, + testDriver := "", + testDriverArgs := #[], + lintDriver := "", + lintDriverArgs := #[], + version := { toSemVerCore := { major := 0, minor := 0, patch := 0 }, specialDescr := "" }, + versionTags := { filter := #, name := `default, descr? := none}, + description := "", + keywords := #[], + homepage := "", + license := "", + licenseFiles := #[FilePath.mk "LICENSE"], + readmeFile := FilePath.mk "README.md", + reservoir := true, + enableArtifactCache? := none, + restoreAllArtifacts? := none, + libPrefixOnWindows := false, + allowImportAll := false, + builtinLint? := none, + checks := #[], + fixedToolchain := false}, + configFile := FilePath.mk "lakefile.lean", + relConfigFile := FilePath.mk "lakefile.lean", + relManifestFile := FilePath.mk "lake-manifest.json", + scope := "", + remoteUrl := "", + depConfigs := #[], + depIdxs := #[], + depPkgs := #[], + targetDecls := + #[{toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `widgetPackageLock, + kind := `input_file, + config := Impossible!, + wf_data := …}, + pkg_eq := …}, + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `widgetDir, + kind := `input_dir, + config := Impossible!, + wf_data := …}, + pkg_eq := …}, + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `widgetJs, + kind := Lean.Name.anonymous, + config := #, + wf_data := …}, + pkg_eq := …}, + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `MyLibrary, + kind := `lean_lib, + config := + {toLeanConfig := + { buildType := Lake.BuildType.release, + leanOptions := #[], + moreLeanArgs := #[], + weakLeanArgs := #[], + moreLeancArgs := #[], + moreServerOptions := #[], + weakLeancArgs := #[], + moreLinkObjs := #[], + moreLinkLibs := #[], + moreLinkArgs := #[], + weakLinkArgs := #[], + backend := Lake.Backend.default, + platformIndependent := none, + precompileImports := false, + dynlibs := #[], + plugins := #[], + requiresModuleSystem := false, + allowNonModules := false }, + srcDir := FilePath.mk ".", + roots := #[`MyLibrary], + globs := #[Lake.Glob.one `MyLibrary], + libName := "", + libPrefixOnWindows := false, + needs := #[Lake.BuildKey.packageTarget Lean.Name.anonymous `widgetJs], + extraDepTargets := #[], + precompileLibrary := false, + precompileModules := false, + defaultFacets := #[`lean_lib.leanArts], + nativeFacets := #, + allowImportAll := false}, + wf_data := …}, + pkg_eq := …}], + targetDeclMap := + {`widgetJs ↦ + {toPConfigDecl := + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `widgetJs, + kind := Lean.Name.anonymous, + config := #, + wf_data := …}, + pkg_eq := …}, + name_eq := …}, + `widgetDir ↦ + {toPConfigDecl := + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `widgetDir, + kind := `input_dir, + config := Impossible!, + wf_data := …}, + pkg_eq := …}, + name_eq := …}, + `MyLibrary ↦ + {toPConfigDecl := + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `MyLibrary, + kind := `lean_lib, + config := + {toLeanConfig := + { buildType := Lake.BuildType.release, + leanOptions := #[], + moreLeanArgs := #[], + weakLeanArgs := #[], + moreLeancArgs := #[], + moreServerOptions := #[], + weakLeancArgs := #[], + moreLinkObjs := #[], + moreLinkLibs := #[], + moreLinkArgs := #[], + weakLinkArgs := #[], + backend := Lake.Backend.default, + platformIndependent := none, + precompileImports := false, + dynlibs := #[], + plugins := #[], + requiresModuleSystem := false, + allowNonModules := false }, + srcDir := FilePath.mk ".", + roots := #[`MyLibrary], + globs := #[Lake.Glob.one `MyLibrary], + libName := "", + libPrefixOnWindows := false, + needs := #[Lake.BuildKey.packageTarget Lean.Name.anonymous `widgetJs], + extraDepTargets := #[], + precompileLibrary := false, + precompileModules := false, + defaultFacets := #[`lean_lib.leanArts], + nativeFacets := #, + allowImportAll := false}, + wf_data := …}, + pkg_eq := …}, + name_eq := …}, + `widgetPackageLock ↦ + {toPConfigDecl := + {toConfigDecl := + {pkg := Lean.Name.mkNum `MyPackage 0, + name := `widgetPackageLock, + kind := `input_file, + config := Impossible!, + wf_data := …}, + pkg_eq := …}, + name_eq := …}, + }, + defaultTargets := #[`MyLibrary], + scripts := {}, + defaultScripts := #[], + postUpdateHooks := #[], + buildArchive := ELIDED, + testDriver := "", + lintDriver := ""} +``` +::: +:::: + # Displaying Widgets Widgets are [React components](https://react.dev/learn/your-first-component) exported from widget modules. From 88006253cc37c6028e86b97efed0f80b34f7928f Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 02:11:08 +0000 Subject: [PATCH 15/19] plural --- Manual/Interaction/Widgets.lean | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index ad1781762..763bf1a8a 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -410,7 +410,8 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] When rendering a panel widget, the InfoView extends the props object obtained from the {name}`Widget.WidgetInstance` with additional, automatically computed properties that reflect the editor state (for instance the current cursor position). These additional props are documented as [`PanelWidgetProps`](https://leanprover.github.io/vscode-lean4/infoview/interfaces/index.PanelWidgetProps.html). - A panel widget should be collapsible (conventionally a [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) element). + Panel widgets should be collapsible, so that users can easily hide them. + Conventionally, a [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) element is used. A panel widget is re-rendered when the source position it describes is re-elaborated. From bd02100ab84468c6433c612445deed7acbe150f9 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 03:08:56 +0000 Subject: [PATCH 16/19] simplify --- Manual/Interaction/Widgets.lean | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 763bf1a8a..17da3d256 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -113,14 +113,13 @@ The {ref "lake-config-lean"}[Lean configuration format] for Lake is necessary fo In the `lakefile.lean` below, the [package-lock.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json) file and the source directory `widget/src` are first registered as additional build inputs. The targets are named `widgetPackageLock` and `widgetDir`, respectively. Their existence ensures that changes to the input files trigger a rebuild. -In order to normalize line endings, the `text` option is set. The example assumes that no other files influence the build; in real projects, additional files may need to be included: bundler configuration, TypeScript settings, etc. A `widgetJs` target that builds the JavaScript bundle is then defined. The bundle resides in `widget/dist/index.js` and is generated as the output of `npm run build`. By using {name}`Lake.buildFileUnlessUpToDate'`, this script only runs the build command if the input files have changed. -Finally, the Lean library target takes `widgetJs` as an additional dependency via the {tomlField Lake.LeanLibConfig}`needs` array. +Finally, the Lean library target `MyLibrary` takes `widgetJs` as an additional dependency via the {tomlField Lake.LeanLibConfig}`needs` array. :::lakeLean ```lean From 41e324ad65ddf956c4d1b44a059d31aec1a1d7b4 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 03:43:45 +0000 Subject: [PATCH 17/19] TypeName workaround --- Manual/Interaction/Widgets.lean | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 17da3d256..dcc1de6f9 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -485,15 +485,9 @@ variable (α : Type) ``` For a {lean}`Server.RpcEncodable (Server.WithRpcRef α)` instance to synthesize successfully, the type {lean}`α` must have a {name}`TypeName` instance. -:::example "TypeName and Imported Constants" -We discourage deriving {lean}`TypeName α` outside of the module where {lean}`α` is defined. -Instead, define a single-field structure (a “newtype”) wrapping {lean}`α`, and derive {lean}`TypeName` for that. -```lean -structure MyNat where - val : Nat - deriving TypeName -``` -::: +Deriving {lean}`TypeName α` outside of the module where {lean}`α` is defined can lead to conflicting instances downstream, so it is discouraged. +Patching the defining module may not be possible. +A workaround is to define a “newtype” structure containing a single field of type {lean}`α`, and to then derive {lean}`TypeName` for that structure. :::: Use {name}`Server.WithRpcRef.mk` to construct RPC references. From 94a2b2f895fe481d2508c2c4f20c9d51c7e9f10a Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Tue, 10 Nov 2026 04:10:52 +0000 Subject: [PATCH 18/19] RPC registration example --- Manual/Interaction/Widgets.lean | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index dcc1de6f9..2d38ad87a 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -479,6 +479,15 @@ Instead, the client receives an opaque identifier that can later be used to retr {docstring +allowMissing Server.WithRpcRef} +Use {name}`Server.WithRpcRef.mk` to construct RPC references. + +{docstring Server.WithRpcRef.mk} + +### {name}`TypeName` for References +%%% +tag := "widgets-typename-references" +%%% + ::::leanSection ```lean -show variable (α : Type) @@ -486,14 +495,11 @@ variable (α : Type) For a {lean}`Server.RpcEncodable (Server.WithRpcRef α)` instance to synthesize successfully, the type {lean}`α` must have a {name}`TypeName` instance. Deriving {lean}`TypeName α` outside of the module where {lean}`α` is defined can lead to conflicting instances downstream, so it is discouraged. -Patching the defining module may not be possible. -A workaround is to define a “newtype” structure containing a single field of type {lean}`α`, and to then derive {lean}`TypeName` for that structure. +Patching the defining module is preferred. +When this is not possible, a workaround is to define a “newtype” structure containing a single field of type {lean}`α`. +A {lean}`TypeName` instance can then be derived for that structure. :::: -Use {name}`Server.WithRpcRef.mk` to construct RPC references. - -{docstring Server.WithRpcRef.mk} - ## RPC Methods :::sectionNote @@ -520,6 +526,11 @@ The {name}`Server.RequestM.asTask` convenience function does exactly this. ::: :::example "Registering an RPC Method" +This example registers an {tech}[RPC method] with an {tech}[RPC reference] as the argument. + +First, the {ref "widgets-typename-references"}[{name}`TypeName` instance workaround] is applied: the basic {name}`String` type is wrapped in a structure called `Cell`. +This structure will be kept server-side, with the client holding a reference to it. + ```imports -show import Lean.Server.Rpc ``` @@ -530,7 +541,16 @@ open Lean structure Cell where str : String deriving TypeName +``` + +Then, an RPC method named `unwrapStr` is defined and registered. +When invoked by a client later, its body would execute in the language server. +Given a reference to a `Cell`, the method extracts the nested string and returns it directly. +The helper {name}`Server.RequestM.asTask` wraps this computation in a concurrent task. +From the client's perspective, this remote endpoint receives an opaque, numeric reference and sends back a JSON string. + +```lean /-- Extracts a string from a server-side cell and sends it to the client. From 06cd109ac2511ca3eaea04a1ce1bff0dbe0ec735 Mon Sep 17 00:00:00 2001 From: Wojciech Nawrocki Date: Wed, 11 Nov 2026 06:06:25 +0000 Subject: [PATCH 19/19] better examples --- Manual/Interaction/Widgets.lean | 107 +++++++++++++++++++++------ static/screenshots/widgets-hello.png | Bin 0 -> 12289 bytes 2 files changed, 84 insertions(+), 23 deletions(-) create mode 100644 static/screenshots/widgets-hello.png diff --git a/Manual/Interaction/Widgets.lean b/Manual/Interaction/Widgets.lean index 2d38ad87a..11a852000 100644 --- a/Manual/Interaction/Widgets.lean +++ b/Manual/Interaction/Widgets.lean @@ -41,6 +41,8 @@ To register a widget module in Lean, tag its definition with the {attr}`widget_m It must be possible to convert the definition to a {name}`Widget.Module`, i.e., the definition's type must have a {name}`Widget.ToModule` instance. :::example "Registering a Widget Module" +This example registers a {tech}[widget module] called `helloModule`. + ```imports -show import Lean.Widget.UserWidget ``` @@ -49,7 +51,7 @@ open Lean ``` ```lean @[widget_module] -def foo : Widget.Module where +def helloModule : Widget.Module where javascript := r#" export default function() { return "Hello, world!" } "# @@ -411,14 +413,14 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] Panel widgets should be collapsible, so that users can easily hide them. Conventionally, a [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) element is used. + To match other InfoView components, the nested `` element typically has `mv2 pointer non-selectable` CSS classes, whereas content has the `ml1` class. A panel widget is re-rendered when the source position it describes is re-elaborated. Finally, the {keywordOf Lean.Widget.widgetCmd}`#widget` command can be used to quickly render a panel widget. - :::example "Using the `#widget` Command" - This example defines a minimal panel widget and uses the `#widget` command to display it. - Internally, the command invokes {name}`Widget.savePanelWidgetInfo` to associate the panel widget with the source line the command appears on. + :::example "Defining and Displaying a Panel Widget" (tag := "widgets-defining-displaying-panel-widget") + This example defines a minimal {tech}[InfoView panel widget] and uses the `#widget` command to display it. ```imports -show import Lean.Widget.Commands @@ -426,22 +428,51 @@ Lean can display widgets in two ways: within messages in the {tech}[message log] ```lean -show open Lean ``` + + First, the widget's props are specified as a structure with a single {name}`String` prop called `name`. + This is not strictly necessary—props are transmitted as untyped {name}`Json` values—but describing the schema as a Lean type is good practice. + ```lean structure Props where name : String - deriving FromJson, ToJson + deriving FromJson, ToJson + ``` + Next, a widget module called `helloWidget` is defined and registered. + Its JavaScript implementation is inlined as a string literal. + It follows the styling conventions outlined above. + + ```lean @[widget_module] def helloWidget : Widget.Module where javascript := " import * as React from 'react'; export default function(props) { const name = props.name || 'world' - return React.createElement('b', {}, 'Hello, ' + name + '!') + + return React.createElement('details', {}, [ + React.createElement('summary', + {'className': 'mv2 pointer non-selectable'}, + 'Hello Widget' + ), + React.createElement('b', + {'className': 'ml1'}, + 'Hello, ' + name + '!' + ) + ]) }" + ``` + + Finally, the `#widget` command is used to display an instance of this widget. + Internally, this invokes {name}`Widget.savePanelWidgetInfo` to associate the instance with the source line the command appears on. + ```lean #widget helloWidget with { name := "Hexapus" : Props } ``` + + The following is rendered in the InfoView: + + ![Screenshot of rendered HTML. A 'Hello Widget' header with bold 'Hello, Hexapus!' text under it.](static/screenshots/widgets-hello.png) ::: # Remote Procedure Calls @@ -458,6 +489,9 @@ Transfer may be impractical due to a slow network, and objects may not be easily The Remote Procedure Call (RPC) mechanism allows client-side widget code to manipulate {tech (key := "RPC reference")}[RPC references] to server-side data, and to execute {tech (key := "RPC method")}[RPC methods] in the server. ## Encoding and References +%%% +tag := "widgets-encoding-references" +%%% The {name}`Server.RpcEncodable` type class marks client-server transferrable types. The wire format is {ref "JSON"}[JSON], and any type with both {name}`Lean.ToJson` and {name}`Lean.FromJson` instances is encodable. @@ -525,10 +559,10 @@ Ideally, a method implementation returns immediately, doing most of its work in The {name}`Server.RequestM.asTask` convenience function does exactly this. ::: -:::example "Registering an RPC Method" +:::example "Registering an RPC Method" (tag := "widgets-registering-rpc-method") This example registers an {tech}[RPC method] with an {tech}[RPC reference] as the argument. -First, the {ref "widgets-typename-references"}[{name}`TypeName` instance workaround] is applied: the basic {name}`String` type is wrapped in a structure called `Cell`. +First, the {name}`TypeName` {ref "widgets-typename-references"}[instance workaround] is applied: the basic {name}`String` type is wrapped in a structure called `Cell`. This structure will be kept server-side, with the client holding a reference to it. ```imports -show @@ -570,22 +604,21 @@ Any LSP client may create RPC sessions and invoke RPC methods. ::: Any widget React component may invoke RPC methods. -To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/functions/index.useRpcSession.html) hook. +To do so, the component should first obtain an _RPC session_ handle via the [`useRpcSession`](https://leanprover.github.io/vscode-lean4/infoview/functions/index.useRpcSession.html) [React hook](https://react.dev/learn/reusing-logic-with-custom-hooks). The handle may then be used to call RPC methods; for details, see [`RpcSessionAtPos.call`](https://leanprover.github.io/vscode-lean4/infoview/interfaces/index.RpcSessionAtPos.html#call) in the InfoView API documentation. Invoking RPC is an asynchronous operation that generally occurs in a [React effect](https://react.dev/reference/react/useEffect). RPC methods are identified in JavaScript by their fully qualified Lean names. :::example "Calling an RPC Method" -Widgets can receive RPC references as props. -This example demonstrates how to pass a reference as a prop and how to invoke an RPC method using the reference as an argument. +This example builds on {ref "widgets-registering-rpc-method" (domain := Manual.examples)}[“Registering an RPC Method”]. +It demonstrates how to instantiate a widget with an RPC reference prop, and how to invoke an RPC method with a reference as the argument. ```imports -show import Lean.Widget ``` ```lean -show open Lean -``` -```lean + structure Cell where str : String deriving TypeName @@ -594,9 +627,23 @@ deriving TypeName def unwrapStr (cell : Server.WithRpcRef Cell) : Server.RequestM (Server.RequestTask String) := Server.RequestM.asTask <| return cell.val.str +``` +First, a widget module `rpcCallWidget` is defined. +It behaves similarly to `helloWidget` in the {ref "widgets-defining-displaying-panel-widget" (domain := Manual.examples)}[“Defining and Displaying a Panel Widget”] example, but also exercises RPC functionality. + +The single prop, now called `cellRef`, is an RPC reference to a `Cell` value. +Instead of deriving {name}`FromJson` and {name}`ToJson` instances for the `Props` structure, {name}`Server.RpcEncodable` is derived directly; as explained {ref "widgets-encoding-references"}[above], the former two would fail. +In the render function, the client's RPC session is accessed via `useRpcSession`. +Afterwards, a [React effect](https://react.dev/reference/react/useEffect) is declared. +The effect runs when the component is [mounted](https://react.dev/learn/lifecycle-of-reactive-effects). +It invokes `RpcSessionAtPos.call` with the fully qualified name of the RPC method, which in this case is just `'unwrapStr'`. +The RPC call accesses the server-side `Cell`, sending back the wrapped value as a JavaScript string. +The value is then stored in the component's state and eventually displayed. + +```lean structure Props where - cell : Server.WithRpcRef Cell + cellRef : Server.WithRpcRef Cell deriving Server.RpcEncodable @[widget_module] @@ -605,21 +652,35 @@ def rpcCallWidget : Widget.Module where import * as React from 'react' import { useRpcSession } from '@leanprover/infoview' - export default function({ cell }) { - const rs = useRpcSession() + export default function({ cellRef }) { const [display, setDisplay] = React.useState() + + const rs = useRpcSession() React.useEffect(() => { - rs.call('unwrapStr', cell).then(s => setDisplay(s)) + rs.call('unwrapStr', cellRef).then(s => setDisplay(s)) }, []) - return React.createElement('b', {}, [display]) + + return React.createElement('details', {}, [ + React.createElement('summary', + {'className': 'mv2 pointer non-selectable'}, + 'RPC Widget' + ), + React.createElement('b', {'className': 'ml1'}, [display]) + ]) } "# +``` + +Having declared the widget, we call {name}`Widget.savePanelWidgetInfo` to instantiate it and associate it with the syntactic span of the {keywordOf Lean.runMeta}`run_meta` keyword. +The RPC reference is initialized with a string literal value. +```lean run_meta - let cell ← Server.WithRpcRef.mk { str := "Server-side hello!" } - Widget.addPanelWidgetLocal { rpcCallWidget with - id := .anonymous - props := Server.rpcEncode { cell : Props } - } + let stx ← getRef + let cellRef ← Server.WithRpcRef.mk { str := "Server-side hello!" } + Widget.savePanelWidgetInfo + rpcCallWidget.javascriptHash + (Server.rpcEncode { cellRef : Props }) + stx ``` ::: diff --git a/static/screenshots/widgets-hello.png b/static/screenshots/widgets-hello.png new file mode 100644 index 0000000000000000000000000000000000000000..e7899e42325d6534ac679a8e423a659cd98799ca GIT binary patch literal 12289 zcmZX41yo$kvhENDcemi~?mD%P5KPfK-GwN&@6uVzQ7tIDAv6C;B_AT$MeX-yCah5;yhA;JT{kY^_Y5D4{+jg*wS zf|L}6x{H&QjlCrZBp;Qgi=g*r7(dTYld^HDICKMy#RyXrN+#ihWgki-!9Ym|#;Yrc zL9T|wL(y^5mac=PiZ++B)HwF9gBDiBz%h?x(|lxe+VtJbKFt<>d78`$oX8Qr*&qUG zwF^>d@KwM|#B-><#yK7&%ugMo=mcw-f>J@qJOV~hk$8A`=%z&WFD7DZ;K-^@EB4uY z&xb(PLy@jf6c9F?Gm~1+c+f2e$O}c6W&-x39-?=HjW-q1#;dv#LU_b;Ga^;pANWM7 z+CLs#@>>W4BYi;>%&r34ZXm6Dipin<5-Cz`*htbakswU-Wxozr7Z-0#_Mj!=`$&rP zU)*m3XB1wttqv3EB2vUc@m!M#Ts}%rjr<(D6`wutR#N@y_5sySFO9p8lCxg0x8urU zFMPO`3&g;t92Xg?2W!p?qxPGm56W zHM$e@DKm+OIj@)y#dYLI0|HN7WN>VYbYwZ^V0G} zXT5ipl+geI`~zA)3wkusSQ5NEam-q3__N-Q*cMEgjao7`IWqAal!ZZpdU)5S zRCXeAF#!THaSHV$1fvx8*aYpfmR5#IcG+nHPdrOGwA&r5$753>CuHYn8gY+WCk-;A zGGzY_i!Xu2p9&SnDEzT|Yf{+jIqoML5EF;cP*h2)gU6!l; zoUL^AS-6|tPNt(ol@j-Fi6E!t!iI{D92%`}0+vuy>V{R>b zZKH543-3okg6I~_2$v&q3!;*X6d90LEgH%1DApcyv;Dd^OK??Km9VH)NR@*Ibvs-l zjoW!6x@$kIIWN5Gp%Z7kmphCj^>ofv9>*@nZ??%Y~ zj_*P$%a!vw*9a!@DF!#c&2#!95VdgqJ|z1E0c4``^z<|s@S#8j^!h_ce&}a$0Xw?K zaR!(vmsDoFeP#h856W-s5lns$e?DSyguH#@`vYtgM1KYsM1dpkH9Aw&>j z1H~MJ?T6yBAXI+$sU@<9ZU1KS0dp=$_5*SbY{oad53p+?%*8kzuS9>q-bPa(A{9`& zNn>!zvS14LA(>Ha$Wvg)_faUwBPYirVliq)j>#z|aaoAgeiY?78MP)-dCFK|Af;UUe9#)qOz6(1NhVy}lR6qZgY9iTPB`iEVc zgWmKsa^j4Uy)%E-qe+h~HZ!;9(+N&{m!^ld0Ls7Qt%5xo5ZjT?iRb>{+hQPf=9Lqp z*8hG->Fny3tpi^?onO!;WT*KVMoTs9qVu|8!#c9P?#jT2VY1hn645FI%RaFJ{mB%$A8u}F- zTHd7>3VXsMr`9~5XvZ_sl}A6b7Hdzd&XUcDl}~BE)>>i`NfTtkV`^g3)i$Zr)MC}r zuSn5G(HhmpC^ykL(fM4aUvXFIJZDv@T}GyAQ@6XMe*d>nEH0>_3x-o(WU0w*-TQ3oZJ-V|k*f!y1MVhGfC7q8gz2 zpv9qvpvi};Sw^NvsC84=EEnf;d0~(7@jh(C0veeisg)vN#RSWDbXo8FOeyEP$tjR7|*n_v8o*VH10DNH$Ip}@JTm&vk9ul!OF$5pqJBp zYi(nhW!*YeKXDP3R*kn>@vUOzu#0zmWzeU>z4*$Vq!4YEZq(}YIG*9$LO);c*PiQo zQrmr7`r1|NMX_X#8ULaW7JEa6*CW>~4}K4}4|3=$=v(MA=a#;zAWKHICcN&|d z#;+Sln}s(>zHkb;xlJF0Pdnw>=eDTgsV)vq4S?gaxJv@YNZt#-@4BShUuAR4aArd> z{$$+M+SVFvY-iNIHny(0#@DiLZp-yKQz?`6H`r7BM(}ss?|e}s(F+lDpT|9$)2zML z)ysap%DTt8)j_dyuB&Y?hpWRgE3Z;7r}N)uoabA&TK6K?yq9}-zt8+9>dh?cuWL;n z1n;As;&1)`+??g_1#*E<5YZWstWo9=V=;`#Z#jl|7(~m2%IKG9y{yiLF(u{ohN2S< z?WOoKjQf8hxufLb`Oql~vhdmaFYSC-{ow4?E8u2y(2}Y}?ZpS`nHM1ruc% zMYW;-Rdd%BXk}|h`vpkCC|$>dA{gZ3Y+pmevatfE$%#H z4r7ESB4ZR|`1W{{-bT*^U>SM*^Zf!8IvO4;u_`C zk+Wfj$pidblm(Oxi*O6aiN{R5tS0VCabZs1x9EcOwEJc1Qkk?ODR!yCqRqw@^i25f z%2%0fKDG%0${kX{@^lJ^mpoe~-P*RSPcrumo5I~xFSCuIHW4M2Y6PlIxn{!e&SUrC zAaLE|eeYe~^AUW)onZFkiQ%<7vbXR!JpL(Y<%&P{D~CkHb5Z25qsqIRKoCC-uQNYi zpxZ2HE4URU?-Bb^$-PdouH|+?axyHNU@Hb3vx1+X-{E+EgKaY0uQ@n#G1Eo6MoSP# z`gFAN_93H$)xq#*oBgcIw#(KrEww_;B5U8>f zw+FXXcjTPaU#1<*FaF*ZpMP09Te-j5>h^oFJt5khy_0<`c{xe;^f~qD@(kEqBbk3V zlbVRAAy*Rn<-c;3b$9oe(Z@d7t$IX#_2tRx^2?U*(#^w@;L{UTd?xiKvT1FhjSZ+{ z9SOvW1iHs-3Cx5FFpr=V3T%#G-Kyz1=cN*~xRwX`-XA!&w70^2dp-f_N&3%6fuyHF zk*){_nVeGYXGZkmAtT6Gd1zmy1C+)U;9k^m_h<9B$u?ePRd5q-Jfp;$g{2LCSGECA z2Kb$VlsYOJ2*we1=M<<%Tk0uTsi=UMfHEQo3_}cp14=MJ5`!W6PgxegDX{;vzXE|G zY(U_D_fZA%zfU5N{_^}QhfNL#ApkXOAbCMw{ZDTg1}NJ(B=E|wI0Y#eMH zRAR^!6ci#Z7FI%<(z5?%2Wp~J)^2VegxJ|VJw4exx!Igt-m`NG3JS7waItf7u>w6< zUA-OM%)D3~U8(;iP7fK}vgtB|^lm!-YFw2cF>W`GVcPA(3SfBOG_l>gQEUz~dX z%gH6k_uriVMfty++OC!^QcezlN;k3p-L8K#|2Og9j3VrRXZ~L+@vmk6rxjRdF=P?; z|LmC<@`BG~Ik1hdZKTz-fE+Nge;yIw_b)*Hn*#}xL0Y%&L@R?cR^pPpi^jW;6ol z387A#6H}aZQE+8+IDh_06u{l_zDsabbUz^1_w=FXCRcEO>|%nOd(!)TC!Qc; zm@o*HO8q-H?YpK~8X=6V1m!nyKVA?(;EDm^Xj#RC`Ibg-69~vRhOIOQqJ!r-BgJ2w%xasS~gnVV0`q zYD)0fFR3@$EwbS==+>Cv4aSplo8@_JBWW~Pskr8UeYZ0Zw|%#tuRFa^sjIfu;@q3k zw>O$012m5}q|mEHFMKh~et79|e!O*d-W$P7bITQSmtL$kmYSCk>w3C2+&P_=BS)jf zeGRR1-B-ndm!5+{VBKGK62zm^Sq(pVz9~`0a_Tq_Z=D=GUw)q-wV&s!3g@0CBj)Uq zX)6gTCBhA1G5m@;*pu1aA{2PuPe8}A-5T)Zv&LY4_wr{}O~t2PLksEQsHXeV&6FIr z7M}S0lj(L}6j|=`{ZWlNp4CLoFQf+V%b!ym7g9S&4Hm=LI6ndH*B!pMTM^^!exxLP z_8iV_BUGDSf<{|dm|<#Exwx6oneUtozyQByhNI4;8h@cUJzRg6Ao>%D+i|UBiX(=A z{W|n+D}r1(ll%RI*GA{##pqAtu6Rv~GEv{_U5SNz_O~q2tgmsjf)uL=SsC=w<`i?e z->Xsx0ZVgvE4LIu=EJ~&YJyJ0)feh|_W}&n_1$3nc<0OWgWxhRdK~+h6eH$bG#)dm z)wfooB5Rise61_3VaN5htnjlj?ny8m)1XJ}TSfa)wS06``oRt5mh+uKgnN}8S{yB6 zhG%|f4hSCNjd>#!6ee2o=VmkTfeOqVft}(pnJ>P{KepWPUev5GR{u^G{~QiSOB%{` zz&gW1R${Za6x`x_Q(YBuHynvY9r`G=PoNiW(B;?a1+2Y_S5&dHoU`BEUdDELX&#q} zrKjv%&D+hj_SgJQ8@TnS>`cte{p{V3g;wiierFKML1VBLc8D||@^q;h`CdP-tJ|*` z+UX(%92}WceUXFOz?T5$=ST0Lvp8a2Yz&dJj|VfwG1d!JSy9YUJ3qdMo3|Po8k9orhqywk zOsss)yF*x%gY{aOd=4v-*C(qn_^bwHZar37aa=E+Ypt$w$16=r{hsIBGGVOSp=>wn zp7|GHL~5PVMcS1*dG(Duz5ZhENaxg~kvY3qZ%S3Q9UoVlo${SweV4WQZfN%+6+gM; z#_x~PLn7T@R-L+KR7QT)2(^1PJ8e#M-XB&9j@{nw;Vi%om_E{|pdjlELLni3?m_WS z_gAB49xUbG%nR=Z1QL~|;yy327`M&2p7O&A*e`MHV89-;75s8qZ=2tf5rt(-Mpg0C zB5#q4BTnnJx6wj5-01Xe1x$L+njm!`>YPiNMuNsH%PoXufW}>cEr!!ZUDUqW?zI}D z{;L-%&-1RkpV{)J%RjaPRvK-h3M$xwlaG8{Tv*kLItr6V+=VAPie=Ql9B+1a4+m~``R77@xqOT#75-V2=FlUN-|2fJ)T z7Y$@R@Z~}86Il!zhl*kzUlABuueeYa`=D{n`m~8Dia-5H@x}CMt9ToW4qzg-PdP=Qfryp2Os0 zlZpi4+9EG%f05Zh*Zm21%W|5$ekz7#_8QH|#wjDmWhYg*vO|h8I23%Z3k1pVC{>yG z-o3nldz*xA46)mfJ{rGy5JyxIxJ~5qk-HvK=u|EaV3Sp-^fIJJHLG!Nq!CCDd^=5| ztDRmsuh!enGvT14t;rlCN|AKOKuvs4cyTcPNElqZfZY~10v;R^#BbfPQrC^c#B~?3 zLm{m6aX~TAnJT4kp&3M=FhuOd=ww4>sy^c1{d5e*f)|}_I?12eYj&g-zfE2|Jl$-% zI;?)Zx@~ezOoblH!p@wNEJCC*a6q!;yAbs16{h~SQaz}!oaN2$bvjm_+rZ~Lxz6;E zo1cPi5(E**RakNCZAk&x((2cQM349G4G>LO1aux7DhC3{ckF4Ot;72t*2a(xE%94V zEZlx}8)L~8W%V|&WVLfuSz{G_nU-~M{lkOVJHgwY8AS&Sb$Z$|;P&y|&hW*8Rg(Q( z09=Qkm8fbL+@7a~%Aup5H_=FiQoAlNZ&sS@L{F#G-CM#?2z)lCNfbd};lk=zNfD~; z7ODy$l`VV6SrO_+V3{w43=8y4;DQhpb(=+6i)f?@#p!$TNL!g=OHoLQB+i^1x&LnY zt@RniJOSg2Ve`a}C?jP0Jg2OIXRbo(h9k<)sIJ-Na%*|si>OB{zUF&%z(%sVWH|O9fMxrJ!v)Y66D)@e4Un-mdC*dDK^f4 zBH*OHwGqgBgOiWX=Ki^`gpm*O^msYhDiG)avuZ4|Qk#gO9E9++%dOaTn!wl0(+ zdP<)mQ5zdZtWl&XjA2p8J8yN}v{h`dV~{1A?(5ajV)njSD2cRsO~*xa)F7Q|_oMl6 z2VvJi5(m5qsZkn4s04DLHbSv0vKkcf_ zTYf2{EhX@of$y}Lr4x?a7mI{i3z{)PaO*NurZ_U6X1)97zlN5-JsB8dLwkpVJCF6e zJx6`pbc8))89Z|^*m8ZmJo`qyZK`L$$(+Wl1OF3r#&JynDY|+sK`2jpaipc>4lNUl zRIjvX6c-J_n8fIcyE{wLw$Ahsp}|`SwHm^FR$zb$nRbyh3Q)qc#xK9JGE_g4bBBeA zh+0G6MfyjlS23lsx;ONozOYud7*i9l@5L{se#}ucv}FV)Uf+3w%hGZTj43LM%sm%( z^Y{`}ef)-12kDCDD|NF!1gsibzlMOXhUxP&TO?R~>|?{5*He#;!C_%FpNc;6E(pU7 z4<%8@1%@{Kv!uqE&|pQHAGr=Pcs)Ln7h!Z|r`<0bZ+@A=g(6vf{FA?~2dwFOUXbj^ z@B0)<**>E8@8}rOzJod)I~udYJ0l^IgEiJI{F{E<44FOz(&_@d=~D z;xn8@pACh^5 zV>B#nz7eYx{;#E7*z+Tf859H^)zDWHVocv2A;;pa+C=$-YgAz$wu1Y<9$=zp+N_84 zXxbY~TQ9<;rl|N)xY|D1bQ*)4(4B^6*@Ka2XH+*s>z(OSBjKA_3IVi7!!P%^A_R45H%Rz;1Zx;Ev4Pxy>Ti$nmSMCZ{XP|y(F8W1!v zvxKi)M%G9N>Wr`_+2Qtycdin7QkaBCb}X^@3HP_=ohj)X>*0zNtT0}X5ZQrbFQ&|AcGJnla&Z}ZDEy<^|G?}1tpEs6ptaO9pw z;49+WRA_^!Vx{?v!jMMFW#fnsBgB6>kJ!9dNKW5xu~v|feEueF&1JJd%VXF_|2`>= ztt`8kL0P?6uOg>Z4^f_ZT#Ccxo6%4)e3$dk<{{2S72~DYi1)<+x3D>Y|L{=Qu8pD* zhq7cWiF#j!e4|PmW$pujg=0W6>EzxkEz0H_#MXVRX2spHiu)iq|H(x+0M98BsKtMg z$4Y$XWj>b4soj{di z>^k!GKyW8k;u;w5NB~h?c&x-SfL^t~%1jcy2iGS6i1&IllGg$}@)y6>v-(U3P$&8W zeD!Z-t0<|}zXAw0&0*SgfGFsg8bG~IT;^y*LG^zztbI%#_XMH^Ily9AH^|80xYlR$}fkpb`tM zLjS9Nh{_aPj5|*BK4+^7z_LBL{x|E34lP^ZVJ$|jJyITKz#x|qQDdRccl+cwfODIH zngzJzh89UOis#OK&6@#7CSF@%l7Fz3Sho0w8U44v?_HvKNg9h=uZ znEL?OPDcDa#;NOWp!0S+hIZ6t^l;sC)14eZa9ekHx<=Dq8YYCo1llw25zovMR#{s& z>>I|{wqw{gL_x<^9Fb?E?A^6-O20e@Nj)uSZ+?Ver02O&Bt4Hb31p~V;nk$m( zv}vs_#RzgNe@%~lkD#g>z|1U4YGQZ0Gnc0C%pNi2=V`w@?Lv24LVc1Hu;y|EUF+wH z5f5k8#K(OCs3cqaQkeO%48zauD>R89Xs}P^Y2mS-6xo?gJX%Rp2+^p^2(elxX!DE& zX`_;&xq^wyx2+pF)kMxi71eLnT-DU>xPmoJNB?h!Nzt1eMRmZ-KVf|PCJzdL$j$1Y zVW3y55UfvKo$7o38@Vtj9Z3Y!nC$XbrgnOtnpMB&L|MK|A*ri@kZ{ajM+;POOa;S6Sil1pG8TC*M7hKDmd95w;lUF`Y`EZcb( z^m*+bx+68fwvhjv-T|R_ie1rYcs61-(H2u<@+2m z^7~#NOTH#xffYP}hA5sdIe&*ENZr;Ks{d7zoxWYSGa-EHR@43LcmOIq}cFsH4q^wGxn71pUe6jFT@mknDZ7uroXe^=lwErt-smuZ6D{~?7-Y- z&m8YOs&3CojP(W1!8%|p>%%wjB=%Di{0{ZD9_cPcx&1+0t6n>CI|uhidDg5u1;Zbb zHv!L_fNN_@8u z=Y!;dWxs|sps@e!j1y?bOwNuT5GQyG@`F4UHH4 znQ8xoDf=2;Mt!|QKolSFz&Y*pZf zpr(IDo##7Vbzd|#Tr~DHJ_4}4Q}IR2>-C?Ia9jwf%MfMLp0s|jS*-X{-&Ts67~}By z>t0?a;k3*=?A}B@@IKuCIfLM|Ls5;o?QdG8>2zTH@YmZAF}dFWSk#>@Y9~i{!CJSl+eq74q4jQrzgn&}1vJ~P~s5wcp&%uhb2FGk%%uQvl< zG*=AP`!HI7BZwaW96sysVrx4#hc6EkTrz4rPMMCt&2rd3K??acG@pJCF z%_Saq?--Upb3CF-MMEi;ZsA5{~h zVkR|dIR`gAU9V<<=;F;%u4k?ID86v)Vq#plyYO&*slD}J#cRxi723{|I=nO4j)15$ zvJg_)?n&p!E}%y3e8W`k6^!@YO_JM|v#U8T=irtnP7u4dJ_3Ts?8RwH>Vssy_FSS} z+A$}4pWJ1{P=le4omV=%#xo_J1DJ_Kr!`&oBiS0ha~G7O@wWN1V7f4*9ko-_l5kZ@ zEp0f|%R9VzlAPDSv&%F>RsHE%PoNpQ-!x(oL>>+(uXlH0Ed3y2`TNSbC@A#novZ#7 zLG;y?h>Ut`KuFFyYK2vdADL@>-RCvfAlI)IY#dLGc_TnTEl^e#az^cLsu?H|>H>A`lHh5$jGe1R3>mqK*m-`d_MccZ9pj8ytvC zVPWZu6)m`s;fnWo{53If$>kqE8@L8Myg!O>1^2If(YpN`fqUqM>kpw~u=ja+x>;=~ zC2lRc0KW92FJGSai>NS_wb(&YG~DkQBXTNQBUc^an7fMYu+KFb(O2Xb#AEBaHE$|Z zoomfjOt>|})Ivt_!E4T7c9#P>r-8P9|d?iju1ym_Yw{Y1`|$* zOSF4+YTi)|4&bEz)GC?MbW#d`<)(5sp3KYnC@Du{`V$kl@a<$8gTrvQ6IY7Z7r&Dn zjdqgZ12+OkCs{QLvP0Kix}l;aUX6;me|$K*D2Ua>Rm-lo{d0nt5Kpl`I+k^3vQcmk znFBn*t10`qtC^J9-Nu5?ehgJ3;o$x`@gjnko?vSR$(M!3$ciU5^rw(4_m znnA1L)&P0dOx!|SRl^?aG{>J5sHQOLg~w;}X@NWE>dy1B#B&oN9$fsgfo_wCpkAsn zE!cMh${yYaxG+v9bEWk4x_)x;Wau#nJF?8euNo~I=kHRxkF(dOzav@T9!ao0iiB{@ zq?er;Dbtj1RjGxf?bq+fwi_uJR;CQiR3b|qa%1O3jAbF3aupti>?T5oQkoe>F2bbN zn3d2VJKA?Fa*+|Mjr4v-ouLCbxLIO=v!@M($sOs{`}9r^@j0ib7}_(X7F>vBW7p(& z?=DAdYNW4;K3|&@aaS%(jt>cf%P%Oph@C{J(v(&a3=i5WC>iAs*E(hLfGP6fIIwaT zWbSWr^D}A&@8wqt+kOU(!x)#+caUS_>XjVQ{rZS=)OAZCG`BT5?0FnABbEyhqg$w5(W7C=KrBX(XLltq zK;QJ;sEppddR%r^cy5=n$D}8ff`LnwUEY<$&J;^7Y;NH9!3?s_gKo5upj$n${=+e? zCHcC=30gE;c+t7*n9((HxPtnUz}qh8YzF)lev8y!7~+rWAA?MaWyMmB1!x9zlMh?H zt6FQ!@&SuZJ@R>16jsBwr(8;)I61JIDztqx6JEp#fx+*U^r>Mqb{1JG_EW0&E~tn& zMe{|1rDo{jjo}_}Z#k&-6ZO>53~_?2daH{G`{>hh z1OwS;-&FywBGYn+$nhT`0b6oBZnOh_>DtOdS?M7k1vM0?UyM#0Rc|LF+Y}+n>PQ^fOzspR2%HWwP551A)zdYoot&c>|0YDSQ}1b zm#4b_BO}2rEaX{P6LDN2%*KhDS)$c4UEhl4g2_%gXDqhyq?h9PAbFFivP#o#lg#&c zE0janWt;uOft@X8zJYK1Tgs2u`E8o2_78?lte4PB#r33tg$*C?d2L;H6xK#{kK~!9 zb-)WXNG1q&nHds3-_1A)Tqe$TIkn7w|5e4x&LkL9hosrj{)7-GCvvi3-QzKRd^g|0 z4+uPNNmSfx$^5~#(wt9DMQ$(a!6~v|egoN7IE@ zJ#xzv_AMXb1O6Sy$OJtW09~JhoWS$qED?nYIgO43u|&CzwBoN->qA^t|Q`Em;yjQZBh2)hAKIzPdSAP@O{$Mv?`_K2>%P;%?b?D(Sl0; vPA)Z>OBgMPQyM_}s3`08_J}-iK`$UK`EsT(4c5P(vw#$2RHdsWO@sd*;FTGc literal 0 HcmV?d00001