BrowserSm

A Squeak Smalltalk Virtual Machine for Web Browsers

View on GitHub Live Demo Get Started

Constitution

BrowserSm Constitution

Ratified: 2026-02-25 Version: 1.6 Status: Active Governance: Constitution supersedes all other project documents. Amendments require documented rationale, review, and migration plan.

Preamble

BrowserSm is a web browser implemented in Squeak Smalltalk 6.0, deployed via BSvm — a JavaScript-based Smalltalk interpreter that runs the Squeak image in web browsers and on the desktop. This constitution establishes the non-negotiable principles that govern every specification, plan, and line of code in the project. It is rooted in the design philosophy of Smalltalk as articulated by Dan Ingalls — personal mastery, uniform metaphor, modularity, factoring, and the reactive principle — and extends those values into the domain of web standards implementation.

The project has two layers with a strict abstraction boundary between them:

  • The Smalltalk Image (Articles I–XII): BrowserSm — a pure Smalltalk web browser application. All browser logic is idiomatic Squeak Smalltalk running in a standard Squeak 6.0 image. The image is VM-agnostic: it runs identically on BSvm, Cog, or any Squeak-compatible VM.
  • The VM (Article XIII): BSvm — a minimal JavaScript implementation of the Squeak bytecode interpreter. It maps Smalltalk’s “native assembly” (bytecodes and primitives) to JavaScript and host platform APIs. BSvm is specified in VM_SPECIFICATION.md.

The purpose of this document is to ensure that BrowserSm is built to the same standard of rigor and internal consistency that defines Squeak itself: a system comprehensible to a single individual, where every component can present itself meaningfully for observation and manipulation.

Article I — Smalltalk-Native Principle

All implementation MUST be idiomatic Squeak Smalltalk. The entire system — including the presentation tier — is native Smalltalk executed in the Squeak interpreter.

  1. Classes use BS prefix for namespace isolation (e.g., BSBrowser, BSDOMNode).
  2. Method selectors follow Smalltalk conventions: camelCase, keyword messages with colons, accessors named after their instance variables.
  3. Protocol categories follow standard Squeak organization: accessing, initialization, testing, private, printing, events, actions.
  4. No external language runtimes shall exist in the system. There is no JavaScript engine, no Node.js process, no IPC bridge, no transpilation layer. All code — browser chrome, page rendering, and web page scripting — compiles and executes natively in the Squeak Smalltalk interpreter. Turtles all the way down.
  5. The system SHALL be fully functional when loaded into a stock Squeak 6.0 image and SHALL NOT depend on external processes. For browser deployment, the image MAY be stripped to include only BrowserSm and its dependencies (see VM_SPECIFICATION.md §18.3), but the unstripped system MUST remain loadable and functional in a full Squeak 6.0 image for development and debugging.
  6. Every object MUST be inspectable. The Reactive Principle applies: any BrowserSm component accessible to the user must be able to present itself in a meaningful way for observation and manipulation via standard Squeak tools (Inspector, Explorer, Debugger).
  7. The browser’s own user interface (window chrome, toolbar, address bar, viewport, developer tools, dialogs) MUST be implemented entirely in Morphic — Squeak’s native UI framework. No web framework (React, Angular, etc.), no HTML/CSS-based UI toolkit, and no external rendering library shall be used for the browser’s presentation tier. The browser renders web content TO Morphic; it does not render THROUGH a web stack.
  8. All browser UI logic — event handling, layout of chrome elements, status updates, tab management, developer tools panels — executes as native Smalltalk message sends within the Squeak interpreter’s process scheduler. No transpilation, no foreign runtime, no embedded browser engine.
  9. The Morphic presentation tier SHALL leverage Squeak’s live object system: every UI component is a live Morph subclass that can be inspected, modified, and debugged at runtime using standard Squeak development tools (Inspector, Explorer, Debugger, halos).

Article II — Standards-Referential Development

Every implemented feature MUST trace to a published specification.

  1. HTML features trace to the WHATWG HTML Living Standard.
  2. CSS features trace to the W3C CSS Snapshot 2025 and the specific CSS module specifications therein.
  3. DOM features trace to the WHATWG DOM Living Standard.
  4. Web APIs (Fetch, Storage, URL, Console, etc.) trace to their respective W3C/WHATWG specifications. These APIs are implemented in native Smalltalk — no JavaScript engine is involved.
  5. Each requirement in the requirements specification MUST include a [Spec-Ref] citation to the authoritative section of the relevant standard.
  6. Where BrowserSm intentionally deviates from or subsets a standard, the deviation MUST be documented with rationale in the requirements specification under a [Deviation] marker.
  7. The Smalltalk script runtime (sandboxed evaluation of web page <script> elements) has no external standard; its specification IS the BrowserSm requirements document, and it MUST document its semantics with the same rigor as if it were a W3C specification.

Article III — Architectural Purity

Clean separation of concerns with explicit interfaces.

  1. DOM/CSS/HTML Separation: Each subsystem SHALL be independently testable and SHALL NOT directly access internals of other subsystems.
  2. Resource Loading: Network I/O, file I/O, and image loading SHALL be factored into a separate BSResourceLoader subsystem with a clean async interface.
  3. Rendering Pipeline: HTML parsing → DOM construction → CSS application → layout → painting → display SHALL be explicit pipeline stages with defined inputs and outputs.
  4. Error Isolation: Parse errors, script errors, network errors, and rendering errors SHALL be contained within their respective subsystems and SHALL NOT crash the browser.
  5. Plugin Architecture: Extension points SHALL be explicitly designed with documented protocols, not ad-hoc hooks.

Article IV — Web Standards Compliance

Implement web standards correctly or not at all.

  1. No Partial Implementations: If a CSS property is implemented, it MUST handle all defined values and edge cases. If an HTML element is implemented, it MUST support all standard attributes and behaviors.
  2. Error Handling: Error recovery MUST follow the relevant specification (e.g., HTML5 parsing error recovery, CSS invalid value handling).
  3. Compatibility: When standards conflict or are ambiguous, BrowserSm SHALL follow the behavior of the most recent Chrome/Firefox consensus.
  4. Documentation: Each implemented feature MUST document its compliance level: “Full”, “Partial” (with list of missing features), or “Planned”.
  5. Testing: Compliance SHALL be verified against official test suites where available (HTML5 test suite, CSS test suite, etc.).

Article V — Performance by Design

Performance is an architectural concern, not an afterthought.

  1. Incremental Algorithms: HTML parsing, CSS application, and layout algorithms SHALL be designed for incremental operation. Adding one DOM node SHOULD NOT require re-parsing the entire document.
  2. Caching: Parsed CSS, computed styles, and layout results SHALL be cached and invalidated surgically.
  3. Lazy Evaluation: Resources (images, stylesheets, scripts) SHALL be loaded on demand, not eagerly.
  4. Memory Management: Object graphs MUST be designed to avoid memory leaks. Circular references between DOM nodes, CSS rules, and layout objects MUST be broken explicitly.
  5. Measurement: Performance-critical paths MUST be instrumented with measurement tools. “I think this is fast” is not acceptable.

Article VI — Developer Experience

The system MUST be a joy to debug and extend.

  1. Inspectable State: Every major object (BSBrowser, BSDOMDocument, BSCSSStylesheet) MUST have meaningful inspect and printOn: implementations.
  2. Error Messages: Error messages MUST be actionable. “Syntax error” is not acceptable; “Expected semicolon after property value ‘red’ on line 23” is.
  3. Debugging Tools: BrowserSm SHALL provide native Smalltalk debugging tools: DOM inspector, CSS debugger, script debugger, performance profiler.
  4. Live Modification: It MUST be possible to modify CSS, HTML, and script behavior at runtime using standard Squeak tools.
  5. Documentation: Every public class and method MUST have clear documentation explaining its purpose, parameters, and usage.

Article VII — Code Quality Standards

Code quality is non-negotiable.

  1. Method Length: Methods SHALL NOT exceed 25 lines. Complex logic MUST be factored into smaller, named methods.
  2. Class Responsibility: Classes SHALL have a single, clear responsibility. “Utility” classes and “Manager” classes are code smells.
  3. Naming: Class and method names MUST be self-documenting. Abbreviations are discouraged except for well-established conventions (HTML, CSS, DOM, URL).
  4. Comments: Code SHOULD be self-documenting. Comments SHOULD explain “why”, not “what”. If you need a comment to explain what code does, refactor the code.
  5. Testing: Every public method MUST have unit tests. Complex algorithms MUST have comprehensive test suites with edge cases.

Article VIII — Resource Management

Efficient use of system resources is mandatory.

  1. Memory Limits: BrowserSm SHALL impose reasonable limits on DOM tree size, CSS rule count, and script execution memory.
  2. CPU Limits: Long-running operations (parsing large documents, complex layout) MUST be interruptible and SHOULD yield control to the UI.
  3. Network Efficiency: HTTP requests MUST be optimized: connection pooling, compression, appropriate caching headers.
  4. Storage: Local storage, cookies, and cache SHALL respect user privacy and storage quotas.
  5. Battery Life: On mobile deployments, BrowserSm SHOULD minimize battery usage through efficient rendering and network usage.

Article IX — Security Model

Security MUST be designed in, not bolted on.

  1. Sandbox Isolation: Web page scripts execute in a capability-based sandbox with no access to the file system, network, or other web pages.
  2. XSS Prevention: All user content MUST be properly escaped when rendered. HTML injection MUST be impossible.
  3. CSRF Protection: Cross-origin requests MUST be subject to same-origin policy enforcement.
  4. Content Security Policy: BrowserSm SHOULD support CSP headers for additional protection.
  5. Privacy: BrowserSm SHALL NOT track users, collect analytics, or send data to third parties without explicit user consent.

Article X — Compatibility Strategy

Be compatible where it matters, innovative where it doesn’t.

  1. Core Standards: HTML5, CSS3, and DOM MUST be implemented to specification.
  2. JavaScript Alternative: Web page scripts are Smalltalk, not JavaScript. This is a deliberate architectural choice.
  3. Legacy Support: BrowserSm MAY choose not to support obsolete web standards (Flash, Java applets, IE6 quirks).
  4. Progressive Enhancement: BrowserSm SHOULD gracefully degrade when encountering unsupported features.
  5. User Agent: BrowserSm SHOULD identify itself honestly in HTTP headers and navigator.userAgent.

Article XI — Deployment Architecture

Support multiple deployment scenarios without compromising the core.

  1. Desktop Squeak: BrowserSm MUST run in a standard Squeak desktop image for development and debugging.
  2. Web Deployment: BrowserSm MUST run in web browsers via BSvm with identical functionality.
  3. Mobile Deployment: BrowserSm MAY be adapted for mobile platforms while maintaining architectural integrity.
  4. Server-Side: BrowserSm components MAY be used server-side for HTML/CSS processing without modification.
  5. Embedding: BrowserSm MAY be embedded in other Squeak applications as a web content component.

Article XII — Scripting Runtime

Web page scripts execute as sandboxed Smalltalk within the Squeak interpreter.

  1. Language: Web pages use <script type="text/smalltalk"> for embedded scripting. JavaScript is not supported.
  2. Sandbox: Script execution is confined to a capability-based sandbox with restricted class access.
  3. DOM Access: Scripts access the DOM through the same BSdom* objects used by the browser itself.
  4. Web APIs: Scripts access web APIs (localStorage, fetch, console) through Smalltalk objects, not JavaScript globals.
  5. Error Handling: Script errors are caught at the sandbox boundary and do not crash the browser.
  6. Performance: Script execution is subject to time limits and resource quotas.
  7. Security: Scripts cannot access the file system, network (except through controlled APIs), or other web pages.

Article XIII — Virtual Machine Specification

BSvm provides the minimal substrate needed to run Squeak in JavaScript environments.

  1. Scope: BSvm implements only the Squeak bytecode interpreter and object memory. All browser logic remains in the Smalltalk image.
  2. Specification: BSvm is fully specified in VM_SPECIFICATION.md and MUST NOT deviate from that specification.
  3. Platform Mapping: BSvm maps Squeak primitives to JavaScript/Web APIs but does not add new primitives.
  4. Performance: BSvm SHOULD be optimized for modern JavaScript engines but MUST NOT sacrifice correctness for speed.
  5. Debugging: BSvm SHOULD provide debugging hooks for inspecting Smalltalk state from browser developer tools.
  6. Standards: BSvm SHOULD use modern JavaScript features (ES6+) and web standards (WebGL, WebAssembly where appropriate).

Article XIV — Version Management

Changes are governed by semantic versioning and compatibility guarantees.

  1. Semantic Versioning: BrowserSm follows semver: MAJOR.MINOR.PATCH.
  2. API Stability: Public APIs (class interfaces, method signatures) are stable within major versions.
  3. Web Standards: Support for new web standards is added in minor versions.
  4. Breaking Changes: Breaking changes require major version bumps and migration guides.
  5. Deprecation: Features are deprecated for at least one major version before removal.
  6. Image Format: The BrowserSm image format is versioned independently and MUST be loadable by compatible BSvm versions.

Article XV — Quality Assurance

Quality is verified through automated testing and continuous integration.

  1. Test Coverage: All public methods MUST have unit tests. Critical paths MUST have integration tests.
  2. Regression Tests: Bug fixes MUST include regression tests to prevent reoccurrence.
  3. Performance Tests: Performance-critical code MUST have benchmark tests with defined acceptance criteria.
  4. Compatibility Tests: New features MUST be tested against the web standards test suites.
  5. Cross-Platform: Tests MUST pass on both desktop Squeak and BSvm deployments.
  6. Continuous Integration: All tests MUST pass before code is merged to the main branch.

Article XVI — Documentation Standards

Documentation is part of the implementation, not an afterthought.

  1. Class Documentation: Every class MUST have a class comment explaining its purpose and usage.
  2. Method Documentation: Public methods MUST have method comments explaining parameters and return values.
  3. Architecture Documentation: System architecture MUST be documented with diagrams and explanations.
  4. User Documentation: End-user features MUST have user documentation with examples.
  5. Specifications: All requirements MUST be documented with traceability to web standards.
  6. Change Log: All changes MUST be documented in the project change log.

Article XVII — Community and Governance

The project is governed transparently with clear contribution guidelines.

  1. Open Source: BrowserSm is open source under the MIT license.
  2. Contribution Guidelines: Contributors MUST follow the contribution guidelines and code of conduct.
  3. Code Review: All code changes MUST be reviewed by at least one maintainer.
  4. Decision Making: Technical decisions are made transparently with documented rationale.
  5. Community Standards: The project maintains professional, inclusive community standards.
  6. Maintenance: The project has designated maintainers responsible for ongoing development and support.

Article XVIII — Amendment Process

This constitution can be amended through a defined process.

  1. Proposal: Constitutional amendments MUST be proposed with detailed rationale and impact analysis.
  2. Review: Amendments MUST be reviewed by the project maintainers and community.
  3. Migration Plan: Breaking amendments MUST include a migration plan for existing code.
  4. Documentation: Amendments MUST be documented with version history and effective dates.
  5. Grandfathering: Existing code has a grace period to comply with new constitutional requirements.

This constitution ensures that BrowserSm maintains architectural integrity while growing in capability and adoption. It embodies the Smalltalk values of transparency, simplicity, and power.

© 2026 BrowserSm Project. Source Code | Issues | License