Skip to content

Documents the host asset pipeline and theming - #84

Merged
johnnyt merged 1 commit into
mainfrom
sui-191-embedding-theming-verification
Sep 2, 2026
Merged

Documents the host asset pipeline and theming#84
johnnyt merged 1 commit into
mainfrom
sui-191-embedding-theming-verification

Conversation

@johnnyt

@johnnyt johnnyt commented Sep 2, 2026

Copy link
Copy Markdown
Member

Closes the ADR-0009 embedding story's verification gap: until now nothing had
compiled this package's JavaScript in a bundler, and the guide described a
theming surface nobody had styled against.

What was exercised

A throwaway host, removed after the run. Nothing outside this repo was written.

  1. mix hex.build --unpack from this branch. The tarball does ship
    assets/package.json, assets/js/index.js, assets/js/expression_input.js
    • the embedding story depends on that and it holds today.
  2. The unpacked tarball placed at <host>/deps/statifier_ui, and the host's
    own assets/package.json declaring
    "statifier_ui": "file:../deps/statifier_ui/assets". npm install linked
    node_modules/statifier_ui -> ../../deps/statifier_ui/assets.
  3. The host's own esbuild bundled it. The metafile's inputs are
    ../deps/statifier_ui/assets/js/index.js and
    ../deps/statifier_ui/assets/js/expression_input.js; the output is
    priv/static/assets/app.js, 6.6kb.
  4. A page served on a private loopback port carrying the components' real
    rendered markup - ops_view/1 and expression_input/1 rendered through
    Phoenix.LiveViewTest, not hand-typed HTML - plus a host stylesheet written
    only against the documented classes. The hook mounted, stamped
    data-hook="attached", and built the completion popup, which the host
    stylesheet then themed. First time this package's JavaScript has run outside
    a test.

What the guide gained

  • The asset pipeline: how the JavaScript reaches a host's bundler, what the
    tarball ships, that npm install links rather than copies, and what a
    Node-free host still gets (working, unenhanced markup - every component has a
    no-JavaScript affordance).
  • Theming, by grep rather than memory: no component reads a CSS custom
    property, a var(), a data-theme, or a prefers-color-scheme. That is the
    contract, not a gap in it - the host owns the palette outright. All 38 classes
    lib/ and assets/ render or build are now enumerated, including the popup
    selectors the hook creates at runtime that appear in no template.
  • The fallback contract: an embedder may render its own surfaces off trace
    wire format v1 at three levels - recompose the panes, keep the read model and
    drop the markup, or take the messages - and is never locked into the shipped
    components. The two obligations that travel with the third level (never
    present a partial stream as whole, never present a carried configuration as a
    measured one) are stated, because they are properties of the data rather than
    of these components.

Corrections

  • The guide said "This package ships no JavaScript" while explaining the Mermaid
    pane. True until assets/ landed; now scoped to the Mermaid client.
  • StatifierUI.Diagram's classDef active bakes literal Mermaid colours into
    the diagram source, so the active-configuration highlight is unreachable from
    a host stylesheet and stays light under a dark theme. Recorded as a known gap
    rather than fixed - it is a lib/ change and outside this bead.

Notes

Docs only. No path under lib/, test/, config/, mix.exs, mix.lock,
assets/, or docs/wire-format.md changed, so the local gate carve-out applies
and no mix quality ran; CI replays the full gate on this request. No changelog
fragment: documentation is on changelog.d/README.md's do-not-write list.

Rebased onto main after sui-pb2's trace-capture landed; no conflict, and the
class enumeration re-verified against grep on the rebased HEAD.

Exercises the ADR-0009 embedding story end to end in a throwaway
Phoenix-shaped host: the hex tarball this branch builds, unpacked to
deps/, pulled in as "statifier_ui": "file:../deps/statifier_ui/assets",
bundled by the host's own esbuild, and served with the components'
real rendered markup. The hook attaches and the completion popup opens
over it, which is the first time this package's JavaScript has been
run outside a test.

Three things the guide could not say before:

- how the JavaScript reaches a host's bundler, what the tarball ships,
  and what a Node-free host still gets
- what a stylesheet can reach. No component reads a CSS custom
  property, a data-theme, or a prefers-color-scheme, so the class and
  data-attribute contract is the whole theming surface; every class
  the package renders or the hook builds is now listed, including the
  popup selectors no template renders
- the fallback contract: a host renders its own surfaces off trace
  wire format v1 and is never locked into the shipped components,
  with the two obligations that come with doing so

Also corrects a claim the guide made about shipping no JavaScript,
true until assets/ landed, and records that the diagram's Mermaid
classDef carries literal colours no host stylesheet can reach.

Refs: sui-191
@johnnyt
johnnyt merged commit d826514 into main Sep 2, 2026
1 check passed
@johnnyt
johnnyt deleted the sui-191-embedding-theming-verification branch September 2, 2026 18:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant