$ show w3c/css-houdini-drafts
This is the working repository of the W3C CSS Houdini Task Force: a collection of editor's drafts (specifications) for browser APIs that expose CSS internals to JavaScript. The content is written in Bikeshed (.bs) format and processed by a Python build pipeline (bin/build-markdown.py, bin/build-index.py, Makefiles, GitHub Actions) into the HTML specs served via GitHub Pages. The repository contains formal, normative algorithm definitions for the CSS Paint API (registerPaint), CSS Layout API (registerLayout), CSS Animation Worklet (registerAnimator), CSS Properties & Values API, CSS Typed OM, Font Metrics API, Box Tree API, and Worklets. It is not a runtime application or a data pipeline — it is documentation-as-code with build automation and small runnable examples — but it is classified as "application" because its dominant content is executable artifacts (worklet demo code, CI scripts, build tooling) rather than data assets. The highest-craft content is in the spec sources: the CSS Typed OM draft defines a complete, self-contained algebra for CSS numeric values (base types, percent hints, sum values, unit conversion, canonical units) plus a reify/serialize pair that converts between internal CSS representations and typed JavaScript objects. The CSS Layout API draft specifies a work-queue processing model, global scope selection, and structured serialization for worklet data — all reusable algorithmic patterns for browser-engine implementers and polyfill authors. The included paint-worklet demos (circle, arc, chat) are isolated, copy-pasteable examples of the registerPaint contract. Maintenance is active: the last commit is recent, the Typed OM changes section references live GitHub issues/PRs, and the CI installs pinned dependencies. However, there is notable internal drift: css-parser-api has been moved to WICG (its Overview.bs is blank), worklets/Overview.bs now redirects to the HTML Standard, scroll-customization-api remains an explainer without a formal spec, and several Typed OM reification entries are explicitly empty stubs or marked with open issue markers. The 2018 issue-list artifacts and README_old.md files add historical clutter. For engineers, the practical value is threefold: (1) reference implementations of the Houdini API surface for anyone building polyfills, browser features, or CSS tooling; (2) a clean, reusable Bikeshed-spec build/deploy pipeline (Python scripts + GitHub Action) that can be extracted to any W3C-style spec repo; and (3) minimal worklet starter examples. It is not code you deploy — it is a standards workshop, and the quality bar is standards-writing rigor rather than software architecture.
The LLM identified 4 files worth highlighting for reuse:
Defines the complete formal type system for CSS numeric values — base types, percent hints, compatible unit conversion, and sum values — plus the reify/serialize pair that maps between internal CSS representations and typed JavaScript objects. These algorithm definitions are explicitly designed for cross-spec reuse (CSS Values & Units and other Houdini specs import them). Any engineer building a CSS parser, polyfill, or browser-engine CSSOM implementation can extract this as the authoritative model for typed CSS value handling. Demonstrates non-obvious skill in formalizing a subtle domain model with exhaustive per-property rules.
Specifies the CSS Layout API's registerLayout() contract, including the work-queue processing model, global scope selection, intrinsic-size and layout callback invocation algorithms, fallback-to-flow-layout semantics, and structured serialization of worklet data. The processing-model algorithms and work-queue patterns are self-contained and reusable as a reference for implementing any worklet-based extension API in a browser engine or embedding the layout contract in a JS layout engine.
Python script that converts Bikeshed .bs specification sources into Markdown output, used as part of the repo's build pipeline alongside a GitHub Actions workflow. It is a self-contained, parameterized build tool that can be extracted to any spec-driven or documentation-as-code repository using Bikeshed, eliminating the need to reverse-engineer Bikeshed's output conventions.
A minimal, self-contained CSS Paint API worklet demonstrating the registerPaint() contract: a paint callback class that draws a circle into the provided PaintRenderingContext2D. It is an isolated, copy-pasteable starter template for anyone implementing or testing paint worklets, and it codifies the exact registration and callback signatures a worklet global scope must expose.