@cruglobal/cornerstone-components 0.1.0

package/dist/unbundled/skills/cornerstone/references/customizing.md

@@ -0,0 +1,180 @@
+# Customizing
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/customizing
+
+Cornerstone is built to be customized. Every component is styled with design tokens you can
+override, and each one exposes CSS parts, custom properties and custom states so you can reach
+inside it without fighting the shadow DOM.
+
+## Customizing with CSS
+
+For even more customizations, you can off-road and override any theme just with CSS — no preprocessor required. All tokens use the `--cs-` prefix to prevent collisions with other libraries. Write a stylesheet that overrides Cornerstone's [design tokens](https://cruglobal.github.io/cornerstone-design-system/tokens) and you're off to the races.
+
+Here's a starter that tweaks fonts, spacing, and corner radius across both color schemes:
+
+```css
+/* Custom CSS — applies to both light and dark mode */
+:where(:root),
+.cs-light,
+.cs-dark,
+.cs-invert {
+  --cs-font-family-body: 'Inter', sans-serif;
+  --cs-font-family-heading: 'Crimson Pro', serif;
+  --cs-border-radius-scale: 1.5;
+  --cs-space-scale: 1.125;
+}
+```
+
+To create your own light mode styles, scope your styles to the following selectors:
+
+```css
+:where(:root),
+.cs-light,
+.cs-dark .cs-invert {
+  /* your styles here */
+}
+```
+
+To create your own dark mode styles, scope your styles to these selectors:
+
+```css
+.cs-dark,
+.cs-invert {
+  /* your styles here */
+}
+```
+
+| Selector              | What It Targets                                                                |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `:where(:root)`       | The default scope, with low specificity so other theme classes can override it |
+| `.cs-light`           | Explicit light sections                                                        |
+| `.cs-dark`            | Explicit dark sections                                                         |
+| `.cs-invert`          | Flips the current color scheme for the section it's applied to                 |
+| `.cs-dark .cs-invert` | An inverted descendant inside a dark section (becomes light)                   |
+
+For a complete list of all custom properties used for theming, refer to `src/styles/themes/default.css` in the project's source code.
+
+## Customizing Components
+
+While themes offer a high-level way to customize the library, individual components offer different hooks as a low-level way to customize them one at a time. Cornerstone components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose a set of CSS parts, custom properties, and custom states that can be targeted to customize their appearance.
+
+### CSS Parts
+
+CSS parts offer the most flexibility to customize individual components. The "parts" exposed by each component can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.
+
+Parts allow you to style _any_ standard CSS property, not just those exposed through custom properties. Here's an example that modifies buttons with the `gradient-button` class.
+
+```html
+<cs-button class="gradient-button"> Gradient Button </cs-button>
+
+<style>
+  .gradient-button::part(button) {
+    background: linear-gradient(217deg, var(--cs-color-sky-50), var(--cs-color-purple-50), var(--cs-color-cerise-50));
+    border: solid 1px var(--cs-color-purple-50);
+    transition:
+      transform 100ms,
+      box-shadow 100ms;
+  }
+
+  .gradient-button::part(button):hover {
+    box-shadow: var(--cs-shadow-m);
+    transform: translateY(-3px);
+  }
+
+  .gradient-button::part(button):active {
+    box-shadow: inset var(--cs-shadow-s);
+    transform: translateY(0);
+  }
+
+  .gradient-button::part(label) {
+    color: white;
+    text-shadow: rgb(0 0 0 / 0.3) 0 -1px;
+  }
+</style>
+```
+
+CSS parts have a few important advantages:
+
+- Customizations can be made to components with explicit selectors, such as `::part(icon)`, rather than implicit selectors, such as `.button > div > span + .icon`, that are much more fragile.
+
+- The internal structure of a component will likely change as it evolves. By exposing CSS parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.
+
+- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
+
+Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
+
+#### Part names
+
+A component's outermost element takes a part named after the component itself, so `<cs-button>` exposes `button` and `<cs-details>` exposes `details`. Where an inner element already holds that name — `<cs-input>` names its native control `input` — the wrapper takes a `-wrapper` suffix instead: `input-wrapper`, `textarea-wrapper`.
+
+Not every component has one. When a component's outer element is the host, style it directly instead — `cs-card { ... }` rather than a part.
+
+### Custom Properties
+
+Components expose custom properties that are scoped to the component, not global, so they do not have the same `--cs-` prefix as a theme's custom properties. These custom properties reflect common qualities of a component, such as `--background-color`, `--border-style`, `--size`, etc.
+
+You can set custom properties on a component in your stylesheet.
+
+```css
+cs-avatar {
+  --size: 6rem;
+}
+```
+
+This will also work if you need to target a subset of components with a specific class.
+
+```css
+cs-avatar.your-class {
+  --size: 6rem;
+}
+```
+
+Alternatively, you can set them inline directly on the element.
+
+```html
+<cs-avatar style="--size: 6rem;"></cs-avatar>
+```
+
+The custom properties exposed by each component can be found in the component's API documentation.
+
+### Custom States
+
+Components can expose custom states that allow you to style them based on their current condition using the `:state()` selector. Custom states provide a way to target specific component states that aren't covered by standard pseudo-classes like `:hover` or `:focus`.
+Here's an example that styles a checkbox that's checked.
+
+```css
+cs-checkbox:state(checked) {
+  outline: dotted 2px tomato;
+}
+```
+
+Custom states can be combined with CSS parts and custom properties to create sophisticated customizations. The custom states exposed by each component can be found in the component's API documentation under the "Custom States" section.
+
+### Native Elements
+
+If you're using [native styles](https://cruglobal.github.io/cornerstone-design-system/utilities/native), any custom styles added for a component should also target the corresponding native element. In general, the same styles you declare for components will work just the same to style their native counterparts.
+
+For example, we can give `<input type="checkbox">` the same custom styles as `<cs-checkbox>` by using standard CSS properties and CSS parts:
+
+```html
+<cs-checkbox class="pinkify">Cornerstone checkbox</cs-checkbox>
+<br />
+<label>
+  <input type="checkbox" class="pinkify" />
+  HTML checkbox
+</label>
+
+<style>
+  cs-checkbox.pinkify::part(control),
+  input[type='checkbox'].pinkify {
+    border-width: 3px;
+  }
+
+  cs-checkbox.pinkify:state(checked)::part(control),
+  input[type='checkbox'].pinkify:checked {
+    background-color: hotpink;
+    border-color: hotpink;
+    color: lavenderblush;
+  }
+</style>
+```

package/dist/unbundled/skills/cornerstone/references/form-controls.md

@@ -0,0 +1,188 @@
+# Form Controls
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/form-controls
+
+Cornerstone form controls are form-associated custom elements, meaning they will submit with forms just like native `<form>` controls. They also support constraint validation, which is the platform's version of client-side form validation.
+
+## Constraint Validation
+
+Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Cornerstone form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. Cornerstone implements many of the same attributes as native form controls, but check the documentation for a list of supported properties for each component.
+
+If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `<form>` element.
+
+And if this syntax looks unfamiliar, don't worry! Most of what you're learning on this page is platform knowledge that applies to native form controls, too.
+
+> **Warning**
+>
+> Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. You should always validate and sanitize user input on the server!
+
+### Required Fields
+
+To make a field required, use the `required` attribute. Required fields will automatically receive an asterisk after their labels. The form will not be submitted if a required field is incomplete.
+
+```html
+<form class="input-validation-required">
+  <cs-input name="name" label="Name" required></cs-input>
+  <br />
+  <cs-select label="Favorite Animal" with-clear required>
+    <cs-option value="birds">Birds</cs-option>
+    <cs-option value="cats">Cats</cs-option>
+    <cs-option value="dogs">Dogs</cs-option>
+    <cs-option value="other">Other</cs-option>
+  </cs-select>
+  <br />
+  <cs-textarea name="comment" label="Comment" required></cs-textarea>
+  <br />
+  <cs-checkbox required>Check me before submitting</cs-checkbox>
+  <br /><br />
+  <cs-button appearance="filled" type="submit" variant="neutral">Submit</cs-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-required');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('cs-button'),
+    customElements.whenDefined('cs-checkbox'),
+    customElements.whenDefined('cs-input'),
+    customElements.whenDefined('cs-option'),
+    customElements.whenDefined('cs-select'),
+    customElements.whenDefined('cs-textarea'),
+  ]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+  });
+</script>
+```
+
+#### Styling the Required Indicator
+
+The asterisk is drawn with three [design tokens](https://cruglobal.github.io/cornerstone-design-system/tokens/component-groups#form-controls). Override them to change the character, its color, and the space between it and the label.
+
+- [`--cs-form-control-required-content`](https://cruglobal.github.io/cornerstone-design-system/tokens/component-groups#token-cs-form-control-required-content) - the content appended to the label, e.g. `'*'`
+- [`--cs-form-control-required-content-color`](https://cruglobal.github.io/cornerstone-design-system/tokens/component-groups#token-cs-form-control-required-content-color) - the indicator's color
+- [`--cs-form-control-required-content-offset`](https://cruglobal.github.io/cornerstone-design-system/tokens/component-groups#token-cs-form-control-required-content-offset) - the inline space between the label and the indicator
+
+```html
+<form class="custom-required-indicator">
+  <cs-input name="name" label="Name" required></cs-input>
+</form>
+
+<style>
+  .custom-required-indicator {
+    --cs-form-control-required-content: '(required)';
+    --cs-form-control-required-content-color: var(--cs-color-danger-on-quiet);
+    --cs-form-control-required-content-offset: 0.5em;
+  }
+</style>
+```
+
+Set `--cs-form-control-required-content` to `''` to remove the indicator.
+
+### Input Patterns
+
+To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern), use the `pattern` attribute. This example only allows the letters A-Z, so the form will not submit if a number or symbol is entered. This only works with `<cs-input>` elements.
+
+```html
+<form class="input-validation-pattern">
+  <cs-input name="letters" required label="Letters" pattern="[A-Za-z]+"></cs-input>
+  <br />
+  <cs-button appearance="filled" type="submit" variant="neutral">Submit</cs-button>
+  <cs-button appearance="filled" type="reset" variant="neutral">Reset</cs-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-pattern');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([customElements.whenDefined('cs-button'), customElements.whenDefined('cs-input')]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+  });
+</script>
+```
+
+### Input Types
+
+Some input types will automatically trigger constraints, such as `email` and `url`.
+
+```html
+<form class="input-validation-type">
+  <cs-input type="email" label="Email" placeholder="you@example.com" required></cs-input>
+  <br />
+  <cs-input type="url" label="URL" placeholder="https://example.com/" required></cs-input>
+  <br />
+  <cs-button appearance="filled" type="submit" variant="neutral">Submit</cs-button>
+  <cs-button appearance="filled" type="reset" variant="neutral">Reset</cs-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-type');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([customElements.whenDefined('cs-button'), customElements.whenDefined('cs-input')]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+  });
+</script>
+```
+
+### Custom Error Messages
+
+To create a custom validation error, pass a non-empty string to the `setCustomValidity()` method. This will override any existing validation constraints. The form will not be submitted when a custom validity is set and the browser will show a validation error when the containing form is submitted. To make the input valid again, call `setCustomValidity()` again with an empty string.
+
+```html
+<form class="input-validation-custom">
+  <cs-input label="Type cornerstone" required></cs-input>
+  <br />
+  <cs-button appearance="filled" type="submit" variant="neutral">Submit</cs-button>
+  <cs-button appearance="filled" type="reset" variant="neutral">Reset</cs-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-custom');
+  const input = form.querySelector('cs-input');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([customElements.whenDefined('cs-button'), customElements.whenDefined('cs-input')]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+
+    input.addEventListener('input', () => {
+      if (input.value === 'cornerstone') {
+        input.setCustomValidity('');
+      } else {
+        input.setCustomValidity("Hey, you're supposed to type 'cornerstone' before submitting this!");
+      }
+    });
+  });
+</script>
+```
+
+> **Info**
+>
+> Custom validation can be applied to any form control that supports the `setCustomValidity()` method. It is not limited to inputs and textareas.
+
+## Custom Validation Styles
+
+Due to the many ways form controls are used, Cornerstone doesn't provide out of the box validation styles for form controls as part of its default theme.
+
+Instead, the following [custom states](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states) will be applied to reflect a control's validity as users interact with it. You can use them to create custom styles for any of the validation states you're interested in.
+
+- `:state(required)` - the form control is required
+- `:state(optional)` - the form control is optional
+- `:state(invalid)` - the form control is invalid
+- `:state(valid)` - the form control is valid
+- `:state(user-invalid)` - the form control is invalid and the user has interacted with it
+- `:state(user-valid)` - the form control is valid and the user has interacted with it
+
+These custom states work alongside the browser's built-in pseudo classes for validation: [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required), [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional), [`:invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid), [`:valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:valid), [`:user-invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-invalid), and [`:user-valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-valid).

package/dist/unbundled/skills/cornerstone/references/frameworks/rails.md

@@ -0,0 +1,206 @@
+# Ruby on Rails
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/frameworks/rails
+
+<div class="cs-cluster cs-gap-2xs cs-not-prose">
+  <cs-badge variant="success" appearance="filled" pill>
+    <cs-icon name="check_circle" slot="start"></cs-icon>Verified on Rails 8.1
+  </cs-badge>
+  <cs-badge variant="neutral" appearance="filled" pill>Propshaft</cs-badge>
+  <cs-badge variant="neutral" appearance="filled" pill>Turbo</cs-badge>
+</div>
+
+Rails renders HTML on the server, and a custom element *is* an HTML element — so there is no integration
+layer to write. A Rails view can use `cs-*` tags the moment the browser has the library.
+
+Getting it there has one wrinkle, and it is worth understanding before you copy anything: **Cornerstone's
+autoloader builds asset URLs at runtime, and Propshaft fingerprints every file it serves.** Those two facts
+do not compose, so the asset pipeline is the wrong home for the JavaScript.
+
+## Serve the library from `public/`
+
+The split builds resolve components in two stages, and Propshaft breaks the earlier one.
+
+Each entry file is a stub of *relative* chunk imports — `cornerstone.loader.js` opens with 17
+`./chunks/chunk.*.js` specifiers, and a component file with around 40. The browser resolves those against the
+importing module's own URL, and nothing rewrites them: Propshaft renames the files but does not touch JS
+import specifiers. So under digest-only serving every chunk 404s and **the loader never executes at all**.
+Measured: 17 module 404s and no library code running. Setting a base path makes no difference, because the
+failure is below it.
+
+If you get past that, the autoloader imports `{basePath}/components/{tag}/{tag}.js` when it sees an
+unregistered `cs-*` tag, and Propshaft has renamed that file too. That second failure *is* reported — the
+console shows `Unable to autoload <cs-button> from /components/button/button.js` — but the first one shows only
+a wall of anonymous 404s with no mention of Cornerstone, which is why this is easy to lose an hour to.
+
+You have two ways out. Either serve the library from `public/`, which is the simple path, or use the
+single-file build, which is the one artifact a fingerprinting pipeline can serve.
+
+### Option 1: the single-file build, fingerprinted
+
+`cornerstone.all.js` is every component in one file — no chunks, no dynamic import, no URL built at runtime.
+That makes it an ordinary asset, so Propshaft can fingerprint it like any other:
+
+```bash
+npm install @cruglobal/cornerstone-components
+cp node_modules/@cruglobal/cornerstone-components/dist/bundled/cornerstone.all.js app/assets/javascript/
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<%= javascript_include_tag "cornerstone.all", type: "module", "data-turbo-track": "reload" %>
+```
+
+Verified against a digest-only pipeline: every component upgrades, no failed requests, clean console.
+
+The trade is size. It is 188 KB gzipped, fixed, because it contains all 70 components whether you use them or
+not. A page using one button costs about 57 KB gzipped through the loader instead. Break-even is somewhere
+around a dozen components, so an application shell probably wins and a marketing page probably loses.
+
+### Option 2: serve the split build from `public/`
+
+Files under `public/` are served verbatim, which sidesteps the problem entirely:
+
+```bash
+npm install @cruglobal/cornerstone-components
+cp -R node_modules/@cruglobal/cornerstone-components/dist/bundled public/cornerstone
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<link rel="stylesheet" href="/cornerstone/styles/cornerstone.css">
+<script type="module" src="/cornerstone/cornerstone.loader.js"></script>
+```
+
+That is the whole setup. The loader resolves its base path from its own module URL, so there is no
+`setBasePath` call and no `data-cornerstone` attribute to add.
+
+What this actually costs is smaller than it sounds. A page with one button fetches 43 files, and 40 of the 42
+JavaScript files — 98.4% of the gzipped bytes — are **already content-hashed by our own build**. The only two
+undigested files are `cornerstone.loader.js` and the component itself: 921 gzipped bytes. So you are not
+opting out of caching for the library, you are opting out for under a kilobyte of it.
+
+Use the **bundled** build, as above. The unbundled one keeps nine dependencies as bare specifiers — `lit`,
+`@floating-ui/dom`, `@shoelace-style/localize` and six more — which the browser cannot resolve without an
+import map covering every one. The bundled build inlines them. Copy the whole directory either way: the
+loader fetches each component at runtime, so a lone `cornerstone.loader.js` does nothing.
+
+### Fingerprinting the stylesheet, if you want it
+
+The CSS has no runtime URL construction, so it *can* go through Propshaft and benefit from fingerprinting.
+Drop the library's `styles/` directory into `app/assets/` and reference it by logical path:
+
+```erb
+<%= stylesheet_link_tag "cornerstone", "data-turbo-track": "reload" %>
+```
+
+Rails adds each direct subdirectory of `app/assets` to the load path as its own root. Copied as
+`app/assets/styles`, that directory *is* the root, so the logical path is `cornerstone` — the directory name
+does not appear in it. Propshaft rewrites the nested `@import` chain — `cornerstone.css` pulls in the layers,
+the theme, and the theme's palette and variants — so all of it resolves fingerprinted.
+
+> **Warning**
+>
+> **`stylesheet_link_tag :app` will flat-link every file you put here.** Rails 8's generated layout includes
+> `stylesheet_link_tag :app`, which Propshaft expands to every `.css` file under `app/assets`. After this copy a
+> page goes from **1 stylesheet link to 32** — each internal partial linked separately, unordered, outside the
+> `@import` cascade the library builds. It still renders, because the partials are idempotent and
+> `cornerstone.css` is among them, but it is 31 wasted requests. Either drop `:app` from the layout, or keep the
+> stylesheet in `public/` alongside the components.
+
+## Import maps
+
+`importmap-rails` does not help here and is not needed. The loader is reached by a plain `<script>` tag from
+a stable URL, so there is nothing to pin, and pinning it *through* the asset pipeline reintroduces the digest
+problem above.
+
+If you pin components directly instead of using the autoloader, pass `preload: false`. `pin_all_from`
+defaults to `preload: true`, which emits a `<link rel="modulepreload">` per file on every page — pointed at
+70 components that is 70 requests queued on one connection whatever the page renders. `moa`'s own
+`config/importmap.rb` documents this after it cost that app 159 module requests per page load.
+
+## Icons
+
+`<cs-icon>` does **not** use the library's base path. Icons come from a CDN by default — a page using
+`check_circle` fetches `https://cdn.jsdelivr.net/npm/@material-symbols/svg-400@…/sharp/check_circle.svg` —
+so no extra setup is needed, but the requests do leave your origin. To serve them yourself, use
+`setIconPath` — see [`<cs-icon>`](https://cruglobal.github.io/cornerstone-design-system/components/icon) for the directory layout it expects.
+
+## Turbo
+
+Turbo Drive replaces `<body>` rather than reloading the page. Custom elements handle that on their own —
+`customElements.define` is global, so elements in the new body upgrade as they are parsed, and the autoloader
+keeps working across navigations.
+
+What needs handling is the flash between visits: Turbo swaps in the new body before its components have
+registered, so they paint unstyled for a frame or two. Cornerstone ships an API for exactly this:
+
+```js
+// app/javascript/application.js
+import { preventTurboFouce } from '/cornerstone/cornerstone.js';
+
+preventTurboFouce();
+```
+
+It hooks `turbo:before-render`, holds the render until every component in the incoming body has registered,
+and gives up after two seconds so a failed import cannot wedge navigation. Pair it with the `cs-cloak` class
+for the initial load — both are covered on [Reducing FOUCE](https://cruglobal.github.io/cornerstone-design-system/utilities/fouce).
+
+## Stimulus
+
+Cornerstone's events are ordinary DOM events that bubble and compose, so a Stimulus action descriptor takes
+them directly:
+
+```erb
+<div data-controller="filters">
+  <cs-select data-action="change->filters#apply">
+    <cs-option value="all">All</cs-option>
+  </cs-select>
+</div>
+```
+
+The action needs a `data-controller` scope on the element or an ancestor, as any Stimulus action does — without
+it nothing fires.
+
+```js
+// app/javascript/controllers/filters_controller.js
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller {
+  apply(event) {
+    console.log(event.target.value);
+  }
+}
+```
+
+Note the event name. Form controls emit **native-named** events — `change`, `input`, `focus`, `blur` — so a
+Stimulus action for `<cs-select>` reads exactly as it would for a native `<select>`. The `cs-` prefix is
+reserved for events with no native equivalent, like `<cs-select>`'s own `cs-clear`.
+
+Read the value off the element rather than the event, as you would natively: `event.target.value`.
+
+## What has been verified
+
+> **Info**
+>
+> Checked in a generated Rails 8.1.3.1 app with Propshaft, importmap-rails and Turbo:
+>
+> - **`public/` setup** — the button registered, upgraded, rendered at its themed size, and the base path
+>   auto-detected as `/cornerstone`.
+> - **The digest problem** — reproduced both halves. Propshaft's own load path reports
+>   `components/button/button-166a237e.js`, and the undigested URL the autoloader requests returns 404.
+>   It is **not** silent: the autoloader logs one `console.warn` per component,
+>   `Unable to autoload <cs-button> from /components/button/button.js`. That warning, not the 404, is the thing
+>   to look for.
+> - **`preventTurboFouce` across a real Turbo visit** — with the call in place, the incoming body's components
+>   were registered before render (`cs-card` had its shadow root); with it removed, the same navigation rendered
+>   them unregistered. It holds the render exactly as advertised.
+> - **Propshaft for the stylesheet** — the theme's fonts applied, so the `@import` chain resolved. The logical
+>   path and the `:app` behaviour above were both measured against Propshaft's own resolver.
+>
+> Two things worth knowing before you copy into `public/`: `npm install` in a generated Rails app creates a
+> `package.json` and lock file at the app root, since one does not exist; and the copy is **11 MB across 1,114
+> files, all web-served** — 350 `.d.ts`, 142 React wrappers and the agent skill included. A three-component page
+> issues roughly 50 requests.
+>
+> **Not yet verified:** the `jsbundling-rails` path, and `setIconPath` against self-hosted SVGs.