brut 0.0.28 → 0.1.0

data/brutrb.com/getting-started.md

@@ -83,25 +83,24 @@ Docker container for local observability via OpenTelemetry.
    ```
    > dx/start
    ```
-4. Now, "log in" to the container where your app and its tests will run:
+4. Now, install your aps gems and set it all up:
 
    ```
-   > dx/exec login
-   ```
-
-5. Set everything up:
-
-   ```
-   inside-container> bin/setup
+   > dx/exec bin/setup
    ```
 
 Now, you're ready to go.  See [Dev Environemnt](/dev-environment) for details on how
 this all works.
 
+> [!NOTE]
+> Instead of running `dx/exec` in front of your commands, you
+> can instead do `dx/exec bash` to "log in" to the running container.
+> You'll have a normal prompt and can issue commands directly from there.
+
 ## Run the App
 
 ```
-inside-container> bin/dev
+dx/exec bin/dev
 ```
 
 You can now visit your app at `localhost:6502`
@@ -128,10 +127,10 @@ There are a few tests you can run, as well as some checks that you aren't using
 RubyGems with security vulnerabilities.  Run it all now with `bin/ci`:
 
 ```
-inside-container> bin/dev
+dx/exec bin/ci
 ```
 
 ## Now Build The Rest of Your App 🦉
 
-You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the API docs.  You might also want to check out the docs for [LSP Support](/lsp).
+You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the [API docs](/api/index.html).  You might also want to check out the docs for [LSP Support](/lsp).
 

data/brutrb.com/handlers.md

@@ -6,137 +6,161 @@ Handlers process form submissions, and *actions* work similarly to process any a
 
 Where a [page](/pages) renders a web page in HTML, a *handler* responds to all other HTTP requests.  To respond to such HTTP requests, you'd first create a [route](/routes), using `form`, `action`, or `path`.
 
-### Declaring Routes
+### Handler Structure
 
-`form` and `action` are intended to be used when an HTTP form is being submitted. The latter—`action`—is for when your form has no user-editable elements.  This is akin to Rails' `button_to` helper, where the contents of the URL contains everything needed to service the request.
+A handler's initializer is subject to [keyword injection](/keyword-injection), with
+the addition of the `form:` keyword, which, if present, will be an instance of the
+associated form class, populated with the data in the form submission (not available for `path` or `action` routes).
 
-`path` is for arbitrary HTTP requests and methods, so to create a webhook that responds to a PUT, you'd use:
+You must implement `handle` to process the form.  **A handler's public API, as
+called by Brut and your tests, is `handle!`**, however you implement `handle`, which
+`handle!` calls.
 
-```ruby
-# inside app/src/app.rb
-path "/webhooks/stripe", method: :put
-```
-
-In all cases, the class to receive and process these requests is a handler, whose name is conventional based on the route. For example, the webhook above would be handled by `Webhooks::StripeHandler`.
-
-### Implementing Handlers
+`handle`'s return value dictates what will happen next:
 
-A handler works like a page, in that its initializer can receive any injectible arguments.  These would include a form object, dynamic elements of the route, or anything else available from the request.  See [Keyword Injection](/keyword-injection) for the details, noting that your handler can be inejcted with custom objects you've configured in a route hook.
+| Return Value | Behavior |
+|---|---|
+|Instance of a page or component | That page or component's HTML is generated and returned.  This is not a redirect, but more like `render :new` in a Rails controller |
+|`Brut::FrontEnd::HttpStatus` | This HTTP status is returned with no body. Use `http_status` from `Brut::FrontEnd::HandlingResults` (included in all handlers) to create an instance from a number |
+| `URI` | Redirect to the URI.  Use `redirect_to` from `Brut::FrontEnd::HandlingResults` (included in all handlers) to generate a URI from a page class and parameters |
+| Two element array with *element 0* being a `Brut::FrontEnd::HttpStatus`, and *element 1* being a page or component instance | Generates the page or component's HTML, but sets the given status instead of 200. Useful for Ajax responses where the HTTP status affects client-side behavior |
+| `Brut::FrontEnd::Download` | Download a file |
+| `Brut::FrontEnd::GenericResponse` | wrap any Rack response |
 
-After the handler is created, it's `before_handle` method is called. If it returns `nil`, `handle` is called to trigger whatever logic the handler needs to trigger.
-
-Both `handle` and `before_handle` can return a variety of objects that determine what will happen:
+> [!IMPORTANT]
+> The only way to render something other than HTML is to do so as a
+> `GenericResponse`, which is basically the low-level Rack API. Brut
+> encourages Ajax responses to be HTML and for you to use the browser's
+> APIs to interact with that HTML.  Brut may make it easier to work
+> with other types of content in the future.
 
-* An instance of a page or component means that page or component is rendered.  This is not a redirect to the page, so it is more like Rails' `render :new` and **not** a `redirect_to(new_widgets_path)`.
-* A `Brut::FrontEnd::HttpStatus` which sends that status and an empty body back.  This object can be created from
-an integer using the `http_status` helper, available to all handlers.
-* A `URI`, which will cause a redirect to that URI.  You can create the `URI` yourself, or use the helper
-`redirect_to`, which accepts a string.
-* A two-element array with a page or component as the first element and an `Brut::FrontEnd::HttpStatus` as the
-second.  This will render that page  or component's HTML, but use the given status instead of 200.  This can be useful for Ajax requests where you want to use HTML your respond format, but also, say, a 422 status to indicate a constraint violation has occured.
-* A `Brut::FrontEnd::Download`, which encapsulates a file to be downloaded.
-* A `Brut::FrontEnd::GenericResponse`, which wraps any Rack response with a defined type.
+### Handling a Form Submission
 
-`before_handle` may also return `nil` to indicate that `handle` should be called. `handle` may not return `nil`.
+A common pattern when handling a form submisssion is to check for any constraint
+violations. If there are some, re-generate the HTML for the page containing the
+form, highlighting the violations. Otherwise, save the data and redirect to another
+page.
 
-Supposing our `LoginForm` and `LoginHandler` wanted to use a common pattern of re-rendering `LoginPage` on constraint violations, and forwarding on to, say, a `DashboardPage`.  Your handler might look like so:
+Here's how that looks:
 
-```ruby {23-27}
-# app/src/front_end/handlers/login_handler.rb
-class LoginHandler < AppHandler
-  def initialize(form:, session:) # We'll discuss the session later
-    @form    = form
-    @session = session
+```ruby
+class NewWidgetHandler < AppHandler
+  def initialize(form:)
+    @form = form
   end
 
   def handle
+    # if no client-side violations were submitted
     if !@form.constraint_violations?
-      authorized_user = AuthorizedUser.login(
-        email: form.email,
-        password: form.password
-      )
-      if authorized_user.nil?
+      widget = DB::Widget.find(name: form.name)
+      if widget
         @form.server_side_constraint_violation(
-          input_name: :email,
-          key: :login_not_found
+          input_name: :name,
+          key: :name_is_taken
         )
-      else
-        session.authorized_user = authorized_user
       end
     end
+
     if @form.constraint_violations?
-      LoginPage.new(form: @form)
+      NewWidgetPage.new(form: @form)
     else
-      redirect_to(DashboardPage.routing)
+      DB::Widget.create(name: form.name,
+                        quantity: form.quantity,
+                        description: form.description)
+      redirect_to(WidgetsPage)
     end
   end
 end
 ```
 
-> [!IMPORTANT]
-> The only way to render something other than HTML is to do so as a
-> `GenericResponse`, which is basically the low-level Rack API. Brut
-> encourages Ajax responses to be HTML and for you to use the browser's
-> APIs to interact with that HTML.  Brut may make it easier to work
-> with other types of content in the future.
+Unlike a Rails controller, the return value of `handle` controls the behavior.  As
+we saw in [Form Constraints](/form-constraints), the HTML generated by
+`NewWidgetPage` will show constraint violations, so by returning
+`NewWidgetPage.new(form: @form)`, the page has the same form instance, including all
+the constraint violations, and the visitor will see the problems.
 
-## Testing
+### Handling Other Requests
 
-Testing handlers requires calling their *public API*, which is `handle!`.  This is not the method you implement (which is the non-bang `handle`).  The reason is that `handle!` manages the logic around calling `before_handle`, which allows your tests to always call `handle!` and know they are testing how the  handler would be used in produciton.
+Non-form submissions work similarly, however there is no form available.  If the
+request could potentially involve a visitor-initiated error, you can use the
+[flash](/flash-and-session) to communicate back.  The flash is available for injection into the
+initializer and, assuming your page uses it to show messages, can allow for
+communication when something is wrong:
 
-Each handler spec includes `Brut::SpecSupport::HandlerSupport`, which allows you to create production-like flash, clock, and session objects. To assert the results of calling `handle!`, there are several RSpec matchers you can use to make your tests easier to write.
+```ruby
+class App
+  # ...
 
-* `have_redirected_to` will check that the handler redirected to a give URI.
-* `have_rendered` will check that the handler rendered a specific page
-* `have_returned_http_status` will check that the handler returned an HTTP status
-* `have_constraint_violation` will check if a form had a particular constraint violation set on it
+  routes do
+    action "/delete_widget/:widget_id"
 
-```ruby
-require "spec_helper"
-
-RSpec.describe LoginPage do
-  describe "#handle!" do
-    context "when login is not valid" do
-      it "re-renders LoginPage" do
-        form = LoginForm.new(params: {
-          email: "nonexistent@example.com",
-          password: "not a password",
-        })
-        result = described_class.new(
-          form:,
-          session: empty_session # empty_session provided by HandlerSupport
-        )
-        expect(result).to have_rendered(LoginPage)
-        expect(form).to have_constraint_violation(:email, key: :login_not_found)
-      end
-    end
-    context "when login is valid" do
-      it "forward to the DashboardPage" do
-        user = create(:user, # Assume this is set up via FactoryBot
-                      email: "pat@example.com",
-                      password: "1q2w3e4r5t6y7u8i9o")
-
-        form = LoginForm.new(params: {
-          email: "pat@example.com",
-          password: "1q2w3e4r5t6y7u8i9o",
-        })
-        session = empty_session
-        result = described_class.new(
-          form:,
-          session:,
-        )
-        expect(result).to have_redirected_to(DashboardPage.routing)
-        expect(session.authorized_user).not_to eq(nil)
-        # Session will be explained later
-      end
+    # ...
+  end
+end
+
+class DeleteWidgetByIdHandler < AppHandler
+  def initialize(widget_id:, flash:)
+    @widget_id = widget_id
+    @flash     = flash
+  end
+
+  def handle
+    widget = DB::Widget.find!(id: @widget_id)
+    if widget.can_delete?
+      widget.delete
+      @flash.notice = :widget_deleted
+      redirect_to(WidgetsPage)
+    else
+      @flash.alert = :widget_cannot_be_deleted
+      WidgetsPage.new
     end
   end
 end
 ```
 
+### Hooks
+
+A handler's public API is `handle!`, because it first calls `before_handle`. This
+operates as a before hook, and has the same return values as `handle`, with the
+exception of also recognizing `nil`, which indicates processing should proceed to
+`handle`.
+
+Generally, you don't need to implement hooksd on a per-handler  basis, but may find
+it useful in a shared super class to implement cross-cutting behavior.
+
+## Testing
+
+See [Unit Testing](/unit-tests) for some basic assumptions and configuration available for all Brut unit tests.
+
+Handler tests should be straightforward: you create your handler, call `handle!`
+(remember, `handle!` is the public API, and will call your hooks, which you want in
+ a test), then examine the result returned and any ancillary behavior, such as
+updated database records.
+
+Some matchers are available to make assertions about `handle!`'s return value:
+
+* `have_redirected_to` will check that the handler redirected to a give URI. See `Brut::SpecSupport::Matchers::HaveRedirectedTo`.
+* `have_generated` will check that the handler generated a specific page or component's HTML. See `<D-f>Brut::SpecSupport::Matchers::HaveGenerated`.
+* `have_returned_http_status` will check that the handler returned an HTTP status. See `Brut::SpecSupport::Matchers::HaveReturnedHttpStatus`.
+* `have_constraint_violation` will check if a form had a particular constraint violation set on it. See `Brut::SpecSupport::Matchers::HaveConstraintViolation`.
+
 ## Recommended Practices
 
-You should avoid having business logic in your handlers.  Since handlers bridge the gap between HTTP and your app, their API is naturally simplistic and String-based.  The handler should defer to business logic (which can be done by either passing the form object directly, or extracting its data and passing that).  Based on the response, the handler will then decide what HTTP response is approriate.
+### You Don't Always Need Resourceful or RESTful Routes
+
+For any code where the browser is performing a submission, use either `form` or
+`action` to declare your route. These will both use an HTTP `POST` to your server and handler.  In the example above, we had a `POST` to `/delete_widget/:widget_id`, and not, say, a `DELETE` to it.
+
+The main reason is that a browser can only submit to a server using `GET` or `POST`, so there's little value in "tunneling" another verb of POST. It doesn't really matter.  And, even though you may use Ajax to submit such data, having it degrade to normal browser-based HTTP is a good practice.
+
+For API-like calls where a browser will never directly interact with the route, and
+it would only be via a server-to-server call, RESTful routes makes sense. But they
+don't need to be the default.
+
+### Avoid Business Logic in Handlers
+
+
+Since handlers bridge the gap between HTTP and your app, their API is naturally simplistic and String-based.  The handler should defer to business logic (which can be done by either passing the form object directly, or extracting its data and passing that).  Based on the response, the handler will then decide what HTTP response is approriate.
 
 This means that your handlers will be relatively simple and their tests will as well.  It does mean that their tests may require the use of mocks or stubs, but that's fine.  Mocks and stubs exist for a reason.
 

data/brutrb.com/hooks.md

@@ -6,11 +6,10 @@ hooks can happen before a page or handler is called, or after.
 ## Overview
 
 We've seen examples thusfar of using a route hook to place the authenticated user or account into the
-request context for later injection into pages or handlers. Brut uses route hooks to locale detection and
-for content security policies.
+request context for later injection into pages or handlers. Brut uses route hooks for locale detection and for content security policies.
 
-At its core, a before hook is a class that extends `Brut::FrontEnd::RouteHook` and implements `before`
-and an after hook implements `after`.  Both `before` and `after` can be [injected](/keyword-injection) with request-time information.
+At its core, a *before* hook is a class that extends `Brut::FrontEnd::RouteHook` and implements `before`
+and an *after* hook implements `after`.  Both `before` and `after` can be [injected](/keyword-injection) with request-time information.
 
 To register a hook, you'd call `before` or `after` in your `App`:
 
@@ -28,16 +27,11 @@ end
 
 The value can be a string or symbol, but should not be the class itself, as this can mess with load order.
 
-The code for `RequireAuthBeforeHook` we saw before was marked with a red warning that it wasn't production ready.  Let's
-see what a more realistic hook would look like.
+Let's implement a realistic hook that checks for authenticated users.  Our hook will
+detect if a user is logged in. If not, we'll redirect to a login page. 
 
-The purpose of `RequireAuthBeforeHook` is to detect if a user is logged in.  If they are, all is well. If they are not,
-we want to redirect them to a login page unless the page they've requested is allowed for logged-out users.
-
-Let's suppose that the home page (`/`) and any page starting with `/auth/` are allowed for logged-out users (`/auth/` being pages related to logging in).
-
-Brut also reserves some routes for its own, and we want those to be allowed to logged-out users as well. Brut sets
-`"brut.owned_path"` in the Rack environment if the requested URL is one it is managing.
+Of course, the login page will need to be accessible without logging in.  We also
+don't want Brut-owned paths to require login, either.
 
 `before` will need access to the request context, session, Rack request, and Rack environment:
 
@@ -51,8 +45,7 @@ class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
 end
 ```
 
-We'll use the Rack request's `path_info` to check for allowed routes, and the aforementioned `env["brut.owned_path"]` to
-check for a Brut-owned path:
+We'll use the Rack request's `path_info` to check for allowed routes.  Brut will set `"brut.owned_path"` in the Rack environment for any path that it owns. We can check that to allow access to those paths.
 
 ```ruby {4-6}
 # app/src/front_end/route_hooks/require_auth_before_hook.rb
@@ -154,9 +147,7 @@ end
 
 ## Testing
 
-Route hooks are normal classes, you could test them as you would a handler or other class.  This may be
-advisable for complex hooks, however it may be more realistic to test their behavior through end-to-end
-tests as this will ensure they are configured correctly in the context of the app.
+Route hooks are normal classes, you could test them as you would a handler or other class.  This may be advisable for complex hooks, however it may be more realistic to test their behavior through end-to-end tests as this will ensure they are configured correctly in the context of the app.
 
 ## Recommended Practices
 
@@ -174,5 +165,12 @@ For page- or use-case-specific behavior, it may be better to put the logic in a
 
 _Last Updated June 12, 2025_
 
-Route hooks and Middlewares do not share implementations, however they are similar in concept.  These
-concepts may be unified in the future.
+Route hooks and Middlewares do not share implementations, however they are similar in concept.  These concepts may be unified in the future.
+
+Hooks are applied in `Brut::Framework::MCP` usiung Sinatra's hooks mechanism.  While
+Brut may not always be based on Sinatra, it is now. You should not rely on it.
+
+Lastly, there is some dissonance in how keyword injection works.  Pages and Handlers
+have initializer injection, while hooks use method injection.  This may change -
+Hooks may be re-designed to use initializer injection, and even changed so that
+before and after hooks have different base classes.

data/brutrb.com/i18n.md

@@ -167,14 +167,16 @@ t("cv.be.required") # => This field is required
 
 ## Testing
 
-In tests, you can call `t` and `l` to examine values as needed.
+In tests, you can call `t` and `l` to examine values as needed. You may find the
+`have_i18n_string` matcher usefult to check generated HTML for I18n values (see `Brut::SpecSupport::Matchers::HaveI18nString`).
 
 > [!WARNING]
-> This aspect of Brut could use improvement. It likely will not work for non-English locales.
+> Brut hardcodes English for tests, which you may not want.  This will be addressed
+> in the future.
 
 ## Recommended Practices
 
-Could use help here - The implementation feels like a bare minium
+None at this time, however Brut's I18n has not been battle-tested.
 
 
 ## Technical Notes
@@ -185,4 +187,4 @@ Could use help here - The implementation feels like a bare minium
 
 _Last Updated May 7, 2025_
 
-TBD
+None at this time.

data/brutrb.com/index.md

@@ -6,8 +6,8 @@ hero:
   name: "Brut RB"
   text: "Raw Ruby Web Apps"
   tagline: Standards-based, No-nonsense, HTML-first, Low Ceremony
-  image:
-    src: /images/logo.png
+  ximage:
+    src: /images/LogoTall.png
     alt: "A Ruby gemstone embedded into a concrete, brutalist building"
   actions:
     - theme: brand
@@ -20,7 +20,7 @@ hero:
       text: Conceptual Overview
       link: /overview
 
-features:
+xfeatures:
   - title: Standards-Based
     icon:  📄
     details: "Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"
@@ -34,3 +34,4 @@ features:
     icon: 🏘️
     details: "Sequel, Phlex, I18n, RSpec. They do it best"
 ---
+![logo](/images/LogoStop.png)

data/brutrb.com/instrumentation.md

@@ -28,7 +28,7 @@ Brut automatically sets up OpenTelemetry (OTel) tracing.  The primary interface
 `Brut::Instrumentation::OpenTelemetry`, which is available via `Brut.container.instrumentation`.  We'll
 discuss that in a moment.
 
-To configure the specifics of where the traces wil go, the OTel gem uses environment variables:
+To configure the specifics of where the traces will go, the OTel gem uses environment variables:
 
 | Variable                             | Value                      | Purpose                                                                                                                                                         |
 |--------------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -44,7 +44,7 @@ When you created your Brut app, your `.env.development` and `.env.test` should h
 environment variables that will send instrumentation to the otel-desktop-viewer that was also configured.
 
 If you run your app using `bin/dev` and use the app for a bit, then go to `http://localhost:8000`, you
-will see the otel-desktop-viewer UI and can browser the spans and traces sent by Brut.
+will see the otel-desktop-viewer UI and can browse the spans and traces sent by Brut.
 
 
 ### What is Instrumented By Default
@@ -54,7 +54,7 @@ data.  Brut will attempt to conform to standard semantics for HTTP requests and
 
 Here is a non-exhaustive list of what Brut automatically instruments:
 
-* How long each page or handler request takes
+* How long each page or handler request takes, broken down by components.
 * CLI execution time
 * Time to rebuild the schema for tests
 * Time to run tests
@@ -75,7 +75,7 @@ Here is a non-exhaustive list of what Brut automatically instruments:
 > the actual values inserted or used in `WHERE` clauses.
 > While you should not be putting sensitive data into your database,
 > be warned that this is happening. There are plans to improve this
-> to be more flexible and reduce the Schance of sensitive data
+> to be more flexible and reduce the chance of sensitive data
 > being sent in traces.
 
 ### Adding Your Own Instrumentation
@@ -155,16 +155,14 @@ The class `Brut::FrontEnd::Handlers::InstrumentationHandler` is set up to receiv
 client-side to provide insights about client-side behavior as part of a server-side request.  Brut
 attempts to join up any client-side instrumentation to the request that served it.
 
-It does this `Brut::FrontEnd::Components::Traceparent` component, which is included in your default layout
-when you created your Brut app.  This creates a `<meta>` tag containing standardized information used to
+It does this via the `Brut::FrontEnd::Components::Traceparent` component, which is included in your default layout when you created your Brut app.  This creates a `<meta>` tag containing standardized information used to
 connect the client-side behavior to the server-side request.
 
 The Brut custom element `<brut-tracing>` uses this information, along with statistics from the browser, to
 send a custom payload back to Brut at the route `/__brut/instrumentation`, which is handled by the
 aforementioned `InstrumentationHandler`.
 
-You should then see client-side tracing information as a sub-span of your HTTP request.  The information
-available depends on the browser, and some browsers don't send much.
+You should then see client-side tracing information as a sub-span of your HTTP request.  The information available depends on the browser, and some browsers don't send much. Also keep in mind that clock drift is real and while client-side timings are accurate, the timestamps will not be.
 
 ## Testing
 
@@ -187,8 +185,7 @@ specific issues.
 _Last Updated June 12, 2025_
 
 
-Brut does not have plans to support non-OTel instrumentation, nor does it have plans to provide hooks to
-use proprietary formats.  This could change of course.
+Brut does not have plans to support non-OTel instrumentation, nor does it have plans to provide hooks to use proprietary formats.
 
 The client-side portion of this is highly customized.  The Otel open source code for the client side is
 massive and hugely complex, so Brut decided to try to produce something simple and straightforward as a

data/brutrb.com/javascript.md

@@ -1,9 +1,9 @@
 # JavaScript
 
-Brut provides basic bundling using [esbuild](https://esbuild.github.io/).  Brut does not support nor prevent the
-use of any front-end framework.  Brut does, however, include [BrutJS](/brut-js), a lightweight library of HTML custom
-elements and utility code.  These elements can provide a fair bit of front-end functionality using progressive
-enhancement without the need for a framework.
+Brut provides basic bundling using [esbuild](https://esbuild.github.io/).  You can
+use any front-end framework with Brut, but you don't have to use one.
+
+Brut provides [BrutJS](/brut-js), which is a lightweight library of HTML custom elements and utility code.  These elements can provide a fair bit of front-end functionality using progressive enhancement without the need for a framework.
 
 ## Overview
 
@@ -19,7 +19,7 @@ For example, if you have a `Widget` class that uses a `Status` class, and you al
 
 First, `package.json` (in your app's root) would include `"foobar"` (and it must set `"type"` to `"module"`):
 
-```json {2,5}
+```json {3,6}
 {
   "name": "your-app",
   "type": "module",
@@ -50,7 +50,7 @@ Notice that "foobar", since it's brought in as a third party dependency, is impo
 here!  Every third party library has a different syntax for how to import whatever it is or does. Consult the
 documentation of each third party library you wish to import.
 
-The second `import` uses a `./` because it's importing a file in `app/src/front_end/js` namely `Widget.js`.  Be
+The second `import` uses a `./` because it's importing a file in `app/src/front_end/js`, namely `Widget.js`.  Be
 careful here, too, as you must be sure to `export` the right thing.  Here's what `app/src/front_end/js/Widget.js`
 might look like:
 
@@ -96,16 +96,13 @@ details on this can be found in [assets](/assets).
 ## Testing
 
 Client-side behavior is best tested with end-to-end tests, however you can simplify your end-to-end tests by
-creating unit tests of your custom elements.  BrutJS provides support for this. TBD LINK.
+creating unit tests of your custom elements.  [BrutJS provides limited support for this](/brut-js/api/module-testing.html)
 
 ## Recommended Practices
 
-Brut encourages you to use HTML custom elements as progressive enhancements over server-generated views.  This
-sort of client-side code will age well.  The toolchain and dependencies are minimal, so you will not have to
-worry too much about code written this way.
+Brut encourages you to use HTML custom elements as progressive enhancements over server-generated views.  This sort of client-side code will age well.  The toolchain and dependencies are minimal, so you will not have to worry too much about code written this way.
 
-It *will* be lower level and more verbose than existing frameworks.  We would argue that it is not significantly
-more difficult and the sustainability is worth it.
+It *will* be lower level and more verbose than existing frameworks.  We would argue that it is not significantly more difficult and the sustainability is worth it.
 
 ## Technical Notes
 
@@ -118,5 +115,8 @@ _Last Updated May 7, 2025_
 Currently, Brut only supports a single entry point and bundle.  This could be easily made more flexible if there
 is a desire to finely tweak the JavaScript loaded on specific pages.
 
-Brut also does not expose any esbuild configuration.  This could be provided in the future, but for now, it is
-hard-coded.
+Brut also does not expose any esbuild configuration.  This could be provided in the future, but for now, it is hard-coded.
+
+Brut may provide more direct support for import maps, but as of now, import maps are
+not widely used outside of Rails, and tend to cause a lot of problems, especially if
+you aren't able to field an HTTP/2 web server (or even know what that is).