The Explorer
The Hypermedia Explorer is a web page at explore.hyper.media that shows the raw data behind any hm:// or ipfs:// URL, follows the activity feed, and lets you try Seed API requests against a site.

The Hypermedia Explorer is a web page that shows the raw data on the network. Developers and operators use it to see what a daemon really holds. The public copy is at https://explore.hyper.media.

Paste an hm:// URL, an ipfs:// CID or the web address of a Seed page. The Explorer shows the resource as data: the document's metadata and blocks, its change history, its comments, citations and capabilities, and its child documents.

It also does four other things:

    It lists the root documents the network knows.

    It follows the activity feed.

    It decodes any blob.

    It has an API lab, where you try Seed API requests by hand.

Where the code is

The code is in frontend/apps/explore, package @shm/explore. It is a static single-page app built with Vite, React, react-router and Tailwind. It has no server of its own. It uses @seed-hypermedia/client (the SDK), @shm/shared and @shm/ui straight from source through Vite aliases. The shared packages describes them.

Path

What it holds

src/main.tsx, src/App.tsx

Entry point and routes.

src/universal-client.ts

The data layer: a web universal client whose requests go to the configured API host.

src/queryClient.ts, src/apiHostStore.ts

The API host setting.

src/components/HM.tsx, src/components/tabs/

The resource view and its tabs.

src/components/IPFS.tsx

The blob view.

src/components/ApiLab.tsx, src/api-lab.ts

The API lab; the logic lives in @shm/shared/api-lab.

src/components/Feed.tsx, src/components/List.tsx

The activity feed and the list of root documents.

The app is part of the pnpm workspace.

How it talks to the daemon

The Explorer never talks to a daemon directly. It talks to the Seed API of a Seed web app. Every request is createSeedClient(apiHost).request(key, input). So the Explorer shows exactly what the daemon of that site can see. The API host setting chooses the site. Configuration describes it.

You can point the Explorer at three kinds of host:

    A local web app, to inspect your development node.

    https://hyper.media, to see what the gateway sees.

    Any site, to see what that site's daemon has synced.

The same resource can look different on two hosts. That difference often answers a sync question.

Configuration

    API host. It defaults to VITE_PUBLIC_EXPLORE_API_HOST, or http://localhost:3000 when that is not set at build time. You can change it in the settings panel behind the gear icon. The choice is saved in the browser's localStorage.

    VITE_SEED_WEB_ORIGIN. When set at build time, the blob view links to that web app's inspector for editing.

What it shows

Route

View

/

A search box for hm://, ipfs:// and https:// URLs of Hypermedia documents.

/hm/<account>/<path>

A resource. Tabs, each with a count, cover the document, changes, comments, citations, capabilities, child documents, comments the account wrote, the profile, and a comment's versions. View terms such as /:comments select a tab, the same way they do in the web app.

/ipfs/<cid>

A decoded blob. The signer principals are shown as hm:// links, and there are copy and download buttons. The view knows schemas: it recognises a schema blob, and it checks a blob that names a schema against that schema.

/list

The root documents the host knows.

/feed

The activity feed, paged, with the latest event.

/api-lab

The API lab.

When a resource is not found, deleted or redirected, the Explorer shows a status panel that names the state. This makes tombstones and redirects easy to see.

The API lab

The API lab is a place to try the Seed API by hand. It works in four steps:

    It loads GET /api/schema from the API host. The answer lists every request key with its kind (query or action), method and path.

    You pick a key. The lab loads GET /api/schema?key=<Key>, the JSON Schema of that key's input and output.

    The lab writes a first payload for you and shows the exact HTTP request it will send, with the query string or the CBOR body.

    It sends the request and shows the result.

The desktop app's API bridge and every web app serve the same schema route, so the lab works against both. Seed API documents the same keys.

Running it

pnpm explore # Vite dev server on :5173, reading from the web app on :3000 pnpm explore:build # static build in frontend/apps/explore/dist pnpm --filter @shm/explore test

./dev up starts it as the explore pane beside the web app it reads from. The build is a folder of static files that any web host can serve. The hosted copy at explore.hyper.media reads from hyper.media. This repository does not define how that copy is deployed.

Working with it

In the Seed app

The desktop app has its own tools for the same purpose: the blob editor and the metadata editor. The Explorer covers the reading part in any browser, against any site.

CLI

seed-cli document get, seed-cli blob and seed-cli activity read the same data from a terminal. Use --json to get what the Explorer shows. See the CLI reference.

SDK

The Explorer is a small example of an app built on the SDK's createSeedClient, with the React Query models of @shm/shared on top.

Seed API

Everything the Explorer shows comes from /api/<Key> on the API host. The API lab is the way to learn those keys by trying them. Seed API documents them.

Agents

Seed Agents do not use the Explorer. A Seed Agent reads the same data with its read verb, and a coding agent reads it through the CLI. An Explorer URL is still a useful thing to give a person when an agent reports what it found.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

People