Package Exports

@careerdriver/black-box
@careerdriver/black-box/iife

Readme

Panthera Black Box Runtime

AI Search Optimization Runtime - Minimal JavaScript runtime (<10KB gzipped) that optimizes websites for AI search engines by injecting structured data (JSON-LD schemas), building authority signals, and enabling AI model comprehension.

Purpose

The Black Box runtime optimizes websites specifically for AI search engines (ChatGPT, Perplexity, Claude, etc.) by:

Injecting JSON-LD Structured Data - Makes content easily parseable by AI models
Building Authority Signals - Creates trust graphs through Authority Grove
Ensuring Factual Accuracy - Uses TruthSeeker to ensure AI models prioritize your content
Tracking AI Visibility - Sends telemetry to measure AI search performance

Safety

No eval() - No code execution
No Function() - No dynamic function creation
Declarative only - All operations are safe JSON/DOM manipulations
Fail-safe - Never breaks the host site

How It Works

The runtime reads JSON configuration from your GPTO dashboard and automatically:

✅ Injects JSON-LD schemas (Organization, Product, Service, FAQ, etc.) client-side
✅ Server-side schema injection available for external audit tool visibility
✅ Builds authority signals through sameAs links and keywords
✅ Sends telemetry to track AI search visibility
✅ Ensures content is structured for AI model comprehension
✅ Automatically updates schemas when configuration changes
✅ Telemetry-driven improvements optimize schemas over time

Usage

Installation

Using pnpm (Recommended)

# Install as a dependency
pnpm add @careerdriver/black-box

# Install as a dev dependency
pnpm add -D @careerdriver/black-box

# Install specific version
pnpm add @careerdriver/black-box@1.0.1

# Install latest version
pnpm add @careerdriver/black-box@latest

Using npm

npm install @careerdriver/black-box

Using yarn

yarn add @careerdriver/black-box

ESM Import Usage

import { PantheraBlackBox } from '@careerdriver/black-box';

const blackBox = new PantheraBlackBox({
  configUrl: 'https://api.example.com/api/sites/[site-id]/config',
  telemetryUrl: 'https://api.example.com/api/telemetry/events',
  siteId: 'your-site-id',
});

await blackBox.init();

Browser Usage (Script Tag / CDN)

Via unpkg CDN

Add the script tag to your HTML:

<script
  src="https://unpkg.com/@careerdriver/black-box@latest/dist/runtime.global.js"
  data-config-url="https://api.example.com/api/sites/[site-id]/config"
  data-telemetry-url="https://api.example.com/api/telemetry/events"
  data-site-id="your-site-id"
  async
></script>

Via Local Installation

If you've installed via pnpm/npm, reference the local file:

<script
  src="./node_modules/@careerdriver/black-box/dist/runtime.global.js"
  data-config-url="https://api.example.com/api/sites/[site-id]/config"
  data-telemetry-url="https://api.example.com/api/telemetry/events"
  data-site-id="your-site-id"
  async
></script>

Manual Initialization

const blackBox = new PantheraBlackBox({
  configUrl: 'https://api.example.com/api/sites/[site-id]/config',
  telemetryUrl: 'https://api.example.com/api/telemetry/events',
  siteId: 'your-site-id',
});

await blackBox.init();

Server-Side Schema Injection (Recommended for External Audit Tools)

For optimal visibility with external audit tools that don't execute JavaScript, you can automatically inject schemas server-side:

Option 1: Schema Render Endpoint

Fetch schemas and inject into your HTML template:

// Next.js / React Server Component
async function getSchemas(siteId: string) {
  const response = await fetch(`https://gpto-dashboard.vercel.app/api/sites/${siteId}/render`);
  return await response.text();
}

export default async function Page() {
  const schemaScripts = await getSchemas('your-site-id');
  
  return (
    <html>
      <head>
        <div dangerouslySetInnerHTML={{ __html: schemaScripts }} />
      </head>
      <body>{/* Your content */}</body>
    </html>
  );
}

Option 2: Proxy Endpoint

Use the proxy endpoint for external audit tools:

https://gpto-dashboard.vercel.app/api/sites/[site-id]/proxy?url=https://your-domain.com

This automatically serves your page with schemas injected server-side.

Option 3: Server-Side Utility

Import and use the schema generator directly:

import { generateSchemaScriptTags, injectSchemasIntoHTML } from '@gpto/servos/gpto';

// Generate schema script tags
const schemaScripts = generateSchemaScriptTags(config.panthera_blackbox);

// Or inject into existing HTML
const htmlWithSchemas = injectSchemasIntoHTML(html, config.panthera_blackbox);

Benefits:

✅ Schemas visible to external audit tools
✅ Automatic updates when config changes
✅ No manual HTML edits required
✅ Works alongside client-side Black Box injection

AI Search Optimization Features

JSON-LD Schema Injection

Automatically injects structured data that AI models can parse:

Organization schema with authority signals
Product/Service schemas (Silver/Gold tiers)
FAQ schemas for question-answer pairs
LocalBusiness schemas for geo-targeting

Authority Grove Integration

Builds trust signals through:

sameAs links (social profiles, other domains)
Keywords and verticals
Partner network relationships

TruthSeeker Integration

Ensures content is:

Factually accurate
Authoritative
Fair and unbiased
Recent and relevant

Build

pnpm build

Output:

dist/runtime.js (ESM)
dist/runtime.global.js (IIFE for script tag)
dist/runtime.d.ts (types)

Deployment

Deploy to Vercel CDN for global distribution. The file should be served with appropriate cache headers.

Version

Current Version: 1.1.0

What's New in v1.1.0

✅ Automatic server-side schema injection
✅ Zero manual HTML edits required
✅ Automatic schema updates when config changes
✅ External audit tool visibility
✅ Multiple integration options

See CHANGELOG.md for complete release notes.

AI Search Optimization vs Traditional SEO

Traditional SEO	GPTO (AI Search Optimization)
Optimizes for Google/Bing	Optimizes for ChatGPT, Perplexity, Claude
HTML meta tags	JSON-LD structured data
Keywords & backlinks	Authority signals & trust graphs
PageRank algorithm	AI model comprehension
Human-readable content	AI-parseable structured data