peptide-repo/pr-vision
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.1 — dashboard visuals + deploy pipeline

Browse Source 
Piece 1 — Visuals
- Add KPI bento bar (score tile with run-health pill, cost tile, last-run tile).
  Run-health pill shows 'All models healthy' / 'N model(s) degraded' / 'No run
  yet' sourced from PRV_Model_Registry health fields via collector.
- Add config-change trendline marker: inline configMarker Chart.js plugin draws
  a vertical dashed orange line + pin at every config_version boundary.
  Legend swatch + annotation note appear when breaks exist.
- Chart sits in fixed .prv-chartbox (300px); typeof-Chart guard + .prv-noscript
  fallback — cannot grow layout, degrades gracefully offline.
- PRV_Dashboard_Renderer: new class owns bento tile + trendline rendering.
  PRV_Ai_Visibility_Panel is now a thin orchestrator (237 lines).
- PRV_Ai_Visibility_Collector: trendline query now includes MIN(config_version)
  per run; collect() adds last_run_counts and config_versions to payload.
- PRV_Admin_Page: get_dashboard_css() returns Assay dark palette CSS.

Piece 2 — Deploy pipeline
- .github/workflows/deploy.yml: on push to main, runs CI, rsyncs plugin to
  Hostinger PROD (excl. .git .github tests phpunit composer vendor phpcs *.md),
  purges LiteSpeed, health-checks (200/403). Standalone — not smoke-gated.

DoD
- Version 0.2.1 in header + constant; CHANGELOG, ARCHITECTURE, CONVENTIONS,
  CONTEXT all updated same commit.
- tests/unit/test-dashboard-panel.php: 27 assertions.
- Pre-push checks: no PHP built-in name shadows in bootstrap.php; all
  includes/*.php files <= 300 lines (max: 298).
This commit is contained in:
Engineer (geomonitor)
2026-06-14 12:52:07 +00:00
parent 2fcef7a323
commit 2a2424ce8c
12 changed files with 940 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
includes/collector/class-prv-ai-visibility-collector.php
View File

@@ -11,9 +11,11 @@ declare(strict_types=1);
* AI-visibility data collector — v1 implementation of PRV_Data_Collector.
*
* Reads the prv_ai_visibility table and returns structured data for:
* - Trendline: per-run visibility score (% cited, position-weighted).
* - Trendline: per-run visibility score (% cited, position-weighted) with config_version stamp.
* - Standings: per-peptide latest cited status, our position, competing domains.
* - Run metadata: last run time, MTD cost vs cap.
* - Per-model run-health from PRV_Model_Registry (last_run_counts).
* - All config-version records for trendline break annotations (config_versions).
*
* Score formula (documented in CONTEXT.md):
* base_score = cited_probes / total_probes (range 0–1)
@@ -21,10 +23,13 @@ declare(strict_types=1);
* visibility_score = round((base_score + position_bonus) / 2, 4)
*
* Who triggers: PRV_Admin_Page calls the registered collector via the registry.
* Dependencies: $wpdb, PRV_Table_Manager, PRV_Cost_Ledger, PRV_Config.
* Dependencies: $wpdb, PRV_Table_Manager, PRV_Cost_Ledger, PRV_Config,
* PRV_Model_Registry, PRV_Config_Version.
*
* @see interface-prv-data-collector.php — Interface this implements.
* @see class-prv-ai-visibility-panel.php — Renders the data returned here.
* @see class-prv-model-registry.php — Source of per-model health data.
* @see class-prv-config-version.php — Source of config-version records.
* @see CONTEXT.md — Score formula + glossary.
* @see ARCHITECTURE.md — §Storage, §Score.
* @package PrVision
@@ -51,11 +56,13 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
* {@inheritDoc}
*
* @return array{
* trendline: array<int, array{run_id: string, captured_at: string, score: float}>,
* trendline: array<int, array{run_id: string, captured_at: string, score: float, config_version: int|null}>,
* standings: array<string, array{label: string, cited: bool, our_position: int|null, top_domains: string[], model_count: int}>,
* last_run_at: string|null,
* mtd_cost_usd: float,
* monthly_cap_usd: float,
* last_run_counts: array<string, array{health_status: string, health_probed: int, health_errors: int}>,
* config_versions: array<int, array<string, mixed>>,
* }
*/
public function collect(): array {
@@ -63,13 +70,14 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
$table = PRV_Table_Manager::get_table_name();
// ── Trendline: one score per run_id ────────────────────────────
// ── Trendline: one score per run_id, with config_version ───────
// phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
$run_rows = $wpdb->get_results(
"SELECT run_id, MIN(captured_at) AS captured_at,
SUM(cited) AS cited_count,
COUNT(*) AS total_count,
SUM(CASE WHEN our_position IS NOT NULL THEN 1.0/our_position ELSE 0 END) AS position_sum
SUM(CASE WHEN our_position IS NOT NULL THEN 1.0/our_position ELSE 0 END) AS position_sum,
MIN(config_version) AS config_version
FROM {$table}
GROUP BY run_id
ORDER BY MIN(captured_at) ASC
@@ -81,13 +89,14 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
$trendline = array();
foreach ( (array) $run_rows as $row ) {
$trendline[] = array(
'run_id' => (string) $row['run_id'],
'captured_at' => (string) $row['captured_at'],
'score' => $this->compute_score(
'run_id' => (string) $row['run_id'],
'captured_at' => (string) $row['captured_at'],
'score' => $this->compute_score(
(int) $row['cited_count'],
(int) $row['total_count'],
(float) $row['position_sum']
),
'config_version' => isset( $row['config_version'] ) ? (int) $row['config_version'] : null,
);
}
@@ -108,7 +117,7 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
$standings = array();
foreach ( (array) $standing_rows as $row ) {
$top_domains = $this->extract_top_domains( (string) ( $row['domains_json_list'] ?? '' ) ); // phpcs:ignore Generic.Formatting.MultipleStatementAlignment.NotSameWarning
$top_domains = $this->extract_top_domains( (string) ( $row['domains_json_list'] ?? '' ) );
$standings[ (string) $row['peptide_slug'] ] = array(
'label' => (string) $row['peptide_label'],
'cited' => (bool) (int) $row['cited'],
@@ -123,12 +132,20 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
$last_run = $wpdb->get_var( "SELECT MAX(captured_at) FROM {$table}" );
// phpcs:enable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
// ── Per-model health from PRV_Model_Registry ────────────────────
$last_run_counts = $this->collect_model_health();
// ── Config-version records for trendline break annotations ──────
$config_versions = PRV_Config_Version::get_all_versions();
return array(
'trendline' => $trendline,
'standings' => $standings,
'last_run_at' => $last_run ? (string) $last_run : null,
'mtd_cost_usd' => $this->ledger->get_month_to_date_usd(),
'monthly_cap_usd' => PRV_Config::get_monthly_budget_usd(),
'last_run_counts' => $last_run_counts,
'config_versions' => $config_versions,
);
}
@@ -159,6 +176,32 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
return round( ( $base_score + $position_bonus ) / 2.0, 4 );
}
/**
* Collect per-model health data from PRV_Model_Registry for the dashboard pill.
*
* Returns a keyed map of model slug -> health fields. Models with
* health_status='disabled' are included so the pill reflects all registered
* models, not just the active ones.
*
* @return array<string, array{health_status: string, health_probed: int, health_errors: int}>
*/
private function collect_model_health(): array {
$models = PRV_Model_Registry::get_all();
$out = array();
foreach ( $models as $m ) {
$slug = (string) ( $m['slug'] ?? '' );
if ( '' === $slug ) {
continue;
}
$out[ $slug ] = array(
'health_status' => (string) ( $m['health_status'] ?? 'unknown' ),
'health_probed' => (int) ( $m['health_probed'] ?? 0 ),
'health_errors' => (int) ( $m['health_errors'] ?? 0 ),
);
}
return $out;
}
/**
* Extract and deduplicate the top domain names from a GROUP_CONCAT result.
*

98
includes/core/class-prv-admin-page.php
View File

@@ -10,9 +10,10 @@ declare(strict_types=1);
/**
* PR Vision top-level admin page.
*
* Registers the "PR Vision" menu item (manage_options), enqueues Chart.js,
* handles the "Run now" POST action (nonce + capability), and delegates
* rendering to the registered panels via PRV_Collector_Registry.
* Registers the "PR Vision" menu item (manage_options), enqueues Chart.js
* and the dashboard stylesheet, handles the "Run now" POST action (nonce +
* capability), and delegates rendering to the registered panels via
* PRV_Collector_Registry.
*
* Who triggers: PRV_Plugin::init() → is_admin() guard.
* Dependencies: PRV_Collector_Registry, PRV_Probe_Runner.
@@ -20,6 +21,7 @@ declare(strict_types=1);
* @see class-prv-plugin.php — Calls register_hooks().
* @see class-prv-collector-registry.php — Provides panels.
* @see class-prv-probe-runner.php — Invoked by the Run now action.
* @see class-prv-ai-visibility-panel.php — Panel renderer, consumes CSS added here.
* @see ARCHITECTURE.md — §Admin dashboard.
* @package PrVision
*/
@@ -73,7 +75,10 @@ class PRV_Admin_Page {
}
/**
* Enqueue Chart.js on the PR Vision page only.
* Enqueue Chart.js and dashboard styles on the PR Vision page only.
*
* Chart.js is loaded from the jsdelivr CDN. The dashboard panel degrades
* gracefully when the CDN is blocked (typeof guard + .prv-noscript fallback).
*
* @param string $hook Current admin page hook.
*
@@ -92,16 +97,7 @@ class PRV_Admin_Page {
true
);
wp_add_inline_style(
'wp-admin',
'.prv-meta-bar{display:flex;gap:20px;margin:10px 0 15px;flex-wrap:wrap;}
.prv-meta-item{background:#f6f7f7;padding:6px 12px;border-radius:4px;font-size:13px;}
.prv-card{background:#fff;border:1px solid #c3c4c7;padding:16px 20px;margin-bottom:20px;border-radius:4px;}
.prv-card h2{margin-top:0;}
.prv-proxy-note{margin:10px 0;}
.prv-standings th,.prv-standings td{vertical-align:middle;}
canvas#prv-trendline-chart{max-height:300px;}'
);
wp_add_inline_style( 'wp-admin', $this->get_dashboard_css() );
}
/**
@@ -158,7 +154,6 @@ class PRV_Admin_Page {
$this->render_run_done_notice();
// "Run now" button form.
echo '<form method="post" action="' . esc_url( admin_url( 'admin-post.php' ) ) . '">';
echo '<input type="hidden" name="action" value="prv_run_now">';
wp_nonce_field( self::NONCE_ACTION, self::NONCE_FIELD );
@@ -204,4 +199,77 @@ class PRV_Admin_Page {
);
echo '</p></div>';
}
/**
* Return the dashboard CSS for the PR Vision admin page.
*
* Uses CSS custom properties matching the "Assay" dark design palette from
* design/pr-vision/design-proposal.md. Scoped to .prv-* selectors so it
* cannot leak into WP admin chrome.
*
* @return string CSS string.
*/
private function get_dashboard_css(): string {
return '
/* === PR Vision dashboard — "Assay" palette (dark-adapted) === */
.prv-bento{display:grid;grid-template-columns:1.25fr 1fr 1fr;gap:16px;margin:18px 0 22px;}
@media(max-width:820px){.prv-bento{grid-template-columns:1fr;}}
.prv-tile{background:#1C2228;border:1px solid #3A4651;border-radius:12px;padding:20px 22px;position:relative;min-height:140px;display:flex;flex-direction:column;}
.prv-tile-label{font-size:11.5px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:#9AA7B2;margin-bottom:6px;}
.prv-tile-big{font-size:42px;font-weight:700;color:#EEF2F5;line-height:1;font-variant-numeric:tabular-nums;margin-top:auto;}
.prv-tile-big small{font-size:16px;font-weight:600;color:#9AA7B2;margin-left:3px;}
.prv-tile-sub{font-size:12.5px;color:#9AA7B2;margin-top:8px;}
.prv-tile-delta{font-size:12.5px;font-weight:600;margin-top:8px;}
.prv-delta--up{color:#9BE635;} .prv-delta--down{color:#FF6B5E;} .prv-delta--flat{color:#9AA7B2;}
/* health pill */
.prv-health-pill{position:absolute;top:14px;right:14px;display:inline-flex;align-items:center;gap:5px;font-size:11.5px;font-weight:600;padding:3px 9px 3px 7px;border-radius:999px;}
.prv-health-dot{width:7px;height:7px;border-radius:50%;flex:0 0 7px;}
.prv-health--ok{background:rgba(155,230,53,.15);color:#9BE635;} .prv-health--ok .prv-health-dot{background:#9BE635;}
.prv-health--warn{background:rgba(255,157,77,.15);color:#FFB36E;} .prv-health--warn .prv-health-dot{background:#FF9D4D;}
.prv-health--neutral{background:rgba(136,147,160,.14);color:#B4BDC7;} .prv-health--neutral .prv-health-dot{background:#8893A0;}
/* cost tile */
.prv-cost-row{display:flex;align-items:baseline;gap:4px;margin-top:auto;}
.prv-cost-big{font-size:28px;font-weight:700;color:#EEF2F5;font-variant-numeric:tabular-nums;}
.prv-cost-cap{font-size:13px;color:#9AA7B2;}
.prv-meter{height:10px;border-radius:999px;background:#2A333C;margin-top:8px;border:1px solid #333D47;overflow:hidden;}
.prv-meter>span{display:block;height:100%;border-radius:999px;background:#34C0CA;transition:width .3s ease;}
.prv-meter--capped>span{background:#FF9D4D;}
.prv-trunc-badge{display:flex;align-items:flex-start;gap:7px;margin-top:10px;background:rgba(255,157,77,.15);border:1px solid rgba(255,157,77,.42);border-radius:6px;padding:8px 10px;font-size:12px;color:#EEF2F5;line-height:1.4;}
.prv-trunc-icon{color:#FFB36E;font-size:14px;flex:0 0 16px;margin-top:1px;}
.prv-trunc-badge b{color:#FFB36E;}
/* last run tile */
.prv-tile-ts{font-size:20px;font-weight:700;color:#EEF2F5;margin-top:auto;line-height:1.2;}
.prv-tile-meta{font-size:12.5px;color:#9AA7B2;margin-top:6px;}
/* cards */
.prv-card{background:#1C2228;border:1px solid #3A4651;border-radius:12px;margin:0 0 20px;}
.prv-card-head{display:flex;align-items:center;justify-content:space-between;padding:18px 22px 0;}
.prv-card-head h2{font-size:16px;font-weight:600;color:#EEF2F5;margin:0;}
.prv-card-body{padding:10px 22px 20px;}
/* chart */
.prv-chartbox{position:relative;height:300px;max-height:300px;padding:14px 8px 0;overflow:hidden;}
.prv-chartbox canvas{max-height:286px;}
.prv-chart-fallback{display:none;height:100%;align-items:center;justify-content:center;text-align:center;color:#9AA7B2;font-size:13px;padding:0 24px;}
.prv-chartbox.prv-noscript .prv-chart-fallback{display:flex;}
.prv-chartbox.prv-noscript canvas{display:none;}
/* chart legend */
.prv-chartcap{display:flex;align-items:center;gap:16px;flex-wrap:wrap;padding:8px 22px 4px;font-size:12.5px;color:#9AA7B2;}
.prv-chartcap-item{display:inline-flex;align-items:center;gap:6px;}
.prv-leg-solid{width:20px;height:0;border-top:3px solid #34C0CA;display:inline-block;}
.prv-leg-dash{width:20px;height:0;border-top:2px dashed #B6F25A;display:inline-block;}
.prv-leg-cfg{display:inline-flex;align-items:center;gap:3px;}
.prv-leg-cfg::before{content:"";width:0;height:14px;border-left:2px dashed #FFB36E;display:inline-block;}
.prv-leg-cfg::after{content:"";width:8px;height:8px;border-radius:50%;background:#FF9D4D;display:inline-block;}
/* config change note */
.prv-cfg-note{display:flex;gap:10px;align-items:flex-start;margin:8px 22px 14px;background:rgba(255,157,77,.15);border:1px solid rgba(255,157,77,.42);border-radius:8px;padding:11px 14px;color:#EEF2F5;font-size:13px;line-height:1.45;}
.prv-cfg-note-icon{color:#FFB36E;font-style:normal;flex:0 0 16px;margin-top:1px;}
.prv-cfg-note b{color:#FFB36E;}
/* standings table */
.prv-standings{margin:0;}
.prv-status{display:inline-flex;align-items:center;gap:4px;font-size:12.5px;font-weight:600;padding:2px 8px;border-radius:999px;}
.prv-status--cited{background:rgba(155,230,53,.15);color:#9BE635;}
.prv-status--not-yet{background:rgba(136,147,160,.14);color:#B4BDC7;}
/* proxy note */
.prv-proxy-note{margin:10px 0;}
';
}
}

205
includes/panel/class-prv-ai-visibility-panel.php
View File

@@ -8,26 +8,50 @@
declare(strict_types=1);
/**
* AI-visibility dashboard panel — renders the PR Vision admin page.
* AI-visibility dashboard panel — orchestrates the PR Vision admin page.
*
* Renders four sections:
* Renders five sections by delegating the visual heavy-lifting to helper classes:
* 1. Proxy-metric disclaimer note.
* 2. Chart.js trendline of visibility score across runs.
* 3. Per-peptide standings table (cited, position, top competitor domains).
* 4. MTD cost vs cap + last-run time.
* 2. KPI bento bar (score tile with run-health pill, cost tile, last-run tile)
* — via PRV_Dashboard_Renderer::render_bento().
* 3. Chart.js trendline with config-change vertical markers
* — via PRV_Dashboard_Renderer::render_trendline().
* 4. Per-peptide standings table.
*
* All output is escaped. Chart.js is enqueued via PRV_Admin_Page.
* The run-health pill (score tile) and config-change markers (trendline) are
* the two v0.2.1 additions.
*
* Chart.js is enqueued via PRV_Admin_Page. The chart sits in a fixed-height box
* and degrades gracefully: if Chart.js is unavailable the typeof guard adds
* .prv-noscript, hiding the canvas and showing a fallback note in the same space.
*
* Who triggers: PRV_Admin_Page::render_page() via PRV_Collector_Registry.
* Dependencies: PRV_Ai_Visibility_Collector (data format contract).
* Dependencies: PRV_Ai_Visibility_Collector (data format), PRV_Dashboard_Renderer.
*
* @see interface-prv-dashboard-panel.php — Interface this implements.
* @see class-prv-ai-visibility-collector.php — Produces the $data array.
* @see class-prv-dashboard-renderer.php — Renders bento + trendline.
* @see class-prv-admin-page.php — Enqueues Chart.js; calls render().
* @package PrVision
*/
class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
/**
* Visual renderer for the bento tiles and trendline.
*
* @var PRV_Dashboard_Renderer
*/
private PRV_Dashboard_Renderer $renderer;
/**
* Constructor.
*
* @param PRV_Dashboard_Renderer|null $renderer Injected for testing; auto-created otherwise.
*/
public function __construct( ?PRV_Dashboard_Renderer $renderer = null ) {
$this->renderer = $renderer ?? new PRV_Dashboard_Renderer();
}
/**
* {@inheritDoc}
*
@@ -36,15 +60,16 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
* @return void
*/
public function render( array $data ): void {
$trendline = is_array( $data['trendline'] ?? null ) ? $data['trendline'] : array();
$standings = is_array( $data['standings'] ?? null ) ? $data['standings'] : array();
$last_run_at = isset( $data['last_run_at'] ) && $data['last_run_at'] ? esc_html( (string) $data['last_run_at'] ) : esc_html__( 'Never', 'pr-vision' );
$mtd_cost = isset( $data['mtd_cost_usd'] ) ? (float) $data['mtd_cost_usd'] : 0.0;
$cap = isset( $data['monthly_cap_usd'] ) ? (float) $data['monthly_cap_usd'] : PRV_DEFAULT_MONTHLY_BUDGET_USD;
$trendline = is_array( $data['trendline'] ?? null ) ? $data['trendline'] : array();
$standings = is_array( $data['standings'] ?? null ) ? $data['standings'] : array();
$last_run_at = isset( $data['last_run_at'] ) && $data['last_run_at'] ? esc_html( (string) $data['last_run_at'] ) : esc_html__( 'Never', 'pr-vision' );
$mtd_cost = isset( $data['mtd_cost_usd'] ) ? (float) $data['mtd_cost_usd'] : 0.0;
$cap = isset( $data['monthly_cap_usd'] ) ? (float) $data['monthly_cap_usd'] : PRV_DEFAULT_MONTHLY_BUDGET_USD;
$last_run_counts = is_array( $data['last_run_counts'] ?? null ) ? $data['last_run_counts'] : array();
$this->render_proxy_note();
$this->render_meta_bar( $last_run_at, $mtd_cost, $cap );
$this->render_trendline( $trendline );
$this->render_bento_band( $trendline, $standings, $last_run_at, $mtd_cost, $cap, $last_run_counts );
$this->renderer->render_trendline( $trendline );
$this->render_standings( $standings );
}
@@ -68,55 +93,53 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
}
/**
* Render the run metadata bar (last run, cost, cap).
* Prepare bento-band data and delegate rendering to PRV_Dashboard_Renderer.
*
* @param string $last_run_at Formatted last-run timestamp or "Never".
* @param float $mtd_cost Month-to-date spend in USD.
* @param float $cap Monthly cap in USD.
* @param array<int, array{run_id: string, captured_at: string, score: float}> $trendline Trendline data.
* @param array<string, array{label: string, cited: bool}> $standings Standings map.
* @param string $last_run_at Formatted timestamp.
* @param float $mtd_cost Month-to-date spend USD.
* @param float $cap Monthly cap USD.
* @param array<string, array{health_status: string}> $last_run_counts Per-model health.
*
* @return void
*/
private function render_meta_bar( string $last_run_at, float $mtd_cost, float $cap ): void {
$pct = $cap > 0 ? min( 100.0, round( $mtd_cost / $cap * 100, 1 ) ) : 0;
echo '<div class="prv-meta-bar">';
echo '<span class="prv-meta-item"><strong>' . esc_html__( 'Last run:', 'pr-vision' ) . '</strong> ' . esc_html( $last_run_at ) . '</span>';
echo '<span class="prv-meta-item"><strong>' . esc_html__( 'MTD cost:', 'pr-vision' ) . '</strong> $' . esc_html( number_format( $mtd_cost, 4 ) ) . ' / $' . esc_html( number_format( $cap, 2 ) ) . ' (' . esc_html( $pct ) . '% of cap)</span>';
echo '</div>';
}
private function render_bento_band(
array $trendline,
array $standings,
string $last_run_at,
float $mtd_cost,
float $cap,
array $last_run_counts
): void {
$current_score = empty( $trendline ) ? 0.0 : (float) end( $trendline )['score'];
$prev_score = count( $trendline ) >= 2 ? (float) $trendline[ count( $trendline ) - 2 ]['score'] : null;
$cited_count = 0;
$total_count = count( $standings );
/**
* Render the Chart.js visibility score trendline.
*
* @param array<int, array{run_id: string, captured_at: string, score: float}> $trendline Trendline data points.
*
* @return void
*/
private function render_trendline( array $trendline ): void {
echo '<div class="prv-card"><h2>' . esc_html__( 'Visibility Score — Trend', 'pr-vision' ) . '</h2>';
if ( empty( $trendline ) ) {
echo '<p>' . esc_html__( 'No probe runs recorded yet. Click "Run now" to collect the first data point.', 'pr-vision' ) . '</p></div>';
return;
foreach ( $standings as $row ) {
if ( ! empty( $row['cited'] ) ) {
$cited_count++;
}
}
$labels = array();
$scores = array();
foreach ( $trendline as $point ) {
$labels[] = esc_js( gmdate( 'M j', (int) strtotime( $point['captured_at'] ) ) );
$scores[] = (float) $point['score'];
}
$health = $this->derive_health_pill_state( $last_run_counts );
$pct = $cap > 0 ? min( 100.0, round( $mtd_cost / $cap * 100, 1 ) ) : 0;
$truncated = (bool) get_option( 'prv_last_run_truncated', false );
$labels_json = wp_json_encode( $labels );
$scores_json = wp_json_encode( $scores );
echo '<canvas id="prv-trendline-chart" height="120"></canvas>';
// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
echo '<script>document.addEventListener("DOMContentLoaded",function(){';
echo 'var ctx=document.getElementById("prv-trendline-chart").getContext("2d");';
// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
echo 'new Chart(ctx,{type:"line",data:{labels:' . $labels_json . ',datasets:[{label:"Visibility Score",data:' . $scores_json . ',borderColor:"#2271b1",tension:0.3,fill:false}]},options:{scales:{y:{min:0,max:1,title:{display:true,text:"Score"}}},plugins:{legend:{display:false}}}});';
echo '});</script>';
echo '</div>';
$this->renderer->render_bento(
$current_score,
$prev_score,
$cited_count,
$total_count,
$health,
$mtd_cost,
$cap,
$pct,
$truncated,
$last_run_at,
$total_count
);
}
/**
@@ -127,15 +150,14 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
* @return void
*/
private function render_standings( array $standings ): void {
echo '<div class="prv-card"><h2>' . esc_html__( 'Current Standings', 'pr-vision' ) . '</h2>';
echo '<div class="prv-card"><div class="prv-card-head"><h2>' . esc_html__( 'Current Standings', 'pr-vision' ) . '</h2></div><div class="prv-card-body">';
if ( empty( $standings ) ) {
echo '<p>' . esc_html__( 'No standings data yet.', 'pr-vision' ) . '</p></div>';
echo '<p>' . esc_html__( 'No standings data yet.', 'pr-vision' ) . '</p></div></div>';
return;
}
echo '<table class="wp-list-table widefat fixed striped prv-standings">';
echo '<thead><tr>';
echo '<table class="wp-list-table widefat fixed striped prv-standings"><thead><tr>';
echo '<th>' . esc_html__( 'Peptide', 'pr-vision' ) . '</th>';
echo '<th>' . esc_html__( 'Cited?', 'pr-vision' ) . '</th>';
echo '<th>' . esc_html__( 'Our Position', 'pr-vision' ) . '</th>';
@@ -143,18 +165,73 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
echo '</tr></thead><tbody>';
foreach ( $standings as $row ) {
$cited_icon = $row['cited'] ? '&#x2705;' : '&#x274C;';
$position = null !== $row['our_position'] ? '#' . (int) $row['our_position'] : '—';
$domains = implode( ', ', array_map( 'esc_html', (array) $row['top_domains'] ) );
$is_cited = ! empty( $row['cited'] );
$cited_dot = $is_cited ? '&#x25CF;' : '&#x25CB;';
$cited_label = $is_cited ? esc_html__( 'Cited', 'pr-vision' ) : esc_html__( 'Not yet', 'pr-vision' );
$cited_class = $is_cited ? 'prv-status prv-status--cited' : 'prv-status prv-status--not-yet';
$position = null !== $row['our_position'] ? '#' . (int) $row['our_position'] : '—';
$domains = implode( ', ', array_map( 'esc_html', (array) $row['top_domains'] ) );
echo '<tr>';
echo '<td>' . esc_html( (string) $row['label'] ) . '</td>';
echo '<td>' . $cited_icon . '</td>'; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- only emoji
echo '<td><span class="' . esc_attr( $cited_class ) . '">' . $cited_dot . ' ' . $cited_label . '</span></td>'; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped — dot is HTML entity; label escaped above; class esc_attr'd
echo '<td>' . esc_html( $position ) . '</td>';
echo '<td>' . wp_kses_post( $domains ) . '</td>';
echo '</tr>';
}
echo '</tbody></table></div>';
echo '</tbody></table></div></div>';
}
/**
* Derive the run-health pill state and label from per-model health data.
*
* States: 'ok' (all healthy/disabled), 'warn' (any retired), 'neutral' (no data yet).
*
* @param array<string, array{health_status: string}> $last_run_counts Per-model health map.
*
* @return array{state: string, label: string}
*/
private function derive_health_pill_state( array $last_run_counts ): array {
if ( empty( $last_run_counts ) ) {
return array(
'state' => 'neutral',
'label' => __( 'No run yet', 'pr-vision' ),
);
}
$retired_count = 0;
$healthy_count = 0;
foreach ( $last_run_counts as $model ) {
$status = (string) ( $model['health_status'] ?? 'unknown' );
if ( 'retired' === $status ) {
$retired_count++;
} elseif ( 'healthy' === $status ) {
$healthy_count++;
}
}
if ( $retired_count > 0 ) {
return array(
'state' => 'warn',
'label' => sprintf(
/* translators: %d: number of degraded models */
_n( '%d model degraded', '%d models degraded', $retired_count, 'pr-vision' ),
$retired_count
),
);
}
if ( 0 === $healthy_count ) {
return array(
'state' => 'neutral',
'label' => __( 'No run yet', 'pr-vision' ),
);
}
return array(
'state' => 'ok',
'label' => __( 'All models healthy', 'pr-vision' ),
);
}
}

298
includes/panel/class-prv-dashboard-renderer.php Normal file
View File

@@ -0,0 +1,298 @@
<?php
/**
* Dashboard visual renderer: bento tiles + trendline chart for the AI-visibility panel.
*
* @package PrVision
*/
declare(strict_types=1);
/**
* Renders the KPI bento bar and the Chart.js trendline for PRV_Ai_Visibility_Panel.
*
* Split from PRV_Ai_Visibility_Panel to keep each file under 300 lines.
* Handles the v0.2.1 additions: run-health pill on the score tile, config-change
* vertical dashed markers on the trendline, and the budget-truncation badge on
* the cost tile.
*
* Who triggers: PRV_Ai_Visibility_Panel::render() — called directly.
* Dependencies: none (all data passed as arguments).
*
* @see class-prv-ai-visibility-panel.php — Orchestrator that calls this renderer.
* @see class-prv-ai-visibility-collector.php — Produces the data consumed here.
* @see design/pr-vision/design-proposal.md — Palette + layout specification.
* @package PrVision
*/
class PRV_Dashboard_Renderer {
/**
* Render the three-tile KPI bento band.
*
* @param float $current_score Current visibility score 0–1.
* @param float|null $prev_score Previous-run score, null if first run.
* @param int $cited_count Number of cited peptides.
* @param int $total_count Total peptides tracked.
* @param array{state: string, label: string} $health Run-health pill state + label.
* @param float $mtd_cost Month-to-date spend USD.
* @param float $cap Monthly budget cap USD.
* @param float $pct Percentage of cap consumed.
* @param bool $truncated Whether the last run hit the cap.
* @param string $last_run_at Formatted run timestamp or "Never".
* @param int $row_count Total peptide row count.
*
* @return void
*/
public function render_bento(
float $current_score,
?float $prev_score,
int $cited_count,
int $total_count,
array $health,
float $mtd_cost,
float $cap,
float $pct,
bool $truncated,
string $last_run_at,
int $row_count
): void {
echo '<div class="prv-bento">';
$this->render_score_tile( $current_score, $prev_score, $cited_count, $total_count, $health );
$this->render_cost_tile( $mtd_cost, $cap, $pct, $truncated );
$this->render_lastrun_tile( $last_run_at, $row_count );
echo '</div>';
}
/**
* Render the Chart.js trendline with config-change vertical markers.
*
* The chart lives in a fixed-height .prv-chartbox (300px) and is created
* inside a typeof-Chart guard. If Chart.js is unavailable the guard adds
* .prv-noscript, hiding the canvas and showing an in-box fallback note
* without reflow or throw.
*
* Config-change markers are detected from consecutive config_version values
* in the trendline. An inline configMarker Chart.js plugin draws a vertical
* dashed orange line + pin circle at each boundary index.
*
* @param array<int, array{run_id: string, captured_at: string, score: float, config_version?: int}> $trendline Trendline data points.
*
* @return void
*/
public function render_trendline( array $trendline ): void {
echo '<div class="prv-card prv-card--chart">';
echo '<div class="prv-card-head"><h2>' . esc_html__( 'Visibility Score — Trend', 'pr-vision' ) . '</h2></div>';
if ( empty( $trendline ) ) {
echo '<div class="prv-card-body"><p>' . esc_html__( 'No probe runs recorded yet. Click "Run now" to collect the first data point.', 'pr-vision' ) . '</p></div></div>';
return;
}
$labels = array();
$scores = array();
$marker_indices = array();
$prev_version = null;
foreach ( $trendline as $idx => $point ) {
$labels[] = gmdate( 'M j', (int) strtotime( (string) $point['captured_at'] ) );
$scores[] = round( (float) $point['score'] * 100, 2 );
$cv = isset( $point['config_version'] ) ? (int) $point['config_version'] : null;
if ( null !== $prev_version && null !== $cv && $cv !== $prev_version ) {
$marker_indices[] = $idx;
}
$prev_version = $cv;
}
$labels_json = wp_json_encode( $labels );
$scores_json = wp_json_encode( $scores );
$marker_indices_json = wp_json_encode( $marker_indices );
$has_markers = ! empty( $marker_indices );
echo '<div class="prv-chartbox">';
echo '<canvas id="prv-trendline-chart" aria-label="' . esc_attr__( 'Visibility score over time', 'pr-vision' ) . '" role="img"></canvas>';
echo '<div class="prv-chart-fallback">' . esc_html__( 'Trend chart needs Chart.js — the data still reads in the standings table below.', 'pr-vision' ) . '</div>';
echo '</div>';
echo '<div class="prv-chartcap">';
echo '<span class="prv-chartcap-item"><span class="prv-leg-solid"></span>' . esc_html__( 'Visibility score (%)', 'pr-vision' ) . '</span>';
echo '<span class="prv-chartcap-item"><span class="prv-leg-dash"></span>' . esc_html__( 'First-citation goal', 'pr-vision' ) . '</span>';
if ( $has_markers ) {
echo '<span class="prv-chartcap-item"><span class="prv-leg-cfg"></span>' . esc_html__( 'Config changed', 'pr-vision' ) . '</span>';
}
echo '</div>';
if ( $has_markers ) {
echo '<div class="prv-cfg-note"><span class="prv-cfg-note-icon" aria-hidden="true">&#x2139;</span>';
echo '<span><b>' . esc_html__( 'Scored config changed', 'pr-vision' ) . '</b> — ';
echo esc_html__( 'segments either side of the orange markers are separate baselines; the line does not represent one continuous trend across breaks.', 'pr-vision' );
echo '</span></div>';
}
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
echo '<script>(function(){';
echo 'var labels=' . $labels_json . ';';
echo 'var scores=' . $scores_json . ';';
echo 'var markerIdx=' . $marker_indices_json . ';';
echo 'var box=document.getElementById("prv-trendline-chart");';
echo 'if(!box){return;}';
echo 'var wrap=box.closest?box.closest(".prv-chartbox"):box.parentNode;';
echo 'if(typeof Chart==="undefined"){if(wrap){wrap.classList.add("prv-noscript");}return;}';
$this->echo_chart_js_plugin();
echo 'var ctx=box.getContext("2d");';
echo 'var grad=ctx.createLinearGradient(0,0,0,300);';
echo 'grad.addColorStop(0,"rgba(52,192,202,0.28)");grad.addColorStop(1,"rgba(52,192,202,0)");';
echo 'new Chart(ctx,{plugins:[configMarker],type:"line",data:{labels:labels,datasets:[';
echo '{label:' . wp_json_encode( __( 'Visibility Score (%)', 'pr-vision' ) ) . ',data:scores,';
echo 'borderColor:"#34C0CA",backgroundColor:grad,tension:0.3,fill:true,';
echo 'pointBackgroundColor:"#34C0CA",pointBorderColor:"#14181C",pointBorderWidth:1,pointRadius:4},';
echo '{label:' . wp_json_encode( __( 'First-citation goal (5%)', 'pr-vision' ) ) . ',data:scores.map(function(){return 5;}),';
echo 'borderColor:"#B6F25A",borderDash:[6,4],borderWidth:1.5,pointRadius:0,fill:false}';
echo ']},options:{maintainAspectRatio:false,interaction:{mode:"index",intersect:false},';
echo 'scales:{x:{grid:{color:"#2C353E"},ticks:{color:"#9AA7B2",font:{size:11}}},';
echo 'y:{min:0,max:100,grid:{color:"#2C353E"},ticks:{color:"#9AA7B2",font:{size:11}},';
echo 'title:{display:true,text:"Score %",color:"#9AA7B2",font:{size:11}}}},';
echo 'plugins:{legend:{display:false},tooltip:{backgroundColor:"#232B33",borderColor:"#3A4651",borderWidth:1,';
echo 'titleColor:"#EEF2F5",bodyColor:"#C2CCD6",callbacks:{afterBody:function(items){';
echo 'var idx=items[0].dataIndex;return markerIdx.indexOf(idx)>=0?["⚑ Scored config changed here"]:[];';
echo '}}}}';
echo '}});})();</script>';
// phpcs:enable WordPress.Security.EscapeOutput.OutputNotEscaped
echo '</div>';
}
/**
* Emit the configMarker inline Chart.js plugin (no external CDN).
*
* Draws a vertical dashed orange line + pin circle at each marker index.
* Must be called inside a <script> block after markerIdx is defined.
*
* @return void
*/
private function echo_chart_js_plugin(): void {
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
echo 'var configMarker={id:"configMarker",afterDraw:function(chart){';
echo 'if(!markerIdx.length){return;}';
echo 'var c=chart.ctx,xA=chart.scales.x,yA=chart.scales.y;';
echo 'c.save();';
echo 'markerIdx.forEach(function(idx){';
echo 'var xP=xA.getPixelForValue(idx);';
echo 'c.strokeStyle="#FFB36E";c.lineWidth=2;c.setLineDash([5,4]);';
echo 'c.beginPath();c.moveTo(xP,yA.top);c.lineTo(xP,yA.bottom);c.stroke();';
echo 'c.setLineDash([]);c.fillStyle="#FF9D4D";c.strokeStyle="#14181C";c.lineWidth=1.5;';
echo 'c.beginPath();c.arc(xP,yA.top+8,5,0,Math.PI*2);c.fill();c.stroke();';
echo '});c.restore();';
echo '}};';
// phpcs:enable WordPress.Security.EscapeOutput.OutputNotEscaped
}
/**
* Render the visibility score KPI tile with run-health pill.
*
* @param float $score Current visibility score 0–1.
* @param float|null $prev_score Previous run score, null if first run.
* @param int $cited Number of cited peptides.
* @param int $total Total peptides tracked.
* @param array{state: string, label: string} $health Run-health pill state.
*
* @return void
*/
private function render_score_tile( float $score, ?float $prev_score, int $cited, int $total, array $health ): void {
$score_pct = round( $score * 100, 1 );
$delta_html = $this->build_delta_html( $score, $prev_score );
echo '<div class="prv-tile prv-tile--score">';
echo '<span class="prv-health-pill prv-health--' . esc_attr( $health['state'] ) . '" aria-label="' . esc_attr__( 'Run health', 'pr-vision' ) . '">';
echo '<span class="prv-health-dot" aria-hidden="true"></span>';
echo esc_html( $health['label'] );
echo '</span>';
echo '<div class="prv-tile-label">' . esc_html__( 'Visibility Score', 'pr-vision' ) . '</div>';
echo '<div class="prv-tile-big">' . esc_html( (string) $score_pct ) . '<small>%</small></div>';
echo $delta_html; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped — built by build_delta_html; values escaped inside
echo '<div class="prv-tile-sub">' . esc_html(
sprintf(
/* translators: 1: cited count, 2: total peptide count */
__( '%1$d of %2$d peptides cited', 'pr-vision' ),
$cited,
$total
)
) . '</div>';
echo '</div>';
}
/**
* Render the MTD cost KPI tile with budget meter and optional truncation badge.
*
* @param float $mtd_cost Month-to-date spend USD.
* @param float $cap Monthly cap USD.
* @param float $pct Percentage of cap consumed.
* @param bool $truncated Whether the last run was truncated by the cap.
*
* @return void
*/
private function render_cost_tile( float $mtd_cost, float $cap, float $pct, bool $truncated ): void {
$meter_class = $pct >= 100 ? 'prv-meter prv-meter--capped' : 'prv-meter';
echo '<div class="prv-tile prv-tile--cost">';
echo '<div class="prv-tile-label">' . esc_html__( 'MTD Cost', 'pr-vision' ) . '</div>';
echo '<div class="prv-cost-row">';
echo '<span class="prv-cost-big">$' . esc_html( number_format( $mtd_cost, 4 ) ) . '</span>';
echo '<span class="prv-cost-cap"> / $' . esc_html( number_format( $cap, 2 ) ) . '</span>';
echo '</div>';
echo '<div class="' . esc_attr( $meter_class ) . '" role="progressbar" aria-valuenow="' . esc_attr( (string) $pct ) . '" aria-valuemin="0" aria-valuemax="100" aria-label="' . esc_attr__( 'Budget used', 'pr-vision' ) . '"><span style="width:' . esc_attr( $pct ) . '%"></span></div>';
if ( $truncated ) {
echo '<div class="prv-trunc-badge"><span class="prv-trunc-icon" aria-hidden="true">&#x26A0;</span>';
echo '<span><b>' . esc_html__( 'Last run truncated', 'pr-vision' ) . '</b> — ';
echo esc_html__( 'hit the cap before all probes completed.', 'pr-vision' ) . '</span></div>';
}
echo '</div>';
}
/**
* Render the last-run KPI tile.
*
* @param string $last_run_at Formatted run timestamp or "Never".
* @param int $row_count Peptide count tracked.
*
* @return void
*/
private function render_lastrun_tile( string $last_run_at, int $row_count ): void {
echo '<div class="prv-tile prv-tile--lastrun">';
echo '<div class="prv-tile-label">' . esc_html__( 'Last Run', 'pr-vision' ) . '</div>';
echo '<div class="prv-tile-ts">' . esc_html( $last_run_at ) . '</div>';
if ( $row_count > 0 ) {
echo '<div class="prv-tile-meta">' . esc_html(
sprintf(
/* translators: %d: peptide row count */
__( '%d peptides tracked', 'pr-vision' ),
$row_count
)
) . '</div>';
}
echo '</div>';
}
/**
* Build a pre-escaped delta indicator HTML string for the score tile.
*
* @param float $current Current score 0–1.
* @param float|null $previous Previous run score, null if first run.
*
* @return string Pre-escaped HTML, or empty string when no previous score.
*/
public function build_delta_html( float $current, ?float $previous ): string {
if ( null === $previous ) {
return '';
}
$diff = round( ( $current - $previous ) * 100, 2 );
if ( $diff > 0 ) {
return '<div class="prv-tile-delta prv-delta--up">&#x25B2; +' . esc_html( number_format( $diff, 2 ) ) . '%</div>';
}
if ( $diff < 0 ) {
return '<div class="prv-tile-delta prv-delta--down">&#x25BC; ' . esc_html( number_format( $diff, 2 ) ) . '%</div>';
}
return '<div class="prv-tile-delta prv-delta--flat">&#x2014; ' . esc_html__( 'no change', 'pr-vision' ) . '</div>';
}
}