@instafy/cli 0.2.3 → 0.3.0

package/dist/bind/src/sse.mjs

@@ -0,0 +1,119 @@
+// Server-sent events: every connected viewer gets every event. A ring buffer (200 events, 2 MB) serves
+// Last-Event-ID replay after a reconnect; a comment ping every 15 s keeps proxies from closing the stream.
+//
+// A stream also ends on its own after MAX_STREAM_MS. Whatever authenticates the viewer in front of the binder (the
+// preview broker's forwardAuth, a proxy) decides once per request, so a stream that never ended would keep
+// delivering after the viewer's access was revoked. EventSource reconnects by itself (retry: 2000) and the ring
+// replays from Last-Event-ID, so a viewer sees no gap; the reconnect simply passes that check again.
+
+export const RING_SIZE = 200;
+export const RING_BYTES = 2 * 1024 * 1024;
+export const PING_MS = 15_000;
+/** Open streams per site; more are refused with 503 so one token holder cannot pin the binder's sockets. */
+export const MAX_CLIENTS = 50;
+/**
+ * Open streams per source (one address behind the preview tunnel or a proxy), so one viewer cannot take every slot.
+ * Past it that source's new stream is refused like a full hub; the bind client then falls back to polling.
+ */
+export const MAX_PER_SOURCE = 8;
+/** How long one stream lives before the client reconnects (and is checked again). */
+export const MAX_STREAM_MS = 60_000;
+
+export class EventHub {
+  constructor({
+    ringSize = RING_SIZE, ringBytes = RING_BYTES, pingMs = PING_MS, maxClients = MAX_CLIENTS, maxPerSource = MAX_PER_SOURCE,
+    maxStreamMs = MAX_STREAM_MS,
+  } = {}) {
+    this.ringSize = ringSize;
+    this.ringBytes = ringBytes;
+    this.ringUsed = 0;
+    this.maxClients = maxClients;
+    this.maxPerSource = maxPerSource;
+    this.maxStreamMs = maxStreamMs;
+    this.ring = [];
+    this.nextId = 1;
+    this.clients = new Set();
+    /** source -> open responses, oldest first */
+    this.bySource = new Map();
+    this.ping = setInterval(() => {
+      for (const res of this.clients) res.write(": ping\n\n");
+    }, pingMs);
+    this.ping.unref?.();
+  }
+
+  get size() {
+    return this.clients.size;
+  }
+
+  /**
+   * Attach a response as an SSE stream. `hello` is sent first and never buffered. `source` identifies who opened it
+   * (see sourceOf in server.mjs; null = not limited per source); one source holds at most maxPerSource streams.
+   * Returns null when full.
+   */
+  attach(req, res, { hello = null, lastEventId = null, source = null } = {}) {
+    const own = source == null ? 0 : this.bySource.get(source)?.length || 0;
+    if (this.clients.size >= this.maxClients || own >= this.maxPerSource) {
+      res.writeHead(503, { "content-type": "application/json", "retry-after": "10", "cache-control": "no-store" });
+      res.end(JSON.stringify({ ok: false, reason: "too many viewers" }));
+      return null;
+    }
+    res.writeHead(200, {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "x-accel-buffering": "no",
+    });
+    res.write("retry: 2000\n\n");
+    if (hello) res.write(`event: ${hello.type}\ndata: ${JSON.stringify(hello)}\n\n`);
+    const last = Number(lastEventId ?? req.headers["last-event-id"]);
+    if (Number.isFinite(last) && last > 0) {
+      for (const entry of this.ring) if (entry.id > last) res.write(entry.frame);
+    }
+    this.clients.add(res);
+    if (source != null) {
+      if (!this.bySource.has(source)) this.bySource.set(source, []);
+      this.bySource.get(source).push(res);
+    }
+    const timer = this.maxStreamMs > 0 ? setTimeout(() => res.end(), this.maxStreamMs) : null;
+    timer?.unref?.();
+    let dropped = false;
+    const drop = () => {
+      if (dropped) return;
+      dropped = true;
+      if (timer) clearTimeout(timer);
+      this.clients.delete(res);
+      const list = source == null ? null : this.bySource.get(source);
+      if (list) {
+        const i = list.indexOf(res);
+        if (i >= 0) list.splice(i, 1);
+        if (list.length === 0) this.bySource.delete(source);
+      }
+    };
+    req.on("close", drop);
+    res.on("close", drop);
+    res.on("finish", drop);
+    res.on("error", drop);
+    return drop;
+  }
+
+  /** Broadcast a host message; its `type` is the SSE event name. Returns the event id. */
+  broadcast(message) {
+    const id = this.nextId++;
+    const frame = `id: ${id}\nevent: ${message.type}\ndata: ${JSON.stringify(message)}\n\n`;
+    const bytes = Buffer.byteLength(frame);
+    this.ring.push({ id, frame, bytes });
+    this.ringUsed += bytes;
+    while (this.ring.length > 1 && (this.ring.length > this.ringSize || this.ringUsed > this.ringBytes)) {
+      this.ringUsed -= this.ring.shift().bytes;
+    }
+    for (const res of this.clients) res.write(frame);
+    return id;
+  }
+
+  close() {
+    clearInterval(this.ping);
+    for (const res of this.clients) res.end();
+    this.clients.clear();
+    this.bySource.clear();
+  }
+}

package/dist/bind/src/starters/blank/app.js

@@ -0,0 +1,17 @@
+/* Blank starter: the theme and site.js only, for anything the other starters don't fit (a quiz, a calculator…).
+ * Build the page here with site.h (text always via textContent) and the theme's few patterns: .card, .list,
+ * .field, .seg, .btn (at most one .btn.primary), .trust for any fact, .notice, .empty. Keep theme.css and site.js.
+ * Keep view state in the query (site.state / site.setState) and give rows ids, so shared links and Studio's
+ * Present / Follow show the same view.
+ * SPDX-License-Identifier: AGPL-3.0-only */
+(function () {
+  "use strict";
+  site.start({
+    data: null,
+    render: function () {
+      site.head({});
+      var list = document.getElementById("list");
+      list.replaceChildren(site.empty("Nothing here yet.", null, "Ask in chat to build this page."));
+    }
+  });
+})();

package/dist/bind/src/starters/blank/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="theme-color" content="#FFFFFF" media="(prefers-color-scheme: light)">
+<meta name="theme-color" content="#141414" media="(prefers-color-scheme: dark)">
+<title>New page</title>
+<link rel="stylesheet" href="theme.css">
+<!-- Restyle only when asked: override --if-* tokens in a <style> here, after theme.css. -->
+</head>
+<body>
+<main class="page">
+  <header class="head"><h1 class="title" id="title">New page</h1><p class="lede" id="lede"></p></header>
+  <section id="list"></section>
+  <footer class="notes" id="notes" hidden></footer>
+</main>
+<script src="__bind/client.js"></script>
+<script src="site.js"></script>
+<script src="app.js"></script>
+</body>
+</html>

package/dist/bind/src/starters/checklist/app.js

@@ -0,0 +1,171 @@
+/* Checklist starter: packing, to-do, steps, a shared list. Ticks are shared by every viewer and device.
+ * You design the content in data.json; keep theme.css and site.js. Restyle only when asked.
+ *
+ * data.json:
+ *   title, lede
+ *   people?: ["Ana", "Ben"]    only when each person keeps their own ticks ("each of us packs")
+ *   groups: [{id, title, items: [{ref: "item:charger", text, note?, fact?}]}]
+ *   fact: {"v": "Sockets are type G", "src": "…", "url": "https://…", "date": "2026-10-17"}
+ * A tick sends set_check {ref, done, who?}; the binder stores it and every page shows it. Without a binder,
+ * ticks stay on this device. Checked items stay in place (muted, struck through). Query: ?who=<name>. A per-person
+ * list shows no ticks until the viewer picks a name ("Whose list is this?" with one plain button per person, "I'm
+ * Ana"); this browser remembers the pick. After that a segmented "Ana | Ben" switches lists.
+ * Rows: id="item-<slug>", data-ref="<ref>".
+ * SPDX-License-Identifier: AGPL-3.0-only */
+(function () {
+  "use strict";
+  var h = site.h;
+  var optimistic = {}; // "<ref>|<attr>" -> {done, id}: shown at once, until the binder answers
+  var failed = {};     // "<ref>|<attr>" -> the tick that did not save
+  var mine = {};       // intent id -> "<ref>|<attr>"
+  var known = false;   // the binder (if any) has said whether it stores ticks
+
+  var bind = window.instafyBind;
+  if (bind) {
+    bind.on("done", function (m) { var k = mine[m.id]; if (!k) return; delete mine[m.id]; delete optimistic[k]; site.schedule(); });
+    bind.on("error", function (m) { var k = mine[m.id]; if (!k) return; delete mine[m.id]; failed[k] = optimistic[k] && optimistic[k].done; delete optimistic[k]; site.schedule(); });
+    bind.on("ack", function (m) {
+      if (m.status !== "rejected" || !mine[m.id]) return;
+      var k = mine[m.id];
+      delete mine[m.id];
+      failed[k] = optimistic[k] && optimistic[k].done;
+      delete optimistic[k];
+      site.schedule();
+    });
+  }
+  site.ready().then(function () { known = true; site.schedule(); });
+
+  site.start({
+    data: "data.json",
+    // a per-person list never guesses whose it is: the viewer picks (and this browser remembers it)
+    state: { who: "" },
+    render: render
+  });
+
+  function shared() { return site.canCheck("set_check", { readable: true }); }
+  function attrFor(who) {
+    if (!who) return "done";
+    return "done_" + (who.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 40) || "x");
+  }
+  function storeKey() { return "checklist:" + location.pathname; }
+  function readLocal() {
+    try { return JSON.parse(localStorage.getItem(storeKey()) || "{}") || {}; } catch (e) { return {}; }
+  }
+  function writeLocal(all) {
+    try { localStorage.setItem(storeKey(), JSON.stringify(all)); } catch (e) { /* private window: ticks last this visit */ }
+  }
+  var memory = null; // when localStorage is blocked
+  function isDone(ref, attr) {
+    var k = ref + "|" + attr;
+    if (optimistic[k]) return optimistic[k].done;
+    if (shared()) {
+      var r = site.live(ref, attr);
+      return !!(r && r.value === true);
+    }
+    var all = memory || readLocal();
+    if (all[attr] && ref in all[attr]) return !!all[attr][ref];
+    var saved = site.live(ref, attr); // a saved copy of the page still shows the ticks it was saved with
+    return !!(saved && saved.value === true);
+  }
+  function tick(ref, attr, who, done) {
+    var k = ref + "|" + attr;
+    delete failed[k];
+    if (shared()) {
+      var params = { ref: ref, done: done, at: new Date().toISOString() };
+      if (who) params.who = who;
+      try {
+        var id = bind.intent("set_check", params, { ref: ref, ui: "check" });
+        mine[id] = k;
+        optimistic[k] = { done: done, id: id };
+      } catch (e) {
+        failed[k] = done;
+      }
+    } else {
+      var all = memory || readLocal();
+      all[attr] = all[attr] || {};
+      all[attr][ref] = done;
+      writeLocal(all);
+      if (readLocal()[attr] === undefined) memory = all;
+    }
+    site.schedule();
+  }
+
+  var restored = false;
+  function render(data, st) {
+    site.head(data);
+    var people = data.people || [];
+    if (people.length && !st.who && !restored) {
+      restored = true;
+      var mine = site.recall("who");
+      if (mine && people.indexOf(mine) >= 0) return site.setState({ who: mine });
+    }
+    var who = people.length && people.indexOf(st.who) >= 0 ? st.who : "";
+    var attr = attrFor(who);
+    var groups = data.groups || [];
+    var all = [];
+    groups.forEach(function (g) { (g.items || []).forEach(function (i) { all.push(i); }); });
+    var doneCount = all.filter(function (i) { return isDone(i.ref, attr); }).length;
+
+    var bar = document.getElementById("bar");
+    bar.replaceChildren();
+    var pick = function (v) { site.remember("who", v); site.setState({ who: v }); };
+    if (people.length && !who) {
+      // nothing to tick until the viewer says whose list it is, so nobody ticks someone else's bag: a question and one
+      // plain button per person (an empty segmented control looks broken, not like a question)
+      bar.appendChild(h("p", { "class": "progress pick-q", text: "Whose list is this?" }));
+      people.forEach(function (p) {
+        bar.appendChild(h("button", { "class": "btn", text: "I'm " + p, attrs: { type: "button", "data-key": "pick:" + p }, on: { click: function () { pick(p); } } }));
+      });
+      bar.hidden = false;
+      document.getElementById("list").replaceChildren();
+      site.notes([], []); // the notes belong to a list; there is none yet
+      return;
+    }
+    if (people.length) bar.appendChild(site.seg("who", "Whose list", people.map(function (p) { return { value: p, label: p }; }), who, pick));
+    bar.hidden = !bar.firstChild;
+
+    var list = document.getElementById("list");
+    list.replaceChildren();
+    if (!all.length) {
+      list.appendChild(site.empty("Nothing on the list yet.", null, "Ask in chat to add some."));
+      site.notes([], []);
+      return;
+    }
+    var top = h("div", { "class": "stack" },
+      h("div", null,
+        h("p", { "class": "progress", text: (who ? who + ": " : "") + doneCount + " of " + all.length + " done" }),
+        known && !shared() ? h("p", { "class": "cap", text: "Ticks are saved on this device only." }) : null));
+    groups.forEach(function (g) {
+      var items = g.items || [];
+      var n = items.filter(function (i) { return isDone(i.ref, attr); }).length;
+      top.appendChild(h("section", { "class": "group", attrs: { id: "group-" + site.slug(g.id || g.title) } },
+        h("div", { "class": "group-head" }, h("h2", { text: g.title }), h("span", { "class": "cap", text: n + " of " + items.length })),
+        h("ul", { "class": "list checks" }, items.map(function (i) { return row(i, attr, who); }))));
+    });
+    list.appendChild(top);
+
+    var sources = [];
+    all.forEach(function (i) { sources = sources.concat(site.sourcesOf([i.fact])); });
+    site.notes(data.unchecked, sources);
+  }
+
+  function row(item, attr, who) {
+    var k = item.ref + "|" + attr;
+    var done = isDone(item.ref, attr);
+    var input = h("input", { attrs: { type: "checkbox", checked: done, disabled: !known, "data-key": "tick:" + item.ref } });
+    input.addEventListener("change", function () { tick(item.ref, attr, who, input.checked); });
+    var attrs = site.rowAttrs(item.ref, "item");
+    var linked = !!(item.fact && site.safeUrl(item.fact.url));
+    return h("li", { "class": "item", attrs: attrs },
+      h("label", { "class": "check" }, input,
+        h("span", { "class": "text" },
+          h("span", { "class": "label-text", text: item.text }),
+          item.note ? h("span", { "class": "cap", text: item.note }) : null,
+          // a fact without a link reads like a note, in the row ("To confirm · whether pools need a swim cap")
+          item.fact && !linked ? h("span", { "class": "item-fact cap" }, site.trust(item.fact, { unknown: "To confirm" })) : null)),
+      // a fact with a link sits under the row, outside the tick target, as a quiet caption
+      item.fact && linked ? h("p", { "class": "item-fact" }, site.trust(item.fact, { unknown: "To confirm" })) : null,
+      k in failed ? h("p", { "class": "cap err" }, site.icon("error"), " Couldn't save · ",
+        h("button", { "class": "link-btn", text: "Try again", attrs: { type: "button", "data-key": "retry:" + item.ref }, on: { click: function () { tick(item.ref, attr, who, failed[k] !== false); } } })) : null);
+  }
+})();

package/dist/bind/src/starters/checklist/bound.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "title": "Checklist",
+  "intents": {
+    "set_check": {
+      "label": "Tick",
+      "describe": "Store one tick so every viewer sees the same list. Refs and people must be in data.json.",
+      "executor": "script",
+      "handler": "handlers/set_check.mjs",
+      "params": {
+        "type": "object",
+        "required": ["ref", "done"],
+        "additionalProperties": false,
+        "properties": {
+          "ref": { "type": "string", "maxLength": 80, "pattern": "^item:[a-z0-9-]{1,60}$" },
+          "done": { "type": "boolean" },
+          "who": { "type": "string", "maxLength": 24, "pattern": "^[A-Za-z0-9À-ÿ' -]{1,24}$" },
+          "at": { "type": "string", "format": "date-time", "maxLength": 40 }
+        }
+      },
+      "target": { "records": "data/records/set_check.json" },
+      "lanes": ["local"],
+      "pending": "item",
+      "cooldown_s": 0,
+      "timeout_s": 15
+    }
+  },
+  "results": { "files": ["data/records/set_check.json"], "poll_s": 5, "sse": true }
+}

package/dist/bind/src/starters/checklist/data.json

@@ -0,0 +1,26 @@
+{
+  "title": "Before the launch",
+  "lede": "Tick things off as you go. Everyone sees the same list.",
+  "groups": [
+    {
+      "id": "prepare",
+      "title": "Prepare",
+      "items": [
+        { "ref": "item:book-room", "text": "Book the room", "fact": { "v": "Holds 40 people", "src": "Venue page", "url": "https://example.com/venue", "date": "2026-10-17" } },
+        { "ref": "item:invitations", "text": "Send the invitations" },
+        { "ref": "item:name-tags", "text": "Print name tags" },
+        { "ref": "item:parking", "text": "Tell guests where to park", "fact": { "note": "parking near the venue" } }
+      ]
+    },
+    {
+      "id": "on-the-day",
+      "title": "On the day",
+      "items": [
+        { "ref": "item:projector", "text": "Test the projector" },
+        { "ref": "item:chairs", "text": "Set out the chairs" },
+        { "ref": "item:photos", "text": "Take a group photo" }
+      ]
+    }
+  ],
+  "unchecked": []
+}

package/dist/bind/src/starters/checklist/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="theme-color" content="#FFFFFF" media="(prefers-color-scheme: light)">
+<meta name="theme-color" content="#141414" media="(prefers-color-scheme: dark)">
+<title>Checklist</title>
+<link rel="stylesheet" href="theme.css">
+<!-- Restyle only when asked: override --if-* tokens in a <style> here, after theme.css. -->
+</head>
+<body>
+<main class="page">
+  <header class="head"><h1 class="title" id="title">Checklist</h1><p class="lede" id="lede"></p></header>
+  <div class="bar" id="bar" hidden></div>
+  <section id="list"></section>
+  <footer class="notes" id="notes" hidden></footer>
+</main>
+<script src="__bind/client.js"></script>
+<script src="site.js"></script>
+<script src="app.js"></script>
+</body>
+</html>