janela 0.2.1 → 0.4.0

data/UPGRADING.md

@@ -0,0 +1,172 @@
+# Upgrading Janela
+
+What to do, in order, when a release needs you to act. For what
+changed and why, see [CHANGELOG.md](CHANGELOG.md); for why it was
+decided, see [docs/decisions](docs/decisions/INDEX.md).
+
+After any upgrade, run:
+
+```bash
+bin/rails janela:doctor
+```
+
+It reads your application and lists what still needs changing.
+
+## 0.3.0 to 0.4.0
+
+Selecting more than one value in a dimension (ADR 024). Most hosts do
+nothing: the gesture, the predicate and the keys all arrive on their
+own. Two things need you only if you have reached into Janela's own
+markup.
+
+**1. `selected_value` is now `selected_values`.**
+
+Only if you overrode a pane view. It returns an array, because a
+dimension can now hold more than one value, and the null group is in
+it like any other label:
+
+```erb
+- <% if label.to_s == query.selected_value.to_s %>
++ <% if query.selected?(label) %>
+```
+
+**2. A click now writes `_in` rather than `_eq`.**
+
+A shared link is `?q[status_in][]=paid` instead of `?q[status_eq]=paid`.
+Links you sent before keep working, because Ransack reads both and
+Janela still marks an `_eq` value as selected. You only need to act if
+something of yours parses Janela's URLs or asserts on them, such as a
+test:
+
+```ruby
+- assert_includes page.current_url, "q[status_eq]=paid"
++ assert_includes page.current_url, "q[status_in][]=paid"
+```
+
+**Nothing else changed.** Ctrl or Cmd click adds a value to a
+selection, Escape clears the frame's filters, and both work from the
+keyboard because a value is a real button and Enter carries the same
+modifier. A chart highlights every selected bar.
+
+## 0.2.1 to 0.3.0
+
+Two things arrive together. Janela's own words settle on frames and
+panes, which is a rename across your application: a frame is the
+dashboard, a pane is one visual in it. And a dashboard can now be a
+database record rather than only ERB, which is what the new tables and
+the engine's own pages are for.
+
+Step 1 is the one that breaks a page if you skip it. The renames after
+it can be done in any order, and `janela:doctor` will tell you what you
+have missed.
+
+**1. Run the migrations.**
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Required if you mount the engine, even if you never intend to store a
+dashboard. From this release the mount root serves an index of frames,
+so without the tables `/dashboards` raises where it used to work.
+
+**2. Rename the Stimulus controller you register.**
+
+```js
+// app/javascript/controllers/index.js, or wherever you register it
+- import JanelaDashboardController from "@retail-tasker/janela/dashboard_controller"
+- application.register("janela--dashboard", JanelaDashboardController)
++ import JanelaFrameController from "@retail-tasker/janela/frame_controller"
++ application.register("janela--frame", JanelaFrameController)
+```
+
+On importmap the path is `janela/frame_controller` rather than
+`janela/dashboard_controller`. On npm, reinstall so the new export
+path resolves:
+
+```bash
+yarn add github:retail-tasker/janela#v0.4.0   # or bump your version range
+```
+
+**3. Rename the helper that wraps your panes.**
+
+```erb
+- <%= janela_dashboard do %>
++ <%= janela_frame do %>
+    <%= janela_pane Order, :revenue %>
+  <% end %>
+```
+
+`janela_pane` and `janela_snapshot_pane` are unchanged.
+
+**4. Rename any Janela data attributes in your own markup.**
+
+Anything you wrote by hand, most likely a clear button:
+
+```erb
+- <button data-action="janela--dashboard#clear">Clear filters</button>
++ <button data-action="janela--frame#clear">Clear filters</button>
+```
+
+The same applies to `data-janela--dashboard-target` and
+`data-janela--dashboard-*-param` if you built your own controls.
+
+**5. Rename the constants, if you reference them.**
+
+Most applications do not.
+
+| Was | Now |
+| --- | --- |
+| `Janela::Pane` | `Janela::Query` |
+| `Janela::Pane#frame_id` | `Janela::Query#turbo_frame_id` |
+| `Janela::DashboardHelper` | `Janela::FramesHelper` |
+| `Janela::PanesController` | `Janela::QueriesController` |
+| `Janela::SnapshotPanesController` | `Janela::SnapshotQueriesController` |
+
+`Janela::Pane` is reserved for a database record in a later release,
+which is why the runtime object had to give the name up.
+
+If you override Janela's view, move your copy from
+`app/views/janela/panes/` to `app/views/janela/queries/`.
+
+**6. Tell Janela what a new frame belongs to, if your policy asks.**
+
+Only for a multi tenant host. If your Pundit scope filters
+`Janela::Frame` by an owner, a frame created through Janela's own form
+would be saved with no owner and hidden by that scope the instant it
+was saved. Define the hook on the controller Janela inherits from:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def janela_frame_owner
+    Current.account # whatever your scope filters frames by
+  end
+end
+```
+
+`janela:doctor` reports this one for you: it asks your policy for a
+scope and looks for an owner in it. `docs/multi-tenancy.md`, shipped
+in the gem, has the wiring for Pundit, acts_as_tenant and CanCanCan.
+
+**7. Link the stylesheet, if you have not.**
+
+```erb
+<%= stylesheet_link_tag "janela" %>
+```
+
+Optional. It is the grid and enough style to read a pane, and Janela's
+own pages load it themselves either way.
+
+**Numbers read differently, and you need do nothing.** A measure now
+renders to the precision it means rather than to whatever the database
+returned, so a sum of a `decimal(10, 2)` column that read as `375.0`
+reads as `375.00`. Declare `precision:`, `prefix:` or `suffix:` on the
+measure to say otherwise. Nothing is rounded before it is stored or
+compared.
+
+**Nothing else changed.** Pane URLs, the route helpers `pane_path` and
+`snapshot_pane_path`, turbo frame ids, and the CSS hooks
+`janela-pane`, `janela-chart`, `janela-value` and `janela-empty` are
+all as they were. Your measures, dimensions and snapshots are
+untouched.

data/app/assets/javascripts/janela/chart_controller.js

@@ -4,11 +4,12 @@ import { Chart, registerables } from "chart.js"
 Chart.register(...registerables)
 
 // Renders one pane as a chart and turns a click on a bar into the same
-// toggle event a table button emits, so the dashboard controller cannot tell
-// the difference. Turbo replaces the frame on every cross-filter, so the chart
-// is destroyed on disconnect and rebuilt on connect.
+// toggle event a table button emits, so the frame controller cannot tell the
+// difference. Turbo replaces the turbo frame on every cross-filter, so the
+// chart is destroyed on disconnect and rebuilt on connect.
 export default class extends Controller {
-  static values = { type: String, labels: Array, values: Array, filters: Object, title: String, selected: String }
+  static values = { type: String, labels: Array, values: Array, filters: Object, title: String,
+                    selected: Array, formatted: Array }
 
   connect() {
     this.chart = new Chart(this.element, {
@@ -25,22 +26,34 @@ export default class extends Controller {
       options: {
         animation: false,
         scales: { y: { beginAtZero: true } },
-        plugins: { legend: { display: false } },
-        onClick: (_event, elements) => {
+        plugins: {
+          legend: { display: false },
+          // The server formatted every number for the table, so the tooltip
+          // reads the same string rather than formatting a second time here
+          // and disagreeing with the cell beside it.
+          tooltip: { callbacks: { label: (item) => this.formattedValue[item.dataIndex] ?? item.formattedValue } }
+        },
+        onClick: (event, elements) => {
           if (elements.length === 0) return
           const label = this.labelsValue[elements[0].index]
           const [key, value] = this.filtersValue[String(label)] || []
-          if (key) this.dispatch("toggle", { detail: { key, value } })
+          // A custom event carries no modifier flags of its own, so the
+          // gesture is read here and passed on (ADR 024).
+          const additive = event.native?.ctrlKey === true || event.native?.metaKey === true
+          if (key) this.dispatch("toggle", { detail: { key, value, additive } })
         }
       }
     })
   }
 
-  // With nothing selected every bar is solid; with a selection only that bar is.
+  // With nothing selected every bar is solid; with a selection only the
+  // selected ones are, and there can be more than one of them.
   colours() {
-    const selected = this.selectedValue
+    const selected = this.selectedValue.map(String)
     return this.labelsValue.map((label) =>
-      !selected || label === selected ? "rgba(54, 162, 235, 0.9)" : "rgba(54, 162, 235, 0.25)"
+      selected.length === 0 || selected.includes(String(label))
+        ? "rgba(54, 162, 235, 0.9)"
+        : "rgba(54, 162, 235, 0.25)"
     )
   }
 

data/app/assets/javascripts/janela/frame_controller.js

@@ -0,0 +1,188 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Shared filter state for every pane in the frame. Clicking a value rewrites
+// each turbo frame's src, and Turbo reloads one whenever its src changes, so
+// cross-filtering needs no streams, no sockets and no state library.
+export default class extends Controller {
+  static targets = ["pane"]
+  static values = { filters: Object }
+
+  initialize() {
+    this.supersede = this.supersede.bind(this)
+  }
+
+  // A pane is a turbo frame that outlives its own contents, so the listener is
+  // attached once per frame rather than once per render.
+  paneTargetConnected(pane) {
+    pane.addEventListener("turbo:before-fetch-request", this.supersede)
+    // What the server already rendered this pane for is what Janela has asked
+    // for, so a later change is measured against it rather than against
+    // nothing.
+    pane.dataset.janelaAsked ||= this.urlFor(pane).href
+  }
+
+  paneTargetDisconnected(pane) {
+    pane.removeEventListener("turbo:before-fetch-request", this.supersede)
+    pane.janelaRequest?.abort()
+  }
+
+  // The request for what Janela last asked for wins, and any other is
+  // cancelled before it can land. A pane's load can be in flight when a click
+  // asks it for something else, and Turbo renders whatever arrives, so an
+  // older answer could overwrite a newer one and leave the pane showing
+  // numbers for filters nobody has any more. Neither arrival order nor start
+  // order settles it: a lazy load can begin after a click and still be for the
+  // old address. What was asked for is the only honest rule (#33).
+  supersede(event) {
+    const pane = event.currentTarget
+    const options = event.detail?.fetchOptions
+    const url = event.detail?.url
+    if (!options || !url) return
+
+    const request = new AbortController()
+    options.signal?.addEventListener("abort", () => request.abort(), { once: true })
+    options.signal = request.signal
+
+    const asked = pane.dataset.janelaAsked
+    if (asked && new URL(url, window.location.origin).href !== asked) {
+      // Stale before it started. Cancel it, and make sure the pane still ends
+      // up fetching what was asked for, since this may have been its only load.
+      request.abort()
+      // Bounded, so an address spelled differently from the one Janela built
+      // cannot set a pane correcting itself forever.
+      const corrections = pane.janelaCorrectedFor === asked ? (pane.janelaCorrections || 0) : 0
+      if ((!pane.janelaRequest || pane.janelaRequestFor !== asked) && corrections < 2) {
+        pane.janelaCorrectedFor = asked
+        pane.janelaCorrections = corrections + 1
+        queueMicrotask(() => { pane.src === asked ? pane.reload() : (pane.src = asked) })
+      }
+      return
+    }
+
+    pane.janelaRequest?.abort()
+    pane.janelaRequest = request
+    pane.janelaRequestFor = asked
+    request.signal.addEventListener("abort", () => {
+      if (pane.janelaRequest === request) pane.janelaRequest = null
+    }, { once: true })
+  }
+
+  // Table buttons send key/value as Stimulus action params; charts dispatch a
+  // custom event carrying them in detail. Either way it is one value being
+  // added to or taken out of a selection.
+  //
+  // A plain click selects that value alone, or clears the dimension if it was
+  // the only one selected. Ctrl or Cmd adds and removes while the rest stay,
+  // which is how every list in every operating system already behaves. The
+  // same event carries the same flags when Enter is pressed on a focused
+  // value, so the keyboard needs nothing of its own (ADR 024).
+  toggle(event) {
+    const { key, value } = { ...event.detail, ...event.params }
+    const additive = event.ctrlKey || event.metaKey || event.detail?.additive === true
+    const filters = { ...this.filtersValue }
+    const selected = this.valuesFor(filters, key).includes(String(value))
+
+    // The null group asks for rows that have nothing there, so it cannot be
+    // combined with a value: Ransack ands its conditions, and the pair matches
+    // no row at all. It is exclusive within its dimension instead.
+    this.clearDimension(filters, key)
+
+    if (key.endsWith("_null")) {
+      if (!selected) filters[key] = "1"
+    } else {
+      let values = additive ? this.valuesFor(this.filtersValue, key) : []
+      values = selected ? values.filter((each) => each !== String(value)) : [ ...values, String(value) ]
+      if (values.length) filters[key] = [ ...new Set(values) ].sort()
+    }
+
+    this.filtersValue = filters
+  }
+
+  clear() {
+    if (Object.keys(this.filtersValue).length) this.filtersValue = {}
+  }
+
+  // Whatever is selected for one key, as a set of strings. A filter arrives as
+  // an array from a click and as a string from a hand written _eq link.
+  valuesFor(filters, key) {
+    const held = filters[key]
+    if (held === undefined) return []
+
+    return (Array.isArray(held) ? held : [ held ]).map(String)
+  }
+
+  // Every filter Janela itself writes for the same dimension: the values, the
+  // null group, and an _eq that a shared link may still carry. A host's own
+  // q[...] filters use other predicates and are left alone (ADR 008).
+  clearDimension(filters, key) {
+    const base = key.replace(/_(in|null|eq)$/, "")
+    for (const suffix of [ "in", "null", "eq" ]) delete filters[`${base}_${suffix}`]
+  }
+
+  // Stimulus calls this as the controller starts, with the filters the server
+  // rendered, so nothing has changed yet. A frame is already showing the right
+  // numbers, and a src assigned here would make Turbo fetch every pane and
+  // throw that first render away (ADR 014).
+  //
+  // Janela keeps its own record of what it last applied rather than trusting
+  // the previous value it is handed. On a page opened from a filtered link,
+  // Stimulus passes the default empty object as the previous value, not
+  // nothing, so a check on that alone reloaded every pane on connect, and the
+  // redundant load could land after a click and undo it (#33).
+  filtersValueChanged(filters) {
+    const applied = JSON.stringify(filters)
+    if (this.applied === undefined || this.applied === applied) {
+      this.applied = applied
+      return
+    }
+    this.applied = applied
+
+    this.paneTargets.forEach((pane) => {
+      const url = this.urlFor(pane)
+
+      // Janela's own record of what it last asked this pane for, rather than
+      // the pane's src. A lazy load that began before a click lands after it,
+      // and Turbo then puts the URL it fetched back on the frame while leaving
+      // the newer content in place, so src stops describing what is on screen.
+      // Reading it meant the next change that happened to match was skipped
+      // and the pane kept numbers nobody had asked for (#33).
+      if (pane.dataset.janelaAsked === url.href) return
+
+      pane.dataset.janelaAsked = url.href
+      pane.src = url.href
+    })
+
+    this.syncPageUrl()
+  }
+
+  // The page URL carries the same q[...] the panes do, so a reload or a
+  // pasted link opens the frame filtered (ADR 008). Replaced rather than
+  // pushed: a click is not a place the back button should return to.
+  syncPageUrl() {
+    const url = new URL(window.location.href)
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.startsWith("q[")) url.searchParams.delete(key)
+    }
+    this.writeFilters(url)
+    if (url.href !== window.location.href) history.replaceState(history.state, "", url)
+  }
+
+  urlFor(pane) {
+    const url = new URL(pane.dataset.janelaSrc, window.location.origin)
+    this.writeFilters(url)
+    return url
+  }
+
+  // Sorted, keys and values both, so the browser serialises a selection the
+  // same way every time and an unchanged src is never reloaded.
+  writeFilters(url) {
+    for (const key of Object.keys(this.filtersValue).sort()) {
+      const held = this.filtersValue[key]
+      if (Array.isArray(held)) {
+        for (const value of [ ...held ].sort()) url.searchParams.append(`q[${key}][]`, value)
+      } else {
+        url.searchParams.set(`q[${key}]`, held)
+      }
+    }
+  }
+}

data/app/assets/javascripts/janela/vitral_controller.js

@@ -0,0 +1,263 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Draws vitral's leadlight and lets it answer the pointer: every node leans
+// toward the cursor, hardest nearby and not at all far away, then settles back
+// when it leaves. A window made of data, which is the only excuse for an
+// effect on a page about dashboards.
+//
+// Optional in every sense. The theme is complete without it, the stylesheet
+// carries a static lattice for anyone who never loads this, Janela's own pages
+// never load it, and a visitor who has asked for less motion gets a still one.
+export default class extends Controller {
+  static values = {
+    columns: { type: Number, default: 17 },
+    rows: { type: Number, default: 13 },
+    reach: { type: Number, default: 260 },   // how far the pull carries, in pixels
+    pull: { type: Number, default: 26 },     // how far a node nearest the cursor travels
+    overscan: { type: Number, default: 70 }, // how far past the window the glass is cut
+    near: { type: Number, default: 0.16 },   // how much of a scroll the lead takes
+    far: { type: Number, default: 0.06 }     // and the light behind it, which is further away
+  }
+
+  connect() {
+    this.canvas = document.createElement("canvas")
+    this.canvas.className = "vitral-lattice"
+    this.canvas.setAttribute("aria-hidden", "true")
+    document.body.prepend(this.canvas)
+    this.pen = this.canvas.getContext("2d")
+    this.element.classList.add("vitral-live")
+
+    this.still = window.matchMedia("(prefers-reduced-motion: reduce)").matches ||
+                 !window.matchMedia("(hover: hover)").matches
+
+    this.onResize = this.onResize.bind(this)
+    this.onMove = this.onMove.bind(this)
+    this.onLeave = this.onLeave.bind(this)
+    this.onScroll = this.onScroll.bind(this)
+
+    // Decoration waits its turn. Cutting the glass is a few hundred polygons,
+    // and a dashboard's first paint and its frames matter more than a
+    // background does, so the first draw happens once the browser is idle.
+    this.idle = window.requestIdleCallback
+      ? requestIdleCallback(() => this.cut(), { timeout: 600 })
+      : setTimeout(() => this.cut(), 120)
+
+    window.addEventListener("resize", this.onResize, { passive: true })
+    if (!this.still) {
+      window.addEventListener("scroll", this.onScroll, { passive: true })
+      this.onScroll()
+      window.addEventListener("pointermove", this.onMove, { passive: true })
+      document.addEventListener("pointerleave", this.onLeave)
+    }
+  }
+
+  disconnect() {
+    window.removeEventListener("resize", this.onResize)
+    window.removeEventListener("scroll", this.onScroll)
+    window.removeEventListener("pointermove", this.onMove)
+    document.removeEventListener("pointerleave", this.onLeave)
+    cancelAnimationFrame(this.frame)
+    cancelAnimationFrame(this.drifting)
+    if (window.cancelIdleCallback && this.idle) cancelIdleCallback(this.idle)
+    clearTimeout(this.resizing)
+    this.canvas?.remove()
+    this.element.classList.remove("vitral-live")
+  }
+
+  // Cutting the glass: a jittered grid of nodes, then cells over them, some
+  // cut across the diagonal the way a real window is. Seeded, so the same
+  // window is cut every time rather than a new one on every load.
+  cut() {
+    const random = seeded(1912)
+    const page = document.documentElement.scrollHeight - window.innerHeight
+    this.slack = this.still ? 0 : Math.min(600, Math.ceil(page * this.nearValue) + 20)
+
+    const w = window.innerWidth
+    const h = window.innerHeight + this.slack * 2
+    this.canvas.width = Math.ceil(w * devicePixelRatio)
+    this.canvas.height = Math.ceil(h * devicePixelRatio)
+    this.canvas.style.width = `${w}px`
+    this.canvas.style.height = `${h}px`
+    this.canvas.style.top = `${-this.slack}px`
+    this.canvas.style.bottom = "auto"
+    this.pen.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, 0, 0)
+    this.paper = [ w, h ]
+
+    const cols = this.columnsValue
+    // Taller glass, same size cells, so the pattern does not stretch.
+    const rows = Math.max(3, Math.round(this.rowsValue * h / window.innerHeight))
+
+    // Cut wider than the window, and pin the outermost ring. A node that can
+    // be dragged off the edge takes the glass with it and leaves a bare gap
+    // there, so the outer ring is held and lives off screen besides. The
+    // window flexes; its frame does not.
+    const pad = this.overscanValue
+    const cw = (w + pad * 2) / cols, ch = (h + pad * 2) / rows
+
+    this.nodes = []
+    const index = (r, c) => r * (cols + 1) + c
+    for (let r = 0; r <= rows; r++) {
+      for (let c = 0; c <= cols; c++) {
+        const pinned = c === 0 || c === cols || r === 0 || r === rows
+        const x = -pad + c * cw + (pinned ? 0 : (random() - 0.5) * 0.64 * cw)
+        const y = -pad + r * ch + (pinned ? 0 : (random() - 0.5) * 0.64 * ch)
+        this.nodes.push({ home: [ x, y ], at: [ x, y ], pinned })
+      }
+    }
+
+    const tints = [ "58,122,235", "28,168,158", "240,176,70", "224,96,130", "138,110,228" ]
+    this.cells = []
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < cols; c++) {
+        const a = index(r, c), b = index(r, c + 1), d = index(r + 1, c + 1), e = index(r + 1, c)
+        const quads = random() < 0.45
+          ? (random() < 0.5 ? [ [ a, b, d ], [ a, d, e ] ] : [ [ a, b, e ], [ b, d, e ] ])
+          : [ [ a, b, d, e ] ]
+        for (const corners of quads) {
+          const tint = random() < 0.3
+            ? `rgba(${tints[Math.floor(random() * tints.length)]}, ${(0.025 + random() * 0.035).toFixed(3)})`
+            : null
+          this.cells.push({ corners, tint })
+        }
+      }
+    }
+
+    this.draw()
+  }
+
+  onResize() {
+    clearTimeout(this.resizing)
+    this.resizing = setTimeout(() => this.cut(), 150)
+  }
+
+  // Both background layers move with the page, and neither keeps up with it.
+  // What is near slides past, what is far barely shifts, which is what makes
+  // the window read as a window rather than as wallpaper.
+  onScroll() {
+    if (this.drifting) return
+
+    this.drifting = requestAnimationFrame(() => {
+      this.drifting = null
+      const scrolled = window.scrollY
+
+      // Each layer is clamped to the slack it actually has, or it drifts past
+      // its own edge and shows the bare ground behind it on a long page. The
+      // lead's slack is how much taller than the window it was cut; the
+      // light's is the 20vmax it hangs outside the window by.
+      const lead = this.slack ?? 0
+      const light = 0.2 * Math.max(window.innerWidth, window.innerHeight)
+
+      this.element.style.setProperty("--vitral-drift-near", `${clamp(-scrolled * this.nearValue, lead)}px`)
+      this.element.style.setProperty("--vitral-drift-far", `${clamp(-scrolled * this.farValue, light)}px`)
+
+      // The glass has just slid under a cursor that has not moved, so the
+      // nodes have to take aim again or they stay reaching for the place the
+      // cursor used to be.
+      if (this.aim) this.start()
+    })
+  }
+
+  onMove(event) {
+    // Kept in screen coordinates and converted when the frame is drawn. The
+    // glass is cut taller than the window and drifts as the page scrolls, so
+    // where the cursor is on screen is not where it is on the canvas, and
+    // converting here would mean reading layout on every pointer event.
+    this.aim = [ event.clientX, event.clientY ]
+    this.element.style.setProperty("--vitral-shift-x", (event.clientX / window.innerWidth - 0.5).toFixed(3))
+    this.element.style.setProperty("--vitral-shift-y", (event.clientY / window.innerHeight - 0.5).toFixed(3))
+    this.start()
+  }
+
+  onLeave() {
+    this.aim = null
+    this.start()
+  }
+
+  start() {
+    if (this.frame) return
+    this.frame = requestAnimationFrame(() => this.step())
+  }
+
+  // Each node eases toward where the pointer wants it, so the glass leans and
+  // settles rather than snapping. The loop stops once nothing is moving,
+  // because a background that animates forever is a laptop fan.
+  step() {
+    this.frame = null
+    if (!this.nodes) return
+
+    // One layout read per frame rather than one per pointer event. The rect
+    // accounts for the overscan, the scroll drift and the pointer parallax in
+    // a single measurement, so the pull lands where the cursor actually is.
+    const pointer = this.aimOnGlass()
+    let moving = false
+
+    for (const node of this.nodes) {
+      const [ hx, hy ] = node.home
+      let tx = hx, ty = hy
+
+      if (pointer && !node.pinned) {
+        const dx = pointer[0] - hx, dy = pointer[1] - hy
+        const distance = Math.hypot(dx, dy)
+        const force = Math.exp(-((distance / this.reachValue) ** 2))
+        if (distance > 0.5) {
+          tx = hx + (dx / distance) * this.pullValue * force
+          ty = hy + (dy / distance) * this.pullValue * force
+        }
+      }
+
+      node.at[0] += (tx - node.at[0]) * 0.16
+      node.at[1] += (ty - node.at[1]) * 0.16
+      if (Math.abs(tx - node.at[0]) > 0.08 || Math.abs(ty - node.at[1]) > 0.08) moving = true
+    }
+
+    this.draw()
+    if (moving) this.start()
+  }
+
+  aimOnGlass() {
+    if (!this.aim) return null
+
+    const rect = this.canvas.getBoundingClientRect()
+    return [ this.aim[0] - rect.left, this.aim[1] - rect.top ]
+  }
+
+  draw() {
+    const pen = this.pen
+    pen.clearRect(0, 0, this.paper[0], this.paper[1])
+    pen.lineWidth = 1
+    pen.lineJoin = "round"
+    // The stylesheet owns the colour, so a retheme is one property and the
+    // live lattice never disagrees with the static one.
+    pen.strokeStyle = this.ink ||= getComputedStyle(this.element)
+      .getPropertyValue("--vitral-lattice-ink").trim() || "rgba(44, 62, 84, 0.11)"
+
+    for (const cell of this.cells) {
+      pen.beginPath()
+      cell.corners.forEach((corner, position) => {
+        const [ x, y ] = this.nodes[corner].at
+        position === 0 ? pen.moveTo(x, y) : pen.lineTo(x, y)
+      })
+      pen.closePath()
+      if (cell.tint) {
+        pen.fillStyle = cell.tint
+        pen.fill()
+      }
+      pen.stroke()
+    }
+  }
+}
+
+function clamp(value, limit) {
+  return Math.max(-limit, Math.min(limit, value)).toFixed(1)
+}
+
+// Mulberry32: small, seeded, and good enough to cut glass with.
+function seeded(seed) {
+  return function () {
+    seed |= 0
+    seed = seed + 0x6D2B79F5 | 0
+    let t = Math.imul(seed ^ seed >>> 15, 1 | seed)
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t
+    return ((t ^ t >>> 14) >>> 0) / 4294967296
+  }
+}