BrowserSm

A Squeak Smalltalk Virtual Machine for Web Browsers

View on GitHub Live Demo Get Started

User Guide

BrowserSm User Guide

This guide covers using BrowserSm as both a Squeak development environment and as a web browsing application.

Table of Contents

  1. Getting Started
  2. The Squeak Environment
  3. Using the Browser Application
  4. Development Workflow
  5. Browser Features
  6. Troubleshooting

Getting Started

Launching BrowserSm

Visit https://pauljbernard.github.io/browsersm/demo/ to launch BrowserSm directly in your browser.

Local Development

1
2
3
4

git clone https://github.com/pauljbernard/browsersm.git
cd browsersm
python3 -m http.server 8080
# Visit: http://localhost:8080/vm/index.html

First Launch

When BrowserSm starts, you’ll see:

  1. Boot Process: The VM loads the Squeak image (may take 10-30 seconds)
  2. Squeak Desktop: Familiar Squeak environment with windows and tools
  3. Browser Application: The reference web browser opens automatically

The Squeak Environment

BrowserSm provides a complete Squeak development environment in your browser:

Core Tools

System Browser

Browse and edit all Smalltalk code:

1

World menu → Tools → Browser
  • View class hierarchies
  • Edit methods with syntax highlighting
  • Compile and test code changes instantly

Inspector

Examine any object in detail:

1
2
3
4
5
6
7

"Inspect any object"
object inspect.

"Examples"
Date today inspect.
World inspect.
Browser new inspect.

Workspace

Execute arbitrary Smalltalk code:

1

World menu → Tools → Workspace

Example workspace expressions:

1
2
3
4
5
6
7
8
9
10

"Basic arithmetic"
2 + 3.

"Create objects"
browser := BSBrowser new.
browser open.

"Explore the system"
Smalltalk allClasses size.
Transcript show: 'Hello, World!'; cr.

Debugger

Debug code with full stepping and inspection:

  • Set breakpoints in methods
  • Step through execution
  • Inspect variables and stack frames
  • Modify code during debugging

System Navigation

World Menu

Right-click anywhere to access:

  • Tools: Browser, Workspace, Inspector, Process Browser
  • Applications: Browser, Games, Utilities
  • System: Preferences, Updates, Help

Window Management

  • Drag: Move windows by title bars
  • Resize: Drag window corners/edges
  • Collapse: Click window collapse button
  • Close: Click window close button (X)

Using the Browser Application

Basic Navigation

The BrowserSm web browser provides standard browsing capabilities:

Address Bar

1
2
3

Type URLs and press Enter:
https://example.com
file:///local/path/page.html
  • Back: Return to previous page
  • Forward: Go to next page
  • Reload: Refresh current page
  • Home: Return to start page

Tab Management

  • New Tab: Cmd/Ctrl+T or click + button
  • Close Tab: Click X on tab or Cmd/Ctrl+W
  • Switch Tabs: Click tab or Cmd/Ctrl+1-9

Advanced Features

Developer Tools

Access powerful debugging tools:

1

Browser menu → Developer → Open Inspector

DOM Inspector:

  • View HTML structure as live objects
  • Inspect DOM nodes and properties
  • Modify attributes and content

CSS Debugger:

  • Examine computed styles
  • View CSS rules and specificity
  • Test style changes interactively

Smalltalk Script Console:

  • Execute Smalltalk scripts in page context
  • Access DOM through BSdom* objects
  • Debug script execution

Script Debugging

Web pages can include Smalltalk scripts:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!DOCTYPE html>
<html>
<body>
    <button id="myButton">Click me</button>

    <script type="text/smalltalk">
        "Smalltalk script - not JavaScript!"
        button := document getElementById: 'myButton'.
        button addEventListener: 'click' handler: [
            button setAttribute: 'style' value: 'background-color: red'.
            console log: 'Button clicked!'.
        ].
    </script>
</body>
</html>

Page Source Viewer

1

Browser menu → View → Source
  • View HTML source as parsed DOM
  • Inspect element relationships
  • See computed styles and layout

Development Workflow

Creating Browser Extensions

Extend the browser with custom Smalltalk code:

Custom Element Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

"Define a custom HTML element"
BSDOMElement subclass: #MyCustomButton
    instanceVariableNames: 'clickCount'
    classVariableNames: ''
    poolDictionaries: ''
    category: 'MyExtensions'.

MyCustomButton>>initialize
    super initialize.
    self tagName: 'my-button'.
    clickCount := 0.
    self addEventListener: 'click' handler: [ self handleClick ].

MyCustomButton>>handleClick
    clickCount := clickCount + 1.
    self textContent: 'Clicked ', clickCount printString, ' times'.

"Register the element"
BSHTMLParser registerCustomElement: 'my-button' class: MyCustomButton.

Browser Plugin Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

"Create a browser plugin"
Object subclass: #MyAdBlocker
    instanceVariableNames: 'blockedDomains'
    classVariableNames: ''
    poolDictionaries: ''
    category: 'MyExtensions'.

MyAdBlocker>>initialize
    super initialize.
    blockedDomains := Set new.
    blockedDomains add: 'ads.example.com'.

    "Register with browser"
    BSBrowser default addPlugin: self.

MyAdBlocker>>shouldBlockURL: url
    ^ blockedDomains anySatisfy: [ :domain |
        url includesSubstring: domain ].

MyAdBlocker>>processRequest: request
    ^ (self shouldBlockURL: request url)
        ifTrue: [ nil "Block request" ]
        ifFalse: [ request "Allow request" ].

Testing and Debugging

Unit Testing

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

"Create test cases"
TestCase subclass: #MyBrowserTest
    instanceVariableNames: 'browser'
    classVariableNames: ''
    poolDictionaries: ''
    category: 'MyExtensions-Tests'.

MyBrowserTest>>setUp
    browser := BSBrowser new.

MyBrowserTest>>testBasicNavigation
    browser navigateTo: 'https://example.com'.
    self assert: browser currentURL equals: 'https://example.com'.

MyBrowserTest>>testDOMManipulation
    browser loadHTML: '<div id="test">Hello</div>'.
    element := browser currentPage document getElementById: 'test'.
    self assert: element textContent equals: 'Hello'.

Live Debugging

1
2
3
4
5
6
7
8
9
10

"Debug running browser"
browser := BSBrowser allInstances first.
browser inspect.  "Examine browser state"

"Debug current page"
page := browser currentPage.
page document inspect.  "Examine DOM"

"Debug CSS engine"
browser cssProcessor inspect.

Browser Features

Web Standards Support

HTML5

  • Semantic elements (article, section, nav, etc.)
  • Form elements and validation
  • Media elements (audio, video)
  • Canvas and SVG graphics

CSS3

  • Flexbox layout
  • Transitions and animations
  • Media queries
  • Advanced selectors

Web APIs

  • DOM manipulation
  • Local Storage
  • Fetch API (HTTP requests)
  • Console logging

Smalltalk Scripting

Unlike traditional browsers, BrowserSm executes Smalltalk scripts instead of JavaScript:

Basic Scripting

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<script type="text/smalltalk">
    "Access DOM elements"
    element := document getElementById: 'myElement'.
    element textContent: 'Updated from Smalltalk!'.

    "Use web APIs"
    localStorage setItem: 'greeting' value: 'Hello, Smalltalk!'.
    console log: (localStorage getItem: 'greeting').

    "Make HTTP requests"
    fetch url: 'https://api.example.com/data'
        then: [ :response | console log: response ]
        catch: [ :error | console error: error ].
</script>

Event Handling

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<script type="text/smalltalk">
    "Add event listeners"
    buttons := document querySelectorAll: 'button'.
    buttons do: [ :button |
        button addEventListener: 'click' handler: [
            button style setProperty: 'background-color' value: 'blue'.
        ].
    ].

    "Custom event dispatching"
    customEvent := document createEvent: 'CustomEvent'.
    customEvent initCustomEvent: 'myEvent' bubbles: true detail: 'data'.
    document dispatchEvent: customEvent.
</script>

Performance Monitoring

Browser Performance

1
2
3
4
5

"Check browser performance"
stats := browser performanceStats.
Transcript show: 'Pages loaded: ', stats pagesLoaded printString; cr.
Transcript show: 'Memory usage: ', stats memoryUsage printString; cr.
Transcript show: 'Render time: ', stats averageRenderTime printString; cr.

VM Performance

1
2
3
4
5

"Check VM performance"
vmStats := SmalltalkVM current performanceStats.
Transcript show: 'Bytecodes executed: ', vmStats bytecodesExecuted printString; cr.
Transcript show: 'GC time: ', vmStats gcTime printString; cr.
Transcript show: 'Memory allocated: ', vmStats memoryAllocated printString; cr.

Troubleshooting

Common Issues

Browser Won’t Load Page

1
2
3
4
5
6
7
8

"Check network connectivity"
BSResourceLoader default testConnection: 'https://example.com'.

"Clear cache"
browser clearCache.

"Reset browser state"
browser reset.

Slow Performance

1
2
3
4
5
6
7
8

"Enable performance optimizations"
BSConfiguration default
    enableDisplayListCaching: true;
    enableIncrementalLayout: true;
    maxCachedResources: 50.

"Trigger garbage collection"
Smalltalk garbageCollect.

Script Errors

1
2
3
4
5
6
7

"Check script sandbox settings"
BSScriptRuntime default
    timeout; "Current timeout"
    whitelistedClasses; "Available classes"

"Enable script debugging"
BSScriptRuntime default enableDebugging: true.

Debugging Tools

System Browser

Examine all BrowserSm code:

1

Browser → BSBrowser → browse

Process Browser

Monitor system processes:

1

World menu → System → Process Browser

Object Inspectors

1
2
3
4

"Inspect key objects"
BSBrowser default inspect.
BSResourceLoader default inspect.
BSScriptRuntime default inspect.

Getting Help

BrowserSm brings the power of live Smalltalk development to web browsing. Every component is inspectable, every behavior is modifiable, and every problem has a Smalltalk solution.

© 2026 BrowserSm Project. Source Code | Issues | License