Writing IOSync-safe components

Your light DOM is your source

With live output → input sync on, which is the default, anything a component adds to or changes in its light DOM is adopted into your source: children, text, attributes, classes and inline styles, on the host or on its children. Adoption happens when the page loads, when the output is initialized, and whenever the editor is not focused. The next Load then runs the component again on top of the adopted markup, and duplicates follow.

Undeclared elements reload every edit

While at least one custom element outside a template is not declared sync-safe, every edit anywhere reloads the output, and removing the last such element reloads it once more. Declaring the tag, as the next section shows, keeps edits hot-patching. See When the output reloads.

Put internal markup in a shadow root

Prefer a closed shadow root. A closed root is not reachable through element.shadowRoot, so IOSync never observes it, never writes it back and never materializes it. Internal state belongs in JavaScript or in ElementInternals, not in attributes of the host.

An open runtime shadow root is safe only while Shadow Source Materialization (F7) is off, or when its host carries oi:exclude=shadowroot Experimental. See Runtime shadow roots and Shadow Source Materialization.

Style with adopted style sheets

Constructable style sheets produce no DOM nodes and no mutation records, so they never sync back and are never materialized. Put per-instance values, such as a time offset, into a per-instance sheet like :host { --t: … }, not into the host's style attribute.

const base = new CSSStyleSheet, time = new CSSStyleSheet
base.replaceSync(':host { display: block }')
root.adoptedStyleSheets = [base, time]
time.replaceSync(`:host { --t: ${t} }`)   // a per-instance value, with no style attribute on the host

The analog clock that the Elefunc blog describes does this with its --t value.

Color text with the Highlight API

Use CSS.highlights and ::highlight(name) instead of wrapping words in <span> elements. A highlight is a set of ranges, not DOM, so the source text stays untouched. Expose state with custom states, this.attachInternals().states and :state(x), rather than with reflected classes.

const hits = new Highlight, range = new Range
range.setStart(node, 0); range.setEnd(node, 4)
hits.add(range)
CSS.highlights.set('hit', hits)        // style it with ::highlight(hit) { … }
this.attachInternals().states.add('none')   // and style :host(:state(none))

Animate without writing attributes

An attribute that is the intended state should change from script, but write it only when the value actually changes. The analog clock writes its at attribute while you drag it, and only when the value is new, so the blog post describes the playground wiring as "attribute changes flowing in both directions". A write of the same value is ignored, and every other change is a source edit.

For animation, use CSS animations or Web Animations, which mutate no attributes. Do not write style on light-DOM nodes on every frame.

Keep overlays and generated lists out of the observed tree

Put runtime overlays, such as toasts, popovers and debug panels, in a closed shadow root, or in a container marked oi:exclude or oi:exclude=subtree that has no authored children. Avoid appending them straight to <body>: they would be adopted into the source. document.head is not observed either, but it is not rendered, so it suits only invisible helpers.

In this example the script appends a list item every second. They stay out of the source even with live output → input sync on. A change to an attribute of #log itself, such as log.dataset.count = 3, still syncs back. The list is empty in the source: write containers that a script fills empty, and let the script fill them.

<ul id=log oi:exclude=subtree></ul>
<script type=module>
  setInterval(() => log.append(Object.assign(document.createElement('li'), { textContent: new Date().toLocaleTimeString() })), 1000)
</script>

Declarative shadow roots are source-bound

A <template shadowrootmode=open> inside a host belongs to your source. Edits inside it morph the live shadow root in place, runtime nodes inside it are preserved, and changes inside it sync back through the template, whatever the state of Shadow Source Materialization. Edit the CSS or the text in this example:

<div>
  <template shadowrootmode=open>
    <style>:host { display: block; padding: 1rem; border: 1px solid; border-radius: .5rem }</style>
    <slot></slot>
  </template>
  Light content
</div>

The host is a <div>, so no io:sync declaration is needed.

Adding and removing a root

Adding a source shadow root to a host that is already live is refused, because it cannot be rolled back: the status reads i→o failed: Adding a shadow root to an existing host cannot be rolled back. Press F5 to apply it. Removing a source-declared shadow root from an existing host replaces the host element, so its identity and state are lost.

Runtime shadow roots and Shadow Source Materialization

Runtime shadow roots are the open roots that scripts create with attachShadow(). They are not written to the source, and mutations inside them are ignored, unless Shadow Source Materialization is on. It is off by default. Toggle it with F7, with the command Toggle Shadow Source Materialization, with srs=1 in the URL, or with sync.shadowRootMaterializationToggle().

• When it is on, a normal reverse sync, live or F6, writes each reachable runtime open shadow root into the source as <template shadowrootmode=open>…</template>, directly after the host's start tag. Later edits inside it become source-bound edits.
• Materialized templates always say shadowrootmode=open. They carry no shadowrootdelegatesfocus, shadowrootclonable or shadowrootserializable, and adoptedStyleSheets are not serialized, because they are not DOM. A component that relies on constructable style sheets therefore materializes without its styles.
• Switching it on writes nothing by itself. The templates appear at the next full snapshot, for example F6.
• Switching it off removes from the source the templates that this mode created. The live shadow roots, and the edits made in them, stay.

Experimental To keep one host's runtime shadow tree out of materialization, mark the host with oi:exclude=shadowroot. The host's attributes and light DOM still sync. In this example, a source edit from title=Hi to title=Yo re-renders the heading, and nothing reaches the source:

<meta io:sync=x-card>
<x-card oi:exclude=shadowroot title=Hi></x-card>
<script type=module>
  customElements.define('x-card', class extends HTMLElement {
    static observedAttributes = ['title']
    #root = this.attachShadow({ mode: 'open' })
    attributeChangedCallback() { this.#root.replaceChildren(Object.assign(document.createElement('h2'), { textContent: this.title })) }
  })
</script>

Dynamically inserted templates

Experimental Playground only In the playground, the output runtime watches the document. When a <template shadowrootmode=open> is inserted dynamically, for example by a hot patch or by your own innerHTML or append(), the runtime attaches it as a real open shadow root. It honors shadowrootdelegatesfocus, but not clonable or serializable. Templates whose host already has a shadow root are removed, and dynamically inserted closed templates stay inert. A deployed page follows the HTML standard instead: only HTML parsing, by the page parser, setHTMLUnsafe() or Document.parseHTMLUnsafe(), attaches declarative shadow roots, and innerHTML does not. Do not rely on the playground's behavior in code you deploy. See Playground and edge differences.