TREF

Traceable Reference Format

A JSON-based format for knowledge exchange where references are structural, not optional.

What is TREF?

TREF is a knowledge exchange format – not a CMS, not an AI model, not a platform. It's a JSON format for creating self-contained units of knowledge that preserve:

• Content – the actual information
• Metadata – author, timestamps, source
• License – attribution requirements
• References – URLs, archived snippets, search prompts, hashes
• Lineage – parent/child relationships, version history

Install

npm install tref-block

Or use CDN:

<script type="module">
  import { TrefWrapper } from 'https://cdn.jsdelivr.net/npm/tref-block';
</script>

Core Principles

1. The Block is the Atom of Truth – smallest meaningful unit of knowledge
2. Reference Lineage – modifications create new blocks, preserving history
3. References Survive – not just URLs, but archived snippets and search prompts
4. AI-First, Human-Readable – JSON format readable by both machines and humans
5. Verifiability Over Authority – trust through transparency, not central control
6. Copy = Citation – copying preserves origin, references, and license
7. The Icon IS the Block – no extra containers, just the draggable icon

Browser Components

Two components enable TREF exchange between websites and AI chats. See src/wrapper/README.md for full design guide.

TrefWrapper – Display and Share

const wrapper = new TrefWrapper(block);
container.innerHTML = wrapper.toHTML();
wrapper.attachEvents(container.querySelector('.tref-wrapper'));

• ICON is the drag handle (only the icon, not the entire block)
• Actions appear on hover: copy content, copy JSON, download, history
• Auto-validates SHA-256 on display – tampered blocks show red X icon
• Status feedback in the shortId badge

SHA-256 Validation

Every block's ID is a SHA-256 hash of its content. If content is modified, the hash won't match:

// Automatic (runs on attachEvents)
wrapper.attachEvents(element);  // Shows red X if invalid

// Manual validation
const result = await wrapper.validate();
if (!result.valid) {
  console.log('Tampered!', result.expected, result.actual);
}

// Standalone function
import { validateBlock } from 'tref-block';
const result = await validateBlock(block);

Version History

Track article versions with a simple JSON file:

// Add history URL to wrapper element
wrapperEl.dataset.history = 'history.json';

// history.json format
{
  "current": "sha256:abc123...",
  "versions": [
    { "v": 2, "id": "sha256:abc...", "date": "2026-01-08" },
    { "v": 1, "id": "sha256:def...", "date": "2026-01-01" }
  ]
}

Click the history icon in hover menu to see all versions.

TrefReceiver – Accept TREF Blocks

const receiver = new TrefReceiver(element, {
  onReceive: wrapper => console.log('Got block:', wrapper.block),
  onError: err => console.error(err),
});

Drag-and-Drop Flow

┌─────────────────┐                    ┌─────────────────┐
│   Site A        │                    │   Site B / Chat │
│                 │     drag TREF      │                 │
│  [TREF icon] ──────────────────────► │  [Drop Zone]    │
│   TrefWrapper   │                    │   TrefReceiver  │
└─────────────────┘                    └─────────────────┘

The entire block (content, refs, license, lineage) transfers with the drag.

Quick Start

npm install
npm run build         # build browser bundle
npm run dev           # start dev server (http://localhost:8080)
npm run check         # typecheck + lint + format
npm test              # run tests

Architecture

Single source, many outputs:

src/wrapper/wrapper.js    ← Write code here
        │
    npm run build
        ▼
dist/tref-block.js        ← Built output (10kb)
        │
        ├──> CDN (jsdelivr/unpkg)
        ├──> npm install
        └──> demo/

Development

This project uses TypeScript-level safety in pure JavaScript:

• JSDoc type annotations
• TypeScript CLI for type checking (no transpilation)
• ESLint with type-aware rules
• Zod for runtime validation
• Prettier for formatting

npm run build:browser # build browser bundle
npm run typecheck     # type check
npm run lint          # lint
npm run format        # format code
npm run check         # all checks
npm test              # run tests

Project Structure

src/
  wrapper/
    wrapper.js        # TrefWrapper + TrefReceiver (single source)
  cli/
    index.js          # CLI tool
  mcp/
    server.js         # MCP server for Claude Code
dist/
  tref-block.js       # Built browser bundle
demo/
  index.html          # Visual testing
doc/
  project.md          # Vision & architecture
  TrefBlockUIUX.md    # UI/UX specification

Documentation

• Project & Architecture – vision, principles, single-source architecture
• UI/UX Specification – complete UI/UX design guide
• Auto TREF Block Generation – build TREF blocks from markdown at commit time

Status

v0.3.0 – SHA-256 validation and version history.

• TrefWrapper + TrefReceiver (drag-and-drop)
• SHA-256 validation – auto-detects tampered content with red X icon
• Version history – popup showing all versions with dates
• Accessibility: ARIA, keyboard, focus-visible
• Mobile/touch support: tap-to-toggle, long-press
• Dropdown action menu with SVG icons (Feather style)
• CLI tool (tref publish, tref validate, tref derive)
• MCP server for Claude Code integration
• Live demo at tref.lpmwfx.com

License

AGPL-3.0-or-later