| # 11. Browser integration |
|
|
| This chapter is informative. It says how a browser could host DSSL natively, stage by stage, |
| and which parts are cheap and which are real engineering. Nothing here is proposed to a |
| standards body, no browser implements it, and the reference crate has not been wired into any |
| engine. It is written so that a browser team can judge the size of the job. |
|
|
| ## 11.1 Delivery |
|
|
| DSSL needs a way to reach the parser, the way CSS has `<link rel="stylesheet">` and `<style>`. |
|
|
| - **INT-1.** A DSSL stylesheet is text with the media type `text/dssl`. (No registration is |
| proposed. This is a placeholder name.) |
| - **INT-2.** `<link rel="stylesheet" type="text/dssl" href="...">` and |
| `<style type="text/dssl">...</style>` load DSSL. A browser that does not know the type does |
| not load it, which is how CSS has always been introduced. |
| - **INT-3.** Several stylesheets are one cascade in load order (CAS-16), the same as CSS. |
| Tokens and motions flow from earlier files to later ones (4.5, 7.3) in that order. |
|
|
| Authors who need a page to work in a browser with no DSSL support can ship the output of |
| `dssl build` as CSS. That is the *static lane*. It is an author's choice, not a part of native |
| support, and it is described in 11.5. |
|
|
| ## 11.2 Where the parser sits |
|
|
| In every engine, a stylesheet becomes a list of rule objects, and nothing after that stage |
| cares what syntax the rules came from. A DSSL front end replaces the tokenizer and parser (CSS |
| stage 1) and produces the same kind of rule objects. |
|
|
| ``` |
| CSS text --> CSS tokenizer + parser --\ |
| >--> rule objects --> style resolution --> layout --> paint |
| DSSL text --> DSSL parser + resolver --/ |
| ``` |
|
|
| - **INT-4.** The resolved document (chapter 10) is the hand-off. Each rule record maps to an |
| engine rule: `sel` to the selector list, `decls` to the declaration block, `layer` to a |
| cascade layer, `media` and `containers` to conditional wrappers, and `order` to source order. |
| - **INT-5.** Engine-native declarations (`@...`, 6.8) are not properties. They go to the feature |
| that owns them (11.4), not to the style system's property table. |
|
|
| This is also how new CSS syntax has entered engines before. Nesting and cascade layers are |
| parsed into the same rule tree as everything else. |
|
|
| ## 11.3 The part that lowers to CSS |
|
|
| A large part of DSSL is already expressible in CSS. The proof is `dssl build`, which does exactly |
| that. Here is real output, from the reference engine, for a small source: |
|
|
| ```dssl |
| tokens { color { brand: #c2185b } } |
| .card { |
| background: color.brand |
| padding: 16 |
| row: gap 8 between center |
| radius: md |
| hover { background: color.brand/80 } |
| @media dark { background: #181310 } |
| } |
| ``` |
|
|
| compiles to the following (reformatted, and without the built-in token declarations): |
|
|
| ```css |
| @layer tokens, base, components, utilities, pin; |
| |
| @layer tokens { |
| :where(:root) { --dssl-color-brand: #c2185b; } |
| } |
| |
| @layer components { |
| :where(.card) { |
| background: var(--dssl-color-brand); |
| padding: 16px; |
| display: flex; |
| flex-direction: row; |
| gap: 8px; |
| justify-content: space-between; |
| align-items: center; |
| border-radius: var(--dssl-radius-md); |
| } |
| :where(.card:hover) { |
| background: color-mix(in oklab, var(--dssl-color-brand) 80%, transparent); |
| } |
| @media (prefers-color-scheme: dark) { |
| :where(.card) { background: #181310; } |
| } |
| } |
| ``` |
|
|
| The mapping: |
|
|
| | DSSL | CSS it lowers to | |
| |---|---| |
| | tokens | custom properties on `:root`, inside `@layer tokens` | |
| | layers and `pin` | `@layer`, with `!important` for `pin` | |
| | no specificity | every selector wrapped in `:where()` so order alone decides | |
| | states | pseudo-classes | |
| | `@media`, `@container` | the same at-rules | |
| | semantic properties (`row`, `grid`, `radius`, `fluid`, ...) | longhand properties and `clamp()` | |
| | alpha (`color.ink/20`) | `color-mix(in oklab, ..., transparent)` | |
| | `motion` | `@keyframes` | |
| | `raw` | verbatim | |
| | `glass` | `backdrop-filter` and a background color | |
|
|
| - **INT-6.** A native engine MAY implement this part by lowering to its own CSS rule objects. |
| The result must equal the cascade of chapter 5. In particular, the `:where()` wrapping is how |
| CSS reproduces "no specificity", and the layer ranks reproduce CAS-1. |
|
|
| ## 11.4 The part that needs engine work |
|
|
| | Feature | What is missing from CSS | What a native engine adds | |
| |---|---|---| |
| | `@signal` | Named values set by the page, readable by the cascade | A page-visible store of named values, with ancestor lookup (CAS-39), invalidating style when one changes. The nearest CSS feature is a container style query on a custom property. Support differs between engines and must be checked before relying on it. | |
| | `seen` | A pseudo-class that matches once an element has been in view | An element flag set by the same machinery as intersection observation, and style invalidation when it flips (CAS-27). | |
| | `animate` | Per-element motion lists with `jitter`, `essential` and `stagger` | Mapping to the engine's keyframe animation, with a delay offset per child. `essential` and reduced motion are policy on top. | |
| | `texture` | A generated image layer that sits on the author's own background | A background image generator keyed by the layer record (FX-7), cached per tile. | |
| | `aura` | Glow and particles outside the box, over everything, with a particle budget | A page-level paint layer above content that does not take pointer events, with the budget of FX-18. | |
| | `slider` | One description for all engines' range-input parts | Direct styling of the control parts, plus a value-as-fraction the style can read (FX-27). | |
| | `tilt` | Pointer-driven 3D transform without restyling | A compositor-driven transform from pointer position (FX-32). | |
| | `bend`, `fold`, `bend-around` | Transforms that need the element's own box, or a container's children | These run during or after layout, because they need box sizes (FX-37, FX-38). | |
| | `overlap` | A rule that moves elements out of overlaps | Hook after layout (FX-40). This is the hardest item and is not specified yet. | |
| | alignment promotion | A box type chosen from an alignment word | Rule CAS-47 at computed-value time. | |
|
|
| - **INT-7.** For each row, the spec's description half (chapter 8) and corpus fixes what the |
| feature means. How the engine realises it is the engine's business, as long as the rendering |
| contract holds. |
|
|
| ## 11.5 The static lane and native support |
|
|
| `dssl build` already exists. Today it is the exit lane for pages that need no JavaScript. With |
| native support, the rows of 11.3 stop needing it, because the browser lowers them itself. What |
| stays on the author's side is what 11.4 lists and nothing else. |
|
|
| The build report already counts those leftovers (`@signal` rules, engine-native declarations), |
| so it is a ready measure of how much of a given page is the cheap part and how much is the |
| engine-work part. |
|
|
| ## 11.6 How a browser team would check their work |
|
|
| - Level 1 and 2: run the corpus (chapter 10). The expected JSON is committed. No browser |
| needed. |
| - Level 3: element-level tests, in the style of the web platform tests. A fixture is a small |
| HTML file, a DSSL file and the expected computed value of chosen properties on chosen |
| elements. These do not exist yet. They are the first thing to write after milestone 1. |
| - Level 4: reftests, comparing a rendering to a reference rendering, and pixel tests for the |
| effects (the repository already has pixel helpers in `scripts/lib/pixels.mjs`). |
|
|
| ## 11.7 What is not claimed |
|
|
| - No browser supports DSSL natively today, and this repository does not change that. |
| - The reference crate does not exist yet beyond a stub (see `native/README.md`). When it does, |
| it will parse and resolve. It will not match elements, compute styles or paint. |
| - The lowering table in 11.3 is the claim of the existing build lane, checked by the repository's |
| static parity test. It has not been run in browsers other than Chromium. |
|
|
