@rayfold/explorer 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+Rayfold
+Copyright 2026 The Rayfold Authors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+The data in data/gutenberg.json.gz is derived from the Project Gutenberg catalogue
+(https://www.gutenberg.org/ebooks/offline_catalogs.html) and is not covered by this
+project's copyright. See data/README.md for its source. Project Gutenberg is a
+registered trademark of the Project Gutenberg Literary Archive Foundation; Rayfold is
+not affiliated with or endorsed by Project Gutenberg.

package/README.md

@@ -0,0 +1,55 @@
+# @rayfold/explorer
+
+The page a [Rayfold](https://github.com/eddyboutros/rayfold) server serves next to its endpoint: the counterpart of
+Swagger UI and GraphiQL. It reads the server's manifest, so it shows what the schema actually says rather than a copy
+that can drift.
+
+```sh
+npm install @rayfold/explorer
+```
+
+```ts
+import { createServer } from "node:http";
+import { createHttpHandler } from "@rayfold/server";
+import { createExplorerHandler } from "@rayfold/explorer";
+
+const endpoint = createHttpHandler(server, { viewer });
+const explorer = createExplorerHandler({ endpoint: "/rayfold", title: "Acme API" });
+
+createServer((req, res) => {
+  if (explorer(req, res)) return;          // serves /rayfold/explorer
+  if ((req.url ?? "").startsWith("/rayfold")) return endpoint(req, res);
+  res.writeHead(404).end();
+});
+```
+
+The page lists every operation with its arguments, what it returns, what it costs and which policies guard it; fills
+in a request with a shape that selects the scalar fields of the result, as a starting point; sends the batch to the
+endpoint like any other client; and shows the frames as they arrive, each with its cost. A command that allows
+`@simulate` can be run as a **dry run**, which reports what would happen and writes nothing. A query can be sent
+`live`, and the frames keep arriving as the data changes.
+
+It is one self-contained document: no fonts, scripts or styles from anywhere else, so it works behind a strict
+`Content-Security-Policy` and with no network beyond your own server.
+
+## Where it is served, and to whom
+
+Nothing is served unless you mount it. The explorer talks to the endpoint as a browser client: what a visitor can read
+through it is exactly what the endpoint's own policies allow for the token they paste into it, and no more. On a public
+deployment, mount it behind the same authentication as the rest of your administration pages, or only in development:
+
+```ts
+if (process.env.NODE_ENV !== "production") app.use(createExplorerHandler());
+```
+
+`explorerHtml(options)` returns the same page as a string, for serving it from a framework of your own.
+
+## Options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `endpoint` | `/rayfold` | Where the page sends its batches, and where it reads the manifest. |
+| `path` | `<endpoint>/explorer` | Where the page itself is served. |
+| `title` | `Rayfold` | Shown in the header, to tell one service from another. |
+
+Apache-2.0.

package/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The Rayfold explorer: the page a Rayfold server serves next to its endpoint, the counterpart of Swagger UI and
+ * GraphiQL. It lists every operation the manifest declares with its arguments, result, cost and the policies that
+ * guard it; helps write a shape; sends a batch and shows the frames as they arrive, with their cost; and dry-runs a
+ * command that allows `@simulate`, so trying one changes nothing.
+ *
+ * It talks to the endpoint over HTTP like any other client, so it needs no access to the server object and adds no
+ * dependency to it. Mount it where you like:
+ *
+ *   const explorer = createExplorerHandler({ endpoint: "/rayfold", title: "Acme API" });
+ *   createServer((req, res) => { if (explorer(req, res)) return; ... });
+ *
+ * Nothing is served unless you mount it, so a production deployment exposes it only on purpose.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export interface ExplorerOptions {
+    /** Where the Rayfold endpoint is mounted. Default `/rayfold`. */
+    endpoint?: string;
+    /** Where this page is served. Default `<endpoint>/explorer`. */
+    path?: string;
+    /** Shown in the header, to tell one service from another. */
+    title?: string;
+}
+/** The page itself, for serving from a framework of your own. */
+export declare function explorerHtml(opts?: ExplorerOptions): string;
+/**
+ * A Node handler that serves the page. It answers only its own path and returns false for anything else, so it can
+ * sit in front of the rest of an application.
+ */
+export declare function createExplorerHandler(opts?: ExplorerOptions): (req: IncomingMessage, res: ServerResponse) => boolean;

package/index.js

@@ -0,0 +1,271 @@
+const settings = (opts = {}) => {
+    const endpoint = opts.endpoint ?? "/rayfold";
+    return {
+        endpoint,
+        path: opts.path ?? `${endpoint}/explorer`,
+        config: { endpoint, title: opts.title ?? "Rayfold" },
+    };
+};
+/** The page itself, for serving from a framework of your own. */
+export function explorerHtml(opts = {}) {
+    return PAGE.replace("__RAYFOLD_EXPLORER_CONFIG__", JSON.stringify(settings(opts).config).replace(/</g, "\\u003c"));
+}
+/**
+ * A Node handler that serves the page. It answers only its own path and returns false for anything else, so it can
+ * sit in front of the rest of an application.
+ */
+export function createExplorerHandler(opts = {}) {
+    const { path } = settings(opts);
+    const html = explorerHtml(opts);
+    return (req, res) => {
+        const url = (req.url ?? "/").split("?")[0];
+        if (url !== path && url !== `${path}/`)
+            return false;
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            res.writeHead(405, { allow: "GET, HEAD" }).end();
+            return true;
+        }
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        res.end(req.method === "HEAD" ? undefined : html);
+        return true;
+    };
+}
+// The page is one self-contained document: no fonts, scripts or styles from anywhere else, so it works behind a
+// strict content-security-policy and offline. Client code avoids template literals, since this is one itself.
+const PAGE = String.raw `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Rayfold explorer</title>
+<style>
+:root { color-scheme: light dark; --ink: #16202b; --muted: #5b6875; --rule: #d6dde5; --surface: #fff; --ground: #f3f6f9; --accent: #2a78d6; --ok: #0a7d3f; --bad: #b3261e; }
+@media (prefers-color-scheme: dark) { :root { --ink: #e8eef5; --muted: #a2aebc; --rule: #2b333d; --surface: #171c22; --ground: #0f1318; --accent: #5aa2f0; --ok: #4cc073; --bad: #f2836f; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--ground); color: var(--ink); font: 14px/1.55 ui-sans-serif, system-ui, "Segoe UI", sans-serif; }
+header { display: flex; gap: 12px; align-items: baseline; padding: 12px 16px; border-bottom: 1px solid var(--rule); background: var(--surface); }
+header h1 { font-size: 15px; margin: 0; font-weight: 600; }
+header .meta { color: var(--muted); font: 12px/1.4 ui-monospace, monospace; }
+main { display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 0; height: calc(100vh - 49px); }
+@media (max-width: 800px) { main { grid-template-columns: 1fr; height: auto; } }
+aside { border-right: 1px solid var(--rule); overflow: auto; background: var(--surface); }
+aside h2 { font: 600 11px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); margin: 14px 12px 6px; }
+button.op { display: block; width: 100%; text-align: left; border: 0; background: none; color: inherit; font: inherit; padding: 6px 12px; cursor: pointer; }
+button.op:hover, button.op.on { background: var(--ground); }
+button.op .kind { font: 11px ui-monospace, monospace; color: var(--muted); margin-left: 6px; }
+section.work { display: grid; grid-template-rows: auto auto 1fr; min-width: 0; }
+.doc { padding: 12px 16px; border-bottom: 1px solid var(--rule); background: var(--surface); }
+.doc h3 { margin: 0 0 4px; font-size: 15px; }
+.doc dl { display: grid; grid-template-columns: 92px minmax(0, 1fr); gap: 2px 10px; margin: 6px 0 0; font-size: 13px; }
+.doc dt { color: var(--muted); font: 12px ui-monospace, monospace; }
+.doc dd { margin: 0; font-family: ui-monospace, monospace; overflow-wrap: anywhere; }
+.editor { display: grid; gap: 8px; padding: 12px 16px; border-bottom: 1px solid var(--rule); }
+textarea, input[type=text] { width: 100%; font: 12.5px/1.5 ui-monospace, monospace; color: inherit; background: var(--surface); border: 1px solid var(--rule); border-radius: 6px; padding: 8px; }
+textarea { min-height: 120px; resize: vertical; }
+.row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+.row label { font-size: 12.5px; color: var(--muted); display: flex; gap: 5px; align-items: center; }
+button.go { background: var(--accent); color: #fff; border: 0; border-radius: 6px; padding: 7px 14px; font: 600 13px/1 inherit; cursor: pointer; }
+button.go:disabled { opacity: .55; cursor: default; }
+.out { overflow: auto; padding: 12px 16px; display: grid; gap: 8px; align-content: start; }
+.frame { border: 1px solid var(--rule); border-left-width: 3px; border-radius: 6px; background: var(--surface); padding: 8px 10px; }
+.frame pre { margin: 4px 0 0; font: 12px/1.5 ui-monospace, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+.frame .tag { font: 600 11px ui-monospace, monospace; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); }
+.frame.ok, .frame.data { border-left-color: var(--ok); }
+.frame.error { border-left-color: var(--bad); }
+.frame.patch, .frame.item, .frame.at { border-left-color: var(--accent); }
+.hint { color: var(--muted); font-size: 12.5px; }
+code { font-family: ui-monospace, monospace; }
+</style>
+</head>
+<body>
+<script type="application/json" id="config">__RAYFOLD_EXPLORER_CONFIG__</script>
+<header>
+  <h1 id="title">Rayfold</h1>
+  <span class="meta" id="about">reading the manifest...</span>
+</header>
+<main>
+  <aside id="ops"></aside>
+  <section class="work">
+    <div class="doc" id="doc"><p class="hint">Pick an operation on the left. The explorer reads everything it shows from the server's manifest.</p></div>
+    <div class="editor">
+      <textarea id="req" spellcheck="false"></textarea>
+      <div class="row">
+        <button class="go" id="send">Send</button>
+        <label><input type="checkbox" id="simulate"> dry run</label>
+        <label><input type="checkbox" id="live"> live</label>
+        <label>auth <input type="text" id="token" placeholder="bearer token" style="width:170px"></label>
+        <span class="hint" id="status"></span>
+      </div>
+      <p class="hint">A batch can hold several ops, and a later one can use an earlier result: <code>{"$ref": "1.id"}</code> in its args. Ctrl+Enter sends.</p>
+    </div>
+    <div class="out" id="out"></div>
+  </section>
+</main>
+<script>
+var CONFIG = JSON.parse(document.getElementById("config").textContent);
+var $ = function (sel) { return document.querySelector(sel); };
+var manifest = null;
+var current = null;
+
+document.getElementById("title").textContent = CONFIG.title;
+
+function text(node, s) { node.textContent = s; return node; }
+function el(tag, cls, s) { var n = document.createElement(tag); if (cls) n.className = cls; if (s !== undefined) n.textContent = s; return n; }
+function typeName(t) {
+  if (!t) return "?";
+  if (t.kind === "list") return "[" + typeName(t.of) + "]" + (t.nullable ? "?" : "");
+  var args = t.args && t.args.length ? "<" + t.args.map(typeName).join(", ") + ">" : "";
+  return t.name + args + (t.nullable ? "?" : "");
+}
+function annotationsOf(def, name) { return (def.annotations || []).filter(function (a) { return a.name === name; }); }
+function costOf(def) {
+  var c = annotationsOf(def, "cost")[0];
+  if (!c) return "default";
+  return Object.keys(c.args).map(function (k) { return k + " " + JSON.stringify(c.args[k]); }).join(", ");
+}
+function policiesOf(def) {
+  var names = [];
+  annotationsOf(def, "allow").forEach(function () { names.push("allow"); });
+  annotationsOf(def, "deny").forEach(function () { names.push("deny"); });
+  return names.length ? names.join(", ") : "none on the operation";
+}
+/** A shape that selects the scalar fields of what an op returns: a starting point, not a rule. */
+function defaultShape(typeRef) {
+  var base = typeRef;
+  while (base && base.kind === "list") base = base.of;
+  if (!base) return "";
+  var def = manifest.schema.types[base.name];
+  if (!def || !def.fields) return "";
+  if (base.name === "Page" && base.args && base.args.length) {
+    return "{ total hasMore cursor items " + (defaultShape(base.args[0]) || "{ id }") + " }";
+  }
+  var scalars = def.fields.filter(function (f) {
+    var t = f.type.kind === "list" ? f.type.of : f.type;
+    var sub = manifest.schema.types[t.name];
+    return !f.args.length && sub && (sub.kind === "scalar" || sub.kind === "enum");
+  });
+  if (!scalars.length) return "";
+  return "{ " + scalars.map(function (f) { return f.name; }).join(" ") + " }";
+}
+function argSkeleton(def) {
+  var args = {};
+  def.args.forEach(function (a) {
+    if (a.default !== undefined) { args[a.name] = a.default; return; }
+    var t = a.type.kind === "list" ? a.type.of : a.type;
+    var sub = manifest.schema.types[t.name];
+    args[a.name] = a.type.kind === "list" ? [] : sub && sub.kind === "enum" ? sub.values[0].name : t.name === "Int" || t.name === "Float" || t.name === "Long" ? 0 : t.name === "Boolean" ? false : "";
+  });
+  return args;
+}
+function show(op) {
+  current = op;
+  Array.prototype.forEach.call(document.querySelectorAll("button.op"), function (b) { b.classList.toggle("on", b.dataset.op === op.name); });
+  var doc = document.getElementById("doc");
+  doc.innerHTML = "";
+  doc.appendChild(el("h3", null, op.name + "(" + op.args.map(function (a) { return a.name + ": " + typeName(a.type); }).join(", ") + ")"));
+  if (op.description) doc.appendChild(el("p", "hint", op.description));
+  var dl = el("dl");
+  function add(k, v) { dl.appendChild(el("dt", null, k)); dl.appendChild(el("dd", null, v)); }
+  add("kind", op.kind);
+  add("returns", typeName(op.returns));
+  add("cost", costOf(op));
+  add("policies", policiesOf(op));
+  if (op.throws && op.throws.length) add("throws", op.throws.join(" | "));
+  if (op.emits && op.emits.length) add("emits", op.emits.join(" "));
+  if (annotationsOf(op, "simulate").length) add("dry run", "allowed: tick it and nothing is written");
+  doc.appendChild(dl);
+
+  var request = { ops: [{ id: 1, op: op.name, args: argSkeleton(op) }] };
+  var shape = defaultShape(op.returns);
+  if (shape) request.ops[0].shape = shape;
+  if (op.kind === "command") request.ops[0].key = "explorer-" + Math.random().toString(36).slice(2).padEnd(16, "0").slice(0, 16);
+  $("#req").value = JSON.stringify(request, null, 2);
+  $("#simulate").disabled = op.kind !== "command";
+  $("#live").disabled = op.kind !== "query";
+}
+function render(frames, ms) {
+  var out = document.getElementById("out");
+  out.innerHTML = "";
+  frames.forEach(function (f) {
+    var kind = "error" in f ? "error" : "ok" in f ? "ok" : "at" in f ? "at" : "patch" in f ? "patch" : "item" in f ? "item" : "data" in f ? "data" : "fin";
+    var box = el("div", "frame " + kind);
+    var cost = f.meta && f.meta.cost !== undefined ? "  cost " + f.meta.cost : "";
+    box.appendChild(el("span", "tag", kind + (f.id !== undefined ? " · op " + f.id : "") + cost));
+    box.appendChild(el("pre", null, JSON.stringify(f, null, 2)));
+    out.appendChild(box);
+  });
+  $("#status").textContent = frames.length + (frames.length === 1 ? " frame" : " frames") + " in " + ms + " ms";
+}
+async function send() {
+  var button = $("#send");
+  button.disabled = true;
+  $("#status").textContent = "sending...";
+  var started = Date.now();
+  try {
+    var body = JSON.parse($("#req").value);
+    if (current && current.kind === "command" && $("#simulate").checked) body.ops.forEach(function (o) { o.simulate = true; });
+    if (current && current.kind === "query" && $("#live").checked) body.ops.forEach(function (o) { o.live = true; });
+    var headers = { "content-type": "application/rayfold+json" };
+    if ($("#token").value) headers.authorization = "Bearer " + $("#token").value;
+    var res = await fetch(CONFIG.endpoint, { method: "POST", headers: headers, body: JSON.stringify(body) });
+    var frames = [];
+    var reader = res.body.getReader();
+    var decoder = new TextDecoder();
+    var buffered = "";
+    for (;;) {
+      var chunk = await reader.read();
+      if (chunk.done) break;
+      buffered += decoder.decode(chunk.value, { stream: true });
+      var cut;
+      while ((cut = buffered.indexOf(String.fromCharCode(10))) >= 0) {
+        var line = buffered.slice(0, cut);
+        buffered = buffered.slice(cut + 1);
+        if (line.trim()) frames.push(JSON.parse(line));
+        render(frames, Date.now() - started);
+      }
+    }
+    if (buffered.trim()) frames.push(JSON.parse(buffered));
+    render(frames, Date.now() - started);
+  } catch (e) {
+    $("#out").innerHTML = "";
+    var box = el("div", "frame error");
+    box.appendChild(el("span", "tag", "explorer"));
+    box.appendChild(el("pre", null, String(e && e.message ? e.message : e)));
+    $("#out").appendChild(box);
+    $("#status").textContent = "";
+  } finally {
+    button.disabled = false;
+  }
+}
+async function start() {
+  try {
+    manifest = await (await fetch(CONFIG.endpoint + "/manifest")).json();
+  } catch (e) {
+    text(document.getElementById("about"), "no manifest at " + CONFIG.endpoint + "/manifest");
+    return;
+  }
+  text(document.getElementById("about"), "rayfold " + manifest.rayfold + " · schema " + String(manifest.schemaHash).slice(0, 12) + " · extensions " + (manifest.extensions || []).join(", "));
+  var ops = Object.keys(manifest.schema.ops).map(function (n) { return manifest.schema.ops[n]; });
+  var aside = document.getElementById("ops");
+  ["query", "command", "stream"].forEach(function (kind) {
+    var mine = ops.filter(function (o) { return o.kind === kind; }).sort(function (a, b) { return a.name < b.name ? -1 : 1; });
+    if (!mine.length) return;
+    aside.appendChild(el("h2", null, kind === "query" ? "queries" : kind === "command" ? "commands" : "streams"));
+    mine.forEach(function (op) {
+      var b = el("button", "op");
+      b.dataset.op = op.name;
+      b.appendChild(document.createTextNode(op.name));
+      b.appendChild(el("span", "kind", typeName(op.returns)));
+      b.onclick = function () { show(op); };
+      aside.appendChild(b);
+    });
+  });
+  if (ops.length) show(ops.filter(function (o) { return o.kind === "query"; })[0] || ops[0]);
+}
+$("#send").onclick = send;
+$("#req").addEventListener("keydown", function (e) { if (e.ctrlKey && e.key === "Enter") send(); });
+start();
+</script>
+</body>
+</html>`;
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,MAAM,QAAQ,GAAG,CAAC,IAAI,GAAoB,EAAE,EAA8D,EAAE;IAC1G,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC;IAC7C,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,GAAG,QAAQ,WAAW;QACzC,MAAM,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,EAAE;KACrD,CAAC;AACJ,CAAC,CAAC;AAEF,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAC,IAAI,GAAoB,EAAE;IACrD,OAAO,IAAI,CAAC,OAAO,CAAC,6BAA6B,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;AACrH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAI,GAAoB,EAAE;IAC9D,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAClB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG;YAAE,OAAO,KAAK,CAAC;QACrD,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAClD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC;QAChG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED,gHAAgH;AAChH,8GAA8G;AAC9G,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA2Of,CAAC","sourcesContent":["/**\n * The Rayfold explorer: the page a Rayfold server serves next to its endpoint, the counterpart of Swagger UI and\n * GraphiQL. It lists every operation the manifest declares with its arguments, result, cost and the policies that\n * guard it; helps write a shape; sends a batch and shows the frames as they arrive, with their cost; and dry-runs a\n * command that allows `@simulate`, so trying one changes nothing.\n *\n * It talks to the endpoint over HTTP like any other client, so it needs no access to the server object and adds no\n * dependency to it. Mount it where you like:\n *\n *   const explorer = createExplorerHandler({ endpoint: \"/rayfold\", title: \"Acme API\" });\n *   createServer((req, res) => { if (explorer(req, res)) return; ... });\n *\n * Nothing is served unless you mount it, so a production deployment exposes it only on purpose.\n */\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\n\nexport interface ExplorerOptions {\n  /** Where the Rayfold endpoint is mounted. Default `/rayfold`. */\n  endpoint?: string;\n  /** Where this page is served. Default `<endpoint>/explorer`. */\n  path?: string;\n  /** Shown in the header, to tell one service from another. */\n  title?: string;\n}\n\ninterface ExplorerConfig {\n  endpoint: string;\n  title: string;\n}\n\nconst settings = (opts: ExplorerOptions = {}): { endpoint: string; path: string; config: ExplorerConfig } => {\n  const endpoint = opts.endpoint ?? \"/rayfold\";\n  return {\n    endpoint,\n    path: opts.path ?? `${endpoint}/explorer`,\n    config: { endpoint, title: opts.title ?? \"Rayfold\" },\n  };\n};\n\n/** The page itself, for serving from a framework of your own. */\nexport function explorerHtml(opts: ExplorerOptions = {}): string {\n  return PAGE.replace(\"__RAYFOLD_EXPLORER_CONFIG__\", JSON.stringify(settings(opts).config).replace(/</g, \"\\\\u003c\"));\n}\n\n/**\n * A Node handler that serves the page. It answers only its own path and returns false for anything else, so it can\n * sit in front of the rest of an application.\n */\nexport function createExplorerHandler(opts: ExplorerOptions = {}): (req: IncomingMessage, res: ServerResponse) => boolean {\n  const { path } = settings(opts);\n  const html = explorerHtml(opts);\n  return (req, res) => {\n    const url = (req.url ?? \"/\").split(\"?\")[0];\n    if (url !== path && url !== `${path}/`) return false;\n    if (req.method !== \"GET\" && req.method !== \"HEAD\") {\n      res.writeHead(405, { allow: \"GET, HEAD\" }).end();\n      return true;\n    }\n    res.writeHead(200, { \"content-type\": \"text/html; charset=utf-8\", \"cache-control\": \"no-store\" });\n    res.end(req.method === \"HEAD\" ? undefined : html);\n    return true;\n  };\n}\n\n// The page is one self-contained document: no fonts, scripts or styles from anywhere else, so it works behind a\n// strict content-security-policy and offline. Client code avoids template literals, since this is one itself.\nconst PAGE = String.raw`<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n<title>Rayfold explorer</title>\n<style>\n:root { color-scheme: light dark; --ink: #16202b; --muted: #5b6875; --rule: #d6dde5; --surface: #fff; --ground: #f3f6f9; --accent: #2a78d6; --ok: #0a7d3f; --bad: #b3261e; }\n@media (prefers-color-scheme: dark) { :root { --ink: #e8eef5; --muted: #a2aebc; --rule: #2b333d; --surface: #171c22; --ground: #0f1318; --accent: #5aa2f0; --ok: #4cc073; --bad: #f2836f; } }\n* { box-sizing: border-box; }\nbody { margin: 0; background: var(--ground); color: var(--ink); font: 14px/1.55 ui-sans-serif, system-ui, \"Segoe UI\", sans-serif; }\nheader { display: flex; gap: 12px; align-items: baseline; padding: 12px 16px; border-bottom: 1px solid var(--rule); background: var(--surface); }\nheader h1 { font-size: 15px; margin: 0; font-weight: 600; }\nheader .meta { color: var(--muted); font: 12px/1.4 ui-monospace, monospace; }\nmain { display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 0; height: calc(100vh - 49px); }\n@media (max-width: 800px) { main { grid-template-columns: 1fr; height: auto; } }\naside { border-right: 1px solid var(--rule); overflow: auto; background: var(--surface); }\naside h2 { font: 600 11px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); margin: 14px 12px 6px; }\nbutton.op { display: block; width: 100%; text-align: left; border: 0; background: none; color: inherit; font: inherit; padding: 6px 12px; cursor: pointer; }\nbutton.op:hover, button.op.on { background: var(--ground); }\nbutton.op .kind { font: 11px ui-monospace, monospace; color: var(--muted); margin-left: 6px; }\nsection.work { display: grid; grid-template-rows: auto auto 1fr; min-width: 0; }\n.doc { padding: 12px 16px; border-bottom: 1px solid var(--rule); background: var(--surface); }\n.doc h3 { margin: 0 0 4px; font-size: 15px; }\n.doc dl { display: grid; grid-template-columns: 92px minmax(0, 1fr); gap: 2px 10px; margin: 6px 0 0; font-size: 13px; }\n.doc dt { color: var(--muted); font: 12px ui-monospace, monospace; }\n.doc dd { margin: 0; font-family: ui-monospace, monospace; overflow-wrap: anywhere; }\n.editor { display: grid; gap: 8px; padding: 12px 16px; border-bottom: 1px solid var(--rule); }\ntextarea, input[type=text] { width: 100%; font: 12.5px/1.5 ui-monospace, monospace; color: inherit; background: var(--surface); border: 1px solid var(--rule); border-radius: 6px; padding: 8px; }\ntextarea { min-height: 120px; resize: vertical; }\n.row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }\n.row label { font-size: 12.5px; color: var(--muted); display: flex; gap: 5px; align-items: center; }\nbutton.go { background: var(--accent); color: #fff; border: 0; border-radius: 6px; padding: 7px 14px; font: 600 13px/1 inherit; cursor: pointer; }\nbutton.go:disabled { opacity: .55; cursor: default; }\n.out { overflow: auto; padding: 12px 16px; display: grid; gap: 8px; align-content: start; }\n.frame { border: 1px solid var(--rule); border-left-width: 3px; border-radius: 6px; background: var(--surface); padding: 8px 10px; }\n.frame pre { margin: 4px 0 0; font: 12px/1.5 ui-monospace, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }\n.frame .tag { font: 600 11px ui-monospace, monospace; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); }\n.frame.ok, .frame.data { border-left-color: var(--ok); }\n.frame.error { border-left-color: var(--bad); }\n.frame.patch, .frame.item, .frame.at { border-left-color: var(--accent); }\n.hint { color: var(--muted); font-size: 12.5px; }\ncode { font-family: ui-monospace, monospace; }\n</style>\n</head>\n<body>\n<script type=\"application/json\" id=\"config\">__RAYFOLD_EXPLORER_CONFIG__</script>\n<header>\n  <h1 id=\"title\">Rayfold</h1>\n  <span class=\"meta\" id=\"about\">reading the manifest...</span>\n</header>\n<main>\n  <aside id=\"ops\"></aside>\n  <section class=\"work\">\n    <div class=\"doc\" id=\"doc\"><p class=\"hint\">Pick an operation on the left. The explorer reads everything it shows from the server's manifest.</p></div>\n    <div class=\"editor\">\n      <textarea id=\"req\" spellcheck=\"false\"></textarea>\n      <div class=\"row\">\n        <button class=\"go\" id=\"send\">Send</button>\n        <label><input type=\"checkbox\" id=\"simulate\"> dry run</label>\n        <label><input type=\"checkbox\" id=\"live\"> live</label>\n        <label>auth <input type=\"text\" id=\"token\" placeholder=\"bearer token\" style=\"width:170px\"></label>\n        <span class=\"hint\" id=\"status\"></span>\n      </div>\n      <p class=\"hint\">A batch can hold several ops, and a later one can use an earlier result: <code>{\"$ref\": \"1.id\"}</code> in its args. Ctrl+Enter sends.</p>\n    </div>\n    <div class=\"out\" id=\"out\"></div>\n  </section>\n</main>\n<script>\nvar CONFIG = JSON.parse(document.getElementById(\"config\").textContent);\nvar $ = function (sel) { return document.querySelector(sel); };\nvar manifest = null;\nvar current = null;\n\ndocument.getElementById(\"title\").textContent = CONFIG.title;\n\nfunction text(node, s) { node.textContent = s; return node; }\nfunction el(tag, cls, s) { var n = document.createElement(tag); if (cls) n.className = cls; if (s !== undefined) n.textContent = s; return n; }\nfunction typeName(t) {\n  if (!t) return \"?\";\n  if (t.kind === \"list\") return \"[\" + typeName(t.of) + \"]\" + (t.nullable ? \"?\" : \"\");\n  var args = t.args && t.args.length ? \"<\" + t.args.map(typeName).join(\", \") + \">\" : \"\";\n  return t.name + args + (t.nullable ? \"?\" : \"\");\n}\nfunction annotationsOf(def, name) { return (def.annotations || []).filter(function (a) { return a.name === name; }); }\nfunction costOf(def) {\n  var c = annotationsOf(def, \"cost\")[0];\n  if (!c) return \"default\";\n  return Object.keys(c.args).map(function (k) { return k + \" \" + JSON.stringify(c.args[k]); }).join(\", \");\n}\nfunction policiesOf(def) {\n  var names = [];\n  annotationsOf(def, \"allow\").forEach(function () { names.push(\"allow\"); });\n  annotationsOf(def, \"deny\").forEach(function () { names.push(\"deny\"); });\n  return names.length ? names.join(\", \") : \"none on the operation\";\n}\n/** A shape that selects the scalar fields of what an op returns: a starting point, not a rule. */\nfunction defaultShape(typeRef) {\n  var base = typeRef;\n  while (base && base.kind === \"list\") base = base.of;\n  if (!base) return \"\";\n  var def = manifest.schema.types[base.name];\n  if (!def || !def.fields) return \"\";\n  if (base.name === \"Page\" && base.args && base.args.length) {\n    return \"{ total hasMore cursor items \" + (defaultShape(base.args[0]) || \"{ id }\") + \" }\";\n  }\n  var scalars = def.fields.filter(function (f) {\n    var t = f.type.kind === \"list\" ? f.type.of : f.type;\n    var sub = manifest.schema.types[t.name];\n    return !f.args.length && sub && (sub.kind === \"scalar\" || sub.kind === \"enum\");\n  });\n  if (!scalars.length) return \"\";\n  return \"{ \" + scalars.map(function (f) { return f.name; }).join(\" \") + \" }\";\n}\nfunction argSkeleton(def) {\n  var args = {};\n  def.args.forEach(function (a) {\n    if (a.default !== undefined) { args[a.name] = a.default; return; }\n    var t = a.type.kind === \"list\" ? a.type.of : a.type;\n    var sub = manifest.schema.types[t.name];\n    args[a.name] = a.type.kind === \"list\" ? [] : sub && sub.kind === \"enum\" ? sub.values[0].name : t.name === \"Int\" || t.name === \"Float\" || t.name === \"Long\" ? 0 : t.name === \"Boolean\" ? false : \"\";\n  });\n  return args;\n}\nfunction show(op) {\n  current = op;\n  Array.prototype.forEach.call(document.querySelectorAll(\"button.op\"), function (b) { b.classList.toggle(\"on\", b.dataset.op === op.name); });\n  var doc = document.getElementById(\"doc\");\n  doc.innerHTML = \"\";\n  doc.appendChild(el(\"h3\", null, op.name + \"(\" + op.args.map(function (a) { return a.name + \": \" + typeName(a.type); }).join(\", \") + \")\"));\n  if (op.description) doc.appendChild(el(\"p\", \"hint\", op.description));\n  var dl = el(\"dl\");\n  function add(k, v) { dl.appendChild(el(\"dt\", null, k)); dl.appendChild(el(\"dd\", null, v)); }\n  add(\"kind\", op.kind);\n  add(\"returns\", typeName(op.returns));\n  add(\"cost\", costOf(op));\n  add(\"policies\", policiesOf(op));\n  if (op.throws && op.throws.length) add(\"throws\", op.throws.join(\" | \"));\n  if (op.emits && op.emits.length) add(\"emits\", op.emits.join(\" \"));\n  if (annotationsOf(op, \"simulate\").length) add(\"dry run\", \"allowed: tick it and nothing is written\");\n  doc.appendChild(dl);\n\n  var request = { ops: [{ id: 1, op: op.name, args: argSkeleton(op) }] };\n  var shape = defaultShape(op.returns);\n  if (shape) request.ops[0].shape = shape;\n  if (op.kind === \"command\") request.ops[0].key = \"explorer-\" + Math.random().toString(36).slice(2).padEnd(16, \"0\").slice(0, 16);\n  $(\"#req\").value = JSON.stringify(request, null, 2);\n  $(\"#simulate\").disabled = op.kind !== \"command\";\n  $(\"#live\").disabled = op.kind !== \"query\";\n}\nfunction render(frames, ms) {\n  var out = document.getElementById(\"out\");\n  out.innerHTML = \"\";\n  frames.forEach(function (f) {\n    var kind = \"error\" in f ? \"error\" : \"ok\" in f ? \"ok\" : \"at\" in f ? \"at\" : \"patch\" in f ? \"patch\" : \"item\" in f ? \"item\" : \"data\" in f ? \"data\" : \"fin\";\n    var box = el(\"div\", \"frame \" + kind);\n    var cost = f.meta && f.meta.cost !== undefined ? \"  cost \" + f.meta.cost : \"\";\n    box.appendChild(el(\"span\", \"tag\", kind + (f.id !== undefined ? \" · op \" + f.id : \"\") + cost));\n    box.appendChild(el(\"pre\", null, JSON.stringify(f, null, 2)));\n    out.appendChild(box);\n  });\n  $(\"#status\").textContent = frames.length + (frames.length === 1 ? \" frame\" : \" frames\") + \" in \" + ms + \" ms\";\n}\nasync function send() {\n  var button = $(\"#send\");\n  button.disabled = true;\n  $(\"#status\").textContent = \"sending...\";\n  var started = Date.now();\n  try {\n    var body = JSON.parse($(\"#req\").value);\n    if (current && current.kind === \"command\" && $(\"#simulate\").checked) body.ops.forEach(function (o) { o.simulate = true; });\n    if (current && current.kind === \"query\" && $(\"#live\").checked) body.ops.forEach(function (o) { o.live = true; });\n    var headers = { \"content-type\": \"application/rayfold+json\" };\n    if ($(\"#token\").value) headers.authorization = \"Bearer \" + $(\"#token\").value;\n    var res = await fetch(CONFIG.endpoint, { method: \"POST\", headers: headers, body: JSON.stringify(body) });\n    var frames = [];\n    var reader = res.body.getReader();\n    var decoder = new TextDecoder();\n    var buffered = \"\";\n    for (;;) {\n      var chunk = await reader.read();\n      if (chunk.done) break;\n      buffered += decoder.decode(chunk.value, { stream: true });\n      var cut;\n      while ((cut = buffered.indexOf(String.fromCharCode(10))) >= 0) {\n        var line = buffered.slice(0, cut);\n        buffered = buffered.slice(cut + 1);\n        if (line.trim()) frames.push(JSON.parse(line));\n        render(frames, Date.now() - started);\n      }\n    }\n    if (buffered.trim()) frames.push(JSON.parse(buffered));\n    render(frames, Date.now() - started);\n  } catch (e) {\n    $(\"#out\").innerHTML = \"\";\n    var box = el(\"div\", \"frame error\");\n    box.appendChild(el(\"span\", \"tag\", \"explorer\"));\n    box.appendChild(el(\"pre\", null, String(e && e.message ? e.message : e)));\n    $(\"#out\").appendChild(box);\n    $(\"#status\").textContent = \"\";\n  } finally {\n    button.disabled = false;\n  }\n}\nasync function start() {\n  try {\n    manifest = await (await fetch(CONFIG.endpoint + \"/manifest\")).json();\n  } catch (e) {\n    text(document.getElementById(\"about\"), \"no manifest at \" + CONFIG.endpoint + \"/manifest\");\n    return;\n  }\n  text(document.getElementById(\"about\"), \"rayfold \" + manifest.rayfold + \" · schema \" + String(manifest.schemaHash).slice(0, 12) + \" · extensions \" + (manifest.extensions || []).join(\", \"));\n  var ops = Object.keys(manifest.schema.ops).map(function (n) { return manifest.schema.ops[n]; });\n  var aside = document.getElementById(\"ops\");\n  [\"query\", \"command\", \"stream\"].forEach(function (kind) {\n    var mine = ops.filter(function (o) { return o.kind === kind; }).sort(function (a, b) { return a.name < b.name ? -1 : 1; });\n    if (!mine.length) return;\n    aside.appendChild(el(\"h2\", null, kind === \"query\" ? \"queries\" : kind === \"command\" ? \"commands\" : \"streams\"));\n    mine.forEach(function (op) {\n      var b = el(\"button\", \"op\");\n      b.dataset.op = op.name;\n      b.appendChild(document.createTextNode(op.name));\n      b.appendChild(el(\"span\", \"kind\", typeName(op.returns)));\n      b.onclick = function () { show(op); };\n      aside.appendChild(b);\n    });\n  });\n  if (ops.length) show(ops.filter(function (o) { return o.kind === \"query\"; })[0] || ops[0]);\n}\n$(\"#send\").onclick = send;\n$(\"#req\").addEventListener(\"keydown\", function (e) { if (e.ctrlKey && e.key === \"Enter\") send(); });\nstart();\n</script>\n</body>\n</html>`;\n"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rayfold/explorer",
+  "version": "0.1.0",
+  "description": "The Rayfold explorer: a page served next to the endpoint that lists every operation from the manifest, writes shapes, sends batches and dry-runs commands.",
+  "keywords": [
+    "rayfold",
+    "api",
+    "protocol",
+    "explorer",
+    "playground",
+    "documentation"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://eddyboutros.github.io/rayfold/",
+  "bugs": {
+    "url": "https://github.com/eddyboutros/rayfold/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eddyboutros/rayfold.git",
+    "directory": "packages/explorer"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}