@careerdriver/black-box

v1.3.0

Published

a month ago

AI Search Optimization Runtime - Automatic JSON-LD schema injection with server-side rendering support

0High
0Medium
0Low

braieswabe-cdhq

mcelestino-conversion

ai-search gpt-optimization schema.org json-ld seo ai-visibility structured-data chatgpt perplexity claude

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
✅ Periodic telemetry sends comprehensive metrics every 5 minutes for real-time dashboard updates
✅ Ensures content is structured for AI model comprehension
✅ Automatically updates schemas when configuration changes
✅ Telemetry-driven improvements optimize schemas over time

Usage

Context-Only Mode (No Header/HTML Injection)

If you want Blackbox to collect telemetry/context only (without changing visible HTML or <head>), set:

{
  "panthera_blackbox": {
    "frontend_mode": "context_only",
    "invisible_context_only": true
  }
}

In this mode, Blackbox keeps config fetch + telemetry sending active, but skips schema/meta/title/content injections.

Quick Start Guide

Step 1: Install via npm (Primary)

npm install @careerdriver/black-box

The runtime is ESM-only and works with modern bundlers (Vite, Next.js, Webpack 5) and ESM-compatible environments.

Step 2: Import and initialize

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

const blackBox = new PantheraBlackBox({
  configUrl: 'https://gpto-dashboard.vercel.app/api/sites/YOUR-SITE-ID/config',
  telemetryUrl: 'https://gpto-dashboard.vercel.app/api/telemetry/events',
  siteId: 'YOUR-SITE-ID',
});

await blackBox.init();

Step 3: (Recommended) Add Server-Side Schema Injection

For optimal visibility with external audit tools, inject schemas server-side. Schemas update automatically when your configuration changes.

Option A: Schema Render Endpoint

Fetch schemas and inject into your HTML template:

// Next.js / React
const schemas = await fetch('https://gpto-dashboard.vercel.app/api/sites/[your-site-id]/render');
const schemaHTML = await schemas.text();

// Inject into HTML
<div dangerouslySetInnerHTML={{ __html: schemaHTML }} />

Option B: Proxy Endpoint

Use for external audit tools or testing:

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

Replace your-domain.com with your actual domain.

✅ Automatic Updates: Schemas are generated from your configuration and update automatically. No manual HTML edits needed!

Installation (Canonical: NPM + ESM)

Using npm (Primary)

npm install @careerdriver/black-box

The runtime is ESM-only and works with modern bundlers (Vite, Next.js, Webpack 5) and ESM-compatible environments.

Step 2: Import and Initialize

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

const blackBox = new PantheraBlackBox({
  configUrl: 'https://gpto-dashboard.vercel.app/api/sites/YOUR-SITE-ID/config',
  telemetryUrl: 'https://gpto-dashboard.vercel.app/api/telemetry/events',
  siteId: 'YOUR-SITE-ID',
});

await blackBox.init();

Using pnpm

# 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/[email protected]

# Install latest version (includes periodic telemetry)
pnpm add @careerdriver/black-box@latest

Note: v1.2.0+ includes periodic telemetry for real-time dashboard updates. See Periodic Telemetry Guide for details.

Using npm

# Install latest version
npm install @careerdriver/black-box@latest

# Install specific version
npm install @careerdriver/[email protected]

Using yarn

# Install latest version (includes periodic telemetry)
yarn add @careerdriver/black-box@latest

# Install specific version
yarn add @careerdriver/[email protected]

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, fallback)

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>

Note: The @latest version includes periodic telemetry (v1.2.0+). To use a specific version, replace @latest with @1.3.0 or your preferred version.

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

Periodic Telemetry (v1.2.0+)

Automatically sends comprehensive metrics to the GPTO dashboard every 5 minutes:

Features:

Real-time Dashboard Updates: Populates telemetry, confusion, authority, schema, and coverage metrics
Comprehensive Metrics: Collects real metrics from page state (JSON-LD schemas, authority signals, content gaps)
Confusion Detection: Tracks repeated searches, dead ends, and drop-offs
Coverage Analysis: Detects content gaps, funnel stages, and intent mismatches
Configurable Interval: Default 5 minutes, customizable via config

Enable Periodic Telemetry:

Add to your site configuration in the GPTO dashboard:

{
  "panthera_blackbox": {
    "telemetry": {
      "emit": true,
      "keys": [
        "ts.authority",
        "ai.schemaCompleteness",
        "ai.structuredDataQuality",
        "ai.authoritySignals",
        "ai.searchVisibility"
      ],
      "periodic": {
        "enabled": true,
        "intervalMs": 300000
      }
    }
  }
}

What Gets Sent:

Page views, interactions, and searches (aggregated counts)
Schema completeness and quality scores
Authority and trust signals
Confusion patterns (repeated searches, dead ends, drop-offs)
Content gaps and funnel stage detection
Intent detection and coverage analysis
Page-level coverage metadata (page, missingContentDimensions)
Recommended focus hints (recommendedFocus) for dashboard explanations
Rich confusion evidence (deadEndsDetail, dropOffsDetail, repeatedSearchesDetail)
Config-aware capture metadata (captureMeta.configFrameworkVersion)
Recommendation feedback references (recommendationFeedback.activeReadabilityActionIds)

AI Readability Config Contract (Additive)

The config endpoint can now include panthera_blackbox.ai_readability with evidence-backed clarity scoring and recommended actions.

{
  "panthera_blackbox": {
    "ai_readability": {
      "frameworkVersion": "gpto.ai_readability.v1",
      "packageTier": "bronze",
      "overall": { "score": 0, "grade": "F" },
      "recommendedActions": [],
      "insufficientData": {
        "reason": "Readability rollup is still building.",
        "missingSignals": ["periodic telemetry", "readability rollup"]
      }
    }
  }
}

GPTO readability metrics describe clarity and machine-readability. They do not claim traffic, revenue, lead, conversion, or ROI outcomes.

Dashboard Integration: All periodic telemetry data automatically populates:

Telemetry dashboard (views, visits, top pages)
Confusion dashboard (dead ends, repeated searches)
Authority dashboard (trust scores, confidence gaps)
Schema dashboard (completeness, quality)
Coverage dashboard (content gaps, missing stages)
Business Brief (executive insights)
Pulse Cards (experience health, trust lift, coverage risk)
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.

Maintainer Release

Use the release helper from repo root to validate runtime + suite compatibility before publishing:

./scripts/release-black-box.sh

After checks pass:

cd apps/black-box
npm publish --access public

Version

Current Version: 1.2.3

What's New in v1.2.3

✅ Additive telemetry enrichment for confusion root-cause evidence
✅ Additive telemetry enrichment for coverage detail and recommended focus
✅ Backward-compatible payload shape (no breaking changes for integrators)
✅ NPM-first installation guidance for website-integrated runtime

What's New in v1.2.0

✅ Periodic Telemetry: Automatic comprehensive metrics collection every 5 minutes
✅ Real-time Dashboard Updates: Populates all dashboard sections with live data
✅ Enhanced Metrics Collection: Real metrics from page state (not random values)
✅ Confusion Detection: Tracks repeated searches, dead ends, drop-offs
✅ Coverage Analysis: Detects content gaps, funnel stages, intent mismatches
✅ Configurable Interval: Customize periodic telemetry interval

Previous Features (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 |