Web components that land in your Hologram actions

Every host rewrites the same shim

A custom element does the right thing: it emits a composed CustomEvent that bubbles out of its shadow root. A server-driven UI framework has no template syntax to bind it. So the widget works, the framework works, and the seam between them is yours to write by hand.

Today that means a JS shim like this one, living somewhere in your assets:

document.addEventListener("persona-select", (event) => {
Hologram.dispatchAction("chose", "page", {
  persona_id: event.detail.personaId,   // camelCase to snake_case, by hand
  click_count: event.detail.clickCount,
});
});

Every key translated by hand. Every host re-derives it. And it sits next to the other afternoon-cost surprises: shadow-DOM event retargeting, kebab versus camel versus snake, js_import paths that resolve against the caller's file. That last one is a fact everyone learns exactly once.

tessera replaces the shim with one generated attribute:

data-tsr-on="persona-select:chose@page"

The bridge that reads it ships with the library. The alternatives today are re-implementing the widget natively or skipping it. There is a fourth option: make the seam a versioned contract that mix compile writes for you. That is tessera.

The spec is the source of truth

One module declares the component. Five macros describe the wire surface: attr, prop (with json:), event, slot, cy. Everything else on this page is generated from it. (Tier 1 components also declare their behavior in the same module with state, template and action; see the code.)

defmodule MyApp.Components.PersonaCard do
use Noizu.Tessera.Component,
tag: "persona-card",
js: "persona_card.mjs"

attr :display_name, :string, required: true
attr :disabled, :boolean, default: false

prop :tag_list, :list, json: true, default: []

event "persona-select", detail: %{persona_id: :string, click_count: :integer}

slot "default"
cy "persona-card-root"
end

export default {
version: 1,
tag: "persona-card",
attrs:  [{ name: "display-name", key: "displayName", type: "string", required: true, default: null }],
props:  [{ name: "tagList", type: "list", json: true, default: [] }],
events: [{ name: "persona-select", detail: {personaId: "string", clickCount: "integer"} }],
slots:  ["default"],
cy: "persona-card-root",
};

<persona-card
display-name="Ada"
tsr-props='{"tagList":["a","b"]}'
data-tsr-on="persona-select:chose@page;persona-hover:hover@picker1"
data-cy="persona-card-root"></persona-card>

Hover any name. Its kebab attribute, camelCase key and spec atom light up together; they are one declaration in three places.

Names are checked at compile time, not discovered at runtime. A key must survive the snake_case to camelCase round trip byte-for-byte. col_2_width collapses to col2Width and back to col2_width, so the compiler rejects it and suggests the rename. The generated module is gitignored and content-compared: editing it by hand is futile, and recompiles only rewrite it when the spec actually changed. The compiler's own goldens are checked in; regenerating them is an explicit mix tessera.golden (--check in CI), so codegen drift fails a build instead of surprising a user.

The same compile step emits a Custom Elements Manifest (custom-elements.json, schema 1.0.0) for tooling. One spec, three artifacts, no drift between them.

What the compile step buys you

Suites (tessera develop, 2026-11-12): ExUnit 454 passed / 0 failed; Tier-1 conformance 55 passed / 0 failed / 26 pending; Tier-2 conformance 31 passing / 0 failing / 49 pending of 80. What works today.

What's in 0.2.0

The Lit-parity milestone, grouped by what you are trying to do. Every item below has a conformance case or an ExUnit test behind it; the limits are listed after.

Honest limits

• Pre-1.0: the API may still change
• Full Tier-2 Lit parity is not claimed; Tier 2 is a Hologram-runtime engine, not a Lit re-implementation
• SSR and Declarative Shadow DOM are proven in a spike, not shipped
• 40 Lit features are accepted gaps (Lit context among them; Signals is a design choice, built-in reactivity instead), each with a documented alternative in docs/notes/gap-acceptance.md

The 0.2.0 surface, in code

Four short examples. The Elixir ones mirror the conformance fixtures in the tessera repo, so the syntax is the syntax the compiler is tested against.

defmodule MyApp.Components.ClickCounter do
  use Noizu.Tessera.Component,
    tag: "click-counter",
    js: "click_counter.mjs"

  attr(:step, :integer, default: 1)
  state(:count, :integer, default: 0)
  event("count-changed", detail: %{count: :integer})
  cy("click-counter-root")

  styles(~CSS"""
  :host {
    display: inline-block;
    padding: var(--tsr-click-counter-padding, 8px);
  }
  .count { color: var(--tsr-click-counter-accent, #6cf); }
  """)

  template(~TSR"""
  <div data-cy="click-counter-root">
    <button type="button" $click={:bump}>+</button>
    <span class="count" part="count">{@count}</span>
  </div>
  """)

  action(:bump, fn state, _params ->
    emit("count-changed", %{count: state.count + @step})
    %{state | count: state.count + @step}
  end)
end

# Keep this file out of the base's directory:
# :inherit beside the base is a compile error.
defmodule MyApp.CounterExt do
  use VendorKit.ClickCounter, tag: :inherit, priority: 10

  event("count-doubled", detail: %{layer: :string})

  action(:bump, fn state, params ->
    emit("count-doubled", %{layer: "mine"})
    # next layer down, ultimately the vendor's own action
    base_action(:bump, state, params)
  end)
end

const el = document.querySelector("click-counter");

// First-registered interceptor is outermost.
// Return without calling next() to veto.
const off = el.onAction("bump", (params, next) => {
  analytics.tick("bump", params);   // params: camelCase
  return next({ ...params, step: 2 });
});

// Either casing; unknown names return { ok: false }
el.dispatchAction("bump", { step: 5 });

// Fresh frozen camelCase snapshot (snake_case reads alias)
console.log(el.state.count);

el.addEventListener("tsr-state-change", (e) => {
  console.log(e.detail.action, e.detail.keys);
});

off();   // unsubscribe

mix tessera.from_lit path/to/my-el.ts
mix tessera.from_lit src/my-element.ts   --out packages/my_element
mix compile   # writes the wire contract
# render() and methods are not converted; port by hand

Takeover is extension, not replacement: the base tag's conformance suite has to keep passing on the taken-over element. Details in Extend without forking the package.

From shadow DOM to action clause

The bridge is a document-level capture listener installed by the generated adapter. When an event fires it resolves the host element, parses its data-tsr-on, and dispatches. You write the action; nothing else.

defmodule MyPage do
use Hologram.Page
alias PersonaKit.PersonaCard

def template do
~HOLO"""
<PersonaCard display_name="Ada" on_persona_select={:chose} />
"""
end

def action(:chose, params, page), do: put_state(page, params)
end

<PersonaCard
cid="p1"
display_name="Grace Hopper"
on_persona_select={{:chose, target: "p1"}}
/>

Detail keys arrive snake_cased, converted recursively by the bridge before dispatch. If no binding matches, or no Hologram is on the page, the bridge does nothing and the event stays an ordinary DOM CustomEvent.

Two engines, one contract

One Elixir definition compiles into either engine, and both expose the same extension surface, so an extender never needs to know which one ran. You pick per component, not per project.

The rule that keeps this honest: neither tier approximates the other's core. Tier 1 cannot model the Hologram runtime; Tier 2 cannot model Lit's update lifecycle, directives or styles DSL. Both compile from the same definition into the same extension contract.

51 of Lit's 80 P0 features compile natively on Tier 1 in 0.2.0, 23 more are reachable through a sanctioned escape hatch, and the last 6 are accepted gaps with a reason on record: the Lit context protocol (use the bus seam), decorators (the output is decorator-free by design) and .d.ts generation. The update-time seam and the directive and author-CSS pipelines that used to be on the worklist have landed (will_update, updated, shouldUpdate, classMap, styleMap, the styles DSL). Across all 227 features, 40 are rejected by both tiers and accepted on purpose (34 with a hatch, 6 as design choices), including Lit context; Signals is a deliberate design choice (built-in reactivity instead). Each is documented as unsupported, not quietly missing. Full Tier-2 Lit parity is not claimed.

One tag, any host

To the browser, a tessera component is a standard custom element: a tag with a shadow root, attributes for scalars, a tsr-props JSON attribute for structured data, and CustomEvents dispatched with bubbles: true and composed: true so they cross the shadow boundary. The core package has no runtime dependencies; the Elixir side is the authoring layer and the Hologram bridge, and neither is required by the element at runtime.

<PersonaCard display_name="Ada" on_persona_select={:chose} />

The React path works the way any custom element does in React: render the tag, listen with addEventListener, no wrapper components. We label it an example because it is one; it is a documented snippet, not an executed test. The plain HTML host above is the e2e-tested one.

For tooling and non-Elixir consumers, mix tessera.manifest writes a standard Custom Elements Manifest (custom-elements.json, schema 1.0.0) from the same specs. If your source of truth is TypeScript, tessera is not your authoring layer; the wire contract is a plain, documented format you can target, and the manifest tells you what ships.

Extend without forking the package

The extension contract (EXTENSION-CONTRACT.md, v0.1) is the kit-vendor surface: a vendor ships a base element and consuming apps extend it without forking it. The contract's own thesis: the runtime is an implementation detail; the extension surface is the product. 0.2.0 implements it on both engines. First, the JS-side mechanisms that need no Elixir at all:

import { behaviors } from "@noizu/tessera-core/behaviors";

behaviors.add("persona-card", (el) => {
const onClick = () => el.classList.add("is-selected");
el.addEventListener("click", onClick);
el.dataset.enriched = "true";

return () => {
// runs on disconnect (Hologram re-renders may mount/unmount the host)
el.removeEventListener("click", onClick);
};
});

import { LitElement, html } from "lit";
import { TesseraElement } from "@noizu/tessera-core/element";
import { defineOnce } from "@noizu/tessera-core/define";
import contract from "./persona-card.contract.generated.mjs";

class MyPersonaCard extends TesseraElement(LitElement, contract) {
render() { /* your template */ }
}

// FIRST definition of the tag wins — register before the library's own
// module evaluates, or your class will be skipped (with one console.warn).
defineOnce("persona-card", MyPersonaCard);

import { emit } from "@noizu/tessera-core/events";
import { behaviors } from "@noizu/tessera-core/behaviors";

// persona-composer wraps <persona-card> in its own shadow root.
behaviors.add("persona-composer", (el) => {
const card = el.shadowRoot?.querySelector("persona-card");
if (!card) return;
const onPick = (e) => {
// Re-emit FROM THE OUTER ELEMENT so the composer's own
// data-tsr-on binding fires.
emit(el, "persona-select", { personaId: e.detail?.personaId ?? null });
};
card.addEventListener("persona-select", onPick);
return () => card.removeEventListener("persona-select", onPick);
});

This is not a footnote; it is the documented rule. When element B sits inside element A's shadow root and both bind the same event name, A's action fires and B's does not. Re-emitting from the outer element is the deliberate pattern, and persona-picker ships doing exactly that.

The contract surface — shipped in 0.2.0 (contract v0.1)

These APIs are implemented on both engines in 0.2.0, and the semantics are the spec's. The package is pre-1.0, so treat the surface as stable-ish rather than frozen. The conformance suite pins the behavior; where Tier 2 has cases still pending, the status board says so.

defmodule VendorKit.FilterListExt do
use Acme.FilterList, tag: :inherit, priority: 10, overrides: [:increment]
# layers overrides over the vendor element — nothing is substituted

def action(:increment, params, component) do
component = put_state(component, last_vendor_touch: true)
base_action(:increment, params, component)   # next layer down, ultimately the vendor base
end
end

action :increment, fn state, params ->
state = base_action(:increment, state, params)
%{state | last_vendor_touch: true}
end

Takeover is extension, never replacement. tag: :inherit registers under the base's own tag: inherited behavior keeps working, overrides sit on top, and the base tag's conformance suite must still pass — the gate that keeps "extend" from becoming "replace". Several extenders of one tag compose in a deterministic chain (dependency depth, then priority:, then module name; the vendor base sits innermost; conflicts warn at compile time naming both modules). Never last-wins. Fresh-tag derivation stays the default. One engine difference, stated up front: Tier-1 layers compose through real ES super; Hologram's IR has no super, so Tier-2 chains are linear and list their overrides with overrides:. Deriving across engines is a compile error, not a surprise.

Every action is open. el.dispatchAction(name, params) and el.onAction(name, interceptor) exist on every declared action; internal: true is advisory labeling, not access control. The trade-off is stated, not hidden: any page script can trigger any action, so guard destructive or costly ones inside the body, and name them like they are public, because they are — renaming or removing any action is a MAJOR version bump. el.state is a read-only camelCase snapshot with snake_case read aliases and a tsr-state-change event; onAction/dispatchAction accept either casing, and interceptors wrap the pipeline in onion order, first-registered outermost.

JS and any-framework extenders are first-class: behaviors.add, subclassing and onAction work with no Elixir and no recompilation. Same surface on both engines; an extender never tiers their overrides.

On the Elixir side, override __tessera_init__/2 (client) or __tessera_init__/3 (server) to seed state. Never override init/2 or init/3; the generated inits run the registration call, and a hand-written init written before them would shadow it and kill registration. (Source: docs/AUTHORING.md.)

Ship your widget kit as one hex package

tessera started the way yours probably did: the same component maintained twice, once as a JS element and once as a server-side component, drifting. The spec module is the fix. One declaration becomes the element, the contract, the manifest and the render glue.

mix tessera.gen.component persona-card --module MyApp.Components.PersonaCard
# writes lib/my_app/components/persona_card.ex (spec skeleton),
#       persona_card.mjs (element template — replace the body, keep register),
#       test/components/persona_card_test.mjs

use Noizu.Tessera.Package,
components: [MyApp.Components.PersonaCard]

mix tessera.manifest
# writes tessera-manifest.json + custom-elements.json (CEM 1.0.0)

The mix tasks are the whole workflow: tessera.install wires the JS side, tessera.gen.component scaffolds, tessera.manifest aggregates across your dep tree into one committed, diffable pair of files. Generated output is deterministic, so contract changes review like any other diff.

Your package also ships an extension surface: derivation with use Vendor.Element, same-tag takeover behind the base conformance gate, open actions protected by semver (renaming any action is a MAJOR bump), and two version axes: the wire contract at v1, and extension_api (first stable value 1.0.0), pinnable at derivation or on behaviors.add. Each package can scaffold a built-in interactive gallery (mix tessera.gen.gallery, driven by the manifest from mix tessera.cem): live demos, typed attribute, property and slot editors, and an event log, so consumers try the kit before adding the dep.

What works today, what doesn't

amber = pending scenarios, counted and never faked green. · last checked 2026-11-12 · sources: tessera develop CI toolchain (Elixir 1.18) + docs/notes/lit-parity.md (in the tessera repo)

Hex: noizu_tessera 0.2.0 is on hex.pm (docs on HexDocs) — the dep line below is the install path. 0.2.0 is the Lit-parity milestone: pre-1.0, so the API may still change. docs/notes/lit-parity.md in the repo lists exactly what is covered and what is accepted as a gap; full Tier-2 Lit parity is not claimed. Open source (MIT) because early readers make better contracts.

Clone the demo and run it

{:noizu_tessera, "~> 0.2.0"}

git clone https://github.com/the-robot-lives/tessera
cd tessera/demo/hologram_app
mix deps.get
mix tessera.install
mix holo
# → http://localhost:5586  (stateless, cid-targeted, picker, behaviors, Link nav)

cd ../plain_html
npm install && npm run build && npm run serve
# → http://localhost:5587

In your own app: add the dep, mix tessera.install, author or alias a component, drop the tag in ~HOLO with on_<event>={:action}. Full walkthrough: docs/CONSUMING.md.

Fair questions, straight answers

Good places to help

The repo is public and MIT. Small and concrete beats large and speculative; open an issue first.

• The remaining Linux e2e legs: hologram_main (a/c/d) still fail on ubuntu runners while the blocking smoke legs pass. Repro, hypotheses and the ruled-out list are in docs/notes/e2e-linux-ci.md (TODO(tessera-e2e-linux)).
• Tier 2's 49 pending conformance scenarios, and shipping SSR with Declarative Shadow DOM (spike-proven, not shipped).
• Try mix tessera.from_lit on a real Lit element and report what the extractor missed.
• Extension-contract feedback: write a derivation against a vendor element and tell us where the contract got in your way.
• Turn the React example into a real, executed test host.
• The upstream Hologram PR for native custom-event binding; the bridge is the interim answer.
• More example packages: a data table, a chart wrapper, whatever you would want to install.
• Contract tooling: validators and linters over custom-elements.json and CONTRACT.md §1.

Install it from hex, or watch the repo for releases. We will not invent a waitlist.