brut 0.0.21 → 0.0.23

data/brutrb.com/images/spa.dot

@@ -0,0 +1,19 @@
+digraph G {
+
+  Node[fontname="Helvetica"]
+  Edge[fontname="Baskerville"]
+
+  ShouldBeSPA              -> SessionMoreThan10Minutes
+  SessionMoreThan10Minutes -> No [label="No"]
+  SessionMoreThan10Minutes -> TenUpdatesPrimaryData [label="Yes"]
+  TenUpdatesPrimaryData    -> No [label="No"]
+  TenUpdatesPrimaryData    -> Maybe [label="Yes"]
+ 
+  ShouldBeSPA              [ shape=rect label="Should this App\nby a Single-Page-App (SPA)?"]
+  No                       [ shape=octagon]
+  Maybe                    [ shape=circle]
+  SessionMoreThan10Minutes [ shape=diamond label="Sessions last\nlonger than\n10 minutes?\n"]
+  TenUpdatesPrimaryData    [ shape=diamond label="More than 10\nupdates to primary\nuser data?"]
+  
+  { rank=same; SessionMoreThan10Minutes; No }
+}

data/brutrb.com/images/workspace-protocol.dot

@@ -0,0 +1,44 @@
+digraph G {
+
+  rankdir="LR"
+  nodesep=0.55
+  compound=true
+  node[shape=box fontname=avenir]
+
+  Setup[label=<
+    <FONT face="avenir">Setup</FONT>
+    <br/>
+    <FONT face="Courier New">bin/setup</FONT>
+  >]
+  Run[label=<
+    <FONT face="avenir">Run</FONT>
+    <br/>
+    <FONT face="Courier New">bin/dev</FONT>
+  >]
+  Test[label=<
+    <FONT face="avenir">Test</FONT>
+    <br/>
+    <FONT face="Courier New">bin/test</FONT>
+  >]
+  CI[label=<
+    <FONT face="avenir">Test</FONT>
+    <br/>
+    <FONT face="Courier New">bin/ci</FONT>
+  >]
+  Code[label=<
+    <FONT face="avenir">Code</FONT>
+    <br/>
+    <FONT face="Baskerville">Write Code</FONT>
+    <br/>
+    <FONT face="Courier New">bin/db</FONT>
+    <br/>
+    <FONT face="Courier New">bin/scaffold</FONT>
+  >]
+  Setup -> Run
+  Setup -> Code
+  Run   -> Code
+  Code  -> Test
+  Test  -> Code
+  Test  -> CI
+  { rank=same; Run; Code; }
+}

data/brutrb.com/index.md

@@ -0,0 +1,36 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Brut RB"
+  text: "Raw Ruby Web Apps"
+  tagline: Standards-based, No-nonsense, HTML-first, Low Ceremony
+  image:
+    src: /images/logo.png
+    alt: "A Ruby gemstone embedded into a concrete, brutalist building"
+  actions:
+    - theme: brand
+      text: "Brut is Not Yet Released"
+      link: /not-released
+    - theme: brand
+      text: "Getting Started"
+      link: /getting-started
+    - theme: alt
+      text: Conceptual Overview
+      link: /overview
+
+features:
+  - 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"
+  - title: Convention-Oriented
+    icon: 🎚️
+    details: "In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."
+  - title: Objects and Methods
+    icon: 💻
+    details: "Author classes to create objects on which to call methods. Nothing fancy."
+  - title: Builds on Community Libraries
+    icon: 🏘️
+    details: "Sequel, Phlex, I18n, RSpec. They do it best"
+---

data/brutrb.com/instrumentation.md

@@ -0,0 +1,183 @@
+# Instrumentation and Observability
+
+Brut has built-in support for OpenTelemetry, which is an open standard used by many observability vendors
+to allow you to understand the behavior of your app in production.  Brut also includes a configuration for
+the [otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer/), which allows you to see
+instrumentation in development.
+
+## Overview
+
+### Why Instrument?
+
+In production, you'll need to know what your app is doing and how well it's working.  Historically, logs
+can provide this information in a roundabout way. Over the last many years, Application Performance
+Monitoring (APM) vendors like New Relic and Data Dog allowed developers to see much richer detail about
+how an app is working.
+
+You could see, for example, the 95th percentil of your dashboard controller's performance, or the top 10
+slowest SQL statements your app is executing.  OpenTelemetry attempts to unify the API used to communicate
+this information from your app to your chosen vendor, and most vendors support it.
+
+Instrumentation, then, is a way to record what your app is doing, how long its taking, and perhaps even
+why it's doing what it's doing, down to a very specific level.  If properly configured, you could examine
+the performance of the app for a particular user on a particular day.
+
+### Setting up Instrumentation
+
+Brut automatically sets up OpenTelemetry (OTel) tracing.  The primary interface you will use is
+`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:
+
+| Variable                             | Value                      | Purpose                                                                                                                                                         |
+|--------------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT`        | Depends on environment     | Where to send the tracers. This is provided by your vendor, but is `http://otel-desktop-viewer:4318` in development                                             |
+| `OTEL_EXPORTER_OTLP_HEADERS`         | Depends on vendor          | Your vendor may ask you to set this. It often contains identifying information or API keys                                                                      |
+| `OTEL_EXPORTER_OTLP_PROTOCOL`        | http/protobuf              | Your vendor may request a different protocol, but protobuf is common and supported by otel-desktop-viewer                                                       |
+| `OTEL_LOG_LEVEL`                     | debug                      | Useful when setting everything up to understand why things aren't working if they aren't working                                                                |
+| `OTEL_RUBY_BSP_START_THREAD_ON_BOOT` | false                      | Deals with esoteric issues with Puma. See [this GitHub issue](https://github.com/open-telemetry/opentelemetry-ruby/issues/462) for the details.
+| `OTEL_SERVICE_NAME`                  | Your app's `id` from `App` | Identifiers your app's name to the vendor                                                                                                                       |
+| `OTEL_TRACES_EXPORTER`               | otlp                       | Configures the class inside the OTel gem that will export the instrumentation to the vendor. If you omit this, Brut will log the instrumentation to the console |
+
+When you created your Brut app, your `.env.development` and `.env.test` should have values for all these
+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.
+
+
+### What is Instrumented By Default
+
+Brut attempts to automatically instrument useful things so you don't have to do anything to start getting
+data.  Brut will attempt to conform to standard semantics for HTTP requests and SQL statements.
+
+Here is a non-exhaustive list of what Brut automatically instruments:
+
+* How long each page or handler request takes
+* CLI execution time
+* Time to rebuild the schema for tests
+* Time to run tests
+* Time to apply migrations
+* Time spent inside a route hook
+* The locale detected from the browser
+* The layout class used when rendering a page
+* If a requested path is owned by Brut or not
+* Ignored parameters on all form submissions
+* How long reloading takes in development
+* CSP reporting results
+
+### Adding Your Own Instrumentation
+
+You can add instrumentation in a few ways:
+
+* *Spans* record a block of code. They are shown as a sub-span if one is already in effect.  When you
+create a span, that means it will be shown in the context of the HTTP request.
+* *Attributes* can be added to the current span to provide more context about what is happening. For
+example, the HTTP request method is an attribute of the span used for the HTTP request.  These attributes
+allow for sophisticated querying in the vendor's UI.
+* *Events* record things that happen and metadata about that thing. These are like log statements. They
+are associated with the span you are in when you add the event.
+
+These can all be added via `Brut.container.instrumentation`, which is a
+`Brut::Instrumentation::OpenTelemetry` instance.
+
+These methods are available:
+
+* `span(name,**attributes,&block)` - Create a new span around the block yielded.
+* `add_attributes(attributes)` - Add attributes to the current span. These will be prefixed with your
+app's prefix so it's clear in the observability UI that they are for your app and not standard.
+* `add_event(name,**attributes)` - Add an event with optional attributes for the current span.
+* `record_exception(ex,attributes=nil)` - Record an exception that was caught.
+* `record_and_reraise_exception!(ex,attributes=nil)` - Record an exception and raise it.
+
+Suppose you want to instrument `RequireAuthBeforeHook` from the [hooks](/hooks) documentation. Although
+the hook's `before` method is instrumented by Brut already, let's add some metadata to that span, and also
+add a span around the login check.
+
+```ruby {11-16,18,20,23-26}
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+    is_home_page       = request.path_info.match(/^\/?$/)
+    is_auth_route      = request.path_info.match?(/^\/auth\//)
+    is_brut_owned_path = env["brut.owned_path"]
+
+    requires_login = !is_home_page  &&
+                     !is_auth_route && 
+                     !is_brut_owned_path
+    Brut.container.instrumentation.add_attributes(
+      requires_login:,
+      is_home_page:,
+      is_auth_route:,
+      is_brut_owned_path:
+    )
+
+    Brut.container.instrumentation.span("login-check") do |span|
+      if session.logged_in?
+        span.add_attributes(logged_in: true)
+        request_context[:authenticated_account] = session.authenticated_account
+        requires_login = false
+      else
+        span.add_attributes(logged_in: false)
+      end
+    end
+
+    if requires_login
+      redirect_to(Auth::LoginPage)
+    else
+      continue
+    end
+
+  end
+end
+```
+
+Now, for every request someone makes to our app, we will see a span for the `RequireAuthBeforeHook`, and
+inside that span, we'll see the attributes we added as well as a sub-span representing the login check
+(which itself will have an attribute about the user's logged-in status).
+
+### Client-Side Observability
+
+
+The class `Brut::FrontEnd::Handlers::InstrumentationHandler` is set up to receive information from the
+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
+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.
+
+## Testing
+
+Generally you don't want to test instrumentation unless it's highly complex and critical to the app's
+ability to be maintained.  Ideally, your end-to-end tests will cover all the instrumentation code you
+write so you can be sure that none of that causes a problem.
+
+## Recommended Practices
+
+Entire books and conferences exist on how to properly instrument your app.  Our suggestion is to take what
+you have by default and add additional instrumentation only to solve specific problems or identify
+specific issues.
+
+## Technical Notes
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_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.
+
+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
+start. This can and will evolve over time.

data/brutrb.com/javascript.md

@@ -0,0 +1,122 @@
+# 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.
+
+## Overview
+
+All your app's JavaScript lives in `app/src/front_end/js`, or in modules you bring in via `package.json`.  Brut
+will *bundle* all of that up into a single `.js` file that is served up with your app.  Brut does this by using
+esbuild, a stable and standardized tool for bundling JavaScript.
+
+The way esbuild works is to be given an *entry point* that requires, or transitively requires, all of your
+JavaScript by using ES6 modules. `app/src/front_end/js/index.js` is the entry point for your app.
+
+For example, if you have a `Widget` class that uses a `Status` class, and you also use the third party library
+"foobar", here is how all the files would look.
+
+First, `package.json` (in your app's root) would include `"foobar"` (and it must set `"type"` to `"module"`):
+
+```json {2,5}
+{
+  "name": "your-app",
+  "type": "module",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "foobar": "^0.0.11"
+  },
+  "devDependencies": {
+    "chokidar-cli": "^3.0.0",
+    "esbuild": "^0.20.2",
+    "jsdom": "^25.0.1",
+    "mocha": "^10.7.3",
+    "playwright": "^1.50.1"
+  },
+}
+```
+
+Next, `app/src/front_end/js/index.js` would import both `"foobar"` and `"Widget"`:
+
+```javascript
+import { foobar } from "foobar"
+import Widget from "./Widget"
+
+// ...
+```
+
+Notice that "foobar", since it's brought in as a third party dependency, is imported without a `./`.  Be careful
+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
+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:
+
+```javascript
+import Status from "./extra/Status"
+
+class Widget {
+  status = new Status()
+}
+
+export default Widget
+```
+
+Note that we import `Status` here.  Unlike Ruby, ES6 modules requires each class that references a class to
+import it explicitly.  Also notice that we do `export default Widget`, which allows `import Widget` to work.
+
+Finally, `app/src/front_end/extra/Status.js` looks like so:
+
+```javascript
+class Status {
+}
+export default Status
+```
+
+When `bin/build-assets` runs, esbuild will use `app/src/front_end/js/index.js` as its *entry point*, and will
+bundle both `Widget.js` and the "foobar" library.  When it bundles `Widget.js`, it will see that it imports
+`extra/Status.js` and bundle that, too.
+
+This bundle can be included in your app by ensuring this is in your layout:
+
+```ruby {5}
+def view_template
+  doctype
+  html(lang: "en") do
+    head do
+      script(defer: true, src: asset_path("/js/app.js"))
+      # ...
+```
+
+The `asset_path` helper takes a logical path—`/js/app.js`—and returns the actual path the browser can use.  More
+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.
+
+## 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.
+
+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
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_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.

data/brutrb.com/jobs.md

@@ -0,0 +1,14 @@
+# Background Jobs
+
+Brut provides little direct support for background jobs. Currently, Brut recommends Sidekiq, since it is
+battle-tested, well-supported, and open source.
+
+When you set up your Brut app, it should ask if you want Sidekiq support and add the necessary configuraiton.
+
+It will expect jobs in `app/src/back_end/jobs`.
+
+> [!WARNING]
+> The way Sidekiq is configured with Brut is effective and reliable, but it is complex.  It currently
+> involves several moving parts to make it work properly.  This will be an area for improvement.
+
+

data/brutrb.com/keyword-injection.md

@@ -0,0 +1,237 @@
+# Keyword Injection
+
+Brut is desiged around classes and objects, as compared to modules and DSLs.  Almost everything you do when building your app is to create a class that has an initializer and implements one or more methods.  But, these initalizers and methods often need information from the request that Brut is managing.
+
+In a basic Rack or Sinatra app, you would access this information via Rack's API, which is essentially a `Hash` of whatever. It's error-prone and requires consulting documentation, source code, or runtime information to figure out what's stored where.
+
+Brut can instead inject these values explicitly into the classes of yours it creates.  It does this based on the
+names of keyword arguments declared by your class' intializer or a template method Brut will call.
+
+## Overview
+
+For example, a [Page](/pages) requires you to implement an initializer. That initializer's keyword arguments define what
+information is needed. Brut provides that information when it creates the object. This is a form of dependency injection and it can simplify your code if used effectively.
+
+Consider this route:
+
+```ruby
+page "/widgets/:id"
+```
+
+Brut will expect to find `WidgetsByIdPage`.  Your initializer can declare `id:` as a keyword arg and this will be passed when the
+class is created:
+
+```ruby
+class WidgetsByIdPage < AppPage
+  def initialize(id:)
+    @widget = DB::Widget.find(id)
+  end
+end
+```
+
+If the page requires access to the session, it can declare that:
+
+```ruby {2,4}
+class WidgetsByIdPage < AppPage
+  def initialize(id:, session:)
+    @widget       = DB::Widget.find(id)
+    @current_user = session.current_user
+  end
+end
+```
+
+Because `session:` is a required argument, Brut cannot instantiate the page without it, so it will always be
+passed in and availbale.
+
+### Standard Injectible Information
+
+In any request, the following information is available to be injected:
+
+* `session:` - An instance of your app's `Brut::FrontEnd::Session` subclass for the current visitor's session.
+* `flash:` - An instance of your app's `Brut::FrontEnd::Flash` subclass.
+* `xhr:` - true if this was an Ajax request.
+* `body:` - the body submitted, if any.
+* `csrf_token:` - The current CSRF token.
+* `clock:` - A `Clock` to be used to access the current time in the visitor's time zone.
+* `http_*` - any parameter that starts with `http_` is assumed to be for an HTTP header. For example, `http_accept_language` would be
+given the value for the "Accept-Language" header.  See the section on HTTP headers below.
+* `env:` - The Rack env.  This is discouraged, but available if you can't get what you want directly
+
+Depending on the context, other information is available:
+
+* `form:` - If a form was submitted, this is the `Brut::FrontEnd::Form` subclass containing the data. See [Forms](/forms).
+* Any query string paramter - Note that if these conflict with existing Brut values, the behavior is undefined.  Name your query string parameters carefully. These should have default values or your page won't work if they are omitted.
+* Any route parameter - These should not have default values, since they are required for Brut to match the route.
+
+A `Brut::FrontEnd::RouteHook` is slightly different. Only the following data is available to be injected:
+
+* `request_context:` - The current request context, thought it may be `nil` depending on when the hook runs
+* `session:` - An instance of your app's `Brut::FrontEnd::Session` subclass for the current visitor's session.
+* `request:` - The Rack request
+* `response:` - The Rack response
+* `env:` - The Rack env.
+
+### HTTP Headers
+
+Since any header can be sent with a request, Brut allows you to access them, including non-standard ones.  Rack (which is based on CGI), provides access to all HTTP headers in the `env` by taking the header name, replacing dashes ("-") with underscores ("\_"), and prepending `http_` to the name, then uppercasing it.  Thus, "User-Agent" becomes `HTTP_USER_AGENT`.
+
+Because Ruby parameters and variables must start with a lower-case letter, Brut uses the lowercased version of the Rack/CGI variable.
+Thus, to receive the "User-Agent", you would declare the keyword parameter `http_user_agent`.
+
+Further, because headers come from the client and may not be under your control, the value that is actually injected depends on a few
+things:
+
+* If your keyword arg is required, i.e. there is no default value:
+  - If the header was not provided, `nil` is injected.
+  - If the header *was* provided, it's value is injected, even if it's the empty string.
+* If your keyword arg is optional, i.e.  it has a default value
+  - If the header was not provided, no value is injected, and your code will receive the default value.
+  - If the header *was* provided, it's value is injected, even if it's the empty string.
+
+### Ordering and Disambiguation
+
+You are discouraged from using builtin keys for your own data or request parameters.  For example, you should not have a query string
+parameter named `env` as this conflicts with the builtin `env` that Brut will inject.
+
+Since you can inject your own data (see below), you are free to corrupt the request context.  Please don't do this. Brut may actively
+prevent this in the future.
+
+You can also use the request context to put your own data that can be injected.
+
+### Injecting Custom Data
+
+The correct place to inject your own data into the request is in a [before hook](/hooks).  When you
+configure a before hook, it will run after Brut's internal
+`Brut::FrontEnd::RouteHooks::SetupRequestContext`, which ensures the request context exists and is ready
+for use.
+
+For example, here is how you might inject the currently logged-in account based on the session:
+
+```ruby
+class AuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:)
+    if session.authenticated_account
+      request_context[:authenticated_account] = session.authenticated_account
+    end
+    continue
+  end
+end
+```
+
+Note that the value is only injected if it exists.  It's important not to inject `nil` for values that
+don't exist.
+
+You may be thinking that this particular example is unnecessary. You could simply inject `session:` and
+call `session.authenticated_account`:
+
+```ruby
+class DashboardPage < AppPage
+  def initialize(session:)
+    @widgets = session.authenticated_account.widgets # e.g.
+  end
+end
+```
+
+If `DashboardPage` requires an authenticated account, by only injecting the session, you'll need to handle the case where `session.authenticated_account` is `nil`.  Instead, if you configure the `AuthBeforeHook` as above, then inject `authenticated_account`, you avoid the need for this logic:
+
+```ruby
+class DashboardPage < AppPage
+  def initialize(authenticated_account:)
+    @widgets = authenticated_account.widgets # e.g.
+  end
+end
+```
+
+Because `AuthBeforeHook` never injects `nil`, `DashboardPage` can rely on `authenticated_account` always being present.  Further, if a visitor tried to access `/dashboard_page` without having been authenticated, Brut would be unable to create an instance of `DashboardPage` and generate an error.
+
+### `nil` and Empty Strings
+
+When a keyword argument has no default value, Brut will require that value to exist and be available for injection. If the keyword is
+not one of the canned always-available values, it will look in the request context, then in the query string.
+
+If the request has the keyword as a key, *it will inject whatever value it finds, including `nil`*.  In general, you should avoid
+injecting `nil` when you actually intend to not have a value.
+
+For example, the `AuthBeforeHook` above, you could implement it like so:
+
+```ruby
+request_context[:authenticated_account] = session.authenticated_account
+```
+
+The problem is that if the visitor is not logged in, the `:authenticated_account` *will* have a value, and that value will be `nil`. This is almost certainly not what you want.
+
+For query string parameters, the HTTP spec says that they are strings.  Thus, if a query string parameter is present in ther request
+URL, it will *always* have a value and *never* be `nil`.  If the paramter doesn't have a value after the `=` (e.g. for `foo` in `?foo=&bar=quux`), the value will be the empty string.
+
+This means you must write code to explicitly handle the cases you care about.
+
+### When Values Aren't Available
+
+When a value is not available for injection, and the keyword doesn't provide a default, Brut will raise an error.  This is because
+such a situation represents a design error.
+
+For example, the `DashboardPage` above requires an `authenticated_account`.  Your app should never route a logged-out visitor to that
+page.  This allows the `DashboardPage` to avoid having to check for `nil` and figure out what to do.
+
+This is most relevant for query string parameters, since they can be easily manipulated by the visitor in their browser.  Query string
+parameters should always have a default value, even if it's `nil`.
+
+*Path* parameters (like `:id` in `WidgetsByIdPage`) should *never* have a default value as their absence means a different URL was
+requested.  For example, `/widgets` would trigger a `WidgetsPage`. *Only* if the `:id` path parameter is present would the
+`WidgetsByIdPage` be triggered, so it's safe to omit the default value for `id:` (and pointless to include one).
+
+See [route hooks](/hooks).
+
+### Testing
+
+Brut will not create your classes in a test.  Instead, you must pass in the values you want.  There are various
+helpers in `Brut::SpecSupport` to create blank or empty versions of the special classes.
+
+In particular, A basic `request_context` is setup per test and injected into the Thread local storage. This means
+that if your test should trigger a codepath that *does* cause Brut to use keyword injection, useful values will
+be injected.
+
+For your tests, however, you should pass in directly what you need:
+
+```ruby
+page = WidgetsByIdPage.new(id: widget.id, session: empty_session)
+```
+
+## Recommended Practices
+
+Consider a method like so:
+
+``` ruby
+def create_widget(name:, organization: nil, quantity: 10)
+```
+
+Outside of Brut, the way to interpret this arguments is as follows:
+
+* `name` is required
+* `organization` is optional
+* `quantity` has a default value of 10 if not provided
+
+Any method or intializer that will be keyword-injected should be designed with this in mind.  Thus, the following guidelines will be helpful in managing your app:
+
+* **Choose arguments based on the needs of the class:**
+  - If a value is optional, default it to either `nil` or a symbol that indicates what happens when the value is omitted
+  - If an optional value has a default, use that (this should be rare for pages, handlers, components, and hooks)
+  - Otherwise, do not provide a default for the keyword
+* **Design for non-`nil` values instead of allowing `nil` and checking for it**
+  - If a page needs, say, the currently logged-in user, set that up as injectible with no default.
+  - If a codepath creates that page without the logged-in user, you will get a very obvious error and
+    can figure out how it happened. Your page's code doesn't need to figure out what to do with `nil`
+* **Do not inject `nil` into the request context.** When your code requires a value for a keyword, you want to rely on that value being non-nil.  Thus, avoid injecting `nil` into the request context. Brut will allow it as a sort-of escape hatch, but you should design your app to avoid it
+* **Be careful injecting global data.**  The request context instance is per request, but you could certainly put global data into it. For example, you may put an initialized API client into the request context as a convieniece. **Be careful** because your app is multi-threaded.  Any object that is not scoped to the request must be thread-safe.
+
+## Technical Notes
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_Last Updated May 7, 2025_
+
+Keyword injection is currently implemented in a few places and not available via public API.  It could be useful
+as an API and it will be exposed at some point. For now, it's only available for Brut-managed classes as
+documented here.