selfstore-gate

The first-run screen. It asks where the data should live, before the app has a durable home. Data that lives only in a browser profile dies with it, so the question is worth a screen of its own rather than a line buried in settings.

It is a frame around <selfstore-connect>, and it decides one thing the plain connect widget cannot: whether to be on screen at all.

<selfstore-gate id="gate"></selfstore-gate>
<script type="module">
  const el = document.getElementById('gate');
  el.targets = { file: true, webdav: true };
  el.store = store;
</script>

It opens itself

The condition is the engine’s own status.action === 'choose-destination'. That covers both an ephemeral store and one still on the device-only cache, and it ranks a destination needing attention above a missing one - so the gate never demands a choice when the real problem is a broken connection.

You do not compute this. Asking the target kind by hand would miss the ranking and nag the user over a connection that just needs reconnecting.

Properties

armed, and the flash you want to avoid

Leave armed at true for a plain drop-in. An app that restores its destination asynchronously should set it false until that settles, so a connected user never glimpses the gate on the way in:

el.armed = false;
await restoreDestination();
el.armed = true;

deferrable, and coming back

Device-only is a working mode, just a fragile one. deferrable decides whether to offer it. When the user takes it, deferred goes true and the gate stays shut for the session; assign deferred = false from a “choose a destination” entry elsewhere in your app to bring it back.

Attributes

Only these two are observed. Everything else is a property.

In a framework that assigns properties - Svelte, Vue, React 19 - write deferrable={false}, not deferrable="false": the property setter stores what it is given, and a non-empty string is truthy. See the boolean trap.

Slots

Your own chrome goes in the light DOM. Slotted nodes are never rebuilt, so a component you slot in keeps its state across the gate’s re-renders.

<selfstore-gate>
  <div slot="brand"><img src="/logo.svg" alt="Acme" /></div>
  <div slot="extra"><a href="/demo">Try the demo first</a></div>
  <div slot="footer"><small>Acme, 2026</small></div>
</selfstore-gate>

Events

The connect journey inside the gate emits its own events - selfstore-connected, selfstore-error, selfstore-cancelled - and they bubble through, so listen for those to know the destination was chosen.

Parts

The connect element inside lives in the gate’s shadow root and its parts are not re-exported, so selfstore-gate::part(card) does not reach the destination cards. Custom properties do cross - see styling.

Custom properties

Beyond the shared set, the gate adds:

Labels

Every string is a key with a default, and the widget ships English and French. The 5 keys it owns are listed on every label key; how the resolution works is on wording.