Skip to content

Add agent visibility: llms.txt + HTML fallback + JSON-LD #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hrhrng merged 1 commit into from
Mar 14, 2026
Merged

Add agent visibility: llms.txt + HTML fallback + JSON-LD #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 94 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
<!DOCTYPE html>
<html lang="zh-CN">
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/png" href="/icon.png" />
<link rel="apple-touch-icon" href="/icon.png" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Super JSON - Your Final ONLINE JSON Editor</title>
<meta name="description" content="Super JSON Editor: parse, edit, and reconstruct deeply nested/escaped JSON structures. Agent-friendly URL API for presenting JSON to humans." />
<link rel="help" type="text/plain" href="/llms.txt" title="LLM-readable site documentation" />
<script>
(function() {
var m = window.location.pathname.match(/\/preview\/(.+?)\/(?:index\.html)?$/);
Expand All @@ -18,9 +20,100 @@
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebApplication",
"name": "Super JSON Editor",
"url": "https://hrhrng.github.io/super-json",
"description": "Parse, edit, and reconstruct deeply nested/escaped JSON structures. Supports multi-layer JSON parsing, bidirectional sync, and an agent-friendly URL API.",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Any (Web Browser)",
"offers": { "@type": "Offer", "price": "0" }
}
</script>
<style>
/* Agent-readable content: visible before JS loads, hidden after React mounts */
#agent-info { font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; padding: 1rem; color: #e0e0e0; background: #1a1a2e; }
#agent-info h1 { font-size: 1.5rem; }
#agent-info h2 { font-size: 1.2rem; margin-top: 1.5rem; }
#agent-info code { background: #2a2a4a; padding: 2px 6px; border-radius: 3px; }
#agent-info pre { background: #2a2a4a; padding: 1rem; border-radius: 6px; overflow-x: auto; }
#agent-info table { border-collapse: collapse; width: 100%; }
#agent-info th, #agent-info td { border: 1px solid #333; padding: 6px 10px; text-align: left; }
#root:not(:empty) ~ #agent-info { display: none; }
</style>
</head>
<body>
<div id="root"></div>

<!--
AGENT-READABLE CONTENT
This section is visible to AI agents, web crawlers, and non-JS clients.
It is automatically hidden when the React application mounts into #root.
-->
<div id="agent-info">
<h1>Super JSON Editor</h1>
<p><strong>Built for agents, designed for humans.</strong> Present JSON results to humans via an interactive browser viewer instead of dumping raw JSON in a terminal.</p>

<h2>Agent URL API</h2>
<p>Construct a URL to open JSON directly in the editor. No server upload — all data is encoded in the URL (client-side only).</p>

<h3>URL Parameters</h3>
<table>
<thead><tr><th>Parameter</th><th>Encoding</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>r</code></td><td>Base64url</td><td>JSON content, base64url-encoded. Shell-friendly, no dependencies needed.</td></tr>
<tr><td><code>s</code></td><td>LZ-String</td><td>JSON content, LZ-String compressed (used by the app's built-in Share button, smaller URLs).</td></tr>
<tr><td><code>t</code></td><td>URL-encoded string</td><td>Custom tab name displayed in the editor.</td></tr>
<tr><td><code>h</code></td><td><code>1</code> to enable</td><td>Auto-switch to Hero mode (JSON Hero interactive viewer with tree navigation, type info, search).</td></tr>
</tbody>
</table>

<h3>Quick Start (Shell)</h3>
<pre><code># Inline JSON
encoded=$(echo -n '{"hello":"world"}' | base64 | tr '+/' '-_' | tr -d '=\n')
echo "https://hrhrng.github.io/super-json?r=${encoded}&amp;t=My%20Data"

# From a file
encoded=$(base64 &lt; data.json | tr '+/' '-_' | tr -d '=\n')
echo "https://hrhrng.github.io/super-json?r=${encoded}&amp;t=File%20Data"

# With Hero mode (interactive tree viewer)
echo "https://hrhrng.github.io/super-json?r=${encoded}&amp;t=My%20Data&amp;h=1"</code></pre>

<h2>Features</h2>
<ul>
<li><strong>Multi-layer JSON parsing</strong> — handles deeply nested escaped JSON strings</li>
<li><strong>Multi-document tabs</strong> — work with multiple JSON documents simultaneously</li>
<li><strong>Bidirectional sync</strong> — real-time synchronization between parent and child layers</li>
<li><strong>Hero mode</strong> — JSON Hero interactive viewer with tree navigation, type info, and search</li>
<li><strong>Diff mode</strong> — side-by-side JSON comparison</li>
<li><strong>Auto-save</strong> — automatic persistence to localStorage</li>
<li><strong>Monaco Editor</strong> — VS Code's editor with syntax highlighting and validation</li>
</ul>

<h2>For AI Agents</h2>
<p>If you are an AI agent and want to present JSON to a human user:</p>
<ol>
<li>Take the JSON content you want to display</li>
<li>Base64url-encode it: <code>base64 | tr '+/' '-_' | tr -d '='</code></li>
<li>Construct the URL: <code>https://hrhrng.github.io/super-json?r={encoded}&amp;t={tab_name}</code></li>
<li>Present the link to the user — they will see the JSON in a full interactive editor</li>
</ol>
<p>The URL is entirely client-side. No data is sent to any server (unless Hero mode <code>h=1</code> is used, which sends to jsonhero.io).</p>
<p>For very large JSON (&gt;6KB encoded), the URL may exceed browser limits. Consider splitting the data or using the app directly.</p>

<h2>Claude Code Skill</h2>
<p>Install the <code>present-json</code> skill to use Super JSON directly from Claude Code:</p>
<pre><code>claude install-skill https://github.com/hrhrng/super-json/tree/main/skills/present-json</code></pre>
<p>Then use <code>/present-json [json-or-file] [tab-name]</code> to present JSON to users interactively.</p>

<noscript>
<p><em>This application requires JavaScript to run. The information above describes the URL API that can be used programmatically.</em></p>
</noscript>
</div>

<script type="module" src="/src/main.tsx"></script>
</body>
</html>
194 changes: 194 additions & 0 deletions public/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
# Super JSON Editor — Full Documentation

> Parse, edit, and reconstruct deeply nested/escaped JSON structures. Built for agents, designed for humans.

## Overview

Super JSON Editor is a standalone web application at `https://hrhrng.github.io/super-json`. It provides a professional IDE-like experience for working with JSON, with special strength in handling multi-layer escaped JSON (JSON strings containing stringified JSON, which in turn contain more stringified JSON, etc.).

The app is entirely client-side. No data leaves the browser unless Hero mode is explicitly used.

## URL API Reference

### Base URL

```
https://hrhrng.github.io/super-json
```

### Query Parameters

| Parameter | Required | Encoding | Description |
|-----------|----------|----------|-------------|
| `r` | One of `r` or `s` | Base64url | JSON content encoded with base64url (standard base64 with `+/` replaced by `-_`, padding `=` stripped). Recommended for shell/agent use. |
| `s` | One of `r` or `s` | LZ-String | JSON content compressed with `LZString.compressToEncodedURIComponent()`. Produces shorter URLs. Used by the app's built-in Share button. |
| `t` | No | URL-encoded string | Custom tab name. Defaults to "Shared Document" or a name derived from the JSON content (`title` or `name` field). |
| `h` | No | `1` to enable | Auto-switch to Hero mode. Sends the JSON to `jsonhero.io/api/create.json` to create a temporary interactive viewer (24h TTL). |

### Base64url Encoding (parameter `r`)

Standard across all POSIX shells:

```bash
# Encode
encoded=$(echo -n "$JSON_CONTENT" | base64 | tr '+/' '-_' | tr -d '=\n')

# Encode from file
encoded=$(base64 < file.json | tr '+/' '-_' | tr -d '=\n')
```

Decoding (for reference):
1. Replace `-` with `+`, `_` with `/`
2. Add `=` padding to make length a multiple of 4
3. Standard base64 decode

### LZ-String Encoding (parameter `s`)

Requires the `lz-string` library (npm/browser):

```javascript
import LZString from 'lz-string'
const compressed = LZString.compressToEncodedURIComponent(jsonString)
const url = `https://hrhrng.github.io/super-json?s=${compressed}`
```

### URL Size Limits

- Most browsers support URLs up to ~8,000 characters
- Base64 encoding expands data by ~33%
- For JSON larger than ~6KB, consider:
- Using LZ-String compression (`s` parameter) for better compression
- Splitting the data into smaller pieces
- Having the user paste directly into the editor

## Complete Examples

### Agent Workflow: Present API Response

```bash
# 1. You have JSON from an API call
json='{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]}'

# 2. Encode it
encoded=$(echo -n "$json" | base64 | tr '+/' '-_' | tr -d '=\n')

# 3. Construct URL
url="https://hrhrng.github.io/super-json?r=${encoded}&t=API%20Response"

# 4. Present to user
echo "View the API response interactively: $url"
```

### Agent Workflow: Present with Hero Mode

```bash
# Same as above, but add &h=1 for the interactive tree viewer
url="https://hrhrng.github.io/super-json?r=${encoded}&t=API%20Response&h=1"
```

### Agent Workflow: Present File Contents

```bash
encoded=$(base64 < config.json | tr '+/' '-_' | tr -d '=\n')
echo "https://hrhrng.github.io/super-json?r=${encoded}&t=Config"
```

## View Modes

The editor has four view modes:

### Layer Mode (default)
Three-panel layout:
1. **Input Panel** (left) — paste or edit raw JSON
2. **Layer Editor** (middle) — tabbed interface showing each detected JSON layer with bidirectional sync
3. **Output Panel** (right) — reconstructed JSON after edits

User clicks **Parse** to analyze layers, edits in the layer tabs, then clicks **Apply** to generate output.

### Hero Mode
Two-panel layout:
1. **JSON Input** (left) — paste JSON
2. **JSON Hero Viewer** (right) — embedded iframe from jsonhero.io with interactive tree navigation, type info, and search

### Diff Mode
Side-by-side JSON comparison with highlighted differences.

### Processor Mode
JSON transformation tools.

## Multi-Layer JSON Parsing

The core feature. Given input like:

```json
{
"config": "{\"database\":\"{\\\"host\\\":\\\"localhost\\\",\\\"port\\\":5432}\"}"
}
```

The analyzer detects three layers:
- **Layer 0**: The outer object
- **Layer 1**: The `config` field (was an escaped JSON string)
- **Layer 2**: The `database` field (was a doubly-escaped JSON string)

Each layer gets its own editor tab. Edits in any layer automatically sync to parent and child layers.

## Multi-Document Support

- Multiple JSON documents open simultaneously as tabs
- Each document has independent state (input, layers, output)
- Double-click tab to rename
- Auto-save to localStorage

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Enter` | Analyze/Parse JSON |
| `Ctrl+S` | Generate Output |
| `Ctrl+T` | New Document |
| `Ctrl+W` | Close Current Document |
| `Ctrl+Tab` | Switch to Next Document |

## Claude Code Skill: present-json

### Installation

```
claude install-skill https://github.com/hrhrng/super-json/tree/main/skills/present-json
```

### Usage

```
/present-json [json-content-or-file-path] [tab-name]
```

### When to Use

- You produced JSON output the user needs to review (API responses, query results, configs)
- The JSON is complex/nested and hard to read as plain text
- You want the user to explore, edit, search, or navigate the JSON interactively

### What It Does

1. Takes JSON content (inline or from a file)
2. Base64url-encodes it using shell commands (`base64`, `tr`)
3. Generates a clickable URL to `https://hrhrng.github.io/super-json?r=...&t=...`
4. Presents the link to the user

No dependencies required — uses only POSIX shell builtins.

## Technical Details

- **Stack**: React + TypeScript + Vite + Monaco Editor + Zustand
- **Hosting**: GitHub Pages at `https://hrhrng.github.io/super-json`
- **Source**: `https://github.com/hrhrng/super-json`
- **Privacy**: All processing is client-side. No data sent to any server except when Hero mode (`h=1`) creates a temporary jsonhero.io session (24h TTL).
- **Browser Support**: Chrome, Firefox, Safari, Edge (requires ES6+)

## Links

- [Live App](https://hrhrng.github.io/super-json)
- [GitHub Repository](https://github.com/hrhrng/super-json)
- [Skill: present-json](https://github.com/hrhrng/super-json/tree/main/skills/present-json)
69 changes: 69 additions & 0 deletions public/llms.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Super JSON Editor

> Parse, edit, and reconstruct deeply nested/escaped JSON structures. Built for agents, designed for humans.

## URL API

Construct a URL to open JSON directly in the interactive editor. All data is encoded in the URL — no server upload, fully client-side.

Base URL: `https://hrhrng.github.io/super-json`

### Parameters

- `r`: JSON content, base64url-encoded (shell-friendly, no dependencies)
- `s`: JSON content, LZ-String compressed (smaller URLs, used by built-in Share button)
- `t`: Custom tab name, URL-encoded
- `h`: Set to `1` to auto-switch to Hero mode (JSON Hero interactive viewer with tree navigation, type info, search)

### Usage (Shell)

```bash
# Inline JSON → shareable link
encoded=$(echo -n '{"hello":"world"}' | base64 | tr '+/' '-_' | tr -d '=\n')
echo "https://hrhrng.github.io/super-json?r=${encoded}&t=My%20Data"

# From a file
encoded=$(base64 < data.json | tr '+/' '-_' | tr -d '=\n')
echo "https://hrhrng.github.io/super-json?r=${encoded}&t=File%20Data"

# With Hero mode (interactive tree viewer)
echo "https://hrhrng.github.io/super-json?r=${encoded}&t=My%20Data&h=1"
```

## For AI Agents

If you are an AI agent and want to present JSON to a human user:

1. Take the JSON content you want to display
2. Base64url-encode it: `base64 | tr '+/' '-_' | tr -d '='`
3. Construct the URL: `https://hrhrng.github.io/super-json?r={encoded}&t={tab_name}`
4. Present the link to the user — they will see the JSON in a full interactive editor

Privacy: the URL is entirely client-side. No data is sent to any server (unless Hero mode `h=1` is used, which sends to jsonhero.io with 24h TTL).

For large JSON (>6KB encoded), the URL may exceed browser limits.

## Claude Code Skill

Install the `present-json` skill to use Super JSON directly from Claude Code:

```
claude install-skill https://github.com/hrhrng/super-json/tree/main/skills/present-json
```

Then use `/present-json [json-or-file] [tab-name]` to present JSON interactively.

## Features

- Multi-layer JSON parsing — handles deeply nested escaped JSON strings
- Multi-document tabs — work with multiple JSON documents simultaneously
- Bidirectional sync — real-time synchronization between parent and child layers
- Hero mode — JSON Hero interactive viewer with tree navigation and search
- Diff mode — side-by-side JSON comparison
- Monaco Editor — VS Code's editor with syntax highlighting and validation
- Auto-save — automatic persistence to localStorage

## Links

- [Source Code](https://github.com/hrhrng/super-json)
- [Skill: present-json](https://github.com/hrhrng/super-json/tree/main/skills/present-json)
Loading