GUI HTML/CSS Embedded browser

# BrowserWidget

`BrowserWidget` renders local, generated, or remote HTML content inside a Klyn window. It provides asynchronous navigation, history, CSS layout, images, scrolling, page zoom, and a deterministic DOM scripting profile without adding a third-party browser runtime.

Native Embedded Rendering

The widget uses the regular Klyn painting backend. HTML parsing, CSS resolution, and layout produce a retained display list, so scrolling and ordinary repaint operations do not parse or lay out the document again.

BrowserWidget rendering the same reference page used for browser comparison. Click the image to inspect it at full size.
Loading Content

Import `klyn.gui.windows.browser` explicitly. The constructor accepts an initial URL, while `navigateToString` is useful for generated reports, help pages, and previews.

    import klyn.gui.windows
    import klyn.gui.windows.browser
    import klyn.gui.windows.layouts

    window = MainWindow("Documentation")
    window.size = (1000, 700)

    browser = BrowserWidget("file:///opt/klyn/docs/api/index.html")
    browser.layoutParams = DockLayoutParams("fill")

    window.centralWidget.layout = DockLayout(spacing=0)
    (window.centralWidget.layout as DockLayout).add(browser, "fill")
    window.run()

    browser.navigateToString(
        "<h1>Build completed</h1><p>No errors found.</p>",
        "about:build-report"
    )

Supported locations include `file:`, `http:`, `https:`, `data:`, `about:`, local paths, and relative links resolved against the current document URL.

Navigation and History

Browser chrome is intentionally separate from the document widget. Applications can build the exact toolbar they need with the navigation API and observe the typed navigation events.

    browser.homeUrl = "file:///opt/klyn/docs/index.html"
    browser.navigated += lambda(event: BrowserNavigationEvent): print(event.url)
    browser.navigationFailed += lambda(event: BrowserNavigationErrorEvent): print(event.message)

    browser.navigate("https://klyn.deepcodia.fr/")
    if browser.canGoBack:
        browser.goBack()

    for entry in browser.history.entries():
        print(entry.title + " - " + entry.url)

Use `goForward`, `refresh`, `stop`, and `goHome` for their usual browser actions. Assigning `url` starts the same asynchronous navigation as `navigate`.

Maintainable Browser Architecture

The implementation is split into independent packages so future browser work does not turn the widget into a monolith:

- `klyn.gui.windows.browser`: public widget, navigation events, and history.
- `browser.resources`: URI resolution and asynchronous page/resource loading.
- `browser.dom`: tolerant HTML tokenization and document tree.
- `browser.css`: stylesheet parsing, selectors, inheritance, variables, and cascade.
- `browser.layout`: block, inline, flex, table, image layout, and retained display list.
- `browser.scripting`: isolated deterministic DOM script execution.

Deterministic DOM Scripting

`allowScripts` controls inline and external scripts. The built-in profile is intended for desktop help, reports, and documentation: title/location assignments, text or HTML updates, inline style changes, and `classList` mutations. It deliberately does not expose host process or filesystem APIs to page scripts.

    browser.allowScripts = true
    browser.executeScript("document.getElementById('status').textContent = 'Ready';")
    value = browser.executeScript("return document.title;")

Zoom and Scrolling

Set `zoomFactor` for page-specific zoom. The global GUI content zoom remains active in addition to this value. Keyboard and mouse-wheel scrolling use the retained layout.

    browser.zoomFactor = 1.25
    browser.scrollTo(0, 500)
    browser.scrollBy(0, 120)

Run the Sample

    klyn samples/gui/BrowserWidgetSample.kn

Next Step

Continue with Canvas and Custom Painting, or use DockWorkspace to host browser-based documentation in a larger desktop application.