eui-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59195020fcb69b8505cacd7ea0e69a2b6e1b62aee5d643d12b23cf5e28d59c44
+  data.tar.gz: 4d5f6ab4418724e05f811cf421face93e14f80771d18d2b0489d40b3b1552610
+SHA512:
+  metadata.gz: c916bad7e89041aa084bde702f29e5c53752b71d2ba6293dad7097b9017c1ef1ffadc4ad87f4303e705b297628bbc2de3b53203c4b1cd4963e6b14bcd853e912
+  data.tar.gz: 224ee331e613b7d5435f51c4a87b91f46295f1bbb82babb0ca9ef9b0b3d0513f8a02a3a97a8e79594666d8d7573175dbd3e03c7b9bb2f880f6b0f5c34b1a28de

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.0
+
+The first cut: enough to write an EUI application in Ruby and have the
+reference client draw it.
+
+- `EUI::Proto` — the wire format of `spec/02`: varints, the 64-byte style
+  record, nodes, values, handlers, ops, batches and every session frame,
+  checked against the byte vectors the spec pins.
+- `EUI::View` — a view hash compiled into interned atoms, styles and
+  colours, and diffed against the tree the client holds: keyed children
+  reconcile by `MoveChild`, and one changed word is one `SetText`.
+- `EUI::Session` / `EUI::Server` — the HTTP and WebSocket halves of
+  `spec/01`: manifest, content-addressed assets, and a session that
+  welcomes, mounts, patches, answers a ping and rebuilds on a resync.
+- `EUI::Component` — state, handlers, and a view that is a function of the
+  state.
+- `EUI::Blake3` — BLAKE3 in Ruby, because an asset is named by the hash of
+  its content.
+- `EUI::Manifest` — the signed `EUIM` record, with an Ed25519 publisher key
+  kept on disk.
+- `bench/` — the same application in Ruby and in Soli, and a driver that
+  measures both until the server goes quiet. Writing it found two of this
+  gem's own faults: a quadratic keyed reconciliation (a 10 000-row sort took
+  17.7 s; a Fenwick tree made it 0.8 s) and a style record compiled once per
+  node rather than once per distinct style (a 50 000-node render went from
+  2.9 s to 0.6 s).
+
+Not yet: local handlers (`spec/07` bytecode), file transfers (`spec/01`
+§6), session resume, and the windowed `list`'s `window` event.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Bonnaure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# eui-ruby
+
+EUI applications, written in Ruby.
+
+[EUI](https://github.com/solisoft/eui) delivers an application interface over
+HTTPS without HTML, CSS or JavaScript. The server sends a tree that is
+**already resolved**, in a compact binary encoding; a native client applies
+it, lays it out and draws it on the GPU. There is no tolerant parse at the
+other end, no cascade to resolve, no script to run.
+
+This gem is the server half: the wire format, the view encoder and its diff,
+the session, the content-addressed asset store, the signed manifest, and a
+component model in which a view is a hash and a handler changes state.
+
+```ruby
+require "eui"
+
+class Counter < EUI::Component
+  def mount(params)
+    super          # the window, as it is right now
+    @count = 0
+  end
+
+  on("increment") { @count += 1 }
+
+  def render
+    column(gap: 5, align: "center", justify: "center",
+           width: "100%", height: "100%", bg: "surface.base") do
+      [text(@count.to_s, size: "4xl", weight: "bold"),
+       button("Increment", "increment")]
+    end
+  end
+end
+
+app = EUI::App.new(name: "Counter", app_id: "counter.example")
+app.mount("counter", Counter)
+app.run(port: 5099)
+```
+
+```
+EUI_ALLOW_INSECURE_LOOPBACK=1 eui ws://127.0.0.1:5099/_eui/session/counter
+```
+
+Pressing the button sends **one** `SetText`. Not a page, not a diffed DOM,
+not a frame of JSON: the style records went once, at mount, and every later
+render names them by id.
+
+## What a view is
+
+A hash, and a pure function of the state. `EUI::DSL` — included in every
+component — builds them, but there is nothing behind the helpers: print one
+and you have the whole document.
+
+```ruby
+{"k" => "box", "s" => {"display" => "column", "gap" => 4},
+ "c" => [{"k" => "text", "t" => "Hi", "s" => {"size" => "lg"}}]}
+```
+
+- **`k`** one of the seventeen primitive kinds. Everything a person would
+  call a widget — button, dialog, table, date picker — is composed from
+  these on the server, which is why the catalogue grows without shipping a
+  new client.
+- **`s`** a flat style hash in the spec's own vocabulary. An unknown key is
+  an error, not a key that does nothing.
+- **`c`** children, **`t`** text, **`p`** props, **`on`** handlers,
+  **`key`** identity for reconciliation.
+
+**[eui.solisoft.net/components](https://eui.solisoft.net/components) is the
+reference for all of it** — every node key, all seventeen kinds, every style
+key and all thirty-three colour roles, the event names, and the catalogue of
+composed widgets, each one shown with the hash it returns. It is written
+against Soli, and the vocabulary is the protocol's, so a style hash or a node
+on that page is the same style hash and the same node here. The rest of the
+site is worth the visit too: [the running demo](https://eui.solisoft.net/demo),
+[the controls](https://eui.solisoft.net/controls) every widget is built from,
+and [what is not there yet](https://eui.solisoft.net/gaps).
+
+Colour is a **role** — `surface.raised`, `text.muted`, `danger.base` — never
+a literal. The client resolves it against the viewer's theme, so the page is
+right in dark mode *without this server ever learning which mode they are
+in*. Sizes are scale indices, by index or by name: `size: "lg"`, `gap: 4`,
+`radius: "md"`.
+
+What this gem ships is the primitives plus a few composed widgets — `button`,
+`card`, `field`, `divider`, `spacer`. Anything else in the catalogue is a
+function that returns a hash, so it ports to Ruby by writing the same hash.
+
+```ruby
+column(gap: 4, pad: 6, bg: "surface.base") do
+  [ text("Total", size: "sm", fg: "text.muted"),
+    text(format("%.2f", @total), size: "2xl", font: "mono"),
+    row(gap: 3) { [button("Save", "save"), button("Delete", "delete", tone: "danger")] },
+    divider,
+    keyed("row-#{id}", card { [text(name)] }) ]
+end
+```
+
+## What a handler is
+
+A block, or a method, named by the **view** rather than by the event kind —
+`{"on" => {"wake" => "tick"}}` arrives as `tick`. It changes state and
+returns; it never touches the tree.
+
+```ruby
+on("pick") { |params| @selected = params["props"]["id"] }
+```
+
+`params` carries `node`, `kind`, `payload` and `props` — the node's props as
+the server last rendered them. That last one is what lets one handler serve
+ten thousand rows: put the identifying value on the node, not in the
+handler's name.
+
+A handler that raises leaves the state unchanged and the screen right; it is
+a line in the log, not the end of somebody's session. A **view** that cannot
+be encoded is the other way round: it fails identically on every later
+render, so the session ends with `Error 400` and the reason.
+
+## Running it
+
+| | |
+|---|---|
+| `app.run(port: 5099)` | plain `ws://` on loopback, for development |
+| `app.run(host: "0.0.0.0", port: 443, tls: {cert:, key:})` | TLS 1.3, which is the protocol's floor |
+
+A release client refuses `ws://` outright; a debug one takes
+`EUI_ALLOW_INSECURE_LOOPBACK=1`. `EUI_TRACE=1` on the server prints every
+frame and every event a session sees, which is the first thing to reach for
+when a click does nothing.
+
+Three endpoints, and nothing else: `/.well-known/eui` (the signed manifest),
+`/_eui/asset/<blake3-hex>` (content-addressed, immutable, served to anyone),
+and the session itself.
+
+```ruby
+app = EUI::App.new(name: "Books", app_id: "books.example",
+                   key_path: "config/eui_publisher.pem",
+                   capabilities: %w[net.open])
+app.font("Space Grotesk", ["public/fonts/space-grotesk-400.ttf",
+                           "public/fonts/space-grotesk-700.ttf"])
+```
+
+The publisher key is generated on first use and kept: a client pins it
+against `app_id` on first run and refuses a different one later. It belongs
+to the application, not to a deployment, and it never belongs in a
+repository.
+
+## What is here, and what is not
+
+Implemented: the whole wire format of `spec/02` (checked against the byte
+vectors that document pins), the session frames of `spec/01`, the view
+encoder with its append-only tables, a keyed diff that reorders by
+`MoveChild`, assets, fonts, notifications, `scroll_to` and `focus_to`, the
+manifest, and BLAKE3 in Ruby because an asset is named by the hash of its
+content.
+
+Not yet:
+
+- **Local handlers** (`spec/07`). A handler is a server round trip; the
+  bytecode a client runs for itself — the hover that answers without a
+  packet — is the next milestone.
+- **File transfers** (`spec/01` §6): `Upload` and `Blob` are decoded and
+  dropped.
+- **Session resume** (`spec/01` §4.1): a socket that breaks gets a fresh
+  session and a fresh `Mount`, which is a conforming answer and a worse one.
+- The windowed `list`'s `window` event, and `scene` uniforms.
+
+## Tests
+
+```
+rake test
+# or, with nothing installed but Ruby itself:
+ruby -Ilib -Itest -e 'Dir["test/**/*_test.rb"].each { |f| require File.expand_path(f) }'
+```
+
+61 of them, and the ones worth reading are `test/proto_test.rb` — the spec's
+own §8 example, 150 bytes, byte for byte — and `test/session_test.rb`, which
+runs a real application on a real socket and counts the ops a click costs.
+
+## Against the other four
+
+The same application, written five times — in Soli, Ruby, Python, PHP and
+JavaScript, node for node. [`bench/`](bench/) holds all five and the one
+driver that measures them, each phase timed until the server goes quiet. At
+500 rows, one number changed: **9 bytes** out of every one of them, 12 ms in
+Soli, 24 ms here, 9 ms in Node. The bytes being identical is the protocol's
+claim; the rest ranks by JIT, and the memory column ranks what else is in the
+process. [`bench/README.md`](bench/README.md) has the tables, the method and
+the caveats.
+
+## Licence
+
+MIT.

data/examples/counter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# The counter, as an EUI application in Ruby.
+#
+#   ruby -Ilib examples/counter.rb
+#   EUI_ALLOW_INSECURE_LOOPBACK=1 eui ws://127.0.0.1:5099/_eui/session/counter
+#
+# What to look at: `render` is a pure function of `@count`, and pressing a
+# button sends one `SetText` — not a page, not a diffed DOM, not a frame of
+# JSON. The style records were sent once, at mount, and every later render
+# references them by id.
+
+require_relative '../lib/eui'
+
+class Counter < EUI::Component
+  def mount(params)
+    super
+    @count = 0
+  end
+
+  on('increment') { @count += 1 }
+  on('decrement') { @count -= 1 }
+  on('reset')     { @count = 0 }
+
+  def render
+    column(
+      display: 'column', justify: 'center', align: 'center', gap: 7,
+      bg: 'surface.base', width: '100%', height: '100%', pad: 8
+    ) do
+      [
+        text('COUNTER', size: 'sm', weight: 'semibold', fg: 'text.muted', font: 'mono'),
+        text(@count.to_s, size: '4xl', weight: 'bold', fg: tone),
+        row(gap: 4) do
+          [
+            button('−', 'decrement', tone: 'quiet', size: 'lg'),
+            button('Reset', 'reset', tone: 'quiet'),
+            button('+', 'increment', size: 'lg')
+          ]
+        end,
+        divider(width: 320),
+        text(footnote, size: 'xs', fg: 'text.muted', font: 'mono')
+      ]
+    end
+  end
+
+  private
+
+  # Colour by what the number *is*, so it reads as a legend rather than
+  # decoration — and reads right in either theme, because the client
+  # resolves the role and this server never learns which one they are in.
+  def tone
+    return 'danger.base' if @count.negative?
+    return 'text.muted' if @count.zero?
+
+    'success.base'
+  end
+
+  def footnote
+    "#{width} × #{height} · #{@viewport['mode'] || 'light'}"
+  end
+end
+
+app = EUI::App.new(name: 'Counter', app_id: 'counter.eui-ruby')
+app.mount('counter', Counter)
+app.run(port: Integer(ENV.fetch('PORT', '5099')))

data/lib/eui/app.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'assets'
+require_relative 'manifest'
+require_relative 'server'
+
+module EUI
+  # An application: the components it serves, the assets they name, and the
+  # manifest that says who published it.
+  #
+  #     app = EUI::App.new(name: "Counter", app_id: "counter.example")
+  #     app.mount("counter", Counter)
+  #     app.run(port: 5012)
+  #
+  # The first component mounted is the one a bare origin opens, because the
+  # protocol has one entry and a server here has many: `wss://host` has to
+  # mean something, and the first one in the file is what a person reading
+  # it top to bottom would say.
+  class App
+    attr_reader :components, :assets, :name, :app_id
+
+    def initialize(name:, app_id: nil, version: '0.1.0', root: Dir.pwd,
+                   key_path: nil, capabilities: [], logger: nil)
+      @name = name
+      @app_id = app_id || name.downcase.gsub(/[^a-z0-9]+/, '-')
+      @version = version
+      @root = root
+      @assets = Assets.new(root: root)
+      @components = {}
+      @capabilities = capabilities
+      @key_path = key_path
+      @logger = logger
+    end
+
+    def mount(path, component_class)
+      name = path.to_s.delete_prefix('/')
+      @components[name] = component_class
+      @default ||= name
+      self
+    end
+
+    def component_for(name)
+      return @components[@default] if name.nil?
+
+      @components[name]
+    end
+
+    # The face an application draws in, bound to a font role and sent as
+    # content-addressed assets — so the window talks to no font service and
+    # opens no connection the session did not.
+    #
+    # Declaring one at boot is what takes the manifest's floor to EUI 4;
+    # calling it later falls back to `sans` for the sessions already open
+    # rather than ending them.
+    def font(family, paths)
+      hashes = Array(paths).map { |path| @assets.add_file(path) }
+      @fonts ||= {}
+      @fonts[family] = hashes
+      family
+    end
+
+    def fonts = @fonts || {}
+
+    # The signed record at `/.well-known/eui`. Without a key path there is
+    # no manifest, which a debug client on loopback accepts and a release
+    # client does not.
+    def manifest
+      return nil unless @key_path
+
+      @manifest ||= Manifest.new(
+        app_id: @app_id, name: @name, version: @version,
+        key: Manifest.publisher_key(@key_path),
+        entry: "/_eui/session/#{@default}",
+        capabilities: @capabilities,
+        protocol_min: 1, protocol_max: Proto::PROTOCOL_VERSION
+      )
+    end
+
+    def run(host: '127.0.0.1', port: 5012, tls: nil)
+      Server.new(self, host: host, port: port, tls: tls, logger: @logger).start
+    end
+  end
+end

data/lib/eui/assets.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'blake3'
+require_relative 'errors'
+
+module EUI
+  # The content-addressed store behind `/_eui/asset/<blake3-hex>`.
+  #
+  # An asset is named by the hash of its bytes, so the name *is* the
+  # content: the client recomputes it and discards a mismatch, a proxy may
+  # serve it to anyone, and `immutable` is always the right cache header. A
+  # file somebody uploaded is not an asset — that travels in the session
+  # (`spec/01-transport.md` §6), because it is one person's and not the
+  # same for everyone.
+  class Assets
+    TYPES = {
+      '.png' => 'image/png', '.jpg' => 'image/jpeg', '.jpeg' => 'image/jpeg',
+      '.gif' => 'image/gif', '.webp' => 'image/webp', '.svg' => 'image/svg+xml',
+      '.ttf' => 'font/ttf', '.otf' => 'font/otf', '.woff2' => 'font/woff2',
+      '.wav' => 'audio/wav', '.mp3' => 'audio/mpeg', '.ogg' => 'audio/ogg',
+      '.mp4' => 'video/mp4', '.wgsl' => 'text/wgsl'
+    }.freeze
+
+    Entry = Struct.new(:bytes, :content_type)
+
+    def initialize(root: Dir.pwd)
+      @root = File.expand_path(root)
+      @by_hash = {}
+      @by_path = {}
+      @lock = Mutex.new
+    end
+
+    # Take a file into the store and answer its hash. Cheap to call on
+    # every render: a path whose mtime and size have not moved is not read
+    # again.
+    def add_file(path)
+      full = File.expand_path(path, @root)
+      unless full.start_with?(@root + File::SEPARATOR) || full == @root
+        raise ViewError, "an asset must live under #{@root}, got #{path}"
+      end
+      raise ViewError, "no such asset: #{path}" unless File.file?(full)
+
+      stat = File.stat(full)
+      stamp = [stat.mtime.to_f, stat.size]
+      @lock.synchronize do
+        cached = @by_path[full]
+        return cached[1] if cached && cached[0] == stamp
+
+        bytes = File.binread(full)
+        hash = Blake3.digest(bytes)
+        @by_hash[hash] = Entry.new(bytes, TYPES.fetch(File.extname(full).downcase, 'application/octet-stream'))
+        @by_path[full] = [stamp, hash]
+        hash
+      end
+    end
+
+    # Bytes that have no file — a picture out of a database, a chart this
+    # process drew — reach a window the same way.
+    def add_bytes(bytes, content_type: 'application/octet-stream')
+      bytes = bytes.b
+      hash = Blake3.digest(bytes)
+      @lock.synchronize { @by_hash[hash] = Entry.new(bytes, content_type) }
+      hash
+    end
+
+    def fetch(hex)
+      return nil unless /\A[0-9a-f]{64}\z/.match?(hex)
+
+      @lock.synchronize { @by_hash[[hex].pack('H*')] }
+    end
+
+    def size = @lock.synchronize { @by_hash.size }
+
+    def self.hex(hash) = hash.unpack1('H*')
+  end
+end

data/lib/eui/blake3.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module EUI
+  # BLAKE3, in Ruby, because an asset is named by the hash of its content
+  # and the client recomputes it (`spec/01-transport.md` §2.2).
+  #
+  # Only the plain hash: no keyed mode, no key derivation, no extendable
+  # output past 32 bytes. That is every use the protocol has for it — an
+  # asset's name — and each of the others is a footgun this library would
+  # rather not carry.
+  module Blake3
+    OUT_LEN = 32
+    BLOCK_LEN = 64
+    CHUNK_LEN = 1024
+
+    CHUNK_START = 1 << 0
+    CHUNK_END   = 1 << 1
+    PARENT      = 1 << 2
+    ROOT        = 1 << 3
+
+    IV = [
+      0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A,
+      0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19
+    ].freeze
+
+    MSG_PERMUTATION = [2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8].freeze
+
+    MASK = 0xFFFF_FFFF
+
+    class << self
+      def hexdigest(data) = digest(data).unpack1('H*')
+
+      def digest(data)
+        hasher = Hasher.new
+        hasher.update(data)
+        hasher.digest
+      end
+
+      def file(path)
+        hasher = Hasher.new
+        File.open(path, 'rb') do |io|
+          while (block = io.read(65_536))
+            hasher.update(block)
+          end
+        end
+        hasher.digest
+      end
+
+      def rotr(x, n) = ((x >> n) | (x << (32 - n))) & MASK
+
+      def g(state, a, b, c, d, mx, my)
+        state[a] = (state[a] + state[b] + mx) & MASK
+        state[d] = rotr(state[d] ^ state[a], 16)
+        state[c] = (state[c] + state[d]) & MASK
+        state[b] = rotr(state[b] ^ state[c], 12)
+        state[a] = (state[a] + state[b] + my) & MASK
+        state[d] = rotr(state[d] ^ state[a], 8)
+        state[c] = (state[c] + state[d]) & MASK
+        state[b] = rotr(state[b] ^ state[c], 7)
+      end
+
+      def round(state, m)
+        g(state, 0, 4, 8, 12, m[0], m[1])
+        g(state, 1, 5, 9, 13, m[2], m[3])
+        g(state, 2, 6, 10, 14, m[4], m[5])
+        g(state, 3, 7, 11, 15, m[6], m[7])
+        g(state, 0, 5, 10, 15, m[8], m[9])
+        g(state, 1, 6, 11, 12, m[10], m[11])
+        g(state, 2, 7, 8, 13, m[12], m[13])
+        g(state, 3, 4, 9, 14, m[14], m[15])
+      end
+
+      # The one primitive: a chaining value and a block in, sixteen words
+      # out. The first eight are the next chaining value; all sixteen are
+      # the root's output.
+      def compress(cv, block, counter, block_len, flags)
+        state = [
+          cv[0], cv[1], cv[2], cv[3], cv[4], cv[5], cv[6], cv[7],
+          IV[0], IV[1], IV[2], IV[3],
+          counter & MASK, (counter >> 32) & MASK, block_len, flags
+        ]
+        m = block
+        7.times do |r|
+          round(state, m)
+          m = MSG_PERMUTATION.map { |i| m[i] } if r < 6
+        end
+        8.times do |i|
+          state[i] ^= state[i + 8]
+          state[i + 8] ^= cv[i]
+        end
+        state
+      end
+
+      def words_of(block)
+        block = block.ljust(BLOCK_LEN, "\x00") if block.bytesize < BLOCK_LEN
+        block.unpack('V16')
+      end
+
+      def parent_output(left, right, flags)
+        Output.new(IV.dup, left + right, 0, BLOCK_LEN, PARENT | flags)
+      end
+
+      def parent_cv(left, right, flags) = parent_output(left, right, flags).chaining_value
+    end
+
+    # A node's output, before anybody has decided whether it is the root.
+    # Which it is changes the flags, and so changes the bytes: that is what
+    # keeps a chunk's hash from being a tree's hash.
+    Output = Struct.new(:input_cv, :block_words, :counter, :block_len, :flags) do
+      def chaining_value
+        Blake3.compress(input_cv, block_words, counter, block_len, flags)[0, 8]
+      end
+
+      def root_bytes(length = OUT_LEN)
+        out = +''
+        counter = 0
+        while out.bytesize < length
+          words = Blake3.compress(input_cv, block_words, counter, block_len, flags | ROOT)
+          out << words.pack('V16')
+          counter += 1
+        end
+        out.byteslice(0, length)
+      end
+    end
+
+    # One chunk of at most 1024 bytes, compressed a block at a time.
+    class ChunkState
+      attr_reader :chunk_counter
+
+      def initialize(key, chunk_counter, flags)
+        @cv = key.dup
+        @chunk_counter = chunk_counter
+        @block = +''
+        @block.force_encoding(Encoding::BINARY)
+        @blocks_compressed = 0
+        @flags = flags
+      end
+
+      def length = (BLOCK_LEN * @blocks_compressed) + @block.bytesize
+
+      def start_flag = @blocks_compressed.zero? ? CHUNK_START : 0
+
+      def update(input)
+        offset = 0
+        while offset < input.bytesize
+          if @block.bytesize == BLOCK_LEN
+            @cv = Blake3.compress(@cv, Blake3.words_of(@block), @chunk_counter, BLOCK_LEN, @flags | start_flag)[0, 8]
+            @blocks_compressed += 1
+            @block = +''
+            @block.force_encoding(Encoding::BINARY)
+          end
+          want = BLOCK_LEN - @block.bytesize
+          take = [want, input.bytesize - offset].min
+          @block << input.byteslice(offset, take)
+          offset += take
+        end
+        self
+      end
+
+      def output
+        Output.new(@cv, Blake3.words_of(@block), @chunk_counter, @block.bytesize, @flags | start_flag | CHUNK_END)
+      end
+    end
+
+    # The streaming hasher. Chunks are merged into a binary tree as they
+    # complete, so hashing a 200 MB file costs a stack of at most 54
+    # chaining values.
+    class Hasher
+      def initialize(key: IV.dup, flags: 0)
+        @key = key
+        @flags = flags
+        @chunk = ChunkState.new(key, 0, flags)
+        @stack = []
+      end
+
+      def update(input)
+        input = input.b
+        offset = 0
+        while offset < input.bytesize
+          if @chunk.length == CHUNK_LEN
+            add_chunk(@chunk.output.chaining_value, @chunk.chunk_counter + 1)
+            @chunk = ChunkState.new(@key, @chunk.chunk_counter + 1, @flags)
+          end
+          want = CHUNK_LEN - @chunk.length
+          take = [want, input.bytesize - offset].min
+          @chunk.update(input.byteslice(offset, take))
+          offset += take
+        end
+        self
+      end
+
+      def digest(length = OUT_LEN)
+        output = @chunk.output
+        @stack.reverse_each do |left|
+          output = Blake3.parent_output(left, output.chaining_value, @flags)
+        end
+        output.root_bytes(length)
+      end
+
+      def hexdigest(length = OUT_LEN) = digest(length).unpack1('H*')
+
+      private
+
+      # A chunk's chaining value joins the tree, merging with everything to
+      # its left that is now complete — which is what the low bits of the
+      # chunk count say.
+      def add_chunk(cv, total_chunks)
+        while (total_chunks & 1).zero?
+          cv = Blake3.parent_cv(@stack.pop, cv, @flags)
+          total_chunks >>= 1
+        end
+        @stack.push(cv)
+      end
+    end
+  end
+end