documentation more consistent

README.md

@@ -1,11 +1,35 @@
 # racket-webview
 
-Webview integration for racket
+Webview integration for Racket.
 
-## Release v0.1.8
+## Release v0.1.11
 
-Uses release v0.2.2 of racket-webview-qt. 
+This release assigns explicit, file-prefixed Scribble tags to manual parts and sections. This prevents duplicate collected-information warnings for headings such as `Overview`, `Example`, `Conversion`, `Events`, and `racket-webview` during `raco setup`.
-QtWebEngine select popup rendering issue observed with older Qt 6.x.
+
-Symptom: native HTML <select> popup keeps growing/repainting while open;
+The process-interface changes from v0.1.10 remain unchanged.
-QtWebEngine process busy, Racket process idle.
+
-Resolved by upgrading to Qt 6.11.1.
+### Process interface (introduced in v0.1.10)
+
+This version replaces the FFI/shared-memory transport with a child-process
+interface to racket-webview-qt v0.2.3:
+
+- commands: JSON lines on child stdin
+- results and events: JSON lines on child stdout
+- backend diagnostics: child stderr
+
+The public Racket procedures, command numbers, command payloads, result symbols,
+and event JSON remain unchanged. Set `RKT_WEBVIEW_PRG` to an explicit locally
+built backend executable during development.
+
+## Previous Qt update
+
+QtWebEngine select popup rendering issues were observed with older Qt 6.x. The
+native HTML `<select>` popup could keep growing or repainting while open while
+the QtWebEngine process remained busy. Upgrading to Qt 6.11.1 resolved this.
+
+### Qt backend logging
+
+Structured stderr records from `rktwebview_prg` are logged through `simple-log`
+under the separate topic `webview-backend`. Ordinary Racket-side messages keep
+the topic `webview`. Unstructured stderr lines are accepted and logged at debug
+level under `webview-backend`.

example1/example.rkt

@@ -310,7 +310,8 @@
 (webview-set-loglevel 'debug)
 (define log-file (build-path (find-system-path 'temp-dir) "example1.log"))
 (displayln (format "logging to ~a" log-file))
-(sl-log-to-file log-file)
+;(sl-log-to-file log-file)
+(define store (sl-log-to-store 10000))
 
 (define (run-example)
   (let* ((ini (new ini% [file 'web-racket-example1]))
@@ -327,5 +328,5 @@
   (let ((window (run-example)))
     (webview-wait-for-quit)
     (webview-exit)
-    (exit)
+    ;(exit)
     ))

info.rkt

@@ -1,8 +1,8 @@
 #lang info
 
 (define pkg-authors '(hnmdijkema))
-(define version "0.1.9")
+(define version "0.1.11")
-(define license 'MIT)   
+(define license 'MIT)
 (define collection "racket-webview")
 (define pkg-desc "racket-webview - A Web Based GUI library, based on a Qt WebEngine backend")
 
@@ -13,13 +13,13 @@
   )
 
 (define deps
- '("racket/base" 
+ '("racket/base"
-   "http-easy" 
+   "http-easy"
-   "gregor" 
+   "gregor"
-   "racket/gui" 
+   "racket/gui"
-   "html-printer-lib" 
+   "html-printer-lib"
-   "racket/net" 
+   "racket/net"
-   "simple-ini" 
+   "simple-ini"
    "gregor-utils"
    "racket-sprintf"
    "lru-cache"

private/utils.rkt

@@ -40,11 +40,19 @@
        warn-webview
        fatal-webview
        sync-log-webview
+
+       dbg-webview-backend
+       err-webview-backend
+       info-webview-backend
+       warn-webview-backend
+       fatal-webview-backend
+       sync-log-webview-backend
        
        )
 
 
 (sl-def-log webview)
+(sl-def-log webview-backend)
 
 (define-syntax while
 (syntax-rules ()

racket-webview-downloader.rkt

@@ -26,7 +26,7 @@
 
 (define rkt-qt-version-major 0)
 (define rkt-qt-version-minor 2)
-(define rkt-qt-version-patch (if (eq? (system-type 'os) 'windows) 2 1))
+(define rkt-qt-version-patch 3)
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Internal functions
@@ -164,7 +164,7 @@
         (let ((out (open-output-file version-file #:exists 'replace)))
           (write version out)
           (close-output-port out)))
-      (displayln "Version file written; ready for FFI integration")
+      (displayln "Version file written; backend process is ready")
       #t
       )
     )

racket-webview.rkt

@@ -1042,7 +1042,7 @@
                           (return (list (list 'id id)
                                         (list 'style (send Object entries r))))))))
           )
-      (displayln js-code)
+      ;(displayln js-code)
       (let ((r (webview-call-js wv js-code)))
       ;                       (format
       ;                        (js-code
@@ -1056,7 +1056,7 @@
       ;                         "  return { id: id, style: r };"
       ;                         "}") cl))
       ;                     )))
-        (display "Result: ") (write r) (newline)
+      ;  (display "Result: ") (write r) (newline)
         (if (eq? r #f)
             #f
             (let ((h (hash-ref r 'with-ids)))
@@ -1067,8 +1067,8 @@
                                        (make-hash (map (λ (e) (cons (to-symbol (car e)) (cadr e))) (cadr style-rec)))
                                        )
                                  )) h)))
-                (displayln (format "l = ~a" l))
+                ;(displayln (format "l = ~a" l))
-                (write l)(newline)
+                ;(write l)(newline)
               ; l = ((volume-meter . #hash((display . none))))
               ; ((volume-meter . #hash(("display" . "none"))))
                 (if (symbol? selector)

scrbl/js-transform.scrbl

@@ -3,7 +3,7 @@
 @(require (for-label racket/base
                      "../private/js-transform.rkt"))
 
-@title{JavaScript Transformation}
+@title[#:tag "js-transform"]{JavaScript Transformation}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/private/js-transform]
@@ -47,7 +47,7 @@ This generates JavaScript source that assigns a function to
 sets an attribute, and writes a message to the JavaScript console.
 }
 
-@section{Primitive values}
+@section[#:tag "js-transform-primitive-values"]{Primitive values}
 
 Numbers are emitted as JavaScript numeric literals.  Strings are emitted as
 double-quoted JavaScript strings, with embedded double quotes escaped.
@@ -68,7 +68,7 @@ Symbols can be quoted to produce JavaScript string values:
  (send console log 'hello))
 ]
 
-@section{Function calls and method calls}
+@section[#:tag "js-transform-function-calls-and-method-calls"]{Function calls and method calls}
 
 A form that is not recognized as a special DSL form is treated as a JavaScript
 function call:
@@ -109,7 +109,7 @@ document.getElementById("hi")
 Using @racket[send] keeps the method-call structure explicit in the DSL.  It is
 usually clearer than writing dotted JavaScript names directly as function names.
 
-@section{Operators}
+@section[#:tag "js-transform-operators"]{Operators}
 
 The DSL supports a small set of JavaScript infix operators.
 
@@ -138,7 +138,7 @@ For example:
        (return (* x x)))))
 ]
 
-@section{Definitions and assignments}
+@section[#:tag "js-transform-definitions-and-assignments"]{Definitions and assignments}
 
 @defform[(define (name arg ...) body ...)]{
 
@@ -165,7 +165,7 @@ Generates a JavaScript assignment.
 This produces an assignment to @tt{window.answer}.
 }
 
-@section{Functions}
+@section[#:tag "js-transform-functions"]{Functions}
 
 @defform[(lambda (arg ...) body ...)]{
 Generates a JavaScript function expression.
@@ -194,7 +194,7 @@ A function body may contain more than one DSL statement:
          (return (* x x)))))
 ]
 
-@section{Control flow and statement blocks}
+@section[#:tag "js-transform-control-flow-and-statement-blocks"]{Control flow and statement blocks}
 
 @defform[(if condition then-expr else-expr)]{
 
@@ -236,7 +236,7 @@ Generates a JavaScript @tt{return} statement.
 ]
 }
 
-@section{Sequential bindings}
+@section[#:tag "js-transform-sequential-bindings"]{Sequential bindings}
 
 @defform[(let* ((id expr) ...) body ...)]{
 
@@ -256,7 +256,7 @@ context.  Use @racket[let*] instead, so that the generated JavaScript bindings
 remain explicitly sequential.
 }
 
-@section{Lists}
+@section[#:tag "js-transform-lists"]{Lists}
 
 @defform[(list expr ...)]{
 
@@ -287,7 +287,7 @@ console.log([ x].concat([ y].concat([ z])));
 }|
 }
 
-@section{Embedding Racket values}
+@section[#:tag "js-transform-embedding-racket-values"]{Embedding Racket values}
 
 @defform[(eval value)]{
 
@@ -306,7 +306,7 @@ The value is converted to JavaScript source text before the generated JavaScript
 is returned.
 }
 
-@section{Example}
+@section[#:tag "js-transform-example"]{Example}
 
 The following example combines function definition, method calls, list
 construction, sequential bindings and a lambda expression passed to a JavaScript
@@ -327,7 +327,7 @@ method:
 This generates a JavaScript function that logs an array, constructs the same
 array in a local binding, maps over it, and returns the mapped result.
 
-@section{Limitations}
+@section[#:tag "js-transform-limitations"]{Limitations}
 
 This transformer is intentionally small.  It is not a complete JavaScript
 parser, not a JavaScript evaluator and not a general Racket-to-JavaScript

scrbl/menu.scrbl

@@ -8,7 +8,7 @@
                      json
                      "../menu.rkt"))
 
-@title{menu}
+@title[#:tag "menu"]{menu}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/menu]
@@ -18,7 +18,7 @@ Menu data structures used by the webview library.
 This module provides constructors, predicates, traversal helpers, mutation
 operations, and JSON conversion for menu trees.
 
-@section{Overview}
+@section[#:tag "menu-overview"]{Overview}
 
 A menu is represented as a tree. A menu consists of menu items, and a menu item
 may optionally contain a submenu.
@@ -29,14 +29,14 @@ strings and may be supplied either as @racket[#f], strings, or URL values.
 The module does not display menus itself. It provides the menu data structure
 used by higher layers.
 
-@section{Internal Representation}
+@section[#:tag "menu-internal-representation"]{Internal Representation}
 
 Internally, menus are represented by transparent structure values. These
 structure constructors and predicates are not exported directly. The public API
 uses constructor procedures and helper functions operating on those internal
 values.
 
-@section{Predicates}
+@section[#:tag "menu-predicates"]{Predicates}
 
 @defproc[(is-wv-menu? [mnu any/c]) boolean?]{
 
@@ -48,7 +48,7 @@ list is a list of internal menu items, and every submenu recursively also
 satisfies @racket[is-wv-menu?].
 }
 
-@section{Constructors}
+@section[#:tag "menu-constructors"]{Constructors}
 
 @defproc[(wv-menu [item-or-id any/c] ...)
          any/c]{
@@ -97,7 +97,7 @@ stored.
 If any argument does not satisfy these conditions, an exception is raised.
 }
 
-@section{Traversal and Lookup}
+@section[#:tag "menu-traversal-and-lookup"]{Traversal and Lookup}
 
 @defproc[(wv-menu-for-each [menu any/c] [cb procedure?]) boolean?]{
 
@@ -121,7 +121,7 @@ After the callback has been applied, the original @racket[menu] value is
 returned.
 }
 
-@section{Mutation}
+@section[#:tag "menu-mutation"]{Mutation}
 
 @defproc[(wv-menu-set-title! [menu any/c] [id symbol?] [title string?])
          any/c]{
@@ -154,7 +154,7 @@ Sets the callback of the menu item identified by @racket[id].
 @racket[menu] value.
 }
 
-@section{Conversion}
+@section[#:tag "menu-conversion"]{Conversion}
 
 @defproc[(wv-menu->json [menu any/c]) string?]{
 
@@ -177,7 +177,7 @@ The @racket['id] field of the top-level menu is also converted to a string in
 the JSON output.
 }
 
-@section{Accessors}
+@section[#:tag "menu-accessors"]{Accessors}
 
 @defproc[(wv-menu-id [m any/c]) any/c]{
 

scrbl/racket-webview-collection.scrbl

@@ -5,7 +5,7 @@
           scribble/core
           )
 
-@title{@elem{racket-webview}}
+@title[#:tag "racket-webview-collection"]{@elem{racket-webview}}
 
 @table-of-contents[]
 

scrbl/racket-webview-downloader.scrbl

@@ -7,7 +7,7 @@
                      setup/dirs
                      "../racket-webview-downloader.rkt"))
 
-@title{racket-webview-downloader}
+@title[#:tag "racket-webview-downloader"]{racket-webview-downloader}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/racket-webview-downloader]
@@ -18,7 +18,7 @@ This module provides functions for checking whether the native runtime is
 already installed, whether it can be resolved and downloaded, and for
 downloading and unpacking it into the user's addon directory.
 
-@section{Overview}
+@section[#:tag "racket-webview-downloader-overview"]{Overview}
 
 The module manages one specific downloadable version of the native
 @tt{racket-webview-qt} package. The version is fixed in the source code through
@@ -36,7 +36,7 @@ The download URL is derived from:
 The downloaded archive is installed below the user's addon directory in a
 subdirectory named @tt{racket-webview-qt}.
 
-@section{Installation Layout}
+@section[#:tag "racket-webview-downloader-installation-layout"]{Installation Layout}
 
 The installation directory is:
 
@@ -57,7 +57,7 @@ The OS and architecture components are derived from:
 (system-type 'arch)
 ]
 
-@section{Availability and Version Checks}
+@section[#:tag "racket-webview-downloader-availability-and-version-checks"]{Availability and Version Checks}
 
 @defproc[(racket-webview-qt-is-available?) boolean?]{
 
@@ -93,7 +93,7 @@ The returned path has the form:
 ]
 }
 
-@section{Downloadability Checks}
+@section[#:tag "racket-webview-downloader-downloadability-checks"]{Downloadability Checks}
 
 @defproc[(racket-webview-qt-resolves?) boolean?]{
 
@@ -114,7 +114,7 @@ succeeds, the port is closed immediately and the function returns
 @racket[#t]. Any failure is caught and results in @racket[#f].
 }
 
-@section{Downloading}
+@section[#:tag "racket-webview-downloader-downloading"]{Downloading}
 
 @defproc[(download-racket-webview-qt) boolean?]{
 
@@ -138,7 +138,7 @@ If no download port can be obtained, the function raises an exception. Otherwise
 on successful completion, it returns @racket[#t].
 }
 
-@section{Notes}
+@section[#:tag "racket-webview-downloader-notes"]{Notes}
 
 The module forces HTTPS downloads by temporarily setting the current HTTPS
 protocol to @racket['secure] while opening the download port.

scrbl/racket-webview-intro.scrbl

@@ -23,24 +23,25 @@
 @(define version (webview-version-string))
 
 
-@title{Racket Webview - v@version - Introduction}
+@title[#:tag "racket-webview-intro"]{Racket Webview - v@version - Introduction}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule{racket-webview}
 
-@section{Overview}
+@section[#:tag "racket-webview-intro-overview"]{Overview}
 
 This documentation is provided for version @bold{@version} of racket webview.
 
 Racket Webview is a class-oriented webview library built on top of a Qt-based
 native runtime.
 
-The library is layered. At the lowest level a native FFI layer is used. On top
+The library is layered. At the lowest level, Racket starts a separate Qt helper
-of that, @racketmodname[racket-webview/racket-webview] provides a functional API. The
+process and exchanges line-delimited JSON messages through stdin and stdout.
-class-oriented API described in this manual is built from smaller modules on top
+On top of that, @racketmodname[racket-webview/racket-webview] provides a
-of that layer.
+functional API. The class-oriented API described in this manual is built from
+smaller modules on top of that layer.
 
-@section{Core Concepts}
+@section[#:tag "racket-webview-intro-core-concepts"]{Core Concepts}
 
 The library is structured around two main concepts:
 
@@ -51,7 +52,7 @@ The library is structured around two main concepts:
 A context manages local file serving, certificates, and settings. A window loads
 content, handles events, and provides access to DOM elements.
 
-@section{Modules}
+@section[#:tag "racket-webview-intro-modules"]{Modules}
 
 The public API is divided into the following modules:
 
@@ -65,7 +66,7 @@ The public API is divided into the following modules:
  @item{@racketmodname[racket-webview/rgba] — RGBA color values}
  @item{@racketmodname[racket-mimetypes] — MIME type lookup}]
 
-@section{Typical Usage}
+@section[#:tag "racket-webview-intro-typical-usage"]{Typical Usage}
 
 A typical application creates a @racket[wv-context%] object and then creates one
 or more @racket[wv-window%] objects within that context. DOM elements are

scrbl/racket-webview-qt.scrbl

@@ -2,23 +2,24 @@
 
 @defmodule{racket-webview/racket-webview-qt}
 
-@title{Racket FFI Interface for @tt{rktwebview_qt}}
+@title[#:tag "rktwebview-process"]{Racket Process Interface for @tt{rktwebview_prg}}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
-@section{Overview}
+@section[#:tag "racket-webview-qt-overview"]{Overview}
 
-The module @tt{racket-webview-qt.rkt} provides a Racket FFI wrapper around the
+The module @tt{racket-webview-qt.rkt} provides the low-level Racket interface to
-native @tt{rktwebview_qt} library. It loads the shared library, initializes the
+the Qt helper process @tt{rktwebview_prg}. It keeps the existing command numbers,
-native runtime, and exposes Racket functions for creating and controlling
+JSON command payloads, result symbols, event strings, and public Racket
-webview windows.
+procedures, but no longer loads a shared library through FFI.
 
-If the Qt backend is available locally, it is loaded directly. Otherwise the
+The helper process is started lazily when the first backend operation is
-module attempts to resolve and download the backend. If that is not possible,
+requested. Commands are written as one JSON object per line to the process
-the module continues in a degraded mode in which a limited subset of the
+stdin. Results and asynchronous events are read from stdout. Backend diagnostics
-FFI entry points will only display a warning and perform a no-op. All others will fail. 
+are copied from stderr to the current Racket error port.
 
-The wrapper translates the low-level C interface into a Racket-oriented API
+Each command has a request identifier. The identifier is transport metadata and
-based on structures, callbacks, and ordinary Racket values.
+does not alter the existing command payload. It makes it possible to associate
+a result with the correct caller when multiple Racket threads use the backend.
 
 The module provides:
 
@@ -30,81 +31,39 @@ The module provides:
  @item{window geometry and visibility control}
  @item{native dialogs}
  @item{asynchronous event delivery}
- @item{version and cleanup utilities}
+ @item{version and cleanup utilities}]
-]
 
-@section{Requirements}
+@section[#:tag "racket-webview-qt-backend-availability"]{Backend Availability}
 
-The native backend requires Qt version @tt{6.10.2} or newer.
+The environment variable @tt{RKT_WEBVIEW_PRG} may name an explicit backend
+executable. This is useful during development and testing.
 
-The shared library @tt{rktwebview_qt} must therefore be built against Qt
+Without that variable, the module uses the existing downloader and installation
-@tt{6.10.2} or a compatible later release.
+directory. Availability is checked when the first backend operation is made,
+not while the module is loaded. If the configured backend cannot be found or
+downloaded, that operation raises an exception with the reason.
 
-Earlier Qt versions are not supported.
+@section[#:tag "racket-webview-qt-module-initialization"]{Module Initialization}
 
-@section{Backend Availability}
+Starting the backend performs the following steps:
-
-The module first checks whether the expected @tt{racket-webview-qt} backend is
-already installed.
-
-If it is not installed, the module attempts to resolve the configured download
-site. If the site can be resolved and the configured archive is downloadable,
-the backend is downloaded automatically.
-
-If the download site cannot be resolved, if no archive is available for the
-current operating system and machine architecture, or if the download fails, the
-module does not immediately abort module loading. Instead it switches to a
-degraded mode in which native FFI loading is disabled.
-
-In that degraded mode, a textual reason is stored internally and selected FFI
-entry points are replaced by fallback implementations.
-
-When the backend cannot be loaded, the module defines fallback implementations
-for missing FFI entry points through @racket[define-ffi-definer] and
-@racket[#:default-make-fail].
-
-These fallbacks behave in two different ways.
-
-For a small set of initialization and shutdown functions, a non-failing fallback
-is installed:
 
 @itemlist[#:style 'compact
- @item{@racket[rkt_webview_env] returns @racket[#t]}
+ @item{locates or downloads @tt{rktwebview_prg}}
- @item{@racket[rkt_webview_events_waiting] returns @racket[0]}
+ @item{sets the Qt runtime environment for the child process}
- @item{@racket[rkt_webview_init] returns @racket[#t]}
+ @item{starts the child with separate stdin, stdout, and stderr pipes}
- @item{@racket[rkt_webview_cleanup] returns @racket[#t]}]
+ @item{starts a stdout protocol reader}
+ @item{starts a stderr forwarding thread}
+ @item{waits for the protocol-version handshake}
+ @item{starts an independent Racket event-dispatch thread}]
 
-All other missing FFI functions raise an exception when called.
+Stdout is reserved for protocol records. Human-readable backend logging is
+written only to stderr.
 
-Fallback warnings are emitted at most once per function. If native loading was
+Currently the wrapper supports @tt{'linux} and @tt{'windows} release layouts.
-disabled because the backend was unavailable, the warning message includes the
-recorded reason. If native loading was enabled but a specific symbol could not
-be loaded from the library, the error names the library file.
 
-@section{Module Initialization}
+@section[#:tag "racket-webview-qt-data-model"]{Data Model}
 
-Loading the module performs several initialization steps automatically.
+@subsection[#:tag "racket-webview-qt-rkt-wv-structure"]{The @tt{rkt-wv} Structure}
-
-@itemlist[#:style 'compact
- @item{determines the operating system and architecture}
- @item{sets Qt runtime environment variables}
- @item{loads the @tt{rktwebview_qt} shared library}
- @item{initializes the native runtime}
- @item{starts a background thread that processes native events}
-]
-
-Currently the wrapper supports the following platforms:
-
-@itemlist[#:style 'compact
- @item{@tt{'linux}}
- @item{@tt{'windows}}
-]
-
-If the current system is unsupported, loading the module raises an error.
-
-@section{Data Model}
-
-@subsection{The @tt{rkt-wv} Structure}
 
 Each webview window is represented by a transparent Racket structure.
 
@@ -136,7 +95,7 @@ an opaque handle.
 @;Returns the native window handle associated with @racket[wv].
 @;}
 
-@section{HTTP(S) Contexts}
+@section[#:tag "racket-webview-qt-http-s-contexts"]{HTTP(S) Contexts}
 
 A context represents the shared HTTP(S) environment used by webviews.
 
@@ -167,7 +126,7 @@ The returned context identifier can be passed to
 @racket[rkt-webview-create] to create webviews within that context.
 }
 
-@section{Creating Webviews}
+@section[#:tag "racket-webview-qt-creating-webviews"]{Creating Webviews}
 
 @defproc[(rkt-webview-create
           [context exact-integer?]
@@ -194,14 +153,15 @@ Events generated by the native layer are delivered asynchronously through
 @racket[evt-callback].
 }
 
-@section{Window Lifecycle}
+@section[#:tag "racket-webview-qt-window-lifecycle"]{Window Lifecycle}
 
 @defproc[(rkt-webview-close [wv rkt-wv?]) boolean?]{
 
 Requests that the webview window be closed.
 
-The wrapper forwards the request to the native backend and schedules cleanup of
+The wrapper forwards the request to the helper process. The Qt-generated
-the event-processing loop.
+@tt{"closed"} event is delivered asynchronously, after which the Racket handle
+is removed.
 
 Returns @racket[#t].
 }
@@ -222,7 +182,7 @@ This function is also registered with the Racket plumber so that cleanup occurs
 automatically when the process exits.
 }
 
-@section{Window Configuration}
+@section[#:tag "racket-webview-qt-window-configuration"]{Window Configuration}
 
 @defproc[(rkt-webview-set-title! [wv rkt-wv?] [title string?])
          symbol?]{
@@ -246,7 +206,7 @@ This token may be used by the native layer when accepting certain
 self-signed certificates.
 }
 
-@section{Navigation}
+@section[#:tag "racket-webview-qt-navigation"]{Navigation}
 
 @defproc[(rkt-webview-set-url! [wv rkt-wv?] [url string?]) symbol?]{
 
@@ -272,7 +232,7 @@ Returns a result symbol such as:
 ]
 }
 
-@section{JavaScript Execution}
+@section[#:tag "racket-webview-qt-javascript-execution"]{JavaScript Execution}
 
 @defproc[(rkt-webview-run-js [wv rkt-wv?] [js string?]) symbol?]{
 
@@ -305,7 +265,7 @@ where:
 The JSON structure is generated by the native backend.
 }
 
-@section{Window Geometry}
+@section[#:tag "racket-webview-qt-window-geometry"]{Window Geometry}
 
 @defproc[(rkt-webview-move [wv rkt-wv?] [x exact-integer?] [y exact-integer?])
          symbol?]{
@@ -362,15 +322,15 @@ Possible results:
 ]
 }
 
-@section{Developer Tools}
+@section[#:tag "racket-webview-qt-developer-tools"]{Developer Tools}
 
 @defproc[(rkt-webview-open-devtools [wv rkt-wv?]) symbol?]{
 Opens the browser developer tools window.
 }
 
-@section{Native Dialogs}
+@section[#:tag "racket-webview-qt-native-dialogs"]{Native Dialogs}
 
-Dialog functions return immediately with a status code.  
+Dialog functions return immediately with a status code.
 The user’s choice is delivered asynchronously through the event callback.
 
 @defproc[(rkt-webview-choose-dir
@@ -413,7 +373,7 @@ Requests a file-save dialog.
 Shows a native message box.
 }
 
-@section{Event Delivery}
+@section[#:tag "racket-webview-qt-event-delivery"]{Event Delivery}
 
 Each webview has an associated event callback.
 
@@ -445,23 +405,23 @@ Typical event types include:
 
 The wrapper does not parse the JSON payload.
 
-@section{Version Information}
+@section[#:tag "racket-webview-qt-version-information"]{Version Information}
 
 @defproc[(rkt-webview-version)
          (list/c list? list?)]{
 
-Returns version information for the native backend.
+Returns the stdio protocol version and the expected Qt backend release.
 
 Example result:
 
 @racketblock[
 (list
- (list 'webview-c-api 1 0 0)
+ (list 'webview-stdio-api 1 0 0)
- (list 'qt 6 10 2))
+ (list 'racket-webview-qt 0 2 3))
 ]
 }
 
-@section{Example}
+@section[#:tag "racket-webview-qt-example"]{Example}
 
 @racketblock[
 (define ctx
@@ -480,16 +440,16 @@ Example result:
 (rkt-webview-set-url! wv "https://example.org")
 ]
 
-@section{Summary}
+@section[#:tag "racket-webview-qt-summary"]{Summary}
 
-The FFI module provides a thin Racket interface to the native
+The module provides a thin Racket interface to the separate
-@tt{rktwebview_qt} backend.
+@tt{rktwebview_prg} process.
 
 Key characteristics:
 
 @itemlist[#:style 'compact
- @item{thin wrapper around the native C API}
+ @item{line-delimited JSON over stdin and stdout}
- @item{asynchronous event delivery}
+ @item{request identifiers for concurrent synchronous calls}
- @item{JSON-based event payloads}
+ @item{asynchronous event delivery on a separate Racket thread}
- @item{simple Racket structures for webviews}
+ @item{unchanged JSON event payloads}
-]
+ @item{simple Racket structures for webviews}]

scrbl/racket-webview.scrbl

@@ -3,7 +3,7 @@
 @(require racket/base
           scribble/core)
 
-@title{racket-webview}
+@title[#:tag "racket-webview"]{racket-webview}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/racket-webview]
@@ -14,7 +14,7 @@ This module provides a structured programming model around the lower-level
 webview bindings. It introduces contexts, a local HTTPS server, JSON-based
 event handling, and DOM and JavaScript utilities.
 
-@section{Architecture}
+@section[#:tag "racket-webview-architecture"]{Architecture}
 
 The module builds on the lower-level bindings from
 @racketmodname[racket-webview/racket-webview-qt]. It adds:
@@ -31,7 +31,7 @@ JavaScript calls. When an HTML file is
 served, the context's CSS boilerplate is injected immediately before the
 closing @tt{</head>} tag.
 
-@section{Contexts}
+@section[#:tag "racket-webview-contexts"]{Contexts}
 
 
 @defproc[(webview-new-context
@@ -76,7 +76,7 @@ This URL can be used to construct URLs from relative path information.
 Recognizes context values.
 }
 
-@section{Windows}
+@section[#:tag "racket-webview-windows"]{Windows}
 
 @defproc[(webview-create
           [context wv-context?]
@@ -136,7 +136,7 @@ Resizes the window.
 Returns the current window state.
 }
 
-@section{Navigation and Content}
+@section[#:tag "racket-webview-navigation-and-content"]{Navigation and Content}
 
 @defproc[(webview-set-url! [wv wv-win?] [url (or/c string? url?)])
          symbol?]{
@@ -176,7 +176,7 @@ The result is the symbol returned by @racket[webview-run-js].
 Sets the window title.
 }
 
-@section{JavaScript}
+@section[#:tag "racket-webview-javascript"]{JavaScript}
 
 @defproc[(webview-run-js [wv wv-win?] [js string?]) symbol?]{
 Evaluates JavaScript.
@@ -196,7 +196,7 @@ structure, an exception is raised.
 }
 
 
-@section{Dialogs}
+@section[#:tag "racket-webview-dialogs"]{Dialogs}
 
 Dialog functions return immediately. Results are delivered asynchronously via
 events.
@@ -254,9 +254,9 @@ is indicated through the event.
 }
 
 
-@section{DOM Interaction}
+@section[#:tag "racket-webview-dom-interaction"]{DOM Interaction}
 
-@subsection{Selectors and Element Identifiers}
+@subsection[#:tag "racket-webview-selectors-and-element-identifiers"]{Selectors and Element Identifiers}
 
 Many functions accept either an element identifier or a CSS selector.
 
@@ -272,7 +272,7 @@ If a string is provided, it is used directly as a CSS selector.
 
 Functions apply their effect to all matched elements.
 
-@subsection{Event Binding}
+@subsection[#:tag "racket-webview-event-binding"]{Event Binding}
 
 @defproc[(webview-bind!
           [wv wv-win?]
@@ -300,7 +300,7 @@ Selector handling is the same as for @racket[webview-bind!]. The result is a
 list describing the removed bindings.
 }
 
-@subsection{DOM Values}
+@subsection[#:tag "racket-webview-dom-values"]{DOM Values}
 
 @defproc[(webview-set-value!
           [wv wv-win?]
@@ -367,7 +367,7 @@ Returns the value converted to a datetime.
 Returns the value converted to a color.
 }
 
-@subsection{Classes, Styles}
+@subsection[#:tag "racket-webview-classes-styles"]{Classes, Styles}
 
 @defproc[(webview-add-class!
           [wv wv-win?]
@@ -428,7 +428,7 @@ If @racket[selector] is a symbol, the result for that single element is returned
 directly. Otherwise the result covers all matched elements.
 }
 
-@subsection{Attributes}
+@subsection[#:tag "racket-webview-attributes"]{Attributes}
 
 @defproc[(webview-set-attr!
           [wv wv-win?]
@@ -517,7 +517,7 @@ Returns the attribute value converted to a datetime.
 Returns the attribute value converted to a color.
 }
 
-@subsection{Inner HTML}
+@subsection[#:tag "racket-webview-inner-html"]{Inner HTML}
 
 @defproc[(webview-set-innerHTML!
           [wv wv-win?]
@@ -531,7 +531,7 @@ Returns @racket['oke] if the injected JavaScript yields a true value, and
 @racket['failed] otherwise.
 }
 
-@section{File Filters}
+@section[#:tag "racket-webview-file-filters"]{File Filters}
 
 @defstruct*[wv-permitted-exts ([name string?]
                                [exts (listof symbol?)])]{
@@ -548,7 +548,7 @@ Represents a file dialog filter entry.
 Recognizes lists of filter entries.
 }
 
-@section{Utilities}
+@section[#:tag "racket-webview-utilities"]{Utilities}
 
 @defproc[(webview-default-boilerplate-js [custom-js procedure?] ...)
          string?]{
@@ -576,7 +576,7 @@ If an additional procedure is supplied, its returned string is appended to that
 Creates a standard file getter.
 }
 
-@section{Diagnostics}
+@section[#:tag "racket-webview-diagnostics"]{Diagnostics}
 
 @defproc[(webview-version) list?]{
 Returns version information.
@@ -589,7 +589,8 @@ Returns runtime information.
 @defproc[(webview-set-loglevel [l (or/c 'error 'warning 'info 'debug)])
          void?]{
 
-Sets the native log level.
+Sets the Qt backend log level.
 
-The native log file path can be obtained via @racket[webview-info].
+Backend diagnostics are written to stderr. The destination reported by
+@racket[webview-info] is @tt{"stderr"}.
 }

scrbl/rgba.scrbl

@@ -6,7 +6,7 @@
                      racket/string
                      racket/contract))
 
-@title{rgba}
+@title[#:tag "rgba"]{rgba}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/rgba]
@@ -16,7 +16,7 @@ RGBA color support used by the webview library.
 This module exports a transparent @racket[rgba] structure together with
 predicates and conversion procedures for working with CSS-style color values.
 
-@section{Overview}
+@section[#:tag "rgba-overview"]{Overview}
 
 An @racket[rgba] value represents a color using red, green, blue, and alpha
 components.
@@ -35,7 +35,7 @@ The intended external representation is the CSS form:
 "rgba(r,g,b,a)"
 ]
 
-@section{Predicates}
+@section[#:tag "rgba-predicates"]{Predicates}
 
 @defproc[(rgba/color? [v any/c]) boolean?]{
 
@@ -53,7 +53,7 @@ A valid alpha component is a real number in the range from @racket[0] to
 @racket[1], inclusive.
 }
 
-@section{Structure Type}
+@section[#:tag "rgba-structure-type"]{Structure Type}
 
 @defstruct*[rgba ([r rgba/color?]
                   [g rgba/color?]
@@ -68,7 +68,7 @@ components. The field @racket[a] is the alpha component.
 The structure is transparent.
 }
 
-@section{Conversion}
+@section[#:tag "rgba-conversion"]{Conversion}
 
 @defproc[(rgba->string [c rgba?]) string?]{
 

scrbl/rktwebview-api.scrbl

@@ -4,18 +4,19 @@
 
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
-@title{C API for Racket Integration}
+@title[#:tag "rktwebview-api"]{C API for Racket Integration}
 
-This section describes the C API exactly as defined in @tt{rktwebview.h} and
+This section documents the legacy C API defined in @tt{rktwebview.h} and
-@tt{rktwebview_types.h}. The API is used from Racket through FFI, but is
+@tt{rktwebview_types.h}. The source remains in the backend repository for
-documented here in its native C/C++ form.
+reference and comparison, but the current build no longer exposes this shared
+library to Racket. The active integration uses the stdio process protocol.
 
 The interface is deliberately small. Handles are integers, most operations
 return a @tt{result_t}, and structured values are returned as @tt{rkt_data_t *}.
 The latter are caller-owned and must be released with
 @tt{rkt_webview_free_data()}.
 
-@section{Version, Export, and Basic Types}
+@section[#:tag "rktwebview-api-version-export-and-basic-types"]{Version, Export, and Basic Types}
 
 The public API version is:
 
@@ -39,7 +40,7 @@ typedef int rkt_wv_context_t;
 @tt{rktwebview_t} identifies a webview. @tt{rkt_wv_context_t} identifies a
 context.
 
-@section{Enums and Structured Data}
+@section[#:tag "rktwebview-api-enums-and-structured-data"]{Enums and Structured Data}
 
 The API defines the following enums: @tt{rkt_webview_loglevel_t},
 @tt{result_t}, @tt{window_state_t}, @tt{rkt_messagetype_t}, and
@@ -91,7 +92,7 @@ typedef struct {
 
 The @tt{kind} field determines which member of @tt{data} is valid.
 
-@section{Ownership}
+@section[#:tag "rktwebview-api-ownership"]{Ownership}
 
 Any function returning @tt{rkt_data_t *} returns allocated memory. The caller
 must release it using:
@@ -104,7 +105,7 @@ This applies to values returned by @tt{rkt_webview_info()},
 @tt{rkt_webview_version()}, @tt{rkt_webview_get_event()}, and
 @tt{rkt_webview_call_js()}.
 
-@section{Environment and Runtime Control}
+@section[#:tag "rktwebview-api-environment-and-runtime-control"]{Environment and Runtime Control}
 
 @defproc[(rkt_webview_env [env_cmds any/c]) void?]{
 C signature:
@@ -184,7 +185,7 @@ Returns a pointer to @tt{rkt_data_t}. The returned object has
 Return value: @tt{rkt_data_t *}, caller-owned.
 }
 
-@subsection{Events}
+@subsection[#:tag "rktwebview-api-events"]{Events}
 
 @defproc[(rkt_webview_events_waiting) exact-integer?]{
 C signature:
@@ -212,7 +213,7 @@ returned pointer may be null.
 Return value: @tt{rkt_data_t *}, caller-owned, or null.
 }
 
-@subsubsection{Event Polling}
+@subsubsection[#:tag "rktwebview-api-event-polling"]{Event Polling}
 
 Events are retrieved explicitly by polling. In normal use, polling should be
 performed regularly; a polling interval of about 10 ms is appropriate.
@@ -221,7 +222,7 @@ This keeps the event queue flowing, allows asynchronous operations such as
 dialogs to complete in a timely manner, and avoids the impression that the system
 has stalled while the Racket side is simply not looking.
 
-@section{Contexts}
+@section[#:tag "rktwebview-api-contexts"]{Contexts}
 
 @defproc[(rkt_webview_new_context [boilerplate_js string?]
                                   [optional_server_cert_pem string?])
@@ -239,7 +240,7 @@ self-signed certificate.
 Return value: @tt{rkt_wv_context_t}.
 }
 
-@section{Webviews}
+@section[#:tag "rktwebview-api-webviews"]{Webviews}
 
 @defproc[(rkt_webview_create [context exact-integer?]
                              [parent exact-integer?])
@@ -307,7 +308,7 @@ specified webview.
 Return value: none.
 }
 
-@section{Navigation and JavaScript}
+@section[#:tag "rktwebview-api-navigation-and-javascript"]{Navigation and JavaScript}
 
 @defproc[(rkt_webview_set_url [wv exact-integer?] [url string?]) exact-integer?]{
 C signature:
@@ -377,7 +378,7 @@ Opens developer tools for the specified webview.
 Return value: @tt{result_t}.
 }
 
-@section{Window Management}
+@section[#:tag "rktwebview-api-window-management"]{Window Management}
 
 @defproc[(rkt_webview_move [w exact-integer?] [x exact-integer?] [y exact-integer?])
          exact-integer?]{
@@ -491,7 +492,7 @@ Returns the current state of the specified window.
 Return value: @tt{window_state_t}.
 }
 
-@section{Dialogs}
+@section[#:tag "rktwebview-api-dialogs"]{Dialogs}
 
 The dialog functions are asynchronous. They request that the dialog be opened on
 the Qt side, but do not block the Racket side while the dialog is shown. This is
@@ -574,7 +575,7 @@ reported through events.
 Return value: @tt{result_t}.
 }
 
-@section{Remarks}
+@section[#:tag "rktwebview-api-remarks"]{Remarks}
 
 The API is queue-based. Commands are issued through function calls; events are
 retrieved explicitly using @tt{rkt_webview_events_waiting()} and

scrbl/rktwebviewqt-internals.scrbl

@@ -1,265 +1,114 @@
 #lang scribble/manual
-@(require racket/runtime-path)
 
 @defmodule{racket-webview/internals}
 
-@title{Qt WebView Backend Architecture}
+@title[#:tag "rktwebviewqt-internals"]{Qt WebView Backend Architecture}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
-@section{Introduction}
+@section[#:tag "rktwebviewqt-internals-overview"]{Overview}
 
-It would, of course, be preferable to place everything within a single process,
+The runtime consists of two processes. The Racket process owns the public API,
-under a unified structure. This would be elegant. It is not how things are.
+contexts used by the local HTTPS server, handle wrappers, and user callbacks.
+The helper process @tt{rktwebview_prg} owns @tt{QApplication}, Qt widgets,
+@tt{QWebEngineProfile} objects, and all browser state.
 
-@(define-runtime-path img-path ".")
+The processes communicate through standard pipes. There is no shared library,
-@(define img (path->string (build-path img-path
+shared-memory queue, or callback from native code into the Racket runtime.
-                                       "rktwebview-shared-memory-diagram-simple.svg"
-                                       )))
-@;@(displayln (format "image: '~a'"  img))
 
-@centered{
+@section[#:tag "rktwebviewqt-internals-standard-streams"]{Standard Streams}
-  @image[#:scale 0.45]{@img}
-}
 
-Qt WebEngine establishes its own order: threads, event loops, internal state.
+The streams have fixed roles:
-Once set in motion, it does not easily yield. It persists, and it expects its
-environment to adapt accordingly. These conditions are accepted.
 
-The Racket process, however, is of a different nature. It is light, precise,
+@itemlist[#:style 'compact
-capable of starting and stopping without residue. It must remain so.
+ @item{child stdin carries commands from Racket}
+ @item{child stdout carries the handshake, command results, and events}
+ @item{child stderr carries diagnostic logging}]
 
-So a boundary is drawn.
+Messages on stdin and stdout are compact UTF-8 JSON objects, one object per
+line. Stdout must not contain ordinary logging because the Racket protocol
+reader treats every value there as a protocol record.
 
-On one side, Qt: a large, immovable instrument—something like an organ. Once it
+@section[#:tag "rktwebviewqt-internals-protocol-compatibility"]{Protocol Compatibility}
-begins to sound, it fills the space, and it is not easily silenced. On the other,
-Racket: a violin, agile and expressive, able to begin and end a phrase at will.
 
-They do not become the same instrument. They are allowed to play together.
+The command identifiers in @tt{rkt_protocol.h} and the JSON objects used as
-Communication is arranged accordingly. A shared memory region, containing three
+command payloads are unchanged. The process transport adds an outer message
-queues: commands, results, and events. A command is issued. It crosses the boundary. It is taken up and executed. A result returns.
+object with a type and, for commands and results, a request identifier.
-Events also arise, independently, and must be handled when they appear.
 
-Within this structure, the violin may move freely—provided it does not attempt to
+A command has this form:
-reconfigure the organ. No attempt is made to unify the instruments. Such efforts would not improve the music. Instead, the composition is written so that each plays its part.
 
-From the outside, one hears only a simple exchange: a call, a response. Internally, the balance is carefully maintained. For now, this is sufficient. And it holds.
+@verbatim|{{"type":"command","id":17,"command":6,"data":{"wv":1,"url":"https://example.test"}}}|
 
-@section{Overview}
+A corresponding result has this form:
 
-This backend provides a webview implementation by delegating all GUI and browser
+@verbatim|{{"type":"result","id":17,"result":0,"data":null}}|
-functionality to a separate Qt process.
 
-The embedding Racket process does not manipulate Qt widgets directly. Instead,
+The request identifier prevents concurrent calls from consuming each other's
-it communicates with a helper process that owns the Qt event loop and all
+results. It is not visible in the public API.
-@tt{QWebEngine} objects.
 
-This design exists to work around limitations of Qt WebEngine in combination with
+@section[#:tag "rktwebviewqt-internals-command-execution"]{Command Execution}
-the lifecycle model of the DrRacket environment.
 
-@section{Execution Model}
+A Racket caller registers a private response channel, writes a command while
+holding the transport write lock, and waits on that channel.
 
-The runtime consists of two processes: the embedding Racket process and a helper
+The Qt process has a command-reader thread. That thread parses stdin records and
-process running Qt and Qt WebEngine.
+calls the existing @tt{Rktwebview_qt} methods. Those methods post commands to the
+Qt GUI thread and wait for completion. The command-reader thread then writes the
+result record to stdout.
 
-All GUI state lives in the helper process. The embedding side holds no direct
+The Racket stdout reader is the only thread that reads protocol output. It uses
-references to Qt objects. Communication is explicit and happens through shared
+the request identifier to forward each result to the correct waiting caller.
-memory.
 
-@section{Shared Memory and Queues}
+@section[#:tag "rktwebviewqt-internals-event-delivery"]{Event Delivery}
 
-A shared memory region is created during initialization. Inside that region,
+Qt events remain the original JSON strings. The Qt callback converts them only
-three FIFO queues are established: a command queue, a result queue, and an event
+into this transport record:
-queue.
 
-Each message consists of a numeric code and a payload, typically JSON:
+@verbatim|{{"type":"event","wv":1,"data":"{...original event JSON...}"}}|
 
-@centerline{@tt{(code, payload)}}
+The stdout reader captures the callback associated with the handle and places
+the callback plus event string on an asynchronous Racket channel. A separate
+event thread invokes user callbacks. Therefore a slow user callback cannot block
+protocol parsing or prevent command results from being received.
 
-The queues have distinct roles. The @italic{command queue} carries requests from the embedding process to the Qt process, for example creating a window, loading a URL, or executing JavaScript. The @italic{result queue} carries direct replies to those commands. A synchronous call on the embedding side blocks until a corresponding result is available. The @italic{event queue} carries asynchronous notifications generated by the Qt side, such as page load completion, navigation requests, window movement, or events
+Capturing the callback while the event record is read is important for window
-originating from JavaScript.
+closure. Qt writes the @tt{"closed"} event before the result of the close command.
+The handle can be removed immediately after the result reaches its caller, but
+the already captured callback still receives the event.
 
-@section{Command Execution}
+@section[#:tag "rktwebviewqt-internals-contexts-and-handles"]{Contexts and Handles}
 
-A function call on the embedding side is translated into a command and written to
+A context corresponds to a @tt{QWebEngineProfile} and is identified by an
-the command queue.
+integer. A webview or tray icon is also identified by an integer handle. Only
+these numbers cross the process boundary; Qt object pointers never do.
 
-From there the flow is fixed: (1) the command is read by a worker thread in the
+The existing Racket @tt{rkt-wv} structure is retained so the higher layers do
-helper process, (2) it is reposted onto the Qt GUI thread, (3) the GUI thread
+not need to change.
-executes the operation, and (4) the result is written back to the result queue.
 
-The worker thread never manipulates Qt objects. All GUI work happens on the GUI
+@section[#:tag "rktwebviewqt-internals-lifecycle-and-failure-handling"]{Lifecycle and Failure Handling}
-thread.
 
-From the caller’s perspective, a synchronous call returns only after the GUI
+The backend writes a protocol-version handshake after initialization. Racket
-thread has completed the action.
+waits for this handshake before sending application commands.
 
-@section{Event Delivery}
+For normal shutdown, Racket closes open handles, sends the existing quit
+command, waits for its result, closes the child's stdin, and waits for the child
+process and reader threads.
 
-Many relevant events are not tied to a specific command. Page loading, navigation
+If Racket terminates unexpectedly, the operating system closes the stdin pipe.
-attempts, window movement, and JavaScript-originated events are delivered through
+The command-reader thread sees EOF, closes all Qt windows, and quits the Qt event
-the event queue.
+loop. This replaces the former shared-memory alive and alive-ack queues.
 
-Events are retrieved explicitly by polling.
+If stdout closes unexpectedly, Racket marks all handles invalid and delivers an
+exception to every command still waiting for a result.
 
-Each event contains a name, an identifier, and optional fields depending on its
+@section[#:tag "rktwebviewqt-internals-logging"]{Logging}
-type. Events are delivered in FIFO order.
 
-@section{Contexts and Webviews}
+The Qt backend writes its existing log messages to stderr. Racket forwards that
+stream to its current error port. The @racket[rkt-webview-info] result reports
+@tt{"stderr"} as the backend log destination and retains zero-valued
+shared-memory metrics for compatibility with callers that display those fields.
 
-The backend uses a two-level model consisting of contexts and webviews.
+@section[#:tag "rktwebviewqt-internals-development-override"]{Development Override}
 
-A context represents a browser environment and corresponds to a
+Setting @tt{RKT_WEBVIEW_PRG} to a backend executable bypasses the installed
-@tt{QWebEngineProfile}. It defines how pages run, including injected scripts and optional trust configuration using explicitly trusted self-signed certificates.
+release directory. This makes it possible to test a newly compiled backend
-
+without repackaging or changing the downloader first.
-Each context is identified by an integer handle.
-
-Within a context, one or more webviews can be created. A webview represents a
-window containing a browser view. Webviews are also identified by integer
-handles.
-
-A webview always belongs to exactly one context. When creating a webview, the
-context handle must be provided.
-
-Webviews may optionally have a parent webview. If a parent is specified, the
-resulting window is created as a modal child of that parent; otherwise it is
-created as a top-level window.
-
-From the Racket side, this means that a context must be created first. That
-context handle is then used to create webviews, which are subsequently addressed
-through their own handles.
-
-All Qt objects remain internal to the helper process; only these integer handles
-cross the process boundary.
-
-@section{JavaScript Bridge}
-
-Each context installs a small JavaScript bridge into every page, allowing
-JavaScript code to send structured data to the host via:
-
-@centerline{@tt{window.rkt_send_event(obj)}}
-
-The objects are collected and forwarded to the event queue.
-
-@section{Navigation and Window Behavior}
-
-User actions are not always executed immediately; navigation initiated by the
-user may result in a @tt{"navigation-request"} event instead of being followed
-automatically, and closing a window may result in a @tt{"can-close?"} event. The
-Racket side is expected to decide how to handle these situations.
-
-@section{Design Considerations}
-
-@bold{Qt WebEngine lifecycle.}
-Qt WebEngine cannot be safely reinitialized within a single process.
-
-In practice, once a @tt{QApplication} using WebEngine has been started and shut
-down, the WebEngine runtime cannot be started again. This is a known and
-documented limitation (see for example QTBUG-70519, QTBUG-87460,
-QTBUG-145033). The underlying cause is that WebEngine starts internal threads
-and resources that are not fully released, even after application shutdown.
-
-Attempts to reinitialize WebEngine in the same process result in undefined
-behavior, including crashes, hangs, or inconsistent state.
-
-In the DrRacket environment, where components may be restarted under a
-custodian, this makes an in-process design fundamentally unsuitable. Even when
-libraries are loaded and unloaded using @tt{#:custodian}, the WebEngine runtime
-cannot be reset to a clean state.
-
-By moving Qt and WebEngine into a separate process, this limitation is avoided
-entirely: each start of the backend creates a fresh runtime, and terminating the
-helper process guarantees that all associated threads and resources are released
-by the operating system.
-
-@bold{Event loop and threading.}
-Qt requires that GUI operations are performed on the Qt GUI thread.
-
-Instead of attempting to integrate Qt’s event loop with Racket, the design
-isolates Qt completely and runs it in its own process.
-
-Within that process, a worker thread receives commands and forwards them to the
-GUI thread using Qt’s event mechanism (via @tt{postEvent}). The Racket side never
-interacts with Qt objects directly.
-
-@bold{Failure isolation.}
-Qt WebEngine is a large subsystem with its own internal processes (including the
-Chromium-based @tt{QtWebEngineProcess}) and is generally stable in practice.
-
-Running the Qt side in a separate process provides isolation: if the helper
-process terminates, the embedding Racket process remains unaffected and can
-decide how to recover.
-
-@bold{Shared memory communication.}
-The communication pattern consists of commands, results, and events, mapped onto
-shared memory FIFO queues, keeping the model simple and explicit.
-
-@bold{JSON encoding.}
-All payloads are encoded as JSON, providing a natural bridge between JavaScript,
-Qt/C++, and Racket: JavaScript produces JSON natively, Qt maps it to variant
-types, and Racket can decode it easily.
-
-For control commands, payload sizes are small and infrequent, so serialization
-cost is negligible compared to GUI-thread execution and WebEngine processing; for
-dynamic data such as JavaScript results and custom events, JSON is the
-appropriate representation. A binary protocol would reduce overhead but increase
-complexity and reduce inspectability.
-
-@section{Shared Memory Architecture}
-
-Communication between the Racket process and @tt{rktwebview_prg} is implemented
-using a shared memory region. This region serves three purposes at once: it
-stores shared data structures, it provides a simple allocator, and it hosts the
-FIFO queues used for message passing.
-
-At the start of the shared memory block, a small administration area is stored,
-including a pointer to the current end of allocated memory, a list of active
-allocations, a free list, and a fixed slot table. The slot table acts as a
-directory of shared objects; queues are created once, stored in slots, and can be
-retrieved by both processes using only the slot number.
-
-Memory allocation inside the shared block is intentionally simple. Each
-allocation is preceded by a small header containing size information and links
-for a double-linked list. Allocation first attempts to reuse a block from the
-free list; if no suitable block is available, memory is taken from the unused
-tail of the region. Freed blocks are returned to the free list and may later be
-reused. Blocks are not compacted or coalesced. This is not a general-purpose
-heap; it is a small, predictable allocator for queue items and payload strings.
-
-Shared objects are referenced primarily through offsets (via @tt{ShmPlace})
-rather than raw pointers. This makes the layout independent of the virtual
-address at which the shared memory is mapped in each process.
-
-Queues are built directly on top of this allocator. Each queue consists of a
-small header containing the first item, the last item, and a count, followed by a
-linked list of queue items. Each item stores a numeric command or event code, a
-pointer to its payload in shared memory, and links to neighboring items.
-
-Synchronization is split into two layers. A shared lock protects allocator and
-queue metadata, while each queue has its own semaphore indicating whether items
-are available. One mechanism protects the structure; the other tells you whether
-there is anything worth reading.
-
-On POSIX systems such as Linux, shared memory is implemented using
-@tt{shm_open}, @tt{ftruncate}, and @tt{mmap}, with synchronization via named
-POSIX semaphores created using @tt{sem_open}. The owner process initializes these
-objects and removes them again using @tt{shm_unlink} and @tt{sem_unlink}.
-
-On Windows, the same model is implemented using @tt{CreateFileMappingA} and
-@tt{MapViewOfFile} for shared memory, and @tt{CreateSemaphoreA} or
-@tt{OpenSemaphoreA} for synchronization. The design is identical, but the kernel
-objects follow the Windows lifetime model and are released when the last handle
-is closed.
-
-The shared memory region has a fixed size (currently 10MB) and is not resized at
-runtime. Although the use of @tt{ShmPlace} offsets would in principle allow
-relocation, resizing would require coordinated remapping in both processes while
-all activity is paused. The current design therefore treats the region as
-fixed-size and relies on reuse of freed blocks.
-
-This implies that the communication channel is bounded. Payloads such as
-@tt{set_html} or large JavaScript results must fit within the available free
-space in the shared memory block. In practice, the usable limit is somewhat below
-the nominal 10MB due to allocator overhead, queue administration, and concurrent
-messages.
-
-This is a message transport, not an infinite sack of HTML.

scrbl/wv-context.scrbl

@@ -10,12 +10,12 @@
                      "../wv-context.rkt"
                      ))
 
-@title{wv-context}
+@title[#:tag "wv-context"]{wv-context}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/wv-context]
 
-@section{Overview}
+@section[#:tag "wv-context-overview"]{Overview}
 
 The library is organized around two main concepts: contexts and windows.
 

scrbl/wv-dialog.scrbl

@@ -8,7 +8,7 @@
                      "../wv-dialog.rkt"
                      "../wv-window.rkt"))
 
-@title{wv-dialog}
+@title[#:tag "wv-dialog"]{wv-dialog}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/wv-dialog]
@@ -16,18 +16,18 @@
 Dialog-window wrapper built on top of @racket[wv-window%].
 
 This module exports the @racket[wv-dialog%] class. It is a specialized window
-class whose initial size and position are derived from its parent window.
+class whose initial size and position are derived from its parent window. Closing a dialog does not quit the application by default.
 
-@section{Overview}
+@section[#:tag "wv-dialog-overview"]{Overview}
 
 A @racket[wv-dialog%] object is a @racket[wv-window%] that initializes itself as
 a dialog relative to its parent window.
 
 The class inherits the window lifecycle, event handling, navigation, and dialog
 support from @racket[wv-window%]. Its only specialization in the current source
-is the implementation of @racket[init-size].
+is the implementation of @racket[init-size]. A dialog also changes the inherited @racket[quit-on-close] default to @racket[#f].
 
-@section{Class: wv-dialog%}
+@section[#:tag "wv-dialog-class-wv-dialog"]{Class: wv-dialog%}
 
 @defclass[wv-dialog% wv-window% ()]{
 
@@ -37,12 +37,14 @@ The class inherits the fields @racket[parent], @racket[settings],
 @racket[wv-context], @racket[html-path], @racket[x], @racket[y],
 @racket[width], and @racket[height] from @racket[wv-window%].
 
-@defconstructor[()]{
+@defconstructor[([quit-on-close any/c #f])]{
 
 Creates a dialog window.
 
-The constructor does not define additional initialization arguments of its own.
+The inherited @racket[quit-on-close] initialization argument defaults to
-Construction is delegated to @racket[wv-window%] through @racket[super-new].
+@racket[#f] for dialogs. Closing a dialog therefore closes only that dialog and
+does not release @racket[webview-wait-for-quit]. Pass @racket[#t] explicitly
+only when closing this dialog should terminate the application.
 }
 
 @defmethod[(init-size) any/c]{

scrbl/wv-element.scrbl

@@ -10,7 +10,7 @@
                      "../racket-webview.rkt"
                      "../wv-element.rkt"))
 
-@title{wv-element}
+@title[#:tag "wv-element"]{wv-element}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/wv-element]
@@ -22,7 +22,7 @@ represent one DOM element within a @racket[wv-window%] and provide a small
 object-oriented interface for event dispatch, content replacement, CSS class
 manipulation, style access, and attribute access.
 
-@section{Overview}
+@section[#:tag "wv-element-overview"]{Overview}
 
 A @racket[wv-element%] object is associated with:
 
@@ -37,7 +37,7 @@ of its methods therefore follow the contracts of those lower-level functions.
 The class also stores per-element event callbacks used by @racket[wv-window%]
 when dispatching JavaScript events received from the browser.
 
-@section{Class: wv-element%}
+@section[#:tag "wv-element-class-wv-element"]{Class: wv-element%}
 
 @defclass[wv-element% object% ()]{
 

scrbl/wv-input.scrbl

@@ -11,7 +11,7 @@
                      "../wv-input.rkt"
                      "../rgba.rkt"))
 
-@title{wv-input}
+@title[#:tag "wv-input"]{wv-input}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/wv-input]
@@ -22,7 +22,7 @@ This module exports a family of classes derived from @racket[wv-element%]. Each
 class represents one DOM input element and provides a typed @racket[get] method
 together with a @racket[set!] method.
 
-@section{Overview}
+@section[#:tag "wv-input-overview"]{Overview}
 
 All classes in this module inherit from @racket[wv-element%].
 
@@ -39,7 +39,7 @@ lower-level DOM/value API from @racketmodname[racket-webview]. Their accepted
 argument shapes and result values therefore follow the contracts of those
 lower-level functions.
 
-@section{Common Structure}
+@section[#:tag "wv-input-common-structure"]{Common Structure}
 
 All input wrapper classes have the same constructor shape:
 
@@ -56,7 +56,7 @@ Each class provides two public methods:
  @item{@racket[get], returning the current typed value}
  @item{@racket[set!], writing a new value through @racket[webview-set-value!]}]
 
-@section{Class: wv-input/text%}
+@section[#:tag "wv-input-class-wv-input-text"]{Class: wv-input/text%}
 
 @defclass[wv-input/text% wv-element% ()]{
 
@@ -89,7 +89,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/number%}
+@section[#:tag "wv-input-class-wv-input-number"]{Class: wv-input/number%}
 
 @defclass[wv-input/number% wv-element% ()]{
 
@@ -122,7 +122,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/boolean%}
+@section[#:tag "wv-input-class-wv-input-boolean"]{Class: wv-input/boolean%}
 
 @defclass[wv-input/boolean% wv-element% ()]{
 
@@ -155,7 +155,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/date%}
+@section[#:tag "wv-input-class-wv-input-date"]{Class: wv-input/date%}
 
 @defclass[wv-input/date% wv-element% ()]{
 
@@ -188,7 +188,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/time%}
+@section[#:tag "wv-input-class-wv-input-time"]{Class: wv-input/time%}
 
 @defclass[wv-input/time% wv-element% ()]{
 
@@ -221,7 +221,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/datetime%}
+@section[#:tag "wv-input-class-wv-input-datetime"]{Class: wv-input/datetime%}
 
 @defclass[wv-input/datetime% wv-element% ()]{
 
@@ -254,7 +254,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/range%}
+@section[#:tag "wv-input-class-wv-input-range"]{Class: wv-input/range%}
 
 @defclass[wv-input/range% wv-element% ()]{
 
@@ -287,7 +287,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/check%}
+@section[#:tag "wv-input-class-wv-input-check"]{Class: wv-input/check%}
 
 @defclass[wv-input/check% wv-element% ()]{
 
@@ -320,7 +320,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/radio%}
+@section[#:tag "wv-input-class-wv-input-radio"]{Class: wv-input/radio%}
 
 @defclass[wv-input/radio% wv-element% ()]{
 
@@ -353,7 +353,7 @@ Writes @racket[v] by delegating to:
 }
 }
 
-@section{Class: wv-input/color%}
+@section[#:tag "wv-input-class-wv-input-color"]{Class: wv-input/color%}
 
 @defclass[wv-input/color% wv-element% ()]{
 

scrbl/wv-settings.scrbl

@@ -9,7 +9,7 @@
                      racket/file
                      "../wv-settings.rkt"))
 
-@title{wv-settings}
+@title[#:tag "wv-settings"]{wv-settings}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/wv-settings]
@@ -20,7 +20,7 @@ This module exports the @racket[wv-settings%] class, which provides a small
 object-oriented interface over an @racket[ini] settings backend. Settings are
 accessed relative to a context.
 
-@section{Overview}
+@section[#:tag "wv-settings-overview"]{Overview}
 
 A @racket[wv-settings%] object combines:
 
@@ -30,7 +30,7 @@ A @racket[wv-settings%] object combines:
 
 Keys used in this class are symbols.
 
-@section{Class: wv-settings%}
+@section[#:tag "wv-settings-class-wv-settings"]{Class: wv-settings%}
 
 @defclass[wv-settings% object% ()]{
 

scrbl/wv-tray.scrbl

@@ -6,7 +6,7 @@
                      "../wv-tray.rkt"
                      "../menu.rkt"))
 
-@title{Tray Icons}
+@title[#:tag "wv-tray"]{Tray Icons}
 
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 

scrbl/wv-window.scrbl

@@ -15,7 +15,7 @@
                      "../rgba.rkt"
                      "../wv-window.rkt"))
 
-@title{wv-window}
+@title[#:tag "wv-window"]{wv-window}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
 @defmodule[racket-webview/wv-window]
@@ -26,7 +26,7 @@ This module exports the @racket[wv-window%] class and re-exports the APIs from
 @racketmodname[wv-element], @racketmodname[wv-input], @racketmodname[rgba], and
 @racketmodname[wv-settings].
 
-@section{Overview}
+@section[#:tag "wv-window-overview"]{Overview}
 
 A @racket[wv-window%] object represents one webview window.
 
@@ -37,7 +37,7 @@ element wrappers through @racket[element].
 The class also provides synchronous wrappers around the asynchronous dialog
 interface by using continuations internally.
 
-@section{Class: wv-window%}
+@section[#:tag "wv-window-class-wv-window"]{Class: wv-window%}
 
 @defclass[wv-window% object% ()]{
 
@@ -478,7 +478,7 @@ The resulting geometry is then applied through @racket[move] and @racket[resize]
 }
 }
 
-@section{Events}
+@section[#:tag "wv-window-events"]{Events}
 
 The window installs an internal event handler when it is created.
 
@@ -499,7 +499,7 @@ This handler reacts to the following event kinds produced by the lower layer:
 
 Unhandled events are printed to the console by the current implementation.
 
-@section{Function: root-file-not-found-handler}
+@section[#:tag "wv-window-function-root-file-not-found-handler"]{Function: root-file-not-found-handler}
 
 @defproc[(root-file-not-found-handler [standard-file string?]
                                       [not-found-handler procedure?] ...)
@@ -527,7 +527,7 @@ Its behavior is as follows:
 Only the first optional @racket[not-found-handler] is used.
 }
 
-@section{Re-exports}
+@section[#:tag "wv-window-re-exports"]{Re-exports}
 
 This module also re-exports the public APIs from:
 

wv-dialog.rkt

@@ -14,9 +14,10 @@
 
 (define wv-dialog%
   (class wv-window%
+    (init [quit-on-close #f])
     (inherit-field parent settings wv-context html-path x y width height)
     
-    (super-new)
+    (super-new [quit-on-close quit-on-close])
 
     (define/override (init-size)
       (dbg-webview "init-size")

wv-element.rkt

@@ -53,11 +53,11 @@
         (let ((d* (string->symbol (format "~a" (car d)))))
           (webview-set-style! wv element-id (list 'display d*))))
       (let ((style-hash (webview-get-style wv element-id 'display)))
-        (displ "style-hash: ") (write style-hash) (newline)
+        ;(displ "style-hash: ") (write style-hash) (newline)
         (let ((display-style (hash-ref (if (eq? style-hash #f)
                                            (make-hash)
                                            style-hash) 'display #f)))
-          (displayln display-style)
+          ;(displayln display-style)
           (if (eq? display-style #f)
               #f
               (string->symbol display-style)))))