bitclust-core 1.3.0 → 1.6.0

data/theme/default/js/NOTICE

@@ -0,0 +1,42 @@
+Third-party notices for theme/default/js/
+=========================================
+
+The following files are vendored verbatim from RDoc's Aliki theme
+(lib/rdoc/generator/template/aliki/js/), RDoc v7.2.0:
+
+  * search_navigation.js
+  * search_ranker.js
+  * search_controller.js
+
+Per RDoc's LEGAL.rdoc, the Aliki theme is written by Stan Lo and is included
+under the MIT License:
+
+  https://github.com/ruby/rdoc/blob/v7.2.0/LEGAL.rdoc
+
+----------------------------------------------------------------------
+MIT License
+
+Copyright (c) 2025 Stan Lo
+
+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.
+----------------------------------------------------------------------
+
+Note: search_init.js is original to BitClust and is not part of the vendored
+Aliki files. It is dual-licensed under the Ruby License or the MIT License so
+it can be used together with the MIT-licensed Aliki files above.

data/theme/default/js/run-worker.js

@@ -0,0 +1,111 @@
+// Module Worker that runs one RUN-button sample. Loaded by theme/default/js/run.js
+// via `new Worker(url, { type: 'module' })`; one Worker instance per execution
+// (see run.js for why: a fresh VM per run needs no cross-run state, and it
+// makes terminate()-to-stop trivial). Named .js rather than .mjs for the same
+// MIME-serving reason as run.js (see the comment at the top of that file).
+//
+// Protocol:
+//   main -> worker: { module: WebAssembly.Module, code: string }
+//   worker -> main: { type: 'output', text: string }   (zero or more, in order)
+//   worker -> main: { type: 'done' }                   (exactly one, on success)
+//   worker -> main: { type: 'error', message: string } (exactly one, on failure)
+// Exactly one of 'done'/'error' is posted, always last. The main thread may
+// also just call worker.terminate() (STOP button / timeout); the worker does
+// not need to post anything in that case.
+
+const VM_ESM_URL = 'https://cdn.jsdelivr.net/npm/@ruby/wasm-wasi@2.9.3-2.9.4/dist/browser/+esm'
+
+// Same idea as run.js's old (pre-Worker) PRELUDE -- redirect $stdout/$stderr
+// -- but instead of buffering into a StringIO for one bulk read at the end,
+// each write is forwarded to the main thread immediately via postOutput()
+// so long-running or infinite-output samples show progress instead of
+// growing an in-wasm string forever. $stderr shares the same sink so
+// interleaving still reads naturally, matching the previous StringIO-based
+// behavior. Ruby only ever hands the JS bridge a plain string, so
+// $stdout.write calls self.postOutput(), a small helper defined below
+// (rather than calling self.postMessage directly from Ruby) so that
+// postMessage itself stays the single place that emits the { type: ... }
+// envelope; main.onmessage never has to disambiguate a bare string from a
+// control message.
+//
+// Kernel#puts/print/p reach a non-IO $stdout through its #write, but the
+// manual's samples also call IO methods on $stdout/$stderr *directly*
+// ($stderr.puts, $stdout.putc, $stdout.print, $stdout.flush, $stderr.tty?,
+// ...). The old StringIO provided those for free, so the common ones are
+// implemented here; their semantics are covered by test/test_run_worker_prelude.rb,
+// which evals this prelude in a real Ruby with the JS bridge stubbed.
+export const PRELUDE = `
+require "js"
+class JSStreamIO
+  def write(*parts)
+    text = parts.join
+    JS.global.call(:postOutput, text)
+    text.bytesize
+  end
+  def <<(obj)
+    write(obj)
+    self
+  end
+  def puts(*args)
+    if args.empty?
+      write("\n")
+    else
+      args.flatten.each do |arg|
+        s = arg.to_s
+        s = s + "\n" unless s.end_with?("\n")
+        write(s)
+      end
+    end
+    nil
+  end
+  def print(*args)
+    write(args.join)
+    nil
+  end
+  def printf(*args)
+    write(sprintf(*args))
+    nil
+  end
+  def putc(ch)
+    write(ch.is_a?(String) ? ch[0] : ch.chr)
+    ch
+  end
+  def flush; self; end
+  def sync; true; end
+  def sync=(value); value; end
+  def tty?; false; end
+  alias isatty tty?
+end
+$stdout = JSStreamIO.new
+$stderr = $stdout
+`
+
+export function formatRunError(error) {
+  const text = String((error && error.message) || error)
+  return text.split('\n').slice(0, 20).join('\n')
+}
+
+// Guarded the same way run.js guards its init(): this file is imported by
+// test/js/test_run.mjs under QuickJS, which has neither `self` (as the
+// Worker global) nor a real postMessage/onmessage.
+if (typeof self !== 'undefined' && typeof WorkerGlobalScope !== 'undefined') {
+  self.postOutput = (text) => self.postMessage({ type: 'output', text })
+
+  self.onmessage = async (event) => {
+    const { module, code } = event.data
+    try {
+      const { DefaultRubyVM } = await import(VM_ESM_URL)
+      const { vm } = await DefaultRubyVM(module, { consolePrint: false })
+      vm.eval(PRELUDE)
+      try {
+        vm.eval(code)
+      } catch (e) {
+        self.postMessage({ type: 'error', message: formatRunError(e) })
+        return
+      }
+      self.postMessage({ type: 'done' })
+    } catch (e) {
+      self.postMessage({ type: 'error', message: formatRunError(e) })
+    }
+  }
+}

data/theme/default/js/run.js

@@ -0,0 +1,350 @@
+// RUN button for Ruby sample code: executes the sample in-browser with
+// ruby.wasm, off the main thread in a Web Worker (theme/default/js/run-worker.js)
+// so an infinite loop or long sleep in the sample can't freeze the page; a
+// STOP button and a timeout both just Worker.terminate() it. Named .js
+// rather than .mjs: module scripts are subject to strict MIME checking, and
+// servers whose MIME table lacks an "mjs" entry (e.g. nginx before 1.21.4)
+// serve .mjs as application/octet-stream, which browsers refuse to execute.
+// The same reasoning applies to run-worker.js. Enabled per page via
+//   <meta name="rurema-run-ruby-wasm" content="<ruby+stdlib.wasm URL>">
+// which the layout emits when statichtml was invoked with --run-ruby-wasm.
+// The wasm URL is chosen by the build side to match the documented Ruby
+// version. This file only compiles that wasm (WebAssembly.compileStreaming
+// needs no loader library, just the bytes); the CDN-hosted @ruby/wasm-wasi
+// loader is pinned and imported inside run-worker.js, which is the only
+// place that actually instantiates a VM from the compiled module.
+const OUTPUT_LIMIT = 64 * 1024
+const RUN_TIMEOUT_MS = 30 * 1000
+
+// Resolved relative to this module's own URL (not the page URL), so it keeps
+// working regardless of how deep the current page is under the site root or
+// how custom_js_url() built run.js's own <script src>. Computed lazily
+// (rather than as a module-level constant) because the `URL` global does
+// not exist under QuickJS, which imports this file for its pure-function
+// tests without ever calling into the browser-only code path below.
+function workerUrl() {
+  return new URL('run-worker.js', import.meta.url)
+}
+
+// Wrap an async loader so concurrent and repeated calls share one in-flight
+// promise, while a rejected attempt clears the cache so the next call
+// retries instead of staying broken forever.
+export function createOnceLoader(loadFn) {
+  let cached
+  return function () {
+    if (!cached) {
+      cached = (async () => {
+        try {
+          return await loadFn()
+        } catch (error) {
+          cached = undefined
+          throw error
+        }
+      })()
+    }
+    return cached
+  }
+}
+
+export function formatRunError(error) {
+  const text = String((error && error.message) || error)
+  return text.split('\n').slice(0, 20).join('\n')
+}
+
+export function truncateOutput(text, limit = OUTPUT_LIMIT) {
+  if (text.length <= limit) return text
+  return text.slice(0, limit) + '\n... (truncated)'
+}
+
+// Appends one output chunk to the accumulated text, applying the same
+// display cap as truncateOutput. Once the cap is hit, further chunks are
+// dropped (not just re-truncating the same prefix again and again), so a
+// runaway output loop does the "... (truncated)" marker once and then does
+// O(1) work per chunk instead of O(output length).
+export function accumulateOutput(current, chunk, limit = OUTPUT_LIMIT) {
+  if (current.endsWith('\n... (truncated)')) return current
+  return truncateOutput(current + chunk, limit)
+}
+
+export const STOPPED_NOTE = '(停止しました)'
+// 出力が空のサンプルでも実行が終わったことがわかるように、
+// 正常終了時も必ずこの注記を出力欄の末尾に付ける
+export const DONE_NOTE = '(正常終了しました)'
+export function timeoutNote(seconds) {
+  return `(${seconds}秒でタイムアウトしました)`
+}
+
+// Text used when flattening the highlighted sample for editing. The
+// compiler emits a newline right after <code>, which textContent keeps —
+// left as-is it shows up as an empty first line once the block becomes
+// editable (script.js strips the same artifact for COPY).
+export function editableText(text) {
+  return text.replace(/^\n+/, '')
+}
+
+// Compiles the wasm module once (cached like the old single-VM version) and
+// hands a fresh Worker + that same compiled Module to each run. The Module
+// is a structured-cloneable postMessage payload, so terminate()-ing a run
+// and starting another never needs to recompile.
+function createRunner(wasmUrl) {
+  const loadModule = createOnceLoader(async () => {
+    return WebAssembly.compileStreaming(fetch(wasmUrl)).catch(async () => {
+      // Retry without streaming for servers that send a non-wasm MIME type
+      // (e.g. `ruby -run -e httpd` when testing locally).
+      const response = await fetch(wasmUrl)
+      return WebAssembly.compile(await response.arrayBuffer())
+    })
+  })
+  return {
+    loadModule,
+    // One Worker per run (see module comment): terminate() always yields a
+    // clean slate, and samples never see another run's VM state.
+    spawn() {
+      return new Worker(workerUrl(), { type: 'module' })
+    },
+  }
+}
+
+function setupBlock(pre, runner) {
+  const code = pre.querySelector('code')
+  if (!code) return
+
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.className = 'highlight__run-button'
+  button.textContent = 'RUN'
+  // script.js has already inserted the toolbar row (with the COPY button
+  // in its button group) right before the pre — its window.onload handler
+  // fires before our load listener. Prepend RUN into the same group so
+  // COPY stays rightmost. The buttons live outside the pre: keeping them
+  // inside required a zero top padding, made the cursor flicker between
+  // pointer and text, and broke the editable-code layout.
+  const toolbar = pre.previousElementSibling
+  let group = toolbar && toolbar.classList.contains('highlight__toolbar')
+    ? toolbar.querySelector('.highlight__button-group')
+    : null
+  if (!group) {
+    // script.js が無いテーマ向けの保険: 最小構成のツールバーを自前で作る
+    const ownToolbar = document.createElement('div')
+    ownToolbar.className = 'highlight__toolbar'
+    group = document.createElement('span')
+    group.className = 'highlight__button-group'
+    ownToolbar.appendChild(group)
+    pre.before(ownToolbar)
+  }
+  group.prepend(button)
+
+  let output
+  let outputTextNode
+  const ensureOutput = () => {
+    if (!output) {
+      output = document.createElement('pre')
+      output.className = 'highlight__run-output'
+      output.setAttribute('aria-live', 'polite')
+      // 出力テキストは専用のテキストノードに持つ(丸ごと差し替えられる)
+      outputTextNode = document.createTextNode('')
+      output.appendChild(outputTextNode)
+      pre.after(output)
+      // 実行結果もコピーできるようにする(script.js の公開フック)。
+      // 出力は実行のたびに変わるので、クリック時のテキストを渡す
+      if (window.ruremaAddCopyButton) {
+        window.ruremaAddCopyButton(output, () => outputTextNode.data)
+        // 出力欄のヘッダー行と出力欄は、入力欄の pre に密着させて
+        // 1つのブロックに見せる(境の 2px の白は CSS 側)。左端には
+        // 出力欄だとわかるように「実行結果」のタブを付ける
+        const outToolbar = output.previousElementSibling
+        if (outToolbar && outToolbar.classList.contains('highlight__toolbar')) {
+          outToolbar.classList.add('highlight__toolbar--attached')
+          const label = document.createElement('span')
+          label.className = 'caption'
+          label.textContent = '実行結果'
+          outToolbar.insertBefore(label, outToolbar.firstChild)
+          pre.classList.add('highlight--with-output')
+        }
+      }
+    }
+    return output
+  }
+  const setOutputText = (text) => {
+    outputTextNode.data = text
+  }
+
+  // plaintext-only が使えないブラウザ向けの paste フォールバック。
+  // 既定のリッチペーストは改行を <br>/<div> に変えたり先頭の改行を
+  // 落としたりする(貼り付けた内容が前の行にくっつく)ので、text/plain
+  // をキャレット位置にそのまま挿入する
+  const pastePlainText = (event) => {
+    if (!event.clipboardData) return
+    event.preventDefault()
+    const text = event.clipboardData.getData('text/plain')
+    const selection = window.getSelection()
+    if (!selection || selection.rangeCount === 0) return
+    const range = selection.getRangeAt(0)
+    range.deleteContents()
+    const node = document.createTextNode(text)
+    range.insertNode(node)
+    range.setStartAfter(node)
+    range.collapse(true)
+    selection.removeAllRanges()
+    selection.addRange(range)
+  }
+
+  // After the first run the sample becomes editable (like a scratchpad);
+  // Ctrl+Enter (or Cmd+Enter) re-runs the edited code. The COPY button
+  // keeps copying the original text.
+  const enableEditing = () => {
+    if (code.isContentEditable) return
+    // 編集でハイライトの span に文字が食い込むと、貼り付けた文字が
+    // その場の色を引き継いで中途半端に崩れるため、編集可能にする
+    // 時点でプレーンテキスト化して色を消す。コンパイラが <code> の
+    // 直後に置く改行(編集開始時に先頭の空行として見える)もここで除く
+    code.textContent = editableText(code.textContent)
+    // 改行入力・貼り付けが <br>/<div> にならないよう plaintext-only を
+    // 優先する。未対応ブラウザは代入が SyntaxError になるか値が変わらない
+    // ので、従来どおり true にして paste だけ自前で処理する
+    try {
+      code.contentEditable = 'plaintext-only'
+    } catch (e) {
+      // fall through
+    }
+    if (code.contentEditable !== 'plaintext-only') {
+      code.contentEditable = 'true'
+      code.addEventListener('paste', pastePlainText)
+    }
+    code.spellcheck = false
+    pre.dataset.editing = 'true'
+    pre.addEventListener('keydown', (event) => {
+      if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) {
+        event.preventDefault()
+        execute()
+      }
+    })
+    // code は内容ぶんの高さしかないので、その外側(pre の padding や
+    // 1行サンプルの下の余白)をクリックしたときも入力欄に入れるよう、
+    // pre 自身へのクリックで code にフォーカスして末尾にキャレットを置く
+    pre.addEventListener('click', (event) => {
+      if (event.target !== pre) return
+      code.focus()
+      const selection = window.getSelection()
+      if (!selection) return
+      const range = document.createRange()
+      range.selectNodeContents(code)
+      range.collapse(false)
+      selection.removeAllRanges()
+      selection.addRange(range)
+    })
+  }
+
+  // Non-null exactly while a run's Worker is alive; STOP terminates it and
+  // the timeout/message handlers all check this to avoid acting twice on
+  // the same run (e.g. a timeout racing a message that just arrived).
+  let current = null
+
+  const finish = (out, label, isError) => {
+    if (current && current.timer) clearTimeout(current.timer)
+    current = null
+    if (isError) out.classList.add('highlight__run-output--error')
+    enableEditing()
+    button.textContent = label
+    button.disabled = false
+    button.removeAttribute('aria-busy')
+  }
+
+  // Final notes (stop / timeout / the run's error message) are appended
+  // directly, bypassing accumulateOutput's 64KB cap: the cap exists to stop
+  // unbounded *output* growth, and these one-shot notes are bounded — they
+  // must stay visible precisely in the runaway-output case where the cap
+  // has already been hit and accumulateOutput would drop them.
+  const appendNote = (text) => {
+    const separator = outputTextNode.data === '' ? '' : '\n'
+    setOutputText(outputTextNode.data + separator + text)
+  }
+
+  const stop = () => {
+    if (!current) return
+    current.worker.terminate()
+    const out = ensureOutput()
+    appendNote(STOPPED_NOTE)
+    finish(out, 'RUN', false)
+  }
+
+  const execute = async () => {
+    if (current) return // mid-run click on the (now STOP-labeled) button; use the dedicated STOP path
+    if (button.disabled) return
+    button.disabled = true
+    button.setAttribute('aria-busy', 'true')
+    button.textContent = 'LOADING...'
+    const out = ensureOutput()
+    out.classList.remove('highlight__run-output--error')
+    setOutputText('')
+
+    let module
+    try {
+      module = await runner.loadModule()
+    } catch (e) {
+      setOutputText(formatRunError(e))
+      finish(out, 'RETRY', true)
+      return
+    }
+
+    const worker = runner.spawn()
+    const timer = setTimeout(() => {
+      if (!current) return
+      worker.terminate()
+      appendNote(timeoutNote(RUN_TIMEOUT_MS / 1000))
+      finish(out, 'RUN', false)
+    }, RUN_TIMEOUT_MS)
+    current = { worker, timer }
+
+    button.textContent = 'STOP'
+    button.disabled = false
+    button.setAttribute('aria-busy', 'true')
+
+    worker.onmessage = (event) => {
+      const message = event.data
+      if (!current || current.worker !== worker) return
+      if (message.type === 'output') {
+        setOutputText(accumulateOutput(outputTextNode.data, message.text))
+      } else if (message.type === 'done') {
+        appendNote(DONE_NOTE)
+        finish(out, 'RUN', false)
+      } else if (message.type === 'error') {
+        appendNote(message.message)
+        finish(out, 'RUN', true)
+      }
+    }
+    worker.onerror = (event) => {
+      if (!current || current.worker !== worker) return
+      event.preventDefault()
+      setOutputText(formatRunError(event.message || event))
+      finish(out, 'RETRY', true)
+    }
+    worker.postMessage({ module, code: code.textContent })
+  }
+  button.addEventListener('click', () => {
+    if (current) {
+      stop()
+    } else {
+      execute()
+    }
+  })
+}
+
+function init() {
+  const meta = document.querySelector('meta[name="rurema-run-ruby-wasm"]')
+  if (!meta || !meta.content) return
+  const blocks = document.querySelectorAll('pre.highlight.ruby')
+  if (blocks.length === 0) return
+  const runner = createRunner(meta.content)
+  blocks.forEach((pre) => setupBlock(pre, runner))
+}
+
+// Guarded so the module stays side-effect-free outside a browser
+// (test/js/test_run.mjs imports it under QuickJS).
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+  if (document.readyState === 'complete') {
+    init()
+  } else {
+    window.addEventListener('load', init)
+  }
+}

data/theme/default/js/search_controller.js

@@ -0,0 +1,134 @@
+/*
+ * Vendored from RDoc's Aliki theme (lib/rdoc/generator/template/aliki/js/), RDoc v7.2.0.
+ * Copyright (c) 2025 Stan Lo. Released under the MIT License.
+ * See https://github.com/ruby/rdoc/blob/v7.2.0/LEGAL.rdoc
+ */
+SearchController = function(data, input, result) {
+  this.data = data;
+  this.input = input;
+  this.result = result;
+
+  this.current = null;
+  this.view = this.result.parentNode;
+  this.ranker = new SearchRanker(data.index);
+  this.init();
+}
+
+SearchController.prototype = Object.assign({}, SearchNavigation, new function() {
+  var suid = 1;
+
+  this.init = function() {
+    var _this = this;
+    var observer = function(e) {
+      switch(e.key) {
+        case 'ArrowUp':
+        case 'ArrowDown':
+          return;
+      }
+      _this.search(_this.input.value);
+    };
+    this.input.addEventListener('keyup', observer);
+    this.input.addEventListener('click', observer); // mac's clear field
+
+    this.ranker.ready(function(results, isLast) {
+      _this.addResults(results, isLast);
+    })
+
+    this.initNavigation();
+    this.setNavigationActive(false);
+  }
+
+  this.search = function(value, selectFirstMatch) {
+    this.selectFirstMatch = selectFirstMatch;
+
+    value = value.trim();
+    if (value) {
+      this.setNavigationActive(true);
+    } else {
+      this.setNavigationActive(false);
+    }
+
+    if (value == '') {
+      this.lastQuery = value;
+      this.result.innerHTML = '';
+      this.result.setAttribute('aria-expanded', 'false');
+      this.setNavigationActive(false);
+    } else if (value != this.lastQuery) {
+      this.lastQuery = value;
+      this.result.setAttribute('aria-busy',     'true');
+      this.result.setAttribute('aria-expanded', 'true');
+      this.firstRun = true;
+      this.ranker.find(value);
+    }
+  }
+
+  this.addResults = function(results, isLast) {
+    var target = this.result;
+    if (this.firstRun && (results.length > 0 || isLast)) {
+      this.current = null;
+      this.result.innerHTML = '';
+    }
+
+    for (var i=0, l = results.length; i < l; i++) {
+      var item = this.renderItem.call(this, results[i]);
+      item.setAttribute('id', 'search-result-' + target.childElementCount);
+      target.appendChild(item);
+    };
+
+    if (this.firstRun && results.length > 0) {
+      this.firstRun = false;
+      this.current = target.firstChild;
+      this.current.classList.add('search-selected');
+    }
+    //TODO: ECMAScript
+    //if (jQuery.browser.msie) this.$element[0].className += '';
+
+    if (this.selectFirstMatch && this.current) {
+      this.selectFirstMatch = false;
+      this.select(this.current);
+    }
+
+    if (isLast) {
+      this.selectFirstMatch = false;
+      this.result.setAttribute('aria-busy', 'false');
+    }
+  }
+
+  this.move = function(isDown) {
+    if (!this.current) return;
+    var next = isDown ? this.current.nextElementSibling : this.current.previousElementSibling;
+    if (next) {
+      this.current.classList.remove('search-selected');
+      next.classList.add('search-selected');
+      this.input.setAttribute('aria-activedescendant', next.getAttribute('id'));
+      this.scrollInElement(next, this.result);
+      this.current = next;
+      this.input.value = next.firstChild.firstChild.text;
+      this.input.select();
+    }
+    return true;
+  }
+
+  this.hlt = function(html) {
+    return this.escapeHTML(html).
+      replace(/\u0001/g, '<em>').
+      replace(/\u0002/g, '</em>');
+  }
+
+  this.escapeHTML = function(html) {
+    return html.replace(/[&<>"`']/g, function(c) {
+      return '&#' + c.charCodeAt(0) + ';';
+    });
+  }
+
+  this.hide = function() {
+    this.result.setAttribute('aria-expanded', 'false');
+    this.setNavigationActive(false);
+  }
+
+  this.show = function() {
+    this.result.setAttribute('aria-expanded', 'true');
+    this.setNavigationActive(true);
+  }
+});
+