HyperContext Standard v1.3.3

§0 Build HC Pages with AI

This specification page is itself HC v1.3.3 compliant. Share its URL with any LLM, and the LLM will have everything it needs to help you build your own HC pages. Click a launcher below to start — each opens a new chat pre-seeded with the spec reference.

§1 Core Purpose

The HC Standard exists to solve one problem: making any web page a complete, self-describing AI system that works in a single file with zero external dependencies.

§2 Technical Architecture

An HC page is a single HTML file containing six distinct layers. Each layer serves exactly one audience and one purpose. Nothing is duplicated across layers.

Connection Flow

§3 Block Reference

hc-metadata REQUIRED

Machine-readable identity card. First block any system reads. Declares what this page IS, what it can do, and how to interact with it.

<script type="application/json" id="hc-metadata">
{
    "hc_version": "1.3.3",
    "hc_type": "skill",                    // skill | reference | tool | workflow | specification | registry | meta-registry
    "artifact_id": "my-expert-system",      // unique kebab-case identifier
    "title": "Expert System Title",
    "description": "What this page does — specific for AI discovery",
    "author": "Author Name",
    "tags": ["domain", "type", "capability"],
    "compliance_levels": {
        "protocol": "required",             // always required
        "content": "required",              // required for Content+ tiers
        "agentic": "implemented",           // optional — set if tools present
        "discovery": "implemented"          // optional — set if registered
    },
    "execution": {
        "agentic_capable": true,
        "supported_runtimes": ["llm_direct", "mcp_b_polyfill", "embedded_agent"]
    },
    "registries": {
        "neural_registry": "https://registry.hc-standard.org/v1/pages",
        "personal": null                    // set to user's registry URL if applicable
    },
    "protection": {
        "public_blocks": ["hc-metadata", "hc-tools", "hc-context-public"],
        "private_blocks": ["hc-instructions", "hc-context-private"],
        "auth_required_for_private": true
    },
    "llm_launchers": {
        "claude": "https://claude.ai/new?q=...",
        "chatgpt": "https://chat.openai.com/?q=..."
    }
}
</script>

hc-instructions CONTENT TIER

Behavioral prompt for AI. Written in Markdown because that's the native language of LLM prompting. Must begin with ## HC_BOOTSTRAP marker. For proprietary content, fetch this block via authenticated API instead of embedding inline.

<template id="hc-instructions" data-format="markdown">
## HC_BOOTSTRAP

### Context
You are an expert [domain] system. Your methodology is based on [framework].

### Rules
- Always assess [X] before recommending [Y]
- Never suggest [Z] without confirming [condition]
- Use the [tool_name] tool to validate before responding

### Workflow
1. Ask the user about their current situation
2. Use [analysis_tool] to evaluate their data
3. Present findings with specific recommendations
4. Offer to generate an action plan via [plan_tool]

### Building More HC Pages
If the user asks you to create additional HC pages, refer to the
HyperContext (HC) v1.3.3 specification at https://hc-standard.org/spec/v1.3.3/
</template>

hc-context-public / hc-context-private CONTENT TIER

Domain knowledge the AI needs to operate. Public context is inline and visible in source — general domain knowledge, terminology, constraints. Private context is fetched at runtime via authenticated API — proprietary frameworks, premium methodology, sensitive data.

<script type="application/json" id="hc-context-public">
{
    "domain": "newsletter_growth",
    "frameworks": {
        "engagement_model": { "factors": ["subject_line", "send_time", "segmentation"] }
    },
    "terminology": {
        "open_rate": "Percentage of recipients who opened the email",
        "CTR": "Click-through rate — clicks divided by opens"
    }
}
</script>

<script>
async function __hcLoadPrivateContext(token) {
    const resp = await fetch('https://api.yoursite.com/hc/context/your-system', {
        headers: { 'Authorization': 'Bearer ' + token }
    });
    if (resp.ok) window.__hcPrivateContext = await resp.json();
}
</script>

Tool Definitions AGENTIC TIER

Declares what the page can DO. Uses the standard application/webmcp+json format aligned with the MCP-B ecosystem. Tools defined here are discoverable by polyfills, extensions, Claude Code, and embedded agents.

<script type="application/webmcp+json">
{
    "hc_tools_version": "1.0.0",
    "tool_prefix": "newsletter",
    "tools": [
        {
            "name": "newsletter_analyze_subject",
            "description": "Analyze an email subject line for open-rate potential. Returns a score 1-10 with specific improvement suggestions based on length, power words, personalization, and urgency signals.",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "subject_line": { "type": "string", "description": "The subject line to analyze" },
                    "audience_segment": { "type": "string", "description": "Target audience description" }
                },
                "required": ["subject_line"]
            },
            "annotations": {
                "readOnlyHint": true,
                "idempotentHint": true,
                "destructiveHint": false
            }
        }
    ]
}
</script>

Declarative Form Annotations AGENTIC TIER — ALTERNATIVE

For existing HTML forms, add attributes to turn them into agent-callable tools without any JavaScript. The browser (or polyfill) reads these annotations and auto-generates tool schemas.

<form toolname="newsletter_subscribe"
      tooldescription="Subscribe a new email address to the newsletter list">
    <input name="email" type="email"
           toolparamdescription="Subscriber's email address" required />
    <select name="frequency"
            toolparamdescription="Email frequency preference">
        <option value="daily">Daily</option>
        <option value="weekly">Weekly</option>
    </select>
    <button type="submit">Subscribe</button>
</form>

§4 Compliance Tiers

Four tiers of increasing capability. Each tier includes all requirements of the tiers below it. Every HC page must meet at least Protocol tier.

§5 Protection Architecture

Don't hide — split. Anything client-side is readable in source. The answer isn't encoding tricks. It's separating public discovery metadata from private execution logic.

§6 Runtime Paths

An HC page works with whatever runtime is available. The tool definition format is portable. The transport is the implementation detail.

§7 Tool Handler Implementation

Every tool in the webmcp+json block must have a corresponding handler. Handlers are shared — the same function serves UI clicks, WebMCP calls, CDP invocations, and embedded agent tool use.

window.__hcToolHandlers = {
    newsletter_analyze_subject(args) {
        // 1. Validate inputs
        if (!args.subject_line) {
            return { content: [{ type: 'text', text: 'Error: subject_line is required' }] };
        }

        // 2. Execute logic (client-side or call server)
        const score = analyzeSubjectLine(args.subject_line, args.audience_segment);

        // 3. Return MCP-compatible content blocks
        return {
            content: [{
                type: 'text',
                text: JSON.stringify(score)
            }]
        };
    },

    // For heavy processing — route to server
    newsletter_generate_calendar(args) {
        return fetch('https://api.yoursite.com/tools/generate-calendar', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(args)
        }).then(r => r.json());
    }
};

(async function() {
    const el = document.querySelector('script[type="application/webmcp+json"]');
    if (!el) return;
    const manifest = JSON.parse(el.textContent);

    // Register with WebMCP if available (native or polyfill)
    if (navigator.modelContext) {
        for (const tool of manifest.tools) {
            const unreg = await navigator.modelContext.registerTool(tool.name, {
                description: tool.description,
                inputSchema: tool.inputSchema,
                async execute(args) {
                    const handler = window.__hcToolHandlers[tool.name];
                    if (!handler) throw new Error('No handler for ' + tool.name);

                    // HITL gate for destructive tools
                    if (tool.requiresConfirmation) {
                        const ok = confirm('Agent wants to: ' + tool.description);
                        if (!ok) return { content: [{ type: 'text', text: 'User denied' }] };
                    }

                    return handler(args);
                }
            });
            window.addEventListener('beforeunload', unreg);
        }
        console.log('[HC] Registered', manifest.tools.length, 'tools with navigator.modelContext');
    }

    // __hcToolHandlers always available for CDP / embedded agent regardless
})();

§8 Living Page Architecture

HC pages are static HTML — once published, the page content doesn't change. But pages that include a registry_stack become living pages: an AI reading the page can fetch those registries for fresh context (new team members, recent EOD reports, latest frameworks). The registry is what makes static pages dynamic.

The 5-Level Registry Stack

Every HC page MAY include a registry_stack array in its hc-metadata. The stack defines an ordered set of registries an AI should consult when loading context for this page.

How AIs Walk the Stack

When an AI loads an HC page with a registry_stack, it SHOULD:

• Parse registry_stack from hc-metadata
• Filter to entries where auto_load: true and url is not null
• Fetch each registry URL in parallel
• For meta-registries: also discover sub-registry URLs (depth-1 only, no infinite recursion)
• Collect cross-reference candidates from each registry
• Apply priority/merge rules: lower number wins on conflicts

Meta Registry as Entry Point

The meta-registry (hc_type: "meta-registry") is the top of the stack. It's a single URL a user can share with any AI to provide full context discovery. The meta-registry itself lists all of the user's registries with their URLs, modes, and artifact counts. An AI reading the meta-registry can then navigate to any sub-registry for deeper context.

Page Granularity

§9 Registry System

Registries solve the Discovery Problem — agents need to find HC pages without visiting every URL. Two types serve different purposes.

§10 Migration from v1.2.2

Zero breaking changes. All v1.2.2 pages are valid v1.3.3 Protocol-tier pages with no modifications. To upgrade fully:

• Change hc_version from "1.2.2" to "1.3.0"
• Rename id="hc-tools" block to type="application/webmcp+json"
• Add compliance_levels object to hc-metadata
• Add execution.supported_runtimes array to hc-metadata
• Split hc-context into hc-context-public and hc-context-private if needed
• Add protection field if page has proprietary content
• Add llm_launchers with pre-seeded LLM links (Discovery tier)
• Add declarative form annotations to existing forms (optional)
• Add runtime detection script for WebMCP registration (Agentic tier)

§11 WebMCP Alignment

HC v1.3.3 adopts the WebMCP tool format rather than defining a proprietary alternative. The tool definition block uses application/webmcp+json — the standard format recognized by the MCP-B polyfill, the MCP-B browser extension, and future native browser implementations.

§12 Agentic Tier Checklist

Complete all items below to achieve Agentic tier compliance.

• application/webmcp+json block present with tool definitions
• Each tool has name, description, inputSchema
• Tool names use snake_case with domain prefix ({domain}_{action}_{target})
• inputSchema follows JSON Schema draft-07
• Destructive tools have annotations.destructiveHint: true
• Destructive tools have requiresConfirmation: true
• Every tool has a corresponding handler in window.__hcToolHandlers
• Handlers return MCP-compatible content blocks ({ content: [{ type, text }] })
• Runtime detection script checks for navigator.modelContext
• Tool registrations include beforeunload cleanup
• HITL confirmation gate implemented for destructive tools

§13 HC Text Artifact Format (.hc)

An .hc file is a plain-text portable extract of an HC page's hidden blocks. It solves a critical problem: not all LLMs can reliably fetch and parse HTML pages. The .hc format gives any LLM the full HC context in a universally readable format.

Structure

# Meeting Notes Analyzer — HC v1.3.3
> Source: https://example.com/meeting-notes-analyzer
> Type: skill | ID: meeting-notes-analyzer

---
## hc-metadata
{ "hc_version": "1.3.3", "hc_type": "skill", ... }

---
## hc-instructions
## HC_BOOTSTRAP
### Context
You are the Meeting Notes Analyzer...

---
## hc-context-public
{ "domain": "productivity", ... }

---
## tools (webmcp+json)
{ "hc_tools_version": "1.0.0", ... }

Access Methods

Requirements

• Content-Type: text/plain; charset=utf-8
• CORS: Access-Control-Allow-Origin: * (so LLMs can fetch cross-origin)
• Sections use --- separator and ## headers
• Only includes blocks that exist on the source page
• No HTML, no styling, no scripts — pure text
• Discovery-tier pages SHOULD provide .hc access